mdkg 0.1.2 → 0.1.4

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

@@ -3,20 +3,21 @@ 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"));
 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";
@@ -37,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" });
@@ -48,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"]);
@@ -65,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) {
@@ -130,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),
@@ -209,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;
@@ -228,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] ?? {};
@@ -284,45 +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) {
-    fs_1.default.mkdirSync(path_1.default.dirname(indexPath), { recursive: true });
-    fs_1.default.writeFileSync(indexPath, JSON.stringify(index, null, 2), "utf8");
+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

@@ -2,6 +2,8 @@
 
 This repository uses mdkg for deterministic project memory.
 
+mdkg is pre-v1 public alpha software. Treat generated graph, cache, bundle, and DAL contracts as usable but still stabilizing before v1.
+
 Read these files in order:
 1. `.mdkg/core/SOUL.md` if it exists
 2. `.mdkg/core/HUMAN.md` if it exists
@@ -23,12 +25,14 @@ Agent operating prompt:
 - 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 index` to refresh JSON compatibility caches and `.mdkg/index/mdkg.sqlite` when SQLite mode is enabled.
 - 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 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

@@ -22,6 +22,11 @@ Primary commands:
 - `mdkg task`
 - `mdkg validate`
 
+Index backend:
+- fresh mdkg workspaces default to `index.backend: sqlite`
+- `.mdkg/index/mdkg.sqlite` is rebuildable and commit-eligible when intentionally tracked
+- JSON compatibility caches remain generated and ignored by default
+
 Validation commands:
 - `mdkg validate [--out <path>] [--quiet] [--json]`
 
@@ -87,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
@@ -109,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]`
@@ -130,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`