maestro/docs/tools/workspace-apps.md

ワークスペース・アプリの作り方（エージェント向け）

ユーザーから「ワークスペース・アプリを作って」「○○用の GUI を作って」などと頼まれたときの 手順です。専用ツールは不要 — edit: true の movement で Write/Edit を使って HTML を書く だけで成立します。

何を作るか

ワークスペースの apps/{name}/index.html に置く、自己完結した 1 枚の HTML（インライン JS/CSS、data: 画像のみ）。ユーザーはワークスペースの「アプリ」タブから「開く」で起動します。 アプリはサンドボックス iframe（opaque origin、allow-same-origin 無し）で動き、ファイル I/O は 親への postMessage ブリッジ経由のみです。

守るべき制約（重要）

• 外部ネットワーク禁止: default-src 'none'; connect-src 'none' の CSP が自動注入される。 外部 CDN・外部 API・別ファイルの <script src>・Web フォントは読み込めない。すべてインライン化する。
• 資格情報は渡らない: I/O は親がユーザーのセッションで代理する。ユーザーの権限を超えられない。
• パスはワークスペース相対: output/...・apps/{name}/data/... への書き込みは確認不要。 それ以外への書き込み・削除はユーザー確認が出る。..・絶対パスは拒否される。

ブリッジ API（要点）

// 一意 id を付けて postMessage、message イベントで応答を id 突き合わせ。
const { entries } = await call({ type: 'listFiles', dir: 'output' });   // 一覧
const { content } = await call({ type: 'readFile', path: 'output/x.md' }); // 読み取り
await call({ type: 'writeFile', path: 'output/note.md', content: '...' }); // 書き込み
await call({ type: 'deleteFile', path: 'output/old.txt' });             // 削除（常に確認）

完全なプロトコル・最小ヘルパー実装・応答形式は docs/workspace-apps-bridge.md を参照。

ひな型をコピーする

動くサンプルが docs/examples/workspace-apps/file-note/ にある（index.html ＋ app.json）。 output/ を一覧・閲覧し、メモを output/note.md に保存する自己完結アプリ。これを土台に、 依頼に合わせて改変して apps/{name}/index.html に Write するのが最短。

apps/{name}/app.json（任意）で一覧の表示名・説明・エントリを指定できる（無ければフォルダ名）。

仕上げ

• 書き込んだら、ユーザーに「アプリ」タブの「開く」で起動できることを一言伝える。
• アプリ名（フォルダ名）は内容が分かる短い英小文字＋ハイフンにする（例: invoice-gen）。