mdkg 0.3.7 → 0.3.8

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

@@ -29,8 +29,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 +111,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.

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -6,8 +6,9 @@ Verify live help with:
 - `mdkg --help`
 - `mdkg help <command>`
 
-Optional reusable SPEC capability records are accessed through `mdkg spec ...`.
-Repos without SPEC files remain valid.
+Optional reusable manifest capability records are accessed through `mdkg manifest ...`.
+Repos without MANIFEST/SPEC files remain valid. `mdkg spec ...` remains a
+legacy alias for one compatibility release.
 
 Primary commands:
 - `mdkg init`
@@ -20,6 +21,7 @@ Primary commands:
 - `mdkg handoff create <id-or-qid> [--ws <alias>] [--depth <n>] [--out <path>] [--json]`
 - `mdkg skill`
 - `mdkg capability`
+- `mdkg manifest`
 - `mdkg spec`
 - `mdkg archive`
 - `mdkg bundle`
@@ -118,9 +120,11 @@ Project database commands:
 - active `.mdkg/db/runtime/` files and `.mdkg/db` WAL/SHM/journal/lock/temp files are ignored by default
 
 Validation commands:
-- `mdkg validate [--out <path>] [--quiet] [--changed-only] [--json]`
+- `mdkg validate [--out <path>] [--json-out <path>] [--quiet] [--changed-only] [--summary] [--limit <n>] [--json]`
 - `--changed-only` filters warning presentation to changed `.mdkg` files while full graph errors still run
-- JSON receipts include `warning_diagnostics` with warning ids, categories, severity, paths, refs, and remediation text
+- `--summary` emits bounded warning samples for agent/CI logs; `--limit <n>` controls the sample size
+- `--out <path>` writes the compatibility text report; `--json-out <path>` writes a clean full JSON receipt
+- JSON receipts include `warning_summary` and `warning_diagnostics` with warning ids, categories, severity, paths, refs, and remediation text
 
 Node creation commands:
 - `mdkg new <type> "<title>" [options] [--json]`
@@ -128,19 +132,21 @@ Node creation commands:
 - `mdkg new spike "<research question>" [options] [--json]`
 
 Agent workflow file type creation:
-- `mdkg new spec "<title>" [options] [--json]`
+- `mdkg new manifest "<title>" [options] [--json]`
 - `mdkg new work "<title>" [options] [--json]`
 - `mdkg new work_order "<title>" [options] [--json]`
 - `mdkg new receipt "<title>" [options] [--json]`
 - `mdkg new feedback "<title>" [options] [--json]`
 - `mdkg new dispute "<title>" [options] [--json]`
 - `mdkg new proposal "<title>" [options] [--json]`
-- `mdkg new spec "image worker" --id agent.image-worker`
+- `mdkg new spec "<title>" [options] [--json]` is a deprecated alias for
+  `mdkg new manifest` and creates `MANIFEST.md` with `type: manifest`
+- `mdkg new manifest "image worker" --id agent.image-worker`
 - `mdkg new work "generate image" --id work.generate-image`
 
 Agent workflow notes:
 - `--id <portable-id>` is only for agent workflow file types.
-- `spec` and `work` scaffold as validation-clean standalone docs.
+- `manifest` and `work` scaffold as validation-clean standalone docs.
 - `work_order`, `receipt`, `feedback`, `dispute`, and `proposal` need real refs before strict `mdkg validate` passes.
 - `goal` nodes capture recursive objective state and required checks, but normal `mdkg next` does not select them.
 - `spike` nodes are actionable research/planning work under `.mdkg/work/`; use `mdkg task start|update|done` for lifecycle state.
@@ -195,18 +201,25 @@ Capability discovery:
 - `mdkg capability resolve [query] [--requires <capability>] [--fresh-only] [--json]`
 - capability records are deterministic cache projections from Markdown
 - records include source hash, headings, refs, and `indexed_at`
-- SPEC and WORK capability records include read-only `linkage` arrays for related SPECs, work contracts, work orders, and receipts when those graph mirrors exist
+- MANIFEST/SPEC and WORK capability records include read-only `linkage` arrays for related manifests, work contracts, work orders, and receipts when those graph mirrors exist
 - normal task, epic, feat, bug, test, spike, and checkpoint nodes are intentionally excluded
 
-Spec capability records:
+Manifest capability records:
+- `mdkg manifest list [--json]`
+- `mdkg manifest show <id-or-qid-or-alias> [--json]`
+- `mdkg manifest validate [<id-or-qid-or-alias>] [--json]`
+- `MANIFEST.md` is optional; repos with no manifest files still validate
+- manifest records describe reusable capability surfaces, not general planning notes
+- `mdkg manifest validate` with no ref validates the graph and all optional manifest records
+- `mdkg manifest validate <ref>` also checks that the target manifest reference exists
+- `mdkg manifest ...` is the focused manifest command family; `mdkg capability ...` remains broader skill/manifest/work/core/design discovery
+
+Legacy spec capability records:
 - `mdkg spec list [--json]`
 - `mdkg spec show <id-or-qid-or-alias> [--json]`
 - `mdkg spec validate [<id-or-qid-or-alias>] [--json]`
-- `SPEC.md` is optional; repos with no SPEC files still validate
-- SPEC records describe reusable capability surfaces, not general planning notes
-- `mdkg spec validate` with no ref validates the graph and all optional SPEC records
-- `mdkg spec validate <ref>` also checks that the target SPEC reference exists
-- `mdkg spec ...` is the focused SPEC command family; `mdkg capability ...` remains broader skill/spec/work/core/design discovery
+- `mdkg spec ...` is a deprecated alias for `mdkg manifest ...` during the compatibility bridge
+- legacy `SPEC.md` files remain valid for one compatibility release
 
 Archive sidecars:
 - `mdkg archive add <file> [--id <archive.id>] [--kind source|artifact] [--visibility private|internal|public] [--title <title>] [--refs <...>] [--relates <...>] [--json]`
@@ -281,8 +294,8 @@ Work semantic mirrors:
 - `mdkg work receipt verify <id-or-qid> [--json]`
 - `mdkg work receipt update <id-or-qid> [--receipt-status <status>] [--add-artifacts <...>] [--add-proof-refs <...>] [--add-attestation-refs <...>] [--json]`
 - `mdkg work artifact add <order-or-receipt-id-or-qid> <file> [--id <archive.id>] [--kind source|artifact] [--json]`
-- `mdkg work validate [<id-or-qid>] [--type spec|work|work_order|receipt|feedback|dispute|proposal] [--json]`
-- `work trigger` accepts a `WORK.md` ref directly or a `SPEC.md` capability ref with exactly one resolvable work contract; it creates a submitted order mirror and never executes work
+- `mdkg work validate [<id-or-qid>] [--type manifest|spec|work|work_order|receipt|feedback|dispute|proposal] [--json]`
+- `work trigger` accepts a `WORK.md` ref directly or a `MANIFEST.md` / legacy `SPEC.md` capability ref with exactly one resolvable work contract; it creates a submitted order mirror and never executes work
 - example: `mdkg work trigger work.example --id order.example-1 --requester user://example --json`
 - `work trigger --enqueue <queue>` requires a valid project DB plus an explicitly created active queue, creates a submitted order mirror, and enqueues a local delivery message without executing work
 - `work order status` is read-only and reports deterministic order state plus linked receipts

package/dist/init/README.md

@@ -27,7 +27,7 @@ mdkg show <id>
 mdkg pack <id>
 mdkg handoff create <id-or-qid> --json
 mdkg capability search "..."
-mdkg spec list --json
+mdkg manifest list --json
 mdkg archive list
 mdkg bundle create --profile private
 mdkg graph clone .mdkg/bundles/private/all.mdkg.zip --target demos/demo-1 --json
@@ -37,14 +37,14 @@ mdkg fix plan --json
 mdkg validate
 ```
 
-This repo is already initialized. Use `mdkg upgrade` to preview safe scaffold updates, `mdkg index` to create or refresh generated graph/skill/capability/subgraph and SQLite caches after init, `mdkg new` to create work, `mdkg new goal "..."` plus `mdkg goal activate/current/next/claim/evaluate` for recursive long-running objectives, `mdkg search`/`mdkg show` to inspect graph state, `mdkg capability ...` to inspect cached skill/spec/work/core/design capabilities, `mdkg spec ...` for focused optional SPEC records, `mdkg capability resolve ...` to rank local and subgraph capabilities, `mdkg archive ...` to register source/artifact sidecars, `mdkg work ...` to create work contract/order/receipt semantic mirrors and deterministic trigger/verification records, `mdkg bundle ...` to create full graph snapshot bundles, `mdkg graph ...` to clone/fork/import authored graph templates, `mdkg subgraph ...` to register read-only child graph planning views, `mdkg pack <id>` to build deterministic context, `mdkg handoff create <id-or-qid> --json` to create a sanitized copy-ready agent handoff prompt, and `mdkg validate` before closeout.
+This repo is already initialized. Use `mdkg upgrade` to preview safe scaffold updates, `mdkg index` to create or refresh generated graph/skill/capability/subgraph and SQLite caches after init, `mdkg new` to create work, `mdkg new goal "..."` plus `mdkg goal activate/current/next/claim/evaluate` for recursive long-running objectives, `mdkg search`/`mdkg show` to inspect graph state, `mdkg capability ...` to inspect cached skill/manifest/spec/work/core/design capabilities, `mdkg manifest ...` for focused optional manifest records, `mdkg capability resolve ...` to rank local and subgraph capabilities, `mdkg archive ...` to register source/artifact sidecars, `mdkg work ...` to create work contract/order/receipt semantic mirrors and deterministic trigger/verification records, `mdkg bundle ...` to create full graph snapshot bundles, `mdkg graph ...` to clone/fork/import authored graph templates, `mdkg subgraph ...` to register read-only child graph planning views, `mdkg pack <id>` to build deterministic context, `mdkg handoff create <id-or-qid> --json` to create a sanitized copy-ready agent handoff prompt, and `mdkg validate` before closeout.
 
 `mdkg handoff create` summarizes goal/work state, included pack nodes, latest
 checkpoint, boundaries, required checks, next actions, and raw-content marker
 warnings without copying raw node bodies into the prompt. Use `--out` to write
 the handoff artifact inside the repo root.
 
-For large historical graphs, `mdkg validate --changed-only --json` keeps warning review focused on changed `.mdkg` files while full graph errors still run. `mdkg format --headings --dry-run --json` previews missing recommended heading additions before `--apply`.
+For large historical graphs, `mdkg validate --changed-only --json` keeps warning review focused on changed `.mdkg` files while full graph errors still run. `mdkg validate --summary --json --limit 20` keeps agent and CI logs bounded, and `--json-out <path>` writes a clean full JSON receipt artifact. `mdkg format --headings --dry-run --summary --json --limit 20` previews missing recommended heading additions with bounded output before `--apply`.
 
 Use `mdkg status --json` for a read-only operator summary of Git, graph,
 selected-goal, project DB, and generated-cache health before mutating work. Use
@@ -80,15 +80,17 @@ intentionally with `mdkg new task ...` or `mdkg new test ...`.
 Agent workflow docs can use semantic ids:
 
 ```bash
-mdkg new spec "image worker" --id agent.image-worker
+mdkg new manifest "image worker" --id agent.image-worker
 mdkg new work "generate image" --id work.generate-image
 ```
 
-`SPEC.md` is optional. Repos without SPEC files still validate. When present,
-SPEC records describe reusable capability surfaces rather than general planning
-notes. `mdkg spec list/show/validate` is the focused SPEC command family, while
-`mdkg capability ...` remains the broader read-only discovery surface for
-skills, SPECs, WORK contracts, core docs, and design docs.
+`MANIFEST.md` is optional. Repos without manifest files still validate. When
+present, manifest records describe reusable capability surfaces rather than
+general planning notes. `SPEC.md` remains a legacy alias for one compatibility
+release, and `mdkg spec list/show/validate` remains a deprecated alias for
+`mdkg manifest list/show/validate`. `mdkg capability ...` remains the broader
+read-only discovery surface for skills, manifests, WORK contracts, core docs,
+and design docs.
 
 Read `AGENT_START.md` first when this repo includes it.