artshelf 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -58,6 +58,53 @@
   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.
+- Added an `--agent` render mode to `artshelf review`, `status`, and `doctor`: a
+  compact, deterministic single-line JSON decision packet (health, counts,
+  attention categories or classified decision groups, blockers, the next safe
+  action, and a verification command) tuned for agents acting on results.
+  `--agent` takes precedence over `--json`, while `--json` stays the full,
+  backward-compatible audit report. The default human renders of these three
+  commands now lead each ledger and summary line with a `✓`/`⚠` attention glyph
+  (plain Unicode, no color) so redirected output stays clean.
+
+## [0.10.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.9.0...artshelf-v0.10.0) (2026-06-12)
+
+
+### Features
+
+* **cli:** add --agent decision-packet render mode for review, status, and doctor ([4d2dee0](https://github.com/calvinnwq/artshelf/commit/4d2dee099569803b887ae49438b0747d1330ec5d))
+* **cli:** add --agent render mode and implement status --agent ([36f8e78](https://github.com/calvinnwq/artshelf/commit/36f8e7839d535fcabddadfc616ba518a9b444114))
+* **cli:** add ✓/⚠ attention glyphs to human renders of status/doctor/review ([6f6cbe8](https://github.com/calvinnwq/artshelf/commit/6f6cbe85d54886cfd137791863e1b3554ca908f0))
+* **cli:** implement artshelf doctor --agent compact decision packet ([d9abd4e](https://github.com/calvinnwq/artshelf/commit/d9abd4e75a7f4b2898eeacc3b3404221f4456bd4))
+* **cli:** implement artshelf review --agent compact decision packet ([6f5476c](https://github.com/calvinnwq/artshelf/commit/6f5476ca987de3190f7a8760c6bb9c1efa8b9fce))
+
+
+### Bug Fixes
+
+* **cli:** preserve ledger scope in agent next actions ([a583683](https://github.com/calvinnwq/artshelf/commit/a583683064cdd16dd929766dc01f23fc31fa50e7))
+
+## [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

@@ -112,6 +112,8 @@ destructive deletion.
 - **Trash before delete** — `cleanup=delete` stays refused; physical deletion
   needs its own reviewed trash purge. No silent deletion, ever.
 - **`--json` on every command**, so agents can act on structured output.
+- **`--agent` on `review`/`status`/`doctor`**, a compact, token-efficient
+  decision packet for agents, while the default render stays human-scannable.
 
 ## Reference
 
@@ -120,8 +122,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 +135,19 @@ 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`; `review`, `status`, and `doctor`
+also take `--agent` for a compact decision packet; `--ledger`, `--registry`, and
+`--all` are scope flags only on commands that list them.
 </details>
 
 <details>
@@ -159,7 +165,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:
@@ -212,7 +242,9 @@ files or writing a plan.
 
 ```bash
 artshelf review --json
+artshelf review --agent
 artshelf review --all --json
+artshelf review --all --agent
 ```
 
 `review` is the compact report surface for scheduled checks. `--all` reads every
@@ -227,6 +259,16 @@ triage count and states the same next safe action (repair broken ledgers, dry-ru
 cleanup, inspect missing paths, or nothing to do). Review never writes a plan, so
 the next action always points at an explicit follow-up command.
 
+`review`, `status`, and `doctor` share three render modes. The default human
+render leads each ledger and summary line with a `✓`/`⚠` attention glyph; `--json`
+stays the full, backward-compatible audit report; and `--agent` emits a compact,
+deterministic single-line JSON decision packet for agents, taking precedence over
+`--json` when both are passed. For `review`, the packet sorts records into
+ready-for-approval, needs-review-first, and blocked groups. Because review is
+read-only and never mints a cleanup plan, the only exact approval target it emits
+is `resolve missing`; cleanup-eligible records stay needs-review-first and point
+at `cleanup --dry-run`, which mints the reviewed plan id to approve.
+
 ### `artshelf doctor`
 
 Reports whether Artshelf is healthy on the current machine without mutating
@@ -235,6 +277,7 @@ anything.
 ```bash
 artshelf doctor
 artshelf doctor --json
+artshelf doctor --agent
 artshelf doctor --ledger <path>
 artshelf doctor --registry <path>
 ```
@@ -254,7 +297,11 @@ A healthy machine exits 0. A broken registry file or any stale or invalid
 registered ledger exits non-zero with actionable errors. Humans should run
 `artshelf doctor` after install or when `--all` commands behave unexpectedly; agents
 may run it on a schedule to catch stale registry entries before relying on
-cleanup planning. Doctor never creates plans, receipts, or records.
+cleanup planning. Doctor never creates plans, receipts, or records. Like `review`
+and `status`, `doctor` accepts `--agent` for a compact single-line JSON decision
+packet (health, registry and registered-ledger health, blockers, cleanup-safety
+posture, next action, and a verify command); `--agent` takes precedence over
+`--json`.
 
 ### `artshelf status`
 
@@ -263,7 +310,9 @@ The lightweight daily "what is going on?" view across ledgers.
 ```bash
 artshelf status
 artshelf status --json
+artshelf status --agent
 artshelf status --all --json
+artshelf status --all --agent
 artshelf status --all --registry <path> --json
 ```
 
@@ -282,7 +331,9 @@ never creates plans or receipts and never mutates records. A healthy machine
 exits 0. In `--all` mode, a broken registry or any stale or invalid registered
 ledger exits non-zero. Due entries are normal operational state and do not change
 the exit code. With single `--ledger`, a not-yet-created ledger reports empty
-counts.
+counts. Like `review` and `doctor`, `status` accepts `--agent` for a compact
+single-line JSON decision packet (health, counts, attention categories, blockers,
+next action, and a verify command); `--agent` takes precedence over `--json`.
 
 ### `artshelf update`
 
@@ -361,8 +412,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:
@@ -743,6 +794,8 @@ human review.
 - Package includes the deterministic `ArtshelfReviewReport` schema, canonical
   example, and portable renderer script for agent-rendered review reports.
 - All core commands support `--json`.
+- `review`, `status`, and `doctor` also support `--agent`, a compact single-line
+  JSON decision packet for agents that takes precedence over `--json`.
 - Tests cover record/list/find/get/status-filter/due/validate/resolve/registry,
   `artshelf doctor`, the `artshelf status` dashboard, `--all` review, stale-registry,
   dry-run, global-dry-run, execute-plan, and trash list/purge behavior.