mdkg 0.3.7 → 0.3.9

package/CHANGELOG.md

@@ -8,6 +8,56 @@ mdkg is pre-v1 public alpha software. Command, graph, cache, bundle, and DAL con
 
 ## Unreleased
 
+## 0.3.9 - 2026-06-27
+
+### Added
+
+- Added `.mdkg/config.json` customization overlays for organization standards,
+  custom core docs, and configured skill mirror target paths while keeping the
+  mdkg CLI kernel upgradable through `mdkg upgrade --apply`.
+- Added configurable skill mirror support so repos can mirror canonical
+  `.mdkg/skills` into arbitrary contained agent-local skill roots, with
+  `.agents/skills` and `.claude/skills` preserved as defaults.
+- Added `COLLABORATION.md` as the canonical collaboration/operator profile core
+  doc while keeping `HUMAN.md` as a one-release legacy alias.
+- Added deterministic release-notes data generation from `CHANGELOG.md` for
+  public docs and future per-release cards.
+
+### Changed
+
+- Updated `mdkg init --agent` and `mdkg upgrade --apply` to seed and preserve
+  customization overlays, configurable mirrors, `COLLABORATION.md`, legacy
+  `HUMAN.md`, and accurate managed init-manifest hashes.
+- Refreshed first-party mdkg skills and default init seed skills for current CLI
+  coverage, MANIFEST authoring, configured mirror targets, pre-publish gates,
+  and explicit no-publish/no-tag/no-push approval boundaries.
+- Expanded `npm run docs:check` and `prepublishOnly` to verify generated CLI
+  docs, generated release-note data, and public command examples before publish.
+
+## 0.3.8 - 2026-06-25
+
+### Added
+
+- Planned and began a warning-scale UX hardening lane for large multi-repo
+  mdkg orchestration runs.
+- Added bounded validation warning summaries, summary-mode output, and a clean
+  JSON receipt artifact path for warning-heavy validation workflows.
+- Added heading formatter summary-mode output for large recommended-heading
+  migration previews.
+- Added a packed warning UX smoke to prepublish automation so high-volume
+  warning output regressions are caught before release.
+
+### Changed
+
+- Renamed the reusable capability surface to canonical `MANIFEST.md`
+  terminology across scaffolds, help, command references, init assets, and
+  skills. `SPEC.md` and `mdkg spec ...` remain explicit legacy aliases for one
+  compatibility release, with manifest-first warnings and migration guidance.
+- Improved strict doctor, subgraph, and handoff remediation guidance for
+  multi-repo operators.
+- Updated repo-local skill guidance for child-first commit and root subgraph
+  refresh sequencing.
+
 ## 0.3.7 - 2026-06-20
 
 ### Added

package/CLI_COMMAND_MATRIX.md

@@ -1,7 +1,7 @@
 # CLI Command Matrix
 
-as_of: 2026-06-17
-package_version_in_source: 0.3.6
+as_of: 2026-06-21
+package_version_in_source: 0.3.9
 source: live help from `src/cli.ts`, runtime command handlers, and `dec-15`..`dec-18`
 status: canonical single-source command and flag reference for mdkg
 
@@ -12,6 +12,18 @@ This file is the one place humans and LLMs should check for the live mdkg comman
 Verification commands:
 - `npm run cli:snapshot`
 - `npm run cli:check`
+- `npm run docs:check`
+- `npm run smoke:mdkg-dev`
+- `npm run smoke:mdkg-dev-docs`
+- `npm run smoke:mdkg-dev-seo`
+- `npm run smoke:demo-graph`
+
+mdkg.dev launch-readiness surfaces in this repo:
+- `mdkg-dev/` is the Astro static-site subproject.
+- `docs/` is the Starlight docs subproject and repo-first documentation source plus generated command-reference output.
+- `examples/` contains local mdkg demo/template graphs for agentic-coding and website-generation demos.
+- `demo_agentic_coding:goal-1` and `template_mdkg_dev:goal-1` are private read-only subgraph qids after the root bundles are registered.
+- Site/docs/demo assets are not npm runtime payload and must not imply production deploy, DNS change, analytics activation, or durable demo promotion.
 
 ## Teaching model
 
@@ -55,7 +67,8 @@ Advanced / maintenance commands:
 Skills are first-class and are accessed only through `mdkg skill ...`.
 Generic `list/show/search` do not expose skills.
 Capability cache discovery is read-only and accessed through `mdkg capability ...`.
-Optional reusable SPEC capability records are accessed through `mdkg spec ...`.
+Reusable manifest capability records are accessed through `mdkg manifest ...`;
+`mdkg spec ...` remains a one-compatibility-release legacy alias.
 Archive sidecars are accessed through `mdkg archive ...`.
 Full graph snapshot bundles are accessed through `mdkg bundle ...`.
 Whole-graph clone, fork, and same-repo template import workflows are accessed through `mdkg graph ...`.
@@ -105,7 +118,7 @@ Notes:
 - `--agent` is the canonical complete AI-agent bootstrap path
 - removed flags `--llm`, `--agents`, `--claude`, and `--omni` fail before mutation with guidance to use `mdkg init --agent`
 - published bootstrap config is root-only by default
-- `--agent` creates `AGENT_START.md`, `AGENTS.md`, `CLAUDE.md`, `llms.txt`, `CLI_COMMAND_MATRIX.md`, strict-node core docs, default mdkg usage skills, `events.jsonl`, registry, and skill mirrors
+- `--agent` creates `AGENT_START.md`, `AGENTS.md`, `CLAUDE.md`, `llms.txt`, `CLI_COMMAND_MATRIX.md`, strict-node `SOUL.md` / `COLLABORATION.md` core docs, legacy `HUMAN.md`, default mdkg usage skills, `events.jsonl`, registry, and configured skill mirrors
 - run `mdkg index` after fresh init before treating `mdkg doctor --strict --json` as a clean health gate; init writes source scaffold files and index writes generated caches
 
 ### `mdkg upgrade`
@@ -156,22 +169,26 @@ Types:
 - `test`
 
 Agent workflow file types:
-- `spec`
+- `manifest`
 - `work`
 - `work_order`
 - `receipt`
 - `feedback`
 - `dispute`
 - `proposal`
+- `spec` is a legacy alias for `manifest` during the compatibility bridge and
+  emits `MANIFEST.md`.
 
 Agent workflow file type creation:
-- `mdkg new spec "<title>" [options] [--json]`
+- `mdkg new manifest "<title>" [options] [--json]`
 - `mdkg new work "<title>" [options] [--json]`
 - `mdkg new work_order "<title>" [options] [--json]`
 - `mdkg new receipt "<title>" [options] [--json]`
 - `mdkg new feedback "<title>" [options] [--json]`
 - `mdkg new dispute "<title>" [options] [--json]`
 - `mdkg new proposal "<title>" [options] [--json]`
+- `mdkg new spec "<title>" [options] [--json]` is a deprecated alias for
+  `mdkg new manifest` and creates `MANIFEST.md` with `type: manifest`.
 
 Goal node creation:
 - `mdkg new goal "<title>" [options] [--json]`
@@ -426,7 +443,9 @@ JSON receipt:
 - `{ action: "synced", sync: { synced, pruned, targets } }`
 
 Notes:
-- syncs canonical `.mdkg/skills/` into `.agents/skills/` and `.claude/skills/`
+- syncs canonical `.mdkg/skills/` into configured
+  `customization.skill_mirrors.targets` paths from `.mdkg/config.json`
+- defaults are `.agents/skills` and `.claude/skills`
 - preserves unrelated existing folders
 - same-slug collisions fail unless forced
 
@@ -514,7 +533,7 @@ Notes:
 
 When to use:
 - discover deterministic capability surfaces across enabled workspaces
-- query skills, `SPEC.md`, `WORK.md`, core docs, and design docs without loading the whole graph body set
+- query skills, canonical `MANIFEST.md`, legacy `SPEC.md`, `WORK.md`, core docs, and design docs without loading the whole graph body set
 
 Usage:
 - `mdkg capability list [--kind <kind>] [--visibility <level>] [--json]`
@@ -539,17 +558,48 @@ Notes:
 - `capability resolve` ranks local and subgraph capabilities deterministically for orchestration planning
 - stale subgraphs remain visible with degraded ranking unless `--fresh-only` is supplied
 - records include deterministic source metadata such as workspace, visibility, kind, id/qid/slug, path, headings, refs, source hash, and `indexed_at`
-- SPEC and WORK capability records include read-only `linkage` arrays for related SPECs, work contracts, work orders, and receipts when those graph mirrors exist
+- MANIFEST/SPEC and WORK capability records include read-only `linkage` arrays for related manifests, work contracts, work orders, and receipts when those graph mirrors exist
 - `.mdkg/index/capabilities.json` is rebuilt by `mdkg index` and by capability commands when stale
 - normal task, epic, feat, bug, test, spike, and checkpoint nodes are intentionally excluded
 - visibility is mdkg export metadata used by capability filters, `pack --visibility`, public bundle checks, validation, and doctor diagnostics; it is not secret scanning or body redaction
 
+### `mdkg manifest`
+
+When to use:
+- list reusable capability surfaces from canonical `MANIFEST.md` or legacy
+  `SPEC.md`
+- show one manifest capability record by id, qid, path, or alias
+- validate the graph while ensuring a named manifest capability exists
+
+Usage:
+- `mdkg manifest list [--json]`
+- `mdkg manifest show <id-or-qid-or-alias> [--json]`
+- `mdkg manifest validate [<id-or-qid-or-alias>] [--json]`
+
+Flags:
+- `--json`
+
+Notes:
+- `MANIFEST.md` is canonical and `SPEC.md` remains a legacy alias; repos with no
+  manifest/spec files remain valid
+- manifest records are reusable-capability oriented, not documentation-only
+  planning notes
+- `mdkg manifest validate` with no ref validates the graph and all
+  manifest/spec records
+- `mdkg manifest validate <ref>` also checks that the target manifest reference
+  exists
+- JSON records keep capability `kind: spec` for compatibility and include
+  manifest metadata describing canonical, legacy, or transitional source mode
+- use `mdkg capability ...` for broader skill, MANIFEST/SPEC, WORK, core-doc,
+  and design-doc capability discovery
+
 ### `mdkg spec`
 
 When to use:
-- list optional `SPEC.md` reusable capability surfaces
-- show one SPEC capability record by id, qid, path, or alias
-- validate the graph while ensuring a named SPEC capability exists
+- temporarily support existing scripts during the one-compatibility-release
+  bridge to `mdkg manifest ...`
+- list, show, or validate the same MANIFEST/SPEC capability records with legacy
+  command labeling
 
 Usage:
 - `mdkg spec list [--json]`
@@ -560,11 +610,14 @@ Flags:
 - `--json`
 
 Notes:
-- `SPEC.md` is optional; repos with no SPEC files remain valid
-- SPEC records are reusable-capability oriented, not documentation-only planning notes
-- `mdkg spec validate` with no ref validates the graph and all optional SPEC records
-- `mdkg spec validate <ref>` also checks that the target SPEC reference exists
-- use `mdkg capability ...` for broader skill, SPEC, WORK, core-doc, and design-doc capability discovery
+- `mdkg spec` is a legacy alias for `mdkg manifest` during the compatibility
+  bridge
+- `mdkg spec validate` with no ref validates the graph and all manifest/spec
+  records
+- `mdkg spec validate <ref>` also checks that the target manifest reference
+  exists
+- JSON receipts keep `kind: spec` and add `canonical_kind: manifest`,
+  `legacy_alias: true`, and deprecation metadata
 
 ### `mdkg archive`
 
@@ -776,21 +829,21 @@ Usage:
 - `mdkg work receipt update <id-or-qid> [--receipt-status <status>] [--add-artifacts <...>] [--add-proof-refs <...>] [--add-attestation-refs <...>] [--add-evidence-hashes <sha256:...>] [--json]`
 - `mdkg work artifact add <order-or-receipt-id-or-qid> <file> [--id <archive.id>] [--kind source|artifact] [--json]`
 - `mdkg work validate [<id-or-qid>] [--type <workflow-type>] [--json]`
-- `mdkg work validate [<id-or-qid>] [--type spec|work|work_order|receipt|feedback|dispute|proposal] [--json]`
+- `mdkg work validate [<id-or-qid>] [--type manifest|spec|work|work_order|receipt|feedback|dispute|proposal] [--json]`
 
 Notes:
 - work commands mutate 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 trigger` accepts a `WORK.md` ref directly or a `SPEC.md` capability ref with exactly one resolvable work contract; it creates a submitted order mirror and never executes work
+- `work trigger` accepts a `WORK.md` ref directly or a `MANIFEST.md` / legacy `SPEC.md` capability ref with exactly one resolvable work contract; it creates a submitted order mirror and never executes work
 - example: `mdkg work trigger work.example --id order.example-1 --requester user://example --json`
 - `work trigger --enqueue <queue>` requires a valid project DB plus an explicitly created active queue, creates a submitted order mirror, and enqueues a local delivery message without executing work
 - `work order new` accepts URI-style requester/request/trigger refs, archive input refs, optional queue refs, and stable payload hashes
 - `work order status` is read-only and reports deterministic order state plus linked receipts
 - `work receipt new` accepts URI-style cost/proof/attestation refs, explicit redaction policy, and SHA-256 evidence/input/output hash refs
 - `work receipt verify` is read-only and reports linkage, evidence, archive ref, hash, outcome, and redaction-policy checks; invalid receipts print JSON before exiting nonzero
-- `work validate` is read-only and reports typed diagnostics for SPEC.md, WORK.md, WORK_ORDER.md, RECEIPT.md, FEEDBACK.md, DISPUTE.md, and PROPOSAL.md mirrors; obvious raw secret, prompt, token, or payload markers are warnings, not hard failures
+- `work validate` is read-only and reports typed diagnostics for MANIFEST.md, legacy SPEC.md, WORK.md, WORK_ORDER.md, RECEIPT.md, FEEDBACK.md, DISPUTE.md, and PROPOSAL.md mirrors; obvious raw secret, prompt, token, or payload markers are warnings, not hard failures
 - `work artifact add` calls `mdkg archive add`, then attaches the resulting `archive://...` ref to the target order or receipt
 - `work order update`, `work receipt update`, and `work artifact add` accept local ids or local qids; subgraph qids are read-only and must be changed in their source workspace
 
@@ -937,18 +990,25 @@ When to use:
 - run the repo trust gate before calling work done
 
 Usage:
-- `mdkg validate [--out <path>] [--quiet] [--changed-only] [--json]`
+- `mdkg validate [--out <path>] [--json-out <path>] [--quiet] [--changed-only] [--summary] [--limit <n>] [--json]`
 - `--changed-only` filters warning presentation to changed `.mdkg` files while full graph errors still run
-- JSON receipts include `warning_diagnostics` with warning ids, categories, severity, paths, refs, and remediation text
+- `--summary` emits bounded warning samples for agent/CI logs; `--limit <n>` controls the sample size
+- `--out <path>` writes the compatibility text report; `--json-out <path>` writes a clean full JSON receipt
+- JSON receipts include `warning_summary` and `warning_diagnostics` with warning ids, categories, severity, paths, refs, and remediation text
 
 Flags:
 - `--out <path>`
+- `--json-out <path>`
 - `--quiet`
+- `--changed-only`
+- `--summary`
+- `--limit <n>`
 - `--json`
 
 JSON receipt:
-- `{ action: "validated", ok, warning_count, error_count, warnings, errors, report_path }`
+- `{ action: "validated", ok, warning_count, error_count, warnings, warning_diagnostics, warning_summary, errors, report_path?, json_receipt_path? }`
 - `report_path` is included only when `--out` is used.
+- `json_receipt_path` is included only when `--json-out` is used.
 
 Notes:
 - validates nodes, graph integrity, skills, and event log contracts
@@ -1107,11 +1167,12 @@ Usage:
 
 Usage:
 - `mdkg format`
-- `mdkg format --headings [--dry-run|--apply] [--json]`
+- `mdkg format --headings [--dry-run|--apply] [--summary] [--limit <n>] [--json]`
 
 Notes:
 - default `mdkg format` normalizes frontmatter in place
 - `mdkg format --headings` defaults to dry-run and returns planned missing-heading additions
+- `--summary` emits bounded heading-change samples for agent/CI logs; `--limit <n>` controls the sample size
 - `mdkg format --headings --apply` appends missing recommended body headings and returns a migration receipt
 
 ### `mdkg status`

package/README.md

@@ -1,6 +1,6 @@
 # mdkg
 
-mdkg is a local-first CLI for turning structured Markdown into deterministic project memory.
+Markdown Knowledge Graph (`mdkg`) is Git-native project memory for AI coding agents: structured Markdown, deterministic context packs, handoffs, checkpoints, and validation.
 
 It is built for:
 - human builders who want project truth and task state in git
@@ -14,10 +14,30 @@ mdkg stays deliberately boring:
 - first-class rebuildable SQLite cache through built-in `node:sqlite`
 - no daemon, hosted index, or vector DB
 
-Current package version in source: `0.3.6`
+Current package version in source: `0.3.9`
 
 mdkg is still pre-v1 public alpha software. The public package is usable, but graph, cache, bundle, and DAL contracts may continue to change quickly while the project converges on a stable v1 surface.
 
+## mdkg.dev launch workspace
+
+This repo now owns the prelaunch mdkg.dev source layout:
+
+- `mdkg-dev/` is the Astro static-site subproject for the canonical public site.
+- `docs/` is the Starlight docs subproject and repo-first documentation source plus generated command-reference output.
+- `examples/` contains local demo/template mdkg graphs for agentic coding and mdkg.dev website-generation demos.
+
+These surfaces are intentionally excluded from the npm package payload. They are source and launch-readiness assets, not runtime CLI dependencies. The launch gates are local and deterministic:
+
+```bash
+npm run docs:check
+npm run smoke:mdkg-dev
+npm run smoke:mdkg-dev-docs
+npm run smoke:mdkg-dev-seo
+npm run smoke:demo-graph
+```
+
+The canonical site remains `mdkg.dev`. Demo graphs and preview deploys are separate from canonical SEO; durable `demo-N.mdkg.dev` promotion and any production deployment require explicit later approval.
+
 ## The product shape
 
 mdkg has one core job: make repo knowledge cheap to retrieve and safe to reuse.
@@ -47,13 +67,12 @@ goal `scope_refs`.
 ## Install
 
 ```bash
-npm i -g mdkg
-# or
-pnpm add -g mdkg
-# or
-bun add -g mdkg
+npm install -g mdkg
+mdkg --version
 ```
 
+The npm global install path is the canonical public-alpha path covered by release validation. One-off runners and other package managers may be useful in local tooling, but verify them before documenting them for a team.
+
 ## Quickstart
 
 Initialize mdkg in a repo:
@@ -63,7 +82,7 @@ mdkg init --agent
 mdkg index
 ```
 
-This is the canonical AI-agent bootstrap path. It creates `.mdkg/`, `AGENT_START.md`, `AGENTS.md`, `CLAUDE.md`, `llms.txt`, `CLI_COMMAND_MATRIX.md`, strict-node `SOUL.md` / `HUMAN.md`, the three default mdkg usage skills, `events.jsonl`, the skill registry, core pin updates, and mirrored skill folders under `.agents/skills/` and `.claude/skills/`. It also updates `.gitignore` / `.npmignore` by default. Use `--no-update-ignores` to opt out of those ignore-file updates.
+This is the canonical AI-agent bootstrap path. It creates `.mdkg/`, `AGENT_START.md`, `AGENTS.md`, `CLAUDE.md`, `llms.txt`, `CLI_COMMAND_MATRIX.md`, strict-node `SOUL.md` / `COLLABORATION.md`, legacy `HUMAN.md` for one release, the default mdkg usage skills, `events.jsonl`, the skill registry, core pin updates, and configured skill mirrors under `.agents/skills/` and `.claude/skills/` by default. It also updates `.gitignore` / `.npmignore` by default. Use `--no-update-ignores` to opt out of those ignore-file updates.
 
 Run `mdkg index` after a fresh init before using `mdkg status --json` or
 `mdkg doctor --strict --json` as health gates. Init writes source scaffold
@@ -130,7 +149,7 @@ mdkg new task "author mdkg.dev launch planning skill" --parent spike-1 --status
 Create an agent workflow document with a semantic portable id:
 
 ```bash
-mdkg new spec "image worker" --id agent.image-worker
+mdkg new manifest "image worker" --id agent.image-worker
 mdkg new work "generate image" --id work.generate-image
 ```
 
@@ -251,15 +270,17 @@ mdkg index
 mdkg capability list --kind skill --json
 mdkg capability search "image worker" --kind work --json
 mdkg capability show <id-or-qid-or-slug> --json
-mdkg spec list --json
-mdkg spec show <id-or-qid-or-alias> --json
+mdkg manifest list --json
+mdkg manifest show <id-or-qid-or-alias> --json
 ```
 
-`SPEC.md` is optional. Repos with no SPEC files still validate; when present,
-SPEC records describe reusable capability surfaces rather than general planning
-notes. `mdkg spec list/show/validate` is the focused SPEC command family, while
-`mdkg capability ...` remains the broader read-only discovery surface for
-skills, SPECs, WORK contracts, core docs, and design docs.
+`MANIFEST.md` is optional. Repos with no manifest files still validate; when
+present, manifest records describe reusable capability surfaces rather than
+general planning notes. `SPEC.md` remains a legacy alias for one compatibility
+release, and `mdkg spec list/show/validate` remains a deprecated alias for
+`mdkg manifest list/show/validate`. `mdkg capability ...` remains the broader
+read-only discovery surface for skills, manifests, WORK contracts, core docs,
+and design docs.
 
 Register source and artifact files as committed archive sidecars:
 
@@ -380,8 +401,12 @@ Advanced / maintenance commands still exist, but they are not the first-run stor
 
 For large historical graphs, use `mdkg validate --changed-only --json` to keep
 warning review focused on changed `.mdkg` files while full graph errors still
-run. Use `mdkg format --headings --dry-run --json` to review missing recommended
-heading additions before applying them with `--apply`.
+run. Use `mdkg validate --summary --json --limit 20` for bounded agent or CI
+logs, and add `--json-out <path>` when a clean full JSON receipt should be
+written as an artifact. Use
+`mdkg format --headings --dry-run --summary --json --limit 20` to review missing
+recommended heading additions with bounded output before applying them with
+`--apply`.
 
 ## Operator health
 
@@ -461,14 +486,14 @@ Optional skill metadata with prefixes such as `ochatr_*` is treated as vendor ex
 
 mdkg maintains `.mdkg/index/capabilities.json` as a derived access cache for deterministic capability surfaces:
 - skills from `.mdkg/skills/**/SKILL.md`
-- `SPEC.md`
+- canonical `MANIFEST.md` and legacy `SPEC.md`
 - `WORK.md`
 - core docs
 - design docs
 
 The capability cache is not the full graph and is not source of truth. Normal tasks, epics, bugs, tests, feats, and checkpoints remain in the standard graph index. Markdown remains authoritative; deleting the cache is recoverable with `mdkg index` or by running a capability command when auto-reindex is enabled.
 
-Capability records aggregate enabled registered workspaces and include deterministic source metadata such as `workspace`, `visibility`, `kind`, `id`, `qid`, `path`, headings, refs, source hash, and `indexed_at`. SPEC and WORK records also expose read-only `linkage` arrays when related work contracts, work orders, and receipts exist, so an orchestrator can discover a capability from reusable surface to invocation evidence without loading the full graph. Workspace `visibility` also feeds mdkg's export safety checks for public/internal packs and public bundles. This is a CLI safety layer, not secret scanning, body redaction, or a replacement for private git hosting.
+Capability records aggregate enabled registered workspaces and include deterministic source metadata such as `workspace`, `visibility`, `kind`, `id`, `qid`, `path`, headings, refs, source hash, and `indexed_at`. MANIFEST/SPEC and WORK records also expose read-only `linkage` arrays when related work contracts, work orders, and receipts exist, so an orchestrator can discover a capability from reusable surface to invocation evidence without loading the full graph. Workspace `visibility` also feeds mdkg's export safety checks for public/internal packs and public bundles. This is a CLI safety layer, not secret scanning, body redaction, or a replacement for private git hosting.
 
 ## Index backends and parallel safety
 
@@ -565,17 +590,17 @@ or agents can intentionally create the next nodes with normal mdkg commands.
 ## Agent workflow files
 
 mdkg recognizes a small set of canonical agent workflow documents:
-- `SPEC.md` for agent, package, or runtime specifications
+- `MANIFEST.md` for agent, package, or runtime capability manifests
 - `WORK.md` for reusable work contracts
 - `WORK_ORDER.md` for concrete requests against work contracts
 - `RECEIPT.md` for completed work output and artifacts
 - `FEEDBACK.md`, `DISPUTE.md`, and `PROPOSAL.md` for review loops
 
-Use `mdkg new spec|work|work_order|receipt|feedback|dispute|proposal "<title>"` to scaffold them. `--id <portable-id>` is available for these types when semantic ids such as `agent.image-worker` or `work.generate-image` are preferred.
+Use `mdkg new manifest|work|work_order|receipt|feedback|dispute|proposal "<title>"` to scaffold them. `mdkg new spec` remains a deprecated alias that emits `MANIFEST.md` during the compatibility bridge. `--id <portable-id>` is available for these types when semantic ids such as `agent.image-worker` or `work.generate-image` are preferred.
 
-Relational templates contain editable placeholder refs. `spec` and `work` scaffold as validation-clean standalone docs; `work_order`, `receipt`, `feedback`, `dispute`, and `proposal` need real refs before strict `mdkg validate` passes.
+Relational templates contain editable placeholder refs. `manifest` and `work` scaffold as validation-clean standalone docs; `work_order`, `receipt`, `feedback`, `dispute`, and `proposal` need real refs before strict `mdkg validate` passes.
 
-For executable or purchasable capability mirrors, prefer the lifecycle helpers under `mdkg work ...`. They create and update `WORK.md`, `WORK_ORDER.md`, and `RECEIPT.md` semantic mirror files only. `mdkg work trigger` creates a deterministic submitted `WORK_ORDER.md` from a WORK contract or a SPEC with exactly one resolvable work contract. `mdkg work order status` and `mdkg work receipt verify` are read-only review helpers for deterministic closeout. `mdkg work validate [<id-or-qid>] [--type spec|work|work_order|receipt|feedback|dispute|proposal] --json` is a read-only focused validator for agent workflow mirrors; it returns typed diagnostics and warns on obvious raw secret, prompt, token, or payload markers. `mdkg work trigger --enqueue <queue>` optionally writes a local project DB queue delivery message after the queue has been explicitly created and is active; it still does not execute work. Production order state, receipt state, feedback, disputes, payments, ledgers, marketplace inventory, fulfillment records, and execution state remain canonical outside mdkg, such as in Postgres or another application database. Do not store raw secrets, credentials, live payment state, ledger mutations, canonical marketplace state, or bulky raw payloads in these mirrors.
+For executable or purchasable capability mirrors, prefer the lifecycle helpers under `mdkg work ...`. They create and update `WORK.md`, `WORK_ORDER.md`, and `RECEIPT.md` semantic mirror files only. `mdkg work trigger` creates a deterministic submitted `WORK_ORDER.md` from a WORK contract or a MANIFEST with exactly one resolvable work contract; legacy SPEC refs remain supported during the compatibility bridge. `mdkg work order status` and `mdkg work receipt verify` are read-only review helpers for deterministic closeout. `mdkg work validate [<id-or-qid>] [--type manifest|spec|work|work_order|receipt|feedback|dispute|proposal] --json` is a read-only focused validator for agent workflow mirrors; it returns typed diagnostics and warns on obvious raw secret, prompt, token, or payload markers. `mdkg work trigger --enqueue <queue>` optionally writes a local project DB queue delivery message after the queue has been explicitly created and is active; it still does not execute work. Production order state, receipt state, feedback, disputes, payments, ledgers, marketplace inventory, fulfillment records, and execution state remain canonical outside mdkg, such as in Postgres or another application database. Do not store raw secrets, credentials, live payment state, ledger mutations, canonical marketplace state, or bulky raw payloads in these mirrors.
 
 ## Archive sidecars
 
@@ -596,8 +621,8 @@ This release includes:
 - default ignore updates with `--no-update-ignores` for generated JSON index/temp/lock files, `.mdkg/pack/`, and raw archive source copies
 - root-only published init seed config
 - skills indexing and search/show/list support
-- JSON capability cache for skills, `SPEC.md`, `WORK.md`, core docs, and design docs
-- optional `mdkg spec list/show/validate` for reusable SPEC capability records
+- JSON capability cache for skills, `MANIFEST.md` / legacy `SPEC.md`, `WORK.md`, core docs, and design docs
+- optional `mdkg manifest list/show/validate` for reusable manifest capability records, with `mdkg spec ...` retained as a legacy alias for one compatibility release
 - SQLite index backend for fresh workspaces using built-in `node:sqlite`
 - mutation locking and atomic writes for parallel mdkg calls
 - first-class `goal` nodes and `mdkg goal show/next/evaluate/pause/resume/done`