mdkg 0.4.2 → 0.5.1

package/CHANGELOG.md

@@ -8,6 +8,83 @@ mdkg is pre-v1 public alpha software. Command, graph, cache, bundle, and DAL con
 
 ## Unreleased
 
+## 0.5.1 - 2026-07-14
+
+### Changed
+
+- Archive compression now derives writable ownership from enabled local
+  workspaces. `archive compress --all --ws <local-alias>` limits bulk selection,
+  and exact workspace-qualified archive qids are supported for direct targets.
+- Archive compression JSON receipts preserve existing fields and add selected
+  workspace and read-only imported-projection exclusion evidence.
+
+### Fixed
+
+- Fixed `archive compress --all` traversing imported subgraph ZIP-fragment paths
+  and potentially mutating earlier local archives before a later invalid target
+  failed. Imported archives remain discoverable but fail closed for direct
+  compression, and the complete local selection is preflighted before writes.
+
+## 0.5.0 - 2026-07-11
+
+### Added
+
+- Added `loop` as a first-class mdkg work node for reusable, durable agentic
+  processes that can coordinate goals, tasks, tests, spikes, proposals,
+  decisions, checkpoints, receipts, evidence, and repeated attempts.
+- Added the semantic `mdkg loop list`, `show`, `fork`, `plan`, `next`, and
+  `runs` command family, plus deterministic `mdkg new loop` guidance for raw
+  loops versus bundled templates.
+- Added identity-bound loop readiness metadata for pre-run questions, action
+  approvals, evidence lanes, and paired decision/approval waivers.
+- Added immutable template provenance, content hashes, stale-fork warnings,
+  default child materialization, and an explicit planning-only fork mode.
+- Added seven bundled read-only or planning loop templates for security,
+  frontend design, backend/API/CLI design, tech-stack practices, duplication
+  and linting, test/CI/skill infrastructure, and user-story audits.
+- Added the reusable `pursue-mdkg-loop` agent skill to keep authorized child
+  lanes moving, recover blockers through grounded spikes and proposals, and
+  close only against the loop definition of done.
+- Added a gated mdkg.dev announcement and top-level Loops documentation with a
+  purpose-built read-only security audit walkthrough. Public promotion remains
+  controlled by the shared source release manifest.
+
+### Changed
+
+- Integrated loops into parser/template validation, generic discovery,
+  SQLite/JSON indexes, search/show/list output, deterministic pack traversal,
+  generated help, command contracts, init assets, and upgrade fallback paths.
+- Made loop fork dry-runs observational across JSON and SQLite backends: no ID
+  reservation, event write, index persistence, or graph/filesystem mutation.
+- Made read-only loop commands use non-persisting index projections and made
+  `loop next` exhaust authorized nested work and blocker-recovery lanes before
+  reporting the whole loop blocked.
+- Kept loop templates, scoped forks, and run-bearing state under one `loop`
+  node type; mdkg preserves orchestration state while the coding-agent harness
+  remains responsible for executing agents and tools.
+- Added installed-package smoke coverage for every bundled loop template and a
+  public-repository release-readiness workflow across the minimum supported
+  Node version and current Node line.
+- Cleaned mdkg.dev/docs public copy and demo proof surfaces while preserving
+  the existing quickstart-first product journey and Pre-v1 public-alpha scope.
+
+### Fixed
+
+- Fixed readiness projection so unrelated decisions, approvals, evidence, and
+  waivers cannot satisfy a different question, action, or evidence lane.
+- Fixed loop routing so one blocked child does not halt other authorized work,
+  and whole-loop blocking occurs only after useful work and recovery paths are
+  exhausted.
+- Fixed stale-template handling to warn from recorded template identity and
+  content hash without silently rewriting scoped forks.
+
+### Security
+
+- Hardened graph target writes against symlink containment escapes before any
+  destination mutation.
+- Bounded ZIP entry count, compressed size, declared output, total output, and
+  expansion ratio before bundle or subgraph inflation.
+
 ## 0.4.2 - 2026-07-05
 
 ### Added
@@ -63,33 +140,29 @@ mdkg is pre-v1 public alpha software. Command, graph, cache, bundle, and DAL con
   `resource_profile`, WORK `kind`, WORK_ORDER `artifact_policy`, RECEIPT
   `redaction_policy`, `receipt_kind`, `redaction_class`, and pack/bundle
   `--profile` flags.
-- Expanded release-readiness documentation and checks for `0.4.1` so the
-  implementation can hand off to a separate approval-gated publish goal.
+- Expanded documentation and validation checks for `0.4.1` so package readiness
+  can be verified before publication.
 
 ## 0.4.0 - 2026-06-27
 
 ### Added
 
-- Added the `0.4.0` public launch-readiness lane for mdkg.dev and
-  docs.mdkg.dev with explicit source metadata, changelog, generated-doc,
-  npm prepublish, npm postpublish, Vercel production, and Chrome live-validation
-  blockers.
-- Added public release-note and docs coverage for the `0.4.0` launch surface,
-  including per-release changelog cards, launch-track copy, and source-backed
-  currentness requirements.
-- Added Vercel production currentness and Chrome postpublish validation as
-  required evidence before mdkg.dev or docs.mdkg.dev can claim the `0.4.0`
-  launch is live.
+- Added public release cards and changelog detail pages for recent public-alpha
+  versions.
+- Added docs coverage for config overlays, custom skill mirrors,
+  `COLLABORATION.md`, MANIFEST naming, and public-alpha customization guidance.
+- Added mdkg.dev and docs.mdkg.dev copy updates that keep public claims bounded
+  to documented capabilities.
 
 ### Changed
 
-- Updated mdkg.dev and docs.mdkg.dev source copy for the `0.4.0` release target,
+- Updated mdkg.dev and docs.mdkg.dev source copy for the `0.4.0` public alpha,
   including config overlays, custom skill mirrors, `COLLABORATION.md`,
-  MANIFEST/SPEC compatibility, and Plan -> Work -> Evidence launch messaging.
+  MANIFEST/SPEC compatibility, and Plan -> Work -> Evidence messaging.
 - Updated public docs and examples to use the current `mdkg pack --profile
   concise` syntax instead of stale `--pack-profile concise` examples.
 - Aligned source-visible package references, generated release-note data, and
-  generated CLI docs with the `0.4.0` release target.
+  generated CLI docs with `0.4.0`.
 
 ### Fixed
 

package/CLI_COMMAND_MATRIX.md

@@ -1,7 +1,7 @@
 # CLI Command Matrix
 
-as_of: 2026-07-05
-package_version_in_source: 0.4.2
+as_of: 2026-07-14
+package_version_in_source: 0.5.1
 source: live help from `src/cli.ts`, runtime command handlers, and `dec-15`..`dec-18`
 status: canonical single-source command and flag reference for mdkg
 
@@ -46,6 +46,7 @@ Primary commands:
 - `subgraph`
 - `work`
 - `goal`
+- `loop`
 - `task`
 - `next`
 - `validate`
@@ -77,7 +78,12 @@ Low-level Git remote lifecycle primitives are accessed through `mdkg git ...`.
 Read-only child graph orchestration is accessed through `mdkg subgraph ...`.
 Work contract/order/receipt semantic mirrors are accessed through `mdkg work ...`.
 Recursive long-running objective contracts are accessed through `mdkg goal ...`.
+Reusable process-state loops are accessed through `mdkg loop ...`; mdkg stores loop graph state while runtimes execute agents and tools.
 Fresh init workspaces default to the SQLite access cache backend; existing migrated configs stay on JSON until opted in.
+Graph discovery enforces configurable `index.limits` for file count, per-file
+bytes, total bytes, and directory depth before reading Markdown. ZIP, pack, and
+local MCP surfaces apply additional fixed protocol-safe ceilings and return
+deterministic errors when a request or graph exceeds them.
 Project application database foundation commands are accessed through `mdkg db ...`; `mdkg index` remains the compatibility shortcut for graph index rebuilds.
 Operator health summaries are accessed through read-only `mdkg status ...`; deeper diagnostics remain under `mdkg doctor ...`.
 Repair planning is accessed through read-only `mdkg fix plan ...`; duplicate-ID graph repairs can be applied through `mdkg fix apply --family ids ...` or the convenience `mdkg fix ids --apply ...`. Index/cache and graph-reference findings remain plan/manual-review only.
@@ -162,6 +168,7 @@ Types:
 - `dec`
 - `prop`
 - `goal`
+- `loop`
 - `epic`
 - `feat`
 - `task`
@@ -195,6 +202,13 @@ Agent workflow file type creation:
 Goal node creation:
 - `mdkg new goal "<title>" [options] [--json]`
 
+Loop node creation:
+- `mdkg new loop "<title>" [options] [--json]`
+- loops are durable declarative graph process state, not runtime execution jobs
+- a loop may be a reusable template, scoped fork, or run-bearing loop through metadata and links
+- loop metadata records mode, scope, lineage, materialization, child refs, evidence/run refs, definition of done, and blocker-continuation policy
+- default seeded loops are read-only or planning-oriented audit/recommendation templates
+
 Spike node creation:
 - `mdkg new spike "<research question>" [options] [--json]`
 - spikes are actionable research/planning work nodes under `.mdkg/work/`
@@ -244,6 +258,7 @@ JSON receipt:
 Notes:
 - `--id` lets agent workflow files use semantic portable ids such as `agent.image-worker`, `work.generate-image`, or `proposal.review-loop-1`.
 - `goal` nodes capture recursive objective state and required checks, but normal `mdkg next` does not select them.
+- `loop` nodes capture reusable process state, fork lineage, child refs, run/evidence refs, blocker-continuation policy, and a high-bar definition of done; runtime execution remains outside mdkg.
 - `spec` and `work` scaffold as validation-clean standalone docs. `work_order`, `receipt`, `feedback`, `dispute`, and `proposal` templates contain editable placeholder refs and need real graph or `skill.<slug>` refs before strict validation passes.
 
 ### `mdkg show`
@@ -642,9 +657,9 @@ Usage:
 - `mdkg archive show <id-or-archive-uri> [--ws <alias>] [--json]`
 - `mdkg archive verify [id-or-archive-uri] [--json]`
 - `mdkg archive verify [id-or-archive-uri] [--ws <alias>] [--json]`
-- `mdkg archive compress <id-or-archive-uri|--all> [--json]`
-- `mdkg archive compress <id-or-archive-uri> [--ws <alias>] [--json]`
-- `mdkg archive compress --all [--json]`
+- `mdkg archive compress <id-or-archive-uri-or-qid|--all> [--ws <local-alias>] [--json]`
+- `mdkg archive compress <id-or-archive-uri-or-qid> [--ws <local-alias>] [--json]`
+- `mdkg archive compress --all [--ws <local-alias>] [--json]`
 
 Fields:
 - archive sidecars use `type: archive`
@@ -658,6 +673,18 @@ Notes:
 - archive visibility defaults to `private`
 - `archive://<archive.id>` refs are validated against local archive sidecars
 - `archive verify` and `validate` both check the ZIP hash, ZIP readability, payload SHA-256, and payload byte size
+- archive compression is owned exclusively by enabled local workspaces; imported
+  archive projections remain visible to list/show/search but are read-only
+- `archive compress --all` selects every locally writable archive, while
+  `--all --ws <local-alias>` limits selection to one enabled local workspace
+- direct workspace-qualified qids such as `root:archive.example` are supported;
+  imported qids and `--ws <imported-alias>` fail before filesystem path
+  construction with source-workspace and bundle-refresh guidance
+- compression preflights ownership, identity, containment, symlinks, raw input,
+  and destinations for the complete selected set before the first write
+- JSON keeps `action`, `count`, and `archives`, and adds
+  `selection: { requested_workspace, selected_workspaces,
+  excluded_read_only: [{ workspace, qid, reason }] }`
 - `archive verify` passes when the raw local source file is missing but the committed sidecar and ZIP cache are valid
 - generated raw source copies live under `.mdkg/archive/**/source/` and are ignored by default
 - `doctor` warns when archive ZIP caches exceed `archive.large_cache_warning_bytes` (default `26214400`; `0` disables)
@@ -967,6 +994,48 @@ JSON receipts:
 - `evaluate`: `{ action: "evaluated", goal, report_only, runs_scripts, checks, completion_evidence_present }`
 - `pause|resume|done|archive`: `{ action, goal }`
 
+### `mdkg loop`
+
+When to use:
+- inspect reusable loop templates and scoped loop nodes
+- fork a reusable loop template for a concrete project scope
+- inspect loop planning state, child refs, run refs, and evidence refs without executing agents
+
+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]`
+- `mdkg loop list [--ws <alias>] [--no-cache] [--no-reindex] [--json]`
+- `mdkg loop show <loop-or-template> [--meta] [--ws <alias>] [--no-cache] [--no-reindex] [--json]`
+- `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]`
+- `mdkg loop plan <loop> [--ws <alias>] [--no-cache] [--no-reindex] [--json]`
+- `mdkg loop next <loop> [--ws <alias>] [--no-cache] [--no-reindex] [--json]`
+- `mdkg loop runs <loop> [--ws <alias>] [--no-cache] [--no-reindex] [--json]`
+
+Behavior:
+- `loop` is one first-class node type; template, scoped fork, and run-bearing behavior is represented through metadata and links, not separate node types.
+- seed templates resolve from `.mdkg/templates/loops/<name>.loop.md`.
+- `loop list` reports indexed loop nodes plus reusable seed templates.
+- `loop show` reports either an indexed loop node or a seed template body/frontmatter.
+- `loop fork` creates a scoped loop; default materialization creates linked spike/task/test child nodes, while `planning_only` or `--no-children` creates only the scoped loop shell.
+- `loop fork --dry-run` is observational: it writes no nodes, indexes, events, or SQLite reservations, and the next real fork reuses the previewed ids.
+- forked loops retain template identity and content hash; list/show/plan report current, stale, missing-template, or unknown provenance without rewriting forks.
+- `loop plan` reports readiness state, materialization state, child/run/output refs, evidence lanes, blockers, closeout readiness, and blocker-continuation guidance without executing agents.
+- `loop next` is read-only and routes to the next actionable child, readiness lane, or blocker recovery step without claiming work.
+- `loop runs` reports linked `run_refs` and graph `evidence_refs` without executing runtime jobs.
+- mdkg defines reusable process state and graph context; omni-room-runtime or other runtimes execute agents, tools, sandboxes, traces, and model routing.
+
+JSON receipts:
+- `list`: `{ action: "listed", loops, templates, warnings }`
+- `show`: `{ action: "showed", loop, warnings }` or `{ action: "showed", template, warnings }`
+- `fork`: `{ action: "forked"|"planned", loop, template, materialization_mode, materialized_children, pending_materialization, blocker_continuation, warnings }`
+- `plan`: `{ action: "planned", loop, materialization_mode, child_refs, pending_materialization, readiness, blocker_continuation, warnings }`
+- `next`: `{ action: "selected", loop, selected, rationale, skipped, readiness, warnings }`
+- `runs`: `{ action: "listed", loop, run_refs, evidence_refs, warnings }`
+
 ### `mdkg task`
 
 When to use:

package/README.md

@@ -14,7 +14,7 @@ mdkg stays deliberately boring:
 - first-class rebuildable SQLite cache through built-in `node:sqlite`
 - no daemon, hosted index, or vector DB
 
-Current package version in source: `0.4.2`
+Current package version in source: `0.5.1`
 
 mdkg is still pre-v1 public alpha software. The public package is usable, but graph, cache, bundle, and DAL contracts may continue to change quickly while the project converges on a stable v1 surface.
 
@@ -494,10 +494,12 @@ Current source behavior:
 - `mdkg skill sync` refreshes the product-specific mirrors from canonical `.mdkg/skills/`
 - mirrored skill folders are append-focused outputs; preserve unrelated existing folders and fail on same-slug collisions unless explicitly forced
 
-This repo now dogfoods three internal skills:
+This repo now dogfoods mdkg-authored internal skills:
 - `author-mdkg-skill`
 - `select-work-and-ground-context`
 - `build-pack-and-execute-task`
+- `pursue-mdkg-goal`
+- `pursue-mdkg-loop`
 - `verify-close-and-checkpoint`
 
 Optional skill metadata with prefixes such as `ochatr_*` is treated as vendor extension data. Structured skill output exposes it under `extensions.ochatr` while keeping the top-level `ochatr` field as a compatibility alias introduced in 0.0.9. ochatr.ai is a pioneering adopter of this extension pattern, not the name of the base mdkg standard.
@@ -521,6 +523,13 @@ Fresh `mdkg init` workspaces default to `index.backend: sqlite`, which writes `.
 
 `mdkg index` still writes JSON compatibility caches (`global.json`, `skills.json`, `capabilities.json`, and subgraph projections when configured). In SQLite mode it also rebuilds the SQLite cache with nodes, edges, skills, capabilities, archive metadata, subgraphs, source hashes, and schema metadata. Deleting the SQLite file is recoverable with `mdkg index`.
 
+Graph ingestion is bounded before Markdown bodies are read. New workspaces expose
+`index.limits.max_files`, `max_file_bytes`, `max_total_bytes`, and `max_depth` in
+`.mdkg/config.json`; older configs receive the same conservative defaults in
+memory. Pack traversal and body reads are bounded before construction, ZIP input
+is bounded before allocation and inflation, and the local read-only MCP server
+rejects oversized lines, batches, nesting, bodies, tool payloads, and responses.
+
 Mutating commands use a workspace mutation lock plus atomic writes. SQLite mode additionally reserves numeric ids in a SQLite transaction before writing Markdown so parallel `mdkg new` and checkpoint calls avoid naming conflicts. Skipped ids after failed writes are acceptable because Markdown remains canonical.
 
 ## Project DB Layout
@@ -584,6 +593,14 @@ Use `mdkg goal claim [goal-id] <work-id>` to durably set `active_node` after cho
 
 Required checks are stored as report-only guidance. Agents should run the checks themselves, record evidence in the goal or active work item, then use `mdkg goal evaluate` to summarize the current evidence state. During normal goal execution, skill improvements should be recorded as improvement candidates or proposal nodes; edit `SKILL.md` files only when the active node is explicit skill-maintenance work.
 
+## Loop nodes
+
+Loop nodes are durable declarative process state for reusable agentic workflows. Use `mdkg new loop "<process>"` for a loop record, or `mdkg loop fork <template> --scope <scope>` to instantiate a seeded template for a concrete repo, folder, or goal.
+
+`loop` is one first-class node type. A loop can act as a reusable template, scoped fork, or run-bearing loop through metadata and links; mdkg does not create separate `loop_template` or `loop_run` node types in this release. Loop metadata records mode, scope, lineage, materialization mode, child refs, run/evidence refs, definition of done, and blocker-continuation policy.
+
+`mdkg loop list|show|plan|runs` inspect loop state without executing agents. `mdkg loop fork` creates graph state; by default it materializes linked spike/task/test child nodes, while `--planning-only` or `--no-children` creates only the scoped loop shell. mdkg defines reusable process state and graph context; omni-room-runtime or another runtime owns agent/tool execution, sandboxes, traces, and model routing.
+
 ## Research spikes
 
 Spikes are first-class actionable work nodes for research and planning. Use
@@ -636,6 +653,16 @@ When the source passed to `mdkg archive add` is inside the repo, `source_path` i
 
 Archive sidecar visibility defaults to `private`. Use `mdkg archive add --visibility public` only when the sidecar metadata and ZIP cache are safe for public packs or public bundles.
 
+Archive compression follows workspace ownership. `mdkg archive compress --all`
+compresses archives from enabled local workspaces and reports read-only imported
+archive projections as exclusions; it never treats bundle ZIP fragments as
+filesystem paths. Use `--all --ws <local-alias>` to limit bulk compression or a
+workspace-qualified qid such as `root:archive.example` for an exact local
+target. Direct imported qids and imported `--ws` aliases fail before writes with
+guidance to compress in the source workspace and refresh its subgraph bundle.
+The JSON receipt preserves `action`, `count`, and `archives` and adds the
+requested workspace, selected local workspaces, and excluded read-only qids.
+
 By default, init/upgrade ignore generated raw archive source copies with `.mdkg/archive/**/source/`; sidecar `.md` files and compressed `.zip` caches remain commit-eligible. `mdkg doctor` warns when a committed archive ZIP cache exceeds `archive.large_cache_warning_bytes` in `.mdkg/config.json` (default `26214400`; set `0` to disable). Large-cache warnings do not block archive add or validation.
 
 ## Current direction
@@ -650,6 +677,7 @@ This release includes:
 - SQLite index backend for fresh workspaces using built-in `node:sqlite`
 - mutation locking and atomic writes for parallel mdkg calls
 - first-class `goal` nodes and `mdkg goal show/next/evaluate/pause/resume/done`
+- first-class `loop` nodes and `mdkg loop list/show/fork/plan/runs`
 - optional `skills: [...]` on work items
 - pack-time skill inclusion
 - latest-checkpoint resolver + index hint

package/dist/cli.js

@@ -36,6 +36,8 @@ const init_1 = require("./commands/init");
 const new_1 = require("./commands/new");
 const guide_1 = require("./commands/guide");
 const upgrade_1 = require("./commands/upgrade");
+const loop_1 = require("./commands/loop");
+const loop_descriptors_1 = require("./commands/loop_descriptors");
 const goal_1 = require("./commands/goal");
 const event_1 = require("./commands/event");
 const skill_1 = require("./commands/skill");
@@ -80,6 +82,7 @@ function printUsage(log) {
     log("  git         Clone, fetch, inspect, close out, and push Git-backed mdkg projects");
     log("  subgraph    Register, audit, plan, sync, materialize, and verify read-only child graph snapshots");
     log("  work        Create and update work contracts, orders, receipts, and artifacts");
+    log("  loop        List, show, fork, plan, and inspect first-class loop nodes");
     log("  goal        Inspect and advance recursive goal nodes");
     log("  task        Start, update, and complete task-like nodes");
     log("  next        Suggest the next work item");
@@ -146,7 +149,7 @@ function printNewHelp(log) {
     log("Usage:");
     log('  mdkg new <type> "<title>" [options] [--json]');
     log("\nTypes:");
-    log("  rule prd edd dec prop goal epic feat task bug spike checkpoint test");
+    log("  rule prd edd dec prop loop goal epic feat task bug spike checkpoint test");
     log("\nAgent workflow file types:");
     log("  manifest work work_order receipt feedback dispute proposal");
     log("  spec is a legacy alias for manifest and emits MANIFEST.md during the compatibility bridge.");
@@ -179,6 +182,34 @@ function printNewHelp(log) {
     log("  spikes do not run web search, create follow-up nodes, generate SKILL.md, or expose `mdkg spike ...`.");
     printGlobalOptions(log);
 }
+function printLoopHelp(log, subcommand) {
+    printLoopDescriptorHelp(log, (0, loop_descriptors_1.loopDescriptorForSubcommand)(subcommand));
+}
+function printLoopDescriptorHelp(log, descriptor) {
+    log("Usage:");
+    for (const usage of descriptor.usage) {
+        log(`  ${usage}`);
+    }
+    if (descriptor.key === "loop fork") {
+        log("\nMaterialization modes:");
+        log("  default_children planning_only manual");
+    }
+    const commandFlags = descriptor.flags.filter((flag) => flag.name !== "--root");
+    if (commandFlags.length > 0) {
+        log("\nOptions:");
+        for (const flag of commandFlags) {
+            const syntax = flag.value ? `${flag.name} ${flag.value}` : flag.name;
+            log(`  ${syntax.padEnd(28)} ${flag.description}`);
+        }
+    }
+    if (descriptor.notes.length > 0) {
+        log("\nNotes:");
+        for (const note of descriptor.notes) {
+            log(`  ${note}`);
+        }
+    }
+    printGlobalOptions(log);
+}
 function printGuideHelp(log) {
     log("Usage:");
     log("  mdkg guide");
@@ -318,9 +349,10 @@ function printListHelp(log) {
 function printSearchHelp(log) {
     log("Usage:");
     log('  mdkg search "<query>" [--type <type>] [--status <status>] [--ws <alias>]');
-    log("               [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]");
+    log("               [--tags <tag,tag,...>] [--tags-mode any|all] [--limit <n>] [--json|--xml|--toon|--md]");
     log("\nWhen to use:");
     log("  Search mdkg nodes by metadata. Use `mdkg skill search` for skills.");
+    log("  Structured output defaults to a bounded page and reports count, returned_count, limit, and truncated.");
     printGlobalOptions(log);
 }
 function printPackHelp(log) {
@@ -551,8 +583,13 @@ function printArchiveHelp(log, subcommand) {
             break;
         case "compress":
             log("Usage:");
-            log("  mdkg archive compress <id-or-archive-uri> [--ws <alias>] [--json]");
-            log("  mdkg archive compress --all [--json]");
+            log("  mdkg archive compress <id-or-archive-uri-or-qid> [--ws <local-alias>] [--json]");
+            log("  mdkg archive compress --all [--ws <local-alias>] [--json]");
+            log("\nNotes:");
+            log("  - compression mutates archives owned by enabled local workspaces only");
+            log("  - --all excludes read-only imported archive projections and reports them in the receipt");
+            log("  - direct imported qids and --ws <imported-alias> fail with source-workspace guidance");
+            log("  - all selected archives pass ownership and path preflight before the first write");
             break;
         default:
             log("Usage:");
@@ -560,7 +597,7 @@ function printArchiveHelp(log, subcommand) {
             log("  mdkg archive list [--kind source|artifact] [--visibility private|internal|public] [--json]");
             log("  mdkg archive show <id-or-archive-uri> [--json]");
             log("  mdkg archive verify [id-or-archive-uri] [--json]");
-            log("  mdkg archive compress <id-or-archive-uri|--all> [--json]");
+            log("  mdkg archive compress <id-or-archive-uri-or-qid|--all> [--ws <local-alias>] [--json]");
             log("\nNotes:");
             log("  - archive add copies the source, writes a sidecar, and writes a deterministic zip cache");
             log("  - archive visibility defaults to private");
@@ -1254,6 +1291,9 @@ function printCommandHelp(log, command, subcommand) {
         case "work":
             printWorkHelp(log, subcommand);
             return;
+        case "loop":
+            printLoopHelp(log, subcommand);
+            return;
         case "task":
             printTaskHelp(log, subcommand);
             return;
@@ -2508,6 +2548,89 @@ function runSkillSubcommand(parsed, root) {
             throw new errors_1.UsageError("skill requires new/list/show/search/validate/sync");
     }
 }
+function runLoopSubcommand(parsed, root) {
+    const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
+    const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
+    const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+    const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
+    const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
+    switch (subcommand) {
+        case "list": {
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("loop list does not accept positional arguments");
+            }
+            (0, loop_1.runLoopListCommand)({ root, ws, json, noCache, noReindex });
+            return 0;
+        }
+        case "show": {
+            const id = parsed.positionals[2];
+            if (!id || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("loop show requires <loop-or-template>");
+            }
+            const metaOnly = parseBooleanFlag("--meta", parsed.flags["--meta"]);
+            (0, loop_1.runLoopShowCommand)({ root, id, ws, metaOnly, json, noCache, noReindex });
+            return 0;
+        }
+        case "fork": {
+            const template = parsed.positionals[2];
+            if (!template || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("loop fork requires <template>");
+            }
+            const scope = requireFlagValue("--scope", parsed.flags["--scope"]);
+            if (!scope) {
+                throw new errors_1.UsageError("loop fork requires --scope");
+            }
+            const title = requireFlagValue("--title", parsed.flags["--title"]);
+            const materializationMode = requireFlagValue("--materialization", parsed.flags["--materialization"]);
+            const planningOnly = parseBooleanFlag("--planning-only", parsed.flags["--planning-only"]);
+            const noChildren = parseBooleanFlag("--no-children", parsed.flags["--no-children"]);
+            const dryRun = parseBooleanFlag("--dry-run", parsed.flags["--dry-run"]);
+            const runId = requireFlagValue("--run-id", parsed.flags["--run-id"]);
+            (0, loop_1.runLoopForkCommand)({
+                root,
+                template,
+                scope,
+                title,
+                ws,
+                materializationMode: materializationMode,
+                planningOnly,
+                noChildren,
+                dryRun,
+                runId,
+                json,
+                noCache,
+                noReindex,
+            });
+            return 0;
+        }
+        case "plan": {
+            const id = parsed.positionals[2];
+            if (!id || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("loop plan requires <loop>");
+            }
+            (0, loop_1.runLoopPlanCommand)({ root, id, ws, json, noCache, noReindex });
+            return 0;
+        }
+        case "next": {
+            const id = parsed.positionals[2];
+            if (!id || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("loop next requires <loop>");
+            }
+            (0, loop_1.runLoopNextCommand)({ root, id, ws, json, noCache, noReindex });
+            return 0;
+        }
+        case "runs": {
+            const id = parsed.positionals[2];
+            if (!id || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("loop runs requires <loop>");
+            }
+            (0, loop_1.runLoopRunsCommand)({ root, id, ws, json, noCache, noReindex });
+            return 0;
+        }
+        default:
+            throw new errors_1.UsageError("loop requires list/show/fork/plan/next/runs");
+    }
+}
 function runGoalSubcommand(parsed, root) {
     const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
     const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
@@ -2889,6 +3012,8 @@ function runCommand(parsed, root, runtime) {
             return runSubgraphSubcommand(parsed, root);
         case "work":
             return runWorkSubcommand(parsed, root);
+        case "loop":
+            return runLoopSubcommand(parsed, root);
         case "goal":
             return runGoalSubcommand(parsed, root);
         case "task":
@@ -2957,6 +3082,7 @@ function runCommand(parsed, root, runtime) {
             const status = requireFlagValue("--status", parsed.flags["--status"]);
             const tags = parseCsvFlag("--tags", parsed.flags["--tags"]);
             const tagsMode = parseTagsModeFlag(parsed.flags["--tags-mode"]);
+            const limit = parseNumberFlag("--limit", parsed.flags["--limit"]);
             const format = parseQueryOutputFormat(parsed);
             const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
             const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
@@ -2968,6 +3094,7 @@ function runCommand(parsed, root, runtime) {
                 status,
                 tags,
                 tagsMode,
+                limit,
                 format,
                 noCache,
                 noReindex,