mdkg 0.1.0 → 0.1.2

package/dist/commands/format.js

@@ -10,16 +10,34 @@ const config_1 = require("../core/config");
 const frontmatter_1 = require("../graph/frontmatter");
 const template_schema_1 = require("../graph/template_schema");
 const node_1 = require("../graph/node");
+const agent_file_types_1 = require("../graph/agent_file_types");
+const archive_file_1 = require("../graph/archive_file");
 const workspace_files_1 = require("../graph/workspace_files");
 const errors_1 = require("../util/errors");
 const date_1 = require("../util/date");
 const id_1 = require("../util/id");
+const refs_1 = require("../util/refs");
 const DEC_ID_RE = /^dec-[0-9]+$/;
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 const ID_LIST_KEYS = new Set(["refs", "scope"]);
 const ID_REF_LIST_KEYS = new Set(["relates", "blocked_by", "blocks"]);
 const ID_REF_SCALAR_KEYS = new Set(["epic", "parent", "prev", "next"]);
-const PRESERVE_CASE_LIST_KEYS = new Set(["links", "artifacts"]);
+const PRESERVE_CASE_LIST_KEYS = new Set([
+    "links",
+    "artifacts",
+    "work_contracts",
+    "input_refs",
+    "constraint_refs",
+    "proof_refs",
+    "attestation_refs",
+]);
+const EXTERNAL_REF_LIST_KEYS = new Set([
+    "input_refs",
+    "constraint_refs",
+    "proof_refs",
+    "attestation_refs",
+]);
+const HASH_REF_LIST_KEYS = new Set(["input_hashes", "output_hashes"]);
 function isValidId(value) {
     return (0, id_1.isCanonicalId)(value);
 }
@@ -48,7 +66,7 @@ function sortList(values) {
         return 0;
     });
 }
-function normalizeList(values, key, errors, filePath) {
+function normalizeList(values, key, errors, filePath, allowPortableRefs = false) {
     const trimmed = values.map((value) => normalizeScalar(value));
     const shouldLowercase = !PRESERVE_CASE_LIST_KEYS.has(key);
     const normalized = shouldLowercase ? trimmed.map((value) => value.toLowerCase()) : trimmed;
@@ -57,12 +75,18 @@ function normalizeList(values, key, errors, filePath) {
             errors.push(`${filePath}: ${key} entries must be non-empty`);
             continue;
         }
-        if (ID_LIST_KEYS.has(key) && !isValidId(entry)) {
+        if (ID_LIST_KEYS.has(key) && !(allowPortableRefs ? (0, id_1.isPortableId)(entry) : isValidId(entry))) {
             errors.push(`${filePath}: ${key} entries must match <prefix>-<number> or reserved id`);
         }
-        if (ID_REF_LIST_KEYS.has(key) && !(0, id_1.isCanonicalIdRef)(entry)) {
+        if (ID_REF_LIST_KEYS.has(key) && !(allowPortableRefs ? (0, id_1.isPortableIdRef)(entry) : (0, id_1.isCanonicalIdRef)(entry))) {
             errors.push(`${filePath}: ${key} entries must be valid id references`);
         }
+        if (EXTERNAL_REF_LIST_KEYS.has(key) && !(0, refs_1.validatePortableOrUriRef)(entry)) {
+            errors.push(`${filePath}: ${key} entries must be portable ids or URI refs`);
+        }
+        if (HASH_REF_LIST_KEYS.has(key) && !(0, refs_1.isSha256Ref)(entry)) {
+            errors.push(`${filePath}: ${key} entries must be sha256:<64 lowercase hex chars>`);
+        }
     }
     return sortList(normalized);
 }
@@ -73,14 +97,15 @@ function normalizeIdRef(value, key, errors, filePath) {
     }
     return normalized;
 }
-function normalizeFrontmatterValue(key, value, schema, errors, filePath) {
+function normalizeFrontmatterValue(key, value, schema, errors, filePath, type) {
     const expected = schema.keyKinds[key];
     if (expected === "list") {
         if (!Array.isArray(value)) {
             errors.push(`${filePath}: ${key} must be a list`);
             return [];
         }
-        return normalizeList(value, key, errors, filePath);
+        const allowPortableRefs = (0, agent_file_types_1.isAgentFileType)(type) || (0, archive_file_1.isArchiveType)(type);
+        return normalizeList(value, key, errors, filePath, allowPortableRefs);
     }
     if (expected === "boolean") {
         if (typeof value !== "boolean") {
@@ -111,7 +136,7 @@ function normalizeFrontmatter(frontmatter, schema, type, workStatusEnum, priorit
             }
             continue;
         }
-        const normalizedValue = normalizeFrontmatterValue(key, value, schema, errors, filePath);
+        const normalizedValue = normalizeFrontmatterValue(key, value, schema, errors, filePath, type);
         if (normalizedValue !== undefined) {
             normalized[key] = normalizedValue;
         }
@@ -122,8 +147,12 @@ function normalizeFrontmatter(frontmatter, schema, type, workStatusEnum, priorit
     }
     else {
         const normalizedId = idValue.toLowerCase();
-        if (!isValidId(normalizedId)) {
-            errors.push(`${filePath}: id must match <prefix>-<number> or reserved id`);
+        const allowPortableId = (0, agent_file_types_1.isAgentFileType)(type) || (0, archive_file_1.isArchiveType)(type);
+        if (!(allowPortableId ? (0, id_1.isPortableId)(normalizedId) : isValidId(normalizedId))) {
+            const requirement = allowPortableId
+                ? "<prefix>-<number>, reserved id, or allowed portable id"
+                : "<prefix>-<number> or reserved id";
+            errors.push(`${filePath}: id must match ${requirement}`);
         }
         normalized.id = normalizedId;
     }

package/dist/commands/index.js

@@ -10,14 +10,25 @@ const indexer_1 = require("../graph/indexer");
 const index_cache_1 = require("../graph/index_cache");
 const skills_index_cache_1 = require("../graph/skills_index_cache");
 const skills_indexer_1 = require("../graph/skills_indexer");
+const capabilities_indexer_1 = require("../graph/capabilities_indexer");
+const capabilities_index_cache_1 = require("../graph/capabilities_index_cache");
+const bundle_imports_1 = require("../graph/bundle_imports");
 function runIndexCommand(options) {
     const config = (0, config_1.loadConfig)(options.root);
     const nodeIndex = (0, indexer_1.buildIndex)(options.root, config, { tolerant: options.tolerant });
     const skillsIndex = (0, skills_indexer_1.buildSkillsIndex)(options.root, config);
+    const capabilitiesIndex = (0, capabilities_indexer_1.buildCapabilitiesIndex)(options.root, config, nodeIndex);
+    const importsIndex = (0, bundle_imports_1.buildBundleImportsIndex)(options.root, config);
     const nodesOutputPath = path_1.default.resolve(options.root, config.index.global_index_path);
     const skillsOutputPath = (0, skills_indexer_1.resolveSkillsIndexPath)(options.root);
+    const capabilitiesOutputPath = (0, capabilities_indexer_1.resolveCapabilitiesIndexPath)(options.root, config);
+    const importsOutputPath = (0, bundle_imports_1.resolveBundleImportsIndexPath)(options.root);
     (0, index_cache_1.writeIndex)(nodesOutputPath, nodeIndex);
     (0, skills_index_cache_1.writeSkillsIndex)(skillsOutputPath, skillsIndex);
+    (0, capabilities_index_cache_1.writeCapabilitiesIndex)(capabilitiesOutputPath, capabilitiesIndex);
+    (0, bundle_imports_1.writeBundleImportsIndex)(importsOutputPath, importsIndex.index);
     console.log(`index written: ${path_1.default.relative(options.root, nodesOutputPath)}`);
     console.log(`skills index written: ${path_1.default.relative(options.root, skillsOutputPath)}`);
+    console.log(`capabilities index written: ${path_1.default.relative(options.root, capabilitiesOutputPath)}`);
+    console.log(`bundle imports index written: ${path_1.default.relative(options.root, importsOutputPath)}`);
 }

package/dist/commands/init.js

@@ -7,6 +7,7 @@ exports.runInitCommand = runInitCommand;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const config_1 = require("../core/config");
+const migrate_1 = require("../core/migrate");
 const errors_1 = require("../util/errors");
 const date_1 = require("../util/date");
 const version_1 = require("../core/version");
@@ -39,16 +40,28 @@ function listFiles(dir) {
     }
     return files;
 }
-function copySeedFile(src, dest, force, stats) {
+function displayPath(root, filePath) {
+    const relPath = path_1.default.relative(root, filePath).split(path_1.default.sep).join("/");
+    return relPath.length > 0 ? relPath : ".";
+}
+function recordCreated(root, dest, stats) {
+    stats.created += 1;
+    stats.createdPaths.push(displayPath(root, dest));
+}
+function recordSkipped(root, dest, stats) {
+    stats.skipped += 1;
+    stats.skippedPaths.push(displayPath(root, dest));
+}
+function copySeedFile(root, src, dest, force, stats) {
     if (fs_1.default.existsSync(dest) && !force) {
-        stats.skipped += 1;
+        recordSkipped(root, dest, stats);
         return;
     }
     fs_1.default.mkdirSync(path_1.default.dirname(dest), { recursive: true });
     fs_1.default.copyFileSync(src, dest);
-    stats.created += 1;
+    recordCreated(root, dest, stats);
 }
-function copySeedDir(srcDir, destDir, force, stats) {
+function copySeedDir(root, srcDir, destDir, force, stats) {
     if (!fs_1.default.existsSync(srcDir)) {
         return;
     }
@@ -56,7 +69,7 @@ function copySeedDir(srcDir, destDir, force, stats) {
     for (const filePath of files) {
         const relPath = path_1.default.relative(srcDir, filePath);
         const destPath = path_1.default.join(destDir, relPath);
-        copySeedFile(filePath, destPath, force, stats);
+        copySeedFile(root, filePath, destPath, force, stats);
     }
 }
 function appendIgnoreEntries(filePath, entries) {
@@ -73,14 +86,14 @@ function appendIgnoreEntries(filePath, entries) {
     fs_1.default.writeFileSync(filePath, updated, "utf8");
     return true;
 }
-function writeFileIfMissing(filePath, content, force, stats) {
+function writeFileIfMissing(root, filePath, content, force, stats) {
     if (fs_1.default.existsSync(filePath) && !force) {
-        stats.skipped += 1;
+        recordSkipped(root, filePath, stats);
         return;
     }
     fs_1.default.mkdirSync(path_1.default.dirname(filePath), { recursive: true });
     fs_1.default.writeFileSync(filePath, content, "utf8");
-    stats.created += 1;
+    recordCreated(root, filePath, stats);
 }
 function soulTemplate(created) {
     return [
@@ -176,6 +189,48 @@ function seededInitEvent(nowIso) {
     };
     return `${JSON.stringify(event)}\n`;
 }
+function listSeedSkillSlugs(seedDefaultSkills) {
+    if (!fs_1.default.existsSync(seedDefaultSkills)) {
+        return [];
+    }
+    return fs_1.default
+        .readdirSync(seedDefaultSkills, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && fs_1.default.existsSync(path_1.default.join(seedDefaultSkills, entry.name, "SKILL.md")))
+        .map((entry) => entry.name.toLowerCase())
+        .sort();
+}
+function listExistingCanonicalSkillSlugs(root) {
+    const skillsDir = path_1.default.join(root, ".mdkg", "skills");
+    if (!fs_1.default.existsSync(skillsDir)) {
+        return [];
+    }
+    return fs_1.default
+        .readdirSync(skillsDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && fs_1.default.existsSync(path_1.default.join(skillsDir, entry.name, "SKILL.md")))
+        .map((entry) => entry.name.toLowerCase())
+        .sort();
+}
+function preflightSeedConfig(seedConfig) {
+    const raw = JSON.parse(fs_1.default.readFileSync(seedConfig, "utf8"));
+    (0, config_1.validateConfigSchema)((0, migrate_1.migrateConfig)(raw).config);
+}
+function emitPartialInitFailure(root, stats, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error("mdkg init failed after partial writes");
+    console.error(`error: ${message}`);
+    console.error(`created: ${stats.created}`);
+    for (const created of stats.createdPaths) {
+        console.error(`  created: ${created}`);
+    }
+    console.error(`skipped: ${stats.skipped}`);
+    for (const skipped of stats.skippedPaths) {
+        console.error(`  skipped: ${skipped}`);
+    }
+    console.error("recovery:");
+    console.error("  inspect the created paths above");
+    console.error("  rerun `mdkg init --agent` after resolving the reported error");
+    console.error(`  root: ${root}`);
+}
 function parseCoreList(raw) {
     const lines = raw.split(/\r?\n/);
     const header = [];
@@ -224,9 +279,9 @@ function ensureCorePins(coreListPath, requiredPins) {
 function runInitCommand(options) {
     const root = path_1.default.resolve(options.root);
     const seedRoot = options.seedRoot ? path_1.default.resolve(options.seedRoot) : DEFAULT_SEED_SUBDIR;
-    const createAgents = Boolean(options.createAgents || options.createLlm);
-    const createClaude = Boolean(options.createClaude || options.createLlm);
-    const createStartupDocs = Boolean(options.createLlm || options.agent);
+    const createAgents = Boolean(options.agent);
+    const createClaude = Boolean(options.agent);
+    const createStartupDocs = Boolean(options.agent);
     const force = Boolean(options.force);
     const seedConfig = path_1.default.join(seedRoot, "config.json");
     const seedCore = path_1.default.join(seedRoot, "core");
@@ -238,7 +293,13 @@ 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)());
+    const seedSoul = path_1.default.join(seedCore, "SOUL.md");
+    const seedHuman = path_1.default.join(seedCore, "HUMAN.md");
+    const seedManifest = (0, init_manifest_1.createInitManifest)(seedRoot, (0, version_1.readPackageVersion)(), {
+        includeAgentDocs: Boolean(options.agent),
+        includeStartupDocs: Boolean(options.agent),
+        includeDefaultSkills: Boolean(options.agent),
+    });
     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)`);
     }
@@ -263,67 +324,131 @@ function runInitCommand(options) {
     if (options.agent && !fs_1.default.existsSync(seedDefaultSkills)) {
         throw new errors_1.NotFoundError(`init assets missing default skills at ${seedRoot}`);
     }
-    const mdkgDir = path_1.default.join(root, ".mdkg");
-    fs_1.default.mkdirSync(mdkgDir, { recursive: true });
-    fs_1.default.mkdirSync(path_1.default.join(mdkgDir, "work"), { recursive: true });
-    fs_1.default.mkdirSync(path_1.default.join(mdkgDir, "design"), { recursive: true });
-    const stats = { created: 0, skipped: 0 };
-    copySeedFile(seedConfig, path_1.default.join(mdkgDir, "config.json"), force, stats);
-    copySeedFile(seedReadme, path_1.default.join(mdkgDir, "README.md"), force, stats);
-    copySeedDir(seedCore, path_1.default.join(mdkgDir, "core"), force, stats);
-    copySeedDir(seedTemplates, path_1.default.join(mdkgDir, "templates"), force, stats);
-    if (createAgents) {
-        copySeedFile(seedAgents, path_1.default.join(root, "AGENTS.md"), force, stats);
-    }
-    if (createClaude) {
-        copySeedFile(seedClaude, path_1.default.join(root, "CLAUDE.md"), force, stats);
+    preflightSeedConfig(seedConfig);
+    if (options.agent) {
+        (0, skill_mirror_1.preflightSkillMirrorTargets)({
+            root,
+            slugs: [...listSeedSkillSlugs(seedDefaultSkills), ...listExistingCanonicalSkillSlugs(root)],
+            force,
+        });
     }
-    if (createStartupDocs) {
-        copySeedFile(seedLlms, path_1.default.join(root, "llms.txt"), force, stats);
-        copySeedFile(seedAgentStart, path_1.default.join(root, "AGENT_START.md"), force, stats);
-        copySeedFile(seedCliMatrix, path_1.default.join(root, "CLI_COMMAND_MATRIX.md"), force, stats);
+    const stats = {
+        created: 0,
+        skipped: 0,
+        createdPaths: [],
+        skippedPaths: [],
+        ignoreFilesUpdated: [],
+        manifestWritten: false,
+        registryRefreshed: false,
+        mirrorTargets: 0,
+        mirroredSkills: 0,
+    };
+    const mdkgDir = path_1.default.join(root, ".mdkg");
+    try {
+        fs_1.default.mkdirSync(mdkgDir, { recursive: true });
+        fs_1.default.mkdirSync(path_1.default.join(mdkgDir, "work"), { recursive: true });
+        fs_1.default.mkdirSync(path_1.default.join(mdkgDir, "design"), { recursive: true });
+        copySeedFile(root, seedConfig, path_1.default.join(mdkgDir, "config.json"), force, stats);
+        copySeedFile(root, seedReadme, path_1.default.join(mdkgDir, "README.md"), force, stats);
+        copySeedDir(root, seedCore, path_1.default.join(mdkgDir, "core"), force, stats);
+        copySeedDir(root, seedTemplates, path_1.default.join(mdkgDir, "templates"), force, stats);
+        if (createAgents) {
+            copySeedFile(root, seedAgents, path_1.default.join(root, "AGENTS.md"), force, stats);
+        }
+        if (createClaude) {
+            copySeedFile(root, seedClaude, path_1.default.join(root, "CLAUDE.md"), force, stats);
+        }
+        if (createStartupDocs) {
+            copySeedFile(root, seedLlms, path_1.default.join(root, "llms.txt"), force, stats);
+            copySeedFile(root, seedAgentStart, path_1.default.join(root, "AGENT_START.md"), force, stats);
+            copySeedFile(root, seedCliMatrix, path_1.default.join(root, "CLI_COMMAND_MATRIX.md"), force, stats);
+        }
+        if (options.agent) {
+            const today = (0, date_1.formatDate)(new Date());
+            const soulPath = path_1.default.join(mdkgDir, "core", "SOUL.md");
+            const humanPath = path_1.default.join(mdkgDir, "core", "HUMAN.md");
+            const skillsDir = path_1.default.join(mdkgDir, "skills");
+            const registryPath = path_1.default.join(skillsDir, "registry.md");
+            const eventsDir = path_1.default.join(mdkgDir, "work", "events");
+            const eventsPath = path_1.default.join(eventsDir, "events.jsonl");
+            fs_1.default.mkdirSync(skillsDir, { recursive: true });
+            fs_1.default.mkdirSync(eventsDir, { recursive: true });
+            copySeedDir(root, seedDefaultSkills, skillsDir, force, stats);
+            if (!fs_1.default.existsSync(seedSoul)) {
+                writeFileIfMissing(root, soulPath, soulTemplate(today), force, stats);
+            }
+            if (!fs_1.default.existsSync(seedHuman)) {
+                writeFileIfMissing(root, humanPath, humanTemplate(today), force, stats);
+            }
+            writeFileIfMissing(root, registryPath, (0, skill_support_1.registryTemplate)(), force, stats);
+            if (!fs_1.default.existsSync(eventsPath) || force) {
+                writeFileIfMissing(root, eventsPath, seededInitEvent(new Date().toISOString()), force, stats);
+            }
+            const coreListPath = path_1.default.join(mdkgDir, "core", "core.md");
+            ensureCorePins(coreListPath, [SOUL_PIN_ID, HUMAN_PIN_ID]);
+            (0, skill_mirror_1.scaffoldMirrorRoots)(root);
+            const config = (0, config_1.loadConfig)(root);
+            (0, skill_support_1.refreshSkillsRegistry)(root, config);
+            stats.registryRefreshed = true;
+            const mirrorResult = (0, skill_mirror_1.syncSkillMirrors)({ root, config, createRoots: true, force });
+            stats.mirrorTargets = mirrorResult.targets;
+            stats.mirroredSkills = mirrorResult.synced;
+        }
+        (0, init_manifest_1.writeInitManifest)(path_1.default.join(mdkgDir, init_manifest_1.INIT_MANIFEST_FILE), seedManifest);
+        stats.manifestWritten = true;
     }
-    if (options.agent) {
-        const today = (0, date_1.formatDate)(new Date());
-        const soulPath = path_1.default.join(mdkgDir, "core", "SOUL.md");
-        const humanPath = path_1.default.join(mdkgDir, "core", "HUMAN.md");
-        const skillsDir = path_1.default.join(mdkgDir, "skills");
-        const registryPath = path_1.default.join(skillsDir, "registry.md");
-        const eventsDir = path_1.default.join(mdkgDir, "work", "events");
-        const eventsPath = path_1.default.join(eventsDir, "events.jsonl");
-        fs_1.default.mkdirSync(skillsDir, { recursive: true });
-        fs_1.default.mkdirSync(eventsDir, { recursive: true });
-        copySeedDir(seedDefaultSkills, skillsDir, force, stats);
-        writeFileIfMissing(soulPath, soulTemplate(today), force, stats);
-        writeFileIfMissing(humanPath, humanTemplate(today), force, stats);
-        writeFileIfMissing(registryPath, (0, skill_support_1.registryTemplate)(), force, stats);
-        if (!fs_1.default.existsSync(eventsPath) || force) {
-            writeFileIfMissing(eventsPath, seededInitEvent(new Date().toISOString()), force, stats);
+    catch (err) {
+        if (stats.created > 0 || stats.skipped > 0) {
+            emitPartialInitFailure(root, stats, err);
         }
-        const coreListPath = path_1.default.join(mdkgDir, "core", "core.md");
-        ensureCorePins(coreListPath, [SOUL_PIN_ID, HUMAN_PIN_ID]);
-        (0, skill_mirror_1.scaffoldMirrorRoots)(root);
-        const config = (0, config_1.loadConfig)(root);
-        (0, skill_support_1.refreshSkillsRegistry)(root, config);
-        (0, skill_mirror_1.syncSkillMirrors)({ root, config, createRoots: true, force });
+        throw err;
     }
-    (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);
-    if (shouldUpdateGitignore) {
-        appendIgnoreEntries(path_1.default.join(root, ".gitignore"), [
-            ".mdkg/index/",
-            ".mdkg/pack/",
-        ]);
-    }
-    if (shouldUpdateNpmignore) {
-        appendIgnoreEntries(path_1.default.join(root, ".npmignore"), [".mdkg/", ".mdkg/index/", ".mdkg/pack/"]);
+    try {
+        if (shouldUpdateGitignore) {
+            if (appendIgnoreEntries(path_1.default.join(root, ".gitignore"), [
+                ".mdkg/index/",
+                ".mdkg/pack/",
+                ".mdkg/archive/**/source/",
+            ])) {
+                stats.ignoreFilesUpdated.push(".gitignore");
+            }
+        }
+        if (shouldUpdateNpmignore) {
+            if (appendIgnoreEntries(path_1.default.join(root, ".npmignore"), [".mdkg/", ".mdkg/index/", ".mdkg/pack/"])) {
+                stats.ignoreFilesUpdated.push(".npmignore");
+            }
+        }
+        if (options.updateDockerignore) {
+            if (appendIgnoreEntries(path_1.default.join(root, ".dockerignore"), [".mdkg/"])) {
+                stats.ignoreFilesUpdated.push(".dockerignore");
+            }
+        }
     }
-    if (options.updateDockerignore) {
-        appendIgnoreEntries(path_1.default.join(root, ".dockerignore"), [".mdkg/"]);
+    catch (err) {
+        if (stats.created > 0 || stats.skipped > 0) {
+            emitPartialInitFailure(root, stats, err);
+        }
+        throw err;
     }
     console.log(`mdkg init complete: ${stats.created} file(s) created, ${stats.skipped} skipped`);
+    if (stats.manifestWritten) {
+        console.log("managed manifest: .mdkg/init-manifest.json");
+    }
+    if (stats.ignoreFilesUpdated.length > 0) {
+        console.log(`ignore files updated: ${stats.ignoreFilesUpdated.join(", ")}`);
+    }
+    if (options.agent) {
+        console.log("agent bootstrap: AGENT_START.md, AGENTS.md, CLAUDE.md, llms.txt, CLI_COMMAND_MATRIX.md");
+        console.log("agent core pins: rule-soul, rule-human");
+        console.log("agent event log: .mdkg/work/events/events.jsonl");
+        console.log(`skill mirrors: ${stats.mirroredSkills} sync operation(s) across ${stats.mirrorTargets} target(s)`);
+        if (stats.registryRefreshed) {
+            console.log("skill registry: .mdkg/skills/registry.md");
+        }
+    }
     console.log("next:");
     if (createStartupDocs) {
         console.log("  read AGENT_START.md");

package/dist/commands/init_manifest.js

@@ -83,19 +83,32 @@ function seedSourcePath(seedRoot, file) {
     }
     return path_1.default.join(seedRoot, file.path);
 }
-function createInitManifest(seedRoot, mdkgVersion) {
+function createInitManifest(seedRoot, mdkgVersion, options = {
+    includeAgentDocs: true,
+    includeStartupDocs: true,
+    includeDefaultSkills: true,
+}) {
+    const includeAgentDocs = Boolean(options.includeAgentDocs);
+    const includeStartupDocs = Boolean(options.includeStartupDocs);
+    const includeDefaultSkills = Boolean(options.includeDefaultSkills);
     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");
+    if (includeAgentDocs) {
+        for (const doc of AGENT_DOCS) {
+            addSeedFile(files, seedRoot, doc, doc, "agent_doc");
+        }
+    }
+    if (includeStartupDocs) {
+        for (const doc of STARTUP_DOCS) {
+            addSeedFile(files, seedRoot, doc, doc, "startup_doc");
+        }
     }
-    for (const doc of STARTUP_DOCS) {
-        addSeedFile(files, seedRoot, doc, doc, "startup_doc");
+    if (includeDefaultSkills) {
+        addSeedDir(files, seedRoot, path_1.default.join("skills", "default"), ".mdkg/skills", "default_skill");
     }
-    addSeedDir(files, seedRoot, path_1.default.join("skills", "default"), ".mdkg/skills", "default_skill");
     return {
         schema_version: exports.INIT_MANIFEST_SCHEMA_VERSION,
         tool: "mdkg",

package/dist/commands/list.js

@@ -18,14 +18,14 @@ function normalizeWorkspace(value) {
 function runListCommand(options) {
     const config = (0, config_1.loadConfig)(options.root);
     const ws = normalizeWorkspace(options.ws);
-    if (ws && !config.workspaces[ws]) {
+    if (ws && !config.workspaces[ws] && !config.bundle_imports[ws]) {
         throw new errors_1.NotFoundError(`workspace not found: ${ws}`);
     }
     const normalizedType = options.type?.toLowerCase();
     if (normalizedType === "skill") {
         throw new errors_1.UsageError("--type skill is no longer supported here; use `mdkg skill list`");
     }
-    const { index, rebuilt, stale } = (0, index_cache_1.loadIndex)({
+    const { index, rebuilt, stale, warnings } = (0, index_cache_1.loadIndex)({
         root: options.root,
         config,
         useCache: !options.noCache,
@@ -34,6 +34,9 @@ function runListCommand(options) {
     if (stale && !rebuilt && !options.noCache) {
         console.error("warning: index is stale; run mdkg index to refresh");
     }
+    for (const warning of warnings) {
+        console.error(`warning: ${warning}`);
+    }
     let epicQid;
     if (options.epic) {
         const resolved = (0, qid_1.resolveQid)(index, options.epic, ws);

package/dist/commands/new.js

@@ -156,6 +156,9 @@ function runNewCommand(options) {
         throw new errors_1.UsageError("title cannot be empty");
     }
     const type = options.type.toLowerCase();
+    if (type === "archive") {
+        throw new errors_1.UsageError("use `mdkg archive add <file>` to create archive sidecars");
+    }
     if (!node_1.ALLOWED_TYPES.has(type)) {
         throw new errors_1.UsageError(`type must be one of ${Array.from(node_1.ALLOWED_TYPES).join(", ")}`);
     }
@@ -286,6 +289,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,

package/dist/commands/next.js

@@ -21,6 +21,9 @@ function selectNextByPriority(index, ws, statusPreference, priorityMax) {
         if (ws && node.ws !== ws) {
             return false;
         }
+        if (node.source?.imported) {
+            return false;
+        }
         if (!NEXT_TYPES.has(node.type)) {
             return false;
         }
@@ -59,6 +62,10 @@ function runNextCommand(options) {
             throw new errors_1.NotFoundError((0, qid_1.formatResolveError)("id", options.id, resolved, ws));
         }
         const node = index.nodes[resolved.qid];
+        if (node.source?.imported) {
+            console.error("no local next item: imported bundle nodes are read-only planning context");
+            return;
+        }
         const nextQid = node.edges.next;
         if (nextQid && index.nodes[nextQid]) {
             console.log((0, node_card_1.formatNodeCard)(index.nodes[nextQid]));

package/dist/commands/node_card.js

@@ -7,11 +7,14 @@ function formatStatusPriority(node) {
     return `${status}/${priority}`;
 }
 function formatNodeCard(node) {
+    const sourceLabel = node.source?.imported
+        ? ` | import:${node.source.import_alias}${node.source.stale ? ":stale" : ""} | read-only`
+        : "";
     return [
         node.qid,
         node.type,
         formatStatusPriority(node),
         node.title,
         node.path,
-    ].join(" | ");
+    ].join(" | ") + sourceLabel;
 }