npm - artshelf - Versions diffs - 0.6.0 → 0.8.0 - Mend

artshelf 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/CHANGELOG.md +21 -3
package/README.md +146 -219
package/SPEC.md +56 -6
package/dist/src/cli.js +258 -19
package/docs/agent-clean.html +108 -0
package/docs/agent-create.html +98 -0
package/docs/agent-monitor.html +151 -0
package/docs/agent-purge.html +111 -0
package/docs/agent-review.html +120 -0
package/docs/agent-usage.html +114 -402
package/docs/agent-usage.md +52 -474
package/docs/index.html +165 -152
package/docs/install.html +214 -110
package/docs/quickstart.html +105 -106
package/docs/reference.html +239 -164
package/docs/site.css +675 -490
package/docs/site.js +398 -0
package/package.json +1 -1
package/skills/artshelf/SKILL.md +133 -333
package/skills/artshelf/scripts/render-review-report.mjs +160 -0
package/docs/theme.js +0 -42

package/docs/install.html CHANGED Viewed

@@ -3,131 +3,235 @@
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <title>Install Artshelf</title>
-    <meta name="description" content="Install Artshelf from npm or a local source checkout.">
+    <title>Install · Artshelf</title>
+    <meta name="description" content="Install Artshelf from npm or source, then verify with doctor.">
+    <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="theme.js" defer></script>
+    <script src="site.js" defer></script>
   </head>
-  <body>
-    <div class="docs-shell">
-      <nav class="global-nav" aria-label="Documentation">
-        <a class="site-mark" href="index.html"><strong>Artshelf</strong><span>Artifact retention CLI</span></a>
-        <button class="theme-toggle" type="button" data-theme-toggle aria-label="Toggle color theme" aria-pressed="false">Dark</button>
-        <div class="nav-scroll" aria-label="Documentation sections">
-        <div class="nav-section">
-          <p class="nav-section-title">Start</p>
-          <a href="index.html">Overview</a>
-          <a href="install.html" aria-current="page">Install</a>
-          <a href="quickstart.html">Quickstart</a>
+  <body data-page="install.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 class="nav-section">
-          <p class="nav-section-title">Agents</p>
-          <a href="agent-usage.html">Agent usage</a>
-          <a href="https://github.com/calvinnwq/artshelf/blob/main/skills/artshelf/SKILL.md">Agent skill</a>
-        </div>
-        <div class="nav-section">
-          <p class="nav-section-title">Reference</p>
-          <a href="reference.html">CLI reference</a>
-          <a href="https://github.com/calvinnwq/artshelf">GitHub</a>
-        </div>
-        </div>
-      </nav>
-      <div class="docs-content">
-        <header class="page-top">
-          <div class="wrap">
-            <nav class="breadcrumbs" aria-label="Breadcrumbs"><a href="index.html">Docs</a><span>/</span><span>Install</span></nav>
-            <div class="hero">
-              <div>
-                <p class="eyebrow">Install</p>
-                <h1>Install Artshelf.</h1>
-                <p class="lede">
-                  Artshelf is distributed under the unscoped `artshelf` package name.
-                  Source install remains the fallback path.
-                </p>
-              </div>
-              <div class="terminal">
-                <div class="terminal-head"><span class="dot"></span><span class="dot"></span><span class="dot"></span><span>install</span></div>
-                <pre><code>$ npm install -g artshelf
-$ artshelf --version
-$ artshelf doctor</code></pre>
-              </div>
-            </div>
-          </div>
-        </header>
-        <main class="wrap">
-          <article>
-            <section>
-              <h2>Requirements</h2>
-              <div class="grid">
-                <div class="card"><h3>Node.js 22+</h3><p>The package declares `node &gt;=22` and CI runs on Node 24.</p></div>
-                <div class="card"><h3>npm or pnpm</h3><p>Install the global package with your preferred Node package manager.</p></div>
-                <div class="card"><h3>Source tooling</h3><p>Corepack and Git are only needed when cloning, building, and linking from source.</p></div>
-              </div>
-            </section>
-            <section>
-              <h2>Install From npm</h2>
-              <pre><code>npm install -g artshelf
-artshelf --version
-artshelf doctor</code></pre>
-              <pre><code>pnpm add -g artshelf
-artshelf --version
-artshelf doctor</code></pre>
-              <pre><code>npm uninstall -g artshelf</code></pre>
-            </section>
+      </div>
+    </header>
-            <section>
-              <h2>Install From Source</h2>
-              <pre><code>git clone https://github.com/calvinnwq/artshelf.git
+    <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">02</span>Start · Install</p>
+          <h1>Install the CLI, then run doctor.</h1>
+          <p class="lede">
+            Install globally from npm, verify the command works, then hand the setup
+            prompt to your coding agent.
+          </p>
+          <section>
+            <h2>Requirements</h2>
+            <dl class="def-rows">
+              <div><dt>Node.js 22+</dt><dd>the package declares <code>node &gt;=22</code>; CI runs on Node 24</dd></div>
+              <div><dt>npm or pnpm</dt><dd>any Node package manager can install the global package</dd></div>
+              <div><dt>Git + Corepack</dt><dd>only needed for the source install below</dd></div>
+            </dl>
+          </section>
+          <section>
+            <h2>Installation</h2>
+            <p>Pick one method. All three end with the same global <code>artshelf</code> command.</p>
+            <pre><code><span class="c"># npm</span>
+npm install -g artshelf
+<span class="c"># pnpm</span>
+pnpm add -g artshelf
+<span class="c"># from source (needs git + corepack)</span>
+git clone https://github.com/calvinnwq/artshelf.git
 cd artshelf
 corepack enable
 pnpm install --frozen-lockfile
 pnpm run build
 npm link
+<span class="c"># verify whichever you picked</span>
 artshelf --version
-artshelf doctor</code></pre>
-              <p>
-                `npm link` connects the local checkout to your global npm bin, so future rebuilds update the `artshelf`
-                command.
-              </p>
-              <pre><code>npm unlink -g artshelf</code></pre>
-            </section>
-            <section>
-              <h2>Update A Source Install</h2>
-              <pre><code>cd artshelf
+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>
+            <h2>Updating a source install</h2>
+            <pre><code><span class="c"># pull the latest changes and rebuild</span>
+cd artshelf
 git pull
 pnpm install --frozen-lockfile
 pnpm run build
+npm link</code></pre>
+          </section>
+          <section>
+            <h2>Recommended agent setup</h2>
+            <p>
+              Artshelf is agent-operated, so let your agent finish the job. The repo
+              ships <a href="https://github.com/calvinnwq/artshelf/blob/main/INSTALL.md">INSTALL.md</a>
+              with the full agent setup steps: install the portable skill together
+              with its bundled report renderer script, register existing ledgers, and
+              ask you first before creating any scheduled review job. Scheduled jobs
+              stay read-only; cleanup and purge execution always come back to you.
+            </p>
+            <p>Copy this one line into your coding agent:</p>
+            <pre><code>Follow the instructions in https://github.com/calvinnwq/artshelf/blob/main/INSTALL.md to set up Artshelf in this workspace.</code></pre>
+            <p>What the agent will follow, in full:</p>
+            <pre><code># Artshelf agent setup
+These instructions are written for a coding agent. If you are a human, paste
+this one line into your agent and let it do the rest:
+&gt; Follow the instructions in
+&gt; https://github.com/calvinnwq/artshelf/blob/main/INSTALL.md
+&gt; to set up Artshelf in this workspace.
+## 1. Install the CLI
+Check whether it is already installed before changing anything:
+```bash
+artshelf --version
+artshelf doctor
+```
+If the command is missing, install it from npm and verify again:
+```bash
+npm install -g artshelf      # or: pnpm add -g artshelf
+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:
+```bash
+git clone https://github.com/calvinnwq/artshelf.git "$ARTSHELF_REPO"
+cd "$ARTSHELF_REPO"
+corepack enable
+pnpm install --frozen-lockfile
+pnpm run build
 npm link
 artshelf --version
-artshelf doctor</code></pre>
-            </section>
-            <section>
-              <h2>Agent Setup</h2>
-              <p>
-                Agents should prefer the npm install when available. If using a source install,
-                ask the user where to clone it before linking the command.
-              </p>
-              <pre><code>docs/agent-usage.md</code></pre>
-              <div class="note">Verify `artshelf --version` and `artshelf doctor` after either install method.</div>
-            </section>
-            <section>
-              <h2>Preview Docs Locally</h2>
-              <pre><code>pnpm docs:serve</code></pre>
-              <p>
-                This serves the static docs directory at
-                <a href="http://127.0.0.1:8080/">127.0.0.1:8080</a>.
-              </p>
-            </section>
-          </article>
-        </main>
-        <footer class="site-footer"><div class="wrap">Artshelf docs · <a href="quickstart.html">Next: quickstart</a></div></footer>
-      </div>
+artshelf doctor
+```
+## 2. Install the portable skill, including its script
+Install, copy, or reference the portable skill so you register temporary
+artifacts when you create them and check the shelf before handoffs. Copy the
+whole `skills/artshelf` directory, not just SKILL.md: the skill ships with
+`scripts/render-review-report.mjs` (the deterministic review report renderer)
+plus its `schemas/` and `examples/`, and those must travel together.
+```bash
+# from the installed npm package
+rm -rf &lt;your-skills-dir&gt;/artshelf
+cp -R "$(npm root -g)/artshelf/skills/artshelf" &lt;your-skills-dir&gt;/
+# or from a source checkout
+rm -rf &lt;your-skills-dir&gt;/artshelf
+cp -R "$ARTSHELF_REPO/skills/artshelf" &lt;your-skills-dir&gt;/
+```
+Re-run the replacement copy after upgrading the package so the skill and
+script stay in sync with the CLI.
+## 3. Register existing ledgers
+`artshelf put` registers its ledger automatically. Register any existing
+project ledgers so `--all` commands can see them:
+```bash
+artshelf ledgers add --ledger &lt;repo&gt;/.artshelf/ledger.jsonl --name &lt;project&gt; --scope repo --json
+artshelf ledgers list --json
+```
+## 4. Scheduled review (ask the user first)
+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 disables update checks and runs:
+```bash
+ARTSHELF_NO_UPDATE_CHECK=1 \
+artshelf review --all --json
+```
+and reports what needs attention. Scheduled jobs are review and report only:
+never schedule `artshelf cleanup --execute` or `artshelf trash purge
+--execute`.
+## 5. Verify and report
+Finish by showing the user the output of:
+```bash
+artshelf doctor
+artshelf ledgers list --json
+```</code></pre>
+            <div class="callout" data-kind="note">
+              <span class="callout-label">Verify</span>
+              <p>However setup happens, finish with <code>artshelf --version</code> and <code>artshelf doctor</code>.</p>
+            </div>
+          </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/quickstart.html CHANGED Viewed

@@ -3,78 +3,55 @@
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <title>Artshelf Quickstart</title>
-    <meta name="description" content="The approval-first Artshelf workflows: register a temp artifact, review everything safely, approve cleanup safely, and purge old trash explicitly.">
+    <title>Quickstart · Artshelf</title>
+    <meta name="description" content="One artifact through the whole Artshelf lifecycle: register, review, dry-run, approve, verify.">
+    <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="theme.js" defer></script>
+    <script src="site.js" defer></script>
   </head>
-  <body>
-    <div class="docs-shell">
-      <nav class="global-nav" aria-label="Documentation">
-        <a class="site-mark" href="index.html"><strong>Artshelf</strong><span>Artifact retention CLI</span></a>
-        <button class="theme-toggle" type="button" data-theme-toggle aria-label="Toggle color theme" aria-pressed="false">Dark</button>
-        <div class="nav-scroll" aria-label="Documentation sections">
-        <div class="nav-section">
-          <p class="nav-section-title">Start</p>
-          <a href="index.html">Overview</a>
-          <a href="install.html">Install</a>
-          <a href="quickstart.html" aria-current="page">Quickstart</a>
+  <body data-page="quickstart.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 class="nav-section">
-          <p class="nav-section-title">Agents</p>
-          <a href="agent-usage.html">Agent usage</a>
-          <a href="https://github.com/calvinnwq/artshelf/blob/main/skills/artshelf/SKILL.md">Agent skill</a>
-        </div>
-        <div class="nav-section">
-          <p class="nav-section-title">Reference</p>
-          <a href="reference.html">CLI reference</a>
-          <a href="https://github.com/calvinnwq/artshelf">GitHub</a>
-        </div>
-        </div>
-      </nav>
+      </div>
+    </header>
-      <div class="docs-content">
-        <header class="page-top">
-          <div class="wrap">
-            <nav class="breadcrumbs" aria-label="Breadcrumbs"><a href="index.html">Docs</a><span>/</span><span>Quickstart</span></nav>
-            <div class="hero">
-              <div>
-                <p class="eyebrow">Approval-first workflows</p>
-                <h1>Register, review, approve — safely.</h1>
-                <p class="lede">
-                  Artshelf centers on four workflows: register a temp artifact when it is created,
-                  review everything safely before anything moves, approve cleanup safely from a
-                  reviewed plan, and purge old trash only from a separate reviewed plan. Start with
-                  explicit ledger and registry paths when testing.
-                </p>
-              </div>
-              <div class="terminal">
-                <div class="terminal-head"><span class="dot"></span><span class="dot"></span><span class="dot"></span><span>quickstart</span></div>
-                <pre><code>$ mkdir -p /tmp/artshelf-demo
-$ echo "debug output" &gt; /tmp/artshelf-demo/output.txt
-$ artshelf put /tmp/artshelf-demo \
-  --reason "quickstart artifact" \
-  --ttl 1d \
-  --kind scratch \
-  --cleanup trash \
-  --ledger /tmp/artshelf-ledger.jsonl \
-  --registry /tmp/artshelf-registry.json</code></pre>
-              </div>
-            </div>
-          </div>
-        </header>
+    <div class="frame">
+      <nav id="sidebar" class="sidebar" aria-label="Documentation"></nav>
-        <main class="wrap">
-          <article>
-            <section>
-              <h2>1. Register a temp artifact</h2>
-              <p>Create something worth tracking, then put it on the artshelf the moment it exists:</p>
-              <pre><code>mkdir -p /tmp/artshelf-demo
+      <main id="content" class="article-col">
+        <article>
+          <p class="kicker"><span class="n">03</span>Start · Quickstart</p>
+          <h1>Put one artifact on the shelf.</h1>
+          <p class="lede">
+            The whole loop in five minutes, using throwaway paths under <code>/tmp</code>.
+            You will register one artifact, review it, dry-run the cleanup, execute the
+            approved plan, and verify. Trash gets purged separately at the end.
+          </p>
+          <section>
+            <h2>1. Create something temporary</h2>
+            <pre><code><span class="c"># make a scratch artifact to practice on</span>
+mkdir -p /tmp/artshelf-demo
 echo "debug output" &gt; /tmp/artshelf-demo/output.txt
+<span class="c"># put it on the shelf: make this demo immediately due, then trash on approval</span>
 artshelf put /tmp/artshelf-demo \
   --reason "quickstart artifact" \
-  --ttl 1d \
+  --ttl 0m \
   --kind scratch \
   --cleanup trash \
   --owner manual \
@@ -82,61 +59,83 @@ artshelf put /tmp/artshelf-demo \
   --ledger /tmp/artshelf-ledger.jsonl \
   --registry /tmp/artshelf-registry.json \
   --json</code></pre>
-              <p>Capture the returned `id` anywhere future cleanup context matters.</p>
-            </section>
+            <p>Note the <code>id</code> the command returns. You will quote it in handoffs and cleanup reports.</p>
+          </section>
-            <section>
-              <h2>2. Review everything safely</h2>
-              <p>Inspect the ledger and preview cleanup. None of these commands move or delete files.</p>
-              <pre><code>artshelf list --ledger /tmp/artshelf-ledger.jsonl
+          <section>
+            <h2>2. Review without moving files</h2>
+            <div class="callout" data-kind="readonly">
+              <span class="callout-label">Non-destructive</span>
+              <p>These commands are safe for agents and cron jobs. They never move artifacts or trash entries; cleanup <code>--dry-run</code> may register a review plan.</p>
+            </div>
+            <pre><code><span class="c"># everything on the shelf</span>
+artshelf list --ledger /tmp/artshelf-ledger.jsonl
+<span class="c"># quick counts: active, due, trashed</span>
 artshelf status --ledger /tmp/artshelf-ledger.jsonl
+<span class="c"># check the ledger file itself is healthy</span>
 artshelf validate --ledger /tmp/artshelf-ledger.jsonl --json
+<span class="c"># which records are due, kept, or missing</span>
 artshelf due --ledger /tmp/artshelf-ledger.jsonl --json
+<span class="c"># preview cleanup and get a plan id (still moves nothing)</span>
 artshelf cleanup --dry-run --ledger /tmp/artshelf-ledger.jsonl --json</code></pre>
-              <p>
-                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.
-              </p>
-            </section>
+            <p>
+              This demo uses <code>--ttl 0m</code>, so the dry-run writes a plan and prints
+              the <code>planId</code> a human can approve. When nothing is ready, the
+              dry-run reports <code>not-created</code>.
+            </p>
+          </section>
-            <section>
-              <h2>3. Approve cleanup safely</h2>
-              <pre><code>artshelf cleanup --execute \
+          <section>
+            <h2>3. Execute only an approved plan</h2>
+            <p>Copy the <code>planId</code> from the dry-run output in step 2.</p>
+            <pre><code><span class="c"># run only the plan that was reviewed</span>
+artshelf cleanup --execute \
   --plan-id plan_20260601_120000_ab12 \
   --ledger /tmp/artshelf-ledger.jsonl</code></pre>
-              <div class="note">
-                Execute is intentionally separate. Agents must not run it unless a human explicitly
-                approves the reviewed plan id and ledger that produced it. After execution, Artshelf writes
-                a receipt and updates touched records so handled artifacts stop appearing in future due checks.
-                Artshelf also records generated plans and receipts in the ledger as Artshelf-owned
-                artifacts.
-              </div>
-            </section>
-            <section>
-              <h2>4. Purge old trashed records explicitly</h2>
+            <div class="callout" data-kind="boundary">
+              <span class="callout-label">Hard boundary</span>
               <p>
-                After cleanup execution, trashed files are quarantined under the ledger's
-                <code>.artshelf/trash</code> folder. Before physical deletion, run an explicit
-                reviewed trash purge plan:
+                Execute is intentionally separate. Approval names the exact ledger path and
+                reviewed plan id. No global execute path exists.
               </p>
-              <pre><code>artshelf trash list --ledger /tmp/artshelf-ledger.jsonl
-artshelf trash purge --older-than 7d --dry-run --ledger /tmp/artshelf-ledger.jsonl --json</code></pre>
-              <p>
-                A fresh quickstart record will usually be newer than the <code>7d</code>
-                purge cutoff and report <code>not-created</code>; for real old trash, execute
-                only if the dry-run produced entries and the plan id was explicitly reviewed:
-              </p>
-              <pre><code>artshelf trash purge --execute \
+            </div>
+          </section>
+          <section>
+            <h2>4. Verify quiet</h2>
+            <p>After cleanup, run another read-only review.</p>
+            <pre><code><span class="c"># confirm nothing still needs attention</span>
+artshelf review --ledger /tmp/artshelf-ledger.jsonl --json
+<span class="c"># see what cleanup moved into trash</span>
+artshelf trash list --ledger /tmp/artshelf-ledger.jsonl --json</code></pre>
+          </section>
+          <section>
+            <h2>5. Purge trash separately</h2>
+            <p>
+              Cleanup with <code>cleanup=trash</code> moves files into Artshelf trash.
+              Physical deletion needs a separate reviewed purge plan.
+            </p>
+            <pre><code><span class="c"># preview which trashed files are old enough to purge</span>
+artshelf trash purge --older-than 0m --dry-run --ledger /tmp/artshelf-ledger.jsonl --json</code></pre>
+            <p>Then execute with the purge <code>planId</code> the dry-run reported.</p>
+            <pre><code><span class="c"># delete for real, but only with the reviewed purge plan id</span>
+artshelf trash purge --execute \
   --plan-id purge_20260601_120000_ab12 \
   --ledger /tmp/artshelf-ledger.jsonl</code></pre>
-            </section>
-          </article>
-        </main>
-        <footer class="site-footer"><div class="wrap">Artshelf docs · <a href="agent-usage.html">Next: agent usage</a></div></footer>
-      </div>
+          </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>