mdkg 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nick Reames
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# mdkg — Markdown Knowledge Graph
+
+mdkg is a **local-first CLI** that turns structured Markdown into a **searchable, linkable knowledge graph** for engineering work.
+
+It’s designed for:
+- humans who want lightweight project documentation + task tracking **in git**
+- AI coding agents/LLMs that need **deterministic context bundles** for code generation
+
+mdkg is intentionally boring and portable:
+- **Node.js 18+**
+- written in **TypeScript**
+- **zero runtime dependencies** (no sqlite, no external indexers)
+- works with npm / pnpm / bun
+
+---
+
+## Core idea
+
+You store project knowledge as Markdown nodes with strict frontmatter (a small, stable schema). mdkg:
+
+1) indexes those nodes into a local JSON cache (`.mdkg/index/global.json`)
+2) provides fast search/list/show tools
+3) generates deterministic **context packs** for agents (Markdown/JSON/TOON exports)
+
+Everything stays in your repo. No servers. No surprises.
+
+---
+
+## Repository structure
+
+mdkg lives in a hidden directory at the repo root:
+
+- `.mdkg/core/` — rules + “pinned” docs
+- `.mdkg/design/` — decisions + architecture
+- `.mdkg/work/` — epics/tasks/bugs/checkpoints
+- `.mdkg/templates/` — document templates used by `mdkg new`
+- `.mdkg/index/` — generated cache (gitignored)
+
+mdkg is root-only: you run commands from the repository root and mdkg indexes all registered workspaces without “discovering” nested repos.
+
+---
+
+## Install
+
+Pre-release note: this project is being actively developed and dogfooded.
+
+Once published:
+- `npm i -g mdkg`
+- `pnpm add -g mdkg`
+- `bun add -g mdkg`
+
+---
+
+## Quickstart
+
+1) Initialize mdkg in your repo:
+
+```bash
+mdkg init
+```
+
+This creates `.mdkg/` (rules, templates, work folders) and updates ignore rules so caches are not committed.
+
+2) Index your repo (cache is default behavior):
+
+```bash
+mdkg index
+```
+
+3) Create a task from a template:
+
+```bash
+mdkg new task "bootstrap cli" --status todo --priority 1 --tags cli,build
+```
+
+4) Search and list:
+
+```bash
+mdkg search "pack"
+mdkg list --type task --status todo
+mdkg show task-1
+```
+
+5) Generate a deterministic context bundle for an agent:
+
+```bash
+mdkg pack task-1 --format md --verbose
+```
+
+---
+
+## Why this exists
+
+LLMs are great at writing code, but they need **high-quality, structured context**.
+
+mdkg makes that context:
+- easy to author
+- easy to query
+- easy to hand to an agent
+- reproducible across runs and contributors
+
+This is also intended to be a compatible building block for “life git”-style productivity systems (which may later add richer databases like SQLite/Postgres). mdkg stays minimal and local.
+
+---
+
+## Concepts
+
+### Nodes
+
+A node is a Markdown file with strict YAML-like frontmatter fenced by `---`.
+
+Each node must include:
+- `id` (unique)
+- `type` (rule, prd, edd, dec, prop, epic, feat, task, bug, checkpoint)
+- `title`
+- `created` / `updated` (`YYYY-MM-DD`)
+
+Work items also typically include:
+- `status` (backlog, blocked, todo, progress, review, done)
+- `priority` (0..9, where 0 is most urgent)
+
+### Graph links
+
+mdkg treats these frontmatter fields as explicit graph structure:
+- `epic`, `parent`
+- `relates: [...]`
+- `blocked_by: [...]`, `blocks: [...]`
+- `prev`, `next` (chain navigation)
+
+### Searchable metadata
+
+If you want something searchable, put it in frontmatter:
+- `links: [ref, ref]` (URLs or any searchable reference string)
+- `artifacts: [ref, ref]` (build outputs, PRs, commits, releases, tarballs, etc.)
+- `refs: [id, id]` (non-edge references)
+- `aliases: [text, text]`
+
+---
+
+## CLI commands (v1)
+
+### Project setup
+
+- `mdkg init`
+  - create `.mdkg/` structure
+  - add ignore rules for caches
+
+### Indexing
+
+- `mdkg index`
+  - builds `.mdkg/index/global.json`
+  - cache is the default; mdkg will reindex automatically if stale
+
+### Query
+
+- `mdkg show <id-or-qid>`
+- `mdkg list [--type <type>] [--status <status>] [--ws <alias>] [--epic <id>] [--priority <n>]`
+- `mdkg search "<query>"`
+
+### Packs (agent context)
+
+- `mdkg pack <id> [--format md|json|toon] [--verbose] [--depth <n>] [--edges <keys>]`
+
+`--verbose` includes pinned core docs listed in `.mdkg/core/core.md`.
+
+### Workflow helpers
+
+- `mdkg next [<id>] [--ws <alias>]`
+  - follows `next` chain if present; otherwise picks highest priority work item
+
+- `mdkg checkpoint new "<title>"`
+  - creates a checkpoint node (a compression summary)
+
+### Quality gates
+
+- `mdkg validate`
+  - strict frontmatter validation
+  - missing required fields, invalid enums, dangling edges, cycles, duplicates
+
+- `mdkg format`
+  - conservative frontmatter normalizer (idempotent)
+
+---
+
+## Safety
+
+mdkg is designed to avoid accidental leaks:
+- cache files live under `.mdkg/index/` and must be gitignored
+- publishing should use a strict `package.json.files` whitelist
+- `.mdkg/` content should never ship to production builds
+
+---
+
+## Contributing
+
+This repo dogfoods mdkg. The source of truth for behavior is:
+- `.mdkg/core/rule-*.md`
+- `.mdkg/core/guide.md`
+- `.mdkg/core/rule-2-context-pack-rules.md`
+
+Suggested workflow:
+1) create or update a task in `.mdkg/work/`
+2) run `mdkg validate`
+3) generate a pack for the task and use it as agent context
+
+---
+
+## License
+
+MIT (recommended). Add a `LICENSE` file to confirm.

package/dist/cli.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.length === 0) {
+  console.log("mdkg - Markdown Knowledge Graph");
+  console.log("\nUsage:");
+  console.log("  mdkg <command> [options]");
+  process.exit(0);
+}
+
+console.error("Unknown command. Use --help for usage.");
+process.exit(1);

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "mdkg",
+  "version": "0.0.1",
+  "description": "Markdown Knowledge Graph",
+  "license": "MIT",
+  "bin": {
+    "mdkg": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/nickreames/mdkg.git"
+  },
+  "keywords": [
+    "markdown",
+    "knowledge-graph",
+    "cli"
+  ]
+}