From f976f01b429c1f768f119c8d52655254605d8331 Mon Sep 17 00:00:00 2001 From: Dickson Tsai Date: Fri, 19 Jun 2026 11:51:06 +0000 Subject: [PATCH] project-artifact: document headless limitations and registry enumeration --- plugins/project-artifact/README.md | 3 +++ .../project-artifact/skills/project-artifact/SKILL.md | 10 ++++++++-- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/plugins/project-artifact/README.md b/plugins/project-artifact/README.md index c5144008..d60772f0 100644 --- a/plugins/project-artifact/README.md +++ b/plugins/project-artifact/README.md @@ -36,3 +36,6 @@ sequence so the dependency order is obvious and pulls live PR/CI/review state vi - Artifact URLs are minted by the server. The plugin records yours after the first publish so refreshes land on the same address — bookmark it or add it to your team's hub so others can find it. +- Publishing needs an interactive session: headless (`claude -p`) runs don't have the + Artifact tool, so automation can build and update pages but the publish step happens + interactively. diff --git a/plugins/project-artifact/skills/project-artifact/SKILL.md b/plugins/project-artifact/skills/project-artifact/SKILL.md index 135464f4..44772ed7 100644 --- a/plugins/project-artifact/skills/project-artifact/SKILL.md +++ b/plugins/project-artifact/skills/project-artifact/SKILL.md @@ -25,8 +25,9 @@ project-artifact structure stays domain-neutral. 1. **Resolve the artifact config, then locate the project.** Each project gets a directory at `${CLAUDE_PLUGIN_DATA}/artifacts//` holding `config.md` (see **"The artifact config"** below) and `page.html` (the current render); listing `artifacts/` is the - registry of this skill's artifacts on this machine. If the - user names a project, + registry of this skill's artifacts on this machine (enumerate it with Glob or a + directory read — a shell listing of the data dir can be blocked in restricted + environments). If the user names a project, load that slug; if exactly one config matches the session (its repo is the cwd, or its project came up in conversation), use it; a config that exists means this is a **refresh** — follow **"Refreshing an artifact"** below. No config means a first build: @@ -100,6 +101,11 @@ project-artifact structure stays domain-neutral. session published a newer version), WebFetch the URL to see the current content, reconcile, then publish again. +Headless note: the Artifact tool is not available in non-interactive (`claude -p`) +sessions, and writing into the plugin data dir may require a permission grant the run +cannot answer. In that case build the page, save it where the caller asked, and report +that publishing needs an interactive session — don't improvise another publishing path. + ## The artifact config (one per project) A small markdown file at `${CLAUDE_PLUGIN_DATA}/artifacts//config.md`, in the