artshelf 0.6.0 → 0.8.0

package/dist/src/cli.js

@@ -1,8 +1,14 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
 import { appendPreparedRecord, createCleanupPlan, createTrashPurgePlan, dueEntries, executeCleanupPlan, executeTrashPurgePlan, filterRecordsByStatus, findRecords, getRecord, listTrashedRecords, normalizeLedgerPath, prepareRecord, previewCleanupPlan, readLedger, resolveRecord, validateLedger } from "./ledger.js";
 import { listRegisteredLedgers, normalizeRegistryPath, registerLedger } from "./registry.js";
 const VERSION = readPackageVersion();
+const PACKAGE_NAME = "artshelf";
+const NPM_REGISTRY_URL = process.env.ARTSHELF_NPM_REGISTRY_URL ?? `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+const UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
 const BOOLEAN_FLAGS = new Set(["all", "json", "manual-review", "dry-run", "execute", "help", "version", "plain"]);
 const VALUE_FLAGS = new Set([
     "cleanup",
@@ -29,56 +35,83 @@ function readPackageVersion() {
     }
     return packageJson.version;
 }
-function main(argv) {
+async function main(argv) {
     try {
         const parsed = parseArgs(argv);
+        let status = 0;
+        let shouldCheckForUpdate = true;
         if (parsed.command === "--version" || parsed.command === "-v" || boolFlag(parsed, "version")) {
             process.stdout.write(`artshelf ${VERSION}\n`);
-            return 0;
+            return maybeNotifyUpdateAndReturn(0, parsed);
         }
         if (parsed.command === "help" || parsed.command === "--help" || parsed.command === "-h" || boolFlag(parsed, "help")) {
             printHelp(parsed.command === "help" ? parsed.positionals[0] : parsed.command);
-            return 0;
+            return maybeNotifyUpdateAndReturn(0, parsed);
         }
         switch (parsed.command) {
             case "put":
-                return handlePut(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handlePut(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "ledgers":
-                return handleLedgers(parsed, boolFlag(parsed, "json"));
+                status = handleLedgers(parsed, boolFlag(parsed, "json"));
+                break;
             case "list":
-                return handleList(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleList(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "find":
-                return handleFind(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleFind(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "get":
-                return handleGet(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleGet(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "due":
-                return handleDue(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleDue(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "validate":
-                return handleValidate(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleValidate(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "cleanup":
-                return handleCleanup(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleCleanup(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "trash":
-                return handleTrash(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleTrash(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "review":
-                return handleReview(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleReview(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "doctor":
-                return handleDoctor(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleDoctor(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "status":
-                return handleStatus(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleStatus(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
             case "resolve":
-                return handleResolve(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                status = handleResolve(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+                break;
+            case "update":
+                shouldCheckForUpdate = false;
+                status = await handleUpdate(parsed, boolFlag(parsed, "json"));
+                break;
             case undefined:
                 printHelp();
-                return 0;
+                status = 0;
+                break;
             default:
                 throw new Error(`Unknown command: ${parsed.command}`);
         }
+        if (!shouldCheckForUpdate)
+            return status;
+        return maybeNotifyUpdateAndReturn(status, parsed);
     }
     catch (error) {
         process.stderr.write(`artshelf: ${error.message}\nRun \`artshelf help\` for usage.\n`);
         return 1;
     }
 }
+async function maybeNotifyUpdateAndReturn(status, parsed) {
+    await maybeNotifyAvailableUpdate(parsed);
+    return status;
+}
 function handlePut(parsed, ledgerPath, json) {
     const path = parsed.positionals[0];
     if (!path)
@@ -726,6 +759,189 @@ function printStatusSingle(ledger) {
             process.stdout.write(`error: ${message}\n`);
     }
 }
+async function handleUpdate(parsed, json) {
+    if (parsed.positionals.length > 0)
+        throw new Error("update does not accept positional arguments");
+    const info = await getUpdateInfo({ force: true });
+    if (!info)
+        throw new Error("Could not check npm for the latest Artshelf version");
+    if (!info.updateAvailable) {
+        if (json)
+            return printJson({ ok: true, updated: false, current: info.current, latest: info.latest });
+        process.stdout.write(`artshelf is already up to date: v${info.current}\n`);
+        return 0;
+    }
+    if (process.env.ARTSHELF_UPDATE_DRY_RUN === "1") {
+        if (json) {
+            return printJson({
+                ok: true,
+                updated: false,
+                dryRun: true,
+                current: info.current,
+                latest: info.latest,
+                command: ["npm", "install", "-g", `${PACKAGE_NAME}@latest`]
+            });
+        }
+        process.stdout.write(`A new version of artshelf is available: v${info.current} -> v${info.latest}\n`);
+        process.stdout.write(`Dry run: would run "npm install -g ${PACKAGE_NAME}@latest"\n`);
+        return 0;
+    }
+    if (!json) {
+        process.stdout.write(`A new version of artshelf is available: v${info.current} -> v${info.latest}\n`);
+        process.stdout.write(`Updating with "npm install -g ${PACKAGE_NAME}@latest"...\n`);
+    }
+    const result = json
+        ? spawnSync("npm", ["install", "-g", `${PACKAGE_NAME}@latest`], { encoding: "utf8" })
+        : spawnSync("npm", ["install", "-g", `${PACKAGE_NAME}@latest`], { stdio: "inherit" });
+    const status = result.status ?? 1;
+    const spawnError = result.error instanceof Error ? result.error.message : "";
+    if (json) {
+        const stderr = typeof result.stderr === "string" ? result.stderr : "";
+        printJson({
+            ok: status === 0,
+            updated: status === 0,
+            current: info.current,
+            latest: info.latest,
+            stdout: typeof result.stdout === "string" ? result.stdout : "",
+            stderr: appendOutputMessage(stderr, spawnError)
+        });
+        return status;
+    }
+    if (spawnError)
+        process.stderr.write(`Update failed: ${spawnError}\n`);
+    if (status === 0)
+        process.stdout.write(`artshelf updated to v${info.latest}\n`);
+    return status;
+}
+function appendOutputMessage(output, message) {
+    if (!message)
+        return output;
+    if (!output)
+        return message;
+    return `${output}${output.endsWith("\n") ? "" : "\n"}${message}`;
+}
+async function maybeNotifyAvailableUpdate(parsed) {
+    if (process.env.ARTSHELF_NO_UPDATE_CHECK === "1")
+        return;
+    if (parsed.command === "update")
+        return;
+    const info = await getUpdateInfo({ force: false });
+    if (!info?.updateAvailable)
+        return;
+    process.stderr.write(`A new version of artshelf is available: v${info.current} -> v${info.latest}\n`);
+    process.stderr.write(`Run "artshelf update" to update npm installs\n`);
+}
+async function getUpdateInfo(options) {
+    const latest = await getLatestVersion(options);
+    if (!latest)
+        return null;
+    return {
+        current: VERSION,
+        latest,
+        updateAvailable: compareVersions(latest, VERSION) > 0
+    };
+}
+async function getLatestVersion(options) {
+    const override = process.env.ARTSHELF_LATEST_VERSION;
+    if (override)
+        return normalizeVersion(override);
+    if (!options.force) {
+        const cached = readUpdateCache();
+        if (cached)
+            return cached.latest;
+    }
+    const latest = await fetchLatestNpmVersion();
+    writeUpdateCache(latest);
+    return latest;
+}
+function readUpdateCache() {
+    const ttl = Number(process.env.ARTSHELF_UPDATE_CHECK_TTL_MS ?? UPDATE_CHECK_TTL_MS);
+    if (ttl < 0)
+        return null;
+    const cachePath = updateCachePath();
+    if (!existsSync(cachePath))
+        return null;
+    try {
+        const cache = JSON.parse(readFileSync(cachePath, "utf8"));
+        if (cache.latest !== null && typeof cache.latest !== "string")
+            return null;
+        if (typeof cache.checkedAt !== "number")
+            return null;
+        if (Date.now() - cache.checkedAt > ttl)
+            return null;
+        return { latest: cache.latest === null ? null : normalizeVersion(cache.latest) };
+    }
+    catch {
+        return null;
+    }
+}
+function writeUpdateCache(latest) {
+    try {
+        const cachePath = updateCachePath();
+        const dir = dirname(cachePath);
+        if (dir) {
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(cachePath, `${JSON.stringify({ latest, checkedAt: Date.now() }, null, 2)}\n`);
+        }
+    }
+    catch {
+        // Update checks should never affect normal CLI behavior.
+    }
+}
+async function fetchLatestNpmVersion() {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 750);
+    try {
+        const response = await fetch(NPM_REGISTRY_URL, {
+            signal: controller.signal,
+            headers: { accept: "application/json", "user-agent": `artshelf/${VERSION}` }
+        });
+        if (!response.ok)
+            return null;
+        const body = await response.json();
+        if (!body || typeof body !== "object" || typeof body.version !== "string")
+            return null;
+        return normalizeVersion(body.version);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function updateCachePath() {
+    return process.env.ARTSHELF_UPDATE_CACHE ?? join(homedir(), ".artshelf", "update-check.json");
+}
+function normalizeVersion(version) {
+    return version.trim().replace(/^v/i, "");
+}
+function compareVersions(left, right) {
+    const a = parseVersion(left);
+    const b = parseVersion(right);
+    for (let index = 0; index < Math.max(a.numbers.length, b.numbers.length); index += 1) {
+        const diff = (a.numbers[index] ?? 0) - (b.numbers[index] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    if (a.prerelease === b.prerelease)
+        return 0;
+    if (!a.prerelease)
+        return 1;
+    if (!b.prerelease)
+        return -1;
+    return a.prerelease.localeCompare(b.prerelease);
+}
+function parseVersion(version) {
+    const [main = "", prerelease = ""] = normalizeVersion(version).split("-", 2);
+    return {
+        numbers: main.split(".").map((part) => {
+            const parsed = Number.parseInt(part, 10);
+            return Number.isFinite(parsed) ? parsed : 0;
+        }),
+        prerelease
+    };
+}
 function parseArgs(argv) {
     const [command, ...rest] = argv;
     const flags = new Map();
@@ -1107,6 +1323,21 @@ Human output is short enough to paste into a chat; \`artshelf status --all --jso
 is suitable for cron and reporting. Status is read-only: it never creates plans
 or receipts and never mutates records. A healthy selected ledger exits 0; with
 --all, a broken registry or any stale or invalid registered ledger exits non-zero.
+`);
+        return;
+    }
+    if (command === "update") {
+        process.stdout.write(`Usage:
+  artshelf update [--json]
+
+Update checks compare the current CLI version with the latest published npm
+version. Normal commands may print a non-blocking update notice to stderr when a
+newer version is available. Run update to upgrade npm global installs only:
+
+  npm install -g artshelf@latest
+
+pnpm global installs should update with pnpm add -g artshelf@latest; source
+installs should update by pulling, rebuilding, and linking the checkout.
 `);
         return;
     }
@@ -1132,6 +1363,7 @@ Usage:
   artshelf doctor [--json]
   artshelf status [--json]
   artshelf status --all [--json]
+  artshelf update [--json]
   artshelf cleanup --dry-run [--json]
   artshelf cleanup --dry-run --all [--json]
   artshelf cleanup --execute --plan-id <id> [--json]
@@ -1154,4 +1386,11 @@ Examples:
   artshelf cleanup --execute --plan-id plan_20260601_120000_ab12
 `);
 }
-process.exitCode = main(process.argv.slice(2));
+main(process.argv.slice(2))
+    .then((status) => {
+    process.exitCode = status;
+})
+    .catch((error) => {
+    process.stderr.write(`artshelf: ${error.message}\nRun \`artshelf help\` for usage.\n`);
+    process.exitCode = 1;
+});

package/docs/agent-clean.html

@@ -0,0 +1,108 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Clean · Agent usage · Artshelf</title>
+    <meta name="description" content="How agents clean Artshelf artifacts after exact human approval.">
+    <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>
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <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">
+    <link rel="stylesheet" href="site.css">
+    <script src="site.js" defer></script>
+  </head>
+  <body data-page="agent-clean.html">
+    <a class="skip" href="#content">Skip to content</a>
+    <header class="masthead">
+      <div class="masthead-inner">
+        <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>
+        <a class="brand" href="index.html">Artshelf<span class="brand-tag">docs</span></a>
+        <button class="search-btn" type="button" data-search-open><span>Search docs</span><kbd>/</kbd></button>
+        <div class="masthead-tools">
+          <a class="gh" href="https://github.com/calvinnwq/artshelf">GitHub</a>
+          <button class="theme-btn" type="button" data-theme-toggle aria-label="Toggle color theme" aria-pressed="false">
+            <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>
+            <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>
+          </button>
+        </div>
+      </div>
+    </header>
+
+    <div class="frame">
+      <nav id="sidebar" class="sidebar" aria-label="Documentation"></nav>
+
+      <main id="content" class="article-col">
+        <article>
+          <p class="kicker"><span class="n">4.4</span>Agents · Clean</p>
+          <h1>Execute only what was reviewed and approved.</h1>
+          <p class="lede">
+            Clean is meant to be boring. The human approves one plan, the agent runs
+            exactly that plan, writes a receipt, and checks that the next review
+            comes back quiet.
+          </p>
+
+          <section>
+            <h2>Cleanup boundary</h2>
+            <ul class="boundary-list">
+              <li>
+                <span class="stamp readonly">Allowed freely</span>
+                <span><code>validate</code>, <code>review</code>, and <code>cleanup --dry-run</code>.</span>
+              </li>
+              <li>
+                <span class="stamp approval">Needs approval</span>
+                <span><code>cleanup --execute --plan-id</code> for one reviewed plan.</span>
+              </li>
+              <li>
+                <span class="stamp refused">Refused</span>
+                <span>No daemon, no auto-execute, no global execute, no fresh-plan-then-execute.</span>
+              </li>
+            </ul>
+            <pre><code><span class="c"># free to run any time: read-only checks and plan previews</span>
+artshelf validate --json
+artshelf review --all --json
+artshelf cleanup --dry-run --json
+artshelf cleanup --dry-run --all --json
+
+<span class="c"># only after a human approves this exact plan id</span>
+artshelf cleanup --execute --plan-id &lt;id&gt;</code></pre>
+            <div class="callout" data-kind="boundary">
+              <span class="callout-label">Hard boundary</span>
+              <p>
+                Cleanup execution needs explicit human approval for the reviewed plan id.
+                <code>cleanup=trash</code> quarantines files into Artshelf trash — recoverable,
+                not deleted — and <code>cleanup=delete</code> stays refused. Emptying the trash
+                for good is a separate stage: see <a href="agent-purge.html">Purge</a>.
+              </p>
+            </div>
+          </section>
+
+          <section>
+            <h2>Resolve confirmed records</h2>
+            <p>Resolve only updates the ledger; it does not move or delete files.</p>
+            <pre><code><span class="c"># mark a record handled without touching the file</span>
+artshelf resolve &lt;id&gt; --status resolved --reason &lt;text&gt;</code></pre>
+            <p>The approval wording for resolving a batch of missing records:</p>
+            <pre><code>approve artshelf resolve missing ledger &lt;ledger-path&gt; ids &lt;id...&gt;</code></pre>
+          </section>
+
+          <section>
+            <h2>Verify quiet</h2>
+            <p>After cleanup execute or resolve, verify with <code>artshelf review --all --json</code>.</p>
+            <p>
+              Execution writes a receipt and updates touched ledger records to
+              <code>trashed</code>, <code>review-required</code>, or
+              <code>cleanup-refused</code>. Generated plans and receipts are recorded as
+              <code>owner=artshelf</code> artifacts.
+            </p>
+          </section>
+        </article>
+        <footer class="pager" id="pager"></footer>
+      </main>
+
+      <aside class="toc-col"><p class="toc-title">On this page</p><nav id="toc" aria-label="On this page"></nav></aside>
+    </div>
+
+    <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>
+  </body>
+</html>

package/docs/agent-create.html

@@ -0,0 +1,98 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Create · Agent usage · Artshelf</title>
+    <meta name="description" content="How agents create Artshelf records while artifact intent is fresh.">
+    <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>
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <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">
+    <link rel="stylesheet" href="site.css">
+    <script src="site.js" defer></script>
+  </head>
+  <body data-page="agent-create.html">
+    <a class="skip" href="#content">Skip to content</a>
+    <header class="masthead">
+      <div class="masthead-inner">
+        <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>
+        <a class="brand" href="index.html">Artshelf<span class="brand-tag">docs</span></a>
+        <button class="search-btn" type="button" data-search-open><span>Search docs</span><kbd>/</kbd></button>
+        <div class="masthead-tools">
+          <a class="gh" href="https://github.com/calvinnwq/artshelf">GitHub</a>
+          <button class="theme-btn" type="button" data-theme-toggle aria-label="Toggle color theme" aria-pressed="false">
+            <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>
+            <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>
+          </button>
+        </div>
+      </div>
+    </header>
+
+    <div class="frame">
+      <nav id="sidebar" class="sidebar" aria-label="Documentation"></nav>
+
+      <main id="content" class="article-col">
+        <article>
+          <p class="kicker"><span class="n">4.1</span>Agents · Create</p>
+          <h1>Register artifacts while intent is fresh.</h1>
+          <p class="lede">
+            Create is one question: should this non-source artifact outlive the turn?
+            If yes, put it on the shelf while the reason is still obvious.
+          </p>
+
+          <section>
+            <h2>Completion gate</h2>
+            <p>
+              Before any final, status, handoff, or done report, check for files the agent
+              created, copied, exported, quarantined, backed up, or preserved.
+            </p>
+            <ul>
+              <li><strong>Register eligible artifact paths.</strong> Anything non-source that may outlive the command needs a record.</li>
+              <li><strong>State every skip reason.</strong> Source, cache, regeneratable, secret-bearing, or owned elsewhere.</li>
+            </ul>
+            <div class="callout" data-kind="boundary">
+              <span class="callout-label">Hard boundary</span>
+              <p>Do not call work done while known eligible artifacts are neither registered nor explicitly skipped.</p>
+              <p>Do not invent Artshelf entries after the fact just to make a handoff look tidy.</p>
+            </div>
+          </section>
+
+          <section>
+            <h2>Register these</h2>
+            <dl class="def-rows">
+              <div><dt>backup</dt><dd>rollback copy or snapshot</dd></div>
+              <div><dt>evidence</dt><dd>report, log, smoke output</dd></div>
+              <div><dt>quarantine</dt><dd>copied aside for review</dd></div>
+              <div><dt>run</dt><dd>artifact needed to resume a long task</dd></div>
+            </dl>
+          </section>
+
+          <section>
+            <h2>Lookup before put</h2>
+            <pre><code><span class="c"># is this path already on the shelf?</span>
+artshelf find --path &lt;path&gt; --owner &lt;agent-or-runtime&gt; --label &lt;task-or-run-id&gt; --json
+
+<span class="c"># inspect one record by its Artshelf id</span>
+artshelf get &lt;id&gt; --json</code></pre>
+            <p>
+              If <code>find</code> returns a record, reuse that Artshelf id. If it returns
+              no entries, call <code>artshelf put --json</code> and report the new id.
+            </p>
+          </section>
+
+          <section>
+            <h2>Report the id</h2>
+            <p>Use a deterministic Artshelf footnote wherever restart or cleanup context will be read.</p>
+            <pre><code>Artshelf footnote: registered &lt;artifact-path&gt; as &lt;artshelf-id&gt;; reason: &lt;short reason&gt;; due: &lt;YYYY-MM-DD|manual-review&gt;; cleanup=&lt;cleanup-mode&gt;.</code></pre>
+          </section>
+        </article>
+        <footer class="pager" id="pager"></footer>
+      </main>
+
+      <aside class="toc-col"><p class="toc-title">On this page</p><nav id="toc" aria-label="On this page"></nav></aside>
+    </div>
+
+    <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>
+  </body>
+</html>