@cleocode/cleo 2026.5.92 → 2026.5.93

package/dist/cli/index.js

@@ -1584,6 +1584,390 @@ var init_credentials = __esm({
   }
 });
 
+// packages/contracts/src/docs-taxonomy.ts
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+function validateDocKindConfig(raw, source) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new DocKindConfigError(`${source}: top-level value must be an object`, source);
+  }
+  const obj = raw;
+  if (obj.extensions === void 0) {
+    return {};
+  }
+  if (!Array.isArray(obj.extensions)) {
+    throw new DocKindConfigError(`${source}: 'extensions' must be an array`, source);
+  }
+  const extensions = [];
+  for (let i = 0; i < obj.extensions.length; i++) {
+    const item = obj.extensions[i];
+    extensions.push(validateExtensionEntry(item, source, i));
+  }
+  return { extensions };
+}
+function validateExtensionEntry(raw, source, index) {
+  const where = `${source} extensions[${index}]`;
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new DocKindConfigError(`${where}: must be an object`, source);
+  }
+  const obj = raw;
+  const kind = requireString(obj, "kind", where, source);
+  if (!/^[a-z][a-z0-9-]*$/.test(kind)) {
+    throw new DocKindConfigError(
+      `${where}: 'kind' must be lowercase kebab-case (got '${kind}')`,
+      source
+    );
+  }
+  const builtinNames = new Set(BUILTIN_DOC_KIND_VALUES);
+  if (builtinNames.has(kind)) {
+    throw new DocKindConfigError(
+      `${where}: kind '${kind}' shadows a built-in \u2014 built-ins cannot be overridden`,
+      source
+    );
+  }
+  const label = requireString(obj, "label", where, source);
+  const description = requireString(obj, "description", where, source);
+  const defaultOwnerKind = requireString(obj, "defaultOwnerKind", where, source);
+  if (defaultOwnerKind !== "task" && defaultOwnerKind !== "session" && defaultOwnerKind !== "observation" && defaultOwnerKind !== "project") {
+    throw new DocKindConfigError(
+      `${where}: 'defaultOwnerKind' must be task|session|observation|project (got '${defaultOwnerKind}')`,
+      source
+    );
+  }
+  const publishDir = requireString(obj, "publishDir", where, source);
+  const requiresEntityId = obj.requiresEntityId;
+  if (typeof requiresEntityId !== "boolean") {
+    throw new DocKindConfigError(`${where}: 'requiresEntityId' must be a boolean`, source);
+  }
+  let entityIdPattern;
+  if (obj.entityIdPattern !== void 0) {
+    if (typeof obj.entityIdPattern !== "string") {
+      throw new DocKindConfigError(`${where}: 'entityIdPattern' must be a string`, source);
+    }
+    if (obj.entityIdPattern.length > DocKindRegistry.SAFE_REGEX_LENGTH_LIMIT) {
+      throw new DocKindConfigError(
+        `${where}: 'entityIdPattern' exceeds ${DocKindRegistry.SAFE_REGEX_LENGTH_LIMIT} chars`,
+        source
+      );
+    }
+    entityIdPattern = obj.entityIdPattern;
+  }
+  if (requiresEntityId && entityIdPattern === void 0) {
+    throw new DocKindConfigError(
+      `${where}: 'entityIdPattern' is required when 'requiresEntityId' is true`,
+      source
+    );
+  }
+  return {
+    kind,
+    label,
+    description,
+    defaultOwnerKind,
+    publishDir,
+    requiresEntityId,
+    ...entityIdPattern !== void 0 ? { entityIdPattern } : {}
+  };
+}
+function compileExtension(ext, source) {
+  let entityIdPattern;
+  if (ext.entityIdPattern !== void 0) {
+    try {
+      entityIdPattern = new RegExp(ext.entityIdPattern);
+    } catch (err) {
+      throw new DocKindConfigError(
+        `${source}: invalid regex for kind '${ext.kind}': ${err.message}`,
+        source
+      );
+    }
+  }
+  return {
+    kind: ext.kind,
+    label: ext.label,
+    description: ext.description,
+    defaultOwnerKind: ext.defaultOwnerKind,
+    publishDir: ext.publishDir,
+    requiresEntityId: ext.requiresEntityId,
+    ...entityIdPattern !== void 0 ? { entityIdPattern } : {},
+    isExtension: true
+  };
+}
+function requireString(obj, field, where, source) {
+  const value = obj[field];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new DocKindConfigError(`${where}: '${field}' must be a non-empty string`, source);
+  }
+  return value;
+}
+function buildSlugExample(meta) {
+  switch (meta.kind) {
+    case "adr":
+      return "adr-001-intro";
+    case "changeset":
+      return "t9788-docs-taxonomy";
+    case "release-note":
+      return "v2026.5.93";
+    case "rcasd":
+      return "t9788-investigation";
+    default:
+      return meta.entityIdPattern?.source;
+  }
+}
+var BUILTIN_DOC_KINDS, BUILTIN_DOC_KIND_VALUES, DocKindRegistry, DocKindConfigError;
+var init_docs_taxonomy = __esm({
+  "packages/contracts/src/docs-taxonomy.ts"() {
+    "use strict";
+    BUILTIN_DOC_KINDS = [
+      {
+        kind: "adr",
+        label: "ADR",
+        description: "Architectural decision record",
+        defaultOwnerKind: "task",
+        publishDir: "docs/adr",
+        requiresEntityId: true,
+        entityIdPattern: /^adr-\d{3,4}-[a-z0-9-]+$/
+      },
+      {
+        kind: "spec",
+        label: "Spec",
+        description: "Technical specification",
+        defaultOwnerKind: "task",
+        publishDir: "docs/spec",
+        requiresEntityId: false
+      },
+      {
+        kind: "research",
+        label: "Research",
+        description: "Investigation / research note",
+        defaultOwnerKind: "task",
+        publishDir: "docs/research",
+        requiresEntityId: false
+      },
+      {
+        kind: "handoff",
+        label: "Handoff",
+        description: "Session / agent handoff",
+        defaultOwnerKind: "session",
+        publishDir: "docs/handoff",
+        requiresEntityId: false
+      },
+      {
+        kind: "note",
+        label: "Note",
+        description: "Agent observation / informal note",
+        defaultOwnerKind: "observation",
+        publishDir: "docs/note",
+        requiresEntityId: false
+      },
+      {
+        kind: "llm-readme",
+        label: "LLM README",
+        description: "Machine-readable README (llms.txt)",
+        defaultOwnerKind: "project",
+        publishDir: ".",
+        requiresEntityId: false
+      },
+      {
+        kind: "changeset",
+        label: "Changeset",
+        description: "Atomic change entry (release-note input)",
+        defaultOwnerKind: "task",
+        publishDir: ".changeset",
+        requiresEntityId: true,
+        entityIdPattern: /^t\d+-[a-z0-9-]+$/
+      },
+      {
+        kind: "release-note",
+        label: "Release Note",
+        description: "Composed release notes",
+        defaultOwnerKind: "project",
+        publishDir: "docs/release",
+        requiresEntityId: true,
+        entityIdPattern: /^v\d{4}\.\d+\.\d+(-[a-z0-9-]+)?$/
+      },
+      {
+        kind: "plan",
+        label: "Plan",
+        description: "Epic / saga decomposition plan",
+        defaultOwnerKind: "task",
+        publishDir: "docs/plan",
+        requiresEntityId: false
+      },
+      {
+        kind: "rcasd",
+        label: "RCASD",
+        description: "Root-cause analysis + scoped delivery",
+        defaultOwnerKind: "task",
+        publishDir: ".cleo/rcasd",
+        requiresEntityId: true,
+        entityIdPattern: /^t\d+(-.+)?$/
+      }
+    ];
+    BUILTIN_DOC_KIND_VALUES = Object.freeze(
+      BUILTIN_DOC_KINDS.map((d) => d.kind)
+    );
+    DocKindRegistry = class _DocKindRegistry {
+      /**
+       * Maximum allowed length of an `entityIdPattern` source string.
+       *
+       * Caps the input surface so a malformed extension config cannot trigger
+       * pathological regex backtracking. 256 chars is far more than any
+       * realistic slug pattern (typical: 30–60 chars).
+       */
+      static SAFE_REGEX_LENGTH_LIMIT = 256;
+      byKind;
+      orderedEntries;
+      /**
+       * Construct a registry from an explicit array of entries.
+       *
+       * Most callers should use {@link DocKindRegistry.load} instead; this
+       * constructor is exposed for tests that want to bypass filesystem I/O.
+       *
+       * @param entries - Pre-validated doc-kind metadata (built-in + extensions).
+       */
+      constructor(entries) {
+        this.orderedEntries = entries;
+        const map2 = /* @__PURE__ */ new Map();
+        for (const entry of entries) {
+          if (!map2.has(entry.kind)) map2.set(entry.kind, entry);
+        }
+        this.byKind = map2;
+      }
+      /**
+       * Load the canonical registry, merging built-ins with extensions from
+       * `<projectRoot>/.cleo/docs-config.json`.
+       *
+       * Missing or unreadable config file → returns the built-in-only registry.
+       * Malformed config (bad JSON, invalid entry, regex too long, etc.) →
+       * throws {@link DocKindConfigError} so the caller can surface a clear
+       * envelope rather than silently dropping extensions.
+       *
+       * @param projectRoot - Absolute path to the repo root.
+       * @throws DocKindConfigError when the config exists but is invalid.
+       */
+      static load(projectRoot) {
+        const configPath = join(projectRoot, ".cleo", "docs-config.json");
+        let raw;
+        try {
+          raw = readFileSync(configPath, "utf-8");
+        } catch {
+          return new _DocKindRegistry(BUILTIN_DOC_KINDS);
+        }
+        let parsed;
+        try {
+          parsed = JSON.parse(raw);
+        } catch (err) {
+          throw new DocKindConfigError(
+            `${configPath}: invalid JSON \u2014 ${err.message}`,
+            configPath
+          );
+        }
+        const config = validateDocKindConfig(parsed, configPath);
+        const extensions = (config.extensions ?? []).map((ext) => compileExtension(ext, configPath));
+        return new _DocKindRegistry([...BUILTIN_DOC_KINDS, ...extensions]);
+      }
+      /**
+       * Build a registry from already-parsed config — bypasses filesystem I/O.
+       *
+       * Used by tests and HTTP-dispatch callers that hand-construct a config
+       * object instead of reading from disk.
+       *
+       * @param config - Parsed config object (or `undefined` for built-ins only).
+       * @param sourceLabel - Optional label used in error messages.
+       * @throws DocKindConfigError when the config object is invalid.
+       */
+      static fromConfig(config, sourceLabel = "<inline-config>") {
+        if (!config) return new _DocKindRegistry(BUILTIN_DOC_KINDS);
+        const validated = validateDocKindConfig(config, sourceLabel);
+        const extensions = (validated.extensions ?? []).map(
+          (ext) => compileExtension(ext, sourceLabel)
+        );
+        return new _DocKindRegistry([...BUILTIN_DOC_KINDS, ...extensions]);
+      }
+      /**
+       * Default registry — built-in kinds only, no extensions.
+       *
+       * Suitable for code paths that never need project-level extensions
+       * (e.g. unit tests, library-mode consumers).
+       */
+      static builtinOnly() {
+        return new _DocKindRegistry(BUILTIN_DOC_KINDS);
+      }
+      /** True when `kind` is registered (built-in OR extension). */
+      has(kind) {
+        return this.byKind.has(kind);
+      }
+      /** Look up metadata for a registered kind. Returns `undefined` on miss. */
+      get(kind) {
+        return this.byKind.get(kind);
+      }
+      /**
+       * List every registered kind, built-ins first then extensions in
+       * declaration order.
+       *
+       * Used by `cleo docs schema` and `cleo docs list-types`.
+       */
+      list() {
+        return this.orderedEntries;
+      }
+      /**
+       * Validate a slug against the registered pattern for `kind`.
+       *
+       * Behaviour:
+       * - Unknown kind → `{ ok: false, error: "unknown kind '<kind>'" }`.
+       * - Known kind with `requiresEntityId === false` → always `{ ok: true }`.
+       * - Known kind with `requiresEntityId === true` and no pattern → defensive
+       *   `{ ok: false }` since the registry entry is internally inconsistent.
+       * - Known kind with pattern → tests `slug` against the pattern.
+       *
+       * @param kind - Registered kind id.
+       * @param slug - Slug to validate.
+       * @returns Pass/fail result with a human-readable error on failure.
+       */
+      validateSlug(kind, slug) {
+        const meta = this.byKind.get(kind);
+        if (!meta) {
+          return { ok: false, error: `unknown kind '${kind}'` };
+        }
+        if (!meta.requiresEntityId) {
+          return { ok: true };
+        }
+        if (!meta.entityIdPattern) {
+          return {
+            ok: false,
+            error: `kind '${kind}' requires an entityIdPattern but the registry entry omits one`
+          };
+        }
+        if (!meta.entityIdPattern.test(slug)) {
+          return {
+            ok: false,
+            error: `slug '${slug}' does not match pattern ${meta.entityIdPattern.source} for kind '${kind}'`,
+            example: buildSlugExample(meta)
+          };
+        }
+        return { ok: true };
+      }
+      /**
+       * Map a kind to its `publishDir` (e.g. `'adr'` → `'docs/adr'`).
+       *
+       * Returns `undefined` for unknown kinds — callers decide whether to
+       * fall back to a default (e.g. `'docs/note'`) or surface an error.
+       */
+      publishDirFor(kind) {
+        return this.byKind.get(kind)?.publishDir;
+      }
+    };
+    DocKindConfigError = class extends Error {
+      /** Source identifier — file path on disk, or `<inline-config>` for tests. */
+      source;
+      constructor(message, source) {
+        super(message);
+        this.name = "DocKindConfigError";
+        this.source = source;
+      }
+    };
+  }
+});
+
 // packages/contracts/src/engine-result.ts
 var init_engine_result = __esm({
   "packages/contracts/src/engine-result.ts"() {
@@ -1839,6 +2223,7 @@ var init_dialectic = __esm({
 var init_docs = __esm({
   "packages/contracts/src/operations/docs.ts"() {
     "use strict";
+    init_docs_taxonomy();
   }
 });
 
@@ -2990,6 +3375,7 @@ var init_src2 = __esm({
     init_branch_lock();
     init_changesets();
     init_credentials();
+    init_docs_taxonomy();
     init_engine_result();
     init_errors();
     init_evidence_record_schema();
@@ -6003,6 +6389,24 @@ var init_registry = __esm({
         requiredParams: [],
         params: []
       },
+      {
+        gateway: "query",
+        domain: "session",
+        operation: "lint",
+        description: "session.lint (query) \u2014 agent-accountability harness: flag raw-md writes to canonical doc paths in a transcript (T9797)",
+        tier: 1,
+        idempotent: true,
+        sessionRequired: false,
+        requiredParams: ["transcript"],
+        params: [
+          {
+            name: "transcript",
+            type: "string",
+            required: true,
+            description: "Absolute path to the *.jsonl session transcript to lint"
+          }
+        ]
+      },
       {
         gateway: "query",
         domain: "orchestrate",
@@ -6899,6 +7303,25 @@ var init_registry = __esm({
         requiredParams: [],
         params: []
       },
+      // T9796: Docs canon-routing CI gate — block raw *.md writes that bypass SSoT
+      {
+        gateway: "query",
+        domain: "check",
+        operation: "canon.docs",
+        description: "check.canon.docs (query) \u2014 CI gate: rejects new *.md files that bypass the docs SSoT (.cleo/canon.yml routing). Scans git diff additions against rawMdPaths whose owning DocKind has rawMdAllowed:false.",
+        tier: 1,
+        idempotent: true,
+        sessionRequired: false,
+        requiredParams: [],
+        params: [
+          {
+            name: "baseRef",
+            type: "string",
+            required: false,
+            description: "Git revision to diff against (default: origin/main)"
+          }
+        ]
+      },
       // T065: Agent workflow compliance telemetry
       {
         gateway: "query",
@@ -13246,9 +13669,10 @@ function lafsSuccess(data, _operation, extra) {
     ...extra?.page ? { page: extra.page } : {}
   };
 }
-function lafsError(code, message, _operation, fix) {
+function lafsError(code, message, _operation, fix, details) {
   const error = { code, message };
   if (fix !== void 0) error.fix = fix;
+  if (details !== void 0) error.details = details;
   return {
     success: false,
     error
@@ -14126,8 +14550,8 @@ var smoke_provider_exports = {};
 __export(smoke_provider_exports, {
   smokeProvider: () => smokeProvider
 });
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync as readFileSync2 } from "node:fs";
+import { join as join2 } from "node:path";
 function isLocal(dbPath, projectCleoDir, cleoHome) {
   return dbPath.startsWith(projectCleoDir) || dbPath.startsWith(cleoHome);
 }
@@ -14135,7 +14559,7 @@ function classifySpawn(spawnSrcPath) {
   if (!existsSync(spawnSrcPath)) return "no";
   let src;
   try {
-    src = readFileSync(spawnSrcPath, "utf-8");
+    src = readFileSync2(spawnSrcPath, "utf-8");
   } catch {
     return "no";
   }
@@ -14147,7 +14571,7 @@ function countHookEvents(hooksSrcPath, canonicalEvents) {
   if (!existsSync(hooksSrcPath)) return 0;
   let src;
   try {
-    src = readFileSync(hooksSrcPath, "utf-8");
+    src = readFileSync2(hooksSrcPath, "utf-8");
   } catch {
     return 0;
   }
@@ -14158,10 +14582,10 @@ function countHookEvents(hooksSrcPath, canonicalEvents) {
   return count;
 }
 function buildReport(partial) {
-  const sep = "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550";
+  const sep2 = "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550";
   const lines = [
     `CLEO Smoke Probe \u2014 provider: ${partial.providerId}`,
-    sep,
+    sep2,
     `  Adapter loaded:       ${partial.adapterLoaded ? "yes" : "no"}`
   ];
   for (const db of partial.dbChecks) {
@@ -14193,7 +14617,7 @@ async function smokeProvider(providerId) {
     }
   })();
   const monorepoRoot = projectRoot;
-  const adapterDistPath = join(
+  const adapterDistPath = join2(
     monorepoRoot,
     "packages",
     "adapters",
@@ -14223,9 +14647,9 @@ async function smokeProvider(providerId) {
     }
   }
   const cleoHome = coreInternal.getCleoHome();
-  const projectCleoDir = join(projectRoot, CLEO_DIR_NAME);
+  const projectCleoDir = join2(projectRoot, CLEO_DIR_NAME);
   const taskDbPath = coreInternal.getTaskPath(projectRoot);
-  const brainPath = join(projectCleoDir, BRAIN_DB_FILENAME);
+  const brainPath = join2(projectCleoDir, BRAIN_DB_FILENAME);
   const conduitDbPath = coreInternal.getConduitDbPath(projectRoot);
   const nexusDbPath = coreInternal.getNexusDbPath();
   const dbChecks = [
@@ -14245,7 +14669,7 @@ async function smokeProvider(providerId) {
   } catch {
     canonicalEvents = [];
   }
-  const hooksSrcPath = join(
+  const hooksSrcPath = join2(
     monorepoRoot,
     "packages",
     "adapters",
@@ -14255,7 +14679,7 @@ async function smokeProvider(providerId) {
     "hooks.ts"
   );
   const hooksDeclared = countHookEvents(hooksSrcPath, canonicalEvents);
-  const spawnSrcPath = join(
+  const spawnSrcPath = join2(
     monorepoRoot,
     "packages",
     "adapters",
@@ -15553,11 +15977,11 @@ var canon_exports = {};
 __export(canon_exports, {
   runCanonCheck: () => runCanonCheck
 });
-import { readFileSync as readFileSync2 } from "node:fs";
-import { join as join2 } from "node:path";
+import { readFileSync as readFileSync3 } from "node:fs";
+import { join as join3 } from "node:path";
 function readLines(filePath) {
   try {
-    return readFileSync2(filePath, "utf8").split("\n");
+    return readFileSync3(filePath, "utf8").split("\n");
   } catch {
     return [];
   }
@@ -15607,11 +16031,11 @@ function countOperations(registryFilePath) {
 }
 function runCanonCheck(params) {
   const { projectRoot } = params;
-  const typesFile = join2(projectRoot, "packages/cleo/src/dispatch/types.ts");
-  const registryFile = join2(projectRoot, "packages/cleo/src/dispatch/registry.ts");
-  const archGuide = join2(projectRoot, "docs/concepts/CLEO-ARCHITECTURE-GUIDE.md");
-  const visionDoc = join2(projectRoot, "docs/concepts/CLEO-VISION.md");
-  const constitution = join2(projectRoot, "docs/specs/CLEO-OPERATION-CONSTITUTION.md");
+  const typesFile = join3(projectRoot, "packages/cleo/src/dispatch/types.ts");
+  const registryFile = join3(projectRoot, "packages/cleo/src/dispatch/registry.ts");
+  const archGuide = join3(projectRoot, "docs/concepts/CLEO-ARCHITECTURE-GUIDE.md");
+  const visionDoc = join3(projectRoot, "docs/concepts/CLEO-VISION.md");
+  const constitution = join3(projectRoot, "docs/specs/CLEO-OPERATION-CONSTITUTION.md");
   const domainsInCode = countCanonicalDomains(typesFile);
   const operationsInCode = countOperations(registryFile);
   const excludedSet = new Set(EXCLUDED_FILENAMES);
@@ -15681,6 +16105,150 @@ var init_canon = __esm({
   }
 });
 
+// packages/cleo/src/dispatch/domains/check/canon-docs.ts
+var canon_docs_exports = {};
+__export(canon_docs_exports, {
+  loadCanonRegistry: () => loadCanonRegistry,
+  runCanonDocsCheck: () => runCanonDocsCheck
+});
+import { execSync } from "node:child_process";
+import { existsSync as existsSync2, readFileSync as readFileSync4 } from "node:fs";
+import { join as join4, sep } from "node:path";
+import { parse as parseYaml } from "yaml";
+function normaliseDir(dir) {
+  const slashed = dir.split(sep).join("/");
+  return slashed.endsWith("/") ? slashed : `${slashed}/`;
+}
+function listAddedMarkdownFiles(projectRoot, baseRef) {
+  try {
+    const out = execSync(`git diff --diff-filter=A --name-only ${baseRef}...HEAD`, {
+      cwd: projectRoot,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    return out.split("\n").map((line) => line.trim()).filter((line) => line.length > 0 && line.endsWith(".md"));
+  } catch {
+    return [];
+  }
+}
+function validateCanonRegistry(raw, source) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`${source}: top-level value must be an object`);
+  }
+  const obj = raw;
+  const version = obj["version"];
+  if (typeof version !== "number" || version !== 1) {
+    throw new Error(`${source}: 'version' must be the integer 1 (got ${String(version)})`);
+  }
+  const kindsRaw = obj["kinds"];
+  if (kindsRaw === null || typeof kindsRaw !== "object" || Array.isArray(kindsRaw)) {
+    throw new Error(`${source}: 'kinds' must be an object`);
+  }
+  const kinds = {};
+  for (const [kindId, entryRaw] of Object.entries(kindsRaw)) {
+    kinds[kindId] = validateKindEntry(kindId, entryRaw, source);
+  }
+  return { version, kinds };
+}
+function validateKindEntry(kindId, raw, source) {
+  const where = `${source} kinds.${kindId}`;
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`${where}: must be an object`);
+  }
+  const obj = raw;
+  const canonicalHome = obj["canonicalHome"];
+  if (canonicalHome !== "ssot" && canonicalHome !== "ssot-first") {
+    throw new Error(
+      `${where}: 'canonicalHome' must be 'ssot' or 'ssot-first' (got ${String(canonicalHome)})`
+    );
+  }
+  const publishMirror = obj["publishMirror"];
+  if (typeof publishMirror !== "string" || publishMirror.length === 0) {
+    throw new Error(`${where}: 'publishMirror' must be a non-empty string`);
+  }
+  const rawMdAllowed = obj["rawMdAllowed"];
+  if (typeof rawMdAllowed !== "boolean") {
+    throw new Error(`${where}: 'rawMdAllowed' must be a boolean`);
+  }
+  const rawMdPathsRaw = obj["rawMdPaths"];
+  let rawMdPaths;
+  if (rawMdPathsRaw !== void 0) {
+    if (!Array.isArray(rawMdPathsRaw)) {
+      throw new Error(`${where}: 'rawMdPaths' must be an array`);
+    }
+    for (const p of rawMdPathsRaw) {
+      if (typeof p !== "string" || p.length === 0) {
+        throw new Error(`${where}: 'rawMdPaths' entries must be non-empty strings`);
+      }
+    }
+    rawMdPaths = rawMdPathsRaw;
+  }
+  return {
+    canonicalHome,
+    publishMirror,
+    rawMdAllowed,
+    ...rawMdPaths !== void 0 ? { rawMdPaths } : {}
+  };
+}
+function loadCanonRegistry(projectRoot) {
+  const path6 = join4(projectRoot, ".cleo", "canon.yml");
+  if (!existsSync2(path6)) {
+    return void 0;
+  }
+  const text = readFileSync4(path6, "utf8");
+  const parsed = parseYaml(text);
+  return validateCanonRegistry(parsed, path6);
+}
+function runCanonDocsCheck(params) {
+  const { projectRoot, baseRef = "origin/main", candidateFiles } = params;
+  const registry = loadCanonRegistry(projectRoot);
+  if (!registry) {
+    return {
+      passed: true,
+      baseRef,
+      scanned: 0,
+      violations: [],
+      mode: "no-canon"
+    };
+  }
+  const blockingPaths = [];
+  for (const [kind, entry] of Object.entries(registry.kinds)) {
+    if (entry.rawMdAllowed) continue;
+    if (!entry.rawMdPaths || entry.rawMdPaths.length === 0) continue;
+    for (const p of entry.rawMdPaths) {
+      blockingPaths.push({ dir: normaliseDir(p), kind });
+    }
+  }
+  const candidates = candidateFiles ?? listAddedMarkdownFiles(projectRoot, baseRef);
+  const violations = [];
+  for (const file of candidates) {
+    const normalised = file.split(sep).join("/");
+    for (const { dir, kind } of blockingPaths) {
+      if (normalised.startsWith(dir)) {
+        violations.push({
+          file: normalised,
+          kind,
+          matchedPath: dir,
+          fix: `cleo docs add <taskId> ${normalised} --type ${kind}`
+        });
+        break;
+      }
+    }
+  }
+  return {
+    passed: violations.length === 0,
+    baseRef,
+    scanned: candidates.length,
+    violations,
+    mode: "enforced"
+  };
+}
+var init_canon_docs = __esm({
+  "packages/cleo/src/dispatch/domains/check/canon-docs.ts"() {
+    "use strict";
+  }
+});
+
 // packages/cleo/src/dispatch/domains/check.ts
 import {
   checkArchiveStats,
@@ -16132,6 +16700,35 @@ var init_check = __esm({
         const result = runCanonCheck2({ projectRoot });
         return lafsSuccess(result, "canon");
       },
+      "canon.docs": async (params) => {
+        const projectRoot = getProjectRoot3();
+        const { runCanonDocsCheck: runCanonDocsCheck2 } = await Promise.resolve().then(() => (init_canon_docs(), canon_docs_exports));
+        try {
+          const result = runCanonDocsCheck2({
+            projectRoot,
+            ...params.baseRef !== void 0 ? { baseRef: params.baseRef } : {},
+            ...params.candidateFiles !== void 0 ? { candidateFiles: params.candidateFiles } : {}
+          });
+          if (!result.passed) {
+            const firstFix = result.violations[0]?.fix ?? "cleo docs add ...";
+            const fileList = result.violations.map((v) => `${v.file} (kind=${v.kind})`).join(", ");
+            return lafsError(
+              "E_CANON_VIOLATION",
+              `Docs canon violation: ${result.violations.length} raw *.md addition(s) bypass the SSoT \u2014 ${fileList}`,
+              "canon.docs",
+              `Route through SSoT instead: ${firstFix}`,
+              { result }
+            );
+          }
+          return lafsSuccess(result, "canon.docs");
+        } catch (err) {
+          return lafsError(
+            "E_CANON_INVALID",
+            err instanceof Error ? err.message : String(err),
+            "canon.docs"
+          );
+        }
+      },
       "workflow.compliance": async (params) => {
         const projectRoot = getProjectRoot3();
         try {
@@ -16251,7 +16848,9 @@ var init_check = __esm({
             ...envelope.success ? { data: envelope.data } : {
               error: {
                 code: envelope.error?.code !== void 0 ? String(envelope.error.code) : "E_INTERNAL",
-                message: envelope.error?.message ?? "Unknown error"
+                message: envelope.error?.message ?? "Unknown error",
+                ...envelope.error?.fix !== void 0 ? { fix: envelope.error.fix } : {},
+                ...envelope.error?.details !== void 0 ? { details: envelope.error.details } : {}
               }
             }
           };
@@ -16310,6 +16909,7 @@ var init_check = __esm({
             "grade.list",
             "chain.validate",
             "canon",
+            "canon.docs",
             "verify.explain"
           ],
           mutate: ["compliance.record", "compliance.sync", "test.run", "gate.set"]
@@ -16908,6 +17508,23 @@ import {
   resolveAttachmentBackend,
   SlugCollisionError
 } from "@cleocode/core/internal";
+function getDocKindRegistry() {
+  const root = getProjectRoot5();
+  const cached = _registryCache.get(root);
+  if (cached) return cached;
+  try {
+    const registry = DocKindRegistry.load(root);
+    _registryCache.set(root, registry);
+    return registry;
+  } catch {
+    const fallback = DocKindRegistry.builtinOnly();
+    _registryCache.set(root, fallback);
+    return fallback;
+  }
+}
+function registeredKindValues() {
+  return getDocKindRegistry().list().map((d) => d.kind);
+}
 function inferOwnerType(ownerId) {
   if (/^T\d+$/i.test(ownerId)) return "task";
   if (ownerId.startsWith("ses_")) return "session";
@@ -16954,7 +17571,35 @@ function validateSlug(raw) {
   return { valid: true };
 }
 function validateDocsType(raw) {
-  return typeof raw === "string" && DOCS_TYPE_VALUES.includes(raw);
+  if (typeof raw !== "string") return false;
+  return getDocKindRegistry().has(raw);
+}
+function registeredKindList() {
+  return registeredKindValues().join("|");
+}
+function normaliseOrderBy(raw) {
+  if (raw === "sha" || raw === "slug" || raw === "newest") return raw;
+  return "newest";
+}
+function resolveListLimit(raw) {
+  if (typeof raw === "number" && Number.isFinite(raw)) {
+    if (raw <= 0) return Number.POSITIVE_INFINITY;
+    return Math.floor(raw);
+  }
+  return DOCS_LIST_DEFAULT_LIMIT;
+}
+function compareByOrderBy(orderBy) {
+  if (orderBy === "sha") return (a, b) => a.sha256.localeCompare(b.sha256);
+  if (orderBy === "slug") {
+    return (a, b) => {
+      const left = a.slug ?? "";
+      const right = b.slug ?? "";
+      if (!left && right) return 1;
+      if (left && !right) return -1;
+      return left.localeCompare(right);
+    };
+  }
+  return (a, b) => b.createdAt.localeCompare(a.createdAt);
 }
 function docsEnvelopeToResponse(envelope, gateway, operation, startTime) {
   if (!envelope.success) {
@@ -16971,64 +17616,74 @@ function docsEnvelopeToResponse(envelope, gateway, operation, startTime) {
     };
   }
   let attachmentBackend;
+  let hint;
   let responseData = envelope.data;
   if (responseData !== null && responseData !== void 0 && typeof responseData === "object") {
     const dataObj = responseData;
-    if ("attachmentBackend" in dataObj && dataObj["attachmentBackend"] !== void 0) {
-      attachmentBackend = dataObj["attachmentBackend"];
-      const { attachmentBackend: _lifted, ...cleanData } = dataObj;
-      responseData = cleanData;
+    let cleanedData = dataObj;
+    let cleaned = false;
+    if ("attachmentBackend" in cleanedData && cleanedData["attachmentBackend"] !== void 0) {
+      attachmentBackend = cleanedData["attachmentBackend"];
+      const { attachmentBackend: _lifted, ...rest } = cleanedData;
+      cleanedData = rest;
+      cleaned = true;
+    }
+    if ("hint" in cleanedData && typeof cleanedData["hint"] === "string") {
+      hint = cleanedData["hint"];
+    }
+    if (cleaned) {
+      responseData = cleanedData;
     }
   }
   return {
     meta: {
       ...dispatchMeta(gateway, "docs", operation, startTime),
-      ...attachmentBackend !== void 0 ? { attachmentBackend } : {}
+      ...attachmentBackend !== void 0 ? { attachmentBackend } : {},
+      ...hint !== void 0 ? { hint } : {}
     },
     success: true,
     data: responseData
   };
 }
-var DOCS_TYPE_VALUES, SLUG_PATTERN, SLUG_MAX_LEN, _docsTypedHandler, QUERY_OPS3, MUTATE_OPS3, DocsHandler;
+var DOCS_LIST_DEFAULT_LIMIT, _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";
+    init_src2();
     init_typed();
     init_base();
     init_meta2();
-    DOCS_TYPE_VALUES = [
-      "spec",
-      "adr",
-      "research",
-      "handoff",
-      "note",
-      "llm-readme"
-    ];
+    DOCS_LIST_DEFAULT_LIMIT = 50;
+    _registryCache = /* @__PURE__ */ new Map();
     SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
     SLUG_MAX_LEN = 80;
     _docsTypedHandler = defineTypedHandler("docs", {
       // ── docs.list ──────────────────────────────────────────────────────────────
       list: async (params) => {
         const ownerId = params.task ?? params.session ?? params.observation;
-        const isProjectScope = params.project === true;
-        if (!ownerId && !isProjectScope) {
-          return lafsError(
-            "E_INVALID_INPUT",
-            "Provide one of --task, --session, --observation, or --project to scope the list.",
-            "list"
-          );
-        }
+        const explicitProject = params.project === true;
+        const isProjectScope = explicitProject || !ownerId;
         let typeFilter;
         if (params.type !== void 0) {
           if (!validateDocsType(params.type)) {
             return lafsError(
               "E_INVALID_TYPE",
-              `type must be one of: ${DOCS_TYPE_VALUES.join("|")} \u2014 got '${String(params.type)}'`,
+              `type must be one of: ${registeredKindList()} \u2014 got '${String(params.type)}'`,
               "list"
             );
           }
           typeFilter = params.type;
         }
+        const effectiveLimit = resolveListLimit(params.limit);
+        const orderBy = normaliseOrderBy(params.orderBy);
+        const comparator = compareByOrderBy(orderBy);
+        const autoPromoted = isProjectScope && !explicitProject;
+        const hintParts = [];
+        if (autoPromoted) {
+          hintParts.push(
+            "no scope set \u2014 defaulted to --project. Pass --task <id>, --session <id>, or --observation <id> for a narrower listing."
+          );
+        }
         const store = createAttachmentStore();
         const backend = await resolveAttachmentBackend();
         if (isProjectScope) {
@@ -17036,28 +17691,50 @@ var init_docs2 = __esm({
             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
+          }));
+          projected.sort(
+            (a, b) => comparator(
+              { sha256: a._sortSha, slug: a.slug, createdAt: a.createdAt },
+              { 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;
+          if (truncated) {
+            hintParts.push(
+              `showing ${sliced.length} of ${totalCount} \u2014 pass --limit <N> to widen or page further.`
+            );
+          }
           return lafsSuccess(
             {
               ownerId: "",
               ownerType: "task",
               project: true,
               ...typeFilter !== void 0 ? { type: typeFilter } : {},
-              count: rows.length,
-              attachments: rows.map(({ metadata: m, slug, type: type2, ownerId: oid, ownerType: ot }) => ({
-                id: m.id,
-                sha256: `${m.sha256.slice(0, 8)}\u2026`,
-                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
-              })),
+              count: sliced.length,
+              ...truncated ? { totalCount } : {},
+              limit: Number.isFinite(effectiveLimit) ? effectiveLimit : 0,
+              orderBy,
+              ...hintParts.length > 0 ? { hint: hintParts.join(" ") } : {},
+              attachments: sliced.map(({ _sortSha: _drop, ...row }) => row),
               attachmentBackend: backend
             },
             "list"
@@ -17074,25 +17751,45 @@ var init_docs2 = __esm({
           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 } : {}
+        }));
+        projectedOwner.sort(
+          (a, b) => comparator(
+            { sha256: a._sortSha, slug: a.slug, createdAt: a.createdAt },
+            { sha256: b._sortSha, slug: b.slug, createdAt: b.createdAt }
+          )
+        );
+        const totalCountOwner = projectedOwner.length;
+        const slicedOwner = Number.isFinite(effectiveLimit) ? projectedOwner.slice(0, effectiveLimit) : projectedOwner;
+        const truncatedOwner = totalCountOwner > slicedOwner.length;
+        if (truncatedOwner) {
+          hintParts.push(
+            `showing ${slicedOwner.length} of ${totalCountOwner} \u2014 pass --limit <N> to widen or page further.`
+          );
+        }
         return lafsSuccess(
           {
             ownerId: scopedOwner,
             ownerType,
             ...typeFilter !== void 0 ? { type: typeFilter } : {},
-            count: enriched.length,
-            attachments: enriched.map(({ meta: m, slug, type: type2 }) => ({
-              id: m.id,
-              sha256: `${m.sha256.slice(0, 8)}\u2026`,
-              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 } : {}
-            })),
+            count: slicedOwner.length,
+            ...truncatedOwner ? { totalCount: totalCountOwner } : {},
+            limit: Number.isFinite(effectiveLimit) ? effectiveLimit : 0,
+            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
           },
@@ -17293,12 +17990,19 @@ var init_docs2 = __esm({
           if (!validateDocsType(rawType)) {
             return lafsError(
               "E_INVALID_TYPE",
-              `type must be one of: ${DOCS_TYPE_VALUES.join("|")} \u2014 got '${String(rawType)}'`,
+              `type must be one of: ${registeredKindList()} \u2014 got '${String(rawType)}'`,
               "add"
             );
           }
           type2 = rawType;
         }
+        if (type2 !== void 0 && slug !== void 0) {
+          const patternCheck = getDocKindRegistry().validateSlug(type2, slug);
+          if (!patternCheck.ok) {
+            const exampleHint = patternCheck.example ? ` (example: ${patternCheck.example})` : "";
+            return lafsError("E_SLUG_PATTERN_MISMATCH", `${patternCheck.error}${exampleHint}`, "add");
+          }
+        }
         const extras = {};
         if (slug !== void 0) extras.slug = slug;
         if (type2 !== void 0) extras.type = type2;
@@ -24342,7 +25046,7 @@ var init_parser = __esm({
 });
 
 // packages/playbooks/src/migrate-e4.ts
-import { readFileSync as readFileSync3, writeFileSync } from "node:fs";
+import { readFileSync as readFileSync5, writeFileSync } from "node:fs";
 function validatePlaybookCompliance(source) {
   let parsed;
   try {
@@ -24408,7 +25112,7 @@ function migratePlaybook(source) {
   return dump(raw, { lineWidth: 100, noRefs: true });
 }
 function migratePlaybookFile(filePath, dryRun = false) {
-  const source = readFileSync3(filePath, "utf8");
+  const source = readFileSync5(filePath, "utf8");
   const before = validatePlaybookCompliance(source);
   if (!before.parses) {
     return {
@@ -24760,7 +25464,7 @@ var init_state = __esm({
 
 // packages/playbooks/src/runtime.ts
 import { appendFileSync, mkdirSync } from "node:fs";
-import { dirname, join as join3 } from "node:path";
+import { dirname, join as join5 } from "node:path";
 function buildEdgeIndex(def) {
   const outgoing = /* @__PURE__ */ new Map();
   const incoming = /* @__PURE__ */ new Map();
@@ -24928,7 +25632,7 @@ function resolveEdge(fromId, toId, edges) {
 function auditContractViolation(projectRoot, runId, nodeId, field, key, playbookName) {
   if (!projectRoot) return;
   try {
-    const filePath = join3(projectRoot, ".cleo", "audit", "contract-violations.jsonl");
+    const filePath = join5(projectRoot, ".cleo", "audit", "contract-violations.jsonl");
     mkdirSync(dirname(filePath), { recursive: true });
     const entry = JSON.stringify({
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
@@ -25383,9 +26087,9 @@ var init_src3 = __esm({
 });
 
 // packages/cleo/src/dispatch/domains/playbook.ts
-import { existsSync as existsSync2, readFileSync as readFileSync4 } from "node:fs";
+import { existsSync as existsSync3, readFileSync as readFileSync6 } from "node:fs";
 import { homedir } from "node:os";
-import { dirname as dirname2, join as join4, resolve as resolvePath } from "node:path";
+import { dirname as dirname2, join as join6, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 import { listPlaybooks, PlaybookNotFoundError, resolvePlaybook } from "@cleocode/core";
 function normalizeListStatus(raw) {
@@ -25414,7 +26118,7 @@ function resolvePlaybookDirs() {
   if (__playbookRuntimeOverrides.playbookBaseDirs) {
     return __playbookRuntimeOverrides.playbookBaseDirs;
   }
-  const globalDir = join4(homedir(), ".local", "share", "cleo", "playbooks");
+  const globalDir = join6(homedir(), ".local", "share", "cleo", "playbooks");
   const here = dirname2(fileURLToPath(import.meta.url));
   const sourceStarter = resolvePath(here, "..", "..", "..", "..", "playbooks", "starter");
   const bundledStarter = resolvePath(here, "..", "..", "..", "playbooks", "starter");
@@ -25425,16 +26129,16 @@ async function loadPlaybookByName(name) {
     const candidates = resolvePlaybookDirs();
     const fileName = name.endsWith(".cantbook") ? name : `${name}.cantbook`;
     for (const dir of candidates) {
-      const full = join4(dir, fileName);
-      if (existsSync2(full)) {
-        return { sourcePath: full, source: readFileSync4(full, "utf8") };
+      const full = join6(dir, fileName);
+      if (existsSync3(full)) {
+        return { sourcePath: full, source: readFileSync6(full, "utf8") };
       }
     }
     return null;
   }
   try {
-    const { getProjectRoot: getProjectRoot43 } = await import("@cleocode/core/internal");
-    const projectRoot = __playbookRuntimeOverrides.projectRoot ?? getProjectRoot43();
+    const { getProjectRoot: getProjectRoot44 } = await import("@cleocode/core/internal");
+    const projectRoot = __playbookRuntimeOverrides.projectRoot ?? getProjectRoot44();
     const resolved = resolvePlaybook(name, {
       projectRoot,
       globalPlaybooksDir: __playbookRuntimeOverrides.globalPlaybooksDir,
@@ -25478,8 +26182,8 @@ async function acquireDb() {
 async function buildDefaultDispatcher() {
   if (__playbookRuntimeOverrides.dispatcher) return __playbookRuntimeOverrides.dispatcher;
   const { orchestrateSpawnExecute: orchestrateSpawnExecute2 } = await Promise.resolve().then(() => (init_engine(), engine_exports));
-  const { getProjectRoot: getProjectRoot43 } = await import("@cleocode/core/internal");
-  const projectRoot = getProjectRoot43();
+  const { getProjectRoot: getProjectRoot44 } = await import("@cleocode/core/internal");
+  const projectRoot = getProjectRoot44();
   return {
     async dispatch(input2) {
       try {
@@ -25609,11 +26313,11 @@ var init_playbook2 = __esm({
         let sourcePath;
         if (file) {
           const resolved = resolvePath(file);
-          if (!existsSync2(resolved)) {
+          if (!existsSync3(resolved)) {
             return lafsError("E_NOT_FOUND", `playbook file not found: ${resolved}`, "validate");
           }
           sourcePath = resolved;
-          source = readFileSync4(resolved, "utf8");
+          source = readFileSync6(resolved, "utf8");
         } else {
           const loaded = await loadPlaybookByName(name);
           if (loaded === null) {
@@ -25669,8 +26373,8 @@ var init_playbook2 = __esm({
             projectRoot = __playbookRuntimeOverrides.projectRoot;
           } else {
             try {
-              const { getProjectRoot: getProjectRoot43 } = await import("@cleocode/core/internal");
-              projectRoot = getProjectRoot43();
+              const { getProjectRoot: getProjectRoot44 } = await import("@cleocode/core/internal");
+              projectRoot = getProjectRoot44();
             } catch {
               projectRoot = void 0;
             }
@@ -25734,14 +26438,14 @@ var init_playbook2 = __esm({
         const dispatcher = await buildDefaultDispatcher();
         let result;
         try {
-          const { getProjectRoot: getProjectRoot43 } = await import("@cleocode/core/internal");
+          const { getProjectRoot: getProjectRoot44 } = await import("@cleocode/core/internal");
           const opts = {
             db,
             playbook: parsed.definition,
             playbookHash: parsed.sourceHash,
             initialContext,
             dispatcher,
-            projectRoot: getProjectRoot43()
+            projectRoot: getProjectRoot44()
           };
           if (__playbookRuntimeOverrides.approvalSecret !== void 0) {
             opts.approvalSecret = __playbookRuntimeOverrides.approvalSecret;
@@ -26103,16 +26807,16 @@ async function orchestrateRejectOp(params) {
 async function orchestrateClassify(request, context, projectRoot) {
   try {
     const { getCleoCantWorkflowsDir } = await import("@cleocode/core/internal");
-    const { readFileSync: readFileSync18, readdirSync: readdirSync4, existsSync: existsSync17 } = await import("node:fs");
-    const { join: join33 } = await import("node:path");
+    const { readFileSync: readFileSync20, readdirSync: readdirSync4, existsSync: existsSync18 } = await import("node:fs");
+    const { join: join35 } = await import("node:path");
     const workflowsDir = getCleoCantWorkflowsDir();
     const combined = `${request} ${context ?? ""}`.toLowerCase();
     const matches = [];
-    if (existsSync17(workflowsDir)) {
+    if (existsSync18(workflowsDir)) {
       const files = readdirSync4(workflowsDir).filter((f) => f.endsWith(".cant"));
       for (const file of files) {
         try {
-          const src = readFileSync18(join33(workflowsDir, file), "utf-8");
+          const src = readFileSync20(join35(workflowsDir, file), "utf-8");
           const teamMatch = /^team\s+(\S+):/m.exec(src);
           if (!teamMatch) continue;
           const teamName = teamMatch[1];
@@ -26127,12 +26831,12 @@ async function orchestrateClassify(request, context, projectRoot) {
         }
       }
     }
-    const localCantDir = join33(projectRoot, CLEO_DIR_NAME, WORKFLOWS_SUBDIR);
-    if (existsSync17(localCantDir)) {
+    const localCantDir = join35(projectRoot, CLEO_DIR_NAME, WORKFLOWS_SUBDIR);
+    if (existsSync18(localCantDir)) {
       const files = readdirSync4(localCantDir).filter((f) => f.endsWith(".cant"));
       for (const file of files) {
         try {
-          const src = readFileSync18(join33(localCantDir, file), "utf-8");
+          const src = readFileSync20(join35(localCantDir, file), "utf-8");
           const teamMatch = /^team\s+(\S+):/m.exec(src);
           if (!teamMatch) continue;
           const teamName = teamMatch[1];
@@ -28584,7 +29288,13 @@ var init_session_context = __esm({
 });
 
 // packages/cleo/src/dispatch/domains/session.ts
-import { getDb, getLogger as getLogger13, getProjectRoot as getProjectRoot15, sessions } from "@cleocode/core/internal";
+import {
+  getDb,
+  getLogger as getLogger13,
+  getProjectRoot as getProjectRoot15,
+  lintSessionForCanonViolations,
+  sessions
+} from "@cleocode/core/internal";
 import { eq } from "drizzle-orm";
 async function sessionStatusOp() {
   return sessionStatus(getProjectRoot15());
@@ -28644,6 +29354,49 @@ async function sessionRecordDecisionOp(params) {
 async function sessionRecordAssumptionOp(params) {
   return sessionRecordAssumption(getProjectRoot15(), params);
 }
+async function sessionLintOp(params) {
+  if (!params.transcript) {
+    return {
+      success: false,
+      error: { code: "E_INVALID_INPUT", message: "transcript is required" }
+    };
+  }
+  try {
+    const result = lintSessionForCanonViolations({
+      transcriptPath: params.transcript,
+      projectRoot: getProjectRoot15()
+    });
+    const wireResult = {
+      transcriptPath: result.transcriptPath,
+      sessionId: result.sessionId,
+      passed: result.passed,
+      scanned: result.scanned,
+      // Clone to drop readonly modifiers for the wire shape.
+      violations: result.violations.map((v) => ({
+        sessionId: v.sessionId,
+        toolUseId: v.toolUseId,
+        tool: v.tool,
+        path: v.path,
+        docKind: v.docKind,
+        matchedPath: v.matchedPath,
+        kind: v.kind,
+        evidence: v.evidence,
+        fix: v.fix
+      })),
+      warnings: [...result.warnings],
+      mode: result.mode
+    };
+    return { success: true, data: wireResult };
+  } catch (err) {
+    return {
+      success: false,
+      error: {
+        code: "E_CANON_INVALID",
+        message: err instanceof Error ? err.message : String(err)
+      }
+    };
+  }
+}
 async function storeSessionOwnerAuthToken(projectRoot, sessionId, token) {
   const db = await getDb(projectRoot);
   db.update(sessions).set({ ownerAuthToken: token }).where(eq(sessions.id, sessionId)).run();
@@ -28671,7 +29424,8 @@ var init_session3 = __esm({
       suspend: sessionSuspendOp,
       gc: sessionGcOp,
       "record.decision": sessionRecordDecisionOp,
-      "record.assumption": sessionRecordAssumptionOp
+      "record.assumption": sessionRecordAssumptionOp,
+      lint: sessionLintOp
     };
     _sessionTypedHandler = defineTypedHandler("session", {
       // -------------------------------------------------------------------------
@@ -28862,6 +29616,23 @@ var init_session3 = __esm({
           return lafsError("E_INTERNAL", "record.assumption returned no data", "record.assumption");
         }
         return wrapCoreResult(result, "record.assumption");
+      },
+      // T9797 — agent-accountability harness. Returns a LAFS envelope whose
+      // `data` is a SessionLintResult; `error` is set on E_INVALID_INPUT
+      // (missing transcript) or E_CANON_INVALID (malformed canon.yml).
+      lint: async (params) => {
+        const result = await coreOps6.lint(params);
+        if (!result.success) {
+          return lafsError(
+            String(result.error?.code ?? "E_INTERNAL"),
+            result.error?.message ?? "Unknown error",
+            "lint"
+          );
+        }
+        if (!result.data) {
+          return lafsError("E_INTERNAL", "session.lint returned no data", "lint");
+        }
+        return lafsSuccess(result.data, "lint");
       }
     });
     QUERY_OPS8 = /* @__PURE__ */ new Set([
@@ -28872,7 +29643,8 @@ var init_session3 = __esm({
       "decision.log",
       "context.drift",
       "handoff.show",
-      "briefing.show"
+      "briefing.show",
+      "lint"
     ]);
     MUTATE_OPS8 = /* @__PURE__ */ new Set([
       "start",
@@ -30976,8 +31748,8 @@ var init_defaults = __esm({
 });
 
 // packages/cleo/src/dispatch/lib/config-loader.ts
-import { existsSync as existsSync3, readFileSync as readFileSync5 } from "fs";
-import { join as join5 } from "path";
+import { existsSync as existsSync4, readFileSync as readFileSync7 } from "fs";
+import { join as join7 } from "path";
 function loadFromEnv(key) {
   const envKey = `${ENV_PREFIX}${key.toUpperCase()}`;
   return process.env[envKey];
@@ -30998,12 +31770,12 @@ function parseEnvValue(key, value) {
 }
 function loadFromFile(projectRoot) {
   const root = projectRoot || process.cwd();
-  const configPath = join5(root, CLEO_DIR_NAME, CONFIG_JSON);
-  if (!existsSync3(configPath)) {
+  const configPath = join7(root, CLEO_DIR_NAME, CONFIG_JSON);
+  if (!existsSync4(configPath)) {
     return {};
   }
   try {
-    const content = readFileSync5(configPath, "utf-8");
+    const content = readFileSync7(configPath, "utf-8");
     const config = JSON.parse(content);
     const result = {};
     if (config.lifecycleEnforcement) {
@@ -31346,11 +32118,11 @@ var init_security = __esm({
 });
 
 // packages/cleo/src/dispatch/middleware/sanitizer.ts
-function createSanitizer(getProjectRoot43) {
+function createSanitizer(getProjectRoot44) {
   return async (req, next) => {
     if (req.params) {
       try {
-        const root = getProjectRoot43 ? getProjectRoot43() : void 0;
+        const root = getProjectRoot44 ? getProjectRoot44() : void 0;
         req.params = sanitizeParams(req.params, root, {
           domain: req.domain,
           operation: req.operation
@@ -31470,9 +32242,9 @@ __export(cli_exports, {
   resetCliDispatcher: () => resetCliDispatcher
 });
 import { randomUUID as randomUUID5 } from "node:crypto";
-import { existsSync as existsSync4 } from "node:fs";
+import { existsSync as existsSync5 } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname as dirname4, join as join6 } from "node:path";
+import { dirname as dirname4, join as join8 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 import { catalog, registerSkillLibraryFromPath } from "@cleocode/caamp";
 import { autoRecordDispatchTokenUsage, getProjectRoot as getProjectRoot21, hooks } from "@cleocode/core/internal";
@@ -31484,16 +32256,16 @@ function ensureCaampLibrary() {
       const req = createRequire(import.meta.url);
       const skillsPkgJson = req.resolve("@cleocode/skills/package.json");
       const candidate = dirname4(skillsPkgJson);
-      if (existsSync4(join6(candidate, "skills.json"))) {
+      if (existsSync5(join8(candidate, "skills.json"))) {
         skillsRoot = candidate;
       }
     } catch {
     }
     if (!skillsRoot) {
       const thisFile = fileURLToPath3(import.meta.url);
-      const packageRoot = join6(dirname4(thisFile), "..", "..", "..", "..", "..");
-      const candidate = join6(packageRoot, "packages", "skills");
-      if (existsSync4(join6(candidate, "skills.json"))) {
+      const packageRoot = join8(dirname4(thisFile), "..", "..", "..", "..", "..");
+      const candidate = join8(packageRoot, "packages", "skills");
+      if (existsSync5(join8(candidate, "skills.json"))) {
         skillsRoot = candidate;
       }
     }
@@ -31723,7 +32495,10 @@ var init_cli = __esm({
       E_INVALID_OPERATION: 2,
       E_MISSING_PARAMS: 2,
       E_NO_HANDLER: 1,
-      E_INTERNAL: 1
+      E_INTERNAL: 1,
+      // T9796 — docs canon CI gate: violation = fail-build, invalid = tool-error.
+      E_CANON_VIOLATION: 1,
+      E_CANON_INVALID: 2
     };
     _dispatcher = null;
   }
@@ -31885,7 +32660,7 @@ var add_batch_exports = {};
 __export(add_batch_exports, {
   addBatchCommand: () => addBatchCommand
 });
-import { existsSync as existsSync5, readFileSync as readFileSync6 } from "node:fs";
+import { existsSync as existsSync6, readFileSync as readFileSync8 } from "node:fs";
 var addBatchCommand;
 var init_add_batch = __esm({
   "packages/cleo/src/cli/commands/add-batch.ts"() {
@@ -31934,7 +32709,7 @@ var init_add_batch = __esm({
             return;
           }
         } else {
-          if (!existsSync5(filePath)) {
+          if (!existsSync6(filePath)) {
             cliError(
               `File not found: ${filePath}`,
               "E_NOT_FOUND",
@@ -31947,7 +32722,7 @@ var init_add_batch = __esm({
             process.exit(2);
             return;
           }
-          raw = readFileSync6(filePath, "utf-8");
+          raw = readFileSync8(filePath, "utf-8");
         }
         let tasks;
         try {
@@ -33304,12 +34079,12 @@ var init_agent = __esm({
             transportConfig: {},
             isActive: true
           });
-          const { existsSync: existsSync17, mkdirSync: mkdirSync7, writeFileSync: writeFileSync7 } = await import("node:fs");
-          const { join: join33 } = await import("node:path");
-          const cantDir = join33(CLEO_DIR_NAME, AGENTS_SUBDIR);
-          const cantPath = join33(cantDir, `${agentId}.cant`);
+          const { existsSync: existsSync18, mkdirSync: mkdirSync7, writeFileSync: writeFileSync7 } = await import("node:fs");
+          const { join: join35 } = await import("node:path");
+          const cantDir = join35(CLEO_DIR_NAME, AGENTS_SUBDIR);
+          const cantPath = join35(cantDir, `${agentId}.cant`);
           let cantScaffolded = false;
-          if (!existsSync17(cantPath)) {
+          if (!existsSync18(cantPath)) {
             mkdirSync7(cantDir, { recursive: true });
             const role = classification ?? "specialist";
             const cantContent = `---
@@ -33369,7 +34144,7 @@ agent ${agentId}:
               data: {
                 agentId: credential.agentId,
                 displayName: credential.displayName,
-                cantFile: cantScaffolded ? cantPath : existsSync17(cantPath) ? cantPath : null,
+                cantFile: cantScaffolded ? cantPath : existsSync18(cantPath) ? cantPath : null,
                 cantScaffolded
               }
             },
@@ -33490,8 +34265,8 @@ agent ${agentId}:
           const { AgentRegistryAccessor } = await import("@cleocode/core/agents");
           const { getDb: getDb3 } = await import("@cleocode/core/internal");
           const { createRuntime } = await import("@cleocode/runtime");
-          const { existsSync: existsSync17, readFileSync: readFileSync18 } = await import("node:fs");
-          const { join: join33 } = await import("node:path");
+          const { existsSync: existsSync18, readFileSync: readFileSync20 } = await import("node:fs");
+          const { join: join35 } = await import("node:path");
           await getDb3();
           const registry = new AgentRegistryAccessor(getProjectRoot23());
           const credential = await registry.get(args.agentId);
@@ -33511,9 +34286,9 @@ agent ${agentId}:
           }
           let profile = null;
           let cantValidation = null;
-          const cantPath = args.cant ?? join33(CLEO_DIR_NAME, AGENTS_SUBDIR, `${args.agentId}.cant`);
-          if (existsSync17(cantPath)) {
-            profile = readFileSync18(cantPath, "utf-8");
+          const cantPath = args.cant ?? join35(CLEO_DIR_NAME, AGENTS_SUBDIR, `${args.agentId}.cant`);
+          if (existsSync18(cantPath)) {
+            profile = readFileSync20(cantPath, "utf-8");
             try {
               const cantModule = await import("@cleocode/cant");
               const validate = "validate" in cantModule ? cantModule.validate : null;
@@ -34044,8 +34819,8 @@ Task ${args.taskId} reassigned to you by ${active.agentId}. Run: cleo show ${arg
           const { AgentRegistryAccessor } = await import("@cleocode/core/agents");
           const { getDb: getDb3 } = await import("@cleocode/core/internal");
           const { createRuntime } = await import("@cleocode/runtime");
-          const { existsSync: existsSync17 } = await import("node:fs");
-          const { join: join33 } = await import("node:path");
+          const { existsSync: existsSync18 } = await import("node:fs");
+          const { join: join35 } = await import("node:path");
           const { execFile: execFile2 } = await import("node:child_process");
           const { promisify: promisify2 } = await import("node:util");
           const execFileAsync = promisify2(execFile2);
@@ -34065,8 +34840,8 @@ Task ${args.taskId} reassigned to you by ${active.agentId}. Run: cleo show ${arg
           }
           await registry.update(args.agentId, { isActive: true });
           await registry.markUsed(args.agentId);
-          const cantPath = join33(CLEO_DIR_NAME, AGENTS_SUBDIR, `${args.agentId}.cant`);
-          const hasProfile = existsSync17(cantPath);
+          const cantPath = join35(CLEO_DIR_NAME, AGENTS_SUBDIR, `${args.agentId}.cant`);
+          const hasProfile = existsSync18(cantPath);
           const runtime = await createRuntime(registry, {
             agentId: args.agentId,
             pollIntervalMs: 5e3,
@@ -34924,11 +35699,11 @@ Task ${args.taskId} reassigned to you by ${active.agentId}. Run: cleo show ${arg
       async run({ args }) {
         let tempDir = null;
         try {
-          const { existsSync: existsSync17, mkdirSync: mkdirSync7, statSync, readdirSync: readdirSync4, copyFileSync } = await import("node:fs");
-          const { join: join33, basename, resolve: resolve9, extname } = await import("node:path");
+          const { existsSync: existsSync18, mkdirSync: mkdirSync7, statSync, readdirSync: readdirSync4, copyFileSync } = await import("node:fs");
+          const { join: join35, basename, resolve: resolve9, extname } = await import("node:path");
           const { tmpdir: tmpdir2 } = await import("node:os");
           const resolvedPath = resolve9(args.path);
-          if (!existsSync17(resolvedPath)) {
+          if (!existsSync18(resolvedPath)) {
             cliOutput(
               {
                 success: false,
@@ -34949,7 +35724,7 @@ Task ${args.taskId} reassigned to you by ${active.agentId}. Run: cleo show ${arg
             cantPath = resolvedPath;
           } else if (stat3.isFile() && ext === ".cantz") {
             const { execFileSync: execFileSync5 } = await import("node:child_process");
-            tempDir = join33(tmpdir2(), `cleo-agent-install-${Date.now()}`);
+            tempDir = join35(tmpdir2(), `cleo-agent-install-${Date.now()}`);
             mkdirSync7(tempDir, { recursive: true });
             try {
               execFileSync5("unzip", ["-o", "-q", resolvedPath, "-d", tempDir], {
@@ -34971,7 +35746,7 @@ Task ${args.taskId} reassigned to you by ${active.agentId}. Run: cleo show ${arg
               return;
             }
             const topLevel = readdirSync4(tempDir).filter(
-              (entry) => statSync(join33(tempDir, entry)).isDirectory()
+              (entry) => statSync(join35(tempDir, entry)).isDirectory()
             );
             if (topLevel.length !== 1) {
               cliOutput(
@@ -34988,8 +35763,8 @@ Task ${args.taskId} reassigned to you by ${active.agentId}. Run: cleo show ${arg
               return;
             }
             const agentName = topLevel[0];
-            const personaPath = join33(tempDir, agentName, "persona.cant");
-            if (!existsSync17(personaPath)) {
+            const personaPath = join35(tempDir, agentName, "persona.cant");
+            if (!existsSync18(personaPath)) {
               cliOutput(
                 {
                   success: false,
@@ -35003,12 +35778,12 @@ Task ${args.taskId} reassigned to you by ${active.agentId}. Run: cleo show ${arg
               process.exitCode = 6;
               return;
             }
-            cantPath = join33(tempDir, `${agentName}.cant`);
+            cantPath = join35(tempDir, `${agentName}.cant`);
             copyFileSync(personaPath, cantPath);
           } else if (stat3.isDirectory()) {
             const agentName = basename(resolvedPath);
-            const personaPath = join33(resolvedPath, "persona.cant");
-            if (!existsSync17(personaPath)) {
+            const personaPath = join35(resolvedPath, "persona.cant");
+            if (!existsSync18(personaPath)) {
               cliOutput(
                 {
                   success: false,
@@ -35022,9 +35797,9 @@ Task ${args.taskId} reassigned to you by ${active.agentId}. Run: cleo show ${arg
               process.exitCode = 6;
               return;
             }
-            tempDir = join33(tmpdir2(), `cleo-agent-install-${Date.now()}`);
+            tempDir = join35(tmpdir2(), `cleo-agent-install-${Date.now()}`);
             mkdirSync7(tempDir, { recursive: true });
-            cantPath = join33(tempDir, `${agentName}.cant`);
+            cantPath = join35(tempDir, `${agentName}.cant`);
             copyFileSync(personaPath, cantPath);
           } else {
             cliOutput(
@@ -35143,11 +35918,11 @@ Task ${args.taskId} reassigned to you by ${active.agentId}. Run: cleo show ${arg
       },
       async run({ args }) {
         try {
-          const { existsSync: existsSync17, statSync } = await import("node:fs");
+          const { existsSync: existsSync18, statSync } = await import("node:fs");
           const { resolve: resolve9, basename, dirname: dirname13 } = await import("node:path");
           const { execFileSync: execFileSync5 } = await import("node:child_process");
           const resolvedDir = resolve9(args.dir);
-          if (!existsSync17(resolvedDir) || !statSync(resolvedDir).isDirectory()) {
+          if (!existsSync18(resolvedDir) || !statSync(resolvedDir).isDirectory()) {
             cliOutput(
               {
                 success: false,
@@ -35161,9 +35936,9 @@ Task ${args.taskId} reassigned to you by ${active.agentId}. Run: cleo show ${arg
             process.exitCode = 4;
             return;
           }
-          const { join: join33 } = await import("node:path");
-          const personaPath = join33(resolvedDir, "persona.cant");
-          if (!existsSync17(personaPath)) {
+          const { join: join35 } = await import("node:path");
+          const personaPath = join35(resolvedDir, "persona.cant");
+          if (!existsSync18(personaPath)) {
             cliOutput(
               {
                 success: false,
@@ -35210,7 +35985,7 @@ Task ${args.taskId} reassigned to you by ${active.agentId}. Run: cleo show ${arg
               if (entry.isFile()) {
                 fileCount++;
               } else if (entry.isDirectory()) {
-                countFiles(join33(dirPath, entry.name));
+                countFiles(join35(dirPath, entry.name));
               }
             }
           };
@@ -35279,8 +36054,8 @@ Task ${args.taskId} reassigned to you by ${active.agentId}. Run: cleo show ${arg
       },
       async run({ args }) {
         try {
-          const { existsSync: existsSync17, mkdirSync: mkdirSync7, writeFileSync: writeFileSync7 } = await import("node:fs");
-          const { join: join33 } = await import("node:path");
+          const { existsSync: existsSync18, mkdirSync: mkdirSync7, writeFileSync: writeFileSync7 } = await import("node:fs");
+          const { join: join35 } = await import("node:path");
           const { homedir: homedir8 } = await import("node:os");
           const name = args.name;
           const role = args.role;
@@ -35340,13 +36115,13 @@ Task ${args.taskId} reassigned to you by ${active.agentId}. Run: cleo show ${arg
           let targetRoot;
           if (isGlobal) {
             const home = homedir8();
-            const xdgData = process.env["XDG_DATA_HOME"] ?? join33(home, ".local", "share");
-            targetRoot = join33(xdgData, "cleo", "cant", "agents");
+            const xdgData = process.env["XDG_DATA_HOME"] ?? join35(home, ".local", "share");
+            targetRoot = join35(xdgData, "cleo", "cant", "agents");
           } else {
-            targetRoot = join33(getProjectRoot23(), CLEO_DIR_NAME, CANT_AGENTS_SUBDIR);
+            targetRoot = join35(getProjectRoot23(), CLEO_DIR_NAME, CANT_AGENTS_SUBDIR);
           }
-          const agentDir = join33(targetRoot, name);
-          if (existsSync17(agentDir)) {
+          const agentDir = join35(targetRoot, name);
+          if (existsSync18(agentDir)) {
             cliOutput(
               {
                 success: false,
@@ -35370,29 +36145,29 @@ Task ${args.taskId} reassigned to you by ${active.agentId}. Run: cleo show ${arg
             domain,
             parent
           });
-          writeFileSync7(join33(agentDir, "persona.cant"), personaContent, "utf-8");
+          writeFileSync7(join35(agentDir, "persona.cant"), personaContent, "utf-8");
           const manifest = generateManifest({ name, role, tier, domain });
           writeFileSync7(
-            join33(agentDir, "manifest.json"),
+            join35(agentDir, "manifest.json"),
             `${JSON.stringify(manifest, null, 2)}
 `,
             "utf-8"
           );
           const createdFiles = [
-            join33(agentDir, "persona.cant"),
-            join33(agentDir, "manifest.json")
+            join35(agentDir, "persona.cant"),
+            join35(agentDir, "manifest.json")
           ];
           if (team) {
             const teamConfigContent = generateTeamConfig(name, role, team);
-            writeFileSync7(join33(agentDir, "team-config.cant"), teamConfigContent, "utf-8");
-            createdFiles.push(join33(agentDir, "team-config.cant"));
+            writeFileSync7(join35(agentDir, "team-config.cant"), teamConfigContent, "utf-8");
+            createdFiles.push(join35(agentDir, "team-config.cant"));
           }
           if (seedBrain) {
-            const expertiseDir = join33(agentDir, "expertise");
+            const expertiseDir = join35(agentDir, "expertise");
             mkdirSync7(expertiseDir, { recursive: true });
             const seedContent = generateMentalModelSeed(name, role, domain);
-            writeFileSync7(join33(expertiseDir, "mental-model-seed.md"), seedContent, "utf-8");
-            createdFiles.push(join33(expertiseDir, "mental-model-seed.md"));
+            writeFileSync7(join35(expertiseDir, "mental-model-seed.md"), seedContent, "utf-8");
+            createdFiles.push(join35(expertiseDir, "mental-model-seed.md"));
             try {
               const { execFile: execFile2 } = await import("node:child_process");
               const { promisify: promisify2 } = await import("node:util");
@@ -35491,17 +36266,17 @@ Task ${args.taskId} reassigned to you by ${active.agentId}. Run: cleo show ${arg
       },
       async run({ args }) {
         try {
-          const { existsSync: existsSync17, readFileSync: readFileSync18, mkdirSync: mkdirSync7 } = await import("node:fs");
-          const { resolve: resolve9, join: join33 } = await import("node:path");
+          const { existsSync: existsSync18, readFileSync: readFileSync20, mkdirSync: mkdirSync7 } = await import("node:fs");
+          const { resolve: resolve9, join: join35 } = await import("node:path");
           const specPath = resolve9(args.spec);
-          if (!existsSync17(specPath)) {
+          if (!existsSync18(specPath)) {
             cliError(`spec file not found: ${specPath}`, 4, { name: "E_NOT_FOUND" });
             process.exitCode = 4;
             return;
           }
-          const specContent = readFileSync18(specPath, "utf-8");
+          const specContent = readFileSync20(specPath, "utf-8");
           const projectRoot = getProjectRoot23();
-          const outputDir = args["output-dir"] ? resolve9(args["output-dir"]) : join33(projectRoot, ".cleo", "cant", "agents");
+          const outputDir = args["output-dir"] ? resolve9(args["output-dir"]) : join35(projectRoot, ".cleo", "cant", "agents");
           mkdirSync7(outputDir, { recursive: true });
           if (args["dry-run"]) {
             cliOutput(
@@ -36102,9 +36877,9 @@ var init_consent = __esm({
 });
 
 // packages/cleo/src/cli/commands/auth/list.ts
-import { existsSync as existsSync6 } from "node:fs";
+import { existsSync as existsSync7 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
-import { join as join7 } from "node:path";
+import { join as join9 } from "node:path";
 function formatExpiry(expiresAt) {
   if (expiresAt == null) return "never";
   const remaining = expiresAt - Date.now();
@@ -36181,8 +36956,8 @@ var init_list = __esm({
           const p = a2.provider.localeCompare(b.provider);
           return p !== 0 ? p : a2.label.localeCompare(b.label);
         });
-        const claudeCredsPath = join7(homedir2(), ".claude", ".credentials.json");
-        const hint = existsSync6(claudeCredsPath) && entries.every((e) => e.source !== "claude-code") ? "Hint: Claude Code OAuth detected at ~/.claude/.credentials.json but consent is off. Run `cleo auth consent --enable-claude-code` to seed it into the pool." : null;
+        const claudeCredsPath = join9(homedir2(), ".claude", ".credentials.json");
+        const hint = existsSync7(claudeCredsPath) && entries.every((e) => e.source !== "claude-code") ? "Hint: Claude Code OAuth detected at ~/.claude/.credentials.json but consent is off. Run `cleo auth consent --enable-claude-code` to seed it into the pool." : null;
         cliOutput(
           { entries, ...hint !== null ? { hint } : {} },
           {
@@ -36196,8 +36971,8 @@ var init_list = __esm({
 });
 
 // packages/cleo/src/cli/commands/auth/migrate-project-secrets.ts
-import { existsSync as existsSync7, readFileSync as readFileSync7, writeFileSync as writeFileSync2 } from "node:fs";
-import { join as join8 } from "node:path";
+import { existsSync as existsSync8, readFileSync as readFileSync9, writeFileSync as writeFileSync2 } from "node:fs";
+import { join as join10 } from "node:path";
 import { createInterface } from "node:readline";
 function resolveProjectRootArg(arg) {
   if (typeof arg === "string" && arg.length > 0) return arg;
@@ -36205,7 +36980,7 @@ function resolveProjectRootArg(arg) {
 }
 function projectConfigPath(projectRoot) {
   const cleoDir = process.env["CLEO_DIR"] ?? ".cleo";
-  return join8(projectRoot, cleoDir, "config.json");
+  return join10(projectRoot, cleoDir, "config.json");
 }
 function extractApiKeyEntries(config) {
   if (!config || typeof config !== "object") return [];
@@ -36263,7 +37038,7 @@ async function promptYesNo(question) {
 }
 async function runMigrateProjectSecrets(opts) {
   const configPath = projectConfigPath(opts.projectRoot);
-  if (!existsSync7(configPath)) {
+  if (!existsSync8(configPath)) {
     return {
       configPath,
       backupPath: null,
@@ -36272,7 +37047,7 @@ async function runMigrateProjectSecrets(opts) {
       dryRun: opts.dryRun
     };
   }
-  const raw = readFileSync7(configPath, "utf-8");
+  const raw = readFileSync9(configPath, "utf-8");
   let parsed;
   try {
     parsed = JSON.parse(raw);
@@ -37119,9 +37894,9 @@ var init_backup = __esm({
       async run({ args }) {
         const scope = args.scope;
         const { packBundle } = await import("@cleocode/core/store/backup-pack.js");
-        const { getProjectRoot: getProjectRoot43 } = await import("@cleocode/core");
+        const { getProjectRoot: getProjectRoot44 } = await import("@cleocode/core");
         const includesProject = scope === "project" || scope === "all";
-        const projectRoot = includesProject ? getProjectRoot43() : void 0;
+        const projectRoot = includesProject ? getProjectRoot44() : void 0;
         let passphrase;
         if (args.encrypt === true) {
           passphrase = process.env["CLEO_BACKUP_PASSPHRASE"];
@@ -37197,12 +37972,12 @@ var init_backup = __esm({
       },
       async run({ args }) {
         const bundlePath = args.bundle;
-        const { getProjectRoot: getProjectRoot43, getCleoHome: getCleoHome6, getCleoVersion } = await import("@cleocode/core");
+        const { getProjectRoot: getProjectRoot44, getCleoHome: getCleoHome6, getCleoVersion } = await import("@cleocode/core");
         const { BundleError, cleanupStaging, unpackBundle } = await import("@cleocode/core/store/backup-unpack.js");
         const { regenerateConfigJson, regenerateProjectContextJson, regenerateProjectInfoJson } = await import("@cleocode/core/store/regenerators.js");
         const { regenerateAndCompare } = await import("@cleocode/core/store/restore-json-merge.js");
         const { buildConflictReport, writeConflictReport } = await import("@cleocode/core/store/restore-conflict-report.js");
-        const projectRoot = getProjectRoot43();
+        const projectRoot = getProjectRoot44();
         if (args.force !== true) {
           const existing = checkForExistingData(projectRoot, getCleoHome6());
           if (existing.length > 0) {
@@ -37802,13 +38577,13 @@ var briefing_exports = {};
 __export(briefing_exports, {
   briefingCommand: () => briefingCommand
 });
-import { existsSync as existsSync8, readFileSync as readFileSync8 } from "node:fs";
-import { join as join9 } from "node:path";
+import { existsSync as existsSync9, readFileSync as readFileSync10 } from "node:fs";
+import { join as join11 } from "node:path";
 import { pushWarning } from "@cleocode/core";
 import { resolveLegacyCleoDir } from "@cleocode/paths";
 function resolveInjectionTemplatePath() {
   const xdgConfig = resolveLegacyCleoDir(process.env["XDG_CONFIG_HOME"]);
-  return join9(xdgConfig, "templates", "CLEO-INJECTION.md");
+  return join11(xdgConfig, "templates", "CLEO-INJECTION.md");
 }
 function extractSection(content, sectionName) {
   const openTag = `<!-- CLEO-INJECTION:section=${sectionName} -->`;
@@ -37835,7 +38610,7 @@ function renderForAdapter(sectionName, content, format) {
 }
 async function runBriefingInject(sectionName, formatStr) {
   const templatePath = resolveInjectionTemplatePath();
-  if (!existsSync8(templatePath)) {
+  if (!existsSync9(templatePath)) {
     pushWarning({
       code: "W_TEMPLATE_INJECT_FAILED",
       message: `CLEO-INJECTION.md not found at ${templatePath}`
@@ -37852,7 +38627,7 @@ async function runBriefingInject(sectionName, formatStr) {
     process.exitCode = 1;
     return;
   }
-  const content = readFileSync8(templatePath, "utf-8");
+  const content = readFileSync10(templatePath, "utf-8");
   const section = extractSection(content, sectionName);
   if (section === null) {
     const available = INJECTION_SECTION_NAMES.join(", ");
@@ -38014,7 +38789,7 @@ __export(caamp_exports, {
   caampCommand: () => caampCommand
 });
 import { homedir as homedir3 } from "node:os";
-import { join as join10 } from "node:path";
+import { join as join12 } from "node:path";
 var dedupeCommand, caampCommand;
 var init_caamp = __esm({
   "packages/cleo/src/cli/commands/caamp.ts"() {
@@ -38051,18 +38826,18 @@ var init_caamp = __esm({
         } else {
           const home = homedir3();
           filePaths = [
-            join10(home, ".agents", "AGENTS.md"),
+            join12(home, ".agents", "AGENTS.md"),
             // project-level AGENTS.md in cwd
-            join10(process.cwd(), "AGENTS.md")
+            join12(process.cwd(), "AGENTS.md")
           ];
         }
         if (args["dry-run"]) {
           const { parseCaampBlocks } = await import("@cleocode/caamp");
-          const { existsSync: existsSync17 } = await import("node:fs");
+          const { existsSync: existsSync18 } = await import("node:fs");
           const { readFile: readFile7 } = await import("node:fs/promises");
           const dryResults = [];
           for (const filePath of filePaths) {
-            if (!existsSync17(filePath)) {
+            if (!existsSync18(filePath)) {
               dryResults.push({ filePath, exists: false, blockCount: 0, wouldRemove: 0 });
               continue;
             }
@@ -38160,13 +38935,13 @@ var cant_exports = {};
 __export(cant_exports, {
   cantCommand: () => cantCommand
 });
-import { existsSync as existsSync9, mkdirSync as mkdirSync2, readFileSync as readFileSync9, writeFileSync as writeFileSync3 } from "node:fs";
-import { dirname as dirname5, isAbsolute, join as join11, resolve as resolve4 } from "node:path";
+import { existsSync as existsSync10, mkdirSync as mkdirSync2, readFileSync as readFileSync11, writeFileSync as writeFileSync3 } from "node:fs";
+import { dirname as dirname5, isAbsolute, join as join13, resolve as resolve4 } from "node:path";
 function resolveFilePath(file) {
   return isAbsolute(file) ? file : resolve4(process.cwd(), file);
 }
 function ensureExists(filePath, operation) {
-  if (existsSync9(filePath)) return true;
+  if (existsSync10(filePath)) return true;
   cliError(`File not found: ${filePath}`, "E_FILE_READ");
   process.exitCode = 3;
   if (process.env["CLEO_DEBUG"]) humanWarn(`(operation: ${operation})`);
@@ -38316,7 +39091,7 @@ var init_cant = __esm({
         if (!ensureExists(filePath, "cant.migrate")) return;
         try {
           const mod = await loadMigrateEngine();
-          const content = readFileSync9(filePath, "utf-8");
+          const content = readFileSync11(filePath, "utf-8");
           const result = mod.migrateMarkdown(content, filePath, {
             write: isWrite,
             verbose: isVerbose,
@@ -38326,7 +39101,7 @@ var init_cant = __esm({
             const projectRoot = process.cwd();
             let written = 0;
             for (const outputFile of result.outputFiles) {
-              const outputPath = isAbsolute(outputFile.path) ? outputFile.path : join11(projectRoot, outputFile.path);
+              const outputPath = isAbsolute(outputFile.path) ? outputFile.path : join13(projectRoot, outputFile.path);
               mkdirSync2(dirname5(outputPath), { recursive: true });
               writeFileSync3(outputPath, outputFile.content, "utf-8");
               written++;
@@ -38382,7 +39157,7 @@ var chain_exports = {};
 __export(chain_exports, {
   chainCommand: () => chainCommand
 });
-import { readFileSync as readFileSync10 } from "node:fs";
+import { readFileSync as readFileSync12 } from "node:fs";
 var showCommand3, listCommand5, addCommand3, instantiateCommand, advanceCommand, chainCommand;
 var init_chain = __esm({
   "packages/cleo/src/cli/commands/chain.ts"() {
@@ -38424,7 +39199,7 @@ var init_chain = __esm({
         }
       },
       async run({ args }) {
-        const chainJson = JSON.parse(readFileSync10(args.file, "utf-8"));
+        const chainJson = JSON.parse(readFileSync12(args.file, "utf-8"));
         await dispatchFromCli(
           "mutate",
           "pipeline",
@@ -38500,6 +39275,142 @@ var init_chain = __esm({
   }
 });
 
+// packages/cleo/src/cli/commands/changeset.ts
+var changeset_exports = {};
+__export(changeset_exports, {
+  changesetCommand: () => changesetCommand
+});
+import { changesets, getProjectRoot as getProjectRoot27 } from "@cleocode/core";
+function isValidKind(raw) {
+  return typeof raw === "string" && CHANGESET_KINDS.includes(raw);
+}
+function parseTasksFlag(raw) {
+  if (typeof raw !== "string" || raw.length === 0) return void 0;
+  const tasks = raw.split(",").map((t) => t.trim()).filter((t) => t.length > 0);
+  return tasks.length > 0 ? tasks : void 0;
+}
+function parsePrsFlag(raw) {
+  if (typeof raw !== "string" || raw.length === 0) return void 0;
+  const numbers = [];
+  for (const segment of raw.split(",")) {
+    const trimmed = segment.trim();
+    if (trimmed.length === 0) continue;
+    const n = Number.parseInt(trimmed, 10);
+    if (Number.isFinite(n) && n > 0) numbers.push(n);
+  }
+  return numbers.length > 0 ? numbers : void 0;
+}
+var addCommand4, changesetCommand;
+var init_changeset = __esm({
+  "packages/cleo/src/cli/commands/changeset.ts"() {
+    "use strict";
+    init_src2();
+    init_dist();
+    init_renderers();
+    addCommand4 = defineCommand({
+      meta: {
+        name: "add",
+        description: "Author a task-anchored changeset entry. Dual-writes to .changeset/<slug>.md AND the docs SSoT blob store. Slug must match /^t\\d+-[a-z0-9-]+$/ (e.g. t9793-changeset-ssot-integration)."
+      },
+      args: {
+        slug: {
+          type: "string",
+          description: "Filename slug (sans .md). Must match /^t\\d+-[a-z0-9-]+$/. Example: t9793-changeset-ssot-integration",
+          required: true
+        },
+        tasks: {
+          type: "string",
+          description: "Comma-separated CLEO task IDs (T####). Example: T9793,T9788",
+          required: true
+        },
+        kind: {
+          type: "string",
+          description: `Type of change: ${CHANGESET_KINDS.join(" | ")}`,
+          required: true
+        },
+        summary: {
+          type: "string",
+          description: "One-line user-facing description of the change",
+          required: true
+        },
+        prs: {
+          type: "string",
+          description: "Comma-separated PR numbers, when known. Example: 349,357"
+        },
+        notes: {
+          type: "string",
+          description: "Optional longer-form markdown body (becomes the file body)"
+        },
+        breaking: {
+          type: "string",
+          description: "Migration note. REQUIRED when --kind is `breaking`."
+        },
+        "attached-by": {
+          type: "string",
+          description: "Agent identity recorded on the SSoT row (default: cleo-changeset)"
+        }
+      },
+      async run({ args }) {
+        if (!isValidKind(args.kind)) {
+          cliError(`--kind must be one of: ${CHANGESET_KINDS.join(" | ")} \u2014 got '${args.kind}'`, 6, {
+            name: "E_VALIDATION",
+            fix: `cleo changeset add --kind feat ... (or one of: ${CHANGESET_KINDS.join(", ")})`
+          });
+          process.exit(6);
+        }
+        const kind = args.kind;
+        const tasks = parseTasksFlag(args.tasks);
+        if (!tasks) {
+          cliError("--tasks must contain at least one task ID", 6, { name: "E_VALIDATION" });
+          process.exit(6);
+        }
+        const prs = parsePrsFlag(args.prs);
+        const entry = {
+          id: String(args.slug),
+          tasks,
+          kind,
+          summary: String(args.summary),
+          ...prs !== void 0 ? { prs } : {},
+          ...typeof args.notes === "string" && args.notes.length > 0 ? { notes: args.notes } : {},
+          ...typeof args.breaking === "string" && args.breaking.length > 0 ? { breaking: args.breaking } : {}
+        };
+        const projectRoot = getProjectRoot27();
+        const outcome = await changesets.writeChangesetEntry(entry, {
+          projectRoot,
+          ...typeof args["attached-by"] === "string" && args["attached-by"].length > 0 ? { attachedBy: args["attached-by"] } : {}
+        });
+        if (!outcome.ok) {
+          const err = outcome.error;
+          const hint = err.code === "E_SLUG_PATTERN_MISMATCH" && err.example ? `example slug: ${err.example}` : void 0;
+          cliError(err.message, 6 /* VALIDATION_ERROR */, {
+            name: err.code,
+            ...hint ? { fix: hint } : {}
+          });
+          process.exit(6 /* VALIDATION_ERROR */);
+        }
+        const result = outcome.result;
+        humanInfo(`Wrote ${result.filePath}`);
+        humanInfo(`Wrote SSoT blob ${result.attachmentId} (sha=${result.sha256.slice(0, 12)}\u2026)`);
+        cliOutput(result, { command: "changeset add", operation: "changeset.add" });
+      }
+    });
+    changesetCommand = defineCommand({
+      meta: {
+        name: "changeset",
+        description: "Author task-anchored changeset entries that dual-write to .changeset/*.md AND the docs SSoT blob store (T9793)."
+      },
+      subCommands: {
+        add: addCommand4
+      },
+      async run({ cmd, rawArgs }) {
+        const firstArg = rawArgs?.find((a) => !a.startsWith("-"));
+        if (firstArg && cmd.subCommands && firstArg in cmd.subCommands) return;
+        await showUsage(cmd);
+      }
+    });
+  }
+});
+
 // packages/cleo/src/cli/lib/registry-args.ts
 function getOperationParams(gateway, domain, operation) {
   const def = OPERATIONS.find(
@@ -38520,7 +39431,7 @@ var check_exports = {};
 __export(check_exports, {
   checkCommand: () => checkCommand
 });
-var SUPPORTED_PROTOCOL_TYPES, checkSchemaCommand, checkCoherenceCommand, checkTaskCommand, checkOutputCommand, checkChainValidateCommand, checkCanonCommand, checkProtocolCommand, checkProvenanceCommand, checkCommand;
+var SUPPORTED_PROTOCOL_TYPES, checkSchemaCommand, checkCoherenceCommand, checkTaskCommand, checkOutputCommand, checkChainValidateCommand, checkCanonDocsCommand, checkCanonCommand, checkProtocolCommand, checkProvenanceCommand, checkCommand;
 var init_check2 = __esm({
   "packages/cleo/src/cli/commands/check.ts"() {
     "use strict";
@@ -38609,10 +39520,10 @@ var init_check2 = __esm({
         }
       },
       async run({ args }) {
-        const { readFileSync: readFileSync18 } = await import("node:fs");
+        const { readFileSync: readFileSync20 } = await import("node:fs");
         let chain;
         try {
-          chain = JSON.parse(readFileSync18(args.file, "utf8"));
+          chain = JSON.parse(readFileSync20(args.file, "utf8"));
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);
           cliError(`Failed to read or parse chain file: ${message}`, 2, {
@@ -38630,9 +39541,35 @@ var init_check2 = __esm({
         );
       }
     });
+    checkCanonDocsCommand = defineCommand({
+      meta: {
+        name: "docs",
+        description: "CI gate: block raw *.md writes that bypass the docs SSoT (T9796)"
+      },
+      args: {
+        base: {
+          type: "string",
+          description: "Git ref to diff against (default: origin/main)"
+        }
+      },
+      async run({ args }) {
+        await dispatchFromCli(
+          "query",
+          "check",
+          "canon.docs",
+          { baseRef: args.base },
+          { command: "check", operation: "check.canon.docs" }
+        );
+      }
+    });
     checkCanonCommand = defineCommand({
       meta: { name: "canon", description: "CI gate: detect canon drift between docs and live code" },
-      async run() {
+      subCommands: {
+        docs: checkCanonDocsCommand
+      },
+      async run({ cmd, rawArgs }) {
+        const firstArg = rawArgs?.find((a) => !a.startsWith("-"));
+        if (firstArg && cmd.subCommands && firstArg in cmd.subCommands) return;
         await dispatchFromCli("query", "check", "canon", {}, { command: "check" });
       }
     });
@@ -38800,7 +39737,7 @@ var init_check2 = __esm({
         }
       },
       async run({ args }) {
-        const { execSync } = await import("node:child_process");
+        const { execSync: execSync2 } = await import("node:child_process");
         const since = args.since;
         const branch = args.branch || "HEAD";
         const strict = Boolean(args.strict);
@@ -38808,7 +39745,7 @@ var init_check2 = __esm({
         const range = since ? `${since}..${branch}` : branch;
         let logOutput;
         try {
-          logOutput = execSync(`git log --no-merges --pretty=format:"%H	%s" -n ${limit} ${range}`, {
+          logOutput = execSync2(`git log --no-merges --pretty=format:"%H	%s" -n ${limit} ${range}`, {
             encoding: "utf8",
             stdio: ["pipe", "pipe", "pipe"]
           });
@@ -39084,9 +40021,9 @@ var init_code = __esm({
           async run({ args }) {
             await requireTreeSitter();
             const { smartOutline } = await import("@cleocode/core/internal");
-            const { join: join33 } = await import("node:path");
+            const { join: join35 } = await import("node:path");
             const root = process.cwd();
-            const absPath = args.file.startsWith("/") ? args.file : join33(root, args.file);
+            const absPath = args.file.startsWith("/") ? args.file : join35(root, args.file);
             const result = smartOutline(absPath, root);
             if (result.errors.length > 0 && result.symbols.length === 0) {
               cliError(result.errors.join(", "), 1, { name: "E_OUTLINE_FAILED" });
@@ -39177,9 +40114,9 @@ var init_code = __esm({
           async run({ args }) {
             await requireTreeSitter();
             const { smartUnfold } = await import("@cleocode/core/internal");
-            const { join: join33 } = await import("node:path");
+            const { join: join35 } = await import("node:path");
             const root = process.cwd();
-            const absPath = args.file.startsWith("/") ? args.file : join33(root, args.file);
+            const absPath = args.file.startsWith("/") ? args.file : join35(root, args.file);
             const result = smartUnfold(absPath, args.symbol, root);
             if (!result.found) {
               const errs = result.errors.length > 0 ? `: ${result.errors.join(", ")}` : "";
@@ -40298,7 +41235,7 @@ var curator_exports = {};
 __export(curator_exports, {
   curatorCommand: () => curatorCommand
 });
-import { join as join12 } from "node:path";
+import { join as join14 } from "node:path";
 import { getCleoHome } from "@cleocode/paths";
 async function loadCurator() {
   return import("@cleocode/core/sentient/curator.js");
@@ -40328,7 +41265,7 @@ var init_curator = __esm({
         try {
           const { runCuratorTick } = await loadCurator();
           const { readCuratorConfig } = await loadDaemon();
-          const configPath = join12(getCleoHome(), "config.json");
+          const configPath = join14(getCleoHome(), "config.json");
           const cfg = await readCuratorConfig(configPath);
           const result = await runCuratorTick({
             dryRun: args["dry-run"] === true,
@@ -40369,7 +41306,7 @@ var init_curator = __esm({
       async run() {
         try {
           const { readCuratorConfig, curatorCronExpression } = await loadDaemon();
-          const configPath = join12(getCleoHome(), "config.json");
+          const configPath = join14(getCleoHome(), "config.json");
           const cfg = await readCuratorConfig(configPath);
           cliOutput(
             {
@@ -40443,8 +41380,8 @@ var daemon_exports = {};
 __export(daemon_exports, {
   daemonCommand: () => daemonCommand
 });
-import { existsSync as existsSync10 } from "node:fs";
-import { join as join13 } from "node:path";
+import { existsSync as existsSync11 } from "node:fs";
+import { join as join15 } from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 import { getGCDaemonStatus, spawnGCDaemon, stopGCDaemon } from "@cleocode/core/gc/daemon.js";
 import {
@@ -40510,9 +41447,9 @@ async function showDaemonStatus(cleoDir, projectRoot) {
 }
 function resolveDaemonInstallerScript() {
   const filePath = fileURLToPath4(import.meta.url);
-  const candidate1 = join13(filePath, "..", "..", "..", "scripts", "install-daemon-service.mjs");
-  if (existsSync10(candidate1)) return candidate1;
-  const candidate2 = join13(
+  const candidate1 = join15(filePath, "..", "..", "..", "scripts", "install-daemon-service.mjs");
+  if (existsSync11(candidate1)) return candidate1;
+  const candidate2 = join15(
     filePath,
     "..",
     "..",
@@ -40584,13 +41521,13 @@ var init_daemon = __esm({
             {
               pid,
               cleoDir,
-              logs: join13(cleoDir, "logs", "gc.log"),
+              logs: join15(cleoDir, "logs", "gc.log"),
               message: `GC daemon started (PID ${pid})`
             },
             {
               command: "daemon",
               operation: "daemon.start",
-              message: `GC daemon started (PID ${pid}) \u2014 Logs: ${join13(cleoDir, "logs", "gc.log")}`
+              message: `GC daemon started (PID ${pid}) \u2014 Logs: ${join15(cleoDir, "logs", "gc.log")}`
             }
           );
         } catch (err) {
@@ -41219,12 +42156,12 @@ var detect_drift_exports = {};
 __export(detect_drift_exports, {
   detectDriftCommand: () => detectDriftCommand
 });
-import { existsSync as existsSync11, readdirSync, readFileSync as readFileSync11 } from "node:fs";
-import { dirname as dirname6, join as join14 } from "node:path";
+import { existsSync as existsSync12, readdirSync, readFileSync as readFileSync13 } from "node:fs";
+import { dirname as dirname6, join as join16 } from "node:path";
 function findProjectRoot() {
   let currentDir = process.cwd();
   while (currentDir !== "/") {
-    if (existsSync11(join14(currentDir, "package.json"))) {
+    if (existsSync12(join16(currentDir, "package.json"))) {
       return currentDir;
     }
     const parent = dirname6(currentDir);
@@ -41248,11 +42185,11 @@ var init_detect_drift = __esm({
       },
       async run() {
         const projectRoot = findProjectRoot();
-        const isCleoRepo = existsSync11(join14(projectRoot, "packages", "cleo", "src"));
-        const cleoSrcRoot = isCleoRepo ? join14(projectRoot, "packages", "cleo", "src") : join14(projectRoot, "src");
+        const isCleoRepo = existsSync12(join16(projectRoot, "packages", "cleo", "src"));
+        const cleoSrcRoot = isCleoRepo ? join16(projectRoot, "packages", "cleo", "src") : join16(projectRoot, "src");
         const safeRead = (filePath) => {
           try {
-            return readFileSync11(filePath, "utf-8");
+            return readFileSync13(filePath, "utf-8");
           } catch {
             return "";
           }
@@ -41263,8 +42200,8 @@ var init_detect_drift = __esm({
             checks: [],
             recommendations: []
           };
-          const injPath = join14(projectRoot, CLEO_DIR_NAME, TEMPLATES_SUBDIR, CLEO_INJECTION_MD);
-          if (existsSync11(injPath)) {
+          const injPath = join16(projectRoot, CLEO_DIR_NAME, TEMPLATES_SUBDIR, CLEO_INJECTION_MD);
+          if (existsSync12(injPath)) {
             const content = safeRead(injPath);
             userResult.checks.push({
               name: "Agent injection",
@@ -41315,10 +42252,10 @@ var init_detect_drift = __esm({
           }
         };
         try {
-          const specPath = join14(projectRoot, "docs", "specs", "CLEO-OPERATION-CONSTITUTION.md");
-          const registryPath = join14(cleoSrcRoot, "dispatch", "registry.ts");
-          const dispatchDomainsDir = join14(cleoSrcRoot, "dispatch", "domains");
-          if (!existsSync11(specPath)) {
+          const specPath = join16(projectRoot, "docs", "specs", "CLEO-OPERATION-CONSTITUTION.md");
+          const registryPath = join16(cleoSrcRoot, "dispatch", "registry.ts");
+          const dispatchDomainsDir = join16(cleoSrcRoot, "dispatch", "domains");
+          if (!existsSync12(specPath)) {
             addCheck("Gateway-to-spec sync", "fail", "CLEO-OPERATION-CONSTITUTION.md missing", [
               {
                 severity: "error",
@@ -41328,7 +42265,7 @@ var init_detect_drift = __esm({
                 recommendation: "Create docs/specs/CLEO-OPERATION-CONSTITUTION.md with canonical operation definitions"
               }
             ]);
-          } else if (!existsSync11(registryPath) || !existsSync11(dispatchDomainsDir)) {
+          } else if (!existsSync12(registryPath) || !existsSync12(dispatchDomainsDir)) {
             addCheck("Gateway-to-spec sync", "fail", "Dispatch registry or domains missing", [
               {
                 severity: "error",
@@ -41386,9 +42323,9 @@ var init_detect_drift = __esm({
           ]);
         }
         try {
-          const cliDir = join14(cleoSrcRoot, "cli", "commands");
-          const coreDir = isCleoRepo ? join14(projectRoot, "packages", "core", "src") : join14(projectRoot, "src", "core");
-          if (!existsSync11(cliDir)) {
+          const cliDir = join16(cleoSrcRoot, "cli", "commands");
+          const coreDir = isCleoRepo ? join16(projectRoot, "packages", "core", "src") : join16(projectRoot, "src", "core");
+          if (!existsSync12(cliDir)) {
             addCheck("CLI-to-core sync", "fail", "CLI commands directory missing", [
               {
                 severity: "error",
@@ -41397,7 +42334,7 @@ var init_detect_drift = __esm({
                 recommendation: "Verify TypeScript source structure is intact"
               }
             ]);
-          } else if (!existsSync11(coreDir)) {
+          } else if (!existsSync12(coreDir)) {
             addCheck("CLI-to-core sync", "fail", "Core directory missing", [
               {
                 severity: "error",
@@ -41414,8 +42351,8 @@ var init_detect_drift = __esm({
           addCheck("CLI-to-core sync", "fail", `Error: ${getErrorMessage(e)}`);
         }
         try {
-          const domainsDir = join14(cleoSrcRoot, "dispatch", "domains");
-          if (!existsSync11(domainsDir)) {
+          const domainsDir = join16(cleoSrcRoot, "dispatch", "domains");
+          if (!existsSync12(domainsDir)) {
             addCheck("Domain handler coverage", "fail", "Dispatch domains directory missing", [
               {
                 severity: "error",
@@ -41432,8 +42369,8 @@ var init_detect_drift = __esm({
           addCheck("Domain handler coverage", "fail", `Error: ${getErrorMessage(e)}`);
         }
         try {
-          const matrixPath = join14(cleoSrcRoot, "dispatch", "lib", "capability-matrix.ts");
-          if (!existsSync11(matrixPath)) {
+          const matrixPath = join16(cleoSrcRoot, "dispatch", "lib", "capability-matrix.ts");
+          if (!existsSync12(matrixPath)) {
             addCheck("Capability matrix", "fail", "Capability matrix missing", [
               {
                 severity: "error",
@@ -41449,8 +42386,8 @@ var init_detect_drift = __esm({
           addCheck("Capability matrix", "fail", `Error: ${getErrorMessage(e)}`);
         }
         try {
-          const schemaPath = join14(projectRoot, "src", "store", "schema.ts");
-          if (!existsSync11(schemaPath)) {
+          const schemaPath = join16(projectRoot, "src", "store", "schema.ts");
+          if (!existsSync12(schemaPath)) {
             addCheck("Schema validation", "fail", "Schema definition missing", [
               {
                 severity: "error",
@@ -41484,10 +42421,10 @@ var init_detect_drift = __esm({
           addCheck("Schema validation", "fail", `Error: ${getErrorMessage(e)}`);
         }
         try {
-          const visionPath = join14(projectRoot, "docs", "concepts", "CLEO-VISION.md");
-          const specPath = join14(projectRoot, "docs", "specs", "CLEO-PORTABLE-PROJECT-BRAIN-SPEC.md");
+          const visionPath = join16(projectRoot, "docs", "concepts", "CLEO-VISION.md");
+          const specPath = join16(projectRoot, "docs", "specs", "CLEO-PORTABLE-PROJECT-BRAIN-SPEC.md");
           const issues = [];
-          if (!existsSync11(visionPath)) {
+          if (!existsSync12(visionPath)) {
             issues.push({
               severity: "error",
               category: "vision",
@@ -41496,7 +42433,7 @@ var init_detect_drift = __esm({
               recommendation: "Create docs/concepts/CLEO-VISION.md with project vision"
             });
           }
-          if (!existsSync11(specPath)) {
+          if (!existsSync12(specPath)) {
             issues.push({
               severity: "error",
               category: "spec",
@@ -41540,8 +42477,8 @@ var init_detect_drift = __esm({
           addCheck("Canonical identity", "fail", `Error: ${getErrorMessage(e)}`);
         }
         try {
-          const injectionPath = join14(projectRoot, CLEO_DIR_NAME, TEMPLATES_SUBDIR, CLEO_INJECTION_MD);
-          if (!existsSync11(injectionPath)) {
+          const injectionPath = join16(projectRoot, CLEO_DIR_NAME, TEMPLATES_SUBDIR, CLEO_INJECTION_MD);
+          if (!existsSync12(injectionPath)) {
             addCheck("Agent injection", "fail", "Agent injection template missing", [
               {
                 severity: "error",
@@ -41570,8 +42507,8 @@ var init_detect_drift = __esm({
           addCheck("Agent injection", "fail", `Error: ${getErrorMessage(e)}`);
         }
         try {
-          const exitCodesPath = join14(cleoSrcRoot, "dispatch", "lib", "exit-codes.ts");
-          if (!existsSync11(exitCodesPath)) {
+          const exitCodesPath = join16(cleoSrcRoot, "dispatch", "lib", "exit-codes.ts");
+          if (!existsSync12(exitCodesPath)) {
             addCheck("Exit codes", "fail", "Exit codes definition missing", [
               {
                 severity: "error",
@@ -41741,10 +42678,10 @@ var init_diagnostics2 = __esm({
 
 // packages/cleo/src/viewer/pidfile.ts
 import { mkdir, readFile as readFile2, unlink, writeFile } from "node:fs/promises";
-import { dirname as dirname7, join as join15 } from "node:path";
+import { dirname as dirname7, join as join17 } from "node:path";
 import { getCleoHome as getCleoHome2 } from "@cleocode/core/internal";
 function viewerPidFilePath() {
-  return join15(getCleoHome2(), "viewer.pid");
+  return join17(getCleoHome2(), "viewer.pid");
 }
 async function writeViewerPidFile(record) {
   const path6 = viewerPidFilePath();
@@ -41844,11 +42781,11 @@ var init_port_allocator = __esm({
 // packages/cleo/src/viewer/server.ts
 import { createReadStream } from "node:fs";
 import { stat } from "node:fs/promises";
-import { dirname as dirname8, join as join16, normalize, resolve as resolve5 } from "node:path";
+import { dirname as dirname8, join as join18, normalize, resolve as resolve5 } from "node:path";
 import { fileURLToPath as fileURLToPath5 } from "node:url";
 import {
   createAttachmentStore as createAttachmentStore2,
-  getProjectRoot as getProjectRoot27,
+  getProjectRoot as getProjectRoot28,
   searchAllProjectDocs
 } from "@cleocode/core/internal";
 function getViewerAssetsDir() {
@@ -41883,7 +42820,7 @@ function inferTitle(markdown, fallback) {
 }
 async function serveStatic(res, assetsDir, relPath) {
   const safeRel = normalize(relPath).replace(/^[\\/]+/, "");
-  const absPath = join16(assetsDir, safeRel);
+  const absPath = join18(assetsDir, safeRel);
   const resolvedAssets = resolve5(assetsDir) + "/";
   const resolvedAbs = resolve5(absPath);
   if (`${resolvedAbs}/`.indexOf(resolvedAssets) !== 0 && resolvedAbs !== resolve5(assetsDir)) {
@@ -41908,7 +42845,7 @@ async function serveStatic(res, assetsDir, relPath) {
   }
 }
 function buildViewerHandler(opts = {}) {
-  const projectRoot = opts.projectRoot ?? getProjectRoot27();
+  const projectRoot = opts.projectRoot ?? getProjectRoot28();
   const assetsDir = getViewerAssetsDir();
   const store = createAttachmentStore2();
   return async (req, res) => {
@@ -42084,12 +43021,12 @@ var init_server = __esm({
 // packages/cleo/src/cli/commands/docs-viewer.ts
 import { spawn } from "node:child_process";
 import { open as fsOpen } from "node:fs/promises";
-import { join as join17 } from "node:path";
+import { join as join19 } from "node:path";
 import { fileURLToPath as fileURLToPath6 } from "node:url";
-import { getCleoHome as getCleoHome3, getProjectRoot as getProjectRoot28 } from "@cleocode/core";
+import { getCleoHome as getCleoHome3, getProjectRoot as getProjectRoot29 } from "@cleocode/core";
 function getCleoBinPath() {
   const thisFile = fileURLToPath6(import.meta.url);
-  return join17(thisFile, "..", "..", "index.js");
+  return join19(thisFile, "..", "..", "index.js");
 }
 async function waitForExit(pid, timeoutMs, intervalMs = 100) {
   const deadline = Date.now() + timeoutMs;
@@ -42118,7 +43055,7 @@ function openInBrowser(url) {
   }
 }
 async function spawnDetachedServer(opts) {
-  const logFile = join17(getCleoHome3(), "viewer.log");
+  const logFile = join19(getCleoHome3(), "viewer.log");
   const handle = await fsOpen(logFile, "a").catch(() => null);
   const stdio = handle ? ["ignore", handle.fd, handle.fd] : ["ignore", "ignore", "ignore"];
   const args = [
@@ -42137,7 +43074,7 @@ async function spawnDetachedServer(opts) {
     detached: true,
     stdio,
     env: { ...process.env, [DETACHED_CHILD_ENV]: "1" },
-    cwd: getProjectRoot28()
+    cwd: getProjectRoot29()
   });
   child.unref();
   if (handle) await handle.close();
@@ -42289,7 +43226,7 @@ var init_docs_viewer = __esm({
           pid: process.pid,
           port: handle.port,
           host: handle.host,
-          projectRoot: getProjectRoot28(),
+          projectRoot: getProjectRoot29(),
           startedAt: Date.now()
         };
         await writeViewerPidFile(record);
@@ -42565,17 +43502,17 @@ __export(docs_exports, {
   docsCommand: () => docsCommand
 });
 import { appendFile, mkdir as mkdir2, readdir, readFile as readFile3, writeFile as writeFile2 } from "node:fs/promises";
-import { dirname as dirname9, isAbsolute as isAbsolute2, join as join18, resolve as resolve6 } from "node:path";
+import { dirname as dirname9, isAbsolute as isAbsolute2, join as join20, resolve as resolve6 } from "node:path";
 import {
   buildDocsGraph,
   CleoError as CleoError3,
   CounterMismatchError,
-  createDocsAccessor,
+  createAttachmentStoreDocsAccessor,
   exportDocument,
-  formatError as formatError5,
   getAgentOutputsAbsolute,
-  getProjectRoot as getProjectRoot29,
+  getProjectRoot as getProjectRoot30,
   listDocVersions,
+  makeClassifierForScanRoot,
   mergeDocs,
   publishDocs,
   publishDocsAsPr,
@@ -42589,7 +43526,7 @@ import {
   syncFromGit
 } from "@cleocode/core/internal";
 async function getScriptNames(projectRoot) {
-  const scriptsDir = join18(projectRoot, "scripts");
+  const scriptsDir = join20(projectRoot, "scripts");
   try {
     const files = await readdir(scriptsDir);
     return files.filter((f) => f.endsWith(".sh")).map((f) => f.replace(".sh", "")).sort();
@@ -42598,7 +43535,7 @@ async function getScriptNames(projectRoot) {
   }
 }
 async function getIndexedCommands(projectRoot) {
-  const indexPath = join18(projectRoot, "docs", "commands", "COMMANDS-INDEX.json");
+  const indexPath = join20(projectRoot, "docs", "commands", "COMMANDS-INDEX.json");
   const index = await readJson(indexPath);
   if (!index) return [];
   return index.commands.map((c) => c.name).sort();
@@ -42631,7 +43568,7 @@ async function runGapCheck(_projectRoot, filterId) {
     const reviewFiles = files.filter((f) => f.endsWith(".md"));
     for (const file of reviewFiles) {
       if (filterId && !file.includes(filterId)) continue;
-      const filePath = join18(reviewDir, file);
+      const filePath = join20(reviewDir, file);
       const content = await readFile3(filePath, "utf-8");
       const taskMatch = file.match(/^(T\d+)/);
       const taskId = taskMatch ? taskMatch[1] : "UNKNOWN";
@@ -42650,7 +43587,32 @@ async function runGapCheck(_projectRoot, filterId) {
   }
   return results;
 }
-var addCommand4, listCommand7, fetchCommand, removeCommand2, generateCommand, exportCommand4, searchCommand, mergeCommand, graphCommand, rankCommand, versionsCommand, publishCommand2, publishPrCommand, syncCommand3, statusCommand7, gapCheckCommand, importCommand2, docsCommand;
+function toWireKind(meta) {
+  return {
+    kind: meta.kind,
+    label: meta.label,
+    description: meta.description,
+    defaultOwnerKind: meta.defaultOwnerKind,
+    publishDir: meta.publishDir,
+    requiresEntityId: meta.requiresEntityId,
+    ...meta.entityIdPattern ? { entityIdPattern: meta.entityIdPattern.source } : {},
+    isExtension: meta.isExtension === true
+  };
+}
+function loadCliRegistry(projectRoot) {
+  try {
+    return { registry: DocKindRegistry.load(projectRoot) };
+  } catch (err) {
+    if (err instanceof DocKindConfigError) {
+      return {
+        registry: DocKindRegistry.builtinOnly(),
+        configError: { source: err.source, message: err.message }
+      };
+    }
+    throw err;
+  }
+}
+var addCommand5, listCommand7, fetchCommand, removeCommand2, generateCommand, exportCommand4, searchCommand, mergeCommand, graphCommand, rankCommand, versionsCommand, publishCommand2, publishPrCommand, syncCommand3, statusCommand7, gapCheckCommand, importCommand2, schemaCommand, listTypesCommand, docsCommand;
 var init_docs3 = __esm({
   "packages/cleo/src/cli/commands/docs.ts"() {
     "use strict";
@@ -42659,7 +43621,7 @@ var init_docs3 = __esm({
     init_cli();
     init_renderers();
     init_docs_viewer();
-    addCommand4 = defineCommand({
+    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)."
@@ -42697,7 +43659,7 @@ var init_docs3 = __esm({
         },
         type: {
           type: "string",
-          description: "Taxonomy classification: spec|adr|research|handoff|note|llm-readme (T9637)"
+          description: "Taxonomy classification \u2014 run `cleo docs list-types` to enumerate registered kinds (T9637 / T9788)"
         }
       },
       async run({ args }) {
@@ -42732,7 +43694,7 @@ var init_docs3 = __esm({
     listCommand7 = defineCommand({
       meta: {
         name: "list",
-        description: "List attachments. Provide exactly one of --task, --session, --observation, or --project. --type filters across any scope (T9637/T9638)."
+        description: "List attachments. With no scope flag, defaults to project scope and surfaces a hint to narrow with --task, --session, or --observation. --type filters across any scope (T9637/T9638). --limit <N> (default 50) and --orderBy <newest|sha|slug> (default newest) control the browsing window (T9792)."
       },
       args: {
         task: {
@@ -42749,11 +43711,19 @@ var init_docs3 = __esm({
         },
         project: {
           type: "boolean",
-          description: "List ALL attachments in the project (T9638). Mutually exclusive with --task/--session/--observation."
+          description: "List ALL attachments in the project (T9638). Mutually exclusive with --task/--session/--observation. Implicit default when no scope is set (T9792)."
         },
         type: {
           type: "string",
           description: "Filter by classification: spec|adr|research|handoff|note|llm-readme (T9637)"
+        },
+        limit: {
+          type: "string",
+          description: "Maximum number of rows to return (default 50, <=0 for unlimited). When the limit truncates the result set the response carries a hint + totalCount (T9792)."
+        },
+        orderBy: {
+          type: "string",
+          description: "Sort key: newest (default \u2014 most recent first), sha (ascending hex), slug (alphabetical, slug-less rows last) (T9792)."
         }
       },
       async run({ args }) {
@@ -42762,19 +43732,37 @@ var init_docs3 = __esm({
         const observation = args.observation ?? void 0;
         const project = args.project === true;
         const type2 = args.type ?? void 0;
-        const scopeCount = [task, session, observation].filter(Boolean).length + (project ? 1 : 0);
-        if (scopeCount === 0) {
-          cliError("provide one of --task <id>, --session <id>, --observation <id>, or --project", 6, {
-            name: "E_VALIDATION"
-          });
-          process.exit(6);
-        }
-        if (scopeCount > 1) {
+        const limitRaw = args.limit ?? void 0;
+        const orderByRaw = args.orderBy ?? void 0;
+        const ownerCount = [task, session, observation].filter(Boolean).length;
+        if (ownerCount + (project ? 1 : 0) > 1) {
           cliError("--task, --session, --observation, and --project are mutually exclusive", 6, {
             name: "E_VALIDATION"
           });
           process.exit(6);
         }
+        let limit;
+        if (limitRaw !== void 0) {
+          const parsed = Number.parseInt(String(limitRaw), 10);
+          if (Number.isNaN(parsed)) {
+            cliError(`--limit must be an integer \u2014 got '${String(limitRaw)}'`, 6, {
+              name: "E_VALIDATION"
+            });
+            process.exit(6);
+          }
+          limit = parsed;
+        }
+        let orderBy;
+        if (orderByRaw !== void 0) {
+          const candidate = String(orderByRaw);
+          if (candidate !== "newest" && candidate !== "sha" && candidate !== "slug") {
+            cliError(`--orderBy must be one of: newest|sha|slug \u2014 got '${candidate}'`, 6, {
+              name: "E_VALIDATION"
+            });
+            process.exit(6);
+          }
+          orderBy = candidate;
+        }
         await dispatchFromCli(
           "query",
           "docs",
@@ -42784,7 +43772,9 @@ var init_docs3 = __esm({
             ...session ? { session } : {},
             ...observation ? { observation } : {},
             ...project ? { project: true } : {},
-            ...type2 ? { type: type2 } : {}
+            ...type2 ? { type: type2 } : {},
+            ...limit !== void 0 ? { limit } : {},
+            ...orderBy !== void 0 ? { orderBy } : {}
           },
           { command: "docs list" }
         );
@@ -42906,7 +43896,7 @@ var init_docs3 = __esm({
         const taskId = String(args.task);
         const includeAttachments = args["include-attachments"] !== false;
         const includeMemoryRefs = args["include-memory-refs"] === true;
-        const projectRoot = getProjectRoot29();
+        const projectRoot = getProjectRoot30();
         try {
           const result = await exportDocument({
             taskId,
@@ -42936,10 +43926,9 @@ var init_docs3 = __esm({
           }
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);
-          cliOutput(
-            formatError5(new CleoError3(1 /* GENERAL_ERROR */, `docs export failed: ${message}`)),
-            { command: "docs export", operation: "docs.export" }
-          );
+          cliError(`docs export failed: ${message}`, 1 /* GENERAL_ERROR */, {
+            name: "E_DOCS_EXPORT_FAILED"
+          });
           process.exit(1 /* GENERAL_ERROR */);
         }
       }
@@ -42973,7 +43962,7 @@ var init_docs3 = __esm({
         }
       },
       async run({ args }) {
-        const projectRoot = getProjectRoot29();
+        const projectRoot = getProjectRoot30();
         const limit = args.limit ? Number.parseInt(String(args.limit), 10) : 10;
         try {
           const result = args.owner ? await searchDocs2(String(args.query), {
@@ -42988,10 +43977,9 @@ var init_docs3 = __esm({
           cliOutput(result, { command: "docs search", operation: "docs.search" });
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);
-          cliOutput(
-            formatError5(new CleoError3(1 /* GENERAL_ERROR */, `docs search failed: ${message}`)),
-            { command: "docs search", operation: "docs.search" }
-          );
+          cliError(`docs search failed: ${message}`, 1 /* GENERAL_ERROR */, {
+            name: "E_DOCS_SEARCH_FAILED"
+          });
           process.exit(1 /* GENERAL_ERROR */);
         }
       }
@@ -43030,7 +44018,7 @@ var init_docs3 = __esm({
         }
       },
       async run({ args }) {
-        const projectRoot = getProjectRoot29();
+        const projectRoot = getProjectRoot30();
         const rawStrategy = args.strategy ?? "three-way";
         const strategy = rawStrategy === "cherry-pick" || rawStrategy === "multi-diff" ? rawStrategy : "three-way";
         try {
@@ -43047,10 +44035,9 @@ var init_docs3 = __esm({
           cliOutput(result, { command: "docs merge", operation: "docs.merge" });
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);
-          cliOutput(
-            formatError5(new CleoError3(1 /* GENERAL_ERROR */, `docs merge failed: ${message}`)),
-            { command: "docs merge", operation: "docs.merge" }
-          );
+          cliError(`docs merge failed: ${message}`, 1 /* GENERAL_ERROR */, {
+            name: "E_DOCS_MERGE_FAILED"
+          });
           process.exit(1 /* GENERAL_ERROR */);
         }
       }
@@ -43080,7 +44067,7 @@ var init_docs3 = __esm({
         }
       },
       async run({ args }) {
-        const projectRoot = getProjectRoot29();
+        const projectRoot = getProjectRoot30();
         const fmt = args.format ?? "mermaid";
         try {
           const result = await buildDocsGraph({ ownerId: String(args.for), projectRoot });
@@ -43121,10 +44108,9 @@ var init_docs3 = __esm({
           );
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);
-          cliOutput(
-            formatError5(new CleoError3(1 /* GENERAL_ERROR */, `docs graph failed: ${message}`)),
-            { command: "docs graph", operation: "docs.graph" }
-          );
+          cliError(`docs graph failed: ${message}`, 1 /* GENERAL_ERROR */, {
+            name: "E_DOCS_GRAPH_FAILED"
+          });
           process.exit(1 /* GENERAL_ERROR */);
         }
       }
@@ -43150,7 +44136,7 @@ var init_docs3 = __esm({
         }
       },
       async run({ args }) {
-        const projectRoot = getProjectRoot29();
+        const projectRoot = getProjectRoot30();
         try {
           const result = await rankDocs({
             ownerId: String(args.for),
@@ -43160,10 +44146,9 @@ var init_docs3 = __esm({
           cliOutput(result, { command: "docs rank", operation: "docs.rank" });
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);
-          cliOutput(
-            formatError5(new CleoError3(1 /* GENERAL_ERROR */, `docs rank failed: ${message}`)),
-            { command: "docs rank", operation: "docs.rank" }
-          );
+          cliError(`docs rank failed: ${message}`, 1 /* GENERAL_ERROR */, {
+            name: "E_DOCS_RANK_FAILED"
+          });
           process.exit(1 /* GENERAL_ERROR */);
         }
       }
@@ -43189,7 +44174,7 @@ var init_docs3 = __esm({
         }
       },
       async run({ args }) {
-        const projectRoot = getProjectRoot29();
+        const projectRoot = getProjectRoot30();
         try {
           const result = await listDocVersions({
             ownerId: String(args.for),
@@ -43199,10 +44184,9 @@ var init_docs3 = __esm({
           cliOutput(result, { command: "docs versions", operation: "docs.versions" });
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);
-          cliOutput(
-            formatError5(new CleoError3(1 /* GENERAL_ERROR */, `docs versions failed: ${message}`)),
-            { command: "docs versions", operation: "docs.versions" }
-          );
+          cliError(`docs versions failed: ${message}`, 1 /* GENERAL_ERROR */, {
+            name: "E_DOCS_VERSIONS_FAILED"
+          });
           process.exit(1 /* GENERAL_ERROR */);
         }
       }
@@ -43233,7 +44217,7 @@ var init_docs3 = __esm({
         }
       },
       async run({ args }) {
-        const projectRoot = getProjectRoot29();
+        const projectRoot = getProjectRoot30();
         try {
           const result = await publishDocs({
             ownerId: String(args.for),
@@ -43357,7 +44341,7 @@ var init_docs3 = __esm({
       },
       async run({ args }) {
         if (args.from) {
-          const projectRoot = getProjectRoot29();
+          const projectRoot = getProjectRoot30();
           const ownerId = args.for ?? void 0;
           if (!ownerId) {
             cliError(
@@ -43405,7 +44389,7 @@ var init_docs3 = __esm({
           }
         } catch (err) {
           if (err instanceof CleoError3) {
-            cliError(formatError5(err), err.code, { name: "E_DOCS_FAILED" });
+            cliError(err.message, err.code, { name: "E_DOCS_SYNC_FAILED" });
             process.exit(err.code);
           }
           throw err;
@@ -43424,7 +44408,7 @@ var init_docs3 = __esm({
         }
       },
       async run() {
-        const projectRoot = getProjectRoot29();
+        const projectRoot = getProjectRoot30();
         try {
           const result = await statusDocs({ projectRoot });
           cliOutput(result, { command: "docs status", operation: "docs.status" });
@@ -43473,7 +44457,7 @@ var init_docs3 = __esm({
           }
         } catch (err) {
           if (err instanceof CleoError3) {
-            cliError(formatError5(err), err.code, { name: "E_DOCS_FAILED" });
+            cliError(err.message, err.code, { name: "E_DOCS_GAP_CHECK_FAILED" });
             process.exit(err.code);
           }
           throw err;
@@ -43509,7 +44493,7 @@ var init_docs3 = __esm({
         }
       },
       async run({ args }) {
-        const projectRoot = getProjectRoot29();
+        const projectRoot = getProjectRoot30();
         const dirArg = String(args.dir);
         const scanRoot = isAbsolute2(dirArg) ? dirArg : resolve6(projectRoot, dirArg);
         const dryRun = args["dry-run"] === true;
@@ -43523,16 +44507,17 @@ var init_docs3 = __esm({
           })}
 `;
           try {
-            await mkdir2(join18(projectRoot, ".cleo", "audit"), { recursive: true });
+            await mkdir2(join20(projectRoot, ".cleo", "audit"), { recursive: true });
             await appendFile(
-              join18(projectRoot, ".cleo", "audit", "import-force-bypass.jsonl"),
+              join20(projectRoot, ".cleo", "audit", "import-force-bypass.jsonl"),
               auditLine,
               "utf-8"
             );
           } catch {
           }
         }
-        const accessor = createDocsAccessor(projectRoot);
+        const accessor = createAttachmentStoreDocsAccessor(projectRoot);
+        const classify = makeClassifierForScanRoot(scanRoot, projectRoot);
         try {
           const result = await runDocsImport({
             root: scanRoot,
@@ -43540,7 +44525,8 @@ var init_docs3 = __esm({
             dryRun,
             force,
             manifestPath,
-            auditDir: projectRoot
+            auditDir: projectRoot,
+            classify
           });
           cliOutput(
             {
@@ -43569,13 +44555,110 @@ 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)."
+      },
+      args: {
+        "include-counts": {
+          type: "boolean",
+          description: "Include per-kind attachment counts from the project SSoT"
+        }
+      },
+      async run({ args }) {
+        const projectRoot = getProjectRoot30();
+        const { registry, configError } = loadCliRegistry(projectRoot);
+        const kinds = registry.list().map(toWireKind);
+        const extensionsCount = kinds.filter((k) => k.isExtension).length;
+        let counts2;
+        if (args["include-counts"]) {
+          counts2 = {};
+          const { createAttachmentStore: createAttachmentStore3 } = await import("@cleocode/core/internal");
+          const store = createAttachmentStore3();
+          for (const k of kinds) counts2[k.kind] = 0;
+          try {
+            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 {
+          }
+        }
+        cliOutput(
+          {
+            version: 1,
+            builtinsCount: kinds.length - extensionsCount,
+            extensionsCount,
+            kinds,
+            ...counts2 ? { counts: counts2 } : {},
+            ...configError ? { configError } : {}
+          },
+          { command: "docs schema", operation: "docs.schema" }
+        );
+      }
+    });
+    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)."
+      },
+      args: {
+        counts: {
+          type: "boolean",
+          description: "Include per-kind attachment counts from the project SSoT"
+        }
+      },
+      async run({ args }) {
+        const projectRoot = getProjectRoot30();
+        const { registry, configError } = loadCliRegistry(projectRoot);
+        const kinds = registry.list().map(toWireKind);
+        let counts2;
+        if (args.counts) {
+          counts2 = {};
+          const { createAttachmentStore: createAttachmentStore3 } = await import("@cleocode/core/internal");
+          const store = createAttachmentStore3();
+          for (const k of kinds) counts2[k.kind] = 0;
+          try {
+            const rows2 = await store.listAllInProject(projectRoot);
+            for (const row of rows2) {
+              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,
+            ...configError ? { configError } : {}
+          },
+          {
+            command: "docs list-types",
+            operation: "docs.list-types",
+            message: configError ? `loaded built-ins only \u2014 ${configError.message}` : void 0
+          }
+        );
+      }
+    });
     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)"
       },
       subCommands: {
-        add: addCommand4,
+        add: addCommand5,
         list: listCommand7,
         fetch: fetchCommand,
         remove: removeCommand2,
@@ -43592,6 +44675,9 @@ var init_docs3 = __esm({
         status: statusCommand7,
         "gap-check": gapCheckCommand,
         import: importCommand2,
+        // T9788 — canonical doc-kind taxonomy discovery surface.
+        schema: schemaCommand,
+        "list-types": listTypesCommand,
         ...docsViewerSubcommands
       },
       async run({ cmd, rawArgs }) {
@@ -43877,9 +44963,9 @@ __export(migrate_agents_v2_exports, {
   walkAgentsDir: () => walkAgentsDir
 });
 import { createHash as createHash2 } from "node:crypto";
-import { appendFileSync as appendFileSync2, existsSync as existsSync12, mkdirSync as mkdirSync3, readdirSync as readdirSync2, readFileSync as readFileSync12 } from "node:fs";
-import { join as join19 } from "node:path";
-import { getProjectRoot as getProjectRoot30, installAgentFromCant } from "@cleocode/core/internal";
+import { appendFileSync as appendFileSync2, existsSync as existsSync13, mkdirSync as mkdirSync3, readdirSync as readdirSync2, readFileSync as readFileSync14 } from "node:fs";
+import { join as join21 } from "node:path";
+import { getProjectRoot as getProjectRoot31, installAgentFromCant } from "@cleocode/core/internal";
 import { openCleoDb } from "@cleocode/core/store/open-cleo-db";
 function sha256Hex(bytes) {
   return createHash2("sha256").update(bytes).digest("hex");
@@ -43898,15 +44984,15 @@ function extractAgentName(source) {
   return headerMatch[1] ?? null;
 }
 function appendAuditLog(projectRoot, entry) {
-  const auditPath = join19(projectRoot, AUDIT_LOG_RELATIVE);
-  const auditDir = join19(auditPath, "..");
-  if (!existsSync12(auditDir)) {
+  const auditPath = join21(projectRoot, AUDIT_LOG_RELATIVE);
+  const auditDir = join21(auditPath, "..");
+  if (!existsSync13(auditDir)) {
     mkdirSync3(auditDir, { recursive: true });
   }
   appendFileSync2(auditPath, JSON.stringify(entry) + "\n", "utf8");
 }
 function walkAgentsDir(db, scanDir, projectRoot, summary, verbose) {
-  if (!existsSync12(scanDir)) return;
+  if (!existsSync13(scanDir)) return;
   let files;
   try {
     files = readdirSync2(scanDir).filter((f) => f.endsWith(".cant"));
@@ -43917,12 +45003,12 @@ function walkAgentsDir(db, scanDir, projectRoot, summary, verbose) {
     return;
   }
   for (const filename of files) {
-    const cantPath = join19(scanDir, filename);
+    const cantPath = join21(scanDir, filename);
     const relPath = cantPath.replace(`${projectRoot}/`, "");
     let sourceBytes;
     let sourceText;
     try {
-      sourceBytes = readFileSync12(cantPath);
+      sourceBytes = readFileSync14(cantPath);
       sourceText = sourceBytes.toString("utf8");
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
@@ -44014,9 +45100,9 @@ async function runMigrateAgentsV2(projectRoot, verbose = true) {
   const { db: _sdDb } = await openCleoDb("signaldock");
   const db = _sdDb;
   try {
-    const canonicalDir = join19(projectRoot, ".cleo", "cant", "agents");
+    const canonicalDir = join21(projectRoot, ".cleo", "cant", "agents");
     walkAgentsDir(db, canonicalDir, projectRoot, summary, verbose);
-    const legacyDir = join19(projectRoot, ".cleo", "agents");
+    const legacyDir = join21(projectRoot, ".cleo", "agents");
     walkAgentsDir(db, legacyDir, projectRoot, summary, verbose);
   } finally {
     db.close();
@@ -44024,11 +45110,11 @@ async function runMigrateAgentsV2(projectRoot, verbose = true) {
   return summary;
 }
 function readMigrationConflicts(projectRoot) {
-  const auditPath = join19(projectRoot, AUDIT_LOG_RELATIVE);
-  if (!existsSync12(auditPath)) return [];
+  const auditPath = join21(projectRoot, AUDIT_LOG_RELATIVE);
+  if (!existsSync13(auditPath)) return [];
   let raw;
   try {
-    raw = readFileSync12(auditPath, "utf8");
+    raw = readFileSync14(auditPath, "utf8");
   } catch {
     return [];
   }
@@ -44066,7 +45152,7 @@ var init_migrate_agents_v2 = __esm({
         }
       },
       async run({ args }) {
-        const projectRoot = getProjectRoot30();
+        const projectRoot = getProjectRoot31();
         const verbose = args.quiet !== true;
         if (verbose) {
           humanInfo("Scanning .cleo/cant/agents/ and .cleo/agents/ for unregistered agents...");
@@ -44109,8 +45195,8 @@ __export(doctor_exports, {
   doctorCommand: () => doctorCommand2
 });
 import { mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "node:fs";
-import { join as join20 } from "node:path";
-import { getProjectRoot as getProjectRoot31 } from "@cleocode/core";
+import { join as join22 } from "node:path";
+import { getProjectRoot as getProjectRoot32 } from "@cleocode/core";
 import {
   quarantineRogueCleoDir,
   scanRogueCleoDirs
@@ -44148,8 +45234,8 @@ async function scanTestFixturesInProd(projectRoot) {
 }
 async function quarantineTestFixtures(projectRoot, matches) {
   if (matches.length === 0) return 0;
-  const cleoDir = join20(projectRoot, ".cleo");
-  const quarantineDir = join20(
+  const cleoDir = join22(projectRoot, ".cleo");
+  const quarantineDir = join22(
     cleoDir,
     "quarantine",
     `fixture-scan-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}`
@@ -44157,7 +45243,7 @@ async function quarantineTestFixtures(projectRoot, matches) {
   mkdirSync4(quarantineDir, { recursive: true });
   const manifest = matches.map((m) => ({ ...m, quarantinedAt: (/* @__PURE__ */ new Date()).toISOString() }));
   writeFileSync4(
-    join20(quarantineDir, "manifest.jsonl"),
+    join22(quarantineDir, "manifest.jsonl"),
     manifest.map((m) => JSON.stringify(m)).join("\n") + "\n"
   );
   const { getNativeDb } = await import("@cleocode/core/store/sqlite.js");
@@ -44279,6 +45365,23 @@ var init_doctor = __esm({
           type: "boolean",
           description: "Audit orphaned agent worktree directories and report what cleo gc --worktrees would remove (T9043)"
         },
+        /**
+         * T9790: list orphan `.cleo/` directories under
+         * `<projectRoot>/.claude/worktrees/` with full provenance. Read-only.
+         */
+        "audit-worktree-orphans": {
+          type: "boolean",
+          description: "List orphan .cleo/ directories under .claude/worktrees/ (T9790, fallout from T9550/T9580)"
+        },
+        /**
+         * T9790: archive then remove every orphan reported by
+         * `--audit-worktree-orphans`. Combine with `--dry-run` to preview
+         * without touching the filesystem.
+         */
+        "prune-worktree-orphans": {
+          type: "boolean",
+          description: "Archive then remove orphan .cleo/ directories under .claude/worktrees/ (T9790)"
+        },
         "audit-temp": {
           type: "boolean",
           description: "Audit orphaned CLEO-generated temp directories and report what cleo gc --temp would remove (T9043)"
@@ -44336,7 +45439,7 @@ var init_doctor = __esm({
         try {
           if (args.brain) {
             const { computeBrainHealthDashboard } = await import("@cleocode/core/memory/brain-health-dashboard.js");
-            const projectRoot = getProjectRoot31();
+            const projectRoot = getProjectRoot32();
             const dashboard = await computeBrainHealthDashboard(projectRoot);
             cliOutput(dashboard, { command: "doctor", operation: "doctor.brain" });
             if (dashboard.hasP0Failure) {
@@ -44345,7 +45448,7 @@ var init_doctor = __esm({
             return;
           }
           if (args["scan-test-fixtures-in-prod"]) {
-            const projectRoot = getProjectRoot31();
+            const projectRoot = getProjectRoot32();
             const matches = await scanTestFixturesInProd(projectRoot);
             const dryRun = args["dry-run"] !== false && args.quarantine !== true;
             const quarantined = !dryRun && matches.length > 0 ? await quarantineTestFixtures(projectRoot, matches) : void 0;
@@ -44433,7 +45536,7 @@ var init_doctor = __esm({
             progress.complete("Comprehensive diagnostics complete");
           } else if (args["scan-rogue-cleo-dirs"]) {
             progress.step(0, "Scanning for rogue .cleo/ directories");
-            const projectRoot = getProjectRoot31();
+            const projectRoot = getProjectRoot32();
             const reports = scanRogueCleoDirs(projectRoot);
             progress.complete(
               `Found ${reports.length} rogue .cleo/ director${reports.length === 1 ? "y" : "ies"}`
@@ -44442,7 +45545,7 @@ var init_doctor = __esm({
           } else if (args["quarantine-rogue-cleo-dirs"]) {
             const isDryRun = args["dry-run"] === true;
             progress.step(0, `${isDryRun ? "[DRY RUN] " : ""}Scanning for rogue .cleo/ directories`);
-            const projectRoot = getProjectRoot31();
+            const projectRoot = getProjectRoot32();
             const reports = scanRogueCleoDirs(projectRoot);
             if (reports.length === 0) {
               progress.complete("No rogue .cleo/ directories found \u2014 nothing to quarantine");
@@ -44496,7 +45599,7 @@ var init_doctor = __esm({
             const { detectAndRemoveLegacyGlobalFiles, detectAndRemoveStrayProjectNexus } = await import("@cleocode/core/store/cleanup-legacy.js");
             const { getCleoHome: getCleoHome6 } = await import("@cleocode/core");
             const cleoHome = getCleoHome6();
-            const projectRoot = getProjectRoot31();
+            const projectRoot = getProjectRoot32();
             const legacyResult = detectAndRemoveLegacyGlobalFiles(cleoHome);
             const strayResult = detectAndRemoveStrayProjectNexus(projectRoot);
             const isDryRun = args["dry-run"] === true;
@@ -44526,6 +45629,62 @@ var init_doctor = __esm({
             if (checkResult.details?.["orphans"] && checkResult.details["orphans"].length > 0 && (process.exitCode === void 0 || process.exitCode === 0)) {
               process.exitCode = 2;
             }
+          } else if (args["audit-worktree-orphans"]) {
+            progress.step(0, "Scanning for worktree-orphan .cleo/ directories");
+            const { scanWorktreeOrphans } = await import("@cleocode/core/doctor/worktree-orphans.js");
+            const projectRoot = getProjectRoot32();
+            const orphans = await scanWorktreeOrphans(projectRoot);
+            progress.complete(`Found ${orphans.length} orphan${orphans.length === 1 ? "" : "s"}`);
+            cliOutput(
+              { projectRoot, orphans, count: orphans.length },
+              { command: "doctor", operation: "doctor.audit-worktree-orphans" }
+            );
+            if (orphans.length > 0 && (process.exitCode === void 0 || process.exitCode === 0)) {
+              process.exitCode = 2;
+            }
+          } else if (args["prune-worktree-orphans"]) {
+            const isDryRun = args["dry-run"] === true;
+            progress.step(
+              0,
+              `${isDryRun ? "[DRY RUN] " : ""}Scanning + pruning worktree-orphan .cleo/ directories`
+            );
+            const { pruneWorktreeOrphans, scanWorktreeOrphans } = await import("@cleocode/core/doctor/worktree-orphans.js");
+            const projectRoot = getProjectRoot32();
+            const orphans = await scanWorktreeOrphans(projectRoot);
+            if (orphans.length === 0) {
+              progress.complete("No worktree orphans found \u2014 nothing to prune");
+              cliOutput(
+                {
+                  projectRoot,
+                  dryRun: isDryRun,
+                  archivePath: null,
+                  pruned: [],
+                  rejected: [],
+                  totalSizeBytes: 0
+                },
+                { command: "doctor", operation: "doctor.prune-worktree-orphans" }
+              );
+              return;
+            }
+            const archiveDir = join22(projectRoot, ".cleo", "backups");
+            const auditLogPath = join22(projectRoot, ".cleo", "audit", "worktree-prune.jsonl");
+            const result = await pruneWorktreeOrphans(orphans, {
+              archiveDir,
+              auditLogPath,
+              dryRun: isDryRun,
+              projectRoot
+            });
+            const verb = isDryRun ? "Would prune" : "Pruned";
+            progress.complete(
+              `${verb} ${result.pruned.length} orphan${result.pruned.length === 1 ? "" : "s"}${result.rejected.length > 0 ? `, ${result.rejected.length} rejected` : ""}`
+            );
+            cliOutput(
+              { projectRoot, ...result },
+              { command: "doctor", operation: "doctor.prune-worktree-orphans" }
+            );
+            if (result.rejected.length > 0) {
+              process.exitCode = 1;
+            }
           } else if (args["audit-temp"]) {
             progress.step(0, "Auditing orphaned CLEO temp directories");
             const { auditOrphanTempDirs } = await import("@cleocode/core/gc/index.js");
@@ -44545,7 +45704,7 @@ var init_doctor = __esm({
               { command: "doctor", operation: "admin.health" }
             );
             try {
-              const projectRoot = getProjectRoot31();
+              const projectRoot = getProjectRoot32();
               const conflicts = readMigrationConflicts(projectRoot);
               if (conflicts.length > 0) {
                 progress.complete(
@@ -44610,7 +45769,7 @@ __export(event_exports, {
   orchestratorCommand: () => orchestratorCommand
 });
 import { readdir as readdir2 } from "node:fs/promises";
-import { join as join21 } from "node:path";
+import { join as join23 } from "node:path";
 import { cwd as processCwd } from "node:process";
 import { appendEvent } from "@cleocode/core/events/event-bus.js";
 function resolveProjectRoot3(arg) {
@@ -44733,7 +45892,7 @@ var init_event = __esm({
         const agentIdFilter = args.agent;
         const showAll = args.all === true;
         const lines = parseInt(args.lines ?? "20", 10);
-        const eventsDir = join21(projectRoot, ".cleo", "agent-events");
+        const eventsDir = join23(projectRoot, ".cleo", "agent-events");
         try {
           let files = [];
           try {
@@ -44770,8 +45929,8 @@ var init_event = __esm({
           }
           for (const file of filesToTail) {
             const agentId = file.replace(".jsonl", "");
-            const { readFileSync: readFileSync18 } = await import("node:fs");
-            const content = readFileSync18(join21(eventsDir, file), "utf-8");
+            const { readFileSync: readFileSync20 } = await import("node:fs");
+            const content = readFileSync20(join23(eventsDir, file), "utf-8");
             const eventLines = content.trim().split("\n").filter(Boolean);
             const tail = eventLines.slice(-lines);
             if (jsonMode) {
@@ -44841,7 +46000,7 @@ var init_event = __esm({
         const epicFilter = args.epic;
         const follow = args.follow === true;
         const lines = parseInt(args.lines ?? "50", 10);
-        const eventsDir = join21(projectRoot, ".cleo", "agent-events");
+        const eventsDir = join23(projectRoot, ".cleo", "agent-events");
         let files = [];
         try {
           const entries = await readdir2(eventsDir);
@@ -44866,8 +46025,8 @@ var init_event = __esm({
         const printAgentLog = async (file) => {
           const agentId = file.replace(".jsonl", "");
           try {
-            const { readFileSync: readFileSync18 } = await import("node:fs");
-            const content = readFileSync18(join21(eventsDir, file), "utf-8");
+            const { readFileSync: readFileSync20 } = await import("node:fs");
+            const content = readFileSync20(join23(eventsDir, file), "utf-8");
             const eventLines = content.trim().split("\n").filter(Boolean);
             const tail = eventLines.slice(-lines);
             if (jsonMode) {
@@ -45160,7 +46319,7 @@ __export(federation_exports, {
   federationCommand: () => federationCommand
 });
 import { skills } from "@cleocode/core";
-var addFederationPeer, listFederationPeers, removeFederationPeer, addCommand5, removeCommand3, listCommand8, federationCommand;
+var addFederationPeer, listFederationPeers, removeFederationPeer, addCommand6, removeCommand3, listCommand8, federationCommand;
 var init_federation = __esm({
   "packages/cleo/src/cli/commands/federation.ts"() {
     "use strict";
@@ -45168,7 +46327,7 @@ var init_federation = __esm({
     init_dist();
     init_renderers();
     ({ addFederationPeer, listFederationPeers, removeFederationPeer } = skills);
-    addCommand5 = defineCommand({
+    addCommand6 = defineCommand({
       meta: {
         name: "add",
         description: "Add (or update) a federation peer in ~/.cleo/federation.json"
@@ -45268,7 +46427,7 @@ var init_federation = __esm({
         description: "Federation peer management: add, remove, list trusted peers"
       },
       subCommands: {
-        add: addCommand5,
+        add: addCommand6,
         remove: removeCommand3,
         list: listCommand8
       },
@@ -45370,7 +46529,7 @@ __export(gc_exports, {
   gcCommand: () => gcCommand
 });
 import { homedir as homedir4, tmpdir } from "node:os";
-import { join as join22 } from "node:path";
+import { join as join24 } from "node:path";
 import { pruneOrphanTempDirs, pruneOrphanWorktrees } from "@cleocode/core/gc/cleanup.js";
 import { runGC } from "@cleocode/core/gc/runner.js";
 import { readGCState } from "@cleocode/core/gc/state.js";
@@ -45453,7 +46612,7 @@ var init_gc = __esm({
       },
       async run({ args }) {
         const cleoDir = resolveLegacyCleoDir3(args["cleo-dir"]);
-        const statePath = join22(cleoDir, "gc-state.json");
+        const statePath = join24(cleoDir, "gc-state.json");
         try {
           const state = await readGCState(statePath);
           const diskStr = state.lastDiskUsedPct !== null ? `${state.lastDiskUsedPct.toFixed(1)}%` : "unknown";
@@ -45506,8 +46665,8 @@ var init_gc = __esm({
         }
       },
       async run({ args }) {
-        const xdgData = process.env["XDG_DATA_HOME"] ?? join22(homedir4(), ".local", "share");
-        const worktreesRoot = args["worktrees-root"] ?? join22(xdgData, "cleo", "worktrees");
+        const xdgData = process.env["XDG_DATA_HOME"] ?? join24(homedir4(), ".local", "share");
+        const worktreesRoot = args["worktrees-root"] ?? join24(xdgData, "cleo", "worktrees");
         const projectHash = args["project-hash"];
         const dryRun = args["dry-run"];
         const preserveRaw = args["preserve-tasks"];
@@ -45617,13 +46776,13 @@ __export(generate_changelog_exports, {
   generateChangelogCommand: () => generateChangelogCommand
 });
 import { execFileSync as execFileSync2 } from "node:child_process";
-import { existsSync as existsSync13, mkdirSync as mkdirSync5, readFileSync as readFileSync13, writeFileSync as writeFileSync5 } from "node:fs";
-import { dirname as dirname10, join as join23 } from "node:path";
-import { CleoError as CleoError4, formatError as formatError6, getConfigPath, getProjectRoot as getProjectRoot32 } from "@cleocode/core";
+import { existsSync as existsSync14, mkdirSync as mkdirSync5, readFileSync as readFileSync15, writeFileSync as writeFileSync5 } from "node:fs";
+import { dirname as dirname10, join as join25 } from "node:path";
+import { CleoError as CleoError4, getConfigPath, getProjectRoot as getProjectRoot33, pushWarning as pushWarning2 } from "@cleocode/core";
 function getChangelogSource(cwd) {
   const configPath = getConfigPath(cwd);
   try {
-    const config = JSON.parse(readFileSync13(configPath, "utf-8"));
+    const config = JSON.parse(readFileSync15(configPath, "utf-8"));
     return config?.release?.changelog?.source ?? "CHANGELOG.md";
   } catch {
     return "CHANGELOG.md";
@@ -45632,7 +46791,7 @@ function getChangelogSource(cwd) {
 function getEnabledPlatforms(cwd) {
   const configPath = getConfigPath(cwd);
   try {
-    const config = JSON.parse(readFileSync13(configPath, "utf-8"));
+    const config = JSON.parse(readFileSync15(configPath, "utf-8"));
     const outputs = config?.release?.changelog?.outputs ?? [];
     return outputs.filter((o) => o.enabled);
   } catch {
@@ -45650,7 +46809,7 @@ function getDefaultOutputPath(platform) {
   }
 }
 function getGitHubRepoSlug(cwd) {
-  const projectRoot = getProjectRoot32(cwd);
+  const projectRoot = getProjectRoot33(cwd);
   try {
     const remoteUrl = execFileSync2("git", ["remote", "get-url", "origin"], {
       cwd: projectRoot,
@@ -45779,15 +46938,28 @@ var init_generate_changelog = __esm({
       },
       async run({ args }) {
         try {
+          pushWarning2({
+            code: "W_DEPRECATED_COMMAND",
+            message: "`cleo generate-changelog` is deprecated. Use `cleo changeset add` (T9793) + the aggregator (T9759 composer) instead.",
+            severity: "warn",
+            deprecated: "cleo generate-changelog",
+            replacement: "cleo changeset add",
+            removeBy: "v2026.6.0",
+            context: {
+              registryId: "generate-changelog-renderer",
+              task: "T9795",
+              saga: "T9787"
+            }
+          });
           const limit = Number(args.limit ?? 15);
           const targetPlatform = args.platform;
           const dryRun = args["dry-run"] === true;
           const sourceFile = getChangelogSource();
-          const sourcePath = join23(getProjectRoot32(), sourceFile);
-          if (!existsSync13(sourcePath)) {
+          const sourcePath = join25(getProjectRoot33(), sourceFile);
+          if (!existsSync14(sourcePath)) {
             throw new CleoError4(4 /* NOT_FOUND */, `Changelog source not found: ${sourcePath}`);
           }
-          const sourceContent = readFileSync13(sourcePath, "utf-8");
+          const sourceContent = readFileSync15(sourcePath, "utf-8");
           const repoSlug = getGitHubRepoSlug();
           const results = [];
           if (targetPlatform) {
@@ -45796,7 +46968,7 @@ var init_generate_changelog = __esm({
             const outputPath = platformConfig?.path ?? getDefaultOutputPath(targetPlatform);
             const content = generateForPlatform(targetPlatform, sourceContent, repoSlug, limit);
             if (!dryRun) {
-              const fullPath = join23(getProjectRoot32(), outputPath);
+              const fullPath = join25(getProjectRoot33(), outputPath);
               mkdirSync5(dirname10(fullPath), { recursive: true });
               writeFileSync5(fullPath, content, "utf-8");
             }
@@ -45817,7 +46989,7 @@ var init_generate_changelog = __esm({
                 limit
               );
               if (!dryRun) {
-                const fullPath = join23(getProjectRoot32(), platformConfig.path);
+                const fullPath = join25(getProjectRoot33(), platformConfig.path);
                 mkdirSync5(dirname10(fullPath), { recursive: true });
                 writeFileSync5(fullPath, content, "utf-8");
               }
@@ -45839,10 +47011,16 @@ var init_generate_changelog = __esm({
           );
         } catch (err) {
           if (err instanceof CleoError4) {
-            cliError(formatError6(err), err.code, { name: "E_INTERNAL" });
+            cliError(`generate-changelog failed: ${err.message}`, err.code, {
+              name: "E_GENERATE_CHANGELOG_FAILED"
+            });
             process.exit(err.code);
           }
-          throw err;
+          const message = err instanceof Error ? err.message : String(err);
+          cliError(`generate-changelog failed: ${message}`, 1 /* GENERAL_ERROR */, {
+            name: "E_GENERATE_CHANGELOG_FAILED"
+          });
+          process.exit(1 /* GENERAL_ERROR */);
         }
       }
     });
@@ -46957,24 +48135,24 @@ __export(init_exports, {
   getWorkflowTemplatesDir: () => getWorkflowTemplatesDir,
   initCommand: () => initCommand2
 });
-import { existsSync as existsSync14, readFileSync as readFileSync14 } from "node:fs";
-import { dirname as dirname11, join as join24, resolve as resolve7 } from "node:path";
+import { existsSync as existsSync15, readFileSync as readFileSync16 } from "node:fs";
+import { dirname as dirname11, join as join26, resolve as resolve7 } from "node:path";
 import { fileURLToPath as fileURLToPath7 } from "node:url";
 import {
   CleoError as CleoError5,
-  formatError as formatError7,
+  formatError as formatError5,
   initProject as initProject2,
   scaffoldWorkflows
 } from "@cleocode/core";
 function getGitignoreTemplate() {
   try {
     const thisFile = fileURLToPath7(import.meta.url);
-    const packageRoot = join24(thisFile, "..", "..", "..", "..");
-    const localTemplatePath = join24(packageRoot, "templates", "cleo-gitignore");
-    const monorepoTemplatePath = join24(packageRoot, "..", "..", "templates", "cleo-gitignore");
-    const templatePath = existsSync14(localTemplatePath) ? localTemplatePath : monorepoTemplatePath;
-    if (existsSync14(templatePath)) {
-      return readFileSync14(templatePath, "utf-8");
+    const packageRoot = join26(thisFile, "..", "..", "..", "..");
+    const localTemplatePath = join26(packageRoot, "templates", "cleo-gitignore");
+    const monorepoTemplatePath = join26(packageRoot, "..", "..", "templates", "cleo-gitignore");
+    const templatePath = existsSync15(localTemplatePath) ? localTemplatePath : monorepoTemplatePath;
+    if (existsSync15(templatePath)) {
+      return readFileSync16(templatePath, "utf-8");
     }
   } catch {
   }
@@ -46983,7 +48161,7 @@ function getGitignoreTemplate() {
 function getWorkflowTemplatesDir() {
   const thisFile = fileURLToPath7(import.meta.url);
   const packageRoot = resolve7(dirname11(thisFile), "..", "..", "..", "..");
-  return join24(packageRoot, "templates", "workflows");
+  return join26(packageRoot, "templates", "workflows");
 }
 var initCommand2;
 var init_init = __esm({
@@ -47083,7 +48261,7 @@ var init_init = __esm({
           );
         } catch (err) {
           if (err instanceof CleoError5) {
-            cliError(formatError7(err), err.code, { name: "E_INTERNAL" });
+            cliError(formatError5(err), err.code, { name: "E_INTERNAL" });
             process.exit(err.code);
           }
           throw err;
@@ -47898,7 +49076,7 @@ var llm_cost_exports = {};
 __export(llm_cost_exports, {
   costCommand: () => costCommand
 });
-import { getProjectRoot as getProjectRoot33 } from "@cleocode/core/internal";
+import { getProjectRoot as getProjectRoot34 } from "@cleocode/core/internal";
 import { computeCost } from "@cleocode/core/llm/usage-pricing";
 function resolveSessionId(raw) {
   if (raw === "current") {
@@ -47971,7 +49149,7 @@ var init_llm_cost = __esm({
           process.exit(6);
         }
         const sessionId = resolveSessionId(rawSessionId);
-        const projectRoot = getProjectRoot33(process.cwd());
+        const projectRoot = getProjectRoot34(process.cwd());
         let breakdown;
         try {
           breakdown = await loadSessionCostBreakdown(projectRoot, sessionId);
@@ -48612,7 +49790,7 @@ var llm_exports = {};
 __export(llm_exports, {
   llmCommand: () => llmCommand
 });
-import { pushWarning as pushWarning2 } from "@cleocode/core";
+import { pushWarning as pushWarning3 } from "@cleocode/core";
 async function getListProviders() {
   const { listProviders } = await import(
     /* webpackIgnore: true */
@@ -48646,7 +49824,7 @@ function makeLlmSubcommand(opts) {
     }
   });
 }
-var API_KEY_FLAG_DEPRECATION, addCommand6, listCommand11, removeCommand4, useCommand, profileCommand, testCommand, whoamiCommand, listProvidersCommand, contextEnginesListCommand, contextEnginesCommand, loginCommand, refreshCatalogCommand, llmCommand;
+var API_KEY_FLAG_DEPRECATION, addCommand7, listCommand11, removeCommand4, useCommand, profileCommand, testCommand, whoamiCommand, listProvidersCommand, contextEnginesListCommand, contextEnginesCommand, loginCommand, refreshCatalogCommand, llmCommand;
 var init_llm3 = __esm({
   "packages/cleo/src/cli/commands/llm.ts"() {
     "use strict";
@@ -48658,7 +49836,7 @@ var init_llm3 = __esm({
     init_llm_refresh_catalog();
     init_llm_stream();
     API_KEY_FLAG_DEPRECATION = "[warning] --api-key exposes the secret to 'ps' listings and shell history. Prefer --api-key-stdin or --api-key-env=NAME for production use.";
-    addCommand6 = defineCommand({
+    addCommand7 = defineCommand({
       meta: {
         name: "add",
         // Help text lists --api-key-stdin first (recommended path) and
@@ -48743,7 +49921,7 @@ var init_llm3 = __esm({
           apiKey = envValue;
           source = "env";
         } else if (typeof a["api-key"] === "string" && a["api-key"]) {
-          pushWarning2({
+          pushWarning3({
             code: "W_DEPRECATED_FLAG",
             message: API_KEY_FLAG_DEPRECATION,
             deprecated: "--api-key=<value>",
@@ -49071,7 +50249,7 @@ var init_llm3 = __esm({
         description: "Manage LLM credentials, role profiles, and resolver diagnostics"
       },
       subCommands: {
-        add: addCommand6,
+        add: addCommand7,
         "context-engines": contextEnginesCommand,
         cost: costCommand,
         list: listCommand11,
@@ -49519,10 +50697,10 @@ __export(memory_exports, {
   memoryCommand: () => memoryCommand
 });
 import { createHash as createHash3 } from "node:crypto";
-import { existsSync as existsSync15, mkdirSync as mkdirSync6, readdirSync as readdirSync3, readFileSync as readFileSync15, writeFileSync as writeFileSync6 } from "node:fs";
+import { existsSync as existsSync16, mkdirSync as mkdirSync6, readdirSync as readdirSync3, readFileSync as readFileSync17, writeFileSync as writeFileSync6 } from "node:fs";
 import { homedir as homedir5 } from "node:os";
-import { join as join25 } from "node:path";
-import { getProjectRoot as getProjectRoot34 } from "@cleocode/core";
+import { join as join27 } from "node:path";
+import { getProjectRoot as getProjectRoot35 } from "@cleocode/core";
 import {
   getBrainDb as getBrainDb2,
   getDreamStatus,
@@ -49564,8 +50742,8 @@ ${body}`).digest("hex").slice(0, 16);
 }
 function loadImportHashes(stateFile) {
   try {
-    if (!existsSync15(stateFile)) return /* @__PURE__ */ new Set();
-    const raw = readFileSync15(stateFile, "utf-8");
+    if (!existsSync16(stateFile)) return /* @__PURE__ */ new Set();
+    const raw = readFileSync17(stateFile, "utf-8");
     const parsed = JSON.parse(raw);
     return new Set(parsed.hashes);
   } catch {
@@ -49574,7 +50752,7 @@ function loadImportHashes(stateFile) {
 }
 function saveImportHashes(stateFile, hashes) {
   const dir = stateFile.slice(0, stateFile.lastIndexOf("/"));
-  if (!existsSync15(dir)) mkdirSync6(dir, { recursive: true });
+  if (!existsSync16(dir)) mkdirSync6(dir, { recursive: true });
   writeFileSync6(stateFile, JSON.stringify({ hashes: [...hashes] }, null, 2), "utf-8");
 }
 function makeMemorySubcommand(opts) {
@@ -50489,7 +51667,7 @@ var init_memory3 = __esm({
       },
       args: {},
       async run() {
-        const root = getProjectRoot34();
+        const root = getProjectRoot35();
         try {
           const result = await runConsolidation(root);
           cliOutput(result, { command: "memory-consolidate", operation: "memory.consolidate" });
@@ -50513,7 +51691,7 @@ var init_memory3 = __esm({
         }
       },
       async run({ args }) {
-        const root = getProjectRoot34();
+        const root = getProjectRoot35();
         if (args.status) {
           try {
             const status = await getDreamStatus(root);
@@ -50550,7 +51728,7 @@ var init_memory3 = __esm({
         }
       },
       async run({ args }) {
-        const root = getProjectRoot34();
+        const root = getProjectRoot35();
         try {
           const { runObserver, runReflector } = await import("@cleocode/core/memory");
           const observerResult = await runObserver(root, args.session, {
@@ -50590,7 +51768,7 @@ var init_memory3 = __esm({
         }
       },
       async run({ args }) {
-        const root = getProjectRoot34();
+        const root = getProjectRoot35();
         try {
           await getBrainDb2(root);
           const { totalDuplicateRows, groups } = await scanDuplicateEntries();
@@ -50634,16 +51812,16 @@ var init_memory3 = __esm({
         }
       },
       async run({ args }) {
-        const sourceDir = args.from ?? join25(homedir5(), ".claude", "projects", "-mnt-projects-cleocode", "memory");
+        const sourceDir = args.from ?? join27(homedir5(), ".claude", "projects", "-mnt-projects-cleocode", "memory");
         const isDryRun = !!args["dry-run"];
-        const projectRoot = getProjectRoot34();
-        const stateFile = join25(projectRoot, CLEO_DIR_NAME, MIGRATE_MEMORY_HASHES_JSON);
-        if (!existsSync15(sourceDir)) {
+        const projectRoot = getProjectRoot35();
+        const stateFile = join27(projectRoot, CLEO_DIR_NAME, MIGRATE_MEMORY_HASHES_JSON);
+        if (!existsSync16(sourceDir)) {
           cliError(`Source directory not found: ${sourceDir}`, "E_NOT_FOUND", { name: "E_NOT_FOUND" });
           process.exit(1);
           return;
         }
-        const files = readdirSync3(sourceDir).filter((f) => f.endsWith(".md") && f !== "MEMORY.md").map((f) => join25(sourceDir, f));
+        const files = readdirSync3(sourceDir).filter((f) => f.endsWith(".md") && f !== "MEMORY.md").map((f) => join27(sourceDir, f));
         const importedHashes = isDryRun ? /* @__PURE__ */ new Set() : loadImportHashes(stateFile);
         const stats = { total: files.length, imported: 0, skipped: 0, errors: 0 };
         const importedEntries = [];
@@ -50652,7 +51830,7 @@ var init_memory3 = __esm({
         for (const filePath of files) {
           const fileName = filePath.split("/").pop() ?? filePath;
           try {
-            const raw = readFileSync15(filePath, "utf-8");
+            const raw = readFileSync17(filePath, "utf-8");
             if (!raw.trim()) {
               stats.skipped++;
               skippedEntries.push({ file: fileName, reason: "empty file" });
@@ -50849,7 +52027,7 @@ var init_memory3 = __esm({
       },
       args: {},
       async run() {
-        const root = getProjectRoot34();
+        const root = getProjectRoot35();
         try {
           await getBrainDb2(root);
           const result = await getTierStats(root);
@@ -50892,7 +52070,7 @@ var init_memory3 = __esm({
         }
       },
       async run({ args }) {
-        const root = getProjectRoot34();
+        const root = getProjectRoot35();
         const targetTier = args.to;
         const reason = args.reason;
         const validTiers = ["medium", "long"];
@@ -50958,7 +52136,7 @@ var init_memory3 = __esm({
         }
       },
       async run({ args }) {
-        const root = getProjectRoot34();
+        const root = getProjectRoot35();
         const targetTier = args.to;
         const reason = args.reason;
         const validTiers = ["short", "medium"];
@@ -51426,7 +52604,7 @@ var migrate_claude_mem_exports = {};
 __export(migrate_claude_mem_exports, {
   migrateClaudeMemCommand: () => migrateClaudeMemCommand
 });
-import { getProjectRoot as getProjectRoot35, migrateClaudeMem } from "@cleocode/core/internal";
+import { getProjectRoot as getProjectRoot36, migrateClaudeMem } from "@cleocode/core/internal";
 import { ingestLooseAgentOutputs, ingestRcasdDirectories } from "@cleocode/core/memory";
 import { getDb as getDb2 } from "@cleocode/core/store/sqlite";
 var storageCommand, claudeMemCommand, manifestIngestCommand, migrateClaudeMemCommand;
@@ -51489,7 +52667,7 @@ var init_migrate_claude_mem = __esm({
         }
       },
       async run({ args }) {
-        const root = getProjectRoot35();
+        const root = getProjectRoot36();
         try {
           const result = await migrateClaudeMem(root, {
             sourcePath: args.source,
@@ -51538,7 +52716,7 @@ var init_migrate_claude_mem = __esm({
         }
       },
       async run({ args }) {
-        const projectRoot = getProjectRoot35();
+        const projectRoot = getProjectRoot36();
         try {
           const db = await getDb2(projectRoot);
           const rcasdFlag = Boolean(args.rcasd);
@@ -51642,7 +52820,7 @@ __export(nexus_exports, {
 import { appendFile as appendFile2, mkdir as mkdir3 } from "node:fs/promises";
 import { homedir as homedir6 } from "node:os";
 import path4 from "node:path";
-import { getProjectRoot as getProjectRoot36 } from "@cleocode/core";
+import { getProjectRoot as getProjectRoot37 } from "@cleocode/core";
 import { generateGexf, getSymbolImpact } from "@cleocode/core/nexus";
 async function appendDeprecationTelemetry(op, replacement) {
   try {
@@ -51754,7 +52932,7 @@ var init_nexus4 = __esm({
       async run({ args }) {
         applyJsonFlag2(args.json);
         const projectIdOverride = args["project-id"];
-        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot36();
+        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot37();
         const startTime = Date.now();
         try {
           const [{ getNexusDb, nexusSchema }, { getIndexStats }] = await Promise.all([
@@ -52269,7 +53447,7 @@ var init_nexus4 = __esm({
         applyJsonFlag2(args.json);
         const startTime = Date.now();
         const projectIdOverride = args["project-id"];
-        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot36();
+        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot37();
         const projectId = projectIdOverride ?? Buffer.from(repoPath).toString("base64url").slice(0, 32);
         const response = await dispatchRaw("query", "nexus", "clusters", { projectId, repoPath });
         const durationMs = Date.now() - startTime;
@@ -52313,7 +53491,7 @@ var init_nexus4 = __esm({
         applyJsonFlag2(args.json);
         const startTime = Date.now();
         const projectIdOverride = args["project-id"];
-        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot36();
+        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot37();
         const projectId = projectIdOverride ?? Buffer.from(repoPath).toString("base64url").slice(0, 32);
         const response = await dispatchRaw("query", "nexus", "flows", { projectId, repoPath });
         const durationMs = Date.now() - startTime;
@@ -52356,7 +53534,7 @@ var init_nexus4 = __esm({
         void appendDeprecationTelemetry("nexus.context", "cleo graph context");
         const startTime = Date.now();
         const projectIdOverride = args["project-id"];
-        const repoPath = getProjectRoot36();
+        const repoPath = getProjectRoot37();
         const projectId = projectIdOverride ?? Buffer.from(repoPath).toString("base64url").slice(0, 32);
         const limit = parseInt(args.limit, 10);
         const symbolName = args.symbol;
@@ -52419,7 +53597,7 @@ var init_nexus4 = __esm({
         const startTime = Date.now();
         const whyFlag = !!args.why;
         const projectIdOverride = args["project-id"];
-        const repoPath = getProjectRoot36();
+        const repoPath = getProjectRoot37();
         const projectId = projectIdOverride ?? Buffer.from(repoPath).toString("base64url").slice(0, 32);
         const maxDepth = Math.min(parseInt(args.depth, 10), 5);
         const symbolName = args.symbol;
@@ -52491,7 +53669,7 @@ var init_nexus4 = __esm({
         const projectIdOverride = args["project-id"];
         const isIncremental = !!args.incremental;
         const ctx = getFormatContext();
-        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot36();
+        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot37();
         humanInfo(`[nexus] Analyzing: ${repoPath}${isIncremental ? " (incremental)" : ""}`);
         try {
           const [{ getNexusDb, nexusSchema }, { runPipeline }, { eq: eq2 }] = await Promise.all([
@@ -52643,7 +53821,7 @@ var init_nexus4 = __esm({
       async run({ args }) {
         applyJsonFlag2(args.json);
         const startTime = Date.now();
-        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot36();
+        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot37();
         const name = args.name;
         const response = await dispatchRaw("mutate", "nexus", "projects.register", {
           path: repoPath,
@@ -53001,7 +54179,7 @@ var init_nexus4 = __esm({
         applyJsonFlag2(args.json);
         const startTime = Date.now();
         const projectIdOverride = args["project-id"];
-        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot36();
+        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot37();
         const projectId = projectIdOverride ?? Buffer.from(repoPath).toString("base64url").slice(0, 32);
         const response = await dispatchRaw("mutate", "nexus", "refresh-bridge", {
           repoPath,
@@ -53150,7 +54328,7 @@ var init_nexus4 = __esm({
       async run({ args }) {
         applyJsonFlag2(args.json);
         const startTime = Date.now();
-        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot36();
+        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot37();
         const projectIdOverride = args["project-id"];
         const beforeRef = args.before ?? "HEAD~1";
         const afterRef = args.after ?? "HEAD";
@@ -53268,7 +54446,7 @@ var init_nexus4 = __esm({
         applyJsonFlag2(args.json);
         const startTime = Date.now();
         const projectIdOverride = args["project-id"];
-        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot36();
+        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot37();
         const projectId = projectIdOverride ?? Buffer.from(repoPath).toString("base64url").slice(0, 32);
         const response = await dispatchRaw("query", "nexus", "route-map", { projectId });
         const durationMs = Date.now() - startTime;
@@ -53324,7 +54502,7 @@ var init_nexus4 = __esm({
         const startTime = Date.now();
         const routeSymbol = args.routeSymbol;
         const projectIdOverride = args["project-id"];
-        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot36();
+        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot37();
         const projectId = projectIdOverride ?? Buffer.from(repoPath).toString("base64url").slice(0, 32);
         const response = await dispatchRaw("query", "nexus", "shape-check", { routeSymbol, projectId });
         const durationMs = Date.now() - startTime;
@@ -53714,7 +54892,7 @@ var init_nexus4 = __esm({
       async run({ args }) {
         applyJsonFlag2(args.json);
         const startTime = Date.now();
-        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot36();
+        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot37();
         const projectIdOverride = args["project-id"];
         const projectId = projectIdOverride ?? Buffer.from(repoPath).toString("base64url").slice(0, 32);
         const response = await dispatchRaw("mutate", "nexus", "contracts-sync", {
@@ -53818,7 +54996,7 @@ var init_nexus4 = __esm({
       async run({ args }) {
         applyJsonFlag2(args.json);
         const startTime = Date.now();
-        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot36();
+        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot37();
         const projectId = Buffer.from(repoPath).toString("base64url").slice(0, 32);
         const response = await dispatchRaw("mutate", "nexus", "contracts-link-tasks", {
           projectId,
@@ -53894,7 +55072,7 @@ var init_nexus4 = __esm({
       async run({ args }) {
         applyJsonFlag2(args.json);
         const startTime = Date.now();
-        const outputDir = args.output ?? path4.join(getProjectRoot36(), ".cleo", "wiki");
+        const outputDir = args.output ?? path4.join(getProjectRoot37(), ".cleo", "wiki");
         const communityFilter = args.community ?? void 0;
         const isIncremental = !!args.incremental;
         let loomProvider = null;
@@ -53918,11 +55096,11 @@ var init_nexus4 = __esm({
         }
         try {
           const { generateNexusWikiIndex } = await import("@cleocode/core/nexus/wiki-index.js");
-          const result = await generateNexusWikiIndex(outputDir, getProjectRoot36(), {
+          const result = await generateNexusWikiIndex(outputDir, getProjectRoot37(), {
             communityFilter,
             incremental: isIncremental,
             loomProvider,
-            projectRoot: getProjectRoot36()
+            projectRoot: getProjectRoot37()
           });
           const durationMs = Date.now() - startTime;
           if (!result.success) {
@@ -55144,7 +56322,7 @@ __export(otel_exports, {
 import {
   CleoError as CleoError6,
   clearOtelData,
-  formatError as formatError8,
+  formatError as formatError6,
   getOtelSessions,
   getOtelSpawns,
   getOtelStatus,
@@ -55165,7 +56343,7 @@ var init_otel = __esm({
           cliOutput(result, { command: "otel" });
         } catch (err) {
           if (err instanceof CleoError6) {
-            cliError(formatError8(err), err.code, { name: "E_INTERNAL" });
+            cliError(formatError6(err), err.code, { name: "E_INTERNAL" });
             process.exit(err.code);
           }
           throw err;
@@ -55180,7 +56358,7 @@ var init_otel = __esm({
           cliOutput(result, { command: "otel" });
         } catch (err) {
           if (err instanceof CleoError6) {
-            cliError(formatError8(err), err.code, { name: "E_INTERNAL" });
+            cliError(formatError6(err), err.code, { name: "E_INTERNAL" });
             process.exit(err.code);
           }
           throw err;
@@ -55208,7 +56386,7 @@ var init_otel = __esm({
           cliOutput(result, { command: "otel" });
         } catch (err) {
           if (err instanceof CleoError6) {
-            cliError(formatError8(err), err.code, { name: "E_INTERNAL" });
+            cliError(formatError6(err), err.code, { name: "E_INTERNAL" });
             process.exit(err.code);
           }
           throw err;
@@ -55236,7 +56414,7 @@ var init_otel = __esm({
           cliOutput(result, { command: "otel" });
         } catch (err) {
           if (err instanceof CleoError6) {
-            cliError(formatError8(err), err.code, { name: "E_INTERNAL" });
+            cliError(formatError6(err), err.code, { name: "E_INTERNAL" });
             process.exit(err.code);
           }
           throw err;
@@ -55264,7 +56442,7 @@ var init_otel = __esm({
           cliOutput(result, { command: "otel" });
         } catch (err) {
           if (err instanceof CleoError6) {
-            cliError(formatError8(err), err.code, { name: "E_INTERNAL" });
+            cliError(formatError6(err), err.code, { name: "E_INTERNAL" });
             process.exit(err.code);
           }
           throw err;
@@ -55279,7 +56457,7 @@ var init_otel = __esm({
           cliOutput(result, { command: "otel" });
         } catch (err) {
           if (err instanceof CleoError6) {
-            cliError(formatError8(err), err.code, { name: "E_INTERNAL" });
+            cliError(formatError6(err), err.code, { name: "E_INTERNAL" });
             process.exit(err.code);
           }
           throw err;
@@ -56320,7 +57498,7 @@ var refresh_memory_exports = {};
 __export(refresh_memory_exports, {
   refreshMemoryCommand: () => refreshMemoryCommand
 });
-import { getProjectRoot as getProjectRoot37 } from "@cleocode/core";
+import { getProjectRoot as getProjectRoot38 } from "@cleocode/core";
 var refreshMemoryCommand;
 var init_refresh_memory = __esm({
   "packages/cleo/src/cli/commands/refresh-memory.ts"() {
@@ -56333,7 +57511,7 @@ var init_refresh_memory = __esm({
         description: "Regenerate .cleo/memory-bridge.md from brain.db"
       },
       async run() {
-        const projectDir = getProjectRoot37();
+        const projectDir = getProjectRoot38();
         const { writeMemoryBridge } = await import("@cleocode/core/internal");
         const result = await writeMemoryBridge(projectDir);
         if (result.written) {
@@ -56351,7 +57529,7 @@ var relates_exports = {};
 __export(relates_exports, {
   relatesCommand: () => relatesCommand
 });
-var suggestCommand2, addCommand7, discoverCommand3, removeCommand5, listCommand17, relatesCommand;
+var suggestCommand2, addCommand8, discoverCommand3, removeCommand5, listCommand17, relatesCommand;
 var init_relates = __esm({
   "packages/cleo/src/cli/commands/relates.ts"() {
     "use strict";
@@ -56382,7 +57560,7 @@ var init_relates = __esm({
         cliOutput(response.data ?? {}, { command: "relates" });
       }
     });
-    addCommand7 = defineCommand({
+    addCommand8 = defineCommand({
       meta: {
         name: "add",
         description: "Add a relates entry to a task. Valid types: blocks|related|duplicates|absorbs|fixes|extends|supersedes"
@@ -56495,7 +57673,7 @@ var init_relates = __esm({
       },
       subCommands: {
         suggest: suggestCommand2,
-        add: addCommand7,
+        add: addCommand8,
         remove: removeCommand5,
         discover: discoverCommand3,
         list: listCommand17
@@ -56515,7 +57693,7 @@ __export(release_exports, {
   SHIP_DEPRECATION_NOTICE: () => SHIP_DEPRECATION_NOTICE,
   releaseCommand: () => releaseCommand
 });
-import { pushWarning as pushWarning3, release as release2 } from "@cleocode/core";
+import { pushWarning as pushWarning4, release as release2 } from "@cleocode/core";
 var SHIP_DEPRECATION_NOTICE, shipCommand, listCommand18, showCommand10, cancelCommand2, changelogCommand, rollbackCommand, rollbackFullCommand, prStatusCommand, channelCommand, planCommand3, openCommand2, reconcileCommand4, releaseCommand;
 var init_release3 = __esm({
   "packages/cleo/src/cli/commands/release.ts"() {
@@ -56546,7 +57724,7 @@ var init_release3 = __esm({
         }
       },
       async run({ args }) {
-        pushWarning3({
+        pushWarning4({
           code: "W_DEPRECATED_COMMAND",
           message: SHIP_DEPRECATION_NOTICE,
           deprecated: "cleo release ship",
@@ -56642,6 +57820,19 @@ var init_release3 = __esm({
         }
       },
       async run({ args }) {
+        pushWarning4({
+          code: "W_DEPRECATED_COMMAND",
+          message: "`cleo release changelog <tag>` is deprecated. Use `cleo release plan <version> --epic <id>` (T9525) plus the T9759 LLM composer.",
+          severity: "warn",
+          deprecated: "cleo release changelog",
+          replacement: "cleo release plan",
+          removeBy: "v2026.6.0",
+          context: {
+            registryId: "cleo-release-changelog-verb-git-log",
+            task: "T9795",
+            saga: "T9787"
+          }
+        });
         const sinceTag = typeof args["sinceTag"] === "string" && args["sinceTag"].length > 0 ? args["sinceTag"] : typeof args["since"] === "string" && args["since"].length > 0 ? args["since"] : void 0;
         if (sinceTag === void 0) {
           cliError(
@@ -57294,14 +58485,14 @@ var req_exports = {};
 __export(req_exports, {
   reqCommand: () => reqCommand
 });
-var addCommand8, listCommand19, migrateCommand, reqCommand;
+var addCommand9, listCommand19, migrateCommand, reqCommand;
 var init_req = __esm({
   "packages/cleo/src/cli/commands/req.ts"() {
     "use strict";
     init_dist();
     init_cli();
     init_renderers();
-    addCommand8 = defineCommand({
+    addCommand9 = defineCommand({
       meta: {
         name: "add",
         description: "Add a typed AcceptanceGate (with REQ-ID) to a task's acceptance array"
@@ -57381,7 +58572,7 @@ var init_req = __esm({
     reqCommand = defineCommand({
       meta: { name: "req", description: "Manage REQ-ID-addressable acceptance gates on tasks" },
       subCommands: {
-        add: addCommand8,
+        add: addCommand9,
         list: listCommand19,
         migrate: migrateCommand
       },
@@ -57402,14 +58593,14 @@ __export(research_exports, {
 function generateResearchId() {
   return `res_${Date.now()}`;
 }
-var addCommand9, showCommand11, listCommand20, pendingCommand2, linkCommand2, updateCommand, statsCommand5, linksCommand, archiveCommand3, manifestCommand2, researchCommand;
+var addCommand10, showCommand11, listCommand20, pendingCommand2, linkCommand2, updateCommand, statsCommand5, linksCommand, archiveCommand3, manifestCommand2, researchCommand;
 var init_research2 = __esm({
   "packages/cleo/src/cli/commands/research.ts"() {
     "use strict";
     init_dist();
     init_cli();
     init_renderers();
-    addCommand9 = defineCommand({
+    addCommand10 = defineCommand({
       meta: { name: "add", description: "Add a research entry" },
       args: {
         task: {
@@ -57718,7 +58909,7 @@ var init_research2 = __esm({
     researchCommand = defineCommand({
       meta: { name: "research", description: "Research commands and manifest operations" },
       subCommands: {
-        add: addCommand9,
+        add: addCommand10,
         show: showCommand11,
         list: listCommand20,
         pending: pendingCommand2,
@@ -57746,7 +58937,7 @@ __export(restore_exports, {
 });
 import fs3 from "node:fs";
 import path5 from "node:path";
-import { CleoError as CleoError8, getProjectRoot as getProjectRoot38, getTaskAccessor as getTaskAccessor3 } from "@cleocode/core";
+import { CleoError as CleoError8, getProjectRoot as getProjectRoot39, getTaskAccessor as getTaskAccessor3 } from "@cleocode/core";
 function parseMarkdownValue(raw) {
   const trimmed = raw.trim();
   if (trimmed === "_(not present)_" || trimmed === "") return void 0;
@@ -57866,7 +59057,7 @@ var init_restore = __esm({
         description: "Apply manually-resolved conflicts from .cleo/restore-conflicts.md"
       },
       async run() {
-        const projectRoot = getProjectRoot38();
+        const projectRoot = getProjectRoot39();
         const reportPath = path5.join(projectRoot, CLEO_DIR_NAME, RESTORE_CONFLICTS_MD);
         if (!fs3.existsSync(reportPath)) {
           humanLine("No pending restore conflicts. Nothing to finalize.");
@@ -58232,7 +59423,7 @@ __export(revert_exports, {
   revertCommand: () => revertCommand
 });
 import { readFile as readFile4 } from "node:fs/promises";
-import { join as join26 } from "node:path";
+import { join as join28 } from "node:path";
 import { cwd as processCwd2 } from "node:process";
 import { E_RECEIPT_NOT_FOUND } from "@cleocode/core/sentient/chain-walker.js";
 import { SENTIENT_STATE_FILE } from "@cleocode/core/sentient/daemon.js";
@@ -58285,7 +59476,7 @@ async function loadOwnerAttestation(attestationFilePath) {
   return obj;
 }
 async function loadOwnerPubkeys(projectRoot) {
-  const path6 = join26(projectRoot, OWNER_PUBKEYS_FILE);
+  const path6 = join28(projectRoot, OWNER_PUBKEYS_FILE);
   try {
     const raw = await readFile4(path6, "utf-8");
     const parsed = JSON.parse(raw);
@@ -58369,7 +59560,7 @@ var init_revert = __esm({
         if (attestation && allowedPubkeys.size > 0 && !allowedPubkeys.has(attestation.ownerPubkey)) {
           emitFailure2(
             E_OWNER_ATTESTATION_REQUIRED,
-            `Attestation pubkey "${attestation.ownerPubkey}" is not in the owner allowlist at ${join26(projectRoot, OWNER_PUBKEYS_FILE)}`,
+            `Attestation pubkey "${attestation.ownerPubkey}" is not in the owner allowlist at ${join28(projectRoot, OWNER_PUBKEYS_FILE)}`,
             jsonMode
           );
         }
@@ -58422,7 +59613,7 @@ ${lines}`
             identity,
             includeHuman
           });
-          const statePath = join26(projectRoot, SENTIENT_STATE_FILE);
+          const statePath = join28(projectRoot, SENTIENT_STATE_FILE);
           const state = await readSentientState(statePath);
           emitSuccess(
             {
@@ -58563,7 +59754,7 @@ var saga_exports = {};
 __export(saga_exports, {
   sagaCommand: () => sagaCommand
 });
-var createCommand3, addCommand10, listCommand21, membersCommand, rollupCommand2, sagaCommand;
+var createCommand3, addCommand11, listCommand21, membersCommand, rollupCommand2, sagaCommand;
 var init_saga = __esm({
   "packages/cleo/src/cli/commands/saga.ts"() {
     "use strict";
@@ -58606,7 +59797,7 @@ var init_saga = __esm({
         );
       }
     });
-    addCommand10 = defineCommand({
+    addCommand11 = defineCommand({
       meta: {
         name: "add",
         description: "Link a member Epic to a Saga (writes task_relations type=groups)"
@@ -58691,7 +59882,7 @@ var init_saga = __esm({
       },
       subCommands: {
         create: createCommand3,
-        add: addCommand10,
+        add: addCommand11,
         list: listCommand21,
         members: membersCommand,
         rollup: rollupCommand2
@@ -58708,7 +59899,7 @@ var init_saga = __esm({
 // packages/cleo/src/cli/commands/schema.ts
 var schema_exports = {};
 __export(schema_exports, {
-  schemaCommand: () => schemaCommand
+  schemaCommand: () => schemaCommand2
 });
 import { describeOperation } from "@cleocode/lafs";
 function resolveOperationDef(operationArg) {
@@ -58724,7 +59915,7 @@ function resolveOperationDef(operationArg) {
   const operation = operationArg.slice(dotIdx + 1);
   return OPERATIONS.find((op) => op.domain === domain && op.operation === operation) ?? null;
 }
-var schemaCommand;
+var schemaCommand2;
 var init_schema = __esm({
   "packages/cleo/src/cli/commands/schema.ts"() {
     "use strict";
@@ -58732,7 +59923,7 @@ var init_schema = __esm({
     init_registry();
     init_format_context();
     init_renderers();
-    schemaCommand = defineCommand({
+    schemaCommand2 = defineCommand({
       meta: {
         name: "schema",
         description: "Introspect a CLEO operation: show params, types, enums, and declared gates"
@@ -58804,7 +59995,7 @@ __export(self_update_exports, {
 });
 import { execFile } from "node:child_process";
 import { readFile as readFile5 } from "node:fs/promises";
-import { join as join27 } from "node:path";
+import { join as join29 } from "node:path";
 import * as readline2 from "node:readline";
 import { promisify } from "node:util";
 import {
@@ -58819,7 +60010,7 @@ import {
 async function getCurrentVersion() {
   const cleoHome = getCleoHome4();
   try {
-    const content = await readFile5(join27(cleoHome, "VERSION"), "utf-8");
+    const content = await readFile5(join29(cleoHome, "VERSION"), "utf-8");
     return (content.split("\n")[0] ?? "unknown").trim();
   } catch {
     return "unknown";
@@ -58873,7 +60064,7 @@ async function writeRuntimeVersionMetadata(mode, source, version) {
   ];
   await import("node:fs/promises").then(
     ({ writeFile: writeFile4, mkdir: mkdir5 }) => mkdir5(cleoHome, { recursive: true }).then(
-      () => writeFile4(join27(cleoHome, "VERSION"), `${lines.join("\n")}
+      () => writeFile4(join29(cleoHome, "VERSION"), `${lines.join("\n")}
 `, "utf-8")
     )
   );
@@ -59284,7 +60475,7 @@ var sentient_exports = {};
 __export(sentient_exports, {
   sentientCommand: () => sentientCommand
 });
-import { join as join28 } from "node:path";
+import { join as join30 } from "node:path";
 import { cwd as processCwd3 } from "node:process";
 import {
   getSentientDaemonStatus as getSentientDaemonStatus2,
@@ -59359,7 +60550,7 @@ var init_sentient3 = __esm({
             return;
           }
           if (dryRun) {
-            const statePath2 = join28(projectRoot, SENTIENT_STATE_FILE2);
+            const statePath2 = join30(projectRoot, SENTIENT_STATE_FILE2);
             const outcome = await safeRunTick({ projectRoot, statePath: statePath2, dryRun: true });
             emitSuccess2(
               { dryRun: true, outcome },
@@ -59475,7 +60666,7 @@ Logs:  ${logPath}`
         const jsonMode = args.json === true;
         const dryRun = args["dry-run"] === true;
         try {
-          const statePath = join28(projectRoot, SENTIENT_STATE_FILE2);
+          const statePath = join30(projectRoot, SENTIENT_STATE_FILE2);
           const outcome = await safeRunTick({ projectRoot, statePath, dryRun });
           emitSuccess2(
             { outcome, dryRun },
@@ -59544,7 +60735,7 @@ Logs:  ${logPath}`
             return;
           }
           await db.update(tasks).set({ status: "pending", updatedAt: now }).where(eq2(tasks.id, id)).run();
-          const statePath = join28(projectRoot, SENTIENT_STATE_FILE2);
+          const statePath = join30(projectRoot, SENTIENT_STATE_FILE2);
           const state = await readSentientState2(statePath);
           await patchSentientState(statePath, {
             tier2Stats: {
@@ -59596,7 +60787,7 @@ Logs:  ${logPath}`
             return;
           }
           await db.update(tasks).set({ status: "cancelled", cancellationReason: reason, cancelledAt: now, updatedAt: now }).where(eq2(tasks.id, id)).run();
-          const statePath = join28(projectRoot, SENTIENT_STATE_FILE2);
+          const statePath = join30(projectRoot, SENTIENT_STATE_FILE2);
           const state = await readSentientState2(statePath);
           await patchSentientState(statePath, {
             tier2Stats: {
@@ -59641,7 +60832,7 @@ Logs:  ${logPath}`
         const projectRoot = resolveProjectRoot6(args.project);
         const jsonMode = args.json === true;
         try {
-          const statePath = join28(projectRoot, SENTIENT_STATE_FILE2);
+          const statePath = join30(projectRoot, SENTIENT_STATE_FILE2);
           const outcome = await safeRunProposeTick({ projectRoot, statePath });
           emitSuccess2(
             { outcome },
@@ -59661,7 +60852,7 @@ Logs:  ${logPath}`
         const projectRoot = resolveProjectRoot6(args.project);
         const jsonMode = args.json === true;
         try {
-          const statePath = join28(projectRoot, SENTIENT_STATE_FILE2);
+          const statePath = join30(projectRoot, SENTIENT_STATE_FILE2);
           const updated = await patchSentientState(statePath, { tier2Enabled: true });
           emitSuccess2({ tier2Enabled: updated.tier2Enabled }, jsonMode, "Tier-2 proposals enabled");
         } catch (err) {
@@ -59680,7 +60871,7 @@ Logs:  ${logPath}`
         const projectRoot = resolveProjectRoot6(args.project);
         const jsonMode = args.json === true;
         try {
-          const statePath = join28(projectRoot, SENTIENT_STATE_FILE2);
+          const statePath = join30(projectRoot, SENTIENT_STATE_FILE2);
           const updated = await patchSentientState(statePath, { tier2Enabled: false });
           emitSuccess2({ tier2Enabled: updated.tier2Enabled }, jsonMode, "Tier-2 proposals disabled");
         } catch (err) {
@@ -59711,7 +60902,7 @@ Logs:  ${logPath}`
         const projectRoot = resolveProjectRoot6(args.project);
         const jsonMode = args.json === true;
         try {
-          const statePath = join28(projectRoot, SENTIENT_STATE_FILE2);
+          const statePath = join30(projectRoot, SENTIENT_STATE_FILE2);
           const state = await readSentientState2(statePath);
           emitSuccess2(
             {
@@ -60269,7 +61460,7 @@ var sequence_exports = {};
 __export(sequence_exports, {
   sequenceCommand: () => sequenceCommand
 });
-import { getProjectRoot as getProjectRoot39 } from "@cleocode/core/internal";
+import { getProjectRoot as getProjectRoot40 } from "@cleocode/core/internal";
 var showCommand12, checkCommand6, repairCommand, sequenceCommand;
 var init_sequence = __esm({
   "packages/cleo/src/cli/commands/sequence.ts"() {
@@ -60305,7 +61496,7 @@ var init_sequence = __esm({
       meta: { name: "repair", description: "Reset counter to max + 1 if behind" },
       async run() {
         const { repairSequence } = await import("@cleocode/core/internal");
-        const projectRoot = getProjectRoot39();
+        const projectRoot = getProjectRoot40();
         const repair = await repairSequence(projectRoot);
         const result = {
           repaired: repair.repaired,
@@ -60394,7 +61585,7 @@ async function promptOwnerAuthPassword(sessionName) {
   const token = deriveOwnerAuthToken(sessionName, password);
   return token;
 }
-var startCommand7, endCommand, handoffCommand2, statusCommand14, resumeCommand2, findCommand6, listCommand22, gcCommand2, showCommand13, driftCommand, contextDriftCommand, suspendCommand, recordAssumptionCommand, recordDecisionCommand, decisionLogCommand, sessionCommand;
+var startCommand7, endCommand, handoffCommand2, statusCommand14, resumeCommand2, findCommand6, listCommand22, gcCommand2, showCommand13, driftCommand, contextDriftCommand, suspendCommand, recordAssumptionCommand, recordDecisionCommand, decisionLogCommand, lintCommand, sessionCommand;
 var init_session4 = __esm({
   "packages/cleo/src/cli/commands/session.ts"() {
     "use strict";
@@ -60748,8 +61939,8 @@ var init_session4 = __esm({
         "audit-scope": { type: "string", description: "Audit log scope (global|local)" }
       },
       async run({ args }) {
-        const { detectSessionDrift, getProjectRoot: getProjectRoot43 } = await import("@cleocode/core");
-        const projectRoot = await getProjectRoot43();
+        const { detectSessionDrift, getProjectRoot: getProjectRoot44 } = await import("@cleocode/core");
+        const projectRoot = await getProjectRoot44();
         const scope = args["audit-scope"] === "local" ? "local" : "global";
         const report = await detectSessionDrift({ projectRoot, auditScope: scope });
         cliOutput(report, { command: "session drift", operation: "session.drift" });
@@ -60915,6 +62106,28 @@ var init_session4 = __esm({
         );
       }
     });
+    lintCommand = defineCommand({
+      meta: {
+        name: "lint",
+        description: "Flag raw-md writes to canonical doc paths in a session transcript (T9797 \xB7 agent-accountability)"
+      },
+      args: {
+        transcript: {
+          type: "string",
+          description: "Absolute path to the *.jsonl transcript to scan",
+          required: true
+        }
+      },
+      async run({ args }) {
+        await dispatchFromCli(
+          "query",
+          "session",
+          "lint",
+          { transcript: args.transcript },
+          { command: "session", operation: "session.lint" }
+        );
+      }
+    });
     sessionCommand = defineCommand({
       meta: { name: "session", description: "Manage work sessions" },
       subCommands: {
@@ -60933,7 +62146,8 @@ var init_session4 = __esm({
         suspend: suspendCommand,
         "record-assumption": recordAssumptionCommand,
         "record-decision": recordDecisionCommand,
-        "decision-log": decisionLogCommand
+        "decision-log": decisionLogCommand,
+        lint: lintCommand
       },
       async run({ cmd, rawArgs }) {
         const firstArg = rawArgs?.find((a) => !a.startsWith("-"));
@@ -62768,7 +63982,7 @@ __export(sticky_exports, {
   stickyCommand: () => stickyCommand
 });
 import { CleoError as CleoError10 } from "@cleocode/core";
-var addCommand11, listCommand24, showCommand15, convertCommand, archiveCommand4, purgeCommand2, stickyCommand;
+var addCommand12, listCommand24, showCommand15, convertCommand, archiveCommand4, purgeCommand2, stickyCommand;
 var init_sticky3 = __esm({
   "packages/cleo/src/cli/commands/sticky.ts"() {
     "use strict";
@@ -62776,7 +63990,7 @@ var init_sticky3 = __esm({
     init_dist();
     init_cli();
     init_renderers();
-    addCommand11 = defineCommand({
+    addCommand12 = defineCommand({
       meta: { name: "add", description: "Create a new sticky note" },
       args: {
         content: {
@@ -63058,8 +64272,8 @@ var init_sticky3 = __esm({
         description: "Manage sticky notes - quick project-wide ephemeral captures"
       },
       subCommands: {
-        add: addCommand11,
-        jot: addCommand11,
+        add: addCommand12,
+        jot: addCommand12,
         list: listCommand24,
         ls: listCommand24,
         show: showCommand15,
@@ -63189,10 +64403,10 @@ var init_sync = __esm({
         }
       },
       async run({ args }) {
-        const { readFileSync: readFileSync18 } = await import("node:fs");
+        const { readFileSync: readFileSync20 } = await import("node:fs");
         let externalTasks;
         try {
-          externalTasks = JSON.parse(readFileSync18(args.file, "utf8"));
+          externalTasks = JSON.parse(readFileSync20(args.file, "utf8"));
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);
           cliError(`Failed to read or parse external tasks file: ${message}`, 2, {
@@ -63578,12 +64792,12 @@ var token_exports = {};
 __export(token_exports, {
   tokenCommand: () => tokenCommand
 });
-import { readFileSync as readFileSync16 } from "node:fs";
-import { getProjectRoot as getProjectRoot40, measureTokenExchange, recordTokenExchange as recordTokenExchange2 } from "@cleocode/core/internal";
+import { readFileSync as readFileSync18 } from "node:fs";
+import { getProjectRoot as getProjectRoot41, measureTokenExchange, recordTokenExchange as recordTokenExchange2 } from "@cleocode/core/internal";
 function readPayload(args, textKey, fileKey) {
   const text = args[textKey];
   const file = args[fileKey];
-  if (file) return readFileSync16(file, "utf-8");
+  if (file) return readFileSync18(file, "utf-8");
   return text;
 }
 var filterArgs, summaryCommand3, listCommand25, showCommand16, deleteCommand3, clearCommand2, estimateCommand, tokenCommand;
@@ -63743,7 +64957,7 @@ var init_token = __esm({
           domain: args.domain,
           operation: args.operation
         };
-        const result = args.record ? await recordTokenExchange2(getProjectRoot40(), input2) : await measureTokenExchange(input2);
+        const result = args.record ? await recordTokenExchange2(getProjectRoot41(), input2) : await measureTokenExchange(input2);
         cliOutput(result, {
           command: "token",
           operation: args.record ? "admin.token.record" : "token.estimate"
@@ -63778,8 +64992,8 @@ __export(transcript_exports, {
   transcriptCommand: () => transcriptCommand
 });
 import { homedir as homedir7 } from "node:os";
-import { join as join29 } from "node:path";
-import { getProjectRoot as getProjectRoot41 } from "@cleocode/core";
+import { join as join31 } from "node:path";
+import { getProjectRoot as getProjectRoot42 } from "@cleocode/core";
 import {
   parseDurationMs,
   pruneTranscripts,
@@ -63809,7 +65023,7 @@ var init_transcript = __esm({
       async run({ args }) {
         if (args.pending) {
           try {
-            const projectRoot = getProjectRoot41();
+            const projectRoot = getProjectRoot42();
             const { scanPendingTranscripts } = await import("@cleocode/core/memory/transcript-scanner.js");
             const pending = await scanPendingTranscripts(projectRoot);
             cliOutput(
@@ -63832,7 +65046,7 @@ var init_transcript = __esm({
           }
           return;
         }
-        const projectsDir = args["projects-dir"] ?? join29(homedir7(), ".claude", "projects");
+        const projectsDir = args["projects-dir"] ?? join31(homedir7(), ".claude", "projects");
         try {
           const result = await scanTranscripts(projectsDir);
           cliOutput(
@@ -63906,7 +65120,7 @@ var init_transcript = __esm({
       async run({ args }) {
         const tier = args.tier ?? "warm";
         const dryRun = args["dry-run"] ?? false;
-        const projectRoot = getProjectRoot41();
+        const projectRoot = getProjectRoot42();
         try {
           const { extractTranscript } = await import("@cleocode/core/memory/transcript-extractor.js");
           const { findSessionTranscriptPath, listAllTranscripts } = await import("@cleocode/core/memory/transcript-scanner.js");
@@ -64018,7 +65232,7 @@ var init_transcript = __esm({
         const dryRun = args["dry-run"] ?? false;
         const olderThanHours = args["older-than-hours"] ? Number.parseInt(args["older-than-hours"], 10) : 24;
         const limit = args.limit ? Number.parseInt(args.limit, 10) : void 0;
-        const projectRoot = getProjectRoot41();
+        const projectRoot = getProjectRoot42();
         try {
           const { extractTranscript } = await import("@cleocode/core/memory/transcript-extractor.js");
           const { listAllTranscripts } = await import("@cleocode/core/memory/transcript-scanner.js");
@@ -64138,7 +65352,7 @@ var init_transcript = __esm({
           process.exit(2);
           return;
         }
-        const projectsDir = args["projects-dir"] ?? join29(homedir7(), ".claude", "projects");
+        const projectsDir = args["projects-dir"] ?? join31(homedir7(), ".claude", "projects");
         try {
           const pruneResult = await pruneTranscripts({
             olderThanMs,
@@ -64803,15 +66017,15 @@ __export(web_exports, {
 });
 import { execFileSync as execFileSync4, spawn as spawn3 } from "node:child_process";
 import { mkdir as mkdir4, open, readFile as readFile6, rm, stat as stat2, writeFile as writeFile3 } from "node:fs/promises";
-import { join as join30 } from "node:path";
-import { CleoError as CleoError12, formatError as formatError9, getCleoHome as getCleoHome5 } from "@cleocode/core";
+import { join as join32 } from "node:path";
+import { CleoError as CleoError12, formatError as formatError7, getCleoHome as getCleoHome5 } from "@cleocode/core";
 function getWebPaths() {
   const cleoHome = getCleoHome5();
   return {
-    pidFile: join30(cleoHome, "web-server.pid"),
-    configFile: join30(cleoHome, "web-server.json"),
-    logDir: join30(cleoHome, "logs"),
-    logFile: join30(cleoHome, "logs", "web-server.log")
+    pidFile: join32(cleoHome, "web-server.pid"),
+    configFile: join32(cleoHome, "web-server.json"),
+    logDir: join32(cleoHome, "logs"),
+    logFile: join32(cleoHome, "logs", "web-server.log")
   };
 }
 function isProcessRunning(pid) {
@@ -64850,7 +66064,7 @@ async function startWebServer(port, host) {
     throw new CleoError12(1 /* GENERAL_ERROR */, `Server already running (PID: ${status.pid})`);
   }
   const projectRoot = process.env["CLEO_ROOT"] ?? process.cwd();
-  const studioDir = process.env["CLEO_STUDIO_DIR"] ?? join30(projectRoot, "packages", "studio", "build");
+  const studioDir = process.env["CLEO_STUDIO_DIR"] ?? join32(projectRoot, "packages", "studio", "build");
   await mkdir4(logDir, { recursive: true });
   await writeFile3(
     configFile,
@@ -64860,7 +66074,7 @@ async function startWebServer(port, host) {
       startedAt: (/* @__PURE__ */ new Date()).toISOString()
     })
   );
-  const webIndexPath = join30(studioDir, "index.js");
+  const webIndexPath = join32(studioDir, "index.js");
   try {
     await stat2(webIndexPath);
   } catch {
@@ -64957,7 +66171,7 @@ var init_web = __esm({
           await startWebServer(Number.parseInt(args.port, 10), args.host);
         } catch (err) {
           if (err instanceof CleoError12) {
-            console.error(formatError9(err));
+            console.error(formatError7(err));
             process.exit(err.code);
           }
           throw err;
@@ -65001,7 +66215,7 @@ var init_web = __esm({
           cliOutput({ stopped: true }, { command: "web", message: "CLEO Web UI stopped" });
         } catch (err) {
           if (err instanceof CleoError12) {
-            console.error(formatError9(err));
+            console.error(formatError7(err));
             process.exit(err.code);
           }
           throw err;
@@ -65054,7 +66268,7 @@ var init_web = __esm({
           await startWebServer(Number.parseInt(args.port, 10), args.host);
         } catch (err) {
           if (err instanceof CleoError12) {
-            console.error(formatError9(err));
+            console.error(formatError7(err));
             process.exit(err.code);
           }
           throw err;
@@ -65069,7 +66283,7 @@ var init_web = __esm({
           cliOutput(status, { command: "web" });
         } catch (err) {
           if (err instanceof CleoError12) {
-            console.error(formatError9(err));
+            console.error(formatError7(err));
             process.exit(err.code);
           }
           throw err;
@@ -65102,7 +66316,7 @@ var init_web = __esm({
           cliOutput({ url }, { command: "web", message: `Open browser to: ${url}` });
         } catch (err) {
           if (err instanceof CleoError12) {
-            console.error(formatError9(err));
+            console.error(formatError7(err));
             process.exit(err.code);
           }
           throw err;
@@ -65133,7 +66347,7 @@ __export(worktree_exports, {
   worktreeCommand: () => worktreeCommand
 });
 import readline4 from "node:readline";
-import { getProjectRoot as getProjectRoot42, listWorktrees as listWorktrees2 } from "@cleocode/core/internal";
+import { getProjectRoot as getProjectRoot43, listWorktrees as listWorktrees2 } from "@cleocode/core/internal";
 async function promptYesNo2(question) {
   return new Promise((resolve9) => {
     const rl = readline4.createInterface({ input: process.stdin, output: process.stdout });
@@ -65232,7 +66446,7 @@ var init_worktree3 = __esm({
         const yes = args["yes"] === true;
         const staleDaysRaw = typeof args["days"] === "string" ? args["days"] : void 0;
         const staleDays = staleDaysRaw !== void 0 ? Number.parseInt(staleDaysRaw, 10) : void 0;
-        const projectRoot = getProjectRoot42();
+        const projectRoot = getProjectRoot43();
         const listResult = await listWorktrees2({
           projectRoot,
           ...staleDays !== void 0 && !Number.isNaN(staleDays) ? { staleDays } : {}
@@ -65366,8 +66580,8 @@ var init_worktree3 = __esm({
 init_dist();
 init_field_context();
 init_format_context();
-import { readFileSync as readFileSync17 } from "node:fs";
-import { dirname as dirname12, join as join32 } from "node:path";
+import { readFileSync as readFileSync19 } from "node:fs";
+import { dirname as dirname12, join as join34 } from "node:path";
 import { fileURLToPath as fileURLToPath8 } from "node:url";
 
 // packages/cleo/src/cli/generated/command-manifest.ts
@@ -65504,6 +66718,12 @@ var COMMAND_MANIFEST = [
     description: "WarpChain pipeline management (tier-2 orchestrator)",
     load: async () => (await Promise.resolve().then(() => (init_chain(), chain_exports))).chainCommand
   },
+  {
+    exportName: "changesetCommand",
+    name: "changeset",
+    description: "Author task-anchored changeset entries that dual-write to ",
+    load: async () => (await Promise.resolve().then(() => (init_changeset(), changeset_exports))).changesetCommand
+  },
   {
     exportName: "checkCommand",
     name: "check",
@@ -66492,14 +67712,14 @@ function didYouMean(input2, candidates, maxDistance = 2) {
 }
 
 // packages/cleo/src/cli/lib/first-run-detection.ts
-import { existsSync as existsSync16 } from "node:fs";
-import { join as join31 } from "node:path";
+import { existsSync as existsSync17 } from "node:fs";
+import { join as join33 } from "node:path";
 async function detectFirstRun() {
   const envKey = process.env["ANTHROPIC_API_KEY"];
   if (typeof envKey === "string" && envKey.length > 0) return false;
   const { getCleoPlatformPaths } = await import("@cleocode/paths");
-  const configPath = join31(getCleoPlatformPaths().config, "config.json");
-  if (existsSync16(configPath)) return false;
+  const configPath = join33(getCleoPlatformPaths().config, "config.json");
+  if (existsSync17(configPath)) return false;
   try {
     const { getCredentialPool } = await import("@cleocode/core/llm/credential-pool.js");
     const pool = getCredentialPool();
@@ -66613,8 +67833,8 @@ Or via NodeSource: https://github.com/nodesource/distributions
   }
 }
 function getPackageVersion() {
-  const pkgPath = join32(dirname12(fileURLToPath8(import.meta.url)), "../../package.json");
-  const pkg = JSON.parse(readFileSync17(pkgPath, "utf-8"));
+  const pkgPath = join34(dirname12(fileURLToPath8(import.meta.url)), "../../package.json");
+  const pkg = JSON.parse(readFileSync19(pkgPath, "utf-8"));
   return pkg.version;
 }
 var CLI_VERSION = getPackageVersion();
@@ -66766,7 +67986,7 @@ async function runStartupMaintenance() {
     detectAndRemoveStrayProjectNexus,
     getGlobalSalt,
     getLogger: getLogger20,
-    getProjectRoot: getProjectRoot43,
+    getProjectRoot: getProjectRoot44,
     isCleanupMarkerSet,
     migrateSignaldockToConduit,
     needsSignaldockToConduitMigration,
@@ -66775,7 +67995,7 @@ async function runStartupMaintenance() {
   } = await import("@cleocode/core/internal");
   let projectRootForCleanup = "";
   try {
-    projectRootForCleanup = getProjectRoot43();
+    projectRootForCleanup = getProjectRoot44();
   } catch {
   }
   if (!isCleanupMarkerSet(CLI_VERSION, projectRootForCleanup)) {
@@ -66795,7 +68015,7 @@ async function runStartupMaintenance() {
   const isInitInvocation = process.argv.slice(2).some((a) => a === "init");
   if (!isInitInvocation) {
     try {
-      const _projectRootForMigration = getProjectRoot43();
+      const _projectRootForMigration = getProjectRoot44();
       if (needsSignaldockToConduitMigration(_projectRootForMigration)) {
         const migrationResult = migrateSignaldockToConduit(_projectRootForMigration);
         if (migrationResult.status === "failed") {