mdkg 0.0.9 → 0.1.1

package/CHANGELOG.md

@@ -4,6 +4,35 @@ 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.1 - 2026-05-12
+
+### Added
+
+- Added bundled template schema fallback so older workspaces can keep using graph inspection while missing newly introduced built-in templates.
+- Added `safe_to_apply`, `will_write_paths`, `preserved_customizations`, `blocking_conflicts`, and `apply_side_effects` fields to `mdkg upgrade --json`.
+
+### Changed
+
+- `mdkg new <built-in-type>` can use the installed package template when the workspace has not yet vendored that local template.
+- `mdkg doctor` and `mdkg validate` warn, rather than fail, when packaged fallback schemas cover missing local built-in templates.
+- `mdkg upgrade` human output now states whether the receipt is safe to apply and what paths would be written.
+- `mdkg upgrade` skips ignored event logs and points users to `mdkg event enable` instead of creating ignored `.mdkg/work/events/events.jsonl` files.
+
+## 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.1`
 
 ## The product shape
 
@@ -57,6 +57,23 @@ 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 templates, updates unchanged mdkg seed assets, and preserves customized docs, templates, skills, and core files as reported preserved customizations. Review `safe_to_apply`, `will_write_paths`, and `apply_side_effects` in the JSON receipt before applying. Agent-enabled workspaces can receive safe default skill upgrades and skill mirror refreshes; ignored event logs are skipped with guidance to run `mdkg event enable` if provenance should be restored.
+
+Older workspaces can continue to inspect and validate current graph nodes before applying an upgrade. When local templates are missing for newly introduced built-in mdkg types, mdkg uses the installed package's bundled templates as a read-only schema fallback and warns that `mdkg upgrade --apply` can vendor the missing templates.
+
 Create a task:
 
 ```bash
@@ -142,6 +159,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 +222,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,21 @@ 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("  - json receipts include safe_to_apply, will_write_paths, and apply_side_effects");
+    log("  - upgrades default mdkg skills only when they match managed seed fingerprints");
+    log("  - skips ignored event logs; run mdkg event enable if provenance should be restored");
+    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 +390,9 @@ function printCommandHelp(log, command, subcommand) {
         case "init":
             printInitHelp(log);
             return;
+        case "upgrade":
+            printUpgradeHelp(log);
+            return;
         case "guide":
             printGuideHelp(log);
             return;
@@ -909,6 +931,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/doctor.js

@@ -79,12 +79,20 @@ function runDoctorCommand(options) {
     }
     if (config) {
         try {
-            (0, template_schema_1.loadTemplateSchemas)(options.root, config, node_1.ALLOWED_TYPES);
+            const templateSchemaInfo = (0, template_schema_1.loadTemplateSchemasWithInfo)(options.root, config, node_1.ALLOWED_TYPES);
             results.push({
                 name: "templates",
                 ok: true,
                 detail: "template schema set loaded",
             });
+            if (templateSchemaInfo.fallbackTypes.length > 0) {
+                results.push({
+                    name: "local-templates",
+                    ok: true,
+                    level: "warn",
+                    detail: `missing local template schema(s) covered by bundled fallback: ${templateSchemaInfo.fallbackTypes.join(", ")}; run \`mdkg upgrade --apply\` to vendor them`,
+                });
+            }
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -143,7 +151,7 @@ function runDoctorCommand(options) {
     }
     else {
         for (const result of results) {
-            const prefix = result.ok ? "ok" : "fail";
+            const prefix = result.ok ? result.level ?? "ok" : "fail";
             console.log(`${prefix}: ${result.name} - ${result.detail}`);
         }
     }

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/new.js

@@ -286,6 +286,9 @@ function runNewCommand(options) {
     }
     const today = (0, date_1.formatDate)(options.now ?? new Date());
     const template = (0, loader_1.loadTemplate)(options.root, config, type, options.template);
+    if (template.source === "bundled") {
+        console.error(`warning: using bundled template fallback for ${type}; run \`mdkg upgrade --apply\` to vendor missing local templates`);
+    }
     const content = (0, loader_1.renderTemplate)(template, {
         id,
         type,