artshelf 0.3.0

package/docs/agent-usage.md

@@ -0,0 +1,392 @@
+# Agent Usage
+
+Agents that support local skills can copy or reference
+[`skills/artshelf/SKILL.md`](../skills/artshelf/SKILL.md). The public docs site at
+<https://calvinnwq.github.io/artshelf/> explains the same contract in browsable
+form.
+
+Artshelf works best when agents register artifacts at creation time, while the
+reason is still fresh. Do not wait for a cleanup pass to infer intent from file
+age or path names.
+
+## When To Register
+
+Treat Artshelf as a finalization trigger, not an optional cleanup habit. Before an
+agent reports a task as done, it must check whether the task created, copied,
+exported, quarantined, backed up, or preserved any non-source file or directory
+that may outlive the current command.
+
+Call `artshelf put` immediately after creating an eligible artifact:
+
+- config backups
+- rollback copies
+- quarantine folders
+- debug output directories
+- generated reports
+- temporary repo artifacts
+- long-running task evidence
+- copied files kept so a reviewer can inspect them later
+
+Do not register normal source files, committed documentation, package build
+outputs that can be regenerated cheaply, or dependency caches.
+
+If an eligible artifact is not registered, the agent should state why. Common
+valid reasons are: the artifact is source-controlled, it is a cheap
+regeneratable cache/build output, it contains secrets, it belongs to another
+durable artifact system, or the user explicitly asked not to retain it.
+
+## Command Shape
+
+Use the installed CLI when available:
+
+```bash
+artshelf put <path> --reason "<why this exists>" --ttl 3d --kind run-artifact --cleanup review --owner agent
+```
+
+If Artshelf is not installed, use the package-manager install path when
+available:
+
+```bash
+npm install -g artshelf
+artshelf --version
+artshelf doctor
+```
+
+With pnpm:
+
+```bash
+pnpm add -g artshelf
+artshelf --version
+artshelf doctor
+```
+
+For source installs, do not assume a repo path. Ask where the user wants the
+Artshelf repo cloned, then use the supported local 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
+```
+
+Do not create a custom shim. Use the published package or `npm link` from a
+local source checkout.
+
+Useful defaults for agents:
+
+- `--kind scratch` for temporary working directories.
+- `--kind backup` for rollback copies.
+- `--kind run-artifact` for logs, reports, and generated evidence.
+- `--kind quarantine` for files isolated because they may be unsafe or wrong.
+- `--cleanup review` when a human or future agent should inspect before moving.
+- `--cleanup trash` only when the artifact is definitely disposable after the
+  retention window.
+- `--owner <agent-or-runtime>` should name the agent, tool, CI job, or human
+  process that created the artifact.
+- `--label <project>` and `--label <task-id>` when the artifact relates to a
+  repo, PR, issue, workflow id, or run id.
+
+Use `--json` when another tool needs to capture the Artshelf entry id.
+
+## Idempotent Lookup
+
+Integrations should check the ledger before creating another record for the
+same artifact. Use `find` and `get` for read-only lookup:
+
+```bash
+artshelf find --path <path> --owner <agent-or-runtime> --label <task-or-run-id> --json
+artshelf get <id> --json
+```
+
+`find` requires at least one selector: `--path`, `--owner`, `--label`, or
+`--status`. Multiple labels are an all-label match. If `find` returns an
+existing record, report that Artshelf id instead of calling `put` again. If it
+returns no entries, call `put` and record the new id.
+
+## Ledger Registry
+
+Artshelf keeps a user-level registry at `~/.shelf/ledgers.json` so one CLI can
+review all known ledgers without moving project records into one global file.
+`put` registers the ledger it writes to. Register existing ledgers explicitly
+when adopting Artshelf for an existing project:
+
+```bash
+artshelf ledgers add --ledger <repo>/.shelf/ledger.jsonl --name <project> --scope repo
+artshelf ledgers list --json
+```
+
+`artshelf ledgers list --json` validates each registered ledger and reports
+ok/missing/invalid status with entry and warning/error counts, so agents can
+detect stale registry entries without a separate validate pass. Add `--plain`
+for a fast listing that skips validation.
+
+Use the registry for read-only review and discovery:
+
+```bash
+artshelf review --all --json
+artshelf status --all --json
+artshelf due --all --json
+artshelf find --all --owner <agent-or-runtime> --json
+artshelf trash list --all --json
+```
+
+`artshelf review --all --json` returns an aggregate triage summary (affected
+ledgers, due, manual-review, missing-path, executable, and skipped counts plus
+preview plan ids) alongside the per-ledger detail, and states the next safe
+action.
+
+Use global cleanup dry-run when you want Artshelf to write cleanup plans for
+registered ledgers with cleanup entries, without moving files:
+
+```bash
+artshelf cleanup --dry-run --all --json
+```
+
+Do not use `--all` as permission to mutate files. Cleanup execution remains
+ledger-specific and requires a reviewed plan id for that ledger.
+If the executable cleanup entries have not changed, dry-run reuses the existing
+plan id and refreshes the same plan file instead of creating duplicate plans.
+
+## Daily Review Workflow
+
+Use this flow when a scheduled review, recurring task, or user request reports
+Artshelf cleanup attention:
+
+1. Register artifacts early during work, or state why an eligible artifact was
+   skipped.
+2. Review state with read-only commands first:
+   `artshelf ledgers list --json`, `artshelf review --all --json`, and
+   `artshelf trash list --all --json`; for old trash on a selected ledger, run
+   `artshelf trash purge --older-than 7d --dry-run --ledger <ledger-path> --json`.
+3. Present a decision packet instead of raw counts. Include registry health,
+   affected ledgers, due/manual-review/missing-path counts, executable entries,
+   skipped entries, refused entries, trashed record counts and ages, purge
+   dry-run plan ids/skipped entries, and the next safe action.
+4. Classify each candidate:
+   - `trash-safe`: disposable after the reviewed plan moves it into Artshelf trash.
+   - `needs-human-review`: `cleanup=review`, evidence, backups, reports, or
+     anything that should be inspected before closing.
+   - `resolve-candidate`: already handled, missing, or no longer needed; use
+     `artshelf resolve` only after confirmation.
+   - `registry-problem`: stale, missing, or invalid ledger; fix registry health
+     before touching artifacts.
+5. If cleanup execution is appropriate, generate or reuse a dry-run plan, then
+   ask for explicit approval naming the ledger path and reviewed plan id.
+6. For trashed records, require a separate reviewed purge plan before physical
+   deletion:
+
+```bash
+artshelf trash list --ledger <ledger-path>
+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
+```
+
+7. After approved cleanup execute, trash purge, or resolve, verify quiet with
+   `artshelf review --all --json`, plus `artshelf trash list --ledger <ledger-path> --json`
+   and purge receipt evidence after purge, or explain what remains.
+
+Approval wording should be exact:
+
+```text
+approve artshelf cleanup ledger <ledger-path> plan <plan-id>
+approve artshelf trash purge ledger <ledger-path> plan <purge-plan-id>
+```
+
+Never execute from a read-only preview id. Never generate a fresh plan and
+execute it in the same step. `trash` moves artifacts into Artshelf trash; physical
+delete requires a separate reviewed trash purge plan.
+
+## Reasons
+
+Write reasons as small audit notes. A good reason lets a future agent decide
+whether the artifact still matters without replaying the whole conversation.
+
+Good:
+
+```text
+backup before rewriting migration order for issue-123
+```
+
+Weak:
+
+```text
+backup
+```
+
+Include the source of authority when useful: PR number, issue id, workflow id,
+command, failing check, or user request.
+
+## Reporting Artshelf IDs
+
+After registration, include the Artshelf id anywhere future cleanup context will be
+read:
+
+- handoff notes
+- PR comments
+- issue comments
+- daily memory
+- task run summaries
+- incident or debugging notes
+
+Example:
+
+```text
+Temporary parser output registered in Artshelf as shf_20260601_182800_ab12.
+Retain until 2026-06-04; cleanup=review.
+```
+
+## Cleanup Boundary
+
+Agents may run non-destructive cleanup checks:
+
+```bash
+artshelf validate --json
+artshelf validate --all --json
+artshelf due --json
+artshelf due --all --json
+artshelf review --all --json
+```
+
+Cleanup dry-run is safe to run. It writes plan files for later review only when
+there are executable cleanup entries:
+
+```bash
+artshelf cleanup --dry-run --json
+artshelf cleanup --dry-run --all --json
+```
+
+Cleanup execution is approval-only: no daemon, no auto-execute, no global
+execute, and no fresh-plan-then-execute shortcut. Agents must not run this
+without explicit human approval:
+
+```bash
+artshelf cleanup --execute --plan-id <id>
+```
+
+Approval should name the plan id. Do not generate a fresh plan and execute it in
+the same breath. Review the dry-run first, then execute the reviewed plan id.
+After cleanup execution, agents may inspect trash and create a purge dry-run for
+review:
+
+```bash
+artshelf trash list --ledger <ledger-path> --json
+artshelf trash purge --older-than 7d --dry-run --ledger <ledger-path> --json
+```
+
+Trash purge execution is separately approval-only and must name the ledger and
+reviewed purge plan id:
+
+```bash
+artshelf trash purge --execute --plan-id <purge-plan-id> --ledger <ledger-path> --json
+```
+
+No-op dry-runs report `not-created` and do not write plan files. When dry-run or
+execute creates plan or receipt artifacts, Artshelf records those artifacts in the
+ledger as `owner=artshelf`.
+
+`cleanup=delete` stays refused; execution records `cleanup-refused` instead
+of silently deleting files. Physical deletion requires a separate reviewed trash
+purge plan.
+
+Execution writes a receipt and updates touched ledger records to `trashed`,
+`review-required`, or `cleanup-refused`, so handled artifacts stop reappearing in
+future due and dry-run cleanup output.
+
+Agents may mark a ledger record manually resolved when the user confirms the
+artifact was inspected, is already missing, or is no longer needed:
+
+```bash
+artshelf resolve <id> --status resolved --reason <text>
+```
+
+Use a specific reason. `resolve` only updates the ledger; it does not move or
+delete files. Resolved records stop reappearing in future due and dry-run
+cleanup output while remaining visible in `artshelf list --status resolved`.
+
+## Scheduled Review
+
+Agents may schedule routine Artshelf reviews for stale artifacts through their host
+runtime, such as an agent cron, CI job, or recurring task. Keep the scheduled
+job non-destructive:
+
+```bash
+artshelf validate --json
+artshelf due --json
+artshelf review --all --json
+```
+
+Read-only health and dashboard checks are also safe to schedule. Run
+`artshelf review --all --json` for aggregate triage (`summary` and `nextAction`),
+`artshelf doctor --json` to catch a broken or stale registry before relying on
+cleanup planning, and `artshelf status --all --json` for a compact cron summary:
+
+```bash
+artshelf doctor --json
+artshelf status --all --json
+```
+
+Scheduled cleanup and trash purge dry-runs may write plan files for later review
+when entries exist, but must not move or delete files:
+
+```bash
+artshelf cleanup --dry-run --json
+artshelf trash list --ledger <ledger-path> --json
+artshelf trash list --all --json
+artshelf trash purge --older-than 7d --dry-run --ledger <ledger-path> --json
+```
+
+The scheduled job should report the ledger path, due/manual-review/missing-path
+counts, cleanup dry-run plan id, executable entries, skipped entries, and refused
+entries. When reporting trash, `artshelf trash list --all --json` may discover trashed
+records across registered ledgers. Include trashed record counts and target ages;
+run purge dry-runs only for an explicit ledger and report any plan id, matching
+entries, and skipped entries. It should be
+quiet when nothing needs attention unless the user asked for a regular summary.
+
+Use explicit ledger paths when scheduling checks for a known project or user
+ledger. Do not scan arbitrary filesystem locations looking for ledgers unless
+the user has opted into that discovery scope.
+
+Scheduled jobs must not run cleanup execution or trash purge execution. They
+may only dry-run and report plans for later human review:
+
+```bash
+artshelf cleanup --execute --plan-id <id>
+artshelf trash purge --execute --plan-id <id>
+```
+
+Any later execution requires a human to review the dry-run output and approve
+that specific plan id.
+
+## Handoff Pattern
+
+When a task creates registered artifacts, add a short section like this:
+
+```text
+Artshelf artifacts:
+- shf_20260601_182800_ab12: /tmp/parser-output, debug evidence for issue-123,
+  retain until 2026-06-04, cleanup=review
+```
+
+If there are no eligible artifacts, say nothing. If eligible artifacts were
+skipped instead of registered, include the brief skip reason from the completion
+checklist. Do not invent Artshelf entries after the fact just to make a handoff look
+tidy.
+
+## Completion Checklist
+
+Before final response or handoff, agents should review their own file actions
+from the current task:
+
+1. Did I create, copy, export, quarantine, back up, or preserve any non-source
+   file or directory?
+2. Will any of those paths outlive this command?
+3. If yes, did I either register them with Artshelf or record a clear skip reason?
+
+Do not call work done while known eligible artifacts are neither registered nor
+explicitly skipped.

package/docs/index.html

@@ -0,0 +1,172 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Artshelf Docs</title>
+    <meta name="description" content="Artshelf is a tiny CLI for accountable temporary artifact retention.">
+    <link rel="stylesheet" href="site.css">
+    <script src="theme.js" defer></script>
+  </head>
+  <body>
+    <div class="docs-shell">
+      <nav class="global-nav" aria-label="Documentation">
+        <a class="site-mark" href="index.html" aria-current="page">
+          <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" aria-current="page">Overview</a>
+          <a href="install.html">Install</a>
+          <a href="quickstart.html">Quickstart</a>
+        </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">
+              <span>Docs</span>
+            </nav>
+            <div class="hero">
+              <div>
+                <p class="eyebrow">Temporary artifacts · Accountable cleanup</p>
+                <h1>Put run outputs somewhere accountable.</h1>
+                <p class="lede">
+                  Artshelf records why temporary artifacts, backups, and debug evidence exist,
+                  then gives humans and agents a reviewable cleanup plan before anything moves.
+                </p>
+                <div class="actions">
+                  <a class="button primary" href="install.html">Install from source</a>
+                  <a class="button" href="quickstart.html">Quickstart</a>
+                  <a class="button" href="agent-usage.html">Agent usage</a>
+                  <a class="button" href="https://github.com/calvinnwq/artshelf">GitHub</a>
+                </div>
+              </div>
+              <div class="terminal" aria-label="Artshelf terminal example">
+                <div class="terminal-head"><span class="dot"></span><span class="dot"></span><span class="dot"></span><span>artshelf</span></div>
+                <pre><code>$ artshelf put /tmp/parser-output \
+  --reason "debug evidence for parser fix" \
+  --ttl 3d \
+  --kind run-artifact \
+  --cleanup review
+
+recorded shf_20260601_182800_ab12
+retains until: 2026-06-04T08:28:00Z
+
+$ artshelf cleanup --dry-run --json
+{ "plan": { "planId": "not-created", "planPath": null } }</code></pre>
+              </div>
+            </div>
+          </div>
+        </header>
+
+        <main class="wrap">
+          <article>
+            <section>
+              <h2>Why Artshelf Exists</h2>
+              <p>
+                Agent-heavy projects create a lot of temporary stuff: copied files, rollback
+                folders, smoke-test output, reports, and logs. Filesystem age cannot tell a future
+                agent whether those artifacts are still useful. Artshelf captures intent at creation
+                time, while the reason is still fresh.
+              </p>
+              <div class="summary-grid">
+                <div class="stat"><strong>13</strong><span>small v1 commands</span></div>
+                <div class="stat"><strong>0</strong><span>runtime dependencies</span></div>
+                <div class="stat"><strong>JSONL</strong><span>plain ledger storage</span></div>
+                <div class="stat"><strong>dry-run</strong><span>before mutation</span></div>
+              </div>
+            </section>
+
+            <section>
+              <h2>What Artshelf Does</h2>
+              <div class="grid">
+                <div class="card">
+                  <h3>Register a temp artifact</h3>
+                  <p>Record path, reason, owner, labels, retention, and cleanup mode with `artshelf put`.</p>
+                </div>
+                <div class="card">
+                  <h3>Review everything safely</h3>
+                  <p>Use `artshelf due` and `artshelf cleanup --dry-run` to inspect what needs attention; no-op previews report `not-created`.</p>
+                </div>
+                <div class="card">
+                  <h3>Approve cleanup safely</h3>
+                  <p>Cleanup execution uses a human-approved plan id, writes a receipt, and updates ledger state.</p>
+                </div>
+                <div class="card">
+                  <h3>Purge old trash explicitly</h3>
+                  <p>Trash purge physically removes only quarantined trash from a separately reviewed purge plan.</p>
+                </div>
+              </div>
+            </section>
+
+            <section>
+              <h2>Pick Your Path</h2>
+              <div class="grid">
+                <a class="doc-card" href="install.html">
+                  <strong>Install from source</strong>
+                  <span>Clone locally, build, link with npm, and smoke-test the CLI.</span>
+                </a>
+                <a class="doc-card" href="quickstart.html">
+                  <strong>Try the workflow</strong>
+                  <span>Register a temp artifact, review safely, approve cleanup, and purge old trash explicitly.</span>
+                </a>
+                <a class="doc-card" href="agent-usage.html">
+                  <strong>Wire up agents</strong>
+                  <span>Teach agents when to call Artshelf and how to report Artshelf ids.</span>
+                </a>
+                <a class="doc-card" href="reference.html">
+                  <strong>Look up commands</strong>
+                  <span>See the v1 command surface and cleanup safety rules.</span>
+                </a>
+                <a class="doc-card" href="https://github.com/calvinnwq/artshelf/blob/main/SPEC.md">
+                  <strong>Read the spec</strong>
+                  <span>Understand the ledger-first contract and v1 non-goals.</span>
+                </a>
+                <a class="doc-card" href="https://github.com/calvinnwq/artshelf">
+                  <strong>Open the repo</strong>
+                  <span>Source, tests, release automation, and the portable agent skill.</span>
+                </a>
+              </div>
+            </section>
+
+            <section>
+              <h2>Safety Model</h2>
+              <ul>
+                <li>Ledger-first. Artshelf only cleans entries that were registered intentionally.</li>
+                <li>Dry-run before mutation. Plans are written before execution.</li>
+                <li>No daemon or auto-execute path. Only a human-run command can mutate files.</li>
+                <li>No global execute. <code>--all</code> is read-only or dry-run reporting only; trash purge refuses it.</li>
+                <li>No fresh-plan-then-execute shortcut. Execute only a reviewed plan id.</li>
+                <li>Handled records stop appearing in future due and cleanup dry-run output.</li>
+                <li>Cleanup refuses delete actions; physical trash purge needs its own reviewed plan.</li>
+              </ul>
+              <div class="note">
+                Artshelf is an early v1 MVP. Source install and live dogfooding come before npm publishing.
+              </div>
+            </section>
+          </article>
+        </main>
+
+        <footer class="site-footer">
+          <div class="wrap">Artshelf docs · MIT · <a href="https://github.com/calvinnwq/artshelf">GitHub</a></div>
+        </footer>
+      </div>
+    </div>
+  </body>
+</html>