mdkg 0.1.0 → 0.1.2

package/dist/graph/validate_graph.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.collectGraphErrors = collectGraphErrors;
 exports.validateGraph = validateGraph;
+const refs_1 = require("../util/refs");
 function pushError(errors, message) {
     if (errors) {
         errors.push(message);
@@ -9,7 +10,7 @@ function pushError(errors, message) {
     }
     throw new Error(message);
 }
-function validateEdgeTargets(index, allowMissing, knownSkillSlugs, errors) {
+function validateEdgeTargets(index, allowMissing, knownSkillSlugs, externalWorkspaces, errors) {
     const nodes = index.nodes;
     for (const [qid, node] of Object.entries(nodes)) {
         const edges = node.edges;
@@ -33,6 +34,10 @@ function validateEdgeTargets(index, allowMissing, knownSkillSlugs, errors) {
         for (const [edgeKey, values] of edgeLists) {
             for (const value of values) {
                 if (!nodes[value]) {
+                    const [workspace] = value.split(":");
+                    if (workspace && externalWorkspaces?.has(workspace)) {
+                        continue;
+                    }
                     if (edgeKey === "relates" &&
                         node.type === "proposal" &&
                         node.attributes.proposal_kind === "skill_update" &&
@@ -320,7 +325,11 @@ function buildNodeIdsByWorkspace(index) {
     }
     return nodeIdsByWorkspace;
 }
-function validateAgentWorkflowNodeIdRef(qid, ws, field, value, nodeIdsByWorkspace, allowSkillRef, knownSkillSlugs, allowMissing, errors) {
+function validateAgentWorkflowNodeIdRef(qid, ws, field, value, nodeIdsByWorkspace, allowSkillRef, knownSkillSlugs, externalWorkspaces, allowMissing, errors) {
+    const [workspace] = value.split(":");
+    if (workspace && value.includes(":") && externalWorkspaces?.has(workspace)) {
+        return;
+    }
     if (nodeIdsByWorkspace[ws]?.has(value)) {
         return;
     }
@@ -333,7 +342,7 @@ function validateAgentWorkflowNodeIdRef(qid, ws, field, value, nodeIdsByWorkspac
     }
     pushError(errors, `${qid}: ${field} references missing node ${value}`);
 }
-function validateAgentWorkflowFeedbackProposalRefs(index, allowMissing, knownSkillSlugs, errors) {
+function validateAgentWorkflowFeedbackProposalRefs(index, allowMissing, knownSkillSlugs, externalWorkspaces, errors) {
     const nodeIdsByWorkspace = buildNodeIdsByWorkspace(index);
     for (const [qid, node] of Object.entries(index.nodes)) {
         if (node.type !== "feedback" && node.type !== "proposal") {
@@ -342,7 +351,7 @@ function validateAgentWorkflowFeedbackProposalRefs(index, allowMissing, knownSki
         const targetId = node.attributes.target_id;
         if (typeof targetId === "string") {
             const allowSkillTarget = node.type === "proposal" && node.attributes.proposal_kind === "skill_update";
-            validateAgentWorkflowNodeIdRef(qid, node.ws, "target_id", targetId, nodeIdsByWorkspace, allowSkillTarget, knownSkillSlugs, allowMissing, errors);
+            validateAgentWorkflowNodeIdRef(qid, node.ws, "target_id", targetId, nodeIdsByWorkspace, allowSkillTarget, knownSkillSlugs, externalWorkspaces, allowMissing, errors);
         }
         if (node.type !== "proposal") {
             continue;
@@ -355,7 +364,72 @@ function validateAgentWorkflowFeedbackProposalRefs(index, allowMissing, knownSki
             if (typeof value !== "string") {
                 continue;
             }
-            validateAgentWorkflowNodeIdRef(qid, node.ws, `evidence_refs[${indexValue}]`, value, nodeIdsByWorkspace, true, knownSkillSlugs, allowMissing, errors);
+            validateAgentWorkflowNodeIdRef(qid, node.ws, `evidence_refs[${indexValue}]`, value, nodeIdsByWorkspace, true, knownSkillSlugs, externalWorkspaces, allowMissing, errors);
+        }
+    }
+}
+function buildArchiveIdsByWorkspace(index) {
+    const archiveIdsByWorkspace = {};
+    for (const node of Object.values(index.nodes)) {
+        if (node.type !== "archive") {
+            continue;
+        }
+        if (!archiveIdsByWorkspace[node.ws]) {
+            archiveIdsByWorkspace[node.ws] = new Set();
+        }
+        archiveIdsByWorkspace[node.ws].add(node.id);
+    }
+    return archiveIdsByWorkspace;
+}
+function validateArchiveUriValue(qid, ws, field, value, archiveIdsByWorkspace, allowMissing, errors) {
+    if (!value.startsWith("archive://")) {
+        return;
+    }
+    const archiveId = (0, refs_1.archiveIdFromUri)(value);
+    if (!archiveId) {
+        pushError(errors, `${qid}: ${field} has malformed archive ref ${value}`);
+        return;
+    }
+    if (archiveIdsByWorkspace[ws]?.has(archiveId)) {
+        return;
+    }
+    if (allowMissing) {
+        return;
+    }
+    pushError(errors, `${qid}: ${field} references missing archive ${value}`);
+}
+function validateArchiveUriRefs(index, allowMissing, errors) {
+    const archiveIdsByWorkspace = buildArchiveIdsByWorkspace(index);
+    const attributeListFields = [
+        "input_refs",
+        "constraint_refs",
+        "proof_refs",
+        "attestation_refs",
+    ];
+    const attributeScalarFields = ["request_ref", "cost_ref"];
+    for (const [qid, node] of Object.entries(index.nodes)) {
+        for (const [indexValue, value] of node.artifacts.entries()) {
+            validateArchiveUriValue(qid, node.ws, `artifacts[${indexValue}]`, value, archiveIdsByWorkspace, allowMissing, errors);
+        }
+        const attributes = node.attributes ?? {};
+        for (const field of attributeListFields) {
+            const values = attributes[field];
+            if (!Array.isArray(values)) {
+                continue;
+            }
+            for (const [indexValue, value] of values.entries()) {
+                if (typeof value !== "string") {
+                    continue;
+                }
+                validateArchiveUriValue(qid, node.ws, `${field}[${indexValue}]`, value, archiveIdsByWorkspace, allowMissing, errors);
+            }
+        }
+        for (const field of attributeScalarFields) {
+            const value = attributes[field];
+            if (typeof value !== "string") {
+                continue;
+            }
+            validateArchiveUriValue(qid, node.ws, field, value, archiveIdsByWorkspace, allowMissing, errors);
         }
     }
 }
@@ -396,14 +470,16 @@ function collectGraphErrors(index, options = {}) {
     const errors = [];
     const allowMissing = options.allowMissing ?? false;
     const knownSkillSlugs = options.knownSkillSlugs;
-    validateEdgeTargets(index, allowMissing, knownSkillSlugs, errors);
+    const externalWorkspaces = options.externalWorkspaces;
+    validateEdgeTargets(index, allowMissing, knownSkillSlugs, externalWorkspaces, errors);
     validatePrevNextSymmetry(index, allowMissing, errors);
     validateAgentWorkflowSpecWorkContracts(index, allowMissing, errors);
     validateAgentWorkflowWorkOrderWorkRefs(index, allowMissing, errors);
     validateAgentWorkflowReceiptWorkOrderRefs(index, allowMissing, errors);
     validateAgentWorkflowSubagentRefs(index, allowMissing, errors);
     validateAgentWorkflowDisputeRefs(index, allowMissing, errors);
-    validateAgentWorkflowFeedbackProposalRefs(index, allowMissing, knownSkillSlugs, errors);
+    validateAgentWorkflowFeedbackProposalRefs(index, allowMissing, knownSkillSlugs, externalWorkspaces, errors);
+    validateArchiveUriRefs(index, allowMissing, errors);
     detectPrevNextCycles(index, errors);
     return errors;
 }

package/dist/graph/visibility.js

@@ -0,0 +1,214 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VISIBILITY_VALUES = void 0;
+exports.isVisibility = isVisibility;
+exports.normalizeVisibility = normalizeVisibility;
+exports.isVisibleAt = isVisibleAt;
+exports.isLessVisibleThan = isLessVisibleThan;
+exports.effectiveNodeVisibility = effectiveNodeVisibility;
+exports.collectNodeVisibilityReferences = collectNodeVisibilityReferences;
+exports.collectVisibilityViolations = collectVisibilityViolations;
+exports.visibilityViolationMessages = visibilityViolationMessages;
+const errors_1 = require("../util/errors");
+const refs_1 = require("../util/refs");
+exports.VISIBILITY_VALUES = ["public", "internal", "private"];
+const VISIBILITY_RANK = {
+    public: 0,
+    internal: 1,
+    private: 2,
+};
+function isVisibility(value) {
+    return typeof value === "string" && exports.VISIBILITY_VALUES.includes(value);
+}
+function normalizeVisibility(value, label = "--visibility", fallback = "private") {
+    const normalized = (value ?? fallback).toLowerCase();
+    if (isVisibility(normalized)) {
+        return normalized;
+    }
+    throw new errors_1.UsageError(`${label} must be public, internal, or private`);
+}
+function isVisibleAt(recordVisibility, scope) {
+    return VISIBILITY_RANK[recordVisibility] <= VISIBILITY_RANK[scope];
+}
+function isLessVisibleThan(targetVisibility, sourceVisibility) {
+    return VISIBILITY_RANK[targetVisibility] > VISIBILITY_RANK[sourceVisibility];
+}
+function effectiveNodeVisibility(node, config) {
+    if (node.source?.imported && isVisibility(node.source.visibility)) {
+        return node.source.visibility;
+    }
+    const archiveVisibility = node.attributes.visibility;
+    if (node.type === "archive" && isVisibility(archiveVisibility)) {
+        return archiveVisibility;
+    }
+    const workspaceVisibility = config.workspaces[node.ws]?.visibility;
+    if (isVisibility(workspaceVisibility)) {
+        return workspaceVisibility;
+    }
+    const importVisibility = config.bundle_imports[node.ws]?.visibility;
+    if (isVisibility(importVisibility)) {
+        return importVisibility;
+    }
+    return "private";
+}
+function collectStringValues(value, prefix, out) {
+    if (typeof value === "string") {
+        out.push({ field: prefix, value });
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => collectStringValues(item, `${prefix}[${index}]`, out));
+        return;
+    }
+    if (typeof value === "object" && value !== null) {
+        for (const [key, child] of Object.entries(value)) {
+            collectStringValues(child, prefix ? `${prefix}.${key}` : key, out);
+        }
+    }
+}
+function collectNodeStringReferences(node) {
+    const values = [];
+    const edgeFields = [
+        ["epic", node.edges.epic],
+        ["parent", node.edges.parent],
+        ["prev", node.edges.prev],
+        ["next", node.edges.next],
+    ];
+    for (const [field, value] of edgeFields) {
+        if (value) {
+            values.push({ field, value });
+        }
+    }
+    for (const [index, value] of node.edges.relates.entries()) {
+        values.push({ field: `relates[${index}]`, value });
+    }
+    for (const [index, value] of node.edges.blocked_by.entries()) {
+        values.push({ field: `blocked_by[${index}]`, value });
+    }
+    for (const [index, value] of node.edges.blocks.entries()) {
+        values.push({ field: `blocks[${index}]`, value });
+    }
+    for (const [index, value] of node.links.entries()) {
+        values.push({ field: `links[${index}]`, value });
+    }
+    for (const [index, value] of node.artifacts.entries()) {
+        values.push({ field: `artifacts[${index}]`, value });
+    }
+    for (const [index, value] of node.refs.entries()) {
+        values.push({ field: `refs[${index}]`, value });
+    }
+    collectStringValues(node.attributes, "attributes", values);
+    return values;
+}
+function archiveNodeById(index, workspace, archiveId) {
+    const sameWorkspace = index.nodes[`${workspace}:${archiveId}`];
+    if (sameWorkspace?.type === "archive") {
+        return sameWorkspace;
+    }
+    const matches = Object.values(index.nodes).filter((candidate) => candidate.type === "archive" && candidate.id === archiveId);
+    return matches.length === 1 ? matches[0] : undefined;
+}
+function resolveReferenceTarget(index, source, value) {
+    const archiveId = (0, refs_1.archiveIdFromUri)(value);
+    if (archiveId) {
+        return archiveNodeById(index, source.ws, archiveId);
+    }
+    if ((0, refs_1.isUriRef)(value)) {
+        return undefined;
+    }
+    const exact = index.nodes[value];
+    if (exact) {
+        return exact;
+    }
+    if (!value.includes(":")) {
+        return index.nodes[`${source.ws}:${value}`];
+    }
+    return undefined;
+}
+function collectNodeVisibilityReferences(index, config, node) {
+    const references = [];
+    const seen = new Set();
+    for (const ref of collectNodeStringReferences(node)) {
+        const target = resolveReferenceTarget(index, node, ref.value);
+        if (!target || target.qid === node.qid) {
+            continue;
+        }
+        const key = `${ref.field}\0${ref.value}\0${target.qid}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        references.push({
+            field: ref.field,
+            value: ref.value,
+            targetQid: target.qid,
+            targetVisibility: effectiveNodeVisibility(target, config),
+        });
+    }
+    return references;
+}
+function collectVisibilityViolations(index, config, options = {}) {
+    const violations = [];
+    const qids = options.includedQids
+        ? Object.keys(index.nodes).filter((qid) => options.includedQids?.has(qid))
+        : Object.keys(index.nodes);
+    for (const qid of qids.sort()) {
+        const node = index.nodes[qid];
+        if (!node) {
+            continue;
+        }
+        const sourceVisibility = effectiveNodeVisibility(node, config);
+        if (options.scope && !isVisibleAt(sourceVisibility, options.scope)) {
+            continue;
+        }
+        for (const ref of collectNodeVisibilityReferences(index, config, node)) {
+            if (options.includedQids && !options.includedQids.has(ref.targetQid)) {
+                const target = index.nodes[ref.targetQid];
+                if (!target) {
+                    continue;
+                }
+                const targetVisibility = effectiveNodeVisibility(target, config);
+                if (options.scope && isVisibleAt(targetVisibility, options.scope)) {
+                    continue;
+                }
+                violations.push({
+                    qid: node.qid,
+                    visibility: sourceVisibility,
+                    field: ref.field,
+                    value: ref.value,
+                    target_qid: ref.targetQid,
+                    target_visibility: targetVisibility,
+                    message: `${node.qid} references ${targetVisibility} ${ref.targetQid} through ${ref.field}`,
+                });
+                continue;
+            }
+            if (isLessVisibleThan(ref.targetVisibility, sourceVisibility)) {
+                violations.push({
+                    qid: node.qid,
+                    visibility: sourceVisibility,
+                    field: ref.field,
+                    value: ref.value,
+                    target_qid: ref.targetQid,
+                    target_visibility: ref.targetVisibility,
+                    message: `${node.qid} (${sourceVisibility}) references ${ref.targetVisibility} ${ref.targetQid} through ${ref.field}`,
+                });
+                continue;
+            }
+            if (options.scope && !isVisibleAt(ref.targetVisibility, options.scope)) {
+                violations.push({
+                    qid: node.qid,
+                    visibility: sourceVisibility,
+                    field: ref.field,
+                    value: ref.value,
+                    target_qid: ref.targetQid,
+                    target_visibility: ref.targetVisibility,
+                    message: `${node.qid} references ${ref.targetVisibility} ${ref.targetQid} through ${ref.field}, which is excluded by ${options.scope} visibility`,
+                });
+            }
+        }
+    }
+    return violations;
+}
+function visibilityViolationMessages(violations) {
+    return Array.from(new Set(violations.map((violation) => violation.message))).sort();
+}

package/dist/graph/workspace_files.js

@@ -26,6 +26,26 @@ function listMarkdownFiles(dir) {
     }
     return files;
 }
+function listArchiveSidecarFiles(dir) {
+    if (!fs_1.default.existsSync(dir)) {
+        return [];
+    }
+    const entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        if (entry.name === "source") {
+            continue;
+        }
+        const fullPath = path_1.default.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...listArchiveSidecarFiles(fullPath));
+        }
+        else if (entry.isFile() && entry.name.endsWith(".md")) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
 function getWorkspaceDocRoots(root, config) {
     const roots = [];
     const aliases = Object.keys(config.workspaces).sort();
@@ -46,6 +66,7 @@ function listWorkspaceDocFiles(root, config) {
             const folderPath = path_1.default.join(wsRoot, folder);
             files.push(...listMarkdownFiles(folderPath));
         }
+        files.push(...listArchiveSidecarFiles(path_1.default.join(wsRoot, "archive")));
     }
     return files;
 }
@@ -57,6 +78,7 @@ function listWorkspaceDocFilesByAlias(root, config) {
             const folderPath = path_1.default.join(wsRoot, folder);
             files.push(...listMarkdownFiles(folderPath));
         }
+        files.push(...listArchiveSidecarFiles(path_1.default.join(wsRoot, "archive")));
         files.sort();
         result[alias] = files;
     }

package/dist/init/AGENT_START.md

@@ -22,6 +22,17 @@ Agent operating prompt:
 - Use `mdkg show <id>` for direct inspection and `mdkg show <id> --meta` for card-only inspection.
 - Use `mdkg search "..."` and `mdkg next` to discover current 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 archive add/list/show/verify/compress` for committed source and artifact sidecars under `.mdkg/archive`.
+- Use `mdkg work ...` helpers for semantic mirror contracts, work orders, receipts, and artifact registration.
+- Treat work contracts, orders, and receipts as committed semantic mirrors only; never store raw secrets, credentials, live payment state, ledger mutations, or canonical marketplace state in mdkg.
+- Use `artifact://...` for external/runtime-managed artifacts and `archive://...` for committed mdkg archive sidecars.
+- Use `mdkg bundle create/list/show/verify` for explicit full `.mdkg` graph snapshot bundles.
+- Use `mdkg bundle import add/list/verify` to register child bundle snapshots as read-only planning context.
+- Use `mdkg pack <id> --visibility public|internal` only when you need a public-safe or internal-safe pack; no flag remains private-capable local behavior.
+- Mark archive sidecars public only with explicit `mdkg archive add --visibility public` intent.
+- Treat sidecar `.md` plus deterministic `.zip` caches as the commit-eligible archive record; validation and `mdkg archive verify` both check ZIP payload integrity.
+- Before committing repos that track archive caches or `.mdkg/bundles/`, run `mdkg archive compress --all`, `mdkg archive verify --json`, `mdkg bundle create --profile private`, and `mdkg bundle verify .mdkg/bundles/private/all.mdkg.zip`.
 - Use `mdkg task start/update/done` for structured task, bug, and test lifecycle fields.
 - Use `mdkg upgrade` to preview scaffold updates; only run `mdkg upgrade --apply` after reviewing the receipt.
 - Keep nuanced summaries, body text, and manual parent closeout edits in markdown.
@@ -42,12 +53,22 @@ If no task is known:
 - `mdkg next`
 - then use `mdkg pack <id>`
 
+If this is a fresh import or external docs bundle:
+- create a root epic, PRD, or EDD that captures the imported context and source locations
+- create follow-on tasks and tests from that root context instead of scattering untracked notes
+- run `mdkg validate` after the first ingestion pass
+
 Skill discovery:
 - `mdkg skill list --tags stage:plan --json`
 - `mdkg skill list --tags stage:execute --json`
 - `mdkg skill list --tags stage:review --json`
 - `mdkg skill show select-work-and-ground-context`
 
+Capability discovery:
+- `mdkg capability list --kind skill --json`
+- `mdkg capability search "<query>" --kind spec --json`
+- `mdkg capability search "<query>" --kind work --json`
+
 Conventions:
 - `AGENTS.md` is the Codex/OpenAI-oriented wrapper doc.
 - `CLAUDE.md` is the Claude-oriented wrapper doc.

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -15,6 +15,10 @@ Primary commands:
 - `mdkg search`
 - `mdkg pack`
 - `mdkg skill`
+- `mdkg capability`
+- `mdkg archive`
+- `mdkg bundle`
+- `mdkg work`
 - `mdkg task`
 - `mdkg validate`
 
@@ -42,7 +46,7 @@ Agent workflow notes:
 
 Workspace registry commands:
 - `mdkg workspace ls [--json]`
-- `mdkg workspace add <alias> <path> [--mdkg-dir <dir>] [--json]`
+- `mdkg workspace add <alias> <path> [--mdkg-dir <dir>] [--visibility <level>] [--json]`
 - `mdkg workspace rm <alias> [--json]`
 - `mdkg workspace enable <alias> [--json]`
 - `mdkg workspace disable <alias> [--json]`
@@ -60,15 +64,17 @@ Checkpoint commands:
 - `mdkg checkpoint new <title> [--ws <alias>] [--json]`
 
 Agent bootstrap:
-- `mdkg init --llm`
 - `mdkg init --agent`
-- `mdkg init --llm --agent`
 - published bootstrap config is root-only by default
+- `mdkg init --agent` creates the complete startup docs, wrapper docs, default mdkg skills, event log, registry, and skill mirrors
+- removed flags `--llm`, `--agents`, `--claude`, and `--omni` fail before mutation with guidance to use `mdkg init --agent`
 
 Upgrade:
 - `mdkg upgrade` previews safe scaffold updates and writes nothing by default
 - `mdkg upgrade --apply` updates only managed or unchanged init assets
+- JSON receipts include `safe_to_apply`, `will_write_paths`, `preserved_customizations`, `blocking_conflicts`, and `apply_side_effects`
 - customized docs, templates, skills, and core files are preserved and reported
+- ignored event logs are skipped with guidance to run `mdkg event enable`
 
 Skill discovery:
 - `mdkg skill list --tags stage:plan --json`
@@ -77,6 +83,55 @@ Skill discovery:
 - `mdkg skill validate [<slug>] [--json]`
 - `mdkg skill sync [--force] [--json]`
 
+Capability discovery:
+- `mdkg capability list [--kind <skill|spec|work|core|design>] [--visibility <private|internal|public>] [--json]`
+- `mdkg capability search "<query>" [--kind <kind>] [--visibility <level>] [--json]`
+- `mdkg capability show <id-or-qid-or-slug> [--json]`
+- capability records are deterministic cache projections from Markdown
+- records include source hash, headings, refs, and `indexed_at`
+- normal task, epic, feat, bug, test, and checkpoint nodes are intentionally excluded
+
+Archive sidecars:
+- `mdkg archive add <file> [--id <archive.id>] [--kind source|artifact] [--visibility private|internal|public] [--title <title>] [--refs <...>] [--relates <...>] [--json]`
+- `mdkg archive list [--kind source|artifact] [--visibility private|internal|public] [--ws <alias>] [--json]`
+- `mdkg archive show <id-or-archive-uri> [--ws <alias>] [--json]`
+- `mdkg archive verify [id-or-archive-uri] [--ws <alias>] [--json]`
+- `mdkg archive compress <id-or-archive-uri|--all> [--json]`
+- archive sidecars are `type: archive` nodes under `.mdkg/archive`
+- archive visibility defaults to `private`
+- `mdkg validate` and `mdkg archive verify` both check ZIP hash, ZIP readability, payload SHA-256, and payload byte size
+- outside-repo archive sources are recorded as `external:<basename>` instead of absolute local paths
+- `mdkg doctor` warns about ZIP caches larger than `archive.large_cache_warning_bytes`; `0` disables the warning
+- committed sidecar `.md` files and ZIP caches are source-of-truth evidence; raw source copies under `.mdkg/archive/**/source/` are ignored by default
+
+Graph snapshot bundles:
+- `mdkg bundle create [--profile private|public] [--ws <alias|all>] [--output <path>] [--json]`
+- `mdkg bundle verify [bundle-path] [--json]`
+- `mdkg bundle show <bundle-path> [--json]`
+- `mdkg bundle list [--json]`
+- `mdkg bundle import add/list/rm/enable/disable/verify ...`
+- `mdkg bundle import add <alias> <bundle-path> [--visibility private|internal|public] [--profile private|public] [--source-path <path>] [--json]`
+- `mdkg bundle import verify [alias|--all] [--json]`
+- default output is `.mdkg/bundles/<profile>/<workspace-or-all>.mdkg.zip`
+- private bundles are explicit local graph transport artifacts
+- bundle imports are read-only planning views and use import-alias qids such as `child_repo:task-1`
+- repos that track archive caches or bundles should run `mdkg archive compress --all`, `mdkg archive verify --json`, `mdkg bundle create --profile private`, and `mdkg bundle verify .mdkg/bundles/private/all.mdkg.zip` before commit
+- public bundles include only public workspace content and public archive sidecars
+- public bundle creation fails when public records reference private graph, archive, or imported records
+- public/internal imports require public bundle profiles
+
+Work semantic mirrors:
+- `mdkg work contract new "<title>" --id <work.id> --agent-id <agent.id> --kind <kind> --inputs <...> --outputs <...> [--required-capabilities <...>] [--pricing-model <...>] [--json]`
+- `mdkg work order new "<title>" --id <order.id> --work-id <work.id> --requester <ref> [--request-ref <ref>] [--input-refs <...>] [--requested-outputs <...>] [--json]`
+- `mdkg work order update <id-or-qid> [--status <status>] [--add-input-refs <...>] [--add-artifacts <...>] [--json]`
+- `mdkg work receipt new "<title>" --id <receipt.id> --work-order-id <order.id> --outcome success|partial|failure [--receipt-status recorded|verified|rejected|superseded] [--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]`
+- work commands mutate mdkg semantic mirror files only; production order, receipt, feedback, dispute, payment, ledger, marketplace inventory, fulfillment, and execution state remains canonical outside mdkg
+- do not store raw secrets, credentials, live payment state, ledger mutations, or canonical marketplace state in work mirrors
+- `artifact://...` refs identify external/runtime-managed artifacts; `archive://...` refs identify committed mdkg archive sidecars
+- work update and artifact commands accept local ids or local qids; imported bundle qids are read-only and must be changed in their source workspace
+
 Discovery/show export flags:
 - `--json`
 - `--xml`

package/dist/init/README.md

@@ -8,20 +8,28 @@ This repository is initialized for mdkg.
 - `design/`: product/engineering decision records
 - `work/`: epics, tasks, bugs, tests, checkpoints
 - `templates/`: default node templates
+- `archive/`: sidecar metadata and deterministic compressed source/artifact caches
+- `bundles/`: optional committed full graph snapshot bundles
 - `index/`: generated index cache (do not commit)
 - `pack/`: generated context packs (do not commit)
 
-## First Commands
+## Next Commands
 
 ```bash
-mdkg init --llm --agent
 mdkg upgrade
+mdkg new task "..." --status todo --priority 1
 mdkg search "..."
 mdkg show <id>
 mdkg pack <id>
+mdkg capability search "..."
+mdkg archive list
+mdkg bundle create --profile private
+mdkg bundle import list --json
 mdkg validate
 ```
 
+This repo is already initialized. Use `mdkg upgrade` to preview safe scaffold updates, `mdkg new` to create work, `mdkg search`/`mdkg show` to inspect graph state, `mdkg capability ...` to inspect cached skill/spec/work/core/design capabilities, `mdkg archive ...` to register source/artifact sidecars, `mdkg work ...` to create work contract/order/receipt semantic mirrors, `mdkg bundle ...` to create full graph snapshot bundles and read-only child graph imports, `mdkg pack <id>` to build deterministic context, and `mdkg validate` before closeout.
+
 Agent workflow docs can use semantic ids:
 
 ```bash
@@ -45,6 +53,7 @@ Ensure ignore files include:
 
 - `.mdkg/index/`
 - `.mdkg/pack/`
+- `.mdkg/archive/**/source/`
 
 Recommended:
 
@@ -56,4 +65,52 @@ mdkg init --update-gitignore --update-npmignore
 
 `mdkg upgrade` previews safe scaffold updates for existing workspaces and writes nothing by default.
 
-Use `mdkg upgrade --apply` only after reviewing the receipt. Local customizations are preserved and reported instead of overwritten.
+Use `mdkg upgrade --apply` only after reviewing `safe_to_apply`, `will_write_paths`, and `apply_side_effects` in the receipt. Local customizations are preserved and reported instead of overwritten. Missing built-in templates can be loaded from the installed package as a read-only fallback until you vendor them with upgrade.
+
+## Snapshot Bundles
+
+Create explicit full `.mdkg` graph snapshots with:
+
+```bash
+mdkg archive compress --all
+mdkg archive verify --json
+mdkg bundle create --profile private
+mdkg bundle verify .mdkg/bundles/private/all.mdkg.zip
+```
+
+Use this as a pre-commit recommendation only when the repo tracks archive caches or `.mdkg/bundles/`. Private bundles are local graph transport artifacts and may be tracked in private repos when configured. Public bundles require selected workspaces with `visibility: public` and fail closed when public records reference private graph, archive, or imported records.
+
+Register child bundle snapshots as read-only imports with:
+
+```bash
+mdkg bundle import add child_repo child-repo/.mdkg/bundles/private/all.mdkg.zip --source-path child-repo
+mdkg bundle import verify child_repo --json
+```
+
+Imported nodes use the import alias as their qid prefix and can be inspected or packed, but mutations must happen in the owning child repo.
+
+## Archive and Work Mirrors
+
+Archive source/artifact files with:
+
+```bash
+mdkg archive add <file> --id archive.example --kind source --visibility private
+mdkg archive verify archive://archive.example
+```
+
+`mdkg validate` and `mdkg archive verify` both check the archive sidecar contract and deterministic ZIP payload integrity. Raw local archive source copies under `.mdkg/archive/**/source/` are ignored by default; sidecar `.md` files and ZIP caches are the commit-eligible evidence. Outside-repo sources are recorded as `external:<basename>`, and `mdkg doctor` warns about large ZIP caches using `archive.large_cache_warning_bytes` from `.mdkg/config.json`.
+
+Use work lifecycle helpers for semantic mirrors only:
+
+```bash
+mdkg work contract new "example capability" --id work.example --agent-id agent.example --kind example --inputs prompt:text:required --outputs result:text:required
+mdkg work order new "example request" --id order.example-1 --work-id work.example --requester user://example
+mdkg work receipt new "example receipt" --id receipt.example-1 --work-order-id order.example-1 --outcome success
+```
+
+Receipt statuses are `recorded`, `verified`, `rejected`, and `superseded`.
+Update and artifact commands accept local ids or local qids; imported bundle qids are read-only and must be changed in their source workspace.
+
+Production orders, receipts, feedback, disputes, payments, ledgers, marketplace inventory, fulfillment records, and execution state remain canonical outside mdkg. mdkg stores committed semantic mirrors and reviewable evidence. Do not store raw secrets, credentials, live payment state, ledger mutations, canonical marketplace state, or bulky raw payloads in these mirrors.
+
+Use `artifact://...` for external or runtime-managed artifact identities. Use `archive://...` only for committed mdkg archive sidecars.

package/dist/init/config.json

@@ -2,11 +2,22 @@
   "schema_version": 1,
   "tool": "mdkg",
   "root_required": true,
+  "archive": {
+    "large_cache_warning_bytes": 26214400
+  },
   "index": {
     "auto_reindex": true,
     "tolerant": false,
     "global_index_path": ".mdkg/index/global.json"
   },
+  "capabilities": {
+    "cache_path": ".mdkg/index/capabilities.json"
+  },
+  "bundles": {
+    "output_dir": ".mdkg/bundles",
+    "default_profile": "private"
+  },
+  "bundle_imports": {},
   "pack": {
     "default_depth": 2,
     "default_edges": [
@@ -51,7 +62,8 @@
     "root": {
       "path": ".",
       "enabled": true,
-      "mdkg_dir": ".mdkg"
+      "mdkg_dir": ".mdkg",
+      "visibility": "private"
     }
   }
 }