mdkg 0.1.3 → 0.1.4

package/dist/graph/{bundle_imports.js → subgraphs.js}

@@ -3,13 +3,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveBundleImportsIndexPath = resolveBundleImportsIndexPath;
-exports.buildBundleImportsIndex = buildBundleImportsIndex;
-exports.writeBundleImportsIndex = writeBundleImportsIndex;
-exports.isBundleImportsIndexStale = isBundleImportsIndexStale;
-exports.mergeBundleImportsIntoIndex = mergeBundleImportsIntoIndex;
-exports.importWarnings = importWarnings;
-exports.buildImportedCapabilityRecords = buildImportedCapabilityRecords;
+exports.resolveSubgraphsIndexPath = resolveSubgraphsIndexPath;
+exports.buildSubgraphsIndex = buildSubgraphsIndex;
+exports.writeSubgraphsIndex = writeSubgraphsIndex;
+exports.isSubgraphsIndexStale = isSubgraphsIndexStale;
+exports.mergeSubgraphsIntoIndex = mergeSubgraphsIntoIndex;
+exports.subgraphWarnings = subgraphWarnings;
+exports.buildSubgraphCapabilityRecords = buildSubgraphCapabilityRecords;
 const crypto_1 = __importDefault(require("crypto"));
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -17,7 +17,7 @@ const child_process_1 = require("child_process");
 const paths_1 = require("../core/paths");
 const atomic_1 = require("../util/atomic");
 const zip_1 = require("../util/zip");
-const IMPORTS_CACHE_VERSION = 1;
+const SUBGRAPHS_CACHE_VERSION = 1;
 const MANIFEST_ENTRY = "manifest.json";
 const GLOBAL_INDEX_ENTRY = ".mdkg/index/global.json";
 const SKILLS_INDEX_ENTRY = ".mdkg/index/skills.json";
@@ -38,8 +38,8 @@ function readJsonEntry(entries, entryPath) {
 function readBundleEntries(bundlePath) {
     return new Map((0, zip_1.readZipEntries)(fs_1.default.readFileSync(bundlePath)).map((entry) => [entry.name, entry.data]));
 }
-function resolveBundlePath(root, entry) {
-    return path_1.default.resolve(root, entry.path);
+function resolveBundlePath(root, source) {
+    return path_1.default.resolve(root, source.path);
 }
 function gitOutput(cwd, args) {
     const result = (0, child_process_1.spawnSync)("git", args, { cwd, encoding: "utf8", stdio: "pipe" });
@@ -49,13 +49,13 @@ function gitOutput(cwd, args) {
     const output = result.stdout.trim();
     return output.length > 0 ? output : null;
 }
-function sourcePathState(root, entry, manifest, warnings, errors) {
-    if (!entry.source_path) {
+function sourcePathState(root, subgraph, manifest, warnings, errors) {
+    if (!subgraph.source_path) {
         return false;
     }
-    const sourceRoot = path_1.default.resolve(root, entry.source_path);
+    const sourceRoot = path_1.default.resolve(root, subgraph.source_path);
     if (!fs_1.default.existsSync(sourceRoot)) {
-        errors.push(`source_path does not exist: ${entry.source_path}`);
+        errors.push(`source_path does not exist: ${subgraph.source_path}`);
         return false;
     }
     const currentHead = gitOutput(sourceRoot, ["rev-parse", "HEAD"]);
@@ -66,20 +66,17 @@ function sourcePathState(root, entry, manifest, warnings, errors) {
         stale = true;
     }
     if (currentStatus) {
-        warnings.push(`source_path has uncommitted changes: ${entry.source_path}`);
+        warnings.push(`source_path has uncommitted changes: ${subgraph.source_path}`);
         stale = true;
     }
     return stale;
 }
-function ageState(bundlePath, entry, warnings) {
-    if (entry.max_stale_seconds === undefined) {
-        return false;
-    }
+function ageState(bundlePath, maxStaleSeconds, warnings) {
     const ageSeconds = Math.floor((Date.now() - fs_1.default.statSync(bundlePath).mtimeMs) / 1000);
-    if (ageSeconds <= entry.max_stale_seconds) {
+    if (ageSeconds <= maxStaleSeconds) {
         return false;
     }
-    warnings.push(`bundle age ${ageSeconds}s exceeds max_stale_seconds ${entry.max_stale_seconds}`);
+    warnings.push(`bundle age ${ageSeconds}s exceeds max_stale_seconds ${maxStaleSeconds}`);
     return true;
 }
 function remapTarget(target, qidMap) {
@@ -131,72 +128,147 @@ function entryHashErrors(entries, manifest) {
     }
     return errors;
 }
-function projectOneImport(root, alias, entry) {
-    const bundlePath = resolveBundlePath(root, entry);
+function projectOneSource(root, subgraph, source) {
+    const bundlePath = resolveBundlePath(root, source);
     const relativeBundlePath = toPosixPath(path_1.default.relative(root, bundlePath));
     const warnings = [];
     const errors = [];
-    const nodes = {};
-    const reverse_edges = {};
     let manifest;
-    let sourceIndex;
+    let index;
+    let entries;
     let stale = false;
-    if (!entry.enabled) {
+    if (!source.enabled) {
         return {
-            health: {
-                alias,
-                path: entry.path,
+            source,
+            relativeBundlePath,
+            sourceHealth: {
+                label: source.label,
+                path: source.path,
                 enabled: false,
-                visibility: entry.visibility,
-                expected_profile: entry.expected_profile,
+                expected_profile: source.expected_profile,
                 stale: false,
                 warning_count: 0,
                 error_count: 0,
                 warnings: [],
                 errors: [],
             },
-            nodes,
-            reverse_edges,
         };
     }
     try {
         if (!fs_1.default.existsSync(bundlePath)) {
-            throw new Error(`bundle not found: ${entry.path}`);
+            throw new Error(`bundle not found: ${source.path}`);
         }
-        const entries = readBundleEntries(bundlePath);
+        entries = readBundleEntries(bundlePath);
         manifest = readJsonEntry(entries, MANIFEST_ENTRY);
-        sourceIndex = readJsonEntry(entries, GLOBAL_INDEX_ENTRY);
+        index = readJsonEntry(entries, GLOBAL_INDEX_ENTRY);
         readJsonEntry(entries, SKILLS_INDEX_ENTRY);
         readJsonEntry(entries, CAPABILITIES_INDEX_ENTRY);
         errors.push(...entryHashErrors(entries, manifest));
-        if (manifest.profile !== entry.expected_profile) {
-            errors.push(`expected ${entry.expected_profile} bundle but found ${manifest.profile}`);
+        if (manifest.profile !== source.expected_profile) {
+            errors.push(`expected ${source.expected_profile} bundle but found ${manifest.profile}`);
         }
-        stale = sourcePathState(root, entry, manifest, warnings, errors) || stale;
-        stale = ageState(bundlePath, entry, warnings) || stale;
-        const idOwners = new Map();
-        for (const node of Object.values(sourceIndex.nodes)) {
+        stale = sourcePathState(root, subgraph, manifest, warnings, errors) || stale;
+        stale = ageState(bundlePath, subgraph.max_stale_seconds, warnings) || stale;
+    }
+    catch (err) {
+        errors.push(err instanceof Error ? err.message : String(err));
+    }
+    return {
+        source,
+        relativeBundlePath,
+        manifest,
+        index,
+        entries,
+        sourceHealth: {
+            label: source.label,
+            path: source.path,
+            enabled: source.enabled,
+            expected_profile: source.expected_profile,
+            profile: manifest?.profile,
+            bundle_hash: manifest?.bundle_hash,
+            source_git_head: manifest?.source?.git_head ?? null,
+            stale,
+            warning_count: warnings.length,
+            error_count: errors.length,
+            warnings,
+            errors,
+        },
+    };
+}
+function projectOneSubgraph(root, alias, subgraph) {
+    const nodes = {};
+    const reverse_edges = {};
+    if (!subgraph.enabled) {
+        return {
+            health: {
+                alias,
+                enabled: false,
+                visibility: subgraph.visibility,
+                permissions: subgraph.permissions,
+                source_path: subgraph.source_path,
+                source_repo: subgraph.source_repo,
+                stale: false,
+                warning_count: 0,
+                error_count: 0,
+                warnings: [],
+                errors: [],
+                sources: subgraph.sources.map((source) => ({
+                    label: source.label,
+                    path: source.path,
+                    enabled: source.enabled,
+                    expected_profile: source.expected_profile,
+                    stale: false,
+                    warning_count: 0,
+                    error_count: 0,
+                    warnings: [],
+                    errors: [],
+                })),
+            },
+            nodes,
+            reverse_edges,
+        };
+    }
+    const loadedSources = subgraph.sources.map((source) => projectOneSource(root, subgraph, source));
+    const warnings = loadedSources.flatMap((item) => item.sourceHealth.warnings);
+    const errors = loadedSources.flatMap((item) => item.sourceHealth.errors);
+    const stale = loadedSources.some((item) => item.sourceHealth.stale);
+    const idOwners = new Map();
+    for (const loaded of loadedSources) {
+        if (!loaded.source.enabled || loaded.sourceHealth.error_count > 0 || !loaded.index) {
+            continue;
+        }
+        for (const node of Object.values(loaded.index.nodes)) {
             const owners = idOwners.get(node.id) ?? [];
-            owners.push(node.qid);
+            owners.push(`${loaded.source.label ?? loaded.source.path}:${node.qid}`);
             idOwners.set(node.id, owners);
         }
-        for (const [id, owners] of idOwners.entries()) {
-            if (owners.length > 1) {
-                errors.push(`duplicate projected id ${id} from ${owners.join(", ")}; create per-workspace bundles or use portable unique ids`);
-            }
+    }
+    for (const [id, owners] of idOwners.entries()) {
+        if (owners.length > 1) {
+            errors.push(`duplicate projected id ${id} from ${owners.join(", ")}; split sources into separate subgraphs or use portable unique ids`);
         }
-        if (errors.length === 0) {
-            const qidMap = new Map();
-            for (const node of Object.values(sourceIndex.nodes)) {
+    }
+    if (errors.length === 0) {
+        const qidMap = new Map();
+        for (const loaded of loadedSources) {
+            if (!loaded.source.enabled || !loaded.index) {
+                continue;
+            }
+            for (const node of Object.values(loaded.index.nodes)) {
                 qidMap.set(node.qid, `${alias}:${node.id}`);
             }
-            for (const node of Object.values(sourceIndex.nodes)) {
+        }
+        for (const loaded of loadedSources) {
+            if (!loaded.source.enabled || !loaded.index) {
+                continue;
+            }
+            for (const node of Object.values(loaded.index.nodes)) {
                 const projectedQid = qidMap.get(node.qid);
                 const projected = {
                     ...node,
                     ws: alias,
                     qid: projectedQid,
-                    path: `${relativeBundlePath}#${toPosixPath(node.path)}`,
+                    path: `${loaded.relativeBundlePath}#${toPosixPath(node.path)}`,
                     attributes: { ...(node.attributes ?? {}) },
                     edges: {
                         epic: remapTarget(node.edges.epic, qidMap),
@@ -210,18 +282,19 @@ function projectOneImport(root, alias, entry) {
                     source: {
                         imported: true,
                         read_only: true,
-                        import_alias: alias,
+                        subgraph_alias: alias,
                         original_qid: node.qid,
                         original_ws: node.ws,
                         original_path: toPosixPath(node.path),
-                        bundle_path: relativeBundlePath,
-                        bundle_hash: manifest.bundle_hash,
-                        profile: manifest.profile,
-                        visibility: entry.visibility,
+                        bundle_path: loaded.relativeBundlePath,
+                        bundle_hash: loaded.manifest?.bundle_hash,
+                        profile: loaded.manifest?.profile,
+                        visibility: subgraph.visibility,
+                        permissions: subgraph.permissions,
                         stale,
                         warnings: [...warnings],
-                        source_repo: entry.source_repo ?? manifest.source?.repo,
-                        source_git_head: manifest.source?.git_head ?? null,
+                        source_repo: subgraph.source_repo ?? loaded.manifest?.source?.repo,
+                        source_git_head: loaded.manifest?.source?.git_head ?? null,
                     },
                 };
                 nodes[projected.qid] = projected;
@@ -229,46 +302,41 @@ function projectOneImport(root, alias, entry) {
             }
         }
     }
-    catch (err) {
-        errors.push(err instanceof Error ? err.message : String(err));
-    }
     return {
         health: {
             alias,
-            path: entry.path,
-            enabled: entry.enabled,
-            visibility: entry.visibility,
-            expected_profile: entry.expected_profile,
-            profile: manifest?.profile,
-            bundle_hash: manifest?.bundle_hash,
-            source_git_head: manifest?.source?.git_head ?? null,
-            source_repo: entry.source_repo ?? manifest?.source?.repo,
+            enabled: subgraph.enabled,
+            visibility: subgraph.visibility,
+            permissions: subgraph.permissions,
+            source_path: subgraph.source_path,
+            source_repo: subgraph.source_repo,
             stale,
             warning_count: warnings.length,
             error_count: errors.length,
             warnings,
             errors,
+            sources: loadedSources.map((item) => item.sourceHealth),
         },
         nodes,
         reverse_edges,
     };
 }
-function resolveBundleImportsIndexPath(root) {
-    return path_1.default.resolve(root, ".mdkg", "index", "imports.json");
+function resolveSubgraphsIndexPath(root) {
+    return path_1.default.resolve(root, ".mdkg", "index", "subgraphs.json");
 }
-function buildBundleImportsIndex(root, config) {
-    const imports = [];
+function buildSubgraphsIndex(root, config) {
+    const subgraphs = [];
     const nodes = {};
     const reverse_edges = {};
     const workspaces = {};
-    for (const alias of Object.keys(config.bundle_imports).sort()) {
-        const entry = config.bundle_imports[alias];
-        const projected = projectOneImport(root, alias, entry);
-        imports.push(projected.health);
-        if (!entry.enabled || projected.health.error_count > 0) {
+    for (const alias of Object.keys(config.subgraphs).sort()) {
+        const subgraph = config.subgraphs[alias];
+        const projected = projectOneSubgraph(root, alias, subgraph);
+        subgraphs.push(projected.health);
+        if (!subgraph.enabled || projected.health.error_count > 0) {
             continue;
         }
-        workspaces[alias] = { path: `bundle:${entry.path}`, enabled: true };
+        workspaces[alias] = { path: `subgraph:${alias}`, enabled: true };
         Object.assign(nodes, projected.nodes);
         for (const [edgeKey, targets] of Object.entries(projected.reverse_edges)) {
             reverse_edges[edgeKey] = reverse_edges[edgeKey] ?? {};
@@ -285,44 +353,46 @@ function buildBundleImportsIndex(root, config) {
             meta: {
                 tool: config.tool,
                 schema_version: config.schema_version,
-                cache_version: IMPORTS_CACHE_VERSION,
+                cache_version: SUBGRAPHS_CACHE_VERSION,
                 generated_at: new Date().toISOString(),
                 root,
-                import_count: imports.length,
+                subgraph_count: subgraphs.length,
                 node_count: Object.keys(nodes).length,
             },
-            imports,
+            subgraphs,
             nodes,
             reverse_edges,
         },
         workspaces,
     };
 }
-function writeBundleImportsIndex(indexPath, index) {
+function writeSubgraphsIndex(indexPath, index) {
     (0, atomic_1.atomicWriteFile)(indexPath, JSON.stringify(index, null, 2));
 }
-function isBundleImportsIndexStale(root, config) {
-    const indexPath = resolveBundleImportsIndexPath(root);
+function isSubgraphsIndexStale(root, config) {
+    const indexPath = resolveSubgraphsIndexPath(root);
     if (!fs_1.default.existsSync(indexPath)) {
-        return Object.keys(config.bundle_imports).length > 0;
+        return Object.keys(config.subgraphs).length > 0;
     }
     const indexMtime = fs_1.default.statSync(indexPath).mtimeMs;
     const cfgPath = (0, paths_1.configPath)(root);
     if (fs_1.default.existsSync(cfgPath) && fs_1.default.statSync(cfgPath).mtimeMs > indexMtime) {
         return true;
     }
-    for (const entry of Object.values(config.bundle_imports)) {
-        const bundlePath = path_1.default.resolve(root, entry.path);
-        if (!fs_1.default.existsSync(bundlePath)) {
-            return true;
-        }
-        if (fs_1.default.statSync(bundlePath).mtimeMs > indexMtime) {
-            return true;
+    for (const subgraph of Object.values(config.subgraphs)) {
+        for (const source of subgraph.sources) {
+            const bundlePath = path_1.default.resolve(root, source.path);
+            if (!fs_1.default.existsSync(bundlePath)) {
+                return true;
+            }
+            if (fs_1.default.statSync(bundlePath).mtimeMs > indexMtime) {
+                return true;
+            }
         }
     }
     return false;
 }
-function mergeBundleImportsIntoIndex(base, projection) {
+function mergeSubgraphsIntoIndex(base, projection) {
     const nodes = { ...base.nodes, ...projection.index.nodes };
     const reverse_edges = JSON.parse(JSON.stringify(base.reverse_edges));
     for (const [edgeKey, targets] of Object.entries(projection.index.reverse_edges)) {
@@ -348,70 +418,74 @@ function mergeBundleImportsIntoIndex(base, projection) {
         reverse_edges,
     };
 }
-function importWarnings(projection) {
+function subgraphWarnings(projection) {
     const warnings = [];
-    for (const item of projection.index.imports) {
+    for (const item of projection.index.subgraphs) {
         for (const warning of item.warnings) {
-            warnings.push(`bundle import ${item.alias}: ${warning}`);
+            warnings.push(`subgraph ${item.alias}: ${warning}`);
         }
         for (const error of item.errors) {
-            warnings.push(`bundle import ${item.alias}: ${error}`);
+            warnings.push(`subgraph ${item.alias}: ${error}`);
         }
     }
     return warnings;
 }
-function buildImportedCapabilityRecords(root, config) {
+function buildSubgraphCapabilityRecords(root, config) {
     const records = [];
     const warnings = [];
-    for (const alias of Object.keys(config.bundle_imports).sort()) {
-        const entry = config.bundle_imports[alias];
-        if (!entry.enabled) {
+    for (const alias of Object.keys(config.subgraphs).sort()) {
+        const subgraph = config.subgraphs[alias];
+        if (!subgraph.enabled) {
             continue;
         }
-        const projection = projectOneImport(root, alias, entry);
+        const projection = projectOneSubgraph(root, alias, subgraph);
         for (const warning of projection.health.warnings) {
-            warnings.push(`bundle import ${alias}: ${warning}`);
+            warnings.push(`subgraph ${alias}: ${warning}`);
         }
         for (const error of projection.health.errors) {
-            warnings.push(`bundle import ${alias}: ${error}`);
+            warnings.push(`subgraph ${alias}: ${error}`);
         }
         if (projection.health.error_count > 0) {
             continue;
         }
-        try {
-            const bundlePath = resolveBundlePath(root, entry);
-            const relativeBundlePath = toPosixPath(path_1.default.relative(root, bundlePath));
-            const entries = readBundleEntries(bundlePath);
-            const capabilities = readJsonEntry(entries, CAPABILITIES_INDEX_ENTRY);
-            for (const record of capabilities.records ?? []) {
-                const id = String(record.id ?? "");
-                const originalQid = String(record.qid ?? id);
-                const originalWorkspace = String(record.workspace ?? "");
-                const originalPath = String(record.path ?? "");
-                records.push({
-                    ...record,
-                    workspace: alias,
-                    visibility: entry.visibility,
-                    qid: `${alias}:${id}`,
-                    path: `${relativeBundlePath}#${originalPath}`,
-                    source: {
-                        imported: true,
-                        read_only: true,
-                        import_alias: alias,
-                        original_qid: originalQid,
-                        original_workspace: originalWorkspace,
-                        original_path: originalPath,
-                        bundle_path: relativeBundlePath,
-                        bundle_hash: projection.health.bundle_hash,
-                        profile: projection.health.profile,
-                        stale: projection.health.stale,
-                        warnings: [...projection.health.warnings],
-                    },
-                });
+        for (const source of subgraph.sources) {
+            if (!source.enabled) {
+                continue;
+            }
+            try {
+                const bundlePath = resolveBundlePath(root, source);
+                const relativeBundlePath = toPosixPath(path_1.default.relative(root, bundlePath));
+                const entries = readBundleEntries(bundlePath);
+                const capabilities = readJsonEntry(entries, CAPABILITIES_INDEX_ENTRY);
+                for (const record of capabilities.records ?? []) {
+                    const id = String(record.id ?? "");
+                    const originalQid = String(record.qid ?? id);
+                    const originalWorkspace = String(record.workspace ?? "");
+                    const originalPath = String(record.path ?? "");
+                    records.push({
+                        ...record,
+                        workspace: alias,
+                        visibility: subgraph.visibility,
+                        qid: `${alias}:${id}`,
+                        path: `${relativeBundlePath}#${originalPath}`,
+                        source: {
+                            imported: true,
+                            read_only: true,
+                            subgraph_alias: alias,
+                            original_qid: originalQid,
+                            original_workspace: originalWorkspace,
+                            original_path: originalPath,
+                            bundle_path: relativeBundlePath,
+                            stale: projection.health.stale,
+                            permissions: subgraph.permissions,
+                            warnings: [...projection.health.warnings],
+                        },
+                    });
+                }
+            }
+            catch (err) {
+                warnings.push(`subgraph ${alias}: ${err instanceof Error ? err.message : String(err)}`);
             }
-        }
-        catch (err) {
-            warnings.push(`bundle import ${alias}: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
     return { records, warnings };

package/dist/graph/visibility.js

@@ -45,9 +45,9 @@ function effectiveNodeVisibility(node, config) {
     if (isVisibility(workspaceVisibility)) {
         return workspaceVisibility;
     }
-    const importVisibility = config.bundle_imports[node.ws]?.visibility;
-    if (isVisibility(importVisibility)) {
-        return importVisibility;
+    const subgraphVisibility = config.subgraphs[node.ws]?.visibility;
+    if (isVisibility(subgraphVisibility)) {
+        return subgraphVisibility;
     }
     return "private";
 }

package/dist/init/AGENT_START.md

@@ -31,7 +31,8 @@ Agent operating prompt:
 - 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 subgraph add/list/verify` to register child bundle snapshots as read-only planning context.
+- Use `mdkg capability resolve` to rank local and subgraph capabilities for orchestration planning.
 - 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.

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -92,6 +92,7 @@ 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]`
+- `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`
 - normal task, epic, feat, bug, test, and checkpoint nodes are intentionally excluded
@@ -114,16 +115,24 @@ Graph snapshot bundles:
 - `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
+- public bundle creation fails when public records reference private graph, archive, or subgraph records
+
+Subgraph orchestration:
+- `mdkg subgraph add <alias> <bundle-path> [--visibility private|internal|public] [--profile private|public] [--source-path <path>] [--json]`
+- `mdkg subgraph list [--json]`
+- `mdkg subgraph show <alias> [--json]`
+- `mdkg subgraph rm <alias> [--json]`
+- `mdkg subgraph enable <alias> [--json]`
+- `mdkg subgraph disable <alias> [--json]`
+- `mdkg subgraph verify [alias|--all] [--json]`
+- `mdkg subgraph refresh [alias|--all] [--json]`
+- subgraphs are read-only planning views and use subgraph-alias qids such as `child_repo:task-1`
+- subgraph refresh reloads configured bundle sources only and never mutates child repos
+- public/internal subgraphs 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]`
@@ -135,7 +144,7 @@ Work semantic mirrors:
 - 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
+- work update and artifact commands accept local ids or local qids; subgraph qids are read-only and must be changed in their source workspace
 
 Discovery/show export flags:
 - `--json`

package/dist/init/README.md

@@ -26,11 +26,11 @@ mdkg pack <id>
 mdkg capability search "..."
 mdkg archive list
 mdkg bundle create --profile private
-mdkg bundle import list --json
+mdkg subgraph 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.
+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 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, `mdkg bundle ...` to create full graph snapshot bundles, `mdkg subgraph ...` to register read-only child graph planning views, `mdkg pack <id>` to build deterministic context, and `mdkg validate` before closeout.
 
 Agent workflow docs can use semantic ids:
 
@@ -87,16 +87,17 @@ 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.
+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 subgraph records.
 
-Register child bundle snapshots as read-only imports with:
+Register child bundle snapshots as read-only subgraphs 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
+mdkg subgraph add child_repo child-repo/.mdkg/bundles/private/all.mdkg.zip --source-path child-repo
+mdkg capability resolve "child capability" --json
+mdkg subgraph 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.
+Subgraph nodes use the subgraph alias as their qid prefix and can be inspected or packed, but mutations must happen in the owning child repo.
 
 ## Archive and Work Mirrors
 
@@ -118,7 +119,7 @@ mdkg work receipt new "example receipt" --id receipt.example-1 --work-order-id o
 ```
 
 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.
+Update and artifact commands accept local ids or local qids; subgraph 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.