mdkg 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -4,7 +4,33 @@ All notable changes to mdkg are documented here.
 
 This project follows a pragmatic changelog style inspired by Keep a Changelog. Versions use npm package versions.
 
-## 0.1.3 - Unreleased
+mdkg is pre-v1 public alpha software. Command, graph, cache, bundle, and DAL contracts may change quickly while the project converges on a stable v1 surface.
+
+## 0.1.4 - Unreleased
+
+### Added
+
+- Added `mdkg subgraph add/list/show/rm/enable/disable/verify/refresh` as the public read-only child graph orchestration command family.
+- Added `subgraphs` config with multi-source bundle transport, advisory visibility, read permissions, source metadata, and a default 60 minute freshness policy.
+- Added `.mdkg/index/subgraphs.json` as the derived subgraph projection and health cache.
+- Added `mdkg capability resolve [query] [--requires <capability>] [--fresh-only] [--json]` for deterministic local plus subgraph capability ranking.
+- Added packed-package `smoke:subgraph` coverage for root, child, and grandchild orchestration flows.
+
+### Changed
+
+- Replaced the public `mdkg bundle import ...` surface with `mdkg subgraph ...`; legacy calls now exit with migration guidance.
+- `mdkg upgrade --apply` migrates legacy `bundle_imports` config into `subgraphs`.
+- Read commands, `pack`, and capability discovery now project enabled child bundles as read-only subgraph qids such as `child_repo:work.example`.
+- `mdkg index`, SQLite cache rebuilds, `doctor`, and `validate` now use subgraph naming and metadata instead of bundle-import naming.
+- Stale subgraphs remain usable for planning reads with warnings, fail `mdkg subgraph verify`, and are excluded from `capability resolve --fresh-only`.
+- Public/internal subgraphs require public bundle profiles and public bundle creation fails closed on private/internal subgraph references.
+
+### Fixed
+
+- Mutation commands now reject subgraph qids with explicit guidance to update the source workspace for the owning subgraph.
+- Seeded init docs, command matrix, and release skills now teach `subgraph` and `capability resolve` instead of onboarding users through `bundle import`.
+
+## 0.1.3 - 2026-05-20
 
 ### Added
 

package/README.md

@@ -14,7 +14,7 @@ mdkg stays deliberately boring:
 - first-class rebuildable SQLite cache through built-in `node:sqlite`
 - no daemon, hosted index, or vector DB
 
-Current package version in source: `0.1.3`
+Current package version in source: `0.1.4`
 
 mdkg is still pre-v1 public alpha software. The public package is usable, but graph, cache, bundle, and DAL contracts may continue to change quickly while the project converges on a stable v1 surface.
 
@@ -110,20 +110,21 @@ mdkg bundle verify .mdkg/bundles/private/all.mdkg.zip
 mdkg bundle list --json
 ```
 
-Bundles are explicit graph transport artifacts, separate from task context packs. Before a commit in repos that track archives or bundles, refresh compressed archive caches first, then create the private bundle so the committed graph state is self-consistent. Private bundles are the default and may be committed in private repos when configured. Public bundles require at least one selected workspace with `visibility: public` and include only public workspace content and public archive sidecars; bundle creation fails if public content points at private graph, archive, or imported bundle records.
+Bundles are explicit graph transport artifacts, separate from task context packs. Before a commit in repos that track archives or bundles, refresh compressed archive caches first, then create the private bundle so the committed graph state is self-consistent. Private bundles are the default and may be committed in private repos when configured. Public bundles require at least one selected workspace with `visibility: public` and include only public workspace content and public archive sidecars; bundle creation fails if public content points at private graph, archive, or subgraph records.
 
-Import a child repo bundle as a read-only planning view:
+Register a child repo bundle as a read-only subgraph planning view:
 
 ```bash
-mdkg bundle import add child_repo child-repo/.mdkg/bundles/private/all.mdkg.zip --source-path child-repo
-mdkg bundle import list --json
+mdkg subgraph add child_repo child-repo/.mdkg/bundles/private/all.mdkg.zip --source-path child-repo
+mdkg subgraph list --json
 mdkg search "child capability"
 mdkg show child_repo:work.example
 mdkg pack child_repo:work.example --dry-run --stats
-mdkg bundle import verify child_repo --json
+mdkg capability resolve "child capability" --json
+mdkg subgraph verify child_repo --json
 ```
 
-Imported bundle nodes are projected under the import alias, for example `child_repo:task-1`. They are available to `list`, `search`, `show`, `pack`, and capability discovery, but remain read-only; mutate the child repo and refresh its bundle to change imported content. Stale imports warn during planning reads and fail `mdkg bundle import verify`. Public or internal imports must be backed by public bundle profiles; private imports stay private planning context.
+Subgraph nodes are projected under the subgraph alias, for example `child_repo:task-1`. They are available to `list`, `search`, `show`, `pack`, capability discovery, and `capability resolve`, but remain read-only; mutate the child repo and refresh its bundle to change subgraph content. Stale subgraphs warn during planning reads and fail `mdkg subgraph verify`. Public or internal subgraphs must be backed by public bundle profiles; private subgraphs stay private planning context.
 
 Validate before handoff or commit:
 
@@ -158,7 +159,7 @@ mdkg work artifact add receipt.generate-image-1 ./outputs/image.png --id archive
 ```
 
 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.
 
 Update structured task state and evidence while keeping body and narrative edits in markdown:
 
@@ -206,7 +207,7 @@ mdkg lives under a hidden root directory:
 - `.mdkg/archive/` sidecar metadata plus deterministic compressed source/artifact caches
 - `.mdkg/bundles/` optional committed full graph snapshot bundles
 - `.mdkg/index/mdkg.sqlite` optional committed, rebuildable SQLite access cache
-- `.mdkg/index/imports.json` generated read-only bundle import cache
+- `.mdkg/index/subgraphs.json` generated read-only subgraph projection cache
 - `.agents/skills/` Codex/OpenAI-facing mirrored skills
 - `.claude/skills/` Claude-facing mirrored skills
 - `.mdkg/index/*.json` generated JSON compatibility cache files
@@ -300,7 +301,7 @@ Capability records aggregate enabled registered workspaces and include determini
 
 Fresh `mdkg init` workspaces default to `index.backend: sqlite`, which writes `.mdkg/index/mdkg.sqlite` as a rebuildable access cache using Node's built-in `node:sqlite`. Existing workspaces that are migrated from older configs default to `index.backend: json` until they opt in. Markdown files, archive sidecars, bundle manifests, and config remain source of truth in both modes.
 
-`mdkg index` still writes JSON compatibility caches (`global.json`, `skills.json`, `capabilities.json`, and import projections when configured). In SQLite mode it also rebuilds the SQLite cache with nodes, edges, skills, capabilities, archive metadata, bundle imports, source hashes, and schema metadata. Deleting the SQLite file is recoverable with `mdkg index`.
+`mdkg index` still writes JSON compatibility caches (`global.json`, `skills.json`, `capabilities.json`, and subgraph projections when configured). In SQLite mode it also rebuilds the SQLite cache with nodes, edges, skills, capabilities, archive metadata, subgraphs, source hashes, and schema metadata. Deleting the SQLite file is recoverable with `mdkg index`.
 
 Mutating commands use a workspace mutation lock plus atomic writes. SQLite mode additionally reserves numeric ids in a SQLite transaction before writing Markdown so parallel `mdkg new` and checkpoint calls avoid naming conflicts. Skipped ids after failed writes are acceptable because Markdown remains canonical.
 

package/dist/cli.js

@@ -21,7 +21,7 @@ const doctor_1 = require("./commands/doctor");
 const capability_1 = require("./commands/capability");
 const archive_1 = require("./commands/archive");
 const bundle_1 = require("./commands/bundle");
-const bundle_import_1 = require("./commands/bundle_import");
+const subgraph_1 = require("./commands/subgraph");
 const checkpoint_1 = require("./commands/checkpoint");
 const init_1 = require("./commands/init");
 const new_1 = require("./commands/new");
@@ -60,9 +60,10 @@ function printUsage(log) {
     log("  search      Search nodes by query");
     log("  pack        Generate a context pack");
     log("  skill       Create, list, show, search, and validate skills");
-    log("  capability  List, search, and show cached capability surfaces");
+    log("  capability  List, search, show, and resolve cached capability surfaces");
     log("  archive     Add, list, show, verify, and compress archive sidecars");
     log("  bundle      Create, list, show, and verify full graph snapshot bundles");
+    log("  subgraph    Register and verify read-only child graph snapshots");
     log("  work        Create and update work contracts, orders, receipts, and artifacts");
     log("  task        Start, update, and complete task-like nodes");
     log("  next        Suggest the next work item");
@@ -171,7 +172,7 @@ function printIndexHelp(log) {
     log("  - .mdkg/index/global.json");
     log("  - .mdkg/index/skills.json");
     log("  - .mdkg/index/capabilities.json");
-    log("  - .mdkg/index/imports.json when bundle imports are configured");
+    log("  - .mdkg/index/subgraphs.json when subgraphs are configured");
     log("  - .mdkg/index/mdkg.sqlite when index.backend is sqlite");
     printGlobalOptions(log);
 }
@@ -322,14 +323,23 @@ function printCapabilityHelp(log, subcommand) {
             log("  mdkg capability show <id-or-qid-or-slug> [--json]");
             printGlobalOptions(log);
             return;
+        case "resolve":
+            log("Usage:");
+            log('  mdkg capability resolve [query] [--requires <capability>] [--fresh-only] [--json]');
+            log("\nNotes:");
+            log("  Resolves local and subgraph capabilities with deterministic ranking.");
+            printGlobalOptions(log);
+            return;
         default:
             log("Usage:");
             log("  mdkg capability list [--kind <kind>] [--visibility <level>] [--json]");
             log('  mdkg capability search "<query>" [--kind <kind>] [--visibility <level>] [--json]');
             log("  mdkg capability show <id-or-qid-or-slug> [--json]");
+            log('  mdkg capability resolve [query] [--requires <capability>] [--fresh-only] [--json]');
             log("\nNotes:");
             log("  Capability records are deterministic cache projections from Markdown.");
             log("  Cached kinds: skill, spec, work, core, design.");
+            log("  Resolve includes read-only subgraph capability records when configured.");
             printGlobalOptions(log);
     }
 }
@@ -375,12 +385,8 @@ function printBundleHelp(log, subcommand) {
     switch ((subcommand ?? "").toLowerCase()) {
         case "import":
             log("Usage:");
-            log("  mdkg bundle import add <alias> <bundle-path> [--visibility private|internal|public] [--profile private|public] [--source-path <path>] [--source-repo <ref>] [--max-stale-seconds <seconds>] [--json]");
-            log("  mdkg bundle import list [--json]");
-            log("  mdkg bundle import rm <alias> [--json]");
-            log("  mdkg bundle import enable <alias> [--json]");
-            log("  mdkg bundle import disable <alias> [--json]");
-            log("  mdkg bundle import verify [alias|--all] [--json]");
+            log("  mdkg subgraph add/list/show/rm/enable/disable/verify/refresh ...");
+            log("\n`mdkg bundle import` has been replaced by `mdkg subgraph`.");
             break;
         case "create":
             log("Usage:");
@@ -404,15 +410,66 @@ function printBundleHelp(log, subcommand) {
             log("  mdkg bundle verify [bundle-path] [--json]");
             log("  mdkg bundle show <bundle-path> [--json]");
             log("  mdkg bundle list [--json]");
-            log("  mdkg bundle import add/list/rm/enable/disable/verify ...");
             log("\nNotes:");
             log("  - bundles are explicit full .mdkg graph snapshots, not task context packs");
-            log("  - bundle imports are read-only graph views projected under their import alias");
+            log("  - use `mdkg subgraph ...` to register bundle snapshots as read-only planning views");
             log("  - private is the default profile; public bundles fail closed on private refs");
             log("  - .mdkg/bundles/ is commit-eligible when your repo tracks snapshot bundles");
     }
     printGlobalOptions(log);
 }
+function printSubgraphHelp(log, subcommand) {
+    switch ((subcommand ?? "").toLowerCase()) {
+        case "add":
+            log("Usage:");
+            log("  mdkg subgraph add <alias> <bundle-path> [--visibility private|internal|public] [--profile private|public] [--source-path <path>] [--source-repo <ref>] [--max-stale-seconds <seconds>] [--json]");
+            break;
+        case "list":
+            log("Usage:");
+            log("  mdkg subgraph list [--json]");
+            break;
+        case "show":
+            log("Usage:");
+            log("  mdkg subgraph show <alias> [--json]");
+            break;
+        case "rm":
+        case "remove":
+            log("Usage:");
+            log("  mdkg subgraph rm <alias> [--json]");
+            break;
+        case "enable":
+            log("Usage:");
+            log("  mdkg subgraph enable <alias> [--json]");
+            break;
+        case "disable":
+            log("Usage:");
+            log("  mdkg subgraph disable <alias> [--json]");
+            break;
+        case "verify":
+            log("Usage:");
+            log("  mdkg subgraph verify [alias|--all] [--json]");
+            break;
+        case "refresh":
+            log("Usage:");
+            log("  mdkg subgraph refresh [alias|--all] [--json]");
+            break;
+        default:
+            log("Usage:");
+            log("  mdkg subgraph add <alias> <bundle-path> [--visibility private|internal|public] [--profile private|public] [--source-path <path>] [--source-repo <ref>] [--max-stale-seconds <seconds>] [--json]");
+            log("  mdkg subgraph list [--json]");
+            log("  mdkg subgraph show <alias> [--json]");
+            log("  mdkg subgraph rm <alias> [--json]");
+            log("  mdkg subgraph enable <alias> [--json]");
+            log("  mdkg subgraph disable <alias> [--json]");
+            log("  mdkg subgraph verify [alias|--all] [--json]");
+            log("  mdkg subgraph refresh [alias|--all] [--json]");
+            log("\nNotes:");
+            log("  - subgraphs are read-only graph views backed by explicit bundle snapshots");
+            log("  - default permissions are read-only and default freshness is 3600 seconds");
+            log("  - refresh reloads configured bundle sources only; it does not build child bundles");
+    }
+    printGlobalOptions(log);
+}
 function printWorkHelp(log, subcommand) {
     switch ((subcommand ?? "").toLowerCase()) {
         case "contract":
@@ -444,7 +501,7 @@ function printWorkHelp(log, subcommand) {
             log("  - production order, receipt, feedback, dispute, payment, ledger, marketplace inventory, fulfillment, and execution state remains canonical outside mdkg");
             log("  - do not store raw secrets, credentials, live payment state, ledger mutations, or canonical marketplace state in work mirrors");
             log("  - artifact:// refs identify external/runtime-managed artifacts; archive:// refs identify committed mdkg archive sidecars");
-            log("  - update and artifact commands accept local ids or local qids; imported bundle qids are read-only");
+            log("  - update and artifact commands accept local ids or local qids; subgraph qids are read-only");
     }
     printGlobalOptions(log);
 }
@@ -599,6 +656,9 @@ function printCommandHelp(log, command, subcommand) {
         case "bundle":
             printBundleHelp(log, subcommand);
             return;
+        case "subgraph":
+            printSubgraphHelp(log, subcommand);
+            return;
         case "work":
             printWorkHelp(log, subcommand);
             return;
@@ -871,8 +931,20 @@ function runCapabilitySubcommand(parsed, root) {
             (0, capability_1.runCapabilityShowCommand)({ root, id, json, noCache, noReindex });
             return 0;
         }
+        case "resolve": {
+            const query = parsed.positionals.slice(2).join(" ") || undefined;
+            const kind = requireFlagValue("--kind", parsed.flags["--kind"]);
+            const visibility = requireFlagValue("--visibility", parsed.flags["--visibility"]);
+            const requires = requireFlagValue("--requires", parsed.flags["--requires"]);
+            const freshOnly = parseBooleanFlag("--fresh-only", parsed.flags["--fresh-only"]);
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
+            const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
+            (0, capability_1.runCapabilityResolveCommand)({ root, query, kind, visibility, requires, freshOnly, json, noCache, noReindex });
+            return 0;
+        }
         default:
-            throw new errors_1.UsageError("capability requires list/search/show");
+            throw new errors_1.UsageError("capability requires list/search/show/resolve");
     }
 }
 function runArchiveSubcommand(parsed, root) {
@@ -944,78 +1016,7 @@ function runBundleSubcommand(parsed, root) {
     const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
     switch (subcommand) {
         case "import": {
-            const action = (parsed.positionals[2] ?? "").toLowerCase();
-            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
-            switch (action) {
-                case "add": {
-                    const alias = parsed.positionals[3];
-                    const bundlePath = parsed.positionals[4];
-                    if (!alias || !bundlePath || parsed.positionals.length > 5) {
-                        throw new errors_1.UsageError("bundle import add requires <alias> <bundle-path>");
-                    }
-                    const visibility = requireFlagValue("--visibility", parsed.flags["--visibility"]);
-                    const profile = requireFlagValue("--profile", parsed.flags["--pack-profile"]);
-                    const sourcePath = requireFlagValue("--source-path", parsed.flags["--source-path"]);
-                    const sourceRepo = requireFlagValue("--source-repo", parsed.flags["--source-repo"]);
-                    const maxStaleRaw = requireFlagValue("--max-stale-seconds", parsed.flags["--max-stale-seconds"]);
-                    const maxStaleSeconds = maxStaleRaw === undefined ? undefined : Number.parseInt(maxStaleRaw, 10);
-                    (0, bundle_import_1.runBundleImportAddCommand)({
-                        root,
-                        alias,
-                        bundlePath,
-                        visibility,
-                        profile,
-                        sourcePath,
-                        sourceRepo,
-                        maxStaleSeconds,
-                        json,
-                    });
-                    return 0;
-                }
-                case "list": {
-                    if (parsed.positionals.length > 3) {
-                        throw new errors_1.UsageError("bundle import list does not accept positional arguments");
-                    }
-                    (0, bundle_import_1.runBundleImportListCommand)({ root, json });
-                    return 0;
-                }
-                case "rm":
-                case "remove": {
-                    const alias = parsed.positionals[3];
-                    if (!alias || parsed.positionals.length > 4) {
-                        throw new errors_1.UsageError("bundle import rm requires <alias>");
-                    }
-                    (0, bundle_import_1.runBundleImportRemoveCommand)({ root, alias, json });
-                    return 0;
-                }
-                case "enable": {
-                    const alias = parsed.positionals[3];
-                    if (!alias || parsed.positionals.length > 4) {
-                        throw new errors_1.UsageError("bundle import enable requires <alias>");
-                    }
-                    (0, bundle_import_1.runBundleImportEnableCommand)({ root, alias, json });
-                    return 0;
-                }
-                case "disable": {
-                    const alias = parsed.positionals[3];
-                    if (!alias || parsed.positionals.length > 4) {
-                        throw new errors_1.UsageError("bundle import disable requires <alias>");
-                    }
-                    (0, bundle_import_1.runBundleImportDisableCommand)({ root, alias, json });
-                    return 0;
-                }
-                case "verify": {
-                    if (parsed.positionals.length > 4) {
-                        throw new errors_1.UsageError("bundle import verify accepts at most one alias");
-                    }
-                    const alias = parsed.positionals[3];
-                    const all = parseBooleanFlag("--all", parsed.flags["--all"]);
-                    (0, bundle_import_1.runBundleImportVerifyCommand)({ root, alias, all, json });
-                    return 0;
-                }
-                default:
-                    throw new errors_1.UsageError("bundle import requires add/list/rm/enable/disable/verify");
-            }
+            throw new errors_1.UsageError("mdkg bundle import has been replaced by mdkg subgraph; run `mdkg upgrade --apply` to migrate legacy bundle_imports config");
         }
         case "create": {
             if (parsed.positionals.length > 2) {
@@ -1055,7 +1056,98 @@ function runBundleSubcommand(parsed, root) {
             return 0;
         }
         default:
-            throw new errors_1.UsageError("bundle requires create/list/show/verify/import");
+            throw new errors_1.UsageError("bundle requires create/list/show/verify");
+    }
+}
+function runSubgraphSubcommand(parsed, root) {
+    const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
+    const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+    switch (subcommand) {
+        case "add": {
+            const alias = parsed.positionals[2];
+            const bundlePath = parsed.positionals[3];
+            if (!alias || !bundlePath || parsed.positionals.length > 4) {
+                throw new errors_1.UsageError("subgraph add requires <alias> <bundle-path>");
+            }
+            const visibility = requireFlagValue("--visibility", parsed.flags["--visibility"]);
+            const profile = requireFlagValue("--profile", parsed.flags["--pack-profile"]);
+            const sourcePath = requireFlagValue("--source-path", parsed.flags["--source-path"]);
+            const sourceRepo = requireFlagValue("--source-repo", parsed.flags["--source-repo"]);
+            const maxStaleRaw = requireFlagValue("--max-stale-seconds", parsed.flags["--max-stale-seconds"]);
+            const maxStaleSeconds = maxStaleRaw === undefined ? undefined : Number.parseInt(maxStaleRaw, 10);
+            (0, subgraph_1.runSubgraphAddCommand)({
+                root,
+                alias,
+                bundlePath,
+                visibility,
+                profile,
+                sourcePath,
+                sourceRepo,
+                maxStaleSeconds,
+                json,
+            });
+            return 0;
+        }
+        case "list": {
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("subgraph list does not accept positional arguments");
+            }
+            (0, subgraph_1.runSubgraphListCommand)({ root, json });
+            return 0;
+        }
+        case "show": {
+            const alias = parsed.positionals[2];
+            if (!alias || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("subgraph show requires <alias>");
+            }
+            (0, subgraph_1.runSubgraphShowCommand)({ root, alias, json });
+            return 0;
+        }
+        case "rm":
+        case "remove": {
+            const alias = parsed.positionals[2];
+            if (!alias || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("subgraph rm requires <alias>");
+            }
+            (0, subgraph_1.runSubgraphRemoveCommand)({ root, alias, json });
+            return 0;
+        }
+        case "enable": {
+            const alias = parsed.positionals[2];
+            if (!alias || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("subgraph enable requires <alias>");
+            }
+            (0, subgraph_1.runSubgraphEnableCommand)({ root, alias, json });
+            return 0;
+        }
+        case "disable": {
+            const alias = parsed.positionals[2];
+            if (!alias || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("subgraph disable requires <alias>");
+            }
+            (0, subgraph_1.runSubgraphDisableCommand)({ root, alias, json });
+            return 0;
+        }
+        case "verify": {
+            if (parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("subgraph verify accepts at most one alias");
+            }
+            const alias = parsed.positionals[2];
+            const all = parseBooleanFlag("--all", parsed.flags["--all"]);
+            (0, subgraph_1.runSubgraphVerifyCommand)({ root, alias, all, json });
+            return 0;
+        }
+        case "refresh": {
+            if (parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("subgraph refresh accepts at most one alias");
+            }
+            const alias = parsed.positionals[2];
+            const all = parseBooleanFlag("--all", parsed.flags["--all"]);
+            (0, subgraph_1.runSubgraphRefreshCommand)({ root, alias, all, json });
+            return 0;
+        }
+        default:
+            throw new errors_1.UsageError("subgraph requires add/list/show/rm/enable/disable/verify/refresh");
     }
 }
 function runWorkSubcommand(parsed, root) {
@@ -1567,6 +1659,8 @@ function runCommand(parsed, root, runtime) {
             return runArchiveSubcommand(parsed, root);
         case "bundle":
             return runBundleSubcommand(parsed, root);
+        case "subgraph":
+            return runSubgraphSubcommand(parsed, root);
         case "work":
             return runWorkSubcommand(parsed, root);
         case "task":

package/dist/commands/bundle.js

@@ -13,7 +13,7 @@ const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
 const config_1 = require("../core/config");
 const capabilities_indexer_1 = require("../graph/capabilities_indexer");
-const bundle_imports_1 = require("../graph/bundle_imports");
+const subgraphs_1 = require("../graph/subgraphs");
 const indexer_1 = require("../graph/indexer");
 const skills_indexer_1 = require("../graph/skills_indexer");
 const zip_1 = require("../util/zip");
@@ -386,11 +386,11 @@ function collectStringValues(value, out) {
         }
     }
 }
-function publicImportReferenceErrors(config, index, includedQids) {
-    const privateImportAliases = new Set(Object.entries(config.bundle_imports)
+function publicSubgraphReferenceErrors(config, index, includedQids) {
+    const privateSubgraphAliases = new Set(Object.entries(config.subgraphs)
         .filter(([, entry]) => entry.enabled && entry.visibility !== "public")
         .map(([alias]) => alias));
-    if (privateImportAliases.size === 0) {
+    if (privateSubgraphAliases.size === 0) {
         return [];
     }
     const errors = [];
@@ -404,8 +404,8 @@ function publicImportReferenceErrors(config, index, includedQids) {
         values.push(...node.links, ...node.artifacts, ...node.refs, ...node.aliases);
         for (const value of values) {
             const [alias] = value.split(":");
-            if (alias && privateImportAliases.has(alias)) {
-                errors.push(`${node.qid} references private bundle import ${value}`);
+            if (alias && privateSubgraphAliases.has(alias)) {
+                errors.push(`${node.qid} references private subgraph ${value}`);
             }
         }
     }
@@ -465,7 +465,7 @@ function buildBundle(options) {
     const filteredIndex = filterIndex(index, config, selectedSet, profile);
     if (profile === "public") {
         const includedQids = new Set(Object.keys(filteredIndex.nodes));
-        const mergedIndex = (0, bundle_imports_1.mergeBundleImportsIntoIndex)(index, (0, bundle_imports_1.buildBundleImportsIndex)(options.root, config));
+        const mergedIndex = (0, subgraphs_1.mergeSubgraphsIntoIndex)(index, (0, subgraphs_1.buildSubgraphsIndex)(options.root, config));
         const errors = (0, visibility_1.visibilityViolationMessages)((0, visibility_1.collectVisibilityViolations)(mergedIndex, config, {
             includedQids,
             scope: "public",

package/dist/commands/capability.js

@@ -3,10 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runCapabilityListCommand = runCapabilityListCommand;
 exports.runCapabilitySearchCommand = runCapabilitySearchCommand;
 exports.runCapabilityShowCommand = runCapabilityShowCommand;
+exports.runCapabilityResolveCommand = runCapabilityResolveCommand;
 const config_1 = require("../core/config");
 const capabilities_indexer_1 = require("../graph/capabilities_indexer");
 const capabilities_index_cache_1 = require("../graph/capabilities_index_cache");
-const bundle_imports_1 = require("../graph/bundle_imports");
+const subgraphs_1 = require("../graph/subgraphs");
 const errors_1 = require("../util/errors");
 function normalizeKind(value) {
     if (value === undefined) {
@@ -39,11 +40,11 @@ function loadRecords(options) {
     if (stale && !rebuilt && !options.noCache) {
         console.error("warning: capabilities index is stale; run mdkg index to refresh");
     }
-    const imported = (0, bundle_imports_1.buildImportedCapabilityRecords)(options.root, config);
-    for (const warning of imported.warnings) {
+    const subgraph = (0, subgraphs_1.buildSubgraphCapabilityRecords)(options.root, config);
+    for (const warning of subgraph.warnings) {
         console.error(`warning: ${warning}`);
     }
-    return [...index.records, ...imported.records];
+    return [...index.records, ...subgraph.records];
 }
 function applyFilters(records, options) {
     const kind = normalizeKind(options.kind);
@@ -95,6 +96,89 @@ function matchesQuery(record, query) {
     const text = capabilitySearchText(record);
     return terms.every((term) => text.includes(term));
 }
+function recordSource(record) {
+    const source = record.source;
+    return source ?? {};
+}
+function isStale(record) {
+    return recordSource(record).stale === true;
+}
+function hasReadPermission(record) {
+    const permissions = recordSource(record).permissions;
+    return !Array.isArray(permissions) || permissions.includes("read");
+}
+function requirementMatch(record, required) {
+    if (!required) {
+        return 0;
+    }
+    const normalized = required.toLowerCase();
+    const haystack = [
+        ...record.refs,
+        ...record.tags,
+        JSON.stringify(record.spec ?? {}),
+        JSON.stringify(record.work ?? {}),
+        JSON.stringify(record.skill ?? {}),
+    ]
+        .join(" ")
+        .toLowerCase();
+    return haystack.includes(normalized) ? 1 : 0;
+}
+function linkageScore(record) {
+    let score = 0;
+    if (record.kind === "work") {
+        score += 2;
+    }
+    if (record.kind === "spec") {
+        score += 1;
+    }
+    if (record.work || record.spec) {
+        score += 1;
+    }
+    return score;
+}
+function resolveScore(record, options) {
+    let score = 0;
+    if (record.workspace === "root") {
+        score += 1000;
+    }
+    if (!isStale(record)) {
+        score += 500;
+    }
+    if (hasReadPermission(record)) {
+        score += 100;
+    }
+    if (options.query && matchesQuery(record, options.query)) {
+        score += 50;
+    }
+    score += requirementMatch(record, options.requires) * 25;
+    score += linkageScore(record);
+    return score;
+}
+function resolveCapabilities(records, options) {
+    const filtered = records.filter((record) => {
+        if (options.freshOnly && isStale(record)) {
+            return false;
+        }
+        if (options.query && !matchesQuery(record, options.query)) {
+            return false;
+        }
+        if (options.requires && requirementMatch(record, options.requires) === 0) {
+            return false;
+        }
+        return true;
+    });
+    return filtered.sort((a, b) => {
+        const scoreDelta = resolveScore(b, options) - resolveScore(a, options);
+        if (scoreDelta !== 0) {
+            return scoreDelta;
+        }
+        const qidDelta = a.qid.localeCompare(b.qid);
+        if (qidDelta !== 0) {
+            return qidDelta;
+        }
+        return a.path.localeCompare(b.path);
+    });
+}
 function printCapabilityList(records, json, query) {
     if (json) {
         console.log(JSON.stringify({
@@ -160,3 +244,33 @@ function runCapabilityShowCommand(options) {
     const records = loadRecords(options);
     printCapability(resolveCapability(records, options.id), options.json);
 }
+function runCapabilityResolveCommand(options) {
+    const records = applyFilters(loadRecords(options), options);
+    const items = resolveCapabilities(records, options).map((record, rank) => ({
+        rank: rank + 1,
+        score: resolveScore(record, options),
+        stale: isStale(record),
+        item: record,
+    }));
+    if (options.json) {
+        console.log(JSON.stringify({
+            kind: "capability.resolve",
+            query: options.query,
+            requires: options.requires,
+            fresh_only: options.freshOnly === true,
+            count: items.length,
+            items,
+        }, null, 2));
+        return;
+    }
+    if (items.length === 0) {
+        console.log("no capabilities resolved");
+        return;
+    }
+    console.log(`resolved capabilities: ${items.length}`);
+    for (const result of items) {
+        const record = result.item;
+        const stale = result.stale ? " stale" : "";
+        console.log(`${result.rank}. ${record.qid} | score ${result.score}${stale} | ${record.kind} | ${record.title}`);
+    }
+}