mdkg

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
• AI agents that need deterministic context instead of ad-hoc file reading
• human + agent pairs who want one shared source of truth

mdkg stays deliberately boring:

• repo-native under .mdkg/
• TypeScript + Node.js >=24.18.0 <25
• zero third-party runtime dependencies
• first-class rebuildable SQLite cache through built-in node:sqlite
• no daemon, hosted index, or vector DB

Current package version in source: 0.6.0

The 0.6.0 source is an unpublished qualification candidate, not a registry availability claim. Published 0.5.2 has different bootstrap and Git command behavior; the install command below selects the registry version, not this working tree. Check the installed version and the candidate artifact receipt. Final macOS/Linux qualification and security acceptance are still required. Windows is explicitly unqualified. See the 0.6.0 change notes.

The candidate uses built-in Node APIs, not an mdkg-owned native addon or OS-specific SQLite path. Node 24.18+ within the 24 line is required, including DatabaseSync.deserialize, setAuthorizer, enableDefensive and process.availableMemory. Unsupported runtimes refuse before graph discovery or mutation; help and version remain available. Node 24.15 and the tested Node 26.0 do not provide the required API set. Higher majors are not implicitly supported. SQLite observations use memory proportional to the database image and refuse insufficient available memory rather than opening a writable file.

Use a cooperative, access-controlled checkout with one writer per checkout. Preservation of restrictive per-file ACL/owner metadata and resistance to adversarial ancestor-directory replacement remain deferred and unresolved for 0.6.0; they are not fixed or accepted findings. These limits are distinct from ordinary link/type/custody checks, which remain enforced.

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:

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.

The primary loop is:

1. initialize the repo
2. create or select work
3. inspect the current truth
4. build a deterministic pack
5. validate before closing the loop

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

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:

mdkg init
mdkg index

Compact agent setup is the default in the 0.6.0 candidate. Root AGENTS.md and CLAUDE.md contain bounded mdkg-managed sections pointing to .mdkg/AGENT_START.md. Detailed generated discovery lives in .mdkg/llms.txt and .mdkg/CLI_COMMAND_MATRIX.md; canonical skills live in .mdkg/skills/, with default native mirrors under .agents/skills/ and .claude/skills/. Core guidance, templates, the skill registry and event history live under .mdkg/. Existing user instructions outside managed sections, project README, LICENSE and public website discovery files are preserved. Init also updates .gitignore / .npmignore by default; use --no-update-ignores to opt out.

Run mdkg index after a fresh init before using mdkg status --json or mdkg doctor --strict --json as health gates. Init writes source scaffold files; indexing creates the generated graph, skill, capability, subgraph, and SQLite caches that strict doctor expects.

For a graph without agent bootstrap assets, run mdkg init --graph-only. mdkg init --agent remains a compatibility spelling for compact setup; do not combine it with --graph-only. Published 0.5.2 used the older opt-in agent layout; check mdkg --version when following candidate instructions.

Preview safe scaffold upgrades in an existing mdkg workspace:

mdkg upgrade
mdkg upgrade --json

Apply only after reviewing the receipt. Replace PLAN_HASH with its exact plan_hash; pending writes without that reviewed hash are rejected:

mdkg upgrade --apply --plan-hash PLAN_HASH

Upgrade is intentionally conservative. It creates missing managed startup docs and templates, updates unchanged mdkg seed assets, and preserves customized docs, templates, skills, and core files as reported preserved customizations. Review safe_to_apply, will_write_paths, and apply_side_effects in the JSON receipt before applying. Agent-enabled workspaces can receive safe default skill upgrades and skill mirror refreshes; ignored event logs are skipped with guidance to run mdkg event enable if provenance should be restored.

Managed-section edits or stale plans block application rather than overwrite user content. Known generated legacy root guides can become compatibility redirects only with manifest/hash provenance; customized root guides and public llms.txt files remain separate. Review reported conflicts and explicitly selected safe subsets instead of treating every same-named file as generated. Interrupted upgrades require explicit mdkg upgrade --resume --plan-hash PLAN_HASH or mdkg upgrade --recover --plan-hash PLAN_HASH using the hash retained from the reviewed preview, not a replacement hash supplied by edited journal data. Recovery refuses subsequent user edits; it is not a blanket filesystem rollback.

On adopted v2 graphs, scaffold upgrades preserve node identities and aliases; restoring a missing node requires explicit graph creation or reintroduction, not an identity-free seed copy. Schema3 journals bind the complete approved plan, including operations, graph-format bytes and preview dependencies. Changed inputs block resume and recovery. Unbound schema1/2 journals remain inspectable but cannot automatically resume or recover on any graph version. Preserve the journal and affected files for explicit investigation; do not delete it or edit its hash to bypass refusal. This is local approval consistency, not external attestation.

Older workspaces can continue to inspect and validate current graph nodes before applying an upgrade. When local templates are missing for newly introduced built-in mdkg types, mdkg uses the installed package's bundled templates as a read-only schema fallback and warns that mdkg upgrade --apply can vendor the missing templates.

Create a task:

mdkg new task "bootstrap cli" --status todo --priority 1 --tags cli,build

Create a recursive goal for long-running agent work:

mdkg new goal "reach prepublish readiness"
mdkg goal show goal-1 --json
mdkg goal next goal-1
mdkg goal evaluate goal-1 --json

Goal nodes capture a measurable end condition, recursive loop state, required skills, required checks, and completion evidence. They guide agent harnesses through repeated graph-backed progress, while tasks, bugs, tests, spikes, and features remain the concrete executable work units. In this release mdkg goal evaluate is report-only: it lists required checks and evidence state, but does not execute scripts.

Create a research spike when the next useful work is investigation, planning, or grounding a future implementation:

mdkg new spike "research mdkg.dev launch guide" --status todo --priority 1
mdkg task start spike-1
mdkg show spike-1

Spikes are task-like work nodes, not autonomous research agents. mdkg does not perform web search, execute research, create follow-up nodes, or generate SKILL.md files automatically. Record sources, findings, tradeoffs, recommendations, follow-up node ideas, and skill candidates in the spike body, then create follow-up work intentionally:

mdkg new task "write mdkg.dev quickstart guide" --parent spike-1 --status todo --priority 1
mdkg new test "validate mdkg.dev docs examples" --parent spike-1 --status todo --priority 1
mdkg new task "author mdkg.dev launch planning skill" --parent spike-1 --status todo --priority 2

Create an agent workflow document with a semantic portable id:

mdkg new manifest "image worker" --id agent.image-worker
mdkg new work "generate image" --id work.generate-image

Inspect the current truth:

mdkg search "pack"
mdkg show task-1
mdkg next

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:

mdkg archive compress --all
mdkg archive verify --json
mdkg bundle create --profile private
mdkg bundle verify .mdkg/bundles/private/all.mdkg.zip
mdkg bundle list --json

Bundles are explicit graph transport artifacts, separate from task context packs. Before a commit in repos that track archives or bundles, refresh compressed archive caches first, then create the private bundle so the committed graph state is self-consistent. Private bundles are the default and may be committed in private repos when configured. Public bundles require at least one selected workspace with visibility: public and include only public workspace content and public archive sidecars; bundle creation fails if public content points at private graph, archive, or subgraph records.

Clone or fork a reusable graph template into a separate target. Numeric aliases are preserved; a v2 same-project clone retains immutable identities, whereas an independent v2 fork creates new identities with lineage:

mdkg graph clone .mdkg/bundles/private/all.mdkg.zip --target demos/demo-1 --json
mdkg graph fork templates/website-template-mdkg --target demos/live-build --start-goal goal-1 --json

Import a template graph into the current repo only through the rewritten-ID path. Review the dry-run receipt first, then apply explicitly:

mdkg graph import-template templates/website-template-mdkg --start-goal goal-1 --select-goal --dry-run --json
mdkg graph import-template templates/website-template-mdkg --start-goal goal-1 --select-goal --apply --json

graph clone and graph fork preserve numeric aliases, not identical identity semantics; graph import-template rewrites canonical numeric aliases and proven structured links to avoid same-repo collisions. With --select-goal --apply, import-template activates the rewritten imported start goal, pauses competing active root goals, validates the graph, and then writes selected-goal state. Subgraphs remain read-only planning views; use mdkg graph ... when authored graph state should be created.

Register a child repo bundle as a read-only subgraph planning view:

mdkg subgraph add child_repo .mdkg/bundles/private/subgraphs/child_repo.mdkg.zip --source-path projects/child_repo
mdkg subgraph list --json
mdkg search "child capability"
mdkg show child_repo:work.example
mdkg pack child_repo:work.example --dry-run --stats
mdkg capability resolve "child capability" --json
mdkg subgraph verify child_repo --json
mdkg subgraph audit child_repo --target .mdkg/subgraphs --json
mdkg subgraph upgrade-plan child_repo --json

When the child repo is available under a configured root-relative source_path, refresh the root-owned bundle snapshot explicitly:

mdkg subgraph sync child_repo --dry-run --json
mdkg subgraph sync child_repo --json

audit is read-only and reports source-path Git state, dirty tracked child files, bundle validity/freshness, root-owned bundle-path safety, optional materialized-target marker safety, and count-only capability summaries. upgrade-plan is also read-only, returns apply_supported: false, and proposes safe sync/verify/materialize next steps without writing bundles or child files.

sync inspects the child Git repo, refuses dirty tracked changes by default, builds the configured private/public bundle into the root-owned source path, verifies it, and records <branch>@<sha> in source_repo. It never commits, pulls, pushes, checks out, resets, or mutates child mdkg Markdown. Use --allow-dirty only when the dirty state is intentional and must be recorded in the receipt.

Generate a local read-only inspection tree when humans need to browse extracted child graph files:

mdkg subgraph materialize child_repo --target .mdkg/subgraphs --clean --gitignore --json

Materialized trees are generated local state, ignored by graph indexing/search/validation/packing/bundles/SQLite hydration, and protected by a .mdkg-materialized.json marker before clean replacement.

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.

Use read-only Git inspection to bind graph evidence to a local revision:

mdkg git inspect --json

The 0.6.0 candidate removes the Git mutation and lifecycle wrappers without compatibility aliases. Use native Git for clone, fetch, branches, worktrees, reviewed staging, commits, merges and push. Authentication and untrusted-source acceptance belong to the caller, not mdkg. Inspection returns local commit/tree hashes and sanitized descriptors without remote contact or Git-index writes; it is not proof of remote acceptance or execution. Optional graph receipts and DB snapshots remain explicit, separate operations. See the native Git migration guide.

Launch a local read-only MCP server when an MCP-capable agent should inspect a specific mdkg graph without receiving mutation tools:

mdkg mcp serve --stdio --root /path/to/repo

The MCP surface is stdio-only in this release. It exposes read-only tools for status, workspace/subgraph listing, search, show, in-memory pack generation, goal current/next, and validation. It does not expose task updates, goal activation, graph import, queue, event, archive, format, SQL, shell, arbitrary file reads, filesystem mutation, environment variables, or secret access. Future mutation allowlists remain design work.

Validate before handoff or commit:

mdkg validate
mdkg handoff create <id-or-qid> --out .mdkg/handoffs/example.md

Discover cached capability surfaces:

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 manifest list --json
mdkg manifest show <id-or-qid-or-alias> --json

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:

mdkg archive add ./inputs/key_input_doc.pdf --id archive.key-input-doc --kind source --visibility private
mdkg archive verify archive://archive.key-input-doc
mdkg archive list --json

Create semantic mirror work contracts, orders, receipts, and artifacts:

mdkg work contract new "generate image" --id work.generate-image --agent-id agent.image-worker --kind image_generation --inputs prompt:text:required --outputs image_url:url:required
mdkg work trigger work.generate-image --id order.generate-image-1 --requester user://example
mdkg work order status order.generate-image-1 --json
mdkg work receipt new "generate image receipt" --id receipt.generate-image-1 --work-order-id order.generate-image-1 --outcome success --receipt-status recorded
mdkg work receipt verify receipt.generate-image-1 --json
mdkg work artifact add receipt.generate-image-1 ./outputs/image.png --id archive.generated-image --kind artifact

Create a manual order instead of a trigger-created order when you need to supply input refs at order creation time:

mdkg work order new "generate image request" --id order.generate-image-manual --work-id work.generate-image --requester user://example --input-refs archive://archive.key-input-doc

Receipt statuses are recorded, verified, rejected, and superseded. Update and artifact commands accept local ids or local qids; subgraph qids are read-only and must be changed in their source workspace.

Update structured task state and evidence while keeping body and narrative edits in markdown:

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:

mdkg event enable
mdkg event append --kind RUN_COMPLETED --status ok --refs task-1 --notes "manual closeout"

Event validation limits (0.6.0 candidate)

Validation streams contained regular event-log files; it never rotates, deletes, rewrites, or silently skips oversized history. Missing logs remain valid. Links, special files, and exceeded limits produce validation errors, including through the MCP validation tool. After caller-owned native Git operations, run graph validation separately; Git inspection does not validate the graph. A rejected or incomplete validation is not clearance.

Optional events.validation fields in .mdkg/config.json override these defaults:

| Field | Default | Hard safety ceiling | | --- | ---: | ---: | | max_file_bytes | 67,108,864 (64 MiB) | 536,870,912 (512 MiB) | | max_total_bytes | 134,217,728 (128 MiB) | 536,870,912 (512 MiB) | | max_line_bytes | 1,048,576 (1 MiB) | 8,388,608 (8 MiB) | | max_records | 1,000,000 | 5,000,000 | | max_lines | 2,000,000 | 10,000,000 | | max_errors | 1,000 | 10,000 |

Overrides must be positive safe integers; unknown limit names are errors. File and line limits are per file/line; total bytes, physical lines, nonblank records, and event diagnostics are shared across enabled workspaces. Line bytes exclude LF but include an optional CR. A trailing LF does not create an extra physical line. At most max_errors event diagnostics plus one explicit incomplete-validation diagnostic are returned.

Event bytes and decoded Markdown validation bytes also share index.limits.max_total_bytes; the tightest remaining byte budget applies. Blank lines, CRLF, UTF-8 split across read chunks, and a final line without LF remain supported. Validation preserves existing event field semantics; append commands do not rotate logs or guarantee that a growing log stays below limits.

For trusted history that exceeds a default, preserve it, review resource needs, and explicitly increase the relevant configuration within the ceilings. If a hard ceiling is exceeded, stop and plan an explicit archival/segmentation workflow; do not delete history, bypass validation, or claim partial validation is complete.

Create a first-class skill:

mdkg skill new release-readiness "release readiness audit" --description "use when preparing a release"
mdkg skill list
mdkg skill show release-readiness
mdkg skill validate release-readiness

Versioned graph collaboration (0.6.0 candidate)

V2 adoption is explicit. Review mdkg graph migrate --help and its exact plan; upgrade every writer first. The schema2 configuration fence blocks compatible old-client entrypoints, but cannot control an old executable's initialization or force-init. Do not mix old and new writers. Reads/indexes never invent identities. Migration preserves historical evidence and refuses ambiguous legacy continuity.

Use native Git branches/worktrees, one writer per checkout. Branch-local nodes work before commit; stable graph/node identities distinguish independent alias collisions from conflicting edits to the same node. Pin ancestor/incoming/target, review mdkg graph reconcile, then apply its exact unchanged plan. Commit that reviewed graph result under explicit Git authority before the native merge. Resolve graph paths against that exact result, source/configuration separately; validate the combined result, commit the merge and verify both ancestries. Never blanket-select one side of .mdkg. Reconciliation does not stage, merge or fetch.

Selection, indexes, locks, journals and live DB delivery state stay checkout-local. Goal claims still change durable lifecycle and do not provide distributed leases. Inspect interrupted graph transactions with mdkg graph recover <plan-hash>. Every recovery write requires the requested mode's fresh --lock-evidence approval and --confirm-quiescent, an explicit operator assertion that all checkout writers are stopped. Inspection validates exact checkout, lock chain, journal and file evidence; it does not prove quiescence across hosts, reboots or process namespaces. A hash is not authentication, and age/PID absence alone grants nothing. Live/ambiguous PIDs, changed, weak or incomplete evidence refuse. No-lock terminal repeats stay read-only. Do not delete locks to bypass checks. Complete published transaction boundaries are supported, not every possible power-loss window. Final native-worktree/platform qualification remains required.

LLM-readable onboarding artifacts

The root docs below are maintained source/reference material for this repository, not the file layout generated in a new consumer checkout. Start with AGENTS.md or CLAUDE.md and follow the relevant router; load these references as needed:

• AGENT_START.md
• llms.txt
• PACK_EXAMPLES.md
• CLI_COMMAND_MATRIX.md
• COVERAGE_HARDENING_MATRIX.md
• CHANGELOG.md
• CONTRIBUTING.md

Repository shape

mdkg lives under a hidden root directory:

• .mdkg/core/ rules and pinned docs
• .mdkg/design/ product, design, and decision docs
• .mdkg/work/ tasks, bugs, tests, spikes, epics, checkpoints
• .mdkg/templates/ templates used by mdkg new
• .mdkg/skills/ Agent Skills packages
• .mdkg/archive/ sidecar metadata plus deterministic compressed source/artifact caches
• .mdkg/bundles/ optional committed full graph snapshot bundles
• .mdkg/index/mdkg.sqlite optional committed, rebuildable SQLite access cache
• .mdkg/index/subgraphs.json generated read-only subgraph projection cache
• .mdkg/db/ future project application database layout and receipts
• .mdkg/subgraphs/ generated materialized subgraph inspection trees
• .agents/skills/ Codex/OpenAI-facing mirrored skills
• .claude/skills/ Claude-facing mirrored skills
• .mdkg/index/*.json generated JSON compatibility cache files

Primary commands

These are the commands new users and agents should learn first:

• mdkg init
• mdkg upgrade
• mdkg new
• mdkg search
• mdkg show
• mdkg next
• mdkg pack
• mdkg skill
• mdkg capability
• mdkg spec
• mdkg archive
• mdkg work
• mdkg goal
• mdkg task
• mdkg validate
• mdkg status
• mdkg mcp
• mdkg fix

Advanced / maintenance commands still exist, but they are not the first-run story:

• mdkg event
• mdkg checkpoint
• mdkg index
• mdkg guide
• mdkg format
• mdkg doctor --strict --json
• 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 repo. It reports package/release state, Git cleanliness, graph validity, selected-goal state, project DB verification state, and generated cache freshness without rebuilding indexes, running migrations, repairing files, or changing selected-goal state.

Use mdkg doctor --strict --json when a CI job or agent needs actionable typed checks. Strict doctor keeps the existing diagnostic command read-only and adds stable check fields: id, status, severity, message, remediation, and optional refs. Strict mode fails on invalid graph state, stale generated graph/capability cache state, stale or achieved selected-goal state, and enabled project DB verification failures. Warnings such as dirty runtime DB files, archive size guidance, and bundle handoff guidance remain warnings unless their underlying check fails.

Use mdkg fix plan --json when you want repair guidance without mutation. It emits a receipt-shaped plan for generated index/cache repair, missing graph references, and duplicate local ids. Planned changes include affected paths, risk, reason codes, command hints, and per-change apply_supported metadata. Duplicate-ID graph repairs can be applied with mdkg fix apply --family ids --json or mdkg fix ids --apply --json; use --base-ref only after reviewing its meaning. During unresolved Git repair it must match the unique common ancestor. Legacy fix ids splits positional stage2/stage3 only for proven independent additions, preserves manual resolutions and leaves Git staging unchanged. Same-node edits or ambiguous history require semantic review. V2 graphs use graph reconcile, not numeric repair. Index/cache and graph-reference findings remain review-only.

Skills

mdkg supports Agent Skills as procedural memory.

Canonical layout:

.mdkg/skills/<slug>/SKILL.md

Current source behavior:

• skills are indexed into .mdkg/index/skills.json
• .mdkg/skills/ remains the canonical skill source of truth
• .agents/skills/ and .claude/skills/ are materialized mirrors for agent products
• skills have a focused command family:
  • mdkg skill new <slug> "<name>" --description "..."
  • mdkg skill list
  • mdkg skill search "<query>"
  • mdkg skill show <slug>
  • mdkg skill validate [<slug>]
  • mdkg skill sync
• machine-readable skill discovery and inspection is available through:
  • mdkg skill list --json
  • mdkg skill search "<query>" --json
  • mdkg skill show <slug> --json
  • mdkg skill list --xml|--toon|--md
  • mdkg skill search "<query>" --xml|--toon|--md
  • mdkg skill show <slug> --xml|--toon|--md
• work items may reference skills: [slug,...]
• packs may include skills with --skills and --skills-depth
• mdkg indexes and discovers skills but does not execute skill scripts
• SKILL.md is canonical
• SKILLS.md is tolerated on read for compatibility, but validation warns and canonical docs still use SKILL.md
• if both SKILL.md and SKILLS.md exist in one skill folder, validation fails
• mdkg skill new scaffolds SKILL.md, references/, assets/, and scripts/ only when requested with --with-scripts
• mdkg skill sync refreshes the product-specific mirrors from canonical .mdkg/skills/
• mirrored skill folders are append-focused outputs; preserve unrelated existing folders and fail on same-slug collisions unless explicitly forced

This repo now dogfoods mdkg-authored internal skills:

• author-mdkg-skill
• select-work-and-ground-context
• build-pack-and-execute-task
• pursue-mdkg-goal
• pursue-mdkg-loop
• verify-close-and-checkpoint

Skills use a consumer-neutral discovery contract. Unknown authored metadata is preserved in the source document, but is not given privileged search weighting or projected as vendor-specific fields in structured skill output. Runtimes may interpret their own metadata outside mdkg.

Capability cache

mdkg maintains .mdkg/index/capabilities.json as a derived access cache for deterministic capability surfaces:

• skills from .mdkg/skills/**/SKILL.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. Observational capability reads do not persist rebuilt projections: they can derive current results in memory without repairing missing or stale files. Run mdkg index to persist refreshed caches. --no-reindex can instead return an existing stale legacy cache with a warning, or fail if it is missing; v2 discovery derives identity from authored source.

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

Fresh mdkg init workspaces default to index.backend: sqlite, which writes .mdkg/index/mdkg.sqlite as a rebuildable access cache using Node's built-in node:sqlite. Existing workspaces that are migrated from older configs default to index.backend: json until they opt in. Markdown files, archive sidecars, bundle manifests, and config remain source of truth in both modes.

mdkg index still writes JSON compatibility caches (global.json, skills.json, capabilities.json, and subgraph projections when configured). In SQLite mode it also rebuilds the SQLite cache with nodes, edges, skills, capabilities, archive metadata, subgraphs, source hashes, and schema metadata. Deleting the SQLite file is recoverable with mdkg index.

Graph ingestion is bounded before Markdown bodies are read. New workspaces expose index.limits.max_files, max_file_bytes, max_total_bytes, and max_depth in .mdkg/config.json; older configs receive the same conservative defaults in memory. Pack traversal and body reads are bounded before construction, ZIP input is bounded before allocation and inflation, and the local read-only MCP server rejects oversized lines, batches, nesting, bodies, tool payloads, and responses.

Mutating commands use a workspace mutation lock plus atomic writes. SQLite mode additionally reserves numeric ids in a SQLite transaction before writing Markdown so parallel mdkg new and checkpoint calls avoid naming conflicts. Skipped ids after failed writes are acceptable because Markdown remains canonical.

Numeric creation and duplicate repair use exact integers through 9007199254740991; exhausted or unsafe aliases refuse before new source writes. Existing larger aliases remain readable where otherwise valid, but are not silently rounded or renumbered. Creation checks current authored aliases, prospective node syntax and discovery limits before reserving SQLite counters. Legacy new --no-reindex can defer reciprocal relationship completion, not these allocation checks. Portable nonnumeric IDs remain supported for agent files.

Project DB Layout

.mdkg/db is reserved for project application database state, separate from the rebuildable .mdkg/index graph cache. Run mdkg db init to create the generic scaffold and explicitly enable db.enabled in config. The generic layout is .mdkg/db/schema, .mdkg/db/runtime, .mdkg/db/state, and .mdkg/db/receipts; mdkg db init also writes a deterministic .mdkg/db/project-db.json manifest.

Runtime DB files, WAL, SHM, journal, lock, and temp files are ignored by default. mdkg db init does not create an active runtime SQLite database. Run mdkg db migrate after init to create or update the active runtime SQLite database at the configured db.runtime_path; built-in migrations write mdkg-owned generic foundation tables, public local node:sqlite queue delivery tables, internal local event/receipt/reducer tables, writer lease/CAS tables, and queue control state, then record migration order, checksums, and applied timestamps. Queue state is durable local delivery infrastructure, not canonical event history. Use mdkg db queue create|pause|resume|enqueue|claim|ack|fail|dead-letter|release-expired|stats|list|show to operate local project queues. Paused queues reject enqueue/claim while still allowing ack/fail/dead-letter/release-expired so leased work can settle. Event 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. Use mdkg db verify for non-mutating health checks over config, layout, runtime SQLite integrity, migration metadata, and transient runtime files. Use mdkg db stats for deterministic table counts, DB size, migration state, receipt-file count, and state snapshot presence. Use mdkg db snapshot seal to create an explicit sealed checkpoint at .mdkg/db/state/project.sqlite with .mdkg/db/state/project.manifest.json. The default queue policy is --queue-policy drain, which requires no ready or leased queue messages. Use --queue-policy paused only when ready messages are intentionally preserved in paused queues; leased messages always block sealing. Use mdkg db snapshot verify and mdkg db snapshot status for checkpoint health, and use mdkg db snapshot dump / mdkg db snapshot diff as deterministic review aids for SQLite snapshots instead of comparing raw binary bytes. Schema files, manifests, receipt artifacts, and opt-in sealed snapshots remain commit-eligible by explicit repo policy. mdkg doctor warns when active runtime or transient project DB files are present so they are not accidentally committed as sealed state.

Goal nodes

Goal nodes are durable recursive objective contracts. Use mdkg new goal "<objective>" when a human or agent needs to keep working across multiple concrete nodes until a measurable end condition is achieved.

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; 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.

Loop nodes

Loop nodes are durable declarative process state for reusable agentic workflows. Use mdkg new loop "<process>" for a loop record, or mdkg loop fork <template> --scope <scope> to instantiate a seeded template for a concrete repo, folder, or goal.

Loop seed discovery and local indexed-template reads enforce index.limits, capped at the default template safety envelope. Catalog/provenance inspection shares a command-local file/byte budget and reuses each admitted template; subsequent commands read fresh input. Seed discovery also bounds directory entries and depth. Direct seed selection does not parse unrelated templates. Unsafe or oversized guidance is rejected before new loop reserves an alias or writes a node; forked output must independently fit the graph's authoring limits.

loop is one first-class node type. A loop can act as a reusable template, scoped fork, or run-bearing loop through metadata and links; mdkg does not create separate loop_template or loop_run node types in this release. Loop metadata records mode, scope, lineage, materialization mode, child refs, run/evidence refs, definition of done, and blocker-continuation policy.

mdkg loop list|show|plan|runs inspect loop state without executing agents. mdkg loop fork creates graph state; by default it materializes linked spike/task/test child nodes, while --planning-only or --no-children creates only the scoped loop shell. mdkg defines reusable process state and graph context; consuming runtimes own agent/tool execution, sandboxes, traces, and model routing.

Research spikes

Spikes are first-class actionable work nodes for research and planning. Use mdkg new spike "<question>" when the right output is a documented recommendation, not code. They share the existing task lifecycle:

mdkg new spike "research queue-backed materializer UX" --status todo --priority 1
mdkg task start spike-1
mdkg task update spike-1 --status review --add-refs task-250
mdkg task done spike-1

The default spike template includes sections for research question, context, search plan, findings, options and tradeoffs, recommendation, follow-up nodes, skill candidates, data-structure and algorithm notes, UX notes, security notes, mdkg.dev launch implications, and evidence/sources.

Spikes deliberately do not expose a mdkg spike ... namespace in this release, do not run browser or web-search tools, do not create tasks/tests/goals, and do not write SKILL.md files. They make the research output reviewable so humans 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:

• 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 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. 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 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. Receipt verification establishes structural and local-evidence consistency, not external execution, payment, or attestation authenticity. mdkg work validate [<id-or-qid>] [--type manifest|spec|work|work_order|receipt|feedback|dispute|proposal] --json is a read-only focused validator for generic agent workflow mirrors; it returns typed diagnostics and warns on obvious raw secret, prompt, token, or payload markers. Validation profile flags are unsupported; consumer policy is not executed by mdkg.

Optional contract-profile fields are generic semantic mirrors, not runtime execution state. contract_profile is accepted on MANIFEST, WORK, WORK_ORDER, and RECEIPT surfaces; validation_policy_ref and evidence_policy_ref are accepted on MANIFEST, WORK_ORDER, and RECEIPT; receipt_kind and redaction_class are RECEIPT-only. These fields are separate from MANIFEST resource_profile, WORK kind, WORK_ORDER artifact_policy, RECEIPT redaction_policy, and pack/bundle --profile flags. Generic validation accepts well-shaped custom profile, kind, and class values with warnings; policy references remain opaque. Bare profile is intentionally ambiguous and is diagnosed rather than treated as an alias.

For 0.6.0, use runtime_mode: orchestrated; the former room_orchestrated token is rejected without an alias. Work contracts no longer require or generate pricing_model, and --pricing-model is unsupported. Convert authored documents explicitly: retain consumer data in a user-owned custom template only when needed, or move it to the consuming runtime. Init and upgrade do not silently rewrite authored contracts.

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. Omni Room and other downstream runtimes own runtime policy, queue execution, final receipt normalization, and downstream adoption. Do not store raw secrets, credentials, live payment state, ledger mutations, canonical marketplace state, or bulky raw payloads in these mirrors.

Archive sidecars

Archive entries live under .mdkg/archive/<archive.id>/ and are normal graph nodes with type: archive. mdkg archive add copies the source into a managed local source/ directory, writes a frontmatter sidecar <file>.md, and writes a deterministic single-file ZIP cache <file>.zip. The original source path is left untouched.

Archive sidecars support archive://archive.example refs from orders, receipts, artifacts, proof refs, and other workflow metadata. artifact://... refs remain external or runtime-managed artifact identities; archive://... refs name committed mdkg archive sidecars. mdkg validate and mdkg archive verify both require the sidecar contract, ZIP cache hash, readable ZIP payload, payload SHA-256, and payload byte size to match. A missing raw local source copy is non-fatal when the committed sidecar and ZIP cache are valid.

When the source passed to mdkg archive add is inside the repo, source_path is repo-relative. Outside-repo sources are redacted to external:<basename> so sidecars do not leak absolute local paths.

Archive sidecar visibility defaults to private. Use mdkg archive add --visibility public only when the sidecar metadata and ZIP cache are safe for public packs or public bundles.

Archive compression follows workspace ownership. mdkg archive compress --all compresses archives from enabled local workspaces and reports read-only imported archive projections as exclusions; it never treats bundle ZIP fragments as filesystem paths. Use --all --ws <local-alias> to limit bulk compression or a workspace-qualified qid such as root:archive.example for an exact local target. Direct imported qids and imported --ws aliases fail before writes with guidance to compress in the source workspace and refresh its subgraph bundle. The JSON receipt preserves action, count, and archives and adds the requested workspace, selected local workspaces, and excluded read-only qids.

Compression admits the whole selected resource set before reading payloads. Sidecars, raw inputs and caches must share their deepest configured workspace owner, including private or disabled nested roots. Raw inputs stay under the sidecar directory's source/ subtree; caches are .zip files below that directory, outside source/ and nested metadata directories. Custom cache names and source subdirectories remain supported. Resource sharing, ancestor/descendant overlaps, case/Unicode aliases, and configured database/index/template/bundle collisions fail closed. These checks do not expand a sidecar's authority to another archive; explicit archive add <file> source access remains a separate operator choice. Review nonconforming manually authored layouts before compression; mdkg does not rewrite them automatically. Missing or corrupt owned caches remain regenerable.

By default, init/upgrade ignore generated raw archive source copies with .mdkg/archive/**/source/; sidecar .md files and compressed .zip caches remain commit-eligible. mdkg doctor warns when a committed archive ZIP cache exceeds archive.large_cache_warning_bytes in .mdkg/config.json (default 26214400; set 0 to disable). Large-cache warnings do not block archive add or validation.

Current direction

This release includes:

• compact default mdkg init, explicit mdkg init --graph-only, and --agent compatibility
• 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, 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
• first-class loop nodes and mdkg loop list/show/fork/plan/runs
• optional skills: [...] on work items
• pack-time skill inclusion
• latest-checkpoint resolver + index hint
• events JSONL validation
• XML / TOON / Markdown output for node and skill list/search/show
• agent workflow file types and semantic IDs using the --id option on mdkg new
• product-specific skill mirrors for Codex/OpenAI and Claude
• compact .mdkg/AGENT_START.md routing through root AGENTS.md / CLAUDE.md
• conservative mdkg upgrade with mode-aware init manifests
• archive sidecars with deterministic ZIP caches
• semantic mirror helpers under mdkg work ..., including trigger/order status/receipt verification
• explicit public/internal/private visibility enforcement for packs, bundles, archives, imports, validation, and doctor diagnostics
• strict archive ZIP payload integrity checks during validation

Current direction:

• keep the OSS story generic around compact default mdkg init
• use mdkg init --graph-only for repos that do not want agent bootstrap assets
• keep pack <id> at the center of the human/agent loop
• use mdkg task ... for structured state changes and markdown edits for narrative/body content
• make event logging guided instead of purely manual
• dogfood real skills inside the repo
• make skill authoring first-class through mdkg skill
• make CLI_COMMAND_MATRIX.md the single source of truth for the live CLI surface
• keep production execution databases canonical while mdkg stores committed semantic mirrors
• run manual behavior audits before enforcing stronger coverage thresholds

Design and decision records live in the internal graph under .mdkg/design/.

Safety

mdkg is not a secret store.

Use these defaults:

• keep generated .mdkg/index/*.json, temp, lock, WAL, SHM, and journal files gitignored
• commit .mdkg/index/mdkg.sqlite only when the repo intentionally tracks a reasonably sized rebuildable access cache
• keep .mdkg/db/runtime/ and .mdkg/db WAL/SHM/journal/lock/temp files gitignored
• commit .mdkg/db/schema, manifests, receipts, and sealed state snapshots only by explicit repo policy
• keep .mdkg/pack/ gitignored
• keep .mdkg/archive/**/source/ gitignored unless a repo intentionally commits raw local copies
• commit archive sidecar .md metadata and deterministic .zip caches when they are needed for reviewable evidence
• event logs are committed by default; ignore or delete them manually if a repo wants local-only provenance
• do not ship .mdkg/ into production builds or published packages
• if an external orchestrator is writing mdkg state, keep one durable writer per run and batch commits at end-of-run or checkpoint boundaries
• do not commit on every tool call

Contributing

Start with CONTRIBUTING.md. mdkg prefers Prompt Requests before Pull Requests: contributors can submit intent, workflows, prompts, and acceptance criteria without needing to write code first.

This repo dogfoods mdkg itself. The behavior source of truth is the combination of:

• source under src/
• tests under tests/
• internal rules and design docs under .mdkg/

Suggested local loop:

1. create or select a work item
2. inspect truth with search, show, or next
3. build context with pack <id>
4. mutate task state with mdkg task ... when durable state changes
5. ensure event logging exists if the JSONL file was deleted or is missing
6. implement and test
7. run mdkg validate

License

MIT