artshelf 0.7.0 → 0.8.0

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>
@@ -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,7 @@
             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>
 
           <section class="cmd">
@@ -129,6 +129,24 @@ 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>
@@ -184,6 +202,12 @@ artshelf trash purge --execute --plan-id &lt;id&gt; [--ledger &lt;path&gt;] [--j
               <tr><td>--json</td><td>emit machine-readable JSON</td></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 +232,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.8.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.