Surface attention without touching artifacts.

Signals

• Quiet Registry ok, affected ledgers zero, no old trash. Send nothing unless a summary was requested.
• Attention Due, manual-review, missing-path, or purge candidates exist. Report ledger path and plan id.
• Repair Registry stale, ledger invalid, or path state unsafe. Review missing registrations with registry prune; fix invalid files manually.

Ledger registry

One registry lets an agent review known project ledgers without moving records into a global ledger. Reports should include the ledger path and plan id when attention exists.

# register a project ledger so --all review can see it
artshelf ledgers add --ledger <repo>/.artshelf/ledger.jsonl --name <project> --scope repo --json

# list registered ledgers and their health
artshelf ledgers list --json

# review missing/stale registrations without hand-editing JSON
artshelf ledgers prune --dry-run --registry <registry-path> --agent

# review and due-check every registered ledger at once
artshelf review --all --agent
artshelf due --all --json

# find records this agent owns, across ledgers
artshelf find --all --owner <agent-or-runtime> --json

Scheduled review

• Read-only. Validate, status, due, review, doctor, and trash list are fine.
• Quiet by default. Send nothing when the review is clean unless a summary was requested.
• No network mode. Set ARTSHELF_NO_UPDATE_CHECK=1 when jobs must avoid npm update checks and cache writes.
• Never schedule execution. Scheduled jobs must not run cleanup execute, dispose execute, or trash purge execute.

# ledger health, current ledger or all registered ledgers
artshelf validate --json
artshelf validate --all --json

# what is due, kept, or missing
artshelf due --json
artshelf due --all --json

# the full read-only pass: validate + due + plan preview
artshelf review --all --json
artshelf review --all --agent

# CLI version, paths, registry health, safety posture
artshelf doctor --json
artshelf doctor --agent

# lightweight counts, cron-friendly
artshelf status --all --json
artshelf status --all --agent

If registered ledgers are stale/missing, run ledgers prune --dry-run --registry <registry-path> to review removing missing registrations, then approve the exact registry/prune plan before execute. If valid ledgers report missing-path records, run review --all --json for affected classifications, validate --all --json for provenance signals, then reconcile --dry-run --all --json --registry <registry-path> before any reconcile approve/execute step.

Use --agent for concise monitor decisions and exact next actions. Use --json instead when the job needs full audit/API detail for storage, debugging, or a custom report.

Plan previews

# preview cleanup and register a plan, current ledger or all
artshelf cleanup --dry-run --json
artshelf cleanup --dry-run --all --json

# preview stale registry registration pruning
artshelf ledgers prune --dry-run --registry <registry-path> --json

# what is sitting in trash, and how old it is
artshelf trash list --ledger <ledger-path> --json
artshelf trash list --all --json

# preview an age-based purge for one explicit ledger
artshelf trash purge --older-than 7d --dry-run --ledger <ledger-path> --json

Dry-runs may write reusable plan files when entries exist. No-op dry-runs report not-created. Matching cleanup and registry-prune dry-runs reuse the existing plan id.

Hard boundary

Do not scan arbitrary filesystem locations unless the user opted into that discovery scope.

# mutating commands: approval only, never from a schedule
artshelf cleanup --execute --plan-id <id>
artshelf dispose --execute --plan-id <id>
artshelf ledgers prune --execute --plan-id <id>
artshelf trash purge --execute --plan-id <id>