@alessandroraffa/tangyr 0.18.0 → 0.20.0

package/dist/index.js

@@ -1373,7 +1373,7 @@ var require_command = __commonJS({
     var EventEmitter = __require("events").EventEmitter;
     var childProcess = __require("child_process");
     var path45 = __require("path");
-    var fs44 = __require("fs");
+    var fs45 = __require("fs");
     var process5 = __require("process");
     var { Argument: Argument2, humanReadableArgName } = require_argument();
     var { CommanderError: CommanderError2 } = require_error();
@@ -2367,7 +2367,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @param {string} subcommandName
        */
       _checkForMissingExecutable(executableFile, executableDir, subcommandName) {
-        if (fs44.existsSync(executableFile)) return;
+        if (fs45.existsSync(executableFile)) return;
         const executableDirMessage = executableDir ? `searched for local subcommand relative to directory '${executableDir}'` : "no directory for search for local subcommand, use .executableDir() to supply a custom directory";
         const executableMissing = `'${executableFile}' does not exist
  - if '${subcommandName}' is not meant to be an executable command, remove description parameter from '.command()' and use '.description()' instead
@@ -2386,10 +2386,10 @@ Expecting one of '${allowedValues.join("', '")}'`);
         const sourceExt = [".js", ".ts", ".tsx", ".mjs", ".cjs"];
         function findFile(baseDir, baseName) {
           const localBin = path45.resolve(baseDir, baseName);
-          if (fs44.existsSync(localBin)) return localBin;
+          if (fs45.existsSync(localBin)) return localBin;
           if (sourceExt.includes(path45.extname(baseName))) return void 0;
           const foundExt = sourceExt.find(
-            (ext) => fs44.existsSync(`${localBin}${ext}`)
+            (ext) => fs45.existsSync(`${localBin}${ext}`)
           );
           if (foundExt) return `${localBin}${foundExt}`;
           return void 0;
@@ -2401,7 +2401,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         if (this._scriptPath) {
           let resolvedScriptPath;
           try {
-            resolvedScriptPath = fs44.realpathSync(this._scriptPath);
+            resolvedScriptPath = fs45.realpathSync(this._scriptPath);
           } catch {
             resolvedScriptPath = this._scriptPath;
           }
@@ -10489,14 +10489,14 @@ var require_parser = __commonJS({
             case "scalar":
             case "single-quoted-scalar":
             case "double-quoted-scalar": {
-              const fs44 = this.flowScalar(this.type);
+              const fs45 = this.flowScalar(this.type);
               if (atNextItem || it2.value) {
-                map.items.push({ start, key: fs44, sep: [] });
+                map.items.push({ start, key: fs45, sep: [] });
                 this.onKeyLine = true;
               } else if (it2.sep) {
-                this.stack.push(fs44);
+                this.stack.push(fs45);
               } else {
-                Object.assign(it2, { key: fs44, sep: [] });
+                Object.assign(it2, { key: fs45, sep: [] });
                 this.onKeyLine = true;
               }
               return;
@@ -10624,13 +10624,13 @@ var require_parser = __commonJS({
             case "scalar":
             case "single-quoted-scalar":
             case "double-quoted-scalar": {
-              const fs44 = this.flowScalar(this.type);
+              const fs45 = this.flowScalar(this.type);
               if (!it2 || it2.value)
-                fc.items.push({ start: [], key: fs44, sep: [] });
+                fc.items.push({ start: [], key: fs45, sep: [] });
               else if (it2.sep)
-                this.stack.push(fs44);
+                this.stack.push(fs45);
               else
-                Object.assign(it2, { key: fs44, sep: [] });
+                Object.assign(it2, { key: fs45, sep: [] });
               return;
             }
             case "flow-map-end":
@@ -12551,22 +12551,22 @@ var require_parse_async = __commonJS({
       const index = 0;
       const blocksize = opts.blocksize || 40960;
       const parser = new TOMLParser();
-      return new Promise((resolve, reject) => {
-        setImmediate(parseAsyncNext, index, blocksize, resolve, reject);
+      return new Promise((resolve, reject2) => {
+        setImmediate(parseAsyncNext, index, blocksize, resolve, reject2);
       });
-      function parseAsyncNext(index2, blocksize2, resolve, reject) {
+      function parseAsyncNext(index2, blocksize2, resolve, reject2) {
         if (index2 >= str.length) {
           try {
             return resolve(parser.finish());
           } catch (err) {
-            return reject(prettyError(err, str));
+            return reject2(prettyError(err, str));
           }
         }
         try {
           parser.parse(str.slice(index2, index2 + blocksize2));
-          setImmediate(parseAsyncNext, index2 + blocksize2, blocksize2, resolve, reject);
+          setImmediate(parseAsyncNext, index2 + blocksize2, blocksize2, resolve, reject2);
         } catch (err) {
-          reject(prettyError(err, str));
+          reject2(prettyError(err, str));
         }
       }
     }
@@ -12590,7 +12590,7 @@ var require_parse_stream = __commonJS({
     function parseReadable(stm) {
       const parser = new TOMLParser();
       stm.setEncoding("utf8");
-      return new Promise((resolve, reject) => {
+      return new Promise((resolve, reject2) => {
         let readable;
         let ended = false;
         let errored = false;
@@ -12600,12 +12600,12 @@ var require_parse_stream = __commonJS({
           try {
             resolve(parser.finish());
           } catch (err) {
-            reject(err);
+            reject2(err);
           }
         }
         function error(err) {
           errored = true;
-          reject(err);
+          reject2(err);
         }
         stm.once("end", finish);
         stm.once("error", error);
@@ -14307,12 +14307,12 @@ var PromisePolyfill = class extends Promise {
   // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/withResolvers
   static withResolver() {
     let resolve;
-    let reject;
+    let reject2;
     const promise = new Promise((res, rej) => {
       resolve = res;
-      reject = rej;
+      reject2 = rej;
     });
-    return { promise, resolve, reject };
+    return { promise, resolve, reject: reject2 };
   }
 };
 
@@ -14349,10 +14349,10 @@ function createPrompt(view) {
       output
     });
     const screen = new ScreenManager(rl);
-    const { promise, resolve, reject } = PromisePolyfill.withResolver();
-    const cancel = () => reject(new CancelPromptError());
+    const { promise, resolve, reject: reject2 } = PromisePolyfill.withResolver();
+    const cancel = () => reject2(new CancelPromptError());
     if (signal) {
-      const abort = () => reject(new AbortPromptError({ cause: signal.reason }));
+      const abort = () => reject2(new AbortPromptError({ cause: signal.reason }));
       if (signal.aborted) {
         abort();
         return Object.assign(promise, { cancel });
@@ -14361,9 +14361,9 @@ function createPrompt(view) {
       cleanups.add(() => signal.removeEventListener("abort", abort));
     }
     cleanups.add(onExit((code, signal2) => {
-      reject(new ExitPromptError(`User force closed the prompt with ${code} ${signal2}`));
+      reject2(new ExitPromptError(`User force closed the prompt with ${code} ${signal2}`));
     }));
-    const sigint = () => reject(new ExitPromptError(`User force closed the prompt with SIGINT`));
+    const sigint = () => reject2(new ExitPromptError(`User force closed the prompt with SIGINT`));
     rl.on("SIGINT", sigint);
     cleanups.add(() => rl.removeListener("SIGINT", sigint));
     return withHooks(rl, (cycle) => {
@@ -14397,7 +14397,7 @@ function createPrompt(view) {
             screen.render(content, bottomContent);
             effectScheduler.run();
           } catch (error) {
-            reject(error);
+            reject2(error);
           }
           effectsSettled = true;
           if (pendingDone !== null) {
@@ -15667,7 +15667,11 @@ function vscodeUserDataDir() {
     return expandHome(process.env.VSCODE_USER_DATA_DIR);
   }
   if (process.env.VSCODE_PORTABLE) {
-    return path7.join(expandHome(process.env.VSCODE_PORTABLE), "user-data", "User");
+    return path7.join(
+      expandHome(process.env.VSCODE_PORTABLE),
+      "user-data",
+      "User"
+    );
   }
   const homeDir = canonicalHomeDir();
   if (process.platform === "darwin") {
@@ -16154,6 +16158,25 @@ var KIT_COMPONENTS = [
   "rules",
   "hooks"
 ];
+var DEFAULT_ENTRYPOINT = "ORIENTATION.md";
+var LEGACY_ENTRYPOINT = "CLAUDE.md";
+function resolveEntrypoint(kit) {
+  const declared = kit.entrypoint;
+  if (declared !== void 0) {
+    const file = path9.join(kit.path, declared);
+    return fs8.existsSync(file) ? { file, name: declared, legacy: false } : null;
+  }
+  const canonical = path9.join(kit.path, DEFAULT_ENTRYPOINT);
+  if (fs8.existsSync(canonical)) {
+    return { file: canonical, name: DEFAULT_ENTRYPOINT, legacy: false };
+  }
+  const legacy = path9.join(kit.path, LEGACY_ENTRYPOINT);
+  if (fs8.existsSync(legacy)) {
+    return { file: legacy, name: LEGACY_ENTRYPOINT, legacy: true };
+  }
+  return null;
+}
+var LEGACY_ENTRYPOINT_NOTICE = `This kit has no '${DEFAULT_ENTRYPOINT}' and no 'entrypoint' in tangyr-kit.yaml, so '${LEGACY_ENTRYPOINT}' was used. '${DEFAULT_ENTRYPOINT}' is the contract's canonical orientation document; '${LEGACY_ENTRYPOINT}' is one of the names targets translate it to, and a kit that ships only the translation is naming a target rather than itself. To fix: rename '${LEGACY_ENTRYPOINT}' to '${DEFAULT_ENTRYPOINT}', or add "entrypoint: ${LEGACY_ENTRYPOINT}" to tangyr-kit.yaml to keep the name deliberately.`;
 function discoverKits(searchPaths) {
   const kits = [];
   for (const searchPath of searchPaths) {
@@ -16198,6 +16221,7 @@ function loadKit(kitPath) {
     version: manifestResult.version,
     description: manifestResult.description,
     archetype: manifestResult.archetype,
+    ...manifestResult.entrypoint !== void 0 ? { entrypoint: manifestResult.entrypoint } : {},
     discipline: manifestResult.discipline,
     components
   };
@@ -17845,7 +17869,7 @@ async function runCacheClearCommand(options, logger) {
 }
 
 // src/commands/cleanup.ts
-import fs24 from "fs";
+import fs25 from "fs";
 import path22 from "path";
 
 // node_modules/glob/dist/esm/index.min.js
@@ -20992,7 +21016,7 @@ function removeManagedEntries(filePath, parser, serializer, removeManaged, logge
 }
 
 // src/commands/uninstall.ts
-import fs23 from "fs";
+import fs24 from "fs";
 import path21 from "path";
 
 // src/core/managed-sources.ts
@@ -21043,10 +21067,11 @@ function hooksSourceExists(sourceRoot, config) {
   }
   return fs20.readdirSync(hooksDir).some((f) => f.endsWith(".md") && !f.startsWith("."));
 }
-function hooksSourceLabel(config) {
-  return normalizeManagedSourcePath(
-    path19.posix.join(config.source.hooks.replace(/\\/gu, "/"), "hooks.json")
+function hooksSourceLabel(sourceRoot, config) {
+  const dir = normalizeManagedSourcePath(
+    config.source.hooks.replace(/\\/gu, "/")
   );
+  return fs20.existsSync(resolveHooksSourceFile(sourceRoot, config)) ? path19.posix.join(dir, "hooks.json") : `${dir}/`;
 }
 function resolveMcpSourceFile(sourceRoot, config) {
   return path19.resolve(sourceRoot, config.source.mcp);
@@ -21060,44 +21085,148 @@ function normalizeManagedSourcePath(rawPath) {
 }
 
 // src/compiler/hook-components.ts
-var import_yaml6 = __toESM(require_dist(), 1);
-import fs21 from "fs";
+import fs22 from "fs";
 import path20 from "path";
+
+// src/compiler/loss-report.ts
+import fs21 from "fs";
+function createLossReport() {
+  return {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    targets: {},
+    summary: {},
+    informational: []
+  };
+}
+function addInformational(report, target, component, source, severity, detail) {
+  report.informational.push({ target, component, source, severity, detail });
+}
+function addLoss(report, target, component, loss) {
+  const targetReport = report.targets[target] ?? {};
+  const componentReport = targetReport[component] ?? [];
+  componentReport.push(loss);
+  targetReport[component] = componentReport;
+  report.targets[target] = targetReport;
+  const targetSummary = report.summary[target] ?? {
+    info: 0,
+    warning: 0,
+    error: 0
+  };
+  for (const field of loss.fields) {
+    targetSummary[field.severity] += 1;
+  }
+  report.summary[target] = targetSummary;
+}
+var lossSeverityByEntryType = {
+  "command-as-skill": "info",
+  "rule-as-instruction": "info",
+  "rule-mode-downgrade": "warning",
+  "rule-path-scoping": "warning",
+  "hook-event-drop": "warning",
+  // A declaration the parser refuses installs nothing, anywhere, and used to
+  // do so silently. Error severity is what makes install and sync exit 3.
+  "hook-declaration-invalid": "error",
+  // Both source forms present means one of them is inert and nothing says
+  // which. Error severity, because the CLI cannot tell an author which half
+  // of their kit it is ignoring without them deciding first.
+  "hook-source-ambiguous": "error",
+  // A warning, not an error: the hooks that do reach the target are correct,
+  // and the remedy is a choice about scope rather than a defect in the kit.
+  "hook-script-path-unresolved": "warning",
+  "hook-as-plugin": "error",
+  "instructions-shim": "info",
+  "permission-coarsening": "error",
+  "provider-not-representable": "error",
+  "provider-wire-protocol": "error",
+  "model-not-representable": "error",
+  "persona-not-representable": "error",
+  "settings-not-representable": "warning"
+};
+function resolveLossSeverity(kind, name, action, explicitSeverity) {
+  if (explicitSeverity) {
+    return explicitSeverity;
+  }
+  return lossSeverityByEntryType[action];
+}
+function writeLossReport(filePath, report) {
+  if (!filePath) {
+    return;
+  }
+  fs21.writeFileSync(filePath, `${JSON.stringify(report, null, 2)}
+`);
+}
+
+// src/compiler/hook-components.ts
+var import_yaml6 = __toESM(require_dist(), 1);
+function reject(filePath, field, reason) {
+  return { ok: false, rejection: { file: filePath, field, reason } };
+}
 function parseHookDeclaration(filePath) {
   let raw;
   try {
-    raw = fs21.readFileSync(filePath, "utf8");
+    raw = fs22.readFileSync(filePath, "utf8");
   } catch {
-    return null;
+    return reject(filePath, "<file>", "the file could not be read");
   }
   const fm = extractFrontmatter(raw);
   if (!fm) {
-    return null;
+    return reject(
+      filePath,
+      "<frontmatter>",
+      "no YAML frontmatter was found; a hook declaration opens with a '---' block carrying name, description and events"
+    );
   }
-  const { name, description, events } = fm;
+  const { name, description, events, command } = fm;
   if (typeof name !== "string" || !name.trim()) {
-    return null;
+    return reject(filePath, "name", "expected a non-empty string");
   }
   if (typeof description !== "string" || !description.trim()) {
-    return null;
+    return reject(filePath, "description", "expected a non-empty string");
+  }
+  if (command !== void 0 && (typeof command !== "string" || !command.trim())) {
+    return reject(
+      filePath,
+      "command",
+      "expected a non-empty string naming the command the harness runs; omit the field entirely to accept the synthesized default"
+    );
   }
   if (!Array.isArray(events) || events.length === 0) {
-    return null;
+    return reject(
+      filePath,
+      "events",
+      'expected a non-empty list of event objects, e.g. "- event: PreToolUse\\n  timeout: 10\\n  statusMessage: \u2026". A list of plain event names is the most common mistake and is rejected: each entry must be an object'
+    );
   }
   const parsedEvents = [];
-  for (const entry of events) {
+  for (const [index, entry] of events.entries()) {
     if (!entry || typeof entry !== "object") {
-      return null;
+      return reject(
+        filePath,
+        `events[${index}]`,
+        `expected an object with 'event', 'timeout' and 'statusMessage'; found ${typeof entry === "string" ? `the bare string "${entry}"` : typeof entry}`
+      );
     }
     const ev = entry;
     if (typeof ev.event !== "string" || !ev.event.trim()) {
-      return null;
+      return reject(
+        filePath,
+        `events[${index}].event`,
+        "expected a non-empty string naming the harness event"
+      );
     }
     if (typeof ev.timeout !== "number") {
-      return null;
+      return reject(
+        filePath,
+        `events[${index}].timeout`,
+        "expected a number, in seconds"
+      );
     }
     if (typeof ev.statusMessage !== "string" || !ev.statusMessage.trim()) {
-      return null;
+      return reject(
+        filePath,
+        `events[${index}].statusMessage`,
+        "expected a non-empty string shown while the hook runs"
+      );
     }
     const parsed = {
       event: ev.event,
@@ -21110,15 +21239,23 @@ function parseHookDeclaration(filePath) {
     parsedEvents.push(parsed);
   }
   return {
-    name: name.trim(),
-    description: description.trim(),
-    events: parsedEvents
+    ok: true,
+    declaration: {
+      name: name.trim(),
+      description: description.trim(),
+      ...typeof command === "string" ? { command: command.trim() } : {},
+      events: parsedEvents
+    }
   };
 }
-function hookCommand(name) {
-  return `npx tsx ~/.agents/hooks/scripts/${name}.ts`;
+var GLOBAL_HOOK_SCRIPTS_DIR = "~/.agents/hooks/scripts";
+function synthesizedHookCommand(name, scriptsDir = GLOBAL_HOOK_SCRIPTS_DIR) {
+  return `npx tsx ${scriptsDir}/${name}.ts`;
+}
+function resolveHookCommand(declaration, scriptsDir) {
+  return declaration.command ?? synthesizedHookCommand(declaration.name, scriptsDir);
 }
-function synthesizeHooksJson(declarations) {
+function synthesizeHooksJson(declarations, scriptsDir) {
   const hooks = {};
   for (const decl of declarations) {
     for (const ev of decl.events) {
@@ -21129,7 +21266,7 @@ function synthesizeHooksJson(declarations) {
         hooks: [
           {
             type: "command",
-            command: hookCommand(decl.name),
+            command: resolveHookCommand(decl, scriptsDir),
             timeout: ev.timeout,
             statusMessage: ev.statusMessage
           }
@@ -21148,35 +21285,56 @@ function synthesizeHooksJson(declarations) {
   }
   return { hooks };
 }
-function loadSourceHooks(hooksDir, hookNames) {
+function loadSourceHooks(hooksDir, hookNames, scriptsDir) {
   const hooksJsonPath = path20.join(hooksDir, "hooks.json");
-  if (fs21.existsSync(hooksJsonPath)) {
-    const raw = fs21.readFileSync(hooksJsonPath, "utf8");
+  if (fs22.existsSync(hooksJsonPath)) {
+    const raw = fs22.readFileSync(hooksJsonPath, "utf8");
     return JSON.parse(raw);
   }
   const declarations = loadHookDeclarations(hooksDir, hookNames);
-  return synthesizeHooksJson(declarations);
+  return synthesizeHooksJson(declarations, scriptsDir);
 }
 function loadHookDeclarations(hooksDir, hookNames) {
   let names;
   if (hookNames && hookNames.length > 0) {
     names = hookNames;
   } else {
-    if (!fs21.existsSync(hooksDir) || !fs21.statSync(hooksDir).isDirectory()) {
+    if (!fs22.existsSync(hooksDir) || !fs22.statSync(hooksDir).isDirectory()) {
       return [];
     }
-    names = fs21.readdirSync(hooksDir).filter((f) => f.endsWith(".md") && !f.startsWith(".")).map((f) => f.slice(0, -3)).sort();
+    names = fs22.readdirSync(hooksDir).filter((f) => f.endsWith(".md") && !f.startsWith(".")).map((f) => f.slice(0, -3)).sort();
   }
   const declarations = [];
   for (const name of names) {
     const filePath = path20.join(hooksDir, `${name}.md`);
-    const decl = parseHookDeclaration(filePath);
-    if (decl) {
-      declarations.push(decl);
+    const result = parseHookDeclaration(filePath);
+    if (result.ok) {
+      declarations.push(result.declaration);
     }
   }
   return declarations;
 }
+function collectHookRejections(hooksDir, hookNames) {
+  if (fs22.existsSync(path20.join(hooksDir, "hooks.json"))) {
+    return [];
+  }
+  if (!fs22.existsSync(hooksDir) || !fs22.statSync(hooksDir).isDirectory()) {
+    return [];
+  }
+  const names = hookNames && hookNames.length > 0 ? hookNames : fs22.readdirSync(hooksDir).filter((f) => f.endsWith(".md") && !f.startsWith(".")).map((f) => f.slice(0, -3)).sort();
+  const rejections = [];
+  for (const name of names) {
+    const filePath = path20.join(hooksDir, `${name}.md`);
+    if (!fs22.existsSync(filePath)) {
+      continue;
+    }
+    const result = parseHookDeclaration(filePath);
+    if (!result.ok) {
+      rejections.push(result.rejection);
+    }
+  }
+  return rejections;
+}
 function extractFrontmatter(content) {
   if (!content.startsWith("---\n")) {
     return null;
@@ -21197,22 +21355,179 @@ function extractFrontmatter(content) {
   }
   return parsed;
 }
+function reportHookRejections(report, targets, hooksDir, hookNames) {
+  const rejections = collectHookRejections(hooksDir, hookNames);
+  for (const rejection of rejections) {
+    const name = path20.basename(rejection.file, ".md");
+    for (const target of targets) {
+      addLoss(report, target, "hooks", {
+        source: `hooks/${path20.basename(rejection.file)}`,
+        fields: [
+          {
+            field: rejection.field,
+            action: "hook-declaration-invalid",
+            severity: "error",
+            detail: `Hook '${name}' was not installed: its declaration was rejected at '${rejection.field}' \u2014 ${rejection.reason}. To fix: correct that field in this file, then re-run. Until then this hook reaches no target.`
+          }
+        ]
+      });
+    }
+  }
+  return rejections;
+}
+function declarationFileNames(hooksDir) {
+  if (!fs22.existsSync(hooksDir) || !fs22.statSync(hooksDir).isDirectory()) {
+    return [];
+  }
+  return fs22.readdirSync(hooksDir).filter((f) => f.endsWith(".md") && !f.startsWith(".")).sort();
+}
+function detectHooksSourceForm(hooksDir) {
+  const hasJson = fs22.existsSync(path20.join(hooksDir, "hooks.json"));
+  const hasDeclarations = declarationFileNames(hooksDir).length > 0;
+  if (hasJson && hasDeclarations) return { kind: "both" };
+  if (hasJson) return { kind: "hooks-json" };
+  if (hasDeclarations) return { kind: "declarations" };
+  return { kind: "absent" };
+}
+function registrations(hooksJson) {
+  const out = /* @__PURE__ */ new Set();
+  if (!hooksJson || typeof hooksJson !== "object") return out;
+  const hooks = hooksJson.hooks;
+  if (!hooks || typeof hooks !== "object") return out;
+  for (const [event, entries] of Object.entries(
+    hooks
+  )) {
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      if (!entry || typeof entry !== "object") continue;
+      const e = entry;
+      const matcher = typeof e.matcher === "string" ? e.matcher : "*";
+      const inner = Array.isArray(e.hooks) ? e.hooks : [];
+      for (const h of inner) {
+        if (!h || typeof h !== "object") continue;
+        const command = h.command;
+        out.add(`${event} [${matcher}] ${String(command)}`);
+      }
+    }
+  }
+  return out;
+}
+function describeHooksSourceConflict(hooksDir, hookNames) {
+  if (detectHooksSourceForm(hooksDir).kind !== "both") {
+    return null;
+  }
+  const jsonPath = path20.join(hooksDir, "hooks.json");
+  const declared = declarationFileNames(hooksDir);
+  let divergence = "";
+  try {
+    const fromJson = registrations(
+      JSON.parse(fs22.readFileSync(jsonPath, "utf8"))
+    );
+    const fromDeclarations = registrations(
+      synthesizeHooksJson(loadHookDeclarations(hooksDir, hookNames))
+    );
+    const onlyJson = [...fromJson].filter((r) => !fromDeclarations.has(r));
+    const onlyDeclarations = [...fromDeclarations].filter(
+      (r) => !fromJson.has(r)
+    );
+    if (onlyJson.length === 0 && onlyDeclarations.length === 0) {
+      divergence = " The two forms currently register the same hooks, so nothing is being lost yet \u2014 but only one of them is read, and the next edit to the other will be silent.";
+    } else {
+      const lines = [
+        ...onlyJson.map((r) => `    shipped, not declared: ${r}`),
+        ...onlyDeclarations.map((r) => `    declared, not shipped: ${r}`)
+      ];
+      divergence = " The two forms disagree. Only hooks.json is read, so:\n" + lines.join("\n");
+    }
+  } catch (error) {
+    divergence = ` The two forms could not be compared: ${error instanceof Error ? error.message : String(error)}.`;
+  }
+  return `This kit declares its hooks twice: '${jsonPath}' and ${declared.length} declaration file${declared.length === 1 ? "" : "s"} (${declared.join(", ")}) in the same directory. A kit must write one form or the other.${divergence}
+  To fix: keep the declarations and delete hooks.json \u2014 the declarations are the documented form, they carry the description and the per-event statusMessage, and they are what 'tangyr validate' checks. Before deleting, fold anything above that hooks.json ships and the declarations do not into the matching hooks/<name>.md, and add every hook name to 'components.hooks' in tangyr-kit.yaml. To keep hooks.json instead, delete the .md files \u2014 but note that no target then receives a hook description, and the manifest's hook list stops being checked against anything.`;
+}
+function loadKitHooksSource(sourceRoot, config, scriptsDir) {
+  if (!hooksSourceExists(sourceRoot, config)) {
+    return null;
+  }
+  const hooksDir = resolveHooksSourceDir(sourceRoot, config);
+  const hooks = loadSourceHooks(
+    hooksDir,
+    resolveKitHookNames(sourceRoot),
+    scriptsDir
+  );
+  const form = detectHooksSourceForm(hooksDir);
+  return {
+    hooks,
+    path: form.kind === "declarations" ? hooksDir : path20.join(hooksDir, "hooks.json"),
+    label: hooksSourceLabel(sourceRoot, config),
+    // Hashed over the compiled input rather than over one file's bytes: the
+    // declaration form has no single file to hash, and what provenance needs
+    // to identify is what was compiled.
+    hash: computeBytesHash(Buffer.from(JSON.stringify(hooks), "utf8"))
+  };
+}
+function reportHooksSourceConflict(report, targets, hooksDir, hookNames) {
+  const message = describeHooksSourceConflict(hooksDir, hookNames);
+  if (!message) {
+    return null;
+  }
+  for (const target of targets) {
+    addLoss(report, target, "hooks", {
+      source: `${path20.basename(hooksDir)}/`,
+      fields: [
+        {
+          field: "hooks.json",
+          action: "hook-source-ambiguous",
+          severity: "error",
+          detail: message
+        }
+      ]
+    });
+  }
+  return message;
+}
+function reportProjectScopeScriptPath(report, targets, hooksDir, hookNames) {
+  const affected = targets.filter((t) => t !== "claude-code");
+  if (affected.length === 0) {
+    return [];
+  }
+  const synthesized = loadHookDeclarations(hooksDir, hookNames).filter(
+    (d) => d.command === void 0
+  );
+  if (synthesized.length === 0) {
+    return [];
+  }
+  for (const target of affected) {
+    addLoss(report, target, "hooks", {
+      source: `${path20.basename(hooksDir)}/`,
+      fields: [
+        {
+          field: "command",
+          action: "hook-script-path-unresolved",
+          severity: "warning",
+          detail: `The ${synthesized.length} hook${synthesized.length === 1 ? "" : "s"} that take the synthesized command name '${GLOBAL_HOOK_SCRIPTS_DIR}/<name>.ts', which a project-scope install does not write. Only the claude-code adapter delivers hook scripts into a project, and only its own commands are resolved against the project. To fix, choose one: install this kit at global scope, where the path is correct; install claude-code alongside ${target} so the scripts reach the project, and give each hook an explicit 'command' pointing at them; or give each hook a 'command' of its own. Until then these hooks do not run under ${target}.`
+        }
+      ]
+    });
+  }
+  return affected;
+}
 
 // src/core/remove.ts
-import fs22 from "fs";
+import fs23 from "fs";
 function removeManagedPath(managedPath) {
   let stat;
   try {
-    stat = fs22.lstatSync(managedPath);
+    stat = fs23.lstatSync(managedPath);
   } catch {
     return;
   }
   if (stat.isSymbolicLink() || stat.isFile()) {
-    fs22.unlinkSync(managedPath);
+    fs23.unlinkSync(managedPath);
     return;
   }
   if (stat.isDirectory()) {
-    fs22.rmSync(managedPath, { recursive: true, force: true });
+    fs23.rmSync(managedPath, { recursive: true, force: true });
   }
 }
 
@@ -21320,7 +21635,7 @@ async function runUninstallCommand(options, logger) {
         runtime
       );
       for (const actualPath of paths) {
-        if (actualPath && (fs23.existsSync(actualPath) || isSymlink(actualPath))) {
+        if (actualPath && (fs24.existsSync(actualPath) || isSymlink(actualPath))) {
           removeManagedPath(actualPath);
           logger.verbose(`  removed: ${actualPath}`);
           removedCount++;
@@ -21334,7 +21649,7 @@ async function runUninstallCommand(options, logger) {
         scope,
         runtime
       );
-      if (actualPath && (fs23.existsSync(actualPath) || isSymlink(actualPath))) {
+      if (actualPath && (fs24.existsSync(actualPath) || isSymlink(actualPath))) {
         removeManagedPath(actualPath);
         logger.verbose(`  removed: ${actualPath}`);
         removedCount++;
@@ -21368,14 +21683,14 @@ async function runUninstallCommand(options, logger) {
       restoreBackup(backup, logger);
     }
     const manifestPath = path21.join(scopePath, "manifest.json");
-    if (fs23.existsSync(manifestPath)) {
-      fs23.unlinkSync(manifestPath);
+    if (fs24.existsSync(manifestPath)) {
+      fs24.unlinkSync(manifestPath);
       logger.verbose(`  removed manifest: ${manifestPath}`);
     }
     try {
-      const remaining = fs23.readdirSync(scopePath);
+      const remaining = fs24.readdirSync(scopePath);
       if (remaining.length === 0) {
-        fs23.rmdirSync(scopePath);
+        fs24.rmdirSync(scopePath);
         logger.verbose(`  removed empty scope directory: ${scopePath}`);
       }
     } catch {
@@ -21619,9 +21934,9 @@ function resolveAllClaudeRoots(manifest, runtime, claudeConfigDirs) {
       })
     ].map((root) => path21.resolve(root))
   );
-  if (home && fs23.existsSync(home)) {
+  if (home && fs24.existsSync(home)) {
     try {
-      for (const entry of fs23.readdirSync(home, { withFileTypes: true })) {
+      for (const entry of fs24.readdirSync(home, { withFileTypes: true })) {
         if (entry.isDirectory() && entry.name.startsWith(".claude-")) {
           roots.add(path21.resolve(home, entry.name));
         }
@@ -21748,7 +22063,7 @@ function addCompiledGlobPlans(artifacts, pattern, expectedTarget, component) {
   for (const artifactPath of ts(pattern).sort()) {
     let marker = null;
     try {
-      marker = extractProvenanceMarker(fs23.readFileSync(artifactPath, "utf8"));
+      marker = extractProvenanceMarker(fs24.readFileSync(artifactPath, "utf8"));
     } catch {
       continue;
     }
@@ -21768,7 +22083,7 @@ function addCompiledGlobPlans(artifacts, pattern, expectedTarget, component) {
 function addManagedSymlinkChildren(artifacts, directory, runtime, component) {
   let entries;
   try {
-    entries = fs23.readdirSync(directory, { withFileTypes: true });
+    entries = fs24.readdirSync(directory, { withFileTypes: true });
   } catch {
     return;
   }
@@ -21958,12 +22273,8 @@ function resolveKitManagedArtifacts(runtime, scope, selectedTools, manifest, cla
         expectedTarget: "copilot"
       }
     );
-    const hooksSourcePath = resolveHooksSourceFile(
-      runtime.sourceRoot,
-      runtime.config
-    );
-    const hooksSource = hooksSourceLabel(runtime.config);
-    if (fs23.existsSync(hooksSourcePath)) {
+    const hooksSource = hooksSourceLabel(runtime.sourceRoot, runtime.config);
+    if (hooksSourceExists(runtime.sourceRoot, runtime.config)) {
       artifacts.push({
         component: "copilot hooks",
         path: path21.join(copilotPaths.hooks, "tangyr-managed.json"),
@@ -21977,7 +22288,7 @@ function resolveKitManagedArtifacts(runtime, scope, selectedTools, manifest, cla
       runtime.config
     );
     const mcpSource = mcpSourceLabel(runtime.config);
-    if (fs23.existsSync(mcpSourcePath)) {
+    if (fs24.existsSync(mcpSourcePath)) {
       artifacts.push({
         component: "copilot mcp",
         path: copilotPaths.mcpSharedFile,
@@ -22038,12 +22349,8 @@ function resolveKitManagedArtifacts(runtime, scope, selectedTools, manifest, cla
         kind: "direct"
       });
     }
-    const hooksSourcePath = resolveHooksSourceFile(
-      runtime.sourceRoot,
-      runtime.config
-    );
-    const hooksSource = hooksSourceLabel(runtime.config);
-    if (fs23.existsSync(hooksSourcePath)) {
+    const hooksSource = hooksSourceLabel(runtime.sourceRoot, runtime.config);
+    if (hooksSourceExists(runtime.sourceRoot, runtime.config)) {
       artifacts.push({
         component: "codex hooks",
         path: codexPaths.hooksSharedFile,
@@ -22056,7 +22363,7 @@ function resolveKitManagedArtifacts(runtime, scope, selectedTools, manifest, cla
       runtime.config
     );
     const mcpSource = mcpSourceLabel(runtime.config);
-    if (fs23.existsSync(mcpSourcePath)) {
+    if (fs24.existsSync(mcpSourcePath)) {
       artifacts.push({
         component: "codex mcp",
         path: codexPaths.mcpSharedFile,
@@ -22133,7 +22440,7 @@ function resolveKitManagedArtifacts(runtime, scope, selectedTools, manifest, cla
       runtime.config
     );
     const mcpSource = mcpSourceLabel(runtime.config);
-    if (fs23.existsSync(mcpSourcePath)) {
+    if (fs24.existsSync(mcpSourcePath)) {
       artifacts.push({
         component: "opencode config",
         path: opencodePaths.configDoc,
@@ -22214,7 +22521,7 @@ function resolveKitManagedArtifacts(runtime, scope, selectedTools, manifest, cla
       runtime.config
     );
     const mcpSource = mcpSourceLabel(runtime.config);
-    if (fs23.existsSync(mcpSourcePath)) {
+    if (fs24.existsSync(mcpSourcePath)) {
       artifacts.push({
         component: "cursor mcp",
         path: cursorPaths.mcpFile,
@@ -22294,7 +22601,7 @@ function resolveKitManagedArtifacts(runtime, scope, selectedTools, manifest, cla
       runtime.config
     );
     const mcpSource = mcpSourceLabel(runtime.config);
-    if (fs23.existsSync(mcpSourcePath)) {
+    if (fs24.existsSync(mcpSourcePath)) {
       artifacts.push({
         component: "cline mcp",
         path: clinePaths.mcpFile,
@@ -22376,12 +22683,12 @@ function isKitManagedArtifact(artifact, runtime) {
     return artifactClass === "managed-symlink" || artifactClass === "managed-stale" || artifactClass === "managed-compiled";
   }
   if (artifact.kind === "compiled") {
-    if (!fs23.existsSync(artifact.path)) {
+    if (!fs24.existsSync(artifact.path)) {
       return false;
     }
     try {
       const marker = extractProvenanceMarker(
-        fs23.readFileSync(artifact.path, "utf8")
+        fs24.readFileSync(artifact.path, "utf8")
       );
       return marker?.target === artifact.expectedTarget && marker?.source === artifact.expectedSource;
     } catch {
@@ -22389,7 +22696,7 @@ function isKitManagedArtifact(artifact, runtime) {
     }
   }
   if (artifact.kind === "recorded") {
-    return fs23.existsSync(artifact.path) || isSymlink(artifact.path);
+    return fs24.existsSync(artifact.path) || isSymlink(artifact.path);
   }
   if (artifact.kind === "kit-pointer") {
     return isKitPointer(artifact);
@@ -22398,11 +22705,11 @@ function isKitManagedArtifact(artifact, runtime) {
     return isLegacyOperatingGuideCopy(artifact.path);
   }
   if (artifact.kind === "codex-mcp") {
-    if (!fs23.existsSync(artifact.path)) {
+    if (!fs24.existsSync(artifact.path)) {
       return false;
     }
     const section = readManagedTomlSection(
-      fs23.readFileSync(artifact.path, "utf8")
+      fs24.readFileSync(artifact.path, "utf8")
     );
     const marker = section ? extractProvenanceMarker(section) : null;
     return marker?.target === artifact.expectedTarget && marker?.source === artifact.expectedSource;
@@ -22428,16 +22735,16 @@ function isKitManagedArtifact(artifact, runtime) {
   return hasManagedCodexHooks(parsed, artifact.expectedSource);
 }
 function removeManagedCompiledArtifact(artifact, logger) {
-  if (!fs23.existsSync(artifact.path)) {
+  if (!fs24.existsSync(artifact.path)) {
     return false;
   }
   const marker = extractProvenanceMarker(
-    fs23.readFileSync(artifact.path, "utf8")
+    fs24.readFileSync(artifact.path, "utf8")
   );
   if (marker?.target !== artifact.expectedTarget || marker?.source !== artifact.expectedSource) {
     return false;
   }
-  fs23.rmSync(artifact.path, { force: true });
+  fs24.rmSync(artifact.path, { force: true });
   logger.verbose(`  removed ${artifact.component}: ${artifact.path}`);
   return true;
 }
@@ -22508,12 +22815,12 @@ function removeManagedJsonArtifact(artifact, logger) {
   if (!parsed || !hasManagedRootMetadata(parsed, artifact.expectedTarget)) {
     return false;
   }
-  fs23.rmSync(artifact.path, { force: true });
+  fs24.rmSync(artifact.path, { force: true });
   logger.verbose(`  removed ${artifact.component}: ${artifact.path}`);
   return true;
 }
 function removeRecordedArtifact(artifact, logger) {
-  if (!fs23.existsSync(artifact.path) && !isSymlink(artifact.path)) {
+  if (!fs24.existsSync(artifact.path) && !isSymlink(artifact.path)) {
     return false;
   }
   removeManagedPath(artifact.path);
@@ -22521,10 +22828,10 @@ function removeRecordedArtifact(artifact, logger) {
   return true;
 }
 function removeExactManagedFile(artifact, logger) {
-  if (!fs23.existsSync(artifact.path)) {
+  if (!fs24.existsSync(artifact.path)) {
     return false;
   }
-  fs23.rmSync(artifact.path, { force: true });
+  fs24.rmSync(artifact.path, { force: true });
   logger.verbose(`  removed ${artifact.component}: ${artifact.path}`);
   return true;
 }
@@ -22558,10 +22865,10 @@ function removeManagedCodexHooksArtifact(artifact, logger) {
   return true;
 }
 function removeManagedCodexMcpArtifact(artifact, logger) {
-  if (!fs23.existsSync(artifact.path)) {
+  if (!fs24.existsSync(artifact.path)) {
     return false;
   }
-  const content = fs23.readFileSync(artifact.path, "utf8");
+  const content = fs24.readFileSync(artifact.path, "utf8");
   const managedSection = readManagedTomlSection(content);
   if (!managedSection) {
     return false;
@@ -22576,9 +22883,9 @@ function removeManagedCodexMcpArtifact(artifact, logger) {
     codexManagedMcpEnd
   );
   if (cleaned.trim().length === 0) {
-    fs23.rmSync(artifact.path, { force: true });
+    fs24.rmSync(artifact.path, { force: true });
   } else {
-    fs23.writeFileSync(artifact.path, cleaned);
+    fs24.writeFileSync(artifact.path, cleaned);
   }
   logger.verbose(`  removed ${artifact.component}: ${artifact.path}`);
   return true;
@@ -22771,11 +23078,11 @@ function managedArtifactPlanPriority(artifact) {
   return 2;
 }
 function readJsonObject2(filePath) {
-  if (!fs23.existsSync(filePath)) {
+  if (!fs24.existsSync(filePath)) {
     return null;
   }
   try {
-    const parsed = JSON.parse(fs23.readFileSync(filePath, "utf8"));
+    const parsed = JSON.parse(fs24.readFileSync(filePath, "utf8"));
     return isRecord(parsed) ? parsed : null;
   } catch {
     return null;
@@ -22823,22 +23130,22 @@ function removeLegacyClaudeSharedPermission(value) {
   return Object.keys(cleaned).length === 0 ? void 0 : cleaned;
 }
 function isKitPointer(artifact) {
-  if (!artifact.expectedPath || !fs23.existsSync(artifact.path)) {
+  if (!artifact.expectedPath || !fs24.existsSync(artifact.path)) {
     return false;
   }
   try {
-    const recordedPath = fs23.readFileSync(artifact.path, "utf8").trim();
+    const recordedPath = fs24.readFileSync(artifact.path, "utf8").trim();
     return recordedPath.length > 0 && path21.resolve(recordedPath) === path21.resolve(artifact.expectedPath);
   } catch {
     return false;
   }
 }
 function isLegacyOperatingGuideCopy(filePath) {
-  if (!fs23.existsSync(filePath)) {
+  if (!fs24.existsSync(filePath)) {
     return false;
   }
   try {
-    return fs23.readFileSync(filePath, "utf8").startsWith(legacyOperatingGuideSignature);
+    return fs24.readFileSync(filePath, "utf8").startsWith(legacyOperatingGuideSignature);
   } catch {
     return false;
   }
@@ -22860,10 +23167,10 @@ function matchesManagedMetadata(metadata, artifact) {
 }
 function writeJsonOrRemove(filePath, parsed) {
   if (isEmptyJsonValue(parsed)) {
-    fs23.rmSync(filePath, { force: true });
+    fs24.rmSync(filePath, { force: true });
     return;
   }
-  fs23.writeFileSync(filePath, `${JSON.stringify(parsed, null, 2)}
+  fs24.writeFileSync(filePath, `${JSON.stringify(parsed, null, 2)}
 `);
 }
 function isEmptyJsonValue(value) {
@@ -22989,20 +23296,20 @@ function removeDelimitedManagedSection(content, startMarker, endMarker) {
   return `${content.slice(0, start)}${content.slice(removalEnd)}`;
 }
 function restoreBackup(backup, logger) {
-  if (!fs23.existsSync(backup.backupLocation)) {
+  if (!fs24.existsSync(backup.backupLocation)) {
     logger.warn(`  backup not found: ${backup.backupLocation}`);
     return;
   }
   const destDir = path21.dirname(backup.originalPath);
-  fs23.mkdirSync(destDir, { recursive: true });
-  fs23.renameSync(backup.backupLocation, backup.originalPath);
+  fs24.mkdirSync(destDir, { recursive: true });
+  fs24.renameSync(backup.backupLocation, backup.originalPath);
   logger.verbose(
     `  restored: ${backup.backupLocation} \u2192 ${backup.originalPath}`
   );
 }
 function isSymlink(p) {
   try {
-    return fs23.lstatSync(p).isSymbolicLink();
+    return fs24.lstatSync(p).isSymbolicLink();
   } catch {
     return false;
   }
@@ -23076,7 +23383,7 @@ function cleanupClaudeCode(config, sourceRoot, configDir, logger, scope) {
   )) {
     const artifactClass = classifyArtifact(artifact.path, config, sourceRoot);
     if (artifactClass === "managed-symlink" || artifactClass === "managed-compiled" || artifactClass === "managed-stale") {
-      fs24.rmSync(artifact.path, { recursive: true, force: true });
+      fs25.rmSync(artifact.path, { recursive: true, force: true });
       logger.info(`${artifact.component}: removed ${artifact.path}`);
     }
   }
@@ -23289,7 +23596,7 @@ function removeManagedValueByKey2(value, keyName, keyValue) {
 function removeManagedDirectPath(artifactPath, config, sourceRoot, component, logger) {
   const artifactClass = classifyArtifact(artifactPath, config, sourceRoot);
   if (artifactClass === "managed-symlink" || artifactClass === "managed-compiled" || artifactClass === "managed-stale") {
-    fs24.rmSync(artifactPath, { recursive: true, force: true });
+    fs25.rmSync(artifactPath, { recursive: true, force: true });
     logger.info(`${component}: removed ${artifactPath}`);
   }
 }
@@ -23299,30 +23606,30 @@ function removeManagedCompiledFiles(dir, pattern, expectedTarget, logger) {
   }
 }
 function removeManagedCompiledFile(filePath, expectedTarget, logger) {
-  if (!fs24.existsSync(filePath)) {
+  if (!fs25.existsSync(filePath)) {
     return;
   }
-  const marker = extractProvenanceMarker(fs24.readFileSync(filePath, "utf8"));
+  const marker = extractProvenanceMarker(fs25.readFileSync(filePath, "utf8"));
   if (marker?.target === expectedTarget) {
-    fs24.rmSync(filePath, { force: true });
+    fs25.rmSync(filePath, { force: true });
     logger.info(`removed ${filePath}`);
   }
 }
 function removeManagedJsonFile(filePath, markerKey, logger) {
-  if (!fs24.existsSync(filePath)) {
+  if (!fs25.existsSync(filePath)) {
     return;
   }
   const parsed = readJsonObject(filePath);
   if (isRecord(parsed[markerKey])) {
-    fs24.rmSync(filePath, { force: true });
+    fs25.rmSync(filePath, { force: true });
     logger.info(`removed ${filePath}`);
   }
 }
 function removeCodexManagedTomlSection(filePath, logger) {
-  if (!fs24.existsSync(filePath)) {
+  if (!fs25.existsSync(filePath)) {
     return;
   }
-  const content = fs24.readFileSync(filePath, "utf8");
+  const content = fs25.readFileSync(filePath, "utf8");
   const next = removeDelimitedManagedSection2(
     content,
     codexManagedMcpStart2,
@@ -23331,7 +23638,7 @@ function removeCodexManagedTomlSection(filePath, logger) {
   if (next === content) {
     return;
   }
-  fs24.writeFileSync(filePath, next);
+  fs25.writeFileSync(filePath, next);
   logger.info(`mcp: removed managed section from ${filePath}`);
 }
 function removeDelimitedManagedSection2(content, startMarker, endMarker) {
@@ -23403,7 +23710,7 @@ function toVerbosity(value) {
 }
 
 // src/commands/detect.ts
-import fs25 from "fs";
+import fs26 from "fs";
 import os5 from "os";
 import path23 from "path";
 import { spawnSync } from "child_process";
@@ -23444,7 +23751,7 @@ var bundledCursorExecutablePathsByPlatform = {
 };
 function detectTargets(logger, dependencies = {}) {
   const spawnSyncImpl = dependencies.spawnSyncImpl ?? defaultSpawnSync;
-  const pathExists = dependencies.pathExists ?? fs25.existsSync;
+  const pathExists = dependencies.pathExists ?? fs26.existsSync;
   const homeDirectory = dependencies.homeDirectory ?? os5.homedir();
   const platform = dependencies.platform ?? process.platform;
   const locator = platform === "win32" ? "where.exe" : "which";
@@ -23479,8 +23786,8 @@ function detectsCopilot(logger, dependencies = {}) {
   return detectCopilot(logger, dependencies);
 }
 function detectCopilot(logger, dependencies = {}) {
-  const pathExists = dependencies.pathExists ?? fs25.existsSync;
-  const readFile = dependencies.readFile ?? ((filePath) => fs25.readFileSync(filePath, "utf8"));
+  const pathExists = dependencies.pathExists ?? fs26.existsSync;
+  const readFile = dependencies.readFile ?? ((filePath) => fs26.readFileSync(filePath, "utf8"));
   const platform = dependencies.platform ?? process.platform;
   if (detectEditorExtension(
     "Copilot",
@@ -23508,8 +23815,8 @@ function detectCopilot(logger, dependencies = {}) {
 }
 function detectEditorExtension(label, matchesExtension, logger, dependencies = {}) {
   const spawnSyncImpl = dependencies.spawnSyncImpl ?? defaultSpawnSync;
-  const pathExists = dependencies.pathExists ?? fs25.existsSync;
-  const readDirectory = dependencies.readDirectory ?? fs25.readdirSync;
+  const pathExists = dependencies.pathExists ?? fs26.existsSync;
+  const readDirectory = dependencies.readDirectory ?? fs26.readdirSync;
   const homeDirectory = dependencies.homeDirectory ?? os5.homedir();
   const platform = dependencies.platform ?? process.platform;
   const commandCandidates = [
@@ -23620,45 +23927,55 @@ function logDetectionError(attemptedCommand, error, logger) {
 }
 
 // src/commands/doctor.ts
-import fs27 from "fs";
+import fs28 from "fs";
 import path25 from "path";
 
 // src/utils/fs.ts
-import fs26 from "fs";
+import fs27 from "fs";
 import path24 from "path";
 function ensureDir(dirPath) {
-  fs26.mkdirSync(dirPath, { recursive: true });
+  fs27.mkdirSync(dirPath, { recursive: true });
 }
 function createRelativeSymlink(source, destination, type, options) {
   const absoluteSource = path24.resolve(source);
-  const relative = path24.relative(realPathOrInput(path24.dirname(destination)), absoluteSource);
+  const relative = path24.relative(
+    realPathOrInput(path24.dirname(destination)),
+    absoluteSource
+  );
   if (process.platform === "win32" && type === "dir") {
-    fs26.symlinkSync(absoluteSource, destination, "junction");
+    fs27.symlinkSync(absoluteSource, destination, "junction");
     return;
   }
   if (process.platform === "win32" && type === "file") {
     try {
-      fs26.symlinkSync(relative, destination, "file");
+      fs27.symlinkSync(relative, destination, "file");
     } catch (error) {
       if (!hasErrorCode(error, "EPERM")) {
         throw error;
       }
       if (!options?.provenanceMarker) {
-        throw new Error(`${destination}: file symlink unavailable on Windows and no provenance marker was provided.`);
+        throw new Error(
+          `${destination}: file symlink unavailable on Windows and no provenance marker was provided.`
+        );
       }
-      createManagedCopy(source, destination, options.provenanceMarker, options.logger);
+      createManagedCopy(
+        source,
+        destination,
+        options.provenanceMarker,
+        options.logger
+      );
       options.logger?.warn(
         `${destination}: file symlink unavailable on Windows \u2014 using managed copy with provenance metadata (behavioral contract C-09)`
       );
     }
     return;
   }
-  fs26.symlinkSync(relative, destination, type);
+  fs27.symlinkSync(relative, destination, type);
 }
 function createManagedCopy(source, destination, provenanceMarker, _logger) {
   ensureDir(path24.dirname(destination));
-  const content = fs26.readFileSync(source, "utf8");
-  fs26.writeFileSync(destination, `${provenanceMarker}
+  const content = fs27.readFileSync(source, "utf8");
+  fs27.writeFileSync(destination, `${provenanceMarker}
 ${content}`);
 }
 function hasErrorCode(error, expectedCode) {
@@ -23666,7 +23983,7 @@ function hasErrorCode(error, expectedCode) {
 }
 function realPathOrInput(filePath) {
   try {
-    return fs26.realpathSync(filePath);
+    return fs27.realpathSync(filePath);
   } catch {
     return filePath;
   }
@@ -23679,7 +23996,7 @@ function runDoctorCommand(options, logger) {
     import.meta.url
   );
   const findings = [];
-  if (!fs27.existsSync(configPath)) {
+  if (!fs28.existsSync(configPath)) {
     findings.push(`${configPath}: missing`);
   }
   const hooksJsonPath = path25.join(
@@ -23687,9 +24004,9 @@ function runDoctorCommand(options, logger) {
     config.source.hooks,
     "hooks.json"
   );
-  if (fs27.existsSync(hooksJsonPath)) {
+  if (fs28.existsSync(hooksJsonPath)) {
     try {
-      JSON.parse(fs27.readFileSync(hooksJsonPath, "utf8"));
+      JSON.parse(fs28.readFileSync(hooksJsonPath, "utf8"));
     } catch (err) {
       findings.push(
         `hooks/hooks.json: ${err instanceof Error ? err.message : String(err)}`
@@ -23764,9 +24081,9 @@ function checkClaudeCode(options, findings, config, sourceRoot, configDir, logge
         /* @__PURE__ */ new Set([path25.resolve(artifact.path)]),
         config
       )) {
-        fs27.unlinkSync(artifact.path);
+        fs28.unlinkSync(artifact.path);
         ensureDir(path25.dirname(artifact.path));
-        const symlinkType = fs27.statSync(sourcePath).isDirectory() ? "dir" : "file";
+        const symlinkType = fs28.statSync(sourcePath).isDirectory() ? "dir" : "file";
         createRelativeSymlink(sourcePath, artifact.path, symlinkType, {
           logger,
           provenanceMarker: symlinkType === "file" && artifact.sourceKey ? formatProvenanceMarker(
@@ -23779,7 +24096,7 @@ function checkClaudeCode(options, findings, config, sourceRoot, configDir, logge
         logger.info(`${artifact.component}: recreated managed symlink`);
       }
     }
-    if (options.fix && !fs27.existsSync(path25.dirname(artifact.path))) {
+    if (options.fix && !fs28.existsSync(path25.dirname(artifact.path))) {
       ensureDir(path25.dirname(artifact.path));
     }
     checkParentWritablePath(artifact.path, artifact.component, findings);
@@ -23841,24 +24158,24 @@ function checkParentWritablePath(targetPath, label, findings) {
   checkWritablePath(path25.dirname(targetPath), `${label} parent`, findings);
 }
 function checkWritablePath(checkPath, label, findings) {
-  if (!fs27.existsSync(checkPath)) {
+  if (!fs28.existsSync(checkPath)) {
     findings.push(`${label}: path does not exist`);
     return;
   }
   try {
-    fs27.accessSync(checkPath, fs27.constants.R_OK | fs27.constants.W_OK);
+    fs28.accessSync(checkPath, fs28.constants.R_OK | fs28.constants.W_OK);
   } catch {
     findings.push(`${label}: path is not readable and writable`);
   }
 }
 function walkHookScripts(dir) {
-  if (!fs27.existsSync(dir)) {
+  if (!fs28.existsSync(dir)) {
     return [];
   }
-  return fs27.readdirSync(dir).map((entry) => path25.join(dir, entry)).filter((entryPath) => fs27.statSync(entryPath).isFile());
+  return fs28.readdirSync(dir).map((entry) => path25.join(dir, entry)).filter((entryPath) => fs28.statSync(entryPath).isFile());
 }
 function fixManagedHookScriptModes(scriptRoot, sourceRoot, logger) {
-  if (!fs27.existsSync(scriptRoot)) {
+  if (!fs28.existsSync(scriptRoot)) {
     return;
   }
   if (hasSymlinkAncestor(scriptRoot, resolveTargetPath("~/.agents")) || isInside(realPathOrInput2(scriptRoot), realPathOrInput2(sourceRoot))) {
@@ -23868,7 +24185,7 @@ function fixManagedHookScriptModes(scriptRoot, sourceRoot, logger) {
     return;
   }
   for (const scriptPath of walkHookScripts(scriptRoot)) {
-    fs27.chmodSync(scriptPath, 493);
+    fs28.chmodSync(scriptPath, 493);
   }
 }
 function hasSymlinkAncestor(targetPath, stopAt) {
@@ -23885,7 +24202,7 @@ function hasSymlinkAncestor(targetPath, stopAt) {
       ...segments.slice(0, index + 1)
     );
     try {
-      return fs27.lstatSync(candidate).isSymbolicLink();
+      return fs28.lstatSync(candidate).isSymbolicLink();
     } catch {
       return false;
     }
@@ -23897,14 +24214,14 @@ function isInside(childPath, parentPath) {
 }
 function realPathOrInput2(filePath) {
   try {
-    return fs27.realpathSync(filePath);
+    return fs28.realpathSync(filePath);
   } catch {
     return filePath;
   }
 }
 
 // src/commands/init.ts
-import fs28 from "fs";
+import fs29 from "fs";
 import path26 from "path";
 var import_yaml7 = __toESM(require_dist(), 1);
 async function runInitCommand(_options, logger) {
@@ -23920,16 +24237,18 @@ async function runInitCommand(_options, logger) {
     "rules",
     "hooks"
   ].filter(
-    (relativePath) => fs28.existsSync(path26.join(sourceRoot, relativePath))
+    (relativePath) => fs29.existsSync(path26.join(sourceRoot, relativePath))
   ).length;
   const detectedTargets = detectTargets(logger);
   const enabledTargets = await dist_default4({
     message: `Detected ${componentCount} source components. Select targets`,
-    choices: Object.entries(detectedTargets).map(([name, detected]) => ({
-      name,
-      value: name,
-      checked: detected
-    }))
+    choices: Object.entries(detectedTargets).map(
+      ([name, detected]) => ({
+        name,
+        value: name,
+        checked: detected
+      })
+    )
   });
   const onConflict = await dist_default8({
     message: "Conflict policy",
@@ -23939,7 +24258,7 @@ async function runInitCommand(_options, logger) {
     }))
   });
   const configPath = path26.join(sourceRoot, "tangyr.config.yaml");
-  if (fs28.existsSync(configPath)) {
+  if (fs29.existsSync(configPath)) {
     const overwrite = await dist_default5({
       message: `${configPath} exists. Overwrite?`,
       default: false
@@ -23949,7 +24268,7 @@ async function runInitCommand(_options, logger) {
       return;
     }
   }
-  fs28.writeFileSync(
+  fs29.writeFileSync(
     configPath,
     (0, import_yaml7.stringify)({
       schema: 1,
@@ -23992,11 +24311,11 @@ function toConflictPolicy2(value) {
 }
 
 // src/commands/install.ts
-import fs37 from "fs";
+import fs38 from "fs";
 import path37 from "path";
 
 // src/core/channel-state.ts
-import fs29 from "fs";
+import fs30 from "fs";
 import path27 from "path";
 var CHANNEL_STATE_FILENAME = ".tangyr-channels.json";
 function stateFilePath(cacheRoot) {
@@ -24009,7 +24328,7 @@ function readState(cacheRoot) {
   const filePath = stateFilePath(cacheRoot);
   let raw;
   try {
-    raw = fs29.readFileSync(filePath, "utf8");
+    raw = fs30.readFileSync(filePath, "utf8");
   } catch (err) {
     if (err.code === "ENOENT") {
       return { state: {} };
@@ -24056,13 +24375,13 @@ function writeChannelSequence(params) {
     [key]: { sequence, version, seenAt: now.toISOString() }
   };
   const filePath = stateFilePath(cacheRoot);
-  fs29.mkdirSync(path27.dirname(filePath), { recursive: true, mode: 448 });
+  fs30.mkdirSync(path27.dirname(filePath), { recursive: true, mode: 448 });
   const tempPath = `${filePath}.${process.pid}.tmp`;
-  fs29.writeFileSync(tempPath, `${JSON.stringify(state, null, 2)}
+  fs30.writeFileSync(tempPath, `${JSON.stringify(state, null, 2)}
 `, {
     mode: 384
   });
-  fs29.renameSync(tempPath, filePath);
+  fs30.renameSync(tempPath, filePath);
 }
 function assertChannelNotRolledBack(params) {
   const { originUrl, kit, channel, seen, seenVersion, incoming } = params;
@@ -24078,7 +24397,7 @@ var CHANNEL_POINTER_TYPE = "tangyr.channel-pointer.v1";
 var DEFAULT_CHANNEL = "stable";
 
 // src/core/materialize.ts
-import fs30 from "fs";
+import fs31 from "fs";
 import path28 from "path";
 
 // src/core/integrity.ts
@@ -24489,10 +24808,10 @@ function verifyBundleFileHashes(bundle) {
 function writeStagedFiles(stagingDir, decoded) {
   for (const [rawPath, bytes] of decoded) {
     const target = sanitizeBundleFilePath(rawPath, stagingDir);
-    fs30.mkdirSync(path28.dirname(target), { recursive: true, mode: 448 });
+    fs31.mkdirSync(path28.dirname(target), { recursive: true, mode: 448 });
     let existingStat;
     try {
-      existingStat = fs30.lstatSync(target);
+      existingStat = fs31.lstatSync(target);
     } catch (error) {
       if (error.code !== "ENOENT") {
         throw error;
@@ -24503,7 +24822,7 @@ function writeStagedFiles(stagingDir, decoded) {
         `Refusing to write "${rawPath}" \u2014 a symbolic link already exists at the target path.`
       );
     }
-    fs30.writeFileSync(target, bytes, { mode: 384, flag: "wx" });
+    fs31.writeFileSync(target, bytes, { mode: 384, flag: "wx" });
   }
 }
 function verifyWarmCacheEntry(entryDir, reference, keys, now) {
@@ -24559,14 +24878,14 @@ async function materializeRemoteKit(params) {
     writeStagedFiles(stagingDir, decoded);
     writeBundleDocument(stagingDir, bundle);
     writeCompletionMarker(stagingDir, reference);
-    if (replace && fs30.existsSync(entryDir)) {
-      fs30.rmSync(entryDir, { recursive: true, force: true });
+    if (replace && fs31.existsSync(entryDir)) {
+      fs31.rmSync(entryDir, { recursive: true, force: true });
     }
     publishCacheEntry(stagingDir, entryDir);
     return entryDir;
   } catch (error) {
     if (stagingDir !== void 0) {
-      fs30.rmSync(stagingDir, { recursive: true, force: true });
+      fs31.rmSync(stagingDir, { recursive: true, force: true });
     }
     throw error;
   }
@@ -24902,65 +25221,13 @@ function sleep(ms2) {
 // src/adapters/codex.ts
 var TOML3 = __toESM(require_toml(), 1);
 import crypto5 from "crypto";
-import fs32 from "fs";
+import fs33 from "fs";
 import path31 from "path";
 
 // src/compiler/agents.ts
 var TOML = __toESM(require_toml(), 1);
 var import_yaml8 = __toESM(require_dist(), 1);
 import path29 from "path";
-
-// src/compiler/loss-report.ts
-function createLossReport() {
-  return {
-    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    targets: {},
-    summary: {},
-    informational: []
-  };
-}
-function addInformational(report, target, component, source, severity, detail) {
-  report.informational.push({ target, component, source, severity, detail });
-}
-function addLoss(report, target, component, loss) {
-  const targetReport = report.targets[target] ?? {};
-  const componentReport = targetReport[component] ?? [];
-  componentReport.push(loss);
-  targetReport[component] = componentReport;
-  report.targets[target] = targetReport;
-  const targetSummary = report.summary[target] ?? {
-    info: 0,
-    warning: 0,
-    error: 0
-  };
-  for (const field of loss.fields) {
-    targetSummary[field.severity] += 1;
-  }
-  report.summary[target] = targetSummary;
-}
-var lossSeverityByEntryType = {
-  "command-as-skill": "info",
-  "rule-as-instruction": "info",
-  "rule-mode-downgrade": "warning",
-  "rule-path-scoping": "warning",
-  "hook-event-drop": "warning",
-  "hook-as-plugin": "error",
-  "instructions-shim": "info",
-  "permission-coarsening": "error",
-  "provider-not-representable": "error",
-  "provider-wire-protocol": "error",
-  "model-not-representable": "error",
-  "persona-not-representable": "error",
-  "settings-not-representable": "warning"
-};
-function resolveLossSeverity(kind, name, action, explicitSeverity) {
-  if (explicitSeverity) {
-    return explicitSeverity;
-  }
-  return lossSeverityByEntryType[action];
-}
-
-// src/compiler/agents.ts
 var writeCapabilityClasses = /* @__PURE__ */ new Set(["filesystem-write", "shell-execution"]);
 var copilotToolAliasesByClass = {
   delegation: "agent",
@@ -25380,12 +25647,37 @@ function compileCursorHooks(sourceHooksJson, mappings, lossReport, sourceLabel)
   let dropped = 0;
   for (const [sourceEvent, payload] of Object.entries(sourceHooks)) {
     const mapping = normalizeHookEventRule(
-      targetMapping.source_to_target[sourceEvent]
+      targetMapping.source_to_target[sourceEvent],
+      "cursor",
+      sourceEvent
     );
     if (mapping.status === "mapped" && mapping.target_event) {
-      const sourceCommand = isRecord(payload) && typeof payload.command === "string" ? payload.command : Array.isArray(payload) && isRecord(payload[0]) && typeof payload[0].command === "string" ? payload[0].command : "";
-      hooks[mapping.target_event] = { command: sourceCommand };
+      const extracted = extractHookCommand(payload);
+      if (!extracted.command) {
+        droppedEvents.push(sourceEvent);
+        addHookLoss(
+          lossReport,
+          "cursor",
+          sourceEvent,
+          sourceLabel,
+          "error",
+          `${sourceEvent}: no command could be read from the source entry, so nothing was written for Cursor. To fix: check that the hook declares a command \u2014 'tangyr validate' names the file and the field.`
+        );
+        dropped += 1;
+        continue;
+      }
+      hooks[mapping.target_event] = { command: extracted.command };
       translated += 1;
+      if (extracted.matcher) {
+        addInformational(
+          lossReport,
+          "cursor",
+          "hooks",
+          sourceLabel,
+          "warning",
+          `${sourceEvent}: the source scopes this hook to '${extracted.matcher}', and Cursor's hook entry carries no matcher. It will run for every tool call on this event, not only the matched ones.`
+        );
+      }
       continue;
     }
     droppedEvents.push(sourceEvent);
@@ -25504,7 +25796,9 @@ function compileCopilotHooks(sourceHooksJson, mappings, lossReport, sourceLabel)
   }
   for (const [sourceEvent, payload] of Object.entries(sourceHooks)) {
     const mapping = normalizeHookEventRule(
-      targetMapping.source_to_target[sourceEvent]
+      targetMapping.source_to_target[sourceEvent],
+      "copilot",
+      sourceEvent
     );
     if (mapping.status === "mapped" && mapping.target_event) {
       hooks[mapping.target_event] = payload;
@@ -25539,11 +25833,35 @@ function compileCopilotHooks(sourceHooksJson, mappings, lossReport, sourceLabel)
   }
   return { payload: { hooks }, translated, dropped, droppedEvents };
 }
-function normalizeHookEventRule(value) {
+function extractHookCommand(payload) {
+  const entries = Array.isArray(payload) ? payload : [payload];
+  for (const entry of entries) {
+    if (!isRecord(entry)) continue;
+    const matcher = typeof entry.matcher === "string" && entry.matcher ? { matcher: entry.matcher } : {};
+    if (typeof entry.command === "string" && entry.command) {
+      return { command: entry.command, ...matcher };
+    }
+    const inner = Array.isArray(entry.hooks) ? entry.hooks : [];
+    for (const hook of inner) {
+      if (isRecord(hook) && typeof hook.command === "string" && hook.command) {
+        return { command: hook.command, ...matcher };
+      }
+    }
+  }
+  return { command: "" };
+}
+function normalizeHookEventRule(value, target, sourceEvent) {
   if (typeof value === "string") {
     return { status: "mapped", target_event: value };
   }
-  return value ?? { status: "drop" };
+  if (value) {
+    return value;
+  }
+  return {
+    status: "unmapped",
+    severity: "warning",
+    reason: `mappings/hook-events.yaml has no entry for '${sourceEvent}' under target '${target}', so it was dropped without a decision behind it. To fix: add '${sourceEvent}' to that file \u2014 to source_events, and to every target's source_to_target with either a target_event or a stated reason for dropping it.`
+  };
 }
 function compileCodexHooks(sourceHooksJson, mappings, lossReport, sourceLabel) {
   const targetMapping = mappings.hookEvents.targets.codex;
@@ -25557,7 +25875,9 @@ function compileCodexHooks(sourceHooksJson, mappings, lossReport, sourceLabel) {
   let dropped = 0;
   for (const [sourceEvent, payload] of Object.entries(sourceHooks)) {
     const mapping = normalizeHookEventRule(
-      targetMapping.source_to_target[sourceEvent]
+      targetMapping.source_to_target[sourceEvent],
+      "codex",
+      sourceEvent
     );
     if (mapping.status === "mapped" && mapping.target_event) {
       hooks[mapping.target_event] = markCodexManaged(payload, sourceLabel);
@@ -25890,7 +26210,7 @@ function compileOpenCodeMcp(sourceMcpJson, lossReport, sourceLabel) {
 // src/compiler/rules.ts
 import path30 from "path";
 var import_yaml9 = __toESM(require_dist(), 1);
-import fs31 from "fs";
+import fs32 from "fs";
 function compileRules(sourceRulesDir, target, _mappings, lossReport) {
   if (target === "copilot") {
     addLoss(lossReport, "copilot", "rules", {
@@ -25960,7 +26280,7 @@ ${parsed.body.trim()}`);
   return { agentsAppendix: appendixParts.join("\n\n"), dotRulesFiles };
 }
 function parseRule(ruleFile) {
-  const content = fs31.readFileSync(ruleFile, "utf8");
+  const content = fs32.readFileSync(ruleFile, "utf8");
   if (!content.startsWith("---\n")) {
     return { mode: "guidance", body: content };
   }
@@ -26011,7 +26331,7 @@ ${parsed.body.trim()}`);
 function compileCursorRules(sourceRulesDir, _lossReport) {
   const dotRulesFiles = [];
   for (const ruleFile of ts(path30.join(sourceRulesDir, "*.md")).sort()) {
-    const content = fs31.readFileSync(ruleFile, "utf8");
+    const content = fs32.readFileSync(ruleFile, "utf8");
     const name = path30.basename(ruleFile, ".md");
     let frontmatterData = {};
     let body = content;
@@ -26058,7 +26378,7 @@ ${body}`;
 function compileClineRules(sourceRulesDir, lossReport) {
   const dotRulesFiles = [];
   for (const ruleFile of ts(path30.join(sourceRulesDir, "*.md")).sort()) {
-    const content = fs31.readFileSync(ruleFile, "utf8");
+    const content = fs32.readFileSync(ruleFile, "utf8");
     const name = path30.basename(ruleFile, ".md");
     let frontmatterData = {};
     let body = content;
@@ -26283,7 +26603,7 @@ function buildProviderTomlSection(config, sourceRoot, mappings, scope, lossRepor
   const cp = mappings.modelTiers.custom_provider;
   if (!cp) return "";
   const agentsDir = path31.join(sourceRoot, config.source.agents);
-  if (!fs32.existsSync(agentsDir)) return "";
+  if (!fs33.existsSync(agentsDir)) return "";
   const agentFiles = ts(path31.join(agentsDir, "*.md")).sort();
   const hasProviderAgent = agentFiles.some((agentFile) => {
     const { data } = parseMarkdownFrontmatter(agentFile);
@@ -26379,7 +26699,7 @@ function syncRules(config, sourceRoot, paths, rules, options, logger, manifest,
 function syncInstructions(config, sourceRoot, paths, agentsAppendix, options, logger, manifest, scopePath) {
   const source = path31.join(sourceRoot, config.source.instructions);
   const destination = resolveTargetPath(paths.instructions);
-  const composed = `${fs32.readFileSync(source, "utf8").trim()}
+  const composed = `${fs33.readFileSync(source, "utf8").trim()}
 
 --- tangyr managed rules ---
 ${agentsAppendix}`.trim();
@@ -26414,7 +26734,7 @@ ${composed}
 function syncSkills(config, sourceRoot, paths, options, logger, manifest, scopePath) {
   const source = path31.resolve(sourceRoot, config.source.skills);
   const destination = resolveTargetPath(paths.skills);
-  if (!fs32.existsSync(source)) {
+  if (!fs33.existsSync(source)) {
     return skippedMissingSource("skills", source);
   }
   if (options.dryRun) {
@@ -26430,12 +26750,12 @@ function syncSkills(config, sourceRoot, paths, options, logger, manifest, scopeP
     };
   }
   if (artifactClass === "managed-stale" && isOurStaleSymlink(destination, /* @__PURE__ */ new Set([destination]), config)) {
-    fs32.unlinkSync(destination);
+    fs33.unlinkSync(destination);
     logger.verbose(`Skills: created skills path ${destination}`);
   } else if (artifactClass === "unmanaged-conflict" && !handleConflict(destination, config, options, logger, manifest, scopePath)) {
     return { component: "skills", status: "conflict", path: destination };
   } else if (artifactClass === "managed-symlink") {
-    fs32.unlinkSync(destination);
+    fs33.unlinkSync(destination);
   }
   ensureDir(path31.dirname(destination));
   createRelativeSymlink(source, destination, "dir");
@@ -26444,7 +26764,7 @@ function syncSkills(config, sourceRoot, paths, options, logger, manifest, scopeP
 }
 function syncAgents(config, sourceRoot, paths, mappings, extensions, options, lossReport, logger, manifest, scopePath) {
   const sourceAgentsRoot = path31.join(sourceRoot, config.source.agents);
-  if (!fs32.existsSync(sourceAgentsRoot)) {
+  if (!fs33.existsSync(sourceAgentsRoot)) {
     return [skippedMissingSource("agents", sourceAgentsRoot)];
   }
   const sourceAgents = ts(path31.join(sourceAgentsRoot, "*.md")).sort();
@@ -26486,14 +26806,16 @@ function syncHooks(config, sourceRoot, paths, mappings, options, lossReport, log
     logger.warn(message);
     return { component: "hooks", status: "skipped", path: message };
   }
-  const source = resolveHooksSourceFile(sourceRoot, config);
-  const sourceLabel = hooksSourceLabel(config);
-  if (!fs32.existsSync(source)) {
-    return skippedMissingSource("hooks", source);
+  const hooksSource = loadKitHooksSource(sourceRoot, config);
+  if (!hooksSource) {
+    return skippedMissingSource(
+      "hooks",
+      resolveHooksSourceDir(sourceRoot, config)
+    );
   }
-  const sourceHooksJson = JSON.parse(fs32.readFileSync(source, "utf8"));
+  const { path: source, label: sourceLabel } = hooksSource;
   const compiled = compileHooks(
-    sourceHooksJson,
+    hooksSource.hooks,
     "codex",
     mappings,
     lossReport,
@@ -26513,7 +26835,7 @@ function syncHooks(config, sourceRoot, paths, mappings, options, lossReport, log
     destination,
     hostHooks,
     stringifyJson2,
-    !fs32.existsSync(destination),
+    !fs33.existsSync(destination),
     logger
   );
   return {
@@ -26526,7 +26848,7 @@ function syncMcp(config, sourceRoot, paths, options, lossReport, logger, provide
   const source = resolveMcpSourceFile(sourceRoot, config);
   const sourceLabel = mcpSourceLabel(config);
   const destination = resolveTargetPath(paths.mcp_shared_file);
-  if (!fs32.existsSync(source)) {
+  if (!fs33.existsSync(source)) {
     if (providerToml && !options.dryRun) {
       const changed2 = writeTomlManagedSection(
         destination,
@@ -26541,7 +26863,7 @@ function syncMcp(config, sourceRoot, paths, options, lossReport, logger, provide
     }
     return skippedMissingSource("mcp", source);
   }
-  const sourceMcpJson = JSON.parse(fs32.readFileSync(source, "utf8"));
+  const sourceMcpJson = JSON.parse(fs33.readFileSync(source, "utf8"));
   const compiled = compileMcp(sourceMcpJson, "codex", lossReport, sourceLabel);
   const managedContent = providerToml ? `${compiled.trimEnd()}${providerToml}` : compiled;
   if (options.dryRun) {
@@ -26564,11 +26886,11 @@ function writeCompiledArtifact(component, destination, content, expectedHash, co
     return { component, status: "conflict", path: destination };
   }
   ensureDir(path31.dirname(destination));
-  fs32.writeFileSync(destination, content);
+  fs33.writeFileSync(destination, content);
   return { component, status: "success", path: destination };
 }
 function writeTomlManagedSection(destination, managedContent, logger) {
-  const current = fs32.existsSync(destination) ? fs32.readFileSync(destination, "utf8") : "";
+  const current = fs33.existsSync(destination) ? fs33.readFileSync(destination, "utf8") : "";
   const isFirstWrite = current.length > 0 && !current.includes(managedMcpStart);
   if (isFirstWrite) {
     logger.warn(
@@ -26585,7 +26907,7 @@ ${managedMcpEnd}
     return false;
   }
   ensureDir(path31.dirname(destination));
-  fs32.writeFileSync(destination, next.trimStart());
+  fs33.writeFileSync(destination, next.trimStart());
   return true;
 }
 function removeManagedTomlSection(content) {
@@ -26612,16 +26934,16 @@ function handleConflict(destination, config, options, logger, manifest, scopePat
       backupFile(destination, manifest);
       writeManifest(scopePath, manifest);
     } else {
-      fs32.renameSync(destination, `${destination}.bak.${Date.now()}`);
+      fs33.renameSync(destination, `${destination}.bak.${Date.now()}`);
     }
     return true;
   }
-  fs32.rmSync(destination, { recursive: true, force: true });
+  fs33.rmSync(destination, { recursive: true, force: true });
   return true;
 }
 function isCompiledCurrent(destination, expectedContent, expectedHash) {
   try {
-    const current = fs32.readFileSync(destination, "utf8");
+    const current = fs33.readFileSync(destination, "utf8");
     const marker = extractProvenanceMarker(current);
     return expectedHash ? marker?.hash === expectedHash && marker.target === "codex" && current === expectedContent : current === expectedContent;
   } catch {
@@ -26640,16 +26962,16 @@ function shouldSkipComponent(options, component) {
 }
 function isSymlinkTo(linkPath, source) {
   try {
-    return fs32.realpathSync(linkPath) === fs32.realpathSync(source);
+    return fs33.realpathSync(linkPath) === fs33.realpathSync(source);
   } catch {
     return false;
   }
 }
 function readJsonObject3(filePath) {
-  if (!fs32.existsSync(filePath)) {
+  if (!fs33.existsSync(filePath)) {
     return {};
   }
-  const parsed = JSON.parse(fs32.readFileSync(filePath, "utf8"));
+  const parsed = JSON.parse(fs33.readFileSync(filePath, "utf8"));
   return isRecord4(parsed) ? parsed : {};
 }
 function stringifyJson2(value) {
@@ -26665,7 +26987,7 @@ function hashString(value) {
 
 // src/adapters/copilot.ts
 import crypto6 from "crypto";
-import fs33 from "fs";
+import fs34 from "fs";
 import path33 from "path";
 
 // src/compiler/commands.ts
@@ -26850,7 +27172,7 @@ function syncCopilot(config, sourceRoot, mappings, extensions, options, lossRepo
 function syncProviderLoss(config, sourceRoot, mappings, lossReport) {
   if (!mappings.modelTiers.custom_provider) return;
   const agentsDir = path33.join(sourceRoot, config.source.agents);
-  if (!fs33.existsSync(agentsDir)) return;
+  if (!fs34.existsSync(agentsDir)) return;
   for (const agentFile of ts(path33.join(agentsDir, "*.md")).sort()) {
     const { data } = parseMarkdownFrontmatter(agentFile);
     const hasProvider = typeof data.provider === "string" || typeof data.provider === "object" && data.provider !== null && Object.keys(data.provider).length > 0;
@@ -26881,10 +27203,10 @@ function syncCopilotInstructions(config, sourceRoot, options, lossReport, logger
     return [{ component: "instructions", status: "skipped", path: message }];
   }
   const source = path33.resolve(sourceRoot, config.source.instructions);
-  if (!fs33.existsSync(source)) {
+  if (!fs34.existsSync(source)) {
     return [skippedMissingSource2("instructions", source)];
   }
-  const rawContent = fs33.readFileSync(source, "utf8");
+  const rawContent = fs34.readFileSync(source, "utf8");
   const contentHash = hashString2(rawContent);
   const marker = formatProvenanceMarker(
     "markdown",
@@ -26951,7 +27273,7 @@ function writeInstructionsFile(component, destination, content, contentHash, con
     return { component, status: "conflict", path: destination };
   }
   ensureDir(path33.dirname(destination));
-  fs33.writeFileSync(destination, content);
+  fs34.writeFileSync(destination, content);
   return { component, status: "success", path: destination };
 }
 function hashString2(value) {
@@ -26960,7 +27282,7 @@ function hashString2(value) {
 function syncSkills2(config, sourceRoot, paths, options, logger, manifest, scopePath) {
   const source = path33.resolve(sourceRoot, config.source.skills);
   const destination = resolveTargetPath(paths.skills);
-  if (!fs33.existsSync(source)) {
+  if (!fs34.existsSync(source)) {
     return skippedMissingSource2("skills", source);
   }
   if (options.dryRun) {
@@ -26976,11 +27298,11 @@ function syncSkills2(config, sourceRoot, paths, options, logger, manifest, scope
     };
   }
   if (artifactClass === "managed-stale" && isOurStaleSymlink(destination, /* @__PURE__ */ new Set([destination]), config)) {
-    fs33.unlinkSync(destination);
+    fs34.unlinkSync(destination);
   } else if (artifactClass === "unmanaged-conflict" && !handleConflict2(destination, config, options, logger, manifest, scopePath)) {
     return { component: "skills", status: "conflict", path: destination };
   } else if (artifactClass === "managed-symlink") {
-    fs33.unlinkSync(destination);
+    fs34.unlinkSync(destination);
   }
   ensureDir(path33.dirname(destination));
   createRelativeSymlink(source, destination, "dir");
@@ -26988,7 +27310,7 @@ function syncSkills2(config, sourceRoot, paths, options, logger, manifest, scope
 }
 function syncAgents2(config, sourceRoot, paths, mappings, extensions, options, lossReport, logger, manifest, scopePath) {
   const sourceAgentsRoot = path33.join(sourceRoot, config.source.agents);
-  if (!fs33.existsSync(sourceAgentsRoot)) {
+  if (!fs34.existsSync(sourceAgentsRoot)) {
     return [skippedMissingSource2("agents", sourceAgentsRoot)];
   }
   const sourceAgents = ts(path33.join(sourceAgentsRoot, "*.md")).sort();
@@ -27025,7 +27347,7 @@ function syncAgents2(config, sourceRoot, paths, mappings, extensions, options, l
 }
 function syncCommands(config, sourceRoot, paths, options, logger, manifest, scopePath) {
   const sourceCommandsRoot = path33.join(sourceRoot, config.source.commands);
-  if (!fs33.existsSync(sourceCommandsRoot)) {
+  if (!fs34.existsSync(sourceCommandsRoot)) {
     return [skippedMissingSource2("commands", sourceCommandsRoot)];
   }
   const sourceCommands = ts(path33.join(sourceCommandsRoot, "*.md")).sort();
@@ -27057,18 +27379,20 @@ function syncCommands(config, sourceRoot, paths, options, logger, manifest, scop
   });
 }
 function syncHooks2(config, sourceRoot, paths, mappings, options, lossReport, logger) {
-  const source = resolveHooksSourceFile(sourceRoot, config);
-  const sourceLabel = hooksSourceLabel(config);
   const destination = path33.join(
     resolveTargetPath(paths.hooks),
     "tangyr-managed.json"
   );
-  if (!fs33.existsSync(source)) {
-    return skippedMissingSource2("hooks", source);
+  const hooksSource = loadKitHooksSource(sourceRoot, config);
+  if (!hooksSource) {
+    return skippedMissingSource2(
+      "hooks",
+      resolveHooksSourceDir(sourceRoot, config)
+    );
   }
-  const sourceHooksJson = JSON.parse(fs33.readFileSync(source, "utf8"));
+  const { path: source, label: sourceLabel, hash: sourceHash } = hooksSource;
   const compiled = compileHooks(
-    sourceHooksJson,
+    hooksSource.hooks,
     "copilot",
     mappings,
     lossReport,
@@ -27077,7 +27401,7 @@ function syncHooks2(config, sourceRoot, paths, mappings, options, lossReport, lo
   const payload = {
     _tangyr: {
       source: sourceLabel,
-      hash: computeSourceHash(source),
+      hash: sourceHash,
       target: "copilot"
     },
     ...compiled.payload
@@ -27092,7 +27416,7 @@ function syncHooks2(config, sourceRoot, paths, mappings, options, lossReport, lo
     "hooks",
     destination,
     serialized,
-    computeSourceHash(source),
+    sourceHash,
     config,
     sourceRoot,
     options,
@@ -27103,10 +27427,10 @@ function syncMcp2(config, sourceRoot, paths, options, lossReport, logger) {
   const source = resolveMcpSourceFile(sourceRoot, config);
   const sourceLabel = mcpSourceLabel(config);
   const destination = resolveTargetPath(paths.mcp_shared_file);
-  if (!fs33.existsSync(source)) {
+  if (!fs34.existsSync(source)) {
     return skippedMissingSource2("mcp", source);
   }
-  const sourceMcpJson = JSON.parse(fs33.readFileSync(source, "utf8"));
+  const sourceMcpJson = JSON.parse(fs34.readFileSync(source, "utf8"));
   const compiled = compileMcp(
     sourceMcpJson,
     "copilot",
@@ -27137,12 +27461,12 @@ function writeCompiledArtifact2(component, destination, content, expectedHash, c
     return { component, status: "conflict", path: destination };
   }
   ensureDir(path33.dirname(destination));
-  fs33.writeFileSync(destination, content);
+  fs34.writeFileSync(destination, content);
   return { component, status: "success", path: destination };
 }
 function isCompiledCurrent2(destination, expectedContent, expectedHash) {
   try {
-    const current = fs33.readFileSync(destination, "utf8");
+    const current = fs34.readFileSync(destination, "utf8");
     const marker = extractProvenanceMarker(current);
     return expectedHash ? marker?.hash === expectedHash && marker.target === "copilot" && current === expectedContent : current === expectedContent;
   } catch {
@@ -27165,11 +27489,11 @@ function handleConflict2(destination, config, options, logger, manifest, scopePa
       backupFile(destination, manifest);
       writeManifest(scopePath, manifest);
     } else {
-      fs33.renameSync(destination, `${destination}.bak.${Date.now()}`);
+      fs34.renameSync(destination, `${destination}.bak.${Date.now()}`);
     }
     return true;
   }
-  fs33.rmSync(destination, { recursive: true, force: true });
+  fs34.rmSync(destination, { recursive: true, force: true });
   return true;
 }
 function shouldSkipComponent2(options, component) {
@@ -27193,14 +27517,14 @@ function cleanupLegacyAgents(paths, options, logger) {
       outcomes.push({ component: "agents", status: "dry-run", path: filePath });
       continue;
     }
-    fs33.rmSync(filePath, { force: true });
+    fs34.rmSync(filePath, { force: true });
     outcomes.push({ component: "agents", status: "success", path: filePath });
   }
   return outcomes;
 }
 function isCopilotManagedCompiledFile(filePath) {
   try {
-    return extractProvenanceMarker(fs33.readFileSync(filePath, "utf8"))?.target === "copilot";
+    return extractProvenanceMarker(fs34.readFileSync(filePath, "utf8"))?.target === "copilot";
   } catch {
     return false;
   }
@@ -27214,7 +27538,7 @@ function skippedMissingSource2(component, source) {
 }
 function isSymlinkTo2(linkPath, source) {
   try {
-    return fs33.realpathSync(linkPath) === fs33.realpathSync(source);
+    return fs34.realpathSync(linkPath) === fs34.realpathSync(source);
   } catch {
     return false;
   }
@@ -27222,7 +27546,7 @@ function isSymlinkTo2(linkPath, source) {
 
 // src/adapters/cursor.ts
 import crypto7 from "crypto";
-import fs34 from "fs";
+import fs35 from "fs";
 import path34 from "path";
 function syncCursor(config, sourceRoot, mappings, extensions, options, lossReport, logger, manifest, scopePath) {
   const scope = options.scope ?? "global";
@@ -27376,7 +27700,7 @@ function syncCursor(config, sourceRoot, mappings, extensions, options, lossRepor
 function syncInstructions2(config, sourceRoot, paths, options, lossReport, logger, manifest, scopePath) {
   const source = path34.join(sourceRoot, config.source.instructions);
   const destination = resolveTargetPath(paths.instructions);
-  const baseContent = fs34.existsSync(source) ? fs34.readFileSync(source, "utf8").trim() : "";
+  const baseContent = fs35.existsSync(source) ? fs35.readFileSync(source, "utf8").trim() : "";
   const personaContent = extractPrimaryPersonaContent(
     config,
     sourceRoot,
@@ -27415,7 +27739,7 @@ ${composed}
 }
 function extractPrimaryPersonaContent(config, sourceRoot, lossReport) {
   const agentsDir = path34.join(sourceRoot, config.source.agents);
-  if (!fs34.existsSync(agentsDir)) {
+  if (!fs35.existsSync(agentsDir)) {
     return null;
   }
   const agentFiles = ts(path34.join(agentsDir, "*.md")).sort();
@@ -27459,7 +27783,7 @@ function extractPrimaryPersonaContent(config, sourceRoot, lossReport) {
 }
 function syncAgents3(config, sourceRoot, paths, mappings, extensions, options, lossReport, logger, manifest, scopePath) {
   const sourceAgentsRoot = path34.join(sourceRoot, config.source.agents);
-  if (!fs34.existsSync(sourceAgentsRoot)) {
+  if (!fs35.existsSync(sourceAgentsRoot)) {
     return [skippedMissingSource3("agents", sourceAgentsRoot)];
   }
   const sourceAgents = ts(path34.join(sourceAgentsRoot, "*.md")).sort();
@@ -27509,7 +27833,7 @@ function syncAgents3(config, sourceRoot, paths, mappings, extensions, options, l
 }
 function syncRules2(config, sourceRoot, paths, mappings, options, lossReport, logger, manifest, scopePath) {
   const sourceRulesDir = path34.join(sourceRoot, config.source.rules);
-  if (!fs34.existsSync(sourceRulesDir)) {
+  if (!fs35.existsSync(sourceRulesDir)) {
     return [skippedMissingSource3("rules", sourceRulesDir)];
   }
   const compiled = compileRules(sourceRulesDir, "cursor", mappings, lossReport);
@@ -27540,7 +27864,7 @@ function syncRules2(config, sourceRoot, paths, mappings, options, lossReport, lo
 }
 function syncCommands2(config, sourceRoot, paths, options, logger, manifest, scopePath) {
   const sourceCommandsRoot = path34.join(sourceRoot, config.source.commands);
-  if (!fs34.existsSync(sourceCommandsRoot)) {
+  if (!fs35.existsSync(sourceCommandsRoot)) {
     return [skippedMissingSource3("commands", sourceCommandsRoot)];
   }
   const sourceCommands = ts(path34.join(sourceCommandsRoot, "*.md")).sort();
@@ -27548,7 +27872,7 @@ function syncCommands2(config, sourceRoot, paths, options, logger, manifest, sco
   return sourceCommands.map((commandFile) => {
     const baseName = path34.basename(commandFile, ".md");
     const destination = path34.join(skillsRoot, baseName, "SKILL.md");
-    const commandContent = fs34.readFileSync(commandFile, "utf8");
+    const commandContent = fs35.readFileSync(commandFile, "utf8");
     const relativeSource = `commands/${path34.basename(commandFile)}`;
     const marker = formatProvenanceMarker(
       "markdown",
@@ -27589,7 +27913,7 @@ ${commandContent.trim()}
 }
 function syncSkills3(config, sourceRoot, options, logger, manifest, scopePath, component = "skills", destination = "", asSymlink = false) {
   const source = path34.resolve(sourceRoot, config.source.skills);
-  if (!fs34.existsSync(source)) {
+  if (!fs35.existsSync(source)) {
     return skippedMissingSource3(component, source);
   }
   if (options.dryRun) {
@@ -27603,18 +27927,18 @@ function syncSkills3(config, sourceRoot, options, logger, manifest, scopePath, c
       return { component, status: "skipped-current", path: destination };
     }
     if (artifactClass === "managed-stale" && isOurStaleSymlink(destination, /* @__PURE__ */ new Set([destination]), config)) {
-      fs34.unlinkSync(destination);
+      fs35.unlinkSync(destination);
     } else if (artifactClass === "unmanaged-conflict" && !handleConflict3(destination, config, options, logger, manifest, scopePath)) {
       return { component, status: "conflict", path: destination };
     } else if (artifactClass === "managed-symlink") {
-      fs34.unlinkSync(destination);
+      fs35.unlinkSync(destination);
     }
     ensureDir(path34.dirname(destination));
     createRelativeSymlink(source, destination, "dir");
     logger.verbose(`Skills: created shared skills symlink ${destination}`);
     return { component, status: "success", path: destination };
   }
-  if (fs34.existsSync(destination)) {
+  if (fs35.existsSync(destination)) {
     return { component, status: "skipped-current", path: destination };
   }
   ensureDir(destination);
@@ -27622,10 +27946,11 @@ function syncSkills3(config, sourceRoot, options, logger, manifest, scopePath, c
   return { component, status: "success", path: destination };
 }
 function syncHooks3(config, sourceRoot, paths, mappings, options, lossReport, logger) {
-  const source = resolveHooksSourceFile(sourceRoot, config);
-  const sourceLabel = hooksSourceLabel(config);
+  const hooksSource = loadKitHooksSource(sourceRoot, config);
+  const source = hooksSource?.path ?? resolveHooksSourceDir(sourceRoot, config);
+  const sourceLabel = hooksSource?.label ?? hooksSourceLabel(sourceRoot, config);
   const destination = resolveTargetPath(paths.hooks_file);
-  const sourceHooksJson = fs34.existsSync(source) ? JSON.parse(fs34.readFileSync(source, "utf8")) : { hooks: {} };
+  const sourceHooksJson = hooksSource?.hooks ?? { hooks: {} };
   const compiled = compileHooks(
     sourceHooksJson,
     "cursor",
@@ -27640,17 +27965,17 @@ function syncHooks3(config, sourceRoot, paths, mappings, options, lossReport, lo
   const hooksFileContent = `${JSON.stringify({ version: 1, hooks: compiled.payload }, null, 2)}
 `;
   ensureDir(path34.dirname(destination));
-  fs34.writeFileSync(destination, hooksFileContent);
+  fs35.writeFileSync(destination, hooksFileContent);
   return { component: "hooks", status: "success", path: destination };
 }
 function syncMcp3(config, sourceRoot, paths, options, lossReport, logger, manifest, scopePath) {
   const source = resolveMcpSourceFile(sourceRoot, config);
   const sourceLabel = mcpSourceLabel(config);
   const destination = resolveTargetPath(paths.mcp_file);
-  if (!fs34.existsSync(source)) {
+  if (!fs35.existsSync(source)) {
     return skippedMissingSource3("mcp", source);
   }
-  const sourceMcpJson = JSON.parse(fs34.readFileSync(source, "utf8"));
+  const sourceMcpJson = JSON.parse(fs35.readFileSync(source, "utf8"));
   const mcpJson = compileMcp(sourceMcpJson, "cursor", lossReport, sourceLabel);
   if (options.dryRun) {
     logger.info(`[dry-run] mcp: compile ${source} -> ${destination}`);
@@ -27702,7 +28027,7 @@ function syncPermissions(config, paths, options, _lossReport, logger, manifest,
 }
 function syncProviderPin(config, sourceRoot, lossReport) {
   const agentsDir = path34.join(sourceRoot, config.source.agents);
-  if (!fs34.existsSync(agentsDir)) return;
+  if (!fs35.existsSync(agentsDir)) return;
   for (const agentFile of ts(path34.join(agentsDir, "*.md")).sort()) {
     const { data } = parseMarkdownFrontmatter(agentFile);
     const hasCustomProvider = typeof data.provider === "string" || typeof data.provider === "object" && data.provider !== null && Object.keys(data.provider).length > 0;
@@ -27735,7 +28060,7 @@ function writeCompiledArtifact3(component, destination, content, expectedHash, c
     return { component, status: "conflict", path: destination };
   }
   ensureDir(path34.dirname(destination));
-  fs34.writeFileSync(destination, content);
+  fs35.writeFileSync(destination, content);
   return { component, status: "success", path: destination };
 }
 function handleConflict3(destination, config, options, logger, manifest, scopePath) {
@@ -27754,16 +28079,16 @@ function handleConflict3(destination, config, options, logger, manifest, scopePa
       backupFile(destination, manifest);
       writeManifest(scopePath, manifest);
     } else {
-      fs34.renameSync(destination, `${destination}.bak.${Date.now()}`);
+      fs35.renameSync(destination, `${destination}.bak.${Date.now()}`);
     }
     return true;
   }
-  fs34.rmSync(destination, { recursive: true, force: true });
+  fs35.rmSync(destination, { recursive: true, force: true });
   return true;
 }
 function isCompiledCurrent3(destination, expectedContent, expectedHash) {
   try {
-    const current = fs34.readFileSync(destination, "utf8");
+    const current = fs35.readFileSync(destination, "utf8");
     const marker = extractProvenanceMarker(current);
     return expectedHash ? marker?.hash === expectedHash && marker.target === "cursor" && current === expectedContent : current === expectedContent;
   } catch {
@@ -27782,7 +28107,7 @@ function shouldSkipComponent3(options, component) {
 }
 function isSymlinkTo3(linkPath, source) {
   try {
-    return fs34.realpathSync(linkPath) === fs34.realpathSync(source);
+    return fs35.realpathSync(linkPath) === fs35.realpathSync(source);
   } catch {
     return false;
   }
@@ -27793,7 +28118,7 @@ function hashString3(value) {
 
 // src/adapters/cline.ts
 import crypto8 from "crypto";
-import fs35 from "fs";
+import fs36 from "fs";
 import path35 from "path";
 function syncCline(config, sourceRoot, mappings, extensions, options, lossReport, logger, manifest, scopePath) {
   const scope = options.scope ?? "global";
@@ -27929,7 +28254,7 @@ function syncInstructions3(config, sourceRoot, paths, scope, options, lossReport
   }
   const source = path35.join(sourceRoot, config.source.instructions);
   const destination = resolveTargetPath(paths.instructions);
-  const baseContent = fs35.existsSync(source) ? fs35.readFileSync(source, "utf8").trim() : "";
+  const baseContent = fs36.existsSync(source) ? fs36.readFileSync(source, "utf8").trim() : "";
   const marker = formatProvenanceMarker(
     "markdown",
     path35.basename(config.source.instructions),
@@ -27958,7 +28283,7 @@ ${baseContent}
 }
 function syncAgents4(config, sourceRoot, mappings, extensions, options, lossReport, logger) {
   const sourceAgentsRoot = path35.join(sourceRoot, config.source.agents);
-  if (!fs35.existsSync(sourceAgentsRoot)) {
+  if (!fs36.existsSync(sourceAgentsRoot)) {
     return [skippedMissingSource4("agents", sourceAgentsRoot)];
   }
   const sourceAgents = ts(path35.join(sourceAgentsRoot, "*.md")).sort();
@@ -27978,7 +28303,7 @@ function syncAgents4(config, sourceRoot, mappings, extensions, options, lossRepo
 }
 function syncRules3(config, sourceRoot, paths, mappings, options, lossReport, logger, manifest, scopePath) {
   const sourceRulesDir = path35.join(sourceRoot, config.source.rules);
-  if (!fs35.existsSync(sourceRulesDir)) {
+  if (!fs36.existsSync(sourceRulesDir)) {
     return [skippedMissingSource4("rules", sourceRulesDir)];
   }
   const compiled = compileRules(sourceRulesDir, "cline", mappings, lossReport);
@@ -28009,7 +28334,7 @@ function syncRules3(config, sourceRoot, paths, mappings, options, lossReport, lo
 }
 function syncCommands3(config, sourceRoot, paths, options, logger, manifest, scopePath) {
   const sourceCommandsRoot = path35.join(sourceRoot, config.source.commands);
-  if (!fs35.existsSync(sourceCommandsRoot)) {
+  if (!fs36.existsSync(sourceCommandsRoot)) {
     return [skippedMissingSource4("commands", sourceCommandsRoot)];
   }
   const sourceCommands = ts(path35.join(sourceCommandsRoot, "*.md")).sort();
@@ -28017,7 +28342,7 @@ function syncCommands3(config, sourceRoot, paths, options, logger, manifest, sco
   return sourceCommands.map((commandFile) => {
     const baseName = path35.basename(commandFile);
     const destination = path35.join(workflowsRoot, baseName);
-    const commandContent = fs35.readFileSync(commandFile, "utf8");
+    const commandContent = fs36.readFileSync(commandFile, "utf8");
     const relativeSource = `commands/${path35.basename(commandFile)}`;
     const marker = formatProvenanceMarker(
       "markdown",
@@ -28055,7 +28380,7 @@ ${commandContent.trim()}
 function syncSkills4(config, sourceRoot, paths, options, logger, manifest, scopePath) {
   const source = path35.resolve(sourceRoot, config.source.skills);
   const destination = resolveTargetPath(paths.skills);
-  if (!fs35.existsSync(source)) {
+  if (!fs36.existsSync(source)) {
     return skippedMissingSource4("skills", source);
   }
   if (options.dryRun) {
@@ -28075,7 +28400,7 @@ function syncSkills4(config, sourceRoot, paths, options, logger, manifest, scope
       return { component: "skills", status: "conflict", path: destination };
     }
   } else if (artifactClass === "managed-symlink") {
-    fs35.unlinkSync(destination);
+    fs36.unlinkSync(destination);
   }
   ensureDir(path35.dirname(destination));
   createRelativeSymlink(source, destination, "dir");
@@ -28083,9 +28408,10 @@ function syncSkills4(config, sourceRoot, paths, options, logger, manifest, scope
   return { component: "skills", status: "success", path: destination };
 }
 function syncHooks4(config, sourceRoot, mappings, options, lossReport, logger) {
-  const source = resolveHooksSourceFile(sourceRoot, config);
-  const sourceLabel = hooksSourceLabel(config);
-  const sourceHooksJson = fs35.existsSync(source) ? JSON.parse(fs35.readFileSync(source, "utf8")) : { hooks: {} };
+  const hooksSource = loadKitHooksSource(sourceRoot, config);
+  const source = hooksSource?.path ?? resolveHooksSourceDir(sourceRoot, config);
+  const sourceLabel = hooksSource?.label ?? hooksSourceLabel(sourceRoot, config);
+  const sourceHooksJson = hooksSource?.hooks ?? { hooks: {} };
   compileHooks(sourceHooksJson, "cline", mappings, lossReport, sourceLabel);
   if (options.dryRun) {
     logger.info(`[dry-run] hooks: record hook-as-plugin loss for ${source}`);
@@ -28100,10 +28426,10 @@ function syncMcp4(config, sourceRoot, paths, options, lossReport, logger, manife
   const source = resolveMcpSourceFile(sourceRoot, config);
   const sourceLabel = mcpSourceLabel(config);
   const destination = resolveTargetPath(paths.mcp_file);
-  if (!fs35.existsSync(source)) {
+  if (!fs36.existsSync(source)) {
     return skippedMissingSource4("mcp", source);
   }
-  const sourceMcpJson = JSON.parse(fs35.readFileSync(source, "utf8"));
+  const sourceMcpJson = JSON.parse(fs36.readFileSync(source, "utf8"));
   const mcpJson = compileMcp(sourceMcpJson, "cline", lossReport, sourceLabel);
   if (options.dryRun) {
     logger.info(`[dry-run] mcp: compile ${source} -> ${destination}`);
@@ -28147,7 +28473,7 @@ function syncSettings(lossReport) {
 }
 function syncProviderAndModel(config, sourceRoot, lossReport) {
   const agentsDir = path35.join(sourceRoot, config.source.agents);
-  if (!fs35.existsSync(agentsDir)) return;
+  if (!fs36.existsSync(agentsDir)) return;
   for (const agentFile of ts(path35.join(agentsDir, "*.md")).sort()) {
     const { data } = parseMarkdownFrontmatter(agentFile);
     const relativeSource = `agents/${path35.basename(agentFile)}`;
@@ -28198,7 +28524,7 @@ function writeCompiledArtifact4(component, destination, content, expectedHash, c
     return { component, status: "conflict", path: destination };
   }
   ensureDir(path35.dirname(destination));
-  fs35.writeFileSync(destination, content);
+  fs36.writeFileSync(destination, content);
   return { component, status: "success", path: destination };
 }
 function handleConflict4(destination, config, options, logger, manifest, scopePath) {
@@ -28217,16 +28543,16 @@ function handleConflict4(destination, config, options, logger, manifest, scopePa
       backupFile(destination, manifest);
       writeManifest(scopePath, manifest);
     } else {
-      fs35.renameSync(destination, `${destination}.bak.${Date.now()}`);
+      fs36.renameSync(destination, `${destination}.bak.${Date.now()}`);
     }
     return true;
   }
-  fs35.rmSync(destination, { recursive: true, force: true });
+  fs36.rmSync(destination, { recursive: true, force: true });
   return true;
 }
 function isCompiledCurrent4(destination, expectedContent, expectedHash) {
   try {
-    const current = fs35.readFileSync(destination, "utf8");
+    const current = fs36.readFileSync(destination, "utf8");
     const marker = extractProvenanceMarker(current);
     return expectedHash ? marker?.hash === expectedHash && marker.target === "cline" && current === expectedContent : current === expectedContent;
   } catch {
@@ -28245,7 +28571,7 @@ function shouldSkipComponent4(options, component) {
 }
 function isSymlinkTo4(linkPath, source) {
   try {
-    return fs35.realpathSync(linkPath) === fs35.realpathSync(source);
+    return fs36.realpathSync(linkPath) === fs36.realpathSync(source);
   } catch {
     return false;
   }
@@ -28256,7 +28582,7 @@ function hashString4(value) {
 
 // src/adapters/opencode.ts
 import crypto9 from "crypto";
-import fs36 from "fs";
+import fs37 from "fs";
 import os6 from "os";
 import path36 from "path";
 var import_yaml11 = __toESM(require_dist(), 1);
@@ -28380,7 +28706,7 @@ function syncOpenCode(config, sourceRoot, mappings, extensions, options, lossRep
 function syncInstructions4(config, sourceRoot, paths, agentsAppendix, options, logger, manifest, scopePath) {
   const source = path36.join(sourceRoot, config.source.instructions);
   const destination = resolveTargetPath(paths.instructions);
-  const baseContent = fs36.existsSync(source) ? fs36.readFileSync(source, "utf8").trim() : "";
+  const baseContent = fs37.existsSync(source) ? fs37.readFileSync(source, "utf8").trim() : "";
   const composed = agentsAppendix ? `${baseContent}
 
 --- tangyr managed rules ---
@@ -28415,7 +28741,7 @@ ${composed}
 }
 function syncAgents5(config, sourceRoot, paths, mappings, extensions, options, lossReport, logger, manifest, scopePath) {
   const sourceAgentsRoot = path36.join(sourceRoot, config.source.agents);
-  if (!fs36.existsSync(sourceAgentsRoot)) {
+  if (!fs37.existsSync(sourceAgentsRoot)) {
     return [skippedMissingSource5("agents", sourceAgentsRoot)];
   }
   const sourceAgents = ts(path36.join(sourceAgentsRoot, "*.md")).sort();
@@ -28488,7 +28814,7 @@ function applyProviderModelBinding(compiled, mappings) {
 }
 function syncCommands4(config, sourceRoot, paths, options, logger, manifest, scopePath) {
   const sourceCommandsRoot = path36.join(sourceRoot, config.source.commands);
-  if (!fs36.existsSync(sourceCommandsRoot)) {
+  if (!fs37.existsSync(sourceCommandsRoot)) {
     return [skippedMissingSource5("commands", sourceCommandsRoot)];
   }
   const sourceCommands = ts(path36.join(sourceCommandsRoot, "*.md")).sort();
@@ -28551,7 +28877,7 @@ ${body.trimEnd()}
 }
 function syncSkills5(config, sourceRoot, _paths, options, logger, manifest, scopePath, component = "skills", destination = "") {
   const source = path36.resolve(sourceRoot, config.source.skills);
-  if (!fs36.existsSync(source)) {
+  if (!fs37.existsSync(source)) {
     return skippedMissingSource5(component, source);
   }
   if (options.dryRun) {
@@ -28563,11 +28889,11 @@ function syncSkills5(config, sourceRoot, _paths, options, logger, manifest, scop
     return { component, status: "skipped-current", path: destination };
   }
   if (artifactClass === "managed-stale" && isOurStaleSymlink(destination, /* @__PURE__ */ new Set([destination]), config)) {
-    fs36.unlinkSync(destination);
+    fs37.unlinkSync(destination);
   } else if (artifactClass === "unmanaged-conflict" && !handleConflict5(destination, config, options, logger, manifest, scopePath)) {
     return { component, status: "conflict", path: destination };
   } else if (artifactClass === "managed-symlink") {
-    fs36.unlinkSync(destination);
+    fs37.unlinkSync(destination);
   }
   ensureDir(path36.dirname(destination));
   createRelativeSymlink(source, destination, "dir");
@@ -28578,13 +28904,13 @@ function syncMcp5(config, sourceRoot, paths, mappings, options, lossReport, logg
   const source = resolveMcpSourceFile(sourceRoot, config);
   const sourceLabel = mcpSourceLabel(config);
   const destination = resolveTargetPath(paths.config_doc);
-  if (!fs36.existsSync(source)) {
+  if (!fs37.existsSync(source)) {
     if (!options.dryRun) {
       syncConfigDoc(paths, {}, lossReport, {}, mappings);
     }
     return skippedMissingSource5("mcp", source);
   }
-  const sourceMcpJson = JSON.parse(fs36.readFileSync(source, "utf8"));
+  const sourceMcpJson = JSON.parse(fs37.readFileSync(source, "utf8"));
   const mcpJson = compileMcp(
     sourceMcpJson,
     "opencode",
@@ -28613,9 +28939,10 @@ function syncPermissions2(config, _sourceRoot, paths, options, lossReport, logge
   return { component: "settings", status: "success", path: destination };
 }
 function syncHooks5(config, sourceRoot, mappings, options, lossReport) {
-  const source = resolveHooksSourceFile(sourceRoot, config);
-  const sourceLabel = hooksSourceLabel(config);
-  const sourceHooksJson = fs36.existsSync(source) ? JSON.parse(fs36.readFileSync(source, "utf8")) : { hooks: {} };
+  const hooksSource = loadKitHooksSource(sourceRoot, config);
+  const source = hooksSource?.path ?? resolveHooksSourceDir(sourceRoot, config);
+  const sourceLabel = hooksSource?.label ?? hooksSourceLabel(sourceRoot, config);
+  const sourceHooksJson = hooksSource?.hooks ?? { hooks: {} };
   compileHooks(sourceHooksJson, "opencode", mappings, lossReport, sourceLabel);
   const message = "hooks: Skip \u2014 OpenCode exposes hooks only as plugin code (hook-as-plugin loss recorded)";
   return { component: "hooks", status: "skipped", path: message };
@@ -28649,9 +28976,9 @@ function syncProviderBlock(mappings) {
 function syncConfigDoc(paths, mcpEntries, _lossReport, permissionMap, mappings) {
   const destination = resolveTargetPath(paths.config_doc);
   let existing = {};
-  if (fs36.existsSync(destination)) {
+  if (fs37.existsSync(destination)) {
     try {
-      existing = JSON.parse(fs36.readFileSync(destination, "utf8"));
+      existing = JSON.parse(fs37.readFileSync(destination, "utf8"));
     } catch {
       existing = {};
     }
@@ -28677,7 +29004,7 @@ function syncConfigDoc(paths, mcpEntries, _lossReport, permissionMap, mappings)
     }
   }
   ensureDir(path36.dirname(destination));
-  fs36.writeFileSync(destination, `${JSON.stringify(config, null, 2)}
+  fs37.writeFileSync(destination, `${JSON.stringify(config, null, 2)}
 `);
 }
 function writeCompiledArtifact5(component, destination, content, expectedHash, config, sourceRoot, options, logger, manifest, scopePath) {
@@ -28689,7 +29016,7 @@ function writeCompiledArtifact5(component, destination, content, expectedHash, c
     return { component, status: "conflict", path: destination };
   }
   ensureDir(path36.dirname(destination));
-  fs36.writeFileSync(destination, content);
+  fs37.writeFileSync(destination, content);
   return { component, status: "success", path: destination };
 }
 function handleConflict5(destination, config, options, logger, manifest, scopePath) {
@@ -28708,16 +29035,16 @@ function handleConflict5(destination, config, options, logger, manifest, scopePa
       backupFile(destination, manifest);
       writeManifest(scopePath, manifest);
     } else {
-      fs36.renameSync(destination, `${destination}.bak.${Date.now()}`);
+      fs37.renameSync(destination, `${destination}.bak.${Date.now()}`);
     }
     return true;
   }
-  fs36.rmSync(destination, { recursive: true, force: true });
+  fs37.rmSync(destination, { recursive: true, force: true });
   return true;
 }
 function isCompiledCurrent5(destination, expectedContent, expectedHash) {
   try {
-    const current = fs36.readFileSync(destination, "utf8");
+    const current = fs37.readFileSync(destination, "utf8");
     const marker = extractProvenanceMarker(current);
     return expectedHash ? marker?.hash === expectedHash && marker.target === "opencode" && current === expectedContent : current === expectedContent;
   } catch {
@@ -28736,7 +29063,7 @@ function shouldSkipComponent5(options, component) {
 }
 function isSymlinkTo5(linkPath, source) {
   try {
-    return fs36.realpathSync(linkPath) === fs36.realpathSync(source);
+    return fs37.realpathSync(linkPath) === fs37.realpathSync(source);
   } catch {
     return false;
   }
@@ -28745,7 +29072,7 @@ function hashString5(value) {
   return `sha256:${crypto9.createHash("sha256").update(value).digest("hex")}`;
 }
 function parseCommandFile(commandFile) {
-  const content = fs36.readFileSync(commandFile, "utf8");
+  const content = fs37.readFileSync(commandFile, "utf8");
   if (!content.startsWith("---\n")) {
     return { data: {}, body: content };
   }
@@ -28765,10 +29092,10 @@ function parseCommandFile(commandFile) {
 // src/commands/install.ts
 function isBackupableFile(targetPath) {
   try {
-    const lstat = fs37.lstatSync(targetPath);
+    const lstat = fs38.lstatSync(targetPath);
     if (lstat.isDirectory()) return false;
     if (lstat.isSymbolicLink()) {
-      const stat = fs37.statSync(targetPath);
+      const stat = fs38.statSync(targetPath);
       return stat.isFile();
     }
     return lstat.isFile();
@@ -28780,8 +29107,8 @@ function backupConflictingTarget(targetPath, scopePath) {
   const ts2 = (/* @__PURE__ */ new Date()).toISOString().replace(/[-:]/gu, "").replace("T", "T").replace(/\.\d+Z$/u, "Z");
   const relativeToRoot = path37.relative("/", targetPath).replace(/^\.\.\/+/gu, "");
   const backupPath = path37.join(scopePath, "backups", ts2, relativeToRoot);
-  fs37.mkdirSync(path37.dirname(backupPath), { recursive: true });
-  fs37.copyFileSync(targetPath, backupPath);
+  fs38.mkdirSync(path37.dirname(backupPath), { recursive: true });
+  fs38.copyFileSync(targetPath, backupPath);
   return backupPath;
 }
 async function runInstallCommand(options, logger) {
@@ -28837,6 +29164,10 @@ async function runInstallCommand(options, logger) {
   logger.info(
     `Installing kit '${kitInfo.name}' (${kitInfo.archetype}) into ${scope} scope for: ${tools.join(", ")}`
   );
+  const resolvedEntrypoint = resolveEntrypoint(kitInfo);
+  if (resolvedEntrypoint?.legacy) {
+    logger.warn(LEGACY_ENTRYPOINT_NOTICE);
+  }
   const scopePath = resolveScopePath(
     scope,
     scope === "project" ? process.cwd() : void 0
@@ -28951,7 +29282,7 @@ ACCEPTED CONFLICTS (backup-and-replace applied to ${conflictingFindings.length}
           logger.info(`    source: ${finding.tool}`);
           logger.info(`    action: backup-and-replace`);
           logger.info(`    backup: ${backupLocation}`);
-        } else if (fs37.existsSync(finding.path)) {
+        } else if (fs38.existsSync(finding.path)) {
           logger.info(`  - ${finding.path}`);
           logger.info(`    source: ${finding.tool}`);
           logger.info(
@@ -29066,6 +29397,30 @@ Installation complete: ${installedCount} files installed.`);
   logger.info(`Kit: ${kitInfo.name} (archetype: ${kitInfo.archetype})`);
   logger.info(`Scope: ${scope}`);
   logger.info(`Tools: ${tools.join(", ")}`);
+  reportHookRejections(
+    installLossReport,
+    tools,
+    path37.resolve(kitInfo.path, "hooks"),
+    kitInfo.components.hooks.declared
+  );
+  const hooksConflict = reportHooksSourceConflict(
+    installLossReport,
+    tools,
+    path37.resolve(kitInfo.path, "hooks"),
+    kitInfo.components.hooks.declared
+  );
+  if (hooksConflict) {
+    logger.warn(hooksConflict);
+  }
+  if (scope === "project") {
+    reportProjectScopeScriptPath(
+      installLossReport,
+      tools,
+      path37.resolve(kitInfo.path, "hooks"),
+      kitInfo.components.hooks.declared
+    );
+  }
+  writeLossReport(options.lossReport, installLossReport);
   exitOnErrorSeverityLoss(installLossReport, logger, {
     ignoreErrors: options.ignoreErrors ?? false
   });
@@ -29205,12 +29560,12 @@ function applyClaudeCodePlacements(placements, manifest, skippedTargetPaths, log
       continue;
     }
     const destDir = path37.dirname(placement.destination);
-    fs37.mkdirSync(destDir, { recursive: true });
+    fs38.mkdirSync(destDir, { recursive: true });
     if (placement.type === "symlink") {
-      if (fs37.existsSync(placement.destination) || isSymlink2(placement.destination)) {
+      if (fs38.existsSync(placement.destination) || isSymlink2(placement.destination)) {
         removeManagedPath(placement.destination);
       }
-      fs37.symlinkSync(
+      fs38.symlinkSync(
         placement.source,
         placement.destination,
         placement.isDir ? "dir" : "file"
@@ -29219,12 +29574,12 @@ function applyClaudeCodePlacements(placements, manifest, skippedTargetPaths, log
         `  symlink: ${placement.source} \u2192 ${placement.destination}`
       );
     } else {
-      fs37.copyFileSync(placement.source, placement.destination);
+      fs38.copyFileSync(placement.source, placement.destination);
       logger.verbose(`  copy: ${placement.source} \u2192 ${placement.destination}`);
     }
     addArtifactToManifest(manifest, {
       relativePath: placement.manifestKey,
-      hash: fs37.statSync(placement.source).isDirectory() ? `dir:${placement.source}` : computeSourceHash(placement.source),
+      hash: fs38.statSync(placement.source).isDirectory() ? `dir:${placement.source}` : computeSourceHash(placement.source),
       origin: "tangyr-managed"
     });
     count++;
@@ -29636,12 +29991,12 @@ function getClaudeCodePlacements(kitInfo, scope = "global", projectRoot, mapping
     };
   }
   const placements = [];
-  const claudeMd = path37.join(kitInfo.path, "CLAUDE.md");
-  if (fs37.existsSync(claudeMd)) {
+  const entrypoint = resolveEntrypoint(kitInfo);
+  if (entrypoint) {
     placements.push({
-      source: claudeMd,
+      source: entrypoint.file,
       destination: resolvedPaths.instructions,
-      manifestKey: "claude-code/CLAUDE.md",
+      manifestKey: `claude-code/${entrypoint.name}`,
       type: "symlink",
       isDir: false
     });
@@ -29654,7 +30009,7 @@ function getClaudeCodePlacements(kitInfo, scope = "global", projectRoot, mapping
   };
   for (const [component, targetPath] of Object.entries(componentDirMap)) {
     const componentDir = path37.join(kitInfo.path, component);
-    if (fs37.existsSync(componentDir) && fs37.statSync(componentDir).isDirectory()) {
+    if (fs38.existsSync(componentDir) && fs38.statSync(componentDir).isDirectory()) {
       placements.push({
         source: componentDir,
         destination: targetPath,
@@ -29668,12 +30023,12 @@ function getClaudeCodePlacements(kitInfo, scope = "global", projectRoot, mapping
 }
 function getClaudeCodePlacementsFromProfile(kitInfo, profile) {
   const placements = [];
-  const claudeMd = path37.join(kitInfo.path, "CLAUDE.md");
-  if (fs37.existsSync(claudeMd)) {
+  const entrypoint = resolveEntrypoint(kitInfo);
+  if (entrypoint) {
     placements.push({
-      source: claudeMd,
+      source: entrypoint.file,
       destination: profile.instructions,
-      manifestKey: "claude-code/CLAUDE.md",
+      manifestKey: `claude-code/${entrypoint.name}`,
       type: "symlink",
       isDir: false
     });
@@ -29686,7 +30041,7 @@ function getClaudeCodePlacementsFromProfile(kitInfo, profile) {
   };
   for (const [component, targetPath] of Object.entries(componentDirMap)) {
     const componentDir = path37.join(kitInfo.path, component);
-    if (fs37.existsSync(componentDir) && fs37.statSync(componentDir).isDirectory()) {
+    if (fs38.existsSync(componentDir) && fs38.statSync(componentDir).isDirectory()) {
       placements.push({
         source: componentDir,
         destination: targetPath,
@@ -29700,9 +30055,9 @@ function getClaudeCodePlacementsFromProfile(kitInfo, profile) {
 }
 function collectAllFiles(kitInfo) {
   const files = /* @__PURE__ */ new Map();
-  const claudeMd = path37.join(kitInfo.path, "CLAUDE.md");
-  if (fs37.existsSync(claudeMd)) {
-    files.set("CLAUDE.md", claudeMd);
+  const entrypoint = resolveEntrypoint(kitInfo);
+  if (entrypoint) {
+    files.set(entrypoint.name, entrypoint.file);
   }
   for (const [component, reconciliation] of Object.entries(
     kitInfo.components
@@ -29719,7 +30074,7 @@ function collectAllFiles(kitInfo) {
 }
 function isSymlink2(p) {
   try {
-    return fs37.lstatSync(p).isSymbolicLink();
+    return fs38.lstatSync(p).isSymbolicLink();
   } catch {
     return false;
   }
@@ -29854,10 +30209,13 @@ function withDirectKit(kits, directKitPath) {
 
 // src/commands/probe.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import fs38 from "fs";
+import fs39 from "fs";
 import path39 from "path";
 function runProbeCommand(options, logger) {
-  const { config, configDir, sourceRoot } = resolveRuntime(options, import.meta.url);
+  const { config, configDir, sourceRoot } = resolveRuntime(
+    options,
+    import.meta.url
+  );
   const platformPaths = readYamlObject(
     path39.join(
       resolveConfiguredPath(config.mappings, configDir, sourceRoot, "mappings"),
@@ -29885,7 +30243,9 @@ function runProbeCommand(options, logger) {
     console.log(JSON.stringify(rows, null, 2));
   } else {
     for (const row of rows) {
-      logger.info(`${row.target}	${row.key}	${row.exists ? "exists" : "missing"}	${row.path}`);
+      logger.info(
+        `${row.target}	${row.key}	${row.exists ? "exists" : "missing"}	${row.path}`
+      );
     }
   }
 }
@@ -29893,15 +30253,26 @@ function toProbeRow(target, key, rawPath) {
   const resolved = resolveTargetPath(rawPath);
   let accessible = false;
   try {
-    fs38.accessSync(resolved);
+    fs39.accessSync(resolved);
     accessible = true;
   } catch {
     accessible = false;
   }
-  return { target, key, path: resolved, exists: fs38.existsSync(resolved), accessible };
+  return {
+    target,
+    key,
+    path: resolved,
+    exists: fs39.existsSync(resolved),
+    accessible
+  };
 }
 function codexRuntimeProbeRows() {
-  const rows = commandProbeRows("codex", "binary", process.platform === "win32" ? "where.exe" : "which", ["codex"]);
+  const rows = commandProbeRows(
+    "codex",
+    "binary",
+    process.platform === "win32" ? "where.exe" : "which",
+    ["codex"]
+  );
   if (process.platform !== "linux") {
     return rows;
   }
@@ -29909,7 +30280,7 @@ function codexRuntimeProbeRows() {
     ["binary_snap", "/snap/bin/codex"],
     ["binary_flatpak", "/var/lib/flatpak/exports/bin/codex"]
   ]) {
-    if (fs38.existsSync(candidatePath)) {
+    if (fs39.existsSync(candidatePath)) {
       rows.push(toProbeRow("codex", key, candidatePath));
     }
   }
@@ -29925,7 +30296,7 @@ function commandProbeRows(target, key, command, args) {
 
 // src/commands/status.ts
 import crypto10 from "crypto";
-import fs39 from "fs";
+import fs40 from "fs";
 import path40 from "path";
 function runStatusCommand(options, logger) {
   const { config, configDir, sourceRoot } = resolveRuntime(
@@ -30010,7 +30381,7 @@ function classifyCodexFiles(config, sourceRoot, configDir) {
     mappings,
     createLossReport()
   );
-  const instructionsSource = fs39.readFileSync(path40.join(sourceRoot, config.source.instructions), "utf8").trim();
+  const instructionsSource = fs40.readFileSync(path40.join(sourceRoot, config.source.instructions), "utf8").trim();
   const composedInstructions = `${instructionsSource}
 
 --- tangyr managed rules ---
@@ -30075,11 +30446,11 @@ ${rules.agentsAppendix}`.trim();
       config,
       sourceRoot
     ),
-    fs39.existsSync(hooksSource) ? classifyCodexHooksFile(resolveTargetPath(codexPaths.hooksSharedFile)) : notConfiguredRow(
+    fs40.existsSync(hooksSource) ? classifyCodexHooksFile(resolveTargetPath(codexPaths.hooksSharedFile)) : notConfiguredRow(
       "hooks",
       resolveTargetPath(codexPaths.hooksSharedFile)
     ),
-    fs39.existsSync(mcpSource) ? classifyCompiledFile(
+    fs40.existsSync(mcpSource) ? classifyCompiledFile(
       "mcp",
       resolveTargetPath(codexPaths.mcpSharedFile),
       "codex",
@@ -30099,7 +30470,7 @@ function classifyCodexHooksFile(filePath) {
       conformant: true
     };
   }
-  if (!fs39.existsSync(filePath)) {
+  if (!fs40.existsSync(filePath)) {
     return {
       component: "hooks",
       className: "missing",
@@ -30182,7 +30553,7 @@ function classifyCopilotFiles(config, sourceRoot, configDir) {
       config,
       sourceRoot
     ),
-    fs39.existsSync(hooksSource) ? classifyCompiledFile(
+    fs40.existsSync(hooksSource) ? classifyCompiledFile(
       "hooks",
       path40.join(
         resolveTargetPath(copilotPaths.hooks),
@@ -30199,7 +30570,7 @@ function classifyCopilotFiles(config, sourceRoot, configDir) {
         "tangyr-managed.json"
       )
     ),
-    fs39.existsSync(mcpSource) ? classifyCompiledFile(
+    fs40.existsSync(mcpSource) ? classifyCompiledFile(
       "mcp",
       resolveTargetPath(copilotPaths.mcpSharedFile),
       "copilot",
@@ -30374,14 +30745,14 @@ function classifyMcp(filePath, sourcePath) {
 }
 function isSymlinkCurrent(linkPath, sourcePath) {
   try {
-    return fs39.realpathSync(linkPath) === fs39.realpathSync(sourcePath);
+    return fs40.realpathSync(linkPath) === fs40.realpathSync(sourcePath);
   } catch {
     return false;
   }
 }
 function isCompiledCurrent6(filePath, sourcePath) {
   try {
-    const marker = extractProvenanceMarker(fs39.readFileSync(filePath, "utf8"));
+    const marker = extractProvenanceMarker(fs40.readFileSync(filePath, "utf8"));
     return marker?.hash === computeSourceHash(sourcePath) && marker.target === "claude-code";
   } catch {
     return false;
@@ -30411,7 +30782,7 @@ function classifyCompiledFile(component, filePath, target, expectedHash, config,
 }
 function readCompiledContent(filePath) {
   try {
-    return fs39.readFileSync(filePath, "utf8");
+    return fs40.readFileSync(filePath, "utf8");
   } catch {
     return null;
   }
@@ -30442,7 +30813,7 @@ function hashString6(value) {
 }
 
 // src/commands/sync.ts
-import fs41 from "fs";
+import fs42 from "fs";
 import path42 from "path";
 
 // node_modules/chalk/source/vendor/ansi-styles/index.js
@@ -30941,7 +31312,7 @@ var chalkStderr = createChalk({ level: stderrColor ? stderrColor.level : 0 });
 var source_default = chalk;
 
 // src/adapters/claude-code.ts
-import fs40 from "fs";
+import fs41 from "fs";
 import path41 from "path";
 
 // src/core/shim.ts
@@ -31080,7 +31451,14 @@ function syncClaudeCode(config, sourceRoot, options, logger, mappings, manifest,
       )
     );
     outcomes.push(
-      syncHooks6(config, sourceRoot, options, logger, profile.hooks_shared_file)
+      syncHooks6(
+        config,
+        sourceRoot,
+        options,
+        logger,
+        profile.hooks_shared_file,
+        profile.hooks
+      )
     );
   }
   if (!shouldSkipComponent6(options, "mcp")) {
@@ -31107,7 +31485,7 @@ function syncClaudeCode(config, sourceRoot, options, logger, mappings, manifest,
 function syncProviderLoss2(config, sourceRoot, mappings, lossReport) {
   if (!mappings.modelTiers.custom_provider) return;
   const agentsDir = path41.join(sourceRoot, config.source.agents);
-  if (!fs40.existsSync(agentsDir)) return;
+  if (!fs41.existsSync(agentsDir)) return;
   for (const agentFile of ts(path41.join(agentsDir, "*.md")).sort()) {
     const { data } = parseMarkdownFrontmatter(agentFile);
     const hasProvider = typeof data.provider === "string" || typeof data.provider === "object" && data.provider !== null && Object.keys(data.provider).length > 0;
@@ -31137,19 +31515,19 @@ function shouldSkipComponent6(options, component) {
 function applyClaudeCodeShimUpgrade(shimPath, agentsMdPath, manifest, scopePath, logger) {
   const expectedBodyHash = shimBodyHash();
   const shimContent = buildAgentsMdShim(shimPath, agentsMdPath, "claude-code");
-  if (!fs40.existsSync(shimPath)) {
+  if (!fs41.existsSync(shimPath)) {
     manifest.artifacts.push({
       relativePath: path41.relative(scopePath, shimPath),
       hash: expectedBodyHash,
       origin: "tangyr-managed"
     });
     writeManifest(scopePath, manifest);
-    fs40.mkdirSync(path41.dirname(shimPath), { recursive: true });
-    fs40.writeFileSync(shimPath, shimContent);
+    fs41.mkdirSync(path41.dirname(shimPath), { recursive: true });
+    fs41.writeFileSync(shimPath, shimContent);
     logger?.verbose(`instructions-shim: wrote @AGENTS.md shim -> ${shimPath}`);
     return;
   }
-  const existing = fs40.readFileSync(shimPath, "utf8");
+  const existing = fs41.readFileSync(shimPath, "utf8");
   const firstNonEmptyLine = existing.split("\n").find((l) => l.trim().length > 0) ?? "";
   const marker = extractProvenanceMarker(firstNonEmptyLine);
   if (marker !== null && marker.hash === expectedBodyHash) {
@@ -31160,7 +31538,7 @@ function applyClaudeCodeShimUpgrade(shimPath, agentsMdPath, manifest, scopePath,
   }
   backupFile(shimPath, manifest);
   writeManifest(scopePath, manifest);
-  fs40.writeFileSync(shimPath, shimContent);
+  fs41.writeFileSync(shimPath, shimContent);
   manifest.artifacts.push({
     relativePath: path41.relative(scopePath, shimPath),
     hash: expectedBodyHash,
@@ -31174,7 +31552,7 @@ function syncDirectComponent(config, sourceRoot, options, logger, directComponen
     config.source[directComponent.sourceKey]
   );
   const destination = directComponent.destination;
-  if (!fs40.existsSync(source)) {
+  if (!fs41.existsSync(source)) {
     return skippedMissingSource6(directComponent.component, source);
   }
   if (options.dryRun) {
@@ -31196,7 +31574,7 @@ function syncDirectComponent(config, sourceRoot, options, logger, directComponen
     };
   }
   if (artifactClass === "managed-stale" && isOurStaleSymlink(destination, /* @__PURE__ */ new Set([destination]), config)) {
-    fs40.unlinkSync(destination);
+    fs41.unlinkSync(destination);
   } else if (artifactClass === "unmanaged-conflict" && !handleConflict6(destination, config, options, logger, manifest, scopePath)) {
     return {
       component: directComponent.component,
@@ -31204,7 +31582,7 @@ function syncDirectComponent(config, sourceRoot, options, logger, directComponen
       path: destination
     };
   } else if (artifactClass === "managed-symlink") {
-    fs40.unlinkSync(destination);
+    fs41.unlinkSync(destination);
   }
   ensureDir(path41.dirname(destination));
   createRelativeSymlink(source, destination, directComponent.type, {
@@ -31224,7 +31602,7 @@ function syncDirectComponent(config, sourceRoot, options, logger, directComponen
 }
 function syncClaudeCodeSkills(config, sourceRoot, options, logger, destination, manifest, scopePath) {
   const source = path41.resolve(sourceRoot, config.source.skills);
-  if (!fs40.existsSync(source)) {
+  if (!fs41.existsSync(source)) {
     return [skippedMissingSource6("skills", source)];
   }
   const declaredNames = resolveKitSkillNames(sourceRoot);
@@ -31279,7 +31657,7 @@ function syncClaudeCodeSkills(config, sourceRoot, options, logger, destination,
 function syncSingleSkill(config, sourceRoot, options, logger, source, destination, name, manifest, scopePath) {
   const skillSource = path41.join(source, name);
   const skillDestination = path41.join(destination, name);
-  if (!fs40.existsSync(skillSource)) {
+  if (!fs41.existsSync(skillSource)) {
     return skippedMissingSource6("skills", skillSource);
   }
   const artifactClass = classifyArtifact(skillDestination, config, sourceRoot);
@@ -31291,7 +31669,7 @@ function syncSingleSkill(config, sourceRoot, options, logger, source, destinatio
     };
   }
   if (artifactClass === "managed-stale" && isOurStaleSymlink(skillDestination, /* @__PURE__ */ new Set([skillDestination]), config)) {
-    fs40.unlinkSync(skillDestination);
+    fs41.unlinkSync(skillDestination);
   } else if (artifactClass === "unmanaged-conflict" && !handleConflict6(
     skillDestination,
     config,
@@ -31302,26 +31680,28 @@ function syncSingleSkill(config, sourceRoot, options, logger, source, destinatio
   )) {
     return { component: "skills", status: "conflict", path: skillDestination };
   } else if (artifactClass === "managed-symlink") {
-    fs40.unlinkSync(skillDestination);
+    fs41.unlinkSync(skillDestination);
   }
   createRelativeSymlink(skillSource, skillDestination, "dir");
   return { component: "skills", status: "success", path: skillDestination };
 }
 function migrateWholesaleSkillsSymlink(source, destination, declaredNames, logger) {
   const foreignNames = foreignSkillNames(source, declaredNames);
-  fs40.unlinkSync(destination);
+  fs41.unlinkSync(destination);
   ensureDir(destination);
   for (const name of foreignNames) {
     const from = path41.join(source, name);
     const to = path41.join(destination, name);
-    if (fs40.existsSync(to)) {
+    if (fs41.existsSync(to)) {
       logger.warn(
-        `skills migration: ${to} already exists \u2014 skipping move of ${from} to avoid overwrite`
+        `skills migration: ${to} already exists \u2014 skipping ${from} to avoid overwrite. Nothing in the kit was changed.`
       );
       continue;
     }
-    fs40.renameSync(from, to);
-    logger.info(`skills migration: moved ${from} -> ${to}`);
+    fs41.cpSync(from, to, { recursive: true, verbatimSymlinks: true });
+    logger.warn(
+      `skills migration: '${name}' is present under the kit's skills/ but is not declared in its manifest. Copied ${from} -> ${to} so the harness can read it. The original is left in the kit deliberately: this command does not modify a kit. Remove ${from} yourself if it does not belong there, or declare it in tangyr-kit.yaml if it does.`
+    );
   }
 }
 function foreignSkillNames(source, declaredNames) {
@@ -31332,21 +31712,21 @@ function foreignSkillNames(source, declaredNames) {
   return listSkillDirNames(source).filter((name) => !declaredSet.has(name));
 }
 function listSkillDirNames(dir) {
-  if (!fs40.existsSync(dir)) {
+  if (!fs41.existsSync(dir)) {
     return [];
   }
-  return fs40.readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map((entry) => entry.name);
+  return fs41.readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map((entry) => entry.name);
 }
 function isSymlinkPath(filePath) {
   try {
-    return fs40.lstatSync(filePath).isSymbolicLink();
+    return fs41.lstatSync(filePath).isSymbolicLink();
   } catch {
     return false;
   }
 }
 function syncHookScriptsBridge(config, sourceRoot, options, logger, destination, manifest, scopePath) {
   const source = path41.resolve(sourceRoot, config.source.hooks);
-  if (!fs40.existsSync(source)) {
+  if (!fs41.existsSync(source)) {
     return skippedMissingSource6("hooks", source);
   }
   if (options.dryRun) {
@@ -31358,17 +31738,25 @@ function syncHookScriptsBridge(config, sourceRoot, options, logger, destination,
     return { component: "hooks", status: "skipped-current", path: destination };
   }
   if (artifactClass === "managed-stale" && isOurStaleSymlink(destination, /* @__PURE__ */ new Set([destination]), config)) {
-    fs40.unlinkSync(destination);
+    fs41.unlinkSync(destination);
   } else if (artifactClass === "unmanaged-conflict" && !handleConflict6(destination, config, options, logger, manifest, scopePath)) {
     return { component: "hooks", status: "conflict", path: destination };
   } else if (artifactClass === "managed-symlink") {
-    fs40.unlinkSync(destination);
+    fs41.unlinkSync(destination);
   }
   ensureDir(path41.dirname(destination));
   createRelativeSymlink(source, destination, "dir");
   return { component: "hooks", status: "success", path: destination };
 }
-function syncHooks6(config, sourceRoot, options, logger, destination) {
+function hookScriptsDir(scriptsBridge) {
+  const globalBridge = resolveTargetPath("~/.agents/hooks");
+  if (path41.resolve(scriptsBridge) === path41.resolve(globalBridge)) {
+    return GLOBAL_HOOK_SCRIPTS_DIR;
+  }
+  const relative = path41.relative(process.cwd(), scriptsBridge);
+  return relative.startsWith("..") || path41.isAbsolute(relative) ? path41.join(scriptsBridge, "scripts") : `"$CLAUDE_PROJECT_DIR"/${path41.posix.join(relative.split(path41.sep).join("/"), "scripts")}`;
+}
+function syncHooks6(config, sourceRoot, options, logger, destination, scriptsBridge) {
   const hooksDir = resolveHooksSourceDir(sourceRoot, config);
   if (!hooksSourceExists(sourceRoot, config)) {
     return skippedMissingSource6("hooks", hooksDir);
@@ -31380,14 +31768,15 @@ function syncHooks6(config, sourceRoot, options, logger, destination) {
   const settings = readJsonObject4(destination);
   const sourceHooks = loadSourceHooks(
     hooksDir,
-    resolveKitHookNames(sourceRoot)
+    resolveKitHookNames(sourceRoot),
+    hookScriptsDir(scriptsBridge)
   );
   settings.hooks = markManaged(sourceHooks.hooks ?? {});
   const changed = writeSharedFile(
     destination,
     settings,
     stringifyJson3,
-    !fs40.existsSync(destination),
+    !fs41.existsSync(destination),
     logger
   );
   return {
@@ -31398,7 +31787,7 @@ function syncHooks6(config, sourceRoot, options, logger, destination) {
 }
 function syncMcp6(config, sourceRoot, options, logger, destination) {
   const source = path41.resolve(sourceRoot, config.source.mcp);
-  if (!fs40.existsSync(source)) {
+  if (!fs41.existsSync(source)) {
     return skippedMissingSource6("mcp", source);
   }
   if (options.dryRun) {
@@ -31423,7 +31812,7 @@ function syncMcp6(config, sourceRoot, options, logger, destination) {
     destination,
     hostConfig,
     stringifyJson3,
-    !fs40.existsSync(destination),
+    !fs41.existsSync(destination),
     logger
   );
   return {
@@ -31434,7 +31823,7 @@ function syncMcp6(config, sourceRoot, options, logger, destination) {
 }
 function syncSettings2(config, sourceRoot, options, logger, destination) {
   const source = path41.resolve(sourceRoot, config.source.settings);
-  if (!fs40.existsSync(source)) {
+  if (!fs41.existsSync(source)) {
     return skippedMissingSource6("settings", source);
   }
   if (options.dryRun) {
@@ -31452,7 +31841,7 @@ function syncSettings2(config, sourceRoot, options, logger, destination) {
     destination,
     settings,
     stringifyJson3,
-    !fs40.existsSync(destination),
+    !fs41.existsSync(destination),
     logger
   );
   return {
@@ -31477,11 +31866,11 @@ function handleConflict6(destination, config, options, logger, manifest, scopePa
       backupFile(destination, manifest);
       writeManifest(scopePath, manifest);
     } else {
-      fs40.renameSync(destination, `${destination}.bak.${Date.now()}`);
+      fs41.renameSync(destination, `${destination}.bak.${Date.now()}`);
     }
     return true;
   }
-  fs40.rmSync(destination, { recursive: true, force: true });
+  fs41.rmSync(destination, { recursive: true, force: true });
   return true;
 }
 function skippedMissingSource6(component, source) {
@@ -31493,16 +31882,16 @@ function skippedMissingSource6(component, source) {
 }
 function isSymlinkTo6(linkPath, source) {
   try {
-    return fs40.realpathSync(linkPath) === fs40.realpathSync(source);
+    return fs41.realpathSync(linkPath) === fs41.realpathSync(source);
   } catch {
     return false;
   }
 }
 function readJsonObject4(filePath) {
-  if (!fs40.existsSync(filePath)) {
+  if (!fs41.existsSync(filePath)) {
     return {};
   }
-  const parsed = JSON.parse(fs40.readFileSync(filePath, "utf8"));
+  const parsed = JSON.parse(fs41.readFileSync(filePath, "utf8"));
   return isRecord5(parsed) ? parsed : {};
 }
 function markManaged(value) {
@@ -31698,6 +32087,31 @@ async function runSyncCommand(options, logger) {
       throwUnrecognizedTarget(target);
     }
   }
+  if (kitInfo) {
+    reportHookRejections(
+      lossReport,
+      targets,
+      path42.resolve(kitInfo.path, "hooks"),
+      kitInfo.components.hooks.declared
+    );
+    const hooksConflict = reportHooksSourceConflict(
+      lossReport,
+      targets,
+      path42.resolve(kitInfo.path, "hooks"),
+      kitInfo.components.hooks.declared
+    );
+    if (hooksConflict) {
+      logger.warn(hooksConflict);
+    }
+    if (syncOptions.scope === "project") {
+      reportProjectScopeScriptPath(
+        lossReport,
+        targets,
+        path42.resolve(kitInfo.path, "hooks"),
+        kitInfo.components.hooks.declared
+      );
+    }
+  }
   writeLossReport(options.lossReport, lossReport);
   printOutcomeTable(results);
   if (kitInfo && kitSync && !options.dryRun) {
@@ -31764,13 +32178,6 @@ function colorStatus(status) {
   }
   return source_default.yellow(status);
 }
-function writeLossReport(filePath, report) {
-  if (!filePath) {
-    return;
-  }
-  fs41.writeFileSync(filePath, `${JSON.stringify(report, null, 2)}
-`);
-}
 function prepareKitManifest(scope, projectRoot, kitInfo) {
   const scopePath = resolveScopePath(scope, projectRoot);
   const manifest = readManifest(scopePath) ?? createEmptyManifest(kitInfo.archetype, kitInfo.kitFormat, scope);
@@ -31810,7 +32217,7 @@ function updateManifest(kitInfo, kitSync) {
 }
 function resolveKitFilePath(kitPath, relativePath) {
   const fullPath = path42.join(kitPath, relativePath);
-  return fs41.existsSync(fullPath) ? fullPath : null;
+  return fs42.existsSync(fullPath) ? fullPath : null;
 }
 function cleanupRemovedManagedArtifacts(config, mappings, targets, options, removedSourcePaths, logger) {
   if (removedSourcePaths.length === 0 || !mappings) {
@@ -31857,7 +32264,9 @@ function componentForRemovedSource(relativePath, config) {
   if (relativePath.startsWith("rules/")) {
     return "rules";
   }
-  if (relativePath === hooksSourceLabel(config)) {
+  if (relativePath.startsWith(
+    `${normalizeManagedSourcePath(config.source.hooks.replace(/\\/gu, "/"))}/`
+  )) {
     return "hooks";
   }
   if (relativePath === mcpSourceLabel(config)) {
@@ -32126,17 +32535,17 @@ function cleanupRemovedClineArtifact(relativePath, paths, logger) {
   }
 }
 function removeManagedCompiledArtifact2(artifactPath, expectedTarget, expectedSource, logger) {
-  if (!fs41.existsSync(artifactPath)) {
+  if (!fs42.existsSync(artifactPath)) {
     return;
   }
-  if (!fs41.statSync(artifactPath).isFile()) {
+  if (!fs42.statSync(artifactPath).isFile()) {
     return;
   }
-  const marker = extractProvenanceMarker(fs41.readFileSync(artifactPath, "utf8"));
+  const marker = extractProvenanceMarker(fs42.readFileSync(artifactPath, "utf8"));
   if (marker?.source !== expectedSource || marker.target !== expectedTarget) {
     return;
   }
-  fs41.rmSync(artifactPath, { force: true });
+  fs42.rmSync(artifactPath, { force: true });
   logger.verbose(`  removed stale target artifact: ${artifactPath}`);
 }
 function removeManagedCopilotMcpArtifact2(artifactPath, expectedSource, logger) {
@@ -32167,10 +32576,10 @@ function removeManagedCodexHooksArtifact2(artifactPath, expectedSource, logger)
   logger.verbose(`  removed stale target artifact: ${artifactPath}`);
 }
 function removeManagedCodexMcpArtifact2(artifactPath, expectedSource, logger) {
-  if (!fs41.existsSync(artifactPath)) {
+  if (!fs42.existsSync(artifactPath)) {
     return;
   }
-  const content = fs41.readFileSync(artifactPath, "utf8");
+  const content = fs42.readFileSync(artifactPath, "utf8");
   const startMarker = "# tangyr: managed mcp start";
   const endMarker = "# tangyr: managed mcp end";
   const startIndex = content.indexOf(startMarker);
@@ -32187,19 +32596,19 @@ function removeManagedCodexMcpArtifact2(artifactPath, expectedSource, logger) {
   const after = content.slice(endIndex + endMarker.length).trimStart();
   const cleaned = [before, after].filter((entry) => entry.length > 0).join("\n\n");
   if (cleaned.length === 0) {
-    fs41.rmSync(artifactPath, { force: true });
+    fs42.rmSync(artifactPath, { force: true });
   } else {
-    fs41.writeFileSync(artifactPath, `${cleaned}
+    fs42.writeFileSync(artifactPath, `${cleaned}
 `);
   }
   logger.verbose(`  removed stale target artifact: ${artifactPath}`);
 }
 function readJsonObject5(filePath) {
-  if (!fs41.existsSync(filePath)) {
+  if (!fs42.existsSync(filePath)) {
     return null;
   }
   try {
-    const parsed = JSON.parse(fs41.readFileSync(filePath, "utf8"));
+    const parsed = JSON.parse(fs42.readFileSync(filePath, "utf8"));
     return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
   } catch {
     return null;
@@ -32213,10 +32622,10 @@ function readJsonMetadata(value) {
 }
 function writeJsonOrRemove2(filePath, parsed) {
   if (isEmptyJsonValue2(parsed)) {
-    fs41.rmSync(filePath, { force: true });
+    fs42.rmSync(filePath, { force: true });
     return;
   }
-  fs41.writeFileSync(filePath, `${JSON.stringify(parsed, null, 2)}
+  fs42.writeFileSync(filePath, `${JSON.stringify(parsed, null, 2)}
 `);
 }
 function isEmptyJsonValue2(value) {
@@ -32276,7 +32685,7 @@ function removeManagedHookEntries(value, expectedSource) {
 }
 
 // src/commands/validate.ts
-import fs42 from "fs";
+import fs43 from "fs";
 import path43 from "path";
 var SUPPORTED_KIT_FORMATS2 = [1];
 var SUPPORTED_DISCIPLINE_VERSIONS = [
@@ -32303,6 +32712,14 @@ var FRONTMATTER_REQUIRED_FIELDS = {
   rules: [],
   hooks: ["name", "description", "events"]
 };
+var CANONICAL_SKILL_SUBFOLDERS = [
+  "assets",
+  "references",
+  "schemas",
+  "scripts",
+  "tests",
+  "evals"
+];
 function runValidateCommand(options, logger) {
   const { kitInfo } = resolveRuntime(options, import.meta.url);
   if (!kitInfo) {
@@ -32315,16 +32732,26 @@ function runValidateCommand(options, logger) {
   const result = validateKit(kitInfo);
   if (options.json) {
     logger.info(JSON.stringify(result, null, 2));
-  } else if (result.conformant) {
-    logger.info(
-      `validate: OK (kit '${kitInfo.name}' conforms to kitFormat ${kitInfo.kitFormat})`
-    );
   } else {
-    logger.error(
-      `validate: FAILED (${result.violations.length} violation${result.violations.length === 1 ? "" : "s"})`
-    );
-    for (const v2 of result.violations) {
-      logger.error(`  [${v2.code}] ${v2.location}: ${v2.message}`);
+    if (result.conformant) {
+      logger.info(
+        `validate: OK (kit '${kitInfo.name}' conforms to kitFormat ${kitInfo.kitFormat})`
+      );
+    } else {
+      logger.error(
+        `validate: FAILED (${result.violations.length} violation${result.violations.length === 1 ? "" : "s"})`
+      );
+      for (const v2 of result.violations) {
+        logger.error(`  [${v2.code}] ${v2.location}: ${v2.message}`);
+      }
+    }
+    if (result.notices.length > 0) {
+      logger.warn(
+        `validate: ${result.notices.length} notice${result.notices.length === 1 ? "" : "s"} (not violations; the verdict above stands)`
+      );
+      for (const n7 of result.notices) {
+        logger.warn(`  [${n7.code}] ${n7.location}: ${n7.message}`);
+      }
     }
   }
   if (!result.conformant) {
@@ -32341,11 +32768,60 @@ function validateKit(kitInfo) {
   violations.push(...checkComponentFrontmatter(kitInfo));
   violations.push(...checkReservedRootNames(kitInfo));
   violations.push(...checkHumanOnlyCommandInvocation(kitInfo));
+  violations.push(...checkHookDeclarations(kitInfo));
+  collect(violations, checkHooksSourceForm(kitInfo));
   return {
     conformant: violations.length === 0,
-    violations
+    violations,
+    notices: checkSkillSubfolderNames(kitInfo)
   };
 }
+function checkSkillSubfolderNames(kit) {
+  const notices = [];
+  const canonical = new Set(CANONICAL_SKILL_SUBFOLDERS);
+  for (const name of kit.components.skills.declared) {
+    const skillDir = path43.join(kit.path, "skills", name);
+    let entries;
+    try {
+      entries = fs43.readdirSync(skillDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith(".") || canonical.has(entry.name)) {
+        continue;
+      }
+      notices.push({
+        code: "skill-subfolder-unrecognized",
+        location: `skills/${name}/${entry.name}/`,
+        message: `skills: '${name}' contains a subfolder '${entry.name}' that the contract does not enumerate. The recognized names are ${CANONICAL_SKILL_SUBFOLDERS.join(", ")}. This is not a violation, and nothing is rejected: the CLI carries the whole skill folder to local targets either way. It is reported so a convention stays visible rather than drifting silently.`
+      });
+    }
+  }
+  return notices;
+}
+function checkHooksSourceForm(kit) {
+  const hooksDir = path43.join(kit.path, "hooks");
+  const message = describeHooksSourceConflict(
+    hooksDir,
+    kit.components.hooks.declared
+  );
+  return message ? {
+    code: "hooks-source-ambiguous",
+    location: "hooks/",
+    message
+  } : null;
+}
+function checkHookDeclarations(kit) {
+  const hooksDir = path43.join(kit.path, "hooks");
+  return collectHookRejections(hooksDir, kit.components.hooks.declared).map(
+    (r) => ({
+      code: "hook-declaration-invalid",
+      location: `hooks/${path43.basename(r.file)}`,
+      message: `hooks: '${path43.basename(r.file, ".md")}' was rejected at '${r.field}' \u2014 ${r.reason}. Until this is fixed the hook is not installed on any target; install and sync report it as an error-severity loss and exit 3. To fix: correct the field named above in this file.`
+    })
+  );
+}
 function collect(violations, v2) {
   if (v2) violations.push(v2);
 }
@@ -32360,16 +32836,19 @@ function checkKitFormatSupported(kit) {
   return null;
 }
 function checkEntrypointExists(kit) {
-  const entrypoint = "CLAUDE.md";
+  const declared = kit.entrypoint;
+  const entrypoint = declared ?? DEFAULT_ENTRYPOINT;
   const entrypointPath = path43.join(kit.path, entrypoint);
-  if (!fs42.existsSync(entrypointPath)) {
-    return {
-      code: "entrypoint-missing",
-      location: entrypoint,
-      message: `entrypoint '${entrypoint}' does not exist at the kit root`
-    };
+  if (fs43.existsSync(entrypointPath)) {
+    return null;
   }
-  return null;
+  const legacyPresent = declared === void 0 && fs43.existsSync(path43.join(kit.path, LEGACY_ENTRYPOINT));
+  const remedy = legacyPresent ? `This kit has '${LEGACY_ENTRYPOINT}' but not '${DEFAULT_ENTRYPOINT}'. Until now validate looked for '${LEGACY_ENTRYPOINT}' unconditionally; it now reads the manifest's 'entrypoint', defaulting to '${DEFAULT_ENTRYPOINT}' \u2014 the contract's canonical orientation document, of which '${LEGACY_ENTRYPOINT}' is a target translation. To fix: either add "entrypoint: ${LEGACY_ENTRYPOINT}" to tangyr-kit.yaml to keep the current filename, or rename '${LEGACY_ENTRYPOINT}' to '${DEFAULT_ENTRYPOINT}'.` : declared === void 0 ? `No 'entrypoint' is declared in tangyr-kit.yaml, so '${DEFAULT_ENTRYPOINT}' is expected at the kit root. To fix: create it, or declare the file you use with "entrypoint: <filename>".` : `tangyr-kit.yaml declares "entrypoint: ${declared}", and no such file exists at the kit root. To fix: create it, or correct the declaration.`;
+  return {
+    code: "entrypoint-missing",
+    location: entrypoint,
+    message: `entrypoint '${entrypoint}' does not exist at the kit root. ${remedy}`
+  };
 }
 function checkDisciplineVersionSupported(kit) {
   if (!SUPPORTED_DISCIPLINE_VERSIONS.includes(kit.discipline.version)) {
@@ -32420,7 +32899,7 @@ function checkComponentFrontmatter(kit) {
     for (const name of kit.components[cat].declared) {
       if (missingSet.has(name)) continue;
       const filePath = cat === "skills" ? path43.join(kit.path, cat, name, "SKILL.md") : path43.join(kit.path, cat, `${name}.md`);
-      if (!fs42.existsSync(filePath)) continue;
+      if (!fs43.existsSync(filePath)) continue;
       const relPath = path43.relative(kit.path, filePath);
       try {
         const { data } = parseMarkdownFrontmatter(filePath);
@@ -32446,10 +32925,10 @@ function checkComponentFrontmatter(kit) {
 }
 function checkReservedRootNames(kit) {
   const violations = [];
-  if (!fs42.existsSync(kit.path) || !fs42.statSync(kit.path).isDirectory()) {
+  if (!fs43.existsSync(kit.path) || !fs43.statSync(kit.path).isDirectory()) {
     return violations;
   }
-  const entries = fs42.readdirSync(kit.path, { withFileTypes: true });
+  const entries = fs43.readdirSync(kit.path, { withFileTypes: true });
   for (const entry of entries) {
     if (RESERVED_ROOT_NAMES.includes(entry.name)) {
       violations.push({
@@ -32467,7 +32946,7 @@ function checkHumanOnlyCommandInvocation(kit) {
   for (const name of kit.components.commands.declared) {
     if (missingSet.has(name)) continue;
     const filePath = path43.join(kit.path, "commands", `${name}.md`);
-    if (!fs42.existsSync(filePath)) continue;
+    if (!fs43.existsSync(filePath)) continue;
     let data;
     try {
       ({ data } = parseMarkdownFrontmatter(filePath));
@@ -32489,7 +32968,7 @@ function checkHumanOnlyCommandInvocation(kit) {
 }
 
 // src/commands/verify.ts
-import fs43 from "fs";
+import fs44 from "fs";
 import path44 from "path";
 function runVerifyCommand(options, logger) {
   const { config, configDir, sourceRoot, kitInfo } = resolveRuntime(
@@ -32582,7 +33061,7 @@ function verifyClaudeCodeGlobalRoots(roots, manifestKeys, mappings) {
         continue;
       }
       const fullPath = subPath ? path44.join(slotPath, subPath) : slotPath;
-      if (!fs43.existsSync(fullPath)) {
+      if (!fs44.existsSync(fullPath)) {
         failures.push(
           `claude-code/${slot}${subPath ? `/${subPath}` : ""} missing in root ${root}: ${fullPath}`
         );
@@ -32712,7 +33191,7 @@ function buildProgram() {
   ).option(
     "--json",
     `Emit {"degraded": true} on stderr only when this resolution fell back to a warm cache after a network failure; otherwise this flag has no effect and output is unchanged \u2014 unlike --json on other commands, which always replaces the command's entire output.`
-  ).option("--tools <list>", "Comma-separated list of target tools").option("--scope <scope>", "Installation scope: global or project").option(
+  ).option("--tools <list>", "Comma-separated list of target tools").option("--loss-report <path>", "Write semantic loss report JSON to a file").option("--scope <scope>", "Installation scope: global or project").option(
     "--ignore-errors",
     "Suppress exit code 3 when error-severity loss entries are present"
   ).action(