mdkg 0.3.7 → 0.3.9

package/dist/core/config.js

@@ -3,6 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SKILL_MIRROR_TARGETS = void 0;
+exports.defaultCustomizationConfig = defaultCustomizationConfig;
 exports.validateConfigSchema = validateConfigSchema;
 exports.loadConfig = loadConfig;
 const fs_1 = __importDefault(require("fs"));
@@ -30,6 +32,7 @@ const DEFAULT_ARCHIVE_LARGE_CACHE_WARNING_BYTES = 26214400;
 const DEFAULT_SQLITE_COMMIT_WARNING_BYTES = 52428800;
 const DEFAULT_LOCK_TIMEOUT_MS = 10000;
 const DEFAULT_SUBGRAPH_MAX_STALE_SECONDS = 3600;
+exports.DEFAULT_SKILL_MIRROR_TARGETS = [".agents/skills", ".claude/skills"];
 const DEFAULT_PROJECT_DB_CONFIG = {
     enabled: false,
     schema_version: project_db_1.PROJECT_DB_CONFIG_SCHEMA_VERSION,
@@ -41,6 +44,20 @@ const DEFAULT_PROJECT_DB_CONFIG = {
     receipts_path: project_db_1.PROJECT_DB_RECEIPTS_DIR,
     migration_table: project_db_1.PROJECT_DB_MIGRATION_TABLE,
 };
+function defaultCustomizationConfig() {
+    return {
+        standards: {
+            profile: "default",
+            refs: [],
+        },
+        core_docs: {
+            custom_paths: [],
+        },
+        skill_mirrors: {
+            targets: [...exports.DEFAULT_SKILL_MIRROR_TARGETS],
+        },
+    };
+}
 function isObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -171,6 +188,35 @@ function requireKnownLowercaseUniqueStringArray(value, path, allowed, errors, al
     }
     return items;
 }
+function requireUniqueStringArray(value, path, errors, allowEmpty = false) {
+    const items = requireStringArray(value, path, errors);
+    if (items === undefined) {
+        return undefined;
+    }
+    if (items.length === 0) {
+        if (!allowEmpty) {
+            errors.push(`${path} must not be empty`);
+        }
+        return items;
+    }
+    const seen = new Set();
+    for (let i = 0; i < items.length; i += 1) {
+        const item = items[i];
+        if (item.trim().length === 0) {
+            errors.push(`${path}[${i}] must not be empty`);
+            continue;
+        }
+        if (item !== item.trim()) {
+            errors.push(`${path}[${i}] must not include surrounding whitespace`);
+        }
+        if (seen.has(item)) {
+            errors.push(`${path} must not contain duplicate value "${item}"`);
+            continue;
+        }
+        seen.add(item);
+    }
+    return items;
+}
 function requireObject(value, path, errors) {
     if (!isObject(value)) {
         errors.push(`${path} must be an object`);
@@ -213,6 +259,33 @@ function requireContainedPath(value, path, errors) {
         return undefined;
     }
 }
+function requireContainedPathArray(value, path, errors, allowEmpty = true) {
+    if (!Array.isArray(value)) {
+        errors.push(`${path} must be an array of relative paths`);
+        return undefined;
+    }
+    if (value.length === 0) {
+        if (!allowEmpty) {
+            errors.push(`${path} must not be empty`);
+        }
+        return [];
+    }
+    const items = [];
+    const seen = new Set();
+    for (let i = 0; i < value.length; i += 1) {
+        const normalized = requireContainedPath(value[i], `${path}[${i}]`, errors);
+        if (!normalized) {
+            continue;
+        }
+        if (seen.has(normalized)) {
+            errors.push(`${path} must not contain duplicate path "${normalized}"`);
+            continue;
+        }
+        seen.add(normalized);
+        items.push(normalized);
+    }
+    return items;
+}
 function requireSqlIdentifier(value, path, errors) {
     const raw = requireString(value, path, errors);
     if (raw === undefined) {
@@ -266,6 +339,10 @@ function validateConfigSchema(raw) {
         ? { output_dir: ".mdkg/bundles", default_profile: "private" }
         : requireObject(raw.bundles, "bundles", errors);
     const dbRaw = raw.db === undefined ? DEFAULT_PROJECT_DB_CONFIG : requireObject(raw.db, "db", errors);
+    const customizationDefaults = defaultCustomizationConfig();
+    const customizationRaw = raw.customization === undefined
+        ? customizationDefaults
+        : requireObject(raw.customization, "customization", errors);
     if (raw.bundle_imports !== undefined && raw.subgraphs !== undefined) {
         errors.push("config must not define both subgraphs and legacy bundle_imports");
     }
@@ -370,6 +447,60 @@ function validateConfigSchema(raw) {
             };
         }
     }
+    let customization;
+    if (customizationRaw) {
+        const standardsRaw = customizationRaw.standards === undefined
+            ? customizationDefaults.standards
+            : requireObject(customizationRaw.standards, "customization.standards", errors);
+        const coreDocsRaw = customizationRaw.core_docs === undefined
+            ? customizationDefaults.core_docs
+            : requireObject(customizationRaw.core_docs, "customization.core_docs", errors);
+        const skillMirrorsRaw = customizationRaw.skill_mirrors === undefined
+            ? customizationDefaults.skill_mirrors
+            : requireObject(customizationRaw.skill_mirrors, "customization.skill_mirrors", errors);
+        const standardsProfile = standardsRaw
+            ? standardsRaw.profile === undefined
+                ? customizationDefaults.standards.profile
+                : requireString(standardsRaw.profile, "customization.standards.profile", errors)
+            : undefined;
+        const standardsRefs = standardsRaw
+            ? standardsRaw.refs === undefined
+                ? customizationDefaults.standards.refs
+                : requireUniqueStringArray(standardsRaw.refs, "customization.standards.refs", errors, true)
+            : undefined;
+        const coreDocPaths = coreDocsRaw
+            ? coreDocsRaw.custom_paths === undefined
+                ? customizationDefaults.core_docs.custom_paths
+                : requireContainedPathArray(coreDocsRaw.custom_paths, "customization.core_docs.custom_paths", errors, true)
+            : undefined;
+        const mirrorTargets = skillMirrorsRaw
+            ? skillMirrorsRaw.targets === undefined
+                ? customizationDefaults.skill_mirrors.targets
+                : requireContainedPathArray(skillMirrorsRaw.targets, "customization.skill_mirrors.targets", errors, true)
+            : undefined;
+        if (standardsProfile !== undefined) {
+            if (standardsProfile.trim().length === 0) {
+                errors.push("customization.standards.profile must not be empty");
+            }
+            if (standardsProfile !== standardsProfile.trim()) {
+                errors.push("customization.standards.profile must not include surrounding whitespace");
+            }
+        }
+        if (standardsProfile && standardsRefs && coreDocPaths && mirrorTargets) {
+            customization = {
+                standards: {
+                    profile: standardsProfile,
+                    refs: standardsRefs,
+                },
+                core_docs: {
+                    custom_paths: coreDocPaths,
+                },
+                skill_mirrors: {
+                    targets: mirrorTargets,
+                },
+            };
+        }
+    }
     const packLimitsRaw = packRaw ? requireObject(packRaw.limits, "pack.limits", errors) : undefined;
     const pack = packRaw
         ? {
@@ -605,6 +736,7 @@ function validateConfigSchema(raw) {
         capabilities: capabilities,
         bundles: bundles,
         db: db,
+        customization: customization,
         subgraphs,
         pack: pack,
         templates: templates,

package/dist/graph/agent_file_types.js

@@ -3,15 +3,20 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AGENT_ATTRIBUTE_KEY_ORDER = exports.AGENT_FILE_BASENAMES = exports.AGENT_FILE_TYPES = void 0;
+exports.AGENT_ATTRIBUTE_KEY_ORDER = exports.AGENT_FILE_BASENAMES = exports.AGENT_FILE_TYPES = exports.LEGACY_SPEC_BASENAME = exports.CANONICAL_MANIFEST_BASENAME = void 0;
 exports.isAgentFileType = isAgentFileType;
+exports.isManifestSemanticType = isManifestSemanticType;
+exports.collectManifestSiblingConflicts = collectManifestSiblingConflicts;
 exports.validateAgentFileName = validateAgentFileName;
 exports.validateAgentFrontmatter = validateAgentFrontmatter;
 exports.extractAgentAttributes = extractAgentAttributes;
 const path_1 = __importDefault(require("path"));
 const id_1 = require("../util/id");
 const refs_1 = require("../util/refs");
+exports.CANONICAL_MANIFEST_BASENAME = "MANIFEST.md";
+exports.LEGACY_SPEC_BASENAME = "SPEC.md";
 exports.AGENT_FILE_TYPES = [
+    "manifest",
     "spec",
     "work",
     "work_order",
@@ -21,7 +26,8 @@ exports.AGENT_FILE_TYPES = [
     "proposal",
 ];
 exports.AGENT_FILE_BASENAMES = {
-    spec: "SPEC.md",
+    manifest: exports.CANONICAL_MANIFEST_BASENAME,
+    spec: exports.LEGACY_SPEC_BASENAME,
     work: "WORK.md",
     work_order: "WORK_ORDER.md",
     receipt: "RECEIPT.md",
@@ -29,23 +35,25 @@ exports.AGENT_FILE_BASENAMES = {
     dispute: "DISPUTE.md",
     proposal: "PROPOSAL.md",
 };
+const MANIFEST_ATTRIBUTE_KEYS = [
+    "version",
+    "spec_kind",
+    "role",
+    "runtime_mode",
+    "work_contracts",
+    "requested_capabilities",
+    "skill_refs",
+    "tool_refs",
+    "model_refs",
+    "wasm_component_refs",
+    "runtime_image_refs",
+    "subagent_refs",
+    "resource_profile",
+    "update_policy",
+];
 exports.AGENT_ATTRIBUTE_KEY_ORDER = {
-    spec: [
-        "version",
-        "spec_kind",
-        "role",
-        "runtime_mode",
-        "work_contracts",
-        "requested_capabilities",
-        "skill_refs",
-        "tool_refs",
-        "model_refs",
-        "wasm_component_refs",
-        "runtime_image_refs",
-        "subagent_refs",
-        "resource_profile",
-        "update_policy",
-    ],
+    manifest: MANIFEST_ATTRIBUTE_KEYS,
+    spec: MANIFEST_ATTRIBUTE_KEYS,
     work: [
         "version",
         "agent_id",
@@ -207,9 +215,39 @@ function formatError(filePath, message) {
 function isAgentFileType(type) {
     return exports.AGENT_FILE_TYPES.includes(type);
 }
+function isManifestSemanticType(type) {
+    return type === "manifest" || type === "spec";
+}
+function collectManifestSiblingConflicts(filePaths, formatDir) {
+    const basenamesByDir = new Map();
+    for (const filePath of filePaths) {
+        const basename = path_1.default.basename(filePath);
+        if (basename !== exports.CANONICAL_MANIFEST_BASENAME && basename !== exports.LEGACY_SPEC_BASENAME) {
+            continue;
+        }
+        const dirPath = path_1.default.dirname(filePath);
+        const basenames = basenamesByDir.get(dirPath) ?? new Set();
+        basenames.add(basename);
+        basenamesByDir.set(dirPath, basenames);
+    }
+    const conflicts = [];
+    for (const [dirPath, basenames] of Array.from(basenamesByDir.entries()).sort()) {
+        if (basenames.has(exports.CANONICAL_MANIFEST_BASENAME) && basenames.has(exports.LEGACY_SPEC_BASENAME)) {
+            conflicts.push(`${formatDir(dirPath)}: MANIFEST.md and SPEC.md cannot both exist in the same logical Omni unit; keep MANIFEST.md and remove the legacy SPEC.md alias`);
+        }
+    }
+    return conflicts;
+}
 function validateAgentFileName(type, filePath) {
+    const basename = path_1.default.basename(filePath);
+    if (type === "spec" && basename === exports.CANONICAL_MANIFEST_BASENAME) {
+        return;
+    }
     const expected = exports.AGENT_FILE_BASENAMES[type];
-    if (path_1.default.basename(filePath) !== expected) {
+    if (basename !== expected) {
+        if (isManifestSemanticType(type)) {
+            throw formatError(filePath, `manifest files must be named MANIFEST.md (canonical) or SPEC.md (legacy alias); ${type} files must be named ${expected}`);
+        }
         throw formatError(filePath, `${type} files must be named ${expected}`);
     }
 }
@@ -303,7 +341,7 @@ function validateSpecKind(value, filePath) {
     }
     const route = DOCUMENTATION_ONLY_SPEC_KIND_ROUTES[value];
     if (route) {
-        throw formatError(filePath, `spec_kind ${value} is documentation-only; ${route}. SPEC.md must define a reusable invocable capability surface.`);
+        throw formatError(filePath, `spec_kind ${value} is documentation-only; ${route}. MANIFEST.md must define a reusable invocable capability surface; legacy SPEC.md follows the same contract.`);
     }
     throw formatError(filePath, `spec_kind must be one of ${Array.from(SPEC_KIND_VALUES).join(", ")}; documentation-only records belong in normal mdkg nodes such as task, test, epic, goal, checkpoint, EDD, PRD, DEC, bug, feedback, dispute, or proposal.`);
 }
@@ -398,6 +436,7 @@ function validateAgentFrontmatter(type, frontmatter, filePath) {
     const version = expectString(frontmatter, "version", filePath);
     requireSemver(version, "version", filePath);
     switch (type) {
+        case "manifest":
         case "spec": {
             const specKind = optionalString(frontmatter, "spec_kind", filePath);
             if (specKind) {

package/dist/graph/capabilities_indexer.js

@@ -10,6 +10,7 @@ const crypto_1 = __importDefault(require("crypto"));
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const indexer_1 = require("./indexer");
+const agent_file_types_1 = require("./agent_file_types");
 const skills_indexer_1 = require("./skills_indexer");
 exports.CAPABILITIES_INDEX_RELATIVE_PATH = ".mdkg/index/capabilities.json";
 exports.CAPABILITY_KINDS = ["skill", "spec", "work", "core", "design"];
@@ -41,7 +42,7 @@ function workspaceMdkgPrefix(entry) {
     return `${wsPath}${mdkgDir}/`;
 }
 function classifyNodeCapability(node, config) {
-    if (node.type === "spec") {
+    if ((0, agent_file_types_1.isManifestSemanticType)(node.type)) {
         return "spec";
     }
     if (node.type === "work") {
@@ -115,7 +116,7 @@ function resolveWorkSpecs(index, workNode) {
     const candidates = new Map();
     const workRefs = nodeRefSet(workNode);
     for (const node of Object.values(index.nodes)) {
-        if (node.type !== "spec" || node.ws !== workNode.ws) {
+        if (!(0, agent_file_types_1.isManifestSemanticType)(node.type) || node.ws !== workNode.ws) {
             continue;
         }
         const agentId = typeof workNode.attributes.agent_id === "string" ? workNode.attributes.agent_id : undefined;
@@ -159,9 +160,49 @@ function buildCapabilityLinkage(index, node, kind) {
         receipt_qids: receipts.map((receiptNode) => receiptNode.qid),
     };
 }
+function manifestCapabilityMetadata(node) {
+    if (!(0, agent_file_types_1.isManifestSemanticType)(node.type)) {
+        return undefined;
+    }
+    const sourceBasename = path_1.default.posix.basename(node.path);
+    const compatibilityMode = sourceBasename === agent_file_types_1.LEGACY_SPEC_BASENAME
+        ? "legacy"
+        : node.type === "spec"
+            ? "transitional"
+            : "canonical";
+    return {
+        semantic_kind: "manifest",
+        source_basename: sourceBasename,
+        source_type: node.type,
+        canonical_basename: agent_file_types_1.CANONICAL_MANIFEST_BASENAME,
+        legacy_basename: agent_file_types_1.LEGACY_SPEC_BASENAME,
+        compatibility_mode: compatibilityMode,
+        legacy: compatibilityMode !== "canonical",
+        deprecated: compatibilityMode !== "canonical",
+        command_family: "manifest",
+        legacy_command_family: "spec",
+    };
+}
+function manifestSearchAliases(metadata) {
+    if (!metadata) {
+        return [];
+    }
+    return [
+        "manifest",
+        "manifest.md",
+        "MANIFEST.md",
+        "manifest capability",
+        "MANIFEST.md legacy SPEC.md",
+        "spec.md compatibility alias",
+        "legacy spec.md",
+        metadata.compatibility_mode,
+        metadata.source_basename,
+    ];
+}
 function nodeCapabilityRecord(root, config, index, node, kind, indexedAt) {
     const absolutePath = path_1.default.resolve(root, node.path);
     const content = fs_1.default.readFileSync(absolutePath, "utf8");
+    const manifest = kind === "spec" ? manifestCapabilityMetadata(node) : undefined;
     const record = {
         kind,
         workspace: node.ws,
@@ -172,7 +213,7 @@ function nodeCapabilityRecord(root, config, index, node, kind, indexedAt) {
         title: node.title,
         tags: [...node.tags],
         refs: [...node.refs],
-        aliases: [...node.aliases],
+        aliases: Array.from(new Set([...node.aliases, ...manifestSearchAliases(manifest)])),
         links: [...node.links],
         artifacts: [...node.artifacts],
         updated: node.updated,
@@ -182,6 +223,7 @@ function nodeCapabilityRecord(root, config, index, node, kind, indexedAt) {
         node_type: node.type,
     };
     if (kind === "spec") {
+        record.manifest = manifest;
         record.spec = pickAttributes(node.attributes, [
             "version",
             "spec_kind",

package/dist/graph/indexer.js

@@ -10,6 +10,7 @@ const node_1 = require("./node");
 const workspace_files_1 = require("./workspace_files");
 const validate_graph_1 = require("./validate_graph");
 const template_schema_1 = require("./template_schema");
+const agent_file_types_1 = require("./agent_file_types");
 function normalizeEdgeTarget(value, ws) {
     if (value.includes(":")) {
         return value;
@@ -48,6 +49,10 @@ function buildIndex(root, config, options = {}) {
     for (const alias of workspaceAliases) {
         idsByWorkspace[alias] = new Set();
         const files = docFilesByAlias[alias];
+        const manifestConflicts = (0, agent_file_types_1.collectManifestSiblingConflicts)(files, (dirPath) => path_1.default.relative(root, dirPath).split(path_1.default.sep).join("/") || ".");
+        if (manifestConflicts.length > 0 && !tolerant) {
+            throw new Error(manifestConflicts[0]);
+        }
         for (const filePath of files) {
             if (path_1.default.basename(filePath) === "core.md" && path_1.default.basename(path_1.default.dirname(filePath)) === "core") {
                 continue;

package/dist/graph/template_schema.js

@@ -9,6 +9,9 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const frontmatter_1 = require("./frontmatter");
 const builtin_1 = require("../templates/builtin");
+const TEMPLATE_SCHEMA_ALIASES = {
+    spec: "manifest",
+};
 function listMarkdownFiles(dir) {
     if (!fs_1.default.existsSync(dir)) {
         return [];
@@ -46,6 +49,34 @@ function addKeyToSchema(schema, key, kind, filePath) {
         schema.listKeys.add(key);
     }
 }
+function cloneSchema(schema, type) {
+    return {
+        type,
+        allowedKeys: new Set(schema.allowedKeys),
+        keyKinds: { ...schema.keyKinds },
+        listKeys: new Set(schema.listKeys),
+    };
+}
+function loadBundledSchema(type) {
+    const bundledPath = (0, builtin_1.requireBundledTemplatePath)(type);
+    const content = fs_1.default.readFileSync(bundledPath, "utf8");
+    const { frontmatter } = (0, frontmatter_1.parseFrontmatter)(content, bundledPath);
+    const typeValue = frontmatter.type;
+    if (typeValue !== type) {
+        throw new Error(`bundled template fallback type mismatch for ${type}: ${bundledPath}`);
+    }
+    const schema = {
+        type,
+        allowedKeys: new Set(),
+        keyKinds: {},
+        listKeys: new Set(),
+    };
+    for (const [key, value] of Object.entries(frontmatter)) {
+        const kind = getValueKind(value);
+        addKeyToSchema(schema, key, kind, bundledPath);
+    }
+    return schema;
+}
 function loadTemplateSchemas(root, config, requiredTypes) {
     return loadTemplateSchemasWithInfo(root, config, requiredTypes).schemas;
 }
@@ -84,24 +115,13 @@ function loadTemplateSchemasWithInfo(root, config, requiredTypes) {
     if (requiredTypes) {
         const required = Array.from(requiredTypes, (value) => value.toLowerCase());
         for (const missingType of required.filter((value) => !schemas[value])) {
-            const bundledPath = (0, builtin_1.requireBundledTemplatePath)(missingType);
-            const content = fs_1.default.readFileSync(bundledPath, "utf8");
-            const { frontmatter } = (0, frontmatter_1.parseFrontmatter)(content, bundledPath);
-            const typeValue = frontmatter.type;
-            if (typeValue !== missingType) {
-                throw new Error(`bundled template fallback type mismatch for ${missingType}: ${bundledPath}`);
-            }
-            const schema = {
-                type: missingType,
-                allowedKeys: new Set(),
-                keyKinds: {},
-                listKeys: new Set(),
-            };
-            schemas[missingType] = schema;
-            for (const [key, value] of Object.entries(frontmatter)) {
-                const kind = getValueKind(value);
-                addKeyToSchema(schema, key, kind, bundledPath);
+            const aliasType = TEMPLATE_SCHEMA_ALIASES[missingType];
+            if (aliasType) {
+                const aliasSchema = schemas[aliasType] ?? loadBundledSchema(aliasType);
+                schemas[missingType] = cloneSchema(aliasSchema, missingType);
+                continue;
             }
+            schemas[missingType] = loadBundledSchema(missingType);
             fallbackTypes.push(missingType);
         }
     }

package/dist/graph/validate_graph.js

@@ -2,7 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.collectGraphErrors = collectGraphErrors;
 exports.validateGraph = validateGraph;
+const agent_file_types_1 = require("./agent_file_types");
 const refs_1 = require("../util/refs");
+const qid_1 = require("../util/qid");
 const goal_scope_1 = require("./goal_scope");
 function pushError(errors, message) {
     if (errors) {
@@ -147,7 +149,7 @@ function validateAgentWorkflowSpecWorkContracts(index, allowMissing, errors) {
         });
     }
     for (const [qid, node] of Object.entries(index.nodes)) {
-        if (node.type !== "spec") {
+        if (!(0, agent_file_types_1.isManifestSemanticType)(node.type)) {
             continue;
         }
         const workContracts = node.attributes.work_contracts;
@@ -233,7 +235,7 @@ function validateAgentWorkflowReceiptWorkOrderRefs(index, allowMissing, external
 function buildSpecRolesByWorkspace(index) {
     const specRolesByWorkspace = {};
     for (const node of Object.values(index.nodes)) {
-        if (node.type !== "spec") {
+        if (!(0, agent_file_types_1.isManifestSemanticType)(node.type)) {
             continue;
         }
         if (!specRolesByWorkspace[node.ws]) {
@@ -247,8 +249,12 @@ function buildSpecRolesByWorkspace(index) {
     return specRolesByWorkspace;
 }
 function resolveSpecRole(index, ws, value) {
-    const node = resolveTypedNodeRef(index, ws, value, "spec");
-    if (!node) {
+    const resolved = (0, qid_1.resolveQid)(index, value, ws);
+    if (resolved.status !== "ok") {
+        return undefined;
+    }
+    const node = index.nodes[resolved.qid];
+    if (!node || !(0, agent_file_types_1.isManifestSemanticType)(node.type)) {
         return undefined;
     }
     return {
@@ -259,7 +265,7 @@ function resolveSpecRole(index, ws, value) {
 function validateAgentWorkflowSubagentRefs(index, allowMissing, externalWorkspaces, errors) {
     const specRolesByWorkspace = buildSpecRolesByWorkspace(index);
     for (const [qid, node] of Object.entries(index.nodes)) {
-        if (node.type !== "spec" && node.type !== "work") {
+        if (!(0, agent_file_types_1.isManifestSemanticType)(node.type) && node.type !== "work") {
             continue;
         }
         const subagentRefs = node.attributes.subagent_refs;

package/dist/init/AGENT_START.md

@@ -6,14 +6,15 @@ mdkg is pre-v1 public alpha software. Treat generated graph, cache, bundle, and
 
 Read these files in order:
 1. `.mdkg/core/SOUL.md` if it exists
-2. `.mdkg/core/HUMAN.md` if it exists
-3. `.mdkg/README.md`
-4. `CLI_COMMAND_MATRIX.md`
+2. `.mdkg/core/COLLABORATION.md` if it exists
+3. `.mdkg/core/HUMAN.md` if it exists as a legacy alias
+4. `.mdkg/README.md`
+5. `CLI_COMMAND_MATRIX.md`
 
 Trust order:
 - source code
 - mdkg rules, design docs, decisions, and work nodes
-- SOUL/HUMAN collaboration anchors
+- SOUL/COLLABORATION anchors and legacy HUMAN notes
 - relevant skills
 - chat history
 
@@ -29,8 +30,8 @@ Agent operating prompt:
 - Treat goal `required_checks` as report-only guidance from mdkg. Run commands yourself, then record evidence in the goal or active work item.
 - Record skill improvement candidates during normal goal execution; edit `SKILL.md` only when the active node is explicit skill-maintenance work.
 - Use `mdkg skill list`, `mdkg skill search`, and `mdkg skill show <slug>` for skill discovery.
-- Use `mdkg capability list/search/show` for deterministic skills, `SPEC.md`, `WORK.md`, core-doc, and design-doc capability discovery.
-- Use `mdkg spec list/show/validate` for focused optional `SPEC.md` capability records.
+- Use `mdkg capability list/search/show` for deterministic skills, `MANIFEST.md` / legacy `SPEC.md`, `WORK.md`, core-doc, and design-doc capability discovery.
+- Use `mdkg manifest list/show/validate` for focused optional `MANIFEST.md` capability records; `mdkg spec ...` remains a legacy alias for one compatibility release.
 - Use `mdkg index` to refresh JSON compatibility caches and `.mdkg/index/mdkg.sqlite` when SQLite mode is enabled.
 - Treat `.mdkg/db` as project application state; use `mdkg db init` to create
   the generic scaffold and enable `db.enabled` without creating an active
@@ -111,9 +112,9 @@ Capability discovery:
 - `mdkg capability list --kind skill --json`
 - `mdkg capability search "<query>" --kind spec --json`
 - `mdkg capability search "<query>" --kind work --json`
-- `mdkg spec list --json`
-- `mdkg spec show <id-or-qid-or-alias> --json`
-- `mdkg spec validate <id-or-qid-or-alias> --json`
+- `mdkg manifest list --json`
+- `mdkg manifest show <id-or-qid-or-alias> --json`
+- `mdkg manifest validate <id-or-qid-or-alias> --json`
 
 Conventions:
 - `AGENTS.md` is the Codex/OpenAI-oriented wrapper doc.