using-open-artifacts

Open Artifacts

ユーザーが URL で共有できる、自己完結型の HTML、Markdown、または React アーティファクトを公開します。ビューアーはアーティファクトの本文をサンドボックス化された iframe 内に保持し、サービスのクローム、テーマ切り替え、バージョン選択、コメント、オプションの Live または Handoff コントロールを管理します。アーティファクトのバージョンは不変です。チャンネルを使うと、後から公開した場合も 1 つの URL を維持できます。

公開用 CLI は、このファイルと同じ場所にある scripts/artifact.mjs にバンドルされています。スキルのインストール先はエージェントによって異なるため（例：.claude/skills/ または別の Agent Skills ディレクトリ）、この SKILL.md を含むディレクトリを SKILL_DIR として特定し、タスクごとに ARTIFACT_CLI="$SKILL_DIR/scripts/artifact.mjs" を使用してください。プロジェクトのルートから node "$ARTIFACT_CLI" ... を実行します。グローバルにインストールされた artifact バイナリはありません。また、Recipe のパスはプロジェクトルートの作業ディレクトリを基準に解決されます。CLI の実行には Node.js 22 以降が必要です。

セットアップ（プロジェクトごとに一度）

CLI にはインスタンス URL が必要です。解決順は、--api フラグ、OPEN_ARTIFACTS_URL、プロジェクトの .artifacts/config.json または .artifacts/config.local.json、次に ~/.config/open-artifacts/config.json です。いずれも設定されていない場合は、ユーザーにインスタンス URL を尋ね、プロジェクトの設定ファイルに書き込んでください。CREATE_TOKEN でアクセス制限されたインスタンスでは、OPEN_ARTIFACTS_TOKEN または設定内の createToken を使用します。coda0.com のようなホステッド／SaaS インスタンスでは、node "$ARTIFACT_CLI" login を実行してください。ブラウザーでの認証手順については auth.md を参照してください。保存済みの sk_ API キーは、--token または OPEN_ARTIFACTS_API_KEY で明示的に上書きされない限り、セルフホストの create-token 値より優先されます。

各アーティファクトは、JSON Recipe と順序付けされたフラグメントから構築されます。作成または更新する前に、recipe.md をお読みください。共有 Recipe とフラグメントはプロジェクトのソースであり、コミットできます。.artifacts/recipes/ と .artifacts/fragments/ の下に配置してください。ローカルまたは暗号化されたソースは、.artifacts/recipes.local/ と .artifacts/fragments.local/ の下に配置します。

状態は .artifacts/ に保存されます。Manifest v2 に記録されるのは公開状態とビルドハッシュのみです。credentials.json、ローカルマニフェスト、非公開の Recipe／フラグメント、プレビューは gitignore の対象です。プロジェクトで最初に create を実行する際は、アーティファクトをローカルにするかどうかを尋ね、ローカルを推奨してください。選択内容を artifact.local に記録し、それに応じた場所に Recipe／フラグメントを配置します。

状態を変更するコマンドは、同時に実行せず、必ず 1 つずつ実行してください。 これには create、update、delete、migrate、ack、auto-update、login、logout が含まれます。install-hook もプロジェクト設定を書き換えます。credentials.json とマニフェストは、ロックなしの読み取り・変更・書き込みで更新されます。書き込みの直前に再読み込みを行うため、各コマンドのネットワーク往復を挟む競合は防げますが、2 つのコマンドの書き込みが実際に交錯すると、片方の変更が失われる可能性があります。書き込みトークンを失うと復旧できません。再発行するエンドポイントはありません。そのため、必ず順番に実行してください。これは特に「すべてを再生成する」処理で重要です。並列に実行せず、ループで処理してください。

まだインスタンスがない場合は、deployment.md を案内してください。インスタンスを用意する 3 つの方法（デプロイの設定不要で公開共有インスタンスを使う、自分の Cloudflare アカウントにセルフホストする、チームのインスタンスを共有する）と、コンテンツの機密性に基づいて選択するための信頼モデルの表が記載されています。ユーザーから依頼されない限り、代わりにデプロイしないでください。

アーティファクトを公開するタイミング

ユーザーが共有可能または単独で利用できるものを求めている場合は公開してください。たとえば、レポート、ダッシュボード、ドキュメントページ、視覚化、デモ、長文の解説などです。短い回答、コードスニペット、会話内で一度だけ読む内容は公開しないでください。判断に迷う場合は、会話内で回答し、公開することも提案してください。

ハーネスが対応している場合は、コンテンツ生成を分離する

公開または再公開では、プロジェクトのリソースとデザインの参考資料を読み、Recipe とフラグメントを作成し、決定論的なビルドを検証して、CLI を実行します。ホストがサブエージェントやタスクのプリミティブを提供している場合は、このコンテンツ生成ワークフローに使用し、親の会話では結果を受け取るだけで済むようにしてください。これはワークフローの最適化であり、CLI の要件ではありません。ホストにサブエージェント機能がない場合は、現在のエージェントで同じワークフローを実行してください。

可能であれば、初回公開の create と再公開の update の両方、およびそれらにつながるデザイン作業に、それぞれ別のタスクを使用してください。Claude Code では Agent タスクを利用できます。他のハーネスにも同等の機能がある場合があります。現在のエージェントしか作業者がいない場合に、架空の分離境界を作らないでください。

作業者が単独で作業できるように必要な情報をすべて渡したうえで、作業を任せてください。

• 概要：何を、誰に向けて、なぜ公開または更新するのか。
• 更新の場合：アーティファクト ID。作業者は node "$ARTIFACT_CLI" show <id> を実行し、現在公開されているバージョンを開始時の参考資料として読み込みます。 ロックされたデザインでは、そのページ先頭の方向性コメントに、変更してはならない内容が記載されています。「ロック」とはビジュアルの方向性（レジスター、パレットの色相ファミリー、レイアウトの姿勢）を変更してはならないという意味であり、アーティファクトが検証ゲートの対象外になるという意味ではありません。元の公開時にはなかったコントラストや CSP のチェックが後から追加され、以前は合格していたトークンが不合格になることがあります。その場合、更新時には問題のあるトークンを同じ色相の範囲内で調整し（たとえば、ライトテーマの --accent を数段階暗くする）、ページの方向性を保ったままゲートに合格させる必要があります。（暗号化されたアーティファクトの場合、show は作成時に credentials.json に保存されたパスワードを使ってローカルで復号するため、ユーザーに再入力を求めずに平文を復元できます。）その後、Manifest v2 に記録された Recipe とそのフラグメント、および scope の対象となるプロジェクトファイルを読み込みます。
• 公開に関する明示的な要件。タイトル、説明、ファビコン、スコープ、チャンネル、監視対象の glob、レベル、Canvas モード、ローカリティ、自動更新を Recipe に記載してください。パスワードは含めないでください。

作業者は、リソースの調査、計画、design.md、recipe.md、関連するモードの参考資料の読み込み、Recipe とフラグメントの作成、validate の実行、必要に応じたプレビューのビルド、create／update の実行、検証まで、残りのワークフロー全体を自分で実行します。そして、URL、バージョン番号、変更内容を示す一行だけの簡潔な要約を返します。親はその内容をユーザーに伝え、公開を独自に再実行したり、デザインに関する推論を自身のコンテキストに保持したりしてはいけません。

軽量な記録管理コマンドである status、ack <id>、auto-update <id> on|off、list、show <id>、whoami、logout、install-hook はコンテンツを作成しないため、直接実行できます。分離が役立つのは、create と update のコンテンツ生成部分のみです。

任意の参照 DNA（エージェント側のみ）

ユーザーが明示的に**「アーティファクトの参照 DNA としてこれを調べて」、「このデザイン DNA を使って」**と伝えた場合、またはスクリーンショットや公開 URL からアーティファクトの方向性を抽出するよう求めた場合は、作成に取りかかる前に reference-dna.md を読んでください。通常の引用、ソース URL、リンク集は、このワークフローの実行条件になりません。

URL の場合、調査タスクを委任する前に、親の会話でユーザーから所有権または公開参照に関する確認を得てください。調査タスクが作成するのは診断結果のみです。後から明示的に採用する決定がない限り、公開もサイドカーの書き込みも行いません。承認されたサイドカーは静的な Recipe 入力であり、ハッシュ化されて監視対象になります。また、アーティファクトの本文やランタイムには含まれません。ソースの安全規則については study.md を読んでください。

ページの設計方法

HTML でデザイン成果物を制作する、熟練のデザイナーとして取り組んでください。HTML はツールであり、表現媒体ではありません。ブリーフがダッシュボードなら情報デザイナーとして、レポートならエディトリアルデザイナーとして、プロトタイプならインタラクションデザイナーとして考えてください。何でも「ウェブページ」として仕上げるのは避けてください。

ワークフロー：（1）ブリーフを理解します。成果物の種類、忠実度、対象者、ブランドやデザインシステムの有無を確認します。（2）リソースを調べます。プロジェクトにデザインシステム（トークン、テーマ、コンポーネントのスタイル）がある場合は、すべて読み込み、適用します。優先順位はユーザーの指示、プロジェクトのシステム、そして自分の判断の順です。（3）計画を明示します。デザインの読み取りを一行で示し（「次のように捉えています：Z の方向性で、Y 向けの X」）、明るい配色か暗い配色かを選ぶシーンを一文で表現し、名前付きのパレット値を 4～6 個、タイポグラフィの役割、レイアウトのコンセプトを一文で示します。（4）実際のコンテンツを使って制作し、lorem ipsum は使いません。（5）最後に一度だけ、design.md に記載された公開前チェックを実施します。構造の grep、P0 チェックリスト（両テーマでのコントラスト、360px、禁止された定番表現、状態、モーションの低減、コピーの監査）、続いて 5 つの観点（思想／階層／実行／具体性／抑制）で批評します。3/5 未満の項目は修正し、一度だけ再採点して公開します。レンダリングを繰り返して確認しないでください。

ページを書き始める前に、design.md を読んでください。ここにはデザイン思想の全容が記載されています。ブランドとプロダクトの表現の使い分け（積み重ねた親しみやすさと独自性）、AI らしさを安易に持ち込む表現の禁止事項、共有トークンの仕様（Recipe ビルダーが references/tokens.css を注入します。テーマのフラグメントでアイデンティティトークンを上書きしてください）、インストール済みフォントの見本ライブラリ（CSP はフォントの ダウンロード をブロックしますが、OS のライブラリはブロックしません。Iowan、Charter、Avenir、Optima などを利用できます）、すぐに貼り付けられる OKLch パレットを備えた 5 つの方向性（エディトリアル／モダンミニマル／ヒューマン／テックユーティリティ／ブルータリスト）、CSP 環境での視覚素材に関するガイダンス（テキストだけの大きな塊ではなく、SVG チャート／図解／タイポグラフィを活用した表現）、トークンに基づくコンポーネントの仕様、ビューアーフレームの詳細（固定ヘッダーの高さ、テーマの設定）、そして公開のたびに実行する公開前チェックが含まれています。

視覚的な方向性を持つ HTML Artifact を作成する場合は、フラグメントを書く前に quality.md を読んでください。 形式に応じたデザインブリーフ、レベル 3 の批評、ブランド表現の成果物における構造の選択、CSP に準拠した視覚素材の選択、ビルドの静的品質プロファイル、320/375/414/768px でレンダリングする smoke コマンドが記載されています。Canvas は引き続き canvas.md に従い、Markdown はビューアーが管理する .oa-md のスタイルを維持します。ユーザーがスクリーンショットや URL を参考にして学ぶよう明示的に求めた場合は、参考資料を調べる前に reference-dna.md を読んでください。ここから、参照元の安全性については study.md に案内されます。リモートコンテンツは信頼できないものとしてエージェント側に保持し、Artifact にフェッチ処理やリモートアセットを含めることはありません。

制作品質レベル（1 / 2 / 3）

すべてのアーティファクトは、次の3段階のいずれかで作成します。ブリーフに基づいて選び、Recipe に artifact.level: 1|2|3 として記録してください。

• レベル1 — シンプル： 文字組みを中心とするドキュメント（レポート、記事、API リファレンス、メモ）。派手なヒーロー表示はなく、JavaScript は最小限です。「一度読めばよい」コンテンツのデフォルトです。本文は <main class="oa-prose"> で囲みます。これは契約で定められた散文のベースライン（行幅の上限、パディング、見出しとコードのスタイル）です。トークンを定義しても構造を忘れたドキュメントが、何もない状態で公開されるのを防ぎます。
• レベル2 — インタラクティブ： ダッシュボード、ドキュメントサイト、デモ、プロトタイプ。状態を持つインメモリ JavaScript、ナビゲーション、コピーボタン、展開可能なセクション、控えめなトランジションを備えます。判断に迷い、ブリーフがインタラクティブな場合のデフォルトです。ブリーフの大部分が読むためのテキストなら、レベル1のほうが安全な選択です（構造のベースラインが備わっており、L2 では構造を作成者が用意するためです）。L2 以上を構築する前に、8つの状態に関する契約、フォーカスの可視性、ヒットターゲット、フォームのパターン、待機状態について、references/interaction.md を読んでください。
• レベル3 — リッチ： ランディングページ／マーケティングページ、製品紹介。読み込みシーケンス、スクロール時の表示、ビュートランジションなど、動きを連携させます。すべてネイティブのブラウザー API を使用し、外部ライブラリは使いません（厳格な CSP により CDN がブロックされるためです）。L3 を構築する前に、ネイティブなモーションパターンライブラリをまとめた references/motion.md を読んでください（ここでも interaction.md が適用されます）。

ドキュメントを L3 として過剰に作り込まないでください。ランディングページを L1 として公開しないでください。レベルは、単に「アニメーションの量」を決めるものではなく、コンポーネントの契約とモーションの予算を定めます。

キャンバスモード

レベルとは独立して、artifact.canvas: true にすると、ページのシェルが、パン／ズーム可能な無限の空間平面とフレームに置き換わります。どのレベルとも組み合わせられます。レベル1は空間的なメモ、レベル2は複数フレームのプロトタイプ（デフォルトの用途）、レベル3はショーケースとしてのキャンバスです。構築する前に references/canvas.md を読んでください。勢いとピンチ操作の物理挙動、オプションのプレゼンターツアー、コネクターのスポットライト表示、#frame-id によるディープリンクを備えた、完全なベンダー同梱のランタイム（CSS + バニラ JavaScript）のほか、フレームおよび自由形式の契約と、キャンバスの公開ゲートについて記載されています。

オプションのビューアーワークフロー

ライブ編集は、インスタンスで LIVE_DO がバインドされている場合にのみ利用でき、アーティファクト所有者の sk_ セッションが必要です。また、インプレースで update --live を実行する前に、ローカルの Recipe ソースを編集します。ライブセッションを開始する前に live.md を読んでください。OPEN_ARTIFACTS_HANDOFF=1 を設定したデプロイでは、ホスト側のウェブカメラ／マイクによる録音と再生が公開される場合もあります。これはビューアーの UI であり、Recipe の形式でもアーティファクト側の API でもありません。どちらの機能もオプションで、セルフホスト可能なインスタンスでは利用できない場合があります。

コンテンツ作成 — 厳守事項

アーティファクトのフレームには厳格な CSP が適用されます。作成したコードから外部リクエストを送信することはできません（CDN スクリプト、リモート画像、fetch/XHR/WebSockets）。

• CSS と JS はすべてインラインにし、画像とフォントは data: URI として埋め込みます。システムフォントスタックを使うか、@font-face の data: URI としてフォントをインライン化してください。OPEN_ARTIFACTS_WEB_FONTS="1" を設定したデプロイでは、Web フォントを /fonts/<family>--<weight>[--italic] プロキシ経由で同一オリジンから読み込むか、許可リストに登録されたフォント CDN（Fontshare / Google Fonts）から直接読み込むこともできます。Mermaid を使う場合は、常にセルフホストされ、許可リストに登録された <script src="/vendor/mermaid.runtime.js"> パスから配信されます（通常の非モジュールスクリプト）。Web フォントのフラグとは無関係です。references/fonts.md と references/scripts.md を参照してください。ビルドゲートにより、@font-face／@import の接続先はこれらのフォントホストに、<script src> の接続先は許可リストに登録された同一オリジンの /vendor/... バンドルに制限されるため、任意の外部ホストには一切接続できません。
• アイコンには Remix Icon を推奨します。 references/icons.md にある、ベンダー提供の約90種類のインライン SVG サブセット（ナビゲーション、アクション、ステータス、ソーシャル、一般的な UI）を参照してください。<svg> ブロック全体をインラインでコピーしてください。fill="currentColor" を使っているため、色は親要素から継承されます。Remix Icon の CDN にはリンクしないでください（CSP によってブロックされます）。インライン SVG のみを使用してください。アイコンをテキストの横に置く場合は、規約に従った中央揃えの行で囲んでください（<h2 class="oa-ico-text"><svg class="oa-ico">…</svg> Title</h2>）。見出しにアイコンだけを置くと位置が低くなり、ビルドに失敗します。
• localStorage／sessionStorage は使用しないでください（サンドボックスによってブロックされます）。状態はメモリ内に保持してください。
• 簡潔なタイトルを artifact.title に設定してください。
• ライトテーマとダークテーマの両方に対応してください。ビルダーは references/tokens.css を挿入します。テーマフラグメントには、レイヤーに属さない :root ブロック（ライト）と :root[data-theme="dark"] ブロックの両方を必ず記述してください。トークン規約が提供するのは変数のみで、要素のスタイルは適用しません。レベル1の HTML ドキュメントでは、本文を <main class="oa-prose"> で囲み、規約で提供される文章の基本スタイル（行幅の上限、ページ余白、見出しのサイズ、code／pre／table のスタイル）を適用してください。デフォルトではブラウザー標準の余白を持つ全幅ドキュメントになるため、行幅の上限がない L1 の非キャンバスページは validate で失敗します。Markdown の場合は何も必要ありません。ビューアーが自動的に .oa-md で囲みます。ビューアーの UI（サービスヘッダー、テーマ切り替え、ブランドチップ、バージョンピッカー、コメント、デプロイで有効化された Live／Handoff コントロール）は、配信時にホストが挿入します。これらを手動で作成しないでください。 トークン規約のクロームブリッジにより、UI は自動的にプロジェクトのアイデンティティパレットに従います。そのため、テーマフラグメント内で --oa-* ビューアートークンを上書きしないでください。L2／L3 はデザイン上、全幅表示にすることもできます。その場合は構造を明示的に作成してください。
• レスポンシブ対応：本文の横スクロールを発生させないでください。幅の広い表やコードは、それぞれに overflow-x: auto のコンテナーを用意してください。

Markdown の作成

上記の厳しい制約のほとんどはHTML 固有であり、Markdown には適用されません。Markdown Recipe は本文の .md をそのまま公開します。ビルダーは references/tokens.css を挿入せず、コンテンツを <style> ブロックで囲まず、HTML の検証ゲート（テーマフラグメント、:root／[data-theme="dark"] 要件、コントラストチェック、L1 の幅上限、禁止トロープの検索）も実行しません。ビューアーは生の Markdown を .oa-md で囲み、ビューアーのデフォルトトークンを使ってクライアント側でレンダリングします。そのため、次の点に注意してください。

• document.theme、document.fragments.theme／styles／scripts はすべて省略する必要があります。テーマ／スタイル／スクリプトのフラグメントを含む Markdown Recipe は validate によって拒否されます（エラー：「Markdown recipes only support body fragments」）。1 つ以上の .md ファイルのみを含む document.fragments.body を指定してください。document.theme は省略するか、null にできます。
• Markdown の成果物にはテーマ、スタイル、スクリプトを設定できません。インタラクション、アイデンティティトークン、またはデフォルトを超える幅の上限が必要な場合は、代わりに HTML として作成してください。
• artifact.title は引き続きページタイトルと OG カードに使われます。最初の # 見出しも、タイトルのフォールバックとして抽出されます。
• 両テーマへの対応は自動です（ビューアーの .oa-md シェルがライト／ダークのトークンを読み取ります）。作成時に指定するものはありません。

Markdown ファイル（.md）はクライアント側でレンダリングされます。インタラクティブなものやデザインを重視するものには HTML が適しています。

AI っぽさが目立つ定番表現は避けてください（design.md に一致時に拒否される項目の一覧があります）。 サイドストライプのアクセント枠、グラデーションテキスト（background-clip: text）、装飾的なグラスモーフィズム、同一パターンのカードグリッド、ヒーロー指標のテンプレート、アイコンタイルの積み重ね（すべてのカード見出しの上に浮かぶ角丸アイコンタイル）、各セクションの上に置く大文字の短いラベルや 01 / 02 / 03 のマーカー、ダーク背景での色付きのグローシャドウ、イタリック体のセリフフォントを使ったヒーロー表示、格言風の文章のリズム（「X ではありません。Y です。」）、モバイル幅で収まらない見出し、作り上げた内容（偽の指標や推薦文、「Acme Corp」など）です。偽の数値より、正直なプレースホルダーを使ってください。コントラスト（両テーマで本文は ≥ 4.5:1）を確認し、色付きのほぼ白い背景にくすんだグレーを決して使わないでください。ビューポート全体を使うセクションには min-height: calc(100dvh - var(--oa-header-h, 2.5rem)) を使ってください。ビューアーが固定ヘッダーを追加します。最新の CSS はインラインですべて使用できます。text-wrap: pretty/balance、CSS Grid、コンテナクエリ、color-mix()、:has()、ビュー遷移、流動的な文字サイズのための clamp() などです。

公開

(ハーネスがタスクを提供している場合は、コンテンツ生成タスク内で実行してください。プロジェクトのルートから実行してください。)

Recipe と順序付きフラグメントを作成して検証し、公開します。

node "$ARTIFACT_CLI" validate .artifacts/recipes/app-interactions.recipe.json
node "$ARTIFACT_CLI" create .artifacts/recipes/app-interactions.recipe.json

Recipe はファビコン、スコープ、チャンネル、監視対象の glob、レベル、Canvas モード、ローカリティ、自動更新を管理します。ファビコンは安定したものを使用してください。create の呼び出し間で同じ URL を再利用するには kebab-case のチャンネルを使い、新しい URL を生成するには null を使います。create はメモリ内で合成して、最後に 1 つのペイロードを送信します。共有可能な URL が出力されます。

Manifest v2 に Recipe のパスと Recipe／入力／出力のハッシュが記録されるのは、公開が成功した後のみです。書き込みトークンとチャンネルトークンは、Git で無視される認証情報ファイルに保存されます。

公開後のライブモード

ライブ対応インスタンスでは（インスタンスが LIVE_DO にバインドされており、ログイン済みの場合、CLI は create の直後に「ライブモード」のヒントを表示します）、アーティファクトの公開後はデフォルトでウォッチャーを起動してください。

node "$ARTIFACT_CLI" live <ID> --watch

バックグラウンドタスクとして実行し（ハーネスごとのパターンは references/live.md の「ハーネスに関する注意事項」を参照）、セッション中は実行したままにしてください。ライブセッション中に行うことはポーリングだけです。ビューワーページを自分で操作することはありません（ブラウザーの自動操作、Live のクリック、要素の選択、アーティファクトページでのプロンプト入力は禁止です）。ビューワーはユーザーが操作します。アーティファクトの URL を開いて Live をクリックし、要素を選択した後、それぞれについて変更を入力する（generate イベント）か、要素のテキストをインラインで編集します（「テキストを編集」、edit イベント）。references/live.md の「コピーの編集」セクションを参照してください。ウォッチャーは各イベントを表示するので、それに応じて操作します（Recipe のソースを編集し、update を実行して、done と返信します）。ウォッチャーの接続中は、ビューワーの Live ボタンに Connected と表示されるため、ユーザーは要素を選択する前にエージェントがオンラインであることを確認できます。保留中のイベントがウォッチャーにリースされている間は、切り替えボタンのアクセント色のドットが点滅します（「エージェントが編集を処理しています」）。ウォッチャーが切断されると、起動時のヒントとともに琥珀色の点滅するドットが表示されます。ウォッチャーが接続されていなくても、Live をクリックするとピッカーが開き、コピー可能な起動プロンプトも表示されます。編集を送信する前にウォッチャーを起動してください。セッションの前に references/live.md を読んでください。

更新

（ハーネスにコンテンツ生成タスクが用意されている場合は、そのタスク内で実行してください。プロジェクトのルートから実行します。）

node "$ARTIFACT_CLI" update <id> [recipe.json] [--label "what-changed"]

同じ URL で、新しいバージョンになります。パスを指定しない場合、update は Manifest v2 に記録された Recipe を使用します。プロジェクトのソースを読んだうえで、そのフラグメントを更新し、必要に応じて show <id> と比較してください。CLI はメモリ内で再ビルドと検証を行ってから、一度だけ公開します。最初の位置引数はアーティファクトの短い ID であり、Recipe のパスではありません。従来の Manifest v1 エントリーは自動的に移行されます。公開前に生成されたソースを確認または編集したい場合に限り、先に migrate <id> を実行してください。409 バージョン競合は、別の書き込み元が先に公開したことを意味します。現在のバージョンを確認し、上書きが意図的な場合にのみ --force を使用してください。--label の上限は UTF-8 で 60 バイトです。

Live 経由で依頼された変更には、Recipe を編集した後、node "$ARTIFACT_CLI" update <id> --live を使用してください。これにより、現在配信中のバージョンがそのまま置き換えられます。v10 のアーティファクトは v10 のままで、その後の通常の update で v11 が作成されます。

build <recipe> --output <path> は、明示的なローカルプレビューを書き出します。--standalone は HTML Recipe の場合にのみ追加してください。list、show <id> [--v N]、delete <id> で、一般的な読み取りとクリーンアップを行えます。delete はサーバー上のアーティファクトとローカルのマニフェストエントリーを削除します。

古くなったアーティファクトの検出（意図がある場合にのみ再公開）

ソースに変更があっても、それだけでアーティファクトが編集または再公開されることはありません。プロジェクトで最初に create を実行した後、オプションの Claude Code Stop フックをインストールするかどうか、ユーザーに確認してください。黙ってインストールしてはいけません。同意が得られたら、node "$ARTIFACT_CLI" install-hook を実行します。これにより .claude/settings.json に Stop フックが追加され、ターンの終了時に差分が通知されます。ほかのエージェントハーネスでは、それぞれのフック連携を使用するか、次の手動チェックを実行してください。

node "$ARTIFACT_CLI" status

古くなったと報告されたアーティファクトごとに、変更されたファイルが記録済みの対象範囲に影響するかどうかを判断してください。

• 影響する場合 → プロジェクトの現在の状態を反映するようページの内容を再生成し、update を実行します。これにより再公開され、スナップショットも更新されます。再生成はコンテンツの生成にあたるため、上記の「ハーネスがサポートしている場合はコンテンツ生成を分離する」に従い、ハーネスに専用タスクがある場合はそれを使用してください。この判断を Stop フック経由で自律的に行う場合も、人から直接依頼された場合と同様です。
• 影響しない場合（例：ユーザー向けの対象範囲に動作上の変更がないリファクタリング、または対象範囲内で方針が確定している場合）→ node "$ARTIFACT_CLI" ack <id> を実行します。これによりオフラインでスナップショットの基準が更新され、再公開は行われません。同じ無関係な変更が毎ターン報告されることもなくなります。ack はマニフェストの変更のみを行い、コンテンツを生成しないため、そのまま実行して問題ありません。古い状態のまま放置しないでください。フックがインストールされている場合、基準が update または ack で更新されるまで、以後のすべてのターンで再度通知されます。

特定のアーティファクトを自動ループの対象にする

デフォルトでは、インストール後の Stop フックは、監視対象のすべての古くなったアーティファクトを通知します。再生成するか ack を実行するかの判断は、各アーティファクトについて引き続き必要です。ほとんどのアーティファクトについてはフックから通知せず、特定のアーティファクトのみを通知したい場合は、そのアーティファクトの自動更新フラグを有効にします。

node "$ARTIFACT_CLI" auto-update <id> on

この設定によって、フラグが付いたアーティファクトに対する判断方法が変わることはありません。変わるのは、Stop フックが通知できるアーティファクトの範囲だけです。

• アーティファクトごとのオプトインで、完全に分離されています。マニフェスト内の1つのエントリの autoUpdate フィールドだけを切り替え、ほかのエントリの状態を読み書きすることはありません。デフォルトではオフです。この機能が導入される前に作成されたものを含め、切り替えられたことのないアーティファクトはオフとして扱われ、古くなっていてもフックからは一切通知されません。
• 人が手動で実行する通常の node "$ARTIFACT_CLI" status（--hook なし）は、このフラグによる絞り込みの対象になりません。古くなった監視対象のアーティファクトをすべて常に報告します。対象を絞り込むのは、人がいない状況で自律的に実行される Stop フックの処理のみです。
• オンにするには、そのアーティファクトの書き込みトークンがすでに存在している必要があります（存在しない場合は明確なエラーになります）。また、Stop フックがまだインストールされていない場合は、自動的にインストールされます。フックをインストールせず、ヒントだけを表示する create とは異なり、auto-update <id> on の実行は、フックのインストールに対するユーザーの同意を意味します。そのまま進めてください。インストールが行われると、CLI が確認を表示します。
• オフにする（node "$ARTIFACT_CLI" auto-update <id> off）場合、インストール済みのフックはそのまま残ります。このアーティファクトへの通知を停止するだけです。

パスワード保護

node "$ARTIFACT_CLI" create .artifacts/recipes.local/q3.recipe.json --password "..."

Recipe で security.encrypted: true と kebab-case の security.passwordCredential を設定してください。暗号化された Recipe とフラグメントは、非公開の .artifacts ソースディレクトリに配置する必要があります。

コンテンツはローカルで暗号化されます（PBKDF2 600k + AES-256-GCM）。サーバーには暗号文のみが保存され、閲覧者はブラウザーで復号します。URL とパスワードは別々の経路で共有してください。シェル履歴やプロセス一覧にパスワードが残る懸念がある場合は、コマンドラインでパスワードを渡す代わりに、名前付き環境変数または Git で無視される認証情報ファイルを使用してください。CLI は、--password、対応する OPEN_ARTIFACTS_PASSWORD_* 環境変数、または Git で無視される認証情報ファイルから、名前付き認証情報を取得します。パスワードが Recipe や Manifest に入ることはありません。タイトルとファビコンはサービスメタデータとして平文のまま残るため、機密情報を含めないでください。

読み戻し

生のコンテンツは、API パスのみにあります — GET <instance>/api/artifacts/<id>/raw。ビューアーパス GET <instance>/a/<id> は、レンダリングされたビューアーページ（HTML）を返すもので、生の バイト列は返しません。/a/<id>/raw はルートではなく、404 を返します。次の2つを混同しないでください。 /a/<id> = ブラウザーで表示されるページ、/api/artifacts/<id>/raw = 公開された状態で保存されている コンテンツ。

GET <instance>/api/artifacts/<id> はメタデータとバージョン履歴を返し、 GET <instance>/api/artifacts/<id>/raw は保存されたコンテンツを返します （古いバージョンには ?v=N を指定します）。暗号化されていないアーティファクトの場合、返されるのはページ そのもの（text/plain）です。暗号化されたアーティファクトの場合は JSON 形式の暗号文 エンベロープです。代わりに node "$ARTIFACT_CLI" show <id> [--v N] [--password ...] を実行してください。指定または保存された認証情報を使用して、 ローカルで復号します。ビューアー URL でも ?v=N を使用できます。