mdkg 0.1.1 → 0.1.3

package/dist/graph/workspace_files.js

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

package/dist/init/AGENT_START.md

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

package/dist/init/CLI_COMMAND_MATRIX.md

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

package/dist/init/README.md

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

package/dist/init/config.json

@@ -2,11 +2,26 @@
   "schema_version": 1,
   "tool": "mdkg",
   "root_required": true,
+  "archive": {
+    "large_cache_warning_bytes": 26214400
+  },
   "index": {
     "auto_reindex": true,
     "tolerant": false,
-    "global_index_path": ".mdkg/index/global.json"
+    "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"
+  },
+  "bundles": {
+    "output_dir": ".mdkg/bundles",
+    "default_profile": "private"
   },
+  "bundle_imports": {},
   "pack": {
     "default_depth": 2,
     "default_edges": [
@@ -51,7 +66,8 @@
     "root": {
       "path": ".",
       "enabled": true,
-      "mdkg_dir": ".mdkg"
+      "mdkg_dir": ".mdkg",
+      "visibility": "private"
     }
   }
 }

package/dist/init/core/guide.md

@@ -10,7 +10,7 @@ relates: []
 refs: []
 aliases: []
 created: 2026-01-06
-updated: 2026-01-22
+updated: 2026-05-14
 ---
 
 # Agent guide
@@ -19,8 +19,9 @@ This repo uses **mdkg** to manage documentation, decisions, and work tracking.
 
 ## Quickstart
 
-- `mdkg init --llm`
+- `mdkg init --agent`
 - `mdkg index`
+- `mdkg capability list --kind skill --json`
 - `mdkg new task "..." --status todo --priority 1`
 - `mdkg list --status todo`
 - `mdkg pack <id> --verbose`
@@ -32,6 +33,7 @@ This repo uses **mdkg** to manage documentation, decisions, and work tracking.
 - `mdkg guide` (print this guide)
 - `mdkg new <type> "<title>"`
 - `mdkg list` / `mdkg show` / `mdkg search`
+- `mdkg capability list` / `mdkg capability search` / `mdkg capability show`
 - `mdkg pack`
 - `mdkg next`
 - `mdkg validate` / `mdkg format`
@@ -94,6 +96,8 @@ If formatting drift is common (especially with agent edits):
 
 Index is cached by default and auto-reindexed when stale.
 
+`mdkg index` writes the node index, skills index, and capability cache. The capability cache is a derived access layer for skills, `SPEC.md`, `WORK.md`, core docs, and design docs; it is not source of truth and does not include normal task/epic/test/checkpoint nodes.
+
 If debugging index issues:
 - run `mdkg index`
 - inspect errors from strict frontmatter enforcement

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

@@ -10,7 +10,7 @@ relates: []
 refs: []
 aliases: []
 created: 2026-01-06
-updated: 2026-03-08
+updated: 2026-05-17
 ---
 
 # mdkg CLI contract
@@ -69,6 +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
 
 If a user provides an unqualified ID and it is ambiguous globally:
 - mdkg MUST error and suggest qualified IDs.
@@ -102,9 +105,14 @@ If a user provides an unqualified ID and it is ambiguous globally:
   - updates `.gitignore` and `.npmignore` by default
   - `--no-update-ignores` disables default ignore writes
   - explicit flags (`--update-gitignore`, `--update-npmignore`, `--update-dockerignore`) force writes even with global opt-out
-  - `--llm` is the canonical documented path for creating `AGENTS.md`, `CLAUDE.md`, `llms.txt`, and `AGENT_START.md`
-  - `--agents` / `--claude` remain compatibility flags, but are not part of the primary onboarding story
-  - `--agent` adds strict-node bootstrap docs and scaffolding:
+  - `--agent` is the canonical documented path for complete AI-agent bootstrap
+  - `--llm`, `--agents`, `--claude`, and `--omni` fail before mutation with guidance to use `mdkg init --agent`
+  - `--agent` adds startup docs, strict-node bootstrap docs, and scaffolding:
+    - `AGENT_START.md`
+    - `AGENTS.md`
+    - `CLAUDE.md`
+    - `llms.txt`
+    - `CLI_COMMAND_MATRIX.md`
     - `.mdkg/core/SOUL.md` (`id: rule-soul`)
     - `.mdkg/core/HUMAN.md` (`id: rule-human`)
     - seeded canonical skills:
@@ -116,6 +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 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
@@ -129,11 +138,15 @@ If a user provides an unqualified ID and it is ambiguous globally:
 - `mdkg workspace ls`
 - `mdkg workspace add <alias> <path>`
 - `mdkg workspace rm <alias>`
+- workspace entries may include advisory `visibility: private|internal|public` metadata for capability-cache filtering
 
 ### Indexing
 - `mdkg index`
   - 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 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)
@@ -170,12 +183,64 @@ 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
 - 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]`
   - `mdkg skill search "<query>" [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]`
   - `mdkg skill validate [<slug>]`
   - `mdkg skill sync [--force]`
+- capabilities are cached Markdown projections under `mdkg capability ...`:
+  - `mdkg capability list [--kind <skill|spec|work|core|design>] [--visibility <private|internal|public>] [--json]`
+  - `mdkg capability search "<query>" [--kind <kind>] [--visibility <level>] [--json]`
+  - `mdkg capability show <id-or-qid-or-slug> [--json]`
+  - capability records are read-only derived cache entries, not source of truth
+  - 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]`
+  - `mdkg archive list [--kind source|artifact] [--visibility private|internal|public] [--ws <alias>] [--json]`
+  - `mdkg archive show <id-or-archive-uri> [--ws <alias>] [--json]`
+  - `mdkg archive verify [id-or-archive-uri] [--ws <alias>] [--json]`
+  - `mdkg archive compress <id-or-archive-uri|--all> [--json]`
+  - `archive://<archive.id>` refs resolve against local archive sidecars
+  - archive visibility defaults to `private`
+  - in-repo source paths are recorded repo-relative; outside-repo source paths are redacted as `external:<basename>`
+  - `mdkg validate` and `mdkg archive verify` both check ZIP cache hash, ZIP readability, payload hash, and payload byte size
+  - raw copied sources live under `.mdkg/archive/**/source/`; sidecar `.md` and deterministic `.zip` caches remain commit-eligible
+- full graph snapshot bundles live under `mdkg bundle ...`:
+  - `mdkg bundle create [--profile private|public] [--ws <alias|all>] [--output <path>] [--json]`
+  - `mdkg bundle verify [bundle-path] [--json]`
+  - `mdkg bundle show <bundle-path> [--json]`
+  - `mdkg bundle list [--json]`
+  - `mdkg bundle import add <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
+  - `mdkg pack --visibility public|internal|private` records explicit pack visibility and filters public/internal packs through the same fail-closed policy
+- 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]`
+  - `mdkg work order update <id-or-qid> [--status <status>] [--add-input-refs <...>] [--add-artifacts <...>] [--json]`
+  - `mdkg work receipt new "<title>" --id <receipt.id> --work-order-id <order.id> --outcome success|partial|failure [--receipt-status recorded|verified|rejected|superseded] [--json]`
+  - `mdkg work receipt update <id-or-qid> [--receipt-status <status>] [--add-artifacts <...>] [--add-proof-refs <...>] [--add-attestation-refs <...>] [--json]`
+  - `mdkg work artifact add <order-or-receipt-id-or-qid> <file> [--id <archive.id>] [--kind source|artifact] [--json]`
+  - 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
 - discovery/show output flags are mutually exclusive; text mode remains the default when none are supplied
 
 ### Task lifecycle mutation
@@ -186,6 +251,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
 - `mdkg task done <id-or-qid> [--checkpoint "<title>"] [...]`
   - supports `task`, `bug`, and `test` nodes only
   - sets `status: done`
@@ -242,6 +308,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 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,9 @@ 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
 
@@ -29,13 +31,24 @@ 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/`
 
 ## npm publish safety (required)
 
@@ -57,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
@@ -69,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:
@@ -81,11 +99,28 @@ 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-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.
+
+## Archive safety
+
+- Archive sidecar `.md` files and deterministic `.zip` caches are the commit-eligible evidence record.
+- Raw copied sources under `.mdkg/archive/**/source/` stay ignored by default.
+- `mdkg validate` and `mdkg archive verify` must both check ZIP cache hash, ZIP readability, payload hash, and payload byte size.
+- Outside-repo archive sources must be recorded as redacted labels such as `external:key_input_doc.pdf`, not absolute local paths.
+- `mdkg doctor` warns when committed archive ZIP caches exceed `archive.large_cache_warning_bytes`; this is advisory and does not block validation.
+
 ## Workspace safety
 
 Workspace-local `.mdkg/` directories (near code) should follow the same rules:
@@ -95,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/`