artshelf 0.7.0 → 0.9.0

package/docs/agent-clean.html

@@ -47,11 +47,11 @@
             <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>
+                <span><code>validate</code>, <code>review</code>, and <code>cleanup --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>
+                <span><code>cleanup --execute --plan-id</code> for one reviewed plan.</span>
               </li>
               <li>
                 <span class="stamp refused">Refused</span>
@@ -70,31 +70,13 @@ artshelf cleanup --execute --plan-id &lt;id&gt;</code></pre>
               <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.
+                <code>cleanup=trash</code> quarantines files into Artshelf trash — recoverable,
+                not deleted — and <code>cleanup=delete</code> stays refused. Emptying the trash
+                for good is a separate stage: see <a href="agent-purge.html">Purge</a>.
               </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>
@@ -106,7 +88,7 @@ artshelf resolve &lt;id&gt; --status resolved --reason &lt;text&gt;</code></pre>
 
           <section>
             <h2>Verify quiet</h2>
-            <p>After cleanup execute, trash purge, or resolve, verify with <code>artshelf review --all --json</code>.</p>
+            <p>After cleanup execute 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

package/docs/agent-monitor.html

@@ -67,7 +67,7 @@
               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
+artshelf ledgers add --ledger &lt;repo&gt;/.artshelf/ledger.jsonl --name &lt;project&gt; --scope repo --json
 
 <span class="c"># list registered ledgers and their health</span>
 artshelf ledgers list --json
@@ -89,6 +89,7 @@ artshelf find --all --owner &lt;agent-or-runtime&gt; --json</code></pre>
             <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>No network mode.</strong> Set <code>ARTSHELF_NO_UPDATE_CHECK=1</code> when jobs must avoid npm update checks and cache writes.</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>

package/docs/agent-purge.html

@@ -0,0 +1,111 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Purge · Agent usage · Artshelf</title>
+    <meta name="description" content="How agents purge Artshelf trash: physical deletion only from a separate, separately reviewed purge plan.">
+    <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-purge.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.5</span>Agents · Purge</p>
+          <h1>Delete for real, from its own reviewed plan.</h1>
+          <p class="lede">
+            Purge is the only stage that physically deletes. Clean trashes; purge
+            empties the trash — and only from a separate plan a human reviewed and
+            approved. Trashed records stay discoverable until you deliberately
+            remove them.
+          </p>
+
+          <section>
+            <h2>Purge boundary</h2>
+            <ul class="boundary-list">
+              <li>
+                <span class="stamp readonly">Allowed freely</span>
+                <span><code>trash list</code> and <code>trash purge --dry-run</code> — discover and preview, moving nothing.</span>
+              </li>
+              <li>
+                <span class="stamp approval">Needs approval</span>
+                <span><code>trash purge --execute --plan-id</code> for one reviewed purge plan, on one ledger.</span>
+              </li>
+              <li>
+                <span class="stamp refused">Refused</span>
+                <span>No global purge — <code>--all</code> is not supported for purge — and no piggybacking on the cleanup plan that trashed the file.</span>
+              </li>
+            </ul>
+            <div class="callout" data-kind="boundary">
+              <span class="callout-label">Hard boundary</span>
+              <p>
+                The purge plan is always separate from the cleanup plan and separately
+                reviewed. Physical deletion never happens as a side effect of cleanup.
+              </p>
+            </div>
+          </section>
+
+          <section>
+            <h2>Preview, then purge</h2>
+            <p>
+              Purge runs the loop one more time: list what is in trash, preview an
+              age-based purge plan to get a purge plan id, then execute only that id
+              after a human approves it.
+            </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>
+            <p>The approval wording for a purge:</p>
+            <pre><code>approve artshelf trash purge ledger &lt;ledger-path&gt; plan &lt;purge-plan-id&gt;</code></pre>
+          </section>
+
+          <section>
+            <h2>Verify quiet</h2>
+            <p>
+              After a purge executes, confirm the trash is empty and the shelf is
+              quiet with <code>artshelf trash list --all --json</code> and
+              <code>artshelf review --all --json</code>.
+            </p>
+            <p>
+              Purge writes a receipt and records it as an <code>owner=artshelf</code>
+              artifact, so the deletion stays auditable even after the files are gone.
+            </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-usage.html

@@ -4,7 +4,7 @@
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <title>Agent usage · Artshelf</title>
-    <meta name="description" content="How agents use Artshelf safely: Create, Monitor, Review, Clean.">
+    <meta name="description" content="How agents use Artshelf safely: Create, Monitor, Review, Clean, Purge.">
     <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>
@@ -35,9 +35,9 @@
       <main id="content" class="article-col">
         <article>
           <p class="kicker"><span class="n">04</span>Agents · Overview</p>
-          <h1>Create, monitor, review, clean.</h1>
+          <h1>Create, monitor, review, clean, purge.</h1>
           <p class="lede">
-            An agent's whole relationship with Artshelf fits in four stages. Each stage
+            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.
           </p>
@@ -63,14 +63,18 @@
               <a class="ledger-row" href="agent-clean.html">
                 <span class="n">4.4</span>
                 <span class="stage">Clean</span>
-                <span class="what"><span class="cmdline">artshelf cleanup --execute --plan-id &lt;id&gt;</span>Run the one plan the human approved, clear old trash with its own reviewed purge plan, resolve confirmed ids, and verify the next review is quiet.</span>
+                <span class="what"><span class="cmdline">artshelf cleanup --execute --plan-id &lt;id&gt;</span>Run the one plan the human approved, resolve confirmed ids, and verify the next review is quiet.</span>
+              </a>
+              <a class="ledger-row" href="agent-purge.html">
+                <span class="n">4.5</span>
+                <span class="stage">Purge</span>
+                <span class="what"><span class="cmdline">artshelf trash purge --execute --plan-id &lt;id&gt;</span>Clear old trash through its own separately reviewed purge plan. Physical deletion never piggybacks on the cleanup plan that trashed the file.</span>
               </a>
             </div>
             <p>
-              Trash rides the same loop. Monitor lists what sits in Artshelf trash,
-              Review previews an age-based purge plan, and Clean executes only the
-              reviewed purge plan id. Clearing trash never piggybacks on the cleanup
-              plan that trashed the file.
+              Clean trashes; Purge deletes. Cleanup quarantines artifacts into Artshelf
+              trash, and only a separate, separately reviewed purge plan removes them for
+              good — a second approval boundary before destructive deletion.
             </p>
           </section>
 
@@ -78,7 +82,7 @@
             <h2>Operating principles</h2>
             <dl class="def-rows">
               <div><dt>agents remember</dt><dd>use the portable skill so final, status, and handoff turns check artifacts</dd></div>
-              <div><dt>crons only read</dt><dd>scheduled jobs may validate, review, dry-run, and report, but never execute</dd></div>
+              <div><dt>crons only read</dt><dd>scheduled jobs may validate, review, dry-run, and report, but never execute; set <code>ARTSHELF_NO_UPDATE_CHECK=1</code> when they must avoid npm network checks and update-cache writes</dd></div>
               <div><dt>humans approve</dt><dd>mutation needs exact approval targets: ledger path, reviewed plan id, or record id list</dd></div>
             </dl>
           </section>

package/docs/agent-usage.md

@@ -11,7 +11,7 @@ mutation.
 
 ## Workflow Summary
 
-Use Artshelf as a four-stage loop around agent work:
+Use Artshelf as a five-stage loop around agent work:
 
 1. **Create**: register durable temp artifacts with lookup-before-put and
    `artshelf put`, or state the skip reason.
@@ -19,10 +19,12 @@ Use Artshelf as a four-stage loop around agent work:
    paths, and trash state.
 3. **Review**: turn raw output into an `ArtshelfReviewReport` decision packet
    with exact approval targets.
-4. **Clean**: execute approved plans, clear trash only from a separate
-   reviewed purge plan, resolve confirmed ids, then verify quiet.
+4. **Clean**: execute approved cleanup plans (which trash, never delete),
+   resolve confirmed ids, then verify quiet.
+5. **Purge**: clear old trash only from a separate, separately reviewed purge
+   plan; physical deletion never piggybacks on the cleanup plan.
 
-This maps to the product loop: **Create -> Monitor -> Review -> Clean**.
+This maps to the product loop: **Create -> Monitor -> Review -> Clean -> Purge**.
 
 ## Child Pages
 
@@ -34,13 +36,16 @@ The browsable docs split the workflow into focused child pages:
   and preview plans.
 - [Review](agent-review.html): decision packet schema, classifications, and
   exact approval wording.
-- [Clean](agent-clean.html): approval-only cleanup, trash purge, resolve,
-  receipts, and verify-quiet checks.
+- [Clean](agent-clean.html): approval-only cleanup, resolve, receipts, and
+  verify-quiet checks.
+- [Purge](agent-purge.html): separately reviewed trash purge that physically
+  deletes, with its own approval target and receipts.
 
 ## Operating Principles
 
 - Agents remember with the portable skill.
-- Scheduled checks read and report only.
+- Scheduled checks read and report only; set `ARTSHELF_NO_UPDATE_CHECK=1` when
+  they must avoid npm network checks and update-cache writes.
 - Review output is a decision packet, not raw counts.
 - Approval names the exact ledger, plan id, or record ids.
 - Every approved action ends with a read-only verification.

package/docs/index.html

@@ -63,7 +63,7 @@ artshelf review --json</code></pre>
           <section>
             <h2>The loop</h2>
             <p>
-              Everything in Artshelf follows four stages: Create, Monitor, Review, Clean.
+              Everything in Artshelf follows five stages: Create, Monitor, Review, Clean, Purge.
               The agent docs use the same names, and each stage links to its page.
             </p>
             <div class="ledger">
@@ -75,7 +75,7 @@ artshelf review --json</code></pre>
               <a class="ledger-row" href="agent-monitor.html">
                 <span class="n">4.2</span>
                 <span class="stage">Monitor</span>
-                <span class="what"><span class="cmdline">artshelf review --all --json</span>Check the shelf on a schedule. Monitor commands only read, so agents and cron jobs can run them safely.</span>
+                <span class="what"><span class="cmdline">artshelf review --all --json</span>Check the shelf on a schedule. Monitor commands do not mutate ledgers or artifacts, so agents and cron jobs can run them safely.</span>
               </a>
               <a class="ledger-row" href="agent-review.html">
                 <span class="n">4.3</span>
@@ -85,7 +85,12 @@ artshelf review --json</code></pre>
               <a class="ledger-row" href="agent-clean.html">
                 <span class="n">4.4</span>
                 <span class="stage">Clean</span>
-                <span class="what"><span class="cmdline">artshelf cleanup --execute --plan-id &lt;id&gt;</span>Run the one plan the human approved, then clear trash with its own reviewed purge plan. Artshelf writes receipts, and a follow-up review confirms the shelf is quiet.</span>
+                <span class="what"><span class="cmdline">artshelf cleanup --execute --plan-id &lt;id&gt;</span>Run the one plan the human approved. Artshelf trashes the file, writes receipts, and a follow-up review confirms the shelf is quiet.</span>
+              </a>
+              <a class="ledger-row" href="agent-purge.html">
+                <span class="n">4.5</span>
+                <span class="stage">Purge</span>
+                <span class="what"><span class="cmdline">artshelf trash purge --execute --plan-id &lt;id&gt;</span>Permanently remove old trashed artifacts through a separate, separately reviewed purge plan. Physical deletion never piggybacks on the cleanup plan.</span>
               </a>
             </div>
           </section>
@@ -153,7 +158,7 @@ artshelf review --json</code></pre>
 ~/.artshelf/ledgers.json
 
 <span class="c"># put registers its ledger automatically; add existing ones explicitly</span>
-artshelf ledgers add --ledger &lt;repo&gt;/.artshelf/ledger.jsonl --name &lt;project&gt; --scope repo
+artshelf ledgers add --ledger &lt;repo&gt;/.artshelf/ledger.jsonl --name &lt;project&gt; --scope repo --json
 
 <span class="c"># --all commands read across every registered ledger</span>
 artshelf review --all --json</code></pre>
@@ -164,7 +169,7 @@ artshelf review --all --json</code></pre>
             <ul>
               <li><a href="install.html">Install</a>: get the CLI from npm and check it with <code>artshelf doctor</code>.</li>
               <li><a href="quickstart.html">Quickstart</a>: walk one real artifact through the whole loop in five minutes.</li>
-              <li><a href="agent-usage.html">Agent usage</a>: the Create, Monitor, Review, Clean contract for coding agents.</li>
+              <li><a href="agent-usage.html">Agent usage</a>: the Create, Monitor, Review, Clean, Purge contract for coding agents.</li>
               <li><a href="reference.html">CLI reference</a>: every command on one page.</li>
             </ul>
           </section>

package/docs/install.html

@@ -69,13 +69,26 @@ npm link
 
 <span class="c"># verify whichever you picked</span>
 artshelf --version
-artshelf doctor</code></pre>
+artshelf doctor
+
+<span class="c"># later, for npm installs only</span>
+artshelf update</code></pre>
             <p>
               <code>npm link</code> connects the local checkout to your global npm bin, so
               later rebuilds update the <code>artshelf</code> command. To remove an npm
               install, run <code>npm uninstall -g artshelf</code>; for a source install,
               run <code>npm unlink -g artshelf</code>.
             </p>
+            <p>
+              Artshelf checks npm occasionally and prints update notices to stderr, so
+              scripted JSON output stays clean. <code>artshelf update</code> is for npm
+              global installs only and runs <code>npm install -g artshelf@latest</code>.
+              pnpm global installs should update with
+              <code>pnpm add -g artshelf@latest</code>; source installs should update
+              by pulling, rebuilding, and linking again. Set
+              <code>ARTSHELF_NO_UPDATE_CHECK=1</code> for scheduled jobs that must
+              avoid network and update-cache writes.
+            </p>
           </section>
 
           <section>
@@ -127,6 +140,18 @@ artshelf --version
 artshelf doctor
 ```
 
+If Artshelf says a newer version is available and you used npm, update the npm
+install and verify again:
+
+```bash
+artshelf update
+artshelf --version
+artshelf doctor
+```
+
+If you used pnpm, update with `pnpm add -g artshelf@latest` instead.
+For source installs, pull, rebuild, and run `npm link` again.
+
 Only use a source install when the user asks for one, and ask the user where
 to clone the repo first instead of assuming a repo path:
 
@@ -176,9 +201,10 @@ artshelf ledgers list --json
 
 Ask the user whether they want a scheduled review job before creating one.
 If they approve, schedule a read-only review job (daily works well) in your
-host runtime that runs:
+host runtime that disables update checks and runs:
 
 ```bash
+ARTSHELF_NO_UPDATE_CHECK=1 \
 artshelf review --all --json
 ```
 

package/docs/reference.html

@@ -40,7 +40,14 @@
             Artshelf v1 keeps the API narrow: put entries in a ledger, query existing
             records, write a cleanup plan, and use separate reviewed plan ids for
             cleanup execution and trash purge. Every command below is tagged read-only,
-            writes ledger, writes registry, or approval-gated.
+            writes ledger, writes registry, npm install, or approval-gated.
+          </p>
+          <p>
+            Run <code>artshelf help</code> for the grouped command list. Use
+            <code>artshelf &lt;command&gt; --help</code> or
+            <code>artshelf help &lt;command&gt;</code> for focused help; nested commands
+            such as <code>artshelf trash purge --help</code> and
+            <code>artshelf ledgers add --help</code> show only that subcommand.
           </p>
 
           <section class="cmd">
@@ -70,7 +77,7 @@ artshelf ledgers list [--plain] [--json]</code></pre>
           <section class="cmd">
             <div class="cmd-head"><h2>artshelf ledgers add</h2><span class="cmd-flag plan">writes registry</span></div>
             <pre><code><span class="c"># register an existing ledger for --all review</span>
-artshelf ledgers add --ledger &lt;path&gt; [--name &lt;project&gt;] [--scope repo|user|other]</code></pre>
+artshelf ledgers add --ledger &lt;path&gt; [--name &lt;project&gt;] [--scope repo|user|other] [--json]</code></pre>
             <p>
               <code>add</code> registers an existing ledger so Artshelf can review it through one
               entry point; scope is inferred from the path when omitted.
@@ -129,13 +136,31 @@ artshelf doctor [--json]</code></pre>
             </p>
           </section>
 
+          <section class="cmd">
+            <div class="cmd-head"><h2>artshelf update</h2><span class="cmd-flag plan">npm install</span></div>
+            <pre><code><span class="c"># install the latest published npm package</span>
+artshelf update [--json]</code></pre>
+            <p>
+              Normal commands may print a non-blocking notice to stderr when npm has a
+              newer published version. <code>artshelf update</code> runs
+              <code>npm install -g artshelf@latest</code> and is for npm global installs
+              only. pnpm global installs should update with
+              <code>pnpm add -g artshelf@latest</code>. Source installs should update by
+              pulling, rebuilding, and linking the checkout. Notices are cached in
+              <code>~/.artshelf/update-check.json</code>; set
+              <code>ARTSHELF_NO_UPDATE_CHECK=1</code> to disable automatic checks for
+              no-network scripts and scheduled jobs. Read-only command labels refer
+              to ledger and artifact mutation, not this optional update-check cache.
+            </p>
+          </section>
+
           <section class="cmd">
             <div class="cmd-head"><h2>artshelf cleanup</h2><span class="cmd-flag approval">approval-gated</span></div>
             <pre><code><span class="c"># preview cleanup and register a reviewed plan</span>
 artshelf cleanup --dry-run [--all] [--json]
 
 <span class="c"># execute exactly one reviewed plan (approval only)</span>
-artshelf cleanup --execute --plan-id &lt;id&gt; [--ledger &lt;path&gt;]</code></pre>
+artshelf cleanup --execute --plan-id &lt;id&gt; [--ledger &lt;path&gt;] [--json]</code></pre>
             <p>
               <code>--dry-run</code> creates and registers a cleanup plan without moving files;
               no-op dry-runs report <code>not-created</code>, and matching dry-runs reuse the
@@ -170,20 +195,59 @@ artshelf trash purge --execute --plan-id &lt;id&gt; [--ledger &lt;path&gt;] [--j
 
           <section class="cmd">
             <div class="cmd-head"><h2>artshelf resolve</h2><span class="cmd-flag plan">writes ledger</span></div>
-            <pre><code>artshelf resolve &lt;id&gt; --status resolved --reason &lt;text&gt;</code></pre>
+            <pre><code>artshelf resolve &lt;id&gt; --status resolved --reason &lt;text&gt; [--json]</code></pre>
             <p>Mark a handled, missing, or no-longer-needed record as manually resolved. Updates the ledger only; never moves or deletes files.</p>
           </section>
 
           <section>
-            <h2>Global options</h2>
+            <h2>Global flags</h2>
+            <p>Only these apply to every command.</p>
+            <table class="opts">
+              <tr><th>option</th><th>meaning</th></tr>
+              <tr><td>-h, --help</td><td>show help for artshelf or a specific command</td></tr>
+              <tr><td>-v, --version</td><td>show the Artshelf version</td></tr>
+            </table>
+          </section>
+
+          <section>
+            <h2>Output mode</h2>
+            <p>
+              <code>--json</code> is the agent contract: it switches commands that return data,
+              records, plans, receipts, or health output to machine-readable JSON on stdout.
+              Update notices and other diagnostics stay on stderr and never corrupt JSON output.
+            </p>
             <table class="opts">
               <tr><th>option</th><th>meaning</th></tr>
-              <tr><td>--ledger &lt;path&gt;</td><td>use an explicit JSONL ledger</td></tr>
-              <tr><td>--registry &lt;path&gt;</td><td>use an explicit ledger registry</td></tr>
-              <tr><td>--all</td><td>read all registered ledgers for supported commands</td></tr>
-              <tr><td>--json</td><td>emit machine-readable JSON</td></tr>
+              <tr><td>--json</td><td>emit machine-readable JSON on commands that return data</td></tr>
+            </table>
+          </section>
+
+          <section>
+            <h2>Scope flags (command-specific)</h2>
+            <p>
+              These select which ledger or registry a command reads or writes. They are not
+              universal global flags; each only applies to the commands that support it.
+            </p>
+            <table class="opts">
+              <tr><th>option</th><th>meaning</th></tr>
+              <tr><td>--ledger &lt;path&gt;</td><td>target an explicit JSONL ledger</td></tr>
+              <tr><td>--registry &lt;path&gt;</td><td>target an explicit ledger registry</td></tr>
+              <tr><td>--all</td><td>read every registered ledger on commands that support discovery (<code>list</code>, <code>find</code>, <code>get</code>, <code>due</code>, <code>validate</code>, <code>review</code>, <code>status</code>, <code>cleanup --dry-run</code>, <code>trash list</code>)</td></tr>
+            </table>
+          </section>
+
+          <section>
+            <h2>Environment</h2>
+            <table class="opts">
+              <tr><th>variable</th><th>meaning</th></tr>
               <tr><td>ARTSHELF_REGISTRY</td><td>override the default ledger registry path</td></tr>
               <tr><td>ARTSHELF_NOW</td><td>override current time for retention and due calculations</td></tr>
+              <tr><td>ARTSHELF_NO_UPDATE_CHECK=1</td><td>disable automatic npm update checks</td></tr>
+              <tr><td>ARTSHELF_UPDATE_CACHE</td><td>override the update-check cache path</td></tr>
+              <tr><td>ARTSHELF_UPDATE_CHECK_TTL_MS</td><td>override the update-check cache TTL</td></tr>
+              <tr><td>ARTSHELF_NPM_REGISTRY_URL</td><td>override the npm latest-version endpoint</td></tr>
+              <tr><td>ARTSHELF_UPDATE_DRY_RUN=1</td><td>print the npm update command without running it</td></tr>
+              <tr><td>ARTSHELF_LATEST_VERSION</td><td>override the latest-version value for tests</td></tr>
             </table>
           </section>
 
@@ -208,7 +272,8 @@ artshelf trash purge --execute --plan-id &lt;id&gt; [--ledger &lt;path&gt;] [--j
               repo it defaults to <code>~/.artshelf/ledger.jsonl</code>. A user-level registry at
               <code>~/.artshelf/ledgers.json</code> is the discovery index for <code>--all</code>
               review, status, cleanup dry-run, and trash-list; project records stay in their own
-              repo-local ledgers.
+              repo-local ledgers. Automatic update checks cache their last npm result at
+              <code>~/.artshelf/update-check.json</code> by default.
             </p>
             <div class="callout" data-kind="boundary">
               <span class="callout-label">Hard boundary</span>

package/docs/site.js

@@ -20,7 +20,8 @@
             { n: "4.1", t: "Create", h: "agent-create.html" },
             { n: "4.2", t: "Monitor", h: "agent-monitor.html" },
             { n: "4.3", t: "Review", h: "agent-review.html" },
-            { n: "4.4", t: "Clean", h: "agent-clean.html" }
+            { n: "4.4", t: "Clean", h: "agent-clean.html" },
+            { n: "4.5", t: "Purge", h: "agent-purge.html" }
           ]
         },
         { t: "Agent skill", h: "https://github.com/calvinnwq/artshelf/tree/main/skills/artshelf", ext: true }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artshelf",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Tiny CLI for accountable temporary artifact retention.",
   "type": "module",
   "author": "Calvin",

package/skills/artshelf/SKILL.md

@@ -34,7 +34,6 @@ Check for the CLI first:
 ```bash
 artshelf --version
 artshelf doctor
-artshelf help put
 ```
 
 If missing, install from npm when appropriate:
@@ -44,6 +43,9 @@ npm install -g artshelf
 artshelf doctor
 ```
 
+Update npm globals with `artshelf update` when a notice appears; use
+`pnpm add -g artshelf@latest` for pnpm or pull/rebuild/`npm link` for source.
+
 For source installs, ask where to clone the repo. Do not hard-code a personal
 repo path or create a custom shim.
 
@@ -58,8 +60,7 @@ artshelf doctor
 ```
 
 Install, copy, or reference this portable skill only after the user chooses the
-integration path. Offer to schedule read-only review job delivery in the host
-runtime.
+integration path. Offer to schedule read-only review job delivery in the host runtime.
 
 ## Create
 
@@ -109,8 +110,8 @@ artshelf ledgers add --ledger <repo>/.artshelf/ledger.jsonl --name <project> --s
 
 ### Scheduled Review
 
-Scheduled jobs are review/report only. Reports should name the ledger path and
-plan id when attention exists. They may run:
+Scheduled jobs are review/report only. Set `ARTSHELF_NO_UPDATE_CHECK=1` for no
+npm network/cache writes. Reports should name the ledger path and plan ids. They may run:
 
 ```bash
 artshelf validate --json
@@ -205,7 +206,7 @@ approve artshelf resolve missing ledger <ledger-path> ids <id...>
 ```
 
 Never execute from a read-only preview id. Never generate a fresh plan and
-execute it in the same step. After any approved action, verify with `artshelf review --all --json` and report whether the review is quiet.
+execute it in the same step. After cleanup or resolve approval, verify with `artshelf review --all --json`; after trash purge approval, also run `artshelf trash list --all --json`.
 
 ## Clean
 
@@ -226,13 +227,8 @@ Cleanup execution requires approval naming the reviewed ledger and plan id:
 artshelf cleanup --execute --plan-id <id> --ledger <ledger-path> --json
 ```
 
-Trash purge is separate from cleanup and needs its own reviewed purge plan:
-
-```bash
-artshelf trash list --ledger <ledger-path> --json
-artshelf trash purge --older-than 7d --dry-run --ledger <ledger-path> --json
-artshelf trash purge --execute --plan-id <purge-plan-id> --ledger <ledger-path> --json
-```
+Cleanup with `cleanup=trash` quarantines files into Artshelf trash. Physical
+deletion belongs to the separate Purge stage.
 
 Resolve only after confirmation; it updates the ledger and does not move or
 delete files:
@@ -247,6 +243,13 @@ For batches, ask for exact approval:
 approve artshelf resolve missing ledger <ledger-path> ids <id...>
 ```
 
+## Purge
+
+Trash purge is separate from cleanup and needs its own reviewed purge plan. List
+trash and dry-run purge freely; execute `artshelf trash purge --execute --plan-id <purge-plan-id> --ledger <ledger-path> --json` only after exact approval:
+`approve artshelf trash purge ledger <ledger-path> plan <purge-plan-id>`. After
+purge execute, verify quiet with `artshelf trash list --all --json` and `artshelf review --all --json`.
+
 ## Safety
 
 - Do not register secrets or credential dumps.