mdkg 0.1.2 → 0.1.4

package/dist/init/README.md

@@ -2,6 +2,8 @@
 
 This repository is initialized for mdkg.
 
+mdkg is pre-v1 public alpha software. Graph, cache, bundle, and DAL contracts may change quickly before v1.
+
 ## Layout
 
 - `core/`: rules, operating guide, and pinned docs
@@ -10,7 +12,7 @@ This repository is initialized for mdkg.
 - `templates/`: default node templates
 - `archive/`: sidecar metadata and deterministic compressed source/artifact caches
 - `bundles/`: optional committed full graph snapshot bundles
-- `index/`: generated index cache (do not commit)
+- `index/`: generated JSON caches plus optional commit-eligible `mdkg.sqlite`
 - `pack/`: generated context packs (do not commit)
 
 ## Next Commands
@@ -24,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:
 
@@ -51,10 +53,17 @@ Read `AGENT_START.md` first when this repo includes it.
 
 Ensure ignore files include:
 
-- `.mdkg/index/`
+- `.mdkg/index/*.json`
+- `.mdkg/index/*.tmp`
+- `.mdkg/index/write.lock/`
+- `.mdkg/index/*.sqlite-wal`
+- `.mdkg/index/*.sqlite-shm`
+- `.mdkg/index/*.sqlite-journal`
 - `.mdkg/pack/`
 - `.mdkg/archive/**/source/`
 
+Fresh mdkg workspaces default to `index.backend: sqlite`; `.mdkg/index/mdkg.sqlite` is a rebuildable cache and may be committed when the repo intentionally tracks it and it stays reasonably small.
+
 Recommended:
 
 ```bash
@@ -78,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
 
@@ -109,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.
 

package/dist/init/config.json

@@ -8,7 +8,11 @@
   "index": {
     "auto_reindex": true,
     "tolerant": false,
-    "global_index_path": ".mdkg/index/global.json"
+    "backend": "sqlite",
+    "global_index_path": ".mdkg/index/global.json",
+    "sqlite_path": ".mdkg/index/mdkg.sqlite",
+    "sqlite_commit_warning_bytes": 52428800,
+    "lock_timeout_ms": 10000
   },
   "capabilities": {
     "cache_path": ".mdkg/index/capabilities.json"
@@ -17,7 +21,7 @@
     "output_dir": ".mdkg/bundles",
     "default_profile": "private"
   },
-  "bundle_imports": {},
+  "subgraphs": {},
   "pack": {
     "default_depth": 2,
     "default_edges": [

package/dist/init/core/rule-1-mdkg-conventions.md

@@ -229,8 +229,9 @@ The cache is enabled by default.
 
 - Root global index lives at `.mdkg/index/global.json`
 - Root skills index lives at `.mdkg/index/skills.json`
+- Root SQLite access cache lives at `.mdkg/index/mdkg.sqlite` when `index.backend` is `sqlite`.
 - Index is rebuilt automatically when stale unless disabled by flag/config.
-- `.mdkg/index/` is generated and MUST be gitignored.
+- Generated JSON index/temp/lock files are ignored. `.mdkg/index/mdkg.sqlite` is rebuildable and may be committed only by explicit repo policy.
 
 ## Safety guidance (high level)
 

package/dist/init/core/rule-3-cli-contract.md

@@ -69,9 +69,9 @@ Workspaces are registered in `.mdkg/config.json`.
 
 Qualified IDs may be used as input:
 - `<ws>:<id>` (example: `e2e:task-12`)
-- Imported bundle nodes use the same qualified form with the import alias:
-  - `<import-alias>:<id>` (example: `agent_image:work.generate-image`)
-  - imported nodes are read-only planning context and MUST NOT be selected by local mutation commands
+- Subgraph nodes use the same qualified form with the subgraph alias:
+  - `<subgraph-alias>:<id>` (example: `agent_image:work.generate-image`)
+  - subgraph nodes are read-only planning context and MUST NOT be selected by local mutation commands
 
 If a user provides an unqualified ID and it is ambiguous globally:
 - mdkg MUST error and suggest qualified IDs.
@@ -124,7 +124,7 @@ If a user provides an unqualified ID and it is ambiguous globally:
     - `.agents/skills/`
     - `.claude/skills/`
     - deterministic `core.md` pin insertion (`rule-soul`, then `rule-human`)
-    - ignore policy for `.mdkg/index/`, `.mdkg/pack/`, and raw archive source copies under `.mdkg/archive/**/source/`
+    - ignore policy for generated JSON index/temp/lock files, `.mdkg/pack/`, and raw archive source copies under `.mdkg/archive/**/source/`
   - mirrored skills are append-focused outputs:
     - `.mdkg/skills/` remains canonical
     - unrelated existing folders under `.agents/skills/` and `.claude/skills/` are preserved
@@ -145,7 +145,8 @@ If a user provides an unqualified ID and it is ambiguous globally:
   - rebuild global cache `.mdkg/index/global.json`
   - rebuild skills cache `.mdkg/index/skills.json` from `.mdkg/skills/<slug>/SKILL.md`
   - rebuild capability cache `.mdkg/index/capabilities.json` from skills, `SPEC.md`, `WORK.md`, core docs, and design docs
-  - rebuild bundle import projection cache `.mdkg/index/imports.json` when bundle imports are configured
+  - rebuild subgraph projection cache `.mdkg/index/subgraphs.json` when subgraphs are configured
+  - rebuild SQLite access cache `.mdkg/index/mdkg.sqlite` when `index.backend` is `sqlite`
   - tolerate `.mdkg/skills/<slug>/SKILLS.md` on read with warning
   - fail validation if both `SKILL.md` and `SKILLS.md` exist in one skill directory
   - strict by default (fails on invalid frontmatter)
@@ -182,10 +183,10 @@ Common flags:
 - `mdkg search "<query>" [--type <type>] [--status <status>] [--ws <alias>] [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]`
   - search SHOULD match on IDs, titles, tags, path tokens, and searchable frontmatter lists (`links`, `artifacts`, `refs`, `aliases`)
 - `mdkg list [--type <type>] [--status <status>] [--ws <alias>] [--epic <id>] [--blocked] [--priority <n>] [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]`
-- enabled bundle imports are included in `show`, `search`, `list`, `pack`, and `capability` reads by default:
-  - imported nodes surface `source.imported: true` in JSON output
-  - human output labels imported nodes as read-only and stale when applicable
-  - stale imports warn during planning reads but remain usable
+- enabled subgraphs are included in `show`, `search`, `list`, `pack`, and `capability` reads by default:
+  - subgraph nodes surface `source.imported: true` and `source.subgraph_alias` in JSON output
+  - human output labels subgraph nodes as read-only and stale when applicable
+  - stale subgraphs warn during planning reads but remain usable
 - skills are first-class under `mdkg skill ...` only:
   - `mdkg skill list [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]`
   - `mdkg skill show <slug> [--meta] [--json|--xml|--toon|--md]`
@@ -196,7 +197,9 @@ Common flags:
   - `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 read-only derived cache entries, not source of truth
+  - `resolve` ranks local and subgraph capability candidates deterministically and degrades stale subgraphs unless `--fresh-only` is supplied
   - normal task, epic, feat, bug, test, and checkpoint nodes are not capability records
 - archives are first-class sidecar nodes under `mdkg archive ...`:
   - `mdkg archive add <file> [--id <archive.id>] [--kind source|artifact] [--visibility private|internal|public] [--title <title>] [--refs <...>] [--relates <...>] [--json]`
@@ -214,21 +217,26 @@ Common flags:
   - `mdkg bundle verify [bundle-path] [--json]`
   - `mdkg bundle show <bundle-path> [--json]`
   - `mdkg bundle list [--json]`
-  - `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]`
-  - `mdkg bundle import list [--json]`
-  - `mdkg bundle import rm <alias> [--json]`
-  - `mdkg bundle import enable <alias> [--json]`
-  - `mdkg bundle import disable <alias> [--json]`
-  - `mdkg bundle import verify [alias|--all] [--json]`
   - bundles are explicit transport artifacts and are not rewritten by `mdkg index`
   - default output is `.mdkg/bundles/<profile>/<workspace-or-all>.mdkg.zip`
   - public bundles must fail closed when public records reference private graph or archive records
-  - public bundles must fail closed when public records reference private/internal imported graph records
-  - bundle imports are read-only projected graph views; child repos remain owners of real mutations and commits
-  - `bundle import verify` exits nonzero for stale, missing, corrupt, profile-mismatched, or duplicate-id imports
-  - public bundle creation must not re-export imported child graph content and must fail if public local nodes reference private/internal imports
-  - public/internal imports require `expected_profile: public`; private bundle profiles cannot be promoted through import visibility
+  - public bundles must fail closed when public records reference private/internal subgraph records
+  - public bundle creation must not re-export subgraph content and must fail if public local nodes reference private/internal subgraphs
   - `mdkg pack --visibility public|internal|private` records explicit pack visibility and filters public/internal packs through the same fail-closed policy
+- subgraph orchestration lives under `mdkg subgraph ...`:
+  - `mdkg subgraph add <alias> <bundle-path> [--visibility private|internal|public] [--profile private|public] [--source-path <path>] [--source-repo <ref>] [--max-stale-seconds <seconds>] [--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 projected graph views; child repos remain owners of real mutations and commits
+  - `subgraph refresh` reloads configured bundle sources only and never builds or mutates child repos
+  - `subgraph verify` exits nonzero for stale, missing, corrupt, profile-mismatched, or duplicate-id subgraphs
+  - public/internal subgraphs require `expected_profile: public`; private bundle profiles cannot be promoted through subgraph visibility
+  - legacy `mdkg bundle import ...` exits with guidance to run `mdkg upgrade --apply` and use `mdkg subgraph ...`
 - work lifecycle helpers live under `mdkg work ...`:
   - `mdkg work contract new "<title>" --id <work.id> --agent-id <agent.id> --kind <kind> --inputs <...> --outputs <...> [--required-capabilities <...>] [--pricing-model <...>] [--json]`
   - `mdkg work order new "<title>" --id <order.id> --work-id <work.id> --requester <ref> [--request-ref <ref>] [--input-refs <...>] [--requested-outputs <...>] [--json]`
@@ -239,7 +247,7 @@ Common flags:
   - these commands mutate mdkg semantic mirror files only; production order, receipt, feedback, dispute, payment, ledger, marketplace inventory, fulfillment, and execution state remains canonical outside mdkg
   - work mirrors must not store raw secrets, credentials, live payment state, ledger mutations, or canonical marketplace state
   - `artifact://...` refs identify external/runtime-managed artifacts; `archive://...` refs identify committed mdkg archive sidecars
-  - 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
 - discovery/show output flags are mutually exclusive; text mode remains the default when none are supplied
 
 ### Task lifecycle mutation
@@ -250,7 +258,7 @@ Common flags:
   - supports additive list mutation for `artifacts`, `links`, `refs`, `skills`, `tags`, and `blocked_by`
   - supports scalar replacement for `status` and `priority`
   - `--clear-blocked-by` resets blockers before optional re-add
-  - imported bundle qids fail with an explicit read-only import error
+  - subgraph qids fail with an explicit read-only subgraph error
 - `mdkg task done <id-or-qid> [--checkpoint "<title>"] [...]`
   - supports `task`, `bug`, and `test` nodes only
   - sets `status: done`
@@ -307,8 +315,8 @@ Common flags:
 - `mdkg validate`
   - strict frontmatter + graph integrity checks (exit code 2 on failure)
   - validates optional node->skill references
-  - validates configured bundle imports and fails on missing/corrupt enabled bundles, malformed import config, duplicate projected ids, and invalid import refs
-  - warns, but does not fail, on stale imports
+  - validates configured subgraphs and fails on missing/corrupt enabled bundles, malformed subgraph config, duplicate projected ids, and invalid subgraph refs
+  - warns, but does not fail, on stale subgraphs
   - validates optional `.mdkg/work/events/events.jsonl` record shape when file exists
   - warns when `.agents/skills/` or `.claude/skills/` drift from canonical `.mdkg/skills/`
 - `mdkg format`

package/dist/init/core/rule-4-repo-safety-and-ignores.md

@@ -21,7 +21,8 @@ mdkg content may contain sensitive notes and internal project planning. This rul
 
 - `.mdkg/` must not be shipped to production deployments.
 - `.mdkg/` must not be published to npm.
-- `.mdkg/index/` must never be committed.
+- Generated JSON index, temp, lock, WAL, SHM, and journal files under `.mdkg/index/` must not be committed.
+- `.mdkg/index/mdkg.sqlite` is a rebuildable access cache and may be committed when the repo intentionally tracks it and it stays reasonably small.
 - `.mdkg/bundles/` may be committed only when the repo intentionally tracks private or public snapshot bundles.
 
 ## Git ignore requirements
@@ -30,13 +31,22 @@ The repo MUST ignore at minimum:
 
 - `node_modules/`
 - `dist/`
-- `.mdkg/index/`
+- `.mdkg/index/*.json`
+- `.mdkg/index/*.tmp`
+- `.mdkg/index/write.lock/`
+- `.mdkg/index/*.sqlite-wal`
+- `.mdkg/index/*.sqlite-shm`
+- `.mdkg/index/*.sqlite-journal`
 - `.mdkg/pack/`
 - `.mdkg/archive/**/source/`
 
 Recommended `.gitignore` entries:
-- `.mdkg/index/`
-- `.mdkg/index/**`
+- `.mdkg/index/*.json`
+- `.mdkg/index/*.tmp`
+- `.mdkg/index/write.lock/`
+- `.mdkg/index/*.sqlite-wal`
+- `.mdkg/index/*.sqlite-shm`
+- `.mdkg/index/*.sqlite-journal`
 - `.mdkg/pack/`
 - `.mdkg/archive/**/source/`
 
@@ -60,7 +70,12 @@ Additional belt-and-suspenders:
 If the repo is containerized:
 - `.dockerignore` SHOULD exclude:
   - `.mdkg/`
-  - `.mdkg/index/`
+  - `.mdkg/index/*.json`
+  - `.mdkg/index/*.tmp`
+  - `.mdkg/index/write.lock/`
+  - `.mdkg/index/*.sqlite-wal`
+  - `.mdkg/index/*.sqlite-shm`
+  - `.mdkg/index/*.sqlite-journal`
   - `node_modules/`
   - `dist/` (if built in container)
   - any other local artifacts
@@ -72,8 +87,8 @@ For application builds:
 
 `mdkg init` updates ignore files by default for safety:
 
-- `.gitignore` appends `.mdkg/index/`, `.mdkg/pack/`
-- `.npmignore` appends `.mdkg/`, `.mdkg/index/`, `.mdkg/pack/`
+- `.gitignore` appends generated index cache/temp/lock patterns, `.mdkg/pack/`, and raw archive source ignores.
+- `.npmignore` appends `.mdkg/`, generated index cache/temp/lock patterns, and `.mdkg/pack/`.
 - `--no-update-ignores` disables these default writes
 
 Explicit flags remain available and take precedence:
@@ -84,16 +99,16 @@ Explicit flags remain available and take precedence:
 
 ## Index safety
 
-- `.mdkg/index/` is generated.
-- Index files may contain extracted metadata and could expose sensitive strings.
-- Index files MUST be ignored from git.
+- `.mdkg/index/` contains generated caches.
+- JSON index files may contain extracted metadata and could expose sensitive strings; they MUST be ignored from git.
+- `.mdkg/index/mdkg.sqlite` contains the same rebuildable access data and may be committed only by explicit repo policy; `mdkg doctor` warns when it exceeds `index.sqlite_commit_warning_bytes`.
 - Index rebuild should be deterministic and safe to regenerate at any time.
 
 ## Bundle safety
 
 - `.mdkg/bundles/` stores explicit snapshot artifacts and is not ignored by default.
 - Private bundles may include sensitive authored mdkg content and should stay in private repos.
-- Public bundles must be created with `mdkg bundle create --profile public` so private graph, archive, and imported bundle refs fail closed.
+- Public bundles must be created with `mdkg bundle create --profile public` so private graph, archive, and subgraph refs fail closed.
 - Public-safe packs must be created with `mdkg pack <id> --visibility public`; internal-safe packs use `--visibility internal`. These filters do not redact Markdown body text.
 - Bundle ZIPs must exclude `.mdkg/pack/`, existing `.mdkg/index/`, nested `.mdkg/bundles/`, and raw `.mdkg/archive/**/source/` files.
 - Repos that track archive caches or bundles should refresh in this order before commit: `mdkg archive compress --all`, `mdkg archive verify --json`, `mdkg bundle create --profile private`, then bundle verify.
@@ -115,7 +130,8 @@ Workspace-local `.mdkg/` directories (near code) should follow the same rules:
 
 ## Summary checklist
 
-- ✅ `.mdkg/index/` ignored
+- ✅ generated JSON index/temp/lock files ignored
+- ✅ `.mdkg/index/mdkg.sqlite` committed only by explicit repo policy
 - ✅ event logs are committed by default unless a repo chooses to ignore them manually
 - ✅ npm publishes only `dist/`, `README.md`, `LICENSE`
 - ✅ optional `.npmignore` excludes `.mdkg/`

package/dist/init/core/rule-5-release-and-versioning.md

@@ -37,14 +37,15 @@ The npm package MUST include:
 
 It MUST NOT include:
 - `.mdkg/` docs
-- `.mdkg/index/`
+- generated `.mdkg/index/` caches
 - source code (optional; can be included later, but not required)
 
 ## Release checklist (v1)
 
 1) Ensure clean working tree
 - no uncommitted changes
-- all `.mdkg/index/` ignored
+- generated JSON index/temp/lock files ignored
+- `.mdkg/index/mdkg.sqlite` either intentionally tracked or absent
 
 2) Rebuild and validate
 - run `mdkg index`
@@ -79,4 +80,4 @@ Release notes should call out:
 - new commands / flags
 - changes to pack behavior
 - changes to config schema (and how migration behaves)
-- new node types or template changes
+- new node types or template changes

package/dist/init/init-manifest.json

@@ -1,12 +1,12 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "mdkg_version": "0.1.2",
+  "mdkg_version": "0.1.4",
   "files": [
     {
       "path": ".mdkg/config.json",
       "category": "config",
-      "sha256": "8f0fd9ba020511e22d912f59c39bdd1c09706595564361694860ded3e9488e7e"
+      "sha256": "5d2cf5e773353a59178fe86f8528413a00a73e2879fb1e020d01b49c0715a9ce"
     },
     {
       "path": ".mdkg/core/core.md",
@@ -26,7 +26,7 @@
     {
       "path": ".mdkg/core/rule-1-mdkg-conventions.md",
       "category": "core",
-      "sha256": "20073cd21c148f1b93a382550f835ccb2e896cc676903328557004319235c112"
+      "sha256": "15f886e6661046de45ad798c292d74cc1ff3cc14c8cfcc82ed0b8c35635d0477"
     },
     {
       "path": ".mdkg/core/rule-2-context-pack-rules.md",
@@ -36,17 +36,17 @@
     {
       "path": ".mdkg/core/rule-3-cli-contract.md",
       "category": "core",
-      "sha256": "ad151ac183dea1158884c4341154118d9623392871062b8faa6cecd4bde580ba"
+      "sha256": "4ec25c6936eefe0857a2946b47f0b65c9481bd65f1159fd5456bec6cce9de7ea"
     },
     {
       "path": ".mdkg/core/rule-4-repo-safety-and-ignores.md",
       "category": "core",
-      "sha256": "b4638d8b5aeae74768fb971a8844aa473177df8814b929fedff6faf865a034cc"
+      "sha256": "2374e8684dfb32d24d560c83c99c33ff655cfdfe6811372dc3959ec93318a6db"
     },
     {
       "path": ".mdkg/core/rule-5-release-and-versioning.md",
       "category": "core",
-      "sha256": "4fc6648052f80b90b2efc173e3bcab16cb0bc6680bb8b04f76c66fff06ad19cd"
+      "sha256": "e97b00aa3ade29011f1f2b482042ec292f74aad8b1d72e2f8e691cdeca5d4f70"
     },
     {
       "path": ".mdkg/core/rule-6-templates-and-schemas.md",
@@ -61,7 +61,7 @@
     {
       "path": ".mdkg/README.md",
       "category": "mdkg_doc",
-      "sha256": "fc85d07197da2fce189d295b6e6047de2a49b711adc74c991029faec6be385de"
+      "sha256": "5ee6c141c0052e78671762e69c111f7f0a5d7f79b35c8f78c5b3b41901bd6959"
     },
     {
       "path": ".mdkg/skills/build-pack-and-execute-task/SKILL.md",
@@ -76,7 +76,7 @@
     {
       "path": ".mdkg/skills/verify-close-and-checkpoint/SKILL.md",
       "category": "default_skill",
-      "sha256": "cf9d7f01eb78a3cf669b6303c2f22c7c08529fe0181e008a7b45c5e5b70ceb49"
+      "sha256": "67fc3d7e3c59b53add62306624391c1a416d0c66077729d79e1be0a303538f42"
     },
     {
       "path": ".mdkg/templates/default/archive.md",
@@ -176,7 +176,7 @@
     {
       "path": "AGENT_START.md",
       "category": "startup_doc",
-      "sha256": "6ff5915ea72d7453b2f7666e138808b6b0854123c7030bcced313a15f86c2b3a"
+      "sha256": "abde8671d34fcc7abd8570cf8c10b940cbe8f339edb369bd046045aa5626c0fc"
     },
     {
       "path": "AGENTS.md",
@@ -191,7 +191,7 @@
     {
       "path": "CLI_COMMAND_MATRIX.md",
       "category": "startup_doc",
-      "sha256": "f852a4f0a99c87aeb123a839c2902798ffdf5bf8012b4f367cb9c85905473ae7"
+      "sha256": "14deecded057a99284d2dc147855d12dedffec049da51fed3b1ebdae3105d537"
     },
     {
       "path": "llms.txt",

package/dist/init/skills/default/verify-close-and-checkpoint/SKILL.md

@@ -46,7 +46,7 @@ Use this local repo-only checklist before publishing mdkg:
 
 1. Confirm package intent and version in `package.json`, `package-lock.json`, `README.md`, `CLI_COMMAND_MATRIX.md`, and `CHANGELOG.md`.
 2. Use a clean npm cache: `export NPM_CONFIG_CACHE=/private/tmp/mdkg-npm-cache`.
-3. Run `npm ci`, `npm run build`, `node scripts/assert-publish-ready.js`, `npm run test`, `npm run cli:check`, `node dist/cli.js validate`, `npm run smoke:consumer`, `npm run smoke:matrix`, `npm run smoke:upgrade`, `npm run smoke:init`, `npm run smoke:capabilities`, `npm run smoke:archive-work`, `npm run smoke:bundle`, `npm run smoke:bundle-import`, and `npm run smoke:visibility`.
+3. Run `npm ci`, `npm run build`, `node scripts/assert-publish-ready.js`, `npm run test`, `npm run cli:check`, `node dist/cli.js validate`, `npm run smoke:consumer`, `npm run smoke:matrix`, `npm run smoke:upgrade`, `npm run smoke:init`, `npm run smoke:capabilities`, `npm run smoke:archive-work`, `npm run smoke:bundle`, `npm run smoke:subgraph`, and `npm run smoke:visibility`.
 4. Run `npm pack --dry-run --json` and confirm the tarball includes `dist/cli.js`, compiled folders, `dist/init/`, release docs, and `scripts/postinstall.js`.
 5. Confirm registry state with `npm view mdkg version --registry=https://registry.npmjs.org/`.
 6. Publish only after the registry still shows the previous version and npm auth is known to have write access.

package/dist/util/argparse.js

@@ -83,6 +83,7 @@ const VALUE_FLAGS = new Set([
     "--source-path",
     "--source-repo",
     "--max-stale-seconds",
+    "--requires",
 ]);
 const BOOLEAN_FLAGS = new Set([
     "--tolerant",
@@ -116,6 +117,7 @@ const BOOLEAN_FLAGS = new Set([
     "--with-scripts",
     "--clear-blocked-by",
     "--all",
+    "--fresh-only",
 ]);
 const FLAG_ALIASES = {
     "--o": "--out",

package/dist/util/atomic.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.atomicWriteFile = atomicWriteFile;
+exports.writeFileExclusive = writeFileExclusive;
+const crypto_1 = __importDefault(require("crypto"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function randomSuffix() {
+    return `${process.pid}-${Date.now()}-${crypto_1.default.randomBytes(6).toString("hex")}`;
+}
+function writeAndSync(filePath, data, flags) {
+    const handle = fs_1.default.openSync(filePath, flags);
+    try {
+        if (typeof data === "string") {
+            fs_1.default.writeFileSync(handle, data, "utf8");
+        }
+        else {
+            fs_1.default.writeFileSync(handle, data);
+        }
+        fs_1.default.fsyncSync(handle);
+    }
+    finally {
+        fs_1.default.closeSync(handle);
+    }
+}
+function atomicWriteFile(filePath, data) {
+    fs_1.default.mkdirSync(path_1.default.dirname(filePath), { recursive: true });
+    const tempPath = path_1.default.join(path_1.default.dirname(filePath), `.${path_1.default.basename(filePath)}.${randomSuffix()}.tmp`);
+    try {
+        writeAndSync(tempPath, data, "wx");
+        fs_1.default.renameSync(tempPath, filePath);
+    }
+    catch (err) {
+        fs_1.default.rmSync(tempPath, { force: true });
+        throw err;
+    }
+}
+function writeFileExclusive(filePath, data) {
+    fs_1.default.mkdirSync(path_1.default.dirname(filePath), { recursive: true });
+    writeAndSync(filePath, data, "wx");
+}

package/dist/util/lock.js

@@ -0,0 +1,72 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withMutationLock = withMutationLock;
+exports.lockTimeoutFromConfig = lockTimeoutFromConfig;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const HELD_LOCKS = new Set();
+function sleepSync(ms) {
+    const shared = new SharedArrayBuffer(4);
+    const view = new Int32Array(shared);
+    Atomics.wait(view, 0, 0, ms);
+}
+function lockDir(root) {
+    return path_1.default.resolve(root, ".mdkg", "index", "write.lock");
+}
+function lockOwner() {
+    return JSON.stringify({
+        pid: process.pid,
+        node: process.version,
+        created_at: new Date().toISOString(),
+    }, null, 2);
+}
+function withMutationLock(root, timeoutMs, fn) {
+    const dir = lockDir(root);
+    if (HELD_LOCKS.has(dir)) {
+        return fn();
+    }
+    fs_1.default.mkdirSync(path_1.default.dirname(dir), { recursive: true });
+    const started = Date.now();
+    let lastError;
+    while (Date.now() - started <= timeoutMs) {
+        try {
+            fs_1.default.mkdirSync(dir);
+            let acquired = false;
+            try {
+                fs_1.default.writeFileSync(path_1.default.join(dir, "owner.json"), lockOwner(), "utf8");
+                HELD_LOCKS.add(dir);
+                acquired = true;
+                try {
+                    return fn();
+                }
+                finally {
+                    HELD_LOCKS.delete(dir);
+                    fs_1.default.rmSync(dir, { recursive: true, force: true });
+                }
+            }
+            catch (err) {
+                if (!acquired) {
+                    fs_1.default.rmSync(dir, { recursive: true, force: true });
+                }
+                throw err;
+            }
+        }
+        catch (err) {
+            const code = typeof err === "object" && err !== null && "code" in err ? String(err.code) : "";
+            if (code !== "EEXIST") {
+                throw err;
+            }
+            lastError = err;
+            sleepSync(25);
+        }
+    }
+    const detailPath = path_1.default.join(dir, "owner.json");
+    const owner = fs_1.default.existsSync(detailPath) ? fs_1.default.readFileSync(detailPath, "utf8").trim() : "unknown owner";
+    throw new Error(`timed out waiting for mdkg mutation lock at ${path_1.default.relative(root, dir)}; owner: ${owner || "unknown"}`);
+}
+function lockTimeoutFromConfig(config) {
+    return config.index.lock_timeout_ms;
+}

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "mdkg",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Markdown Knowledge Graph",
   "license": "MIT",
   "bin": {
     "mdkg": "dist/cli.js"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && node scripts/add-shebang.js && node scripts/copy-init-assets.js",
-    "build:test": "tsc -p tsconfig.test.json",
+    "build": "node scripts/clean-build-output.js && tsc -p tsconfig.build.json && node scripts/add-shebang.js && node scripts/copy-init-assets.js",
+    "build:test": "node scripts/clean-build-output.js tests && tsc -p tsconfig.test.json",
     "test": "npm run build && npm run build:test && node --test dist/tests/**/*.test.js",
     "test:coverage": "npm run build && npm run build:test && node --test --experimental-test-coverage dist/tests/**/*.test.js",
     "smoke:consumer": "npm run build && node scripts/smoke-consumer.js",
@@ -18,16 +18,19 @@
     "smoke:capabilities": "npm run build && node scripts/smoke-capabilities.js",
     "smoke:archive-work": "npm run build && node scripts/smoke-archive-work.js",
     "smoke:bundle": "npm run build && node scripts/smoke-bundle.js",
-    "smoke:bundle-import": "npm run build && node scripts/smoke-bundle-import.js",
+    "smoke:bundle-import": "npm run smoke:subgraph",
     "smoke:visibility": "npm run build && node scripts/smoke-visibility.js",
+    "smoke:sqlite": "npm run build && node scripts/smoke-sqlite.js",
+    "smoke:parallel": "npm run build && node scripts/smoke-parallel.js",
     "cli:snapshot": "npm run build && node scripts/cli_help_snapshot.js",
     "cli:check": "npm run build && node scripts/cli_help_snapshot.js --check",
     "prepack": "npm run build && node scripts/assert-publish-ready.js",
-    "prepublishOnly": "npm run test && npm run cli:check && node dist/cli.js validate && npm run smoke:consumer && npm run smoke:matrix && npm run smoke:upgrade && npm run smoke:init && npm run smoke:capabilities && npm run smoke:archive-work && npm run smoke:bundle && npm run smoke:bundle-import && npm run smoke:visibility && node scripts/assert-publish-ready.js",
-    "postinstall": "node scripts/postinstall.js"
+    "prepublishOnly": "npm run test && npm run cli:check && node dist/cli.js validate && npm run smoke:consumer && npm run smoke:matrix && npm run smoke:upgrade && npm run smoke:init && npm run smoke:capabilities && npm run smoke:archive-work && npm run smoke:bundle && npm run smoke:subgraph && npm run smoke:visibility && npm run smoke:sqlite && npm run smoke:parallel && node scripts/assert-publish-ready.js",
+    "postinstall": "node scripts/postinstall.js",
+    "smoke:subgraph": "npm run build && node scripts/smoke-subgraph.js"
   },
   "devDependencies": {
-    "@types/node": "^18.19.0",
+    "@types/node": "^24.0.0",
     "typescript": "^5.4.0"
   },
   "files": [
@@ -46,7 +49,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=24.15.0"
   },
   "repository": {
     "type": "git",
@@ -56,5 +59,6 @@
     "markdown",
     "knowledge-graph",
     "cli"
-  ]
+  ],
+  "dependencies": {}
 }