mdkg 0.1.0 → 0.1.2

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-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 `.mdkg/index/`, `.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,14 @@ 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
   - 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 +182,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 +250,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 +307,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

@@ -22,6 +22,7 @@ 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.
+- `.mdkg/bundles/` may be committed only when the repo intentionally tracks private or public snapshot bundles.
 
 ## Git ignore requirements
 
@@ -31,11 +32,13 @@ The repo MUST ignore at minimum:
 - `dist/`
 - `.mdkg/index/`
 - `.mdkg/pack/`
+- `.mdkg/archive/**/source/`
 
 Recommended `.gitignore` entries:
 - `.mdkg/index/`
 - `.mdkg/index/**`
 - `.mdkg/pack/`
+- `.mdkg/archive/**/source/`
 
 ## npm publish safety (required)
 
@@ -86,6 +89,23 @@ Explicit flags remain available and take precedence:
 - Index files MUST be ignored from git.
 - 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:

package/dist/init/core/rule-6-templates-and-schemas.md

@@ -108,6 +108,13 @@ Design docs (`prd/edd/prop`):
 Rules (`rule-*`):
 - no required status field
 
+Archives (`archive`):
+- required id starts with `archive.`
+- required fields: `archive_kind`, `source_path`, `stored_path`, `compressed_path`, `mime_type`, `byte_size`, `sha256`, `compressed_sha256`, `visibility`, `provenance`, `ingest_status`
+- `source_path` is repo-relative for in-repo sources or `external:<basename>` for outside-repo sources
+- `stored_path` and `compressed_path` are relative to the sidecar directory
+- `mdkg validate` and `mdkg archive verify` both check deterministic ZIP cache integrity and tolerate a missing raw source copy when the ZIP cache is valid
+
 ## Body headings (guidance only)
 
 Body headings are strongly recommended for agent usability but should not be hard requirements.
@@ -187,4 +194,6 @@ Body headings are strongly recommended for agent usability but should not be har
 - Node -> skill references in `skills: [...]` are validated against `.mdkg/skills/<slug>/SKILL.md`.
 - `.mdkg/work/events/events.jsonl` is optional; when present, records are schema-validated by `mdkg validate`.
 - If a template is missing:
-  - `mdkg new` must fail with a helpful error (exit code 3).
+  - built-in mdkg node types may use the installed package's bundled default template as a read-only schema fallback.
+  - commands should warn when bundled fallback is used and recommend `mdkg upgrade --apply` to vendor missing templates.
+  - missing non-built-in templates or missing packaged fallback assets must fail with a helpful error.

package/dist/init/init-manifest.json

@@ -1,12 +1,12 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "mdkg_version": "0.1.0",
+  "mdkg_version": "0.1.2",
   "files": [
     {
       "path": ".mdkg/config.json",
       "category": "config",
-      "sha256": "eb76bf22ae9d04601c2fedac5fd22838797dd2cc829324638a6b69222d40aaa9"
+      "sha256": "8f0fd9ba020511e22d912f59c39bdd1c09706595564361694860ded3e9488e7e"
     },
     {
       "path": ".mdkg/core/core.md",
@@ -16,7 +16,7 @@
     {
       "path": ".mdkg/core/guide.md",
       "category": "core",
-      "sha256": "0b0ba51fbc393b3d5e0a0df4dece6aa822b77ab0f4ee3814b2cdba77ef8b65d9"
+      "sha256": "ffee0b532801d934d32842a9a9b1332df6329ad78d6804b39607553899b5b9ae"
     },
     {
       "path": ".mdkg/core/HUMAN.md",
@@ -36,12 +36,12 @@
     {
       "path": ".mdkg/core/rule-3-cli-contract.md",
       "category": "core",
-      "sha256": "b547a6edc20112013c607a033af4ac0c6bb3f9d66d445b0c545b2890a721b671"
+      "sha256": "ad151ac183dea1158884c4341154118d9623392871062b8faa6cecd4bde580ba"
     },
     {
       "path": ".mdkg/core/rule-4-repo-safety-and-ignores.md",
       "category": "core",
-      "sha256": "d7fc4bfa3727ed7d5353eeb0089ad818b96a755578e217251106422559750291"
+      "sha256": "b4638d8b5aeae74768fb971a8844aa473177df8814b929fedff6faf865a034cc"
     },
     {
       "path": ".mdkg/core/rule-5-release-and-versioning.md",
@@ -51,7 +51,7 @@
     {
       "path": ".mdkg/core/rule-6-templates-and-schemas.md",
       "category": "core",
-      "sha256": "0d6da477c12e3492f43c571a6e4daa373bf05005ef703ad5166b7c8786e553b0"
+      "sha256": "5181e2e8a025cb6b9d160c1232c425bfc426fd8fd1ae3f75ce5052981807fc5f"
     },
     {
       "path": ".mdkg/core/SOUL.md",
@@ -61,12 +61,12 @@
     {
       "path": ".mdkg/README.md",
       "category": "mdkg_doc",
-      "sha256": "26e99be382b48682b7841f14404576f79bf6876b64a90aefa6c99c2440701d2a"
+      "sha256": "fc85d07197da2fce189d295b6e6047de2a49b711adc74c991029faec6be385de"
     },
     {
       "path": ".mdkg/skills/build-pack-and-execute-task/SKILL.md",
       "category": "default_skill",
-      "sha256": "7f6104980e6b2ec0749881c6be2bd3d7982702259c4979763266d1c800aeb410"
+      "sha256": "3e240cb844b22e5e4c0046a4f839ac3c0d771a62d00a72719fc449477564b1ae"
     },
     {
       "path": ".mdkg/skills/select-work-and-ground-context/SKILL.md",
@@ -76,7 +76,12 @@
     {
       "path": ".mdkg/skills/verify-close-and-checkpoint/SKILL.md",
       "category": "default_skill",
-      "sha256": "98a1b02927854201eeea73e3d7c9f5a104fab7a5c72e033ea261995341a8a7ce"
+      "sha256": "cf9d7f01eb78a3cf669b6303c2f22c7c08529fe0181e008a7b45c5e5b70ceb49"
+    },
+    {
+      "path": ".mdkg/templates/default/archive.md",
+      "category": "template",
+      "sha256": "d442523bbecd91a3c4a436043919117da00c145b368612311e98e628fe30d69b"
     },
     {
       "path": ".mdkg/templates/default/bug.md",
@@ -136,7 +141,7 @@
     {
       "path": ".mdkg/templates/default/receipt.md",
       "category": "template",
-      "sha256": "aac6e6e27153a1ca85a515b03f0ac55db3eb0df3f9243c42f0b936f5e5a750b2"
+      "sha256": "f08753cc38e02d73a5df92df58c2d34b0d33749b298eeb31d81aa019c38d43dd"
     },
     {
       "path": ".mdkg/templates/default/rule.md",
@@ -161,17 +166,17 @@
     {
       "path": ".mdkg/templates/default/work_order.md",
       "category": "template",
-      "sha256": "bdbdf6e34d59976a675dd1d25002dfc0ef49e725647c97a9e0b3552c93fb8600"
+      "sha256": "6ee6007674f30f88153ce79ed67d8c736b4f0998ceb0c8314a3f2cf9c48ac88c"
     },
     {
       "path": ".mdkg/templates/default/work.md",
       "category": "template",
-      "sha256": "651b7339f6e23c8745264f3f6641a0c82fcd765247f0a70a9f407a118a49ec00"
+      "sha256": "9d8b971ded7a587105fb8b14bb79f68b612fa6e1962cf06859bab82e2aee57c7"
     },
     {
       "path": "AGENT_START.md",
       "category": "startup_doc",
-      "sha256": "be0990bb81e194a2a396f9520cda66c34d0bbbd36daa5b48773246549aacab2e"
+      "sha256": "6ff5915ea72d7453b2f7666e138808b6b0854123c7030bcced313a15f86c2b3a"
     },
     {
       "path": "AGENTS.md",
@@ -186,7 +191,7 @@
     {
       "path": "CLI_COMMAND_MATRIX.md",
       "category": "startup_doc",
-      "sha256": "eb441dd11b31270ddb31f0a77c75fc744671754cffac3aa8ac6f60e30a1f324f"
+      "sha256": "f852a4f0a99c87aeb123a839c2902798ffdf5bf8012b4f367cb9c85905473ae7"
     },
     {
       "path": "llms.txt",

package/dist/init/skills/default/build-pack-and-execute-task/SKILL.md

@@ -33,7 +33,8 @@ Use `mdkg pack <id>` as the default execution context instead of ad-hoc file gat
 6. Discover skills by metadata first; load full skill bodies only for the selected execution procedures.
 7. Hand the pack, not a loose file list, to the next coding step or agent.
 8. Keep this stage patch-only: subagents and tools may produce patches, test output, and evidence, but not direct mdkg state writes or commits.
-9. If execution reveals new artifacts or blockers, hand them to the orchestrator stage for `mdkg task update ...` as structured field updates; keep narrative summaries in markdown.
+9. If execution creates or changes archive sidecars, raw source files, or bundle-relevant graph state, hand that to the orchestrator stage so pre-commit `mdkg archive compress --all` and `mdkg bundle create --profile private` can run at the durable writer boundary.
+10. If execution reveals new artifacts or blockers, hand them to the orchestrator stage for `mdkg task update ...` as structured field updates; keep narrative summaries in markdown.
 
 ## Outputs
 

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

@@ -40,6 +40,32 @@ Finish work with evidence, validation, and minimal memory drift.
 12. If the latest checkpoint is relevant, use it as durable recall; treat raw events as provenance/debugging, not primary execution context.
 13. If `events.jsonl` is missing, recreate it with `mdkg event enable` before expecting automatic JSONL provenance.
 
+## Pre-Publish Release Gate
+
+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`.
+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.
+7. If publishing fails with 2FA or token policy errors, do not commit; fix npm auth or package policy, then rerun publish.
+8. After successful publish, verify `npm view mdkg version` and `npm view mdkg dist-tags`, then commit the release changes.
+
+## Bundle-Aware Commit Gate
+
+When a repo tracks mdkg archive caches or snapshot bundles, refresh and verify them before the final commit. This is recommended after validation and before staging so the committed semantic graph, compressed archive caches, and snapshot bundle describe the same source state.
+
+```bash
+mdkg archive compress --all
+mdkg archive verify --json
+mdkg bundle create --profile private
+mdkg bundle verify .mdkg/bundles/private/all.mdkg.zip
+```
+
+Skip `mdkg archive compress --all` only when the repo has no `.mdkg/archive` sidecars. Skip bundle refresh only when the repo intentionally does not track `.mdkg/bundles/`. Use `--profile public` or `mdkg pack --visibility public` only for explicit export-safe output after public workspace, archive, and import visibility has been reviewed.
+
 ## Outputs
 
 - Verified mdkg graph state

package/dist/init/templates/default/archive.md

@@ -0,0 +1,33 @@
+---
+id: {{id}}
+type: archive
+title: {{title}}
+archive_kind: source
+source_path: local
+stored_path: source/example.txt
+compressed_path: example.txt.zip
+mime_type: text/plain
+byte_size: 0
+sha256: sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
+compressed_sha256: sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
+visibility: private
+provenance: manual
+ingest_status: pending
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Archive Entry
+
+Describe the source or artifact represented by this sidecar.
+
+# Provenance
+
+Record non-secret provenance and ingest notes.

package/dist/init/templates/default/receipt.md

@@ -7,6 +7,10 @@ work_order_id: order.example
 receipt_status: recorded
 outcome: success
 cost_ref: cost.redacted
+proof_refs: []
+attestation_refs: []
+input_hashes: []
+output_hashes: []
 tags: []
 owners: []
 links: []
@@ -22,9 +26,19 @@ updated: {{updated}}
 
 Record the result and proof summary.
 
+This file is a committed semantic mirror, not canonical payment, ledger,
+marketplace, or execution state. Do not store raw secrets, credentials, live
+payment state, ledger mutations, or bulky payloads here.
+
 # Artifacts
 
-List committed artifact references.
+List committed artifact references. Use `artifact://...` for external or
+runtime-managed artifact identities and `archive://...` for committed mdkg
+archive sidecars.
+
+# Proof
+
+Record non-secret proof, attestation, and hash references.
 
 # Notes
 

package/dist/init/templates/default/work.md

@@ -31,6 +31,10 @@ updated: {{updated}}
 
 Describe the reusable capability contract.
 
+This file is a semantic mirror for discovery and review. Do not store raw
+secrets, credentials, live payment state, ledger mutations, marketplace
+inventory, or canonical execution state here.
+
 # Inputs
 
 Document input descriptors and validation expectations.
@@ -41,4 +45,5 @@ Document output descriptors and artifact expectations.
 
 # Receipt
 
-Describe required receipt evidence.
+Describe required receipt evidence. Production execution systems remain
+canonical for real orders, receipts, payments, ledgers, and fulfillment state.

package/dist/init/templates/default/work_order.md

@@ -8,6 +8,10 @@ work_version: 0.1.0
 requester: user.example
 order_status: submitted
 request_ref: request.example
+input_refs: []
+requested_outputs: [result:text:required]
+constraint_refs: []
+artifact_policy: commit_sidecar_and_zip
 tags: []
 owners: []
 links: []
@@ -23,9 +27,19 @@ updated: {{updated}}
 
 Capture the concrete request against a WORK.md version.
 
+This file is a committed semantic mirror, not the canonical execution database.
+Do not store raw secrets, credentials, live payment state, ledger mutations,
+marketplace inventory, or bulky payloads here.
+
 # Inputs
 
-Record committed input references without secrets.
+Record committed input references without secrets. Use `archive://...` for mdkg
+archive sidecars and `artifact://...` for external or runtime-managed artifact
+identities.
+
+# Requested Outputs
+
+Document the output descriptors requested from the work contract.
 
 # Constraints
 

package/dist/pack/export_md.js

@@ -25,6 +25,9 @@ function renderHeader(meta, nodes) {
     if (meta.body_mode) {
         lines.push(`body_mode: ${meta.body_mode}`);
     }
+    if (meta.visibility) {
+        lines.push(`visibility: ${meta.visibility}`);
+    }
     if (meta.latest_checkpoint_qid) {
         lines.push(`latest_checkpoint_qid: ${meta.latest_checkpoint_qid}`);
     }

package/dist/pack/export_xml.js

@@ -41,6 +41,9 @@ function exportXml(pack) {
     if (pack.meta.body_mode) {
         lines.push(`    <body_mode>${escapeXml(pack.meta.body_mode)}</body_mode>`);
     }
+    if (pack.meta.visibility) {
+        lines.push(`    <visibility>${escapeXml(pack.meta.visibility)}</visibility>`);
+    }
     if (pack.meta.latest_checkpoint_qid) {
         lines.push(`    <latest_checkpoint_qid>${escapeXml(pack.meta.latest_checkpoint_qid)}</latest_checkpoint_qid>`);
     }

package/dist/pack/order.js

@@ -15,6 +15,7 @@ const FALLBACK_TYPES = [
     "feedback",
     "dispute",
     "proposal",
+    "archive",
     "epic",
     "feat",
     "task",

package/dist/pack/pack.js

@@ -1,12 +1,7 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildPack = buildPack;
-const fs_1 = __importDefault(require("fs"));
-const path_1 = __importDefault(require("path"));
-const frontmatter_1 = require("../graph/frontmatter");
+const node_body_1 = require("../graph/node_body");
 const qid_1 = require("../util/qid");
 const order_1 = require("./order");
 const verbose_core_1 = require("./verbose_core");
@@ -105,12 +100,6 @@ function buildPackNode(root, index, qid) {
     if (!node) {
         throw new Error(`node not found: ${qid}`);
     }
-    const filePath = path_1.default.resolve(root, node.path);
-    if (!fs_1.default.existsSync(filePath)) {
-        throw new Error(`file not found for ${qid}: ${node.path}`);
-    }
-    const content = fs_1.default.readFileSync(filePath, "utf8");
-    const body = (0, frontmatter_1.parseFrontmatter)(content, filePath).body.trimEnd();
     return {
         qid: node.qid,
         id: node.id,
@@ -125,7 +114,8 @@ function buildPackNode(root, index, qid) {
         refs: node.refs,
         aliases: node.aliases,
         attributes: node.attributes ?? {},
-        body,
+        ...(node.source ? { source: node.source } : {}),
+        body: (0, node_body_1.readNodeBody)(root, node),
     };
 }
 function mergeWarnings(warnings, message) {

package/dist/templates/builtin.js

@@ -0,0 +1,38 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILTIN_TEMPLATE_SET = void 0;
+exports.templateNameForType = templateNameForType;
+exports.resolveLocalTemplatePath = resolveLocalTemplatePath;
+exports.resolveBundledTemplateRoot = resolveBundledTemplateRoot;
+exports.resolveBundledTemplatePath = resolveBundledTemplatePath;
+exports.requireBundledTemplatePath = requireBundledTemplatePath;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+exports.BUILTIN_TEMPLATE_SET = "default";
+function templateNameForType(type) {
+    const normalized = type.toLowerCase();
+    if (normalized === "checkpoint") {
+        return "chk";
+    }
+    return normalized;
+}
+function resolveLocalTemplatePath(root, config, type, templateSet) {
+    const setName = (templateSet ?? config.templates.default_set).toLowerCase();
+    return path_1.default.resolve(root, config.templates.root_path, setName, `${templateNameForType(type)}.md`);
+}
+function resolveBundledTemplateRoot() {
+    return path_1.default.resolve(__dirname, "..", "init", "templates", exports.BUILTIN_TEMPLATE_SET);
+}
+function resolveBundledTemplatePath(type) {
+    return path_1.default.join(resolveBundledTemplateRoot(), `${templateNameForType(type)}.md`);
+}
+function requireBundledTemplatePath(type) {
+    const templatePath = resolveBundledTemplatePath(type);
+    if (!fs_1.default.existsSync(templatePath)) {
+        throw new Error(`bundled template fallback missing for type ${type}: ${templatePath} (try reinstalling mdkg)`);
+    }
+    return templatePath;
+}