artshelf 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -58,6 +58,29 @@
   pages backed by shared docs-site chrome, search, and navigation.
 - Added `artshelf update` plus cached npm update notices, with
   `ARTSHELF_NO_UPDATE_CHECK=1` for no-network scheduled jobs.
+- Rewrote `artshelf help` into a compact, grouped command list (Create, Inspect,
+  Review, Clean, System) with one-line summaries and focused per-command help,
+  added nested help for `trash`/`ledgers` subcommands plus `artshelf trash help`
+  and `artshelf ledgers help` aliases, advertised short `-h`/`-v` flags, and
+  reclassified `--ledger`, `--registry`, and `--all` as command-specific scope
+  flags instead of global options.
+
+## [0.9.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.8.0...artshelf-v0.9.0) (2026-06-11)
+
+
+### Features
+
+* **cli:** rewrite help with grouped commands, focused per-command help, and short flags ([7310638](https://github.com/calvinnwq/artshelf/commit/73106385ce3e3d037921cdb4ff534614d024244f))
+* **cli:** rewrite top-level help with grouped commands, focused per-command help, and subcommand routing ([c8dea22](https://github.com/calvinnwq/artshelf/commit/c8dea2255628915eb629c5cc4cbc2ef1ec31c3a7))
+
+
+### Bug Fixes
+
+* **cli:** advertise short help flag ([825c4ae](https://github.com/calvinnwq/artshelf/commit/825c4ae38aa61209f22c702a82f51b93c5ea3d09))
+* **cli:** advertise short version flag ([23ca99b](https://github.com/calvinnwq/artshelf/commit/23ca99b0ba7c596a8df89ec3c0384286c55d2a96))
+* **cli:** polish nested help output ([109255d](https://github.com/calvinnwq/artshelf/commit/109255dfa3baa50c6aae837190adb19cfa7249b8))
+* **cli:** support ledgers help subcommand ([18723ce](https://github.com/calvinnwq/artshelf/commit/18723ce384fbdeed33fe066ad0093093d30dc5a5))
+* **cli:** support short help flag ([081b50f](https://github.com/calvinnwq/artshelf/commit/081b50f67a5e0821341aca4f98ab3244ab316338))
 
 ## [0.8.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.7.0...artshelf-v0.8.0) (2026-06-11)
 

package/README.md

@@ -120,8 +120,8 @@ destructive deletion.
 
 ```bash
 artshelf put <path> --reason "debug parser output" --ttl 3d --kind scratch
-artshelf ledgers list [--plain]
-artshelf ledgers add --ledger <path>
+artshelf ledgers list [--plain] [--json]
+artshelf ledgers add --ledger <path> [--name <project>] [--scope repo|user|other] [--json]
 artshelf list [--all] [--status active]
 artshelf find --path <path> --owner <agent-or-runtime> --label <task-or-run-id>
 artshelf find --all --owner <agent-or-runtime>
@@ -133,15 +133,18 @@ artshelf status [--all]
 artshelf doctor
 artshelf update [--json]
 artshelf cleanup --dry-run [--all]
-artshelf cleanup --execute --plan-id <id>
+artshelf cleanup --execute --plan-id <id> [--ledger <path>] [--json]
 artshelf trash list [--all] [--ledger <path>] [--json]
 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 "inspected and no longer needed"
+artshelf resolve <id> --status resolved --reason "inspected and no longer needed" [--ledger <path>] [--json]
 ```
 
-Use `artshelf help` or `artshelf help <command>` for details. All core commands
-support `--json`.
+Use `artshelf help` for a grouped command list, then `artshelf <command> --help`
+or `artshelf help <command>` for focused details. Nested commands such as
+`artshelf trash purge --help` and `artshelf ledgers add --help` show only that
+subcommand. All core commands support `--json`; `--ledger`, `--registry`, and
+`--all` are scope flags only on commands that list them.
 </details>
 
 <details>
@@ -159,7 +162,7 @@ artshelf list --ledger /tmp/artshelf-ledger.jsonl
 Artshelf keeps a small global registry of known ledgers at
 `~/.artshelf/ledgers.json` (override with `--registry <path>` or
 `ARTSHELF_REGISTRY`). `put` registers its ledger automatically; register an
-existing one with `artshelf ledgers add --ledger <path> --name <project>`.
+existing one with `artshelf ledgers add --ledger <path> --name <project> --json`.
 `artshelf ledgers list` validates each registered ledger by default (ok/missing/invalid
 status with counts, non-zero exit when broken), so it doubles as a stale-entry
 check; add `--plain` to skip validation.

package/SPEC.md

@@ -36,6 +36,35 @@ somewhere accountable, with an expiry tag and a cleanup plan.
 
 ## V1 CLI
 
+### Help and option presentation
+
+Top-level help is compact and points readers to focused command help.
+
+```bash
+artshelf help
+artshelf --help
+artshelf <command> --help
+artshelf help <command>
+artshelf <command> <subcommand> --help
+artshelf help <command> <subcommand>
+```
+
+Rules:
+
+- `artshelf help`, `artshelf --help`, and `artshelf -h` show a grouped command
+  list with one-line summaries instead of dumping every command variant.
+- Command groups are `Create`, `Inspect`, `Review`, `Clean`, and `System`.
+- `artshelf <command> --help` and `artshelf help <command>` show focused help
+  for that command.
+- Nested help is supported for `trash list`, `trash purge`, `ledgers list`, and
+  `ledgers add`.
+- `artshelf trash help` and `artshelf ledgers help` are aliases for the focused
+  help of those commands, matching `artshelf help trash` and `artshelf help ledgers`.
+- Top-level help presents `-h, --help` and `-v, --version` as global options,
+  `--json` as the output mode, and `--ledger`, `--registry`, and `--all` as
+  command-specific scope flags. The short `-h` and `-v` forms work both at the
+  top level and after a command.
+
 ### `artshelf put`
 
 Records an existing file or directory in the ledger.
@@ -79,8 +108,9 @@ Lists or registers known Artshelf ledgers.
 
 ```bash
 artshelf ledgers list
+artshelf ledgers list --json
 artshelf ledgers list --plain
-artshelf ledgers add --ledger <path> --name <project> --scope repo
+artshelf ledgers add --ledger <path> --name <project> --scope repo --json
 ```
 
 Rules:
@@ -361,8 +391,8 @@ plan id.
 Executes a previously generated cleanup plan.
 
 ```bash
-artshelf cleanup --execute --plan-id <id>
-artshelf cleanup --execute --plan-id <id> --json
+artshelf cleanup --execute --plan-id <id> [--ledger <path>]
+artshelf cleanup --execute --plan-id <id> [--ledger <path>] --json
 ```
 
 Rules:

package/dist/src/cli.js

@@ -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))
@@ -950,6 +954,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;
@@ -1174,7 +1186,93 @@ function printReview(results) {
         process.stdout.write(`ledger: ${result.ledger.path}\n`);
     }
 }
-function printHelp(command) {
+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 +1306,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.
+
+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
 
-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.
+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.
 
-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.
+Usage:
+  artshelf ledgers [command]
+
+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;
     }
@@ -1341,50 +1445,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) => {

package/docs/agent-monitor.html

@@ -67,7 +67,7 @@
               plan id when attention exists.
             </p>
             <pre><code><span class="c"># register a project ledger so --all review can see it</span>
-artshelf ledgers add --ledger &lt;repo&gt;/.artshelf/ledger.jsonl --name &lt;project&gt; --scope repo
+artshelf ledgers add --ledger &lt;repo&gt;/.artshelf/ledger.jsonl --name &lt;project&gt; --scope repo --json
 
 <span class="c"># list registered ledgers and their health</span>
 artshelf ledgers list --json

package/docs/index.html

@@ -158,7 +158,7 @@ artshelf review --json</code></pre>
 ~/.artshelf/ledgers.json
 
 <span class="c"># put registers its ledger automatically; add existing ones explicitly</span>
-artshelf ledgers add --ledger &lt;repo&gt;/.artshelf/ledger.jsonl --name &lt;project&gt; --scope repo
+artshelf ledgers add --ledger &lt;repo&gt;/.artshelf/ledger.jsonl --name &lt;project&gt; --scope repo --json
 
 <span class="c"># --all commands read across every registered ledger</span>
 artshelf review --all --json</code></pre>

package/docs/reference.html

@@ -42,6 +42,13 @@
             cleanup execution and trash purge. Every command below is tagged read-only,
             writes ledger, writes registry, npm install, or approval-gated.
           </p>
+          <p>
+            Run <code>artshelf help</code> for the grouped command list. Use
+            <code>artshelf &lt;command&gt; --help</code> or
+            <code>artshelf help &lt;command&gt;</code> for focused help; nested commands
+            such as <code>artshelf trash purge --help</code> and
+            <code>artshelf ledgers add --help</code> show only that subcommand.
+          </p>
 
           <section class="cmd">
             <div class="cmd-head"><h2>artshelf put</h2><span class="cmd-flag plan">writes ledger</span></div>
@@ -70,7 +77,7 @@ artshelf ledgers list [--plain] [--json]</code></pre>
           <section class="cmd">
             <div class="cmd-head"><h2>artshelf ledgers add</h2><span class="cmd-flag plan">writes registry</span></div>
             <pre><code><span class="c"># register an existing ledger for --all review</span>
-artshelf ledgers add --ledger &lt;path&gt; [--name &lt;project&gt;] [--scope repo|user|other]</code></pre>
+artshelf ledgers add --ledger &lt;path&gt; [--name &lt;project&gt;] [--scope repo|user|other] [--json]</code></pre>
             <p>
               <code>add</code> registers an existing ledger so Artshelf can review it through one
               entry point; scope is inferred from the path when omitted.
@@ -153,7 +160,7 @@ artshelf update [--json]</code></pre>
 artshelf cleanup --dry-run [--all] [--json]
 
 <span class="c"># execute exactly one reviewed plan (approval only)</span>
-artshelf cleanup --execute --plan-id &lt;id&gt; [--ledger &lt;path&gt;]</code></pre>
+artshelf cleanup --execute --plan-id &lt;id&gt; [--ledger &lt;path&gt;] [--json]</code></pre>
             <p>
               <code>--dry-run</code> creates and registers a cleanup plan without moving files;
               no-op dry-runs report <code>not-created</code>, and matching dry-runs reuse the
@@ -188,18 +195,51 @@ artshelf trash purge --execute --plan-id &lt;id&gt; [--ledger &lt;path&gt;] [--j
 
           <section class="cmd">
             <div class="cmd-head"><h2>artshelf resolve</h2><span class="cmd-flag plan">writes ledger</span></div>
-            <pre><code>artshelf resolve &lt;id&gt; --status resolved --reason &lt;text&gt;</code></pre>
+            <pre><code>artshelf resolve &lt;id&gt; --status resolved --reason &lt;text&gt; [--json]</code></pre>
             <p>Mark a handled, missing, or no-longer-needed record as manually resolved. Updates the ledger only; never moves or deletes files.</p>
           </section>
 
           <section>
-            <h2>Global options</h2>
+            <h2>Global flags</h2>
+            <p>Only these apply to every command.</p>
+            <table class="opts">
+              <tr><th>option</th><th>meaning</th></tr>
+              <tr><td>-h, --help</td><td>show help for artshelf or a specific command</td></tr>
+              <tr><td>-v, --version</td><td>show the Artshelf version</td></tr>
+            </table>
+          </section>
+
+          <section>
+            <h2>Output mode</h2>
+            <p>
+              <code>--json</code> is the agent contract: it switches commands that return data,
+              records, plans, receipts, or health output to machine-readable JSON on stdout.
+              Update notices and other diagnostics stay on stderr and never corrupt JSON output.
+            </p>
+            <table class="opts">
+              <tr><th>option</th><th>meaning</th></tr>
+              <tr><td>--json</td><td>emit machine-readable JSON on commands that return data</td></tr>
+            </table>
+          </section>
+
+          <section>
+            <h2>Scope flags (command-specific)</h2>
+            <p>
+              These select which ledger or registry a command reads or writes. They are not
+              universal global flags; each only applies to the commands that support it.
+            </p>
             <table class="opts">
               <tr><th>option</th><th>meaning</th></tr>
-              <tr><td>--ledger &lt;path&gt;</td><td>use an explicit JSONL ledger</td></tr>
-              <tr><td>--registry &lt;path&gt;</td><td>use an explicit ledger registry</td></tr>
-              <tr><td>--all</td><td>read all registered ledgers for supported commands</td></tr>
-              <tr><td>--json</td><td>emit machine-readable JSON</td></tr>
+              <tr><td>--ledger &lt;path&gt;</td><td>target an explicit JSONL ledger</td></tr>
+              <tr><td>--registry &lt;path&gt;</td><td>target an explicit ledger registry</td></tr>
+              <tr><td>--all</td><td>read every registered ledger on commands that support discovery (<code>list</code>, <code>find</code>, <code>get</code>, <code>due</code>, <code>validate</code>, <code>review</code>, <code>status</code>, <code>cleanup --dry-run</code>, <code>trash list</code>)</td></tr>
+            </table>
+          </section>
+
+          <section>
+            <h2>Environment</h2>
+            <table class="opts">
+              <tr><th>variable</th><th>meaning</th></tr>
               <tr><td>ARTSHELF_REGISTRY</td><td>override the default ledger registry path</td></tr>
               <tr><td>ARTSHELF_NOW</td><td>override current time for retention and due calculations</td></tr>
               <tr><td>ARTSHELF_NO_UPDATE_CHECK=1</td><td>disable automatic npm update checks</td></tr>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artshelf",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Tiny CLI for accountable temporary artifact retention.",
   "type": "module",
   "author": "Calvin",