mdkg 0.0.9 → 0.1.0

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to mdkg are documented here.
 
 This project follows a pragmatic changelog style inspired by Keep a Changelog. Versions use npm package versions.
 
+## 0.1.0 - 2026-05-12
+
+### Added
+
+- Added conservative `mdkg upgrade` for existing workspaces.
+- Added `.mdkg/init-manifest.json` ownership tracking for managed init assets.
+- Added v0.0.9 seed fingerprints so clean older workspaces can safely adopt current init docs, templates, and default skills.
+- Added `npm run smoke:upgrade` for packed-package upgrade verification in temporary workspaces.
+
+### Changed
+
+- `mdkg upgrade` defaults to dry-run; `mdkg upgrade --apply` is the only mutating upgrade path.
+- Agent-enabled workspaces can receive safe managed default skill upgrades and mirror refreshes during upgrade.
+- Publish readiness now checks packaged init manifests and runs upgrade smoke before publish.
+
 ## 0.0.9 - 2026-05-12
 
 ### Added

package/README.md

@@ -13,7 +13,7 @@ mdkg stays deliberately boring:
 - zero runtime dependencies
 - no sqlite, daemon, hosted index, or vector DB
 
-Current package version in source: `0.0.9`
+Current package version in source: `0.1.0`
 
 ## The product shape
 
@@ -57,6 +57,21 @@ mdkg init --agent
 
 This adds strict-node `SOUL.md` / `HUMAN.md`, seeds the three default mdkg usage skills, creates `events.jsonl`, updates the skill registry, adds core pin updates, and creates mirrored skill folders under `.agents/skills/` and `.claude/skills/`.
 
+Preview safe scaffold upgrades in an existing mdkg workspace:
+
+```bash
+mdkg upgrade
+mdkg upgrade --json
+```
+
+Apply only after reviewing the receipt:
+
+```bash
+mdkg upgrade --apply
+```
+
+Upgrade is intentionally conservative. It creates missing managed startup docs and updates unchanged mdkg seed assets, but preserves customized docs, templates, skills, and core files as reported conflicts. Agent-enabled workspaces also get safe default skill upgrades and skill mirror refreshes; non-agent workspaces do not gain skills, events, or mirrors implicitly.
+
 Create a task:
 
 ```bash
@@ -142,6 +157,7 @@ mdkg lives under a hidden root directory:
 
 These are the commands new users and agents should learn first:
 - `mdkg init`
+- `mdkg upgrade`
 - `mdkg new`
 - `mdkg search`
 - `mdkg show`
@@ -204,7 +220,7 @@ This repo now dogfoods three internal skills:
 - `build-pack-and-execute-task`
 - `verify-close-and-checkpoint`
 
-Optional skill metadata with prefixes such as `ochatr_*` is treated as vendor extension data. Structured skill output exposes it under `extensions.ochatr` while keeping the top-level `ochatr` field as a 0.0.9 compatibility alias. ochatr.ai is a pioneering adopter of this extension pattern, not the name of the base mdkg standard.
+Optional skill metadata with prefixes such as `ochatr_*` is treated as vendor extension data. Structured skill output exposes it under `extensions.ochatr` while keeping the top-level `ochatr` field as a compatibility alias introduced in 0.0.9. ochatr.ai is a pioneering adopter of this extension pattern, not the name of the base mdkg standard.
 
 ## Agent workflow files
 

package/dist/cli.js

@@ -22,6 +22,7 @@ const checkpoint_1 = require("./commands/checkpoint");
 const init_1 = require("./commands/init");
 const new_1 = require("./commands/new");
 const guide_1 = require("./commands/guide");
+const upgrade_1 = require("./commands/upgrade");
 const event_1 = require("./commands/event");
 const skill_1 = require("./commands/skill");
 const task_1 = require("./commands/task");
@@ -47,6 +48,7 @@ function printUsage(log) {
     log("  mdkg <command> [options]");
     log("\nPrimary commands:");
     log("  init        Initialize .mdkg scaffolding");
+    log("  upgrade     Conservatively upgrade mdkg scaffolding");
     log("  new         Create a node from templates");
     log("  show        Show a node by id or qid");
     log("  list        List nodes with filters");
@@ -66,6 +68,8 @@ function printUsage(log) {
     log("  workspace   Manage workspaces (ls/add/rm/enable/disable)");
     log("\nQuickstart:");
     log("  mdkg init --llm");
+    log("  mdkg upgrade");
+    log("  mdkg upgrade --apply");
     log('  mdkg new task "..." --status todo --priority 1');
     log('  mdkg search "..."');
     log("  mdkg show <id>");
@@ -95,6 +99,19 @@ function printInitHelp(log) {
     log("\nCompatibility flags still supported but not shown in the primary onboarding story.");
     printGlobalOptions(log);
 }
+function printUpgradeHelp(log) {
+    log("Usage:");
+    log("  mdkg upgrade [--dry-run] [--apply] [--json]");
+    log("\nOptions:");
+    log("  --dry-run             Preview upgrade changes without writing files (default)");
+    log("  --apply               Apply safe managed init asset upgrades");
+    log("  --json                Emit machine-readable upgrade receipt");
+    log("\nNotes:");
+    log("  - preserves customized docs, templates, skills, and core files");
+    log("  - upgrades default mdkg skills only when they match managed seed fingerprints");
+    log("  - run without flags first, then rerun with --apply when the receipt looks right");
+    printGlobalOptions(log);
+}
 function printNewHelp(log) {
     log("Usage:");
     log('  mdkg new <type> "<title>" [options] [--json]');
@@ -371,6 +388,9 @@ function printCommandHelp(log, command, subcommand) {
         case "init":
             printInitHelp(log);
             return;
+        case "upgrade":
+            printUpgradeHelp(log);
+            return;
         case "guide":
             printGuideHelp(log);
             return;
@@ -909,6 +929,19 @@ function runCommand(parsed, root, runtime) {
             });
             return 0;
         }
+        case "upgrade": {
+            if (parsed.positionals.length > 1) {
+                throw new errors_1.UsageError("upgrade does not accept positional arguments");
+            }
+            const dryRun = parseBooleanFlag("--dry-run", parsed.flags["--dry-run"]);
+            const apply = parseBooleanFlag("--apply", parsed.flags["--apply"]);
+            if (dryRun && apply) {
+                throw new errors_1.UsageError("choose either --dry-run or --apply, not both");
+            }
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, upgrade_1.runUpgradeCommand)({ root, dryRun, apply, json });
+            return 0;
+        }
         case "guide":
             (0, guide_1.runGuideCommand)({ root });
             return 0;

package/dist/commands/init.js

@@ -9,6 +9,8 @@ const path_1 = __importDefault(require("path"));
 const config_1 = require("../core/config");
 const errors_1 = require("../util/errors");
 const date_1 = require("../util/date");
+const version_1 = require("../core/version");
+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");
@@ -236,6 +238,7 @@ function runInitCommand(options) {
     const seedCliMatrix = path_1.default.join(seedRoot, "CLI_COMMAND_MATRIX.md");
     const seedReadme = path_1.default.join(seedRoot, "README.md");
     const seedDefaultSkills = path_1.default.join(seedRoot, "skills", "default");
+    const seedManifest = (0, init_manifest_1.createInitManifest)(seedRoot, (0, version_1.readPackageVersion)());
     if (!fs_1.default.existsSync(seedConfig) || !fs_1.default.existsSync(seedCore) || !fs_1.default.existsSync(seedTemplates)) {
         throw new errors_1.NotFoundError(`init assets not found at ${seedRoot} (try reinstalling mdkg)`);
     }
@@ -304,6 +307,7 @@ function runInitCommand(options) {
         (0, skill_support_1.refreshSkillsRegistry)(root, config);
         (0, skill_mirror_1.syncSkillMirrors)({ root, config, createRoots: true, force });
     }
+    (0, init_manifest_1.writeInitManifest)(path_1.default.join(mdkgDir, init_manifest_1.INIT_MANIFEST_FILE), seedManifest);
     const noUpdateIgnores = Boolean(options.noUpdateIgnores);
     const shouldUpdateGitignore = Boolean(options.updateGitignore || !noUpdateIgnores);
     const shouldUpdateNpmignore = Boolean(options.updateNpmignore || !noUpdateIgnores);

package/dist/commands/init_manifest.js

@@ -0,0 +1,131 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INIT_MANIFEST_SCHEMA_VERSION = exports.INIT_MANIFEST_FILE = void 0;
+exports.sha256File = sha256File;
+exports.seedSourcePath = seedSourcePath;
+exports.createInitManifest = createInitManifest;
+exports.writeInitManifest = writeInitManifest;
+exports.readInitManifest = readInitManifest;
+exports.loadLegacyInitManifests = loadLegacyInitManifests;
+const crypto_1 = __importDefault(require("crypto"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+exports.INIT_MANIFEST_FILE = "init-manifest.json";
+exports.INIT_MANIFEST_SCHEMA_VERSION = 1;
+const STARTUP_DOCS = ["llms.txt", "AGENT_START.md", "CLI_COMMAND_MATRIX.md"];
+const AGENT_DOCS = ["AGENTS.md", "CLAUDE.md"];
+function toPosixPath(value) {
+    return value.split(path_1.default.sep).join("/");
+}
+function sha256Buffer(value) {
+    return crypto_1.default.createHash("sha256").update(value).digest("hex");
+}
+function sha256File(filePath) {
+    return sha256Buffer(fs_1.default.readFileSync(filePath));
+}
+function listFiles(dirPath) {
+    if (!fs_1.default.existsSync(dirPath)) {
+        return [];
+    }
+    const files = [];
+    const entries = fs_1.default.readdirSync(dirPath, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+        const fullPath = path_1.default.join(dirPath, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...listFiles(fullPath));
+        }
+        else if (entry.isFile()) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+function addSeedFile(files, seedRoot, seedRelativePath, targetPath, category) {
+    const sourcePath = path_1.default.join(seedRoot, seedRelativePath);
+    if (!fs_1.default.existsSync(sourcePath) || !fs_1.default.statSync(sourcePath).isFile()) {
+        return;
+    }
+    files.push({
+        path: toPosixPath(targetPath),
+        category,
+        sha256: sha256File(sourcePath),
+    });
+}
+function addSeedDir(files, seedRoot, seedRelativeDir, targetDir, category) {
+    const sourceDir = path_1.default.join(seedRoot, seedRelativeDir);
+    for (const sourcePath of listFiles(sourceDir)) {
+        const relPath = toPosixPath(path_1.default.relative(sourceDir, sourcePath));
+        files.push({
+            path: path_1.default.posix.join(targetDir, relPath),
+            category,
+            sha256: sha256File(sourcePath),
+        });
+    }
+}
+function seedSourcePath(seedRoot, file) {
+    if (file.path === ".mdkg/config.json") {
+        return path_1.default.join(seedRoot, "config.json");
+    }
+    if (file.path === ".mdkg/README.md") {
+        return path_1.default.join(seedRoot, "README.md");
+    }
+    if (file.path.startsWith(".mdkg/core/")) {
+        return path_1.default.join(seedRoot, "core", file.path.slice(".mdkg/core/".length));
+    }
+    if (file.path.startsWith(".mdkg/templates/")) {
+        return path_1.default.join(seedRoot, "templates", file.path.slice(".mdkg/templates/".length));
+    }
+    if (file.path.startsWith(".mdkg/skills/")) {
+        return path_1.default.join(seedRoot, "skills", "default", file.path.slice(".mdkg/skills/".length));
+    }
+    return path_1.default.join(seedRoot, file.path);
+}
+function createInitManifest(seedRoot, mdkgVersion) {
+    const files = [];
+    addSeedFile(files, seedRoot, "config.json", ".mdkg/config.json", "config");
+    addSeedFile(files, seedRoot, "README.md", ".mdkg/README.md", "mdkg_doc");
+    addSeedDir(files, seedRoot, "core", ".mdkg/core", "core");
+    addSeedDir(files, seedRoot, "templates", ".mdkg/templates", "template");
+    for (const doc of AGENT_DOCS) {
+        addSeedFile(files, seedRoot, doc, doc, "agent_doc");
+    }
+    for (const doc of STARTUP_DOCS) {
+        addSeedFile(files, seedRoot, doc, doc, "startup_doc");
+    }
+    addSeedDir(files, seedRoot, path_1.default.join("skills", "default"), ".mdkg/skills", "default_skill");
+    return {
+        schema_version: exports.INIT_MANIFEST_SCHEMA_VERSION,
+        tool: "mdkg",
+        mdkg_version: mdkgVersion,
+        files: files.sort((a, b) => a.path.localeCompare(b.path)),
+    };
+}
+function writeInitManifest(filePath, manifest) {
+    fs_1.default.mkdirSync(path_1.default.dirname(filePath), { recursive: true });
+    fs_1.default.writeFileSync(filePath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+function readInitManifest(filePath) {
+    if (!fs_1.default.existsSync(filePath)) {
+        return undefined;
+    }
+    const parsed = JSON.parse(fs_1.default.readFileSync(filePath, "utf8"));
+    if (parsed.schema_version !== exports.INIT_MANIFEST_SCHEMA_VERSION || parsed.tool !== "mdkg" || !Array.isArray(parsed.files)) {
+        throw new Error(`${filePath}: invalid mdkg init manifest`);
+    }
+    return parsed;
+}
+function loadLegacyInitManifests(seedRoot) {
+    const legacyDir = path_1.default.join(seedRoot, "legacy");
+    if (!fs_1.default.existsSync(legacyDir)) {
+        return [];
+    }
+    return fs_1.default
+        .readdirSync(legacyDir, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((entry) => readInitManifest(path_1.default.join(legacyDir, entry.name)))
+        .filter((manifest) => manifest !== undefined);
+}

package/dist/commands/upgrade.js

@@ -0,0 +1,286 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runUpgradeCommand = runUpgradeCommand;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const migrate_1 = require("../core/migrate");
+const config_1 = require("../core/config");
+const paths_1 = require("../core/paths");
+const version_1 = require("../core/version");
+const errors_1 = require("../util/errors");
+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 CREATE_ONLY_PRESERVED = new Set([".mdkg/core/core.md"]);
+function seededInitEvent(nowIso) {
+    const event = {
+        ts: nowIso,
+        run_id: `upgrade-${nowIso.replace(/[^0-9]/g, "").slice(0, 14)}`,
+        workspace: "root",
+        agent: "mdkg",
+        kind: "RUN_STARTED",
+        status: "ok",
+        refs: ["edd-4"],
+        artifacts: [],
+        notes: "upgrade ensured agent event log",
+        redacted: true,
+    };
+    return `${JSON.stringify(event)}\n`;
+}
+function requireSeedAssets(seedRoot) {
+    for (const required of ["config.json", "README.md", "core", "templates"]) {
+        if (!fs_1.default.existsSync(path_1.default.join(seedRoot, required))) {
+            throw new errors_1.NotFoundError(`upgrade assets missing ${required} at ${seedRoot} (try reinstalling mdkg)`);
+        }
+    }
+}
+function isAgentWorkspace(root) {
+    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"),
+    ].some((candidate) => fs_1.default.existsSync(candidate));
+}
+function copyFile(src, dest) {
+    fs_1.default.mkdirSync(path_1.default.dirname(dest), { recursive: true });
+    fs_1.default.copyFileSync(src, dest);
+}
+function writeFile(filePath, content) {
+    fs_1.default.mkdirSync(path_1.default.dirname(filePath), { recursive: true });
+    fs_1.default.writeFileSync(filePath, content, "utf8");
+}
+function createSummary() {
+    return {
+        created: 0,
+        updated: 0,
+        migrated: 0,
+        synced: 0,
+        skipped: 0,
+        conflicted: 0,
+        unchanged: 0,
+    };
+}
+function record(summary, changes, change) {
+    changes.push(change);
+    switch (change.action) {
+        case "create":
+            summary.created += 1;
+            break;
+        case "update":
+            summary.updated += 1;
+            break;
+        case "migrate":
+            summary.migrated += 1;
+            break;
+        case "sync":
+            summary.synced += 1;
+            break;
+        case "conflict":
+            summary.skipped += 1;
+            summary.conflicted += 1;
+            break;
+    }
+}
+function buildKnownHashes(manifests) {
+    const hashes = new Map();
+    for (const manifest of manifests) {
+        if (!manifest) {
+            continue;
+        }
+        for (const file of manifest.files) {
+            if (!hashes.has(file.path)) {
+                hashes.set(file.path, new Set());
+            }
+            hashes.get(file.path)?.add(file.sha256);
+        }
+    }
+    return hashes;
+}
+function shouldIncludeFile(file, agentWorkspace) {
+    if (file.category === "default_skill") {
+        return agentWorkspace;
+    }
+    return file.category !== "config";
+}
+function planSeedFile(options) {
+    const destPath = path_1.default.join(options.root, options.file.path);
+    const srcPath = (0, init_manifest_1.seedSourcePath)(options.seedRoot, options.file);
+    const currentHash = fs_1.default.existsSync(destPath) && fs_1.default.statSync(destPath).isFile() ? (0, init_manifest_1.sha256File)(destPath) : undefined;
+    const nextHash = options.file.sha256;
+    if (!currentHash) {
+        record(options.summary, options.changes, {
+            path: options.file.path,
+            category: options.file.category,
+            action: "create",
+            reason: "missing managed init asset",
+        });
+        if (!options.dryRun) {
+            copyFile(srcPath, destPath);
+        }
+        options.managedCurrentFiles.push(options.file);
+        return true;
+    }
+    if (currentHash === nextHash) {
+        options.summary.unchanged += 1;
+        options.managedCurrentFiles.push(options.file);
+        return false;
+    }
+    if (CREATE_ONLY_PRESERVED.has(options.file.path)) {
+        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, {
+            path: options.file.path,
+            category: options.file.category,
+            action: "update",
+            reason: "matches a managed seed hash",
+        });
+        if (!options.dryRun) {
+            copyFile(srcPath, destPath);
+        }
+        options.managedCurrentFiles.push(options.file);
+        return true;
+    }
+    record(options.summary, options.changes, {
+        path: options.file.path,
+        category: options.file.category,
+        action: "conflict",
+        reason: "local changes detected; content preserved",
+    });
+    return false;
+}
+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);
+    (0, config_1.validateConfigSchema)(migrated.config);
+    if (migrated.from === migrated.to) {
+        summary.unchanged += 1;
+        return;
+    }
+    record(summary, changes, {
+        path: ".mdkg/config.json",
+        category: "config",
+        action: "migrate",
+        reason: `config schema_version ${migrated.from} -> ${migrated.to}`,
+    });
+    if (!dryRun) {
+        writeFile(cfgPath, `${JSON.stringify(migrated.config, null, 2)}\n`);
+    }
+}
+function ensureAgentRuntimeFiles(root, dryRun, summary, changes) {
+    const eventsPath = path_1.default.join(root, ".mdkg", "work", "events", "events.jsonl");
+    if (!fs_1.default.existsSync(eventsPath)) {
+        record(summary, changes, {
+            path: ".mdkg/work/events/events.jsonl",
+            category: "event_log",
+            action: "create",
+            reason: "agent workspace is missing event log",
+        });
+        if (!dryRun) {
+            writeFile(eventsPath, seededInitEvent(new Date().toISOString()));
+        }
+    }
+    else {
+        summary.unchanged += 1;
+    }
+}
+function emitHumanReceipt(receipt) {
+    const mode = receipt.dry_run ? "dry-run" : "apply";
+    console.log(`mdkg upgrade ${mode}: ${receipt.summary.created} create, ${receipt.summary.updated} update, ${receipt.summary.migrated} migrate, ${receipt.summary.synced} sync, ${receipt.summary.conflicted} conflict`);
+    if (receipt.changes.length === 0) {
+        console.log("no upgrade changes pending");
+    }
+    else {
+        for (const change of receipt.changes) {
+            console.log(`  ${change.action}: ${change.path} (${change.reason})`);
+        }
+    }
+    if (receipt.dry_run && receipt.changes.some((change) => change.action !== "conflict")) {
+        console.log("next: mdkg upgrade --apply");
+    }
+}
+function runUpgradeCommand(options) {
+    const root = path_1.default.resolve(options.root);
+    const seedRoot = options.seedRoot ? path_1.default.resolve(options.seedRoot) : DEFAULT_SEED_SUBDIR;
+    const dryRun = !options.apply;
+    const version = (0, version_1.readPackageVersion)();
+    requireSeedAssets(seedRoot);
+    const currentManifest = (0, init_manifest_1.createInitManifest)(seedRoot, version);
+    const existingManifest = (0, init_manifest_1.readInitManifest)(path_1.default.join(root, ".mdkg", init_manifest_1.INIT_MANIFEST_FILE));
+    const legacyManifests = (0, init_manifest_1.loadLegacyInitManifests)(seedRoot);
+    const knownHashes = buildKnownHashes([existingManifest, ...legacyManifests]);
+    const summary = createSummary();
+    const changes = [];
+    const agentWorkspace = isAgentWorkspace(root);
+    const managedCurrentFiles = [];
+    migrateConfigIfNeeded(root, dryRun, summary, changes);
+    for (const file of currentManifest.files) {
+        if (!shouldIncludeFile(file, agentWorkspace)) {
+            continue;
+        }
+        planSeedFile({
+            root,
+            seedRoot,
+            file,
+            knownHashes,
+            dryRun,
+            summary,
+            changes,
+            managedCurrentFiles,
+        });
+    }
+    if (agentWorkspace) {
+        ensureAgentRuntimeFiles(root, dryRun, summary, changes);
+    }
+    if (!dryRun) {
+        const appliedManifest = {
+            ...currentManifest,
+            files: managedCurrentFiles.sort((a, b) => a.path.localeCompare(b.path)),
+        };
+        (0, init_manifest_1.writeInitManifest)(path_1.default.join(root, ".mdkg", init_manifest_1.INIT_MANIFEST_FILE), appliedManifest);
+        if (agentWorkspace) {
+            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);
+            const result = (0, skill_mirror_1.syncSkillMirrors)({ root, config, createRoots: true });
+            record(summary, changes, {
+                path: ".agents/skills,.claude/skills",
+                category: "skill_mirror",
+                action: "sync",
+                reason: `${result.synced} mirrored skill(s), ${result.pruned} stale mirror(s) pruned`,
+            });
+        }
+    }
+    const receipt = {
+        action: "upgrade",
+        dry_run: dryRun,
+        version,
+        summary,
+        changes,
+    };
+    if (options.json) {
+        console.log(`${JSON.stringify(receipt, null, 2)}`);
+    }
+    else {
+        emitHumanReceipt(receipt);
+    }
+    return receipt;
+}

package/dist/core/version.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readPackageVersion = readPackageVersion;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function readPackageVersion(startDir = __dirname) {
+    let current = path_1.default.resolve(startDir);
+    for (let i = 0; i < 5; i += 1) {
+        const packagePath = path_1.default.join(current, "package.json");
+        if (fs_1.default.existsSync(packagePath)) {
+            try {
+                const raw = JSON.parse(fs_1.default.readFileSync(packagePath, "utf8"));
+                if (raw.name === "mdkg" && typeof raw.version === "string" && raw.version.trim().length > 0) {
+                    return raw.version;
+                }
+            }
+            catch {
+                return "unknown";
+            }
+        }
+        const parent = path_1.default.dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return "unknown";
+}

package/dist/init/AGENT_START.md

@@ -23,6 +23,7 @@ Agent operating prompt:
 - Use `mdkg search "..."` and `mdkg next` to discover current work.
 - Use `mdkg skill list`, `mdkg skill search`, and `mdkg skill show <slug>` for skill discovery.
 - Use `mdkg task start/update/done` for structured task, bug, and test lifecycle fields.
+- Use `mdkg upgrade` to preview scaffold updates; only run `mdkg upgrade --apply` after reviewing the receipt.
 - Keep nuanced summaries, body text, and manual parent closeout edits in markdown.
 - Use `mdkg event enable` only if `events.jsonl` is missing and provenance should be restored.
 - Use `CLI_COMMAND_MATRIX.md` for the canonical command and flag surface.

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -8,6 +8,7 @@ Verify live help with:
 
 Primary commands:
 - `mdkg init`
+- `mdkg upgrade [--dry-run] [--apply] [--json]`
 - `mdkg new`
 - `mdkg show`
 - `mdkg list`
@@ -64,6 +65,11 @@ Agent bootstrap:
 - `mdkg init --llm --agent`
 - published bootstrap config is root-only by default
 
+Upgrade:
+- `mdkg upgrade` previews safe scaffold updates and writes nothing by default
+- `mdkg upgrade --apply` updates only managed or unchanged init assets
+- customized docs, templates, skills, and core files are preserved and reported
+
 Skill discovery:
 - `mdkg skill list --tags stage:plan --json`
 - `mdkg skill search "<query>" --json`

package/dist/init/README.md

@@ -15,6 +15,7 @@ This repository is initialized for mdkg.
 
 ```bash
 mdkg init --llm --agent
+mdkg upgrade
 mdkg search "..."
 mdkg show <id>
 mdkg pack <id>
@@ -50,3 +51,9 @@ Recommended:
 ```bash
 mdkg init --update-gitignore --update-npmignore
 ```
+
+## Upgrade
+
+`mdkg upgrade` previews safe scaffold updates for existing workspaces and writes nothing by default.
+
+Use `mdkg upgrade --apply` only after reviewing the receipt. Local customizations are preserved and reported instead of overwritten.

package/dist/init/init-manifest.json

@@ -0,0 +1,197 @@
+{
+  "schema_version": 1,
+  "tool": "mdkg",
+  "mdkg_version": "0.1.0",
+  "files": [
+    {
+      "path": ".mdkg/config.json",
+      "category": "config",
+      "sha256": "eb76bf22ae9d04601c2fedac5fd22838797dd2cc829324638a6b69222d40aaa9"
+    },
+    {
+      "path": ".mdkg/core/core.md",
+      "category": "core",
+      "sha256": "d87beecf4229535c0d0feea7deae28b97d0681105a1c282d9961e97918f0bbe8"
+    },
+    {
+      "path": ".mdkg/core/guide.md",
+      "category": "core",
+      "sha256": "0b0ba51fbc393b3d5e0a0df4dece6aa822b77ab0f4ee3814b2cdba77ef8b65d9"
+    },
+    {
+      "path": ".mdkg/core/HUMAN.md",
+      "category": "core",
+      "sha256": "75d2e015cd5ba61062cb84246017ee4f4221610d4a56e4a0b332271b90694965"
+    },
+    {
+      "path": ".mdkg/core/rule-1-mdkg-conventions.md",
+      "category": "core",
+      "sha256": "20073cd21c148f1b93a382550f835ccb2e896cc676903328557004319235c112"
+    },
+    {
+      "path": ".mdkg/core/rule-2-context-pack-rules.md",
+      "category": "core",
+      "sha256": "9dfd46b5ae791220c68304abc0784399509cf606821c937671cf63d6e9a8ce8f"
+    },
+    {
+      "path": ".mdkg/core/rule-3-cli-contract.md",
+      "category": "core",
+      "sha256": "b547a6edc20112013c607a033af4ac0c6bb3f9d66d445b0c545b2890a721b671"
+    },
+    {
+      "path": ".mdkg/core/rule-4-repo-safety-and-ignores.md",
+      "category": "core",
+      "sha256": "d7fc4bfa3727ed7d5353eeb0089ad818b96a755578e217251106422559750291"
+    },
+    {
+      "path": ".mdkg/core/rule-5-release-and-versioning.md",
+      "category": "core",
+      "sha256": "4fc6648052f80b90b2efc173e3bcab16cb0bc6680bb8b04f76c66fff06ad19cd"
+    },
+    {
+      "path": ".mdkg/core/rule-6-templates-and-schemas.md",
+      "category": "core",
+      "sha256": "0d6da477c12e3492f43c571a6e4daa373bf05005ef703ad5166b7c8786e553b0"
+    },
+    {
+      "path": ".mdkg/core/SOUL.md",
+      "category": "core",
+      "sha256": "2bfdd4d1a65dd18c14d3e8469d0d5c74c6cc7c067f0b56d227532b7ab620795a"
+    },
+    {
+      "path": ".mdkg/README.md",
+      "category": "mdkg_doc",
+      "sha256": "26e99be382b48682b7841f14404576f79bf6876b64a90aefa6c99c2440701d2a"
+    },
+    {
+      "path": ".mdkg/skills/build-pack-and-execute-task/SKILL.md",
+      "category": "default_skill",
+      "sha256": "7f6104980e6b2ec0749881c6be2bd3d7982702259c4979763266d1c800aeb410"
+    },
+    {
+      "path": ".mdkg/skills/select-work-and-ground-context/SKILL.md",
+      "category": "default_skill",
+      "sha256": "c8c04134532deda079f9ee290a66b2423892f9789fa946e44db4c89c05b8e1bf"
+    },
+    {
+      "path": ".mdkg/skills/verify-close-and-checkpoint/SKILL.md",
+      "category": "default_skill",
+      "sha256": "98a1b02927854201eeea73e3d7c9f5a104fab7a5c72e033ea261995341a8a7ce"
+    },
+    {
+      "path": ".mdkg/templates/default/bug.md",
+      "category": "template",
+      "sha256": "88e3f8d67aa3b2156be2006bd1c8139b7b16b46f2c05a4f4d840b3746a40f9c5"
+    },
+    {
+      "path": ".mdkg/templates/default/chk.md",
+      "category": "template",
+      "sha256": "15f793e422009c76f8bda72c3609157acd7f03762d9c9bdb096c4aa2e2c3fb89"
+    },
+    {
+      "path": ".mdkg/templates/default/dec.md",
+      "category": "template",
+      "sha256": "a2f7098fea538c153ac290f2e2edb2e755ca9dd07d17c2a127fb23959517ece9"
+    },
+    {
+      "path": ".mdkg/templates/default/dispute.md",
+      "category": "template",
+      "sha256": "b1c5330fd4a1e3f03dbb4ac8907bd728e55537e053dcf43ebcbdc835ff1d0579"
+    },
+    {
+      "path": ".mdkg/templates/default/edd.md",
+      "category": "template",
+      "sha256": "44828719927cfd31389b9d55b57fc4fa9bc640f3e2475baefe585e4043740f5e"
+    },
+    {
+      "path": ".mdkg/templates/default/epic.md",
+      "category": "template",
+      "sha256": "56697b69af027fe08c00866c0c0670f7d7e2a0857803bd4aabb99f4761311879"
+    },
+    {
+      "path": ".mdkg/templates/default/feat.md",
+      "category": "template",
+      "sha256": "99cfdd97b40b119cf899fd766d816c07b7daaafd8ec8e70e6c6de5c0d37f581c"
+    },
+    {
+      "path": ".mdkg/templates/default/feedback.md",
+      "category": "template",
+      "sha256": "61ad7b8b717d17736ba505f814fa6e4f9ec61f7fe4ae6622359304620a99d649"
+    },
+    {
+      "path": ".mdkg/templates/default/prd.md",
+      "category": "template",
+      "sha256": "afee167576a4f881ab191867e118864b7b5629e14b9c4a61359c8fbd7ececeee"
+    },
+    {
+      "path": ".mdkg/templates/default/prop.md",
+      "category": "template",
+      "sha256": "839b976a8ddc0d6abddfbe6114dfb87f64471958ae807c011538777b758aa1f0"
+    },
+    {
+      "path": ".mdkg/templates/default/proposal.md",
+      "category": "template",
+      "sha256": "16bfa81b6e665064e93e0d1b625dccc518b9885f87a32a15e5ba5441c2c27ea8"
+    },
+    {
+      "path": ".mdkg/templates/default/receipt.md",
+      "category": "template",
+      "sha256": "aac6e6e27153a1ca85a515b03f0ac55db3eb0df3f9243c42f0b936f5e5a750b2"
+    },
+    {
+      "path": ".mdkg/templates/default/rule.md",
+      "category": "template",
+      "sha256": "6321abf72af61a6513d7bfaa2d3122b2aa3bd2b95b662a52d569fb2bf819fda1"
+    },
+    {
+      "path": ".mdkg/templates/default/spec.md",
+      "category": "template",
+      "sha256": "e3e05d8d627c478d2757451f61b5a8fda8a75da9885a9261b2f8f5cb8a3a36dc"
+    },
+    {
+      "path": ".mdkg/templates/default/task.md",
+      "category": "template",
+      "sha256": "f6385dd4f56f1c8df164ac3e79d82c5a3fde3f952dc9cdc78c0b8077caa62277"
+    },
+    {
+      "path": ".mdkg/templates/default/test.md",
+      "category": "template",
+      "sha256": "bdae53e5cb4bd77712da155bbcfc24409ced8162c977e6bc478a9d1e695ddef7"
+    },
+    {
+      "path": ".mdkg/templates/default/work_order.md",
+      "category": "template",
+      "sha256": "bdbdf6e34d59976a675dd1d25002dfc0ef49e725647c97a9e0b3552c93fb8600"
+    },
+    {
+      "path": ".mdkg/templates/default/work.md",
+      "category": "template",
+      "sha256": "651b7339f6e23c8745264f3f6641a0c82fcd765247f0a70a9f407a118a49ec00"
+    },
+    {
+      "path": "AGENT_START.md",
+      "category": "startup_doc",
+      "sha256": "be0990bb81e194a2a396f9520cda66c34d0bbbd36daa5b48773246549aacab2e"
+    },
+    {
+      "path": "AGENTS.md",
+      "category": "agent_doc",
+      "sha256": "9e33a1c20320e317e1e37dbb09fd0303e355b9e7d49cf2128fe791aaa2ce2fb1"
+    },
+    {
+      "path": "CLAUDE.md",
+      "category": "agent_doc",
+      "sha256": "3ff3ec5560968f7f1bf6f7d34a3c4b6e636edc9f0d45f717cdebc4df3b76403a"
+    },
+    {
+      "path": "CLI_COMMAND_MATRIX.md",
+      "category": "startup_doc",
+      "sha256": "eb441dd11b31270ddb31f0a77c75fc744671754cffac3aa8ac6f60e30a1f324f"
+    },
+    {
+      "path": "llms.txt",
+      "category": "startup_doc",
+      "sha256": "8316bb8f634c6fb290ef1591e9c5b9786a2ddc06d25ab7d448fce8f4aebf65b8"
+    }
+  ]
+}

package/dist/init/legacy/v0.0.9-init-manifest.json

@@ -0,0 +1,197 @@
+{
+  "schema_version": 1,
+  "tool": "mdkg",
+  "mdkg_version": "0.0.9",
+  "files": [
+    {
+      "path": ".mdkg/config.json",
+      "category": "config",
+      "sha256": "eb76bf22ae9d04601c2fedac5fd22838797dd2cc829324638a6b69222d40aaa9"
+    },
+    {
+      "path": ".mdkg/core/HUMAN.md",
+      "category": "core",
+      "sha256": "75d2e015cd5ba61062cb84246017ee4f4221610d4a56e4a0b332271b90694965"
+    },
+    {
+      "path": ".mdkg/core/SOUL.md",
+      "category": "core",
+      "sha256": "2bfdd4d1a65dd18c14d3e8469d0d5c74c6cc7c067f0b56d227532b7ab620795a"
+    },
+    {
+      "path": ".mdkg/core/core.md",
+      "category": "core",
+      "sha256": "d87beecf4229535c0d0feea7deae28b97d0681105a1c282d9961e97918f0bbe8"
+    },
+    {
+      "path": ".mdkg/core/guide.md",
+      "category": "core",
+      "sha256": "0b0ba51fbc393b3d5e0a0df4dece6aa822b77ab0f4ee3814b2cdba77ef8b65d9"
+    },
+    {
+      "path": ".mdkg/core/rule-1-mdkg-conventions.md",
+      "category": "core",
+      "sha256": "20073cd21c148f1b93a382550f835ccb2e896cc676903328557004319235c112"
+    },
+    {
+      "path": ".mdkg/core/rule-2-context-pack-rules.md",
+      "category": "core",
+      "sha256": "9dfd46b5ae791220c68304abc0784399509cf63d6e9a8ce8f"
+    },
+    {
+      "path": ".mdkg/core/rule-3-cli-contract.md",
+      "category": "core",
+      "sha256": "b547a6edc20112013c607a033af4ac0c6bb3f9d66d445b0c545b2890a721b671"
+    },
+    {
+      "path": ".mdkg/core/rule-4-repo-safety-and-ignores.md",
+      "category": "core",
+      "sha256": "d7fc4bfa3727ed7d5353eeb0089ad818b96a755578e217251106422559750291"
+    },
+    {
+      "path": ".mdkg/core/rule-5-release-and-versioning.md",
+      "category": "core",
+      "sha256": "4fc6648052f80b90b2efc173e3bcab16cb0bc6680bb8b04f76c66fff06ad19cd"
+    },
+    {
+      "path": ".mdkg/core/rule-6-templates-and-schemas.md",
+      "category": "core",
+      "sha256": "0d6da477c12e3492f43c571a6e4daa373bf05005ef703ad5166b7c8786e553b0"
+    },
+    {
+      "path": ".mdkg/README.md",
+      "category": "mdkg_doc",
+      "sha256": "580ed58d4406783f79dd839902de3238647c99605e0849a87ca19a6bd9c738a2"
+    },
+    {
+      "path": ".mdkg/skills/build-pack-and-execute-task/SKILL.md",
+      "category": "default_skill",
+      "sha256": "7f6104980e6b2ec0749881c6be2bd3d7982702259c4979763266d1c800aeb410"
+    },
+    {
+      "path": ".mdkg/skills/select-work-and-ground-context/SKILL.md",
+      "category": "default_skill",
+      "sha256": "c8c04134532deda079f9ee290a66b2423892f9789fa946e44db4c89c05b8e1bf"
+    },
+    {
+      "path": ".mdkg/skills/verify-close-and-checkpoint/SKILL.md",
+      "category": "default_skill",
+      "sha256": "1d1bbb2cb09d13bc469706e60c38f883457d507144a33fd2675a7c1c48118132"
+    },
+    {
+      "path": ".mdkg/templates/default/bug.md",
+      "category": "template",
+      "sha256": "88e3f8d67aa3b2156be2006bd1c8139b7b16b46f2c05a4f4d840b3746a40f9c5"
+    },
+    {
+      "path": ".mdkg/templates/default/chk.md",
+      "category": "template",
+      "sha256": "15f793e422009c76f8bda72c3609157acd7f03762d9c9bdb096c4aa2e2c3fb89"
+    },
+    {
+      "path": ".mdkg/templates/default/dec.md",
+      "category": "template",
+      "sha256": "a2f7098fea538c153ac290f2e2edb2e755ca9dd07d17c2a127fb23959517ece9"
+    },
+    {
+      "path": ".mdkg/templates/default/dispute.md",
+      "category": "template",
+      "sha256": "b1c5330fd4a1e3f03dbb4ac8907bd728e55537e053dcf43ebcbdc835ff1d0579"
+    },
+    {
+      "path": ".mdkg/templates/default/edd.md",
+      "category": "template",
+      "sha256": "44828719927cfd31389b9d55b57fc4fa9bc640f3e2475baefe585e4043740f5e"
+    },
+    {
+      "path": ".mdkg/templates/default/epic.md",
+      "category": "template",
+      "sha256": "56697b69af027fe08c00866c0c0670f7d7e2a0857803bd4aabb99f4761311879"
+    },
+    {
+      "path": ".mdkg/templates/default/feat.md",
+      "category": "template",
+      "sha256": "99cfdd97b40b119cf899fd766d816c07b7daaafd8ec8e70e6c6de5c0d37f581c"
+    },
+    {
+      "path": ".mdkg/templates/default/feedback.md",
+      "category": "template",
+      "sha256": "61ad7b8b717d17736ba505f814fa6e4f9ec61f7fe4ae6622359304620a99d649"
+    },
+    {
+      "path": ".mdkg/templates/default/prd.md",
+      "category": "template",
+      "sha256": "afee167576a4f881ab191867e118864b7b5629e14b9c4a61359c8fbd7ececeee"
+    },
+    {
+      "path": ".mdkg/templates/default/prop.md",
+      "category": "template",
+      "sha256": "839b976a8ddc0d6abddfbe6114dfb87f64471958ae807c011538777b758aa1f0"
+    },
+    {
+      "path": ".mdkg/templates/default/proposal.md",
+      "category": "template",
+      "sha256": "16bfa81b6e665064e93e0d1b625dccc518b9885f87a32a15e5ba5441c2c27ea8"
+    },
+    {
+      "path": ".mdkg/templates/default/receipt.md",
+      "category": "template",
+      "sha256": "aac6e6e27153a1ca85a515b03f0ac55db3eb0df3f9243c42f0b936f5e5a750b2"
+    },
+    {
+      "path": ".mdkg/templates/default/rule.md",
+      "category": "template",
+      "sha256": "6321abf72af61a6513d7bfaa2d3122b2aa3bd2b95b662a52d569fb2bf819fda1"
+    },
+    {
+      "path": ".mdkg/templates/default/spec.md",
+      "category": "template",
+      "sha256": "e3e05d8d627c478d2757451f61b5a8fda8a75da9885a9261b2f8f5cb8a3a36dc"
+    },
+    {
+      "path": ".mdkg/templates/default/task.md",
+      "category": "template",
+      "sha256": "f6385dd4f56f1c8df164ac3e79d82c5a3fde3f952dc9cdc78c0b8077caa62277"
+    },
+    {
+      "path": ".mdkg/templates/default/test.md",
+      "category": "template",
+      "sha256": "bdae53e5cb4bd77712da155bbcfc24409ced8162c977e6bc478a9d1e695ddef7"
+    },
+    {
+      "path": ".mdkg/templates/default/work.md",
+      "category": "template",
+      "sha256": "651b7339f6e23c8745264f3f6641a0c82fcd765247f0a70a9f407a118a49ec00"
+    },
+    {
+      "path": ".mdkg/templates/default/work_order.md",
+      "category": "template",
+      "sha256": "bdbdf6e34d59976a675dd1d25002dfc0ef49e725647c97a9e0b3552c93fb8600"
+    },
+    {
+      "path": "AGENTS.md",
+      "category": "agent_doc",
+      "sha256": "9e33a1c20320e317e1e37dbb09fd0303e355b9e7d49cf2128fe791aaa2ce2fb1"
+    },
+    {
+      "path": "AGENT_START.md",
+      "category": "startup_doc",
+      "sha256": "ef8ec5feedbac948a1c63d14c5fff5bb41e3903d9de2c2b3e4db779278ff1b19"
+    },
+    {
+      "path": "CLAUDE.md",
+      "category": "agent_doc",
+      "sha256": "3ff3ec5560968f7f1bf6f7d34a3c4b6e636edc9f0d45f717cdebc4df3b76403a"
+    },
+    {
+      "path": "CLI_COMMAND_MATRIX.md",
+      "category": "startup_doc",
+      "sha256": "e39f45786eaf0cef07cc6fecd0c230474cfd7ee016a3736128566325cef73519"
+    },
+    {
+      "path": "llms.txt",
+      "category": "startup_doc",
+      "sha256": "8316bb8f634c6fb290ef1591e9c5b9786a2ddc06d25ab7d448fce8f4aebf65b8"
+    }
+  ]
+}

package/dist/init/skills/default/verify-close-and-checkpoint/SKILL.md

@@ -28,16 +28,17 @@ Finish work with evidence, validation, and minimal memory drift.
 
 1. Run the relevant technical gates for the changed surface.
 2. Run `mdkg validate` before closing the task.
-3. Use `mdkg task update <id> ...` for additive evidence and structured metadata changes; keep narrative/body edits in markdown.
-4. Use `mdkg task done <id> --checkpoint "<title>"` when the task should close with milestone compression.
-5. Batch durable mdkg writes at one boundary: task status, artifact refs, optional checkpoint, and commit.
-6. Mark tasks done only after evidence exists.
-7. Create a checkpoint only for milestone-level transitions, not every small step.
-8. For feat or epic closeout, prefer a checkpoint body as the durable narrative summary of what changed and what is next.
-9. Use feat closeout scope as direct children with `parent: <feat-id>` and epic closeout scope as descendant work with `epic: <epic-id>`.
-10. Parent status edits remain manual; do not invent a hidden parent-closeout workflow.
-11. If the latest checkpoint is relevant, use it as durable recall; treat raw events as provenance/debugging, not primary execution context.
-12. If `events.jsonl` is missing, recreate it with `mdkg event enable` before expecting automatic JSONL provenance.
+3. For mdkg scaffold or release work, include `mdkg upgrade` dry-run/apply evidence and any package smoke that exercises upgrade behavior.
+4. Use `mdkg task update <id> ...` for additive evidence and structured metadata changes; keep narrative/body edits in markdown.
+5. Use `mdkg task done <id> --checkpoint "<title>"` when the task should close with milestone compression.
+6. Batch durable mdkg writes at one boundary: task status, artifact refs, optional checkpoint, and commit.
+7. Mark tasks done only after evidence exists.
+8. Create a checkpoint only for milestone-level transitions, not every small step.
+9. For feat or epic closeout, prefer a checkpoint body as the durable narrative summary of what changed and what is next.
+10. Use feat closeout scope as direct children with `parent: <feat-id>` and epic closeout scope as descendant work with `epic: <epic-id>`.
+11. Parent status edits remain manual; do not invent a hidden parent-closeout workflow.
+12. If the latest checkpoint is relevant, use it as durable recall; treat raw events as provenance/debugging, not primary execution context.
+13. If `events.jsonl` is missing, recreate it with `mdkg event enable` before expecting automatic JSONL provenance.
 
 ## Outputs
 

package/dist/util/argparse.js

@@ -79,6 +79,7 @@ const BOOLEAN_FLAGS = new Set([
     "--concise",
     "--version",
     "--dry-run",
+    "--apply",
     "--json",
     "--xml",
     "--toon",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdkg",
-  "version": "0.0.9",
+  "version": "0.1.0",
   "description": "Markdown Knowledge Graph",
   "license": "MIT",
   "bin": {
@@ -13,10 +13,11 @@
     "test:coverage": "npm run build && npm run build:test && node --test --experimental-test-coverage dist/tests/**/*.test.js",
     "smoke:consumer": "npm run build && node scripts/smoke-consumer.js",
     "smoke:matrix": "npm run build && node scripts/smoke-command-matrix.js",
+    "smoke:upgrade": "npm run build && node scripts/smoke-upgrade.js",
     "cli:snapshot": "npm run build && node scripts/cli_help_snapshot.js",
     "cli:check": "npm run build && node scripts/cli_help_snapshot.js --check",
     "prepack": "npm run build && node scripts/assert-publish-ready.js",
-    "prepublishOnly": "npm run test && npm run cli:check && node dist/cli.js validate && npm run smoke:consumer && npm run smoke:matrix && node scripts/assert-publish-ready.js",
+    "prepublishOnly": "npm run test && npm run cli:check && node dist/cli.js validate && npm run smoke:consumer && npm run smoke:matrix && npm run smoke:upgrade && node scripts/assert-publish-ready.js",
     "postinstall": "node scripts/postinstall.js"
   },
   "devDependencies": {