artshelf 0.6.0 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +21 -3
- package/README.md +146 -219
- package/SPEC.md +56 -6
- package/dist/src/cli.js +258 -19
- package/docs/agent-clean.html +108 -0
- package/docs/agent-create.html +98 -0
- package/docs/agent-monitor.html +151 -0
- package/docs/agent-purge.html +111 -0
- package/docs/agent-review.html +120 -0
- package/docs/agent-usage.html +114 -402
- package/docs/agent-usage.md +52 -474
- package/docs/index.html +165 -152
- package/docs/install.html +214 -110
- package/docs/quickstart.html +105 -106
- package/docs/reference.html +239 -164
- package/docs/site.css +675 -490
- package/docs/site.js +398 -0
- package/package.json +1 -1
- package/skills/artshelf/SKILL.md +133 -333
- package/skills/artshelf/scripts/render-review-report.mjs +160 -0
- package/docs/theme.js +0 -42
package/docs/agent-usage.html
CHANGED
|
@@ -3,412 +3,124 @@
|
|
|
3
3
|
<head>
|
|
4
4
|
<meta charset="utf-8">
|
|
5
5
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
6
|
-
<title>
|
|
7
|
-
<meta name="description" content="How agents
|
|
6
|
+
<title>Agent usage · Artshelf</title>
|
|
7
|
+
<meta name="description" content="How agents use Artshelf safely: Create, Monitor, Review, Clean, Purge.">
|
|
8
|
+
<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>
|
|
9
|
+
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
10
|
+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
11
|
+
<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">
|
|
8
12
|
<link rel="stylesheet" href="site.css">
|
|
9
|
-
<script src="
|
|
13
|
+
<script src="site.js" defer></script>
|
|
10
14
|
</head>
|
|
11
|
-
<body>
|
|
12
|
-
<
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
<button class="
|
|
16
|
-
<
|
|
17
|
-
<
|
|
18
|
-
|
|
19
|
-
<a href="
|
|
20
|
-
<
|
|
21
|
-
|
|
15
|
+
<body data-page="agent-usage.html">
|
|
16
|
+
<a class="skip" href="#content">Skip to content</a>
|
|
17
|
+
<header class="masthead">
|
|
18
|
+
<div class="masthead-inner">
|
|
19
|
+
<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>
|
|
20
|
+
<a class="brand" href="index.html">Artshelf<span class="brand-tag">docs</span></a>
|
|
21
|
+
<button class="search-btn" type="button" data-search-open><span>Search docs</span><kbd>/</kbd></button>
|
|
22
|
+
<div class="masthead-tools">
|
|
23
|
+
<a class="gh" href="https://github.com/calvinnwq/artshelf">GitHub</a>
|
|
24
|
+
<button class="theme-btn" type="button" data-theme-toggle aria-label="Toggle color theme" aria-pressed="false">
|
|
25
|
+
<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>
|
|
26
|
+
<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>
|
|
27
|
+
</button>
|
|
22
28
|
</div>
|
|
23
|
-
<div class="nav-section">
|
|
24
|
-
<p class="nav-section-title">Agents</p>
|
|
25
|
-
<a href="agent-usage.html" aria-current="page">Agent usage</a>
|
|
26
|
-
<a href="https://github.com/calvinnwq/artshelf/blob/main/skills/artshelf/SKILL.md">Agent skill</a>
|
|
27
|
-
</div>
|
|
28
|
-
<div class="nav-section">
|
|
29
|
-
<p class="nav-section-title">Reference</p>
|
|
30
|
-
<a href="reference.html">CLI reference</a>
|
|
31
|
-
<a href="https://github.com/calvinnwq/artshelf">GitHub</a>
|
|
32
|
-
</div>
|
|
33
|
-
</div>
|
|
34
|
-
</nav>
|
|
35
|
-
|
|
36
|
-
<div class="docs-content">
|
|
37
|
-
<header class="page-top">
|
|
38
|
-
<div class="wrap">
|
|
39
|
-
<nav class="breadcrumbs" aria-label="Breadcrumbs"><a href="index.html">Docs</a><span>/</span><span>Agent usage</span></nav>
|
|
40
|
-
<div class="hero">
|
|
41
|
-
<div>
|
|
42
|
-
<p class="eyebrow">For local agents and automation</p>
|
|
43
|
-
<h1>Register artifacts while intent is fresh.</h1>
|
|
44
|
-
<p class="lede">
|
|
45
|
-
Agents should use Artshelf when temporary files need accountability, restart
|
|
46
|
-
context, or later human review. Source files and cheap build outputs stay out.
|
|
47
|
-
</p>
|
|
48
|
-
</div>
|
|
49
|
-
<div class="terminal">
|
|
50
|
-
<div class="terminal-head"><span class="dot"></span><span class="dot"></span><span class="dot"></span><span>agent contract</span></div>
|
|
51
|
-
<pre><code>$ artshelf put <path> \
|
|
52
|
-
--reason "<why this exists>" \
|
|
53
|
-
--ttl 3d \
|
|
54
|
-
--kind run-artifact \
|
|
55
|
-
--cleanup review \
|
|
56
|
-
--owner agent \
|
|
57
|
-
--label <project> \
|
|
58
|
-
--json</code></pre>
|
|
59
|
-
</div>
|
|
60
|
-
</div>
|
|
61
|
-
</div>
|
|
62
|
-
</header>
|
|
63
|
-
|
|
64
|
-
<main class="wrap">
|
|
65
|
-
<article>
|
|
66
|
-
<section>
|
|
67
|
-
<h2>Registration Trigger</h2>
|
|
68
|
-
<p>
|
|
69
|
-
Treat Artshelf as a finalization check, not an optional cleanup habit. Before an agent reports a task as done,
|
|
70
|
-
it should check whether the task created, copied,
|
|
71
|
-
exported, quarantined, backed up, or preserved any non-source file or directory
|
|
72
|
-
that may outlive the current command.
|
|
73
|
-
</p>
|
|
74
|
-
<p>
|
|
75
|
-
Register eligible artifacts immediately. If an eligible artifact is skipped,
|
|
76
|
-
state the reason: source-controlled, regeneratable, secret-bearing, already
|
|
77
|
-
tracked by another durable ledger, or explicitly not retained by request.
|
|
78
|
-
</p>
|
|
79
|
-
</section>
|
|
80
|
-
|
|
81
|
-
<section>
|
|
82
|
-
<h2>Install Behavior</h2>
|
|
83
|
-
<p>
|
|
84
|
-
If <code>artshelf</code> is not installed, prefer the package-manager install
|
|
85
|
-
when available and verify the CLI before registering artifacts.
|
|
86
|
-
</p>
|
|
87
|
-
<pre><code>npm install -g artshelf
|
|
88
|
-
artshelf --version
|
|
89
|
-
artshelf doctor</code></pre>
|
|
90
|
-
<pre><code>pnpm add -g artshelf
|
|
91
|
-
artshelf --version
|
|
92
|
-
artshelf doctor</code></pre>
|
|
93
|
-
<p>
|
|
94
|
-
For source installs, ask where the user wants the repo cloned before setup.
|
|
95
|
-
Use the local clone, build, and <code>npm link</code> path. Do not create a
|
|
96
|
-
custom shim.
|
|
97
|
-
</p>
|
|
98
|
-
<pre><code>git clone https://github.com/calvinnwq/artshelf.git "$ARTSHELF_REPO"
|
|
99
|
-
cd "$ARTSHELF_REPO"
|
|
100
|
-
corepack enable
|
|
101
|
-
pnpm install --frozen-lockfile
|
|
102
|
-
pnpm run build
|
|
103
|
-
npm link
|
|
104
|
-
artshelf --version
|
|
105
|
-
artshelf doctor</code></pre>
|
|
106
|
-
</section>
|
|
107
|
-
|
|
108
|
-
<section>
|
|
109
|
-
<h2>Use Artshelf For</h2>
|
|
110
|
-
<div class="grid">
|
|
111
|
-
<div class="card"><h3>Backups</h3><p>Rollback copies, pre-edit snapshots, migration backups, and quarantine folders.</p></div>
|
|
112
|
-
<div class="card"><h3>Evidence</h3><p>Debug output directories, generated reports, logs, and live-smoke artifacts.</p></div>
|
|
113
|
-
<div class="card"><h3>Long runs</h3><p>Workflow artifacts a future agent might need to resume, review, or clean up.</p></div>
|
|
114
|
-
</div>
|
|
115
|
-
</section>
|
|
116
|
-
|
|
117
|
-
<section>
|
|
118
|
-
<h2>Skip Artshelf For</h2>
|
|
119
|
-
<ul>
|
|
120
|
-
<li>Source files that belong in git.</li>
|
|
121
|
-
<li>Build outputs and dependency caches that can be regenerated cheaply.</li>
|
|
122
|
-
<li>Secrets, credential dumps, or private tokens.</li>
|
|
123
|
-
<li>Artifacts already owned by a more specific durable workflow ledger.</li>
|
|
124
|
-
</ul>
|
|
125
|
-
</section>
|
|
126
|
-
|
|
127
|
-
<section>
|
|
128
|
-
<h2>Idempotent Lookup</h2>
|
|
129
|
-
<p>
|
|
130
|
-
Integrations should query the ledger before creating another record for the same
|
|
131
|
-
artifact. <code>find</code> and <code>get</code> are read-only; they never move,
|
|
132
|
-
resolve, or delete files.
|
|
133
|
-
</p>
|
|
134
|
-
<pre><code>artshelf find --path <path> --owner <agent-or-runtime> --label <task-or-run-id> --json
|
|
135
|
-
artshelf get <id> --json</code></pre>
|
|
136
|
-
<p>
|
|
137
|
-
<code>find</code> requires at least one selector. Multiple labels are an all-label
|
|
138
|
-
match. If it returns a record, reuse that Artshelf id; otherwise call
|
|
139
|
-
<code>artshelf put</code> and record the new id.
|
|
140
|
-
</p>
|
|
141
|
-
</section>
|
|
142
|
-
|
|
143
|
-
<section>
|
|
144
|
-
<h2>Ledger Registry</h2>
|
|
145
|
-
<p>
|
|
146
|
-
Artshelf keeps a user-level registry at `~/.artshelf/ledgers.json` so one CLI can
|
|
147
|
-
review all known ledgers without moving project records into one global file.
|
|
148
|
-
<code>put</code> registers the ledger it writes to.
|
|
149
|
-
</p>
|
|
150
|
-
<pre><code>artshelf ledgers add --ledger <repo>/.artshelf/ledger.jsonl --name <project> --scope repo
|
|
151
|
-
artshelf ledgers list --json
|
|
152
|
-
artshelf review --all --json
|
|
153
|
-
artshelf status --all --json
|
|
154
|
-
artshelf find --all --owner <agent-or-runtime> --json
|
|
155
|
-
artshelf trash list --all --json</code></pre>
|
|
156
|
-
<p>
|
|
157
|
-
Renamed installs before <code>0.5.0</code> used <code>.shelf</code> paths. For migration,
|
|
158
|
-
copy the old ledger directories into <code>.artshelf</code>, rewrite registry entries,
|
|
159
|
-
validate the new registry, and keep the <code>.shelf</code> copies until rollback is no
|
|
160
|
-
longer needed.
|
|
161
|
-
</p>
|
|
162
|
-
<p>
|
|
163
|
-
<code>artshelf ledgers list --json</code> validates each registered ledger and reports
|
|
164
|
-
ok/missing/invalid status with entry and warning/error counts, so agents can detect
|
|
165
|
-
stale registry entries without a separate validate pass; add <code>--plain</code> for a
|
|
166
|
-
fast listing that skips validation. <code>artshelf review --all --json</code> returns an
|
|
167
|
-
aggregate triage summary and the next safe action next to the per-ledger detail.
|
|
168
|
-
</p>
|
|
169
|
-
<p>Use global cleanup dry-run when you want Artshelf to write cleanup plans for registered ledgers with cleanup entries, without moving files.</p>
|
|
170
|
-
<pre><code>artshelf cleanup --dry-run --all --json</code></pre>
|
|
171
|
-
<div class="note">
|
|
172
|
-
<code>--all</code> is for discovery and review. Cleanup execution remains
|
|
173
|
-
ledger-specific and requires a reviewed plan id for that ledger.
|
|
174
|
-
</div>
|
|
175
|
-
<p>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.</p>
|
|
176
|
-
</section>
|
|
177
|
-
|
|
178
|
-
<section>
|
|
179
|
-
<h2>Daily Review Workflow</h2>
|
|
180
|
-
<p>
|
|
181
|
-
Use this flow when a scheduled review, recurring task, or user request reports
|
|
182
|
-
Artshelf cleanup attention.
|
|
183
|
-
</p>
|
|
184
|
-
<ol>
|
|
185
|
-
<li>Register artifacts early during work, or state why an eligible artifact was skipped.</li>
|
|
186
|
-
<li>Review state with read-only commands first: <code>artshelf ledgers list --json</code>, <code>artshelf review --all --json</code>, and <code>artshelf trash list --all --json</code>; for old trash on a selected ledger, run <code>artshelf trash purge --older-than 7d --dry-run --ledger <ledger-path> --json</code>.</li>
|
|
187
|
-
<li>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.</li>
|
|
188
|
-
<li>Classify each candidate as <code>trash-safe</code>, <code>needs-human-review</code>, <code>resolve-candidate</code>, or <code>registry-problem</code>.</li>
|
|
189
|
-
<li>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.</li>
|
|
190
|
-
<li>For trashed records, require a separate reviewed purge plan before physical deletion.</li>
|
|
191
|
-
<li>After approved cleanup execute, trash purge, or resolve, verify quiet with <code>artshelf review --all --json</code>, plus <code>artshelf trash list --ledger <ledger-path> --json</code> and purge receipt evidence after purge, or explain what remains.</li>
|
|
192
|
-
</ol>
|
|
193
|
-
<pre><code>artshelf trash list --ledger <ledger-path>
|
|
194
|
-
artshelf trash purge --older-than 7d --dry-run --ledger <ledger-path> --json
|
|
195
|
-
artshelf trash purge --execute --plan-id <purge-plan-id> --ledger <ledger-path> --json</code></pre>
|
|
196
|
-
<h3>Review Plan Report Schema</h3>
|
|
197
|
-
<p>
|
|
198
|
-
When a dry-run creates or reuses a cleanup or trash purge plan, surface the
|
|
199
|
-
plan in a compact human-readable report. The report should let the user
|
|
200
|
-
approve, ask for changes, or request alternatives without opening the plan
|
|
201
|
-
file.
|
|
202
|
-
</p>
|
|
203
|
-
<p>
|
|
204
|
-
For deterministic agent integrations, construct an
|
|
205
|
-
<code>ArtshelfReviewReport</code> JSON object first, then render it to text.
|
|
206
|
-
Use <a href="schemas/artshelf-review-report.schema.json">schemas/artshelf-review-report.schema.json</a>
|
|
207
|
-
for the packet shape and
|
|
208
|
-
<a href="examples/artshelf-review-report.json">examples/artshelf-review-report.json</a>
|
|
209
|
-
as the canonical example. The schema locks report structure; the CLI output
|
|
210
|
-
and approval rules still define cleanup safety.
|
|
211
|
-
</p>
|
|
212
|
-
<p>
|
|
213
|
-
Render the JSON packet as a compact decision card using
|
|
214
|
-
<code>decisionSummary</code> and <code>decisionGroups</code>. Lead with
|
|
215
|
-
counts, then show exactly what is ready for approval and what needs review
|
|
216
|
-
first. Emojis are encouraged when the host renders them well because they
|
|
217
|
-
make review groups scannable; omit them only for plain-text or
|
|
218
|
-
accessibility-constrained surfaces.
|
|
219
|
-
</p>
|
|
220
|
-
<pre><code>Artshelf daily review
|
|
221
|
-
Status: <ok|attention needed>; registry <ok|attention>
|
|
222
|
-
|
|
223
|
-
✅ Ready for approval: <n>
|
|
224
|
-
👀 Needs review first: <n>
|
|
225
|
-
⚠️ Blocked: <n>
|
|
226
|
-
|
|
227
|
-
Recommendation
|
|
228
|
-
<one short sentence with the next safest action>.
|
|
229
|
-
|
|
230
|
-
Ready for approval
|
|
231
|
-
1. <short item label>
|
|
232
|
-
Why: <short reason>
|
|
233
|
-
Action: <what approval will do>
|
|
234
|
-
approve artshelf cleanup ledger <ledger-path> plan <plan-id>
|
|
235
|
-
|
|
236
|
-
2. <short item label>
|
|
237
|
-
Why: <short reason>
|
|
238
|
-
Action: <ledger-only update, no file changes>
|
|
239
|
-
approve artshelf resolve missing ledger <ledger-path> ids <id...>
|
|
240
|
-
|
|
241
|
-
Needs review first
|
|
242
|
-
1. <short item label>
|
|
243
|
-
Why: <short reason>
|
|
244
|
-
Suggested next step: inspect path, then choose keep, change retention, resolve, or clean up later
|
|
245
|
-
Path: <path>
|
|
246
|
-
|
|
247
|
-
Blocked
|
|
248
|
-
<none, or the registry/refused/missing-path blocker and next repair step>
|
|
249
|
-
|
|
250
|
-
Safety
|
|
251
|
-
Dry-run only. No execute, resolve, or delete ran.</code></pre>
|
|
252
|
-
<p>
|
|
253
|
-
Keep the full <code>ArtshelfReviewReport</code> JSON as the audit packet
|
|
254
|
-
and include it as an attachment, linked file, or expandable detail when the
|
|
255
|
-
host supports that. Do not paste the whole packet into chat unless the user
|
|
256
|
-
asks for it. For long plans, show only the first 3 to 5 decisions under
|
|
257
|
-
each visible group, then state the hidden count by group and classification.
|
|
258
|
-
Do not hide refused, registry-problem, or missing-path items.
|
|
259
|
-
</p>
|
|
260
|
-
<p>
|
|
261
|
-
If the host supports buttons, menus, or other interactive controls, they
|
|
262
|
-
should emit exact text commands such as the approval targets below. Always
|
|
263
|
-
include the exact approval target in the message body as a fallback for
|
|
264
|
-
clients where those controls do not render.
|
|
265
|
-
</p>
|
|
266
|
-
<pre><code>approve artshelf cleanup ledger <ledger-path> plan <plan-id>
|
|
267
|
-
approve artshelf trash purge ledger <ledger-path> plan <purge-plan-id>
|
|
268
|
-
approve artshelf resolve missing ledger <ledger-path> ids <id...></code></pre>
|
|
269
|
-
<div class="note">
|
|
270
|
-
Never execute from a read-only preview id. Never generate a fresh plan and execute
|
|
271
|
-
it in the same step. <code>trash</code> moves artifacts into Artshelf trash; physical
|
|
272
|
-
delete requires a separate reviewed trash purge plan.
|
|
273
|
-
</div>
|
|
274
|
-
</section>
|
|
275
|
-
|
|
276
|
-
<section>
|
|
277
|
-
<h2>Report The ID</h2>
|
|
278
|
-
<pre><code>Artshelf artifacts:
|
|
279
|
-
- shf_20260601_182800_ab12: /tmp/parser-output, debug evidence for issue-123,
|
|
280
|
-
retain until 2026-06-04, cleanup=review</code></pre>
|
|
281
|
-
<p>
|
|
282
|
-
Put the id in handoffs, PR comments, issue comments, memory, or task run
|
|
283
|
-
summaries when the artifact matters for restart.
|
|
284
|
-
</p>
|
|
285
|
-
<p>
|
|
286
|
-
If there are no eligible artifacts, say nothing. If eligible artifacts were
|
|
287
|
-
skipped instead of registered, include the brief skip reason from the
|
|
288
|
-
completion checklist.
|
|
289
|
-
</p>
|
|
290
|
-
<p>
|
|
291
|
-
When <code>artshelf put --json</code> succeeds, include a deterministic Artshelf
|
|
292
|
-
footnote in the same handoff, status, final response, or run summary that
|
|
293
|
-
mentions the artifact.
|
|
294
|
-
</p>
|
|
295
|
-
<pre><code>Artshelf footnote: registered <artifact-path> as <artshelf-id>; reason: <short reason>; due: <YYYY-MM-DD|manual-review>; cleanup=<cleanup-mode>.</code></pre>
|
|
296
|
-
</section>
|
|
297
|
-
|
|
298
|
-
<section>
|
|
299
|
-
<h2>Cleanup Boundary</h2>
|
|
300
|
-
<pre><code>artshelf validate --json
|
|
301
|
-
artshelf validate --all --json
|
|
302
|
-
artshelf due --json
|
|
303
|
-
artshelf due --all --json
|
|
304
|
-
artshelf review --all --json</code></pre>
|
|
305
|
-
<p>Cleanup dry-run is safe to run. It writes plan files for later review only when there are executable cleanup entries; no-op dry-runs report <code>not-created</code> and write no plan file. Matching dry-runs reuse the existing plan id and refresh the plan timestamp.</p>
|
|
306
|
-
<pre><code>artshelf cleanup --dry-run --json
|
|
307
|
-
artshelf cleanup --dry-run --all --json</code></pre>
|
|
308
|
-
<pre><code>artshelf cleanup --execute --plan-id <id></code></pre>
|
|
309
|
-
<pre><code>artshelf trash list --ledger <ledger-path> --json
|
|
310
|
-
artshelf trash purge --older-than 7d --dry-run --ledger <ledger-path> --json
|
|
311
|
-
artshelf trash purge --execute --plan-id <purge-plan-id> --ledger <ledger-path> --json</code></pre>
|
|
312
|
-
<div class="note">
|
|
313
|
-
Execution is approval-only: no daemon, no auto-execute, no global execute, and no
|
|
314
|
-
fresh-plan-then-execute shortcut. Cleanup execution needs explicit human approval
|
|
315
|
-
for the reviewed plan id. Trash list and purge dry-run are review steps; trash
|
|
316
|
-
purge execution needs separate approval naming the ledger and reviewed purge plan
|
|
317
|
-
id. Execution writes a receipt and updates touched ledger records to `trashed`,
|
|
318
|
-
`review-required`, or `cleanup-refused`. <code>cleanup=delete</code> stays refused
|
|
319
|
-
instead of silently deleting files; physical deletion requires a separate reviewed
|
|
320
|
-
trash purge plan. Artshelf records generated plans and receipts as `owner=artshelf`
|
|
321
|
-
artifacts.
|
|
322
|
-
</div>
|
|
323
|
-
<p>
|
|
324
|
-
Agents may mark a ledger record manually resolved when the user confirms the
|
|
325
|
-
artifact was inspected, is already missing, or is no longer needed.
|
|
326
|
-
</p>
|
|
327
|
-
<pre><code>artshelf resolve <id> --status resolved --reason <text></code></pre>
|
|
328
|
-
<p>
|
|
329
|
-
Use a specific reason. <code>resolve</code> only updates the ledger; it does not
|
|
330
|
-
move or delete files. For batches of missing-path records, ask for approval that
|
|
331
|
-
names the exact ledger and ids.
|
|
332
|
-
</p>
|
|
333
|
-
<pre><code>approve artshelf resolve missing ledger <ledger-path> ids <id...></code></pre>
|
|
334
|
-
<p>
|
|
335
|
-
After resolution, verify with <code>artshelf review --all --json</code> and report
|
|
336
|
-
whether the review is quiet or what remains. Resolved records stop reappearing
|
|
337
|
-
in future due and dry-run cleanup output while remaining visible through
|
|
338
|
-
<code>artshelf list --status resolved</code>.
|
|
339
|
-
</p>
|
|
340
|
-
</section>
|
|
341
|
-
|
|
342
|
-
<section>
|
|
343
|
-
<h2>Scheduled Review</h2>
|
|
344
|
-
<p>
|
|
345
|
-
Agents may schedule routine Artshelf checks for stale artifacts through their host
|
|
346
|
-
runtime, such as an agent cron, CI job, or recurring task. Keep scheduled jobs
|
|
347
|
-
non-destructive.
|
|
348
|
-
</p>
|
|
349
|
-
<pre><code>artshelf validate --json
|
|
350
|
-
artshelf validate --all --json
|
|
351
|
-
artshelf due --json
|
|
352
|
-
artshelf due --all --json
|
|
353
|
-
artshelf review --all --json</code></pre>
|
|
354
|
-
<p>
|
|
355
|
-
Read-only health and dashboard checks are also safe to schedule. Run
|
|
356
|
-
<code>artshelf review --all --json</code> for aggregate triage (<code>summary</code>
|
|
357
|
-
and <code>nextAction</code>), <code>artshelf doctor --json</code> to catch a broken
|
|
358
|
-
or stale registry before relying on cleanup planning, and
|
|
359
|
-
<code>artshelf status --all --json</code> for a compact cron summary.
|
|
360
|
-
</p>
|
|
361
|
-
<pre><code>artshelf doctor --json
|
|
362
|
-
artshelf status --all --json</code></pre>
|
|
363
|
-
<p>
|
|
364
|
-
Scheduled cleanup and trash purge dry-runs may write plan files for later review
|
|
365
|
-
when entries exist, but must not move or delete files. Matching cleanup dry-runs
|
|
366
|
-
reuse the existing plan id and refresh the plan timestamp.
|
|
367
|
-
</p>
|
|
368
|
-
<pre><code>artshelf cleanup --dry-run --json
|
|
369
|
-
artshelf cleanup --dry-run --all --json
|
|
370
|
-
artshelf trash list --ledger <ledger-path> --json
|
|
371
|
-
artshelf trash list --all --json
|
|
372
|
-
artshelf trash purge --older-than 7d --dry-run --ledger <ledger-path> --json</code></pre>
|
|
373
|
-
<p>
|
|
374
|
-
Reports should include the ledger path, due/manual-review/missing-path counts,
|
|
375
|
-
cleanup dry-run plan id, executable entries, skipped entries, and refused entries.
|
|
376
|
-
Trash reports may use <code>artshelf trash list --all --json</code> to discover
|
|
377
|
-
trashed records across registered ledgers, then include trashed record counts
|
|
378
|
-
and target ages. Run purge dry-runs only for an explicit ledger and report
|
|
379
|
-
any plan id, matching entries, and skipped entries.
|
|
380
|
-
Stay quiet when nothing needs attention unless a regular summary was requested.
|
|
381
|
-
</p>
|
|
382
|
-
<div class="note">
|
|
383
|
-
Use explicit ledger paths for scheduled checks. Do not scan arbitrary filesystem
|
|
384
|
-
locations for ledgers unless the user opted into that discovery scope. Never
|
|
385
|
-
schedule cleanup execution or trash purge execution; scheduled jobs may only
|
|
386
|
-
dry-run and report plans for later human review.
|
|
387
|
-
</div>
|
|
388
|
-
</section>
|
|
389
|
-
|
|
390
|
-
<section>
|
|
391
|
-
<h2>Completion Checklist</h2>
|
|
392
|
-
<ol>
|
|
393
|
-
<li>Did you create, copy, export, quarantine, back up, or preserve any non-source file or directory?</li>
|
|
394
|
-
<li>Will any of those paths outlive this command?</li>
|
|
395
|
-
<li>If yes, did you register them with Artshelf or state why Artshelf is not appropriate?</li>
|
|
396
|
-
</ol>
|
|
397
|
-
<div class="note">Do not call work done while known eligible artifacts are neither registered nor explicitly skipped.</div>
|
|
398
|
-
</section>
|
|
399
|
-
|
|
400
|
-
<section>
|
|
401
|
-
<h2>Portable Skill</h2>
|
|
402
|
-
<p>
|
|
403
|
-
The repo ships a portable skill at
|
|
404
|
-
<a href="https://github.com/calvinnwq/artshelf/blob/main/skills/artshelf/SKILL.md">skills/artshelf/SKILL.md</a>.
|
|
405
|
-
Agents that support local skills can copy or reference it directly.
|
|
406
|
-
</p>
|
|
407
|
-
</section>
|
|
408
|
-
</article>
|
|
409
|
-
</main>
|
|
410
|
-
<footer class="site-footer"><div class="wrap">Artshelf docs · <a href="reference.html">Next: CLI reference</a></div></footer>
|
|
411
29
|
</div>
|
|
30
|
+
</header>
|
|
31
|
+
|
|
32
|
+
<div class="frame">
|
|
33
|
+
<nav id="sidebar" class="sidebar" aria-label="Documentation"></nav>
|
|
34
|
+
|
|
35
|
+
<main id="content" class="article-col">
|
|
36
|
+
<article>
|
|
37
|
+
<p class="kicker"><span class="n">04</span>Agents · Overview</p>
|
|
38
|
+
<h1>Create, monitor, review, clean, purge.</h1>
|
|
39
|
+
<p class="lede">
|
|
40
|
+
An agent's whole relationship with Artshelf fits in five stages. Each stage
|
|
41
|
+
has its own page with the exact commands; this page is the contract that
|
|
42
|
+
ties them together.
|
|
43
|
+
</p>
|
|
44
|
+
|
|
45
|
+
<section>
|
|
46
|
+
<h2>Workflow summary</h2>
|
|
47
|
+
<div class="ledger">
|
|
48
|
+
<a class="ledger-row" href="agent-create.html">
|
|
49
|
+
<span class="n">4.1</span>
|
|
50
|
+
<span class="stage">Create</span>
|
|
51
|
+
<span class="what"><span class="cmdline">artshelf put <path> --reason <why> --ttl <ttl></span>Register a temporary file while you still remember why it exists, or state the reason for skipping it.</span>
|
|
52
|
+
</a>
|
|
53
|
+
<a class="ledger-row" href="agent-monitor.html">
|
|
54
|
+
<span class="n">4.2</span>
|
|
55
|
+
<span class="stage">Monitor</span>
|
|
56
|
+
<span class="what"><span class="cmdline">artshelf review --all --json</span>Check the shelf on a schedule with read-only commands, and stay quiet when everything is clear.</span>
|
|
57
|
+
</a>
|
|
58
|
+
<a class="ledger-row" href="agent-review.html">
|
|
59
|
+
<span class="n">4.3</span>
|
|
60
|
+
<span class="stage">Review</span>
|
|
61
|
+
<span class="what"><span class="cmdline">artshelf cleanup --dry-run --json</span>Preview cleanup, then turn the output into an <code>ArtshelfReviewReport</code> decision packet a human can approve.</span>
|
|
62
|
+
</a>
|
|
63
|
+
<a class="ledger-row" href="agent-clean.html">
|
|
64
|
+
<span class="n">4.4</span>
|
|
65
|
+
<span class="stage">Clean</span>
|
|
66
|
+
<span class="what"><span class="cmdline">artshelf cleanup --execute --plan-id <id></span>Run the one plan the human approved, resolve confirmed ids, and verify the next review is quiet.</span>
|
|
67
|
+
</a>
|
|
68
|
+
<a class="ledger-row" href="agent-purge.html">
|
|
69
|
+
<span class="n">4.5</span>
|
|
70
|
+
<span class="stage">Purge</span>
|
|
71
|
+
<span class="what"><span class="cmdline">artshelf trash purge --execute --plan-id <id></span>Clear old trash through its own separately reviewed purge plan. Physical deletion never piggybacks on the cleanup plan that trashed the file.</span>
|
|
72
|
+
</a>
|
|
73
|
+
</div>
|
|
74
|
+
<p>
|
|
75
|
+
Clean trashes; Purge deletes. Cleanup quarantines artifacts into Artshelf
|
|
76
|
+
trash, and only a separate, separately reviewed purge plan removes them for
|
|
77
|
+
good — a second approval boundary before destructive deletion.
|
|
78
|
+
</p>
|
|
79
|
+
</section>
|
|
80
|
+
|
|
81
|
+
<section>
|
|
82
|
+
<h2>Operating principles</h2>
|
|
83
|
+
<dl class="def-rows">
|
|
84
|
+
<div><dt>agents remember</dt><dd>use the portable skill so final, status, and handoff turns check artifacts</dd></div>
|
|
85
|
+
<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>
|
|
86
|
+
<div><dt>humans approve</dt><dd>mutation needs exact approval targets: ledger path, reviewed plan id, or record id list</dd></div>
|
|
87
|
+
</dl>
|
|
88
|
+
</section>
|
|
89
|
+
|
|
90
|
+
<section>
|
|
91
|
+
<h2>The mental model</h2>
|
|
92
|
+
<ul class="boundary-list">
|
|
93
|
+
<li>
|
|
94
|
+
<span class="stamp readonly">Green path</span>
|
|
95
|
+
<span>Artifact is due, the dry-run plan is reviewed, and the approval target is exact.</span>
|
|
96
|
+
</li>
|
|
97
|
+
<li>
|
|
98
|
+
<span class="stamp approval">Review first</span>
|
|
99
|
+
<span>Artifact needs a human look, a retention change, or a keep/snooze decision.</span>
|
|
100
|
+
</li>
|
|
101
|
+
<li>
|
|
102
|
+
<span class="stamp refused">Blocked</span>
|
|
103
|
+
<span>Registry is stale, a path is suspicious, or the action would delete without a purge plan.</span>
|
|
104
|
+
</li>
|
|
105
|
+
</ul>
|
|
106
|
+
</section>
|
|
107
|
+
|
|
108
|
+
<section>
|
|
109
|
+
<h2>Portable skill</h2>
|
|
110
|
+
<p>
|
|
111
|
+
The repo ships a portable skill at
|
|
112
|
+
<a href="https://github.com/calvinnwq/artshelf/tree/main/skills/artshelf">skills/artshelf</a>.
|
|
113
|
+
Agents that support local skills can copy or reference the whole directory directly,
|
|
114
|
+
including the bundled report renderer, schema, and example copies.
|
|
115
|
+
</p>
|
|
116
|
+
</section>
|
|
117
|
+
</article>
|
|
118
|
+
<footer class="pager" id="pager"></footer>
|
|
119
|
+
</main>
|
|
120
|
+
|
|
121
|
+
<aside class="toc-col"><p class="toc-title">On this page</p><nav id="toc" aria-label="On this page"></nav></aside>
|
|
412
122
|
</div>
|
|
123
|
+
|
|
124
|
+
<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>
|
|
413
125
|
</body>
|
|
414
126
|
</html>
|