mdkg 0.3.6 → 0.3.8

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.8`
 
 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.
@@ -29,19 +49,30 @@ The primary loop is:
 4. build a deterministic pack
 5. validate before closing the loop
 
-If an agent is involved, the default handoff primitive is `mdkg pack <id>`.
+If an agent is involved, use `mdkg pack <id>` for deterministic context and
+`mdkg handoff create <id-or-qid> --json` for a sanitized, copy-ready agent
+handoff prompt. Handoffs summarize goal/work state, included pack nodes, latest
+checkpoint, boundaries, required checks, next actions, and raw-content marker
+warnings without copying raw node bodies into the prompt.
 If a repo needs repeatable procedures, author them as first-class skills under `.mdkg/skills/`.
 
+Work nodes can separate semantic background from executable scope with
+`context_refs` and `evidence_refs`. Use `context_refs` for related plans,
+external docs, subgraph qids, or URI references that explain why work exists.
+Use `evidence_refs` for proof, audit, receipt, checkpoint, archive, or URI
+references. These fields are indexed, validated, shown, and packable, but they
+do not make referenced nodes actionable goal work; keep executable queues in
+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:
@@ -118,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
 ```
 
@@ -136,6 +167,7 @@ Build deterministic context:
 mdkg pack task-1
 mdkg pack task-1 --profile concise --dry-run --stats
 mdkg pack task-1 --visibility public --dry-run
+mdkg pack task-1 --edges context_refs,evidence_refs --format json
 ```
 
 Create a full `.mdkg` graph snapshot bundle for root or child orchestration:
@@ -208,6 +240,8 @@ Materialized trees are generated local state, ignored by graph indexing/search/v
 
 Subgraph nodes are projected under the subgraph alias, for example `child_repo:task-1`. They are available to `list`, `search`, `show`, `pack`, capability discovery, and `capability resolve`, but remain read-only; mutate the child repo and sync its root-owned bundle snapshot to change subgraph content. Root-authored relationship and reference fields can point at configured subgraph qids such as `child_repo:work.example`; local ownership fields such as `epic`, `parent`, `prev`, and `next` stay local-only. Stale subgraphs warn during planning reads and fail `mdkg subgraph verify`. Public or internal subgraphs must be backed by public bundle profiles; private subgraphs stay private planning context.
 
+Use `mdkg graph refs <id-or-qid> --json` to inspect inbound and outbound scope, context, evidence, blocker, related, and structural links for local or read-only subgraph qids without mutating either graph.
+
 Launch a local read-only MCP server when an MCP-capable agent should inspect a
 specific mdkg graph without receiving mutation tools:
 
@@ -226,6 +260,7 @@ Validate before handoff or commit:
 
 ```bash
 mdkg validate
+mdkg handoff create <id-or-qid> --out .mdkg/handoffs/example.md
 ```
 
 Discover cached capability surfaces:
@@ -235,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:
 
@@ -280,8 +317,11 @@ Update structured task state and evidence while keeping body and narrative edits
 mdkg task start task-1 --run-id run_local_1
 mdkg task update task-1 --add-artifacts tests://unit.txt --add-tags release
 mdkg task done task-1 --checkpoint "release readiness milestone"
+mdkg task done task-1 --checkpoint "goal complete" --checkpoint-kind goal-closeout
 ```
 
+Checkpoint kinds are `implementation`, `test-proof`, `goal-closeout`, `audit`, and `handoff`; generated checkpoint bodies include command evidence, pass/fail status, known warnings, changed surfaces, boundaries, and follow-up refs.
+
 Ensure and append baseline event memory:
 
 ```bash
@@ -359,6 +399,15 @@ Advanced / maintenance commands still exist, but they are not the first-run stor
 - `mdkg fix plan --json`
 - `mdkg workspace`
 
+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 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
 
 Use `mdkg status --json` for a read-only operator summary before mutating a
@@ -437,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
 
@@ -478,6 +527,12 @@ rows are durable local project DB history; receipts, reducers, writer leases,
 and materializers remain internal helper surfaces in this release, with no
 public `mdkg db event`, `mdkg db reducer`, `mdkg db lease`, or
 `mdkg db materializer` CLI yet.
+`mdkg db queue contract --json` is the read-only public adapter contract for
+downstream integrations. It documents canonical payload hashing, dedupe keys,
+oldest-ready claim order, lease-owner checked ack/fail/dead-letter, retry
+delay, expired lease reclaim, max-attempt dead-letter behavior, pause/resume,
+snapshot queue policy, and stats without exposing raw SQL or making queue rows
+canonical runtime history.
 `mdkg work trigger --enqueue <queue>` can bridge a submitted work order mirror
 into an explicitly created active project DB queue; it writes local delivery
 state only and never executes work.
@@ -505,7 +560,7 @@ Goal nodes are durable recursive objective contracts. Use `mdkg new goal "<objec
 
 `goal` is work-like but distinct from `task`: it can have status, priority, graph links, skills, explicit `scope_refs`, and structured goal fields, but normal `mdkg next` does not select goals. Use `mdkg goal activate <goal-id>` to make one local root goal active, pause competing local active goals, and select it for future `goal next` calls. Use `mdkg goal select <goal-id>` only when you want to change the local ignored selected-goal pointer without changing lifecycle state. `mdkg goal next <goal-id>` remains available for explicit selection. Epics organize goal scope recursively but are not returned as executable work.
 
-Use `mdkg goal claim [goal-id] <work-id>` to durably set `active_node` after choosing the next scoped item. `goal next` is read-only. Use `mdkg goal pause|resume|done` to update goal state after review, and `mdkg goal archive` for superseded historical roadmap goals that should remain readable but non-actionable.
+Use `mdkg goal claim [goal-id] <work-id>` to durably set `active_node` after choosing the next scoped item. `goal next` is read-only. Use `mdkg goal pause|resume|done` to update goal state after review; closing a goal moves the final `active_node` to `last_active_node` so completed goals keep history without staying actionable. Use `mdkg goal archive` for superseded historical roadmap goals that should remain readable but non-actionable.
 
 Required checks are stored as report-only guidance. Agents should run the checks themselves, record evidence in the goal or active work item, then use `mdkg goal evaluate` to summarize the current evidence state. During normal goal execution, skill improvements should be recorded as improvement candidates or proposal nodes; edit `SKILL.md` files only when the active node is explicit skill-maintenance work.
 
@@ -535,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 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
 
@@ -566,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`