`、並列項目は ``、処理・依存・構成はdiagramブロック、決定・前提・注意はplain textのcallout、レビューしてほしい論点は専用のレビュー観点blockにする。
+- `section`, `text`, `table` block typeは現行rendererに専用描画がないため、最終モデルでは使わない。
+- diagramブロックはMermaid sourceを構造保存用に残し、生成画像を主表示にする。sourceに無い関係や判断を画像側で追加しない。
+- 既存資料を取り込む場合も、既存ファイルをそのまま表示へ流し込まず、`visual-html-renderer` のHTML情報設計規約に従って文書モデルへ再構成する。
+- `build-model` は最終HTMLモデルを作るplannerではなく、入力退避用のsource-capture draftに限る。既存本文やユーザー指定内容を取り込む場合も、そのdraftをそのままrenderせず、agentが設計構造を判断して文書モデルを直接作る。
+
+## Design Document Model Rules
+
+This skill does not convert a `.md` draft into HTML. It designs a reviewable HTML bundle from the beginning. Store new models under `output/tmp//document-model.json` or `output/_/document-model.json`. If temporary natural-language input must be saved, use plain text filenames such as `source.txt`, `input.txt`, or `source-content.txt`. Use `heading_level: 2` for major sections and `heading_level: 3` for detailed subsections. Represent comparisons with tables, steps with ordered lists, parallel items with lists, commands and logs with code blocks, flows and dependencies with diagrams, and decisions or cautions with callouts.
+
+## レビューコメントへの対応
+
+ユーザーが「コメント入れた」「レビューした」「ingest review comments」「process review comments」「reply to review comments」「apply resolved comments」等でコメントの存在を知らせた時に開始する。文書作成（手順 1-10）とは独立したインタラクションであり、以下を毎回実行する。
+
+IMPORTANT: レビューコメントへの回答は、必ず `add-reply` CLI で HTML コメントスレッドに書き戻す。チャットだけで回答を返して終わりにしてはならない。チャットでは補足や次のアクション提案のみ行い、コメントへの実質的な回答は HTML 側に書く。
+
+### 手順
+
+1. `ingest-review` CLI でコメントを分類し、`annotations/review-cycle-state.json` に状態を保存する。`ingest-review` はコメントスレッドへ返信を書かない。
+2. 分類結果に関係なく、各コメントの `comment` と `selected_text` を読み、設計資料の該当箇所の文脈を踏まえてコメントの意図を理解する。
+3. 回答・受領・確認依頼が必要なコメントには、実質的な回答を `add-reply` CLI で HTML コメントスレッドに書き戻す。
+4. `actionable` なコメントは、解決待ちゲートが開いてから設計へ反映し、必要に応じて再 render する。
+5. ユーザーにブラウザでの確認を依頼する。
+
+### なぜチャット回答ではなく add-reply か
+
+- ユーザーはブラウザ上でコメントと回答をセットで読む。チャットに書いた回答は、コメントの文脈から切り離される。
+- 複数コメントがある場合、チャットでは各コメントへの回答の対応関係が崩れる。
+- HTML 上の回答はコメントスレッドに紐づいて永続化される。チャットの回答はセッション終了で消える。
+
+## Handling Review Comments
+
+Start this workflow when the user says comments were added or asks to `ingest review comments`, `process review comments`, `reply to review comments`, or `apply resolved comments`. Always run `ingest-review` to classify comments and write review-cycle state only, inspect each comment's `comment` and `selected_text`, write substantive answers with `add-reply` when a thread needs a response, and apply actionable feedback only when the review gates allow it. Do not answer only in chat; the durable answer belongs in the HTML comment thread.
+
+## コメント自動回答と解決待ちゲート
+
+preview server 起動後に必ず実行する。手順 11 で Monitor ツールによる `watch-comments` を起動し、以下のフローでコメントの自動検知・回答・解決待ちを行う。
+
+### watch-comments の起動
+
+preview server 起動後、以下で SSE イベント監視を開始する。
+
+```bash
+python3 -m scripts.html_review_workbench.cli watch-comments \
+ --root
+```
+
+agent は Monitor ツールでこのプロセスの stdout を監視する。各行は 1 行 JSON のイベント。
+
+### 自動回答フロー
+
+`watch-comments` から `comment_updated` イベントを受信したら:
+
+1. `ingest-review --root ` でコメントを分類し、状態だけを保存する。`ingest-review` の実行だけで返信が追加されることはない。
+2. `comment` と `selected_text` を読み、設計資料の文脈を踏まえて実質的な回答を作成する。
+3. 回答・受領・確認依頼が必要なコメントにだけ `add-reply --root --thread-id --body ""` で HTML コメントスレッドに書き戻す。
+4. 回答本文をコンソール（会話）にも出力する。ユーザーはブラウザとコンソールの両方で回答を確認できる。
+5. `actionable` コメントにはまだ設計変更を適用しない。回答で受領を伝え、スレッド解決後に反映する旨を書く。
+6. 自動回答が完了したら、設計変更には進まず停止する。`ingest-review` と `watch-comments` の出力に含まれる `gate` フィールドが `blocked` の場合、`document-model.json` を含むいかなる設計ファイルも変更してはならない。ゲートが `open` になるまで待機する。
+
+### 解決待ちゲート
+
+IMPORTANT: 未解決の `needs_clarification` スレッドがある間は、設計反映（ドキュメント修正）に進まない。
+
+修正判断の前に以下でゲートを確認する:
+
+```bash
+python3 -m scripts.html_review_workbench.cli check-gates \
+ --root
+```
+
+- `{"gate": "blocked", ...}` → 設計修正を行わない。コメントへの回答に専念する。
+- `{"gate": "open", "resolved_actionable": [...]}` → 解決済みの actionable スレッド内容を document model に反映してよい。
+
+### スレッド解決時の反映フロー
+
+ユーザーがスレッドを「解決」した `comment_updated` イベントを受信したら:
+
+1. `check-gates` でゲートが `open` であることを確認する。
+2. `resolved_actionable` の各スレッドについて、スレッド全体の議論を読み、修正が必要か判断する。
+3. 必要な修正を document model に適用する。
+4. `render` CLI で再生成する。
+5. `notify-update --root --message "コメント反映済み"` でブラウザに更新通知を送る。
+
+### 修正完了のブラウザ通知
+
+`notify-update` を実行すると、preview server 経由でブラウザに SSE イベントが送られ、画面上部にバナーが表示される。ユーザーは自分のタイミングでリロードして確認できる。自動リロードはしない。
+
+```bash
+python3 -m scripts.html_review_workbench.cli notify-update \
+ --root \
+ --message "コメント反映済み。リロードして確認してください"
+```
+
+## Automatic Comment Reply and Resolution Gate
+
+After preview startup, monitor browser comment events with `watch-comments`. On each `comment_updated` event, run `ingest-review`, identify clarification threads, write same-thread replies with `add-reply`, and avoid design edits while unresolved clarification threads remain. Before applying any document changes, run `check-gates`. Apply resolved actionable feedback to the document model, re-render, and use `notify-update` so the browser shows an update notice without forcing an automatic reload.
+
+## CodexでのCLI呼び出し
+
+HTML生成時は、`visual-html-renderer` と同じ共通CLI入口を使う。
+CLI実行前に、この `SKILL.md` の配置から renderer repo root を決める。
+`skills/reviewable-design-doc/SKILL.md` の2階層上が renderer repo root であり、
+そこに `scripts/html_review_workbench/cli.py` が存在することを確認する。
+すべての `python3 -m scripts.html_review_workbench.cli ...` は renderer repo root を
+作業ディレクトリにして実行する。現在のチャットやworkspaceのcwdをrepo rootとして扱わない。
+cwdに `scripts/html_review_workbench/cli.py` が無い場合は、代替HTMLを作らず、
+renderer repo rootへ移動してCLIを実行する。
+
+```bash
+python3 -m scripts.html_review_workbench.cli build-model \
+ --text "" \
+ --output
+
+python3 -m scripts.html_review_workbench.cli attach-image \
+ --model \
+ --block-id \
+ --image
+
+python3 -m scripts.html_review_workbench.cli check-model \
+ --model
+
+python3 -m scripts.html_review_workbench.cli render \
+ --model \
+ --output
+
+python3 -m scripts.html_review_workbench.cli validate \
+ --root
+
+python3 -m scripts.html_review_workbench.cli preview \
+ --root \
+ --mode auto
+```
+
+Codex / Claude では preview コマンドを一回限りの shell から起動することがあるため、標準手順では `--owner-pid` を渡さない。preview server は 24時間アクセスが無い場合に idle timeout で自動停止する。長寿命の所有プロセスが明確に分かる場合だけ `--owner-pid ` を使ってよい。一回限りの shell の `$$` や `$PPID` は短命プロセスを指すため使わない。
+
+Codex sandbox内で `tailscale ip -4` が設定ファイル読み取りに失敗する場合は、`visual-html-renderer` と同じく `python3 -m scripts.html_review_workbench.preview_host_resolve` で取得したIPv4を `HTML_REVIEW_WORKBENCH_TAILSCALE_IP` に渡してから `preview --mode auto` を起動する。
+
+`preview` が `status: running` を返した場合、レビュー依頼の最終応答に `url` を必ず含める。ファイルパスだけで完了しない。標準では `--owner-pid` を渡さず、24時間アクセスが無い場合に idle timeout で自動停止させる。長寿命の所有プロセスが明確な場合だけ `--owner-pid ` を使う。
+
+レビュー取り込み時は、最新のpreview sessionまたはユーザー指定の成果物rootから `annotations/comments.json` を読み込む。
+
+```bash
+python3 -m scripts.html_review_workbench.cli ingest-review \
+ --root
+```
+
+回答・受領・確認依頼が必要なコメントへagent replyを書き戻す場合は、`ingest-review` の分類結果から対象thread idを確認し、同じ成果物rootへ `add-reply` を実行する。
+
+```bash
+python3 -m scripts.html_review_workbench.cli add-reply \
+ --root \
+ --thread-id \
+ --body ""
+```
+
+document modelへ反映する場合は、完全一致置換に限定して明示的に実行する。
+
+```bash
+python3 -m scripts.html_review_workbench.cli ingest-review \
+ --root \
+ --model \
+ --apply-model
+```
+
+解決待ちゲートの確認:
+
+```bash
+python3 -m scripts.html_review_workbench.cli check-gates \
+ --root
+```
+
+コメント変更の SSE 監視（Monitor ツールで stdout を監視する）:
+
+```bash
+python3 -m scripts.html_review_workbench.cli watch-comments \
+ --root
+```
+
+ドキュメント更新通知をブラウザへ送信:
+
+```bash
+python3 -m scripts.html_review_workbench.cli notify-update \
+ --root \
+ --message "コメント反映済み"
+```
+
+## CLI Usage in Codex
+
+Use the same shared CLI as `visual-html-renderer`. Resolve the renderer repo root from this `SKILL.md`: two levels above `skills/reviewable-design-doc/SKILL.md`. Run every `python3 -m scripts.html_review_workbench.cli ...` command from that repo root. If the current workspace does not contain `scripts/html_review_workbench/cli.py`, move to the renderer repo root instead of creating fallback HTML. Use `ingest-review`, `add-reply`, `check-gates`, `watch-comments`, and `notify-update` for review cycles.
+
+## 完了時の確認
+
+- `index.html` と `renderer-manifest.json` が生成され、`validate` が `status: ok` を返している。
+- `check-model` が `status: ok` 相当の成功終了を返している。
+- preview有効時は、レビュー用URLをユーザーへ提示している。
+- レビュー取り込み後、`annotations/review-cycle-state.json` が生成されている。
+- 回答・受領・確認依頼が必要なコメントには、`add-reply` によりHTMLコメントスレッド上のagent replyが追加されている。
+- コメント反映でユーザー確認が必要な場合は、チャットだけでなくHTMLコメントへ返信済みであることを確認している。
+
+## 実シナリオ検証
+
+自動テスト pass と CLI の JSON 出力確認は、実シナリオ検証ではない。「動作確認」を求められた場合、以下のエンドツーエンドフローを実行する。
+
+### レビュー取り込み・返信の検証
+
+1. ユーザーが HTML 上にコメントを入れたことを確認する（ユーザーからの報告を待つ）。
+2. `ingest-review` で `comments.json` を取り込み、分類結果を読む。
+3. 各コメントの `comment` と `selected_text` を読み、設計資料の該当箇所の文脈を踏まえて、コメントの意図を理解する。
+4. 回答・受領・確認依頼が必要なコメントに対して、コメント内容に対する実質的な返答を考え、`add-reply` で HTML コメントスレッドに書き戻す。
+5. ユーザーに返信した旨を伝え、ブラウザで表示と内容の両方を確認してもらう。
+
+検証の完了条件: ユーザーがブラウザ上で agent の返信を読み、内容と表示の両方が意図通りであることを確認した時点。CLI が正しい JSON を返したことではない。
+
+## Real Scenario Verification
+
+Passing unit tests and receiving valid CLI JSON are prerequisites, not real scenario verification. For an operational check, the user must add a browser comment, the agent must ingest it, read `comment` and `selected_text`, write the actual answer with `add-reply`, and the user must confirm in the browser that both the reply text and display are correct.
+
+## ガード
+
+- 設計として未確定の内容は確定事項と分けて書く。
+- レビューコメント機能は必須で有効化する。
+- IMPORTANT: レビューコメントに回答する時は `add-reply` で HTML コメントスレッドに書き戻す。チャットで回答内容を述べただけでは回答完了にならない。
+- HTML低レベル実装をこのskillに重複実装しない。
+- IMPORTANT: `comments.json` を Edit ツールや直接のファイル編集で変更してはならない。コメントの追加・返信は必ず `add-reply` CLI 経由で行う。CLI はスキーマ検証を通すため、不正なデータがファイルに書き込まれることを防ぐ。
+
+## Guards
+
+Separate unresolved design ideas from confirmed decisions. Keep review comments enabled. When answering comments, use `add-reply` to write back into the HTML thread; a chat-only answer is not completion. Do not duplicate low-level HTML implementation inside this skill.
+
+IMPORTANT: Never edit `comments.json` directly with the Edit tool or any file-writing tool. All comment mutations must go through the `add-reply` CLI, which enforces schema validation and prevents malformed data from being written.
+
+### 禁止事項 / Prohibited Actions
+
+以下の操作は明示的に禁止する。違反するとデータ破損やレビュープロセスの破綻を引き起こす。
+
+1. `comments.json` を Edit/Write ツールで直接変更すること。reply の追加は `add-reply` CLI のみ。
+2. `check-gates` が `blocked` を返している状態で `document-model.json` を変更すること。
+3. `ingest-review` の出力に `"gate": {"gate": "blocked", ...}` が含まれている状態で設計変更に着手すること。
+4. `render` の stderr 警告を無視して次のステップに進むこと。
+
+The following actions are explicitly prohibited. Violations cause data corruption or review process breakdown.
+
+1. Editing `comments.json` directly with Edit/Write tools. Use `add-reply` CLI only.
+2. Modifying `document-model.json` while `check-gates` returns `blocked`.
+3. Starting design changes when `ingest-review` output contains `"gate": {"gate": "blocked", ...}`.
+4. Ignoring `render` stderr warnings and proceeding to the next step.
diff --git a/plugins/u-ichi/reviewable-html-workbench/skills/reviewable-design-doc/agents/openai.yaml b/plugins/u-ichi/reviewable-html-workbench/skills/reviewable-design-doc/agents/openai.yaml
new file mode 100644
index 00000000..07ef7191
--- /dev/null
+++ b/plugins/u-ichi/reviewable-html-workbench/skills/reviewable-design-doc/agents/openai.yaml
@@ -0,0 +1,26 @@
+display_name: Reviewable Design Doc
+short_description: レビュー可能な設計資料HTMLを作り、コメント反映まで扱う / Build review-ready HTML design docs.
+default_prompt: Create a reviewable design doc in HTML / 設計資料をレビュー可能なHTMLで作って
+trigger_examples:
+ - レビュー可能な設計資料
+ - 設計資料をHTMLで
+ - design doc
+ - reviewable design doc
+ - レビュー終わったので確認して
+ - コメントを反映して
+ - create a reviewable design doc
+ - make a design doc in HTML
+ - build a review-ready design document
+ - ingest review comments
+ - process review comments
+ - reply to review comments
+ - apply resolved comments
+entrypoint: python3 -m scripts.html_review_workbench.cli
+working_directory: plugin_root
+workflow:
+ - attach-image
+ - check-model
+ - render
+ - validate
+ - preview
+ - ingest-review
diff --git a/plugins/u-ichi/reviewable-html-workbench/skills/visual-html-renderer/SKILL.md b/plugins/u-ichi/reviewable-html-workbench/skills/visual-html-renderer/SKILL.md
new file mode 100644
index 00000000..b5d87707
--- /dev/null
+++ b/plugins/u-ichi/reviewable-html-workbench/skills/visual-html-renderer/SKILL.md
@@ -0,0 +1,289 @@
+---
+name: visual-html-renderer
+description: |
+ HTMLを最終成果物として生成・検証・プレビューしたい時に使う共通レンダラー。Use this shared renderer when the user wants content turned into a final, validated, previewable HTML artifact. 現行rendererの表現能力を前提にagentが文書モデルを直接設計し、表・リスト・コード・注記・図・生成画像を選んだHTML bundleとセッション限定のプレビューURLを提示する。Triggers: html出力して, HTMLにして, HTMLで出して, この内容をHTMLで出して, HTMLでプレビューして, HTMLレンダラー, HTML出力を共通化, 図示つきHTML, visual HTML renderer, render this as HTML, turn this into HTML, create an HTML preview, generate a visual HTML report, make this a reviewable HTML document, diagrammed HTML report。使用しない場面: Plan Mode 中の計画確認プレビュー、設計内容そのものの作成、Notion投稿だけ、既存HTMLの軽微な見た目修正だけ。Do not use for: Plan Mode proposal previews, creating the design content itself, Notion-only publishing, or minor visual tweaks to existing HTML.
+argument-hint: "[document-model.json] [--output output/_] [--preview auto|tailscale|local|off]"
+strict_procedure: true
+---
+
+# visual-html-renderer
+
+## 役割
+
+HTML出力系skillの共通レンダラーとして、個別HTML生成ロジックを置き換える。
+
+重い処理は `scripts/html_review_workbench/` のPython実装に委譲し、このskillは入力確認、呼び出し順、ガード、検証を担当する。
+
+## Role
+
+Use this skill as the shared renderer for HTML-output workflows. It replaces one-off HTML generation logic with a fixed flow: understand the requested content, design the document model, run the shared CLI, validate the bundle, and return a preview URL. Heavy implementation stays in `scripts/html_review_workbench/`; this skill owns input handling, workflow order, gates, and verification.
+
+Plan Mode 中の計画確認プレビューには、このskillを使わない。その場合は `plan-preview` を使い、一時HTML previewとして扱う。`visual-html-renderer` は通常の最終HTML成果物、レポート、レビュー可能な文書のbundle生成だけを担当する。
+
+Do not use this skill for Plan Mode proposal previews. Route those requests to `plan-preview`; this skill is only for final HTML artifacts, reports, and reviewable document bundles.
+
+## Strict procedure profile
+
+- Strictness: strict-procedure。HTML表現設計、文書モデルread-back、render、validate、preview URL提示までがこのskillの成果。
+- Hard gates: 外部サービス送信、画像生成、外部アップロード、shared state変更は該当する承認ゲートに従う。
+- Forcing function: rendererブロック対応表、render前自己レビュー、`check-model` CLI、Completion receipt。
+- Completion receipt: HTML表現設計、生成物、検証、preview、未実施層を最終応答に必ず含める。
+
+## 言語方針 / Language behavior
+
+Follow the language of the latest user request for progress updates, final responses, preview handoff text, and user-facing summaries. 日本語の依頼には日本語で、英語の依頼には英語で返す。入力本文や引用内容は、ユーザーが翻訳を求めない限り勝手に翻訳しない。HTML内の見出しや本文は、元資料の言語、ユーザーの指定、レビュー対象読者に合わせる。
+
+## 基本手順
+
+0. Plan Mode 中の計画確認プレビュー、`` の視覚確認、計画URLの追加が目的なら、このskillではなく `plan-preview` を使う。
+1. 文書モデルとレンダリングオプションを確認する。
+2. 文書モデルが未指定の場合は、直前の成果物またはユーザー指定内容を読み、HTML表現設計フェーズで構成を決める。
+3. 現行rendererのブロック型に合わせて、agentが `document-model.json` を直接作る。
+4. 一時的な入力退避が必要な場合だけ `build-model` で source-capture draft を作ってよい。ただし draft は最終モデルではないため、そのまま `render` へ渡さない。
+5. render前に `document-model.json` を読み返し、未再構成テキストの流し込みやrenderer非対応型の使用がないことを確認する。
+6. `image.generation_status=requested` のブロックがある場合は、`imagegen` skillで画像を生成し、`attach-image` CLIで文書モデルへ添付する。
+7. `check-model` CLIで最終render前の文書モデル品質を検査する。
+8. `render` CLIでHTML bundleを生成する。
+9. `validate` CLIでHTML、asset、comment schema、図・画像の非空を検証する。
+10. ユーザー向け最終HTMLでは既定で `preview` CLIを `--mode auto` で起動し、返却JSONの `url` と `stop_command` を最終応答に必ず書く。
+11. preview 起動直後に、Monitor ツールで `watch-comments` を開始する。これによりブラウザからのコメントを自動検知できるようになる。Monitor 起動コマンド: `python3 -m scripts.html_review_workbench.cli watch-comments --root `。自前の polling スクリプトではなく、この CLI を使うこと。イベント受信後の処理は `reviewable-design-doc` skill の「コメント自動回答と解決待ちゲート」セクションに従う。
+
+## Basic Workflow
+
+0. If the request is a Plan Mode proposal preview, `` visual check, or plan preview URL request, use `plan-preview` instead of this skill.
+1. Check the document model and rendering options.
+2. If no `document-model.json` is provided, inspect the user's content or the latest artifact and design the HTML structure yourself.
+3. Create the final `document-model.json` directly using the renderer-supported block types.
+4. Use `build-model` only as a source-capture draft when temporary input storage is needed; never pass that draft straight to `render`.
+5. Read back the model before rendering and confirm that raw or unsupported content was not dumped into the model.
+6. If image blocks request generation, use the `imagegen` skill and attach images with `attach-image`.
+7. Run `check-model`, then `render`, then `validate`, then `preview`.
+8. For user-facing artifacts, use `preview --mode auto` by default and include the returned `url` and `stop_command` in the final response.
+9. Start `watch-comments` immediately after preview startup so browser comments can be detected.
+
+## HTML情報設計の規約
+
+HTML出力はテキスト変換ではなく、最終HTML bundleの情報設計として扱う。
+
+- 入力本文の記号や行構造をそのまま表示へ流し込まない。
+- まず内容の意味、用途、読者、比較軸、時系列、依存関係、操作手順、注意点を読み取り、HTML上の表現を選ぶ。
+- 比較は表、手順は番号付きリスト、並列項目はリスト、注意・決定・前提はcallout、処理や依存関係はdiagramブロック、画面イメージや説明画像が有効な箇所はimageブロック、コマンドやログはコードブロックにする。
+- diagramブロックはMermaid sourceを構造保存用に残し、既定では生成画像を主表示にする。生成画像が未添付の場合だけMermaid fallbackを表示する。
+- 現行rendererのブロック型で表現が足りない場合、未再構成テキストへ戻さず、必要なブロック型やレンダリング拡張を検討する。
+- 一時入力ファイルが必要な場合も `.md` は使わない。`source.txt`, `input.txt`, `source-content.txt` のようなプレーンテキスト名を使う。
+- ユーザーへの進捗・最終報告では、`.md` やMarkdownという語をHTML出力の前提として扱わない。
+
+## rendererブロック対応表
+
+現行rendererで最終HTMLに使う表現は、実装上の描画挙動に合わせて選ぶ。
+
+| block type | rendererの扱い | contentに書くもの |
+|---|---|---|
+| `html` | HTML片をそのまま挿入する | agentが設計した ``, `
`, ``, ``, `` 等の構造化HTML |
+| `callout` | HTML escapeしてcallout表示する | 決定、注意、前提などの短いプレーンテキスト。HTMLタグは書かない |
+| `diagram` | Mermaid sourceを保存し、fallback previewまたは生成画像を表示する | `diagram_source` または `diagram.source` にMermaid source。sourceに無い関係を画像側で追加しない |
+| `image` | 添付済み生成画像を表示する | `image.prompt`, `image.alt`, `image.caption`, `image.source_path` |
+| `section` / `text` / `table` | 専用描画なし。通常段落へescapeされる | 最終HTMLモデルでは使わない。表は `html` block内の `` で表現する |
+
+`html` blockはraw insertされるため、外部入力をそのまま混ぜない。入力由来の文字列はagentが意味単位へ再構成し、必要な箇所だけescape済みHTMLとして入れる。
+
+## 見出し階層
+
+rendererは `` を文書タイトルに使う。本文ブロックの見出しは `heading_level` フィールドで制御する。
+
+| heading_level | HTML タグ | 用途 |
+|---|---|---|
+| `2` | `` | 章見出し。文書を大きく区切る上位セクション。読者が目次で選ぶ単位 |
+| `3` | `` | 節見出し。章の中を細分化するサブセクション |
+
+- `heading_level` は必須。`2`（章）または `3`（直前の章の配下の節）を指定する。
+- content 内に `` や `` を直接書かない。小見出しが必要な場合は `` を使う（renderer が content 内の見出しを自動シフトする）。
+
+## html block 内の HTML 品質
+
+`html` block の content に書く HTML は、セマンティックな構造を意識する。
+
+- 表は `
` に `` と `` を含め、ヘッダセルは `| ` または ` | ` にする。
+- 手順は ``、並列項目は ``、用語と説明の対は `` にする。
+- 長い本文は `` で段落分けし、` ` に流し込まない。
+- 強調は ` `（重要）と ``（ニュアンス）を使い分ける。
+
+## HTML表現設計フェーズ
+
+文書モデルを作る前に、agentは次を決める。
+
+- 読者と用途。
+- 章構成。文書全体を概要→各論→結論のような読み手を誘導する流れに分ける。どのブロックが章（`heading_level: 2`）でどのブロックが節（`heading_level: 3`）かを先に決める。1つの章に節が偏りすぎないようバランスを取る。
+- 主要な情報単位。
+- 比較軸、時系列、依存関係、操作手順、決定、前提、未決事項。
+- 各blockの `type`, `title`, `heading_level`, `content`, `review_required`。
+- 各 `heading_level: 2` ブロックの冒頭に、その章で扱う内容の文脈を示す導入段落を置く。
+- `html` block内で使う表、番号付きリスト、箇条書き、コードブロック、通常本文の構成。
+- 図示または画像が必要な箇所と、Mermaid sourceまたは生成画像prompt。
+
+入力がMarkdownや箇条書きで整理されていても、記号構造をそのまま変換しない。最終HTMLで読みやすい単位へ組み替えてから文書モデルにする。
+
+## HTML Information Design Rules
+
+Treat HTML output as information design for the final bundle, not as text conversion. Identify the audience, purpose, comparison axes, chronology, dependencies, steps, decisions, assumptions, and unresolved issues before writing the model. Use tables for comparisons, ordered lists for procedures, lists for parallel items, callouts for decisions or cautions, diagrams for flows and dependencies, images for useful visual explanations, and code blocks for commands or logs. Even when the input is Markdown or a list, restructure it into readable HTML blocks instead of mechanically converting the symbols.
+
+## 入力モデル未指定時の規約
+
+ユーザーが「html出力して」「HTMLにして」「HTMLで出して」「render this as HTML」「turn this into HTML」「create an HTML preview」「generate a visual HTML report」「make this a reviewable HTML document」「diagrammed HTML report」のように自然文で依頼し、`document-model.json` を指定していない場合も、このskillを発火させる。
+
+その場合は、次の順で入力を決める。
+
+1. ユーザーが明示した対象ファイル、本文、直前の成果物をHTML化対象にする。
+2. 対象が曖昧で、直前の成果物も特定できない場合だけ、短く確認する。
+3. 対象を特定できる場合は、確認で止めずにHTML表現設計フェーズへ進み、`output/tmp//document-model.json` または `output/_/document-model.json` を直接作る。
+4. 作成する文書モデルは `schema_version`, `document_id`, `title`, `generated_at`, `blocks` を必ず持つ。
+5. `image.generation_status=requested` のブロックがある場合は画像生成と `attach-image` を完了してから、`check-model` → `render` → `validate` → `preview` まで進める。
+
+`build-model` は最終HTMLモデルを作るplannerではない。入力を安全に保持する source-capture draft を作るだけで、Markdown表・リスト・コード等の機械変換や、内容に応じた表現選択は行わない。最終HTML出力では、agentがHTML表現設計フェーズで文書モデルを直接設計する。画像生成が外部サービス送信・機密情報・ユーザー承認を要する条件に当たる場合は、該当する承認ゲートに従う。設計判断、要求整理、レビュー観点の作成が主目的の場合は `reviewable-design-doc` を使う。
+
+## When No Input Model Is Provided
+
+Natural requests such as `render this as HTML`, `turn this into HTML`, `create an HTML preview`, `generate a visual HTML report`, `make this a reviewable HTML document`, and `diagrammed HTML report` should still trigger this skill. Use the explicitly named file, pasted content, or latest artifact as the HTML source. Ask only when the target cannot be identified. If the target is clear, proceed into HTML information design and create `output/tmp//document-model.json` or `output/_/document-model.json` directly.
+
+## render前自己レビュー
+
+`render` CLIを呼ぶ前に、文書モデルを読み返して次を確認する。
+
+- `heading_level: 2` のブロックが少なくとも1つある。`heading_level: 3` のブロックが最初の `heading_level: 2` ブロックより前に出現していない。
+- 各 `heading_level: 2` ブロックの content が導入段落で始まっている。
+- `html` block の `` に `` と `` がある。content 内に `` や `` を直接書いていない。
+- `html` blockが未再構成テキストを `` または ` ` だけで抱えていない。
+- 比較対象がある場合は、`html` block内の ` ` 等で比較軸を明示している。
+- 手順がある場合は、`html` block内の `` 等で順序を明示している。
+- 決定、前提、注意は `callout` または専用の `html` blockとして本文に埋もれないようにしている。
+- `callout` blockの `content` にHTMLタグを書いていない。
+- `section`, `text`, `table` block typeを最終モデルで使っていない。
+- `diagram` blockは有効なMermaid sourceを持ち、画像生成promptはsourceに無い事実を追加していない。
+- `image` blockは `source_path` が添付済みになるまで `render` しない。
+
+## Pre-render Self Review
+
+Before calling `render`, read the model back and confirm the heading hierarchy, introductory paragraphs, supported block types, table semantics, ordered steps, callouts, diagram sources, attached images, and absence of raw unstructured dumps. Do not render until requested images have been attached and unsupported block types have been removed.
+
+## 生成画像promptの規約
+
+- diagramブロックの生成画像は、Mermaid sourceのノード、ラベル、矢印方向、関係を保持する。sourceに無い事実、指標、関係、ブランド要素、装飾を追加しない。
+- diagramブロックではMermaid sourceを `assets/diagrams/*.mmd` に保存し、HTML上は生成画像を主表示にする。生成画像が未添付の場合だけMermaid fallbackを表示する。
+- imageブロックの生成画像は、白背景、十分な余白、資料向けの落ち着いた見た目、必要最小限の文字量を基本にする。
+- 画面イメージは実在スクリーンショットではなくmockupとして生成する。公式ロゴ、ブランド名、UIラベル、数値、根拠を入力に無い形で作らない。
+- 概念画像は直感理解の補助に限定する。事実関係、依存関係、数値、判断順を説明する場合はdiagramブロックを優先する。
+
+## CodexでのCLI呼び出し
+
+このskillは、低レベル実装へ直接importせず、共通CLIだけを呼ぶ。
+
+CLI実行前に、この `SKILL.md` の配置から renderer repo root を決める。
+`skills/visual-html-renderer/SKILL.md` の2階層上が renderer repo root であり、
+そこに `scripts/html_review_workbench/cli.py` が存在することを確認する。
+すべての `python3 -m scripts.html_review_workbench.cli ...` は renderer repo root を
+作業ディレクトリにして実行する。現在のチャットやworkspaceのcwdをrepo rootとして扱わない。
+cwdに `scripts/html_review_workbench/cli.py` が無い場合は、代替HTMLを作らず、
+renderer repo rootへ移動してCLIを実行する。
+
+```bash
+python3 -m scripts.html_review_workbench.cli build-model \
+ --text "" \
+ --output
+
+python3 -m scripts.html_review_workbench.cli attach-image \
+ --model \
+ --block-id \
+ --image
+
+python3 -m scripts.html_review_workbench.cli check-model \
+ --model
+
+python3 -m scripts.html_review_workbench.cli render \
+ --model \
+ --output
+
+python3 -m scripts.html_review_workbench.cli validate \
+ --root
+
+python3 -m scripts.html_review_workbench.cli preview \
+ --root \
+ --mode auto
+```
+
+Codex / Claude では preview コマンドを一回限りの shell から起動することがあるため、標準手順では `--owner-pid` を渡さない。preview server は 24時間アクセスが無い場合に idle timeout で自動停止する。
+
+Codex sandbox内で `tailscale ip -4` が設定ファイル読み取りに失敗する場合は、preview本体をsandbox内で起動したまま、IPだけを小さいresolverで先に取得して渡す。
+
+```bash
+python3 -m scripts.html_review_workbench.preview_host_resolve
+
+HTML_REVIEW_WORKBENCH_TAILSCALE_IP= \
+ python3 -m scripts.html_review_workbench.cli preview \
+ --root \
+ --mode auto
+```
+
+長寿命の所有プロセスが明確に分かる場合だけ `--owner-pid ` を使ってよい。一回限りの shell の `$$` や `$PPID` は短命プロセスを指すため使わない。
+
+ユーザーが明示的にプレビュー不要と言った場合、または自動テスト・fixture検証で副作用を抑える場合だけ `--mode off` を使う。ユーザー向け成果物では `--mode off` を既定にしない。
+成果物はユーザーが直接読む最終HTMLなら `output/_/`、再利用しない検証なら `output/tmp//` に置く。
+
+## CLI Usage in Codex
+
+Call only the shared CLI. Resolve the renderer repo root from this `SKILL.md`: two levels above `skills/visual-html-renderer/SKILL.md`. Run every `python3 -m scripts.html_review_workbench.cli ...` command from that repo root. If the current workspace does not contain `scripts/html_review_workbench/cli.py`, move to the renderer repo root instead of creating fallback HTML. Use `--mode off` only for explicit no-preview requests or tests; user-facing artifacts should default to `--mode auto`.
+
+## Preview URL提示とライフサイクル
+
+- `preview` が `status: running` を返した場合、最終応答に `url` を必ず含める。ファイルパスだけで完了しない。
+- `preview` が `status: off` または `status: failed` の場合、URLが無い理由を明示し、可能なら `--mode auto` で再実行してURL提示まで進める。
+- 標準では `--owner-pid` を渡さず、24時間アクセスが無い場合に idle timeout で自動停止させる。長寿命の所有プロセスが明確な場合だけ `--owner-pid ` を使う。
+- 手動停止が必要な時だけ、返却JSONの `stop_command` を使う。PIDなしで全previewを停止しない。
+
+## Preview URL and Lifecycle
+
+When `preview` returns `status: running`, include the `url` in the final response; a file path alone is not completion. If preview is off or failed, state the reason and try `--mode auto` when appropriate. Do not pass `--owner-pid` by default; the preview server stops after 24 hours without access. Use the returned `stop_command` only when manual cleanup is needed.
+
+## 完了時の確認
+
+- `index.html` と `renderer-manifest.json` が生成されている。
+- `validate` が `status: ok` を返している。
+- preview 有効時は提示URL、bind先、PID、停止方法をユーザーへ伝える。
+- preview は `0.0.0.0` にbindしていない。
+
+## 実シナリオ検証
+
+自動テスト pass と CLI の JSON 出力確認は、実シナリオ検証ではない。「動作確認」を求められた場合、以下を実行する。
+
+1. 実際の内容について `document-model.json` を作り、`render` → `validate` → `preview` を実行する。
+2. preview URL をユーザーに提示し、ブラウザで表示を確認してもらう。
+3. 表示に問題がある場合は、文書モデルを修正して再 render する。
+
+検証の完了条件: ユーザーがブラウザ上で最終 HTML の表示を確認した時点。`validate` が `status: ok` を返したことではない。
+
+## Real Scenario Verification
+
+Passing unit tests and receiving valid CLI JSON are prerequisites, not real scenario verification. When the user asks for an operational check, create a real `document-model.json`, run `render` -> `validate` -> `preview`, provide the preview URL, and have the user confirm the rendered HTML in the browser. Verification is complete only after the browser-visible result is accepted.
+
+## Completion receipt
+
+最終応答には次を含める。
+
+- HTML表現設計: 使用した主要block型と、その表現にした理由。
+- 生成物: `index.html` と `renderer-manifest.json` の場所。
+- 検証: `validate` の結果。
+- preview: URL、bind先、PID、`stop_command`。
+- 未実施: 画像生成、manual-acceptance-testing 等の未実施層があれば理由。
+
+Final responses must include: HTML design choices, generated `index.html` and `renderer-manifest.json` paths, validation result, preview URL/bind/PID/`stop_command`, and any unperformed verification layers with reasons.
+
+## ガード
+
+- レンダラーは内容判断を作らない。
+- 図示は入力された構造を補助する目的に限定する。
+- ブラウザを自動で開かない。URL提示までを責務とする。
+- Preview Runtime は `0.0.0.0` にbindしない。
+- 外部サービスへ投稿・アップロードする場合は別途承認ゲートを通す。
+
+## Guards
+
+The renderer does not invent content decisions. Diagrams only support the provided structure. Do not open the browser automatically; return the URL. Never bind Preview Runtime to `0.0.0.0`. Any external posting, upload, or service transmission requires the appropriate approval gate.
diff --git a/plugins/u-ichi/reviewable-html-workbench/skills/visual-html-renderer/agents/openai.yaml b/plugins/u-ichi/reviewable-html-workbench/skills/visual-html-renderer/agents/openai.yaml
new file mode 100644
index 00000000..fd17d764
--- /dev/null
+++ b/plugins/u-ichi/reviewable-html-workbench/skills/visual-html-renderer/agents/openai.yaml
@@ -0,0 +1,27 @@
+display_name: Visual HTML Renderer
+short_description: 図示つきHTML生成とPreview Runtimeを扱う共通レンダラー / Shared renderer for visual HTML previews.
+default_prompt: Create a visual HTML preview / 図示つきHTMLレポートを生成して
+trigger_examples:
+ - html出力して
+ - HTMLにして
+ - HTMLで出して
+ - この内容をHTMLで出して
+ - HTMLでプレビューして
+ - HTMLレンダラー
+ - HTML出力を共通化
+ - 図示つきHTML
+ - visual HTML renderer
+ - render this as HTML
+ - turn this into HTML
+ - create an HTML preview
+ - generate a visual HTML report
+ - make this a reviewable HTML document
+ - diagrammed HTML report
+entrypoint: python3 -m scripts.html_review_workbench.cli
+working_directory: plugin_root
+workflow:
+ - attach-image
+ - check-model
+ - render
+ - validate
+ - preview
| |