skillset 0.13.5 → 0.14.0

package/dist/cli.js

@@ -7024,10 +7024,11 @@ var require_dist = __commonJS((exports) => {
 });
 
 // apps/skillset/src/cli-core.ts
-import { mkdir as mkdir11, writeFile as writeFile11 } from "fs/promises";
-import { basename as basename8, dirname as dirname15, resolve as resolve10 } from "path";
+import { mkdir as mkdir11, writeFile as writeFile12 } from "fs/promises";
+import { basename as basename9, dirname as dirname16, resolve as resolve10 } from "path";
 
 // packages/core/src/authoring.ts
+import { readFile as readFile10, writeFile as writeFile4 } from "fs/promises";
 import { resolve as resolve3, relative as relative11 } from "path";
 
 // packages/core/src/path.ts
@@ -7096,7 +7097,7 @@ var skillsetFeatureRegistry = defineFeatureRegistry([
     id: "activation-probes",
     kind: "workflow",
     renderOwner: "apps/skillset/src/test-runner.ts",
-    sourceShape: ".skillset/config.yaml tests.<name>.activation[]",
+    sourceShape: "workspace skillset.yaml tests.<name>.activation[]",
     status: "implemented",
     summary: "Compiles target-aware manual activation probe assets inside isolated test runs.",
     targetSupport: notTargetRuntime(),
@@ -7109,7 +7110,7 @@ var skillsetFeatureRegistry = defineFeatureRegistry([
     id: "changes",
     kind: "change-management",
     renderOwner: "apps/skillset/src/change-entries.ts",
-    sourceShape: ".skillset/changes/pending/*.yaml and .skillset/changes/history/*.jsonl",
+    sourceShape: "workspace changes/*.md and changes/history.jsonl",
     status: "implemented",
     summary: "Tracks source-unit changes, evidence hashes, pending entries, and applied history.",
     targetSupport: notTargetRuntime(),
@@ -7146,7 +7147,7 @@ var skillsetFeatureRegistry = defineFeatureRegistry([
     id: "distributions",
     kind: "workflow",
     renderOwner: "packages/core/src/distribution.ts",
-    sourceShape: ".skillset/config.yaml distributions",
+    sourceShape: "workspace skillset.yaml distributions",
     status: "implemented",
     summary: "Plans post-build distribution of generated projections without writing or activating runtimes.",
     targetSupport: notTargetRuntime(),
@@ -7550,7 +7551,7 @@ var skillsetFeatureRegistry = defineFeatureRegistry([
     id: "releases",
     kind: "change-management",
     renderOwner: "apps/skillset/src/release.ts",
-    sourceShape: ".skillset/releases/*.jsonl, .skillset/release-state.json, generated changelogs",
+    sourceShape: "workspace changes/releases.jsonl, changes/state.json, generated changelogs",
     status: "implemented",
     summary: "Applies pending changes into versions, release history, changelogs, and generated metadata.",
     targetSupport: bothTargets("metadata_only"),
@@ -8190,7 +8191,7 @@ function validateWorkspaceConfigDocument(record, label) {
   rejectTargetsKey(record, label);
   for (const key of Object.keys(record)) {
     if (!WORKSPACE_CONFIG_TOP_LEVEL_KEYS.has(key)) {
-      throw new Error(`skillset: unsupported workspace config key ${key} in ${label}; ` + "move source identity and compatibility metadata to .skillset/src/skillset.yaml");
+      throw new Error(`skillset: unsupported workspace config key ${key} in ${label}; ` + "move source identity and compatibility metadata to the workspace manifest");
     }
   }
 }
@@ -9631,7 +9632,7 @@ function sourceWarningDiagnostic(message) {
 }
 
 // packages/core/src/build.ts
-import { mkdir as mkdir3, readdir as readdir4, readFile as readFile8, rm, stat as stat7, writeFile as writeFile3 } from "fs/promises";
+import { mkdir as mkdir3, readdir as readdir5, readFile as readFile8, rm, stat as stat7, writeFile as writeFile3 } from "fs/promises";
 import { dirname as dirname7, join as join9, relative as relative9 } from "path";
 
 // packages/core/src/render-result-policy.ts
@@ -10183,10 +10184,10 @@ function isRecord(value) {
 }
 
 // packages/core/src/render.ts
-import { readFileSync, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
-import { readdir as readdir2, readFile as readFile5, stat as stat4 } from "fs/promises";
+import { readFileSync as readFileSync2, readdirSync as readdirSync3, statSync as statSync2 } from "fs";
+import { readdir as readdir3, readFile as readFile5, stat as stat4 } from "fs/promises";
 import { createHash as createHash3 } from "crypto";
-import { basename, dirname as dirname4, join as join6, relative as relative7 } from "path";
+import { basename as basename2, dirname as dirname4, join as join6, relative as relative7 } from "path";
 
 // packages/transforms/src/registry.ts
 var transformEntries = new Map;
@@ -11339,29 +11340,71 @@ function isResourceReference(value) {
 }
 
 // packages/core/src/preprocess.ts
-import { readFile as readFile3 } from "fs/promises";
-import { dirname as dirname2, isAbsolute, join as join3, relative as relative5, resolve as resolve2, sep as sep2 } from "path";
+import { readdirSync as readdirSync2, readFileSync } from "fs";
+import { readdir as readdir2, readFile as readFile3 } from "fs/promises";
+import {
+  basename,
+  dirname as dirname2,
+  isAbsolute,
+  join as join3,
+  relative as relative5,
+  resolve as resolve2,
+  sep as sep2
+} from "path";
 async function preprocessText(content, context) {
   if (isPreprocessDisabled(context.frontmatter)) {
     return normalizeText(content);
   }
-  let expanded = normalizeText(content);
+  const escapedTokens = [];
+  let expanded = escapeTripleBraceTokens(normalizeText(content), escapedTokens);
   expanded = await expandPartials(expanded, context);
-  expanded = expandVariables(expanded, context);
-  return expanded;
+  assertNoRetiredPartialSyntax(expanded, context);
+  expanded = escapeTripleBraceTokens(expanded, escapedTokens);
+  expanded = await expandVariables(expanded, context);
+  return restoreTripleBraceTokens(expanded, escapedTokens);
+}
+function formatPreprocessDependency(rootPath, dependency) {
+  if (isTreePreprocessDependency(dependency))
+    return dependency;
+  return normalizePath2(relative5(rootPath, dependency));
+}
+function readPreprocessDependencySync(rootPath, dependency) {
+  const tree = parseTreePreprocessDependency(dependency);
+  if (tree !== undefined) {
+    return renderDirectoryTreeSync(join3(rootPath, tree.path), tree.depth);
+  }
+  return readFileSync(join3(rootPath, dependency));
+}
+function isTreePreprocessDependency(dependency) {
+  return parseTreePreprocessDependency(dependency) !== undefined;
+}
+function parseTreePreprocessDependency(dependency) {
+  if (!dependency.startsWith("tree:"))
+    return;
+  const separator = dependency.lastIndexOf(":");
+  if (separator <= "tree:".length)
+    return;
+  const path = dependency.slice("tree:".length, separator);
+  const depth = Number(dependency.slice(separator + 1));
+  if (!Number.isInteger(depth) || depth < 0 || depth > 8)
+    return;
+  return { depth, path };
 }
 function isPreprocessDisabled(frontmatter) {
   const skillset = frontmatter.skillset;
   return typeof skillset === "object" && skillset !== null && !Array.isArray(skillset) && skillset.preprocess === false;
 }
 async function expandPartials(content, context) {
-  const partialPattern = /\{\{\s*>\s*([^}\s]+)\s*\}\}/g;
+  assertNoRetiredPartialSyntax(content, context);
+  const partialPattern = /\{\{\s*([^}\s]+)\s*\}\}/g;
   let expanded = "";
   let cursor = 0;
   for (const match of content.matchAll(partialPattern)) {
     const [token, specifier] = match;
     if (specifier === undefined)
       continue;
+    if (!isPartialSpecifier(specifier))
+      continue;
     expanded += content.slice(cursor, match.index);
     expanded += normalizeText(await readPartial(specifier, context));
     cursor = match.index + token.length;
@@ -11377,21 +11420,227 @@ async function readPartial(specifier, context) {
     throw new Error(`skillset: failed to read partial ${specifier} in ${source2}: ${message}`);
   }
 }
-function expandVariables(content, context) {
-  return content.replace(/\{\{\s*([^}\s]+)\s*\}\}/g, (token, key) => {
-    if (key.startsWith("this.")) {
-      const field = key.slice("this.".length);
-      const value2 = readString(context.frontmatter, field);
-      if (value2 === undefined) {
-        throw new Error(`skillset: missing this.${field} reference in ${relative5(context.rootPath, context.sourcePath)}`);
-      }
-      return value2;
+async function expandVariables(content, context) {
+  const variablePattern = /\{\{\s*([^{}]*?)\s*\}\}/g;
+  let expanded = "";
+  let cursor = 0;
+  for (const match of content.matchAll(variablePattern)) {
+    const [token, key] = match;
+    if (key === undefined)
+      continue;
+    expanded += content.slice(cursor, match.index);
+    expanded += await resolveVariable(token, key.trim(), context, {
+      inMarkdownCodeBlock: isMarkdownSource(context.sourcePath) && isInsideFencedCodeBlock(content, match.index),
+      markdown: isMarkdownSource(context.sourcePath)
+    });
+    cursor = match.index + token.length;
+  }
+  return `${expanded}${content.slice(cursor)}`;
+}
+async function resolveVariable(token, key, context, renderContext) {
+  if (key.startsWith("this.")) {
+    const field = key.slice("this.".length);
+    const value = readPathValue(context.frontmatter, field);
+    if (value === undefined) {
+      throw new Error(`skillset: missing this.${field} reference in ${relative5(context.rootPath, context.sourcePath)}`);
     }
-    const value = context.variables?.[key];
+    return stringifyPreprocessValue(value, `this.${field}`, context, renderContext);
+  }
+  const explicitValue = context.variables?.[key];
+  if (explicitValue !== undefined)
+    return explicitValue;
+  if (key.startsWith("skillset.")) {
+    const value = skillsetVariable(key, context);
+    if (value !== undefined)
+      return value;
+  }
+  if (key.startsWith("parent.")) {
+    const value = await parentVariable(key, context);
     if (value !== undefined)
       return value;
-    throw new Error(`skillset: unknown preprocess variable ${token} in ${relative5(context.rootPath, context.sourcePath)}`);
+  }
+  throw new Error(`skillset: unknown preprocess variable ${token} in ${relative5(context.rootPath, context.sourcePath)}`);
+}
+function readPathValue(record, path) {
+  let current = record;
+  for (const segment of path.split(".")) {
+    if (segment.length === 0)
+      return;
+    if (!isJsonRecord2(current))
+      return;
+    current = current[segment];
+  }
+  return current;
+}
+function stringifyPreprocessValue(value, key, context, renderContext) {
+  if (typeof value === "string")
+    return value;
+  if (typeof value === "number" || typeof value === "boolean")
+    return String(value);
+  if (value === null)
+    return "null";
+  try {
+    const json = JSON.stringify(value);
+    if (isJsonRecord2(value) || Array.isArray(value)) {
+      return renderJsonValue(json, JSON.stringify(value, null, 2), renderContext);
+    }
+    return json;
+  } catch {
+    throw new Error(`skillset: cannot stringify ${key} reference in ${relative5(context.rootPath, context.sourcePath)}`);
+  }
+}
+function renderJsonValue(compactJson, prettyJson, renderContext) {
+  if (!renderContext.markdown)
+    return compactJson;
+  if (renderContext.inMarkdownCodeBlock)
+    return prettyJson;
+  return `\`\`\`json
+${prettyJson}
+\`\`\``;
+}
+function skillsetVariable(key, context) {
+  if (key === "skillset.source_path") {
+    return normalizePath2(relative5(context.rootPath, context.sourcePath));
+  }
+  if (key === "skillset.source_dir") {
+    return normalizePath2(relative5(context.rootPath, dirname2(context.sourcePath)));
+  }
+  if (key === "skillset.source_root")
+    return normalizePath2(context.sourceRoot);
+  return;
+}
+async function parentVariable(key, context) {
+  const parentDir = dirname2(context.sourcePath);
+  if (key === "parent.dir")
+    return normalizePath2(relative5(context.rootPath, parentDir));
+  if (key === "parent.name")
+    return basename(parentDir);
+  if (key === "parent.tree")
+    return renderParentTree(parentDir, 2, context);
+  const parsed = parsePreprocessInvocation(key);
+  if (parsed.name === "parent.tree") {
+    return renderParentTree(parentDir, parseParentTreeDepth(parsed, context), context);
+  }
+  return;
+}
+function parsePreprocessInvocation(key) {
+  const [name = "", ...rawArgs] = key.trim().split(/\s+/);
+  const args = new Map;
+  const duplicateArgs = new Set;
+  for (const rawArg of rawArgs) {
+    const separator = rawArg.indexOf(":");
+    if (separator <= 0) {
+      args.set(rawArg, "");
+      continue;
+    }
+    const argName = rawArg.slice(0, separator);
+    if (args.has(argName))
+      duplicateArgs.add(argName);
+    args.set(argName, rawArg.slice(separator + 1));
+  }
+  return { args, duplicateArgs, name };
+}
+function parseParentTreeDepth(invocation, context) {
+  const depth = invocation.args.get("depth");
+  if (invocation.args.size !== 1 || invocation.duplicateArgs.size > 0 || depth === undefined || depth.length === 0) {
+    throw new Error(`skillset: parent.tree in ${relative5(context.rootPath, context.sourcePath)} supports only depth:<0-8>`);
+  }
+  const rawDepth = Number(depth);
+  if (!Number.isInteger(rawDepth) || rawDepth < 0 || rawDepth > 8) {
+    throw new Error(`skillset: parent.tree depth in ${relative5(context.rootPath, context.sourcePath)} must be between 0 and 8`);
+  }
+  return rawDepth;
+}
+async function renderParentTree(parentDir, depth, context) {
+  context.preprocessDependencies?.add(`tree:${normalizePath2(relative5(context.rootPath, parentDir))}:${depth}`);
+  return renderDirectoryTree(parentDir, depth);
+}
+async function renderDirectoryTree(root, depth) {
+  const lines = ["."];
+  if (depth > 0) {
+    lines.push(...await directoryTreeLines(root, depth, ""));
+  }
+  return lines.join(`
+`);
+}
+async function directoryTreeLines(root, depth, indent) {
+  if (depth <= 0)
+    return [];
+  const entries = (await readdir2(root, { withFileTypes: true })).filter((entry) => entry.name !== ".DS_Store").sort((left, right) => {
+    if (left.name < right.name)
+      return -1;
+    if (left.name > right.name)
+      return 1;
+    return 0;
   });
+  const lines = [];
+  for (const entry of entries) {
+    const isDirectory = entry.isDirectory();
+    lines.push(`${indent}- ${entry.name}${isDirectory ? "/" : ""}`);
+    if (isDirectory) {
+      lines.push(...await directoryTreeLines(join3(root, entry.name), depth - 1, `${indent}  `));
+    }
+  }
+  return lines;
+}
+function renderDirectoryTreeSync(root, depth) {
+  const lines = ["."];
+  if (depth > 0) {
+    lines.push(...directoryTreeLinesSync(root, depth, ""));
+  }
+  return lines.join(`
+`);
+}
+function directoryTreeLinesSync(root, depth, indent) {
+  if (depth <= 0)
+    return [];
+  const entries = readdirSync2(root, { withFileTypes: true }).filter((entry) => entry.name !== ".DS_Store").sort((left, right) => {
+    if (left.name < right.name)
+      return -1;
+    if (left.name > right.name)
+      return 1;
+    return 0;
+  });
+  const lines = [];
+  for (const entry of entries) {
+    const isDirectory = entry.isDirectory();
+    lines.push(`${indent}- ${entry.name}${isDirectory ? "/" : ""}`);
+    if (isDirectory) {
+      lines.push(...directoryTreeLinesSync(join3(root, entry.name), depth - 1, `${indent}  `));
+    }
+  }
+  return lines;
+}
+function isJsonRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPartialSpecifier(specifier) {
+  if (specifier.startsWith("this.") || specifier.startsWith("skillset.") || specifier.startsWith("parent.")) {
+    return false;
+  }
+  if (specifier.startsWith("shared:") || specifier.startsWith("root:") || specifier.startsWith("plugin:")) {
+    return true;
+  }
+  return specifier.includes("/") || /^[A-Za-z0-9._-]+\.[A-Za-z0-9._-]+$/.test(specifier);
+}
+function assertNoRetiredPartialSyntax(content, context) {
+  if (!/\{\{\s*>/.test(content))
+    return;
+  throw new Error(`skillset: partials in ${relative5(context.rootPath, context.sourcePath)} use {{shared:path.md}}, {{plugin:path.md}}, or {{relative/path.md}} syntax`);
+}
+function escapeTripleBraceTokens(content, escapedTokens) {
+  return content.replace(/\{\{\{\s*([^{}]+?)\s*\}\}\}/g, (_token, key) => {
+    const marker = `\x00skillset-escaped-${escapedTokens.length}\x00`;
+    escapedTokens.push(`{{${key.trim()}}}`);
+    return marker;
+  });
+}
+function restoreTripleBraceTokens(content, escapedTokens) {
+  let restored = content;
+  for (const [index, value] of escapedTokens.entries()) {
+    restored = restored.replaceAll(`\x00skillset-escaped-${index}\x00`, value);
+  }
+  return restored;
 }
 function resolvePartial(specifier, context) {
   const [scheme, path] = splitSpecifier(specifier);
@@ -11423,6 +11672,35 @@ function normalizeText(content) {
   return content.replaceAll(/\r\n?/g, `
 `);
 }
+function normalizePath2(path) {
+  return path.replaceAll("\\", "/") || ".";
+}
+function isMarkdownSource(path) {
+  return path.endsWith(".md");
+}
+function isInsideFencedCodeBlock(content, index) {
+  const before = content.slice(0, index);
+  let fence;
+  for (const line of before.split(`
+`)) {
+    const match = line.match(/^( {0,3})(`{3,}|~{3,})(.*)$/);
+    if (match === null)
+      continue;
+    const marker = match[2];
+    if (marker === undefined)
+      continue;
+    const char = marker[0];
+    const length = marker.length;
+    if (fence === undefined) {
+      fence = { char, length };
+      continue;
+    }
+    const trailing = match[3] ?? "";
+    if (char === fence.char && length >= fence.length && /^[ \t]*$/.test(trailing))
+      fence = undefined;
+  }
+  return fence !== undefined;
+}
 function resolveInsideScoped(root, candidate, specifier, context) {
   const resolvedRoot = resolve2(root);
   const resolved = resolve2(resolvedRoot, candidate);
@@ -11452,6 +11730,7 @@ import { dirname as dirname3, join as join5, relative as relative6 } from "path"
 import { readFile as readFile4, stat as stat3 } from "fs/promises";
 import { join as join4 } from "path";
 var HISTORY_FILE = "changes/history.jsonl";
+var AMENDMENTS_FILE = "changes/amendments.jsonl";
 async function readAppliedChangeRecords(rootPath, options = {}) {
   const sourceDir = options.sourceDir ?? ".skillset";
   const path = join4(sourceDir, HISTORY_FILE).replaceAll("\\", "/");
@@ -11489,7 +11768,8 @@ async function readAppliedChangeRecords(rootPath, options = {}) {
       sourceHashes: readHistoryEvidence(parsed.evidence, scopes)
     });
   }
-  return entries.sort((left, right) => compareStrings(left.id, right.id));
+  const amended = await applyHistoryAmendments(rootPath, sourceDir, entries);
+  return [...amended].sort((left, right) => compareStrings(left.id, right.id));
 }
 function groupRef(group) {
   if (group === undefined)
@@ -11522,6 +11802,42 @@ function readHistoryGroup(value) {
   const provider = readString(value, "provider");
   return id === undefined ? undefined : { id, ...provider === undefined ? {} : { provider } };
 }
+async function applyHistoryAmendments(rootPath, sourceDir, entries) {
+  const amendments = await readHistoryAmendments(rootPath, sourceDir);
+  if (amendments.size === 0)
+    return entries;
+  return entries.map((entry) => {
+    const amendment = amendments.get(entry.id);
+    return amendment === undefined ? entry : { ...entry, reason: amendment.reason };
+  });
+}
+async function readHistoryAmendments(rootPath, sourceDir) {
+  const path = join4(sourceDir, AMENDMENTS_FILE).replaceAll("\\", "/");
+  const absolutePath = resolveInside(rootPath, path);
+  if (!await exists2(absolutePath))
+    return new Map;
+  const amendments = new Map;
+  const lines = (await readFile4(absolutePath, "utf8")).split(`
+`);
+  for (const [index, line] of lines.entries()) {
+    if (line.trim().length === 0)
+      continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      throw new Error(`skillset: invalid JSON in ${path}:${index + 1}`);
+    }
+    if (!isJsonRecord(parsed))
+      throw new Error(`skillset: expected ${path}:${index + 1} to contain a JSON object`);
+    const id = readString(parsed, "id");
+    const reason = readString(parsed, "reason");
+    if (id === undefined || reason === undefined)
+      continue;
+    amendments.set(id, { reason });
+  }
+  return amendments;
+}
 function readHistoryEvidence(raw, scopes) {
   const evidence = new Map;
   const add = (scope, hash) => {
@@ -12001,13 +12317,13 @@ async function renderPluginSkillFiles(graph, plugin, skill, target, basePath, ou
   const targetSkillFile = join6(targetSkillDir, "SKILL.md");
   const generatedCodexAgentFile = await renderCodexSkillAgentFile(graph, plugin, skill, target, sourceDir, targetSkillDir);
   const generatedCodexToolsFile = renderCodexSkillToolsFile(graph, skill, target, targetSkillDir);
-  const generatedCodexRelativeFiles = new Set([generatedCodexAgentFile, generatedCodexToolsFile].filter((file) => file !== undefined).map((file) => relative7(targetSkillDir, file.path)));
+  const generatedCodexRelativeFiles = new Set([generatedCodexAgentFile?.file, generatedCodexToolsFile].filter((file) => file !== undefined).map((file) => relative7(targetSkillDir, file.path)));
   const rendered = [];
   const renderedRelativeFiles = new Set;
   const skillMarkdown = await renderSkillMarkdown(graph, plugin, skill, target);
   pushSkillRenderedFile(rendered, textFile(targetSkillFile, skillMarkdown.content, relative7(graph.rootPath, skill.sourcePath)), targetSkillDir, renderedRelativeFiles, `${skill.sourcePath}.SKILL.md`);
   if (generatedCodexAgentFile !== undefined) {
-    pushSkillRenderedFile(rendered, generatedCodexAgentFile, targetSkillDir, renderedRelativeFiles, `${skill.sourcePath}.agents/openai.yaml`);
+    pushSkillRenderedFile(rendered, generatedCodexAgentFile.file, targetSkillDir, renderedRelativeFiles, `${skill.sourcePath}.agents/openai.yaml`);
   }
   if (generatedCodexToolsFile !== undefined) {
     pushSkillRenderedFile(rendered, generatedCodexToolsFile, targetSkillDir, renderedRelativeFiles, `${skill.sourcePath}.tools`);
@@ -12032,6 +12348,7 @@ async function renderPluginSkillFiles(graph, plugin, skill, target, basePath, ou
     kind: "plugin-skill",
     outputRoot,
     plugin,
+    preprocessDependencies: skillPreprocessDependencies(skillMarkdown, generatedCodexAgentFile),
     skill,
     sourceDir,
     transforms: skillMarkdown.transforms
@@ -12075,7 +12392,7 @@ async function renderClaudeProjectAgent(graph, agent) {
     preprocessDependencies,
     rootPath: graph.rootPath,
     sourcePath: agent.sourcePath,
-    sourceRoot: join6(graph.sourceDir, "src")
+    sourceRoot: graph.sourceRoot
   });
   const targetPath = join6(targetProjectRoot2(graph, "claude"), "agents", `${agent.outputName}.md`);
   return {
@@ -12111,7 +12428,7 @@ async function renderCodexProjectAgentInstructions(graph, agent, targetOptions,
     preprocessDependencies,
     rootPath: graph.rootPath,
     sourcePath: agent.sourcePath,
-    sourceRoot: join6(graph.sourceDir, "src")
+    sourceRoot: graph.sourceRoot
   });
   const sections = [];
   if (skills !== undefined && skills.length > 0) {
@@ -12124,7 +12441,7 @@ async function renderCodexProjectAgentInstructions(graph, agent, targetOptions,
       preprocessDependencies,
       rootPath: graph.rootPath,
       sourcePath: agent.sourcePath,
-      sourceRoot: join6(graph.sourceDir, "src")
+      sourceRoot: graph.sourceRoot
     });
     if (renderedPrompt.includes("</initial_prompt>")) {
       throw new Error(`skillset: ${relative7(graph.rootPath, agent.sourcePath)} initialPrompt must not contain </initial_prompt>`);
@@ -12139,7 +12456,7 @@ ${renderedPrompt.trimEnd()}
 `;
 }
 function projectAgentPreprocessDependencies(graph, dependencies) {
-  return [...dependencies].sort(compareStrings).map((path) => relative7(graph.rootPath, path));
+  return formattedPreprocessDependencies(graph, dependencies);
 }
 function renderCodexSkillsPreface(targetOptions, skills) {
   const bullets = skills.map((skill) => `- ${skill}`).join(`
@@ -12192,7 +12509,7 @@ async function renderIslandFile(graph, island, targetPath) {
     const content = await renderTextIslandFile(graph, island, targetPath, preprocessDependencies);
     return {
       file: textFile(targetPath, content, relative7(graph.rootPath, island.sourcePath)),
-      preprocessDependencies: [...preprocessDependencies].sort(compareStrings).map((path) => relative7(graph.rootPath, path)),
+      preprocessDependencies: formattedPreprocessDependencies(graph, preprocessDependencies),
       validation: "structured"
     };
   }
@@ -12215,7 +12532,7 @@ async function renderTextIslandFile(graph, island, targetPath, preprocessDepende
       preprocessDependencies,
       rootPath: graph.rootPath,
       sourcePath: island.sourcePath,
-      sourceRoot: join6(graph.sourceDir, "src")
+      sourceRoot: graph.sourceRoot
     });
     return renderValidatedMarkdown(stripSourceFrontmatter(parsed.frontmatter, island.sourcePath), body, `${relative7(graph.rootPath, island.sourcePath)} -> ${targetPath}`);
   }
@@ -12224,7 +12541,7 @@ async function renderTextIslandFile(graph, island, targetPath, preprocessDepende
     preprocessDependencies,
     rootPath: graph.rootPath,
     sourcePath: island.sourcePath,
-    sourceRoot: join6(graph.sourceDir, "src")
+    sourceRoot: graph.sourceRoot
   });
 }
 function rejectIslandTargetEscape(frontmatter, island) {
@@ -12251,13 +12568,13 @@ async function renderStandaloneSkill(graph, skill, target, lockRoots) {
   const targetSkillFile = join6(targetSkillDir, "SKILL.md");
   const generatedCodexAgentFile = await renderCodexSkillAgentFile(graph, undefined, skill, target, sourceDir, targetSkillDir);
   const generatedCodexToolsFile = renderCodexSkillToolsFile(graph, skill, target, targetSkillDir);
-  const generatedCodexRelativeFiles = new Set([generatedCodexAgentFile, generatedCodexToolsFile].filter((file) => file !== undefined).map((file) => relative7(targetSkillDir, file.path)));
+  const generatedCodexRelativeFiles = new Set([generatedCodexAgentFile?.file, generatedCodexToolsFile].filter((file) => file !== undefined).map((file) => relative7(targetSkillDir, file.path)));
   const rendered = [];
   const renderedRelativeFiles = new Set;
   const skillMarkdown = await renderSkillMarkdown(graph, undefined, skill, target);
   pushSkillRenderedFile(rendered, textFile(targetSkillFile, skillMarkdown.content, relative7(graph.rootPath, skill.sourcePath)), targetSkillDir, renderedRelativeFiles, `${skill.sourcePath}.SKILL.md`);
   if (generatedCodexAgentFile !== undefined) {
-    pushSkillRenderedFile(rendered, generatedCodexAgentFile, targetSkillDir, renderedRelativeFiles, `${skill.sourcePath}.agents/openai.yaml`);
+    pushSkillRenderedFile(rendered, generatedCodexAgentFile.file, targetSkillDir, renderedRelativeFiles, `${skill.sourcePath}.agents/openai.yaml`);
   }
   if (generatedCodexToolsFile !== undefined) {
     pushSkillRenderedFile(rendered, generatedCodexToolsFile, targetSkillDir, renderedRelativeFiles, `${skill.sourcePath}.tools`);
@@ -12281,6 +12598,7 @@ async function renderStandaloneSkill(graph, skill, target, lockRoots) {
     graph,
     kind: "standalone-skill",
     outputRoot,
+    preprocessDependencies: skillPreprocessDependencies(skillMarkdown, generatedCodexAgentFile),
     skill,
     sourceDir,
     transforms: skillMarkdown.transforms
@@ -12312,6 +12630,15 @@ function pushSkillRenderedFile(rendered, file, targetSkillDir, renderedRelativeF
 function normalizeRenderedRelativePath(path) {
   return path.replaceAll("\\", "/");
 }
+function formattedPreprocessDependencies(graph, dependencies) {
+  return [...dependencies].map((dependency) => formatPreprocessDependency(graph.rootPath, dependency)).sort(compareStrings);
+}
+function skillPreprocessDependencies(markdown, auxiliary) {
+  return [...new Set([
+    ...markdown.preprocessDependencies,
+    ...auxiliary?.preprocessDependencies ?? []
+  ])].sort(compareStrings);
+}
 async function renderSkillMarkdown(graph, plugin, skill, target) {
   const metadata = skill.metadata;
   const targetOptions = skill.targets[target].options;
@@ -12332,11 +12659,13 @@ async function renderSkillMarkdown(graph, plugin, skill, target) {
       version
     }
   }) : withTargetFrontmatter;
+  const preprocessDependencies = new Set;
   const preprocessedBody = await preprocessText(skill.body, {
     frontmatter: skill.frontmatter,
+    preprocessDependencies,
     rootPath: graph.rootPath,
     sourcePath: skill.sourcePath,
-    sourceRoot: join6(graph.sourceDir, "src"),
+    sourceRoot: graph.sourceRoot,
     ...plugin === undefined ? {} : { pluginPath: plugin.path }
   });
   const dependencyNotice = target === "codex" && plugin !== undefined ? renderCodexDependencyNotice(graph, plugin) : undefined;
@@ -12347,6 +12676,7 @@ ${preprocessedBody}`;
   const translated = target === "codex" && skill.dialect === "claude" ? translateClaudeDialect(linkedBody) : { text: linkedBody, transforms: [] };
   return {
     content: renderValidatedMarkdown(frontmatter, translated.text, `${relative7(graph.rootPath, skill.sourcePath)} -> ${target}`),
+    preprocessDependencies: formattedPreprocessDependencies(graph, preprocessDependencies),
     transforms: translated.transforms
   };
 }
@@ -12380,15 +12710,20 @@ async function renderCodexSkillAgentFile(graph, plugin, skill, target, sourceDir
     return;
   const sourceOpenAiPath = join6(sourceDir, "agents/openai.yaml");
   const hasSourceOpenAi = await exists3(sourceOpenAiPath);
+  const preprocessDependencies = new Set;
   const source2 = hasSourceOpenAi ? parseYamlRecord(await preprocessText(await readFile5(sourceOpenAiPath, "utf8"), {
     frontmatter: skill.frontmatter,
+    preprocessDependencies,
     rootPath: graph.rootPath,
     sourcePath: sourceOpenAiPath,
-    sourceRoot: join6(graph.sourceDir, "src"),
+    sourceRoot: graph.sourceRoot,
     ...plugin === undefined ? {} : { pluginPath: plugin.path }
   }), sourceOpenAiPath) : {};
   const merged = mergeRecords(source2, generated);
-  return textFile(join6(targetSkillDir, "agents/openai.yaml"), renderValidatedYaml(merged, `${relative7(graph.rootPath, sourceOpenAiPath)} -> ${join6(targetSkillDir, "agents/openai.yaml")}`), relative7(graph.rootPath, sourceOpenAiPath));
+  return {
+    file: textFile(join6(targetSkillDir, "agents/openai.yaml"), renderValidatedYaml(merged, `${relative7(graph.rootPath, sourceOpenAiPath)} -> ${join6(targetSkillDir, "agents/openai.yaml")}`), relative7(graph.rootPath, sourceOpenAiPath)),
+    preprocessDependencies: formattedPreprocessDependencies(graph, preprocessDependencies)
+  };
 }
 function renderCodexSkillAgentConfig(skill, label) {
   const implicitInvocation = readImplicitInvocation(skill.frontmatter, "codex", label);
@@ -12424,7 +12759,8 @@ async function renderClaudeRules(graph, lockRoots) {
   const rendered = [];
   for (const rule of graph.rules.filter((sourceRule) => sourceRule.targets.claude.enabled)) {
     const targetFile = join6(CLAUDE_RULES_OUTPUT_ROOT, rule.relativePath);
-    const file = textFile(targetFile, await renderClaudeRuleMarkdown(graph, rule, targetFile), relative7(graph.rootPath, rule.sourcePath));
+    const markdown = await renderClaudeRuleMarkdown(graph, rule, targetFile);
+    const file = textFile(targetFile, markdown.content, relative7(graph.rootPath, rule.sourcePath));
     rendered.push(file);
     lockRootsFor(lockRoots, CLAUDE_RULES_OUTPUT_ROOT, "claude").items.push(lockItemForRule({
       files: [file],
@@ -12432,7 +12768,8 @@ async function renderClaudeRules(graph, lockRoots) {
       name: rule.id,
       outputRoot: CLAUDE_RULES_OUTPUT_ROOT,
       outputPath: targetFile,
-      sourceHash: hashTextRule(rule),
+      preprocessDependencies: markdown.preprocessDependencies,
+      sourceHash: hashTextRule(rule, markdown.preprocessDependencies, graph.rootPath),
       ...rule.sourceOrigin === undefined ? {} : { sourceOrigin: rule.sourceOrigin },
       sourcePath: relative7(graph.rootPath, rule.sourcePath)
     }));
@@ -12450,7 +12787,8 @@ async function renderCodexAgentsFiles(graph, lockRoots) {
   const rendered = [];
   for (const [destination, rules] of [...destinations.entries()].sort(([left], [right]) => compareStrings(left, right))) {
     const markdown = await renderCodexAgentsMarkdown(graph, rules, destination);
-    const file = textFile(destination, markdown.content, `${graph.sourceDir}/${graph.instructionsDir}`);
+    const sourcePath = workspaceRelativeSourcePath(graph, graph.instructionsDir);
+    const file = textFile(destination, markdown.content, sourcePath);
     rendered.push(file);
     lockRootsFor(lockRoots, WORKSPACE_LOCK_ROOT, "workspace").items.push(lockItemForRule({
       files: [file],
@@ -12458,9 +12796,10 @@ async function renderCodexAgentsFiles(graph, lockRoots) {
       name: destination,
       outputRoot: WORKSPACE_LOCK_ROOT,
       outputPath: destination,
-      sourceHash: hashRules(rules),
-      sourcePath: `${graph.sourceDir}/${graph.instructionsDir}`,
-      transforms: markdown.transforms
+      preprocessDependencies: markdown.preprocessDependencies,
+      sourceHash: hashRules(rules, markdown.preprocessDependencies, graph.rootPath),
+      sourcePath,
+      ...markdown.transforms === undefined ? {} : { transforms: markdown.transforms }
     }));
   }
   return rendered;
@@ -12468,12 +12807,18 @@ async function renderCodexAgentsFiles(graph, lockRoots) {
 async function renderClaudeRuleMarkdown(graph, rule, outputPath) {
   const paths = readRulePaths(rule);
   const frontmatter = paths.length === 0 ? {} : { paths: [...paths] };
-  return stringifyOptionalMarkdown(frontmatter, await renderRuleBody(graph, rule, outputPath));
+  const preprocessDependencies = new Set;
+  const body = await renderRuleBody(graph, rule, outputPath, preprocessDependencies);
+  return {
+    content: stringifyOptionalMarkdown(frontmatter, body),
+    preprocessDependencies: formattedPreprocessDependencies(graph, preprocessDependencies)
+  };
 }
 async function renderCodexAgentsMarkdown(graph, rules, outputPath) {
   const counts = new Map;
+  const preprocessDependencies = new Set;
   const sections = rules.map(async (rule) => {
-    const body = await renderRuleBody(graph, rule, outputPath);
+    const body = await renderRuleBody(graph, rule, outputPath, preprocessDependencies);
     if (rule.dialect !== "claude")
       return { rule, body };
     const translated = translateClaudeDialect(body);
@@ -12486,7 +12831,7 @@ async function renderCodexAgentsMarkdown(graph, rules, outputPath) {
   const renderedSections = resolvedSections.filter((section) => section.body.length > 0).map((section) => `<!-- source: ${relative7(graph.rootPath, section.rule.sourcePath)} -->
 ${section.body}`);
   const content = [
-    `<!-- Generated by ${GENERATED_BY2} from ${graph.sourceDir}/${graph.instructionsDir}. Do not edit directly. -->`,
+    `<!-- Generated by ${GENERATED_BY2} from ${workspaceRelativeSourcePath(graph, graph.instructionsDir)}. Do not edit directly. -->`,
     "",
     renderedSections.join(`
 
@@ -12495,7 +12840,11 @@ ${section.body}`);
   ].join(`
 `);
   const transforms = [...counts.entries()].sort(([left], [right]) => compareStrings(left, right)).map(([intent, count]) => ({ count, intent }));
-  return { content, transforms };
+  return {
+    content,
+    preprocessDependencies: formattedPreprocessDependencies(graph, preprocessDependencies),
+    transforms
+  };
 }
 async function codexRuleDestinations(graph, rule) {
   const paths = readRulePaths(rule);
@@ -12534,10 +12883,16 @@ async function matchingRepoFiles(graph, pattern) {
 function isIgnoredRuleMatch(graph, path) {
   if (path.startsWith(".git/") || path.startsWith("node_modules/"))
     return true;
-  if (path === graph.sourceDir || path.startsWith(`${graph.sourceDir}/`))
+  if (graph.sourceDir !== "." && (path === graph.sourceDir || path.startsWith(`${graph.sourceDir}/`))) {
+    return true;
+  }
+  if (path === graph.sourceRoot || path.startsWith(`${graph.sourceRoot}/`))
     return true;
   return graph.outputRoots.some((outputRoot) => path === outputRoot || path.startsWith(`${outputRoot}/`));
 }
+function workspaceRelativeSourcePath(graph, sourcePath) {
+  return graph.sourceDir === "." ? sourcePath : join6(graph.sourceDir, sourcePath);
+}
 function readRulePaths(rule) {
   const value = rule.frontmatter.paths;
   if (value === undefined)
@@ -12563,12 +12918,13 @@ function stringifyOptionalMarkdown(frontmatter, body) {
 `;
   return renderValidatedMarkdown(frontmatter, normalizedBody, "generated instruction markdown");
 }
-async function renderRuleBody(graph, rule, outputPath) {
+async function renderRuleBody(graph, rule, outputPath, preprocessDependencies) {
   return preprocessText(normalizeRuleBody(rule.body), {
     frontmatter: rule.frontmatter,
+    preprocessDependencies,
     rootPath: graph.rootPath,
     sourcePath: rule.sourcePath,
-    sourceRoot: join6(graph.sourceDir, "src"),
+    sourceRoot: graph.sourceRoot,
     variables: ruleVariables(graph, rule, outputPath)
   });
 }
@@ -12747,7 +13103,7 @@ function renderLockFiles(graph, lockRoots) {
       skillsetMetadata: graph.root.compile.skillset.metadata,
       outputRoot,
       schemaVersion: 1,
-      sourceRoot: join6(graph.sourceDir, "src"),
+      sourceRoot: graph.sourceRoot,
       target: lock.target
     };
     rendered.push(textFile(join6(outputRoot, ".skillset.lock"), renderValidatedJson(value, `${outputRoot}/.skillset.lock`)));
@@ -12833,6 +13189,7 @@ function lockItemForRule(args) {
     name: args.name,
     outputHash: hashRenderedFiles(args.outputRoot, args.files),
     outputPath: relative7(args.outputRoot, args.outputPath),
+    ...args.preprocessDependencies.length === 0 ? {} : { preprocessDependencies: args.preprocessDependencies },
     sourceHash: args.sourceHash,
     ...args.sourceOrigin === undefined ? {} : { sourceOrigin: args.sourceOrigin },
     sourcePath: args.sourcePath,
@@ -12878,7 +13235,8 @@ async function lockItemForSkill(args) {
     name: args.skill.id,
     outputHash: hashRenderedFiles(args.outputRoot, args.files),
     outputPath: files.find((file) => file.endsWith("/SKILL.md")) ?? files[0] ?? "",
-    sourceHash: await hashSkillSource(args.sourceDir, args.skill.resources),
+    ...args.preprocessDependencies.length === 0 ? {} : { preprocessDependencies: args.preprocessDependencies },
+    sourceHash: await hashSkillSource(args.sourceDir, args.skill.resources, args.preprocessDependencies, args.graph.rootPath),
     ...args.skill.sourceOrigin === undefined ? {} : { sourceOrigin: args.skill.sourceOrigin },
     sourcePath: relative7(args.graph.rootPath, args.skill.sourcePath),
     ...args.transforms.length === 0 ? {} : { transforms: args.transforms },
@@ -12901,7 +13259,7 @@ function hashIslandSource(island, preprocessDependencies, rootPath) {
     hash.update("dependency\x00");
     hash.update(dependency);
     hash.update("\x00");
-    hash.update(readFileSyncBytes(join6(rootPath, dependency)));
+    hash.update(readPreprocessDependencySync(rootPath, dependency));
     hash.update("\x00");
   }
   return `sha256:${hash.digest("hex")}`;
@@ -12923,7 +13281,7 @@ function hashProjectAgentSource(agent, preprocessDependencies, rootPath) {
     hash.update("dependency\x00");
     hash.update(dependency);
     hash.update("\x00");
-    hash.update(readFileSyncBytes(join6(rootPath, dependency)));
+    hash.update(readPreprocessDependencySync(rootPath, dependency));
     hash.update("\x00");
   }
   return `sha256:${hash.digest("hex")}`;
@@ -13010,7 +13368,7 @@ async function hashPluginFeatureSource(feature2) {
   }
   return `sha256:${hash.digest("hex")}`;
 }
-async function hashSkillSource(sourceDir, resources) {
+async function hashSkillSource(sourceDir, resources, preprocessDependencies, rootPath) {
   const hash = createHash3("sha256");
   hash.update("skillset-skill-source-v2\x00");
   for (const file of await collectFiles2(sourceDir)) {
@@ -13031,6 +13389,13 @@ async function hashSkillSource(sourceDir, resources) {
     hash.update("\x00");
     await hashResourceSource(hash, resource);
   }
+  for (const dependency of preprocessDependencies) {
+    hash.update("preprocess-dependency\x00");
+    hash.update(dependency);
+    hash.update("\x00");
+    hash.update(readPreprocessDependencySync(rootPath, dependency));
+    hash.update("\x00");
+  }
   return `sha256:${hash.digest("hex")}`;
 }
 async function hashResourceSource(hash, resource) {
@@ -13049,10 +13414,10 @@ async function hashResourceSource(hash, resource) {
     hash.update("\x00");
   }
 }
-function hashTextRule(rule) {
-  return hashRules([rule]);
+function hashTextRule(rule, preprocessDependencies, rootPath) {
+  return hashRules([rule], preprocessDependencies, rootPath);
 }
-function hashRules(rules) {
+function hashRules(rules, preprocessDependencies, rootPath) {
   const hash = createHash3("sha256");
   hash.update("skillset-rule-source-v1\x00");
   for (const rule of [...rules].sort((left, right) => compareStrings(left.sourcePath, right.sourcePath))) {
@@ -13063,6 +13428,13 @@ function hashRules(rules) {
     hash.update(rule.body);
     hash.update("\x00");
   }
+  for (const dependency of preprocessDependencies) {
+    hash.update("preprocess-dependency\x00");
+    hash.update(dependency);
+    hash.update("\x00");
+    hash.update(readPreprocessDependencySync(rootPath, dependency));
+    hash.update("\x00");
+  }
   return `sha256:${hash.digest("hex")}`;
 }
 function hashRenderedFiles(outputRoot, files) {
@@ -13077,7 +13449,7 @@ function hashRenderedFiles(outputRoot, files) {
   return `sha256:${hash.digest("hex")}`;
 }
 async function collectFiles2(root) {
-  const entries = await readdir2(root, { withFileTypes: true });
+  const entries = await readdir3(root, { withFileTypes: true });
   const files = [];
   for (const entry of entries.sort((left, right) => compareStrings(left.name, right.name))) {
     const path = join6(root, entry.name);
@@ -13111,14 +13483,14 @@ function hasRenderableContent(path) {
     return !isIgnoredCompanionFile(path);
   if (!stats.isDirectory())
     return false;
-  for (const entry of readdirSync2(path)) {
+  for (const entry of readdirSync3(path)) {
     if (hasRenderableContent(join6(path, entry)))
       return true;
   }
   return false;
 }
 function isIgnoredCompanionFile(path) {
-  const name = basename(path);
+  const name = basename2(path);
   return name === ".DS_Store" || name === ".gitkeep";
 }
 function bytesEqual2(left, right) {
@@ -13158,12 +13530,12 @@ function titleize(value) {
   return value.split("-").filter((part) => part.length > 0).map((part) => `${part[0]?.toUpperCase() ?? ""}${part.slice(1)}`).join(" ");
 }
 function readFileSyncBytes(path) {
-  return readFileSync(path);
+  return readFileSync2(path);
 }
 
 // packages/core/src/resolver.ts
-import { readdir as readdir3, readFile as readFile7, stat as stat6 } from "fs/promises";
-import { basename as basename2, dirname as dirname6, join as join8, relative as relative8, sep as sep3 } from "path";
+import { readdir as readdir4, readFile as readFile7, stat as stat6 } from "fs/promises";
+import { basename as basename3, dirname as dirname6, join as join8, relative as relative8, sep as sep3 } from "path";
 
 // packages/core/src/release-state.ts
 import { mkdir as mkdir2, readFile as readFile6, stat as stat5, writeFile as writeFile2 } from "fs/promises";
@@ -13259,6 +13631,7 @@ var SOURCE_ROOT_DIR = "src";
 var RULES_DIR = "rules";
 var SKILLS_DIR = "skills";
 var SHARED_DIR = "shared";
+var DEDICATED_STATE_DIR = "changes";
 var SKILL_FILE = "SKILL.md";
 var RULES_OUTPUT_ROOT = ".claude/rules";
 var PROJECT_AGENTS_DIR = "agents";
@@ -13268,26 +13641,30 @@ var PROVIDER_SOURCE_DIRS = {
 };
 var PLUGIN_FEATURE_KEYS = ["bin", "mcp"];
 async function loadBuildGraph(rootPath, options = {}) {
-  const sourceDir = options.sourceDir ?? DEFAULT_SOURCE_DIR;
-  const sourcePath = resolveInside(rootPath, sourceDir);
-  const rootConfigPath = join8(sourcePath, ROOT_CONFIG_FILE);
-  const rootSourceManifestPath = join8(sourcePath, SOURCE_ROOT_DIR, ROOT_SOURCE_MANIFEST_FILE);
-  const rootConfig = parseYamlRecord(await readFile7(rootConfigPath, "utf8"), rootConfigPath);
-  validateWorkspaceConfigDocument(rootConfig, rootConfigPath);
-  const sourceManifest = parseYamlRecord(await readFile7(rootSourceManifestPath, "utf8"), rootSourceManifestPath);
-  validateRootSourceManifestDocument(sourceManifest, rootSourceManifestPath);
-  const metadata = readSkillsetMetadata(sourceManifest, rootSourceManifestPath);
-  validateSchemaField(metadata, `${rootSourceManifestPath}.skillset.schema`);
-  validateVersionField(metadata, `${rootSourceManifestPath}.skillset.version`);
-  readSkillsetName(metadata, basename2(rootPath), rootSourceManifestPath);
-  const outputs = readOutputConfig(rootConfig, {}, options.distDir === undefined ? {} : { distDir: options.distDir });
-  const distributions = readDistributionConfig(rootConfig, rootConfigPath);
-  const rootTargets = resolveTargets(readCompileTargets(rootConfig, rootConfigPath), rootConfig, rootConfigPath, {
+  const workspace = await resolveWorkspaceLayout(rootPath, options);
+  const { sourceDir, sourcePath, sourceRoot, sourceRootDir, sourceRootPath } = workspace;
+  const rootConfig = parseYamlRecord(await readFile7(workspace.configPath, "utf8"), workspace.configPath);
+  const sourceManifest = workspace.splitRootManifestPath === undefined ? rootConfig : parseYamlRecord(await readFile7(workspace.splitRootManifestPath, "utf8"), workspace.splitRootManifestPath);
+  if (workspace.splitRootManifestPath === undefined) {
+    validateConfigDocument(rootConfig, workspace.configPath, { allowCompile: true });
+  } else {
+    validateWorkspaceConfigDocument(rootConfig, workspace.configPath);
+    validateRootSourceManifestDocument(sourceManifest, workspace.splitRootManifestPath);
+  }
+  const metadataLabel = workspace.splitRootManifestPath ?? workspace.configPath;
+  const metadata = readSkillsetMetadata(sourceManifest, metadataLabel);
+  validateSchemaField(metadata, `${metadataLabel}.skillset.schema`);
+  validateVersionField(metadata, `${metadataLabel}.skillset.version`);
+  readSkillsetName(metadata, basename3(rootPath), metadataLabel);
+  const outputMetadata = workspace.splitRootManifestPath === undefined ? metadata : {};
+  const outputs = readOutputConfig(rootConfig, outputMetadata, options.distDir === undefined ? {} : { distDir: options.distDir });
+  const distributions = readDistributionConfig(rootConfig, workspace.configPath);
+  const rootTargets = resolveTargets(readCompileTargets(rootConfig, workspace.configPath), rootConfig, workspace.configPath, {
     allowDefaults: true,
     objectInheritsEnabled: true
   });
-  const compileConfig = readCompileConfig(rootConfig, rootConfigPath);
-  const filteredTargets = applyTargetFilter(rootTargets, options.targetFilter, rootConfigPath);
+  const compileConfig = readCompileConfig(rootConfig, workspace.configPath);
+  const filteredTargets = applyTargetFilter(rootTargets, options.targetFilter, workspace.configPath);
   const compile = {
     ...compileConfig,
     build: options.buildMode ?? compileConfig.build,
@@ -13301,29 +13678,33 @@ async function loadBuildGraph(rootPath, options = {}) {
     targets: filteredTargets
   };
   const warnings = [];
-  await rejectLegacySourceLayout(rootPath, sourceDir);
-  await validateSupports(sourceManifest.supports, { label: rootSourceManifestPath, rootPath, warnings });
-  const releaseState = await readReleaseState(rootPath, options);
-  const plugins = await loadPlugins(rootPath, sourceDir, filteredTargets, warnings, outputs);
+  await rejectLegacySourceLayout(rootPath, sourceDir, sourceRootDir);
+  await validateSupports(sourceManifest.supports, { label: metadataLabel, rootPath, warnings });
+  const releaseState = await readReleaseState(rootPath, { ...options, sourceDir });
+  const plugins = await loadPlugins(rootPath, sourceDir, sourceRootDir, filteredTargets, warnings, outputs);
   try {
     validatePluginDependencyGraph(plugins);
   } catch (error) {
     throw featureDiagnosticError(error, {
       code: "plugin-dependencies-invalid",
       featureId: "dependencies",
-      path: join8(sourceDir, SOURCE_ROOT_DIR, PLUGINS_DIR)
+      path: join8(sourceRoot, PLUGINS_DIR)
     });
   }
-  const standaloneSkills = await loadStandaloneSkills(rootPath, sourceDir, filteredTargets, warnings);
-  const { rules, instructionsDir } = await loadInstructions(rootPath, sourceDir, filteredTargets, warnings);
-  const projectAgents = await loadProjectAgents(rootPath, sourceDir, filteredTargets, warnings);
-  const projectIslands = await loadProjectIslands(rootPath, sourceDir, plugins);
+  const standaloneSkills = await loadStandaloneSkills(rootPath, sourceDir, sourceRootDir, filteredTargets, warnings);
+  const { rules, instructionsDir } = await loadInstructions(rootPath, sourceDir, sourceRootDir, filteredTargets, warnings);
+  const projectAgents = await loadProjectAgents(rootPath, sourceDir, sourceRootDir, filteredTargets, warnings);
+  const projectIslands = await loadProjectIslands(rootPath, sourceDir, sourceRootDir, plugins);
   if (plugins.length === 0 && standaloneSkills.length === 0 && rules.length === 0 && projectAgents.length === 0 && projectIslands.length === 0) {
-    throw new Error(`skillset: no source plugins, skills, rules, project agents, or provider source found under ${sourceDir}/${SOURCE_ROOT_DIR}/`);
+    throw new Error(`skillset: no source plugins, skills, rules, project agents, or provider source found under ${sourceRoot}/`);
   }
   const outputRoots = await outputRootsFor(rootPath, outputs, plugins, standaloneSkills, rules);
-  validateOutputRoots(rootPath, sourcePath, outputRoots);
-  validateProjectRoots(rootPath, sourcePath, outputRoots, filteredTargets, projectAgents, projectIslands);
+  const protectedRoots = sourceDir === "." ? [
+    { label: "source root", path: sourceRootPath },
+    { label: "change state", path: resolveInside(rootPath, DEDICATED_STATE_DIR) }
+  ] : [{ label: "source root", path: sourcePath }];
+  validateOutputRoots(rootPath, protectedRoots, outputRoots);
+  validateProjectRoots(rootPath, protectedRoots, outputRoots, filteredTargets, projectAgents, projectIslands);
   return {
     instructionsDir,
     outputRoots: outputRoots.map((outputRoot) => outputRoot.path),
@@ -13333,13 +13714,140 @@ async function loadBuildGraph(rootPath, options = {}) {
     releaseState,
     rules,
     root,
+    rootConfigPath: workspace.configPath,
+    rootManifestPath: workspace.splitRootManifestPath ?? workspace.configPath,
     rootPath,
     sourceDir,
     sourcePath,
+    sourceRoot,
+    sourceRootPath,
     standaloneSkills,
     warnings
   };
 }
+async function detectWorkspaceSourceDir(rootPath, options = {}) {
+  return (await resolveWorkspaceLayout(rootPath, options)).sourceDir;
+}
+async function resolveWorkspaceLayout(rootPath, options) {
+  if (options.sourceDir !== undefined) {
+    if (options.sourceDir === ".")
+      return dedicatedWorkspace(rootPath);
+    const ordinary2 = await ordinaryWorkspace(rootPath, options.sourceDir);
+    if (await workspaceExists(ordinary2))
+      return ordinary2;
+    return legacyOrdinaryWorkspace(rootPath, options.sourceDir);
+  }
+  const ordinary = await ordinaryWorkspace(rootPath);
+  const legacy = await legacyOrdinaryWorkspace(rootPath, DEFAULT_SOURCE_DIR);
+  const dedicated = await dedicatedWorkspace(rootPath);
+  const ordinaryExists = await workspaceExists(ordinary);
+  const legacyExists = await workspaceExists(legacy);
+  const dedicatedExists = await workspaceExists(dedicated);
+  const dedicatedSourceMarkerExists = await hasDedicatedSourceMarker(dedicated.sourceRootPath);
+  if (dedicatedExists && dedicatedSourceMarkerExists && (ordinaryExists || legacyExists)) {
+    throw new Error("skillset: ambiguous workspace layout; found both dedicated root skillset.yaml/skillset and ordinary .skillset workspace");
+  }
+  if (ordinaryExists && legacyExists) {
+    throw new Error("skillset: ambiguous workspace layout; found both .skillset/skillset.yaml and legacy .skillset/config.yaml");
+  }
+  if (dedicatedExists && dedicatedSourceMarkerExists)
+    return dedicated;
+  if (ordinaryExists)
+    return ordinary;
+  if (legacyExists)
+    return legacy;
+  if (dedicatedExists)
+    return dedicated;
+  return legacy;
+}
+async function hasDedicatedSourceMarker(sourceRootPath) {
+  if (await hasSkillSource(join8(sourceRootPath, SKILLS_DIR)))
+    return true;
+  if (await hasPluginSource(join8(sourceRootPath, PLUGINS_DIR)))
+    return true;
+  if (await hasMarkdownSource(join8(sourceRootPath, RULES_DIR)))
+    return true;
+  if (await hasProjectAgentSource(join8(sourceRootPath, PROJECT_AGENTS_DIR)))
+    return true;
+  for (const providerDir of Object.values(PROVIDER_SOURCE_DIRS)) {
+    if (await hasAnyFile(join8(sourceRootPath, providerDir)))
+      return true;
+  }
+  return false;
+}
+async function hasSkillSource(path) {
+  return await exists5(path) && (await findSkillFiles(path)).length > 0;
+}
+async function hasPluginSource(path) {
+  if (!await exists5(path))
+    return false;
+  for (const entry of await readdir4(path, { withFileTypes: true })) {
+    if (!entry.isDirectory())
+      continue;
+    const pluginPath = join8(path, entry.name);
+    if (await exists5(join8(pluginPath, "skillset.yaml")))
+      return true;
+    if (await exists5(join8(pluginPath, "config.yaml")))
+      return true;
+  }
+  return false;
+}
+async function hasMarkdownSource(path) {
+  return await exists5(path) && (await findMarkdownFiles(path)).some(isNonReadmeFile);
+}
+async function hasProjectAgentSource(path) {
+  if (!await exists5(path))
+    return false;
+  const entries = await readdir4(path, { withFileTypes: true });
+  return entries.some((entry) => entry.isFile() && entry.name.endsWith(".md") && entry.name.toLowerCase() !== "readme.md");
+}
+async function hasAnyFile(path) {
+  return await exists5(path) && (await collectFiles3(path)).some(isNonReadmeFile);
+}
+function isNonReadmeFile(path) {
+  return basename3(path).toLowerCase() !== "readme.md";
+}
+async function workspaceExists(workspace) {
+  return exists5(workspace.configPath);
+}
+async function ordinaryWorkspace(rootPath, sourceDir = DEFAULT_SOURCE_DIR) {
+  return {
+    configPath: resolveInside(rootPath, join8(sourceDir, ROOT_SOURCE_MANIFEST_FILE)),
+    configRelativePath: join8(sourceDir, ROOT_SOURCE_MANIFEST_FILE),
+    mode: "ordinary",
+    sourceDir,
+    sourcePath: resolveInside(rootPath, sourceDir),
+    sourceRoot: join8(sourceDir, SOURCE_ROOT_DIR),
+    sourceRootDir: SOURCE_ROOT_DIR,
+    sourceRootPath: resolveInside(rootPath, join8(sourceDir, SOURCE_ROOT_DIR))
+  };
+}
+function dedicatedWorkspace(rootPath) {
+  return {
+    configPath: resolveInside(rootPath, ROOT_SOURCE_MANIFEST_FILE),
+    configRelativePath: ROOT_SOURCE_MANIFEST_FILE,
+    mode: "dedicated",
+    sourceDir: ".",
+    sourcePath: rootPath,
+    sourceRoot: "skillset",
+    sourceRootDir: "skillset",
+    sourceRootPath: resolveInside(rootPath, "skillset")
+  };
+}
+function legacyOrdinaryWorkspace(rootPath, sourceDir) {
+  return {
+    configPath: resolveInside(rootPath, join8(sourceDir, ROOT_CONFIG_FILE)),
+    configRelativePath: join8(sourceDir, ROOT_CONFIG_FILE),
+    mode: "legacy-ordinary",
+    sourceDir,
+    sourcePath: resolveInside(rootPath, sourceDir),
+    sourceRoot: join8(sourceDir, SOURCE_ROOT_DIR),
+    sourceRootDir: SOURCE_ROOT_DIR,
+    sourceRootPath: resolveInside(rootPath, join8(sourceDir, SOURCE_ROOT_DIR)),
+    splitRootManifestPath: resolveInside(rootPath, join8(sourceDir, SOURCE_ROOT_DIR, ROOT_SOURCE_MANIFEST_FILE)),
+    splitRootManifestRelativePath: join8(sourceDir, SOURCE_ROOT_DIR, ROOT_SOURCE_MANIFEST_FILE)
+  };
+}
 function applyTargetFilter(targets, filter, label) {
   if (filter === undefined)
     return targets;
@@ -13364,15 +13872,18 @@ function featureDiagnosticError(error, args) {
     ...args.path === undefined ? {} : { path: args.path }
   });
 }
-async function rejectLegacySourceLayout(rootPath, sourceDir) {
-  const moves = [
-    ["instructions", `${SOURCE_ROOT_DIR}/${RULES_DIR}`],
-    ["rules", `${SOURCE_ROOT_DIR}/${RULES_DIR}`],
-    [SKILLS_DIR, `${SOURCE_ROOT_DIR}/${SKILLS_DIR}`],
-    [PLUGINS_DIR, `${SOURCE_ROOT_DIR}/${PLUGINS_DIR}`],
-    [SHARED_DIR, `${SOURCE_ROOT_DIR}/${SHARED_DIR}`],
-    [`${SOURCE_ROOT_DIR}/claude`, `${SOURCE_ROOT_DIR}/${PROVIDER_SOURCE_DIRS.claude}`],
-    [`${SOURCE_ROOT_DIR}/codex`, `${SOURCE_ROOT_DIR}/${PROVIDER_SOURCE_DIRS.codex}`]
+async function rejectLegacySourceLayout(rootPath, sourceDir, sourceRootDir) {
+  const moves = sourceDir === "." ? [
+    [`${sourceRootDir}/claude`, `${sourceRootDir}/${PROVIDER_SOURCE_DIRS.claude}`],
+    [`${sourceRootDir}/codex`, `${sourceRootDir}/${PROVIDER_SOURCE_DIRS.codex}`]
+  ] : [
+    ["instructions", `${sourceRootDir}/${RULES_DIR}`],
+    ["rules", `${sourceRootDir}/${RULES_DIR}`],
+    [SKILLS_DIR, `${sourceRootDir}/${SKILLS_DIR}`],
+    [PLUGINS_DIR, `${sourceRootDir}/${PLUGINS_DIR}`],
+    [SHARED_DIR, `${sourceRootDir}/${SHARED_DIR}`],
+    [`${sourceRootDir}/claude`, `${sourceRootDir}/${PROVIDER_SOURCE_DIRS.claude}`],
+    [`${sourceRootDir}/codex`, `${sourceRootDir}/${PROVIDER_SOURCE_DIRS.codex}`]
   ];
   for (const [oldPath, newPath] of moves) {
     const absoluteOldPath = resolveInside(rootPath, join8(sourceDir, oldPath));
@@ -13380,24 +13891,24 @@ async function rejectLegacySourceLayout(rootPath, sourceDir) {
       throw new Error(`skillset: ${join8(sourceDir, oldPath)} uses the retired source layout; move it to ${join8(sourceDir, newPath)}`);
     }
   }
-  const pluginsPath = resolveInside(rootPath, join8(sourceDir, SOURCE_ROOT_DIR, PLUGINS_DIR));
+  const pluginsPath = resolveInside(rootPath, join8(sourceDir, sourceRootDir, PLUGINS_DIR));
   if (!await exists5(pluginsPath))
     return;
-  for (const entry of await readdir3(pluginsPath, { withFileTypes: true })) {
+  for (const entry of await readdir4(pluginsPath, { withFileTypes: true })) {
     if (!entry.isDirectory())
       continue;
     for (const [oldProviderDir, newProviderDir] of Object.entries(PROVIDER_SOURCE_DIRS)) {
-      const oldPath = join8(SOURCE_ROOT_DIR, PLUGINS_DIR, entry.name, oldProviderDir);
+      const oldPath = join8(sourceRootDir, PLUGINS_DIR, entry.name, oldProviderDir);
       const absoluteOldPath = resolveInside(rootPath, join8(sourceDir, oldPath));
       if (!await exists5(absoluteOldPath))
         continue;
-      const newPath = join8(SOURCE_ROOT_DIR, PLUGINS_DIR, entry.name, newProviderDir);
+      const newPath = join8(sourceRootDir, PLUGINS_DIR, entry.name, newProviderDir);
       throw new Error(`skillset: ${join8(sourceDir, oldPath)} uses the retired provider source layout; move it to ${join8(sourceDir, newPath)}`);
     }
   }
 }
-async function loadProjectIslands(rootPath, sourceDir, plugins) {
-  const srcPath = resolveInside(rootPath, join8(sourceDir, SOURCE_ROOT_DIR));
+async function loadProjectIslands(rootPath, sourceDir, sourceRootDir, plugins) {
+  const srcPath = resolveInside(rootPath, join8(sourceDir, sourceRootDir));
   if (!await exists5(srcPath))
     return [];
   const islands = [];
@@ -13427,7 +13938,7 @@ async function loadProjectIslands(rootPath, sourceDir, plugins) {
       throw new SkillsetFeatureDiagnosticError({
         code: "target-native-island-unsupported",
         featureId: "target-native-islands",
-        message: `skillset: ${path} targets Codex .rules outside .skillset/src/_codex/rules/; ` + "Codex .rules are project-only command policy",
+        message: `skillset: ${path} targets Codex .rules outside ${join8(sourceDir, sourceRootDir, PROVIDER_SOURCE_DIRS.codex, "rules")}/; ` + "Codex .rules are project-only command policy",
         path
       });
     }
@@ -13436,7 +13947,7 @@ async function loadProjectIslands(rootPath, sourceDir, plugins) {
 }
 async function validatePluginIslandOwners(rootPath, pluginsPath, plugins) {
   const pluginIds = new Set(plugins.map((plugin) => plugin.id));
-  for (const entry of await readdir3(pluginsPath, { withFileTypes: true })) {
+  for (const entry of await readdir4(pluginsPath, { withFileTypes: true })) {
     if (!entry.isDirectory())
       continue;
     if (pluginIds.has(entry.name))
@@ -13455,11 +13966,11 @@ async function loadTargetIsland(rootPath, islandPath, target, plugin) {
     ...plugin === undefined ? {} : { plugin }
   }));
 }
-async function loadProjectAgents(rootPath, sourceDir, rootTargets, warnings) {
-  const agentsPath = resolveInside(rootPath, join8(sourceDir, SOURCE_ROOT_DIR, PROJECT_AGENTS_DIR));
+async function loadProjectAgents(rootPath, sourceDir, sourceRootDir, rootTargets, warnings) {
+  const agentsPath = resolveInside(rootPath, join8(sourceDir, sourceRootDir, PROJECT_AGENTS_DIR));
   if (!await exists5(agentsPath))
     return [];
-  const entries = await readdir3(agentsPath, { withFileTypes: true });
+  const entries = await readdir4(agentsPath, { withFileTypes: true });
   const agents = [];
   for (const entry of entries.sort((left, right) => compareStrings(left.name, right.name))) {
     if (!entry.isFile() || !entry.name.endsWith(".md"))
@@ -13475,7 +13986,7 @@ async function loadProjectAgent(rootPath, sourceDir, agentsPath, sourcePath, par
   const sourceLabel = relative8(rootPath, sourcePath);
   rejectUnsupportedPortableFrontmatter(parts.frontmatter, sourceLabel);
   await validateSupports(parts.frontmatter.supports, { label: sourceLabel, rootPath, warnings });
-  const name = readString(parts.frontmatter, "name") ?? basename2(sourcePath, ".md");
+  const name = readString(parts.frontmatter, "name") ?? basename3(sourcePath, ".md");
   const outputName = sanitizeProjectAgentName(name, sourcePath);
   const description = readString(parts.frontmatter, "description");
   if (description === undefined) {
@@ -13493,7 +14004,7 @@ async function loadProjectAgent(rootPath, sourceDir, agentsPath, sourcePath, par
   warnPortableModel(parts.frontmatter, targets, rootPath, sourcePath, warnings);
   return {
     body: parts.body,
-    filename: basename2(sourcePath),
+    filename: basename3(sourcePath),
     frontmatter: parts.frontmatter,
     name,
     outputName,
@@ -13537,11 +14048,11 @@ function validateProjectAgentCollisions(agents) {
     }
   }
 }
-async function loadInstructions(rootPath, sourceDir, rootTargets, warnings) {
-  const canonicalPath = resolveInside(rootPath, join8(sourceDir, SOURCE_ROOT_DIR, RULES_DIR));
+async function loadInstructions(rootPath, sourceDir, sourceRootDir, rootTargets, warnings) {
+  const canonicalPath = resolveInside(rootPath, join8(sourceDir, sourceRootDir, RULES_DIR));
   const canonicalFiles = await exists5(canonicalPath) ? await findMarkdownFiles(canonicalPath) : [];
   if (canonicalFiles.length === 0) {
-    return { rules: [], instructionsDir: join8(SOURCE_ROOT_DIR, RULES_DIR) };
+    return { rules: [], instructionsDir: join8(sourceRootDir, RULES_DIR) };
   }
   const ruleFiles = canonicalFiles;
   const rules = [];
@@ -13568,7 +14079,7 @@ async function loadInstructions(rootPath, sourceDir, rootTargets, warnings) {
   }
   return {
     rules: rules.sort((left, right) => compareStrings(left.relativePath, right.relativePath)),
-    instructionsDir: join8(SOURCE_ROOT_DIR, RULES_DIR)
+    instructionsDir: join8(sourceRootDir, RULES_DIR)
   };
 }
 function readDialect(frontmatter, label) {
@@ -13586,22 +14097,22 @@ function normalizeRuleFrontmatter(frontmatter, label) {
   }
   return frontmatter;
 }
-async function loadPlugins(rootPath, sourceDir, rootTargets, warnings, outputs) {
-  const pluginsPath = resolveInside(rootPath, join8(sourceDir, SOURCE_ROOT_DIR, PLUGINS_DIR));
+async function loadPlugins(rootPath, sourceDir, sourceRootDir, rootTargets, warnings, outputs) {
+  const pluginsPath = resolveInside(rootPath, join8(sourceDir, sourceRootDir, PLUGINS_DIR));
   if (!await exists5(pluginsPath))
     return [];
-  const entries = await readdir3(pluginsPath, { withFileTypes: true });
+  const entries = await readdir4(pluginsPath, { withFileTypes: true });
   const plugins = [];
   for (const entry of entries.sort((left, right) => compareStrings(left.name, right.name))) {
     if (!entry.isDirectory())
       continue;
     const id = validateSlug(entry.name, "plugin directory");
-    plugins.push(await loadPlugin(rootPath, sourceDir, id, rootTargets, warnings, outputs));
+    plugins.push(await loadPlugin(rootPath, sourceDir, sourceRootDir, id, rootTargets, warnings, outputs));
   }
   return plugins;
 }
-async function loadPlugin(rootPath, sourceDir, id, parentTargets, warnings, outputs) {
-  const pluginPath = resolveInside(rootPath, join8(sourceDir, SOURCE_ROOT_DIR, PLUGINS_DIR, id));
+async function loadPlugin(rootPath, sourceDir, sourceRootDir, id, parentTargets, warnings, outputs) {
+  const pluginPath = resolveInside(rootPath, join8(sourceDir, sourceRootDir, PLUGINS_DIR, id));
   const configPath = await resolvePluginConfigPath(pluginPath);
   const configRelativePath = relative8(rootPath, configPath);
   const config = parseYamlRecord(await readFile7(configPath, "utf8"), configPath);
@@ -13636,7 +14147,7 @@ async function loadPlugin(rootPath, sourceDir, id, parentTargets, warnings, outp
     });
   }
   const features = await loadPluginFeatures(rootPath, pluginPath, config, configPath, targets, id, configuredOutputRoots(outputs));
-  const skills = await loadSkills(rootPath, sourceDir, pluginPath, inheritedTargets, warnings);
+  const skills = await loadSkills(rootPath, sourceDir, sourceRootDir, pluginPath, inheritedTargets, warnings);
   if (await exists5(join8(pluginPath, "hooks.json"))) {
     const path = relative8(rootPath, join8(pluginPath, "hooks.json"));
     throw new SkillsetFeatureDiagnosticError({
@@ -13752,13 +14263,13 @@ async function resolvePluginConfigPath(pluginPath) {
   }
   return candidates[0] ?? join8(pluginPath, "skillset.yaml");
 }
-async function loadSkills(rootPath, sourceDir, pluginPath, parentTargets, warnings) {
+async function loadSkills(rootPath, sourceDir, sourceRootDir, pluginPath, parentTargets, warnings) {
   const skillsPath = join8(pluginPath, SKILLS_DIR);
   if (!await exists5(skillsPath))
     return [];
-  return loadSkillsFromDirectory(rootPath, sourceDir, skillsPath, pluginPath, parentTargets, warnings, pluginPath);
+  return loadSkillsFromDirectory(rootPath, sourceDir, sourceRootDir, skillsPath, pluginPath, parentTargets, warnings, pluginPath);
 }
-async function loadSkillsFromDirectory(rootPath, sourceDir, skillsPath, relativeBasePath, parentTargets, warnings, pluginPath) {
+async function loadSkillsFromDirectory(rootPath, sourceDir, sourceRootDir, skillsPath, relativeBasePath, parentTargets, warnings, pluginPath) {
   const skillFiles = await findSkillFiles(skillsPath);
   const skills = [];
   for (const sourcePath of skillFiles) {
@@ -13777,14 +14288,14 @@ async function loadSkillsFromDirectory(rootPath, sourceDir, skillsPath, relative
       throw new Error(`skillset: ${sourcePath} uses unsupported skillset.version; use top-level version`);
     }
     const sourceOrigin = readSourceOrigin(metadata, sourcePath);
-    const id = validateSlug(readString(parts.frontmatter, "name") ?? basename2(dirname6(sourcePath)), `skill id in ${sourcePath}`);
+    const id = validateSlug(readString(parts.frontmatter, "name") ?? basename3(dirname6(sourcePath)), `skill id in ${sourcePath}`);
     const targets = resolveFeatureTargets(parentTargets, parts.frontmatter, sourcePath, "skills");
     warnPortableModel(parts.frontmatter, targets, rootPath, sourcePath, warnings);
     const relativePath = relative8(relativeBasePath, sourcePath);
     const resources = await readSkillResources(parts.frontmatter.resources, {
       label: sourcePath,
       ...pluginPath === undefined ? {} : { pluginSharedPath: join8(pluginPath, "shared") },
-      sharedPath: resolveInside(rootPath, join8(sourceDir, SOURCE_ROOT_DIR, SHARED_DIR))
+      sharedPath: resolveInside(rootPath, join8(sourceDir, sourceRootDir, SHARED_DIR))
     });
     const dialect = readDialect(parts.frontmatter, relative8(rootPath, sourcePath));
     skills.push({
@@ -13802,11 +14313,11 @@ async function loadSkillsFromDirectory(rootPath, sourceDir, skillsPath, relative
   }
   return skills.sort((left, right) => compareStrings(left.relativePath, right.relativePath));
 }
-async function loadStandaloneSkills(rootPath, sourceDir, rootTargets, warnings) {
-  const skillsPath = resolveInside(rootPath, join8(sourceDir, SOURCE_ROOT_DIR, SKILLS_DIR));
+async function loadStandaloneSkills(rootPath, sourceDir, sourceRootDir, rootTargets, warnings) {
+  const skillsPath = resolveInside(rootPath, join8(sourceDir, sourceRootDir, SKILLS_DIR));
   if (!await exists5(skillsPath))
     return [];
-  const skills = await loadSkillsFromDirectory(rootPath, sourceDir, skillsPath, skillsPath, rootTargets, warnings);
+  const skills = await loadSkillsFromDirectory(rootPath, sourceDir, sourceRootDir, skillsPath, skillsPath, rootTargets, warnings);
   return skills;
 }
 function warnPortableModel(frontmatter, targets, rootPath, sourcePath, warnings) {
@@ -13819,7 +14330,7 @@ function warnPortableModel(frontmatter, targets, rootPath, sourcePath, warnings)
 }
 async function findSkillFiles(root) {
   const files = [];
-  const entries = await readdir3(root, { withFileTypes: true });
+  const entries = await readdir4(root, { withFileTypes: true });
   for (const entry of entries.sort((left, right) => compareStrings(left.name, right.name))) {
     const path = join8(root, entry.name);
     if (entry.isDirectory()) {
@@ -13834,7 +14345,7 @@ async function findSkillFiles(root) {
 }
 async function findMarkdownFiles(root) {
   const files = [];
-  const entries = await readdir3(root, { withFileTypes: true });
+  const entries = await readdir4(root, { withFileTypes: true });
   for (const entry of entries.sort((left, right) => compareStrings(left.name, right.name))) {
     const path = join8(root, entry.name);
     if (entry.isDirectory()) {
@@ -13849,7 +14360,7 @@ async function findMarkdownFiles(root) {
 }
 async function collectFiles3(root) {
   const files = [];
-  const entries = await readdir3(root, { withFileTypes: true });
+  const entries = await readdir4(root, { withFileTypes: true });
   for (const entry of entries.sort((left, right) => compareStrings(left.name, right.name))) {
     const path = join8(root, entry.name);
     if (entry.isDirectory()) {
@@ -13947,7 +14458,7 @@ function isInsidePath(path, root) {
   const relativePath = relative8(root, path);
   return relativePath === "" || !relativePath.startsWith("..") && !relativePath.includes(`..${sep3}`);
 }
-function validateProjectRoots(rootPath, sourcePath, outputRoots, rootTargets, projectAgents, projectIslands) {
+function validateProjectRoots(rootPath, protectedRoots, outputRoots, rootTargets, projectAgents, projectIslands) {
   for (const target of targetNames()) {
     const hasProjectAgentOutput = projectAgents.some((agent) => agent.targets[target].enabled);
     const hasProjectIslandOutput = projectIslands.some((island) => island.plugin === undefined && island.target === target);
@@ -13957,7 +14468,7 @@ function validateProjectRoots(rootPath, sourcePath, outputRoots, rootTargets, pr
       label: `${target}.projectRoot`,
       path: targetProjectRoot3(rootTargets, target)
     };
-    const absoluteProjectRoot = validateOutputRootNotInsideSource(rootPath, sourcePath, projectRoot);
+    const absoluteProjectRoot = validateOutputRootNotInsideProtectedRoots(rootPath, protectedRoots, projectRoot);
     const targetProjectAgents = projectAgents.filter((agent) => agent.targets[target].enabled);
     const targetProjectIslands = projectIslands.filter((island) => island.plugin === undefined && island.target === target);
     for (const outputRoot of outputRoots) {
@@ -13982,10 +14493,10 @@ function targetProjectRoot3(rootTargets, target) {
 function projectAgentOutputPath(projectRoot, target, agent) {
   return join8(projectRoot, "agents", `${agent.outputName}.${target === "claude" ? "md" : "toml"}`);
 }
-function validateOutputRoots(rootPath, sourcePath, outputRoots) {
+function validateOutputRoots(rootPath, protectedRoots, outputRoots) {
   const seen = new Map;
   for (const outputRoot of outputRoots) {
-    const absoluteOutputRoot = validateOutputRootNotInsideSource(rootPath, sourcePath, outputRoot);
+    const absoluteOutputRoot = validateOutputRootNotInsideProtectedRoots(rootPath, protectedRoots, outputRoot);
     const existing = seen.get(absoluteOutputRoot);
     if (existing !== undefined) {
       throw new Error(`skillset: ${outputRoot.label} reuses output root ${outputRoot.path}; already used by ${existing}`);
@@ -13993,10 +14504,12 @@ function validateOutputRoots(rootPath, sourcePath, outputRoots) {
     seen.set(absoluteOutputRoot, outputRoot.label);
   }
 }
-function validateOutputRootNotInsideSource(rootPath, sourcePath, outputRoot) {
+function validateOutputRootNotInsideProtectedRoots(rootPath, protectedRoots, outputRoot) {
   const absoluteOutputRoot = resolveInside(rootPath, outputRoot.path);
-  if (isSameOrInside(absoluteOutputRoot, sourcePath)) {
-    throw new Error(`skillset: ${outputRoot.label} must not point inside source root ${relative8(rootPath, sourcePath)}`);
+  for (const protectedRoot of protectedRoots) {
+    if (isSameOrInside(absoluteOutputRoot, protectedRoot.path)) {
+      throw new Error(`skillset: ${outputRoot.label} must not point inside ${protectedRoot.label} ${relative8(rootPath, protectedRoot.path)}`);
+    }
   }
   return absoluteOutputRoot;
 }
@@ -14428,7 +14941,7 @@ async function listGeneratedFiles(rootPath, outputRoots, rendered, previousManag
   return [...paths].sort();
 }
 async function collectFiles4(root) {
-  const entries = await readdir4(root, { withFileTypes: true });
+  const entries = await readdir5(root, { withFileTypes: true });
   const files = [];
   for (const entry of entries.sort((left, right) => compareStrings(left.name, right.name))) {
     const path = join9(root, entry.name);
@@ -14557,7 +15070,7 @@ async function exists6(path) {
 
 // packages/core/src/lint.ts
 import { readFile as readFile9, stat as stat8 } from "fs/promises";
-import { basename as basename3, dirname as dirname8, join as join10, relative as relative10 } from "path";
+import { basename as basename4, dirname as dirname8, join as join10, relative as relative10 } from "path";
 
 // packages/lint/src/registry.ts
 var lintRules = new Map;
@@ -15040,8 +15553,8 @@ async function lintSkillRules(graph) {
 async function lintSubjectForSkill(graph, skill) {
   return {
     body: skill.body,
-    directoryName: basename3(dirname8(skill.sourcePath)),
-    files: [basename3(skill.sourcePath)],
+    directoryName: basename4(dirname8(skill.sourcePath)),
+    files: [basename4(skill.sourcePath)],
     frontmatter: skill.frontmatter,
     kind: "skill",
     path: relative10(graph.rootPath, skill.sourcePath),
@@ -15323,7 +15836,7 @@ async function explainPath(rootPath, inputPath, options = {}) {
     features: [],
     renderResults: [],
     notes: [
-      `No lock entry references ${target}. Pass a source path under ${graph.sourceDir}/ or a generated output path.`
+      `No lock entry references ${target}. Pass a source path under ${graph.sourceRoot}/ or a generated output path.`
     ]
   };
 }
@@ -15332,6 +15845,86 @@ async function listGeneratedEntries(rootPath, options = {}) {
   const rendered = scopedRenderedFiles(graph, await renderBuildGraph(graph), options.scopes);
   return collectLockItems(rendered).map((item) => item.entry);
 }
+async function suggestSource(rootPath, inputPath, options = {}) {
+  const write = options.write === true;
+  const explanation = await explainPath(rootPath, inputPath, options);
+  const generatedPath = explanation.path;
+  if (explanation.kind !== "generated" || explanation.entries.length === 0) {
+    return refusedSourceSuggestion(generatedPath, explanation.entries, "No Skillset lock entry owns this generated path.", [
+      "Run `skillset explain <path>` to inspect path provenance.",
+      "Update the adaptive source directly if this file is not Skillset-managed."
+    ]);
+  }
+  const uniqueSourcePaths = new Set(explanation.entries.map((entry) => entry.sourcePath));
+  if (uniqueSourcePaths.size !== 1) {
+    return refusedSourceSuggestion(generatedPath, explanation.entries, "Generated path has multiple source owners.", [
+      "Update the owning source files manually, then run `skillset build --yes`."
+    ]);
+  }
+  const [sourcePath] = [...uniqueSourcePaths];
+  if (sourcePath === undefined) {
+    return refusedSourceSuggestion(generatedPath, explanation.entries, "Generated path is missing source ownership.", [
+      "Run `skillset explain <path>` to inspect the stale or corrupt lock entry."
+    ]);
+  }
+  if (generatedPath.endsWith("/CHANGELOG.md") || generatedPath === "CHANGELOG.md") {
+    return refusedSourceSuggestion(generatedPath, explanation.entries, "Generated changelogs are managed projections, not source edit surfaces.", [
+      "Use `skillset change reason <@ref>` before release.",
+      "Use `skillset change amend <@ref>` for applied-history wording after release.",
+      "Use `skillset release amend <@ref>` for release-event metadata."
+    ], sourcePath);
+  }
+  const blockingDependency = explanation.entries.find((entry) => (entry.dependencies?.length ?? 0) > 0 || (entry.preprocessDependencies?.length ?? 0) > 0);
+  if (blockingDependency !== undefined) {
+    return refusedSourceSuggestion(generatedPath, explanation.entries, "Generated path includes dependencies or partials that are not safe to reverse-patch.", [
+      "Update the source file, resources, or partials manually, then run `skillset build --yes`."
+    ], sourcePath);
+  }
+  const primaryEntry = explanation.entries[0];
+  if (primaryEntry?.kind !== "standalone-skill" && primaryEntry?.kind !== "plugin-skill") {
+    return refusedSourceSuggestion(generatedPath, explanation.entries, "Only generated skill Markdown body edits are suggestible in v1.", [
+      "Update the adaptive source manually, then run `skillset build --yes`."
+    ], sourcePath);
+  }
+  if (!generatedPath.endsWith(".md") || !sourcePath.endsWith(".md")) {
+    return refusedSourceSuggestion(generatedPath, explanation.entries, "Only Markdown generated outputs are suggestible in v1.", [
+      "Update the adaptive source manually, then run `skillset build --yes`."
+    ], sourcePath);
+  }
+  const sourceAbsolute = resolve3(rootPath, sourcePath);
+  const generatedAbsolute = resolve3(rootPath, generatedPath);
+  const sourceParts = parseMarkdown(await readFile10(sourceAbsolute, "utf8"), sourcePath);
+  const generatedParts = parseMarkdown(await readFile10(generatedAbsolute, "utf8"), generatedPath);
+  if (sourceParts.body === generatedParts.body) {
+    const lockPath2 = lockPathForEntry(primaryEntry);
+    return {
+      entries: explanation.entries,
+      generatedPath,
+      ...lockPath2 === undefined ? {} : { lockPath: lockPath2 },
+      message: "Generated body matches the source body; no source edit is needed.",
+      nextSteps: ["Run `skillset diff` or `skillset check` to inspect any remaining generated drift."],
+      sourcePath,
+      status: "suggestible",
+      wouldWrite: false,
+      wrote: false
+    };
+  }
+  if (write) {
+    await writeFile4(sourceAbsolute, stringifyMarkdown(sourceParts.frontmatter, generatedParts.body), "utf8");
+  }
+  const lockPath = lockPathForEntry(primaryEntry);
+  return {
+    entries: explanation.entries,
+    generatedPath,
+    ...lockPath === undefined ? {} : { lockPath },
+    message: write ? "Updated the source Markdown body from the generated edit." : "Generated Markdown body can be moved back to the source file.",
+    nextSteps: write ? ["Run `skillset build --yes` to refresh generated output.", "Run `skillset change add` or `skillset change check` if the source edit needs change coverage."] : ["Review the body change, then rerun with `--write --yes` to update source.", "After accepting, run `skillset build --yes`."],
+    sourcePath,
+    status: write ? "written" : "suggestible",
+    wouldWrite: true,
+    wrote: write
+  };
+}
 function listFeatureCapabilities(featureId) {
   const features = featureId === undefined ? listSkillsetFeatures() : [getSkillsetFeature(featureId)].filter((feature2) => feature2 !== undefined);
   return features.map(featureCapability);
@@ -15509,6 +16102,25 @@ function joinOutputRoot2(outputRoot, file) {
     return file;
   return `${outputRoot}/${file}`;
 }
+function lockPathForEntry(entry) {
+  if (entry === undefined)
+    return;
+  return joinOutputRoot2(entry.outputRoot, ".skillset.lock");
+}
+function refusedSourceSuggestion(generatedPath, entries, message, nextSteps, sourcePath) {
+  const lockPath = lockPathForEntry(entries[0]);
+  return {
+    entries,
+    generatedPath,
+    ...lockPath === undefined ? {} : { lockPath },
+    message,
+    nextSteps,
+    ...sourcePath === undefined ? {} : { sourcePath },
+    status: "refused",
+    wouldWrite: false,
+    wrote: false
+  };
+}
 function explainSourceKind(graph, target) {
   if (graph.rules.some((rule) => relative11(graph.rootPath, rule.sourcePath) === target)) {
     return "source-instruction";
@@ -15637,7 +16249,7 @@ var DEFAULT_STRUCTURED_JSON_BASENAMES = new Set([".skillset.lock"]);
 // packages/core/src/deterministic-projection.ts
 var textEncoder4 = new TextEncoder;
 // packages/core/src/destination-ownership.ts
-import { basename as basename4 } from "path";
+import { basename as basename5 } from "path";
 var textDecoder5 = new TextDecoder;
 function classifyDestinationOwnership(args) {
   const file = classifyFileOwnership(args.path, args.target);
@@ -15743,7 +16355,7 @@ function codexInterfaceReason(owner, key) {
   return "Codex interface presentation can be explicitly overlaid by the distribution destination.";
 }
 function fieldSelector(path, ...parts) {
-  return `${basename4(path)}#/${parts.map(escapePointerSegment).join("/")}`;
+  return `${basename5(path)}#/${parts.map(escapePointerSegment).join("/")}`;
 }
 function escapePointerSegment(segment) {
   return segment.replaceAll("~", "~0").replaceAll("/", "~1");
@@ -15796,7 +16408,7 @@ var claudeGeneratedFields = new Set([
   "version"
 ]);
 // packages/core/src/distribution.ts
-import { readFile as readFile10 } from "fs/promises";
+import { readFile as readFile11 } from "fs/promises";
 import { createHash as createHash4 } from "crypto";
 import { resolve as resolve4 } from "path";
 async function planDistributions(rootPath, options = {}) {
@@ -15911,7 +16523,7 @@ async function distributionDestinationState(graph, config, destinationPath, cont
   if (root === undefined)
     return { status: "unknown" };
   try {
-    const current = await readFile10(resolve4(graph.rootPath, root, destinationPath));
+    const current = await readFile11(resolve4(graph.rootPath, root, destinationPath));
     return { content: current, status: bytesEqual4(current, content) ? "unchanged" : "change" };
   } catch (error) {
     if (isNotFound(error))
@@ -16016,7 +16628,7 @@ function isNodeError(error) {
   return error instanceof Error && "code" in error;
 }
 // packages/core/src/version-audit.ts
-import { readFile as readFile11 } from "fs/promises";
+import { readFile as readFile12 } from "fs/promises";
 async function auditVersions(rootPath, options = {}) {
   const graph = await loadBuildGraph(rootPath, options);
   const rendered = await renderBuildGraph(graph);
@@ -16031,7 +16643,7 @@ async function auditVersions(rootPath, options = {}) {
 async function auditVersionLocus(graph, expected) {
   let current;
   try {
-    current = await readFile11(resolveInside(graph.rootPath, expected.path));
+    current = await readFile12(resolveInside(graph.rootPath, expected.path));
   } catch (error) {
     if (isNotFound2(error)) {
       return versionLocus(expected, {
@@ -16250,12 +16862,12 @@ function isNotFound2(error) {
   return error instanceof Error && "code" in error && error.code === "ENOENT";
 }
 // apps/skillset/src/change-entries.ts
-import { readFile as readFile13, rm as rm3, stat as stat10 } from "fs/promises";
+import { readFile as readFile14, rm as rm3, stat as stat10 } from "fs/promises";
 import { join as join13 } from "path";
 
 // apps/skillset/src/change-status.ts
 import { createHash as createHash5 } from "crypto";
-import { mkdir as mkdir4, mkdtemp, readdir as readdir5, readFile as readFile12, rename, rm as rm2, stat as stat9, writeFile as writeFile4 } from "fs/promises";
+import { mkdir as mkdir4, mkdtemp, readdir as readdir6, readFile as readFile13, rename, rm as rm2, stat as stat9, writeFile as writeFile5 } from "fs/promises";
 import { tmpdir } from "os";
 import { dirname as dirname9, join as join12, relative as relative12 } from "path";
 // apps/skillset/src/git-env.ts
@@ -16303,9 +16915,13 @@ var PLUGIN_COMPANION_PATHS = [
 async function changeStatus(rootPath, options = {}) {
   const stagedSnapshot = options.staged === true ? await snapshotGitIndex(rootPath) : undefined;
   try {
-    const current = await collectSourceInventory(stagedSnapshot ?? rootPath, options);
-    const baseline = await resolveBaselineInventory(rootPath, options);
-    const generatedDrift = await diffSkillset(stagedSnapshot ?? rootPath, options);
+    const currentRoot = stagedSnapshot ?? rootPath;
+    const graph = await loadBuildGraph(currentRoot, options);
+    const releaseOptions = withDetectedSourceDir(options, graph);
+    const baselineOptions = options.sourceDir === undefined ? options : releaseOptions;
+    const current = await sourceInventoryForGraph(graph);
+    const baseline = await resolveBaselineInventory(rootPath, baselineOptions, releaseOptions);
+    const generatedDrift = await diffSkillset(currentRoot, releaseOptions);
     return {
       baseline: baseline.baseline,
       generatedDrift,
@@ -16322,6 +16938,12 @@ async function collectSourceInventory(rootPath, options = {}) {
   const graph = await loadBuildGraph(rootPath, options);
   return sourceInventoryForGraph(graph);
 }
+async function detectWorkspaceOptions(rootPath, options) {
+  return { ...options, sourceDir: await detectWorkspaceSourceDir(rootPath, options) };
+}
+function withDetectedSourceDir(options, graph) {
+  return { ...options, sourceDir: graph.sourceDir };
+}
 async function sourceInventoryForGraph(graph) {
   const units = [];
   units.push(await rootConfigUnit(graph));
@@ -16359,25 +16981,28 @@ async function sourceInventoryForGraph(graph) {
   };
 }
 async function rootConfigUnit(graph) {
-  const configPath = join12(graph.sourcePath, ROOT_CONFIG_FILE2);
-  const manifestPath = join12(graph.sourcePath, SOURCE_ROOT_DIR2, ROOT_SOURCE_MANIFEST_FILE2);
-  const sourcePaths = [relativePath(graph, configPath), relativePath(graph, manifestPath)];
+  const configPath = graph.rootConfigPath;
+  const manifestPath = graph.rootManifestPath;
+  const sourcePaths = sortedUnique2([relativePath(graph, configPath), relativePath(graph, manifestPath)]);
   const hash = createSourceHash("root-config");
   hash.update("metadata\x00");
-  hash.update(stringifyJson({ id: "root-config", sourcePaths }));
+  hash.update(stringifyJson({ id: "root-config", sourcePaths: [...sourcePaths] }));
   hash.update("\x00config\x00");
   await hashPathInto(hash, configPath);
-  hash.update("\x00manifest\x00");
-  await hashPathInto(hash, manifestPath);
+  if (manifestPath !== configPath) {
+    hash.update("\x00manifest\x00");
+    await hashPathInto(hash, manifestPath);
+  }
+  const regions = manifestPath === configPath ? await regionsForYaml(configPath) : mergeRegions([
+    ...await regionsForYaml(configPath),
+    ...await regionsForYaml(manifestPath)
+  ]);
   return {
     hash: digest(hash),
     hashSchema: SOURCE_HASH_SCHEMA,
     id: selectorForRootConfig(),
     kind: "root-config",
-    regions: mergeRegions([
-      ...await regionsForYaml(configPath),
-      ...await regionsForYaml(manifestPath)
-    ]),
+    regions,
     sourcePath: sourcePaths[0] ?? "",
     sourcePaths
   };
@@ -16396,7 +17021,7 @@ async function fileUnit(graph, kind, id, sourcePath, regions = [], hashId = id)
 }
 async function skillUnit(graph, skill, kind, id, plugin) {
   const sourceDir = dirname9(skill.sourcePath);
-  const preprocessDependencies = await skillPreprocessDependencies(graph, skill, plugin);
+  const preprocessDependencies = await skillPreprocessDependencies2(graph, skill, plugin);
   const sourcePaths = await sourcePathsForSkill(graph, sourceDir, skill.resources, preprocessDependencies);
   const hash = createSourceHash(kind);
   hash.update("id\x00");
@@ -16434,7 +17059,7 @@ async function ruleUnit(graph, rule) {
     kind: "instruction",
     regions: regionsForRecord(rule.frontmatter),
     sourcePath,
-    sourcePaths: sortedUnique2([sourcePath, ...preprocessDependencies.map((path2) => relativePath(graph, path2))])
+    sourcePaths: sortedUnique2([sourcePath, ...preprocessDependencies])
   };
 }
 async function projectAgentUnit(graph, agent) {
@@ -16458,7 +17083,7 @@ async function projectAgentUnit(graph, agent) {
     kind: "project-agent",
     regions: regionsForRecord(agent.frontmatter),
     sourcePath,
-    sourcePaths: sortedUnique2([sourcePath, ...preprocessDependencies.map((path2) => relativePath(graph, path2))])
+    sourcePaths: sortedUnique2([sourcePath, ...preprocessDependencies])
   };
 }
 async function islandUnit(graph, island) {
@@ -16475,7 +17100,7 @@ async function islandUnit(graph, island) {
   hash.update("\x00relativePath\x00");
   hash.update(island.relativePath);
   hash.update("\x00content\x00");
-  hash.update(await readFile12(island.sourcePath));
+  hash.update(await readFile13(island.sourcePath));
   hash.update("\x00");
   await hashPreprocessDependencies(hash, graph, preprocessDependencies);
   const sourcePath = relativePath(graph, island.sourcePath);
@@ -16486,7 +17111,7 @@ async function islandUnit(graph, island) {
     kind: "target-native-island",
     regions: [{ name: "target-native", severityBearing: true }],
     sourcePath,
-    sourcePaths: sortedUnique2([sourcePath, ...preprocessDependencies.map((path2) => relativePath(graph, path2))])
+    sourcePaths: sortedUnique2([sourcePath, ...preprocessDependencies])
   };
 }
 async function pluginFeatureUnit(graph, plugin, feature2) {
@@ -16562,7 +17187,7 @@ async function sourcePathsForSkill(graph, sourceDir, resources, preprocessDepend
     ...resources.flatMap((resource) => [
       relativePath(graph, resource.sourcePath)
     ]),
-    ...preprocessDependencies.map((path2) => relativePath(graph, path2))
+    ...preprocessDependencies
   ]);
 }
 async function sourcePathsForPath(graph, sourcePath, shouldSkip) {
@@ -16583,7 +17208,7 @@ async function hashPathInto(hash, sourcePath) {
   const stats = await stat9(sourcePath);
   if (stats.isFile()) {
     hash.update("file\x00");
-    hash.update(await readFile12(sourcePath));
+    hash.update(await readFile13(sourcePath));
     hash.update("\x00");
     return;
   }
@@ -16597,7 +17222,7 @@ async function hashDirectory(hash, sourceDir, shouldSkip) {
       continue;
     hash.update(relativeFile);
     hash.update("\x00");
-    hash.update(await readFile12(file));
+    hash.update(await readFile13(file));
     hash.update("\x00");
   }
 }
@@ -16618,31 +17243,31 @@ async function hashResources(hash, resources) {
 async function hashPreprocessDependencies(hash, graph, dependencies) {
   for (const dependency of [...dependencies].sort(compareStrings)) {
     hash.update("preprocess\x00");
-    hash.update(relativePath(graph, dependency));
+    hash.update(dependency);
     hash.update("\x00");
-    hash.update(await readFile12(dependency));
+    hash.update(readPreprocessDependencySync(graph.rootPath, dependency));
     hash.update("\x00");
   }
 }
-async function skillPreprocessDependencies(graph, skill, plugin) {
+async function skillPreprocessDependencies2(graph, skill, plugin) {
   const dependencies = new Set;
   const context = {
     frontmatter: skill.frontmatter,
     preprocessDependencies: dependencies,
     rootPath: graph.rootPath,
     sourcePath: skill.sourcePath,
-    sourceRoot: join12(graph.sourceDir, "src"),
+    sourceRoot: graph.sourceRoot,
     ...plugin === undefined ? {} : { pluginPath: plugin.path }
   };
   await preprocessText(skill.body, context);
   const sourceOpenAiPath = join12(dirname9(skill.sourcePath), "agents/openai.yaml");
   if (await exists7(sourceOpenAiPath)) {
-    await preprocessText(await readFile12(sourceOpenAiPath, "utf8"), {
+    await preprocessText(await readFile13(sourceOpenAiPath, "utf8"), {
       ...context,
       sourcePath: sourceOpenAiPath
     });
   }
-  return [...dependencies].sort(compareStrings);
+  return formattedPreprocessDependencies2(graph, dependencies);
 }
 async function rulePreprocessDependencies(graph, rule) {
   const dependencies = new Set;
@@ -16651,14 +17276,14 @@ async function rulePreprocessDependencies(graph, rule) {
     preprocessDependencies: dependencies,
     rootPath: graph.rootPath,
     sourcePath: rule.sourcePath,
-    sourceRoot: join12(graph.sourceDir, "src"),
+    sourceRoot: graph.sourceRoot,
     variables: {
       "skillset.output_dir": ".",
       "skillset.repo_root": ".",
       "skillset.source_rule": relativePath(graph, rule.sourcePath)
     }
   });
-  return [...dependencies].sort(compareStrings);
+  return formattedPreprocessDependencies2(graph, dependencies);
 }
 async function projectAgentPreprocessDependencies2(graph, agent) {
   const dependencies = new Set;
@@ -16670,7 +17295,7 @@ async function projectAgentPreprocessDependencies2(graph, agent) {
       preprocessDependencies: dependencies,
       rootPath: graph.rootPath,
       sourcePath: agent.sourcePath,
-      sourceRoot: join12(graph.sourceDir, "src")
+      sourceRoot: graph.sourceRoot
     });
   };
   await collect(agent.body);
@@ -16678,13 +17303,13 @@ async function projectAgentPreprocessDependencies2(graph, agent) {
   await collect(readString(agent.targets.claude.options, "initialPrompt"));
   await collect(readString(agent.targets.codex.options, "initialPrompt"));
   await collect(readString(agent.targets.codex.options, "developer_instructions"));
-  return [...dependencies].sort(compareStrings);
+  return formattedPreprocessDependencies2(graph, dependencies);
 }
 async function islandPreprocessDependencies(graph, island) {
   if (!isTextIslandFile2(island.relativePath))
     return [];
   const dependencies = new Set;
-  const source2 = await readFile12(island.sourcePath, "utf8");
+  const source2 = await readFile13(island.sourcePath, "utf8");
   if (island.relativePath.endsWith(".md")) {
     const parsed = parseMarkdown(source2, island.sourcePath);
     await preprocessText(parsed.body, {
@@ -16692,7 +17317,7 @@ async function islandPreprocessDependencies(graph, island) {
       preprocessDependencies: dependencies,
       rootPath: graph.rootPath,
       sourcePath: island.sourcePath,
-      sourceRoot: join12(graph.sourceDir, "src")
+      sourceRoot: graph.sourceRoot
     });
   } else {
     await preprocessText(source2, {
@@ -16700,10 +17325,13 @@ async function islandPreprocessDependencies(graph, island) {
       preprocessDependencies: dependencies,
       rootPath: graph.rootPath,
       sourcePath: island.sourcePath,
-      sourceRoot: join12(graph.sourceDir, "src")
+      sourceRoot: graph.sourceRoot
     });
   }
-  return [...dependencies].sort(compareStrings);
+  return formattedPreprocessDependencies2(graph, dependencies);
+}
+function formattedPreprocessDependencies2(graph, dependencies) {
+  return [...dependencies].map((dependency) => formatPreprocessDependency(graph.rootPath, dependency)).sort(compareStrings);
 }
 function isTextIslandFile2(path2) {
   return /\.(json|md|rules|toml|txt|ya?ml)$/.test(path2);
@@ -16778,15 +17406,15 @@ function compareInventories(current, baseline) {
   }
   return changes.sort((left, right) => compareStrings(left.id, right.id));
 }
-async function resolveBaselineInventory(rootPath, options) {
-  if (options.since !== undefined) {
-    return inventoryFromGitRef(rootPath, options.since, options);
+async function resolveBaselineInventory(rootPath, baselineOptions, releaseOptions) {
+  if (baselineOptions.since !== undefined) {
+    return inventoryFromGitRef(rootPath, baselineOptions.since, baselineOptions);
   }
-  if (options.staged === true) {
-    return inventoryFromGitRef(rootPath, "HEAD", options);
+  if (baselineOptions.staged === true) {
+    return inventoryFromGitRef(rootPath, "HEAD", baselineOptions);
   }
-  const fallback = await fallbackBaselineInventory(rootPath, options);
-  const releaseInventory = await sourceInventoryFromReleaseState(rootPath, options, fallback.inventory);
+  const fallback = await fallbackBaselineInventory(rootPath, baselineOptions);
+  const releaseInventory = await sourceInventoryFromReleaseState(rootPath, releaseOptions, fallback.inventory);
   if (releaseInventory !== undefined)
     return releaseInventory;
   return fallback;
@@ -16801,8 +17429,7 @@ async function fallbackBaselineInventory(rootPath, options) {
 async function inventoryFromGitRef(rootPath, ref, options) {
   const snapshotPath = await snapshotGitRef(rootPath, ref);
   try {
-    await normalizeLegacyBaselineSnapshot(snapshotPath, options);
-    const inventory = await collectSourceInventory(snapshotPath, options);
+    const inventory = await collectGitSnapshotInventory(snapshotPath, options);
     const resolvedRef = await gitRevParse(rootPath, ref);
     return {
       baseline: { kind: "git-ref", ref, ...resolvedRef === undefined ? {} : { resolvedRef } },
@@ -16812,8 +17439,32 @@ async function inventoryFromGitRef(rootPath, ref, options) {
     await rm2(snapshotPath, { force: true, recursive: true });
   }
 }
+async function collectGitSnapshotInventory(snapshotPath, options) {
+  try {
+    await normalizeLegacyBaselineSnapshot(snapshotPath, options);
+    return await collectSourceInventory(snapshotPath, options);
+  } catch (error) {
+    if (options.sourceDir === undefined || !canRetryBaselineWithDetectedLayout(error))
+      throw error;
+    const autoOptions = withoutSourceDir(options);
+    await normalizeLegacyBaselineSnapshot(snapshotPath, autoOptions);
+    return collectSourceInventory(snapshotPath, autoOptions);
+  }
+}
+function withoutSourceDir(options) {
+  const { sourceDir: _sourceDir, ...rest } = options;
+  return rest;
+}
+function canRetryBaselineWithDetectedLayout(error) {
+  if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT")
+    return true;
+  const message = error instanceof Error ? error.message : String(error);
+  return message.startsWith("skillset: no source plugins, skills, rules, project agents, or provider source found");
+}
 async function normalizeLegacyBaselineSnapshot(snapshotPath, options) {
   const sourceDir = options.sourceDir ?? ".skillset";
+  if (sourceDir === ".")
+    return;
   const skillsetPath = join12(snapshotPath, sourceDir);
   if (!await exists7(skillsetPath))
     return;
@@ -16826,7 +17477,7 @@ async function normalizeLegacyBaselineSnapshot(snapshotPath, options) {
 async function moveLegacyBaselinePluginProviderDirs(pluginsPath) {
   if (!await exists7(pluginsPath))
     return;
-  const entries = await readdir5(pluginsPath, { withFileTypes: true });
+  const entries = await readdir6(pluginsPath, { withFileTypes: true });
   for (const entry of entries) {
     if (!entry.isDirectory())
       continue;
@@ -16839,7 +17490,7 @@ async function splitLegacyBaselineRootConfig(skillsetPath) {
   const configPath = join12(skillsetPath, ROOT_CONFIG_FILE2);
   if (!await exists7(configPath))
     return;
-  const config2 = parseYamlRecord(await readFile12(configPath, "utf8"), configPath);
+  const config2 = parseYamlRecord(await readFile13(configPath, "utf8"), configPath);
   const manifest = sourceManifestFromLegacyRootConfig(config2);
   if (manifest === undefined)
     return;
@@ -16848,8 +17499,8 @@ async function splitLegacyBaselineRootConfig(skillsetPath) {
     throw new Error(`skillset: cannot normalize baseline with both root source metadata and ${manifestPath}`);
   }
   await mkdir4(dirname9(manifestPath), { recursive: true });
-  await writeFile4(manifestPath, stringifyYaml(manifest), "utf8");
-  await writeFile4(configPath, stringifyLegacyWorkspaceConfig(workspaceConfigFromLegacyRootConfig(config2)), "utf8");
+  await writeFile5(manifestPath, stringifyYaml(manifest), "utf8");
+  await writeFile5(configPath, stringifyLegacyWorkspaceConfig(workspaceConfigFromLegacyRootConfig(config2)), "utf8");
 }
 function sourceManifestFromLegacyRootConfig(record) {
   const manifest = {};
@@ -16903,13 +17554,16 @@ async function sourceInventoryFromReleaseState(rootPath, options, fallback) {
     });
   }
   return {
-    baseline: { hashSchema: SOURCE_HASH_SCHEMA, kind: "source-inventory", label: ".skillset/changes/state.json" },
+    baseline: { hashSchema: SOURCE_HASH_SCHEMA, kind: "source-inventory", label: releaseStateRelativePath(options) },
     inventory: {
       hashSchema: SOURCE_HASH_SCHEMA,
       units: [...units.values()].sort((left, right) => compareStrings(left.id, right.id))
     }
   };
 }
+function releaseStateRelativePath(options) {
+  return join12(options.sourceDir ?? ".skillset", "changes/state.json");
+}
 function inferredReleaseUnit(id, hash) {
   const kind = kindForSourceUnitId(id);
   return {
@@ -16952,7 +17606,7 @@ async function sourceInventoryFromLock(rootPath, _options) {
     return;
   let parsed;
   try {
-    parsed = JSON.parse(await readFile12(lockPath, "utf8"));
+    parsed = JSON.parse(await readFile13(lockPath, "utf8"));
   } catch {
     return;
   }
@@ -17042,7 +17696,7 @@ ${stderr.trim()}`);
 }
 async function regionsForYaml(sourcePath) {
   try {
-    return regionsForRecord(parseYamlRecord(await readFile12(sourcePath, "utf8"), sourcePath));
+    return regionsForRecord(parseYamlRecord(await readFile13(sourcePath, "utf8"), sourcePath));
   } catch {
     return [];
   }
@@ -17108,7 +17762,7 @@ async function exists7(path2) {
 }
 
 // apps/skillset/src/change-entries.ts
-var PENDING_DIR = "changes/pending";
+var PENDING_DIR = "changes";
 var DEFAULT_REASON_MIN_LENGTH = 40;
 var CHANGE_ID_PATTERN = /^[0-9a-f]{12}$/;
 var CHANGE_REF_MIN_LENGTH = 6;
@@ -17118,8 +17772,10 @@ async function changeCheck(rootPath, options = {}) {
   const stagedSnapshot = options.staged === true ? await snapshotGitIndex(rootPath) : undefined;
   try {
     const status = await changeStatus(rootPath, options);
-    const entries = await readPendingChangeEntries(stagedSnapshot ?? rootPath, options);
-    return await validateChangeCheck(stagedSnapshot ?? rootPath, status, entries, options);
+    const currentRoot = stagedSnapshot ?? rootPath;
+    const storageOptions = await detectWorkspaceOptions(currentRoot, options);
+    const entries = await readPendingChangeEntries(currentRoot, storageOptions);
+    return await validateChangeCheck(currentRoot, status, entries, storageOptions);
   } finally {
     if (stagedSnapshot !== undefined)
       await rm3(stagedSnapshot, { force: true, recursive: true });
@@ -17190,7 +17846,7 @@ async function readPendingChangeEntries(rootPath, options = {}) {
   for (const file of files.sort(compareStrings)) {
     const path2 = join13(sourceDir, PENDING_DIR, file).replaceAll("\\", "/");
     const absolutePath = resolveInside(rootPath, path2);
-    const parts = parseMarkdown(await readFile13(absolutePath, "utf8"), absolutePath);
+    const parts = parseMarkdown(await readFile14(absolutePath, "utf8"), absolutePath);
     const id = readString(parts.frontmatter, "id");
     const bump = readBump(parts.frontmatter.bump);
     const ignored = parts.frontmatter.ignored === true;
@@ -17427,8 +18083,11 @@ function readEvidenceHash(record) {
 }
 async function readReasonMinLength(rootPath, options) {
   const sourceDir = options.sourceDir ?? ".skillset";
-  const configPath = resolveInside(rootPath, join13(sourceDir, "config.yaml"));
-  const config2 = parseYamlRecord(await readFile13(configPath, "utf8"), configPath);
+  const configPaths = sourceDir === "." ? ["skillset.yaml"] : [join13(sourceDir, "config.yaml"), join13(sourceDir, "skillset.yaml")];
+  const resolvedConfigPath = await firstExistingPath(configPaths.map((path2) => resolveInside(rootPath, path2)));
+  if (resolvedConfigPath === undefined)
+    return DEFAULT_REASON_MIN_LENGTH;
+  const config2 = parseYamlRecord(await readFile14(resolvedConfigPath, "utf8"), resolvedConfigPath);
   const changes = config2.changes;
   if (!isJsonRecord(changes))
     return DEFAULT_REASON_MIN_LENGTH;
@@ -17438,6 +18097,13 @@ async function readReasonMinLength(rootPath, options) {
   const minLength = reason.minLength;
   return typeof minLength === "number" && Number.isInteger(minLength) && minLength > 0 ? minLength : DEFAULT_REASON_MIN_LENGTH;
 }
+async function firstExistingPath(paths) {
+  for (const path2 of paths) {
+    if (await exists8(path2))
+      return path2;
+  }
+  return;
+}
 function scopeClass(scope) {
   const normalizedScope = sourceUnitSelector(scope);
   return normalizedScope.startsWith("user:") || normalizedScope.startsWith("global:") ? "user" : "repo";
@@ -17458,48 +18124,43 @@ async function exists8(path2) {
 }
 
 // apps/skillset/src/adopt.ts
-import { mkdtemp as mkdtemp3, mkdir as mkdir7, readFile as readFile16, rm as rm5, stat as stat14, writeFile as writeFile7 } from "fs/promises";
+import { mkdtemp as mkdtemp3, mkdir as mkdir7, readFile as readFile17, rm as rm5, stat as stat13, writeFile as writeFile8 } from "fs/promises";
 import { tmpdir as tmpdir2 } from "os";
-import { basename as basename7, dirname as dirname12, join as join17, relative as relative15, resolve as resolve7 } from "path";
+import { basename as basename8, dirname as dirname12, join as join16, relative as relative15, resolve as resolve7 } from "path";
 
 // apps/skillset/src/import.ts
-import { mkdir as mkdir5, mkdtemp as mkdtemp2, readdir as readdir6, readFile as readFile14, realpath, rename as rename2, rm as rm4, stat as stat12, writeFile as writeFile5 } from "fs/promises";
+import { mkdir as mkdir5, mkdtemp as mkdtemp2, readdir as readdir7, readFile as readFile15, realpath, rename as rename2, rm as rm4, stat as stat11, writeFile as writeFile6 } from "fs/promises";
 import { homedir } from "os";
-import { basename as basename5, dirname as dirname10, join as join15, relative as relative13, resolve as resolve5 } from "path";
-
+import { basename as basename6, dirname as dirname10, join as join14, relative as relative13, resolve as resolve5 } from "path";
 // apps/skillset/src/adoption.ts
-import { stat as stat11 } from "fs/promises";
-import { join as join14 } from "path";
-var ROOT_CONFIG_FILE3 = "config.yaml";
 var NO_SOURCE_MESSAGE = "skillset: no source plugins, skills, rules, project agents, or provider source found";
 async function seedReleaseBaselines(rootPath, options = {}, seedOptions = {}) {
-  const sourceDir = options.sourceDir ?? ".skillset";
-  const configPath = resolveInside(rootPath, join14(sourceDir, ROOT_CONFIG_FILE3));
-  if (!await exists9(configPath)) {
-    return {
-      conflicts: [],
-      entries: [],
-      skippedReason: `${sourceDir}/${ROOT_CONFIG_FILE3} not found`,
-      write: seedOptions.write === true
-    };
-  }
   let graph;
   try {
     graph = await loadBuildGraph(rootPath, options);
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    if (message.startsWith(NO_SOURCE_MESSAGE)) {
+    if (isErrno2(error, "ENOENT") && !await workspaceMarkerExists(rootPath, options)) {
       return {
         conflicts: [],
         entries: [],
-        skippedReason: "no source units to adopt",
+        skippedReason: "skillset workspace not found",
         write: seedOptions.write === true
       };
     }
-    throw error;
-  }
-  const inventory = await collectSourceInventory(rootPath, options);
-  const state = await readReleaseState(rootPath, options);
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.startsWith(NO_SOURCE_MESSAGE)) {
+      return {
+        conflicts: [],
+        entries: [],
+        skippedReason: "no source units to adopt",
+        write: seedOptions.write === true
+      };
+    }
+    throw error;
+  }
+  const resolvedOptions = { ...options, sourceDir: graph.sourceDir };
+  const inventory = await collectSourceInventory(rootPath, resolvedOptions);
+  const state = await readReleaseState(rootPath, resolvedOptions);
   const scopeFilter = seedOptions.scopes === undefined ? undefined : new Set(seedOptions.scopes.map(sourceUnitSelector));
   const entries = [];
   const conflicts = [];
@@ -17551,7 +18212,7 @@ async function seedReleaseBaselines(rootPath, options = {}, seedOptions = {}) {
   }
   let path2;
   if (seedOptions.write === true && entries.some((entry) => entry.status === "create")) {
-    path2 = await writeReleaseState(rootPath, { scopes }, options);
+    path2 = await writeReleaseState(rootPath, { scopes }, resolvedOptions);
   }
   return {
     conflicts,
@@ -17592,16 +18253,16 @@ function sourceRootVersion(graph) {
 function sourcePluginVersion(graph, plugin) {
   return readString(plugin.metadata, "version") ?? sourceRootVersion(graph);
 }
-async function exists9(path2) {
-  try {
-    await stat11(path2);
-    return true;
-  } catch (error) {
-    if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
-      return false;
-    }
-    throw error;
+async function workspaceMarkerExists(rootPath, options) {
+  if (options.sourceDir === ".")
+    return Bun.file(`${rootPath}/skillset.yaml`).exists();
+  if (options.sourceDir !== undefined) {
+    return await Bun.file(`${rootPath}/${options.sourceDir}/skillset.yaml`).exists() || await Bun.file(`${rootPath}/${options.sourceDir}/config.yaml`).exists();
   }
+  return await Bun.file(`${rootPath}/skillset.yaml`).exists() || await Bun.file(`${rootPath}/.skillset/skillset.yaml`).exists() || await Bun.file(`${rootPath}/.skillset/config.yaml`).exists();
+}
+function isErrno2(error, code) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
 
 // apps/skillset/src/import.ts
@@ -17665,15 +18326,16 @@ async function importSources(options) {
 }
 async function importSource(options) {
   const sourcePath = resolve5(options.sourcePath);
-  const sourceDir = options.sourceDir ?? DEFAULT_SOURCE_DIR2;
+  const sourceDir = await resolveImportSourceDir(options.rootPath, options.sourceDir);
+  const sourceRoot = sourceDir === "." ? "skillset" : join14(sourceDir, SOURCE_ROOT_DIR3);
   const name = await resolveImportName(sourcePath, options);
-  const targetPath = resolveInside(options.rootPath, join15(sourceDir, SOURCE_ROOT_DIR3, options.kind === "plugin" ? PLUGINS_DIR2 : SKILLS_DIR2, name));
-  if (await exists10(targetPath)) {
+  const targetPath = resolveInside(options.rootPath, join14(sourceRoot, options.kind === "plugin" ? PLUGINS_DIR2 : SKILLS_DIR2, name));
+  if (await exists9(targetPath)) {
     throw new Error(`skillset: import target already exists: ${targetPath}. ` + "Import never overwrites; remove the existing source or import under a different --name.");
   }
   const targetParent = dirname10(targetPath);
   await mkdir5(targetParent, { recursive: true });
-  const stagingPath = await mkdtemp2(join15(targetParent, `.${basename5(targetPath)}.tmp-`));
+  const stagingPath = await mkdtemp2(join14(targetParent, `.${basename6(targetPath)}.tmp-`));
   let committed = false;
   try {
     const copiedFiles = await copyImportSource(sourcePath, stagingPath, options.kind, name);
@@ -17682,7 +18344,7 @@ async function importSource(options) {
     }
     const frontmatter = await readImportedFrontmatter(stagingPath, options.kind);
     const classification = classifyFrontmatter(frontmatter);
-    if (await exists10(targetPath)) {
+    if (await exists9(targetPath)) {
       throw new Error(`skillset: import target already exists: ${targetPath}. ` + "Import never overwrites; remove the existing source or import under a different --name.");
     }
     await rename2(stagingPath, targetPath);
@@ -17729,6 +18391,23 @@ async function importSource(options) {
     }
   }
 }
+async function resolveImportSourceDir(rootPath, explicitSourceDir) {
+  if (explicitSourceDir !== undefined)
+    return explicitSourceDir;
+  try {
+    return await detectWorkspaceSourceDir(rootPath);
+  } catch (error) {
+    if (isMissingWorkspace(error))
+      return DEFAULT_SOURCE_DIR2;
+    throw error;
+  }
+}
+function isMissingWorkspace(error) {
+  if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT")
+    return true;
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes("skillset workspace not found") || message.includes("no source plugins, skills, rules");
+}
 async function seedImportedBaselines(rootPath, options) {
   const includeScope = (scope) => {
     if (options.kind === "skill")
@@ -17790,20 +18469,20 @@ function isClaudeToolPolicyField(field) {
   return field === "allowed-tools" || field === "disallowed-tools" || field === "disable-model-invocation";
 }
 function importSourcePath(rootPath, targetPath, kind) {
-  const path2 = kind === "skill" ? join15(targetPath, "SKILL.md") : join15(targetPath, "skillset.yaml");
+  const path2 = kind === "skill" ? join14(targetPath, "SKILL.md") : join14(targetPath, "skillset.yaml");
   return relative13(rootPath, path2).replaceAll("\\", "/");
 }
 async function readImportedFrontmatter(targetPath, kind) {
   if (kind === "skill") {
-    const skillFile = join15(targetPath, "SKILL.md");
-    if (!await exists10(skillFile))
+    const skillFile = join14(targetPath, "SKILL.md");
+    if (!await exists9(skillFile))
       return {};
-    return parseMarkdown(await readFile14(skillFile, "utf8"), skillFile).frontmatter;
+    return parseMarkdown(await readFile15(skillFile, "utf8"), skillFile).frontmatter;
   }
-  const configPath = join15(targetPath, "skillset.yaml");
-  if (!await exists10(configPath))
+  const configPath = join14(targetPath, "skillset.yaml");
+  if (!await exists9(configPath))
     return {};
-  return parseYamlRecord(await readFile14(configPath, "utf8"), configPath);
+  return parseYamlRecord(await readFile15(configPath, "utf8"), configPath);
 }
 async function resolveImportName(sourcePath, options) {
   if (options.name !== undefined) {
@@ -17811,22 +18490,22 @@ async function resolveImportName(sourcePath, options) {
   }
   if (options.kind === "skill") {
     const skillPath = await resolveSkillFile(sourcePath);
-    const parts = parseMarkdown(await readFile14(skillPath, "utf8"), skillPath);
+    const parts = parseMarkdown(await readFile15(skillPath, "utf8"), skillPath);
     const metadata2 = readSkillsetMetadata(parts.frontmatter, skillPath);
-    return validateSlug(readSkillsetName(metadata2, readString(parts.frontmatter, "name") ?? basename5(dirname10(skillPath)), skillPath), `skillset.name in ${skillPath}`);
+    return validateSlug(readSkillsetName(metadata2, readString(parts.frontmatter, "name") ?? basename6(dirname10(skillPath)), skillPath), `skillset.name in ${skillPath}`);
   }
   const configPath = await resolvePluginConfig(sourcePath);
   if (configPath === undefined) {
-    return validateSlug(basename5(sourcePath), "plugin directory");
+    return validateSlug(basename6(sourcePath), "plugin directory");
   }
-  const config2 = parseYamlRecord(await readFile14(configPath, "utf8"), configPath);
+  const config2 = parseYamlRecord(await readFile15(configPath, "utf8"), configPath);
   const metadata = readSkillsetMetadata(config2, configPath);
-  return validateSlug(readSkillsetName(metadata, basename5(sourcePath), configPath), `skillset.name in ${configPath}`);
+  return validateSlug(readSkillsetName(metadata, basename6(sourcePath), configPath), `skillset.name in ${configPath}`);
 }
 async function copyImportSource(sourcePath, targetPath, kind, name) {
-  const stats = await stat12(sourcePath);
+  const stats = await stat11(sourcePath);
   if (stats.isFile()) {
-    if (kind !== "skill" || basename5(sourcePath) !== "SKILL.md") {
+    if (kind !== "skill" || basename6(sourcePath) !== "SKILL.md") {
       throw new Error("skillset: importing a file is only supported for skill SKILL.md files");
     }
   }
@@ -17834,11 +18513,11 @@ async function copyImportSource(sourcePath, targetPath, kind, name) {
   const copied = [];
   for (const file of await collectFiles6(copyRoot)) {
     const relativePath2 = relativeImportPath(copyRoot, file, kind);
-    await mkdir5(dirname10(join15(targetPath, relativePath2)), { recursive: true });
-    await writeFile5(join15(targetPath, relativePath2), await readFile14(file));
+    await mkdir5(dirname10(join14(targetPath, relativePath2)), { recursive: true });
+    await writeFile6(join14(targetPath, relativePath2), await readFile15(file));
     copied.push(relativePath2);
   }
-  if (kind === "plugin" && !await exists10(join15(targetPath, "skillset.yaml"))) {
+  if (kind === "plugin" && !await exists9(join14(targetPath, "skillset.yaml"))) {
     await writeImportedPluginConfig(targetPath, name);
     copied.push("skillset.yaml");
   }
@@ -17846,21 +18525,21 @@ async function copyImportSource(sourcePath, targetPath, kind, name) {
 }
 async function stampImportedOrigins(targetPath, sourcePath, copiedFiles, kind, sourceOrigin) {
   if (kind === "plugin") {
-    await writeYamlSourceOrigin(join15(targetPath, "skillset.yaml"), sourceOrigin(sourcePath));
+    await writeYamlSourceOrigin(join14(targetPath, "skillset.yaml"), sourceOrigin(sourcePath));
   }
   for (const file of copiedFiles) {
-    if (basename5(file) !== "SKILL.md")
+    if (basename6(file) !== "SKILL.md")
       continue;
-    await writeMarkdownSourceOrigin(join15(targetPath, file), sourceOrigin(sourcePath, file));
+    await writeMarkdownSourceOrigin(join14(targetPath, file), sourceOrigin(sourcePath, file));
   }
 }
 async function writeYamlSourceOrigin(path2, origin) {
-  const config2 = parseYamlRecord(await readFile14(path2, "utf8"), path2);
-  await writeFile5(path2, stringifyYaml(withSkillsetOrigin(config2, origin)));
+  const config2 = parseYamlRecord(await readFile15(path2, "utf8"), path2);
+  await writeFile6(path2, stringifyYaml(withSkillsetOrigin(config2, origin)));
 }
 async function writeMarkdownSourceOrigin(path2, origin) {
-  const parts = parseMarkdown(await readFile14(path2, "utf8"), path2);
-  await writeFile5(path2, stringifyMarkdown(withSkillsetOrigin(parts.frontmatter, origin), parts.body));
+  const parts = parseMarkdown(await readFile15(path2, "utf8"), path2);
+  await writeFile6(path2, stringifyMarkdown(withSkillsetOrigin(parts.frontmatter, origin), parts.body));
 }
 function withSkillsetOrigin(record, origin) {
   const existing = isJsonRecord(record.skillset) ? record.skillset : {};
@@ -17887,24 +18566,24 @@ function relativeImportPath(sourceRoot, file, kind) {
   return relativePath2;
 }
 async function resolveSkillFile(sourcePath) {
-  const stats = await stat12(sourcePath);
+  const stats = await stat11(sourcePath);
   if (stats.isFile())
     return sourcePath;
-  return join15(sourcePath, "SKILL.md");
+  return join14(sourcePath, "SKILL.md");
 }
 async function resolvePluginConfig(sourcePath) {
   for (const file of ["config.yaml", "skillset.yaml"]) {
-    const candidate = join15(sourcePath, file);
-    if (await exists10(candidate))
+    const candidate = join14(sourcePath, file);
+    if (await exists9(candidate))
       return candidate;
   }
   return;
 }
 async function collectFiles6(root) {
-  const entries = await readdir6(root, { withFileTypes: true });
+  const entries = await readdir7(root, { withFileTypes: true });
   const files = [];
   for (const entry of entries.sort((left, right) => compareStrings(left.name, right.name))) {
-    const path2 = join15(root, entry.name);
+    const path2 = join14(root, entry.name);
     if (entry.isDirectory()) {
       files.push(...await collectFiles6(path2));
     } else if (entry.isFile() && entry.name !== ".DS_Store") {
@@ -17923,12 +18602,12 @@ function resolveImportSourcePath(options) {
 function defaultProviderSkillRoot(provider) {
   const home = homedir();
   if (provider === "agents")
-    return join15(home, ".agents", "skills");
+    return join14(home, ".agents", "skills");
   if (provider === "claude")
-    return join15(home, ".claude", "skills");
+    return join14(home, ".claude", "skills");
   if (provider === "codex")
-    return join15(home, ".codex", "skills");
-  return join15(home, ".skillset");
+    return join14(home, ".codex", "skills");
+  return join14(home, ".skillset");
 }
 async function planImports(sourcePath, requestedKind) {
   if (requestedKind === "skill") {
@@ -17977,46 +18656,46 @@ async function planImports(sourcePath, requestedKind) {
   throw new Error(`skillset: could not infer import kind for ${sourcePath}. ` + "Use --kind skill, --kind skills, --kind plugin, or --kind plugins.");
 }
 async function isSkillSource(sourcePath) {
-  if (!await exists10(sourcePath))
+  if (!await exists9(sourcePath))
     return false;
-  const stats = await stat12(sourcePath);
+  const stats = await stat11(sourcePath);
   if (stats.isFile())
-    return basename5(sourcePath) === "SKILL.md";
+    return basename6(sourcePath) === "SKILL.md";
   if (!stats.isDirectory())
     return false;
-  return exists10(join15(sourcePath, "SKILL.md"));
+  return exists9(join14(sourcePath, "SKILL.md"));
 }
 async function isPluginSource(sourcePath) {
-  if (!await exists10(sourcePath))
+  if (!await exists9(sourcePath))
     return false;
-  const stats = await stat12(sourcePath);
+  const stats = await stat11(sourcePath);
   if (!stats.isDirectory())
     return false;
-  return await exists10(join15(sourcePath, "skillset.yaml")) || await exists10(join15(sourcePath, "config.yaml")) || await exists10(join15(sourcePath, ".claude-plugin", "plugin.json")) || await exists10(join15(sourcePath, ".codex-plugin", "plugin.json"));
+  return await exists9(join14(sourcePath, "skillset.yaml")) || await exists9(join14(sourcePath, "config.yaml")) || await exists9(join14(sourcePath, ".claude-plugin", "plugin.json")) || await exists9(join14(sourcePath, ".codex-plugin", "plugin.json"));
 }
 async function skillChildren(sourcePath) {
   return importChildren(sourcePath, "skill", async (path2) => isSkillSource(path2));
 }
 async function pluginChildren(sourcePath) {
-  const pluginRoot = await exists10(join15(sourcePath, "plugins")) ? join15(sourcePath, "plugins") : sourcePath;
+  const pluginRoot = await exists9(join14(sourcePath, "plugins")) ? join14(sourcePath, "plugins") : sourcePath;
   return importChildren(pluginRoot, "plugin", async (path2) => isPluginSource(path2));
 }
 async function importChildren(sourcePath, kind, predicate) {
-  if (!await exists10(sourcePath))
+  if (!await exists9(sourcePath))
     return [];
-  const stats = await stat12(sourcePath);
+  const stats = await stat11(sourcePath);
   if (!stats.isDirectory())
     return [];
-  const entries = await readdir6(sourcePath, { withFileTypes: true });
+  const entries = await readdir7(sourcePath, { withFileTypes: true });
   const seen = new Set;
   const items = [];
   for (const entry of entries.sort((left, right) => compareStrings(left.name, right.name))) {
     if (entry.name === ".DS_Store")
       continue;
-    const candidate = join15(sourcePath, entry.name);
-    if (!await exists10(candidate))
+    const candidate = join14(sourcePath, entry.name);
+    if (!await exists9(candidate))
       continue;
-    const candidateStats = await stat12(candidate);
+    const candidateStats = await stat11(candidate);
     if (!candidateStats.isDirectory())
       continue;
     if (!await predicate(candidate))
@@ -18041,16 +18720,16 @@ async function writeImportedPluginConfig(targetPath, name) {
     license: nativeManifest.license,
     keywords: nativeManifest.keywords
   };
-  await writeFile5(join15(targetPath, "skillset.yaml"), stringifyYaml({
+  await writeFile6(join14(targetPath, "skillset.yaml"), stringifyYaml({
     skillset: metadata
   }));
 }
 async function readNativePluginManifest(targetPath) {
   for (const file of [".claude-plugin/plugin.json", ".codex-plugin/plugin.json"]) {
-    const candidate = join15(targetPath, file);
-    if (!await exists10(candidate))
+    const candidate = join14(targetPath, file);
+    if (!await exists9(candidate))
       continue;
-    const parsed = JSON.parse(await readFile14(candidate, "utf8"));
+    const parsed = JSON.parse(await readFile15(candidate, "utf8"));
     if (!isJsonRecord(parsed)) {
       throw new Error(`skillset: expected native plugin manifest ${candidate} to contain a JSON object`);
     }
@@ -18058,9 +18737,9 @@ async function readNativePluginManifest(targetPath) {
   }
   return {};
 }
-async function exists10(path2) {
+async function exists9(path2) {
   try {
-    await stat12(path2);
+    await stat11(path2);
     return true;
   } catch (error) {
     if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
@@ -18070,9 +18749,8 @@ async function exists10(path2) {
   }
 }
 // apps/skillset/src/setup.ts
-import { mkdir as mkdir6, readdir as readdir7, readFile as readFile15, realpath as realpath2, stat as stat13, writeFile as writeFile6 } from "fs/promises";
-import { basename as basename6, dirname as dirname11, join as join16, relative as relative14, resolve as resolve6 } from "path";
-
+import { mkdir as mkdir6, readdir as readdir8, readFile as readFile16, realpath as realpath2, stat as stat12, writeFile as writeFile7 } from "fs/promises";
+import { basename as basename7, dirname as dirname11, join as join15, relative as relative14, resolve as resolve6 } from "path";
 // apps/skillset/src/ci.ts
 var EMPTY_DRIFT = { added: [], changed: [], missing: [], removed: [] };
 async function ciSkillset(rootPath, options = {}) {
@@ -18107,6 +18785,7 @@ async function ciSkillset(rootPath, options = {}) {
   }
   const changeErrors = changeIssues.filter((issue) => issue.severity === "error");
   const lintErrors = lintIssues.filter((issue) => issue.severity === "error");
+  const sourceSuggestions = buildError === undefined && hasDrift(drift) ? await sourceSuggestionsForDrift(rootPath, drift, buildOptions) : [];
   let fixedPaths = [];
   if (fix === true && hasDrift(drift) && buildError === undefined && changeError === undefined && changeErrors.length === 0 && lintErrors.length === 0) {
     const staleBefore = [...drift.added, ...drift.changed, ...drift.missing, ...drift.removed];
@@ -18127,6 +18806,7 @@ async function ciSkillset(rootPath, options = {}) {
     fixedPaths,
     lintIssues,
     ok: buildError === undefined && changeError === undefined && lintErrors.length === 0 && changeErrors.length === 0 && !hasDrift(drift),
+    ...sourceSuggestions.length === 0 ? {} : { sourceSuggestions },
     warnings
   };
 }
@@ -18145,7 +18825,7 @@ function renderCiReportMarkdown(report) {
 `;
   }
   if (report.ok) {
-    lines.push(report.fixedPaths.length > 0 ? "Generated output was stale and has been rebuilt mechanically. No source changes are needed." : "All checks passed; the lint warnings below are advisory and do not fail CI.", "");
+    lines.push(hasGeneratedChangelogPath(report.fixedPaths) ? "Generated output was stale and has been rebuilt mechanically. Review rebuilt generated changelogs below in case the edit should be recovered through source-side change history." : report.fixedPaths.length > 0 ? "Generated output was stale and has been rebuilt mechanically. No source changes are needed." : "All checks passed; the lint warnings below are advisory and do not fail CI.", "");
   } else {
     lines.push("Skillset CI found problems; the sections below explain each one.", "");
   }
@@ -18153,6 +18833,9 @@ function renderCiReportMarkdown(report) {
     lines.push("### Rebuilt generated output", "");
     for (const path2 of report.fixedPaths)
       lines.push(`- \`${path2}\``);
+    if (hasGeneratedChangelogPath(report.fixedPaths)) {
+      lines.push("", "Generated `CHANGELOG.md` files are managed projections. Edit pending wording with `skillset change reason <@ref>` before release; use `skillset change amend <@ref>` for applied-history wording after release or `skillset release amend <@ref>` for release-event metadata instead of hand-editing generated changelogs.");
+    }
     lines.push("", "These files were regenerated from source the same way `skillset build --yes` would. Commit the rebuilt output if it is not committed for you.", "");
   }
   if (hasDrift(report.drift)) {
@@ -18165,8 +18848,21 @@ function renderCiReportMarkdown(report) {
       lines.push(`- missing: \`${path2}\``);
     for (const path2 of report.drift.removed)
       lines.push(`- removed: \`${path2}\``);
+    if (hasGeneratedChangelogDrift(report.drift)) {
+      lines.push("", "Generated `CHANGELOG.md` files are managed projections. Edit pending wording with `skillset change reason <@ref>` before release; use `skillset change amend <@ref>` for applied-history wording after release or `skillset release amend <@ref>` for release-event metadata instead of hand-editing generated changelogs.");
+    }
     lines.push("", "Run `skillset build --yes`, review the generated diff, and commit it.", "");
   }
+  if (report.sourceSuggestions !== undefined && report.sourceSuggestions.length > 0) {
+    lines.push("### Source suggestions", "");
+    for (const suggestion of report.sourceSuggestions) {
+      const source2 = suggestion.sourcePath === undefined ? "" : ` source \`${suggestion.sourcePath}\``;
+      lines.push(`- ${suggestion.status}: \`${suggestion.generatedPath}\`${source2}: ${suggestion.message}`);
+      for (const step of suggestion.nextSteps)
+        lines.push(`  - ${step}`);
+    }
+    lines.push("");
+  }
   if (lintErrors.length > 0) {
     lines.push("### Lint issues", "");
     for (const issue of lintErrors) {
@@ -18202,6 +18898,32 @@ function codeBlock(content) {
   return ["```", content.trimEnd(), "```"].join(`
 `);
 }
+function hasGeneratedChangelogDrift(diff) {
+  return hasGeneratedChangelogPath([...diff.added, ...diff.changed, ...diff.missing, ...diff.removed]);
+}
+function hasGeneratedChangelogPath(paths) {
+  return paths.some((path2) => path2.endsWith("/CHANGELOG.md") || path2 === "CHANGELOG.md");
+}
+async function sourceSuggestionsForDrift(rootPath, drift, options) {
+  const paths = [...new Set([...drift.added, ...drift.changed])];
+  const reports = [];
+  for (const path2 of paths) {
+    try {
+      reports.push(await suggestSource(rootPath, path2, options));
+    } catch (error) {
+      reports.push({
+        entries: [],
+        generatedPath: path2,
+        message: errorMessage2(error),
+        nextSteps: ["Run `skillset explain <path>` and update the owning source manually."],
+        status: "refused",
+        wouldWrite: false,
+        wrote: false
+      });
+    }
+  }
+  return reports;
+}
 function errorMessage2(error) {
   return error instanceof Error ? error.message : String(error);
 }
@@ -18297,7 +19019,9 @@ function renderCiWorkflow() {
 // apps/skillset/src/setup.ts
 var DEFAULT_CREATE_NAME = "my-skillset";
 var DEFAULT_GLOBAL_SOURCE = ".skillset/src";
-var SETUP_SOURCE_DIR = ".skillset/src";
+var ORDINARY_WORKSPACE_DIR = ".skillset";
+var ORDINARY_SOURCE_ROOT = ".skillset/src";
+var DEDICATED_SOURCE_ROOT = "skillset";
 var SETUP_SOURCE_PLACEHOLDERS = [
   "agents",
   "hooks",
@@ -18318,11 +19042,11 @@ async function createSkillset(options = {}) {
   }
   const rootPath = createRootPath(options);
   if (await pathExists(rootPath)) {
-    const stats = await stat13(rootPath);
+    const stats = await stat12(rootPath);
     if (!stats.isDirectory()) {
       throw new Error(`skillset: create target exists and is not a directory: ${rootPath}`);
     }
-    const entries = await readdir7(rootPath);
+    const entries = await readdir8(rootPath);
     if (entries.length > 0) {
       throw new Error(`skillset: create target must be empty: ${rootPath}`);
     }
@@ -18334,25 +19058,22 @@ function defaultGlobalSourcePath(homeDir = process.env.HOME ?? "~") {
 }
 async function applySetupPlan(kind, rootPath, options) {
   const name = options.name === undefined ? defaultSetupName(kind, rootPath) : validateSlug(options.name, "skillset setup name");
-  const alreadyAdopted = await pathExists(join16(rootPath, ".skillset/config.yaml"));
+  const layout = await resolveSetupLayout(kind, rootPath, options);
+  const workspaceManifestPath = await setupWorkspaceManifestPath(kind, rootPath, layout);
+  const alreadyAdopted = await setupWorkspaceExists(rootPath, layout);
   const targets = normalizeTargets(options.targets);
-  const plannedFiles = setupFiles({ ...options, kind, name, targets });
+  const plannedFiles = setupFiles({ ...options, kind, layout, name, targets, workspaceManifestPath });
   const git = await setupGit(kind, rootPath, options);
   const files = [];
   for (const file of plannedFiles) {
-    const absolutePath = join16(rootPath, file.path);
+    const absolutePath = join15(rootPath, file.path);
     const existing = await readExistingFile(absolutePath);
     if (existing !== undefined && existing !== file.content) {
-      if (kind === "init" && file.path === ".skillset/config.yaml") {
+      if (kind === "init" && file.path === workspaceManifestPath) {
         await validateExistingRootConfig(absolutePath);
         files.push({ path: file.path, status: "exists" });
         continue;
       }
-      if (kind === "init" && file.path === `${SETUP_SOURCE_DIR}/skillset.yaml`) {
-        await validateExistingSourceManifest(absolutePath);
-        files.push({ path: file.path, status: "exists" });
-        continue;
-      }
       if (file.path === CI_WORKFLOW_PATH) {
         files.push({ path: file.path, status: "exists" });
         continue;
@@ -18363,12 +19084,12 @@ async function applySetupPlan(kind, rootPath, options) {
   }
   if (options.write === true) {
     for (const file of plannedFiles) {
-      const absolutePath = join16(rootPath, file.path);
+      const absolutePath = join15(rootPath, file.path);
       const existing = await readExistingFile(absolutePath);
       if (existing !== undefined)
         continue;
       await mkdir6(dirname11(absolutePath), { recursive: true });
-      await writeFile6(absolutePath, file.content);
+      await writeFile7(absolutePath, file.content);
     }
     if (git?.status === "create")
       await initializeGit(rootPath);
@@ -18383,11 +19104,42 @@ async function applySetupPlan(kind, rootPath, options) {
     importCandidates,
     kind,
     rootPath,
-    sourceDir: SETUP_SOURCE_DIR,
+    sourceDir: layout === "dedicated" ? "." : ORDINARY_WORKSPACE_DIR,
     surveySkips,
     write: options.write === true
   };
 }
+async function resolveSetupLayout(kind, rootPath, options) {
+  if (options.global === true)
+    return "dedicated";
+  if (kind === "create")
+    return "dedicated";
+  const dedicated = await hasDedicatedWorkspaceMarker(rootPath);
+  const ordinary = await hasOrdinaryWorkspaceMarker(rootPath);
+  if (dedicated && ordinary) {
+    throw new Error("skillset: ambiguous setup workspace; found both dedicated root skillset.yaml/skillset and ordinary .skillset workspace");
+  }
+  return dedicated ? "dedicated" : "ordinary";
+}
+async function hasDedicatedWorkspaceMarker(rootPath) {
+  return await pathExists(join15(rootPath, "skillset.yaml")) || await pathExists(join15(rootPath, DEDICATED_SOURCE_ROOT));
+}
+async function hasOrdinaryWorkspaceMarker(rootPath) {
+  return await pathExists(join15(rootPath, ".skillset/skillset.yaml")) || await pathExists(join15(rootPath, ".skillset/config.yaml")) || await pathExists(join15(rootPath, ORDINARY_SOURCE_ROOT));
+}
+async function setupWorkspaceExists(rootPath, layout) {
+  if (layout === "dedicated")
+    return await pathExists(join15(rootPath, "skillset.yaml"));
+  return await pathExists(join15(rootPath, ".skillset/skillset.yaml")) || await pathExists(join15(rootPath, ".skillset/config.yaml"));
+}
+async function setupWorkspaceManifestPath(kind, rootPath, layout) {
+  if (layout === "dedicated")
+    return "skillset.yaml";
+  if (kind === "init" && !await pathExists(join15(rootPath, ".skillset/skillset.yaml")) && await pathExists(join15(rootPath, ".skillset/config.yaml"))) {
+    return ".skillset/config.yaml";
+  }
+  return ".skillset/skillset.yaml";
+}
 async function initRootPath(options) {
   const cwd = resolve6(options.cwd ?? process.cwd());
   if (options.rootPath !== undefined)
@@ -18413,12 +19165,12 @@ async function gitRoot(cwd) {
   return path2.length === 0 ? undefined : path2;
 }
 async function validateExistingRootConfig(path2) {
-  const content = await readFile15(path2, "utf8");
-  validateWorkspaceConfigDocument(parseYamlRecord(content, path2), path2);
-}
-async function validateExistingSourceManifest(path2) {
-  const content = await readFile15(path2, "utf8");
-  validateRootSourceManifestDocument(parseYamlRecord(content, path2), path2);
+  const content = await readFile16(path2, "utf8");
+  const parsed = parseYamlRecord(content, path2);
+  if (path2.endsWith("/config.yaml"))
+    validateWorkspaceConfigDocument(parsed, path2);
+  else
+    validateConfigDocument(parsed, path2, { allowCompile: true });
 }
 var GENERATED_INSTRUCTIONS_MARKER = "<!-- Generated by skillset";
 var ROOT_INSTRUCTION_FILES = ["AGENTS.md", "CLAUDE.md"];
@@ -18430,7 +19182,7 @@ async function detectImportCandidates(rootPath, alreadyAdopted) {
   await maybeCandidate(candidates, rootPath, ".agents/skills", "skills");
   await maybeCandidate(candidates, rootPath, "plugins-claude/plugins", "plugins");
   await maybeCandidate(candidates, rootPath, "plugins-codex/plugins", "plugins");
-  if (await pathExists(join16(rootPath, ".claude-plugin/plugin.json")) || await pathExists(join16(rootPath, ".codex-plugin/plugin.json"))) {
+  if (await pathExists(join15(rootPath, ".claude-plugin/plugin.json")) || await pathExists(join15(rootPath, ".codex-plugin/plugin.json"))) {
     candidates.push({ kind: "plugin", path: "." });
   }
   for (const path2 of [...await marketplacePluginSources(rootPath), ...await nestedPluginSources(rootPath)]) {
@@ -18440,7 +19192,7 @@ async function detectImportCandidates(rootPath, alreadyAdopted) {
   }
   if (!alreadyAdopted) {
     for (const name of ROOT_INSTRUCTION_FILES) {
-      if (await isImportableInstructionFile(join16(rootPath, name))) {
+      if (await isImportableInstructionFile(join15(rootPath, name))) {
         candidates.push({ kind: "instructions", path: name });
       }
     }
@@ -18448,20 +19200,20 @@ async function detectImportCandidates(rootPath, alreadyAdopted) {
   return candidates.sort((left, right) => compareCandidate(left, right));
 }
 async function nestedPluginSources(rootPath) {
-  const pluginsPath = join16(rootPath, "plugins");
+  const pluginsPath = join15(rootPath, "plugins");
   if (!await pathExists(pluginsPath))
     return [];
-  if (!(await stat13(pluginsPath)).isDirectory())
+  if (!(await stat12(pluginsPath)).isDirectory())
     return [];
   const realRoot = await realpath2(rootPath);
   const sources = [];
-  for (const entry of (await readdir7(pluginsPath)).sort()) {
-    const absolutePath = join16(pluginsPath, entry);
+  for (const entry of (await readdir8(pluginsPath)).sort()) {
+    const absolutePath = join15(pluginsPath, entry);
     if (!await pathExists(absolutePath))
       continue;
-    if (!(await stat13(absolutePath)).isDirectory())
+    if (!(await stat12(absolutePath)).isDirectory())
       continue;
-    const hasManifest = await pathExists(join16(absolutePath, ".claude-plugin/plugin.json")) || await pathExists(join16(absolutePath, ".codex-plugin/plugin.json"));
+    const hasManifest = await pathExists(join15(absolutePath, ".claude-plugin/plugin.json")) || await pathExists(join15(absolutePath, ".codex-plugin/plugin.json"));
     if (!hasManifest)
       continue;
     const realSource = await realpath2(absolutePath);
@@ -18479,36 +19231,36 @@ async function nestedPluginSources(rootPath) {
 async function isImportableInstructionFile(path2) {
   if (!await pathExists(path2))
     return false;
-  if (!(await stat13(path2)).isFile())
+  if (!(await stat12(path2)).isFile())
     return false;
-  const content = await readFile15(path2, "utf8");
+  const content = await readFile16(path2, "utf8");
   return !content.startsWith(GENERATED_INSTRUCTIONS_MARKER);
 }
 async function detectSurveySkips(rootPath) {
   const skips = [];
-  await maybeSkip(skips, rootPath, ".claude/commands", "commands", "project-level commands have no portable source home yet; adopt will lower them to target-native islands in the transform milestone", surveySkipOutcome({
+  await maybeSkip(skips, rootPath, ".claude/commands", "commands", "project-level commands have no portable source home yet; adopt will represent them as provider source in the transform milestone", surveySkipOutcome({
     featureId: "target-native-islands",
     path: ".claude/commands",
-    reason: "project-level commands have no portable source home yet; adopt will lower them to target-native islands in the transform milestone",
+    reason: "project-level commands have no portable source home yet; adopt will represent them as provider source in the transform milestone",
     relativeTargetPath: "commands",
     target: "claude"
   }));
-  await maybeSkip(skips, rootPath, ".claude/agents", "agents", "project-level agents are not importable yet; adopt will lower them to .skillset/src/agents/ in the transform milestone", surveySkipOutcome({
+  await maybeSkip(skips, rootPath, ".claude/agents", "agents", "project-level agents are not importable yet; adopt will represent them in the active workspace source root in the transform milestone", surveySkipOutcome({
     featureId: "project-agents",
     path: ".claude/agents",
-    reason: "project-level agents are not importable yet; adopt will lower them to .skillset/src/agents/ in the transform milestone",
+    reason: "project-level agents are not importable yet; adopt will represent them in the active workspace source root in the transform milestone",
     relativeTargetPath: "agents",
     target: "claude"
   }));
-  await maybeSkip(skips, rootPath, ".claude/rules", "rules", "rules are not importable yet; adopt will lower them to .skillset/src/rules/ in the transform milestone", surveySkipOutcome({
+  await maybeSkip(skips, rootPath, ".claude/rules", "rules", "rules are not importable yet; adopt will represent them in the active workspace source root in the transform milestone", surveySkipOutcome({
     featureId: "project-instructions",
     path: ".claude/rules",
-    reason: "rules are not importable yet; adopt will lower them to .skillset/src/rules/ in the transform milestone",
+    reason: "rules are not importable yet; adopt will represent them in the active workspace source root in the transform milestone",
     relativeTargetPath: "rules",
     target: "claude"
   }));
   if (await hasNonSkillCodexContent(rootPath)) {
-    const reason = "Codex content outside .codex/skills has no portable lowering yet; adopt will lower it to target-native islands in the transform milestone";
+    const reason = "Codex content outside .codex/skills has no portable source representation yet; adopt will represent it as provider source in the transform milestone";
     skips.push({
       renderResult: surveySkipOutcome({
         featureId: "target-native-islands",
@@ -18534,14 +19286,14 @@ async function detectSurveySkips(rootPath) {
   return skips.sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
 }
 async function maybeSkip(skips, rootPath, path2, surface, reason, renderResult) {
-  const absolutePath = join16(rootPath, path2);
+  const absolutePath = join15(rootPath, path2);
   if (!await pathExists(absolutePath))
     return;
-  if (!(await stat13(absolutePath)).isDirectory())
+  if (!(await stat12(absolutePath)).isDirectory())
     return;
   if (await isManagedCandidate(absolutePath))
     return;
-  const entries = await readdir7(absolutePath);
+  const entries = await readdir8(absolutePath);
   if (entries.filter((entry) => entry !== ".DS_Store").length === 0)
     return;
   skips.push({ ...renderResult === undefined ? {} : { renderResult }, path: path2, reason, surface });
@@ -18580,39 +19332,39 @@ function foreignManifestRuntime(path2) {
   return path2.match(/^\.([a-z][a-z0-9]*)-plugin$/)?.[1] ?? path2;
 }
 async function hasNonSkillCodexContent(rootPath) {
-  const codexPath = join16(rootPath, ".codex");
+  const codexPath = join15(rootPath, ".codex");
   if (!await pathExists(codexPath))
     return false;
-  if (!(await stat13(codexPath)).isDirectory())
+  if (!(await stat12(codexPath)).isDirectory())
     return false;
   if (await isManagedCandidate(codexPath))
     return false;
-  const entries = await readdir7(codexPath);
+  const entries = await readdir8(codexPath);
   return entries.some((entry) => entry !== "skills" && entry !== ".DS_Store");
 }
 async function foreignPluginManifests(rootPath) {
   const paths = [];
-  for (const entry of (await readdir7(rootPath)).sort()) {
+  for (const entry of (await readdir8(rootPath)).sort()) {
     if (NATIVE_PLUGIN_MANIFEST_DIRS.has(entry))
       continue;
     if (!/^\.[a-z][a-z0-9]*-plugin$/.test(entry))
       continue;
-    const absolutePath = join16(rootPath, entry);
+    const absolutePath = join15(rootPath, entry);
     if (!await pathExists(absolutePath))
       continue;
-    if (!(await stat13(absolutePath)).isDirectory())
+    if (!(await stat12(absolutePath)).isDirectory())
       continue;
     paths.push(entry);
   }
   return paths;
 }
 async function marketplacePluginSources(rootPath) {
-  const manifestPath = join16(rootPath, ".claude-plugin/marketplace.json");
+  const manifestPath = join15(rootPath, ".claude-plugin/marketplace.json");
   if (!await pathExists(manifestPath))
     return [];
   let parsed;
   try {
-    parsed = JSON.parse(await readFile15(manifestPath, "utf8"));
+    parsed = JSON.parse(await readFile16(manifestPath, "utf8"));
   } catch {
     return [];
   }
@@ -18634,7 +19386,7 @@ async function marketplacePluginSources(rootPath) {
       continue;
     if (!await pathExists(absolutePath))
       continue;
-    if (!(await stat13(absolutePath)).isDirectory())
+    if (!(await stat12(absolutePath)).isDirectory())
       continue;
     const realSource = await realpath2(absolutePath);
     if (realSource !== realRoot && !realSource.startsWith(`${realRoot}/`))
@@ -18649,44 +19401,66 @@ async function marketplacePluginSources(rootPath) {
   return sources;
 }
 async function maybeCandidate(candidates, rootPath, path2, kind) {
-  const absolutePath = join16(rootPath, path2);
+  const absolutePath = join15(rootPath, path2);
   if (!await pathExists(absolutePath))
     return;
-  const stats = await stat13(absolutePath);
+  const stats = await stat12(absolutePath);
   if (!stats.isDirectory())
     return;
   if (await isManagedCandidate(absolutePath))
     return;
-  const entries = await readdir7(absolutePath);
+  const entries = await readdir8(absolutePath);
   if (entries.filter((entry) => entry !== ".DS_Store").length === 0)
     return;
   candidates.push({ kind, path: relative14(rootPath, absolutePath).replaceAll("\\", "/") });
 }
 async function isManagedCandidate(path2) {
-  return await pathExists(join16(path2, ".skillset.lock")) || await pathExists(join16(dirname11(path2), ".skillset.lock"));
+  return await pathExists(join15(path2, ".skillset.lock")) || await pathExists(join15(dirname11(path2), ".skillset.lock"));
 }
 function compareCandidate(left, right) {
   return `${left.kind}:${left.path}` < `${right.kind}:${right.path}` ? -1 : `${left.kind}:${left.path}` > `${right.kind}:${right.path}` ? 1 : 0;
 }
 function setupFiles(options) {
+  const sourceRoot = options.layout === "dedicated" ? DEDICATED_SOURCE_ROOT : ORDINARY_SOURCE_ROOT;
+  const changesRoot = options.layout === "dedicated" ? "changes" : ".skillset/changes";
   const files = [
     {
-      path: ".skillset/config.yaml",
-      content: rootConfig(options.targets)
-    },
-    {
-      path: `${SETUP_SOURCE_DIR}/skillset.yaml`,
-      content: rootSourceManifest(options.name)
+      path: options.workspaceManifestPath,
+      content: workspaceManifest(options.name, options.targets)
     },
     {
-      path: `${SETUP_SOURCE_DIR}/.gitkeep`,
+      path: `${sourceRoot}/.gitkeep`,
       content: ""
     },
     ...SETUP_SOURCE_PLACEHOLDERS.map((directory) => ({
-      path: `${SETUP_SOURCE_DIR}/${directory}/.gitkeep`,
+      path: `${sourceRoot}/${directory}/.gitkeep`,
       content: ""
-    }))
+    })),
+    {
+      path: `${changesRoot}/.gitkeep`,
+      content: ""
+    }
   ];
+  if (options.layout === "ordinary") {
+    files.push({
+      path: ".skillset/.gitignore",
+      content: `build/
+`
+    }, {
+      path: ".skillset/build/.gitkeep",
+      content: ""
+    });
+  }
+  if (options.layout === "dedicated" && options.kind === "create" && options.global !== true) {
+    files.push({
+      path: ".gitignore",
+      content: `.skillset/
+`
+    }, {
+      path: "skillset.lock",
+      content: emptyWorkspaceLock()
+    });
+  }
   if (options.kind === "create" && options.global !== true) {
     files.unshift({
       path: "README.md",
@@ -18707,7 +19481,7 @@ async function setupGit(kind, rootPath, options) {
     return;
   return {
     path: ".git",
-    status: await pathExists(join16(rootPath, ".git")) ? "exists" : "create"
+    status: await pathExists(join15(rootPath, ".git")) ? "exists" : "create"
   };
 }
 async function initializeGit(rootPath) {
@@ -18740,10 +19514,20 @@ function rootConfig(targets) {
   ].join(`
 `);
 }
-function rootSourceManifest(name) {
+function workspaceManifest(name, targets) {
   return [
     "skillset:",
     `  name: ${name}`,
+    rootConfig(targets).trimEnd(),
+    ""
+  ].join(`
+`);
+}
+function emptyWorkspaceLock() {
+  return [
+    "{",
+    '  "items": []',
+    "}",
     ""
   ].join(`
 `);
@@ -18752,7 +19536,7 @@ function createReadme(name, targets) {
   return [
     `# ${name}`,
     "",
-    "This repository is a Skillset source repo. Edit files under `.skillset/src/`, then run Skillset commands to preview or write generated Claude and Codex outputs.",
+    "This repository is a dedicated Skillset source repo. Edit files under `skillset/`, then run Skillset commands to preview or write generated Claude and Codex outputs.",
     "",
     "## Quick Start",
     "",
@@ -18765,11 +19549,12 @@ function createReadme(name, targets) {
     "",
     "## Layout",
     "",
-    "- `.skillset/config.yaml` selects compile targets and destination settings.",
-    "- `.skillset/src/skillset.yaml` names the source loadout and carries root source metadata.",
-    "- `.skillset/src/` is the adaptive project source area for rules, agents, hooks, skills, plugins, shared files, and provider source.",
-    "- `.skillset/src/plugins/` holds plugin source when this repo authors marketplace plugins.",
-    "- `.skillset/src/skills/` holds standalone skill source when this repo authors repo-local or user skill roots.",
+    "- `skillset.yaml` names the source loadout and selects compile targets and destination settings.",
+    "- `skillset/` is the adaptive project source area for rules, agents, hooks, skills, plugins, shared files, and provider source.",
+    "- `skillset/plugins/` holds plugin source when this repo authors marketplace plugins.",
+    "- `skillset/skills/` holds standalone skill source when this repo authors repo-local or user skill roots.",
+    "- `changes/` stores pending and applied Skillset change history.",
+    "- `.skillset/` is ignored operational output for previews, test runs, and build scratch data.",
     "",
     `Default compile targets: ${targets.join(", ")}.`,
     ""
@@ -18784,8 +19569,9 @@ function createAgentsGuide(name) {
     "",
     "## Working Rules",
     "",
-    "- Treat `.skillset/src/` as editable source.",
-    "- Treat `.skillset/config.yaml` as workspace/build configuration.",
+    "- Treat `skillset/` as editable source.",
+    "- Treat `skillset.yaml` as workspace/build configuration and root source metadata.",
+    "- Treat `changes/` as Skillset-managed change and release state.",
     "- Treat generated target directories as outputs; do not hand-edit them as source truth.",
     "- Run `skillset build --dry-run` before writing generated outputs.",
     "- Run `skillset check` before committing source changes.",
@@ -18802,10 +19588,10 @@ function createRootPath(options) {
   return resolve6(options.cwd ?? process.cwd(), DEFAULT_CREATE_NAME);
 }
 function defaultSetupName(kind, rootPath) {
-  if (kind === "create" && basename6(rootPath) === "src" && basename6(join16(rootPath, "..")) === ".skillset") {
+  if (kind === "create" && basename7(rootPath) === "src" && basename7(join15(rootPath, "..")) === ".skillset") {
     return DEFAULT_CREATE_NAME;
   }
-  const slug = slugifySetupName(basename6(rootPath));
+  const slug = slugifySetupName(basename7(rootPath));
   return slug.length === 0 ? DEFAULT_CREATE_NAME : slug;
 }
 function slugifySetupName(value) {
@@ -18825,28 +19611,28 @@ function normalizeTargets(targets) {
 }
 async function readExistingFile(path2) {
   try {
-    const stats = await stat13(path2);
+    const stats = await stat12(path2);
     if (!stats.isFile()) {
       throw new Error(`skillset: refusing to overwrite non-file setup path ${path2}`);
     }
-    return await readFile15(path2, "utf8");
+    return await readFile16(path2, "utf8");
   } catch (error) {
-    if (isErrno2(error, "ENOENT"))
+    if (isErrno3(error, "ENOENT"))
       return;
     throw error;
   }
 }
 async function pathExists(path2) {
   try {
-    await stat13(path2);
+    await stat12(path2);
     return true;
   } catch (error) {
-    if (isErrno2(error, "ENOENT"))
+    if (isErrno3(error, "ENOENT"))
       return false;
     throw error;
   }
 }
-function isErrno2(error, code) {
+function isErrno3(error, code) {
   return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
 
@@ -18866,7 +19652,7 @@ async function adoptResolvedRoot(acquisition, options = {}) {
   const { targets, write, ...buildOptions } = options;
   const writeMode = write === true;
   const resolvedRoot = acquisition.rootPath;
-  const alreadyAdopted = await exists11(join17(resolvedRoot, ".skillset/config.yaml"));
+  const alreadyAdopted = await adoptedWorkspaceExists(resolvedRoot);
   const init = await initSkillset({
     cwd: resolvedRoot,
     useGitRoot: false,
@@ -18943,22 +19729,28 @@ async function adoptResolvedRoot(acquisition, options = {}) {
     transformPreviews,
     write: true
   };
-  const reportDir = join17(init.rootPath, ADOPT_REPORT_DIR);
+  const reportDir = join16(init.rootPath, ADOPT_REPORT_DIR);
   await mkdir7(reportDir, { recursive: true });
-  await writeFile7(join17(reportDir, "report.md"), renderAdoptReportMarkdown(report, { rootPath: init.rootPath }));
-  await writeFile7(join17(reportDir, "report.json"), `${JSON.stringify(report, null, 2)}
+  await writeFile8(join16(reportDir, "report.md"), renderAdoptReportMarkdown(report, { rootPath: init.rootPath }));
+  await writeFile8(join16(reportDir, "report.json"), `${JSON.stringify(report, null, 2)}
 `);
   return report;
 }
+async function adoptedWorkspaceExists(rootPath) {
+  const currentOrdinary = await exists10(join16(rootPath, ".skillset/skillset.yaml"));
+  const legacyOrdinary = await exists10(join16(rootPath, ".skillset/config.yaml"));
+  const dedicated = await exists10(join16(rootPath, "skillset.yaml")) && await exists10(join16(rootPath, "skillset"));
+  return currentOrdinary || legacyOrdinary || dedicated;
+}
 function surveySkipRenderResults(skips) {
   return skips.flatMap((skip) => skip.renderResult === undefined ? [] : [skip.renderResult]);
 }
 async function acquireAdoptSource(source2, cwd) {
   const localPath = resolve7(cwd, source2);
-  if (await exists11(localPath)) {
+  if (await exists10(localPath)) {
     return { input: source2, kind: "path", rootPath: localPath };
   }
-  const clonePath = await mkdtemp3(join17(tmpdir2(), "skillset-adopt-remote-"));
+  const clonePath = await mkdtemp3(join16(tmpdir2(), "skillset-adopt-remote-"));
   try {
     await runGit(["clone", "--depth", "1", source2, clonePath], cwd);
     const ref = (await runGit(["-C", clonePath, "rev-parse", "HEAD"], cwd)).trim();
@@ -18992,7 +19784,7 @@ async function importCandidate(rootPath, acquisition, candidate, cutover, previe
   if (candidate.kind === "instructions") {
     try {
       const destination = await importInstructionFile(rootPath, candidate.path);
-      await writeMarkdownSourceOrigin2(join17(rootPath, destination), sourceOriginFor(acquisition, candidate.path));
+      await writeMarkdownSourceOrigin2(join16(rootPath, destination), sourceOriginFor(acquisition, candidate.path));
       cutover.push(candidate.path);
       previewSources.push(destination);
       return { candidate, destination, detail: destination, renderResults: [], ok: true, units: [] };
@@ -19005,7 +19797,7 @@ async function importCandidate(rootPath, acquisition, candidate, cutover, previe
       kind: candidate.kind,
       rootPath,
       sourceOrigin: (sourcePath, copiedFile) => sourceOriginFor(acquisition, relativeOriginPath(rootPath, sourcePath, copiedFile)),
-      sourcePath: join17(rootPath, candidate.path)
+      sourcePath: join16(rootPath, candidate.path)
     });
     const units = batch.imports.map((report) => {
       const sourcePath = relative15(rootPath, report.sourcePath).replaceAll("\\", "/");
@@ -19017,9 +19809,9 @@ async function importCandidate(rootPath, acquisition, candidate, cutover, previe
     });
     for (const report of batch.imports) {
       for (const file of report.copiedFiles) {
-        if (basename7(file) !== "SKILL.md")
+        if (basename8(file) !== "SKILL.md")
           continue;
-        previewSources.push(relative15(rootPath, join17(report.targetPath, file)).replaceAll("\\", "/"));
+        previewSources.push(relative15(rootPath, join16(report.targetPath, file)).replaceAll("\\", "/"));
       }
     }
     return {
@@ -19035,26 +19827,26 @@ async function importCandidate(rootPath, acquisition, candidate, cutover, previe
 }
 async function importInstructionFile(rootPath, sourceName) {
   const destinationRelative = `${INSTRUCTIONS_DIR}/${sourceName.toLowerCase()}`;
-  const destination = join17(rootPath, destinationRelative);
-  if (await exists11(destination)) {
+  const destination = join16(rootPath, destinationRelative);
+  if (await exists10(destination)) {
     throw new Error(`skillset: instructions import target already exists: ${destinationRelative}. ` + "Adopt never overwrites; remove the existing file or merge by hand.");
   }
-  const content = await readFile16(join17(rootPath, sourceName));
+  const content = await readFile17(join16(rootPath, sourceName));
   await mkdir7(dirname12(destination), { recursive: true });
-  await writeFile7(destination, content);
+  await writeFile8(destination, content);
   return destinationRelative;
 }
 function sourceOriginFor(acquisition, path2) {
   return acquisition.kind === "git" ? { path: path2, ref: acquisition.ref, repo: acquisition.repo } : { path: path2 };
 }
 function relativeOriginPath(rootPath, sourcePath, copiedFile) {
-  const sourceFile = copiedFile === undefined ? sourcePath : basename7(sourcePath) === copiedFile ? sourcePath : join17(sourcePath, copiedFile);
+  const sourceFile = copiedFile === undefined ? sourcePath : basename8(sourcePath) === copiedFile ? sourcePath : join16(sourcePath, copiedFile);
   const path2 = relative15(rootPath, sourceFile).replaceAll("\\", "/");
   return path2.length === 0 ? "." : path2;
 }
 async function writeMarkdownSourceOrigin2(path2, origin) {
-  const parts = parseMarkdown(await readFile16(path2, "utf8"), path2);
-  await writeFile7(path2, stringifyMarkdown(withSkillsetOrigin2(parts.frontmatter, origin), parts.body));
+  const parts = parseMarkdown(await readFile17(path2, "utf8"), path2);
+  await writeFile8(path2, stringifyMarkdown(withSkillsetOrigin2(parts.frontmatter, origin), parts.body));
 }
 function withSkillsetOrigin2(record, origin) {
   const existing = isJsonRecord(record.skillset) ? record.skillset : {};
@@ -19076,13 +19868,13 @@ function sourceOriginRecord3(origin) {
 async function buildTransformPreviews(rootPath, paths) {
   const previews = [];
   for (const path2 of paths) {
-    const raw = await readFile16(join17(rootPath, path2), "utf8");
-    const body = basename7(path2) === "SKILL.md" ? markdownBody(raw, path2) : raw;
+    const raw = await readFile17(join16(rootPath, path2), "utf8");
+    const body = basename8(path2) === "SKILL.md" ? markdownBody(raw, path2) : raw;
     const matches = recognizeTransforms(body, "claude");
     if (matches.length === 0)
       continue;
     const transformable = matches.some((match) => match.lowering !== "none");
-    const dialectDeclared = transformable ? await declareClaudeDialect(join17(rootPath, path2)) : false;
+    const dialectDeclared = transformable ? await declareClaudeDialect(join16(rootPath, path2)) : false;
     previews.push({
       dialectDeclared,
       matches: matches.map((match) => {
@@ -19101,7 +19893,7 @@ async function buildTransformPreviews(rootPath, paths) {
   return previews;
 }
 async function declareClaudeDialect(path2) {
-  const raw = await readFile16(path2, "utf8");
+  const raw = await readFile17(path2, "utf8");
   try {
     if (parseMarkdown(raw, path2).frontmatter.dialect !== undefined)
       return true;
@@ -19114,7 +19906,7 @@ dialect: claude
 ---
 
 ${raw}`;
-  await writeFile7(path2, updated);
+  await writeFile8(path2, updated);
   return true;
 }
 function markdownBody(raw, label) {
@@ -19134,7 +19926,7 @@ function renderAdoptReportMarkdown(report, opts) {
   lines.push(`- root: \`${opts.rootPath}\``);
   lines.push(`- result: ${report.ok ? "pass" : "fail"}`);
   if (report.alreadyAdopted) {
-    lines.push("- note: the repo already had `.skillset/config.yaml`; adoption proceeded against the existing source tree");
+    lines.push("- note: the repo already had a Skillset workspace marker; adoption proceeded against the existing source tree");
   }
   lines.push(`- imports: ${succeeded.length} succeeded, ${failed.length} failed`, `- lint: ${lintErrors.length} error(s), ${lintWarnings.length} warning(s)`, report.buildError === undefined ? `- build (isolated): ${report.builtFiles} generated files` : "- build (isolated): failed", `- render results: ${report.renderResults.length}`, "");
   lines.push("## Acquisition", "");
@@ -19262,7 +20054,7 @@ function summarizeRenderResults(outcomes) {
 function aggregatePreviewMatches(matches) {
   const aggregated = new Map;
   for (const match of matches) {
-    const key = `${match.intent}\x00${match.text}\x00${match.codexForm ?? ""}`;
+    const key = JSON.stringify([match.intent, match.text, match.codexForm ?? ""]);
     const existing = aggregated.get(key);
     aggregated.set(key, existing === undefined ? { ...match, count: 1 } : { ...existing, count: existing.count + 1 });
   }
@@ -19277,9 +20069,9 @@ function inlineCode(text) {
 function errorMessage3(error) {
   return error instanceof Error ? error.message : String(error);
 }
-async function exists11(path2) {
+async function exists10(path2) {
   try {
-    await stat14(path2);
+    await stat13(path2);
     return true;
   } catch (error) {
     if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
@@ -19291,10 +20083,11 @@ async function exists11(path2) {
 
 // apps/skillset/src/change-workflow.ts
 import { createHash as createHash6, randomBytes } from "crypto";
-import { mkdir as mkdir8, readFile as readFile17, stat as stat15, writeFile as writeFile8 } from "fs/promises";
-import { isAbsolute as isAbsolute2, join as join18, resolve as resolve8 } from "path";
-var PENDING_DIR2 = "changes/pending";
+import { appendFile, mkdir as mkdir8, readFile as readFile18, stat as stat14, writeFile as writeFile9 } from "fs/promises";
+import { dirname as dirname13, isAbsolute as isAbsolute2, join as join17, resolve as resolve8 } from "path";
+var PENDING_DIR2 = "changes";
 var HISTORY_FILE2 = "changes/history.jsonl";
+var AMENDMENTS_FILE2 = "changes/amendments.jsonl";
 var MIN_REF_LENGTH = 6;
 async function addChangeEntry(rootPath, options) {
   if (options.scopes.length === 0)
@@ -19302,11 +20095,11 @@ async function addChangeEntry(rootPath, options) {
   if (options.bump === undefined)
     throw new Error("skillset: change add requires --bump major, minor, patch, or none");
   const scopes = [...new Set(options.scopes.map(sourceUnitSelector))].sort(compareStrings);
-  const reason = await resolveReason(rootPath, options.reason);
-  const statusOptions = sourceStatusOptions(options);
+  const reason = await resolveChangeReason(rootPath, options.reason);
+  const statusOptions = await detectWorkspaceOptions(rootPath, sourceStatusOptions(options));
   const status = await changeStatus(rootPath, statusOptions);
   const existing = await readAllChangeEntries(rootPath, statusOptions);
-  const id = await generateChangeId(rootPath, { ...options, scopes }, existing.map((entry2) => entry2.id));
+  const id = await generateChangeId(rootPath, { ...options, scopes, ...statusOptions.sourceDir === undefined ? {} : { sourceDir: statusOptions.sourceDir } }, existing.map((entry2) => entry2.id));
   const sourceHashes = new Map;
   for (const scope of scopes) {
     const hash = sourceHashForScope(scope, status.sourceUnits, status.sourceChanges);
@@ -19314,8 +20107,8 @@ async function addChangeEntry(rootPath, options) {
       throw new Error(`skillset: unknown change scope ${scope}`);
     sourceHashes.set(scope, [hash]);
   }
-  const sourceDir = options.sourceDir ?? ".skillset";
-  const relativePath2 = join18(sourceDir, PENDING_DIR2, `${id}.md`).replaceAll("\\", "/");
+  const sourceDir = statusOptions.sourceDir ?? ".skillset";
+  const relativePath2 = join17(sourceDir, PENDING_DIR2, `${id}.md`).replaceAll("\\", "/");
   const absolutePath = resolveInside(rootPath, relativePath2);
   const group = options.group === undefined ? undefined : parseGroupArgument(options.group);
   const entryFrontmatter = pendingFrontmatter({
@@ -19325,8 +20118,8 @@ async function addChangeEntry(rootPath, options) {
     scopes,
     sourceHashes
   });
-  await mkdir8(resolveInside(rootPath, join18(sourceDir, PENDING_DIR2)), { recursive: true });
-  await writeFile8(absolutePath, stringifyMarkdown(entryFrontmatter, reason), "utf8");
+  await mkdir8(resolveInside(rootPath, join17(sourceDir, PENDING_DIR2)), { recursive: true });
+  await writeFile9(absolutePath, stringifyMarkdown(entryFrontmatter, reason), "utf8");
   const [entry] = await readPendingChangeEntries(rootPath, statusOptions).then((entries) => entries.filter((item) => item.id === id));
   if (entry === undefined)
     throw new Error(`skillset: failed to read created change entry ${id}`);
@@ -19334,33 +20127,67 @@ async function addChangeEntry(rootPath, options) {
   return { entry: pendingView(entry, refs) };
 }
 async function updateChangeReason(rootPath, options) {
-  const pendingEntries = await readPendingChangeEntries(rootPath, options);
+  const storageOptions = await detectWorkspaceOptions(rootPath, options);
+  const pendingEntries = await readPendingChangeEntries(rootPath, storageOptions);
   const entry = resolvePendingChangeRef(pendingEntries, options.ref);
-  const newReason = await resolveReason(rootPath, options.reason);
+  const newReason = await resolveChangeReason(rootPath, options.reason);
   const absolutePath = resolveInside(rootPath, entry.path);
-  const parts = parseMarkdown(await readFile17(absolutePath, "utf8"), absolutePath);
+  const parts = parseMarkdown(await readFile18(absolutePath, "utf8"), absolutePath);
   const body = options.append ? `${parts.body.trimEnd()}
 
 ${newReason}` : newReason;
-  await writeFile8(absolutePath, stringifyMarkdown(parts.frontmatter, body), "utf8");
-  const updated = resolvePendingChangeRef(await readPendingChangeEntries(rootPath, options), entry.id ?? options.ref);
-  const refs = refIndex([updated], await readHistoryEntries(rootPath, options));
+  await writeFile9(absolutePath, stringifyMarkdown(parts.frontmatter, body), "utf8");
+  const updated = resolvePendingChangeRef(await readPendingChangeEntries(rootPath, storageOptions), entry.id ?? options.ref);
+  const refs = refIndex([updated], await readHistoryEntries(rootPath, storageOptions));
   return { entry: pendingView(updated, refs) };
 }
+async function amendAppliedChange(rootPath, options) {
+  const storageOptions = await detectWorkspaceOptions(rootPath, options);
+  const pendingEntries = await readPendingChangeEntries(rootPath, storageOptions);
+  const historyEntries = await readHistoryEntries(rootPath, storageOptions);
+  const refs = refIndex(pendingEntries, historyEntries);
+  assertCombinedRefUnambiguous(options.ref, pendingEntries, historyEntries, refs);
+  const pending = tryResolvePending(pendingEntries, options.ref);
+  if (pending !== undefined) {
+    const pendingRef = pending.id === undefined ? options.ref : refs.get(pending.id) ?? `@${pending.id}`;
+    throw new Error(`skillset: ${pendingRef} is pending; use skillset change reason before release`);
+  }
+  const entry = resolveHistoryRef(historyEntries, options.ref);
+  const reason = await resolveChangeReason(rootPath, options.reason);
+  const now = new Date().toISOString();
+  const sourceDir = storageOptions.sourceDir ?? ".skillset";
+  const relativePath2 = join17(sourceDir, AMENDMENTS_FILE2).replaceAll("\\", "/");
+  const absolutePath = resolveInside(rootPath, relativePath2);
+  await mkdir8(dirname13(absolutePath), { recursive: true });
+  await appendFile(absolutePath, `${JSON.stringify({
+    amendedAt: now,
+    id: entry.id,
+    previousReason: entry.reason,
+    reason,
+    source: entry.path
+  })}
+`, "utf8");
+  const updatedHistory = await readHistoryEntries(rootPath, storageOptions);
+  const updatedRefs = refIndex(pendingEntries, updatedHistory);
+  return { entry: historyView(resolveHistoryRef(updatedHistory, entry.id), updatedRefs), path: relativePath2 };
+}
 async function listChangeEntries(rootPath, options = {}) {
-  const pendingEntries = await readPendingChangeEntries(rootPath, options);
-  const historyEntries = await readHistoryEntries(rootPath, options);
+  const storageOptions = await detectWorkspaceOptions(rootPath, options);
+  const pendingEntries = await readPendingChangeEntries(rootPath, storageOptions);
+  const historyEntries = await readHistoryEntries(rootPath, storageOptions);
   const refs = refIndex(pendingEntries, historyEntries);
   const entries = pendingEntries.filter((entry) => options.group === undefined || groupMatches(entry.group, options.group)).map((entry) => pendingView(entry, refs));
   return { entries };
 }
 async function showChangeEntry(rootPath, options) {
-  const resolved = await resolveAnyChangeRef(rootPath, options.ref, options);
+  const storageOptions = await detectWorkspaceOptions(rootPath, options);
+  const resolved = await resolveAnyChangeRef(rootPath, options.ref, storageOptions);
   return { entry: resolved };
 }
 async function readChangeHistory(rootPath, options = {}) {
-  const pendingEntries = await readPendingChangeEntries(rootPath, options);
-  const historyEntries = await readHistoryEntries(rootPath, options);
+  const storageOptions = await detectWorkspaceOptions(rootPath, options);
+  const pendingEntries = await readPendingChangeEntries(rootPath, storageOptions);
+  const historyEntries = await readHistoryEntries(rootPath, storageOptions);
   const refs = refIndex(pendingEntries, historyEntries);
   if (options.ref === undefined)
     return { entries: historyEntries.map((entry) => historyView(entry, refs)) };
@@ -19420,19 +20247,19 @@ async function generateChangeId(rootPath, options, existingIds) {
     const id = hash.digest("hex").slice(0, 12);
     if (existing.has(id))
       continue;
-    if (await exists12(resolveInside(rootPath, join18(sourceDir, PENDING_DIR2, `${id}.md`))))
+    if (await exists11(resolveInside(rootPath, join17(sourceDir, PENDING_DIR2, `${id}.md`))))
       continue;
     return id;
   }
   throw new Error("skillset: failed to generate a unique change id");
 }
-async function resolveReason(rootPath, input) {
+async function resolveChangeReason(rootPath, input) {
   let reason;
   if (input.kind === "inline")
     reason = input.value;
   if (input.kind === "file") {
     const reasonPath = isAbsolute2(input.path) ? input.path : resolve8(rootPath, input.path);
-    reason = await readFile17(reasonPath, "utf8");
+    reason = await readFile18(reasonPath, "utf8");
   }
   if (input.kind === "stdin" || input.kind === "auto") {
     if (input.kind === "auto" && process.stdin.isTTY === true) {
@@ -19502,12 +20329,12 @@ function historyView(entry, refs) {
 }
 async function readHistoryEntries(rootPath, options = {}) {
   const sourceDir = options.sourceDir ?? ".skillset";
-  const path2 = join18(sourceDir, HISTORY_FILE2).replaceAll("\\", "/");
+  const path2 = join17(sourceDir, HISTORY_FILE2).replaceAll("\\", "/");
   const absolutePath = resolveInside(rootPath, path2);
-  if (!await exists12(absolutePath))
+  if (!await exists11(absolutePath))
     return [];
   const entries = [];
-  const lines = (await readFile17(absolutePath, "utf8")).split(`
+  const lines = (await readFile18(absolutePath, "utf8")).split(`
 `);
   for (const [index, line] of lines.entries()) {
     if (line.trim().length === 0)
@@ -19537,7 +20364,44 @@ async function readHistoryEntries(rootPath, options = {}) {
       sourceHashes: readHistoryEvidence2(parsed.evidence, scopes)
     });
   }
-  return entries.sort((left, right) => compareStrings(left.id, right.id));
+  const amended = await applyHistoryAmendments2(rootPath, sourceDir, entries);
+  return [...amended].sort((left, right) => compareStrings(left.id, right.id));
+}
+async function applyHistoryAmendments2(rootPath, sourceDir, entries) {
+  const amendments = await readHistoryAmendments2(rootPath, sourceDir);
+  if (amendments.size === 0)
+    return entries;
+  return entries.map((entry) => {
+    const amendment = amendments.get(entry.id);
+    return amendment === undefined ? entry : { ...entry, reason: amendment.reason };
+  });
+}
+async function readHistoryAmendments2(rootPath, sourceDir) {
+  const path2 = join17(sourceDir, AMENDMENTS_FILE2).replaceAll("\\", "/");
+  const absolutePath = resolveInside(rootPath, path2);
+  if (!await exists11(absolutePath))
+    return new Map;
+  const amendments = new Map;
+  const lines = (await readFile18(absolutePath, "utf8")).split(`
+`);
+  for (const [index, line] of lines.entries()) {
+    if (line.trim().length === 0)
+      continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      throw new Error(`skillset: invalid JSON in ${path2}:${index + 1}`);
+    }
+    if (!isJsonRecord(parsed))
+      throw new Error(`skillset: expected ${path2}:${index + 1} to contain a JSON object`);
+    const id = readString(parsed, "id");
+    const reason = readString(parsed, "reason");
+    if (id === undefined || reason === undefined)
+      continue;
+    amendments.set(id, { reason });
+  }
+  return amendments;
 }
 async function readAllChangeEntries(rootPath, options) {
   const pending = await readPendingChangeEntries(rootPath, options);
@@ -19704,9 +20568,9 @@ function historicalSourceUnitSelector2(raw) {
   }
   return sourceUnitSelector(raw);
 }
-async function exists12(path2) {
+async function exists11(path2) {
   try {
-    await stat15(path2);
+    await stat14(path2);
     return true;
   } catch (error) {
     if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
@@ -19715,6 +20579,7 @@ async function exists12(path2) {
     throw error;
   }
 }
+
 // apps/skillset/src/cli-renderers.ts
 function printDiagnostics(diagnostics) {
   for (const diagnostic of diagnostics) {
@@ -19739,11 +20604,31 @@ function printDiffPlan(diff, reason) {
   for (const path2 of diff.removed)
     console.log(`  - ${path2}`);
   console.log(`skillset: planned ${diff.added.length} added, ${diff.changed.length} changed, ${diff.missing.length} missing, ${diff.removed.length} removed (${reason})`);
+  printGeneratedChangelogDriftHint(diff);
+}
+function hasGeneratedChangelogDrift2(diff) {
+  return hasGeneratedChangelogPath2([...diff.added, ...diff.changed, ...diff.missing, ...diff.removed]);
+}
+function hasGeneratedChangelogPath2(paths) {
+  return paths.some((path2) => path2.endsWith("/CHANGELOG.md") || path2 === "CHANGELOG.md");
+}
+function printGeneratedChangelogDriftHint(diff) {
+  if (!hasGeneratedChangelogDrift2(diff))
+    return;
+  printGeneratedChangelogPathHint([...diff.added, ...diff.changed, ...diff.missing, ...diff.removed]);
+}
+function printGeneratedChangelogPathHint(paths) {
+  if (!hasGeneratedChangelogPath2(paths))
+    return;
+  console.log(generatedChangelogHint());
+}
+function generatedChangelogHint() {
+  return "skillset: generated CHANGELOG.md files are managed projections; edit pending wording with `skillset change reason <@ref>` before release, `skillset change amend <@ref>` for applied-history wording after release, or `skillset release amend <@ref>` for release-event metadata.";
 }
 
 // apps/skillset/src/runtime-hooks/commands.ts
-import { readFile as readFile18, stat as stat16 } from "fs/promises";
-import { join as join19 } from "path";
+import { readFile as readFile19, stat as stat15 } from "fs/promises";
+import { join as join18 } from "path";
 async function resolveSkillsetCommand(rootPath = process.cwd(), env = process.env) {
   const override = env.SKILLSET_HOOK_COMMAND?.trim();
   if (override !== undefined && override.length > 0)
@@ -19797,10 +20682,10 @@ async function commandExists(command, cwd, env) {
   return result.exitCode === 0;
 }
 async function isLocalSkillsetCheckout(rootPath) {
-  if (!await exists13(join19(rootPath, "apps", "skillset", "src", "cli.ts")))
+  if (!await exists12(join18(rootPath, "apps", "skillset", "src", "cli.ts")))
     return false;
   try {
-    const packageJson = JSON.parse(await readFile18(join19(rootPath, "package.json"), "utf8"));
+    const packageJson = JSON.parse(await readFile19(join18(rootPath, "package.json"), "utf8"));
     return packageJson.name === "skillset-workspace";
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT")
@@ -19819,9 +20704,9 @@ async function capture(argv, options) {
   const exitCode = await proc.exited;
   return { exitCode };
 }
-async function exists13(path2) {
+async function exists12(path2) {
   try {
-    await stat16(path2);
+    await stat15(path2);
     return true;
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT")
@@ -20077,13 +20962,21 @@ function renderAgentRuntimeSnippet(target) {
 }
 // apps/skillset/src/runtime-hooks/source-gate.ts
 var HOOK_RELEVANT_SOURCE_PATHS = [
+  "skillset.yaml",
+  "skillset/rules",
+  "skillset/skills",
+  "skillset/plugins",
+  "skillset/shared",
+  "skillset",
+  "changes",
+  ".skillset/skillset.yaml",
   ".skillset/config.yaml",
   ".skillset/src/rules",
   ".skillset/src/skills",
   ".skillset/src/plugins",
   ".skillset/src/shared",
   ".skillset/src",
-  ".skillset/changes/pending"
+  ".skillset/changes"
 ];
 async function readHookSourceGate(rootPath = process.cwd()) {
   const result = await capture2(["git", "status", "--porcelain=v1", "--untracked-files=all", "--", ...HOOK_RELEVANT_SOURCE_PATHS], {
@@ -20168,12 +21061,14 @@ function result(args) {
   };
 }
 // apps/skillset/src/release.ts
-import { appendFile, mkdir as mkdir9, readFile as readFile19, rm as rm6, stat as stat17, writeFile as writeFile9 } from "fs/promises";
+import { appendFile as appendFile2, mkdir as mkdir9, readFile as readFile20, rm as rm6, stat as stat16, writeFile as writeFile10 } from "fs/promises";
 import { createHash as createHash7 } from "crypto";
-import { dirname as dirname13, join as join20 } from "path";
+import { dirname as dirname14, join as join19 } from "path";
 var HISTORY_FILE3 = "changes/history.jsonl";
 var RELEASES_FILE = "changes/releases.jsonl";
+var RELEASE_AMENDMENTS_FILE = "changes/release-amendments.jsonl";
 var STATE_FILE2 = "changes/state.json";
+var MIN_REF_LENGTH2 = 6;
 var BUMP_WEIGHT = {
   none: 0,
   patch: 1,
@@ -20181,17 +21076,18 @@ var BUMP_WEIGHT = {
   major: 3
 };
 async function planRelease(rootPath, options = {}) {
-  const pending = await readPendingChangeEntries(rootPath, options);
+  const releaseOptions = await detectWorkspaceOptions(rootPath, options);
+  const graph = await loadBuildGraph(rootPath, releaseOptions);
+  const pending = await readPendingChangeEntries(rootPath, releaseOptions);
   if (pending.length === 0)
     return { baselineScopes: [], entries: [], ignoredEntries: [], scopes: [] };
-  const check = await changeCheck(rootPath, options);
+  const check = await changeCheck(rootPath, releaseOptions);
   const errors = check.issues.filter((issue) => issue.severity === "error");
   if (errors.length > 0) {
     throw new Error(`skillset: release plan requires valid pending change entries
 ` + errors.map((issue) => `${issue.path ?? "change"}: ${issue.code}: ${issue.message}`).join(`
 `));
   }
-  const graph = await loadBuildGraph(rootPath, options);
   const sourceUnits = new Map(check.status.sourceUnits.map((unit) => [unit.id, unit]));
   const sourceChanges = new Map(check.status.sourceChanges.map((change) => [change.id, change]));
   const entries = check.entries.flatMap((entry) => releaseEntryPlan(entry));
@@ -20208,27 +21104,28 @@ async function planRelease(rootPath, options = {}) {
   };
 }
 async function applyRelease(rootPath, options = {}) {
-  const plan = await planRelease(rootPath, options);
+  const releaseOptions = await detectWorkspaceOptions(rootPath, options);
+  const plan = await planRelease(rootPath, releaseOptions);
   if (plan.entries.length === 0) {
     return { files: [], plan, renderedFiles: 0 };
   }
-  const sourceDir = options.sourceDir ?? ".skillset";
+  const sourceDir = releaseOptions.sourceDir ?? ".skillset";
   const now = new Date().toISOString();
   const files = new Set;
-  const pending = (await changeCheck(rootPath, options)).entries;
+  const pending = (await changeCheck(rootPath, releaseOptions)).entries;
   const snapshots = await snapshotReleaseFiles(rootPath, sourceDir, pending, plan.baselineScopes.length > 0);
   let renderedFiles = 0;
   try {
     await appendHistory(rootPath, sourceDir, pending, now, files);
     if (plan.baselineScopes.length > 0) {
-      const state = await readReleaseState(rootPath, options);
-      const statePath = await writeReleaseState(rootPath, nextReleaseState(state, plan.baselineScopes, now), options);
+      const state = await readReleaseState(rootPath, releaseOptions);
+      const statePath = await writeReleaseState(rootPath, nextReleaseState(state, plan.baselineScopes, now), releaseOptions);
       files.add(statePath);
     }
     if (plan.scopes.length > 0) {
       await appendReleaseRecord(rootPath, sourceDir, plan, now, files);
     }
-    const rendered = await buildSkillset(rootPath, options);
+    const rendered = await buildSkillset(rootPath, releaseOptions);
     renderedFiles = rendered.length;
     for (const file of rendered)
       files.add(file.path);
@@ -20242,6 +21139,31 @@ async function applyRelease(rootPath, options = {}) {
   }
   return { files: [...files].sort(compareStrings), plan, renderedFiles };
 }
+async function amendReleaseRecord(rootPath, options) {
+  const storageOptions = await detectWorkspaceOptions(rootPath, options);
+  const records = await readReleaseRecords(rootPath, storageOptions);
+  const amendments = await readReleaseAmendments(rootPath, storageOptions);
+  const release = releaseView(resolveReleaseRef(records, options.ref), releaseRefIndex(records), amendments);
+  const notes = await resolveChangeReason(rootPath, options.reason);
+  const now = new Date().toISOString();
+  const sourceDir = storageOptions.sourceDir ?? ".skillset";
+  const amendmentPath = join19(sourceDir, RELEASE_AMENDMENTS_FILE).replaceAll("\\", "/");
+  const absolutePath = resolveInside(rootPath, amendmentPath);
+  await mkdir9(dirname14(absolutePath), { recursive: true });
+  await appendFile2(absolutePath, `${JSON.stringify({
+    amendedAt: now,
+    id: release.id,
+    notes,
+    ...release.notes === undefined ? {} : { previousNotes: release.notes },
+    source: release.path
+  })}
+`, "utf8");
+  const updatedAmendments = await readReleaseAmendments(rootPath, storageOptions);
+  return {
+    amendmentPath,
+    release: releaseView(resolveReleaseRef(records, release.id), releaseRefIndex(records), updatedAmendments)
+  };
+}
 function releaseEntryPlan(entry) {
   if (entry.id === undefined || entry.bump === undefined)
     return [];
@@ -20372,9 +21294,9 @@ function nextReleaseState(state, scopesToWrite, updatedAt) {
 async function appendHistory(rootPath, sourceDir, entries, appliedAt, files) {
   if (entries.length === 0)
     return;
-  const relativePath2 = join20(sourceDir, HISTORY_FILE3).replaceAll("\\", "/");
+  const relativePath2 = join19(sourceDir, HISTORY_FILE3).replaceAll("\\", "/");
   const absolutePath = resolveInside(rootPath, relativePath2);
-  await mkdir9(dirname13(absolutePath), { recursive: true });
+  await mkdir9(dirname14(absolutePath), { recursive: true });
   const lines = entries.flatMap((entry) => entry.id === undefined || entry.bump === undefined ? [] : [
     JSON.stringify({
       appliedAt,
@@ -20389,7 +21311,7 @@ async function appendHistory(rootPath, sourceDir, entries, appliedAt, files) {
   ]);
   if (lines.length === 0)
     return;
-  await appendFile(absolutePath, `${lines.join(`
+  await appendFile2(absolutePath, `${lines.join(`
 `)}
 `, "utf8");
   files.add(relativePath2);
@@ -20397,10 +21319,10 @@ async function appendHistory(rootPath, sourceDir, entries, appliedAt, files) {
 async function appendReleaseRecord(rootPath, sourceDir, plan, appliedAt, files) {
   if (plan.scopes.length === 0)
     return;
-  const relativePath2 = join20(sourceDir, RELEASES_FILE).replaceAll("\\", "/");
+  const relativePath2 = join19(sourceDir, RELEASES_FILE).replaceAll("\\", "/");
   const absolutePath = resolveInside(rootPath, relativePath2);
-  await mkdir9(dirname13(absolutePath), { recursive: true });
-  await appendFile(absolutePath, `${JSON.stringify({
+  await mkdir9(dirname14(absolutePath), { recursive: true });
+  await appendFile2(absolutePath, `${JSON.stringify({
     appliedAt,
     baseline: { hashSchema: SOURCE_HASH_SCHEMA, kind: "source-hashes" },
     entries: plan.entries.filter((entry) => !entry.ignored).map((entry) => entry.id).sort(compareStrings),
@@ -20419,18 +21341,18 @@ async function appendReleaseRecord(rootPath, sourceDir, plan, appliedAt, files)
 }
 async function snapshotReleaseFiles(rootPath, sourceDir, entries, includeReleaseState) {
   const paths = new Set([
-    join20(sourceDir, HISTORY_FILE3).replaceAll("\\", "/"),
+    join19(sourceDir, HISTORY_FILE3).replaceAll("\\", "/"),
     ...entries.map((entry) => entry.path)
   ]);
   if (includeReleaseState) {
-    paths.add(join20(sourceDir, STATE_FILE2).replaceAll("\\", "/"));
-    paths.add(join20(sourceDir, RELEASES_FILE).replaceAll("\\", "/"));
+    paths.add(join19(sourceDir, STATE_FILE2).replaceAll("\\", "/"));
+    paths.add(join19(sourceDir, RELEASES_FILE).replaceAll("\\", "/"));
   }
   const snapshots = [];
   for (const path2 of [...paths].sort(compareStrings)) {
     const absolutePath = resolveInside(rootPath, path2);
     snapshots.push({
-      ...await exists14(absolutePath) ? { content: await readFile19(absolutePath) } : {},
+      ...await exists13(absolutePath) ? { content: await readFile20(absolutePath) } : {},
       path: path2
     });
   }
@@ -20443,13 +21365,13 @@ async function restoreSnapshots(rootPath, snapshots) {
       await rm6(absolutePath, { force: true });
       continue;
     }
-    await mkdir9(dirname13(absolutePath), { recursive: true });
-    await writeFile9(absolutePath, snapshot.content);
+    await mkdir9(dirname14(absolutePath), { recursive: true });
+    await writeFile10(absolutePath, snapshot.content);
   }
 }
-async function exists14(path2) {
+async function exists13(path2) {
   try {
-    await stat17(path2);
+    await stat16(path2);
     return true;
   } catch (error) {
     if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
@@ -20487,17 +21409,146 @@ function releaseIdFor(scopes) {
   }
   return hash.digest("hex").slice(0, 12);
 }
+async function readReleaseRecords(rootPath, options = {}) {
+  const sourceDir = options.sourceDir ?? ".skillset";
+  const path2 = join19(sourceDir, RELEASES_FILE).replaceAll("\\", "/");
+  const absolutePath = resolveInside(rootPath, path2);
+  if (!await exists13(absolutePath))
+    return [];
+  const records = [];
+  const lines = (await readFile20(absolutePath, "utf8")).split(`
+`);
+  for (const [index, line] of lines.entries()) {
+    if (line.trim().length === 0)
+      continue;
+    const parsed = parseJsonLine(line, `${path2}:${index + 1}`);
+    const id = readStringField(parsed, "id", `${path2}:${index + 1}`);
+    const entries = readStringArrayField(parsed, "entries", `${path2}:${index + 1}`);
+    const scopes = readReleaseScopeArray(parsed, `${path2}:${index + 1}`);
+    records.push({
+      ...typeof parsed.appliedAt === "string" ? { appliedAt: parsed.appliedAt } : {},
+      entries,
+      id,
+      path: path2,
+      scopes
+    });
+  }
+  return records;
+}
+async function readReleaseAmendments(rootPath, options = {}) {
+  const sourceDir = options.sourceDir ?? ".skillset";
+  const path2 = join19(sourceDir, RELEASE_AMENDMENTS_FILE).replaceAll("\\", "/");
+  const absolutePath = resolveInside(rootPath, path2);
+  if (!await exists13(absolutePath))
+    return new Map;
+  const amendments = new Map;
+  const lines = (await readFile20(absolutePath, "utf8")).split(`
+`);
+  for (const [index, line] of lines.entries()) {
+    if (line.trim().length === 0)
+      continue;
+    const parsed = parseJsonLine(line, `${path2}:${index + 1}`);
+    const id = readStringField(parsed, "id", `${path2}:${index + 1}`);
+    const notes = readStringField(parsed, "notes", `${path2}:${index + 1}`);
+    amendments.set(id, {
+      ...typeof parsed.amendedAt === "string" ? { amendedAt: parsed.amendedAt } : {},
+      id,
+      notes
+    });
+  }
+  return amendments;
+}
+function resolveReleaseRef(records, ref) {
+  const normalized = ref.startsWith("@") ? ref.slice(1) : ref;
+  if (normalized.length < MIN_REF_LENGTH2) {
+    throw new Error(`skillset: release ref ${ref} must include at least ${MIN_REF_LENGTH2} characters`);
+  }
+  const matches = records.filter((record2) => record2.id === normalized || record2.id.startsWith(normalized));
+  if (matches.length === 0)
+    throw new Error(`skillset: unknown release ref ${ref}`);
+  if (matches.length > 1) {
+    throw new Error(`skillset: ambiguous release ref ${ref}; matches ${matches.map((record2) => `@${record2.id.slice(0, MIN_REF_LENGTH2)}`).join(", ")}`);
+  }
+  const [record] = matches;
+  if (record === undefined)
+    throw new Error(`skillset: unknown release ref ${ref}`);
+  return record;
+}
+function releaseRefIndex(records) {
+  const refs = new Map;
+  for (const record of records)
+    refs.set(record.id, `@${record.id.slice(0, MIN_REF_LENGTH2)}`);
+  return refs;
+}
+function releaseView(record, refs, amendments) {
+  const notes = amendments.get(record.id)?.notes;
+  return {
+    ...record.appliedAt === undefined ? {} : { appliedAt: record.appliedAt },
+    entries: record.entries,
+    id: record.id,
+    ...notes === undefined ? {} : { notes },
+    path: record.path,
+    ref: refs.get(record.id) ?? `@${record.id}`,
+    scopes: record.scopes
+  };
+}
+function readReleaseScopeArray(record, location) {
+  if (!Array.isArray(record.scopes))
+    throw new Error(`skillset: release record ${location} scopes must be an array`);
+  return record.scopes.map((item, index) => {
+    const scopeLocation = `${location}.scopes[${index}]`;
+    if (!isRecord3(item))
+      throw new Error(`skillset: release record ${scopeLocation} must be an object`);
+    const scope = readStringField(item, "scope", scopeLocation);
+    return {
+      ...isChangeBump(item.bump) ? { bump: item.bump } : {},
+      entries: Array.isArray(item.entries) ? item.entries.filter((entry) => typeof entry === "string") : [],
+      ...typeof item.nextVersion === "string" ? { nextVersion: item.nextVersion } : {},
+      ...typeof item.previousVersion === "string" ? { previousVersion: item.previousVersion } : {},
+      scope,
+      ...typeof item.sourceHash === "string" ? { sourceHash: item.sourceHash } : {}
+    };
+  });
+}
+function readStringArrayField(record, field, location) {
+  const value = record[field];
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new Error(`skillset: release record ${location} ${field} must be an array of strings`);
+  }
+  return value.map((item) => String(item));
+}
+function readStringField(record, field, location) {
+  const value = record[field];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`skillset: release record ${location} ${field} must be a string`);
+  }
+  return value;
+}
+function parseJsonLine(line, location) {
+  try {
+    const parsed = JSON.parse(line);
+    if (isRecord3(parsed))
+      return parsed;
+  } catch {}
+  throw new Error(`skillset: invalid release JSON in ${location}`);
+}
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isChangeBump(value) {
+  return value === "major" || value === "minor" || value === "patch" || value === "none";
+}
 // apps/skillset/src/test-runner.ts
-import { cp, mkdir as mkdir10, mkdtemp as mkdtemp4, readFile as readFile20, rm as rm7, stat as stat18, writeFile as writeFile10 } from "fs/promises";
+import { cp, mkdir as mkdir10, mkdtemp as mkdtemp4, readFile as readFile21, rm as rm7, stat as stat17, writeFile as writeFile11 } from "fs/promises";
 import { createHash as createHash8, randomBytes as randomBytes2 } from "crypto";
-import { dirname as dirname14, join as join21, relative as relative16, resolve as resolve9 } from "path";
+import { dirname as dirname15, join as join20, relative as relative16, resolve as resolve9 } from "path";
 import { tmpdir as tmpdir3 } from "os";
-var DEFAULT_SOURCE_DIR3 = ".skillset";
 var TEST_BUILD_DIR = "build/tests";
 var TEST_SCHEMA = 1;
 async function runSkillsetTest(rootPath, name, options = {}) {
-  const sourceDir = options.sourceDir ?? DEFAULT_SOURCE_DIR3;
-  const declaration = await readTestDeclaration(rootPath, sourceDir, name);
+  const graph = await loadBuildGraph(rootPath, options);
+  const sourceDir = graph.sourceDir;
+  const declaration = await readTestDeclaration(graph.rootConfigPath, name);
   if (declaration.source !== `repo:${sourceDir}`) {
     throw new Error(`skillset: test ${declaration.name} source ${declaration.source} is not supported yet; use repo:${sourceDir}`);
   }
@@ -20508,23 +21559,23 @@ async function runSkillsetTest(rootPath, name, options = {}) {
     targetFilter: declaration.targets
   };
   const runId = makeRunId(declaration.name);
-  const buildRoot = resolveInside(rootPath, join21(sourceDir, TEST_BUILD_DIR));
-  const runsRoot = join21(buildRoot, "runs");
-  const runPath = join21(runsRoot, runId);
-  const workspacePath = join21(runPath, "workspace");
-  const stagingRoot = await mkdtemp4(join21(tmpdir3(), "skillset-test-"));
-  const stagingWorkspacePath = join21(stagingRoot, "workspace");
-  const stagingSourcePath = join21(stagingWorkspacePath, sourceDir);
+  const buildRoot = resolveInside(rootPath, join20(sourceDir, TEST_BUILD_DIR));
+  const runsRoot = join20(buildRoot, "runs");
+  const runPath = join20(runsRoot, runId);
+  const workspacePath = join20(runPath, "workspace");
+  const stagingRoot = await mkdtemp4(join20(tmpdir3(), "skillset-test-"));
+  const stagingWorkspacePath = join20(stagingRoot, "workspace");
+  const stagingSourcePath = join20(stagingWorkspacePath, sourceDir);
   const sourcePath = resolveInside(rootPath, sourceDir);
   const workspaceLockPath = resolveInside(rootPath, ".skillset.lock");
-  const ignoredSourceBuildPath = resolveInside(rootPath, join21(sourceDir, "build"));
+  const ignoredSourceBuildPath = resolveInside(rootPath, join20(sourceDir, "build"));
   try {
     await mkdir10(stagingWorkspacePath, { recursive: true });
     await cp(sourcePath, stagingSourcePath, {
       filter: (path2) => !isSameOrInside2(ignoredSourceBuildPath, path2),
       recursive: true
     });
-    await copyIfExists(workspaceLockPath, join21(stagingWorkspacePath, ".skillset.lock"));
+    await copyIfExists(workspaceLockPath, join20(stagingWorkspacePath, ".skillset.lock"));
     await copyWorkspaceManagedFiles(rootPath, stagingWorkspacePath, workspaceLockPath, sourceDir);
     const assertions = [];
     let generatedFiles = 0;
@@ -20548,9 +21599,9 @@ async function runSkillsetTest(rootPath, name, options = {}) {
     await cp(stagingWorkspacePath, workspacePath, { recursive: true });
     const activationPath = await writeActivationProbes(runPath, declaration);
     const ok = assertions.every((assertion) => assertion.ok);
-    const reportPath = join21(runPath, "report.json");
-    const reportMarkdownPath = join21(runPath, "report.md");
-    const latestPath = join21(buildRoot, "latest");
+    const reportPath = join20(runPath, "report.json");
+    const reportMarkdownPath = join20(runPath, "report.md");
+    const latestPath = join20(buildRoot, "latest");
     const activationReport = activationPath === undefined ? {} : {
       activation: {
         path: relative16(rootPath, activationPath),
@@ -20569,8 +21620,8 @@ async function runSkillsetTest(rootPath, name, options = {}) {
       ...activationReport,
       workspacePath: relative16(rootPath, workspacePath)
     };
-    await writeFile10(reportPath, renderValidatedJson(report, relative16(rootPath, reportPath)), "utf8");
-    await writeFile10(reportMarkdownPath, renderMarkdownReport(report), "utf8");
+    await writeFile11(reportPath, renderValidatedJson(report, relative16(rootPath, reportPath)), "utf8");
+    await writeFile11(reportMarkdownPath, renderMarkdownReport(report), "utf8");
     await refreshLatest(buildRoot, runPath, latestPath, report, rootPath);
     return {
       assertions,
@@ -20592,9 +21643,8 @@ async function runSkillsetTest(rootPath, name, options = {}) {
     await rm7(stagingRoot, { force: true, recursive: true });
   }
 }
-async function readTestDeclaration(rootPath, sourceDir, requestedName) {
-  const configPath = resolveInside(rootPath, join21(sourceDir, "config.yaml"));
-  const config2 = parseYamlRecord(await readFile20(configPath, "utf8"), configPath);
+async function readTestDeclaration(configPath, requestedName) {
+  const config2 = parseYamlRecord(await readFile21(configPath, "utf8"), configPath);
   const defaultTargets2 = readEffectiveTargets(config2, configPath);
   const tests = config2.tests;
   if (!isJsonRecord(tests)) {
@@ -20761,18 +21811,18 @@ function assertionRecord(assertion) {
 async function runAssertion(workspacePath, assertion, options) {
   if (assertion.kind === "exists") {
     const targetPath = resolveInside(workspacePath, assertion.path);
-    const exists15 = await pathExists2(targetPath);
+    const exists14 = await pathExists2(targetPath);
     return {
       kind: "exists",
-      ok: exists15,
+      ok: exists14,
       path: assertion.path,
-      ...exists15 ? {} : { detail: "path does not exist" }
+      ...exists14 ? {} : { detail: "path does not exist" }
     };
   }
   if (assertion.kind === "contains") {
     const targetPath = resolveInside(workspacePath, assertion.path);
     try {
-      const content = await readFile20(targetPath, "utf8");
+      const content = await readFile21(targetPath, "utf8");
       const ok = content.includes(assertion.text);
       return {
         kind: "contains",
@@ -20816,11 +21866,11 @@ function activationExpectationCandidatePaths(graph, target, expect) {
   }
   if (expect.kind === "agent") {
     const projectRoot = targetProjectRoot4(graph, target);
-    return graph.projectAgents.filter((agent) => agent.name === expect.name || agent.outputName === expect.name).map((agent) => join21(projectRoot, "agents", `${agent.outputName}.${target === "claude" ? "md" : "toml"}`));
+    return graph.projectAgents.filter((agent) => agent.name === expect.name || agent.outputName === expect.name).map((agent) => join20(projectRoot, "agents", `${agent.outputName}.${target === "claude" ? "md" : "toml"}`));
   }
   return [
-    ...graph.standaloneSkills.filter((skill) => skill.id === expect.name).map((skill) => join21(graph.root.outputs.skills[target], dirname14(skill.relativePath), "SKILL.md")),
-    ...graph.plugins.flatMap((plugin) => plugin.skills.filter((skill) => skill.id === expect.name).map((skill) => join21(graph.root.outputs.plugins[target], "plugins", plugin.id, dirname14(skill.relativePath), "SKILL.md")))
+    ...graph.standaloneSkills.filter((skill) => skill.id === expect.name).map((skill) => join20(graph.root.outputs.skills[target], dirname15(skill.relativePath), "SKILL.md")),
+    ...graph.plugins.flatMap((plugin) => plugin.skills.filter((skill) => skill.id === expect.name).map((skill) => join20(graph.root.outputs.plugins[target], "plugins", plugin.id, dirname15(skill.relativePath), "SKILL.md")))
   ];
 }
 function targetProjectRoot4(graph, target) {
@@ -20829,22 +21879,22 @@ function targetProjectRoot4(graph, target) {
 async function writeActivationProbes(runPath, declaration) {
   if (declaration.activationProbes.length === 0)
     return;
-  const activationRoot = join21(runPath, "activation");
+  const activationRoot = join20(runPath, "activation");
   for (const target of declaration.targets) {
     const probes = declaration.activationProbes.filter((probe) => probe.targets.includes(target));
     if (probes.length === 0)
       continue;
-    const targetRoot = join21(activationRoot, target);
+    const targetRoot = join20(activationRoot, target);
     await mkdir10(targetRoot, { recursive: true });
     const records = probes.map((probe) => activationProbeRecord(probe, target));
-    await writeFile10(join21(targetRoot, "probes.json"), renderValidatedJson({
+    await writeFile11(join20(targetRoot, "probes.json"), renderValidatedJson({
       probes: records,
       schemaVersion: TEST_SCHEMA,
       target
     }, `activation ${target} probes`), "utf8");
     for (const record of records) {
       const name = typeof record.name === "string" ? record.name : "probe";
-      await writeFile10(join21(targetRoot, `${name}.md`), renderActivationProbeMarkdown(record), "utf8");
+      await writeFile11(join20(targetRoot, `${name}.md`), renderActivationProbeMarkdown(record), "utf8");
     }
   }
   return activationRoot;
@@ -20901,14 +21951,14 @@ async function refreshLatest(buildRoot, runPath, latestPath, report, rootPath) {
   const latest = {
     name: report.name,
     ok: report.ok,
-    reportPath: relative16(rootPath, join21(latestPath, "report.json")),
+    reportPath: relative16(rootPath, join20(latestPath, "report.json")),
     runId: report.runId,
     runPath: relative16(rootPath, runPath),
     schemaVersion: TEST_SCHEMA,
     source: report.source,
-    workspacePath: relative16(rootPath, join21(latestPath, "workspace"))
+    workspacePath: relative16(rootPath, join20(latestPath, "workspace"))
   };
-  await writeFile10(join21(buildRoot, "latest.json"), renderValidatedJson(latest, relative16(rootPath, join21(buildRoot, "latest.json"))), "utf8");
+  await writeFile11(join20(buildRoot, "latest.json"), renderValidatedJson(latest, relative16(rootPath, join20(buildRoot, "latest.json"))), "utf8");
 }
 function renderMarkdownReport(report) {
   const assertions = Array.isArray(report.assertions) ? report.assertions : [];
@@ -20945,7 +21995,7 @@ function activationProbeCount(report) {
 }
 async function pathExists2(path2) {
   try {
-    await stat18(path2);
+    await stat17(path2);
     return true;
   } catch {
     return false;
@@ -20954,7 +22004,7 @@ async function pathExists2(path2) {
 async function copyIfExists(sourcePath, targetPath) {
   if (!await pathExists2(sourcePath))
     return;
-  await mkdir10(dirname14(targetPath), { recursive: true });
+  await mkdir10(dirname15(targetPath), { recursive: true });
   await cp(sourcePath, targetPath);
 }
 async function copyWorkspaceManagedFiles(rootPath, stagingWorkspacePath, workspaceLockPath, sourceDir) {
@@ -20962,13 +22012,13 @@ async function copyWorkspaceManagedFiles(rootPath, stagingWorkspacePath, workspa
     return;
   let lock;
   try {
-    lock = JSON.parse(await readFile20(workspaceLockPath, "utf8"));
+    lock = JSON.parse(await readFile21(workspaceLockPath, "utf8"));
   } catch {
     return;
   }
   if (!isJsonRecord(lock) || !Array.isArray(lock.items))
     return;
-  const ignoredSourceBuildPath = resolveInside(rootPath, join21(sourceDir, "build"));
+  const ignoredSourceBuildPath = resolveInside(rootPath, join20(sourceDir, "build"));
   for (const item of lock.items) {
     if (!isJsonRecord(item) || !Array.isArray(item.files))
       continue;
@@ -20978,7 +22028,7 @@ async function copyWorkspaceManagedFiles(rootPath, stagingWorkspacePath, workspa
       const sourcePath = resolveInside(rootPath, file);
       if (isSameOrInside2(ignoredSourceBuildPath, sourcePath))
         continue;
-      await copyIfExists(sourcePath, join21(stagingWorkspacePath, file));
+      await copyIfExists(sourcePath, join20(stagingWorkspacePath, file));
     }
   }
 }
@@ -21007,12 +22057,15 @@ var USAGE = [
   "       skillset change <status|check> --staged [--root <path>] [--source <dir>] [--dist <dir>]",
   "       skillset change add --scope <source-unit> --bump <bump> [--group <group>] [--reason <text>|--reason-file <path>|--reason -] [--since <ref>] [--root <path>] [--source <dir>]",
   "       skillset change reason <@ref> [--append] [--reason <text>|--reason-file <path>|--reason -] [--root <path>] [--source <dir>]",
+  "       skillset change amend <@ref> [--reason <text>|--reason-file <path>|--reason -] [--root <path>] [--source <dir>]",
   "       skillset change <show|history> [@ref] [--root <path>] [--source <dir>]",
   "       skillset change list [--group <group>] [--root <path>] [--source <dir>]",
   "       skillset release audit [--root <path>] [--source <dir>] [--dist <dir>]",
   "       skillset release plan [--root <path>] [--source <dir>] [--dist <dir>]",
   "       skillset release apply [--yes|--dry-run] [--root <path>] [--source <dir>] [--dist <dir>]",
+  "       skillset release amend <@ref> [--reason <text>|--reason-file <path>|--reason -] [--root <path>]",
   "       skillset restore <backup-id> [--yes|--dry-run] [--root <path>]",
+  "       skillset suggest-source <generated-path> [--write --yes] [--root <path>] [--source <dir>] [--dist <dir>]",
   "       skillset distribute plan [name] [--root <path>] [--source <dir>] [--dist <dir>]",
   "       skillset features [feature-id] [--json]",
   "       skillset test [name] [--root <path>] [--source <dir>]",
@@ -21027,7 +22080,7 @@ var USAGE = [
   "       skillset import <claude|codex|agents> [--root <path>] [--source <dir>]"
 ].join(`
 `);
-async function runCli(rawArgs = process.argv.slice(2), invokedName = basename8(process.argv[1] ?? "")) {
+async function runCli(rawArgs = process.argv.slice(2), invokedName = basename9(process.argv[1] ?? "")) {
   const args = invokedName === "create-skillset" ? ["create", ...rawArgs] : rawArgs;
   if (args.some((arg) => arg === "--help" || arg === "-h")) {
     console.log(USAGE);
@@ -21065,9 +22118,12 @@ async function runCli(rawArgs = process.argv.slice(2), invokedName = basename8(p
     rootPath,
     rootExplicit,
     releaseSubcommand,
+    releaseReason,
+    releaseRef,
     setupGlobal,
     setupIncludes,
     setupTargets,
+    sourceSuggestionWrite,
     testName,
     yes
   } = parseArgs(args);
@@ -21100,8 +22156,8 @@ async function runCli(rawArgs = process.argv.slice(2), invokedName = basename8(p
     });
     if (ciReportPath !== undefined) {
       const reportPath = resolve10(ciReportPath);
-      await mkdir11(dirname15(reportPath), { recursive: true });
-      await writeFile11(reportPath, renderCiReportMarkdown(report));
+      await mkdir11(dirname16(reportPath), { recursive: true });
+      await writeFile12(reportPath, renderCiReportMarkdown(report));
     }
     printCiReport(report);
     if (!report.ok)
@@ -21146,6 +22202,18 @@ async function runCli(rawArgs = process.argv.slice(2), invokedName = basename8(p
       })).entry);
       return;
     }
+    if (changeSubcommand === "amend") {
+      if (changeRef === undefined)
+        throw new Error("skillset: change amend requires @ref");
+      const report = await amendAppliedChange(rootPath, {
+        ...changeOptions,
+        reason: changeReason ?? { kind: "auto" },
+        ref: changeRef
+      });
+      printChangeEntry("amended", report.entry);
+      console.log(`  amendment: ${report.path}`);
+      return;
+    }
     if (changeSubcommand === "show") {
       if (changeRef === undefined)
         throw new Error("skillset: change show requires @ref");
@@ -21194,7 +22262,17 @@ async function runCli(rawArgs = process.argv.slice(2), invokedName = basename8(p
       printReleaseApply(result3.plan, result3.files, result3.renderedFiles);
       return;
     }
-    throw new Error("skillset: expected release subcommand apply, audit, or plan");
+    if (releaseSubcommand === "amend") {
+      if (releaseRef === undefined)
+        throw new Error("skillset: release amend requires @ref");
+      printReleaseAmend(await amendReleaseRecord(rootPath, {
+        ...options,
+        reason: releaseReason ?? { kind: "auto" },
+        ref: releaseRef
+      }));
+      return;
+    }
+    throw new Error("skillset: expected release subcommand amend, apply, audit, or plan");
   }
   if (command === "restore") {
     if (importPath === undefined)
@@ -21335,6 +22413,7 @@ async function runCli(rawArgs = process.argv.slice(2), invokedName = basename8(p
     for (const path2 of diff.removed)
       console.log(`  - ${path2}`);
     console.log(`skillset: ${diff.added.length} added, ${diff.changed.length} changed, ${diff.missing.length} missing, ${diff.removed.length} removed (run skillset build --yes to apply)`);
+    printGeneratedChangelogDriftHint(diff);
     return;
   }
   if (command === "list") {
@@ -21423,6 +22502,19 @@ async function runCli(rawArgs = process.argv.slice(2), invokedName = basename8(p
       process.exitCode = 1;
     return;
   }
+  if (command === "suggest-source") {
+    if (importPath === undefined) {
+      throw new Error("skillset: expected a generated path to suggest source");
+    }
+    const report = await suggestSource(rootPath, importPath, {
+      ...options,
+      write: sourceSuggestionWrite && yes
+    });
+    printSourceSuggestion(report);
+    if (report.status === "refused")
+      process.exitCode = 1;
+    return;
+  }
   if (command === "doctor") {
     const report = await doctorSkillset(rootPath, options);
     if (jsonOutput) {
@@ -21542,6 +22634,24 @@ function printChangeCheck(report) {
   console.log(`skillset: change check found ${errors} error${errors === 1 ? "" : "s"} and ${warnings} warning${warnings === 1 ? "" : "s"}`);
   process.exitCode = 1;
 }
+function printSourceSuggestion(report) {
+  console.log(`skillset: source suggestion ${report.status} ${report.generatedPath}`);
+  if (report.sourcePath !== undefined)
+    console.log(`  source: ${report.sourcePath}`);
+  if (report.lockPath !== undefined)
+    console.log(`  lock: ${report.lockPath}`);
+  console.log(`  message: ${report.message}`);
+  if (report.wouldWrite)
+    console.log(`  write: ${report.wrote ? "applied" : "preview"}`);
+  for (const entry of report.entries) {
+    console.log(`  owner: [${entry.target}] ${entry.kind ?? "generated"} ${entry.sourcePath} -> ${entry.outputPath}`);
+  }
+  if (report.nextSteps.length > 0) {
+    console.log("  next:");
+    for (const step of report.nextSteps)
+      console.log(`    ${step}`);
+  }
+}
 function printChangeStatus(report) {
   const baseline = report.baseline.kind === "git-ref" ? `git ref ${report.baseline.ref}${report.baseline.resolvedRef === undefined ? "" : ` (${report.baseline.resolvedRef.slice(0, 12)})`}` : `${report.baseline.label} (${report.baseline.hashSchema})`;
   console.log(`skillset: source hash schema ${report.hashSchema}`);
@@ -21570,6 +22680,7 @@ function printChangeStatus(report) {
   for (const path2 of drift.removed)
     console.log(`  generated - ${path2}`);
   console.log(`skillset: generated-output drift ${drift.added.length} added, ${drift.changed.length} changed, ${drift.missing.length} missing, ${drift.removed.length} removed`);
+  printGeneratedChangelogDriftHint(drift);
 }
 function printCiReport(report) {
   for (const issue of report.lintIssues) {
@@ -21584,6 +22695,7 @@ function printCiReport(report) {
   }
   for (const path2 of report.fixedPaths)
     console.log(`  fixed ${path2}`);
+  printGeneratedChangelogPathHint(report.fixedPaths);
   const drift = report.drift;
   for (const path2 of drift.added)
     console.log(`  generated + ${path2}`);
@@ -21593,6 +22705,13 @@ function printCiReport(report) {
     console.log(`  generated ! ${path2}`);
   for (const path2 of drift.removed)
     console.log(`  generated - ${path2}`);
+  printGeneratedChangelogDriftHint(drift);
+  for (const suggestion of report.sourceSuggestions ?? []) {
+    console.log(`  source suggestion ${suggestion.status}: ${suggestion.generatedPath}`);
+    if (suggestion.sourcePath !== undefined)
+      console.log(`    source: ${suggestion.sourcePath}`);
+    console.log(`    ${suggestion.message}`);
+  }
   if (report.buildError !== undefined) {
     console.log(`  build error: ${report.buildError}`);
   }
@@ -21658,6 +22777,26 @@ function printReleaseApply(plan, files, renderedFiles) {
   for (const file of files)
     console.log(`  ${file}`);
 }
+function printReleaseAmend(report) {
+  console.log(`skillset: amended release ${report.release.ref} ${report.release.path}`);
+  console.log(`  id: ${report.release.id}`);
+  console.log(`  amendment: ${report.amendmentPath}`);
+  if (report.release.appliedAt !== undefined)
+    console.log(`  applied: ${report.release.appliedAt}`);
+  if (report.release.entries.length > 0)
+    console.log(`  entries: ${report.release.entries.join(",")}`);
+  for (const scope of report.release.scopes) {
+    const version = scope.previousVersion === undefined || scope.nextVersion === undefined ? "" : ` ${scope.previousVersion} -> ${scope.nextVersion}`;
+    const bump = scope.bump === undefined ? "" : ` (${scope.bump})`;
+    console.log(`  scope: ${sourceUnitDisplay(scope.scope)}${version}${bump}`);
+  }
+  if (report.release.notes !== undefined) {
+    console.log("  notes:");
+    for (const line of report.release.notes.split(`
+`))
+      console.log(`    ${line}`);
+  }
+}
 function printDistributionPlan(report) {
   if (report.plans.length === 0) {
     console.log("skillset: no distributions configured");
@@ -21725,7 +22864,7 @@ function printAdoptReport(report, reason) {
     console.log(`  source: git ${report.acquisition.repo} @ ${report.acquisition.ref}`);
   }
   if (report.alreadyAdopted) {
-    console.log("  note: repo already has .skillset/config.yaml; adopting against existing source");
+    console.log("  note: repo already has a Skillset workspace marker; adopting against existing source");
   }
   for (const file of report.setupFiles) {
     console.log(`  ${file.status === "create" ? "+" : "="} ${file.path}`);
@@ -21845,14 +22984,16 @@ function printRenderResult(outcome) {
 }
 function parseArgs(args) {
   const command = args[0];
-  if (command !== "adopt" && command !== "build" && command !== "change" && command !== "check" && command !== "ci" && command !== "create" && command !== "diff" && command !== "distribute" && command !== "doctor" && command !== "explain" && command !== "features" && command !== "hooks" && command !== "import" && command !== "init" && command !== "lint" && command !== "list" && command !== "release" && command !== "restore" && command !== "test") {
-    throw new Error(`skillset: expected command adopt, build, change, check, ci, create, diff, distribute, doctor, explain, features, hooks, import, init, lint, list, release, restore, or test
+  if (command !== "adopt" && command !== "build" && command !== "change" && command !== "check" && command !== "ci" && command !== "create" && command !== "diff" && command !== "distribute" && command !== "doctor" && command !== "explain" && command !== "features" && command !== "hooks" && command !== "import" && command !== "init" && command !== "lint" && command !== "list" && command !== "release" && command !== "restore" && command !== "suggest-source" && command !== "test") {
+    throw new Error(`skillset: expected command adopt, build, change, check, ci, create, diff, distribute, doctor, explain, features, hooks, import, init, lint, list, release, restore, suggest-source, or test
 ` + USAGE);
   }
   let changeSubcommand;
   let distributionName;
   let distributionSubcommand;
   let releaseSubcommand;
+  let releaseReason;
+  let releaseRef;
   let changeAppend = false;
   let changeBump;
   let changeGroup;
@@ -21886,18 +23027,19 @@ function parseArgs(args) {
   let setupGlobal = false;
   let setupIncludes;
   let setupTargets;
+  let sourceSuggestionWrite = false;
   let testName;
   let yes = false;
   let index = 1;
   if (command === "change") {
     const subcommand = args[index];
     if (!isChangeSubcommand(subcommand)) {
-      throw new Error("skillset: expected change subcommand add, check, history, list, reason, show, or status");
+      throw new Error("skillset: expected change subcommand add, amend, check, history, list, reason, show, or status");
     }
     changeSubcommand = subcommand;
     index += 1;
     const rawRef = args[index];
-    if ((subcommand === "check" || subcommand === "history" || subcommand === "reason" || subcommand === "show") && rawRef !== undefined && !rawRef.startsWith("--")) {
+    if ((subcommand === "amend" || subcommand === "check" || subcommand === "history" || subcommand === "reason" || subcommand === "show") && rawRef !== undefined && !rawRef.startsWith("--")) {
       changeRef = rawRef;
       index += 1;
     }
@@ -21905,10 +23047,15 @@ function parseArgs(args) {
   if (command === "release") {
     const subcommand = args[index];
     if (!isReleaseSubcommand(subcommand)) {
-      throw new Error("skillset: expected release subcommand apply, audit, or plan");
+      throw new Error("skillset: expected release subcommand amend, apply, audit, or plan");
     }
     releaseSubcommand = subcommand;
     index += 1;
+    const rawRef = args[index];
+    if (subcommand === "amend" && rawRef !== undefined && !rawRef.startsWith("--")) {
+      releaseRef = rawRef;
+      index += 1;
+    }
   }
   if (command === "distribute") {
     const subcommand = args[index];
@@ -21962,10 +23109,10 @@ function parseArgs(args) {
       index += 1;
     }
   }
-  if (command === "explain") {
+  if (command === "explain" || command === "suggest-source") {
     const rawPath = args[index];
     if (rawPath === undefined || rawPath.startsWith("--")) {
-      throw new Error("skillset: expected a path to explain");
+      throw new Error(`skillset: expected a path to ${command}`);
     }
     importPath = rawPath;
     index += 1;
@@ -21999,10 +23146,10 @@ function parseArgs(args) {
     const equalsIndex = arg.indexOf("=");
     const flag = equalsIndex === -1 ? arg : arg.slice(0, equalsIndex);
     const inlineValue = equalsIndex === -1 ? undefined : arg.slice(equalsIndex + 1);
-    if (flag !== "--root" && flag !== "--source" && flag !== "--dist" && flag !== "--name" && flag !== "--kind" && flag !== "--from" && flag !== "--append" && flag !== "--bump" && flag !== "--group" && flag !== "--reason" && flag !== "--reason-file" && flag !== "--ref" && flag !== "--since" && flag !== "--staged" && flag !== "--yes" && flag !== "--dry-run" && flag !== "--updated" && flag !== "--all" && flag !== "--isolated" && flag !== "--scope" && flag !== "--global" && flag !== "--targets" && flag !== "--include" && flag !== "--fix" && flag !== "--report" && flag !== "--json" && flag !== "--runner" && flag !== "--target" && flag !== "--agent-runtime" && flag !== "--pre-commit" && flag !== "--pre-push") {
+    if (flag !== "--root" && flag !== "--source" && flag !== "--dist" && flag !== "--name" && flag !== "--kind" && flag !== "--from" && flag !== "--append" && flag !== "--bump" && flag !== "--group" && flag !== "--reason" && flag !== "--reason-file" && flag !== "--ref" && flag !== "--since" && flag !== "--staged" && flag !== "--yes" && flag !== "--dry-run" && flag !== "--updated" && flag !== "--all" && flag !== "--isolated" && flag !== "--scope" && flag !== "--global" && flag !== "--targets" && flag !== "--include" && flag !== "--fix" && flag !== "--report" && flag !== "--json" && flag !== "--runner" && flag !== "--target" && flag !== "--agent-runtime" && flag !== "--pre-commit" && flag !== "--pre-push" && flag !== "--write") {
       throw new Error(`skillset: unknown option ${arg}`);
     }
-    if (flag === "--yes" || flag === "--dry-run" || flag === "--updated" || flag === "--all" || flag === "--isolated" || flag === "--append" || flag === "--staged" || flag === "--global" || flag === "--fix" || flag === "--json" || flag === "--agent-runtime" || flag === "--pre-commit" || flag === "--pre-push") {
+    if (flag === "--yes" || flag === "--dry-run" || flag === "--updated" || flag === "--all" || flag === "--isolated" || flag === "--append" || flag === "--staged" || flag === "--global" || flag === "--fix" || flag === "--json" || flag === "--agent-runtime" || flag === "--pre-commit" || flag === "--pre-push" || flag === "--write") {
       if (inlineValue !== undefined)
         throw new Error(`skillset: ${flag} does not take a value`);
       if (flag === "--yes")
@@ -22031,6 +23178,8 @@ function parseArgs(args) {
         hookPreCommit = true;
       if (flag === "--pre-push")
         hookPrePush = true;
+      if (flag === "--write")
+        sourceSuggestionWrite = true;
       continue;
     }
     const value = inlineValue ?? args[index + 1];
@@ -22047,8 +23196,12 @@ function parseArgs(args) {
       sourceDir = value;
     if (flag === "--dist")
       distDir = value;
-    if (flag === "--ref")
-      changeRef = value;
+    if (flag === "--ref") {
+      if (command === "release" && releaseSubcommand === "amend")
+        releaseRef = value;
+      else
+        changeRef = value;
+    }
     if (flag === "--since")
       changeSince = value;
     if (flag === "--scope") {
@@ -22064,10 +23217,20 @@ function parseArgs(args) {
     }
     if (flag === "--group")
       changeGroup = value;
-    if (flag === "--reason")
-      changeReason = setChangeReason(changeReason, value === "-" ? { kind: "stdin" } : { kind: "inline", value });
-    if (flag === "--reason-file")
-      changeReason = setChangeReason(changeReason, { kind: "file", path: value });
+    if (flag === "--reason") {
+      const reason = value === "-" ? { kind: "stdin" } : { kind: "inline", value };
+      if (command === "release" && releaseSubcommand === "amend")
+        releaseReason = setChangeReason(releaseReason, reason);
+      else
+        changeReason = setChangeReason(changeReason, reason);
+    }
+    if (flag === "--reason-file") {
+      const reason = { kind: "file", path: value };
+      if (command === "release" && releaseSubcommand === "amend")
+        releaseReason = setChangeReason(releaseReason, reason);
+      else
+        changeReason = setChangeReason(changeReason, reason);
+    }
     if (flag === "--bump")
       changeBump = readChangeBump(value);
     if (flag === "--report")
@@ -22159,6 +23322,10 @@ function parseArgs(args) {
   if (command === "release" && releaseSubcommand !== "apply" && (dryRun || yes)) {
     throw new Error("skillset: --yes and --dry-run are only supported with release apply");
   }
+  validateReleaseFlags(command, releaseSubcommand, {
+    ...releaseReason === undefined ? {} : { reason: releaseReason },
+    ...releaseRef === undefined ? {} : { ref: releaseRef }
+  });
   validateTestFlags(command, {
     ...buildMode === undefined ? {} : { buildMode },
     ...distDir === undefined ? {} : { distDir },
@@ -22173,6 +23340,14 @@ function parseArgs(args) {
     ...scopes === undefined ? {} : { scopes },
     ...sourceDir === undefined ? {} : { sourceDir }
   });
+  validateSuggestSourceFlags(command, {
+    ...buildMode === undefined ? {} : { buildMode },
+    ...changeSince === undefined ? {} : { changeSince },
+    dryRun,
+    ...scopes === undefined ? {} : { scopes },
+    write: sourceSuggestionWrite,
+    yes
+  });
   const options = {
     ...buildMode === undefined ? {} : { buildMode },
     ...scopes === undefined ? {} : { scopes },
@@ -22210,20 +23385,23 @@ function parseArgs(args) {
     jsonOutput,
     options,
     ...releaseSubcommand === undefined ? {} : { releaseSubcommand },
+    ...releaseReason === undefined ? {} : { releaseReason },
+    ...releaseRef === undefined ? {} : { releaseRef },
     rootExplicit,
     rootPath: resolve10(rootPath),
     setupGlobal,
     ...setupIncludes === undefined ? {} : { setupIncludes },
     ...setupTargets === undefined ? {} : { setupTargets },
+    sourceSuggestionWrite,
     ...testName === undefined ? {} : { testName },
     yes
   };
 }
 function isReleaseSubcommand(value) {
-  return value === "apply" || value === "audit" || value === "plan";
+  return value === "amend" || value === "apply" || value === "audit" || value === "plan";
 }
 function isChangeSubcommand(value) {
-  return value === "add" || value === "check" || value === "history" || value === "list" || value === "reason" || value === "show" || value === "status";
+  return value === "add" || value === "amend" || value === "check" || value === "history" || value === "list" || value === "reason" || value === "show" || value === "status";
 }
 function readChangeScopes(value) {
   const scopes = value.split(",").map((scope) => scope.trim()).filter((scope) => scope.length > 0);
@@ -22252,8 +23430,8 @@ function validateChangeFlags(command, subcommand, change) {
     append: subcommand === "reason",
     bump: subcommand === "add",
     group: subcommand === "add" || subcommand === "list",
-    reason: subcommand === "add" || subcommand === "reason",
-    ref: subcommand === "check" || subcommand === "history" || subcommand === "reason" || subcommand === "show",
+    reason: subcommand === "add" || subcommand === "amend" || subcommand === "reason",
+    ref: subcommand === "amend" || subcommand === "check" || subcommand === "history" || subcommand === "reason" || subcommand === "show",
     scopes: subcommand === "add",
     staged: subcommand === "check" || subcommand === "status"
   };
@@ -22264,14 +23442,28 @@ function validateChangeFlags(command, subcommand, change) {
   if (change.group !== undefined && !allowed.group)
     throw new Error("skillset: --group is only supported with change add or change list");
   if (change.reason !== undefined && !allowed.reason)
-    throw new Error("skillset: --reason and --reason-file are only supported with change add or change reason");
+    throw new Error("skillset: --reason and --reason-file are only supported with change add, change amend, or change reason");
   if (change.ref !== undefined && !allowed.ref)
-    throw new Error("skillset: --ref is only supported with change check, change history, change reason, or change show");
+    throw new Error("skillset: --ref is only supported with change amend, change check, change history, change reason, or change show");
   if (change.scopes !== undefined && !allowed.scopes)
     throw new Error("skillset: source-unit --scope is only supported with change add");
   if (change.staged && !allowed.staged)
     throw new Error("skillset: --staged is only supported with change status or change check");
 }
+function validateReleaseFlags(command, subcommand, release) {
+  const hasReleaseFlag = release.reason !== undefined || release.ref !== undefined;
+  if (hasReleaseFlag && command !== "release") {
+    throw new Error("skillset: release options are only supported with release commands");
+  }
+  if (command !== "release")
+    return;
+  if (release.reason !== undefined && subcommand !== "amend") {
+    throw new Error("skillset: --reason and --reason-file are only supported with release amend");
+  }
+  if (release.ref !== undefined && subcommand !== "amend") {
+    throw new Error("skillset: --ref is only supported with release amend");
+  }
+}
 function validateHookFlags(command, hooks) {
   const hasHookPrintFlag = hooks.agentRuntime || hooks.preCommit || hooks.prePush || hooks.runner !== undefined || hooks.target !== undefined;
   if (hasHookPrintFlag && (command !== "hooks" || hooks.subcommand !== "print")) {
@@ -22312,6 +23504,25 @@ function validateRestoreFlags(command, restore) {
     throw new Error("skillset: restore only supports --root, --yes, and --dry-run");
   }
 }
+function validateSuggestSourceFlags(command, suggestion) {
+  if (suggestion.write && command !== "suggest-source") {
+    throw new Error("skillset: --write is only supported with suggest-source");
+  }
+  if (command !== "suggest-source")
+    return;
+  if (suggestion.buildMode !== undefined)
+    throw new Error("skillset: --updated and --all are not supported with suggest-source");
+  if (suggestion.changeSince !== undefined)
+    throw new Error("skillset: --since is not supported with suggest-source");
+  if (suggestion.dryRun)
+    throw new Error("skillset: --dry-run is redundant for suggest-source preview mode");
+  if (suggestion.scopes !== undefined)
+    throw new Error("skillset: --scope is not supported with suggest-source");
+  if (suggestion.yes && !suggestion.write)
+    throw new Error("skillset: --yes is only supported with suggest-source --write");
+  if (suggestion.write && !suggestion.yes)
+    throw new Error("skillset: suggest-source --write requires --yes");
+}
 function setBuildMode(current, next) {
   if (current !== undefined && current !== next) {
     throw new Error(`skillset: conflicting build mode flags --${current} and --${next}`);