mdkg 0.0.6 → 0.0.7

package/README.md

@@ -176,10 +176,13 @@ Current source behavior:
   - `mdkg skill show <slug>`
   - `mdkg skill validate [<slug>]`
   - `mdkg skill sync`
-- machine-readable skill discovery is available through:
+- 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
@@ -201,11 +204,13 @@ This repo now dogfoods three internal skills:
 This release includes:
 - `init --agent`
 - default ignore updates with `--no-update-ignores` for `.mdkg/index/` and `.mdkg/pack/`
+- root-only published init seed config
 - skills indexing and search/show/list support
 - 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
 - product-specific skill mirrors for Codex/OpenAI and Claude
 - shared `AGENT_START.md` startup guidance
 

package/dist/cli.js

@@ -134,7 +134,7 @@ function printIndexHelp(log) {
 }
 function printShowHelp(log) {
     log("Usage:");
-    log("  mdkg show <id-or-qid> [--ws <alias>] [--meta] [--json]");
+    log("  mdkg show <id-or-qid> [--ws <alias>] [--meta] [--json|--xml|--toon|--md]");
     log("\nWhen to use:");
     log("  Inspect one mdkg node exactly. Use `mdkg skill show <slug>` for skills.");
     log("\nDefault behavior:");
@@ -144,7 +144,8 @@ function printShowHelp(log) {
 function printListHelp(log) {
     log("Usage:");
     log("  mdkg list [--type <type>] [--status <status>] [--ws <alias>] [--epic <id>]");
-    log("           [--priority <n>] [--blocked] [--tags <tag,tag,...>] [--tags-mode any|all] [--json]");
+    log("           [--priority <n>] [--blocked] [--tags <tag,tag,...>] [--tags-mode any|all]");
+    log("           [--json|--xml|--toon|--md]");
     log("\nWhen to use:");
     log("  List mdkg nodes. Use `mdkg skill list` for skills.");
     printGlobalOptions(log);
@@ -152,7 +153,7 @@ function printListHelp(log) {
 function printSearchHelp(log) {
     log("Usage:");
     log('  mdkg search "<query>" [--type <type>] [--status <status>] [--ws <alias>]');
-    log("               [--tags <tag,tag,...>] [--tags-mode any|all] [--json]");
+    log("               [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]");
     log("\nWhen to use:");
     log("  Search mdkg nodes by metadata. Use `mdkg skill search` for skills.");
     printGlobalOptions(log);
@@ -210,21 +211,21 @@ function printSkillHelp(log, subcommand) {
             return;
         case "list":
             log("Usage:");
-            log("  mdkg skill list [--tags <tag,tag,...>] [--tags-mode any|all] [--json]");
+            log("  mdkg skill list [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]");
             log("\nWhen to use:");
             log("  Discover skills directly, including stage-tagged orchestrator lookups.");
             printGlobalOptions(log);
             return;
         case "show":
             log("Usage:");
-            log("  mdkg skill show <slug> [--meta] [--json]");
+            log("  mdkg skill show <slug> [--meta] [--json|--xml|--toon|--md]");
             log("\nWhen to use:");
             log("  Inspect one skill body or metadata after discovery.");
             printGlobalOptions(log);
             return;
         case "search":
             log("Usage:");
-            log('  mdkg skill search "<query>" [--tags <tag,tag,...>] [--tags-mode any|all] [--json]');
+            log('  mdkg skill search "<query>" [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]');
             log("\nWhen to use:");
             log("  Search skills by trigger text, tags, and stage conventions like `stage:plan`.");
             printGlobalOptions(log);
@@ -244,9 +245,9 @@ function printSkillHelp(log, subcommand) {
         default:
             log("Usage:");
             log('  mdkg skill new <slug> "<name>" --description "<description>" [options]');
-            log("  mdkg skill list [--tags <tag,tag,...>] [--tags-mode any|all] [--json]");
-            log("  mdkg skill show <slug> [--meta] [--json]");
-            log('  mdkg skill search "<query>" [--tags <tag,tag,...>] [--tags-mode any|all] [--json]');
+            log("  mdkg skill list [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]");
+            log("  mdkg skill show <slug> [--meta] [--json|--xml|--toon|--md]");
+            log('  mdkg skill search "<query>" [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]');
             log("  mdkg skill validate [<slug>]");
             log("  mdkg skill sync [--force]");
             log("\nNotes:");
@@ -528,6 +529,25 @@ function parseTagsModeFlag(value) {
     }
     throw new errors_1.UsageError("--tags-mode must be any or all");
 }
+function parseQueryOutputFormat(parsed) {
+    const enabled = [];
+    if (parseBooleanFlag("--json", parsed.flags["--json"])) {
+        enabled.push("json");
+    }
+    if (parseBooleanFlag("--xml", parsed.flags["--xml"])) {
+        enabled.push("xml");
+    }
+    if (parseBooleanFlag("--toon", parsed.flags["--toon"])) {
+        enabled.push("toon");
+    }
+    if (parseBooleanFlag("--md", parsed.flags["--md"])) {
+        enabled.push("md");
+    }
+    if (enabled.length > 1) {
+        throw new errors_1.UsageError("choose at most one output flag: --json, --xml, --toon, or --md");
+    }
+    return enabled[0];
+}
 function handleCommandError(err, command, runtime) {
     const message = err instanceof Error ? err.message : String(err);
     if (err instanceof errors_1.UsageError) {
@@ -622,12 +642,12 @@ function runSkillSubcommand(parsed, root) {
             const tagsMode = parseTagsModeFlag(parsed.flags["--tags-mode"]);
             const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
             const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
-            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            const format = parseQueryOutputFormat(parsed);
             (0, skill_1.runSkillListCommand)({
                 root,
                 tags,
                 tagsMode,
-                json,
+                format,
                 noCache,
                 noReindex,
             });
@@ -639,14 +659,14 @@ function runSkillSubcommand(parsed, root) {
                 throw new errors_1.UsageError("skill show requires <slug>");
             }
             const metaOnly = parseBooleanFlag("--meta", parsed.flags["--meta"]);
-            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            const format = parseQueryOutputFormat(parsed);
             const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
             const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
             (0, skill_1.runSkillShowCommand)({
                 root,
                 slug,
                 metaOnly,
-                json,
+                format,
                 noCache,
                 noReindex,
             });
@@ -659,7 +679,7 @@ function runSkillSubcommand(parsed, root) {
             const query = parsed.positionals.slice(2).join(" ");
             const tags = parseCsvFlag("--tags", parsed.flags["--tags"]);
             const tagsMode = parseTagsModeFlag(parsed.flags["--tags-mode"]);
-            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            const format = parseQueryOutputFormat(parsed);
             const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
             const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
             (0, skill_1.runSkillSearchCommand)({
@@ -667,7 +687,7 @@ function runSkillSubcommand(parsed, root) {
                 query,
                 tags,
                 tagsMode,
-                json,
+                format,
                 noCache,
                 noReindex,
             });
@@ -930,7 +950,7 @@ function runCommand(parsed, root, runtime) {
             }
             const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
             const metaOnly = parseBooleanFlag("--meta", parsed.flags["--meta"]);
-            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            const format = parseQueryOutputFormat(parsed);
             const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
             const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
             (0, show_1.runShowCommand)({
@@ -938,7 +958,7 @@ function runCommand(parsed, root, runtime) {
                 id,
                 ws,
                 metaOnly,
-                json,
+                format,
                 noCache,
                 noReindex,
             });
@@ -956,7 +976,7 @@ function runCommand(parsed, root, runtime) {
             const blocked = parseBooleanFlag("--blocked", parsed.flags["--blocked"]);
             const tags = parseCsvFlag("--tags", parsed.flags["--tags"]);
             const tagsMode = parseTagsModeFlag(parsed.flags["--tags-mode"]);
-            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            const format = parseQueryOutputFormat(parsed);
             const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
             const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
             (0, list_1.runListCommand)({
@@ -969,7 +989,7 @@ function runCommand(parsed, root, runtime) {
                 blocked,
                 tags,
                 tagsMode,
-                json,
+                format,
                 noCache,
                 noReindex,
             });
@@ -985,7 +1005,7 @@ function runCommand(parsed, root, runtime) {
             const status = requireFlagValue("--status", parsed.flags["--status"]);
             const tags = parseCsvFlag("--tags", parsed.flags["--tags"]);
             const tagsMode = parseTagsModeFlag(parsed.flags["--tags-mode"]);
-            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            const format = parseQueryOutputFormat(parsed);
             const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
             const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
             (0, search_1.runSearchCommand)({
@@ -996,7 +1016,7 @@ function runCommand(parsed, root, runtime) {
                 status,
                 tags,
                 tagsMode,
-                json,
+                format,
                 noCache,
                 noReindex,
             });

package/dist/commands/list.js

@@ -53,13 +53,14 @@ function runListCommand(options) {
         tagsMode: options.tagsMode,
     });
     const sorted = (0, sort_1.sortNodesByQid)(filtered);
-    if (options.json) {
-        (0, query_output_1.writeJson)({
+    const format = options.format ?? (options.json ? "json" : undefined);
+    if (format) {
+        (0, query_output_1.writeStructuredOutput)({
             command: "list",
             kind: "node",
             count: sorted.length,
             items: sorted.map(query_output_1.toNodeSummaryJson),
-        });
+        }, format);
         return;
     }
     (0, query_output_1.writeCount)(sorted.length, sorted.length === 0 ? "no nodes matched current filters" : undefined);

package/dist/commands/query_output.js

@@ -5,6 +5,7 @@ exports.toNodeDetailJson = toNodeDetailJson;
 exports.toSkillSummaryJson = toSkillSummaryJson;
 exports.toSkillDetailJson = toSkillDetailJson;
 exports.writeJson = writeJson;
+exports.writeStructuredOutput = writeStructuredOutput;
 exports.writeCount = writeCount;
 function toNodeSummaryJson(node) {
     return {
@@ -76,6 +77,113 @@ function toSkillDetailJson(skill, body) {
 function writeJson(payload) {
     console.log(JSON.stringify(payload, null, 2));
 }
+function escapeXml(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+function isPrimitive(value) {
+    return (value === null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean");
+}
+function objectToXml(tag, value, indent = "") {
+    if (value === undefined) {
+        return [];
+    }
+    if (Array.isArray(value)) {
+        const lines = [`${indent}<${tag}>`];
+        for (const item of value) {
+            lines.push(...objectToXml("item", item, `${indent}  `));
+        }
+        lines.push(`${indent}</${tag}>`);
+        return lines;
+    }
+    if (isPrimitive(value)) {
+        return [`${indent}<${tag}>${escapeXml(value === null ? "" : String(value))}</${tag}>`];
+    }
+    const lines = [`${indent}<${tag}>`];
+    for (const [key, child] of Object.entries(value)) {
+        lines.push(...objectToXml(key, child, `${indent}  `));
+    }
+    lines.push(`${indent}</${tag}>`);
+    return lines;
+}
+function formatMarkdownScalar(value) {
+    return value === null ? "null" : String(value);
+}
+function objectToMarkdown(value, lines, indent = "", key) {
+    if (value === undefined) {
+        return;
+    }
+    if (Array.isArray(value)) {
+        if (key) {
+            lines.push(`${indent}- ${key}:`);
+        }
+        const childIndent = key ? `${indent}  ` : indent;
+        if (value.length === 0) {
+            lines.push(`${childIndent}- []`);
+            return;
+        }
+        for (const item of value) {
+            if (isPrimitive(item)) {
+                lines.push(`${childIndent}- ${formatMarkdownScalar(item)}`);
+                continue;
+            }
+            lines.push(`${childIndent}-`);
+            objectToMarkdown(item, lines, `${childIndent}  `);
+        }
+        return;
+    }
+    if (isPrimitive(value)) {
+        if (!key) {
+            lines.push(`${indent}- ${formatMarkdownScalar(value)}`);
+            return;
+        }
+        lines.push(`${indent}- ${key}: ${formatMarkdownScalar(value)}`);
+        return;
+    }
+    if (key) {
+        lines.push(`${indent}- ${key}:`);
+    }
+    const childIndent = key ? `${indent}  ` : indent;
+    for (const [childKey, childValue] of Object.entries(value)) {
+        objectToMarkdown(childValue, lines, childIndent, childKey);
+    }
+}
+function writeXml(payload) {
+    const lines = ['<?xml version="1.0" encoding="UTF-8"?>'];
+    lines.push(...objectToXml("response", payload));
+    console.log(lines.join("\n"));
+}
+function writeToon(payload) {
+    console.log(JSON.stringify(payload, null, 2));
+}
+function writeMarkdown(payload) {
+    const lines = ["# mdkg response"];
+    objectToMarkdown(payload, lines);
+    console.log(lines.join("\n"));
+}
+function writeStructuredOutput(payload, format) {
+    switch (format) {
+        case "json":
+            writeJson(payload);
+            return;
+        case "xml":
+            writeXml(payload);
+            return;
+        case "toon":
+            writeToon(payload);
+            return;
+        case "md":
+            writeMarkdown(payload);
+            return;
+    }
+}
 function writeCount(count, note) {
     console.error(`count: ${count}`);
     if (note) {

package/dist/commands/search.js

@@ -71,13 +71,14 @@ function runSearchCommand(options) {
         tagsMode: options.tagsMode,
     }).filter((node) => matchesQuery(node, terms));
     const sorted = (0, sort_1.sortNodesByQid)(nodeResults);
-    if (options.json) {
-        (0, query_output_1.writeJson)({
+    const format = options.format ?? (options.json ? "json" : undefined);
+    if (format) {
+        (0, query_output_1.writeStructuredOutput)({
             command: "search",
             kind: "node",
             count: sorted.length,
             items: sorted.map(query_output_1.toNodeSummaryJson),
-        });
+        }, format);
         return;
     }
     (0, query_output_1.writeCount)(sorted.length, sorted.length === 0 ? `no nodes matched query "${query}"` : undefined);

package/dist/commands/show.js

@@ -58,12 +58,13 @@ function runShowCommand(options) {
         const content = fs_1.default.readFileSync(filePath, "utf8");
         body = (0, frontmatter_1.parseFrontmatter)(content, filePath).body.trimEnd();
     }
-    if (options.json) {
-        (0, query_output_1.writeJson)({
+    const format = options.format ?? (options.json ? "json" : undefined);
+    if (format) {
+        (0, query_output_1.writeStructuredOutput)({
             command: "show",
             kind: "node",
             item: (0, query_output_1.toNodeDetailJson)(node, options.metaOnly ? undefined : body),
-        });
+        }, format);
         return;
     }
     const lines = [];

package/dist/commands/skill.js

@@ -205,13 +205,14 @@ function runSkillListCommand(options) {
         console.error("warning: skills index is stale; run mdkg index to refresh");
     }
     const skills = filterSkills(Object.values(index.skills), options.tags, options.tagsMode ?? "any").sort((a, b) => a.qid.localeCompare(b.qid));
-    if (options.json) {
-        (0, query_output_1.writeJson)({
+    const format = options.format ?? (options.json ? "json" : undefined);
+    if (format) {
+        (0, query_output_1.writeStructuredOutput)({
             command: "list",
             kind: "skill",
             count: skills.length,
             items: skills.map(query_output_1.toSkillSummaryJson),
-        });
+        }, format);
         return;
     }
     (0, query_output_1.writeCount)(skills.length, skills.length === 0 ? "no skills matched current filters" : undefined);
@@ -243,12 +244,13 @@ function runSkillShowCommand(options) {
         }
         body = fs_1.default.readFileSync(skillPath, "utf8").trimEnd();
     }
-    if (options.json) {
-        (0, query_output_1.writeJson)({
+    const format = options.format ?? (options.json ? "json" : undefined);
+    if (format) {
+        (0, query_output_1.writeStructuredOutput)({
             command: "show",
             kind: "skill",
             item: (0, query_output_1.toSkillDetailJson)(skill, options.metaOnly ? undefined : body),
-        });
+        }, format);
         return;
     }
     if (options.metaOnly) {
@@ -307,13 +309,14 @@ function runSkillSearchCommand(options) {
     const skills = filterSkills(Object.values(index.skills), options.tags, options.tagsMode ?? "any")
         .filter((skill) => matchesSkillQuery(skill, terms))
         .sort((a, b) => a.qid.localeCompare(b.qid));
-    if (options.json) {
-        (0, query_output_1.writeJson)({
+    const format = options.format ?? (options.json ? "json" : undefined);
+    if (format) {
+        (0, query_output_1.writeStructuredOutput)({
             command: "search",
             kind: "skill",
             count: skills.length,
             items: skills.map(query_output_1.toSkillSummaryJson),
-        });
+        }, format);
         return;
     }
     (0, query_output_1.writeCount)(skills.length, skills.length === 0 ? `no skills matched query "${query}"` : undefined);

package/dist/init/AGENT_START.md

@@ -45,3 +45,9 @@ Conventions:
 - Prefer checkpoints for feat/epic closeout summaries; parent status edits remain manual.
 - If `events.jsonl` is missing, `mdkg task start` and `mdkg task done` will remind you how to recreate it.
 - Files outside mdkg-managed skill mirrors, such as local tool permission files, are not managed by mdkg unless documented explicitly.
+
+Structured discovery/show exports:
+- `--json`
+- `--xml`
+- `--toon`
+- `--md`

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -21,9 +21,16 @@ Agent bootstrap:
 - `mdkg init --llm`
 - `mdkg init --agent`
 - `mdkg init --llm --agent`
+- published bootstrap config is root-only by default
 
 Skill discovery:
 - `mdkg skill list --tags stage:plan --json`
 - `mdkg skill search "<query>" --json`
 - `mdkg skill show <slug> --json`
 - `mdkg skill sync`
+
+Discovery/show export flags:
+- `--json`
+- `--xml`
+- `--toon`
+- `--md`

package/dist/init/config.json

@@ -52,16 +52,6 @@
       "path": ".",
       "enabled": true,
       "mdkg_dir": ".mdkg"
-    },
-    "polish": {
-      "path": "polish",
-      "enabled": true,
-      "mdkg_dir": ".mdkg"
-    },
-    "smoke": {
-      "path": "smoke",
-      "enabled": true,
-      "mdkg_dir": ".mdkg"
     }
   }
-}
+}

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

@@ -88,7 +88,7 @@ If a user provides an unqualified ID and it is ambiguous globally:
 - Commands should be script-friendly:
   - concise outputs for single items
   - predictable formatting
-  - `--json` output for supported discovery/show commands
+  - `--json`, `--xml`, `--toon`, and `--md` output for supported discovery/show commands
   - when printing node summaries (e.g., `show`/list results), outputs SHOULD surface key searchable frontmatter fields such as `links` and `artifacts`
 
 ## Command set (v1 target)
@@ -164,18 +164,19 @@ Common flags:
 - `--template <set>` (default from config)
 
 ### Read/search
-- `mdkg show <id-or-qid> [--meta] [--json]`
+- `mdkg show <id-or-qid> [--meta] [--json|--xml|--toon|--md]`
   - default behavior shows the full node body
   - `--meta` is the compact card-only view
-- `mdkg search "<query>" [--type <type>] [--status <status>] [--ws <alias>] [--tags <tag,tag,...>] [--tags-mode any|all] [--json]`
+- `mdkg search "<query>" [--type <type>] [--status <status>] [--ws <alias>] [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]`
   - search SHOULD match on IDs, titles, tags, path tokens, and searchable frontmatter lists (`links`, `artifacts`, `refs`, `aliases`)
-- `mdkg list [--type <type>] [--status <status>] [--ws <alias>] [--epic <id>] [--blocked] [--priority <n>] [--tags <tag,tag,...>] [--tags-mode any|all] [--json]`
+- `mdkg list [--type <type>] [--status <status>] [--ws <alias>] [--epic <id>] [--blocked] [--priority <n>] [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]`
 - skills are first-class under `mdkg skill ...` only:
-  - `mdkg skill list [--tags <tag,tag,...>] [--tags-mode any|all] [--json]`
-  - `mdkg skill show <slug> [--meta] [--json]`
-  - `mdkg skill search "<query>" [--tags <tag,tag,...>] [--tags-mode any|all] [--json]`
+  - `mdkg skill list [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]`
+  - `mdkg skill show <slug> [--meta] [--json|--xml|--toon|--md]`
+  - `mdkg skill search "<query>" [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]`
   - `mdkg skill validate [<slug>]`
   - `mdkg skill sync [--force]`
+- discovery/show output flags are mutually exclusive; text mode remains the default when none are supplied
 
 ### Task lifecycle mutation
 - `mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"]`

package/dist/init/llms.txt

@@ -15,3 +15,5 @@ First commands:
 - `mdkg pack <id>`
 - `mdkg skill list --tags stage:plan --json`
 - `mdkg validate`
+
+Discovery and show commands also support `--xml`, `--toon`, and `--md` when JSON is not the desired interchange format.

package/dist/util/argparse.js

@@ -79,6 +79,9 @@ const BOOLEAN_FLAGS = new Set([
     "--version",
     "--dry-run",
     "--json",
+    "--xml",
+    "--toon",
+    "--md",
     "--list-profiles",
     "--with-scripts",
     "--clear-blocked-by",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdkg",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Markdown Knowledge Graph",
   "license": "MIT",
   "bin": {