artshelf 0.10.0 → 0.10.2

package/docs/agent-usage.html

@@ -97,7 +97,7 @@
             <dl class="def-rows">
               <div><dt>default</dt><dd>human render: scannable grouped counts, attention states, and a short next action for a person at the terminal</dd></div>
               <div><dt>--agent</dt><dd>a deterministic, token-efficient decision packet (single-line compact JSON) with health, counts, classifications, exact approval targets, blockers, and a verification command</dd></div>
-              <div><dt>--json</dt><dd>the full audit and API contract: complete machine-readable JSON for debugging and existing integrations, unchanged and backward compatible</dd></div>
+              <div><dt>--json</dt><dd>the backward-compatible public audit contract: complete machine-readable JSON for debugging and integrations</dd></div>
             </dl>
           </section>
 

package/docs/agent-usage.md

@@ -60,8 +60,8 @@ both people and agents:
 - **`--agent`**: a deterministic, token-efficient decision packet (single-line
   compact JSON) with health, counts, classifications, exact approval targets,
   blockers, and a verification command. Use it when an agent acts on the result.
-- **`--json`**: the full audit and API contract — complete machine-readable JSON
-  for debugging and existing integrations, unchanged and backward compatible.
+- **`--json`**: the backward-compatible public audit contract — complete
+  machine-readable JSON for debugging and integrations.
 
 Reach for `--agent` when an agent needs to decide and act cheaply; reach for
 `--json` when you want the full record, plan, or health detail for audit or

package/docs/reference.html

@@ -148,7 +148,10 @@ artshelf update [--json]</code></pre>
               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/update-check.json</code>: update-available results use
+              the long 24-hour TTL, while no-update, failed, missing, or null results
+              use a shorter 1-hour TTL so newly published releases are noticed sooner.
+              <code>artshelf update</code> forces a fresh latest-version check. 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.
@@ -226,9 +229,9 @@ artshelf trash purge --execute --plan-id &lt;id&gt; [--ledger &lt;path&gt;] [--j
               to re-run for verification, so an agent can act without parsing decorative output.
             </p>
             <p>
-              <code>--json</code> stays the audit and API contract: the full, pretty-printed report for
-              debugging, audit trails, and existing integrations. It is unchanged and backward compatible,
-              and <code>--agent</code> takes precedence when both are passed. Update notices and other
+              <code>--json</code> stays the backward compatible public audit contract: the full,
+              pretty-printed report for debugging, audit trails, and integrations.
+              <code>--agent</code> takes precedence when both are passed. Update notices and other
               diagnostics stay on stderr and never corrupt JSON or packet output.
             </p>
             <table class="opts">
@@ -261,7 +264,8 @@ artshelf trash purge --execute --plan-id &lt;id&gt; [--ledger &lt;path&gt;] [--j
               <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_UPDATE_CHECK_TTL_MS</td><td>override the update-available cache TTL; also acts as the no-update TTL fallback for compatibility</td></tr>
+              <tr><td>ARTSHELF_NO_UPDATE_CHECK_TTL_MS</td><td>override the no-update/failed cache TTL specifically</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>
@@ -290,7 +294,9 @@ artshelf trash purge --execute --plan-id &lt;id&gt; [--ledger &lt;path&gt;] [--j
               <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. Automatic update checks cache their last npm result at
-              <code>~/.artshelf/update-check.json</code> by default.
+              <code>~/.artshelf/update-check.json</code> by default, with a long TTL
+              for update-available results and a shorter TTL for no-update or failed
+              results.
             </p>
             <div class="callout" data-kind="boundary">
               <span class="callout-label">Hard boundary</span>

package/package.json

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