artshelf 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -54,8 +54,40 @@
 - Added packaged `ArtshelfReviewReport` schema, canonical example files, and a
   portable renderer script for deterministic agent review reports, plus
   deterministic footnote guidance for `artshelf put --json` registrations.
-- Split the agent docs into Create, Monitor, Review, and Clean workflow pages
-  backed by shared docs-site chrome, search, and navigation.
+- Split the agent docs into Create, Monitor, Review, Clean, and Purge workflow
+  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)
+
+
+### Features
+
+* **cli:** add update command ([#35](https://github.com/calvinnwq/artshelf/issues/35)) ([c55f689](https://github.com/calvinnwq/artshelf/commit/c55f689d1a58a10430d1ea00a1dea5de408e5ac2))
 
 ## [0.7.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.6.0...artshelf-v0.7.0) (2026-06-10)
 

package/README.md

@@ -1,51 +1,49 @@
-# Artshelf
+<div align="center">
 
-Artshelf is a tiny CLI for putting temporary artifacts, backups, and run outputs
-somewhere accountable, with an expiry tag and a cleanup plan.
+# 🗃️ Artshelf
 
-It is built for agents first. Coding agents, workflow runners, and review bots
-create files in `tmp/`, repo folders, or backup locations and then lose context.
-Artshelf gives them a small, auditable contract: record why an artifact exists
-when it is created, monitor the ledgers later, present a review packet, and clean
-only from explicit approvals.
+**Accountable retention for the temporary files agents leave behind.**
 
-Artshelf centers on four approval-first workflows: **register a temp artifact** the
-moment it is created, **review everything safely** before anything moves,
-**approve cleanup safely** from a reviewed plan, and **purge old trash
-explicitly** from a separate reviewed plan. The reference sections further down
-stay out of the way until you need them.
+[![npm version](https://img.shields.io/npm/v/artshelf.svg)](https://www.npmjs.com/package/artshelf) [![npm downloads](https://img.shields.io/npm/dm/artshelf.svg)](https://www.npmjs.com/package/artshelf) [![CI](https://github.com/calvinnwq/artshelf/actions/workflows/ci.yml/badge.svg)](https://github.com/calvinnwq/artshelf/actions/workflows/ci.yml) [![docs](https://img.shields.io/badge/docs-site-blue.svg)](https://calvinnwq.github.io/artshelf/) [![license](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) [![X @calvinnwq](https://img.shields.io/badge/X-%40calvinnwq-black?logo=x)](https://x.com/calvinnwq)
 
-## Status
+[**Docs**](https://calvinnwq.github.io/artshelf/) · [Quickstart](#quickstart) · [Spec](SPEC.md) · [Agent setup](INSTALL.md)
 
-Artshelf is an early v1 MVP. The CLI is distributed under the unscoped
-`artshelf` package name. The existing local/source install path remains supported
-as a fallback.
+</div>
 
-## Install
+Agents make a mess. Coding agents, workflow runners, and review bots scatter
+debug dumps, backups, and run outputs across `tmp/` and your repo — then forget
+them. The clutter piles up, and nobody remembers what's safe to delete.
 
-The intended install path is agent-led: ask your agent to install Artshelf,
-verify it, install or reference the portable skill, and offer to schedule a
-read-only review job in the host runtime. Humans can still run the commands
-below directly.
+Artshelf makes that mess accountable. Every artifact is logged with a reason, an
+expiry, and a cleanup plan the moment it's created. Later you review the ledger,
+preview a cleanup, and execute only an approved plan — approval-first, trash
+before delete, `--json` everywhere. No daemon, no surprise deletions, no guessing
+from a filesystem scan.
 
-Install the npm package:
+> **Status:** early v1 MVP, published to npm as the unscoped `artshelf` package.
 
-```bash
-npm install -g artshelf
-artshelf --version
-artshelf doctor
-```
+## Quickstart
 
-With pnpm:
+Install globally — all methods end with the same `artshelf` command (requires
+Node.js 22+):
 
 ```bash
+# npm
+npm install -g artshelf
+
+# pnpm
 pnpm add -g artshelf
+
+# verify
 artshelf --version
 artshelf doctor
+
+# later, for npm installs
+artshelf update
 ```
 
-Source install remains the fallback path: clone the repo, build it, and link the
-CLI with `npm link`.
+<details>
+<summary>Install from source</summary>
 
 ```bash
 git clone https://github.com/calvinnwq/artshelf.git
@@ -58,269 +56,173 @@ artshelf --version
 artshelf doctor
 ```
 
-To remove the linked command later:
-
-```bash
-npm uninstall -g artshelf
-npm unlink -g artshelf
-```
-
-For agent setup, the agent should prompt before optional integration steps:
-
-- install CLI from npm, or use a source checkout
-- install/copy/reference the whole `skills/artshelf` directory
-- register existing project ledgers
-- schedule a read-only review job in the host runtime
-- choose where review packets should be delivered
-
-Agents should drive the selected setup steps explicitly and verify with
-`artshelf doctor`.
-
-## Core Workflows
-
-Artshelf is built around four approval-first workflows. Start here; the reference
-sections below are there when you need them, not before.
-
-### 1. Register a temp artifact
-
-Record an artifact the moment it is created, while the reason is still fresh:
-
-```bash
-artshelf put tmp/run-output --reason "debug parser output" --ttl 3d --kind scratch --cleanup trash
-```
-
-Artshelf returns an id. Capture it anywhere restart or cleanup context matters.
-
-### 2. Review everything safely
-
-Inspect the ledger and preview cleanup without moving anything:
-
-```bash
-artshelf list
-artshelf status
-artshelf due
-artshelf cleanup --dry-run
-```
-
-Because this example keeps the artifact for three days, an immediate dry-run
-reports `not-created` and writes no plan. A dry-run returns a real plan id only
-after `due` shows cleanup entries.
-
-### 3. Approve cleanup safely
-
-Execute only from a reviewed plan id, and only after a human approves it:
-
-```bash
-artshelf cleanup --execute --plan-id plan_20260601_120000_ab12
-```
-
-There is no auto-execute, no global execute, and no fresh-plan-then-execute
-shortcut. Execution writes a receipt and updates the touched ledger records.
-
-### 4. Purge old trash explicitly
-
-Cleanup execution with `cleanup=trash` moves artifacts into Artshelf's local trash
-folder. Those trashed records remain discoverable (`artshelf trash list`) for review
-and should only be physically removed through a separately reviewed trash purge
-plan:
-
-```bash
-artshelf trash purge --older-than 30d --dry-run --json
-artshelf trash purge --execute --plan-id purge_20260601_120000_ab12
-```
-
-This adds a separate approval boundary between quarantine and destructive deletion.
-
-## Ideal Agent Loop
-
-Agents should use Artshelf as a small lifecycle around their own work:
+`npm link` connects the checkout to your global npm bin, so later rebuilds update
+the command. Remove an npm install with `npm uninstall -g artshelf`; a source
+install with `npm unlink -g artshelf`.
+</details>
 
-1. **Create**: when a durable temp artifact, backup, debug output, report, or
-   quarantine folder is created, run lookup-before-put, then `artshelf put`, and
-   include the Artshelf id in the task summary or handoff.
-2. **Monitor**: run scheduled read-only checks such as `artshelf status --all --json`,
-   `artshelf review --all --json`, and `artshelf trash list --all --json`.
-3. **Review**: turn attention into a compact `ArtshelfReviewReport` decision
-   packet with registry health, affected ledgers, grouped candidates, exact
-   approval targets, and a clear safety line.
-4. **Clean**: after explicit approval for the reviewed ledger and plan id, run
-   cleanup or resolve, then verify the next review is quiet or explain what
-   remains.
+Artshelf checks npm occasionally and prints a non-blocking notice to stderr when
+a newer published version is available. Run `artshelf update` only for npm
+global installs; it upgrades with `npm install -g artshelf@latest`. pnpm global
+installs should update with `pnpm add -g artshelf@latest`, and source installs
+still update by pulling, rebuilding, and linking the checkout. Set
+`ARTSHELF_NO_UPDATE_CHECK=1` for scheduled jobs that must avoid network and
+update-cache writes.
 
-## Explicit Ledgers
+### Recommended agent setup
 
-By default, Artshelf writes repo-local `.artshelf/ledger.jsonl` inside a git repo and
-`~/.artshelf/ledger.jsonl` outside one. Use `--ledger <path>` and an isolated
-`--registry <path>` for tests, demos, and unusual workflows:
+Artshelf is agent-operated, so let your agent finish the job. Paste this one line
+into your coding agent:
 
-```bash
-artshelf put /tmp/parser-output --reason "parser fixture" --ttl 1d --ledger /tmp/artshelf-ledger.jsonl --registry /tmp/artshelf-registry.json --json
-artshelf list --ledger /tmp/artshelf-ledger.jsonl
+```text
+Follow the instructions in https://github.com/calvinnwq/artshelf/blob/main/INSTALL.md to set up Artshelf in this workspace.
 ```
 
-Artshelf also keeps a small global registry of known ledgers at
-`~/.artshelf/ledgers.json`. Override it with `--registry <path>` or
-`ARTSHELF_REGISTRY`. `put` registers its ledger automatically, and you can
-register an existing ledger explicitly:
+It will install the CLI, copy the portable skill (with its bundled review-report
+renderer), register any existing project ledgers, and — only with your approval —
+schedule a **read-only** daily review. Scheduled jobs review and report only;
+cleanup and purge execution always come back to you. See [INSTALL.md](INSTALL.md)
+for the full steps.
 
-```bash
-artshelf ledgers list
-artshelf ledgers add --ledger /path/to/repo/.artshelf/ledger.jsonl --name my-repo
-```
+## How it works
 
-`artshelf ledgers list` validates each registered ledger by default — reporting
-ok/missing/invalid status with entry counts, and exiting non-zero when the
-registry or any ledger is broken — so it doubles as a stale-entry check. Add
-`--plain` for the fast listing that skips validation.
+The whole lifecycle is five steps, and every step that touches files is gated on
+a reviewed plan a human approved:
 
-Use `--all` for one read-only discovery entry point across registered ledgers:
+| Step | What happens | Command |
+|------|--------------|---------|
+| **1. Register** | Record an artifact the moment it is created, while the reason is fresh. Returns an id. | `artshelf put <path> --reason "…" --ttl 3d --kind scratch --cleanup trash` |
+| **2. Monitor** | Read-only checks across all known ledgers — moves nothing. | `artshelf status --all --json` · `artshelf due --all` |
+| **3. Review** | Preview a cleanup plan. A real plan id appears only once entries are due. | `artshelf review --all` · `artshelf cleanup --dry-run` |
+| **4. Clean** | Execute exactly the reviewed plan id, after approval. Trashes, never deletes. | `artshelf cleanup --execute --plan-id <id>` |
+| **5. Purge** | Permanently remove old trashed artifacts via a *separate* reviewed plan. | `artshelf trash purge --older-than 30d --dry-run` → `--execute --plan-id <id>` |
 
-```bash
-artshelf review --all --json
-artshelf status --all --json
-artshelf due --all --json
-artshelf trash list --all --json
-artshelf find --all --owner <agent-or-runtime> --json
-```
+Trash is the holding area between steps 4 and 5: cleanup quarantines artifacts
+into Artshelf's local trash (`artshelf trash list`), and only a separately
+reviewed purge removes them for good — a second approval boundary before
+destructive deletion.
 
-`artshelf review --all` adds an aggregate triage summary (affected ledgers, due,
-manual-review, missing-path, executable, and skipped counts plus preview plan
-ids) and states the next safe action, while staying read-only.
+## Safety model
 
-Use global dry-run cleanup when you want Artshelf to write cleanup plans for
-registered ledgers with cleanup entries, without moving files:
+- **Ledger-first**, not filesystem-scan-first — every artifact is a recorded decision.
+- **Dry-run before mutation**, and execute only from a reviewed plan id.
+- **No daemon, no auto-execute, no global execute** — `--all` is read-only or
+  dry-run reporting; cleanup and purge refuse it.
+- **No fresh-plan-then-execute shortcut** — review the plan, then run that plan.
+- **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.
 
-```bash
-artshelf cleanup --dry-run --all --json
-```
+## Reference
 
-Global execution is intentionally refused. To mutate files, review a dry-run
-plan, then execute it against the specific ledger that produced it.
-Repeated dry-runs with the same executable cleanup entries reuse the existing
-plan id and refresh its timestamp instead of creating duplicate plan files.
-
-## Safety Model
-
-- Ledger-first, not filesystem-scan-first.
-- Dry-run before mutation.
-- Execute only from a reviewed plan id.
-- No daemon or auto-execute path.
-- No global execute; cleanup execute and trash purge refuse `--all`.
-  `--all` is read-only or dry-run reporting only.
-- No fresh-plan-then-execute shortcut.
-- Trash/review by default, not delete.
-- No silent deletion; `cleanup=delete` stays refused, and trash purge needs its own reviewed plan.
-- Agent-friendly JSON output from every command.
-- Small enough to actually use.
-
-V1 only moves `cleanup=trash` entries into Artshelf's local trash folder. Entries
-marked `cleanup=review` become `review-required`, and `cleanup=delete` is
-refused as `cleanup-refused`; physical deletion only happens through a separate
-reviewed `artshelf trash purge --execute` plan.
-
-Dry-run cleanup writes a plan only when there are executable cleanup entries.
-No-op dry-runs report `not-created` and avoid writing plan files. When Artshelf does
-write a plan, it also records that plan in the ledger as an Artshelf-owned artifact.
-
-After `cleanup --execute`, Artshelf writes a receipt, records the receipt as a
-Artshelf-owned artifact, and updates touched ledger records. Handled records stop
-appearing in `due` and later dry-run cleanup plans, while `artshelf list` still
-keeps the audit trail visible.
-
-## Commands
+<details>
+<summary>All commands</summary>
 
 ```bash
 artshelf put <path> --reason "debug parser output" --ttl 3d --kind scratch
-artshelf ledgers list
-artshelf ledgers list --plain
-artshelf ledgers add --ledger <path>
-artshelf list
-artshelf list --all
-artshelf list --status active
+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>
-artshelf get <id>
-artshelf get <id> --all
-artshelf due
-artshelf due --all
-artshelf validate
-artshelf validate --all
-artshelf review
-artshelf review --all
+artshelf get <id> [--all]
+artshelf due [--all]
+artshelf validate [--all]
+artshelf review [--all]
+artshelf status [--all]
 artshelf doctor
-artshelf status
-artshelf status --all
-artshelf cleanup --dry-run
-artshelf cleanup --dry-run --all
-artshelf cleanup --execute --plan-id <id>
+artshelf update [--json]
+artshelf cleanup --dry-run [--all]
+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 command 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>
 
-See the [docs site](https://calvinnwq.github.io/artshelf/) for install,
-quickstart, agent usage, and CLI reference. The source repo also keeps the
-[v1 spec](SPEC.md) and [agent usage guide](docs/agent-usage.md).
+<details>
+<summary>Explicit ledgers and <code>--all</code> discovery</summary>
 
-## Agent Skill
+By default, Artshelf writes repo-local `.artshelf/ledger.jsonl` inside a git repo
+and `~/.artshelf/ledger.jsonl` outside one. Use `--ledger <path>` and an isolated
+`--registry <path>` for tests, demos, and unusual workflows:
 
-The package includes an agent-facing skill at `skills/artshelf`. Agents
-that support local skills can copy or reference this directory to learn when to call
-`artshelf put`, how to report deterministic Artshelf footnotes after JSON
-registration, why `artshelf find` / `artshelf get` are the read-only idempotency
-lookup surface, why `cleanup --execute` requires explicit approval for a
-reviewed plan id, how to render dry-run cleanup and trash purge plans as
-review-report decision packets, how to review trashed records with
-`artshelf trash list` before a separately approved trash purge, and when
-`artshelf resolve <id> --status resolved --reason <text>` may mark confirmed
-handled, missing, or no-longer-needed records without moving or deleting files.
+```bash
+artshelf put /tmp/parser-output --reason "parser fixture" --ttl 1d --ledger /tmp/artshelf-ledger.jsonl --registry /tmp/artshelf-registry.json --json
+artshelf list --ledger /tmp/artshelf-ledger.jsonl
+```
 
-The same skill ships in the npm package alongside
-`scripts/render-review-report.mjs`,
+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> --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.
+
+Use `--all` for one read-only discovery entry point across registered ledgers
+(`review`, `status`, `due`, `trash list`, `find`). `artshelf cleanup --dry-run --all`
+writes plans for ledgers with executable entries without moving files. Global
+execution is intentionally refused: to mutate files, review a dry-run plan, then
+execute it against the specific ledger that produced it.
+</details>
+
+<details>
+<summary>Agent skill</summary>
+
+The package includes an agent-facing skill at `skills/artshelf`. Agents that
+support local skills can copy or reference this directory to learn when to call
+`artshelf put`, how to report deterministic footnotes after JSON registration,
+why `artshelf find` / `artshelf get` are the read-only idempotency lookup surface,
+why `cleanup --execute` requires an approved reviewed plan id, how to render
+dry-run cleanup and trash purge plans as review-report decision packets, and when
+`artshelf resolve <id> --status resolved --reason <text>` may mark a record handled
+without moving or deleting files.
+
+The skill ships in the npm package alongside `scripts/render-review-report.mjs`,
 `schemas/artshelf-review-report.schema.json`, and the canonical
-`examples/artshelf-review-report.json` packet. From a source checkout, use the
-whole `skills/artshelf` directory directly. Agents should ask where the user
-wants Artshelf cloned before installing or linking it.
+`examples/artshelf-review-report.json` packet. Copy the whole `skills/artshelf`
+directory so the renderer, schema, and examples travel together.
+</details>
 
-## Development
+<details>
+<summary>Development</summary>
 
 ```bash
 pnpm install
-pnpm check
-```
-
-Preview the static docs site locally:
-
-```bash
-pnpm docs:serve
+pnpm check          # build + test
+pnpm docs:serve     # preview docs at http://127.0.0.1:8080/
 ```
 
-Then open <http://127.0.0.1:8080/>.
+Release Please owns version bumps, changelog, tags, and releases. When a Release
+Please PR merges, the release workflow validates with `pnpm check` and publishes
+`artshelf` to npm through npm Trusted Publishing — no long-lived npm token in
+GitHub secrets. During tests or one-off runs, pass both `--ledger <path>` and
+`--registry <path>` to keep entries out of default Artshelf storage.
+</details>
 
-Release Please owns version bumps, changelog updates, tags, and GitHub releases.
-When a Release Please PR is merged and a release is created, the release workflow
-validates the package with `pnpm check` and publishes `artshelf` to npm through
-npm Trusted Publishing. The npm package must have this repository's release
-workflow configured as a trusted publisher; no long-lived npm token is expected
-in GitHub secrets.
+## Learn more
 
-During tests or one-off runs, pass both `--ledger <path>` and `--registry <path>`
-to keep entries and registry updates out of default Artshelf storage.
+- **[Docs site](https://calvinnwq.github.io/artshelf/)** — install, quickstart, agent usage, and CLI reference.
+- **[v1 spec](SPEC.md)** — the full behavioral contract.
+- **[Agent usage guide](docs/agent-usage.md)** — deeper agent integration notes.
 
 ## Contributing
 
 Artshelf is small on purpose. Keep new behavior ledger-first, previewable, and
 covered by tests. See [CONTRIBUTING.md](CONTRIBUTING.md).
 
-## Support And Security
+## Support and security
 
 Use [GitHub issues](https://github.com/calvinnwq/artshelf/issues) for bugs and
-feature ideas. See
-[SUPPORT.md](SUPPORT.md) and [SECURITY.md](SECURITY.md).
+feature ideas. See [SUPPORT.md](SUPPORT.md) and [SECURITY.md](SECURITY.md).
 
 ## License
 

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:
@@ -284,6 +314,45 @@ ledger exits non-zero. Due entries are normal operational state and do not chang
 the exit code. With single `--ledger`, a not-yet-created ledger reports empty
 counts.
 
+### `artshelf update`
+
+Checks the latest published npm version and, for npm global installs, updates the
+package with npm.
+
+```bash
+artshelf update
+artshelf update --json
+```
+
+Rules:
+
+- Normal commands may perform a best-effort npm update check after command
+  handling and print a non-blocking notice to stderr when a newer version is
+  available.
+- Read-only command guarantees refer to ledger and artifact mutation; automatic
+  update-check cache writes are separate and can be disabled.
+- Update notices must never pollute JSON stdout.
+- Automatic checks cache successful and failed latest-version lookups at
+  `~/.artshelf/update-check.json` by default, with a 24-hour TTL.
+- `ARTSHELF_NO_UPDATE_CHECK=1` disables automatic checks for scheduled jobs,
+  tests, and no-network environments.
+- `ARTSHELF_UPDATE_CACHE` overrides the update-cache path,
+  `ARTSHELF_UPDATE_CHECK_TTL_MS` overrides the cache TTL, and
+  `ARTSHELF_NPM_REGISTRY_URL` overrides the npm latest-version endpoint.
+- `ARTSHELF_LATEST_VERSION` overrides the discovered latest version for tests.
+- `ARTSHELF_UPDATE_DRY_RUN=1` makes `artshelf update` report the npm command it
+  would run without invoking npm.
+- `artshelf update` forces a fresh latest-version check and does not run the
+  automatic post-command notice check.
+- If the current version is already current, update exits 0 and reports that no
+  update was installed.
+- When an update is available, `artshelf update` runs
+  `npm install -g artshelf@latest`; `--json` captures npm stdout/stderr and
+  returns npm's exit code.
+- `artshelf update` is for npm global installs only. pnpm global installs should
+  use `pnpm add -g artshelf@latest`; source installs should pull, rebuild, and
+  link the checkout again.
+
 ### `artshelf cleanup --dry-run`
 
 Creates a cleanup plan when there are executable cleanup entries, but does not
@@ -322,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:
@@ -450,6 +519,10 @@ V1 also supports a user-level registry of known ledgers:
 - Retention and due calculations use wall-clock time by default. `ARTSHELF_NOW`
   overrides it for tests and controlled runs; legacy `SHELF_NOW` is read only
   when `ARTSHELF_NOW` is unset.
+- Automatic npm update checks cache their latest-version result at
+  `~/.artshelf/update-check.json` by default. `ARTSHELF_NO_UPDATE_CHECK=1`
+  disables automatic checks, `ARTSHELF_UPDATE_CACHE` overrides the cache path,
+  and `ARTSHELF_UPDATE_CHECK_TTL_MS` overrides the cache TTL.
 - `put` registers the ledger it writes to.
 - `ledgers add` registers an existing ledger explicitly.
 - `--all` reads registered ledgers as one review surface.
@@ -632,6 +705,9 @@ artshelf trash list --all --json
 artshelf trash purge --older-than <ttl> --dry-run --ledger <path> --json
 ```
 
+Set `ARTSHELF_NO_UPDATE_CHECK=1` for scheduled jobs that must avoid npm network
+checks and update-cache writes.
+
 `artshelf review --all --json` is the read-only all-ledger triage surface;
 scheduled reports should include its aggregate `summary` and `nextAction` when
 whole-machine review is needed.
@@ -683,6 +759,8 @@ human review.
 - CLI reports a read-only daily dashboard through `artshelf status`, with
   `--all --json` suitable for cron and human output short enough to paste into
   a chat; status never creates plans, receipts, or records.
+- CLI can check for npm package updates, print non-blocking stderr notices, and
+  update npm global installs through `artshelf update`.
 - Cleanup dry-run creates a plan id only when there are executable cleanup
   entries; no-op dry-runs do not write plan files.
 - Cleanup dry-run and execute register the plan/receipt artifacts that Artshelf