artshelf 0.8.0 → 0.10.0

package/dist/src/cli.js

@@ -9,7 +9,7 @@ const VERSION = readPackageVersion();
 const PACKAGE_NAME = "artshelf";
 const NPM_REGISTRY_URL = process.env.ARTSHELF_NPM_REGISTRY_URL ?? `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
 const UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
-const BOOLEAN_FLAGS = new Set(["all", "json", "manual-review", "dry-run", "execute", "help", "version", "plain"]);
+const BOOLEAN_FLAGS = new Set(["all", "json", "agent", "manual-review", "dry-run", "execute", "help", "version", "plain"]);
 const VALUE_FLAGS = new Set([
     "cleanup",
     "kind",
@@ -45,7 +45,7 @@ async function main(argv) {
             return maybeNotifyUpdateAndReturn(0, parsed);
         }
         if (parsed.command === "help" || parsed.command === "--help" || parsed.command === "-h" || boolFlag(parsed, "help")) {
-            printHelp(parsed.command === "help" ? parsed.positionals[0] : parsed.command);
+            printHelp(resolveHelpKey(parsed));
             return maybeNotifyUpdateAndReturn(0, parsed);
         }
         switch (parsed.command) {
@@ -147,6 +147,10 @@ function handlePut(parsed, ledgerPath, json) {
 function handleLedgers(parsed, json) {
     const action = parsed.positionals[0] ?? "list";
     const registryPath = normalizeRegistryPath(stringFlag(parsed, "registry"));
+    if (action === "help") {
+        printHelp("ledgers");
+        return 0;
+    }
     if (action === "add") {
         const ledgerPath = normalizeLedgerPath(requiredStringFlag(parsed, "ledger"));
         if (!existsSync(ledgerPath))
@@ -531,12 +535,17 @@ function handleTrashPurge(parsed, ledgerPath, json) {
     return 0;
 }
 function handleReview(parsed, ledgerPath, json) {
+    const agent = boolFlag(parsed, "agent");
     if (boolFlag(parsed, "all")) {
         const registryPath = normalizeRegistryPath(stringFlag(parsed, "registry"));
         const results = registeredLedgersOrThrow(registryPath).map((ledger) => reviewLedger(ledger));
         const ok = results.every((entry) => entry.validate.ok);
         const summary = summarizeReview(results);
-        const nextAction = reviewNextAction(summary);
+        if (agent) {
+            printCompactJson(buildReviewAgentPacketAll(results, summary, registryPath));
+            return ok ? 0 : 1;
+        }
+        const nextAction = reviewNextAction(summary, "all");
         if (json) {
             printJson({ ok, registryPath, summary, nextAction, ledgers: results });
             return ok ? 0 : 1;
@@ -545,6 +554,10 @@ function handleReview(parsed, ledgerPath, json) {
         return ok ? 0 : 1;
     }
     const result = reviewLedger({ name: "current", path: ledgerPath, scope: "other", createdAt: "", updatedAt: "" }, false);
+    if (agent) {
+        printCompactJson(buildReviewAgentPacketSingle(result, ledgerPath));
+        return result.validate.ok ? 0 : 1;
+    }
     if (json) {
         printJson({ ok: result.validate.ok, ledger: result });
         return result.validate.ok ? 0 : 1;
@@ -554,6 +567,10 @@ function handleReview(parsed, ledgerPath, json) {
 }
 function handleDoctor(parsed, ledgerPath, json) {
     const report = buildDoctorReport(ledgerPath, normalizeRegistryPath(stringFlag(parsed, "registry")));
+    if (boolFlag(parsed, "agent")) {
+        printCompactJson(buildDoctorAgentPacket(report));
+        return report.ok ? 0 : 1;
+    }
     if (json) {
         printJson(report);
         return report.ok ? 0 : 1;
@@ -620,16 +637,72 @@ function buildDoctorReport(ledgerPath, registryPath) {
         errors
     };
 }
+// Actionable categories only — ok ledgers are healthy states, never attention.
+// Order is fixed so the packet is byte-for-byte deterministic. Warnings surface
+// even when health is ok (they never fail the machine), mirroring status attention.
+const DOCTOR_ATTENTION_CATEGORIES = ["stale", "invalid", "warnings"];
+function doctorAttention(summary) {
+    return DOCTOR_ATTENTION_CATEGORIES.filter((key) => summary[key] > 0);
+}
+function doctorNextAction(blockers, summary) {
+    if (blockers.length > 0) {
+        return `repair ${blockers.length} registry/ledger issue(s) above, then re-run \`artshelf doctor\``;
+    }
+    if (summary.warnings > 0) {
+        return `healthy, but ${summary.warnings} warning(s) noted — run \`artshelf validate --all\` to inspect; nothing is auto-executed`;
+    }
+    return "artshelf is healthy on this machine — cleanup safety enforced; no action needed";
+}
+function buildDoctorAgentPacket(report) {
+    const blockers = [];
+    if (report.registryError)
+        blockers.push(`registry unreadable: ${report.registryError}`);
+    for (const ledger of report.ledgers) {
+        if (ledger.status !== "ok") {
+            blockers.push(`${ledger.name} ${ledger.status}${ledger.errors.length ? `: ${ledger.errors[0]}` : ""}`);
+        }
+    }
+    return {
+        schemaVersion: 1,
+        command: "doctor",
+        health: report.ok ? "ok" : "attention",
+        version: report.version,
+        node: report.node,
+        ledgerPath: report.ledgerPath,
+        registry: { path: report.registryPath, exists: report.registryExists, ok: report.registryOk, error: report.registryError },
+        ledgers: {
+            total: report.summary.ledgers,
+            ok: report.summary.ok,
+            stale: report.summary.stale,
+            invalid: report.summary.invalid,
+            warnings: report.summary.warnings
+        },
+        attention: doctorAttention(report.summary),
+        blockers,
+        cleanupSafety: report.cleanupSafety,
+        nextAction: doctorNextAction(blockers, report.summary),
+        verification: `artshelf doctor --agent --registry ${report.registryPath}`
+    };
+}
+// Human render (NGX-396): a scannable left-column glyph so attention state is
+// obvious at a glance — ✓ clear, ⚠ needs attention. Plain Unicode (no ANSI
+// color) keeps redirected/piped human output clean, and the `--agent`/`--json`
+// renders never carry glyphs (those stay machine contracts).
+const HUMAN_OK_GLYPH = "✓";
+const HUMAN_ATTENTION_GLYPH = "⚠";
+function attentionGlyph(needsAttention) {
+    return needsAttention ? HUMAN_ATTENTION_GLYPH : HUMAN_OK_GLYPH;
+}
 function printDoctor(report) {
     process.stdout.write(`artshelf ${report.version} (node ${report.node})\n`);
-    process.stdout.write(`health: ${report.ok ? "ok" : "needs attention"}\n`);
+    process.stdout.write(`${attentionGlyph(!report.ok)} health: ${report.ok ? "ok" : "needs attention"}\n`);
     process.stdout.write(`ledger: ${report.ledgerPath}${report.ledgerExists ? "" : " (absent)"}\n`);
     process.stdout.write(`registry: ${report.registryPath}${report.registryExists ? "" : " (absent)"}\n`);
     if (report.registryError)
         process.stdout.write(`registry error: ${report.registryError}\n`);
     process.stdout.write(`registered ledgers: ${report.summary.ledgers} (${report.summary.ok} ok, ${report.summary.stale} stale, ${report.summary.invalid} invalid)\n`);
     for (const ledger of report.ledgers) {
-        process.stdout.write(`  ${ledger.status} ${ledger.name} ${ledger.path}\n`);
+        process.stdout.write(`  ${attentionGlyph(ledger.status !== "ok")} ${ledger.status} ${ledger.name} ${ledger.path}\n`);
         for (const message of ledger.errors)
             process.stdout.write(`    error: ${message}\n`);
     }
@@ -640,8 +713,13 @@ function printDoctor(report) {
     }
 }
 function handleStatus(parsed, ledgerPath, json) {
+    const agent = boolFlag(parsed, "agent");
     if (boolFlag(parsed, "all")) {
         const report = buildStatusReport(normalizeRegistryPath(stringFlag(parsed, "registry")));
+        if (agent) {
+            printCompactJson(buildStatusAgentPacketAll(report));
+            return report.ok ? 0 : 1;
+        }
         if (json) {
             printJson(report);
             return report.ok ? 0 : 1;
@@ -650,6 +728,10 @@ function handleStatus(parsed, ledgerPath, json) {
         return report.ok ? 0 : 1;
     }
     const ledger = statusLedger({ name: "current", path: ledgerPath, scope: "other", createdAt: "", updatedAt: "" }, false);
+    if (agent) {
+        printCompactJson(buildStatusAgentPacketSingle(ledger, ledgerPath));
+        return ledger.ok ? 0 : 1;
+    }
     if (json) {
         printJson({ ok: ledger.ok, ledger });
         return ledger.ok ? 0 : 1;
@@ -733,23 +815,101 @@ function sumStatusCounts(ledgers, key) {
 function formatStatusCounts(counts) {
     return `active ${counts.active} · due ${counts.due} · manual-review ${counts.manualReview} · missing ${counts.missingPath} · kept ${counts.kept} · pending ${counts.pendingCleanup}`;
 }
+// Actionable categories only — active and kept are healthy states, never
+// attention. Order is fixed so the packet is byte-for-byte deterministic.
+const STATUS_ATTENTION_CATEGORIES = ["due", "manualReview", "missingPath", "pendingCleanup"];
+function statusAttention(counts) {
+    return STATUS_ATTENTION_CATEGORIES.filter((key) => counts[key] > 0);
+}
+function statusCommand(scope, command, ledgerPath) {
+    if (scope === "all")
+        return `artshelf ${command} --all`;
+    return ledgerPath ? `artshelf ${command} --ledger ${ledgerPath}` : `artshelf ${command}`;
+}
+function statusNextAction(blockers, counts, scope, ledgerPath) {
+    if (blockers.length > 0) {
+        const verify = statusCommand(scope, "status", ledgerPath);
+        return `repair ${blockers.length} broken ledger(s) above, then re-run \`${verify}\``;
+    }
+    const review = statusCommand(scope, "review", ledgerPath);
+    if (counts.pendingCleanup > 0 || counts.due > 0) {
+        return `run \`${review}\` to preview cleanup plans; nothing is auto-executed`;
+    }
+    if (counts.manualReview > 0) {
+        return `run \`${review}\` to inspect manual-review records; nothing is auto-executed`;
+    }
+    if (counts.missingPath > 0) {
+        return "inspect missing-path records and `artshelf resolve` the ones no longer needed; nothing is auto-executable";
+    }
+    return "nothing due — no broken ledgers and no due, manual-review, missing-path, or pending cleanup entries";
+}
+function buildStatusAgentPacketAll(report) {
+    const blockers = [];
+    if (report.registryError)
+        blockers.push(`registry unreadable: ${report.registryError}`);
+    for (const ledger of report.ledgers) {
+        if (ledger.status !== "ok") {
+            blockers.push(`${ledger.name} ${ledger.status}${ledger.errors.length ? `: ${ledger.errors[0]}` : ""}`);
+        }
+    }
+    const counts = {
+        active: report.totals.active,
+        due: report.totals.due,
+        manualReview: report.totals.manualReview,
+        missingPath: report.totals.missingPath,
+        kept: report.totals.kept,
+        pendingCleanup: report.totals.pendingCleanup
+    };
+    return {
+        schemaVersion: 1,
+        command: "status",
+        scope: "all",
+        health: report.ok ? "ok" : "attention",
+        registry: { path: report.registryPath, exists: report.registryExists, ok: report.registryOk, error: report.registryError },
+        ledgers: { total: report.totals.ledgers, ok: report.totals.ok, stale: report.totals.stale, invalid: report.totals.invalid },
+        counts,
+        attention: statusAttention(counts),
+        blockers,
+        nextAction: statusNextAction(blockers, counts, "all"),
+        verification: `artshelf status --all --agent --registry ${report.registryPath}`
+    };
+}
+function buildStatusAgentPacketSingle(ledger, ledgerPath) {
+    const blockers = ledger.ok
+        ? []
+        : [`${ledger.status}${ledger.errors.length ? `: ${ledger.errors[0]}` : ""}`];
+    return {
+        schemaVersion: 1,
+        command: "status",
+        scope: "single",
+        health: ledger.ok ? "ok" : "attention",
+        ledgerPath,
+        counts: ledger.counts,
+        attention: statusAttention(ledger.counts),
+        blockers,
+        nextAction: statusNextAction(blockers, ledger.counts, "single", ledgerPath),
+        verification: `artshelf status --agent --ledger ${ledgerPath}`
+    };
+}
 function printStatusAll(report) {
-    process.stdout.write(`artshelf status: ${report.ok ? "ok" : "needs attention"}\n`);
+    const anyActionable = report.ledgers.some((ledger) => statusAttention(ledger.counts).length > 0);
+    process.stdout.write(`${attentionGlyph(!report.ok || anyActionable)} artshelf status: ${report.ok ? "ok" : "needs attention"}\n`);
     process.stdout.write(`registry: ${report.registryPath}${report.registryExists ? "" : " (absent)"} — ${report.totals.ledgers} ledgers (${report.totals.ok} ok, ${report.totals.stale} stale, ${report.totals.invalid} invalid)\n`);
     if (report.registryError)
         process.stdout.write(`registry error: ${report.registryError}\n`);
     for (const ledger of report.ledgers) {
         if (ledger.status === "ok") {
-            process.stdout.write(`[${ledger.name}] ${formatStatusCounts(ledger.counts)}\n`);
+            process.stdout.write(`${attentionGlyph(statusAttention(ledger.counts).length > 0)} [${ledger.name}] ${formatStatusCounts(ledger.counts)}\n`);
         }
         else {
-            process.stdout.write(`[${ledger.name}] ${ledger.status}: ${ledger.errors.join("; ")}\n`);
+            process.stdout.write(`${HUMAN_ATTENTION_GLYPH} [${ledger.name}] ${ledger.status}: ${ledger.errors.join("; ")}\n`);
         }
     }
     process.stdout.write(`total: ${formatStatusCounts(report.totals)}\n`);
 }
 function printStatusSingle(ledger) {
-    process.stdout.write(`artshelf status: ${ledger.ok ? "ok" : ledger.status}\n`);
+    const needsAttention = !ledger.ok || statusAttention(ledger.counts).length > 0;
+    process.stdout.write(`${attentionGlyph(needsAttention)} artshelf status: ${ledger.ok ? "ok" : ledger.status}\n`);
     process.stdout.write(`ledger: ${ledger.path}\n`);
     if (ledger.ok) {
         process.stdout.write(`${formatStatusCounts(ledger.counts)}\n`);
@@ -950,6 +1110,14 @@ function parseArgs(argv) {
         const arg = rest[index];
         if (!arg)
             continue;
+        if (arg === "-h") {
+            flags.set("help", true);
+            continue;
+        }
+        if (arg === "-v") {
+            flags.set("version", true);
+            continue;
+        }
         if (!arg.startsWith("--")) {
             positionals.push(arg);
             continue;
@@ -996,6 +1164,12 @@ function printJson(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
     return 0;
 }
+// Agent/compact surface: a single minified JSON line. The default `--json`
+// stays pretty-printed for audit/debug; agent packets optimize for tokens.
+function printCompactJson(value) {
+    process.stdout.write(`${JSON.stringify(value)}\n`);
+    return 0;
+}
 function registeredLedgersOrThrow(registryPath) {
     const ledgers = listRegisteredLedgers(registryPath);
     if (ledgers.length === 0)
@@ -1145,13 +1319,16 @@ function summarizeReview(results) {
     }
     return summary;
 }
-function reviewNextAction(summary) {
+function reviewNextAction(summary, scope, ledgerPath) {
     const broken = summary.invalid + summary.stale;
+    const review = statusCommand(scope, "review", ledgerPath);
     if (broken > 0) {
-        return `repair ${broken} broken ledger(s) above (re-register or fix the file), then re-run \`artshelf review --all\``;
+        const repair = scope === "all" ? "re-register or fix the file" : "fix the file";
+        return `repair ${broken} broken ledger(s) above (${repair}), then re-run \`${review}\``;
     }
     if (summary.executable > 0) {
-        return "run `artshelf cleanup --dry-run --all` to generate plans, then `artshelf cleanup --execute --plan-id <id> --ledger <path>` for each reviewed plan";
+        const dryRun = scope === "all" ? "artshelf cleanup --dry-run --all" : `artshelf cleanup --dry-run${ledgerPath ? ` --ledger ${ledgerPath}` : ""}`;
+        return `run \`${dryRun}\` to generate plans, then \`artshelf cleanup --execute --plan-id <id> --ledger <path>\` for each reviewed plan`;
     }
     if (summary.missingPath > 0) {
         return "inspect missing-path entries and `artshelf resolve` the ones no longer needed; nothing is auto-executable";
@@ -1160,7 +1337,7 @@ function reviewNextAction(summary) {
 }
 function printReviewAll(results, summary, nextAction, registryPath) {
     const needsAttention = summary.invalid + summary.stale + summary.executable + summary.due + summary.manualReview + summary.missingPath > 0;
-    process.stdout.write(`artshelf review --all: ${needsAttention ? "needs attention" : "all clear"}\n`);
+    process.stdout.write(`${attentionGlyph(needsAttention)} artshelf review --all: ${needsAttention ? "needs attention" : "all clear"}\n`);
     process.stdout.write(`registry: ${registryPath} — ${summary.ledgers} ledgers (${summary.ok} ok, ${summary.invalid} invalid, ${summary.stale} stale)\n`);
     printReview(results);
     process.stdout.write(`triage: due ${summary.due} · manual-review ${summary.manualReview} · missing ${summary.missingPath} · executable ${summary.executable} · skipped ${summary.skipped}\n`);
@@ -1169,12 +1346,236 @@ function printReviewAll(results, summary, nextAction, registryPath) {
 function printReview(results) {
     for (const result of results) {
         const visibleDue = result.due.filter((entry) => entry.dueStatus !== "kept");
-        process.stdout.write(`[${result.ledger.name}] ${result.validate.ok ? "ok" : "invalid"}: ${result.validate.entries} entries, ${result.validate.errors.length} errors, ${result.validate.warnings.length} warnings\n`);
+        const needsAttention = !result.validate.ok || visibleDue.length > 0 || result.plan.entries.length > 0;
+        process.stdout.write(`${attentionGlyph(needsAttention)} [${result.ledger.name}] ${result.validate.ok ? "ok" : "invalid"}: ${result.validate.entries} entries, ${result.validate.errors.length} errors, ${result.validate.warnings.length} warnings\n`);
         process.stdout.write(`due/manual/missing: ${visibleDue.length}; plan ${result.plan.planId}: ${result.plan.entries.length} entries, ${result.plan.skipped.length} skipped\n`);
         process.stdout.write(`ledger: ${result.ledger.path}\n`);
     }
 }
-function printHelp(command) {
+// review is read-only, so every safety guarantee holds unconditionally.
+const REVIEW_SAFETY = {
+    dryRunOnly: true,
+    executeAllRefused: true,
+    noExecuteRan: true,
+    noResolveRan: true,
+    noDeleteRan: true
+};
+// Classify each registered ledger's records into decision groups. Order is
+// fixed (registry order, then a stable per-ledger sub-order) so the packet is
+// byte-for-byte deterministic.
+function buildReviewDecisions(results, scope) {
+    const readyForApproval = [];
+    const needsReviewFirst = [];
+    const blocked = [];
+    const review = scope === "all" ? "artshelf review --all" : "artshelf review";
+    for (const result of results) {
+        const { ledger, validate, due } = result;
+        if (!validate.ok) {
+            const status = existsSync(ledger.path) ? "invalid" : "missing";
+            const repair = scope === "all" ? `re-register or fix ${ledger.path}` : `fix ${ledger.path}`;
+            blocked.push({
+                label: `Repair ${ledger.name} ledger (${status})`,
+                itemIds: [],
+                actionType: "fix-registry",
+                approvalTarget: null,
+                reason: validate.errors[0] ?? `${scope === "all" ? "registered ledger" : "ledger"} is ${status}`,
+                nextStep: `${repair}, then re-run \`${review}\``
+            });
+            continue;
+        }
+        const missingPath = due.filter((entry) => entry.dueStatus === "missing-path");
+        const trashSafe = due.filter((entry) => entry.dueStatus === "due" && entry.cleanup === "trash");
+        const inspectItems = due.filter((entry) => entry.dueStatus === "manual-review" ||
+            (entry.dueStatus === "due" && (entry.cleanup === "review" || entry.cleanup === "delete")));
+        // Ready for approval: missing-path records resolve ledger-only with an exact,
+        // plan-less approval target. Resolution updates the ledger and never touches
+        // files, so it is the one action review can hand an agent directly.
+        if (missingPath.length > 0) {
+            const ids = missingPath.map((entry) => entry.id).sort();
+            readyForApproval.push({
+                label: `Resolve ${ids.length} missing-path record(s) in ${ledger.name}`,
+                itemIds: ids,
+                actionType: "resolve-missing",
+                approvalTarget: `approve artshelf resolve missing ledger ${ledger.path} ids ${ids.join(" ")}`,
+                reason: "the recorded path is already missing",
+                nextStep: "confirm the artifact is no longer needed, then approve the ledger-only resolve"
+            });
+        }
+        // Trash-safe records are cleanup-eligible, but review never mints a plan, so
+        // they carry no approval target: the next step is the dry-run that produces
+        // the reviewed plan id to approve.
+        if (trashSafe.length > 0) {
+            const ids = trashSafe.map((entry) => entry.id).sort();
+            needsReviewFirst.push({
+                label: `Plan cleanup for ${ids.length} trash-eligible artifact(s) in ${ledger.name}`,
+                itemIds: ids,
+                actionType: "cleanup",
+                approvalTarget: null,
+                reason: "disposable artifacts are due but no reviewed cleanup plan exists yet",
+                nextStep: `run \`artshelf cleanup --dry-run --ledger ${ledger.path} --json\`, then approve \`approve artshelf cleanup ledger ${ledger.path} plan <plan-id>\``
+            });
+        }
+        // manual-review and cleanup=review records need a human decision before any
+        // cleanup; cleanup=delete is refused outright. None carry an approval target.
+        if (inspectItems.length > 0) {
+            const ids = inspectItems.map((entry) => entry.id).sort();
+            const hasDelete = inspectItems.some((entry) => entry.cleanup === "delete");
+            needsReviewFirst.push({
+                label: `Inspect ${ids.length} record(s) in ${ledger.name} before cleanup`,
+                itemIds: ids,
+                actionType: "inspect",
+                approvalTarget: null,
+                reason: hasDelete
+                    ? "records need manual review; cleanup=delete is refused and never deletes files"
+                    : "records are held for manual review before any cleanup",
+                nextStep: "inspect each path, then keep, change retention, resolve, or set cleanup=trash and plan a cleanup"
+            });
+        }
+    }
+    return { readyForApproval, needsReviewFirst, blocked };
+}
+function reviewCounts(summary) {
+    return {
+        due: summary.due,
+        manualReview: summary.manualReview,
+        missingPath: summary.missingPath,
+        executable: summary.executable,
+        skipped: summary.skipped
+    };
+}
+function buildReviewAgentPacketAll(results, summary, registryPath) {
+    const groups = buildReviewDecisions(results, "all");
+    return {
+        schemaVersion: 1,
+        command: "review",
+        scope: "all",
+        health: summary.invalid + summary.stale > 0 ? "attention" : "ok",
+        registry: { path: registryPath, exists: existsSync(registryPath) },
+        ledgers: { total: summary.ledgers, ok: summary.ok, stale: summary.stale, invalid: summary.invalid },
+        counts: reviewCounts(summary),
+        decisionSummary: {
+            readyForApproval: groups.readyForApproval.length,
+            needsReviewFirst: groups.needsReviewFirst.length,
+            blocked: groups.blocked.length
+        },
+        readyForApproval: groups.readyForApproval,
+        needsReviewFirst: groups.needsReviewFirst,
+        blocked: groups.blocked,
+        safety: REVIEW_SAFETY,
+        nextAction: reviewNextAction(summary, "all"),
+        verification: `artshelf review --all --agent --registry ${registryPath}`
+    };
+}
+function buildReviewAgentPacketSingle(result, ledgerPath) {
+    const summary = summarizeReview([result]);
+    const groups = buildReviewDecisions([result], "single");
+    return {
+        schemaVersion: 1,
+        command: "review",
+        scope: "single",
+        health: summary.invalid + summary.stale > 0 ? "attention" : "ok",
+        ledgerPath,
+        counts: reviewCounts(summary),
+        decisionSummary: {
+            readyForApproval: groups.readyForApproval.length,
+            needsReviewFirst: groups.needsReviewFirst.length,
+            blocked: groups.blocked.length
+        },
+        readyForApproval: groups.readyForApproval,
+        needsReviewFirst: groups.needsReviewFirst,
+        blocked: groups.blocked,
+        safety: REVIEW_SAFETY,
+        nextAction: reviewNextAction(summary, "single", ledgerPath),
+        verification: `artshelf review --agent --ledger ${ledgerPath}`
+    };
+}
+const COMMAND_GROUPS = [
+    {
+        group: "Create",
+        commands: [{ name: "put", summary: "Record an artifact with a reason and retention" }]
+    },
+    {
+        group: "Inspect",
+        commands: [
+            { name: "list", summary: "List ledger records" },
+            { name: "find", summary: "Find records by path, owner, label, or status" },
+            { name: "get", summary: "Show one record by id" },
+            { name: "due", summary: "Show due, manual-review, and missing-path records" },
+            { name: "status", summary: "Summarize ledger and registry counts" }
+        ]
+    },
+    {
+        group: "Review",
+        commands: [
+            { name: "validate", summary: "Check ledger shape and report warnings" },
+            { name: "review", summary: "Preview validate, due, and cleanup plans (read-only)" }
+        ]
+    },
+    {
+        group: "Clean",
+        commands: [
+            { name: "cleanup", summary: "Plan and execute approved cleanups" },
+            { name: "trash", summary: "Inspect and purge Artshelf trash" },
+            { name: "resolve", summary: "Mark a record manually resolved" }
+        ]
+    },
+    {
+        group: "System",
+        commands: [
+            { name: "ledgers", summary: "Manage the ledger registry" },
+            { name: "doctor", summary: "Report Artshelf health on this machine" },
+            { name: "update", summary: "Update the Artshelf CLI" }
+        ]
+    }
+];
+// Commands with subcommands that carry their own focused help. Used to route
+// `artshelf <command> <subcommand> --help` to a nested help key.
+const NESTED_HELP = new Map([
+    ["trash", new Set(["list", "purge"])],
+    ["ledgers", new Set(["list", "add"])]
+]);
+function resolveHelpKey(parsed) {
+    // `artshelf help [command [subcommand]]`
+    if (parsed.command === "help") {
+        return joinHelpKey(parsed.positionals[0], parsed.positionals[1]);
+    }
+    // `artshelf [--help|-h]` with no command resolves to the top-level help.
+    if (!parsed.command || parsed.command === "--help" || parsed.command === "-h") {
+        return "";
+    }
+    // `artshelf <command> [subcommand] --help`
+    return joinHelpKey(parsed.command, parsed.positionals[0]);
+}
+function joinHelpKey(command, subcommand) {
+    if (!command)
+        return "";
+    const subcommands = NESTED_HELP.get(command);
+    if (subcommands && subcommand && subcommands.has(subcommand)) {
+        return `${command} ${subcommand}`;
+    }
+    return command;
+}
+function renderTopLevelHelp() {
+    const names = COMMAND_GROUPS.flatMap((entry) => entry.commands.map((command) => command.name));
+    const width = Math.max(...names.map((name) => name.length)) + 2;
+    const lines = [
+        `Artshelf ${VERSION} — approval-first retention for the temporary files agents leave behind.`,
+        "",
+        "Usage:",
+        "  artshelf <command> [options]",
+        "",
+        "Available Commands:"
+    ];
+    for (const { group, commands } of COMMAND_GROUPS) {
+        lines.push(`  ${group}`);
+        for (const command of commands) {
+            lines.push(`    ${command.name.padEnd(width)}${command.summary}`);
+        }
+    }
+    lines.push("", "Global Options:", "  -h, --help     Show help for artshelf or a specific command", "  -v, --version  Show the Artshelf version", "", "Output:", "  --json       Emit machine-readable JSON on commands that return data", "", "Scope (command-specific):", "  --ledger <path>     Target an explicit JSONL ledger", "  --registry <path>   Target an explicit ledger registry", "  --all               Read every registered ledger (on commands that support it)", "", `Use "artshelf <command> --help" for more information about a command.`, "");
+    return lines.join("\n");
+}
+function printHelp(command = "") {
     if (command === "put") {
         process.stdout.write(`Usage:
   artshelf put <path> --reason <text> (--ttl <ttl>|--retain-until <date>|--manual-review) [options]
@@ -1208,30 +1609,36 @@ Global --all mode is dry-run only.
         return;
     }
     if (command === "trash") {
-        process.stdout.write(`Usage:
-  artshelf trash list [--ledger <path>] [--all] [--json]
-  artshelf trash purge --older-than <ttl> --dry-run [--ledger <path>] [--json]
-  artshelf trash purge --execute --plan-id <id> [--ledger <path>] [--json]
+        process.stdout.write(`Inspect and purge Artshelf trash.
 
-Trash is approval-first. Use list to inspect what is currently in Artshelf trash and
-dry-run purge to generate a reviewed plan id for age-based deletion. Purge
-requires either --dry-run or --execute. Execute requires a reviewed plan id, and
-trash purge is always scoped to one --ledger; --all is not supported for purge
-(only for trash list).
-Trash receipt artifacts are registered when purge executes. Completed receipts are
-refused on repeat execute; started receipts from interrupted purges may be resumed
-and reconciled. Purged records are resolved and no longer reappear as trashed.
+Usage:
+  artshelf trash [command]
+
+Available Commands:
+  list      List records currently held in Artshelf trash
+  purge     Plan or execute approved permanent trash deletion
+
+Flags:
+  -h, --help   help for trash
+
+Use "artshelf trash <command> --help" for more information about a command.
 `);
         return;
     }
     if (command === "ledgers") {
-        process.stdout.write(`Usage:
-  artshelf ledgers list [--plain] [--registry <path>] [--json]
-  artshelf ledgers add --ledger <path> [--name <name>] [--scope repo|user|other] [--registry <path>] [--json]
+        process.stdout.write(`Manage the ledger registry.
+
+Usage:
+  artshelf ledgers [command]
 
-The ledger registry is a global index of known ledgers. It gives Artshelf one read-only entry point without moving project records into one global ledger.
-By default \`list\` validates each registered ledger and reports ok/missing/invalid status, entry counts, and warning/error counts so agents can spot stale registry entries without a separate validate pass; it exits non-zero when the registry or any registered ledger is broken.
-Use \`--plain\` for the fast path that lists registered ledgers without reading them.
+Available Commands:
+  list      List and validate registered ledgers
+  add       Register an existing ledger file
+
+Flags:
+  -h, --help   help for ledgers
+
+Use "artshelf ledgers <command> --help" for more information about a command.
 `);
         return;
     }
@@ -1283,17 +1690,28 @@ Resolved records stay in the audit trail but no longer participate in due or cle
     }
     if (command === "review") {
         process.stdout.write(`Usage:
-  artshelf review [--ledger <path>] [--json]
-  artshelf review --all [--registry <path>] [--json]
+  artshelf review [--ledger <path>] [--json|--agent]
+  artshelf review --all [--registry <path>] [--json|--agent]
 
-Review runs validate, due, and cleanup plan preview without moving files or writing a plan.
-With --all, review adds aggregate triage counts and the next safe action.
+Review runs validate, due, and cleanup plan preview without moving files or
+writing a plan. With --all, review adds aggregate triage counts and the next
+safe action.
+
+Render modes:
+  (default)  Human summary of validation, triage counts, and the next safe action.
+  --json     Full read-only audit report (backward-compatible).
+  --agent    Compact single-line JSON decision packet for agents: health, triage
+             counts, and classified decision groups (ready for approval, needs
+             review first, blocked) with exact approval targets where they are
+             safe. Review is read-only, so cleanup approval targets are minted by
+             \`cleanup --dry-run\`, never leaked from a preview plan id.
+             Token-efficient; --agent takes precedence over --json.
 `);
         return;
     }
     if (command === "doctor") {
         process.stdout.write(`Usage:
-  artshelf doctor [--registry <path>] [--ledger <path>] [--json]
+  artshelf doctor [--registry <path>] [--ledger <path>] [--json|--agent]
 
 Doctor reports whether Artshelf is healthy on this machine: CLI version, selected
 or default ledger path, selected or global registry path, registered ledger health
@@ -1302,6 +1720,14 @@ selected or default ledger and still requires a reviewed plan id; --all execute
 and cleanup=delete are refused, while physical trash purge requires a separate
 reviewed purge plan.
 
+Render modes:
+  (default)  Human summary of machine health and cleanup safety.
+  --json     Full audit report (backward-compatible; suitable for cron/reporting).
+  --agent    Compact single-line JSON decision packet for agents: health, registry
+             and registered-ledger health, blockers, cleanup-safety posture, next
+             action, and a verify command. Token-efficient; --agent takes
+             precedence over --json.
+
 Run it after install, when --all commands behave unexpectedly, or on a schedule to
 catch stale registry entries. Doctor is read-only. A healthy machine exits 0; a
 broken registry or registered ledger exits non-zero with actionable errors.
@@ -1310,8 +1736,8 @@ broken registry or registered ledger exits non-zero with actionable errors.
     }
     if (command === "status") {
         process.stdout.write(`Usage:
-  artshelf status [--ledger <path>] [--json]
-  artshelf status --all [--registry <path>] [--json]
+  artshelf status [--ledger <path>] [--json|--agent]
+  artshelf status --all [--registry <path>] [--json|--agent]
 
 Status is the lightweight daily "what is going on?" view. Without --all, it
 reports counts for the selected or default ledger only. With --all, it adds
@@ -1319,10 +1745,16 @@ registry health, total ledgers, and aggregated counts across registered ledgers.
 Counts include active artifacts, kept, due, manual-review, missing-path, and
 pending cleanup entries.
 
-Human output is short enough to paste into a chat; \`artshelf status --all --json\`
-is suitable for cron and reporting. Status is read-only: it never creates plans
-or receipts and never mutates records. A healthy selected ledger exits 0; with
---all, a broken registry or any stale or invalid registered ledger exits non-zero.
+Render modes:
+  (default)  Human summary, short enough to paste into a chat.
+  --json     Full audit report (backward-compatible; suitable for cron/reporting).
+  --agent    Compact single-line JSON decision packet for agents: health, counts,
+             attention categories, blockers, next action, and a verify command.
+             Token-efficient; --agent takes precedence over --json.
+
+Status is read-only: it never creates plans or receipts and never mutates
+records. A healthy selected ledger exits 0; with --all, a broken registry or any
+stale or invalid registered ledger exits non-zero.
 `);
         return;
     }
@@ -1341,50 +1773,99 @@ installs should update by pulling, rebuilding, and linking the checkout.
 `);
         return;
     }
-    process.stdout.write(`Artshelf ${VERSION}
+    if (command === "due") {
+        process.stdout.write(`Usage:
+  artshelf due [--ledger <path>] [--json]
+  artshelf due --all [--registry <path>] [--json]
 
-Usage:
-  artshelf put <path> --reason <text> (--ttl <ttl>|--retain-until <date>|--manual-review)
-  artshelf ledgers list [--plain] [--json]
-  artshelf ledgers add --ledger <path> [--name <name>] [--json]
-  artshelf list [--json]
-  artshelf list --all [--json]
-  artshelf list --status active [--json]
-  artshelf find --path <path> [--json]
-  artshelf find --all --owner <name> [--json]
-  artshelf get <id> [--json]
-  artshelf get <id> --all [--json]
-  artshelf due [--json]
-  artshelf due --all [--json]
-  artshelf validate [--json]
-  artshelf validate --all [--json]
-  artshelf review [--json]
-  artshelf review --all [--json]
-  artshelf doctor [--json]
-  artshelf status [--json]
-  artshelf status --all [--json]
-  artshelf update [--json]
-  artshelf cleanup --dry-run [--json]
-  artshelf cleanup --dry-run --all [--json]
-  artshelf cleanup --execute --plan-id <id> [--json]
-  artshelf trash list [--all] [--ledger <path>] [--json]
+Due lists records whose retention has elapsed or that need attention: due,
+manual-review, and missing-path entries. Kept entries are hidden in human output.
+Due is read-only and never moves files or writes plans.
+`);
+        return;
+    }
+    if (command === "validate") {
+        process.stdout.write(`Usage:
+  artshelf validate [--ledger <path>] [--json]
+  artshelf validate --all [--registry <path>] [--json]
+
+Validate checks ledger shape and reports errors and warnings, such as records
+that point at missing artifact paths, without changing anything. A clean ledger
+exits 0; shape errors exit non-zero. With --all it validates every registered
+ledger.
+`);
+        return;
+    }
+    if (command === "trash list") {
+        process.stdout.write(`Usage:
+  artshelf trash list [--ledger <path>] [--all] [--registry <path>] [--json]
+
+Options:
+  --ledger <path>          Use a specific ledger file
+  --all                     Include records from all registered ledgers
+  --registry <path>         Registry path used with --all
+  --json                    Emit machine-readable output
+
+Trash list shows records currently held in Artshelf trash without deleting anything.
+With --all it reports trashed records across every registered ledger.
+`);
+        return;
+    }
+    if (command === "trash purge") {
+        process.stdout.write(`Usage:
   artshelf trash purge --older-than <ttl> --dry-run [--ledger <path>] [--json]
   artshelf trash purge --execute --plan-id <id> [--ledger <path>] [--json]
-  artshelf resolve <id> --status resolved --reason <text> [--json]
 
-Global options:
-  --ledger <path>        Use an explicit JSONL ledger
-  --registry <path>      Use an explicit ledger registry
-  --all                  Read all registered ledgers for supported commands
-  --json                 Emit machine-readable JSON
-  --help                 Show help
-  --version              Show version
+Options:
+  --older-than <ttl>        Purge trashed records older than this duration
+  --dry-run                 Build a reviewed purge plan and output a plan id
+  --execute                 Execute a reviewed purge plan
+  --plan-id <id>            Execute only this reviewed purge plan
+  --ledger <path>           Target one specific ledger
+  --json                    Emit machine-readable output
 
-Examples:
-  artshelf put tmp/run-output --reason "debug parser output" --ttl 3d --kind scratch
-  artshelf cleanup --dry-run --json
-  artshelf cleanup --execute --plan-id plan_20260601_120000_ab12
+Trash purge permanently deletes aged trash from a reviewed plan. --dry-run turns
+--older-than into a reviewed purge plan id; --execute deletes only that one reviewed
+plan id. Purge is always scoped to one --ledger; --all is not supported for purge.
+Completed receipts are refused on repeat execute; an interrupted purge may be resumed
+and reconciled.
 `);
+        return;
+    }
+    if (command === "ledgers list") {
+        process.stdout.write(`Usage:
+  artshelf ledgers list [--plain] [--registry <path>] [--json]
+
+Options:
+  --plain                  Skip ledger validation and list registrations directly
+  --registry <path>        Registry path to use
+  --json                   Emit machine-readable output
+
+Ledgers list validates every registered ledger and reports ok/missing/invalid
+status, entry counts, and warnings so agents can spot stale registry entries
+without a separate validate pass. Use --plain for the fast path that lists
+registered ledgers without reading them. It exits non-zero when the registry or
+any registered ledger is broken.
+`);
+        return;
+    }
+    if (command === "ledgers add") {
+        process.stdout.write(`Usage:
+  artshelf ledgers add --ledger <path> [--name <name>] [--scope repo|user|other] [--registry <path>] [--json]
+
+Options:
+  --ledger <path>          Register this ledger file
+  --name <name>            Override the ledger display name
+  --scope <scope>          Registry scope: repo, user, or other
+  --registry <path>        Registry path to update
+  --json                   Emit machine-readable output
+
+Ledgers add registers an existing ledger file in the global registry so --all
+commands and the registry index can find it. The ledger file must already exist.
+`);
+        return;
+    }
+    process.stdout.write(renderTopLevelHelp());
 }
 main(process.argv.slice(2))
     .then((status) => {