フォリオ(Folio)
リクエストと既存のアーティファクトを読んでからHTMLを書いてください。すべての外部依存関係と公開URLはマニフェスト元帳(manifest ledger)に属します。アーティファクトは静的なドキュメントであり、APIを呼び出しません。
フォリオを使用すべき時と、使用すべきでない時
フォリオは永続的で開封可能、共有可能なWeb成果物(ユーザーが保存、再開、または他の人に渡すもの)のためのものです。
以下の場合にフォリオを使用します:
- ユーザーが保存または送信するドキュメント、ダッシュボード、シート、デッキ、またはページを要求した場合
- 出力が成果物であり、クイックルックではない場合(「レポートを作って」、「チーム用のダッシュボードを構築して」、「これをオンラインにして」、「~するページが欲しい」など)
- ユーザーが明示的に動詞を使用した場合(
folio publish、folio audit、folio remix、folio describe)
以下の場合にはフォリオを使用しないでください:
- ユーザーが成果物ではなくクイックルックを望んでいる場合(「見せて」、「どんな感じ?」、「確認して」、「表示できる?」)
- 出力がこの会話の後には開かれない場合(インラインで回答するか、スクラッチファイルを書き、スタンプや元帳、ゲートを付けない)
- リクエストがコードスニペット、設定ファイル、単一関数の場合(これらはブラウザアーティファクトではありません)
入り口ゲート。 アーティファクトフローに入る前に、次の質問をしてください:ユーザーはこのセッションの後にこのファイルを再び開くか? Noなら、フォリオは不適切なツールです — 単に回答してください。Yesなら、進めてください。
スタンドアロンがデフォルトです。 最も軽量なフォリオパスは、1つのフォルダと1つのindex.htmlだけです — サイトルート、site.json、インデックスページは不要です。サイトルートは、2つ目のアーティファクトが現れた場合、またはユーザーがコレクションの公開を要求した場合にのみ表示されます。1ファイルに対してサイトの儀式を作成しないでください。
用語集
フォリオの出力では、これらの用語のみを使用します。
| 用語 | 意味 |
|---|---|
| アーティファクト | 自己完結型の静的Web成果物:CSS/JSを含むHTML、ブラウザで実行可能 |
| バンドル | single-file(インラインCSS/JS)またはmulti-file(リンクされたアセットを1ディレクトリに)のいずれか |
| アーティファクトの種類 | doc、sheet、dashboard、explainer、slides、tool、landingのいずれか |
| ホストプロファイル | サイトが永続的に存在する場所:local、surge、gh-pages、cf-pages、cf-worker |
| 共有(トンネル) | 実行中のローカルサーバーへの一時的な公開URL。localhost.run(デフォルト)またはngrok経由。一時的で、マシンがホストを継続 — 公開ではありません |
| サイトルート | index.htmlとartifacts/ツリーを含むディレクトリで、1つのドメインとして公開されます。アーティファクトはその下のパスであり、別のサブドメインではありません。 |
| サイトマニフェスト | .folio/site.json — 信頼できる情報源です。ドメイン + アーティファクトごとのレジストリ(スラッグ、種類、バンドル、元帳、出典、公開状態)を含みます。スタンプ、インデックス、監査はすべてこれから派生します。 |
| スタンドアロンアーティファクト | サイトルートを持たないアーティファクト。HTMLスタンプが唯一のマニフェストです。2つ目のアーティファクトが現れるとサイトエントリにアップグレードされます。 |
| 出典 | リミックスされたアーティファクトのsourceフィールド:{ slug, site, url }。オリジナルではnull。describe、audit、remixで読み取られます。 |
| マニフェスト | エントリHTML、ファイルリスト、外部依存関係、およびオプションの公開メタデータ |
| 元帳 | マニフェスト元帳 — 依存関係、データファイル、URL、およびビルド前の証拠レベル |
| ゲート | 受け渡し前に合格しなければならないバイナリチェック |
| 証拠レベル | observed、derived、stated、absentのいずれか |
このスキルの使い方
- デフォルト:1つのアーティファクトを作成または更新します。アーティファクトフローに従ってください。単一のアーティファクトはデフォルトでスタンドアロンです — サイトルートは不要です。
folio audit <path|url>:読み取り専用の監査。編集しないでください。references/verbs/audit.mdを読んでください。folio describe <path|url|slug>:アーティファクトのマニフェストエントリ(種類、元帳、出典、公開状態)を読んでください。references/verbs/describe.mdを読んでください。folio share <site-root>:ローカルで実行中のサイトへの一時的な公開リンクを、トンネル経由で開きます(デフォルトはlocalhost.run — インストール不要、アカウント不要;--ngrok代替)。マシンがホストを継続し、URLはプロセスとともに消滅します。「今すぐ誰かに見せる」ために使用し、公開には使用しません。references/verbs/share.mdを読んでください。folio publish <site-root>:選択したホストプロファイルにサイトルート(すべてのアーティファクト)を永続的なホスティングのためにデプロイします。最初にインデックスを再生成し(scripts/gen-index.js)、その後デプロイします。references/verbs/publish.mdを読んでください。folio remix <path|url>:アーティファクトをフォークして変更し、マニフェストの誠実さを維持し、ソースの系統を記録します。references/verbs/remix.mdを読んでください。
1回の実行 = 1つのアーティファクト(ユーザーが複数を指定した場合を除く)。リクエストを満たす最小のバンドルを優先してください。単一アーティファクトはスタンドアロン、複数のアーティファクトは1つのサイトルートの下にあり、1つのドメインとして公開されます。サイトルートモデルとスタンドアロンからサイトへのアップグレードについてはreferences/site-index.mdを読んでください。
非妥協的な規律
- 美しさより先に実行可能。 アーティファクトはブラウザで開き、コアなインタラクションが動作してから、洗練や公開を行います。
- 静的なドキュメントのみ。 外部APIへの
fetch()、WebSocket接続、ライブエンドポイントへのXMLHttpRequestは禁止です。データはインラインで埋め込むか、ローカルファイルからfetch('./data/…')経由で読み込むか、ビルド時に生成します。アーティファクトが行うネットワークリクエストは、元帳に記録されたCDNスクリプト、スタイル、フォントのみです。 - マニフェストの誠実さ。 CDNスクリプト、フォント、画像、データファイルは元帳の行であり、サプライズではありません。
- ローカル優先、次に共有、最後に公開。 デフォルトのホストプロファイルは
localです。動的な方法で実行します —node <folio-skill>/scripts/serve.js <site-root>でartifacts/フォルダを確保し、元帳からインデックス/検索ページを再生成し、空きポートを選び、HTTPで提供します(完全にインライン化された単一ファイルにはfile://で十分ですが、fetchやモジュールインポートでは壊れます)。references/local-server.mdを参照してください。今すぐ誰かに見せるには、一時的なトンネルを開きます —node <folio-skill>/scripts/share.js <site-root>(デフォルトlocalhost.run、インストール/アカウント不要);リンクは一時的で、マシンがホストを継続します。永続的な外部ホスティングはpublish— ユーザーが要求した場合、またはfolio publishが呼び出された場合のみ。共有や公開機能を積極的に宣伝しないでください。 - 静的ファイルに秘密を入れない。 APIキー、トークン、プライベートURLはコミットまたは公開されたHTML/JSに含めてはいけません。
- 見苦しくない。 アーティファクトはビジュアルベースラインに従います。ビルド前に
references/visual-baseline.mdを読んでください。
ゴールド意思決定トレース
リクエスト: このCSVから対話型のレイテンシヒストグラムをチームメイトのために作成する。
インベントリ:
・対象: 新しいアーティファクト `latency-hist`
・既存: なし
・データ: ユーザーが`runs.csv`を添付(observed、840行)
・制約: ローカルフォルダ、公開なし
選択: kind=explainer · bundle=multi-file · host=local · audience=チームメイトへの受け渡し
元帳:
dep | kind | evidence | in artifact as
d3@7 (cdn.jsdelivr) | script | stated, ユーザーがピン留めしていない | index.htmlのscriptタグ + READMEにメモ
runs.csv | data | observed | ./data/runs.csv、fetch('./data/runs.csv')で読み込み
ファイル計画:
作成: artifacts/latency-hist/index.html、style.css、app.js、data/runs.csv、README.md
削除: なし
検証: npx serve artifacts/latency-hist;チャートがレンダリングされる;コンソールクリーン
ゲート: opens-locally=yes、console-clean=yes、ledger-complete=yes、no-secrets=yes、mock-labeled=n/a、visual-baseline=yes
引き渡し: パス、開き方、元帳サマリー、延期事項: なし
スコープフォーク
広範な設計質問の前にスコープを解決します。
| リクエストの形状 | バンドル | ホスト | スキップ |
|---|---|---|---|
| 簡単な使い捨てデモ | single-file | local | README、公開、複数ページ |
| ドキュメントやレポート | single-file または multi-file | local | チャート、重いJS |
| データテーブルやシート | single-file または multi-file | local | 物語散文、装飾 |
| メトリクスダッシュボード | multi-file | local | 完全なCRUD、ライブデータフィード |
| コンセプト解説 | multi-file | local | 密度の高い生データダンプ |
| スライドデッキ | multi-file | local | スクロールレイアウト、ウィジェット |
| 共有されるチームメイト成果物 | multi-file | local | フレームワークビルドステップ |
| 今すぐ誰かに見せる | single-file または multi-file | share (tunnel) | デプロイの儀式、永続的なホスト |
| 永続的な公開リンク | multi-file | surge または cf-pages | 認証、サーバーロジック |
| エージェント引き渡しプレビュー | single-file推奨 | local | 要求されなければ共有/公開 |
曖昧なリクエスト:簡潔に1回だけ質問します。例:「単一の自己完結型ファイル、それとも別々のCSS/JSを持つ小さなフォルダ?」回答がない場合は、機能する最小のバンドルを選択します。
アーティファクトフロー
0. インベントリ
リクエストと既存のアーティファクトツリーを読んでください。references/evidence.mdとreferences/artifact-types.mdを読んでください。
以下を収集します:
- 主題: アーティファクトが表示すべきこと、またはユーザーにさせたいこと
- 入力: ファイル、JSON、CSV、コピー、デザイン制約(証拠レベル付き)
- 既存アーティファクト: パス、エントリHTML、マニフェスト、最後の公開URL(ある場合)
- ホストプロファイル: デフォルト
local;公開が対象範囲内の場合はreferences/host-profiles.mdを読む - 規約ソース:
folio.mdが存在する場合
進行前に、引用付きのコンパクトなインベントリを出力します。
1. 選択
ビルド前に出力:Picks: kind=<x> · bundle=<y> · host=<z> · audience=<a>。
種類が不明な場合はreferences/artifact-types.mdを読んでください。ホストがlocalでない場合はreferences/host-profiles.mdを読んでください。
2. マニフェスト元帳
HTMLを書く前に元帳を構築します。references/manifest-ledger.mdを読んでください。
列:
dep | kind | evidence | in artifact as
種類:script、style、font、image、data、mock、publish-target。
データファイルとモックデータは明示的でなければなりません。外部API呼び出しは対象外です — 規律#2を参照。
3. ファイル計画とビルド
編集前にファイル計画を述べます:
作成: artifacts/<slug>/index.html、app.js、data/sample.json
変更: なし
削除: なし
テンプレートから始めます。 references/templates/<kind>.htmlを読み込んで適応します — {{placeholder}}コンテンツと<!-- Replace: ... -->マーカーを実際のコンテンツで置き換えます。テンプレート自体がゲート通過済みのフォリオアーティファクトであり、トークンブロック、ライト/ダークトグル、ファビコン、および種類固有の構造を持ちます。各テンプレートが提供するものについてはreferences/templates/のインデックスを読んでください。
CSSを書く前にreferences/visual-baseline.mdを読んでください。
ユーザーが特定のスタックを指定しない限り、プレーンなHTML/CSS/JSで構築します。以下を優先します:
- セマンティックHTML、1つの明白なエントリファイル(
index.html) - すべてのビジュアルトークン(色、タイポグラフィ、間隔、半径、影)にCSSカスタムプロパティを使用
- 色にはOKLCHを使用;
:rootトークンブロック外ではインラインのhex/rgbは使用禁止 - バニラJS、または元帳に記録された単一の名前付きCDNライブラリ
multi-file:すべてのアセットパスを相対パスに保ち、絶対マシンパスは禁止- 斜体の見出しは禁止;読みやすいメジャー(
max-width: 60–70ch);htmlとbodyにoverflow-x: clip
アーティファクトがユーザー入力を受け付けたり、サードパーティコンテンツを埋め込んだり、公開されたりする場合はreferences/security.mdを読んでください。
スタンプ(HTMLコメント、エントリファイルの先頭):
<!-- Folio · slug: latency-hist · kind: explainer · bundle: multi-file · host: local -->
<!-- deps: d3@7 · data: runs.csv · publish: none -->
single-fileの場合、スタンプは最小限に保ちます(1行)。
4. 検証
references/verification.mdを読んでください。ホストプロファイルに合ったチェックを実行します。
最小マトリックス:
check | command/evidence | result | notes
例:静的サーバー + エントリURLの読み込み、DevToolsコンソールクリーン、プライマリインタラクションのクリックスルー、壊れたリンクスキャン、file:// vs サーバーノート(fetch用)、ビジュアルベースラインスポットチェック。
5. ゲート
引き渡し前に適用します。noがあると修正ループをトリガーします。
| ゲート | チェック |
|---|---|
opens-locally | エントリHTMLが静的サーバー経由で読み込まれる(または正直なfile://注意事項が文書化されている);サーバー設定についてはreferences/local-server.mdを参照(scripts/serve.jsが1コマンドパス) |
console-clean | プライマリパスでキャッチされていないエラーがない |
ledger-complete | すべての外部依存関係とデータソースが元帳に現れる |
no-secrets | ソースにキー、トークン、プライベートURLがない |
mock-labeled | 実際のデータがない場合、モック/サンプルデータにラベルが付けられている |
static-only | 外部APIへのfetch()、WebSocket、ライブエンドポイントへのXHRがない |
visual-baseline | トークンブロックが存在し、:root外にインライン色がなく、斜体見出しがなく、コントラストが適切 |
publish-ready | 公開時:ホストプロファイルの手順が文書化され、検証されているか、明示的に延期されている |
manifest-derivation | 助言的。 HTMLスタンプ(スラッグ、種類、バンドル)がこのアーティファクトのsite.jsonエントリと一致する。ドリフトをフラグ付け;references/verification.md#manifest-derivation-checkを参照。 |
ビルド後にreferences/slop-test.mdを読んでください。引き渡し前にP0/P1を修正します。
6. 公開(オプション)
ユーザーが公開を要求した場合、またはfolio publishが呼び出された場合のみ。references/verbs/publish.mdとホストプロファイルの詳細ファイルを読んでください。
公開URLをマニフェストと引き渡しに記録します。公開コマンドの出力からの証拠なしにURLを主張しないでください。
7. 引き渡し
以下を含めます:
- アーティファクトのパスとエントリファイル
- ローカルで開く方法(正確なコマンド)
- 公開URL(公開された場合)、証拠付き
- マニフェスト元帳サマリー
- 検証コマンドと結果
- 延期された項目(例:
fetchにはサーバーが必要、モックデータを使用中)
マニフェストや公開の事実を実装の詳細の下に埋めないでください。
BAD/GOODの対比
BAD: ダッシュボードが通常APIからユーザーを読み込むため、fetch('/api/users')を配線する。
GOOD: data/users.jsonを埋め込み、目に見える「サンプルデータ」ラベルを付ける。API呼び出しなし。
BAD: Googleアナリティクス、フォント、3つのCDNライブラリを列挙せずに貼り付ける。 GOOD: 各依存関係はURLと目的を持つ元帳の行である。
BAD: 公開コマンドを実行せずに「https://demo.example.comにデプロイ」と言う。 GOOD: 公開URLはコマンド出力からコピーされるか、延期とマークされる。
BAD: CSS全体に散らばったインラインoklch()値、3つの異なるfont-family宣言。
GOOD: すべてのビジュアル値は:rootトークンブロックにあり、var()で参照される。
規約アーティファクト
folio.md(出力ディレクトリ、デフォルトホスト、CDN許可リスト、命名):オプトイン。references/folio-md.mdを読んでください。一度存在すると、ハウスデフォルトが優先されます。
プロジェクトごとのオプションレイアウト:
…
(翻訳のため一部省略)