mdkg 0.1.2 → 0.1.3

package/dist/graph/sqlite_index.js

@@ -0,0 +1,293 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SQLITE_SCHEMA_VERSION = void 0;
+exports.isSqliteBackend = isSqliteBackend;
+exports.resolveSqlitePath = resolveSqlitePath;
+exports.writeSqliteIndex = writeSqliteIndex;
+exports.reserveSqliteNumericId = reserveSqliteNumericId;
+exports.sqliteHealth = sqliteHealth;
+const crypto_1 = __importDefault(require("crypto"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const staleness_1 = require("./staleness");
+exports.SQLITE_SCHEMA_VERSION = 1;
+function loadDatabaseCtor() {
+    try {
+        const loaded = require("node:sqlite");
+        if (!loaded.DatabaseSync) {
+            throw new Error("node:sqlite DatabaseSync is unavailable");
+        }
+        return loaded.DatabaseSync;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`node:sqlite is required for mdkg SQLite index support: ${message}`);
+    }
+}
+function toPosixPath(value) {
+    return value.split(path_1.default.sep).join("/");
+}
+function sha256File(filePath) {
+    return `sha256:${crypto_1.default.createHash("sha256").update(fs_1.default.readFileSync(filePath)).digest("hex")}`;
+}
+function stripVolatileCacheFields(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => stripVolatileCacheFields(item));
+    }
+    if (value && typeof value === "object") {
+        const input = value;
+        const output = {};
+        for (const key of Object.keys(input).sort()) {
+            if (key === "generated_at" || key === "indexed_at") {
+                continue;
+            }
+            output[key] = stripVolatileCacheFields(input[key]);
+        }
+        return output;
+    }
+    return value;
+}
+function stableCacheJson(value) {
+    return JSON.stringify(stripVolatileCacheFields(value));
+}
+function isSqliteBackend(config) {
+    return config.index.backend === "sqlite";
+}
+function resolveSqlitePath(root, config) {
+    return path_1.default.resolve(root, config.index.sqlite_path);
+}
+function sqliteTempPath(sqlitePath) {
+    return path_1.default.join(path_1.default.dirname(sqlitePath), `.${path_1.default.basename(sqlitePath)}.${process.pid}.${Date.now()}.tmp`);
+}
+function createSchema(db) {
+    db.exec(`
+    PRAGMA journal_mode = DELETE;
+    PRAGMA synchronous = FULL;
+    CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+    CREATE TABLE nodes (
+      qid TEXT PRIMARY KEY,
+      id TEXT NOT NULL,
+      ws TEXT NOT NULL,
+      type TEXT NOT NULL,
+      title TEXT NOT NULL,
+      path TEXT NOT NULL,
+      status TEXT,
+      priority INTEGER,
+      updated TEXT,
+      source_hash TEXT,
+      json TEXT NOT NULL
+    );
+    CREATE TABLE edges (
+      source_qid TEXT NOT NULL,
+      kind TEXT NOT NULL,
+      target_qid TEXT NOT NULL,
+      PRIMARY KEY (source_qid, kind, target_qid)
+    );
+    CREATE TABLE skills (
+      qid TEXT PRIMARY KEY,
+      slug TEXT NOT NULL,
+      ws TEXT NOT NULL,
+      name TEXT NOT NULL,
+      path TEXT NOT NULL,
+      json TEXT NOT NULL
+    );
+    CREATE TABLE capabilities (
+      qid TEXT NOT NULL,
+      kind TEXT NOT NULL,
+      workspace TEXT NOT NULL,
+      visibility TEXT NOT NULL,
+      id TEXT NOT NULL,
+      path TEXT NOT NULL,
+      source_hash TEXT NOT NULL,
+      json TEXT NOT NULL,
+      PRIMARY KEY (qid, kind, path)
+    );
+    CREATE TABLE archives (
+      qid TEXT PRIMARY KEY,
+      visibility TEXT NOT NULL,
+      compressed_path TEXT,
+      compressed_sha256 TEXT,
+      json TEXT NOT NULL
+    );
+    CREATE TABLE bundle_imports (
+      alias TEXT PRIMARY KEY,
+      enabled INTEGER NOT NULL,
+      stale INTEGER NOT NULL,
+      error_count INTEGER NOT NULL,
+      warning_count INTEGER NOT NULL,
+      json TEXT NOT NULL
+    );
+    CREATE TABLE id_allocations (
+      ws TEXT NOT NULL,
+      prefix TEXT NOT NULL,
+      next_value INTEGER NOT NULL,
+      PRIMARY KEY (ws, prefix)
+    );
+  `);
+}
+function insertMeta(db, key, value) {
+    db.prepare("INSERT INTO meta (key, value) VALUES (?, ?)").run(key, value);
+}
+function nodeSourceHash(root, nodePath) {
+    const fullPath = path_1.default.resolve(root, nodePath);
+    if (!fs_1.default.existsSync(fullPath) || !fs_1.default.statSync(fullPath).isFile()) {
+        return undefined;
+    }
+    return sha256File(fullPath);
+}
+function buildSourceFingerprint(options) {
+    const payload = {
+        nodes: Object.values(options.nodeIndex.nodes)
+            .sort((a, b) => a.qid.localeCompare(b.qid))
+            .map((node) => ({
+            qid: node.qid,
+            path: node.path,
+            hash: options.nodeHashes.get(node.qid) ?? "",
+        })),
+        skills: Object.values(options.skillsIndex.skills).sort((a, b) => a.qid.localeCompare(b.qid)),
+        capabilities: options.capabilitiesIndex.records,
+        imports: options.importsIndex.imports,
+    };
+    return `sha256:${crypto_1.default.createHash("sha256").update(stableCacheJson(payload)).digest("hex")}`;
+}
+function writeSqliteIndex(options) {
+    const sqlitePath = resolveSqlitePath(options.root, options.config);
+    fs_1.default.mkdirSync(path_1.default.dirname(sqlitePath), { recursive: true });
+    const tempPath = sqliteTempPath(sqlitePath);
+    fs_1.default.rmSync(tempPath, { force: true });
+    const DatabaseSync = loadDatabaseCtor();
+    const db = new DatabaseSync(tempPath);
+    try {
+        const nodeHashes = new Map();
+        for (const node of Object.values(options.nodeIndex.nodes)) {
+            nodeHashes.set(node.qid, nodeSourceHash(options.root, node.path));
+        }
+        createSchema(db);
+        insertMeta(db, "tool", "mdkg");
+        insertMeta(db, "schema_version", String(exports.SQLITE_SCHEMA_VERSION));
+        insertMeta(db, "package_schema_version", String(options.config.schema_version));
+        insertMeta(db, "backend", options.config.index.backend);
+        insertMeta(db, "source_fingerprint", buildSourceFingerprint({ ...options, nodeHashes }));
+        insertMeta(db, "root", ".");
+        const insertNode = db.prepare("INSERT INTO nodes (qid, id, ws, type, title, path, status, priority, updated, source_hash, json) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
+        const insertEdge = db.prepare("INSERT OR IGNORE INTO edges (source_qid, kind, target_qid) VALUES (?, ?, ?)");
+        for (const node of Object.values(options.nodeIndex.nodes).sort((a, b) => a.qid.localeCompare(b.qid))) {
+            insertNode.run(node.qid, node.id, node.ws, node.type, node.title, toPosixPath(node.path), node.status ?? null, node.priority ?? null, node.updated ?? null, nodeHashes.get(node.qid) ?? null, stableCacheJson(node));
+            for (const [kind, values] of [
+                ["relates", node.edges.relates],
+                ["blocked_by", node.edges.blocked_by],
+                ["blocks", node.edges.blocks],
+            ]) {
+                for (const target of values) {
+                    insertEdge.run(node.qid, kind, target);
+                }
+            }
+            for (const [kind, target] of [
+                ["epic", node.edges.epic],
+                ["parent", node.edges.parent],
+                ["prev", node.edges.prev],
+                ["next", node.edges.next],
+            ]) {
+                if (target) {
+                    insertEdge.run(node.qid, kind, target);
+                }
+            }
+        }
+        const insertSkill = db.prepare("INSERT INTO skills (qid, slug, ws, name, path, json) VALUES (?, ?, ?, ?, ?, ?)");
+        for (const skill of Object.values(options.skillsIndex.skills).sort((a, b) => a.qid.localeCompare(b.qid))) {
+            insertSkill.run(skill.qid, skill.slug, skill.ws, skill.name, skill.path, stableCacheJson(skill));
+        }
+        const insertCapability = db.prepare("INSERT INTO capabilities (qid, kind, workspace, visibility, id, path, source_hash, json) VALUES (?, ?, ?, ?, ?, ?, ?, ?)");
+        for (const record of options.capabilitiesIndex.records) {
+            insertCapability.run(record.qid, record.kind, record.workspace, record.visibility, record.id, record.path, record.source_hash, stableCacheJson(record));
+        }
+        const insertArchive = db.prepare("INSERT INTO archives (qid, visibility, compressed_path, compressed_sha256, json) VALUES (?, ?, ?, ?, ?)");
+        for (const node of Object.values(options.nodeIndex.nodes).filter((item) => item.type === "archive")) {
+            insertArchive.run(node.qid, String(node.attributes.visibility ?? "private"), String(node.attributes.compressed_path ?? ""), String(node.attributes.compressed_sha256 ?? ""), stableCacheJson(node));
+        }
+        const insertImport = db.prepare("INSERT INTO bundle_imports (alias, enabled, stale, error_count, warning_count, json) VALUES (?, ?, ?, ?, ?, ?)");
+        for (const item of options.importsIndex.imports) {
+            insertImport.run(item.alias, item.enabled ? 1 : 0, item.stale ? 1 : 0, item.error_count, item.warning_count, stableCacheJson(item));
+        }
+    }
+    finally {
+        db.close();
+    }
+    fs_1.default.renameSync(tempPath, sqlitePath);
+    return sqlitePath;
+}
+function reserveSqliteNumericId(options) {
+    if (!isSqliteBackend(options.config)) {
+        return undefined;
+    }
+    const sqlitePath = resolveSqlitePath(options.root, options.config);
+    fs_1.default.mkdirSync(path_1.default.dirname(sqlitePath), { recursive: true });
+    const DatabaseSync = loadDatabaseCtor();
+    const db = new DatabaseSync(sqlitePath);
+    try {
+        db.exec("CREATE TABLE IF NOT EXISTS id_allocations (ws TEXT NOT NULL, prefix TEXT NOT NULL, next_value INTEGER NOT NULL, PRIMARY KEY (ws, prefix));");
+        db.exec("BEGIN IMMEDIATE");
+        const row = db
+            .prepare("SELECT next_value FROM id_allocations WHERE ws = ? AND prefix = ?")
+            .get(options.ws, options.prefix);
+        const existing = typeof row?.next_value === "number" ? row.next_value : undefined;
+        const nextValue = Math.max(existing ?? 1, options.currentMax + 1);
+        db.prepare("INSERT INTO id_allocations (ws, prefix, next_value) VALUES (?, ?, ?) ON CONFLICT(ws, prefix) DO UPDATE SET next_value = excluded.next_value").run(options.ws, options.prefix, nextValue + 1);
+        db.exec("COMMIT");
+        return `${options.prefix}-${nextValue}`;
+    }
+    catch (err) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch {
+            // ignore rollback failures when no transaction is active
+        }
+        throw err;
+    }
+    finally {
+        db.close();
+    }
+}
+function sqliteHealth(root, config) {
+    const sqlitePath = resolveSqlitePath(root, config);
+    const warnings = [];
+    const errors = [];
+    if (!fs_1.default.existsSync(sqlitePath)) {
+        warnings.push(`SQLite cache missing at ${toPosixPath(path_1.default.relative(root, sqlitePath))}; run mdkg index`);
+        return { path: sqlitePath, exists: false, size: 0, warnings, errors };
+    }
+    const size = fs_1.default.statSync(sqlitePath).size;
+    if (config.index.sqlite_commit_warning_bytes > 0 && size > config.index.sqlite_commit_warning_bytes) {
+        warnings.push(`SQLite cache exceeds ${config.index.sqlite_commit_warning_bytes} bytes: ${toPosixPath(path_1.default.relative(root, sqlitePath))} (${size} bytes)`);
+    }
+    for (const suffix of ["-wal", "-shm", "-journal"]) {
+        const transient = `${sqlitePath}${suffix}`;
+        if (fs_1.default.existsSync(transient)) {
+            warnings.push(`transient SQLite file present: ${toPosixPath(path_1.default.relative(root, transient))}`);
+        }
+    }
+    try {
+        const DatabaseSync = loadDatabaseCtor();
+        const db = new DatabaseSync(sqlitePath);
+        try {
+            const row = db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get();
+            if (String(row?.value ?? "") !== String(exports.SQLITE_SCHEMA_VERSION)) {
+                errors.push(`SQLite schema mismatch; run mdkg index`);
+            }
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch (err) {
+        errors.push(`failed to read SQLite cache: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if ((0, staleness_1.isIndexStale)(root, config)) {
+        warnings.push("SQLite cache may be stale because source graph files or config changed; run mdkg index");
+    }
+    return { path: sqlitePath, exists: true, size, warnings, errors };
+}

package/dist/init/AGENT_START.md

@@ -2,6 +2,8 @@
 
 This repository uses mdkg for deterministic project memory.
 
+mdkg is pre-v1 public alpha software. Treat generated graph, cache, bundle, and DAL contracts as usable but still stabilizing before v1.
+
 Read these files in order:
 1. `.mdkg/core/SOUL.md` if it exists
 2. `.mdkg/core/HUMAN.md` if it exists
@@ -23,6 +25,7 @@ Agent operating prompt:
 - Use `mdkg search "..."` and `mdkg next` to discover current work.
 - Use `mdkg skill list`, `mdkg skill search`, and `mdkg skill show <slug>` for skill discovery.
 - Use `mdkg capability list/search/show` for deterministic skills, `SPEC.md`, `WORK.md`, core-doc, and design-doc capability discovery.
+- Use `mdkg index` to refresh JSON compatibility caches and `.mdkg/index/mdkg.sqlite` when SQLite mode is enabled.
 - Use `mdkg archive add/list/show/verify/compress` for committed source and artifact sidecars under `.mdkg/archive`.
 - Use `mdkg work ...` helpers for semantic mirror contracts, work orders, receipts, and artifact registration.
 - Treat work contracts, orders, and receipts as committed semantic mirrors only; never store raw secrets, credentials, live payment state, ledger mutations, or canonical marketplace state in mdkg.

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -22,6 +22,11 @@ Primary commands:
 - `mdkg task`
 - `mdkg validate`
 
+Index backend:
+- fresh mdkg workspaces default to `index.backend: sqlite`
+- `.mdkg/index/mdkg.sqlite` is rebuildable and commit-eligible when intentionally tracked
+- JSON compatibility caches remain generated and ignored by default
+
 Validation commands:
 - `mdkg validate [--out <path>] [--quiet] [--json]`
 

package/dist/init/README.md

@@ -2,6 +2,8 @@
 
 This repository is initialized for mdkg.
 
+mdkg is pre-v1 public alpha software. Graph, cache, bundle, and DAL contracts may change quickly before v1.
+
 ## Layout
 
 - `core/`: rules, operating guide, and pinned docs
@@ -10,7 +12,7 @@ This repository is initialized for mdkg.
 - `templates/`: default node templates
 - `archive/`: sidecar metadata and deterministic compressed source/artifact caches
 - `bundles/`: optional committed full graph snapshot bundles
-- `index/`: generated index cache (do not commit)
+- `index/`: generated JSON caches plus optional commit-eligible `mdkg.sqlite`
 - `pack/`: generated context packs (do not commit)
 
 ## Next Commands
@@ -51,10 +53,17 @@ Read `AGENT_START.md` first when this repo includes it.
 
 Ensure ignore files include:
 
-- `.mdkg/index/`
+- `.mdkg/index/*.json`
+- `.mdkg/index/*.tmp`
+- `.mdkg/index/write.lock/`
+- `.mdkg/index/*.sqlite-wal`
+- `.mdkg/index/*.sqlite-shm`
+- `.mdkg/index/*.sqlite-journal`
 - `.mdkg/pack/`
 - `.mdkg/archive/**/source/`
 
+Fresh mdkg workspaces default to `index.backend: sqlite`; `.mdkg/index/mdkg.sqlite` is a rebuildable cache and may be committed when the repo intentionally tracks it and it stays reasonably small.
+
 Recommended:
 
 ```bash

package/dist/init/config.json

@@ -8,7 +8,11 @@
   "index": {
     "auto_reindex": true,
     "tolerant": false,
-    "global_index_path": ".mdkg/index/global.json"
+    "backend": "sqlite",
+    "global_index_path": ".mdkg/index/global.json",
+    "sqlite_path": ".mdkg/index/mdkg.sqlite",
+    "sqlite_commit_warning_bytes": 52428800,
+    "lock_timeout_ms": 10000
   },
   "capabilities": {
     "cache_path": ".mdkg/index/capabilities.json"

package/dist/init/core/rule-1-mdkg-conventions.md

@@ -229,8 +229,9 @@ The cache is enabled by default.
 
 - Root global index lives at `.mdkg/index/global.json`
 - Root skills index lives at `.mdkg/index/skills.json`
+- Root SQLite access cache lives at `.mdkg/index/mdkg.sqlite` when `index.backend` is `sqlite`.
 - Index is rebuilt automatically when stale unless disabled by flag/config.
-- `.mdkg/index/` is generated and MUST be gitignored.
+- Generated JSON index/temp/lock files are ignored. `.mdkg/index/mdkg.sqlite` is rebuildable and may be committed only by explicit repo policy.
 
 ## Safety guidance (high level)
 

package/dist/init/core/rule-3-cli-contract.md

@@ -124,7 +124,7 @@ If a user provides an unqualified ID and it is ambiguous globally:
     - `.agents/skills/`
     - `.claude/skills/`
     - deterministic `core.md` pin insertion (`rule-soul`, then `rule-human`)
-    - ignore policy for `.mdkg/index/`, `.mdkg/pack/`, and raw archive source copies under `.mdkg/archive/**/source/`
+    - ignore policy for generated JSON index/temp/lock files, `.mdkg/pack/`, and raw archive source copies under `.mdkg/archive/**/source/`
   - mirrored skills are append-focused outputs:
     - `.mdkg/skills/` remains canonical
     - unrelated existing folders under `.agents/skills/` and `.claude/skills/` are preserved
@@ -146,6 +146,7 @@ If a user provides an unqualified ID and it is ambiguous globally:
   - rebuild skills cache `.mdkg/index/skills.json` from `.mdkg/skills/<slug>/SKILL.md`
   - rebuild capability cache `.mdkg/index/capabilities.json` from skills, `SPEC.md`, `WORK.md`, core docs, and design docs
   - rebuild bundle import projection cache `.mdkg/index/imports.json` when bundle imports are configured
+  - rebuild SQLite access cache `.mdkg/index/mdkg.sqlite` when `index.backend` is `sqlite`
   - tolerate `.mdkg/skills/<slug>/SKILLS.md` on read with warning
   - fail validation if both `SKILL.md` and `SKILLS.md` exist in one skill directory
   - strict by default (fails on invalid frontmatter)

package/dist/init/core/rule-4-repo-safety-and-ignores.md

@@ -21,7 +21,8 @@ mdkg content may contain sensitive notes and internal project planning. This rul
 
 - `.mdkg/` must not be shipped to production deployments.
 - `.mdkg/` must not be published to npm.
-- `.mdkg/index/` must never be committed.
+- Generated JSON index, temp, lock, WAL, SHM, and journal files under `.mdkg/index/` must not be committed.
+- `.mdkg/index/mdkg.sqlite` is a rebuildable access cache and may be committed when the repo intentionally tracks it and it stays reasonably small.
 - `.mdkg/bundles/` may be committed only when the repo intentionally tracks private or public snapshot bundles.
 
 ## Git ignore requirements
@@ -30,13 +31,22 @@ The repo MUST ignore at minimum:
 
 - `node_modules/`
 - `dist/`
-- `.mdkg/index/`
+- `.mdkg/index/*.json`
+- `.mdkg/index/*.tmp`
+- `.mdkg/index/write.lock/`
+- `.mdkg/index/*.sqlite-wal`
+- `.mdkg/index/*.sqlite-shm`
+- `.mdkg/index/*.sqlite-journal`
 - `.mdkg/pack/`
 - `.mdkg/archive/**/source/`
 
 Recommended `.gitignore` entries:
-- `.mdkg/index/`
-- `.mdkg/index/**`
+- `.mdkg/index/*.json`
+- `.mdkg/index/*.tmp`
+- `.mdkg/index/write.lock/`
+- `.mdkg/index/*.sqlite-wal`
+- `.mdkg/index/*.sqlite-shm`
+- `.mdkg/index/*.sqlite-journal`
 - `.mdkg/pack/`
 - `.mdkg/archive/**/source/`
 
@@ -60,7 +70,12 @@ Additional belt-and-suspenders:
 If the repo is containerized:
 - `.dockerignore` SHOULD exclude:
   - `.mdkg/`
-  - `.mdkg/index/`
+  - `.mdkg/index/*.json`
+  - `.mdkg/index/*.tmp`
+  - `.mdkg/index/write.lock/`
+  - `.mdkg/index/*.sqlite-wal`
+  - `.mdkg/index/*.sqlite-shm`
+  - `.mdkg/index/*.sqlite-journal`
   - `node_modules/`
   - `dist/` (if built in container)
   - any other local artifacts
@@ -72,8 +87,8 @@ For application builds:
 
 `mdkg init` updates ignore files by default for safety:
 
-- `.gitignore` appends `.mdkg/index/`, `.mdkg/pack/`
-- `.npmignore` appends `.mdkg/`, `.mdkg/index/`, `.mdkg/pack/`
+- `.gitignore` appends generated index cache/temp/lock patterns, `.mdkg/pack/`, and raw archive source ignores.
+- `.npmignore` appends `.mdkg/`, generated index cache/temp/lock patterns, and `.mdkg/pack/`.
 - `--no-update-ignores` disables these default writes
 
 Explicit flags remain available and take precedence:
@@ -84,9 +99,9 @@ Explicit flags remain available and take precedence:
 
 ## Index safety
 
-- `.mdkg/index/` is generated.
-- Index files may contain extracted metadata and could expose sensitive strings.
-- Index files MUST be ignored from git.
+- `.mdkg/index/` contains generated caches.
+- JSON index files may contain extracted metadata and could expose sensitive strings; they MUST be ignored from git.
+- `.mdkg/index/mdkg.sqlite` contains the same rebuildable access data and may be committed only by explicit repo policy; `mdkg doctor` warns when it exceeds `index.sqlite_commit_warning_bytes`.
 - Index rebuild should be deterministic and safe to regenerate at any time.
 
 ## Bundle safety
@@ -115,7 +130,8 @@ Workspace-local `.mdkg/` directories (near code) should follow the same rules:
 
 ## Summary checklist
 
-- ✅ `.mdkg/index/` ignored
+- ✅ generated JSON index/temp/lock files ignored
+- ✅ `.mdkg/index/mdkg.sqlite` committed only by explicit repo policy
 - ✅ event logs are committed by default unless a repo chooses to ignore them manually
 - ✅ npm publishes only `dist/`, `README.md`, `LICENSE`
 - ✅ optional `.npmignore` excludes `.mdkg/`

package/dist/init/core/rule-5-release-and-versioning.md

@@ -37,14 +37,15 @@ The npm package MUST include:
 
 It MUST NOT include:
 - `.mdkg/` docs
-- `.mdkg/index/`
+- generated `.mdkg/index/` caches
 - source code (optional; can be included later, but not required)
 
 ## Release checklist (v1)
 
 1) Ensure clean working tree
 - no uncommitted changes
-- all `.mdkg/index/` ignored
+- generated JSON index/temp/lock files ignored
+- `.mdkg/index/mdkg.sqlite` either intentionally tracked or absent
 
 2) Rebuild and validate
 - run `mdkg index`
@@ -79,4 +80,4 @@ Release notes should call out:
 - new commands / flags
 - changes to pack behavior
 - changes to config schema (and how migration behaves)
-- new node types or template changes
+- new node types or template changes

package/dist/init/init-manifest.json

@@ -1,12 +1,12 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "mdkg_version": "0.1.2",
+  "mdkg_version": "0.1.3",
   "files": [
     {
       "path": ".mdkg/config.json",
       "category": "config",
-      "sha256": "8f0fd9ba020511e22d912f59c39bdd1c09706595564361694860ded3e9488e7e"
+      "sha256": "0319f2e92ae0030d67816c025802be50ec5eecc3274e75a4e0ded3e753d945b3"
     },
     {
       "path": ".mdkg/core/core.md",
@@ -26,7 +26,7 @@
     {
       "path": ".mdkg/core/rule-1-mdkg-conventions.md",
       "category": "core",
-      "sha256": "20073cd21c148f1b93a382550f835ccb2e896cc676903328557004319235c112"
+      "sha256": "15f886e6661046de45ad798c292d74cc1ff3cc14c8cfcc82ed0b8c35635d0477"
     },
     {
       "path": ".mdkg/core/rule-2-context-pack-rules.md",
@@ -36,17 +36,17 @@
     {
       "path": ".mdkg/core/rule-3-cli-contract.md",
       "category": "core",
-      "sha256": "ad151ac183dea1158884c4341154118d9623392871062b8faa6cecd4bde580ba"
+      "sha256": "4ff22c60e3b4093492f00c8ddd738f7241192c7b1edbfdcbdc4ed09d95192aa6"
     },
     {
       "path": ".mdkg/core/rule-4-repo-safety-and-ignores.md",
       "category": "core",
-      "sha256": "b4638d8b5aeae74768fb971a8844aa473177df8814b929fedff6faf865a034cc"
+      "sha256": "4edf0efa29ec470e96cad3e0abc7b8f44e2e718d7a9959f9cefc5e1db7e02b6c"
     },
     {
       "path": ".mdkg/core/rule-5-release-and-versioning.md",
       "category": "core",
-      "sha256": "4fc6648052f80b90b2efc173e3bcab16cb0bc6680bb8b04f76c66fff06ad19cd"
+      "sha256": "e97b00aa3ade29011f1f2b482042ec292f74aad8b1d72e2f8e691cdeca5d4f70"
     },
     {
       "path": ".mdkg/core/rule-6-templates-and-schemas.md",
@@ -61,7 +61,7 @@
     {
       "path": ".mdkg/README.md",
       "category": "mdkg_doc",
-      "sha256": "fc85d07197da2fce189d295b6e6047de2a49b711adc74c991029faec6be385de"
+      "sha256": "6ff69157098b5cc780f063ffadabff36b70e8567cec7fc406d7550385c467d0e"
     },
     {
       "path": ".mdkg/skills/build-pack-and-execute-task/SKILL.md",
@@ -176,7 +176,7 @@
     {
       "path": "AGENT_START.md",
       "category": "startup_doc",
-      "sha256": "6ff5915ea72d7453b2f7666e138808b6b0854123c7030bcced313a15f86c2b3a"
+      "sha256": "e5bd54a4321443216645b11fd5f27aff2e8f6c760f21dad12b6d0dbe634b0986"
     },
     {
       "path": "AGENTS.md",
@@ -191,7 +191,7 @@
     {
       "path": "CLI_COMMAND_MATRIX.md",
       "category": "startup_doc",
-      "sha256": "f852a4f0a99c87aeb123a839c2902798ffdf5bf8012b4f367cb9c85905473ae7"
+      "sha256": "6e347620120c93eb9f330d137087f9e6b3279c629fcc24b65af561bd3cf385a0"
     },
     {
       "path": "llms.txt",

package/dist/util/atomic.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.atomicWriteFile = atomicWriteFile;
+exports.writeFileExclusive = writeFileExclusive;
+const crypto_1 = __importDefault(require("crypto"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function randomSuffix() {
+    return `${process.pid}-${Date.now()}-${crypto_1.default.randomBytes(6).toString("hex")}`;
+}
+function writeAndSync(filePath, data, flags) {
+    const handle = fs_1.default.openSync(filePath, flags);
+    try {
+        if (typeof data === "string") {
+            fs_1.default.writeFileSync(handle, data, "utf8");
+        }
+        else {
+            fs_1.default.writeFileSync(handle, data);
+        }
+        fs_1.default.fsyncSync(handle);
+    }
+    finally {
+        fs_1.default.closeSync(handle);
+    }
+}
+function atomicWriteFile(filePath, data) {
+    fs_1.default.mkdirSync(path_1.default.dirname(filePath), { recursive: true });
+    const tempPath = path_1.default.join(path_1.default.dirname(filePath), `.${path_1.default.basename(filePath)}.${randomSuffix()}.tmp`);
+    try {
+        writeAndSync(tempPath, data, "wx");
+        fs_1.default.renameSync(tempPath, filePath);
+    }
+    catch (err) {
+        fs_1.default.rmSync(tempPath, { force: true });
+        throw err;
+    }
+}
+function writeFileExclusive(filePath, data) {
+    fs_1.default.mkdirSync(path_1.default.dirname(filePath), { recursive: true });
+    writeAndSync(filePath, data, "wx");
+}