04Agents · Overview

Create, monitor, review, clean, purge.

An agent's whole relationship with Artshelf fits in five stages. Each stage has its own page with the exact commands; this page is the contract that ties them together.

One simple loop runs the whole shelf, four moves: Capture automatically (register eligible artifacts at creation with artshelf put, or state the skip reason), Review calmly (read-only and dry-run only; turn the output into a decision packet - nothing moves), Approve exactly (a human approves one exact reviewed ledger or registry plus plan id or record ids), and Verify quiet (re-run a read-only check after every approved mutation). The five stages below are the mechanics behind those moves.

Workflow summary

4.1 Create artshelf put <path> --reason <why> --ttl <ttl>Register a temporary file while you still remember why it exists, or state the reason for skipping it. 4.2 Monitor artshelf review --all --jsonCheck the shelf on a schedule with read-only commands, and stay quiet when everything is clear. 4.3 Review artshelf cleanup --dry-run --jsonUse inspect plus cleanup, registry-prune, reconcile, and dispose dry-runs, then turn the output into an ArtshelfReviewReport decision packet a human can approve. 4.4 Clean artshelf cleanup --execute --plan-id <id>Run cleanup or dispose plans the human approved, resolve confirmed ids, and verify the next review is quiet. 4.5 Purge artshelf trash purge --execute --plan-id <id>Clear old trash through its own separately reviewed purge plan or an exact approved trash-purge bundle. Physical deletion never piggybacks on the cleanup plan that trashed the file.

Clean trashes; Purge deletes. Cleanup quarantines artifacts into Artshelf trash, and only a separately reviewed purge plan or exact approved trash-purge bundle removes them for good - a second approval boundary before destructive deletion.

Operating principles

agents remember: use the portable skill so final, status, and handoff turns check artifacts
crons only read: scheduled jobs may validate, review, dry-run, and report, but never execute; set ARTSHELF_NO_UPDATE_CHECK=1 when they must avoid npm network checks and update-cache writes
humans approve: mutation needs exact approval targets: ledger path, reviewed plan id, or record id list

Render modes

review, status, doctor, ledgers prune --dry-run, dispose --dry-run, and per-record get --inspect share agent-oriented render modes so the same data fits both people and agents. Reach for --agent when an agent decides and acts; reach for --json for full record, plan, or health detail. On get, --agent requires --inspect.

default: human render: scannable grouped counts, attention states, and a short next action for a person at the terminal
--agent: a deterministic, token-efficient decision packet (single-line compact JSON) with health, counts, classifications, blockers, record recommendations, approval targets where applicable, and a verification command
--json: the backward-compatible public audit contract: complete machine-readable JSON for debugging and integrations

UI sessions

artshelf ui starts or resumes a durable browser review session for the agent-mediated loop. artshelf ui dashboard --json returns the read-only multi-ledger review buckets, including needs-context, cleanup, resolve, trash, purge candidates, registry/reconcile problems, and recent receipts. artshelf ui detail <record-id> --ledger <path> --json returns the read-only artifact detail drawer with path label, inspect-card output, provenance, audit trail, existence facts, needs-context badge, and last action. Both views are metadata-only and never preview file contents. artshelf ui serve [--scope user|repo] [--port <port>] [--json] hosts those dashboard and detail views as a local browser page for a human reviewer; it binds to loopback (127.0.0.1) only, recomputes live state per request, requires the active UI session capability token printed in the serve URL, serves no script and no file contents, and supports --json for a compact launch packet. The dashboard stays display-only, while the detail drawer adds scriptless forms that capture lightweight human triage intents - inspect, comment, keep/trash/resolve/defer, and dry-run request - recording each as a pending event in the durable session log for the agent to act on after approval. The served bundle workbench at GET /bundle/<bundle-id> shows the selected exact targets, reviewed-only rows, and exact action from an immutable approval snapshot. With the active token, its scriptless form can submit a revised non-empty subset through POST /approve, creating a new immutable approval snapshot and pending approval event without editing the original bundle or executing a workflow. That submit carries only the source bundle id and selected target ids; the server rehydrates the action, reviewed facts, and exact target rows from the stored source bundle instead of trusting hidden browser target JSON. The session command defaults to user-level multi-ledger review and stores session state under ~/.artshelf/ui; use --scope repo or --ledger <path> when the review needs a narrower target.

The browser records exact-target triage intents, the agent polls with artshelf ui poll <session-id> --json, uses artshelf ui execute for approved bundles or runs existing approval-gated commands only after exact human approval, replies with artshelf ui reply, and closes with artshelf ui end. The browser captures triage intents and approval bundles only and never mutates ledgers, files, trash, or plans directly. artshelf ui bundle <session-id> [<bundle-id>] --json is the agent's read surface over persisted approval bundles: with a bundle id it loads one immutable snapshot plus its resolved deliberate selection so the agent can revalidate live state before execution; with no bundle id it lists the session's approved bundles. It never executes a bundle.

artshelf ui execute <session-id> <bundle-id> --json is the agent's mutating path and the one ui subcommand that changes live state: it loads the immutable reviewed snapshot, re-reads live ledger/registry/trash state, then runs a revalidate -> execute -> verify loop through the existing approval-gated dispose or one-way-door purge paths and replies per-target receipts plus the aggregate result to the session. Execution is exact-target only - a stale, missing, mismatched, or unapproved target is refused or skipped, never force-applied - and the agent verifies live state after each command rather than trusting the command exit. Dispose-backed targets also bind to the reviewed dispose-plan entry contents, so missing or unreadable reviewed plans, subject content drift, or changing a same-id plan artifact after approval makes the bundle stale before any dispose receipt is written instead of changing reason, subject, target, or retention semantics. A purge-backed bundle uses the trash-purge action and routes each target through the one-way-door purge executor, which permanently deletes the trashed artifact with no recovery path - distinct from the reversible dispose path; the dashboard purge lane groups candidates by source with a per-group total and a no-recovery warning, the approval workbench restates that warning for a purge bundle, and the purge approval is bound to the exact live trash facts via a digest so any drift between approval and execution makes the target stale before the irreversible deletion. If an earlier execution claimed the approval event as in_progress and stopped before final receipts, rerunning the same session and bundle resumes that claim; there is no ui execute --all and no browser-direct execution. Each selected target receives one of four visible outcomes - executed, skipped_stale, failed, or needs_manual_review - so a partial run never hides a target's state, and a clean run exits 0 while a partial or refused run exits non-zero with every receipt still recorded.

Treat the session token printed by artshelf ui and artshelf ui serve as a secret same-machine browser capability; ending the session revokes future browser writes and served dashboard/detail/bundle access while keeping the audit trail readable.

The mental model

Green path Artifact is due, the dry-run plan is reviewed, and the approval target is exact.
Review first Artifact needs a human look, a retention change, or a keep/snooze decision.
Blocked Registry is stale, a path is suspicious, or the action would delete without a purge plan. Missing registrations use a reviewed registry-prune plan, not hand-edited JSON.

Portable skill

The repo ships a portable skill at skills/artshelf. Agents that support local skills can copy or reference the whole directory directly, including the bundled report renderer, schema, and example copies.