mdkg 0.0.3 → 0.0.4

package/dist/cli.js

@@ -4,6 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCli = runCli;
+exports.main = main;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const argparse_1 = require("./util/argparse");
@@ -20,251 +22,391 @@ const checkpoint_1 = require("./commands/checkpoint");
 const init_1 = require("./commands/init");
 const new_1 = require("./commands/new");
 const guide_1 = require("./commands/guide");
+const event_1 = require("./commands/event");
+const skill_1 = require("./commands/skill");
+const task_1 = require("./commands/task");
 const workspace_1 = require("./commands/workspace");
 const profile_1 = require("./pack/profile");
 const errors_1 = require("./util/errors");
-function printGlobalOptions() {
-    console.log("\nGlobal options:");
-    console.log("  --root, -r <path>   Run against a specific repo root");
-    console.log("  --help, -h          Show help");
-    console.log("  --version, -V       Show version");
-    console.log("  --no-cache          Bypass reading the index cache");
-    console.log("  --no-reindex        Do not auto rebuild when cache is stale");
-}
-function printUsage() {
-    console.log("mdkg - Markdown Knowledge Graph");
-    console.log("\nUsage:");
-    console.log("  mdkg <command> [options]");
-    console.log("\nCommands:");
-    console.log("  init        Initialize .mdkg scaffolding");
-    console.log("  guide       Show the mdkg guide");
-    console.log("  new         Create a node from templates");
-    console.log("  workspace   Manage workspaces (ls/add/rm)");
-    console.log("  index       Build the global index");
-    console.log("  show        Show a node by id or qid");
-    console.log("  list        List nodes with filters");
-    console.log("  search      Search nodes by query");
-    console.log("  pack        Generate a context pack");
-    console.log("  next        Suggest the next work item");
-    console.log("  checkpoint  Create a checkpoint node");
-    console.log("  validate    Validate frontmatter + graph");
-    console.log("  format      Normalize frontmatter");
-    console.log("  doctor      Run install and workspace diagnostics");
-    console.log("\nQuickstart:");
-    console.log("  mdkg init --llm --update-gitignore --update-npmignore");
-    console.log("  mdkg index");
-    console.log('  mdkg new task "..." --status todo --priority 1');
-    console.log("  mdkg list --status todo");
-    console.log("  mdkg pack <id> --verbose");
-    console.log("  mdkg pack <id> --pack-profile concise --dry-run --stats");
-    console.log("  mdkg validate");
-    console.log("\nRun `mdkg help <command>` or `mdkg <command> --help` for details.");
-    printGlobalOptions();
-}
-function printInitHelp() {
-    console.log("Usage:");
-    console.log("  mdkg init [options]");
-    console.log("\nOptions:");
-    console.log("  --force               Overwrite existing mdkg files");
-    console.log("  --agents              Create AGENTS.md");
-    console.log("  --claude              Create CLAUDE.md");
-    console.log("  --llm                 Create AGENTS.md and CLAUDE.md");
-    console.log("  --update-gitignore    Append mdkg ignore entries");
-    console.log("  --update-npmignore    Append mdkg ignore entries");
-    console.log("  --update-dockerignore Append mdkg ignore entries");
-    printGlobalOptions();
-}
-function printNewHelp() {
-    console.log("Usage:");
-    console.log('  mdkg new <type> "<title>" [options]');
-    console.log("\nTypes:");
-    console.log("  rule prd edd dec prop epic feat task bug checkpoint test");
-    console.log("\nOptions:");
-    console.log("  --ws <alias>               Workspace alias (default root)");
-    console.log("  --status <status>          Work item or decision status");
-    console.log("  --priority <0..9>          Work item priority");
-    console.log("  --epic <id>                Epic id");
-    console.log("  --parent <id>              Parent id");
-    console.log("  --prev <id>                Previous id");
-    console.log("  --next <id>                Next id");
-    console.log("  --relates <id,id,...>      Related ids");
-    console.log("  --blocked-by <id,id,...>   Blockers");
-    console.log("  --blocks <id,id,...>       Blocked items");
-    console.log("  --links <ref,ref,...>      Link refs");
-    console.log("  --artifacts <ref,ref,...>  Artifact refs");
-    console.log("  --refs <id,id,...>         Non-edge refs");
-    console.log("  --aliases <text,text,...>  Search aliases");
-    console.log("  --cases <id,id,...>        Test case ids");
-    console.log("  --tags <tag,tag,...>       Tags");
-    console.log("  --owners <owner,owner,...> Owners");
-    console.log("  --supersedes <dec-id>      Decision supersedes");
-    console.log("  --template <set>           Template set");
-    printGlobalOptions();
-}
-function printGuideHelp() {
-    console.log("Usage:");
-    console.log("  mdkg guide");
-    printGlobalOptions();
-}
-function printWorkspaceHelp() {
-    console.log("Usage:");
-    console.log("  mdkg workspace ls");
-    console.log("  mdkg workspace add <alias> <path> [--mdkg-dir <dir>]");
-    console.log("  mdkg workspace rm <alias>");
-    printGlobalOptions();
-}
-function printIndexHelp() {
-    console.log("Usage:");
-    console.log("  mdkg index [--tolerant]");
-    printGlobalOptions();
-}
-function printShowHelp() {
-    console.log("Usage:");
-    console.log("  mdkg show <id-or-qid> [--ws <alias>] [--body]");
-    printGlobalOptions();
-}
-function printListHelp() {
-    console.log("Usage:");
-    console.log("  mdkg list [--type <type>] [--status <status>] [--ws <alias>] [--epic <id>]");
-    console.log("           [--priority <n>] [--blocked]");
-    printGlobalOptions();
-}
-function printSearchHelp() {
-    console.log("Usage:");
-    console.log('  mdkg search "<query>" [--type <type>] [--status <status>] [--ws <alias>]');
-    printGlobalOptions();
-}
-function printPackHelp() {
-    console.log("Usage:");
-    console.log("  mdkg pack <id-or-qid> [options]");
-    console.log("  mdkg pack --list-profiles");
-    console.log("\nOptions:");
-    console.log("  -d, --depth <n>              Traversal depth (default from config pack.default_depth)");
-    console.log("  -e, --edges <keys>           Extra edges: parent,epic,relates,blocked_by,blocks,prev,next");
-    console.log("  -v, --verbose                Include pinned core docs from .mdkg/core/core.md (standard profile only)");
-    console.log("  -f, --format <fmt>           Output format: md|json|toon|xml (default md)");
-    console.log("  -o, --out <path>             Output file path (default .mdkg/pack/pack_<kind>_<id>_<ts>.<ext>)");
-    console.log("  -w, --ws <alias>             Workspace hint when resolving ambiguous ids");
-    console.log("      --pack-profile <name>    Built-in body profile: standard|concise|headers (default standard)");
-    console.log("      --concise                Shorthand for --pack-profile concise");
-    console.log("      --strip-code             Remove fenced code blocks from shaped body content");
-    console.log("      --max-code-lines <n>     Keep at most n lines per fenced code block");
-    console.log("      --max-chars <n>          Hard cap on shaped pack characters");
-    console.log("      --max-lines <n>          Hard cap on shaped pack lines");
-    console.log("      --max-tokens <n>         Hard cap on shaped pack token estimate (~chars/4)");
-    console.log("      --dry-run                Preview selection/order/stats without writing files");
-    console.log("      --truncation-report <p>  Write truncation report JSON (default <out>.truncation.json when needed)");
-    console.log("      --stats                  Print per-node + total pack stats and write stats sidecar JSON");
-    console.log("      --stats-out <path>       Write stats JSON to explicit path");
-    console.log("      --list-profiles          List built-in pack profiles and exit");
-    console.log("\nExamples:");
-    console.log("  mdkg pack --list-profiles");
-    console.log("  mdkg pack task-1 -v");
-    console.log("  mdkg pack task-1 --pack-profile concise --max-tokens 12000 --stats");
-    console.log("  mdkg pack task-1 --pack-profile concise --dry-run");
-    console.log("  mdkg pack epic-2 --format json --max-chars 50000 --truncation-report .mdkg/pack/epic-2.truncation.json");
-    printGlobalOptions();
-}
-function printPackProfiles() {
+function resolveRuntime(runtime = {}) {
+    return {
+        log: runtime.log ?? console.log,
+        error: runtime.error ?? console.error,
+        cwd: runtime.cwd ?? (() => process.cwd()),
+    };
+}
+function printGlobalOptions(log) {
+    log("\nGlobal options:");
+    log("  --root, -r <path>   Run against a specific repo root");
+    log("  --help, -h          Show help");
+    log("  --version, -V       Show version");
+}
+function printUsage(log) {
+    log("mdkg - Markdown Knowledge Graph");
+    log("\nUsage:");
+    log("  mdkg <command> [options]");
+    log("\nPrimary commands:");
+    log("  init        Initialize .mdkg scaffolding");
+    log("  new         Create a node from templates");
+    log("  show        Show a node by id or qid");
+    log("  list        List nodes with filters");
+    log("  search      Search nodes by query");
+    log("  pack        Generate a context pack");
+    log("  skill       Create, list, show, search, and validate skills");
+    log("  task        Start, update, and complete task-like nodes");
+    log("  next        Suggest the next work item");
+    log("  validate    Validate frontmatter + graph");
+    log("\nAdvanced / maintenance commands:");
+    log("  event       Enable or append episodic event logs");
+    log("  checkpoint  Create a checkpoint node");
+    log("  index       Build the global index");
+    log("  guide       Show the mdkg guide");
+    log("  format      Normalize frontmatter");
+    log("  doctor      Run install and workspace diagnostics");
+    log("  workspace   Manage workspaces (ls/add/rm)");
+    log("\nQuickstart:");
+    log("  mdkg init --llm");
+    log('  mdkg new task "..." --status todo --priority 1');
+    log('  mdkg search "..."');
+    log("  mdkg show <id>");
+    log("  mdkg next");
+    log("  mdkg pack <id>");
+    log("  mdkg pack <id> --profile concise --dry-run --stats");
+    log("  mdkg task start <id>");
+    log('  mdkg skill new release-readiness "release readiness audit" --description "use when preparing a release"');
+    log("  mdkg skill list --tags stage:plan --json");
+    log("  mdkg validate");
+    log("\nOptional agent-ready bootstrap:");
+    log("  mdkg init --omni");
+    log("\nRun `mdkg help <command>` or `mdkg <command> --help` for details.");
+    printGlobalOptions(log);
+}
+function printInitHelp(log) {
+    log("Usage:");
+    log("  mdkg init [options]");
+    log("\nOptions:");
+    log("  --force               Overwrite existing mdkg files");
+    log("  --llm                 Create AGENTS.md and CLAUDE.md");
+    log("  --omni                Add SOUL/HUMAN/skills/events scaffolding");
+    log("  --no-update-ignores   Skip default .gitignore/.npmignore updates");
+    log("  --update-gitignore    Append mdkg ignore entries");
+    log("  --update-npmignore    Append mdkg ignore entries");
+    log("  --update-dockerignore Append mdkg ignore entries");
+    log("\nCompatibility flags still supported but not shown in the primary onboarding story.");
+    printGlobalOptions(log);
+}
+function printNewHelp(log) {
+    log("Usage:");
+    log('  mdkg new <type> "<title>" [options]');
+    log("\nTypes:");
+    log("  rule prd edd dec prop epic feat task bug checkpoint test");
+    log("\nOptions:");
+    log("  --ws <alias>               Workspace alias (default root)");
+    log("  --status <status>          Work item or decision status");
+    log("  --priority <0..9>          Work item priority");
+    log("  --epic <id>                Epic id");
+    log("  --tags <tag,tag,...>       Tags");
+    log("  --skills <slug,slug,...>   Skill slugs for work items");
+    log("  --template <set>           Template set");
+    log("  --run-id <id>              Optional event run id when event logging is enabled");
+    log("\nAdvanced metadata flags:");
+    log("  --parent --prev --next --relates --blocked-by --blocks");
+    log("  --links --artifacts --refs --aliases --owners --cases --supersedes");
+    log("  --owners <owner,owner,...> Owners");
+    printGlobalOptions(log);
+}
+function printGuideHelp(log) {
+    log("Usage:");
+    log("  mdkg guide");
+    printGlobalOptions(log);
+}
+function printWorkspaceHelp(log) {
+    log("Usage:");
+    log("  mdkg workspace ls");
+    log("  mdkg workspace add <alias> <path> [--mdkg-dir <dir>]");
+    log("  mdkg workspace rm <alias>");
+    printGlobalOptions(log);
+}
+function printIndexHelp(log) {
+    log("Usage:");
+    log("  mdkg index [--tolerant]");
+    printGlobalOptions(log);
+}
+function printShowHelp(log) {
+    log("Usage:");
+    log("  mdkg show <id-or-qid> [--ws <alias>] [--meta] [--json]");
+    log("\nWhen to use:");
+    log("  Inspect one mdkg node exactly. Use `mdkg skill show <slug>` for skills.");
+    log("\nDefault behavior:");
+    log("  Shows full body content. Use --meta for card + metadata only.");
+    printGlobalOptions(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("\nWhen to use:");
+    log("  List mdkg nodes. Use `mdkg skill list` for skills.");
+    printGlobalOptions(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("\nWhen to use:");
+    log("  Search mdkg nodes by metadata. Use `mdkg skill search` for skills.");
+    printGlobalOptions(log);
+}
+function printPackHelp(log) {
+    log("Usage:");
+    log("  mdkg pack <id-or-qid> [options]");
+    log("  mdkg pack --list-profiles");
+    log("\nOptions:");
+    log("  -w, --ws <alias>             Workspace hint when resolving ambiguous ids");
+    log("  -v, --verbose                Include pinned core docs from .mdkg/core/core.md");
+    log("  -f, --format <fmt>           Output format: md|json|toon|xml (default md)");
+    log("  -o, --out <path>             Output file path");
+    log("      --profile <name>         Body profile: standard|concise|headers (default standard)");
+    log("      --skills <mode>          Skill inclusion: none|auto|<slug,slug,...> (default auto)");
+    log("      --skills-depth <mode>    Skill body mode: meta|full (default meta)");
+    log("      --dry-run                Preview selection/order/stats without writing files");
+    log("      --stats                  Print per-node + total pack stats and write stats sidecar JSON");
+    log("      --list-profiles          List built-in pack profiles and exit");
+    log("\nAdvanced shaping / debug flags:");
+    log("  --depth --edges --strip-code --max-code-lines --max-chars --max-lines --max-tokens");
+    log("  --truncation-report --stats-out");
+    log("\nExamples:");
+    log("  mdkg pack --list-profiles");
+    log("  mdkg pack task-1");
+    log("  mdkg pack task-1 --profile concise --dry-run --stats");
+    log("  mdkg pack task-1 --skills auto --skills-depth full");
+    log("  mdkg pack epic-2 --format json --profile headers");
+    printGlobalOptions(log);
+}
+function printPackProfiles(log) {
     const profiles = (0, profile_1.listPackProfiles)();
-    console.log("Built-in pack profiles:");
+    log("Built-in pack profiles:");
     for (const entry of profiles) {
-        console.log(`- ${entry.profile} (body=${entry.bodyMode})`);
-        console.log(`  ${entry.description}`);
+        log(`- ${entry.profile} (body=${entry.bodyMode})`);
+        log(`  ${entry.description}`);
         if (entry.defaults.length > 0) {
-            console.log(`  defaults: ${entry.defaults.join(", ")}`);
+            log(`  defaults: ${entry.defaults.join(", ")}`);
         }
     }
 }
-function printNextHelp() {
-    console.log("Usage:");
-    console.log("  mdkg next [<id-or-qid>] [--ws <alias>]");
-    printGlobalOptions();
-}
-function printCheckpointHelp() {
-    console.log("Usage:");
-    console.log("  mdkg checkpoint new <title> [--ws <alias>]");
-    console.log("        [--relates <id,id,...>] [--scope <id,id,...>]");
-    printGlobalOptions();
-}
-function printValidateHelp() {
-    console.log("Usage:");
-    console.log("  mdkg validate [--out <path>] [--quiet]");
-    printGlobalOptions();
-}
-function printFormatHelp() {
-    console.log("Usage:");
-    console.log("  mdkg format");
-    printGlobalOptions();
-}
-function printDoctorHelp() {
-    console.log("Usage:");
-    console.log("  mdkg doctor [--json]");
-    console.log("\nChecks:");
-    console.log("  - Node.js version compatibility");
-    console.log("  - mdkg repo root + .mdkg/config.json");
-    console.log("  - Template schema availability");
-    console.log("  - Index load/rebuild health");
-    console.log("\nOptions:");
-    console.log("  --json                Emit machine-readable JSON output");
-    printGlobalOptions();
-}
-function printCommandHelp(command) {
+function printSkillHelp(log, subcommand) {
+    switch ((subcommand ?? "").toLowerCase()) {
+        case "new":
+            log("Usage:");
+            log('  mdkg skill new <slug> "<name>" --description "<description>" [options]');
+            log("\nOptions:");
+            log("  --tags <tag,tag,...>         Optional skill tags");
+            log("  --authors <name,name,...>    Optional authors list");
+            log("  --links <url,url,...>        Optional links list");
+            log("  --run-id <id>                Optional event run id when event logging is enabled");
+            log("  --with-scripts               Create scripts/ in the scaffold");
+            log("  --force                      Overwrite existing SKILL.md");
+            printGlobalOptions(log);
+            return;
+        case "list":
+            log("Usage:");
+            log("  mdkg skill list [--tags <tag,tag,...>] [--tags-mode any|all] [--json]");
+            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("\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("\nWhen to use:");
+            log("  Search skills by trigger text, tags, and stage conventions like `stage:plan`.");
+            printGlobalOptions(log);
+            return;
+        case "validate":
+            log("Usage:");
+            log("  mdkg skill validate [<slug>]");
+            printGlobalOptions(log);
+            return;
+        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 validate [<slug>]");
+            log("\nNotes:");
+            log("  Skills are first-class under `mdkg skill ...`.");
+            log("  Use stage tags like `stage:plan`, `stage:execute`, and `stage:review` with --tags.");
+            printGlobalOptions(log);
+    }
+}
+function printTaskHelp(log, subcommand) {
+    switch ((subcommand ?? "").toLowerCase()) {
+        case "start":
+            log("Usage:");
+            log('  mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"]');
+            log("\nWhen to use:");
+            log("  Move a task, bug, or test into progress and emit a baseline event when logging is enabled.");
+            printGlobalOptions(log);
+            return;
+        case "update":
+            log("Usage:");
+            log("  mdkg task update <id-or-qid> [--ws <alias>] [--status <status>] [--priority <n>]");
+            log("                   [--add-artifacts <a,...>] [--add-links <l,...>] [--add-refs <id,...>]");
+            log("                   [--add-skills <slug,...>] [--add-tags <tag,...>] [--add-blocked-by <id,...>]");
+            log('                   [--clear-blocked-by] [--run-id <id>] [--note "<text>"]');
+            log("\nWhen to use:");
+            log("  Update task metadata and evidence without editing markdown manually.");
+            printGlobalOptions(log);
+            return;
+        case "done":
+            log("Usage:");
+            log('  mdkg task done <id-or-qid> [--ws <alias>] [--add-artifacts <a,...>] [--add-links <l,...>]');
+            log('                 [--add-refs <id,...>] [--checkpoint "<title>"] [--run-id <id>] [--note "<text>"]');
+            log("\nWhen to use:");
+            log("  Mark a task-like node done, optionally create a checkpoint, and emit a completion event when enabled.");
+            printGlobalOptions(log);
+            return;
+        default:
+            log("Usage:");
+            log('  mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"]');
+            log("  mdkg task update <id-or-qid> [options]");
+            log('  mdkg task done <id-or-qid> [--checkpoint "<title>"] [options]');
+            log("\nNotes:");
+            log("  `mdkg task ...` only supports task, bug, and test nodes in this wave.");
+            printGlobalOptions(log);
+    }
+}
+function printEventHelp(log, subcommand) {
+    switch ((subcommand ?? "").toLowerCase()) {
+        case "enable":
+            log("Usage:");
+            log("  mdkg event enable [--ws <alias>] [--no-update-gitignore]");
+            log("\nWhen to use:");
+            log("  Create the append-only JSONL event log for a workspace.");
+            printGlobalOptions(log);
+            return;
+        case "append":
+            log("Usage:");
+            log("  mdkg event append --kind <kind> --status <ok|error|retry|skipped> --refs <id,...>");
+            log('                    [--ws <alias>] [--artifacts <a,...>] [--notes "<text>"] [--run-id <id>]');
+            log("                    [--agent <name>] [--skill <slug>] [--tool <id>]");
+            log("\nWhen to use:");
+            log("  Append explicit provenance events from an orchestrator or manual workflow.");
+            printGlobalOptions(log);
+            return;
+        default:
+            log("Usage:");
+            log("  mdkg event enable [--ws <alias>] [--no-update-gitignore]");
+            log("  mdkg event append --kind <kind> --status <ok|error|retry|skipped> --refs <id,...> [options]");
+            printGlobalOptions(log);
+    }
+}
+function printNextHelp(log) {
+    log("Usage:");
+    log("  mdkg next [<id-or-qid>] [--ws <alias>]");
+    printGlobalOptions(log);
+}
+function printCheckpointHelp(log) {
+    log("Usage:");
+    log("  mdkg checkpoint new <title> [--ws <alias>]");
+    log('        [--relates <id,id,...>] [--scope <id,id,...>] [--run-id <id>] [--note "<text>"]');
+    printGlobalOptions(log);
+}
+function printValidateHelp(log) {
+    log("Usage:");
+    log("  mdkg validate [--out <path>] [--quiet]");
+    printGlobalOptions(log);
+}
+function printFormatHelp(log) {
+    log("Usage:");
+    log("  mdkg format");
+    printGlobalOptions(log);
+}
+function printDoctorHelp(log) {
+    log("Usage:");
+    log("  mdkg doctor [--json]");
+    log("\nChecks:");
+    log("  - Node.js version compatibility");
+    log("  - mdkg repo root + .mdkg/config.json");
+    log("  - Template schema availability");
+    log("  - Index load/rebuild health");
+    log("\nOptions:");
+    log("  --json                Emit machine-readable JSON output");
+    printGlobalOptions(log);
+}
+function printCommandHelp(log, command, subcommand) {
     switch ((command ?? "").toLowerCase()) {
         case "":
         case "help":
-            printUsage();
+            printUsage(log);
             return;
         case "init":
-            printInitHelp();
+            printInitHelp(log);
             return;
         case "guide":
-            printGuideHelp();
+            printGuideHelp(log);
             return;
         case "new":
-            printNewHelp();
+            printNewHelp(log);
             return;
         case "workspace":
-            printWorkspaceHelp();
+            printWorkspaceHelp(log);
             return;
         case "index":
-            printIndexHelp();
+            printIndexHelp(log);
             return;
         case "show":
-            printShowHelp();
+            printShowHelp(log);
             return;
         case "list":
-            printListHelp();
+            printListHelp(log);
             return;
         case "search":
-            printSearchHelp();
+            printSearchHelp(log);
             return;
         case "pack":
-            printPackHelp();
+            printPackHelp(log);
+            return;
+        case "skill":
+            printSkillHelp(log, subcommand);
+            return;
+        case "task":
+            printTaskHelp(log, subcommand);
+            return;
+        case "event":
+            printEventHelp(log, subcommand);
             return;
         case "next":
-            printNextHelp();
+            printNextHelp(log);
             return;
         case "checkpoint":
-            printCheckpointHelp();
+            printCheckpointHelp(log);
             return;
         case "validate":
-            printValidateHelp();
+            printValidateHelp(log);
             return;
         case "format":
-            printFormatHelp();
+            printFormatHelp(log);
             return;
         case "doctor":
-            printDoctorHelp();
+            printDoctorHelp(log);
             return;
         default:
-            printUsage();
+            printUsage(log);
     }
 }
-function printRootError(root) {
-    console.error("mdkg must be run from a repo root with .mdkg/config.json");
-    console.error(`root checked: ${root}`);
-    console.error("hint: run from the repo root, pass --root <path>, or run `mdkg init`");
+function printRootError(error, root) {
+    error("mdkg must be run from a repo root with .mdkg/config.json");
+    error(`root checked: ${root}`);
+    error("hint: run from the repo root, pass --root <path>, or run `mdkg init`");
 }
 function readPackageVersion() {
     const packagePath = path_1.default.resolve(__dirname, "..", "package.json");
@@ -349,462 +491,676 @@ function parseEdgesFlag(value) {
         .filter(Boolean);
     return raw.length > 0 ? raw : undefined;
 }
-function inferCommandFromArgv() {
-    const raw = process.argv[2];
-    if (!raw || raw.startsWith("-")) {
+function parseCsvFlag(flag, value) {
+    if (value === undefined) {
         return undefined;
     }
-    return raw.toLowerCase();
+    if (value === true) {
+        throw new errors_1.UsageError(`${flag} requires a value`);
+    }
+    const items = String(value)
+        .split(",")
+        .map((item) => item.trim().toLowerCase())
+        .filter(Boolean);
+    return items.length > 0 ? items : undefined;
+}
+function parseTagsModeFlag(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === true) {
+        throw new errors_1.UsageError("--tags-mode requires a value");
+    }
+    const normalized = String(value).toLowerCase();
+    if (normalized === "any" || normalized === "all") {
+        return normalized;
+    }
+    throw new errors_1.UsageError("--tags-mode must be any or all");
 }
-function handleCommandError(err) {
+function handleCommandError(err, command, runtime) {
     const message = err instanceof Error ? err.message : String(err);
     if (err instanceof errors_1.UsageError) {
-        console.error(message);
-        printCommandHelp(inferCommandFromArgv());
-        process.exit(1);
+        runtime.error(message);
+        printCommandHelp(runtime.log, command);
+        return 1;
     }
     if (err instanceof errors_1.ValidationError) {
-        console.error(message);
-        process.exit(2);
+        runtime.error(message);
+        return 2;
     }
     if (err instanceof errors_1.NotFoundError) {
-        console.error(message);
-        process.exit(3);
+        runtime.error(message);
+        return 3;
     }
-    console.error(message);
-    process.exit(4);
+    runtime.error(message);
+    return 4;
 }
-function main() {
-    const parsed = (0, argparse_1.parseArgs)(process.argv.slice(2));
-    if (parsed.error) {
-        console.error(parsed.error);
-        printUsage();
-        process.exit(1);
-    }
-    if (parsed.help) {
-        printCommandHelp(parsed.positionals[0]);
-        process.exit(0);
-    }
-    if (parsed.version) {
-        console.log(readPackageVersion());
-        process.exit(0);
+function runWorkspaceSubcommand(parsed, root) {
+    const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
+    switch (subcommand) {
+        case "ls": {
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("workspace ls takes no arguments");
+            }
+            (0, workspace_1.runWorkspaceListCommand)({ root });
+            return 0;
+        }
+        case "add": {
+            const alias = parsed.positionals[2];
+            const workspacePath = parsed.positionals[3];
+            if (!alias || !workspacePath) {
+                throw new errors_1.UsageError("workspace add requires <alias> <path>");
+            }
+            const mdkgDir = requireFlagValue("--mdkg-dir", parsed.flags["--mdkg-dir"]);
+            (0, workspace_1.runWorkspaceAddCommand)({ root, alias, workspacePath, mdkgDir });
+            return 0;
+        }
+        case "rm": {
+            const alias = parsed.positionals[2];
+            if (!alias || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("workspace rm requires <alias>");
+            }
+            (0, workspace_1.runWorkspaceRemoveCommand)({ root, alias });
+            return 0;
+        }
+        default:
+            throw new errors_1.UsageError("workspace requires ls/add/rm");
     }
-    const command = (parsed.positionals[0] ?? "").toLowerCase();
-    if (!command) {
-        printUsage();
-        process.exit(0);
+}
+function runSkillSubcommand(parsed, root) {
+    const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
+    switch (subcommand) {
+        case "new": {
+            const slug = parsed.positionals[2];
+            const name = parsed.positionals[3];
+            if (!slug || !name) {
+                throw new errors_1.UsageError('skill new requires <slug> "<name>"');
+            }
+            if (parsed.positionals.length > 4) {
+                throw new errors_1.UsageError('skill new accepts exactly <slug> "<name>"');
+            }
+            const description = requireFlagValue("--description", parsed.flags["--description"]);
+            if (!description) {
+                throw new errors_1.UsageError("skill new requires --description");
+            }
+            const tags = requireFlagValue("--tags", parsed.flags["--tags"]);
+            const authors = requireFlagValue("--authors", parsed.flags["--authors"]);
+            const links = requireFlagValue("--links", parsed.flags["--links"]);
+            const withScripts = parseBooleanFlag("--with-scripts", parsed.flags["--with-scripts"]);
+            const force = parseBooleanFlag("--force", parsed.flags["--force"]);
+            const runId = requireFlagValue("--run-id", parsed.flags["--run-id"]);
+            (0, skill_1.runSkillNewCommand)({
+                root,
+                slug,
+                name,
+                description,
+                tags,
+                authors,
+                links,
+                withScripts,
+                force,
+                runId,
+            });
+            return 0;
+        }
+        case "list": {
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("skill list does not accept positional arguments");
+            }
+            const tags = parseCsvFlag("--tags", parsed.flags["--tags"]);
+            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"]);
+            (0, skill_1.runSkillListCommand)({
+                root,
+                tags,
+                tagsMode,
+                json,
+                noCache,
+                noReindex,
+            });
+            return 0;
+        }
+        case "show": {
+            const slug = parsed.positionals[2];
+            if (!slug || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("skill show requires <slug>");
+            }
+            const metaOnly = parseBooleanFlag("--meta", parsed.flags["--meta"]);
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            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,
+                noCache,
+                noReindex,
+            });
+            return 0;
+        }
+        case "search": {
+            if (parsed.positionals.length < 3) {
+                throw new errors_1.UsageError("skill search requires a query");
+            }
+            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 noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
+            const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
+            (0, skill_1.runSkillSearchCommand)({
+                root,
+                query,
+                tags,
+                tagsMode,
+                json,
+                noCache,
+                noReindex,
+            });
+            return 0;
+        }
+        case "validate": {
+            if (parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("skill validate accepts at most one slug");
+            }
+            const slug = parsed.positionals[2];
+            (0, skill_1.runSkillValidateCommand)({ root, slug });
+            return 0;
+        }
+        default:
+            throw new errors_1.UsageError("skill requires new/list/show/search/validate");
     }
-    if (command === "help") {
-        printCommandHelp(parsed.positionals[1]);
-        process.exit(0);
-    }
-    const root = parsed.root ? path_1.default.resolve(parsed.root) : process.cwd();
-    if (shouldRequireConfig(command, parsed.flags)) {
-        if (!hasConfig(root)) {
-            printRootError(root);
-            process.exit(1);
+}
+function runTaskSubcommand(parsed, root) {
+    const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
+    switch (subcommand) {
+        case "start": {
+            const id = parsed.positionals[2];
+            if (!id || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("task start requires <id-or-qid>");
+            }
+            const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
+            const runId = requireFlagValue("--run-id", parsed.flags["--run-id"]);
+            const note = requireFlagValue("--note", parsed.flags["--note"]);
+            (0, task_1.runTaskStartCommand)({ root, id, ws, runId, note });
+            return 0;
+        }
+        case "update": {
+            const id = parsed.positionals[2];
+            if (!id || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("task update requires <id-or-qid>");
+            }
+            const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
+            const status = requireFlagValue("--status", parsed.flags["--status"]);
+            const priority = parseNumberFlag("--priority", parsed.flags["--priority"]);
+            const addArtifacts = requireFlagValue("--add-artifacts", parsed.flags["--add-artifacts"]);
+            const addLinks = requireFlagValue("--add-links", parsed.flags["--add-links"]);
+            const addRefs = requireFlagValue("--add-refs", parsed.flags["--add-refs"]);
+            const addSkills = requireFlagValue("--add-skills", parsed.flags["--add-skills"]);
+            const addTags = requireFlagValue("--add-tags", parsed.flags["--add-tags"]);
+            const addBlockedBy = requireFlagValue("--add-blocked-by", parsed.flags["--add-blocked-by"]);
+            const clearBlockedBy = parseBooleanFlag("--clear-blocked-by", parsed.flags["--clear-blocked-by"]);
+            const runId = requireFlagValue("--run-id", parsed.flags["--run-id"]);
+            const note = requireFlagValue("--note", parsed.flags["--note"]);
+            (0, task_1.runTaskUpdateCommand)({
+                root,
+                id,
+                ws,
+                status,
+                priority,
+                addArtifacts,
+                addLinks,
+                addRefs,
+                addSkills,
+                addTags,
+                addBlockedBy,
+                clearBlockedBy,
+                runId,
+                note,
+            });
+            return 0;
         }
+        case "done": {
+            const id = parsed.positionals[2];
+            if (!id || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("task done requires <id-or-qid>");
+            }
+            const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
+            const addArtifacts = requireFlagValue("--add-artifacts", parsed.flags["--add-artifacts"]);
+            const addLinks = requireFlagValue("--add-links", parsed.flags["--add-links"]);
+            const addRefs = requireFlagValue("--add-refs", parsed.flags["--add-refs"]);
+            const checkpoint = requireFlagValue("--checkpoint", parsed.flags["--checkpoint"]);
+            const runId = requireFlagValue("--run-id", parsed.flags["--run-id"]);
+            const note = requireFlagValue("--note", parsed.flags["--note"]);
+            (0, task_1.runTaskDoneCommand)({
+                root,
+                id,
+                ws,
+                addArtifacts,
+                addLinks,
+                addRefs,
+                checkpoint,
+                runId,
+                note,
+            });
+            return 0;
+        }
+        default:
+            throw new errors_1.UsageError("task requires start/update/done");
     }
-    try {
-        switch (command) {
-            case "init": {
-                const force = parseBooleanFlag("--force", parsed.flags["--force"]);
-                const createAgents = parseBooleanFlag("--agents", parsed.flags["--agents"]);
-                const createClaude = parseBooleanFlag("--claude", parsed.flags["--claude"]);
-                const createLlm = parseBooleanFlag("--llm", parsed.flags["--llm"]);
-                const updateGitignore = parseBooleanFlag("--update-gitignore", parsed.flags["--update-gitignore"]);
-                const updateNpmignore = parseBooleanFlag("--update-npmignore", parsed.flags["--update-npmignore"]);
-                const updateDockerignore = parseBooleanFlag("--update-dockerignore", parsed.flags["--update-dockerignore"]);
-                try {
-                    (0, init_1.runInitCommand)({
-                        root,
-                        force,
-                        updateGitignore,
-                        updateNpmignore,
-                        updateDockerignore,
-                        createAgents,
-                        createClaude,
-                        createLlm,
-                    });
-                }
-                catch (err) {
-                    handleCommandError(err);
-                }
-                process.exit(0);
+}
+function runEventSubcommand(parsed, root) {
+    const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
+    switch (subcommand) {
+        case "enable": {
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("event enable does not accept positional arguments");
             }
-            case "guide": {
-                try {
-                    (0, guide_1.runGuideCommand)({ root });
-                }
-                catch (err) {
-                    handleCommandError(err);
-                }
-                process.exit(0);
+            const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
+            const noUpdateGitignore = parseBooleanFlag("--no-update-gitignore", parsed.flags["--no-update-gitignore"]);
+            (0, event_1.runEventEnableCommand)({ root, ws, updateGitignore: !noUpdateGitignore });
+            return 0;
+        }
+        case "append": {
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("event append does not accept positional arguments");
             }
-            case "index": {
-                const tolerant = Boolean(parsed.flags["--tolerant"]);
-                try {
-                    (0, index_1.runIndexCommand)({ root, tolerant });
-                }
-                catch (err) {
-                    handleCommandError(err);
-                }
-                process.exit(0);
+            const kind = requireFlagValue("--kind", parsed.flags["--kind"]);
+            const status = requireFlagValue("--status", parsed.flags["--status"]);
+            const refs = requireFlagValue("--refs", parsed.flags["--refs"]);
+            if (!kind || !status || !refs) {
+                throw new errors_1.UsageError("event append requires --kind, --status, and --refs");
             }
-            case "new": {
-                const type = parsed.positionals[1];
-                const title = parsed.positionals.slice(2).join(" ");
-                if (!type || !title) {
-                    handleCommandError(new errors_1.UsageError("new requires a type and title"));
-                }
-                const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
-                const status = requireFlagValue("--status", parsed.flags["--status"]);
-                const priority = parseNumberFlag("--priority", parsed.flags["--priority"]);
-                const epic = requireFlagValue("--epic", parsed.flags["--epic"]);
-                const parent = requireFlagValue("--parent", parsed.flags["--parent"]);
-                const prev = requireFlagValue("--prev", parsed.flags["--prev"]);
-                const next = requireFlagValue("--next", parsed.flags["--next"]);
-                const relates = requireFlagValue("--relates", parsed.flags["--relates"]);
-                const blockedBy = requireFlagValue("--blocked-by", parsed.flags["--blocked-by"]);
-                const blocks = requireFlagValue("--blocks", parsed.flags["--blocks"]);
-                const links = requireFlagValue("--links", parsed.flags["--links"]);
-                const artifacts = requireFlagValue("--artifacts", parsed.flags["--artifacts"]);
-                const refs = requireFlagValue("--refs", parsed.flags["--refs"]);
-                const aliases = requireFlagValue("--aliases", parsed.flags["--aliases"]);
-                const cases = requireFlagValue("--cases", parsed.flags["--cases"]);
-                const tags = requireFlagValue("--tags", parsed.flags["--tags"]);
-                const owners = requireFlagValue("--owners", parsed.flags["--owners"]);
-                const supersedes = requireFlagValue("--supersedes", parsed.flags["--supersedes"]);
-                const template = requireFlagValue("--template", parsed.flags["--template"]);
-                const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
-                const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
-                try {
-                    (0, new_1.runNewCommand)({
-                        root,
-                        type,
-                        title,
-                        ws,
-                        status,
-                        priority,
-                        epic,
-                        parent,
-                        prev,
-                        next,
-                        relates,
-                        blockedBy,
-                        blocks,
-                        links,
-                        artifacts,
-                        refs,
-                        aliases,
-                        cases,
-                        tags,
-                        owners,
-                        supersedes,
-                        template,
-                        noCache,
-                        noReindex,
-                    });
-                }
-                catch (err) {
-                    handleCommandError(err);
-                }
-                process.exit(0);
+            const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
+            const artifacts = requireFlagValue("--artifacts", parsed.flags["--artifacts"]);
+            const notes = requireFlagValue("--notes", parsed.flags["--notes"]);
+            const runId = requireFlagValue("--run-id", parsed.flags["--run-id"]);
+            const agent = requireFlagValue("--agent", parsed.flags["--agent"]);
+            const skill = requireFlagValue("--skill", parsed.flags["--skill"]);
+            const tool = requireFlagValue("--tool", parsed.flags["--tool"]);
+            (0, event_1.runEventAppendCommand)({
+                root,
+                ws,
+                kind,
+                status,
+                refs,
+                artifacts,
+                notes,
+                runId,
+                agent,
+                skill,
+                tool,
+            });
+            return 0;
+        }
+        default:
+            throw new errors_1.UsageError("event requires enable/append");
+    }
+}
+function runCommand(parsed, root, runtime) {
+    const command = (parsed.positionals[0] ?? "").toLowerCase();
+    switch (command) {
+        case "init": {
+            const force = parseBooleanFlag("--force", parsed.flags["--force"]);
+            const createAgents = parseBooleanFlag("--agents", parsed.flags["--agents"]);
+            const createClaude = parseBooleanFlag("--claude", parsed.flags["--claude"]);
+            const createLlm = parseBooleanFlag("--llm", parsed.flags["--llm"]);
+            const omni = parseBooleanFlag("--omni", parsed.flags["--omni"]);
+            const noUpdateIgnores = parseBooleanFlag("--no-update-ignores", parsed.flags["--no-update-ignores"]);
+            const updateGitignore = parseBooleanFlag("--update-gitignore", parsed.flags["--update-gitignore"]);
+            const updateNpmignore = parseBooleanFlag("--update-npmignore", parsed.flags["--update-npmignore"]);
+            const updateDockerignore = parseBooleanFlag("--update-dockerignore", parsed.flags["--update-dockerignore"]);
+            (0, init_1.runInitCommand)({
+                root,
+                force,
+                updateGitignore,
+                updateNpmignore,
+                updateDockerignore,
+                noUpdateIgnores,
+                createAgents,
+                createClaude,
+                createLlm,
+                omni,
+            });
+            return 0;
+        }
+        case "guide":
+            (0, guide_1.runGuideCommand)({ root });
+            return 0;
+        case "index": {
+            const tolerant = Boolean(parsed.flags["--tolerant"]);
+            (0, index_1.runIndexCommand)({ root, tolerant });
+            return 0;
+        }
+        case "new": {
+            const type = parsed.positionals[1];
+            const title = parsed.positionals.slice(2).join(" ");
+            if (!type || !title) {
+                throw new errors_1.UsageError("new requires a type and title");
             }
-            case "workspace": {
-                const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
-                switch (subcommand) {
-                    case "ls": {
-                        if (parsed.positionals.length > 2) {
-                            handleCommandError(new errors_1.UsageError("workspace ls takes no arguments"));
-                        }
-                        try {
-                            (0, workspace_1.runWorkspaceListCommand)({ root });
-                        }
-                        catch (err) {
-                            handleCommandError(err);
-                        }
-                        process.exit(0);
-                    }
-                    case "add": {
-                        const alias = parsed.positionals[2];
-                        const workspacePath = parsed.positionals[3];
-                        if (!alias || !workspacePath) {
-                            handleCommandError(new errors_1.UsageError("workspace add requires <alias> <path>"));
-                        }
-                        const mdkgDir = requireFlagValue("--mdkg-dir", parsed.flags["--mdkg-dir"]);
-                        try {
-                            (0, workspace_1.runWorkspaceAddCommand)({ root, alias, workspacePath, mdkgDir });
-                        }
-                        catch (err) {
-                            handleCommandError(err);
-                        }
-                        process.exit(0);
-                    }
-                    case "rm": {
-                        const alias = parsed.positionals[2];
-                        if (!alias || parsed.positionals.length > 3) {
-                            handleCommandError(new errors_1.UsageError("workspace rm requires <alias>"));
-                        }
-                        try {
-                            (0, workspace_1.runWorkspaceRemoveCommand)({ root, alias });
-                        }
-                        catch (err) {
-                            handleCommandError(err);
-                        }
-                        process.exit(0);
-                    }
-                    default: {
-                        handleCommandError(new errors_1.UsageError("workspace requires ls/add/rm"));
-                    }
-                }
-                process.exit(0);
+            const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
+            const status = requireFlagValue("--status", parsed.flags["--status"]);
+            const priority = parseNumberFlag("--priority", parsed.flags["--priority"]);
+            const epic = requireFlagValue("--epic", parsed.flags["--epic"]);
+            const parent = requireFlagValue("--parent", parsed.flags["--parent"]);
+            const prev = requireFlagValue("--prev", parsed.flags["--prev"]);
+            const next = requireFlagValue("--next", parsed.flags["--next"]);
+            const relates = requireFlagValue("--relates", parsed.flags["--relates"]);
+            const blockedBy = requireFlagValue("--blocked-by", parsed.flags["--blocked-by"]);
+            const blocks = requireFlagValue("--blocks", parsed.flags["--blocks"]);
+            const links = requireFlagValue("--links", parsed.flags["--links"]);
+            const artifacts = requireFlagValue("--artifacts", parsed.flags["--artifacts"]);
+            const refs = requireFlagValue("--refs", parsed.flags["--refs"]);
+            const aliases = requireFlagValue("--aliases", parsed.flags["--aliases"]);
+            const skills = requireFlagValue("--skills", parsed.flags["--skills"]);
+            const cases = requireFlagValue("--cases", parsed.flags["--cases"]);
+            const tags = requireFlagValue("--tags", parsed.flags["--tags"]);
+            const owners = requireFlagValue("--owners", parsed.flags["--owners"]);
+            const supersedes = requireFlagValue("--supersedes", parsed.flags["--supersedes"]);
+            const template = requireFlagValue("--template", parsed.flags["--template"]);
+            const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
+            const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
+            const runId = requireFlagValue("--run-id", parsed.flags["--run-id"]);
+            (0, new_1.runNewCommand)({
+                root,
+                type,
+                title,
+                ws,
+                status,
+                priority,
+                epic,
+                parent,
+                prev,
+                next,
+                relates,
+                blockedBy,
+                blocks,
+                links,
+                artifacts,
+                refs,
+                aliases,
+                skills,
+                cases,
+                tags,
+                owners,
+                supersedes,
+                template,
+                noCache,
+                noReindex,
+                runId,
+            });
+            return 0;
+        }
+        case "workspace":
+            return runWorkspaceSubcommand(parsed, root);
+        case "skill":
+            return runSkillSubcommand(parsed, root);
+        case "task":
+            return runTaskSubcommand(parsed, root);
+        case "event":
+            return runEventSubcommand(parsed, root);
+        case "show": {
+            const id = parsed.positionals[1];
+            if (!id || parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("show requires a single id");
             }
-            case "show": {
-                const id = parsed.positionals[1];
-                if (!id || parsed.positionals.length > 2) {
-                    handleCommandError(new errors_1.UsageError("show requires a single id"));
-                }
-                const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
-                const includeBody = parseBooleanFlag("--body", parsed.flags["--body"]);
-                const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
-                const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
-                try {
-                    (0, show_1.runShowCommand)({
-                        root,
-                        id,
-                        ws,
-                        includeBody,
-                        noCache,
-                        noReindex,
-                    });
-                }
-                catch (err) {
-                    handleCommandError(err);
-                }
-                process.exit(0);
+            const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
+            const metaOnly = parseBooleanFlag("--meta", parsed.flags["--meta"]);
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
+            const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
+            (0, show_1.runShowCommand)({
+                root,
+                id,
+                ws,
+                metaOnly,
+                json,
+                noCache,
+                noReindex,
+            });
+            return 0;
+        }
+        case "list": {
+            if (parsed.positionals.length > 1) {
+                throw new errors_1.UsageError("list does not accept positional arguments");
             }
-            case "list": {
+            const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
+            const type = requireFlagValue("--type", parsed.flags["--type"]);
+            const status = requireFlagValue("--status", parsed.flags["--status"]);
+            const epic = requireFlagValue("--epic", parsed.flags["--epic"]);
+            const priority = parseNumberFlag("--priority", parsed.flags["--priority"]);
+            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 noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
+            const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
+            (0, list_1.runListCommand)({
+                root,
+                ws,
+                type,
+                status,
+                epic,
+                priority,
+                blocked,
+                tags,
+                tagsMode,
+                json,
+                noCache,
+                noReindex,
+            });
+            return 0;
+        }
+        case "search": {
+            if (parsed.positionals.length < 2) {
+                throw new errors_1.UsageError("search requires a query");
+            }
+            const query = parsed.positionals.slice(1).join(" ");
+            const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
+            const type = requireFlagValue("--type", parsed.flags["--type"]);
+            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 noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
+            const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
+            (0, search_1.runSearchCommand)({
+                root,
+                query,
+                ws,
+                type,
+                status,
+                tags,
+                tagsMode,
+                json,
+                noCache,
+                noReindex,
+            });
+            return 0;
+        }
+        case "pack": {
+            const listProfiles = parseBooleanFlag("--list-profiles", parsed.flags["--list-profiles"]);
+            if (listProfiles) {
                 if (parsed.positionals.length > 1) {
-                    handleCommandError(new errors_1.UsageError("list does not accept positional arguments"));
+                    throw new errors_1.UsageError("pack --list-profiles does not accept positional arguments");
                 }
-                const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
-                const type = requireFlagValue("--type", parsed.flags["--type"]);
-                const status = requireFlagValue("--status", parsed.flags["--status"]);
-                const epic = requireFlagValue("--epic", parsed.flags["--epic"]);
-                const priority = parseNumberFlag("--priority", parsed.flags["--priority"]);
-                const blocked = parseBooleanFlag("--blocked", parsed.flags["--blocked"]);
-                const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
-                const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
-                try {
-                    (0, list_1.runListCommand)({
-                        root,
-                        ws,
-                        type,
-                        status,
-                        epic,
-                        priority,
-                        blocked,
-                        noCache,
-                        noReindex,
-                    });
-                }
-                catch (err) {
-                    handleCommandError(err);
-                }
-                process.exit(0);
+                printPackProfiles(runtime.log);
+                return 0;
             }
-            case "search": {
-                if (parsed.positionals.length < 2) {
-                    handleCommandError(new errors_1.UsageError("search requires a query"));
-                }
-                const query = parsed.positionals.slice(1).join(" ");
-                const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
-                const type = requireFlagValue("--type", parsed.flags["--type"]);
-                const status = requireFlagValue("--status", parsed.flags["--status"]);
-                const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
-                const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
-                try {
-                    (0, search_1.runSearchCommand)({
-                        root,
-                        query,
-                        ws,
-                        type,
-                        status,
-                        noCache,
-                        noReindex,
-                    });
-                }
-                catch (err) {
-                    handleCommandError(err);
-                }
-                process.exit(0);
+            const id = parsed.positionals[1];
+            if (!id || parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("pack requires a single id");
             }
-            case "pack": {
-                const listProfiles = parseBooleanFlag("--list-profiles", parsed.flags["--list-profiles"]);
-                if (listProfiles) {
-                    if (parsed.positionals.length > 1) {
-                        handleCommandError(new errors_1.UsageError("pack --list-profiles does not accept positional arguments"));
-                    }
-                    printPackProfiles();
-                    process.exit(0);
-                }
-                const id = parsed.positionals[1];
-                if (!id || parsed.positionals.length > 2) {
-                    handleCommandError(new errors_1.UsageError("pack requires a single id"));
-                }
-                const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
-                const depth = parseNumberFlag("--depth", parsed.flags["--depth"]);
-                const edges = parseEdgesFlag(parsed.flags["--edges"]);
-                const verbose = parseBooleanFlag("--verbose", parsed.flags["--verbose"]);
-                const concise = parseBooleanFlag("--concise", parsed.flags["--concise"]);
-                const stripCode = parseBooleanFlag("--strip-code", parsed.flags["--strip-code"]);
-                const format = requireFlagValue("--format", parsed.flags["--format"]);
-                const packProfile = requireFlagValue("--pack-profile", parsed.flags["--pack-profile"]);
-                const maxCodeLines = parseNumberFlag("--max-code-lines", parsed.flags["--max-code-lines"]);
-                const maxChars = parseNumberFlag("--max-chars", parsed.flags["--max-chars"]);
-                const maxLines = parseNumberFlag("--max-lines", parsed.flags["--max-lines"]);
-                const maxTokens = parseNumberFlag("--max-tokens", parsed.flags["--max-tokens"]);
-                const dryRun = parseBooleanFlag("--dry-run", parsed.flags["--dry-run"]);
-                const stats = parseBooleanFlag("--stats", parsed.flags["--stats"]);
-                const statsOut = requireFlagValue("--stats-out", parsed.flags["--stats-out"]);
-                const truncationReport = requireFlagValue("--truncation-report", parsed.flags["--truncation-report"]);
-                const out = requireFlagValue("--out", parsed.flags["--out"]);
-                const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
-                const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
-                try {
-                    (0, pack_1.runPackCommand)({
-                        root,
-                        id,
-                        ws,
-                        depth,
-                        edges,
-                        verbose,
-                        concise,
-                        stripCode,
-                        format,
-                        packProfile,
-                        maxCodeLines,
-                        maxChars,
-                        maxLines,
-                        maxTokens,
-                        dryRun,
-                        stats,
-                        statsOut,
-                        truncationReport,
-                        out,
-                        noCache,
-                        noReindex,
-                    });
-                }
-                catch (err) {
-                    handleCommandError(err);
-                }
-                process.exit(0);
+            const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
+            const depth = parseNumberFlag("--depth", parsed.flags["--depth"]);
+            const edges = parseEdgesFlag(parsed.flags["--edges"]);
+            const verbose = parseBooleanFlag("--verbose", parsed.flags["--verbose"]);
+            const concise = parseBooleanFlag("--concise", parsed.flags["--concise"]);
+            const stripCode = parseBooleanFlag("--strip-code", parsed.flags["--strip-code"]);
+            const format = requireFlagValue("--format", parsed.flags["--format"]);
+            const packProfile = requireFlagValue("--pack-profile", parsed.flags["--pack-profile"]);
+            const maxCodeLines = parseNumberFlag("--max-code-lines", parsed.flags["--max-code-lines"]);
+            const maxChars = parseNumberFlag("--max-chars", parsed.flags["--max-chars"]);
+            const maxLines = parseNumberFlag("--max-lines", parsed.flags["--max-lines"]);
+            const maxTokens = parseNumberFlag("--max-tokens", parsed.flags["--max-tokens"]);
+            const skills = requireFlagValue("--skills", parsed.flags["--skills"]);
+            const skillsDepth = requireFlagValue("--skills-depth", parsed.flags["--skills-depth"]);
+            const dryRun = parseBooleanFlag("--dry-run", parsed.flags["--dry-run"]);
+            const stats = parseBooleanFlag("--stats", parsed.flags["--stats"]);
+            const statsOut = requireFlagValue("--stats-out", parsed.flags["--stats-out"]);
+            const truncationReport = requireFlagValue("--truncation-report", parsed.flags["--truncation-report"]);
+            const out = requireFlagValue("--out", parsed.flags["--out"]);
+            const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
+            const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
+            (0, pack_1.runPackCommand)({
+                root,
+                id,
+                ws,
+                depth,
+                edges,
+                verbose,
+                concise,
+                stripCode,
+                format,
+                packProfile,
+                maxCodeLines,
+                maxChars,
+                maxLines,
+                maxTokens,
+                skills,
+                skillsDepth,
+                dryRun,
+                stats,
+                statsOut,
+                truncationReport,
+                out,
+                noCache,
+                noReindex,
+            });
+            return 0;
+        }
+        case "next": {
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("next accepts at most one id");
             }
-            case "next": {
-                if (parsed.positionals.length > 2) {
-                    handleCommandError(new errors_1.UsageError("next accepts at most one id"));
-                }
-                const id = parsed.positionals[1];
-                const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
-                const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
-                const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
-                try {
-                    (0, next_1.runNextCommand)({
-                        root,
-                        id,
-                        ws,
-                        noCache,
-                        noReindex,
-                    });
-                }
-                catch (err) {
-                    handleCommandError(err);
-                }
-                process.exit(0);
+            const id = parsed.positionals[1];
+            const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
+            const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
+            const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
+            (0, next_1.runNextCommand)({
+                root,
+                id,
+                ws,
+                noCache,
+                noReindex,
+            });
+            return 0;
+        }
+        case "checkpoint": {
+            const sub = (parsed.positionals[1] ?? "").toLowerCase();
+            if (!sub) {
+                throw new errors_1.UsageError("checkpoint requires a subcommand");
             }
-            case "checkpoint": {
-                const sub = (parsed.positionals[1] ?? "").toLowerCase();
-                if (!sub) {
-                    handleCommandError(new errors_1.UsageError("checkpoint requires a subcommand"));
-                }
-                if (sub !== "new") {
-                    handleCommandError(new errors_1.UsageError(`unknown checkpoint subcommand: ${sub}`));
-                }
-                const title = parsed.positionals.slice(2).join(" ");
-                const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
-                const relates = requireFlagValue("--relates", parsed.flags["--relates"]);
-                const scope = requireFlagValue("--scope", parsed.flags["--scope"]);
-                const status = requireFlagValue("--status", parsed.flags["--status"]);
-                const priority = parseNumberFlag("--priority", parsed.flags["--priority"]);
-                const template = requireFlagValue("--template", parsed.flags["--template"]);
-                try {
-                    (0, checkpoint_1.runCheckpointNewCommand)({
-                        root,
-                        title,
-                        ws,
-                        relates,
-                        scope,
-                        status,
-                        priority,
-                        template,
-                    });
-                }
-                catch (err) {
-                    handleCommandError(err);
-                }
-                process.exit(0);
+            if (sub !== "new") {
+                throw new errors_1.UsageError(`unknown checkpoint subcommand: ${sub}`);
             }
-            case "validate": {
-                if (parsed.positionals.length > 1) {
-                    handleCommandError(new errors_1.UsageError("validate does not accept positional arguments"));
-                }
-                const out = requireFlagValue("--out", parsed.flags["--out"]);
-                const quiet = parseBooleanFlag("--quiet", parsed.flags["--quiet"]);
-                try {
-                    (0, validate_1.runValidateCommand)({ root, out, quiet });
-                }
-                catch (err) {
-                    handleCommandError(err);
-                }
-                process.exit(0);
+            const title = parsed.positionals.slice(2).join(" ");
+            const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
+            const relates = requireFlagValue("--relates", parsed.flags["--relates"]);
+            const scope = requireFlagValue("--scope", parsed.flags["--scope"]);
+            const status = requireFlagValue("--status", parsed.flags["--status"]);
+            const priority = parseNumberFlag("--priority", parsed.flags["--priority"]);
+            const template = requireFlagValue("--template", parsed.flags["--template"]);
+            const runId = requireFlagValue("--run-id", parsed.flags["--run-id"]);
+            const note = requireFlagValue("--note", parsed.flags["--note"]);
+            (0, checkpoint_1.runCheckpointNewCommand)({
+                root,
+                title,
+                ws,
+                relates,
+                scope,
+                status,
+                priority,
+                template,
+                runId,
+                note,
+            });
+            return 0;
+        }
+        case "validate": {
+            if (parsed.positionals.length > 1) {
+                throw new errors_1.UsageError("validate does not accept positional arguments");
             }
-            case "format": {
-                if (parsed.positionals.length > 1) {
-                    handleCommandError(new errors_1.UsageError("format does not accept positional arguments"));
-                }
-                try {
-                    (0, format_1.runFormatCommand)({ root });
-                }
-                catch (err) {
-                    handleCommandError(err);
-                }
-                process.exit(0);
+            const out = requireFlagValue("--out", parsed.flags["--out"]);
+            const quiet = parseBooleanFlag("--quiet", parsed.flags["--quiet"]);
+            (0, validate_1.runValidateCommand)({ root, out, quiet });
+            return 0;
+        }
+        case "format":
+            if (parsed.positionals.length > 1) {
+                throw new errors_1.UsageError("format does not accept positional arguments");
             }
-            case "doctor": {
-                if (parsed.positionals.length > 1) {
-                    handleCommandError(new errors_1.UsageError("doctor does not accept positional arguments"));
-                }
-                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"]);
-                try {
-                    (0, doctor_1.runDoctorCommand)({ root, noCache, noReindex, json });
-                }
-                catch (err) {
-                    handleCommandError(err);
-                }
-                process.exit(0);
+            (0, format_1.runFormatCommand)({ root });
+            return 0;
+        case "doctor": {
+            if (parsed.positionals.length > 1) {
+                throw new errors_1.UsageError("doctor does not accept positional arguments");
             }
-            default:
-                console.error(`Unknown command: ${command}`);
-                printUsage();
-                process.exit(1);
+            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"]);
+            (0, doctor_1.runDoctorCommand)({ root, noCache, noReindex, json });
+            return 0;
         }
+        default:
+            runtime.error(`Unknown command: ${command}`);
+            printUsage(runtime.log);
+            return 1;
+    }
+}
+function runCli(argv, runtime = {}) {
+    const io = resolveRuntime(runtime);
+    const parsed = (0, argparse_1.parseArgs)(argv);
+    if (parsed.error) {
+        io.error(parsed.error);
+        printUsage(io.log);
+        return 1;
+    }
+    if (parsed.help) {
+        printCommandHelp(io.log, parsed.positionals[0], parsed.positionals[1]);
+        return 0;
+    }
+    if (parsed.version) {
+        io.log(readPackageVersion());
+        return 0;
+    }
+    const command = (parsed.positionals[0] ?? "").toLowerCase();
+    if (!command) {
+        printUsage(io.log);
+        return 0;
+    }
+    if (command === "help") {
+        printCommandHelp(io.log, parsed.positionals[1], parsed.positionals[2]);
+        return 0;
+    }
+    const root = parsed.root ? path_1.default.resolve(parsed.root) : io.cwd();
+    if (shouldRequireConfig(command, parsed.flags) && !hasConfig(root)) {
+        printRootError(io.error, root);
+        return 1;
+    }
+    try {
+        return runCommand(parsed, root, io);
     }
     catch (err) {
-        handleCommandError(err);
+        return handleCommandError(err, command, io);
     }
 }
-main();
+function main(argv = process.argv.slice(2)) {
+    process.exit(runCli(argv, { cwd: () => process.cwd() }));
+}
+if (require.main === module) {
+    main();
+}