mdkg 0.3.8 → 0.3.9

package/CHANGELOG.md

@@ -8,6 +8,32 @@ mdkg is pre-v1 public alpha software. Command, graph, cache, bundle, and DAL con
 
 ## Unreleased
 
+## 0.3.9 - 2026-06-27
+
+### Added
+
+- Added `.mdkg/config.json` customization overlays for organization standards,
+  custom core docs, and configured skill mirror target paths while keeping the
+  mdkg CLI kernel upgradable through `mdkg upgrade --apply`.
+- Added configurable skill mirror support so repos can mirror canonical
+  `.mdkg/skills` into arbitrary contained agent-local skill roots, with
+  `.agents/skills` and `.claude/skills` preserved as defaults.
+- Added `COLLABORATION.md` as the canonical collaboration/operator profile core
+  doc while keeping `HUMAN.md` as a one-release legacy alias.
+- Added deterministic release-notes data generation from `CHANGELOG.md` for
+  public docs and future per-release cards.
+
+### Changed
+
+- Updated `mdkg init --agent` and `mdkg upgrade --apply` to seed and preserve
+  customization overlays, configurable mirrors, `COLLABORATION.md`, legacy
+  `HUMAN.md`, and accurate managed init-manifest hashes.
+- Refreshed first-party mdkg skills and default init seed skills for current CLI
+  coverage, MANIFEST authoring, configured mirror targets, pre-publish gates,
+  and explicit no-publish/no-tag/no-push approval boundaries.
+- Expanded `npm run docs:check` and `prepublishOnly` to verify generated CLI
+  docs, generated release-note data, and public command examples before publish.
+
 ## 0.3.8 - 2026-06-25
 
 ### Added

package/CLI_COMMAND_MATRIX.md

@@ -1,7 +1,7 @@
 # CLI Command Matrix
 
 as_of: 2026-06-21
-package_version_in_source: 0.3.8
+package_version_in_source: 0.3.9
 source: live help from `src/cli.ts`, runtime command handlers, and `dec-15`..`dec-18`
 status: canonical single-source command and flag reference for mdkg
 
@@ -118,7 +118,7 @@ Notes:
 - `--agent` is the canonical complete AI-agent bootstrap path
 - removed flags `--llm`, `--agents`, `--claude`, and `--omni` fail before mutation with guidance to use `mdkg init --agent`
 - published bootstrap config is root-only by default
-- `--agent` creates `AGENT_START.md`, `AGENTS.md`, `CLAUDE.md`, `llms.txt`, `CLI_COMMAND_MATRIX.md`, strict-node core docs, default mdkg usage skills, `events.jsonl`, registry, and skill mirrors
+- `--agent` creates `AGENT_START.md`, `AGENTS.md`, `CLAUDE.md`, `llms.txt`, `CLI_COMMAND_MATRIX.md`, strict-node `SOUL.md` / `COLLABORATION.md` core docs, legacy `HUMAN.md`, default mdkg usage skills, `events.jsonl`, registry, and configured skill mirrors
 - run `mdkg index` after fresh init before treating `mdkg doctor --strict --json` as a clean health gate; init writes source scaffold files and index writes generated caches
 
 ### `mdkg upgrade`
@@ -443,7 +443,9 @@ JSON receipt:
 - `{ action: "synced", sync: { synced, pruned, targets } }`
 
 Notes:
-- syncs canonical `.mdkg/skills/` into `.agents/skills/` and `.claude/skills/`
+- syncs canonical `.mdkg/skills/` into configured
+  `customization.skill_mirrors.targets` paths from `.mdkg/config.json`
+- defaults are `.agents/skills` and `.claude/skills`
 - preserves unrelated existing folders
 - same-slug collisions fail unless forced
 

package/README.md

@@ -14,7 +14,7 @@ mdkg stays deliberately boring:
 - first-class rebuildable SQLite cache through built-in `node:sqlite`
 - no daemon, hosted index, or vector DB
 
-Current package version in source: `0.3.8`
+Current package version in source: `0.3.9`
 
 mdkg is still pre-v1 public alpha software. The public package is usable, but graph, cache, bundle, and DAL contracts may continue to change quickly while the project converges on a stable v1 surface.
 
@@ -82,7 +82,7 @@ mdkg init --agent
 mdkg index
 ```
 
-This is the canonical AI-agent bootstrap path. It creates `.mdkg/`, `AGENT_START.md`, `AGENTS.md`, `CLAUDE.md`, `llms.txt`, `CLI_COMMAND_MATRIX.md`, strict-node `SOUL.md` / `HUMAN.md`, the three default mdkg usage skills, `events.jsonl`, the skill registry, core pin updates, and mirrored skill folders under `.agents/skills/` and `.claude/skills/`. It also updates `.gitignore` / `.npmignore` by default. Use `--no-update-ignores` to opt out of those ignore-file updates.
+This is the canonical AI-agent bootstrap path. It creates `.mdkg/`, `AGENT_START.md`, `AGENTS.md`, `CLAUDE.md`, `llms.txt`, `CLI_COMMAND_MATRIX.md`, strict-node `SOUL.md` / `COLLABORATION.md`, legacy `HUMAN.md` for one release, the default mdkg usage skills, `events.jsonl`, the skill registry, core pin updates, and configured skill mirrors under `.agents/skills/` and `.claude/skills/` by default. It also updates `.gitignore` / `.npmignore` by default. Use `--no-update-ignores` to opt out of those ignore-file updates.
 
 Run `mdkg index` after a fresh init before using `mdkg status --json` or
 `mdkg doctor --strict --json` as health gates. Init writes source scaffold

package/dist/cli.js

@@ -414,7 +414,8 @@ function printSkillHelp(log, subcommand) {
             log("Usage:");
             log("  mdkg skill sync [--force] [--json]");
             log("\nWhen to use:");
-            log("  Rebuild .agents/skills and .claude/skills from canonical .mdkg/skills.");
+            log("  Rebuild configured skill mirror targets from canonical .mdkg/skills.");
+            log("  Defaults are .agents/skills and .claude/skills; add custom targets in .mdkg/config.json.");
             printGlobalOptions(log);
             return;
         default:

package/dist/command-contract.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "package_version": "0.3.8",
+  "package_version": "0.3.9",
   "source": {
     "help_targets": "scripts/cli_help_targets.js",
     "command_matrix": "CLI_COMMAND_MATRIX.md"
@@ -9128,5 +9128,5 @@
       }
     }
   ],
-  "contract_hash": "145781176fcd00d6b7c7edd8e013e902acea2ace8764dbf0bb063a8d3913a3e1"
+  "contract_hash": "3c13c572c740f1e40db33fa5867fa227a8347df0750ef3beb0696d5931761a6c"
 }

package/dist/commands/init.js

@@ -17,6 +17,7 @@ const skill_support_1 = require("./skill_support");
 const skill_mirror_1 = require("./skill_mirror");
 const DEFAULT_SEED_SUBDIR = path_1.default.resolve(__dirname, "..", "init");
 const SOUL_PIN_ID = "rule-soul";
+const COLLABORATION_PIN_ID = "rule-7";
 const HUMAN_PIN_ID = "rule-human";
 const DEFAULT_CORE_LIST_HEADER = [
     "# mdkg verbose core list",
@@ -175,6 +176,52 @@ function humanTemplate(created) {
         "",
     ].join("\n");
 }
+function collaborationTemplate(created) {
+    return [
+        "---",
+        `id: ${COLLABORATION_PIN_ID}`,
+        "type: rule",
+        "title: collaboration profile and operator preferences",
+        "tags: [collaboration, preferences, operator]",
+        "owners: []",
+        "links: []",
+        "artifacts: []",
+        "relates: [rule-human]",
+        "refs: [dec-53]",
+        "aliases: [collaboration, operator-profile]",
+        `created: ${created}`,
+        `updated: ${created}`,
+        "---",
+        "",
+        "# Purpose",
+        "",
+        "Capture stable collaboration preferences, operating boundaries, and repo-specific human expectations so agents can work with less ambiguity.",
+        "",
+        "# Scope",
+        "",
+        "Applies to planning, implementation, review, release, and handoff interactions in this repository.",
+        "",
+        "# Compatibility",
+        "",
+        "`COLLABORATION.md` is canonical. `HUMAN.md` remains a one-release legacy alias for repos and agent prompts that still reference it; read `COLLABORATION.md` first and then use `HUMAN.md` only for compatibility notes not yet migrated.",
+        "",
+        "# Requirements",
+        "",
+        "- Keep top goals, boundaries, and style preferences current.",
+        "- Include ask-before-doing constraints for risky or high-impact actions.",
+        "- Record preferred environment assumptions and validation commands.",
+        "- Preserve local operator customizations during `mdkg upgrade --apply`.",
+        "",
+        "# Notes",
+        "",
+        "Suggested prompts:",
+        "- What are your top 3 goals in this repo right now?",
+        "- What should never happen without confirmation?",
+        "- What coding/review style should the agent prefer?",
+        "- What OS/runtime/test commands should be assumed?",
+        "",
+    ].join("\n");
+}
 function seededInitEvent(nowIso) {
     const event = {
         ts: nowIso,
@@ -277,6 +324,31 @@ function ensureCorePins(coreListPath, requiredPins) {
     fs_1.default.mkdirSync(path_1.default.dirname(coreListPath), { recursive: true });
     fs_1.default.writeFileSync(coreListPath, output, "utf8");
 }
+function refreshManifestHash(root, manifest, relPath) {
+    const entry = manifest.files.find((file) => file.path === relPath);
+    if (!entry) {
+        return;
+    }
+    const targetPath = path_1.default.join(root, relPath);
+    if (fs_1.default.existsSync(targetPath) && fs_1.default.statSync(targetPath).isFile()) {
+        entry.sha256 = (0, init_manifest_1.sha256File)(targetPath);
+    }
+}
+function ensureCreatedCoreManifestEntry(root, manifest, relPath, stats) {
+    if (manifest.files.some((file) => file.path === relPath) || !stats.createdPaths.includes(relPath)) {
+        return;
+    }
+    const targetPath = path_1.default.join(root, relPath);
+    if (!fs_1.default.existsSync(targetPath) || !fs_1.default.statSync(targetPath).isFile()) {
+        return;
+    }
+    manifest.files.push({
+        path: relPath,
+        category: "core",
+        sha256: (0, init_manifest_1.sha256File)(targetPath),
+    });
+    manifest.files.sort((a, b) => a.path.localeCompare(b.path));
+}
 function runInitCommand(options) {
     const root = path_1.default.resolve(options.root);
     const seedRoot = options.seedRoot ? path_1.default.resolve(options.seedRoot) : DEFAULT_SEED_SUBDIR;
@@ -295,6 +367,7 @@ function runInitCommand(options) {
     const seedReadme = path_1.default.join(seedRoot, "README.md");
     const seedDefaultSkills = path_1.default.join(seedRoot, "skills", "default");
     const seedSoul = path_1.default.join(seedCore, "SOUL.md");
+    const seedCollaboration = path_1.default.join(seedCore, "COLLABORATION.md");
     const seedHuman = path_1.default.join(seedCore, "HUMAN.md");
     const seedManifest = (0, init_manifest_1.createInitManifest)(seedRoot, (0, version_1.readPackageVersion)(), {
         includeAgentDocs: Boolean(options.agent),
@@ -367,6 +440,7 @@ function runInitCommand(options) {
         if (options.agent) {
             const today = (0, date_1.formatDate)(new Date());
             const soulPath = path_1.default.join(mdkgDir, "core", "SOUL.md");
+            const collaborationPath = path_1.default.join(mdkgDir, "core", "COLLABORATION.md");
             const humanPath = path_1.default.join(mdkgDir, "core", "HUMAN.md");
             const skillsDir = path_1.default.join(mdkgDir, "skills");
             const registryPath = path_1.default.join(skillsDir, "registry.md");
@@ -378,6 +452,9 @@ function runInitCommand(options) {
             if (!fs_1.default.existsSync(seedSoul)) {
                 writeFileIfMissing(root, soulPath, soulTemplate(today), force, stats);
             }
+            if (!fs_1.default.existsSync(seedCollaboration)) {
+                writeFileIfMissing(root, collaborationPath, collaborationTemplate(today), force, stats);
+            }
             if (!fs_1.default.existsSync(seedHuman)) {
                 writeFileIfMissing(root, humanPath, humanTemplate(today), force, stats);
             }
@@ -386,9 +463,13 @@ function runInitCommand(options) {
                 writeFileIfMissing(root, eventsPath, seededInitEvent(new Date().toISOString()), force, stats);
             }
             const coreListPath = path_1.default.join(mdkgDir, "core", "core.md");
-            ensureCorePins(coreListPath, [SOUL_PIN_ID, HUMAN_PIN_ID]);
-            (0, skill_mirror_1.scaffoldMirrorRoots)(root);
+            ensureCorePins(coreListPath, [SOUL_PIN_ID, COLLABORATION_PIN_ID, HUMAN_PIN_ID]);
+            refreshManifestHash(root, seedManifest, ".mdkg/core/core.md");
+            ensureCreatedCoreManifestEntry(root, seedManifest, ".mdkg/core/SOUL.md", stats);
+            ensureCreatedCoreManifestEntry(root, seedManifest, ".mdkg/core/COLLABORATION.md", stats);
+            ensureCreatedCoreManifestEntry(root, seedManifest, ".mdkg/core/HUMAN.md", stats);
             const config = (0, config_1.loadConfig)(root);
+            (0, skill_mirror_1.scaffoldMirrorRoots)(root, config);
             (0, skill_support_1.refreshSkillsRegistry)(root, config);
             stats.registryRefreshed = true;
             const mirrorResult = (0, skill_mirror_1.syncSkillMirrors)({ root, config, createRoots: true, force });
@@ -452,7 +533,7 @@ function runInitCommand(options) {
     }
     if (options.agent) {
         console.log("agent bootstrap: AGENT_START.md, AGENTS.md, CLAUDE.md, llms.txt, CLI_COMMAND_MATRIX.md");
-        console.log("agent core pins: rule-soul, rule-human");
+        console.log("agent core pins: rule-soul, rule-7, rule-human");
         console.log("agent event log: .mdkg/work/events/events.jsonl");
         console.log(`skill mirrors: ${stats.mirroredSkills} sync operation(s) across ${stats.mirrorTargets} target(s)`);
         if (stats.registryRefreshed) {

package/dist/commands/skill.js

@@ -186,7 +186,7 @@ function runSkillNewCommandLocked(options) {
     (0, atomic_1.atomicWriteFile)(canonicalPath, content);
     (0, skill_support_1.ensureSkillsRegistry)(root, config);
     (0, skill_support_1.refreshSkillsRegistry)(root, config);
-    if ((0, skill_mirror_1.shouldMaintainSkillMirrors)(root)) {
+    if ((0, skill_mirror_1.shouldMaintainSkillMirrors)(root, config)) {
         (0, skill_mirror_1.syncSkillMirrors)({ root, config, createRoots: true, force });
     }
     if (config.index.auto_reindex) {

package/dist/commands/skill_mirror.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.configuredSkillMirrorTargets = configuredSkillMirrorTargets;
 exports.syncSkillMirrors = syncSkillMirrors;
 exports.preflightSkillMirrorTargets = preflightSkillMirrorTargets;
 exports.shouldMaintainSkillMirrors = shouldMaintainSkillMirrors;
@@ -10,22 +11,26 @@ exports.auditSkillMirrors = auditSkillMirrors;
 exports.scaffoldMirrorRoots = scaffoldMirrorRoots;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const config_1 = require("../core/config");
 const skills_indexer_1 = require("../graph/skills_indexer");
 const errors_1 = require("../util/errors");
-const MIRROR_PRODUCTS = ["agents", "claude"];
 const MANIFEST_FILE = ".mdkg-managed.json";
 const MANAGED_ROOT_MARKERS = [
     path_1.default.join(".mdkg", "core", "SOUL.md"),
+    path_1.default.join(".mdkg", "core", "COLLABORATION.md"),
     path_1.default.join(".mdkg", "core", "HUMAN.md"),
 ];
 const ALLOWED_ROOT_ENTRIES = ["SKILL.md", "references", "assets", "scripts"];
-function resolveMirrorTargets(root) {
-    return MIRROR_PRODUCTS.map((product) => {
-        const rootDir = path_1.default.join(root, `.${product}`);
-        const skillsRoot = path_1.default.join(rootDir, "skills");
+function configuredSkillMirrorTargets(config) {
+    const configured = config?.customization.skill_mirrors.targets ?? (0, config_1.defaultCustomizationConfig)().skill_mirrors.targets;
+    return Array.from(new Set(configured.map((value) => value.trim()).filter(Boolean)));
+}
+function resolveMirrorTargets(root, config) {
+    return configuredSkillMirrorTargets(config).map((configuredPath) => {
+        const skillsRoot = path_1.default.join(root, configuredPath);
         return {
-            product,
-            rootDir,
+            configuredPath,
+            rootDir: path_1.default.dirname(skillsRoot),
             skillsRoot,
             manifestPath: path_1.default.join(skillsRoot, MANIFEST_FILE),
         };
@@ -55,11 +60,11 @@ function writeManifest(target, managed) {
     fs_1.default.mkdirSync(target.skillsRoot, { recursive: true });
     fs_1.default.writeFileSync(target.manifestPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
 }
-function shouldCreateMirrorRoots(root) {
+function shouldCreateMirrorRoots(root, config) {
     if (MANAGED_ROOT_MARKERS.some((relPath) => fs_1.default.existsSync(path_1.default.join(root, relPath)))) {
         return true;
     }
-    return resolveMirrorTargets(root).some((target) => fs_1.default.existsSync(target.rootDir) || fs_1.default.existsSync(target.skillsRoot));
+    return resolveMirrorTargets(root, config).some((target) => fs_1.default.existsSync(target.rootDir) || fs_1.default.existsSync(target.skillsRoot));
 }
 function listAllowedEntries(dirPath) {
     if (!fs_1.default.existsSync(dirPath)) {
@@ -235,7 +240,7 @@ function syncSkillMirrors(options) {
     const sources = loadCanonicalSources(options.root, options.config);
     const createRoots = Boolean(options.createRoots);
     const force = Boolean(options.force);
-    const targets = resolveMirrorTargets(options.root);
+    const targets = resolveMirrorTargets(options.root, options.config);
     let synced = 0;
     let pruned = 0;
     let touchedTargets = 0;
@@ -280,7 +285,7 @@ function preflightSkillMirrorTargets(options) {
     if (slugs.length === 0) {
         return;
     }
-    for (const target of resolveMirrorTargets(options.root)) {
+    for (const target of resolveMirrorTargets(options.root, options.config)) {
         if (!fs_1.default.existsSync(target.rootDir) && !fs_1.default.existsSync(target.skillsRoot)) {
             continue;
         }
@@ -293,18 +298,18 @@ function preflightSkillMirrorTargets(options) {
         }
     }
 }
-function shouldMaintainSkillMirrors(root) {
-    return shouldCreateMirrorRoots(root);
+function shouldMaintainSkillMirrors(root, config) {
+    return shouldCreateMirrorRoots(root, config);
 }
 function auditSkillMirrors(root, config) {
-    const shouldAudit = shouldCreateMirrorRoots(root);
+    const shouldAudit = shouldCreateMirrorRoots(root, config);
     if (!shouldAudit) {
         return [];
     }
     const warnings = [];
     const sources = loadCanonicalSources(root, config);
     const sourceBySlug = new Map(sources.map((source) => [source.slug, source]));
-    for (const target of resolveMirrorTargets(root)) {
+    for (const target of resolveMirrorTargets(root, config)) {
         if (!fs_1.default.existsSync(target.skillsRoot)) {
             warnings.push(`${path_1.default.relative(root, target.skillsRoot)}: mirror root missing; run \`mdkg skill sync\``);
             continue;
@@ -335,8 +340,8 @@ function auditSkillMirrors(root, config) {
     }
     return warnings;
 }
-function scaffoldMirrorRoots(root) {
-    for (const target of resolveMirrorTargets(root)) {
+function scaffoldMirrorRoots(root, config) {
+    for (const target of resolveMirrorTargets(root, config)) {
         fs_1.default.mkdirSync(target.skillsRoot, { recursive: true });
         if (!fs_1.default.existsSync(target.manifestPath)) {
             writeManifest(target, []);

package/dist/commands/skill_support.js

@@ -52,7 +52,7 @@ function registryTemplate() {
         "This directory stores Agent Skills packages used by mdkg tooling and orchestrators.",
         "",
         "Use `mdkg skill new <slug> \"<name>\" --description \"...\"` to scaffold a new skill from the built-in Anthropic-aligned template.",
-        "Use `mdkg skill sync` to mirror canonical skills into `.agents/skills/` and `.claude/skills/` when agent bootstrap is enabled.",
+        "Use `mdkg skill sync` to mirror canonical skills into configured `.mdkg/config.json` targets; defaults are `.agents/skills/` and `.claude/skills/`.",
         "Use `CLI_COMMAND_MATRIX.md` as the canonical command and flag reference when updating skill procedures.",
         "",
         "## Conventions",

package/dist/commands/upgrade.js

@@ -21,7 +21,7 @@ const init_manifest_1 = require("./init_manifest");
 const skill_support_1 = require("./skill_support");
 const skill_mirror_1 = require("./skill_mirror");
 const DEFAULT_SEED_SUBDIR = path_1.default.resolve(__dirname, "..", "init");
-const PROTECTED_CORE_DOCS = new Set([".mdkg/core/SOUL.md", ".mdkg/core/HUMAN.md"]);
+const PROTECTED_CORE_DOCS = new Set([".mdkg/core/SOUL.md", ".mdkg/core/COLLABORATION.md", ".mdkg/core/HUMAN.md"]);
 const CREATE_ONLY_PRESERVED = new Set([".mdkg/core/core.md"]);
 const LOCAL_STATE_IGNORE_ENTRIES = [
     ".mdkg/state/",
@@ -51,12 +51,11 @@ function requireSeedAssets(seedRoot) {
         }
     }
 }
-function isAgentWorkspace(root) {
+function isAgentWorkspace(root, config) {
     return [
         path_1.default.join(root, ".mdkg", "skills"),
-        path_1.default.join(root, ".agents", "skills"),
-        path_1.default.join(root, ".claude", "skills"),
         path_1.default.join(root, ".mdkg", "work", "events", "events.jsonl"),
+        ...(0, skill_mirror_1.configuredSkillMirrorTargets)(config).map((target) => path_1.default.join(root, target)),
     ].some((candidate) => fs_1.default.existsSync(candidate));
 }
 function copyFile(src, dest) {
@@ -157,15 +156,6 @@ function planSeedFile(options) {
         options.summary.unchanged += 1;
         return false;
     }
-    if (PROTECTED_CORE_DOCS.has(options.file.path)) {
-        record(options.summary, options.changes, {
-            path: options.file.path,
-            category: options.file.category,
-            action: "conflict",
-            reason: "protected core document exists; local content preserved",
-        });
-        return false;
-    }
     const known = options.knownHashes.get(options.file.path);
     if (known?.has(currentHash)) {
         record(options.summary, options.changes, {
@@ -180,6 +170,15 @@ function planSeedFile(options) {
         options.managedCurrentFiles.push(options.file);
         return true;
     }
+    if (PROTECTED_CORE_DOCS.has(options.file.path)) {
+        record(options.summary, options.changes, {
+            path: options.file.path,
+            category: options.file.category,
+            action: "conflict",
+            reason: "protected core document exists; local content preserved",
+        });
+        return false;
+    }
     record(options.summary, options.changes, {
         path: options.file.path,
         category: options.file.category,
@@ -253,14 +252,26 @@ function migrateProjectDbConfig(input) {
     };
     return { config: raw, changed: true };
 }
+function migrateCustomizationConfig(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        return { config: input, changed: false };
+    }
+    const raw = { ...input };
+    if (raw.customization !== undefined) {
+        return { config: raw, changed: false };
+    }
+    raw.customization = (0, config_1.defaultCustomizationConfig)();
+    return { config: raw, changed: true };
+}
 function migrateConfigIfNeeded(root, dryRun, summary, changes) {
     const cfgPath = (0, paths_1.configPath)(root);
     const raw = JSON.parse(fs_1.default.readFileSync(cfgPath, "utf8"));
     const migrated = (0, migrate_1.migrateConfig)(raw);
     const bundleConfig = migrateLegacyBundleImportsConfig(migrated.config);
     const nextConfig = migrateProjectDbConfig(bundleConfig.config);
-    (0, config_1.validateConfigSchema)(nextConfig.config);
-    if (migrated.from === migrated.to && !bundleConfig.changed && !nextConfig.changed) {
+    const customizationConfig = migrateCustomizationConfig(nextConfig.config);
+    (0, config_1.validateConfigSchema)(customizationConfig.config);
+    if (migrated.from === migrated.to && !bundleConfig.changed && !nextConfig.changed && !customizationConfig.changed) {
         summary.unchanged += 1;
         return;
     }
@@ -271,6 +282,9 @@ function migrateConfigIfNeeded(root, dryRun, summary, changes) {
     if (nextConfig.changed) {
         reasons.push("project db config defaults");
     }
+    if (customizationConfig.changed) {
+        reasons.push("customization overlay defaults");
+    }
     if (migrated.from !== migrated.to) {
         reasons.push(`schema_version ${migrated.from} -> ${migrated.to}`);
     }
@@ -281,9 +295,32 @@ function migrateConfigIfNeeded(root, dryRun, summary, changes) {
         reason: reasons.join(" and "),
     });
     if (!dryRun) {
-        writeFile(cfgPath, `${JSON.stringify(nextConfig.config, null, 2)}\n`);
+        writeFile(cfgPath, `${JSON.stringify(customizationConfig.config, null, 2)}\n`);
     }
 }
+function sameStringArray(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function hasOperatorCustomization(customization) {
+    const defaults = (0, config_1.defaultCustomizationConfig)();
+    return (customization.standards.profile !== defaults.standards.profile ||
+        customization.standards.refs.length > 0 ||
+        customization.core_docs.custom_paths.length > 0 ||
+        !sameStringArray(customization.skill_mirrors.targets, defaults.skill_mirrors.targets));
+}
+function reportPreservedCustomizationOverlay(root, summary, changes) {
+    const config = (0, config_1.validateConfigSchema)((0, migrate_1.migrateConfig)(JSON.parse(fs_1.default.readFileSync((0, paths_1.configPath)(root), "utf8"))).config);
+    if (!hasOperatorCustomization(config.customization)) {
+        summary.unchanged += 1;
+        return;
+    }
+    record(summary, changes, {
+        path: ".mdkg/config.json",
+        category: "customization_overlay",
+        action: "skip",
+        reason: "operator customization overlay is preserved; upgrade does not replace organization standards, custom core docs, or configured skill mirror targets",
+    });
+}
 function migrateClosedGoalActiveNodes(root, dryRun, summary, changes) {
     const config = (0, config_1.validateConfigSchema)((0, migrate_1.migrateConfig)(JSON.parse(fs_1.default.readFileSync((0, paths_1.configPath)(root), "utf8"))).config);
     const filesByAlias = (0, workspace_files_1.listWorkspaceDocFilesByAlias)(root, config);
@@ -503,12 +540,15 @@ function buildApplySideEffects(options) {
             category: "skill_registry",
             action: "update",
             reason: "refreshes canonical skill registry after apply",
-        }, {
-            path: ".agents/skills,.claude/skills",
-            category: "skill_mirror",
-            action: "sync",
-            reason: "syncs managed skill mirrors after apply",
         });
+        if (options.mirrorTargets.length > 0) {
+            effects.push({
+                path: options.mirrorTargets.join(","),
+                category: "skill_mirror",
+                action: "sync",
+                reason: "syncs configured managed skill mirrors after apply",
+            });
+        }
     }
     return effects;
 }
@@ -560,9 +600,11 @@ function runUpgradeCommand(options) {
     const knownHashes = buildKnownHashes([existingManifest, ...legacyManifests]);
     const summary = createSummary();
     const changes = [];
-    const agentWorkspace = isAgentWorkspace(root);
+    const initialConfig = (0, config_1.validateConfigSchema)((0, migrate_1.migrateConfig)(JSON.parse(fs_1.default.readFileSync((0, paths_1.configPath)(root), "utf8"))).config);
+    const agentWorkspace = isAgentWorkspace(root, initialConfig);
     const managedCurrentFiles = [];
     migrateConfigIfNeeded(root, dryRun, summary, changes);
+    reportPreservedCustomizationOverlay(root, summary, changes);
     migrateClosedGoalActiveNodes(root, dryRun, summary, changes);
     migrateLegacySpecManifests(root, dryRun, summary, changes);
     for (const file of currentManifest.files) {
@@ -587,6 +629,7 @@ function runUpgradeCommand(options) {
     const applySideEffects = buildApplySideEffects({
         existingManifest,
         agentWorkspace,
+        mirrorTargets: (0, skill_mirror_1.configuredSkillMirrorTargets)(initialConfig),
         changes,
     });
     for (const effect of applySideEffects) {
@@ -603,11 +646,11 @@ function runUpgradeCommand(options) {
         if (agentWorkspace && applySideEffects.length > 0) {
             const config = (0, config_1.validateConfigSchema)((0, migrate_1.migrateConfig)(JSON.parse(fs_1.default.readFileSync((0, paths_1.configPath)(root), "utf8"))).config);
             (0, skill_support_1.refreshSkillsRegistry)(root, config);
-            (0, skill_mirror_1.scaffoldMirrorRoots)(root);
+            (0, skill_mirror_1.scaffoldMirrorRoots)(root, config);
             (0, skill_mirror_1.syncSkillMirrors)({ root, config, createRoots: true });
         }
     }
-    const preservedCustomizations = changes.filter((change) => change.action === "conflict");
+    const preservedCustomizations = changes.filter((change) => change.action === "conflict" || change.category === "customization_overlay");
     const blockingConflicts = changes.filter((change) => change.action === "conflict" && change.category === "manifest_migration");
     const willWritePaths = changes.filter(isWritableChange).map(writablePathForChange);
     const receipt = {