mdkg 0.0.8 → 0.1.0

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");
@@ -63,9 +65,11 @@ function printUsage(log) {
     log("  guide       Show the mdkg guide");
     log("  format      Normalize frontmatter");
     log("  doctor      Run install and workspace diagnostics");
-    log("  workspace   Manage workspaces (ls/add/rm)");
+    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,12 +99,29 @@ 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]');
+    log('  mdkg new <type> "<title>" [options] [--json]');
     log("\nTypes:");
     log("  rule prd edd dec prop epic feat task bug checkpoint test");
+    log("\nAgent workflow file types:");
+    log("  spec work work_order receipt feedback dispute proposal");
+    log("  Use --id <portable-id> with these types for semantic ids like agent.image-worker.");
     log("\nOptions:");
+    log("  --id <portable-id>         Explicit id for agent workflow file types");
     log("  --ws <alias>               Workspace alias (default root)");
     log("  --status <status>          Work item or decision status");
     log("  --priority <0..9>          Work item priority");
@@ -113,6 +134,8 @@ function printNewHelp(log) {
     log("  --parent --prev --next --relates --blocked-by --blocks");
     log("  --links --artifacts --refs --aliases --owners --cases --supersedes");
     log("  --owners <owner,owner,...> Owners");
+    log("\nNotes:");
+    log("  spec/work scaffold as validation-clean docs; relational workflow docs need real refs.");
     printGlobalOptions(log);
 }
 function printGuideHelp(log) {
@@ -122,9 +145,11 @@ function printGuideHelp(log) {
 }
 function printWorkspaceHelp(log) {
     log("Usage:");
-    log("  mdkg workspace ls");
-    log("  mdkg workspace add <alias> <path> [--mdkg-dir <dir>]");
-    log("  mdkg workspace rm <alias>");
+    log("  mdkg workspace ls [--json]");
+    log("  mdkg workspace add <alias> <path> [--mdkg-dir <dir>] [--json]");
+    log("  mdkg workspace rm <alias> [--json]");
+    log("  mdkg workspace enable <alias> [--json]");
+    log("  mdkg workspace disable <alias> [--json]");
     printGlobalOptions(log);
 }
 function printIndexHelp(log) {
@@ -199,7 +224,7 @@ function printSkillHelp(log, subcommand) {
     switch ((subcommand ?? "").toLowerCase()) {
         case "new":
             log("Usage:");
-            log('  mdkg skill new <slug> "<name>" --description "<description>" [options]');
+            log('  mdkg skill new <slug> "<name>" --description "<description>" [options] [--json]');
             log("\nOptions:");
             log("  --tags <tag,tag,...>         Optional skill tags");
             log("  --authors <name,name,...>    Optional authors list");
@@ -232,24 +257,24 @@ function printSkillHelp(log, subcommand) {
             return;
         case "validate":
             log("Usage:");
-            log("  mdkg skill validate [<slug>]");
+            log("  mdkg skill validate [<slug>] [--json]");
             printGlobalOptions(log);
             return;
         case "sync":
             log("Usage:");
-            log("  mdkg skill sync [--force]");
+            log("  mdkg skill sync [--force] [--json]");
             log("\nWhen to use:");
             log("  Rebuild .agents/skills and .claude/skills from canonical .mdkg/skills.");
             printGlobalOptions(log);
             return;
         default:
             log("Usage:");
-            log('  mdkg skill new <slug> "<name>" --description "<description>" [options]');
+            log('  mdkg skill new <slug> "<name>" --description "<description>" [options] [--json]');
             log("  mdkg skill list [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]");
             log("  mdkg skill show <slug> [--meta] [--json|--xml|--toon|--md]");
             log('  mdkg skill search "<query>" [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]');
-            log("  mdkg skill validate [<slug>]");
-            log("  mdkg skill sync [--force]");
+            log("  mdkg skill validate [<slug>] [--json]");
+            log("  mdkg skill sync [--force] [--json]");
             log("\nNotes:");
             log("  Skills are first-class under `mdkg skill ...`.");
             log("  Use stage tags like `stage:plan`, `stage:execute`, and `stage:review` with --tags.");
@@ -260,7 +285,7 @@ function printTaskHelp(log, subcommand) {
     switch ((subcommand ?? "").toLowerCase()) {
         case "start":
             log("Usage:");
-            log('  mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"]');
+            log('  mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"] [--json]');
             log("\nWhen to use:");
             log("  Move a task, bug, or test into progress as a structured state change.");
             log("  If `events.jsonl` is missing, mdkg prints a short reminder about `mdkg event enable`.");
@@ -271,7 +296,7 @@ function printTaskHelp(log, subcommand) {
             log("  mdkg task update <id-or-qid> [--ws <alias>] [--status <status>] [--priority <n>]");
             log("                   [--add-artifacts <a,...>] [--add-links <l,...>] [--add-refs <id,...>]");
             log("                   [--add-skills <slug,...>] [--add-tags <tag,...>] [--add-blocked-by <id,...>]");
-            log('                   [--clear-blocked-by] [--run-id <id>] [--note "<text>"]');
+            log('                   [--clear-blocked-by] [--run-id <id>] [--note "<text>"] [--json]');
             log("\nWhen to use:");
             log("  Update structured task metadata and evidence while keeping body and narrative edits in markdown.");
             printGlobalOptions(log);
@@ -279,7 +304,7 @@ function printTaskHelp(log, subcommand) {
         case "done":
             log("Usage:");
             log('  mdkg task done <id-or-qid> [--ws <alias>] [--add-artifacts <a,...>] [--add-links <l,...>]');
-            log('                 [--add-refs <id,...>] [--checkpoint "<title>"] [--run-id <id>] [--note "<text>"]');
+            log('                 [--add-refs <id,...>] [--checkpoint "<title>"] [--run-id <id>] [--note "<text>"] [--json]');
             log("\nWhen to use:");
             log("  Mark a task-like node done, optionally create a checkpoint, and emit a completion event when enabled.");
             log("  Use `--checkpoint` for milestone compression, not every routine task completion.");
@@ -287,9 +312,9 @@ function printTaskHelp(log, subcommand) {
             return;
         default:
             log("Usage:");
-            log('  mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"]');
-            log("  mdkg task update <id-or-qid> [options]");
-            log('  mdkg task done <id-or-qid> [--checkpoint "<title>"] [options]');
+            log('  mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"] [--json]');
+            log("  mdkg task update <id-or-qid> [options] [--json]");
+            log('  mdkg task done <id-or-qid> [--checkpoint "<title>"] [options] [--json]');
             log("\nNotes:");
             log("  `mdkg task ...` only supports task, bug, and test nodes in this wave.");
             log("  Feat and epic closeout remain checkpoint-first guidance plus manual parent updates.");
@@ -300,7 +325,7 @@ function printEventHelp(log, subcommand) {
     switch ((subcommand ?? "").toLowerCase()) {
         case "enable":
             log("Usage:");
-            log("  mdkg event enable [--ws <alias>]");
+            log("  mdkg event enable [--ws <alias>] [--json]");
             log("\nWhen to use:");
             log("  Create or ensure the append-only JSONL event log for a workspace.");
             printGlobalOptions(log);
@@ -308,7 +333,7 @@ function printEventHelp(log, subcommand) {
         case "append":
             log("Usage:");
             log("  mdkg event append --kind <kind> --status <ok|error|retry|skipped> --refs <id,...>");
-            log('                    [--ws <alias>] [--artifacts <a,...>] [--notes "<text>"] [--run-id <id>]');
+            log('                    [--ws <alias>] [--artifacts <a,...>] [--notes "<text>"] [--run-id <id>] [--json]');
             log("                    [--agent <name>] [--skill <slug>] [--tool <id>]");
             log("\nWhen to use:");
             log("  Append explicit provenance events from an orchestrator or manual workflow.");
@@ -316,8 +341,8 @@ function printEventHelp(log, subcommand) {
             return;
         default:
             log("Usage:");
-            log("  mdkg event enable [--ws <alias>]");
-            log("  mdkg event append --kind <kind> --status <ok|error|retry|skipped> --refs <id,...> [options]");
+            log("  mdkg event enable [--ws <alias>] [--json]");
+            log("  mdkg event append --kind <kind> --status <ok|error|retry|skipped> --refs <id,...> [options] [--json]");
             printGlobalOptions(log);
     }
 }
@@ -328,13 +353,13 @@ function printNextHelp(log) {
 }
 function printCheckpointHelp(log) {
     log("Usage:");
-    log("  mdkg checkpoint new <title> [--ws <alias>]");
+    log("  mdkg checkpoint new <title> [--ws <alias>] [--json]");
     log('        [--relates <id,id,...>] [--scope <id,id,...>] [--run-id <id>] [--note "<text>"]');
     printGlobalOptions(log);
 }
 function printValidateHelp(log) {
     log("Usage:");
-    log("  mdkg validate [--out <path>] [--quiet]");
+    log("  mdkg validate [--out <path>] [--quiet] [--json]");
     printGlobalOptions(log);
 }
 function printFormatHelp(log) {
@@ -363,6 +388,9 @@ function printCommandHelp(log, command, subcommand) {
         case "init":
             printInitHelp(log);
             return;
+        case "upgrade":
+            printUpgradeHelp(log);
+            return;
         case "guide":
             printGuideHelp(log);
             return;
@@ -573,7 +601,8 @@ function runWorkspaceSubcommand(parsed, root) {
             if (parsed.positionals.length > 2) {
                 throw new errors_1.UsageError("workspace ls takes no arguments");
             }
-            (0, workspace_1.runWorkspaceListCommand)({ root });
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, workspace_1.runWorkspaceListCommand)({ root, json });
             return 0;
         }
         case "add": {
@@ -583,7 +612,8 @@ function runWorkspaceSubcommand(parsed, root) {
                 throw new errors_1.UsageError("workspace add requires <alias> <path>");
             }
             const mdkgDir = requireFlagValue("--mdkg-dir", parsed.flags["--mdkg-dir"]);
-            (0, workspace_1.runWorkspaceAddCommand)({ root, alias, workspacePath, mdkgDir });
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, workspace_1.runWorkspaceAddCommand)({ root, alias, workspacePath, mdkgDir, json });
             return 0;
         }
         case "rm": {
@@ -591,11 +621,30 @@ function runWorkspaceSubcommand(parsed, root) {
             if (!alias || parsed.positionals.length > 3) {
                 throw new errors_1.UsageError("workspace rm requires <alias>");
             }
-            (0, workspace_1.runWorkspaceRemoveCommand)({ root, alias });
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, workspace_1.runWorkspaceRemoveCommand)({ root, alias, json });
+            return 0;
+        }
+        case "enable": {
+            const alias = parsed.positionals[2];
+            if (!alias || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("workspace enable requires <alias>");
+            }
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, workspace_1.runWorkspaceEnableCommand)({ root, alias, json });
+            return 0;
+        }
+        case "disable": {
+            const alias = parsed.positionals[2];
+            if (!alias || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("workspace disable requires <alias>");
+            }
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, workspace_1.runWorkspaceDisableCommand)({ root, alias, json });
             return 0;
         }
         default:
-            throw new errors_1.UsageError("workspace requires ls/add/rm");
+            throw new errors_1.UsageError("workspace requires ls/add/rm/enable/disable");
     }
 }
 function runSkillSubcommand(parsed, root) {
@@ -620,6 +669,7 @@ function runSkillSubcommand(parsed, root) {
             const withScripts = parseBooleanFlag("--with-scripts", parsed.flags["--with-scripts"]);
             const force = parseBooleanFlag("--force", parsed.flags["--force"]);
             const runId = requireFlagValue("--run-id", parsed.flags["--run-id"]);
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
             (0, skill_1.runSkillNewCommand)({
                 root,
                 slug,
@@ -631,6 +681,7 @@ function runSkillSubcommand(parsed, root) {
                 withScripts,
                 force,
                 runId,
+                json,
             });
             return 0;
         }
@@ -698,7 +749,8 @@ function runSkillSubcommand(parsed, root) {
                 throw new errors_1.UsageError("skill validate accepts at most one slug");
             }
             const slug = parsed.positionals[2];
-            (0, skill_1.runSkillValidateCommand)({ root, slug });
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, skill_1.runSkillValidateCommand)({ root, slug, json });
             return 0;
         }
         case "sync": {
@@ -706,7 +758,8 @@ function runSkillSubcommand(parsed, root) {
                 throw new errors_1.UsageError("skill sync does not accept positional arguments");
             }
             const force = parseBooleanFlag("--force", parsed.flags["--force"]);
-            (0, skill_1.runSkillSyncCommand)({ root, force });
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, skill_1.runSkillSyncCommand)({ root, force, json });
             return 0;
         }
         default:
@@ -724,7 +777,8 @@ function runTaskSubcommand(parsed, root) {
             const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
             const runId = requireFlagValue("--run-id", parsed.flags["--run-id"]);
             const note = requireFlagValue("--note", parsed.flags["--note"]);
-            (0, task_1.runTaskStartCommand)({ root, id, ws, runId, note });
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, task_1.runTaskStartCommand)({ root, id, ws, runId, note, json });
             return 0;
         }
         case "update": {
@@ -744,6 +798,7 @@ function runTaskSubcommand(parsed, root) {
             const clearBlockedBy = parseBooleanFlag("--clear-blocked-by", parsed.flags["--clear-blocked-by"]);
             const runId = requireFlagValue("--run-id", parsed.flags["--run-id"]);
             const note = requireFlagValue("--note", parsed.flags["--note"]);
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
             (0, task_1.runTaskUpdateCommand)({
                 root,
                 id,
@@ -759,6 +814,7 @@ function runTaskSubcommand(parsed, root) {
                 clearBlockedBy,
                 runId,
                 note,
+                json,
             });
             return 0;
         }
@@ -774,6 +830,7 @@ function runTaskSubcommand(parsed, root) {
             const checkpoint = requireFlagValue("--checkpoint", parsed.flags["--checkpoint"]);
             const runId = requireFlagValue("--run-id", parsed.flags["--run-id"]);
             const note = requireFlagValue("--note", parsed.flags["--note"]);
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
             (0, task_1.runTaskDoneCommand)({
                 root,
                 id,
@@ -784,6 +841,7 @@ function runTaskSubcommand(parsed, root) {
                 checkpoint,
                 runId,
                 note,
+                json,
             });
             return 0;
         }
@@ -799,7 +857,8 @@ function runEventSubcommand(parsed, root) {
                 throw new errors_1.UsageError("event enable does not accept positional arguments");
             }
             const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
-            (0, event_1.runEventEnableCommand)({ root, ws });
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, event_1.runEventEnableCommand)({ root, ws, json });
             return 0;
         }
         case "append": {
@@ -819,6 +878,7 @@ function runEventSubcommand(parsed, root) {
             const agent = requireFlagValue("--agent", parsed.flags["--agent"]);
             const skill = requireFlagValue("--skill", parsed.flags["--skill"]);
             const tool = requireFlagValue("--tool", parsed.flags["--tool"]);
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
             (0, event_1.runEventAppendCommand)({
                 root,
                 ws,
@@ -831,6 +891,7 @@ function runEventSubcommand(parsed, root) {
                 agent,
                 skill,
                 tool,
+                json,
             });
             return 0;
         }
@@ -868,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;
@@ -882,6 +956,7 @@ function runCommand(parsed, root, runtime) {
             if (!type || !title) {
                 throw new errors_1.UsageError("new requires a type and title");
             }
+            const id = requireFlagValue("--id", parsed.flags["--id"]);
             const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
             const status = requireFlagValue("--status", parsed.flags["--status"]);
             const priority = parseNumberFlag("--priority", parsed.flags["--priority"]);
@@ -905,10 +980,12 @@ function runCommand(parsed, root, runtime) {
             const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
             const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
             const runId = requireFlagValue("--run-id", parsed.flags["--run-id"]);
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
             (0, new_1.runNewCommand)({
                 root,
                 type,
                 title,
+                id,
                 ws,
                 status,
                 priority,
@@ -932,6 +1009,7 @@ function runCommand(parsed, root, runtime) {
                 noCache,
                 noReindex,
                 runId,
+                json,
             });
             return 0;
         }
@@ -1117,6 +1195,7 @@ function runCommand(parsed, root, runtime) {
             const template = requireFlagValue("--template", parsed.flags["--template"]);
             const runId = requireFlagValue("--run-id", parsed.flags["--run-id"]);
             const note = requireFlagValue("--note", parsed.flags["--note"]);
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
             (0, checkpoint_1.runCheckpointNewCommand)({
                 root,
                 title,
@@ -1128,6 +1207,7 @@ function runCommand(parsed, root, runtime) {
                 template,
                 runId,
                 note,
+                json,
             });
             return 0;
         }
@@ -1137,7 +1217,8 @@ function runCommand(parsed, root, runtime) {
             }
             const out = requireFlagValue("--out", parsed.flags["--out"]);
             const quiet = parseBooleanFlag("--quiet", parsed.flags["--quiet"]);
-            (0, validate_1.runValidateCommand)({ root, out, quiet });
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, validate_1.runValidateCommand)({ root, out, quiet, json });
             return 0;
         }
         case "format":

package/dist/commands/checkpoint.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.createCheckpoint = createCheckpoint;
 exports.runCheckpointNewCommand = runCheckpointNewCommand;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -76,7 +77,7 @@ function normalizeWorkspace(value) {
     }
     return normalized;
 }
-function runCheckpointNewCommand(options) {
+function createCheckpoint(options) {
     const title = options.title.trim();
     if (!title) {
         throw new errors_1.UsageError("checkpoint title cannot be empty");
@@ -140,5 +141,21 @@ function runCheckpointNewCommand(options) {
         runId: options.runId,
         now,
     });
-    console.log(`checkpoint created: ${ws}:${id} (${path_1.default.relative(options.root, filePath)})`);
+    return {
+        workspace: ws,
+        id,
+        qid: `${ws}:${id}`,
+        path: path_1.default.relative(options.root, filePath),
+    };
+}
+function runCheckpointNewCommand(options) {
+    const checkpoint = createCheckpoint(options);
+    if (options.json) {
+        console.log(JSON.stringify({
+            action: "created",
+            checkpoint,
+        }, null, 2));
+        return;
+    }
+    console.log(`checkpoint created: ${checkpoint.qid} (${checkpoint.path})`);
 }

package/dist/commands/event.js

@@ -6,6 +6,14 @@ const event_support_1 = require("./event_support");
 const errors_1 = require("../util/errors");
 function runEventEnableCommand(options) {
     const result = (0, event_support_1.ensureEventsEnabled)(options);
+    if (options.json) {
+        console.log(JSON.stringify({
+            action: "enabled",
+            workspace: result.ws,
+            created: result.created,
+        }, null, 2));
+        return;
+    }
     const createdLabel = result.created ? "created" : "already present";
     console.log(`event logging enabled: ${result.ws} (${createdLabel})`);
 }
@@ -41,5 +49,9 @@ function runEventAppendCommand(options) {
         skill: options.skill,
         tool: options.tool,
     });
+    if (options.json) {
+        console.log(JSON.stringify({ action: "appended", event: record }, null, 2));
+        return;
+    }
     console.log(`event appended: ${record.workspace}:${record.kind} (${record.run_id})`);
 }

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);
+}