mdkg 0.4.1 → 0.5.0

package/dist/command-contract.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "package_version": "0.4.1",
+  "package_version": "0.5.0",
   "source": {
     "help_targets": "scripts/cli_help_targets.js",
     "command_matrix": "CLI_COMMAND_MATRIX.md"
@@ -2666,77 +2666,53 @@
       }
     },
     {
-      "key": "global",
+      "key": "git",
       "path": [
-        "global"
+        "git"
       ],
-      "category": "global",
+      "category": "git",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg - Markdown Knowledge Graph",
+      "summary": "mdkg git command",
       "usage": [
-        "  mdkg <command> [options]"
+        "  mdkg git inspect [--json]",
+        "  mdkg git clone <repository-ref> --target <path> [--branch <name>] [--json]",
+        "  mdkg git fetch [--remote <name>] [--branch <name>] [--json]",
+        "  mdkg git closeout [--queue-policy drain|paused] [--output <path>] [--json]",
+        "  mdkg git push-ready --remote <name> --branch <name> [--json]",
+        "  mdkg git push --remote <name> --branch <name> [--stage-all --message <text>] [--json]"
       ],
       "args": [
         {
-          "name": "command",
+          "name": "repository-ref",
           "required": true,
-          "source": "<command>"
-        },
-        {
-          "name": "options",
-          "required": false,
-          "source": "[options]"
+          "source": "<repository-ref>"
         }
       ],
       "flags": [
         {
-          "name": "--agent",
-          "value": null,
-          "required": false,
-          "description": "mdkg init --agent"
-        },
-        {
-          "name": "--apply",
-          "value": null,
-          "required": false,
-          "description": "mdkg upgrade --apply"
-        },
-        {
-          "name": "--description",
-          "value": "\"use",
-          "required": false,
-          "description": "mdkg skill new release-readiness \"release readiness audit\" --description \"use when preparing a release\""
-        },
-        {
-          "name": "--dry-run",
-          "value": null,
+          "name": "--branch",
+          "value": "<name>",
           "required": false,
-          "description": "mdkg pack <id> --profile concise --dry-run --stats"
+          "description": "mdkg git push-ready --remote <name> --branch <name> [--json]"
         },
         {
           "name": "--help",
           "value": null,
           "required": false,
-          "description": "Run `mdkg help <command>` or `mdkg <command> --help` for details."
-        },
-        {
-          "name": "--json",
-          "value": null,
-          "required": false,
-          "description": "mdkg skill list --tags stage:plan --json"
+          "description": "--help, -h          Show help"
         },
         {
-          "name": "--priority",
-          "value": "1",
+          "name": "--message",
+          "value": "<text>",
           "required": false,
-          "description": "mdkg new task \"...\" --status todo --priority 1"
+          "description": "mdkg git push --remote <name> --branch <name> [--stage-all --message <text>] [--json]"
         },
         {
-          "name": "--profile",
-          "value": "concise",
+          "name": "--remote",
+          "value": "<name>",
           "required": false,
-          "description": "mdkg pack <id> --profile concise --dry-run --stats"
+          "description": "mdkg git push-ready --remote <name> --branch <name> [--json]"
         },
         {
           "name": "--root",
@@ -2745,16 +2721,10 @@
           "description": "--root, -r <path>   Run against a specific repo root"
         },
         {
-          "name": "--status",
-          "value": "todo",
-          "required": false,
-          "description": "mdkg new task \"...\" --status todo --priority 1"
-        },
-        {
-          "name": "--tags",
-          "value": "stage:plan",
+          "name": "--target",
+          "value": "<path>",
           "required": false,
-          "description": "mdkg skill list --tags stage:plan --json"
+          "description": "mdkg git clone <repository-ref> --target <path> [--branch <name>] [--json]"
         },
         {
           "name": "--version",
@@ -2769,19 +2739,28 @@
       ],
       "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
-        "none"
+        "inspect-or-mutate-git-backed-mdkg-project-lifecycle"
       ],
       "read_paths": [
         ".mdkg/**"
       ],
-      "write_paths": [],
+      "write_paths": [
+        ".mdkg/db/**",
+        ".mdkg/git/**",
+        ".mdkg/index/**"
+      ],
       "dry_run": {
         "supported": false
       },
-      "lock_policy": "none-read-only",
-      "atomic_write_policy": "none-read-only",
-      "receipts": [],
-      "danger_level": "read-only",
+      "lock_policy": "mutation-lock-required-for-closeout-and-stage-all-push",
+      "atomic_write_policy": "atomic-file-writes-for-closeout-receipts",
+      "receipts": [
+        "git-closeout-receipt",
+        "git-inspect-receipt",
+        "git-push-ready-receipt",
+        "git-push-receipt"
+      ],
+      "danger_level": "mixed",
       "aliases": [],
       "exit_codes": [
         {
@@ -2794,43 +2773,33 @@
         }
       ],
       "examples": [
-        "  mdkg <command> [options]"
+        "  mdkg git clone <repository-ref> --target <path> [--branch <name>] [--json]",
+        "  mdkg git fetch [--remote <name>] [--branch <name>] [--json]",
+        "  mdkg git inspect [--json]"
       ],
       "docs": {
-        "help_target": "mdkg --help",
+        "help_target": "mdkg help git",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
     {
-      "key": "goal",
+      "key": "git clone",
       "path": [
-        "goal"
+        "git",
+        "clone"
       ],
-      "category": "goal",
+      "category": "git",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg goal command",
+      "summary": "mdkg git clone command",
       "usage": [
-        "  mdkg goal show <goal-id-or-qid> [--json]",
-        "  mdkg goal select <goal-id-or-qid> [--json]",
-        "  mdkg goal activate <goal-id-or-qid> [--json]",
-        "  mdkg goal current [--json]",
-        "  mdkg goal next [goal-id-or-qid] [--json]",
-        "  mdkg goal claim [goal-id-or-qid] <work-id-or-qid> [--json]",
-        "  mdkg goal evaluate <goal-id-or-qid> [--json]",
-        "  mdkg goal clear [--json]",
-        "  mdkg goal pause|resume|done|archive <goal-id-or-qid> [--json]"
+        "  mdkg git clone <repository-ref> --target <path> [--branch <name>] [--json]"
       ],
       "args": [
         {
-          "name": "goal-id-or-qid",
-          "required": true,
-          "source": "<goal-id-or-qid>"
-        },
-        {
-          "name": "work-id-or-qid",
+          "name": "repository-ref",
           "required": true,
-          "source": "<work-id-or-qid>"
+          "source": "<repository-ref>"
         }
       ],
       "flags": [
@@ -2846,6 +2815,12 @@
           "required": false,
           "description": "--root, -r <path>   Run against a specific repo root"
         },
+        {
+          "name": "--target",
+          "value": "<path>",
+          "required": false,
+          "description": "mdkg git clone <repository-ref> --target <path> [--branch <name>] [--json]"
+        },
         {
           "name": "--version",
           "value": null,
@@ -2859,24 +2834,23 @@
       ],
       "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
-        "read-or-update-selected-goal-state"
+        "clone-remote-git-repository-into-contained-target"
       ],
       "read_paths": [
         ".mdkg/**"
       ],
       "write_paths": [
-        ".mdkg/**/*.md",
-        ".mdkg/index/**"
+        "<target>/**"
       ],
       "dry_run": {
         "supported": false
       },
-      "lock_policy": "mutation-lock-required-for-select-clear-claim-pause-resume-done",
-      "atomic_write_policy": "atomic-file-writes",
+      "lock_policy": "not-required-for-contained-target",
+      "atomic_write_policy": "delegated-to-system-git",
       "receipts": [
-        "goal-receipt"
+        "git-clone-receipt"
       ],
-      "danger_level": "mixed",
+      "danger_level": "moderate",
       "aliases": [],
       "exit_codes": [
         {
@@ -2889,35 +2863,27 @@
         }
       ],
       "examples": [
-        "  mdkg goal activate <goal-id-or-qid> [--json]",
-        "  mdkg goal select <goal-id-or-qid> [--json]",
-        "  mdkg goal show <goal-id-or-qid> [--json]"
+        "  mdkg git clone <repository-ref> --target <path> [--branch <name>] [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help goal",
+        "help_target": "mdkg help git clone",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
     {
-      "key": "goal activate",
+      "key": "git closeout",
       "path": [
-        "goal",
-        "activate"
+        "git",
+        "closeout"
       ],
-      "category": "goal",
+      "category": "git",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg goal activate command",
+      "summary": "mdkg git closeout command",
       "usage": [
-        "  mdkg goal activate <goal-id-or-qid> [--ws <alias>] [--json]"
-      ],
-      "args": [
-        {
-          "name": "goal-id-or-qid",
-          "required": true,
-          "source": "<goal-id-or-qid>"
-        }
+        "  mdkg git closeout [--queue-policy drain|paused] [--output <path>] [--json]"
       ],
+      "args": [],
       "flags": [
         {
           "name": "--help",
@@ -2944,22 +2910,23 @@
       ],
       "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
-        "activate-goal-and-pause-competing-goals"
+        "write-static-git-closeout-receipts-and-optional-db-snapshot"
       ],
       "read_paths": [
         ".mdkg/**"
       ],
       "write_paths": [
-        ".mdkg/**/*.md",
+        ".mdkg/db/**",
+        ".mdkg/git/**",
         ".mdkg/index/**"
       ],
       "dry_run": {
         "supported": false
       },
       "lock_policy": "mutation-lock-required",
-      "atomic_write_policy": "atomic-file-writes",
+      "atomic_write_policy": "atomic-file-writes-and-sqlite-vacuum-into",
       "receipts": [
-        "goal-state-receipt"
+        "git-closeout-receipt"
       ],
       "danger_level": "moderate",
       "aliases": [],
@@ -2974,33 +2941,27 @@
         }
       ],
       "examples": [
-        "  mdkg goal activate <goal-id-or-qid> [--ws <alias>] [--json]"
+        "  mdkg git closeout [--queue-policy drain|paused] [--output <path>] [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help goal activate",
+        "help_target": "mdkg help git closeout",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
     {
-      "key": "goal archive",
+      "key": "git fetch",
       "path": [
-        "goal",
-        "archive"
+        "git",
+        "fetch"
       ],
-      "category": "goal",
+      "category": "git",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg goal archive command",
+      "summary": "mdkg git fetch command",
       "usage": [
-        "  mdkg goal archive <goal-id-or-qid> [--ws <alias>] [--json]"
-      ],
-      "args": [
-        {
-          "name": "goal-id-or-qid",
-          "required": true,
-          "source": "<goal-id-or-qid>"
-        }
+        "  mdkg git fetch [--remote <name>] [--branch <name>] [--json]"
       ],
+      "args": [],
       "flags": [
         {
           "name": "--help",
@@ -3027,22 +2988,21 @@
       ],
       "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
-        "archive-goal"
+        "fetch-remote-git-refs"
       ],
       "read_paths": [
         ".mdkg/**"
       ],
       "write_paths": [
-        ".mdkg/**/*.md",
-        ".mdkg/index/**"
+        ".git/**"
       ],
       "dry_run": {
         "supported": false
       },
-      "lock_policy": "mutation-lock-required",
-      "atomic_write_policy": "atomic-file-writes",
+      "lock_policy": "delegated-to-system-git",
+      "atomic_write_policy": "delegated-to-system-git",
       "receipts": [
-        "goal-state-receipt"
+        "git-fetch-receipt"
       ],
       "danger_level": "moderate",
       "aliases": [],
@@ -3057,39 +3017,27 @@
         }
       ],
       "examples": [
-        "  mdkg goal archive <goal-id-or-qid> [--ws <alias>] [--json]"
+        "  mdkg git fetch [--remote <name>] [--branch <name>] [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help goal archive",
+        "help_target": "mdkg help git fetch",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
     {
-      "key": "goal claim",
+      "key": "git inspect",
       "path": [
-        "goal",
-        "claim"
+        "git",
+        "inspect"
       ],
-      "category": "goal",
+      "category": "git",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg goal claim command",
+      "summary": "mdkg git inspect command",
       "usage": [
-        "  mdkg goal claim <work-id-or-qid> [--ws <alias>] [--json]",
-        "  mdkg goal claim <goal-id-or-qid> <work-id-or-qid> [--ws <alias>] [--json]"
-      ],
-      "args": [
-        {
-          "name": "goal-id-or-qid",
-          "required": true,
-          "source": "<goal-id-or-qid>"
-        },
-        {
-          "name": "work-id-or-qid",
-          "required": true,
-          "source": "<work-id-or-qid>"
-        }
+        "  mdkg git inspect [--json]"
       ],
+      "args": [],
       "flags": [
         {
           "name": "--help",
@@ -3116,24 +3064,21 @@
       ],
       "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
-        "claim-goal-active-node"
+        "none"
       ],
       "read_paths": [
         ".mdkg/**"
       ],
-      "write_paths": [
-        ".mdkg/**/*.md",
-        ".mdkg/index/**"
-      ],
+      "write_paths": [],
       "dry_run": {
         "supported": false
       },
-      "lock_policy": "mutation-lock-required",
-      "atomic_write_policy": "atomic-file-writes",
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
       "receipts": [
-        "goal-state-receipt"
+        "git-inspect-receipt"
       ],
-      "danger_level": "moderate",
+      "danger_level": "read-only",
       "aliases": [],
       "exit_codes": [
         {
@@ -3146,41 +3091,65 @@
         }
       ],
       "examples": [
-        "  mdkg goal claim <goal-id-or-qid> <work-id-or-qid> [--ws <alias>] [--json]",
-        "  mdkg goal claim <work-id-or-qid> [--ws <alias>] [--json]"
+        "  mdkg git inspect [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help goal claim",
+        "help_target": "mdkg help git inspect",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
     {
-      "key": "goal clear",
+      "key": "git push",
       "path": [
-        "goal",
-        "clear"
+        "git",
+        "push"
       ],
-      "category": "goal",
+      "category": "git",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg goal clear command",
+      "summary": "mdkg git push command",
       "usage": [
-        "  mdkg goal clear [--json]"
+        "  mdkg git push --remote <name> --branch <name> [--json]",
+        "  mdkg git push --remote <name> --branch <name> --stage-all --message <text> [--queue-policy drain|paused] [--json]"
       ],
       "args": [],
       "flags": [
+        {
+          "name": "--branch",
+          "value": "<name>",
+          "required": false,
+          "description": "mdkg git push --remote <name> --branch <name> [--json]"
+        },
         {
           "name": "--help",
           "value": null,
           "required": false,
           "description": "--help, -h          Show help"
         },
+        {
+          "name": "--message",
+          "value": null,
+          "required": false,
+          "description": "- --stage-all writes closeout evidence, stages all changes, commits with --message, then runs push-ready before pushing"
+        },
+        {
+          "name": "--remote",
+          "value": "<name>",
+          "required": false,
+          "description": "mdkg git push --remote <name> --branch <name> [--json]"
+        },
         {
           "name": "--root",
           "value": null,
           "required": false,
           "description": "--root, -r <path>   Run against a specific repo root"
         },
+        {
+          "name": "--stage-all",
+          "value": null,
+          "required": false,
+          "description": "mdkg git push --remote <name> --branch <name> --stage-all --message <text> [--queue-policy drain|paused] [--json]"
+        },
         {
           "name": "--version",
           "value": null,
@@ -3194,24 +3163,26 @@
       ],
       "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
-        "clear-selected-goal"
+        "optional-closeout-stage-commit-and-real-git-push"
       ],
       "read_paths": [
         ".mdkg/**"
       ],
       "write_paths": [
-        ".mdkg/**/*.md",
-        ".mdkg/index/**"
+        ".git/**",
+        ".mdkg/db/**",
+        ".mdkg/git/**",
+        "repo-files/**"
       ],
       "dry_run": {
         "supported": false
       },
       "lock_policy": "mutation-lock-required",
-      "atomic_write_policy": "atomic-file-writes",
+      "atomic_write_policy": "atomic-file-writes-plus-system-git",
       "receipts": [
-        "goal-state-receipt"
+        "git-push-receipt"
       ],
-      "danger_level": "moderate",
+      "danger_level": "high",
       "aliases": [],
       "exit_codes": [
         {
@@ -3224,34 +3195,47 @@
         }
       ],
       "examples": [
-        "  mdkg goal clear [--json]"
+        "  mdkg git push --remote <name> --branch <name> --stage-all --message <text> [--queue-policy drain|paused] [--json]",
+        "  mdkg git push --remote <name> --branch <name> [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help goal clear",
+        "help_target": "mdkg help git push",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
     {
-      "key": "goal current",
+      "key": "git push-ready",
       "path": [
-        "goal",
-        "current"
+        "git",
+        "push-ready"
       ],
-      "category": "goal",
+      "category": "git",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg goal current command",
+      "summary": "mdkg git push-ready command",
       "usage": [
-        "  mdkg goal current [--ws <alias>] [--json]"
+        "  mdkg git push-ready --remote <name> --branch <name> [--json]"
       ],
       "args": [],
       "flags": [
+        {
+          "name": "--branch",
+          "value": "<name>",
+          "required": false,
+          "description": "mdkg git push-ready --remote <name> --branch <name> [--json]"
+        },
         {
           "name": "--help",
           "value": null,
           "required": false,
           "description": "--help, -h          Show help"
         },
+        {
+          "name": "--remote",
+          "value": "<name>",
+          "required": false,
+          "description": "mdkg git push-ready --remote <name> --branch <name> [--json]"
+        },
         {
           "name": "--root",
           "value": null,
@@ -3282,7 +3266,9 @@
       },
       "lock_policy": "none-read-only",
       "atomic_write_policy": "none-read-only",
-      "receipts": [],
+      "receipts": [
+        "git-push-ready-receipt"
+      ],
       "danger_level": "read-only",
       "aliases": [],
       "exit_codes": [
@@ -3296,39 +3282,85 @@
         }
       ],
       "examples": [
-        "  mdkg goal current [--ws <alias>] [--json]"
+        "  mdkg git push-ready --remote <name> --branch <name> [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help goal current",
+        "help_target": "mdkg help git push-ready",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
     {
-      "key": "goal done",
+      "key": "global",
       "path": [
-        "goal",
-        "done"
+        "global"
       ],
-      "category": "goal",
+      "category": "global",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg goal done command",
+      "summary": "mdkg - Markdown Knowledge Graph",
       "usage": [
-        "  mdkg goal done <goal-id-or-qid> [--ws <alias>] [--json]"
+        "  mdkg <command> [options]"
       ],
       "args": [
         {
-          "name": "goal-id-or-qid",
+          "name": "command",
           "required": true,
-          "source": "<goal-id-or-qid>"
+          "source": "<command>"
+        },
+        {
+          "name": "options",
+          "required": false,
+          "source": "[options]"
         }
       ],
       "flags": [
+        {
+          "name": "--agent",
+          "value": null,
+          "required": false,
+          "description": "mdkg init --agent"
+        },
+        {
+          "name": "--apply",
+          "value": null,
+          "required": false,
+          "description": "mdkg upgrade --apply"
+        },
+        {
+          "name": "--description",
+          "value": "\"use",
+          "required": false,
+          "description": "mdkg skill new release-readiness \"release readiness audit\" --description \"use when preparing a release\""
+        },
+        {
+          "name": "--dry-run",
+          "value": null,
+          "required": false,
+          "description": "mdkg pack <id> --profile concise --dry-run --stats"
+        },
         {
           "name": "--help",
           "value": null,
           "required": false,
-          "description": "--help, -h          Show help"
+          "description": "Run `mdkg help <command>` or `mdkg <command> --help` for details."
+        },
+        {
+          "name": "--json",
+          "value": null,
+          "required": false,
+          "description": "mdkg skill list --tags stage:plan --json"
+        },
+        {
+          "name": "--priority",
+          "value": "1",
+          "required": false,
+          "description": "mdkg new task \"...\" --status todo --priority 1"
+        },
+        {
+          "name": "--profile",
+          "value": "concise",
+          "required": false,
+          "description": "mdkg pack <id> --profile concise --dry-run --stats"
         },
         {
           "name": "--root",
@@ -3336,6 +3368,18 @@
           "required": false,
           "description": "--root, -r <path>   Run against a specific repo root"
         },
+        {
+          "name": "--status",
+          "value": "todo",
+          "required": false,
+          "description": "mdkg new task \"...\" --status todo --priority 1"
+        },
+        {
+          "name": "--tags",
+          "value": "stage:plan",
+          "required": false,
+          "description": "mdkg skill list --tags stage:plan --json"
+        },
         {
           "name": "--version",
           "value": null,
@@ -3349,24 +3393,19 @@
       ],
       "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
-        "complete-goal"
+        "none"
       ],
       "read_paths": [
         ".mdkg/**"
       ],
-      "write_paths": [
-        ".mdkg/**/*.md",
-        ".mdkg/index/**"
-      ],
+      "write_paths": [],
       "dry_run": {
         "supported": false
       },
-      "lock_policy": "mutation-lock-required",
-      "atomic_write_policy": "atomic-file-writes",
-      "receipts": [
-        "goal-state-receipt"
-      ],
-      "danger_level": "moderate",
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
+      "receipts": [],
+      "danger_level": "read-only",
       "aliases": [],
       "exit_codes": [
         {
@@ -3379,31 +3418,43 @@
         }
       ],
       "examples": [
-        "  mdkg goal done <goal-id-or-qid> [--ws <alias>] [--json]"
+        "  mdkg <command> [options]"
       ],
       "docs": {
-        "help_target": "mdkg help goal done",
+        "help_target": "mdkg --help",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
     {
-      "key": "goal evaluate",
+      "key": "goal",
       "path": [
-        "goal",
-        "evaluate"
+        "goal"
       ],
       "category": "goal",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg goal evaluate command",
+      "summary": "mdkg goal command",
       "usage": [
-        "  mdkg goal evaluate <goal-id-or-qid> [--ws <alias>] [--json]"
+        "  mdkg goal show <goal-id-or-qid> [--json]",
+        "  mdkg goal select <goal-id-or-qid> [--json]",
+        "  mdkg goal activate <goal-id-or-qid> [--json]",
+        "  mdkg goal current [--json]",
+        "  mdkg goal next [goal-id-or-qid] [--json]",
+        "  mdkg goal claim [goal-id-or-qid] <work-id-or-qid> [--json]",
+        "  mdkg goal evaluate <goal-id-or-qid> [--json]",
+        "  mdkg goal clear [--json]",
+        "  mdkg goal pause|resume|done|archive <goal-id-or-qid> [--json]"
       ],
       "args": [
         {
           "name": "goal-id-or-qid",
           "required": true,
           "source": "<goal-id-or-qid>"
+        },
+        {
+          "name": "work-id-or-qid",
+          "required": true,
+          "source": "<work-id-or-qid>"
         }
       ],
       "flags": [
@@ -3432,19 +3483,24 @@
       ],
       "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
-        "none"
+        "read-or-update-selected-goal-state"
       ],
       "read_paths": [
         ".mdkg/**"
       ],
-      "write_paths": [],
+      "write_paths": [
+        ".mdkg/**/*.md",
+        ".mdkg/index/**"
+      ],
       "dry_run": {
         "supported": false
       },
-      "lock_policy": "none-read-only",
-      "atomic_write_policy": "none-read-only",
-      "receipts": [],
-      "danger_level": "read-only",
+      "lock_policy": "mutation-lock-required-for-select-clear-claim-pause-resume-done",
+      "atomic_write_policy": "atomic-file-writes",
+      "receipts": [
+        "goal-receipt"
+      ],
+      "danger_level": "mixed",
       "aliases": [],
       "exit_codes": [
         {
@@ -3457,31 +3513,33 @@
         }
       ],
       "examples": [
-        "  mdkg goal evaluate <goal-id-or-qid> [--ws <alias>] [--json]"
+        "  mdkg goal activate <goal-id-or-qid> [--json]",
+        "  mdkg goal select <goal-id-or-qid> [--json]",
+        "  mdkg goal show <goal-id-or-qid> [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help goal evaluate",
+        "help_target": "mdkg help goal",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
     {
-      "key": "goal next",
+      "key": "goal activate",
       "path": [
         "goal",
-        "next"
+        "activate"
       ],
       "category": "goal",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg goal next command",
+      "summary": "mdkg goal activate command",
       "usage": [
-        "  mdkg goal next [goal-id-or-qid] [--ws <alias>] [--json]"
+        "  mdkg goal activate <goal-id-or-qid> [--ws <alias>] [--json]"
       ],
       "args": [
         {
           "name": "goal-id-or-qid",
-          "required": false,
-          "source": "[goal-id-or-qid]"
+          "required": true,
+          "source": "<goal-id-or-qid>"
         }
       ],
       "flags": [
@@ -3510,19 +3568,24 @@
       ],
       "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
-        "none"
+        "activate-goal-and-pause-competing-goals"
       ],
       "read_paths": [
         ".mdkg/**"
       ],
-      "write_paths": [],
+      "write_paths": [
+        ".mdkg/**/*.md",
+        ".mdkg/index/**"
+      ],
       "dry_run": {
         "supported": false
       },
-      "lock_policy": "none-read-only",
-      "atomic_write_policy": "none-read-only",
-      "receipts": [],
-      "danger_level": "read-only",
+      "lock_policy": "mutation-lock-required",
+      "atomic_write_policy": "atomic-file-writes",
+      "receipts": [
+        "goal-state-receipt"
+      ],
+      "danger_level": "moderate",
       "aliases": [],
       "exit_codes": [
         {
@@ -3535,25 +3598,25 @@
         }
       ],
       "examples": [
-        "  mdkg goal next [goal-id-or-qid] [--ws <alias>] [--json]"
+        "  mdkg goal activate <goal-id-or-qid> [--ws <alias>] [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help goal next",
+        "help_target": "mdkg help goal activate",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
     {
-      "key": "goal pause",
+      "key": "goal archive",
       "path": [
         "goal",
-        "pause"
+        "archive"
       ],
       "category": "goal",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg goal pause command",
+      "summary": "mdkg goal archive command",
       "usage": [
-        "  mdkg goal pause <goal-id-or-qid> [--ws <alias>] [--json]"
+        "  mdkg goal archive <goal-id-or-qid> [--ws <alias>] [--json]"
       ],
       "args": [
         {
@@ -3588,7 +3651,7 @@
       ],
       "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
-        "pause-goal"
+        "archive-goal"
       ],
       "read_paths": [
         ".mdkg/**"
@@ -3618,31 +3681,37 @@
         }
       ],
       "examples": [
-        "  mdkg goal pause <goal-id-or-qid> [--ws <alias>] [--json]"
+        "  mdkg goal archive <goal-id-or-qid> [--ws <alias>] [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help goal pause",
+        "help_target": "mdkg help goal archive",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
     {
-      "key": "goal resume",
+      "key": "goal claim",
       "path": [
         "goal",
-        "resume"
+        "claim"
       ],
       "category": "goal",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg goal resume command",
+      "summary": "mdkg goal claim command",
       "usage": [
-        "  mdkg goal resume <goal-id-or-qid> [--ws <alias>] [--json]"
+        "  mdkg goal claim <work-id-or-qid> [--ws <alias>] [--json]",
+        "  mdkg goal claim <goal-id-or-qid> <work-id-or-qid> [--ws <alias>] [--json]"
       ],
       "args": [
         {
           "name": "goal-id-or-qid",
           "required": true,
           "source": "<goal-id-or-qid>"
+        },
+        {
+          "name": "work-id-or-qid",
+          "required": true,
+          "source": "<work-id-or-qid>"
         }
       ],
       "flags": [
@@ -3671,7 +3740,7 @@
       ],
       "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
-        "resume-goal"
+        "claim-goal-active-node"
       ],
       "read_paths": [
         ".mdkg/**"
@@ -3701,33 +3770,28 @@
         }
       ],
       "examples": [
-        "  mdkg goal resume <goal-id-or-qid> [--ws <alias>] [--json]"
+        "  mdkg goal claim <goal-id-or-qid> <work-id-or-qid> [--ws <alias>] [--json]",
+        "  mdkg goal claim <work-id-or-qid> [--ws <alias>] [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help goal resume",
+        "help_target": "mdkg help goal claim",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
     {
-      "key": "goal select",
+      "key": "goal clear",
       "path": [
         "goal",
-        "select"
+        "clear"
       ],
       "category": "goal",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg goal select command",
+      "summary": "mdkg goal clear command",
       "usage": [
-        "  mdkg goal select <goal-id-or-qid> [--ws <alias>] [--json]"
-      ],
-      "args": [
-        {
-          "name": "goal-id-or-qid",
-          "required": true,
-          "source": "<goal-id-or-qid>"
-        }
+        "  mdkg goal clear [--json]"
       ],
+      "args": [],
       "flags": [
         {
           "name": "--help",
@@ -3754,7 +3818,7 @@
       ],
       "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
-        "select-goal"
+        "clear-selected-goal"
       ],
       "read_paths": [
         ".mdkg/**"
@@ -3784,33 +3848,27 @@
         }
       ],
       "examples": [
-        "  mdkg goal select <goal-id-or-qid> [--ws <alias>] [--json]"
+        "  mdkg goal clear [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help goal select",
+        "help_target": "mdkg help goal clear",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
     {
-      "key": "goal show",
+      "key": "goal current",
       "path": [
         "goal",
-        "show"
+        "current"
       ],
       "category": "goal",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg goal show command",
+      "summary": "mdkg goal current command",
       "usage": [
-        "  mdkg goal show <goal-id-or-qid> [--ws <alias>] [--json]"
-      ],
-      "args": [
-        {
-          "name": "goal-id-or-qid",
-          "required": true,
-          "source": "<goal-id-or-qid>"
-        }
+        "  mdkg goal current [--ws <alias>] [--json]"
       ],
+      "args": [],
       "flags": [
         {
           "name": "--help",
@@ -3862,38 +3920,31 @@
         }
       ],
       "examples": [
-        "  mdkg goal show <goal-id-or-qid> [--ws <alias>] [--json]"
+        "  mdkg goal current [--ws <alias>] [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help goal show",
+        "help_target": "mdkg help goal current",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
     {
-      "key": "graph",
+      "key": "goal done",
       "path": [
-        "graph"
+        "goal",
+        "done"
       ],
-      "category": "graph",
+      "category": "goal",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg graph command",
+      "summary": "mdkg goal done command",
       "usage": [
-        "  mdkg graph clone <source-bundle-or-mdkg-dir> --target <path> [--json]",
-        "  mdkg graph fork <source-bundle-or-mdkg-dir> --target <path> [--start-goal <goal-id>] [--json]",
-        "  mdkg graph import-template <source-bundle-or-mdkg-dir> [--start-goal <goal-id>] [--select-goal] [--id-prefix <prefix>] [--dry-run] [--apply] [--json]",
-        "  mdkg graph refs <id-or-qid> [--ws <alias>] [--json]"
+        "  mdkg goal done <goal-id-or-qid> [--ws <alias>] [--json]"
       ],
       "args": [
         {
-          "name": "id-or-qid",
-          "required": true,
-          "source": "<id-or-qid>"
-        },
-        {
-          "name": "source-bundle-or-mdkg-dir",
+          "name": "goal-id-or-qid",
           "required": true,
-          "source": "<source-bundle-or-mdkg-dir>"
+          "source": "<goal-id-or-qid>"
         }
       ],
       "flags": [
@@ -3909,12 +3960,6 @@
           "required": false,
           "description": "--root, -r <path>   Run against a specific repo root"
         },
-        {
-          "name": "--target",
-          "value": "<path>",
-          "required": false,
-          "description": "mdkg graph clone <source-bundle-or-mdkg-dir> --target <path> [--json]"
-        },
         {
           "name": "--version",
           "value": null,
@@ -3928,19 +3973,24 @@
       ],
       "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
-        "none"
+        "complete-goal"
       ],
       "read_paths": [
         ".mdkg/**"
       ],
-      "write_paths": [],
+      "write_paths": [
+        ".mdkg/**/*.md",
+        ".mdkg/index/**"
+      ],
       "dry_run": {
         "supported": false
       },
-      "lock_policy": "none-read-only",
-      "atomic_write_policy": "none-read-only",
-      "receipts": [],
-      "danger_level": "read-only",
+      "lock_policy": "mutation-lock-required",
+      "atomic_write_policy": "atomic-file-writes",
+      "receipts": [
+        "goal-state-receipt"
+      ],
+      "danger_level": "moderate",
       "aliases": [],
       "exit_codes": [
         {
@@ -3953,33 +4003,31 @@
         }
       ],
       "examples": [
-        "  mdkg graph clone <source-bundle-or-mdkg-dir> --target <path> [--json]",
-        "  mdkg graph fork <source-bundle-or-mdkg-dir> --target <path> [--start-goal <goal-id>] [--json]",
-        "  mdkg graph import-template <source-bundle-or-mdkg-dir> [--start-goal <goal-id>] [--select-goal] [--id-prefix <prefix>] [--dry-run] [--apply] [--json]"
+        "  mdkg goal done <goal-id-or-qid> [--ws <alias>] [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help graph",
+        "help_target": "mdkg help goal done",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
     {
-      "key": "graph clone",
+      "key": "goal evaluate",
       "path": [
-        "graph",
-        "clone"
+        "goal",
+        "evaluate"
       ],
-      "category": "graph",
+      "category": "goal",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg graph clone command",
+      "summary": "mdkg goal evaluate command",
       "usage": [
-        "  mdkg graph clone <source-bundle-or-mdkg-dir> --target <path> [--json]"
+        "  mdkg goal evaluate <goal-id-or-qid> [--ws <alias>] [--json]"
       ],
       "args": [
         {
-          "name": "source-bundle-or-mdkg-dir",
+          "name": "goal-id-or-qid",
           "required": true,
-          "source": "<source-bundle-or-mdkg-dir>"
+          "source": "<goal-id-or-qid>"
         }
       ],
       "flags": [
@@ -3995,12 +4043,6 @@
           "required": false,
           "description": "--root, -r <path>   Run against a specific repo root"
         },
-        {
-          "name": "--target",
-          "value": "<path>",
-          "required": false,
-          "description": "mdkg graph clone <source-bundle-or-mdkg-dir> --target <path> [--json]"
-        },
         {
           "name": "--version",
           "value": null,
@@ -4039,31 +4081,31 @@
         }
       ],
       "examples": [
-        "  mdkg graph clone <source-bundle-or-mdkg-dir> --target <path> [--json]"
+        "  mdkg goal evaluate <goal-id-or-qid> [--ws <alias>] [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help graph clone",
+        "help_target": "mdkg help goal evaluate",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
     {
-      "key": "graph fork",
+      "key": "goal next",
       "path": [
-        "graph",
-        "fork"
+        "goal",
+        "next"
       ],
-      "category": "graph",
+      "category": "goal",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg graph fork command",
+      "summary": "mdkg goal next command",
       "usage": [
-        "  mdkg graph fork <source-bundle-or-mdkg-dir> --target <path> [--start-goal <goal-id>] [--json]"
+        "  mdkg goal next [goal-id-or-qid] [--ws <alias>] [--json]"
       ],
       "args": [
         {
-          "name": "source-bundle-or-mdkg-dir",
-          "required": true,
-          "source": "<source-bundle-or-mdkg-dir>"
+          "name": "goal-id-or-qid",
+          "required": false,
+          "source": "[goal-id-or-qid]"
         }
       ],
       "flags": [
@@ -4079,12 +4121,6 @@
           "required": false,
           "description": "--root, -r <path>   Run against a specific repo root"
         },
-        {
-          "name": "--target",
-          "value": "<path>",
-          "required": false,
-          "description": "mdkg graph fork <source-bundle-or-mdkg-dir> --target <path> [--start-goal <goal-id>] [--json]"
-        },
         {
           "name": "--version",
           "value": null,
@@ -4123,40 +4159,34 @@
         }
       ],
       "examples": [
-        "  mdkg graph fork <source-bundle-or-mdkg-dir> --target <path> [--start-goal <goal-id>] [--json]"
+        "  mdkg goal next [goal-id-or-qid] [--ws <alias>] [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help graph fork",
+        "help_target": "mdkg help goal next",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
     {
-      "key": "graph import-template",
+      "key": "goal pause",
       "path": [
-        "graph",
-        "import-template"
+        "goal",
+        "pause"
       ],
-      "category": "graph",
+      "category": "goal",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg graph import-template command",
+      "summary": "mdkg goal pause command",
       "usage": [
-        "  mdkg graph import-template <source-bundle-or-mdkg-dir> [--start-goal <goal-id>] [--select-goal] [--id-prefix <prefix>] [--dry-run] [--apply] [--json]"
+        "  mdkg goal pause <goal-id-or-qid> [--ws <alias>] [--json]"
       ],
       "args": [
         {
-          "name": "source-bundle-or-mdkg-dir",
+          "name": "goal-id-or-qid",
           "required": true,
-          "source": "<source-bundle-or-mdkg-dir>"
+          "source": "<goal-id-or-qid>"
         }
       ],
       "flags": [
-        {
-          "name": "--apply",
-          "value": "is",
-          "required": false,
-          "description": "- defaults to dry-run unless --apply is supplied"
-        },
         {
           "name": "--help",
           "value": null,
@@ -4169,18 +4199,6 @@
           "required": false,
           "description": "--root, -r <path>   Run against a specific repo root"
         },
-        {
-          "name": "--select-goal",
-          "value": "requires",
-          "required": false,
-          "description": "- --select-goal requires --start-goal; on apply it activates the imported start goal, pauses competing active root goals, validates, then writes selected-goal state"
-        },
-        {
-          "name": "--start-goal",
-          "value": null,
-          "required": false,
-          "description": "- --select-goal requires --start-goal; on apply it activates the imported start goal, pauses competing active root goals, validates, then writes selected-goal state"
-        },
         {
           "name": "--version",
           "value": null,
@@ -4194,19 +4212,24 @@
       ],
       "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
-        "none"
+        "pause-goal"
       ],
       "read_paths": [
         ".mdkg/**"
       ],
-      "write_paths": [],
+      "write_paths": [
+        ".mdkg/**/*.md",
+        ".mdkg/index/**"
+      ],
       "dry_run": {
         "supported": false
       },
-      "lock_policy": "none-read-only",
-      "atomic_write_policy": "none-read-only",
-      "receipts": [],
-      "danger_level": "read-only",
+      "lock_policy": "mutation-lock-required",
+      "atomic_write_policy": "atomic-file-writes",
+      "receipts": [
+        "goal-state-receipt"
+      ],
+      "danger_level": "moderate",
       "aliases": [],
       "exit_codes": [
         {
@@ -4219,31 +4242,31 @@
         }
       ],
       "examples": [
-        "  mdkg graph import-template <source-bundle-or-mdkg-dir> [--start-goal <goal-id>] [--select-goal] [--id-prefix <prefix>] [--dry-run] [--apply] [--json]"
+        "  mdkg goal pause <goal-id-or-qid> [--ws <alias>] [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help graph import-template",
+        "help_target": "mdkg help goal pause",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
     {
-      "key": "graph refs",
+      "key": "goal resume",
       "path": [
-        "graph",
-        "refs"
+        "goal",
+        "resume"
       ],
-      "category": "graph",
+      "category": "goal",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg graph refs command",
+      "summary": "mdkg goal resume command",
       "usage": [
-        "  mdkg graph refs <id-or-qid> [--ws <alias>] [--json]"
+        "  mdkg goal resume <goal-id-or-qid> [--ws <alias>] [--json]"
       ],
       "args": [
         {
-          "name": "id-or-qid",
+          "name": "goal-id-or-qid",
           "required": true,
-          "source": "<id-or-qid>"
+          "source": "<goal-id-or-qid>"
         }
       ],
       "flags": [
@@ -4272,21 +4295,24 @@
       ],
       "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
-        "none"
+        "resume-goal"
       ],
       "read_paths": [
         ".mdkg/**"
       ],
-      "write_paths": [],
+      "write_paths": [
+        ".mdkg/**/*.md",
+        ".mdkg/index/**"
+      ],
       "dry_run": {
         "supported": false
       },
-      "lock_policy": "none-read-only",
-      "atomic_write_policy": "none-read-only",
+      "lock_policy": "mutation-lock-required",
+      "atomic_write_policy": "atomic-file-writes",
       "receipts": [
-        "graph-refs-receipt"
+        "goal-state-receipt"
       ],
-      "danger_level": "read-only",
+      "danger_level": "moderate",
       "aliases": [],
       "exit_codes": [
         {
@@ -4299,26 +4325,33 @@
         }
       ],
       "examples": [
-        "  mdkg graph refs <id-or-qid> [--ws <alias>] [--json]"
+        "  mdkg goal resume <goal-id-or-qid> [--ws <alias>] [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help graph refs",
+        "help_target": "mdkg help goal resume",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
     {
-      "key": "guide",
+      "key": "goal select",
       "path": [
-        "guide"
+        "goal",
+        "select"
       ],
-      "category": "guide",
+      "category": "goal",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg guide command",
+      "summary": "mdkg goal select command",
       "usage": [
-        "  mdkg guide"
+        "  mdkg goal select <goal-id-or-qid> [--ws <alias>] [--json]"
+      ],
+      "args": [
+        {
+          "name": "goal-id-or-qid",
+          "required": true,
+          "source": "<goal-id-or-qid>"
+        }
       ],
-      "args": [],
       "flags": [
         {
           "name": "--help",
@@ -4340,23 +4373,29 @@
         }
       ],
       "output_formats": [
-        "text"
+        "text",
+        "json"
       ],
-      "json_schema_ref": null,
+      "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
-        "none"
+        "select-goal"
       ],
       "read_paths": [
         ".mdkg/**"
       ],
-      "write_paths": [],
+      "write_paths": [
+        ".mdkg/**/*.md",
+        ".mdkg/index/**"
+      ],
       "dry_run": {
         "supported": false
       },
-      "lock_policy": "none-read-only",
-      "atomic_write_policy": "none-read-only",
-      "receipts": [],
-      "danger_level": "read-only",
+      "lock_policy": "mutation-lock-required",
+      "atomic_write_policy": "atomic-file-writes",
+      "receipts": [
+        "goal-state-receipt"
+      ],
+      "danger_level": "moderate",
       "aliases": [],
       "exit_codes": [
         {
@@ -4369,30 +4408,31 @@
         }
       ],
       "examples": [
-        "  mdkg guide"
+        "  mdkg goal select <goal-id-or-qid> [--ws <alias>] [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help guide",
+        "help_target": "mdkg help goal select",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
     {
-      "key": "handoff",
+      "key": "goal show",
       "path": [
-        "handoff"
+        "goal",
+        "show"
       ],
-      "category": "handoff",
+      "category": "goal",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg handoff command",
+      "summary": "mdkg goal show command",
       "usage": [
-        "  mdkg handoff create <id-or-qid> [--ws <alias>] [--depth <n>] [--out <path>] [--json]"
+        "  mdkg goal show <goal-id-or-qid> [--ws <alias>] [--json]"
       ],
       "args": [
         {
-          "name": "id-or-qid",
+          "name": "goal-id-or-qid",
           "required": true,
-          "source": "<id-or-qid>"
+          "source": "<goal-id-or-qid>"
         }
       ],
       "flags": [
@@ -4402,12 +4442,6 @@
           "required": false,
           "description": "--help, -h          Show help"
         },
-        {
-          "name": "--out",
-          "value": "must",
-          "required": false,
-          "description": "- --out must stay inside the repo root"
-        },
         {
           "name": "--root",
           "value": null,
@@ -4425,25 +4459,1235 @@
         "text",
         "json"
       ],
-      "json_schema_ref": "mdkg.handoff.v1",
+      "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
-        "create-sanitized-agent-handoff-when-out-is-provided"
+        "none"
       ],
       "read_paths": [
         ".mdkg/**"
       ],
-      "write_paths": [
-        ".mdkg/handoffs/**"
-      ],
+      "write_paths": [],
       "dry_run": {
         "supported": false
       },
-      "lock_policy": "not-required-for-stdout-output",
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
+      "receipts": [],
+      "danger_level": "read-only",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg goal show <goal-id-or-qid> [--ws <alias>] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help goal show",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
+    {
+      "key": "graph",
+      "path": [
+        "graph"
+      ],
+      "category": "graph",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg graph command",
+      "usage": [
+        "  mdkg graph clone <source-bundle-or-mdkg-dir> --target <path> [--json]",
+        "  mdkg graph fork <source-bundle-or-mdkg-dir> --target <path> [--start-goal <goal-id>] [--json]",
+        "  mdkg graph import-template <source-bundle-or-mdkg-dir> [--start-goal <goal-id>] [--select-goal] [--id-prefix <prefix>] [--dry-run] [--apply] [--json]",
+        "  mdkg graph refs <id-or-qid> [--ws <alias>] [--json]"
+      ],
+      "args": [
+        {
+          "name": "id-or-qid",
+          "required": true,
+          "source": "<id-or-qid>"
+        },
+        {
+          "name": "source-bundle-or-mdkg-dir",
+          "required": true,
+          "source": "<source-bundle-or-mdkg-dir>"
+        }
+      ],
+      "flags": [
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--target",
+          "value": "<path>",
+          "required": false,
+          "description": "mdkg graph clone <source-bundle-or-mdkg-dir> --target <path> [--json]"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json"
+      ],
+      "json_schema_ref": "mdkg.command_output.v1",
+      "side_effects": [
+        "none"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
+      "receipts": [],
+      "danger_level": "read-only",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg graph clone <source-bundle-or-mdkg-dir> --target <path> [--json]",
+        "  mdkg graph fork <source-bundle-or-mdkg-dir> --target <path> [--start-goal <goal-id>] [--json]",
+        "  mdkg graph import-template <source-bundle-or-mdkg-dir> [--start-goal <goal-id>] [--select-goal] [--id-prefix <prefix>] [--dry-run] [--apply] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help graph",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
+    {
+      "key": "graph clone",
+      "path": [
+        "graph",
+        "clone"
+      ],
+      "category": "graph",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg graph clone command",
+      "usage": [
+        "  mdkg graph clone <source-bundle-or-mdkg-dir> --target <path> [--json]"
+      ],
+      "args": [
+        {
+          "name": "source-bundle-or-mdkg-dir",
+          "required": true,
+          "source": "<source-bundle-or-mdkg-dir>"
+        }
+      ],
+      "flags": [
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--target",
+          "value": "<path>",
+          "required": false,
+          "description": "mdkg graph clone <source-bundle-or-mdkg-dir> --target <path> [--json]"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json"
+      ],
+      "json_schema_ref": "mdkg.command_output.v1",
+      "side_effects": [
+        "none"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
+      "receipts": [],
+      "danger_level": "read-only",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg graph clone <source-bundle-or-mdkg-dir> --target <path> [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help graph clone",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
+    {
+      "key": "graph fork",
+      "path": [
+        "graph",
+        "fork"
+      ],
+      "category": "graph",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg graph fork command",
+      "usage": [
+        "  mdkg graph fork <source-bundle-or-mdkg-dir> --target <path> [--start-goal <goal-id>] [--json]"
+      ],
+      "args": [
+        {
+          "name": "source-bundle-or-mdkg-dir",
+          "required": true,
+          "source": "<source-bundle-or-mdkg-dir>"
+        }
+      ],
+      "flags": [
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--target",
+          "value": "<path>",
+          "required": false,
+          "description": "mdkg graph fork <source-bundle-or-mdkg-dir> --target <path> [--start-goal <goal-id>] [--json]"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json"
+      ],
+      "json_schema_ref": "mdkg.command_output.v1",
+      "side_effects": [
+        "none"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
+      "receipts": [],
+      "danger_level": "read-only",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg graph fork <source-bundle-or-mdkg-dir> --target <path> [--start-goal <goal-id>] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help graph fork",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
+    {
+      "key": "graph import-template",
+      "path": [
+        "graph",
+        "import-template"
+      ],
+      "category": "graph",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg graph import-template command",
+      "usage": [
+        "  mdkg graph import-template <source-bundle-or-mdkg-dir> [--start-goal <goal-id>] [--select-goal] [--id-prefix <prefix>] [--dry-run] [--apply] [--json]"
+      ],
+      "args": [
+        {
+          "name": "source-bundle-or-mdkg-dir",
+          "required": true,
+          "source": "<source-bundle-or-mdkg-dir>"
+        }
+      ],
+      "flags": [
+        {
+          "name": "--apply",
+          "value": "is",
+          "required": false,
+          "description": "- defaults to dry-run unless --apply is supplied"
+        },
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--select-goal",
+          "value": "requires",
+          "required": false,
+          "description": "- --select-goal requires --start-goal; on apply it activates the imported start goal, pauses competing active root goals, validates, then writes selected-goal state"
+        },
+        {
+          "name": "--start-goal",
+          "value": null,
+          "required": false,
+          "description": "- --select-goal requires --start-goal; on apply it activates the imported start goal, pauses competing active root goals, validates, then writes selected-goal state"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json"
+      ],
+      "json_schema_ref": "mdkg.command_output.v1",
+      "side_effects": [
+        "none"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
+      "receipts": [],
+      "danger_level": "read-only",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg graph import-template <source-bundle-or-mdkg-dir> [--start-goal <goal-id>] [--select-goal] [--id-prefix <prefix>] [--dry-run] [--apply] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help graph import-template",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
+    {
+      "key": "graph refs",
+      "path": [
+        "graph",
+        "refs"
+      ],
+      "category": "graph",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg graph refs command",
+      "usage": [
+        "  mdkg graph refs <id-or-qid> [--ws <alias>] [--json]"
+      ],
+      "args": [
+        {
+          "name": "id-or-qid",
+          "required": true,
+          "source": "<id-or-qid>"
+        }
+      ],
+      "flags": [
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json"
+      ],
+      "json_schema_ref": "mdkg.command_output.v1",
+      "side_effects": [
+        "none"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
+      "receipts": [
+        "graph-refs-receipt"
+      ],
+      "danger_level": "read-only",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg graph refs <id-or-qid> [--ws <alias>] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help graph refs",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
+    {
+      "key": "guide",
+      "path": [
+        "guide"
+      ],
+      "category": "guide",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg guide command",
+      "usage": [
+        "  mdkg guide"
+      ],
+      "args": [],
+      "flags": [
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text"
+      ],
+      "json_schema_ref": null,
+      "side_effects": [
+        "none"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
+      "receipts": [],
+      "danger_level": "read-only",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg guide"
+      ],
+      "docs": {
+        "help_target": "mdkg help guide",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
+    {
+      "key": "handoff",
+      "path": [
+        "handoff"
+      ],
+      "category": "handoff",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg handoff command",
+      "usage": [
+        "  mdkg handoff create <id-or-qid> [--ws <alias>] [--depth <n>] [--out <path>] [--json]"
+      ],
+      "args": [
+        {
+          "name": "id-or-qid",
+          "required": true,
+          "source": "<id-or-qid>"
+        }
+      ],
+      "flags": [
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--out",
+          "value": "must",
+          "required": false,
+          "description": "- --out must stay inside the repo root"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json"
+      ],
+      "json_schema_ref": "mdkg.handoff.v1",
+      "side_effects": [
+        "create-sanitized-agent-handoff-when-out-is-provided"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [
+        ".mdkg/handoffs/**"
+      ],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "not-required-for-stdout-output",
       "atomic_write_policy": "atomic-file-write-when-out-is-provided",
       "receipts": [
-        "handoff-receipt"
+        "handoff-receipt"
+      ],
+      "danger_level": "moderate",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg handoff create <id-or-qid> [--ws <alias>] [--depth <n>] [--out <path>] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help handoff",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
+    {
+      "key": "index",
+      "path": [
+        "index"
+      ],
+      "category": "index",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg index command",
+      "usage": [
+        "  mdkg index [--tolerant]"
+      ],
+      "args": [],
+      "flags": [
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text"
+      ],
+      "json_schema_ref": null,
+      "side_effects": [
+        "rebuild-generated-index-cache"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [
+        ".mdkg/index/**"
+      ],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "mutation-lock-required",
+      "atomic_write_policy": "sqlite-transaction-and-atomic-cache-write",
+      "receipts": [
+        "index-rebuild-receipt"
+      ],
+      "danger_level": "moderate",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg index [--tolerant]"
+      ],
+      "docs": {
+        "help_target": "mdkg help index",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
+    {
+      "key": "init",
+      "path": [
+        "init"
+      ],
+      "category": "init",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg init command",
+      "usage": [
+        "  mdkg init [options]"
+      ],
+      "args": [
+        {
+          "name": "options",
+          "required": false,
+          "source": "[options]"
+        }
+      ],
+      "flags": [
+        {
+          "name": "--agent",
+          "value": null,
+          "required": false,
+          "description": "--agent               Create the complete agent bootstrap, skills, events, and mirrors"
+        },
+        {
+          "name": "--force",
+          "value": null,
+          "required": false,
+          "description": "--force               Overwrite existing mdkg files"
+        },
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--no-update-ignores",
+          "value": null,
+          "required": false,
+          "description": "--no-update-ignores   Skip default .gitignore/.npmignore updates"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--update-dockerignore",
+          "value": "Append",
+          "required": false,
+          "description": "--update-dockerignore Append mdkg ignore entries"
+        },
+        {
+          "name": "--update-gitignore",
+          "value": null,
+          "required": false,
+          "description": "--update-gitignore    Append mdkg ignore entries"
+        },
+        {
+          "name": "--update-npmignore",
+          "value": null,
+          "required": false,
+          "description": "--update-npmignore    Append mdkg ignore entries"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text"
+      ],
+      "json_schema_ref": null,
+      "side_effects": [
+        "initialize-mdkg-scaffold"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [
+        ".mdkg/**",
+        "AGENTS.md",
+        "AGENT_START.md",
+        "CLAUDE.md",
+        "CLI_COMMAND_MATRIX.md",
+        "llms.txt"
+      ],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "not-required-before-mdkg-config-exists",
+      "atomic_write_policy": "exclusive-create-and-atomic-file-writes",
+      "receipts": [
+        "init-summary"
+      ],
+      "danger_level": "moderate",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg init [options]"
+      ],
+      "docs": {
+        "help_target": "mdkg help init",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
+    {
+      "key": "list",
+      "path": [
+        "list"
+      ],
+      "category": "list",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg list command",
+      "usage": [
+        "  mdkg list [--type <type>] [--status <status>] [--ws <alias>] [--epic <id>]"
+      ],
+      "args": [],
+      "flags": [
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json",
+        "xml",
+        "toon",
+        "md"
+      ],
+      "json_schema_ref": "mdkg.command_output.v1",
+      "side_effects": [
+        "none"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
+      "receipts": [],
+      "danger_level": "read-only",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg list [--type <type>] [--status <status>] [--ws <alias>] [--epic <id>]"
+      ],
+      "docs": {
+        "help_target": "mdkg help list",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
+    {
+      "key": "loop",
+      "path": [
+        "loop"
+      ],
+      "category": "loop",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg loop command",
+      "usage": [
+        "mdkg loop list [--ws <alias>] [--json]",
+        "mdkg loop show <loop-or-template> [--meta] [--ws <alias>] [--json]",
+        "mdkg loop fork <template> --scope <scope> [--title <title>] [--materialization default_children|planning_only|manual] [--planning-only] [--no-children] [--dry-run] [--run-id <id>] [--ws <alias>] [--json]",
+        "mdkg loop plan <loop> [--ws <alias>] [--json]",
+        "mdkg loop next <loop> [--ws <alias>] [--json]",
+        "mdkg loop runs <loop> [--ws <alias>] [--json]"
+      ],
+      "args": [],
+      "flags": [
+        {
+          "name": "--root",
+          "value": "<path>",
+          "required": false,
+          "description": "Run against a specific repository root; -r is the short alias."
+        },
+        {
+          "name": "--ws",
+          "value": "<alias>",
+          "required": false,
+          "description": "Resolve the command against one workspace alias."
+        },
+        {
+          "name": "--json",
+          "value": null,
+          "required": false,
+          "description": "Emit deterministic JSON instead of text."
+        },
+        {
+          "name": "--no-cache",
+          "value": null,
+          "required": false,
+          "description": "Build a non-persisting in-memory index projection instead of reading the cache."
+        },
+        {
+          "name": "--no-reindex",
+          "value": null,
+          "required": false,
+          "description": "Do not rebuild a stale or missing index projection."
+        },
+        {
+          "name": "--run-id",
+          "value": "<id>",
+          "required": false,
+          "description": "Attach an optional run id to the fork event when event logging is enabled."
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json"
+      ],
+      "json_schema_ref": "mdkg.command_output.v1",
+      "side_effects": [
+        "read-or-write-loop-graph-state"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [
+        ".mdkg/**/*.md",
+        ".mdkg/events/*.jsonl",
+        ".mdkg/index/**"
+      ],
+      "dry_run": {
+        "supported": true,
+        "commands": [
+          "fork"
+        ]
+      },
+      "lock_policy": "mutation-lock-required-for-fork",
+      "atomic_write_policy": "exclusive-create-and-atomic-file-writes",
+      "receipts": [
+        "loop-receipt"
+      ],
+      "danger_level": "mixed",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "mdkg loop fork <template> --scope <scope> [--title <title>] [--materialization default_children|planning_only|manual] [--planning-only] [--no-children] [--dry-run] [--run-id <id>] [--ws <alias>] [--json]",
+        "mdkg loop list [--ws <alias>] [--json]",
+        "mdkg loop show <loop-or-template> [--meta] [--ws <alias>] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help loop",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      },
+      "descriptor_source": "src/commands/loop_descriptors.ts",
+      "handler": "runLoopSubcommand",
+      "help_notes": [
+        "loop is one first-class node type. Templates, scoped forks, and run-bearing loops are represented through metadata and links.",
+        "mdkg defines reusable process state and graph context; runtimes execute agents, tools, sandboxes, traces, and model routing."
+      ]
+    },
+    {
+      "key": "loop fork",
+      "path": [
+        "loop",
+        "fork"
+      ],
+      "category": "loop",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg loop fork command",
+      "usage": [
+        "mdkg loop fork <template> --scope <scope> [--title <title>] [--materialization <mode>] [--planning-only] [--no-children] [--dry-run] [--run-id <id>] [--ws <alias>] [--no-cache] [--no-reindex] [--json]"
+      ],
+      "args": [
+        {
+          "name": "template",
+          "required": true,
+          "source": "<template>",
+          "description": "Loop template node id/qid or seed template name/ref."
+        }
+      ],
+      "flags": [
+        {
+          "name": "--scope",
+          "value": "<scope>",
+          "required": true,
+          "description": "Scope ref, qid, URI, path, or description for the scoped loop."
+        },
+        {
+          "name": "--title",
+          "value": "<title>",
+          "required": false,
+          "description": "Override the generated scoped loop title."
+        },
+        {
+          "name": "--materialization",
+          "value": "<mode>",
+          "required": false,
+          "description": "Child materialization mode: default_children, planning_only, or manual."
+        },
+        {
+          "name": "--planning-only",
+          "value": null,
+          "required": false,
+          "description": "Create only the scoped loop shell."
+        },
+        {
+          "name": "--no-children",
+          "value": null,
+          "required": false,
+          "description": "Alias for planning-only materialization."
+        },
+        {
+          "name": "--dry-run",
+          "value": null,
+          "required": false,
+          "description": "Plan the fork without writing loop or child nodes."
+        },
+        {
+          "name": "--run-id",
+          "value": "<id>",
+          "required": false,
+          "description": "Attach an optional run id to the fork event when event logging is enabled."
+        },
+        {
+          "name": "--root",
+          "value": "<path>",
+          "required": false,
+          "description": "Run against a specific repository root; -r is the short alias."
+        },
+        {
+          "name": "--ws",
+          "value": "<alias>",
+          "required": false,
+          "description": "Resolve the command against one workspace alias."
+        },
+        {
+          "name": "--json",
+          "value": null,
+          "required": false,
+          "description": "Emit deterministic JSON instead of text."
+        },
+        {
+          "name": "--no-cache",
+          "value": null,
+          "required": false,
+          "description": "Build a non-persisting in-memory index projection instead of reading the cache."
+        },
+        {
+          "name": "--no-reindex",
+          "value": null,
+          "required": false,
+          "description": "Do not rebuild a stale or missing index projection."
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json"
+      ],
+      "json_schema_ref": "mdkg.command_output.v1",
+      "side_effects": [
+        "append-loop-fork-event-when-event-logging-is-enabled",
+        "create-scoped-loop-and-optional-child-nodes",
+        "rebuild-derived-indexes-when-auto-reindex-is-enabled",
+        "reserve-sqlite-node-ids-when-configured"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [
+        ".mdkg/**/*.md",
+        ".mdkg/events/*.jsonl",
+        ".mdkg/index/**"
+      ],
+      "dry_run": {
+        "supported": true,
+        "flag": "--dry-run",
+        "side_effects": [
+          "none"
+        ],
+        "write_paths": [],
+        "reserves_ids": false
+      },
+      "lock_policy": "mutation-lock-required",
+      "atomic_write_policy": "exclusive-create-and-atomic-file-writes",
+      "receipts": [
+        "loop-fork-receipt"
+      ],
+      "danger_level": "moderate",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "mdkg loop fork <template> --scope <scope> [--title <title>] [--materialization <mode>] [--planning-only] [--no-children] [--dry-run] [--run-id <id>] [--ws <alias>] [--no-cache] [--no-reindex] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help loop fork",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      },
+      "descriptor_source": "src/commands/loop_descriptors.ts",
+      "handler": "runLoopForkCommand",
+      "help_notes": [
+        "Seed templates resolve from .mdkg/templates/loops/<name>.loop.md.",
+        "Default forks create a scoped loop plus linked spike/task/test child nodes."
+      ]
+    },
+    {
+      "key": "loop list",
+      "path": [
+        "loop",
+        "list"
+      ],
+      "category": "loop",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg loop list command",
+      "usage": [
+        "mdkg loop list [--ws <alias>] [--no-cache] [--no-reindex] [--json]"
+      ],
+      "args": [],
+      "flags": [
+        {
+          "name": "--root",
+          "value": "<path>",
+          "required": false,
+          "description": "Run against a specific repository root; -r is the short alias."
+        },
+        {
+          "name": "--ws",
+          "value": "<alias>",
+          "required": false,
+          "description": "Resolve the command against one workspace alias."
+        },
+        {
+          "name": "--json",
+          "value": null,
+          "required": false,
+          "description": "Emit deterministic JSON instead of text."
+        },
+        {
+          "name": "--no-cache",
+          "value": null,
+          "required": false,
+          "description": "Build a non-persisting in-memory index projection instead of reading the cache."
+        },
+        {
+          "name": "--no-reindex",
+          "value": null,
+          "required": false,
+          "description": "Do not rebuild a stale or missing index projection."
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json"
+      ],
+      "json_schema_ref": "mdkg.command_output.v1",
+      "side_effects": [
+        "none"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
+      "receipts": [
+        "loop-list-receipt"
       ],
-      "danger_level": "moderate",
+      "danger_level": "read-only",
       "aliases": [],
       "exit_codes": [
         {
@@ -4456,68 +5700,92 @@
         }
       ],
       "examples": [
-        "  mdkg handoff create <id-or-qid> [--ws <alias>] [--depth <n>] [--out <path>] [--json]"
+        "mdkg loop list [--ws <alias>] [--no-cache] [--no-reindex] [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help handoff",
+        "help_target": "mdkg help loop list",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
-      }
+      },
+      "descriptor_source": "src/commands/loop_descriptors.ts",
+      "handler": "runLoopListCommand",
+      "help_notes": [
+        "Lists indexed loop nodes and reusable seed loop templates."
+      ]
     },
     {
-      "key": "index",
+      "key": "loop next",
       "path": [
-        "index"
+        "loop",
+        "next"
       ],
-      "category": "index",
+      "category": "loop",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg index command",
+      "summary": "mdkg loop next command",
       "usage": [
-        "  mdkg index [--tolerant]"
+        "mdkg loop next <loop> [--ws <alias>] [--no-cache] [--no-reindex] [--json]"
+      ],
+      "args": [
+        {
+          "name": "loop",
+          "required": true,
+          "source": "<loop>",
+          "description": "Loop node id or qid."
+        }
       ],
-      "args": [],
       "flags": [
         {
-          "name": "--help",
+          "name": "--root",
+          "value": "<path>",
+          "required": false,
+          "description": "Run against a specific repository root; -r is the short alias."
+        },
+        {
+          "name": "--ws",
+          "value": "<alias>",
+          "required": false,
+          "description": "Resolve the command against one workspace alias."
+        },
+        {
+          "name": "--json",
           "value": null,
           "required": false,
-          "description": "--help, -h          Show help"
+          "description": "Emit deterministic JSON instead of text."
         },
         {
-          "name": "--root",
+          "name": "--no-cache",
           "value": null,
           "required": false,
-          "description": "--root, -r <path>   Run against a specific repo root"
+          "description": "Build a non-persisting in-memory index projection instead of reading the cache."
         },
         {
-          "name": "--version",
+          "name": "--no-reindex",
           "value": null,
           "required": false,
-          "description": "--version, -V       Show version"
+          "description": "Do not rebuild a stale or missing index projection."
         }
       ],
       "output_formats": [
-        "text"
+        "text",
+        "json"
       ],
-      "json_schema_ref": null,
+      "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
-        "rebuild-generated-index-cache"
+        "none"
       ],
       "read_paths": [
         ".mdkg/**"
       ],
-      "write_paths": [
-        ".mdkg/index/**"
-      ],
+      "write_paths": [],
       "dry_run": {
         "supported": false
       },
-      "lock_policy": "mutation-lock-required",
-      "atomic_write_policy": "sqlite-transaction-and-atomic-cache-write",
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
       "receipts": [
-        "index-rebuild-receipt"
+        "loop-next-receipt"
       ],
-      "danger_level": "moderate",
+      "danger_level": "read-only",
       "aliases": [],
       "exit_codes": [
         {
@@ -4530,115 +5798,190 @@
         }
       ],
       "examples": [
-        "  mdkg index [--tolerant]"
+        "mdkg loop next <loop> [--ws <alias>] [--no-cache] [--no-reindex] [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help index",
+        "help_target": "mdkg help loop next",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
-      }
+      },
+      "descriptor_source": "src/commands/loop_descriptors.ts",
+      "handler": "runLoopNextCommand",
+      "help_notes": [
+        "Read-only routing for the next actionable child, readiness lane, or blocker recovery step."
+      ]
     },
     {
-      "key": "init",
+      "key": "loop plan",
       "path": [
-        "init"
+        "loop",
+        "plan"
       ],
-      "category": "init",
+      "category": "loop",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg init command",
+      "summary": "mdkg loop plan command",
       "usage": [
-        "  mdkg init [options]"
+        "mdkg loop plan <loop> [--ws <alias>] [--no-cache] [--no-reindex] [--json]"
       ],
       "args": [
         {
-          "name": "options",
-          "required": false,
-          "source": "[options]"
+          "name": "loop",
+          "required": true,
+          "source": "<loop>",
+          "description": "Loop node id or qid."
         }
       ],
       "flags": [
         {
-          "name": "--agent",
-          "value": null,
+          "name": "--root",
+          "value": "<path>",
           "required": false,
-          "description": "--agent               Create the complete agent bootstrap, skills, events, and mirrors"
+          "description": "Run against a specific repository root; -r is the short alias."
         },
         {
-          "name": "--force",
+          "name": "--ws",
+          "value": "<alias>",
+          "required": false,
+          "description": "Resolve the command against one workspace alias."
+        },
+        {
+          "name": "--json",
           "value": null,
           "required": false,
-          "description": "--force               Overwrite existing mdkg files"
+          "description": "Emit deterministic JSON instead of text."
         },
         {
-          "name": "--help",
+          "name": "--no-cache",
           "value": null,
           "required": false,
-          "description": "--help, -h          Show help"
+          "description": "Build a non-persisting in-memory index projection instead of reading the cache."
         },
         {
-          "name": "--no-update-ignores",
+          "name": "--no-reindex",
           "value": null,
           "required": false,
-          "description": "--no-update-ignores   Skip default .gitignore/.npmignore updates"
+          "description": "Do not rebuild a stale or missing index projection."
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json"
+      ],
+      "json_schema_ref": "mdkg.command_output.v1",
+      "side_effects": [
+        "none"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
+      "receipts": [
+        "loop-plan-receipt"
+      ],
+      "danger_level": "read-only",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
         },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "mdkg loop plan <loop> [--ws <alias>] [--no-cache] [--no-reindex] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help loop plan",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      },
+      "descriptor_source": "src/commands/loop_descriptors.ts",
+      "handler": "runLoopPlanCommand",
+      "help_notes": [
+        "Read-only readiness cockpit for loop execution planning."
+      ]
+    },
+    {
+      "key": "loop runs",
+      "path": [
+        "loop",
+        "runs"
+      ],
+      "category": "loop",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg loop runs command",
+      "usage": [
+        "mdkg loop runs <loop> [--ws <alias>] [--no-cache] [--no-reindex] [--json]"
+      ],
+      "args": [
+        {
+          "name": "loop",
+          "required": true,
+          "source": "<loop>",
+          "description": "Loop node id or qid."
+        }
+      ],
+      "flags": [
         {
           "name": "--root",
-          "value": null,
+          "value": "<path>",
           "required": false,
-          "description": "--root, -r <path>   Run against a specific repo root"
+          "description": "Run against a specific repository root; -r is the short alias."
         },
         {
-          "name": "--update-dockerignore",
-          "value": "Append",
+          "name": "--ws",
+          "value": "<alias>",
           "required": false,
-          "description": "--update-dockerignore Append mdkg ignore entries"
+          "description": "Resolve the command against one workspace alias."
         },
         {
-          "name": "--update-gitignore",
+          "name": "--json",
           "value": null,
           "required": false,
-          "description": "--update-gitignore    Append mdkg ignore entries"
+          "description": "Emit deterministic JSON instead of text."
         },
         {
-          "name": "--update-npmignore",
+          "name": "--no-cache",
           "value": null,
           "required": false,
-          "description": "--update-npmignore    Append mdkg ignore entries"
+          "description": "Build a non-persisting in-memory index projection instead of reading the cache."
         },
         {
-          "name": "--version",
+          "name": "--no-reindex",
           "value": null,
           "required": false,
-          "description": "--version, -V       Show version"
+          "description": "Do not rebuild a stale or missing index projection."
         }
       ],
       "output_formats": [
-        "text"
+        "text",
+        "json"
       ],
-      "json_schema_ref": null,
+      "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
-        "initialize-mdkg-scaffold"
+        "none"
       ],
       "read_paths": [
         ".mdkg/**"
       ],
-      "write_paths": [
-        ".mdkg/**",
-        "AGENTS.md",
-        "AGENT_START.md",
-        "CLAUDE.md",
-        "CLI_COMMAND_MATRIX.md",
-        "llms.txt"
-      ],
+      "write_paths": [],
       "dry_run": {
         "supported": false
       },
-      "lock_policy": "not-required-before-mdkg-config-exists",
-      "atomic_write_policy": "exclusive-create-and-atomic-file-writes",
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
       "receipts": [
-        "init-summary"
+        "loop-runs-receipt"
       ],
-      "danger_level": "moderate",
+      "danger_level": "read-only",
       "aliases": [],
       "exit_codes": [
         {
@@ -4651,52 +5994,80 @@
         }
       ],
       "examples": [
-        "  mdkg init [options]"
+        "mdkg loop runs <loop> [--ws <alias>] [--no-cache] [--no-reindex] [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help init",
+        "help_target": "mdkg help loop runs",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
-      }
+      },
+      "descriptor_source": "src/commands/loop_descriptors.ts",
+      "handler": "runLoopRunsCommand",
+      "help_notes": [
+        "Lists run refs and evidence refs without executing runtime jobs."
+      ]
     },
     {
-      "key": "list",
+      "key": "loop show",
       "path": [
-        "list"
+        "loop",
+        "show"
       ],
-      "category": "list",
+      "category": "loop",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg list command",
+      "summary": "mdkg loop show command",
       "usage": [
-        "  mdkg list [--type <type>] [--status <status>] [--ws <alias>] [--epic <id>]"
+        "mdkg loop show <loop-or-template> [--meta] [--ws <alias>] [--no-cache] [--no-reindex] [--json]"
+      ],
+      "args": [
+        {
+          "name": "loop-or-template",
+          "required": true,
+          "source": "<loop-or-template>",
+          "description": "Loop node id/qid or seed template name/ref."
+        }
       ],
-      "args": [],
       "flags": [
         {
-          "name": "--help",
+          "name": "--meta",
           "value": null,
           "required": false,
-          "description": "--help, -h          Show help"
+          "description": "Show metadata without the full body."
         },
         {
           "name": "--root",
+          "value": "<path>",
+          "required": false,
+          "description": "Run against a specific repository root; -r is the short alias."
+        },
+        {
+          "name": "--ws",
+          "value": "<alias>",
+          "required": false,
+          "description": "Resolve the command against one workspace alias."
+        },
+        {
+          "name": "--json",
           "value": null,
           "required": false,
-          "description": "--root, -r <path>   Run against a specific repo root"
+          "description": "Emit deterministic JSON instead of text."
         },
         {
-          "name": "--version",
+          "name": "--no-cache",
           "value": null,
           "required": false,
-          "description": "--version, -V       Show version"
+          "description": "Build a non-persisting in-memory index projection instead of reading the cache."
+        },
+        {
+          "name": "--no-reindex",
+          "value": null,
+          "required": false,
+          "description": "Do not rebuild a stale or missing index projection."
         }
       ],
       "output_formats": [
         "text",
-        "json",
-        "xml",
-        "toon",
-        "md"
+        "json"
       ],
       "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
@@ -4711,7 +6082,9 @@
       },
       "lock_policy": "none-read-only",
       "atomic_write_policy": "none-read-only",
-      "receipts": [],
+      "receipts": [
+        "loop-show-receipt"
+      ],
       "danger_level": "read-only",
       "aliases": [],
       "exit_codes": [
@@ -4725,12 +6098,17 @@
         }
       ],
       "examples": [
-        "  mdkg list [--type <type>] [--status <status>] [--ws <alias>] [--epic <id>]"
+        "mdkg loop show <loop-or-template> [--meta] [--ws <alias>] [--no-cache] [--no-reindex] [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help list",
+        "help_target": "mdkg help loop show",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
-      }
+      },
+      "descriptor_source": "src/commands/loop_descriptors.ts",
+      "handler": "runLoopShowCommand",
+      "help_notes": [
+        "Shows an indexed loop node or a seed loop template."
+      ]
     },
     {
       "key": "manifest",
@@ -9170,5 +10548,5 @@
       }
     }
   ],
-  "contract_hash": "65408d40dd065dfadcaa9bfe3626df5703dce2fe08ce1dd500e371899a8c4f7a"
+  "contract_hash": "e9bd2d82d340887bc58d518c7e67541996f4b7744b2d1981763060575265aa29"
 }