mdkg 0.0.3 → 0.0.5

package/dist/commands/checkpoint.js

@@ -11,8 +11,8 @@ const index_cache_1 = require("../graph/index_cache");
 const loader_1 = require("../templates/loader");
 const date_1 = require("../util/date");
 const errors_1 = require("../util/errors");
-const ID_RE = /^[a-z]+-[0-9]+$/;
-const ID_REF_RE = /^([a-z][a-z0-9_]*:)?[a-z]+-[0-9]+$/;
+const id_1 = require("../util/id");
+const event_support_1 = require("./event_support");
 function parseCsvList(raw) {
     if (!raw) {
         return [];
@@ -24,14 +24,14 @@ function parseCsvList(raw) {
 }
 function normalizeId(value, key) {
     const normalized = value.toLowerCase();
-    if (!ID_RE.test(normalized) && normalized !== "rule-guide") {
-        throw new errors_1.UsageError(`${key} entries must match <prefix>-<number>: ${value}`);
+    if (!(0, id_1.isCanonicalId)(normalized)) {
+        throw new errors_1.UsageError(`${key} entries must match <prefix>-<number> or reserved id: ${value}`);
     }
     return normalized;
 }
 function normalizeIdRef(value, key) {
     const normalized = value.toLowerCase();
-    if (!ID_REF_RE.test(normalized)) {
+    if (!(0, id_1.isCanonicalIdRef)(normalized)) {
         throw new errors_1.UsageError(`${key} entries must match <id> or <ws>:<id>: ${value}`);
     }
     return normalized;
@@ -115,7 +115,8 @@ function runCheckpointNewCommand(options) {
         }
     }
     const scope = parseCsvList(options.scope).map((value) => normalizeId(value, "--scope"));
-    const today = (0, date_1.formatDate)(new Date());
+    const now = options.now ?? new Date();
+    const today = (0, date_1.formatDate)(now);
     const template = (0, loader_1.loadTemplate)(options.root, config, "checkpoint", options.template);
     const content = (0, loader_1.renderTemplate)(template, {
         id,
@@ -129,5 +130,15 @@ function runCheckpointNewCommand(options) {
     });
     fs_1.default.mkdirSync(workDir, { recursive: true });
     fs_1.default.writeFileSync(filePath, content, "utf8");
+    (0, event_support_1.appendAutomaticEvent)({
+        root: options.root,
+        ws,
+        kind: "CHECKPOINT_CREATED",
+        status: "ok",
+        refs: [id],
+        notes: options.note ?? `checkpoint created via mdkg checkpoint new`,
+        runId: options.runId,
+        now,
+    });
     console.log(`checkpoint created: ${ws}:${id} (${path_1.default.relative(options.root, filePath)})`);
 }

package/dist/commands/event.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runEventEnableCommand = runEventEnableCommand;
+exports.runEventAppendCommand = runEventAppendCommand;
+const event_support_1 = require("./event_support");
+const errors_1 = require("../util/errors");
+function runEventEnableCommand(options) {
+    const result = (0, event_support_1.ensureEventsEnabled)(options);
+    const createdLabel = result.created ? "created" : "already present";
+    const ignoreLabel = result.gitignoreUpdated ? "updated .gitignore" : "left .gitignore unchanged";
+    console.log(`event logging enabled: ${result.ws} (${createdLabel}; ${ignoreLabel})`);
+}
+function normalizeEventStatus(value) {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "ok" ||
+        normalized === "error" ||
+        normalized === "retry" ||
+        normalized === "skipped") {
+        return normalized;
+    }
+    throw new errors_1.UsageError("--status must be one of ok, error, retry, skipped");
+}
+function runEventAppendCommand(options) {
+    const kind = options.kind.trim();
+    if (!kind) {
+        throw new errors_1.UsageError("--kind is required");
+    }
+    const refs = (0, event_support_1.normalizeEventRefList)(options.refs);
+    if (refs.length === 0) {
+        throw new errors_1.UsageError("--refs requires at least one id or qid");
+    }
+    const record = (0, event_support_1.appendEvent)({
+        root: options.root,
+        ws: options.ws,
+        kind,
+        status: normalizeEventStatus(options.status),
+        refs,
+        artifacts: (0, event_support_1.normalizeEventStringList)(options.artifacts),
+        notes: options.notes,
+        runId: options.runId,
+        agent: options.agent,
+        skill: options.skill,
+        tool: options.tool,
+    });
+    console.log(`event appended: ${record.workspace}:${record.kind} (${record.run_id})`);
+}

package/dist/commands/event_support.js

@@ -0,0 +1,146 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeWorkspaceForEvents = normalizeWorkspaceForEvents;
+exports.resolveEventsPath = resolveEventsPath;
+exports.createLocalRunId = createLocalRunId;
+exports.isEventLoggingEnabled = isEventLoggingEnabled;
+exports.ensureEventsEnabled = ensureEventsEnabled;
+exports.normalizeEventRefList = normalizeEventRefList;
+exports.normalizeEventStringList = normalizeEventStringList;
+exports.appendEvent = appendEvent;
+exports.appendAutomaticEvent = appendAutomaticEvent;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const config_1 = require("../core/config");
+const errors_1 = require("../util/errors");
+function appendIgnoreEntries(filePath, entries) {
+    const normalizedEntries = entries.map((entry) => entry.trim()).filter(Boolean);
+    if (normalizedEntries.length === 0) {
+        return false;
+    }
+    let existing = "";
+    if (fs_1.default.existsSync(filePath)) {
+        existing = fs_1.default.readFileSync(filePath, "utf8");
+    }
+    const existingLines = new Set(existing
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean));
+    const additions = normalizedEntries.filter((entry) => !existingLines.has(entry));
+    if (additions.length === 0) {
+        return false;
+    }
+    const next = existing.length === 0 ? `${additions.join("\n")}\n` : `${existing.replace(/\s*$/, "\n")}${additions.join("\n")}\n`;
+    fs_1.default.writeFileSync(filePath, next, "utf8");
+    return true;
+}
+function normalizeWorkspaceForEvents(config, raw) {
+    const normalized = (raw ?? "root").toLowerCase();
+    if (normalized === "all") {
+        throw new errors_1.UsageError("--ws all is not valid here");
+    }
+    if (!config.workspaces[normalized]) {
+        throw new errors_1.NotFoundError(`workspace not found: ${normalized}`);
+    }
+    return normalized;
+}
+function resolveEventsPath(root, config, ws = "root") {
+    const entry = config.workspaces[ws];
+    if (!entry) {
+        throw new errors_1.NotFoundError(`workspace not found: ${ws}`);
+    }
+    return path_1.default.resolve(root, entry.path, entry.mdkg_dir, "work", "events", "events.jsonl");
+}
+function formatRunIdTimestamp(now) {
+    const iso = now.toISOString().replace(/[-:]/g, "").replace(/\./g, "").replace("Z", "Z");
+    return iso;
+}
+function createLocalRunId(kind, now = new Date()) {
+    const normalizedKind = kind.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+    return `run_mdkg_cli_${normalizedKind}_${formatRunIdTimestamp(now)}`;
+}
+function isEventLoggingEnabled(root, config, ws) {
+    const normalizedWs = normalizeWorkspaceForEvents(config, ws);
+    return fs_1.default.existsSync(resolveEventsPath(root, config, normalizedWs));
+}
+function ensureEventsEnabled(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const ws = normalizeWorkspaceForEvents(config, options.ws);
+    const eventsPath = resolveEventsPath(options.root, config, ws);
+    const updateGitignore = options.updateGitignore !== false;
+    let created = false;
+    if (!fs_1.default.existsSync(eventsPath)) {
+        fs_1.default.mkdirSync(path_1.default.dirname(eventsPath), { recursive: true });
+        fs_1.default.writeFileSync(eventsPath, "", "utf8");
+        created = true;
+    }
+    let gitignoreUpdated = false;
+    if (updateGitignore) {
+        gitignoreUpdated = appendIgnoreEntries(path_1.default.join(options.root, ".gitignore"), [
+            ".mdkg/work/events/*.jsonl",
+        ]);
+    }
+    return { ws, eventsPath, created, gitignoreUpdated };
+}
+function normalizeIdOrIdRef(value) {
+    return value.trim().toLowerCase();
+}
+function normalizeEventRefList(raw) {
+    if (!raw) {
+        return [];
+    }
+    return raw
+        .split(",")
+        .map((value) => normalizeIdOrIdRef(value))
+        .filter(Boolean);
+}
+function normalizeEventStringList(raw) {
+    if (!raw) {
+        return [];
+    }
+    return raw
+        .split(",")
+        .map((value) => value.trim())
+        .filter(Boolean);
+}
+function buildEventRecord(config, options) {
+    const now = options.now ?? new Date();
+    const ws = normalizeWorkspaceForEvents(config, options.ws);
+    return {
+        ts: now.toISOString(),
+        run_id: options.runId?.trim() || createLocalRunId(options.kind, now),
+        workspace: ws,
+        agent: options.agent?.trim() || "mdkg-cli",
+        kind: options.kind,
+        status: options.status,
+        refs: options.refs.map(normalizeIdOrIdRef).filter(Boolean),
+        artifacts: (options.artifacts ?? []).map((value) => value.trim()).filter(Boolean),
+        notes: options.notes?.trim() ?? "",
+        ...(options.skill ? { skill: options.skill.trim().toLowerCase() } : {}),
+        ...(options.tool ? { tool: options.tool.trim() } : {}),
+    };
+}
+function appendEvent(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const record = buildEventRecord(config, options);
+    if (record.refs.length === 0) {
+        throw new errors_1.UsageError("--refs requires at least one id or qid");
+    }
+    const eventsPath = resolveEventsPath(options.root, config, record.workspace);
+    if (!fs_1.default.existsSync(eventsPath)) {
+        throw new errors_1.NotFoundError(`event logging is not enabled for workspace ${record.workspace}; run \`mdkg event enable --ws ${record.workspace}\``);
+    }
+    fs_1.default.appendFileSync(eventsPath, `${JSON.stringify(record)}\n`, "utf8");
+    return record;
+}
+function appendAutomaticEvent(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const ws = normalizeWorkspaceForEvents(config, options.ws);
+    if (!isEventLoggingEnabled(options.root, config, ws)) {
+        return undefined;
+    }
+    return appendEvent({ ...options, ws });
+}

package/dist/commands/format.js

@@ -13,8 +13,7 @@ const node_1 = require("../graph/node");
 const workspace_files_1 = require("../graph/workspace_files");
 const errors_1 = require("../util/errors");
 const date_1 = require("../util/date");
-const ID_RE = /^[a-z]+-[0-9]+$/;
-const ID_REF_RE = /^([a-z][a-z0-9_]*:)?[a-z]+-[0-9]+$/;
+const id_1 = require("../util/id");
 const DEC_ID_RE = /^dec-[0-9]+$/;
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 const ID_LIST_KEYS = new Set(["refs", "scope"]);
@@ -22,7 +21,7 @@ const ID_REF_LIST_KEYS = new Set(["relates", "blocked_by", "blocks"]);
 const ID_REF_SCALAR_KEYS = new Set(["epic", "parent", "prev", "next"]);
 const PRESERVE_CASE_LIST_KEYS = new Set(["links", "artifacts"]);
 function isValidId(value) {
-    return ID_RE.test(value) || value === "rule-guide";
+    return (0, id_1.isCanonicalId)(value);
 }
 function isCoreListFile(filePath) {
     return path_1.default.basename(filePath) === "core.md" && path_1.default.basename(path_1.default.dirname(filePath)) === "core";
@@ -59,9 +58,9 @@ function normalizeList(values, key, errors, filePath) {
             continue;
         }
         if (ID_LIST_KEYS.has(key) && !isValidId(entry)) {
-            errors.push(`${filePath}: ${key} entries must match <prefix>-<number>`);
+            errors.push(`${filePath}: ${key} entries must match <prefix>-<number> or reserved id`);
         }
-        if (ID_REF_LIST_KEYS.has(key) && !ID_REF_RE.test(entry)) {
+        if (ID_REF_LIST_KEYS.has(key) && !(0, id_1.isCanonicalIdRef)(entry)) {
             errors.push(`${filePath}: ${key} entries must be valid id references`);
         }
     }
@@ -69,7 +68,7 @@ function normalizeList(values, key, errors, filePath) {
 }
 function normalizeIdRef(value, key, errors, filePath) {
     const normalized = normalizeScalar(value).toLowerCase();
-    if (!ID_REF_RE.test(normalized)) {
+    if (!(0, id_1.isCanonicalIdRef)(normalized)) {
         errors.push(`${filePath}: ${key} must be a valid id reference`);
     }
     return normalized;
@@ -124,7 +123,7 @@ function normalizeFrontmatter(frontmatter, schema, type, workStatusEnum, priorit
     else {
         const normalizedId = idValue.toLowerCase();
         if (!isValidId(normalizedId)) {
-            errors.push(`${filePath}: id must match <prefix>-<number>`);
+            errors.push(`${filePath}: id must match <prefix>-<number> or reserved id`);
         }
         normalized.id = normalizedId;
     }

package/dist/commands/index.js

@@ -8,10 +8,16 @@ const path_1 = __importDefault(require("path"));
 const config_1 = require("../core/config");
 const indexer_1 = require("../graph/indexer");
 const index_cache_1 = require("../graph/index_cache");
+const skills_index_cache_1 = require("../graph/skills_index_cache");
+const skills_indexer_1 = require("../graph/skills_indexer");
 function runIndexCommand(options) {
     const config = (0, config_1.loadConfig)(options.root);
-    const index = (0, indexer_1.buildIndex)(options.root, config, { tolerant: options.tolerant });
-    const outputPath = path_1.default.resolve(options.root, config.index.global_index_path);
-    (0, index_cache_1.writeIndex)(outputPath, index);
-    console.log(`index written: ${path_1.default.relative(options.root, outputPath)}`);
+    const nodeIndex = (0, indexer_1.buildIndex)(options.root, config, { tolerant: options.tolerant });
+    const skillsIndex = (0, skills_indexer_1.buildSkillsIndex)(options.root, config);
+    const nodesOutputPath = path_1.default.resolve(options.root, config.index.global_index_path);
+    const skillsOutputPath = (0, skills_indexer_1.resolveSkillsIndexPath)(options.root);
+    (0, index_cache_1.writeIndex)(nodesOutputPath, nodeIndex);
+    (0, skills_index_cache_1.writeSkillsIndex)(skillsOutputPath, skillsIndex);
+    console.log(`index written: ${path_1.default.relative(options.root, nodesOutputPath)}`);
+    console.log(`skills index written: ${path_1.default.relative(options.root, skillsOutputPath)}`);
 }

package/dist/commands/init.js

@@ -6,8 +6,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runInitCommand = runInitCommand;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const config_1 = require("../core/config");
 const errors_1 = require("../util/errors");
+const date_1 = require("../util/date");
+const skill_support_1 = require("./skill_support");
+const skill_mirror_1 = require("./skill_mirror");
 const DEFAULT_SEED_SUBDIR = path_1.default.resolve(__dirname, "..", "init");
+const SOUL_PIN_ID = "rule-soul";
+const HUMAN_PIN_ID = "rule-human";
+const DEFAULT_CORE_LIST_HEADER = [
+    "# mdkg verbose core list",
+    "",
+    "# One node ID per line. Lines starting with # are comments.",
+    "# This list is included by `mdkg pack --verbose`.",
+];
 function listFiles(dir) {
     if (!fs_1.default.existsSync(dir)) {
         return [];
@@ -59,16 +71,169 @@ function appendIgnoreEntries(filePath, entries) {
     fs_1.default.writeFileSync(filePath, updated, "utf8");
     return true;
 }
+function writeFileIfMissing(filePath, content, force, stats) {
+    if (fs_1.default.existsSync(filePath) && !force) {
+        stats.skipped += 1;
+        return;
+    }
+    fs_1.default.mkdirSync(path_1.default.dirname(filePath), { recursive: true });
+    fs_1.default.writeFileSync(filePath, content, "utf8");
+    stats.created += 1;
+}
+function soulTemplate(created) {
+    return [
+        "---",
+        `id: ${SOUL_PIN_ID}`,
+        "type: rule",
+        "title: agent soul and execution contract",
+        "tags: [agent, constraints]",
+        "owners: []",
+        "links: []",
+        "artifacts: []",
+        "relates: []",
+        "refs: []",
+        "aliases: [soul]",
+        `created: ${created}`,
+        `updated: ${created}`,
+        "---",
+        "",
+        "# Purpose",
+        "",
+        "Define the canonical agent execution boundaries and memory contract for this repository.",
+        "",
+        "# Scope",
+        "",
+        "Applies to all orchestrators and coding-agent executions using mdkg in this repo.",
+        "",
+        "# Requirements",
+        "",
+        "- Ask for approval before destructive operations or policy-sensitive actions.",
+        "- Prefer deterministic mdkg packs over ad-hoc context assembly.",
+        "- Follow single-writer commit discipline and event-driven batching.",
+        "- Never place secrets in mdkg docs or generated packs.",
+        "",
+        "# Notes",
+        "",
+        "Customize this file to encode repo-specific constraints, approval boundaries, and memory cadence.",
+        "",
+    ].join("\n");
+}
+function humanTemplate(created) {
+    return [
+        "---",
+        `id: ${HUMAN_PIN_ID}`,
+        "type: rule",
+        "title: human working profile and collaboration preferences",
+        "tags: [human, collaboration, preferences]",
+        "owners: []",
+        "links: []",
+        "artifacts: []",
+        "relates: []",
+        "refs: []",
+        "aliases: [human]",
+        `created: ${created}`,
+        `updated: ${created}`,
+        "---",
+        "",
+        "# Purpose",
+        "",
+        "Capture stable collaboration preferences and boundaries so agents can work with less ambiguity.",
+        "",
+        "# Scope",
+        "",
+        "Applies to planning, implementation, and review interactions in this repository.",
+        "",
+        "# Requirements",
+        "",
+        "- Keep top goals, boundaries, and style preferences current.",
+        "- Include ask-before-doing constraints for risky or high-impact actions.",
+        "- Record preferred environment assumptions and validation commands.",
+        "",
+        "# Notes",
+        "",
+        "Suggested prompts:",
+        "- What are your top 3 goals in this repo right now?",
+        "- What should never happen without confirmation?",
+        "- What coding/review style should the agent prefer?",
+        "- What OS/runtime/test commands should be assumed?",
+        "",
+    ].join("\n");
+}
+function seededInitEvent(nowIso) {
+    const event = {
+        ts: nowIso,
+        run_id: `init-${nowIso.replace(/[^0-9]/g, "").slice(0, 14)}`,
+        workspace: "root",
+        agent: "mdkg",
+        kind: "RUN_STARTED",
+        status: "ok",
+        refs: ["edd-4"],
+        artifacts: [],
+        notes: "init agent scaffold target initialized",
+        redacted: true,
+    };
+    return `${JSON.stringify(event)}\n`;
+}
+function parseCoreList(raw) {
+    const lines = raw.split(/\r?\n/);
+    const header = [];
+    const ids = [];
+    let seenFirstId = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        const isComment = trimmed.startsWith("#");
+        if (!seenFirstId && (trimmed.length === 0 || isComment)) {
+            header.push(line);
+            continue;
+        }
+        if (trimmed.length === 0 || isComment) {
+            seenFirstId = true;
+            continue;
+        }
+        seenFirstId = true;
+        ids.push(trimmed.toLowerCase());
+    }
+    return { header, ids };
+}
+function ensureCorePins(coreListPath, requiredPins) {
+    const raw = fs_1.default.existsSync(coreListPath) ? fs_1.default.readFileSync(coreListPath, "utf8") : "";
+    const { header, ids } = parseCoreList(raw);
+    const seen = new Set();
+    const dedupedExisting = [];
+    for (const id of ids) {
+        if (seen.has(id)) {
+            continue;
+        }
+        seen.add(id);
+        dedupedExisting.push(id);
+    }
+    const required = requiredPins.map((value) => value.toLowerCase());
+    const filteredExisting = dedupedExisting.filter((value) => !required.includes(value));
+    const finalIds = [...required, ...filteredExisting];
+    const headerLines = header.length > 0 ? header : DEFAULT_CORE_LIST_HEADER;
+    const normalizedHeader = headerLines.slice();
+    while (normalizedHeader.length > 0 && normalizedHeader[normalizedHeader.length - 1].trim() === "") {
+        normalizedHeader.pop();
+    }
+    const output = [...normalizedHeader, "", ...finalIds, ""].join("\n");
+    fs_1.default.mkdirSync(path_1.default.dirname(coreListPath), { recursive: true });
+    fs_1.default.writeFileSync(coreListPath, output, "utf8");
+}
 function runInitCommand(options) {
     const root = path_1.default.resolve(options.root);
     const seedRoot = options.seedRoot ? path_1.default.resolve(options.seedRoot) : DEFAULT_SEED_SUBDIR;
     const createAgents = Boolean(options.createAgents || options.createLlm);
     const createClaude = Boolean(options.createClaude || options.createLlm);
+    const createStartupDocs = Boolean(options.createLlm || options.agent);
+    const force = Boolean(options.force);
     const seedConfig = path_1.default.join(seedRoot, "config.json");
     const seedCore = path_1.default.join(seedRoot, "core");
     const seedTemplates = path_1.default.join(seedRoot, "templates");
     const seedAgents = path_1.default.join(seedRoot, "AGENTS.md");
     const seedClaude = path_1.default.join(seedRoot, "CLAUDE.md");
+    const seedLlms = path_1.default.join(seedRoot, "llms.txt");
+    const seedAgentStart = path_1.default.join(seedRoot, "AGENT_START.md");
+    const seedCliMatrix = path_1.default.join(seedRoot, "CLI_COMMAND_MATRIX.md");
     const seedReadme = path_1.default.join(seedRoot, "README.md");
     if (!fs_1.default.existsSync(seedConfig) || !fs_1.default.existsSync(seedCore) || !fs_1.default.existsSync(seedTemplates)) {
         throw new errors_1.NotFoundError(`init assets not found at ${seedRoot} (try reinstalling mdkg)`);
@@ -79,6 +244,15 @@ function runInitCommand(options) {
     if (createClaude && !fs_1.default.existsSync(seedClaude)) {
         throw new errors_1.NotFoundError(`init assets missing CLAUDE.md at ${seedRoot}`);
     }
+    if (createStartupDocs && !fs_1.default.existsSync(seedLlms)) {
+        throw new errors_1.NotFoundError(`init assets missing llms.txt at ${seedRoot}`);
+    }
+    if (createStartupDocs && !fs_1.default.existsSync(seedAgentStart)) {
+        throw new errors_1.NotFoundError(`init assets missing AGENT_START.md at ${seedRoot}`);
+    }
+    if (createStartupDocs && !fs_1.default.existsSync(seedCliMatrix)) {
+        throw new errors_1.NotFoundError(`init assets missing CLI_COMMAND_MATRIX.md at ${seedRoot}`);
+    }
     if (!fs_1.default.existsSync(seedReadme)) {
         throw new errors_1.NotFoundError(`init assets missing README.md at ${seedRoot}`);
     }
@@ -87,34 +261,68 @@ function runInitCommand(options) {
     fs_1.default.mkdirSync(path_1.default.join(mdkgDir, "work"), { recursive: true });
     fs_1.default.mkdirSync(path_1.default.join(mdkgDir, "design"), { recursive: true });
     const stats = { created: 0, skipped: 0 };
-    copySeedFile(seedConfig, path_1.default.join(mdkgDir, "config.json"), Boolean(options.force), stats);
-    copySeedFile(seedReadme, path_1.default.join(mdkgDir, "README.md"), Boolean(options.force), stats);
-    copySeedDir(seedCore, path_1.default.join(mdkgDir, "core"), Boolean(options.force), stats);
-    copySeedDir(seedTemplates, path_1.default.join(mdkgDir, "templates"), Boolean(options.force), stats);
+    copySeedFile(seedConfig, path_1.default.join(mdkgDir, "config.json"), force, stats);
+    copySeedFile(seedReadme, path_1.default.join(mdkgDir, "README.md"), force, stats);
+    copySeedDir(seedCore, path_1.default.join(mdkgDir, "core"), force, stats);
+    copySeedDir(seedTemplates, path_1.default.join(mdkgDir, "templates"), force, stats);
     if (createAgents) {
-        copySeedFile(seedAgents, path_1.default.join(root, "AGENTS.md"), Boolean(options.force), stats);
+        copySeedFile(seedAgents, path_1.default.join(root, "AGENTS.md"), force, stats);
     }
     if (createClaude) {
-        copySeedFile(seedClaude, path_1.default.join(root, "CLAUDE.md"), Boolean(options.force), stats);
+        copySeedFile(seedClaude, path_1.default.join(root, "CLAUDE.md"), force, stats);
+    }
+    if (createStartupDocs) {
+        copySeedFile(seedLlms, path_1.default.join(root, "llms.txt"), force, stats);
+        copySeedFile(seedAgentStart, path_1.default.join(root, "AGENT_START.md"), force, stats);
+        copySeedFile(seedCliMatrix, path_1.default.join(root, "CLI_COMMAND_MATRIX.md"), force, stats);
+    }
+    if (options.agent) {
+        const today = (0, date_1.formatDate)(new Date());
+        const soulPath = path_1.default.join(mdkgDir, "core", "SOUL.md");
+        const humanPath = path_1.default.join(mdkgDir, "core", "HUMAN.md");
+        const skillsDir = path_1.default.join(mdkgDir, "skills");
+        const registryPath = path_1.default.join(skillsDir, "registry.md");
+        const eventsDir = path_1.default.join(mdkgDir, "work", "events");
+        const eventsPath = path_1.default.join(eventsDir, "events.jsonl");
+        fs_1.default.mkdirSync(skillsDir, { recursive: true });
+        fs_1.default.mkdirSync(eventsDir, { recursive: true });
+        writeFileIfMissing(soulPath, soulTemplate(today), force, stats);
+        writeFileIfMissing(humanPath, humanTemplate(today), force, stats);
+        writeFileIfMissing(registryPath, (0, skill_support_1.registryTemplate)(), force, stats);
+        if (!fs_1.default.existsSync(eventsPath) || force) {
+            writeFileIfMissing(eventsPath, seededInitEvent(new Date().toISOString()), force, stats);
+        }
+        const coreListPath = path_1.default.join(mdkgDir, "core", "core.md");
+        ensureCorePins(coreListPath, [SOUL_PIN_ID, HUMAN_PIN_ID]);
+        (0, skill_mirror_1.scaffoldMirrorRoots)(root);
+        const config = (0, config_1.loadConfig)(root);
+        (0, skill_mirror_1.syncSkillMirrors)({ root, config, createRoots: true, force });
     }
-    if (options.updateGitignore) {
-        appendIgnoreEntries(path_1.default.join(root, ".gitignore"), [".mdkg/index/", ".mdkg/pack/"]);
+    const noUpdateIgnores = Boolean(options.noUpdateIgnores);
+    const shouldUpdateGitignore = Boolean(options.updateGitignore || !noUpdateIgnores);
+    const shouldUpdateNpmignore = Boolean(options.updateNpmignore || !noUpdateIgnores);
+    if (shouldUpdateGitignore) {
+        appendIgnoreEntries(path_1.default.join(root, ".gitignore"), [
+            ".mdkg/index/",
+            ".mdkg/pack/",
+            ".mdkg/work/events/*.jsonl",
+        ]);
     }
-    if (options.updateNpmignore) {
+    if (shouldUpdateNpmignore) {
         appendIgnoreEntries(path_1.default.join(root, ".npmignore"), [".mdkg/", ".mdkg/index/", ".mdkg/pack/"]);
     }
     if (options.updateDockerignore) {
         appendIgnoreEntries(path_1.default.join(root, ".dockerignore"), [".mdkg/"]);
     }
-    if (!options.updateGitignore && !options.updateNpmignore && !options.updateDockerignore) {
-        console.error("warning: ignore files were not updated");
-        console.error("hint: rerun `mdkg init --update-gitignore --update-npmignore` to avoid committing cache/pack artifacts");
-    }
     console.log(`mdkg init complete: ${stats.created} file(s) created, ${stats.skipped} skipped`);
     console.log("next:");
-    console.log("  mdkg index");
+    if (createStartupDocs) {
+        console.log("  read AGENT_START.md");
+    }
     console.log('  mdkg new task "..." --status todo --priority 1');
-    console.log("  mdkg list --status todo");
-    console.log("  mdkg pack <id> --verbose");
+    console.log('  mdkg search "..."');
+    console.log("  mdkg show <id>");
+    console.log("  mdkg next");
+    console.log("  mdkg pack <id>");
     console.log("  mdkg validate");
 }

package/dist/commands/list.js

@@ -8,6 +8,7 @@ const errors_1 = require("../util/errors");
 const qid_1 = require("../util/qid");
 const sort_1 = require("../util/sort");
 const node_card_1 = require("./node_card");
+const query_output_1 = require("./query_output");
 function normalizeWorkspace(value) {
     if (!value || value === "all") {
         return undefined;
@@ -20,6 +21,10 @@ function runListCommand(options) {
     if (ws && !config.workspaces[ws]) {
         throw new errors_1.NotFoundError(`workspace not found: ${ws}`);
     }
+    const normalizedType = options.type?.toLowerCase();
+    if (normalizedType === "skill") {
+        throw new errors_1.UsageError("--type skill is no longer supported here; use `mdkg skill list`");
+    }
     const { index, rebuilt, stale } = (0, index_cache_1.loadIndex)({
         root: options.root,
         config,
@@ -39,13 +44,25 @@ function runListCommand(options) {
     }
     const filtered = (0, filter_1.filterNodes)(Object.values(index.nodes), {
         ws,
-        type: options.type,
+        type: normalizedType,
         status: options.status,
         epic: epicQid,
         priority: options.priority,
         blocked: options.blocked,
+        tags: options.tags,
+        tagsMode: options.tagsMode,
     });
     const sorted = (0, sort_1.sortNodesByQid)(filtered);
+    if (options.json) {
+        (0, query_output_1.writeJson)({
+            command: "list",
+            kind: "node",
+            count: sorted.length,
+            items: sorted.map(query_output_1.toNodeSummaryJson),
+        });
+        return;
+    }
+    (0, query_output_1.writeCount)(sorted.length, sorted.length === 0 ? "no nodes matched current filters" : undefined);
     for (const node of sorted) {
         console.log((0, node_card_1.formatNodeCard)(node));
     }