artshelf 0.7.0 → 0.8.0

package/dist/src/cli.js

@@ -1,8 +1,14 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
 import { appendPreparedRecord, createCleanupPlan, createTrashPurgePlan, dueEntries, executeCleanupPlan, executeTrashPurgePlan, filterRecordsByStatus, findRecords, getRecord, listTrashedRecords, normalizeLedgerPath, prepareRecord, previewCleanupPlan, readLedger, resolveRecord, validateLedger } from "./ledger.js";
 import { listRegisteredLedgers, normalizeRegistryPath, registerLedger } from "./registry.js";
 const VERSION = readPackageVersion();
+const PACKAGE_NAME = "artshelf";
+const NPM_REGISTRY_URL = process.env.ARTSHELF_NPM_REGISTRY_URL ?? `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+const UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
 const BOOLEAN_FLAGS = new Set(["all", "json", "manual-review", "dry-run", "execute", "help", "version", "plain"]);
 const VALUE_FLAGS = new Set([
     "cleanup",
@@ -29,56 +35,83 @@ function readPackageVersion() {
     }
     return packageJson.version;
 }
-function main(argv) {
+async function main(argv) {
     try {
         const parsed = parseArgs(argv);
+        let status = 0;
+        let shouldCheckForUpdate = true;
         if (parsed.command === "--version" || parsed.command === "-v" || boolFlag(parsed, "version")) {
             process.stdout.write(`artshelf ${VERSION}\n`);
-            return 0;
+            return maybeNotifyUpdateAndReturn(0, parsed);
         }
         if (parsed.command === "help" || parsed.command === "--help" || parsed.command === "-h" || boolFlag(parsed, "help")) {
             printHelp(parsed.command === "help" ? parsed.positionals[0] : parsed.command);
-            return 0;
+            return maybeNotifyUpdateAndReturn(0, parsed);
         }
         switch (parsed.command) {
             case "put":
-                return handlePut(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handlePut(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "ledgers":
-                return handleLedgers(parsed, boolFlag(parsed, "json"));
+                status = handleLedgers(parsed, boolFlag(parsed, "json"));
+                break;
             case "list":
-                return handleList(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleList(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "find":
-                return handleFind(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleFind(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "get":
-                return handleGet(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleGet(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "due":
-                return handleDue(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleDue(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "validate":
-                return handleValidate(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleValidate(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "cleanup":
-                return handleCleanup(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleCleanup(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "trash":
-                return handleTrash(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleTrash(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "review":
-                return handleReview(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleReview(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "doctor":
-                return handleDoctor(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleDoctor(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "status":
-                return handleStatus(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleStatus(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "resolve":
-                return handleResolve(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleResolve(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
+            case "update":
+                shouldCheckForUpdate = false;
+                status = await handleUpdate(parsed, boolFlag(parsed, "json"));
+                break;
             case undefined:
                 printHelp();
-                return 0;
+                status = 0;
+                break;
             default:
                 throw new Error(`Unknown command: ${parsed.command}`);
         }
+        if (!shouldCheckForUpdate)
+            return status;
+        return maybeNotifyUpdateAndReturn(status, parsed);
     }
     catch (error) {
         process.stderr.write(`artshelf: ${error.message}\nRun \`artshelf help\` for usage.\n`);
         return 1;
     }
 }
+async function maybeNotifyUpdateAndReturn(status, parsed) {
+    await maybeNotifyAvailableUpdate(parsed);
+    return status;
+}
 function handlePut(parsed, ledgerPath, json) {
     const path = parsed.positionals[0];
     if (!path)
@@ -726,6 +759,189 @@ function printStatusSingle(ledger) {
             process.stdout.write(`error: ${message}\n`);
     }
 }
+async function handleUpdate(parsed, json) {
+    if (parsed.positionals.length > 0)
+        throw new Error("update does not accept positional arguments");
+    const info = await getUpdateInfo({ force: true });
+    if (!info)
+        throw new Error("Could not check npm for the latest Artshelf version");
+    if (!info.updateAvailable) {
+        if (json)
+            return printJson({ ok: true, updated: false, current: info.current, latest: info.latest });
+        process.stdout.write(`artshelf is already up to date: v${info.current}\n`);
+        return 0;
+    }
+    if (process.env.ARTSHELF_UPDATE_DRY_RUN === "1") {
+        if (json) {
+            return printJson({
+                ok: true,
+                updated: false,
+                dryRun: true,
+                current: info.current,
+                latest: info.latest,
+                command: ["npm", "install", "-g", `${PACKAGE_NAME}@latest`]
+            });
+        }
+        process.stdout.write(`A new version of artshelf is available: v${info.current} -> v${info.latest}\n`);
+        process.stdout.write(`Dry run: would run "npm install -g ${PACKAGE_NAME}@latest"\n`);
+        return 0;
+    }
+    if (!json) {
+        process.stdout.write(`A new version of artshelf is available: v${info.current} -> v${info.latest}\n`);
+        process.stdout.write(`Updating with "npm install -g ${PACKAGE_NAME}@latest"...\n`);
+    }
+    const result = json
+        ? spawnSync("npm", ["install", "-g", `${PACKAGE_NAME}@latest`], { encoding: "utf8" })
+        : spawnSync("npm", ["install", "-g", `${PACKAGE_NAME}@latest`], { stdio: "inherit" });
+    const status = result.status ?? 1;
+    const spawnError = result.error instanceof Error ? result.error.message : "";
+    if (json) {
+        const stderr = typeof result.stderr === "string" ? result.stderr : "";
+        printJson({
+            ok: status === 0,
+            updated: status === 0,
+            current: info.current,
+            latest: info.latest,
+            stdout: typeof result.stdout === "string" ? result.stdout : "",
+            stderr: appendOutputMessage(stderr, spawnError)
+        });
+        return status;
+    }
+    if (spawnError)
+        process.stderr.write(`Update failed: ${spawnError}\n`);
+    if (status === 0)
+        process.stdout.write(`artshelf updated to v${info.latest}\n`);
+    return status;
+}
+function appendOutputMessage(output, message) {
+    if (!message)
+        return output;
+    if (!output)
+        return message;
+    return `${output}${output.endsWith("\n") ? "" : "\n"}${message}`;
+}
+async function maybeNotifyAvailableUpdate(parsed) {
+    if (process.env.ARTSHELF_NO_UPDATE_CHECK === "1")
+        return;
+    if (parsed.command === "update")
+        return;
+    const info = await getUpdateInfo({ force: false });
+    if (!info?.updateAvailable)
+        return;
+    process.stderr.write(`A new version of artshelf is available: v${info.current} -> v${info.latest}\n`);
+    process.stderr.write(`Run "artshelf update" to update npm installs\n`);
+}
+async function getUpdateInfo(options) {
+    const latest = await getLatestVersion(options);
+    if (!latest)
+        return null;
+    return {
+        current: VERSION,
+        latest,
+        updateAvailable: compareVersions(latest, VERSION) > 0
+    };
+}
+async function getLatestVersion(options) {
+    const override = process.env.ARTSHELF_LATEST_VERSION;
+    if (override)
+        return normalizeVersion(override);
+    if (!options.force) {
+        const cached = readUpdateCache();
+        if (cached)
+            return cached.latest;
+    }
+    const latest = await fetchLatestNpmVersion();
+    writeUpdateCache(latest);
+    return latest;
+}
+function readUpdateCache() {
+    const ttl = Number(process.env.ARTSHELF_UPDATE_CHECK_TTL_MS ?? UPDATE_CHECK_TTL_MS);
+    if (ttl < 0)
+        return null;
+    const cachePath = updateCachePath();
+    if (!existsSync(cachePath))
+        return null;
+    try {
+        const cache = JSON.parse(readFileSync(cachePath, "utf8"));
+        if (cache.latest !== null && typeof cache.latest !== "string")
+            return null;
+        if (typeof cache.checkedAt !== "number")
+            return null;
+        if (Date.now() - cache.checkedAt > ttl)
+            return null;
+        return { latest: cache.latest === null ? null : normalizeVersion(cache.latest) };
+    }
+    catch {
+        return null;
+    }
+}
+function writeUpdateCache(latest) {
+    try {
+        const cachePath = updateCachePath();
+        const dir = dirname(cachePath);
+        if (dir) {
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(cachePath, `${JSON.stringify({ latest, checkedAt: Date.now() }, null, 2)}\n`);
+        }
+    }
+    catch {
+        // Update checks should never affect normal CLI behavior.
+    }
+}
+async function fetchLatestNpmVersion() {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 750);
+    try {
+        const response = await fetch(NPM_REGISTRY_URL, {
+            signal: controller.signal,
+            headers: { accept: "application/json", "user-agent": `artshelf/${VERSION}` }
+        });
+        if (!response.ok)
+            return null;
+        const body = await response.json();
+        if (!body || typeof body !== "object" || typeof body.version !== "string")
+            return null;
+        return normalizeVersion(body.version);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function updateCachePath() {
+    return process.env.ARTSHELF_UPDATE_CACHE ?? join(homedir(), ".artshelf", "update-check.json");
+}
+function normalizeVersion(version) {
+    return version.trim().replace(/^v/i, "");
+}
+function compareVersions(left, right) {
+    const a = parseVersion(left);
+    const b = parseVersion(right);
+    for (let index = 0; index < Math.max(a.numbers.length, b.numbers.length); index += 1) {
+        const diff = (a.numbers[index] ?? 0) - (b.numbers[index] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    if (a.prerelease === b.prerelease)
+        return 0;
+    if (!a.prerelease)
+        return 1;
+    if (!b.prerelease)
+        return -1;
+    return a.prerelease.localeCompare(b.prerelease);
+}
+function parseVersion(version) {
+    const [main = "", prerelease = ""] = normalizeVersion(version).split("-", 2);
+    return {
+        numbers: main.split(".").map((part) => {
+            const parsed = Number.parseInt(part, 10);
+            return Number.isFinite(parsed) ? parsed : 0;
+        }),
+        prerelease
+    };
+}
 function parseArgs(argv) {
     const [command, ...rest] = argv;
     const flags = new Map();
@@ -1107,6 +1323,21 @@ Human output is short enough to paste into a chat; \`artshelf status --all --jso
 is suitable for cron and reporting. Status is read-only: it never creates plans
 or receipts and never mutates records. A healthy selected ledger exits 0; with
 --all, a broken registry or any stale or invalid registered ledger exits non-zero.
+`);
+        return;
+    }
+    if (command === "update") {
+        process.stdout.write(`Usage:
+  artshelf update [--json]
+
+Update checks compare the current CLI version with the latest published npm
+version. Normal commands may print a non-blocking update notice to stderr when a
+newer version is available. Run update to upgrade npm global installs only:
+
+  npm install -g artshelf@latest
+
+pnpm global installs should update with pnpm add -g artshelf@latest; source
+installs should update by pulling, rebuilding, and linking the checkout.
 `);
         return;
     }
@@ -1132,6 +1363,7 @@ Usage:
   artshelf doctor [--json]
   artshelf status [--json]
   artshelf status --all [--json]
+  artshelf update [--json]
   artshelf cleanup --dry-run [--json]
   artshelf cleanup --dry-run --all [--json]
   artshelf cleanup --execute --plan-id <id> [--json]
@@ -1154,4 +1386,11 @@ Examples:
   artshelf cleanup --execute --plan-id plan_20260601_120000_ab12
 `);
 }
-process.exitCode = main(process.argv.slice(2));
+main(process.argv.slice(2))
+    .then((status) => {
+    process.exitCode = status;
+})
+    .catch((error) => {
+    process.stderr.write(`artshelf: ${error.message}\nRun \`artshelf help\` for usage.\n`);
+    process.exitCode = 1;
+});

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

@@ -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.