artshelf 0.8.0 → 0.10.0

package/docs/agent-monitor.html

@@ -67,13 +67,13 @@
               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
 
 <span class="c"># review and due-check every registered ledger at once</span>
-artshelf review --all --json
+artshelf review --all --agent
 artshelf due --all --json
 
 <span class="c"># find records this agent owns, across ledgers</span>
@@ -102,12 +102,20 @@ artshelf due --all --json
 
 <span class="c"># the full read-only pass: validate + due + plan preview</span>
 artshelf review --all --json
+artshelf review --all --agent
 
 <span class="c"># CLI version, paths, registry health, safety posture</span>
 artshelf doctor --json
+artshelf doctor --agent
 
 <span class="c"># lightweight counts, cron-friendly</span>
-artshelf status --all --json</code></pre>
+artshelf status --all --json
+artshelf status --all --agent</code></pre>
+            <p>
+              Use <code>--agent</code> for concise monitor decisions and exact next
+              actions. Use <code>--json</code> instead when the job needs full
+              audit/API detail for storage, debugging, or a custom report.
+            </p>
           </section>
 
           <section>

package/docs/agent-review.html

@@ -44,16 +44,22 @@
           <section>
             <h2>Daily review workflow</h2>
             <ol>
-              <li>Read <code>ledgers list</code>, <code>review --all</code>, and <code>trash list --all</code>.</li>
+              <li>Read <code>ledgers list --json</code>, <code>review --all --agent</code>, and <code>trash list --all --json</code>.</li>
               <li>Run explicit-ledger purge dry-runs only when old trash needs review.</li>
               <li>Classify each candidate: <code>trash-safe</code>, <code>needs-human-review</code>, <code>resolve-candidate</code>, or <code>registry-problem</code>.</li>
               <li>Ask only with exact ledger path, reviewed plan id, or ids.</li>
             </ol>
+            <p>
+              Prefer the built-in <code>--agent</code> packet when an acting agent
+              needs the compact decision surface. Use full <code>--json</code>
+              output when you need every ledger field for audit, debugging, or a
+              custom renderer.
+            </p>
           </section>
 
           <section>
             <h2>Review plan report schema</h2>
-            <p>Construct an <code>ArtshelfReviewReport</code> JSON packet first, then render a compact decision card.</p>
+            <p>For richer host cards, attachments, or audit packets, construct an <code>ArtshelfReviewReport</code> JSON packet first, then render a compact decision card.</p>
             <p>
               Use <a href="schemas/artshelf-review-report.schema.json">schemas/artshelf-review-report.schema.json</a>
               and <a href="examples/artshelf-review-report.json">examples/artshelf-review-report.json</a>.

package/docs/agent-usage.html

@@ -87,6 +87,20 @@
             </dl>
           </section>
 
+          <section>
+            <h2>Render modes</h2>
+            <p>
+              <code>review</code>, <code>status</code>, and <code>doctor</code> share three render modes
+              so the same data fits both people and agents. Reach for <code>--agent</code> when an agent
+              decides and acts; reach for <code>--json</code> for full record, plan, or health detail.
+            </p>
+            <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>
+            </dl>
+          </section>
+
           <section>
             <h2>The mental model</h2>
             <ul class="boundary-list">

package/docs/agent-usage.md

@@ -50,6 +50,23 @@ The browsable docs split the workflow into focused child pages:
 - Approval names the exact ledger, plan id, or record ids.
 - Every approved action ends with a read-only verification.
 
+## Render modes
+
+`review`, `status`, and `doctor` share three render modes so the same data fits
+both people and agents:
+
+- **default**: a human render — scannable grouped counts, attention states, and a
+  short next action for a person at the terminal.
+- **`--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.
+
+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
+debugging. `--agent` takes precedence if both flags are passed.
+
 ## Portable Skill
 
 The repo ships a portable skill at

package/docs/index.html

@@ -158,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>

package/docs/reference.html

@@ -42,6 +42,13 @@
             cleanup execution and trash purge. Every command below is tagged read-only,
             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">
             <div class="cmd-head"><h2>artshelf put</h2><span class="cmd-flag plan">writes ledger</span></div>
@@ -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.
@@ -113,19 +120,20 @@ artshelf validate [--all] [--json]</code></pre>
           <section class="cmd">
             <div class="cmd-head"><h2>artshelf review / status / doctor</h2><span class="cmd-flag readonly">read-only</span></div>
             <pre><code><span class="c"># validate + due + plan preview in one pass</span>
-artshelf review [--all] [--json]
+artshelf review [--all] [--agent] [--json]
 
 <span class="c"># lightweight dashboard of counts</span>
-artshelf status [--all] [--json]
+artshelf status [--all] [--agent] [--json]
 
 <span class="c"># CLI version, resolved paths, registry health</span>
-artshelf doctor [--json]</code></pre>
+artshelf doctor [--agent] [--json]</code></pre>
             <p>
               <code>review</code> runs validate, due, and a cleanup plan preview in one pass; no-op
               previews report <code>not-created</code>, and <code>--all</code> adds an aggregate triage
               summary plus the next safe action. <code>status</code> is the lightweight dashboard of
               counts; <code>--all --json</code> is cron-friendly. <code>doctor</code> reports CLI version,
-              resolved paths, registry health, and the cleanup safety posture.
+              resolved paths, registry health, and the cleanup safety posture. All three also accept
+              <code>--agent</code> for a deterministic, token-efficient decision packet (see Output mode).
             </p>
           </section>
 
@@ -153,7 +161,7 @@ artshelf update [--json]</code></pre>
 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
@@ -188,18 +196,67 @@ 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>
+              Every command has a default human render: compact, scannable terminal output with
+              grouped counts, a leading <code>✓</code>/<code>⚠</code> attention glyph on each ledger
+              and the summary line, and a short next action — meant for a person reading the screen,
+              not a wall of raw JSON. The glyphs are plain Unicode (no ANSI color), so redirected
+              output stays clean.
+            </p>
+            <p>
+              <code>review</code>, <code>status</code>, and <code>doctor</code> add <code>--agent</code>:
+              a deterministic, token-efficient decision packet emitted as a single line of compact JSON.
+              It names health, counts, classifications, exact approval targets, blockers, and the command
+              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
+              diagnostics stay on stderr and never corrupt JSON or packet output.
+            </p>
+            <table class="opts">
+              <tr><th>option</th><th>meaning</th></tr>
+              <tr><td>(default)</td><td>human render: grouped counts, ✓/⚠ attention glyphs, and a short next action</td></tr>
+              <tr><td>--agent</td><td>token-efficient decision packet for agents on <code>review</code>, <code>status</code>, <code>doctor</code></td></tr>
+              <tr><td>--json</td><td>full machine-readable audit 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>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>--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>

package/package.json

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

package/skills/artshelf/SKILL.md

@@ -59,8 +59,7 @@ npm link
 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.
+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.
 
 ## Create
 
@@ -72,15 +71,11 @@ artshelf put <path> --reason "<why this exists>" --ttl 3d --kind run-artifact --
 artshelf get <id> --json
 ```
 
-Register backups, quarantine folders, debug output, generated reports, long-run
-evidence, and copied files kept for review. Skip source files, cheap regenerated
-build output, dependency caches, secrets, credential dumps, and artifacts already
-owned by another durable ledger.
+Register backups, quarantine folders, debug output, generated reports, long-run evidence, and copied files kept for review. Skip source files, cheap regenerated
+build output, dependency caches, secrets, credential dumps, and artifacts already owned by another durable ledger.
 
-Defaults: `kind=scratch` for temp dirs, `backup` for rollback copies,
-`run-artifact` for logs/reports/evidence, `quarantine` for isolated questionable
-files. Use `cleanup=review` when judgment is needed and `cleanup=trash` only when
-later disposal is clearly safe.
+Defaults: `kind=scratch` for temp dirs, `backup` for rollback copies, `run-artifact` for logs/reports/evidence, `quarantine` for isolated questionable
+files. Use `cleanup=review` when judgment is needed and `cleanup=trash` only when later disposal is clearly safe.
 
 When JSON registration succeeds, include this deterministic Artshelf footnote:
 
@@ -94,13 +89,15 @@ Use the ledger registry for whole-machine review:
 
 ```bash
 artshelf ledgers list --json
-artshelf status --all --json
-artshelf review --all --json
+artshelf status --all --agent
+artshelf review --all --agent
 artshelf trash list --all --json
 ```
 
 `artshelf ledgers list --json` reports per-ledger validation status. `--plain`
 skips validation. `--all` is for discovery and review, not mutation permission.
+Use `--agent` on `review`, `status`, and `doctor` for compact decisions; use
+`--json` for full audit/API payloads, custom rendering, or debugging.
 
 Register existing project ledgers explicitly:
 
@@ -144,22 +141,23 @@ Daily Review Workflow: turn raw Artshelf output into a decision packet, not a
 count dump.
 
 1. Run read-only review first: `artshelf ledgers list --json`,
-   `artshelf review --all --json`, and `artshelf trash list --all --json`.
+   `artshelf review --all --agent`, and `artshelf trash list --all --json`.
 2. If cleanup attention exists, run `artshelf cleanup --dry-run --all --json`.
 3. Classify candidates as `trash-safe`, `needs-human-review`,
    `resolve-candidate`, or `registry-problem`.
-4. Use `ArtshelfReviewReport` from
-   `schemas/artshelf-review-report.schema.json`; use
-   `examples/artshelf-review-report.json` as the canonical packet.
-5. Render the compact decision card with `scripts/render-review-report.mjs`;
-   keep `decisionSummary` in audit, while `decisionGroups` drive counts.
-   Emojis are encouraged only in host-specific wrappers, not the renderer.
+4. Use the built-in `--agent` packet when the CLI output is enough to decide,
+   because it is deterministic and token-efficient. Use
+   `ArtshelfReviewReport` from `schemas/artshelf-review-report.schema.json` and
+   `examples/artshelf-review-report.json` when you need a host-specific card,
+   attachment, or richer audit record.
+5. Render full packets with `scripts/render-review-report.mjs`; keep
+   `decisionSummary` in audit, while `decisionGroups` drive counts. Emojis are encouraged only in host-specific wrappers, not the renderer.
 6. Always include the exact approval target in the message body as a fallback.
    Do not paste the whole packet into chat unless the user asks for it.
 
 ### Review Plan Report Schema
 
-Deterministic renderer:
+Deterministic compact decision card renderer:
 
 ```bash
 cd /path/to/skills/artshelf