whiteboard（ホワイトボード）は何をしますか？

説明を、ユーザーが見て、保存して、どこにでも貼り付けられるダイアグラムに変換します。あなたがダイアグラムのソースを記述し、scripts/render.mjs がユーザーのローカルにインストールされたCLIを使ってレンダリングし、パースできない場合は何が問題かを正確に伝えます。

ワークフロー

ダイアグラムの種類と言語を選ぶ。 デフォルトはMermaidです。ネストされたコンテナを持つ大規模なアーキテクチャ図にはD2を使用し、ユーザーから指定があった場合やプロジェクトですでに使用されている場合のみPlantUMLを使用します。それぞれの構文については references/syntax.md を参照してください。
描く前に読む。 ダイアグラムがコードを説明する場合は、まずコードを読んでください。実際の名前を使って、存在するものを描きます。汎用的な図ではありません。プロジェクト全体のリクエスト（アーキテクチャ、制御フロー、データモデル）の場合は、references/modes.md に従ってください。
ソースを書いてレンダリングする。 短いタイトル（最大80文字）を付けて、標準入力からパイプで渡します。タイトルはファイル名になるので、同じダイアグラムを再描画するときは再利用します。
```
node <skill-dir>/scripts/render.mjs --title "チェックアウトのシーケンス" <<'EOF'
sequenceDiagram
  Browser->>API: POST /checkout
  API->>Payments: charge(card)
  Payments-->>API: ok
  API-->>Browser: 201 Created
EOF
```
<skill-dir> はこのファイルがあるフォルダです。これらの言語を使用する場合は、--language d2 または --language plantuml を追加します。Windowsの場合、またはヒアドキュメントが使いにくい場合は、ソースを一時ファイルに書き込み、代わりに --file <path> を渡します。
失敗した場合は修正して再実行する。 終了コード1はレンダラーがソースを拒否したことを意味します。メッセージに行番号が示されます。その行を修正し、同じコマンドを再度実行します。レンダリングされなかったダイアグラムをユーザーに渡さないでください。一般的な修正方法は references/syntax.md の最後にリストされています。
簡潔に報告する。 ダイアグラムが何を示しているか、そしてスクリプトが出力したファイルパス（例：diagrams/checkout-sequence.svg）を伝えます。ユーザーがREADME、Issue、Wikiに貼り付けたい場合は、フェンスで囲まれた ```mermaid ブロックでソースも提供します。GitHub、GitLab、Notion ではこれらがレンダリングされます。

スクリプトリファレンス

オプション	用途
`--title <text>`	必須。ファイルに名前を付けます：`diagrams/<slug>.svg` とその隣にソースファイルが作成されます。
`--language <name>`	`mermaid`（デフォルト）、`d2`、または `plantuml`。
`--file <path>`	標準入力の代わりにファイルからソースを読み取ります。
`--out <dir>`	出力フォルダ。デフォルトはカレントフォルダの `diagrams`。
`--png`	PNGも出力します（スライド、チャットアプリ、画像を表示するターミナル向け）。
`--theme <name>`	`default`、`neutral`、`dark`、または `forest`。
`--config <file>`	チームの色やフォント用のMermaid JSON設定ファイル。
`--check`	検証のみ。何も書き出しません。
`--open`	ユーザーのデフォルトビューアでSVGを開きます。ユーザーが今すぐダイアグラムを見たい場合に使用します。
`--share`	ソースをシークレット GitHub Gist にアップロードし、リンクを表示します。ユーザーが共有を明示的に依頼し、アップロードに同意した場合にのみ実行します。
`--json`	機械可読な結果を出力します。
`--doctor`	Node、各レンダラー、GitHub CLI をチェックし、インストールすべきものを表示します。

終了コード：0 レンダリング成功、1 ソース拒否（修正して再実行）、2 引数エラー、 3 レンダラーがインストールされていません。

ダイアグラムはローカルファイル、環境変数、URLを画像内に読み込むことはありません：

Mermaid は、ネットワークやディスクから何もロードできないサンドボックス化されたブラウザページでレンダリングされます。どのようなMermaid構文でも動作しますが、リモートやローカルの画像、CSSリソースは空白になります。画像を表示する必要がある場合は、data: URLとしてインライン化してください。
PlantUML：単純なディレクティブ（!define、!if、!procedure、!$var、 !theme <name>、!include <stdlib> …）以外のディレクティブ、%getenv や類似の組み込み関数、<img:…> は拒否されます。代わりにコンテンツをインライン化してください。
D2： @ インポートは拒否されます。アイコン、ブロック文字列、HTML、URLを含むダイアグラムはSVGとしてのみレンダリングされ、そこではリンクのままになります。

ユーザーが明示的にインクルードや外部画像を希望する場合にのみ、WHITEBOARD_ALLOW_INCLUDES=1 を設定して再実行してください。

同じタイトルで再描画すると、以前のファイルは diagrams/.versions/<slug>/<n>/ に保持されるため、ダイアグラムを繰り返し修正しても以前のバージョンが失われることはありません。

レンダラーがない場合

終了コード3はインストールコマンドを表示します。実行するコマンドをユーザーに伝え、ユーザーが依頼しない限り、あなた自身でグローバルパッケージをインストールしないでください：

Mermaid： npm i -g @mermaid-js/mermaid-cli
D2： brew install d2、または https://d2lang.com/tour/install を参照
PlantUML： brew install plantuml または apt install plantuml（Javaが必要）

レンダラーがインストールされているが見つからない場合（デスクトップアプリなど、ログインシェルのPATHなしで起動する場合によく発生します）、WHITEBOARD_MMDC、WHITEBOARD_D2、または WHITEBOARD_PLANTUML にフルパスを設定します。Mermaidのレンダリングは、mermaid-cliに付属のブラウザとMermaidバンドルを使用します。スクリプトが mmdc を見つけたがそのパッケージが見つからない場合は、WHITEBOARD_MERMAID_CLI_DIR を @mermaid-js/mermaid-cli フォルダに設定します。何もインストールできない場合は、Mermaidソースをフェンスで囲まれたブロックで提供してください。そうすればGitHub上でレンダリングされ、レンダラーでチェックされなかったことを伝えてください。

良いダイアグラムとは

1つのダイアグラムに1つのアイデア。約15ノードまたは20メッセージを超えるものは、概要図と詳細図に分割します。
すべてのエッジに、流れるものや発生するもの（HTTP、publishes OrderPlaced、1..*）をラベル付けします。
コードの名前を使用します：クラス名、モジュール名、サービス名、実際のエンドポイント、実際のテーブル。
質問に合ったタイプを選びます：時間の経過とともに誰が誰を呼び出すか → シーケンス図。何の部分があるか → アーキテクチャ/フローチャート。データがどのように見えるか → ER図またはクラス図。何かが時間とともにどのように変化するか → 状態遷移図。
ノード内のテキストは短く保ち、詳細はエッジのラベルやノートに記述します。

whiteboard（ホワイトボード）