artshelf 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -51,6 +51,29 @@
   available below the lead.
 - Tightened the portable agent skill description so the completion-gate trigger
   is visible before final responses, status updates, handoffs, and done reports.
+- Added packaged `ArtshelfReviewReport` schema and canonical example files for
+  deterministic agent review reports, plus deterministic footnote guidance for
+  `artshelf put --json` registrations.
+
+## [0.6.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.5.0...artshelf-v0.6.0) (2026-06-07)
+
+
+### Features
+
+* **artshelf:** add public review report assets ([6bc89ae](https://github.com/calvinnwq/artshelf/commit/6bc89ae78150bbb161a387f844f32c7ac23f30da))
+
+
+### Bug Fixes
+
+* **docs:** constrain review approval targets ([eccc16d](https://github.com/calvinnwq/artshelf/commit/eccc16d019f1245a9ab052db51137654a2c3363b))
+
+## [0.5.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.4.1...artshelf-v0.5.0) (2026-06-05)
+
+
+### Features
+
+* default storage to .artshelf paths ([95ef94e](https://github.com/calvinnwq/artshelf/commit/95ef94edef5862c45e5526a27c4adf0bf40306ca))
+* default storage to .artshelf paths ([0da2cda](https://github.com/calvinnwq/artshelf/commit/0da2cda19ff56f78f203840ed71c2379f533750b))
 
 ## [0.4.1](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.4.0...artshelf-v0.4.1) (2026-06-05)
 

package/README.md

@@ -116,8 +116,8 @@ This adds a separate approval boundary between quarantine and destructive deleti
 
 ## Explicit Ledgers
 
-By default, Artshelf writes repo-local `.shelf/ledger.jsonl` inside a git repo and
-`~/.shelf/ledger.jsonl` outside one. Use `--ledger <path>` and an isolated
+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:
 
 ```bash
@@ -126,16 +126,21 @@ artshelf list --ledger /tmp/artshelf-ledger.jsonl
 ```
 
 Artshelf also keeps a small global registry of known ledgers at
-`~/.shelf/ledgers.json`. Override it with `--registry <path>` or
+`~/.artshelf/ledgers.json`. Override it with `--registry <path>` or
 `ARTSHELF_REGISTRY`; renamed installs still honor legacy `SHELF_REGISTRY` when
 `ARTSHELF_REGISTRY` is unset. `put` registers its ledger automatically, and you
 can register an existing ledger explicitly:
 
 ```bash
 artshelf ledgers list
-artshelf ledgers add --ledger /path/to/repo/.shelf/ledger.jsonl --name my-repo
+artshelf ledgers add --ledger /path/to/repo/.artshelf/ledger.jsonl --name my-repo
 ```
 
+Renamed installs before `0.5.0` used `.shelf` storage paths. Migrate by copying
+each ledger directory to `.artshelf`, rewriting registry paths to the copied
+ledgers, validating with `artshelf ledgers list --json`, and keeping the old
+`.shelf` directories until rollback is no longer needed.
+
 `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
@@ -238,15 +243,18 @@ quickstart, agent usage, and CLI reference. The source repo also keeps the
 
 The package includes an agent-facing skill at `skills/artshelf/SKILL.md`. Agents
 that support local skills can copy or reference this file to learn when to call
-`artshelf put`, how to report Artshelf ids in handoffs and issue comments, 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
-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.
-
-The same skill ships in the npm package. From a source checkout, use
+`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.
+
+The same skill ships in the npm package alongside
+`schemas/artshelf-review-report.schema.json` and the canonical
+`examples/artshelf-review-report.json` packet. From a source checkout, use
 `skills/artshelf/SKILL.md` directly. Agents should ask where the user wants
 Artshelf cloned before installing or linking it.
 

package/SPEC.md

@@ -428,8 +428,8 @@ Rules:
 
 V1 supports two scopes:
 
-- repo-local: `.shelf/ledger.jsonl`
-- user-global: `~/.shelf/ledger.jsonl`
+- repo-local: `.artshelf/ledger.jsonl`
+- user-global: `~/.artshelf/ledger.jsonl`
 
 Default behavior:
 
@@ -439,10 +439,14 @@ Default behavior:
 
 V1 also supports a user-level registry of known ledgers:
 
-- registry: `~/.shelf/ledgers.json`
+- registry: `~/.artshelf/ledgers.json`
 - `--registry <path>` overrides the registry path. Without it,
   `ARTSHELF_REGISTRY` is read first, then legacy `SHELF_REGISTRY`, then the
   default registry path.
+- Legacy `.shelf` ledgers are not deleted or moved automatically. Migration is
+  copy-first: copy ledger directories to `.artshelf`, rewrite registry entries,
+  validate the new registry, and retain the old `.shelf` directories for
+  rollback until the new paths are proven quiet.
 - 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.
@@ -462,7 +466,7 @@ V1 also supports a user-level registry of known ledgers:
   "ledgers": [
     {
       "name": "my-repo",
-      "path": "/absolute/path/to/repo/.shelf/ledger.jsonl",
+      "path": "/absolute/path/to/repo/.artshelf/ledger.jsonl",
       "scope": "repo",
       "createdAt": "2026-06-01T05:42:00Z",
       "updatedAt": "2026-06-01T05:42:00Z"
@@ -506,9 +510,9 @@ Handled records may include cleanup outcome fields:
 ```json
 {
   "cleanupPlanId": "plan_20260601_154200_cd34",
-  "receiptPath": "/absolute/path/.shelf/receipts/plan_20260601_154200_cd34.json",
+  "receiptPath": "/absolute/path/.artshelf/receipts/plan_20260601_154200_cd34.json",
   "cleanedAt": "2026-06-01T05:45:00Z",
-  "targetPath": "/absolute/path/.shelf/trash/plan_20260601_154200_cd34/shf_20260601_154200_ab12-artifact",
+  "targetPath": "/absolute/path/.artshelf/trash/plan_20260601_154200_cd34/shf_20260601_154200_ab12-artifact",
   "cleanupReason": "delete is disabled in v1"
 }
 ```
@@ -531,7 +535,7 @@ the purge provenance:
   "resolutionReason": "trash purge completed",
   "purgedAt": "2026-06-01T06:10:00Z",
   "purgePlanId": "purge_20260601_061000_ef56",
-  "purgeReceiptPath": "/absolute/path/.shelf/purge-receipts/purge_20260601_061000_ef56.json"
+  "purgeReceiptPath": "/absolute/path/.artshelf/purge-receipts/purge_20260601_061000_ef56.json"
 }
 ```
 
@@ -593,11 +597,26 @@ Agents may run `artshelf find` and `artshelf get` before `put` to avoid duplicat
 registrations. `find`/`get` are read-only ledger queries; they must not be used
 as permission to clean up or resolve a record.
 
+When `artshelf put --json` succeeds, agents should include a deterministic
+Artshelf footnote in the same handoff, status, final response, or run summary
+that mentions the artifact:
+
+```text
+Artshelf footnote: registered <artifact-path> as <artshelf-id>; reason: <short reason>; due: <YYYY-MM-DD|manual-review>; cleanup=<cleanup-mode>.
+```
+
 Agents may run `artshelf resolve <id> --status resolved --reason <text>` only
 after explicit confirmation that the record has been handled, is missing, or is
 no longer needed. The reason must be specific; resolve does not move or delete
 files.
 
+For batches of missing-path records, agents should ask for exact approval before
+resolving:
+
+```text
+approve artshelf resolve missing ledger <ledger-path> ids <id...>
+```
+
 Scheduled jobs may run:
 
 ```bash
@@ -622,6 +641,15 @@ registered-ledger discovery and should include trashed record counts and target
 ages. Purge dry-runs stay scoped to one explicit ledger and should report any
 plan id, matching entries, and skipped entries.
 
+When a scheduled review or dry-run produces cleanup or trash purge plans,
+deterministic integrations should build an `ArtshelfReviewReport` packet first,
+then render a compact decision report from it. The packet schema is
+`schemas/artshelf-review-report.schema.json`, the canonical example is
+`examples/artshelf-review-report.json`, and packaged docs/skills carry matching
+copies for browsable docs and portable agent installs. The report groups
+decisions into ready-for-approval, needs-review-first, and blocked sections, and
+must still include exact approval targets in the message body.
+
 Scheduled jobs must never run `artshelf cleanup --execute` or
 `artshelf trash purge --execute`; they may only dry-run and report plans for later
 human review.
@@ -662,6 +690,8 @@ human review.
 - CLI can list trashed records (single ledger or `--all`) and purge them through
   an approval-first, ledger-scoped dry-run/execute boundary that writes a purge
   receipt; purge refuses `--all` and never deletes without a reviewed plan id.
+- Package includes the deterministic `ArtshelfReviewReport` schema and canonical
+  example for agent-rendered review reports.
 - All core commands support `--json`.
 - Tests cover record/list/find/get/status-filter/due/validate/resolve/registry,
   `artshelf doctor`, the `artshelf status` dashboard, `--all` review, stale-registry,

package/dist/src/ledger.js

@@ -18,8 +18,8 @@ const RESOLVE_STATUSES = new Set(["resolved"]);
 export function defaultLedgerPath(cwd = process.cwd()) {
     const repoRoot = findGitRoot(cwd);
     if (repoRoot)
-        return join(repoRoot, ".shelf", "ledger.jsonl");
-    return join(homedir(), ".shelf", "ledger.jsonl");
+        return join(repoRoot, ".artshelf", "ledger.jsonl");
+    return join(homedir(), ".artshelf", "ledger.jsonl");
 }
 export function normalizeLedgerPath(path) {
     return resolve(path ?? defaultLedgerPath());

package/dist/src/registry.js

@@ -3,7 +3,7 @@ import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { now, toIso } from "./time.js";
 export function defaultRegistryPath() {
-    return process.env.ARTSHELF_REGISTRY ?? process.env.SHELF_REGISTRY ?? join(homedir(), ".shelf", "ledgers.json");
+    return process.env.ARTSHELF_REGISTRY ?? process.env.SHELF_REGISTRY ?? join(homedir(), ".artshelf", "ledgers.json");
 }
 export function normalizeRegistryPath(path) {
     return resolve(path ?? defaultRegistryPath());
@@ -116,17 +116,17 @@ function normalizeName(name) {
 }
 function inferLedgerName(ledgerPath) {
     const normalized = resolve(ledgerPath);
-    if (normalized === join(homedir(), ".shelf", "ledger.jsonl"))
+    if (normalized === join(homedir(), ".artshelf", "ledger.jsonl"))
         return "global";
-    if (basename(dirname(normalized)) === ".shelf")
+    if (basename(dirname(normalized)) === ".artshelf")
         return basename(dirname(dirname(normalized))) || "repo";
     return basename(dirname(normalized)) || "ledger";
 }
 function inferLedgerScope(ledgerPath) {
     const normalized = resolve(ledgerPath);
-    if (normalized.startsWith(join(homedir(), ".shelf")))
+    if (normalized.startsWith(join(homedir(), ".artshelf")))
         return "user";
-    if (basename(dirname(normalized)) === ".shelf")
+    if (basename(dirname(normalized)) === ".artshelf")
         return "repo";
     return "other";
 }

package/docs/agent-usage.html

@@ -143,16 +143,22 @@ artshelf get &lt;id&gt; --json</code></pre>
             <section>
               <h2>Ledger Registry</h2>
               <p>
-                Artshelf keeps a user-level registry at `~/.shelf/ledgers.json` so one CLI can
+                Artshelf keeps a user-level registry at `~/.artshelf/ledgers.json` so one CLI can
                 review all known ledgers without moving project records into one global file.
                 <code>put</code> registers the ledger it writes to.
               </p>
-              <pre><code>artshelf ledgers add --ledger &lt;repo&gt;/.shelf/ledger.jsonl --name &lt;project&gt; --scope repo
+              <pre><code>artshelf ledgers add --ledger &lt;repo&gt;/.artshelf/ledger.jsonl --name &lt;project&gt; --scope repo
 artshelf ledgers list --json
 artshelf review --all --json
 artshelf status --all --json
 artshelf find --all --owner &lt;agent-or-runtime&gt; --json
 artshelf trash list --all --json</code></pre>
+              <p>
+                Renamed installs before <code>0.5.0</code> used <code>.shelf</code> paths. For migration,
+                copy the old ledger directories into <code>.artshelf</code>, rewrite registry entries,
+                validate the new registry, and keep the <code>.shelf</code> copies until rollback is no
+                longer needed.
+              </p>
               <p>
                 <code>artshelf ledgers list --json</code> validates each registered ledger and reports
                 ok/missing/invalid status with entry and warning/error counts, so agents can detect
@@ -187,8 +193,79 @@ artshelf trash list --all --json</code></pre>
               <pre><code>artshelf trash list --ledger &lt;ledger-path&gt;
 artshelf trash purge --older-than 7d --dry-run --ledger &lt;ledger-path&gt; --json
 artshelf trash purge --execute --plan-id &lt;purge-plan-id&gt; --ledger &lt;ledger-path&gt; --json</code></pre>
+              <h3>Review Plan Report Schema</h3>
+              <p>
+                When a dry-run creates or reuses a cleanup or trash purge plan, surface the
+                plan in a compact human-readable report. The report should let the user
+                approve, ask for changes, or request alternatives without opening the plan
+                file.
+              </p>
+              <p>
+                For deterministic agent integrations, construct an
+                <code>ArtshelfReviewReport</code> JSON object first, then render it to text.
+                Use <a href="schemas/artshelf-review-report.schema.json">schemas/artshelf-review-report.schema.json</a>
+                for the packet shape and
+                <a href="examples/artshelf-review-report.json">examples/artshelf-review-report.json</a>
+                as the canonical example. The schema locks report structure; the CLI output
+                and approval rules still define cleanup safety.
+              </p>
+              <p>
+                Render the JSON packet as a compact decision card using
+                <code>decisionSummary</code> and <code>decisionGroups</code>. Lead with
+                counts, then show exactly what is ready for approval and what needs review
+                first. Emojis are encouraged when the host renders them well because they
+                make review groups scannable; omit them only for plain-text or
+                accessibility-constrained surfaces.
+              </p>
+              <pre><code>Artshelf daily review
+Status: &lt;ok|attention needed&gt;; registry &lt;ok|attention&gt;
+
+✅ Ready for approval: &lt;n&gt;
+👀 Needs review first: &lt;n&gt;
+⚠️ Blocked: &lt;n&gt;
+
+Recommendation
+&lt;one short sentence with the next safest action&gt;.
+
+Ready for approval
+1. &lt;short item label&gt;
+   Why: &lt;short reason&gt;
+   Action: &lt;what approval will do&gt;
+   approve artshelf cleanup ledger &lt;ledger-path&gt; plan &lt;plan-id&gt;
+
+2. &lt;short item label&gt;
+   Why: &lt;short reason&gt;
+   Action: &lt;ledger-only update, no file changes&gt;
+   approve artshelf resolve missing ledger &lt;ledger-path&gt; ids &lt;id...&gt;
+
+Needs review first
+1. &lt;short item label&gt;
+   Why: &lt;short reason&gt;
+   Suggested next step: inspect path, then choose keep, change retention, resolve, or clean up later
+   Path: &lt;path&gt;
+
+Blocked
+&lt;none, or the registry/refused/missing-path blocker and next repair step&gt;
+
+Safety
+Dry-run only. No execute, resolve, or delete ran.</code></pre>
+              <p>
+                Keep the full <code>ArtshelfReviewReport</code> JSON as the audit packet
+                and include it as an attachment, linked file, or expandable detail when the
+                host supports that. Do not paste the whole packet into chat unless the user
+                asks for it. For long plans, show only the first 3 to 5 decisions under
+                each visible group, then state the hidden count by group and classification.
+                Do not hide refused, registry-problem, or missing-path items.
+              </p>
+              <p>
+                If the host supports buttons, menus, or other interactive controls, they
+                should emit exact text commands such as the approval targets below. Always
+                include the exact approval target in the message body as a fallback for
+                clients where those controls do not render.
+              </p>
               <pre><code>approve artshelf cleanup ledger &lt;ledger-path&gt; plan &lt;plan-id&gt;
-approve artshelf trash purge ledger &lt;ledger-path&gt; plan &lt;purge-plan-id&gt;</code></pre>
+approve artshelf trash purge ledger &lt;ledger-path&gt; plan &lt;purge-plan-id&gt;
+approve artshelf resolve missing ledger &lt;ledger-path&gt; ids &lt;id...&gt;</code></pre>
               <div class="note">
                 Never execute from a read-only preview id. Never generate a fresh plan and execute
                 it in the same step. <code>trash</code> moves artifacts into Artshelf trash; physical
@@ -210,6 +287,12 @@ approve artshelf trash purge ledger &lt;ledger-path&gt; plan &lt;purge-plan-id&g
                 skipped instead of registered, include the brief skip reason from the
                 completion checklist.
               </p>
+              <p>
+                When <code>artshelf put --json</code> succeeds, include a deterministic Artshelf
+                footnote in the same handoff, status, final response, or run summary that
+                mentions the artifact.
+              </p>
+              <pre><code>Artshelf footnote: registered &lt;artifact-path&gt; as &lt;artshelf-id&gt;; reason: &lt;short reason&gt;; due: &lt;YYYY-MM-DD|manual-review&gt;; cleanup=&lt;cleanup-mode&gt;.</code></pre>
             </section>
 
             <section>
@@ -244,8 +327,14 @@ artshelf trash purge --execute --plan-id &lt;purge-plan-id&gt; --ledger &lt;ledg
               <pre><code>artshelf resolve &lt;id&gt; --status resolved --reason &lt;text&gt;</code></pre>
               <p>
                 Use a specific reason. <code>resolve</code> only updates the ledger; it does not
-                move or delete files. Resolved records stop reappearing in future due and
-                dry-run cleanup output while remaining visible through
+                move or delete files. For batches of missing-path records, ask for approval that
+                names the exact ledger and ids.
+              </p>
+              <pre><code>approve artshelf resolve missing ledger &lt;ledger-path&gt; ids &lt;id...&gt;</code></pre>
+              <p>
+                After resolution, verify with <code>artshelf review --all --json</code> and report
+                whether the review is quiet or what remains. Resolved records stop reappearing
+                in future due and dry-run cleanup output while remaining visible through
                 <code>artshelf list --status resolved</code>.
               </p>
             </section>

package/docs/agent-usage.md

@@ -92,6 +92,13 @@ Useful defaults for agents:
   repo, PR, issue, workflow id, or run id.
 
 Use `--json` when another tool needs to capture the Artshelf entry id.
+When `artshelf put --json` succeeds, include a deterministic Artshelf footnote in
+the same handoff, status, final response, or run summary that mentions the
+artifact:
+
+```text
+Artshelf footnote: registered <artifact-path> as <artshelf-id>; reason: <short reason>; due: <YYYY-MM-DD|manual-review>; cleanup=<cleanup-mode>.
+```
 
 ## Idempotent Lookup
 
@@ -110,16 +117,20 @@ returns no entries, call `put` and record the new id.
 
 ## Ledger Registry
 
-Artshelf keeps a user-level registry at `~/.shelf/ledgers.json` so one CLI can
+Artshelf keeps a user-level registry at `~/.artshelf/ledgers.json` so one CLI can
 review all known ledgers without moving project records into one global file.
 `put` registers the ledger it writes to. Register existing ledgers explicitly
 when adopting Artshelf for an existing project:
 
 ```bash
-artshelf ledgers add --ledger <repo>/.shelf/ledger.jsonl --name <project> --scope repo
+artshelf ledgers add --ledger <repo>/.artshelf/ledger.jsonl --name <project> --scope repo
 artshelf ledgers list --json
 ```
 
+Renamed installs before `0.5.0` used `.shelf` paths. For migration, copy the old
+ledger directories into `.artshelf`, rewrite registry entries, validate the new
+registry, and keep the `.shelf` copies until rollback is no longer needed.
+
 `artshelf ledgers list --json` validates each registered ledger and reports
 ok/missing/invalid status with entry and warning/error counts, so agents can
 detect stale registry entries without a separate validate pass. Add `--plain`
@@ -190,11 +201,79 @@ artshelf trash purge --execute --plan-id <purge-plan-id> --ledger <ledger-path>
    `artshelf review --all --json`, plus `artshelf trash list --ledger <ledger-path> --json`
    and purge receipt evidence after purge, or explain what remains.
 
+### Review Plan Report Schema
+
+When a dry-run creates or reuses a cleanup or trash purge plan, surface the plan
+in a compact human-readable report. The report should let the user approve, ask
+for changes, or request alternatives without opening the plan file.
+
+For deterministic agent integrations, construct an `ArtshelfReviewReport` JSON
+object first, then render it to text. Use
+[`schemas/artshelf-review-report.schema.json`](schemas/artshelf-review-report.schema.json)
+for the packet shape and
+[`examples/artshelf-review-report.json`](examples/artshelf-review-report.json)
+as the canonical example. The schema locks report structure; the CLI output and
+approval rules still define cleanup safety.
+
+Render the JSON packet as a compact decision card using `decisionSummary` and
+`decisionGroups`. Lead with counts, then show exactly what is ready for approval
+and what needs review first. Emojis are encouraged when the host renders them
+well because they make the groups scannable; omit them only for plain-text or
+accessibility-constrained surfaces.
+
+```text
+Artshelf daily review
+Status: <ok|attention needed>; registry <ok|attention>
+
+✅ Ready for approval: <n>
+👀 Needs review first: <n>
+⚠️ Blocked: <n>
+
+Recommendation
+<one short sentence with the next safest action>.
+
+Ready for approval
+1. <short item label>
+   Why: <short reason>
+   Action: <what approval will do>
+   approve artshelf cleanup ledger <ledger-path> plan <plan-id>
+
+2. <short item label>
+   Why: <short reason>
+   Action: <ledger-only update, no file changes>
+   approve artshelf resolve missing ledger <ledger-path> ids <id...>
+
+Needs review first
+1. <short item label>
+   Why: <short reason>
+   Suggested next step: inspect path, then choose keep, change retention, resolve, or clean up later
+   Path: <path>
+
+Blocked
+<none, or the registry/refused/missing-path blocker and next repair step>
+
+Safety
+Dry-run only. No execute, resolve, or delete ran.
+```
+
+Keep the full `ArtshelfReviewReport` JSON as the audit packet and include it as
+an attachment, linked file, or expandable detail when the host supports that.
+Do not paste the whole packet into chat unless the user asks for it. For long
+plans, show only the first 3 to 5 decisions under each visible group, then state
+the hidden count by group and classification. Do not hide refused,
+registry-problem, or missing-path items.
+
+If the host supports buttons, menus, or other interactive controls, they should
+emit exact text commands such as the approval targets below. Always include the
+exact approval target in the message body as a fallback for clients where those
+controls do not render.
+
 Approval wording should be exact:
 
 ```text
 approve artshelf cleanup ledger <ledger-path> plan <plan-id>
 approve artshelf trash purge ledger <ledger-path> plan <purge-plan-id>
+approve artshelf resolve missing ledger <ledger-path> ids <id...>
 ```
 
 Never execute from a read-only preview id. Never generate a fresh plan and
@@ -305,8 +384,17 @@ artshelf resolve <id> --status resolved --reason <text>
 ```
 
 Use a specific reason. `resolve` only updates the ledger; it does not move or
-delete files. Resolved records stop reappearing in future due and dry-run
-cleanup output while remaining visible in `artshelf list --status resolved`.
+delete files. For batches of missing-path records, ask for approval that names
+the exact ledger and ids:
+
+```text
+approve artshelf resolve missing ledger <ledger-path> ids <id...>
+```
+
+After resolution, verify with `artshelf review --all --json` and report whether
+the review is quiet or what remains. Resolved records stop reappearing in future
+due and dry-run cleanup output while remaining visible in
+`artshelf list --status resolved`.
 
 ## Scheduled Review
 

package/docs/examples/artshelf-review-report.json

@@ -0,0 +1,116 @@
+{
+  "schemaVersion": 1,
+  "scope": {
+    "registryPath": "~/.artshelf/ledgers.json",
+    "ledgerCount": 3,
+    "health": "attention",
+    "registryHealth": "ok",
+    "affectedLedgers": [
+      {
+        "name": "example-project",
+        "ledgerPath": "/path/to/example-project/.artshelf/ledger.jsonl",
+        "validationStatus": "ok"
+      }
+    ]
+  },
+  "plans": [
+    {
+      "type": "cleanup",
+      "ledgerPath": "/path/to/example-project/.artshelf/ledger.jsonl",
+      "planId": "plan_20260606_120000_ab12",
+      "planPath": "/path/to/example-project/.artshelf/plans/plan_20260606_120000_ab12.json",
+      "approvalTarget": "approve artshelf cleanup ledger /path/to/example-project/.artshelf/ledger.jsonl plan plan_20260606_120000_ab12"
+    }
+  ],
+  "summary": {
+    "executable": 1,
+    "skipped": 2,
+    "refused": 0,
+    "manualReview": 1,
+    "missingPath": 1,
+    "trashed": 0
+  },
+  "decisionSummary": {
+    "readyForApproval": 2,
+    "needsReviewFirst": 1,
+    "blocked": 0
+  },
+  "decisionGroups": {
+    "readyForApproval": [
+      {
+        "label": "Clean up temp debug output",
+        "itemIds": ["shf_20260606_120000_ab12"],
+        "actionType": "cleanup",
+        "approvalTarget": "approve artshelf cleanup ledger /path/to/example-project/.artshelf/ledger.jsonl plan plan_20260606_120000_ab12",
+        "reason": "Disposable temp artifact has a reviewed cleanup plan.",
+        "nextStep": "Approve the exact cleanup plan to move the artifact into Artshelf trash."
+      },
+      {
+        "label": "Resolve missing report record",
+        "itemIds": ["shf_20260606_120500_cd34"],
+        "actionType": "resolve-missing",
+        "approvalTarget": "approve artshelf resolve missing ledger /path/to/example-project/.artshelf/ledger.jsonl ids shf_20260606_120500_cd34",
+        "reason": "The report path is already missing.",
+        "nextStep": "Approve the ledger-only resolve command after confirming the report is no longer needed."
+      }
+    ],
+    "needsReviewFirst": [
+      {
+        "label": "Inspect lifecycle smoke report",
+        "itemIds": ["shf_20260606_121000_ef56"],
+        "actionType": "inspect",
+        "approvalTarget": null,
+        "reason": "cleanup=review means the artifact should be inspected before closing.",
+        "nextStep": "Inspect the path, then choose keep, change retention, resolve, or clean up later."
+      }
+    ],
+    "blocked": []
+  },
+  "recommendation": "Approve the reviewed cleanup plan for the disposable temp directory, then resolve the missing record after confirming it is no longer needed.",
+  "items": [
+    {
+      "id": "shf_20260606_120000_ab12",
+      "path": "/tmp/example-debug-output",
+      "classification": "trash-safe",
+      "proposedAction": "execute reviewed cleanup plan",
+      "dueStatus": "due",
+      "reason": "temporary debug output retained for 3 days",
+      "note": "The path exists, cleanup=trash, and the dry-run plan moves it into Artshelf trash."
+    },
+    {
+      "id": "shf_20260606_120500_cd34",
+      "path": "/tmp/missing-report.json",
+      "classification": "resolve-candidate",
+      "proposedAction": "resolve ledger-only after confirmation",
+      "dueStatus": "missing-path",
+      "reason": "report path is already missing",
+      "note": "Resolution updates only the ledger and does not move or delete files."
+    },
+    {
+      "id": "shf_20260606_121000_ef56",
+      "path": "/tmp/lifecycle-smoke-report.json",
+      "classification": "needs-human-review",
+      "proposedAction": "inspect before choosing cleanup or retention",
+      "dueStatus": "manual-review",
+      "reason": "cleanup=review artifact retained for manual inspection",
+      "note": "No approval target is shown until the review decision is known."
+    }
+  ],
+  "alternatives": [
+    "keep the artifact and change retention",
+    "inspect the path before approving cleanup",
+    "regenerate the plan after edits",
+    "resolve missing records ledger-only"
+  ],
+  "safety": {
+    "dryRunOnly": true,
+    "executeAllRefused": true,
+    "noExecuteRan": true,
+    "noResolveRan": true,
+    "noDeleteRan": true
+  },
+  "verification": {
+    "command": "artshelf review --all --json",
+    "successCondition": "no due, manual-review, missing-path, executable, or refused entries remain unless explicitly reported"
+  }
+}

package/docs/quickstart.html

@@ -94,7 +94,7 @@ artshelf validate --ledger /tmp/artshelf-ledger.jsonl --json
 artshelf due --ledger /tmp/artshelf-ledger.jsonl --json
 artshelf cleanup --dry-run --ledger /tmp/artshelf-ledger.jsonl --json</code></pre>
               <p>
-                Dry-run writes a plan under the ledger's `.shelf` directory only when
+                Dry-run writes a plan under the ledger's `.artshelf` directory only when
                 cleanup entries exist. If there is nothing to clean up, it reports
                 <code>not-created</code> and writes no plan file. Review any generated
                 plan id before an execute step.
@@ -119,7 +119,7 @@ artshelf cleanup --dry-run --ledger /tmp/artshelf-ledger.jsonl --json</code></pr
               <h2>4. Purge old trashed records explicitly</h2>
               <p>
                 After cleanup execution, trashed files are quarantined under the ledger's
-                <code>.shelf/trash</code> folder. Before physical deletion, run an explicit
+                <code>.artshelf/trash</code> folder. Before physical deletion, run an explicit
                 reviewed trash purge plan:
               </p>
               <pre><code>artshelf trash list --ledger /tmp/artshelf-ledger.jsonl