artshelf 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -51,6 +51,30 @@
   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, 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.
+
+## [0.7.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.6.0...artshelf-v0.7.0) (2026-06-10)
+
+
+### Features
+
+* **docs:** adopt Ledger redesign for docs site ([#32](https://github.com/calvinnwq/artshelf/issues/32)) ([155aaab](https://github.com/calvinnwq/artshelf/commit/155aaab8c44d1e1a2f373cd47e704dde301fc308))
+
+## [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)
 

package/README.md

@@ -3,10 +3,11 @@
 Artshelf is a tiny CLI for putting temporary artifacts, backups, and run outputs
 somewhere accountable, with an expiry tag and a cleanup plan.
 
-It is built for agent-heavy workflows where files and directories are often
-created in `tmp/`, repo folders, or backup locations and then forgotten. Artshelf
-records why an artifact exists at creation time, then makes later cleanup
-visible and reviewable.
+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.
 
 Artshelf centers on four approval-first workflows: **register a temp artifact** the
 moment it is created, **review everything safely** before anything moves,
@@ -22,6 +23,11 @@ as a fallback.
 
 ## Install
 
+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.
+
 Install the npm package:
 
 ```bash
@@ -59,6 +65,17 @@ 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
@@ -72,7 +89,7 @@ Record an artifact the moment it is created, while the reason is still fresh:
 artshelf put tmp/run-output --reason "debug parser output" --ttl 3d --kind scratch --cleanup trash
 ```
 
-Artshelf returns an id. Capture it anywhere future cleanup context matters.
+Artshelf returns an id. Capture it anywhere restart or cleanup context matters.
 
 ### 2. Review everything safely
 
@@ -114,6 +131,22 @@ 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:
+
+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.
+
 ## Explicit Ledgers
 
 By default, Artshelf writes repo-local `.artshelf/ledger.jsonl` inside a git repo and
@@ -127,20 +160,14 @@ artshelf list --ledger /tmp/artshelf-ledger.jsonl
 
 Artshelf also keeps a small global registry of known ledgers at
 `~/.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:
+`ARTSHELF_REGISTRY`. `put` registers its ledger automatically, and you can
+register an existing ledger explicitly:
 
 ```bash
 artshelf ledgers list
 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
@@ -197,7 +224,7 @@ write a plan, it also records that plan in the ledger as an Artshelf-owned artif
 
 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 future dry-run cleanup plans, while `artshelf list` still
+appearing in `due` and later dry-run cleanup plans, while `artshelf list` still
 keeps the audit trail visible.
 
 ## Commands
@@ -241,19 +268,23 @@ quickstart, agent usage, and CLI reference. The source repo also keeps the
 
 ## Agent Skill
 
-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
-`skills/artshelf/SKILL.md` directly. Agents should ask where the user wants
-Artshelf cloned before installing or linking it.
+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.
+
+The same 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.
 
 ## Development
 

package/SPEC.md

@@ -597,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
@@ -626,6 +641,17 @@ 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 the portable skill includes
+`scripts/render-review-report.mjs` for deterministic text rendering. 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.
@@ -666,6 +692,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, canonical
+  example, and portable renderer script 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/docs/agent-clean.html

@@ -0,0 +1,126 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Clean · Agent usage · Artshelf</title>
+    <meta name="description" content="How agents clean Artshelf artifacts after exact human approval.">
+    <script>(function(){var stored=null;try{stored=localStorage.getItem("artshelf-docs-theme");}catch(e){}var dark=false;try{dark=matchMedia("(prefers-color-scheme: dark)").matches;}catch(e){}document.documentElement.dataset.theme=stored||(dark?"dark":"light");})();</script>
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@0,9..144,450..680;1,9..144,450..680&family=Newsreader:ital,opsz,wght@0,6..72,400..650;1,6..72,400..650&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
+    <link rel="stylesheet" href="site.css">
+    <script src="site.js" defer></script>
+  </head>
+  <body data-page="agent-clean.html">
+    <a class="skip" href="#content">Skip to content</a>
+    <header class="masthead">
+      <div class="masthead-inner">
+        <button class="menu-btn" type="button" data-menu aria-label="Toggle navigation" aria-expanded="false"><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M1 3.5h14M1 8h14M1 12.5h14" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg></button>
+        <a class="brand" href="index.html">Artshelf<span class="brand-tag">docs</span></a>
+        <button class="search-btn" type="button" data-search-open><span>Search docs</span><kbd>/</kbd></button>
+        <div class="masthead-tools">
+          <a class="gh" href="https://github.com/calvinnwq/artshelf">GitHub</a>
+          <button class="theme-btn" type="button" data-theme-toggle aria-label="Toggle color theme" aria-pressed="false">
+            <svg class="icon-moon" viewBox="0 0 20 20" aria-hidden="true"><path d="M14.6 12.1A6.5 6.5 0 0 1 7.4 2.7a6.5 6.5 0 1 0 7.2 9.4z" fill="currentColor"/></svg>
+            <svg class="icon-sun" viewBox="0 0 20 20" aria-hidden="true"><circle cx="10" cy="10" r="3.4" fill="currentColor"/><g stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="10" y1="2" x2="10" y2="4"/><line x1="10" y1="16" x2="10" y2="18"/><line x1="2" y1="10" x2="4" y2="10"/><line x1="16" y1="10" x2="18" y2="10"/><line x1="4.2" y1="4.2" x2="5.6" y2="5.6"/><line x1="14.4" y1="14.4" x2="15.8" y2="15.8"/><line x1="4.2" y1="15.8" x2="5.6" y2="14.4"/><line x1="14.4" y1="5.6" x2="15.8" y2="4.2"/></g></svg>
+          </button>
+        </div>
+      </div>
+    </header>
+
+    <div class="frame">
+      <nav id="sidebar" class="sidebar" aria-label="Documentation"></nav>
+
+      <main id="content" class="article-col">
+        <article>
+          <p class="kicker"><span class="n">4.4</span>Agents · Clean</p>
+          <h1>Execute only what was reviewed and approved.</h1>
+          <p class="lede">
+            Clean is meant to be boring. The human approves one plan, the agent runs
+            exactly that plan, writes a receipt, and checks that the next review
+            comes back quiet.
+          </p>
+
+          <section>
+            <h2>Cleanup boundary</h2>
+            <ul class="boundary-list">
+              <li>
+                <span class="stamp readonly">Allowed freely</span>
+                <span><code>validate</code>, <code>review</code>, <code>cleanup --dry-run</code>, <code>trash list</code>, and <code>trash purge --dry-run</code>.</span>
+              </li>
+              <li>
+                <span class="stamp approval">Needs approval</span>
+                <span><code>cleanup --execute --plan-id</code> and <code>trash purge --execute --plan-id</code>, each for one reviewed plan.</span>
+              </li>
+              <li>
+                <span class="stamp refused">Refused</span>
+                <span>No daemon, no auto-execute, no global execute, no fresh-plan-then-execute.</span>
+              </li>
+            </ul>
+            <pre><code><span class="c"># free to run any time: read-only checks and plan previews</span>
+artshelf validate --json
+artshelf review --all --json
+artshelf cleanup --dry-run --json
+artshelf cleanup --dry-run --all --json
+
+<span class="c"># only after a human approves this exact plan id</span>
+artshelf cleanup --execute --plan-id &lt;id&gt;</code></pre>
+            <div class="callout" data-kind="boundary">
+              <span class="callout-label">Hard boundary</span>
+              <p>
+                Cleanup execution needs explicit human approval for the reviewed plan id.
+                <code>cleanup=delete</code> stays refused instead of silently deleting files.
+              </p>
+            </div>
+          </section>
+
+          <section>
+            <h2>Clear the trash</h2>
+            <p>
+              <code>cleanup=trash</code> moves artifacts into Artshelf trash, so Clean is
+              not finished until the trash is cleared. Purging runs the loop one more
+              time: list what is in trash, preview an age-based purge plan, and execute
+              only after a human approves that purge plan id. Physical deletion never
+              piggybacks on the cleanup plan that trashed the file; the purge plan is
+              always separate and separately reviewed.
+            </p>
+            <pre><code><span class="c"># what is in trash for this ledger</span>
+artshelf trash list --ledger &lt;ledger-path&gt; --json
+
+<span class="c"># preview an age-based purge and get a purge plan id</span>
+artshelf trash purge --older-than 7d --dry-run --ledger &lt;ledger-path&gt; --json
+
+<span class="c"># delete for real, only with the reviewed purge plan id</span>
+artshelf trash purge --execute --plan-id &lt;purge-plan-id&gt; --ledger &lt;ledger-path&gt; --json</code></pre>
+          </section>
+
+          <section>
+            <h2>Resolve confirmed records</h2>
+            <p>Resolve only updates the ledger; it does not move or delete files.</p>
+            <pre><code><span class="c"># mark a record handled without touching the file</span>
+artshelf resolve &lt;id&gt; --status resolved --reason &lt;text&gt;</code></pre>
+            <p>The approval wording for resolving a batch of missing records:</p>
+            <pre><code>approve artshelf resolve missing ledger &lt;ledger-path&gt; ids &lt;id...&gt;</code></pre>
+          </section>
+
+          <section>
+            <h2>Verify quiet</h2>
+            <p>After cleanup execute, trash purge, or resolve, verify with <code>artshelf review --all --json</code>.</p>
+            <p>
+              Execution writes a receipt and updates touched ledger records to
+              <code>trashed</code>, <code>review-required</code>, or
+              <code>cleanup-refused</code>. Generated plans and receipts are recorded as
+              <code>owner=artshelf</code> artifacts.
+            </p>
+          </section>
+        </article>
+        <footer class="pager" id="pager"></footer>
+      </main>
+
+      <aside class="toc-col"><p class="toc-title">On this page</p><nav id="toc" aria-label="On this page"></nav></aside>
+    </div>
+
+    <footer class="colophon"><div class="colophon-inner"><span>Artshelf docs</span><span>MIT</span><a href="https://github.com/calvinnwq/artshelf">GitHub</a></div></footer>
+  </body>
+</html>

package/docs/agent-create.html

@@ -0,0 +1,98 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Create · Agent usage · Artshelf</title>
+    <meta name="description" content="How agents create Artshelf records while artifact intent is fresh.">
+    <script>(function(){var stored=null;try{stored=localStorage.getItem("artshelf-docs-theme");}catch(e){}var dark=false;try{dark=matchMedia("(prefers-color-scheme: dark)").matches;}catch(e){}document.documentElement.dataset.theme=stored||(dark?"dark":"light");})();</script>
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@0,9..144,450..680;1,9..144,450..680&family=Newsreader:ital,opsz,wght@0,6..72,400..650;1,6..72,400..650&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
+    <link rel="stylesheet" href="site.css">
+    <script src="site.js" defer></script>
+  </head>
+  <body data-page="agent-create.html">
+    <a class="skip" href="#content">Skip to content</a>
+    <header class="masthead">
+      <div class="masthead-inner">
+        <button class="menu-btn" type="button" data-menu aria-label="Toggle navigation" aria-expanded="false"><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M1 3.5h14M1 8h14M1 12.5h14" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg></button>
+        <a class="brand" href="index.html">Artshelf<span class="brand-tag">docs</span></a>
+        <button class="search-btn" type="button" data-search-open><span>Search docs</span><kbd>/</kbd></button>
+        <div class="masthead-tools">
+          <a class="gh" href="https://github.com/calvinnwq/artshelf">GitHub</a>
+          <button class="theme-btn" type="button" data-theme-toggle aria-label="Toggle color theme" aria-pressed="false">
+            <svg class="icon-moon" viewBox="0 0 20 20" aria-hidden="true"><path d="M14.6 12.1A6.5 6.5 0 0 1 7.4 2.7a6.5 6.5 0 1 0 7.2 9.4z" fill="currentColor"/></svg>
+            <svg class="icon-sun" viewBox="0 0 20 20" aria-hidden="true"><circle cx="10" cy="10" r="3.4" fill="currentColor"/><g stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="10" y1="2" x2="10" y2="4"/><line x1="10" y1="16" x2="10" y2="18"/><line x1="2" y1="10" x2="4" y2="10"/><line x1="16" y1="10" x2="18" y2="10"/><line x1="4.2" y1="4.2" x2="5.6" y2="5.6"/><line x1="14.4" y1="14.4" x2="15.8" y2="15.8"/><line x1="4.2" y1="15.8" x2="5.6" y2="14.4"/><line x1="14.4" y1="5.6" x2="15.8" y2="4.2"/></g></svg>
+          </button>
+        </div>
+      </div>
+    </header>
+
+    <div class="frame">
+      <nav id="sidebar" class="sidebar" aria-label="Documentation"></nav>
+
+      <main id="content" class="article-col">
+        <article>
+          <p class="kicker"><span class="n">4.1</span>Agents · Create</p>
+          <h1>Register artifacts while intent is fresh.</h1>
+          <p class="lede">
+            Create is one question: should this non-source artifact outlive the turn?
+            If yes, put it on the shelf while the reason is still obvious.
+          </p>
+
+          <section>
+            <h2>Completion gate</h2>
+            <p>
+              Before any final, status, handoff, or done report, check for files the agent
+              created, copied, exported, quarantined, backed up, or preserved.
+            </p>
+            <ul>
+              <li><strong>Register eligible artifact paths.</strong> Anything non-source that may outlive the command needs a record.</li>
+              <li><strong>State every skip reason.</strong> Source, cache, regeneratable, secret-bearing, or owned elsewhere.</li>
+            </ul>
+            <div class="callout" data-kind="boundary">
+              <span class="callout-label">Hard boundary</span>
+              <p>Do not call work done while known eligible artifacts are neither registered nor explicitly skipped.</p>
+              <p>Do not invent Artshelf entries after the fact just to make a handoff look tidy.</p>
+            </div>
+          </section>
+
+          <section>
+            <h2>Register these</h2>
+            <dl class="def-rows">
+              <div><dt>backup</dt><dd>rollback copy or snapshot</dd></div>
+              <div><dt>evidence</dt><dd>report, log, smoke output</dd></div>
+              <div><dt>quarantine</dt><dd>copied aside for review</dd></div>
+              <div><dt>run</dt><dd>artifact needed to resume a long task</dd></div>
+            </dl>
+          </section>
+
+          <section>
+            <h2>Lookup before put</h2>
+            <pre><code><span class="c"># is this path already on the shelf?</span>
+artshelf find --path &lt;path&gt; --owner &lt;agent-or-runtime&gt; --label &lt;task-or-run-id&gt; --json
+
+<span class="c"># inspect one record by its Artshelf id</span>
+artshelf get &lt;id&gt; --json</code></pre>
+            <p>
+              If <code>find</code> returns a record, reuse that Artshelf id. If it returns
+              no entries, call <code>artshelf put --json</code> and report the new id.
+            </p>
+          </section>
+
+          <section>
+            <h2>Report the id</h2>
+            <p>Use a deterministic Artshelf footnote wherever restart or cleanup context will be read.</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>
+        </article>
+        <footer class="pager" id="pager"></footer>
+      </main>
+
+      <aside class="toc-col"><p class="toc-title">On this page</p><nav id="toc" aria-label="On this page"></nav></aside>
+    </div>
+
+    <footer class="colophon"><div class="colophon-inner"><span>Artshelf docs</span><span>MIT</span><a href="https://github.com/calvinnwq/artshelf">GitHub</a></div></footer>
+  </body>
+</html>

package/docs/agent-monitor.html

@@ -0,0 +1,150 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Monitor · Agent usage · Artshelf</title>
+    <meta name="description" content="How agents monitor Artshelf ledgers without mutating files.">
+    <script>(function(){var stored=null;try{stored=localStorage.getItem("artshelf-docs-theme");}catch(e){}var dark=false;try{dark=matchMedia("(prefers-color-scheme: dark)").matches;}catch(e){}document.documentElement.dataset.theme=stored||(dark?"dark":"light");})();</script>
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@0,9..144,450..680;1,9..144,450..680&family=Newsreader:ital,opsz,wght@0,6..72,400..650;1,6..72,400..650&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
+    <link rel="stylesheet" href="site.css">
+    <script src="site.js" defer></script>
+  </head>
+  <body data-page="agent-monitor.html">
+    <a class="skip" href="#content">Skip to content</a>
+    <header class="masthead">
+      <div class="masthead-inner">
+        <button class="menu-btn" type="button" data-menu aria-label="Toggle navigation" aria-expanded="false"><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M1 3.5h14M1 8h14M1 12.5h14" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg></button>
+        <a class="brand" href="index.html">Artshelf<span class="brand-tag">docs</span></a>
+        <button class="search-btn" type="button" data-search-open><span>Search docs</span><kbd>/</kbd></button>
+        <div class="masthead-tools">
+          <a class="gh" href="https://github.com/calvinnwq/artshelf">GitHub</a>
+          <button class="theme-btn" type="button" data-theme-toggle aria-label="Toggle color theme" aria-pressed="false">
+            <svg class="icon-moon" viewBox="0 0 20 20" aria-hidden="true"><path d="M14.6 12.1A6.5 6.5 0 0 1 7.4 2.7a6.5 6.5 0 1 0 7.2 9.4z" fill="currentColor"/></svg>
+            <svg class="icon-sun" viewBox="0 0 20 20" aria-hidden="true"><circle cx="10" cy="10" r="3.4" fill="currentColor"/><g stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="10" y1="2" x2="10" y2="4"/><line x1="10" y1="16" x2="10" y2="18"/><line x1="2" y1="10" x2="4" y2="10"/><line x1="16" y1="10" x2="18" y2="10"/><line x1="4.2" y1="4.2" x2="5.6" y2="5.6"/><line x1="14.4" y1="14.4" x2="15.8" y2="15.8"/><line x1="4.2" y1="15.8" x2="5.6" y2="14.4"/><line x1="14.4" y1="5.6" x2="15.8" y2="4.2"/></g></svg>
+          </button>
+        </div>
+      </div>
+    </header>
+
+    <div class="frame">
+      <nav id="sidebar" class="sidebar" aria-label="Documentation"></nav>
+
+      <main id="content" class="article-col">
+        <article>
+          <p class="kicker"><span class="n">4.2</span>Agents · Monitor</p>
+          <h1>Surface attention without touching artifacts.</h1>
+          <p class="lede">
+            Monitor jobs answer one question: does any ledger need attention?
+            They read, summarize, and stop.
+          </p>
+
+          <section>
+            <h2>Signals</h2>
+            <ul class="boundary-list">
+              <li>
+                <span class="stamp readonly">Quiet</span>
+                <span>Registry ok, affected ledgers zero, no old trash. Send nothing unless a summary was requested.</span>
+              </li>
+              <li>
+                <span class="stamp approval">Attention</span>
+                <span>Due, manual-review, missing-path, or purge candidates exist. Report ledger path and plan id.</span>
+              </li>
+              <li>
+                <span class="stamp refused">Repair</span>
+                <span>Registry stale, ledger invalid, or path state unsafe. Fix discovery before anything else.</span>
+              </li>
+            </ul>
+          </section>
+
+          <section>
+            <h2>Ledger registry</h2>
+            <p>
+              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.
+            </p>
+            <pre><code><span class="c"># register a project ledger so --all review can see it</span>
+artshelf ledgers add --ledger &lt;repo&gt;/.artshelf/ledger.jsonl --name &lt;project&gt; --scope repo
+
+<span class="c"># list registered ledgers and their health</span>
+artshelf ledgers list --json
+
+<span class="c"># review and due-check every registered ledger at once</span>
+artshelf review --all --json
+artshelf due --all --json
+
+<span class="c"># find records this agent owns, across ledgers</span>
+artshelf find --all --owner &lt;agent-or-runtime&gt; --json</code></pre>
+            <div class="callout" data-kind="note">
+              <span class="callout-label">Note</span>
+              <p><code>--all</code> is for discovery and review. It is never permission to mutate files.</p>
+            </div>
+          </section>
+
+          <section>
+            <h2>Scheduled review</h2>
+            <ul>
+              <li><strong>Read-only.</strong> Validate, status, due, review, doctor, and trash list are fine.</li>
+              <li><strong>Quiet by default.</strong> Send nothing when the review is clean unless a summary was requested.</li>
+              <li><strong>Never schedule execution.</strong> Scheduled jobs must not run cleanup execute or trash purge execute.</li>
+            </ul>
+            <pre><code><span class="c"># ledger health, current ledger or all registered ledgers</span>
+artshelf validate --json
+artshelf validate --all --json
+
+<span class="c"># what is due, kept, or missing</span>
+artshelf due --json
+artshelf due --all --json
+
+<span class="c"># the full read-only pass: validate + due + plan preview</span>
+artshelf review --all --json
+
+<span class="c"># CLI version, paths, registry health, safety posture</span>
+artshelf doctor --json
+
+<span class="c"># lightweight counts, cron-friendly</span>
+artshelf status --all --json</code></pre>
+          </section>
+
+          <section>
+            <h2>Plan previews</h2>
+            <pre><code><span class="c"># preview cleanup and register a plan, current ledger or all</span>
+artshelf cleanup --dry-run --json
+artshelf cleanup --dry-run --all --json
+
+<span class="c"># what is sitting in trash, and how old it is</span>
+artshelf trash list --ledger &lt;ledger-path&gt; --json
+artshelf trash list --all --json
+
+<span class="c"># preview an age-based purge for one explicit ledger</span>
+artshelf trash purge --older-than 7d --dry-run --ledger &lt;ledger-path&gt; --json</code></pre>
+            <p>
+              Dry-runs may write reusable plan files when entries exist. No-op dry-runs
+              report <code>not-created</code>. Matching cleanup dry-runs reuse the existing plan id.
+            </p>
+          </section>
+
+          <section>
+            <h2>Hard boundary</h2>
+            <p>Do not scan arbitrary filesystem locations unless the user opted into that discovery scope.</p>
+            <div class="callout" data-kind="boundary">
+              <span class="callout-label">Never scheduled</span>
+              <p>These two commands require exact human approval and must never run from a monitor job:</p>
+            </div>
+            <pre><code><span class="c"># mutating commands: approval only, never from a schedule</span>
+artshelf cleanup --execute --plan-id &lt;id&gt;
+artshelf trash purge --execute --plan-id &lt;id&gt;</code></pre>
+          </section>
+        </article>
+        <footer class="pager" id="pager"></footer>
+      </main>
+
+      <aside class="toc-col"><p class="toc-title">On this page</p><nav id="toc" aria-label="On this page"></nav></aside>
+    </div>
+
+    <footer class="colophon"><div class="colophon-inner"><span>Artshelf docs</span><span>MIT</span><a href="https://github.com/calvinnwq/artshelf">GitHub</a></div></footer>
+  </body>
+</html>