feat: initial public release (MAESTRO)

2026-06-03 05:08:00 +00:00
commit f5c7666f6b
823 changed files with 184150 additions and 0 deletions
@@ -0,0 +1,68 @@
+---
+id: intro
+title: MAESTRO とは / できること
+category: basic
+order: 10
+keywords: [概要, できること, エージェント, piece, movement, はじめに]
+---
+
+## MAESTRO とは
+
+MAESTRO は、あなたの代わりにタスクをこなす **セルフホスト型の AI エージェント基盤** です。「やってほしいこと」を文章で依頼すると、AI エージェントが自律的に道具（ツール）を使って調べ、考え、ファイルを作り、結果を返します。
+
+LLM は Ollama / vLLM など OpenAI 互換 API に接続して動きます。クラウドに依存せず、自分たちのサーバー上で完結させられるのが特長です。
+
+このページでは、まず頭に入れておくと迷わない「考え方」と、何を頼めるかの全体像を紹介します。
+
+## 仕組みのイメージ
+
+難しい用語を抜きにすると、流れはこうです。
+
+1. **あなたがタスクを依頼する** — 例:「2026 年の AI トレンドを調べて output/report.md にまとめて」
+2. **piece（タスクの型）が選ばれる** — 依頼内容を見て、調査用・データ処理用・スライド作成用といった「やり方のテンプレート」が自動で割り当てられます。手動で指定することもできます
+3. **エージェントが loop を回す** — 「考える → ツールを使う → 結果を見る → また考える」を、タスクが終わるまで繰り返します
+4. **完了して結果が返る** — 最終回答と、生成されたファイルを受け取ります
+
+### piece と movement
+
+- **piece** は「このタスクをどう進めるか」を定義した型です。`research`（調査）・`office-process`（Office/PDF 処理）・`slide`（スライド作成）などがあります
+- **movement** は piece の中の「フェーズ」です。たとえば `brainstorming` は「分解 → 集約 → 検証」と複数の movement を順に進みます。各 movement では使えるツールが絞られ、終わると次の movement へ進むか、タスク全体を完了します
+
+この「piece が選ばれて、エージェントが movement を進めながらツールを使う」という形が MAESTRO の中核です。難しく考えず、**依頼を投げれば適切な進め方が選ばれる** とだけ覚えておけば十分です。
+
+piece の詳細や自作については [piece を使う・作る](./05-pieces.md) を参照してください。
+
+## 何を頼めるか（できることマップ）
+
+MAESTRO に頼める代表的な仕事です。
+
+| やりたいこと | 例 |
+|---|---|
+| 調査・リサーチ | Web 検索 + 一次情報の取得 + 出典付きレポート作成 |
+| データ処理 | CSV / JSON の集計・変換・フィルタリング |
+| Office / PDF 処理 | Excel・Word・PowerPoint・PDF の読み取り・加工・文書生成 |
+| スライド作成 | 再編集できる PowerPoint (.pptx) をゼロから生成 |
+| ブラウザ操作 | 認証済みセッションでのスクレイピング・自動入力 |
+| SSH オペレーション | リモートサーバーの稼働確認・設定配信・ログ取得 |
+| コーディング・ファイル作業 | コード生成・ファイル編集・スクリプト実行 |
+| SNS リサーチ | X・Reddit・Hacker News などの反応・評判の収集 |
+| アイデア出し | 複数視点で並列に検討して推奨方針を出す |
+
+これらは「依頼の文章」を見て自動で振り分けられます。何を作ってほしいか・どんな形式で欲しいかを具体的に書くほど、狙い通りの結果になります。
+
+エージェントが実際に呼べるツールの一覧は [ツール一覧](./16-tools.md) を参照してください。
+
+## はじめての一歩
+
+1. **タスクを作る** — 依頼内容を入力して実行します。書き方のコツは [タスクを作って実行する](./02-tasks.md) を参照
+2. **実行中を見る・口を出す** — エージェントの思考やツール呼び出しがリアルタイムに流れます。途中で指示を追加することもできます（[実行中のタスクを見る・介入する](./03-running.md)）
+3. **結果を受け取る** — 生成ファイルをプレビュー・ダウンロードし、出来栄えにフィードバックを返せます（[結果を受け取る](./04-results.md)）
+
+## こんなときは
+
+- **思った piece が選ばれない / 自分で固定したい** → [piece を使う・作る](./05-pieces.md)
+- **定期的に同じタスクを回したい** → [スケジュール実行](./06-schedules.md)
+- **エージェントの道具を増やしたい / 外部サービスと繋ぎたい** → [ツール一覧](./16-tools.md) ・ [MCP 連携](./13-mcp.md)
+- **うまく動かない・止まった** → [トラブルシューティング](./08-troubleshooting.md)
+
+まずは小さな依頼を 1 つ投げてみるのが、MAESTRO を理解する一番の近道です。
@@ -0,0 +1,85 @@
+---
+id: tasks
+title: タスクを作って実行する
+category: basic
+order: 20
+keywords: [タスク作成, piece選択, 添付, 詳細設定, 可視性, ask policy]
+---
+
+## 新しいタスクを作る
+
+タスク一覧の上部にある **「新しい Task」ボタン** を押すと、作成ダイアログが開きます。最低限必要なのは「依頼内容」だけです。
+
+### 依頼内容
+
+「依頼内容」テキストエリアに、エージェントへの指示を書きます。`Ctrl+Enter`（Mac は `Cmd+Enter`）で送信できます。
+
+書き方のコツ:
+
+- **何をしてほしいか** を最初の 1〜2 行で書く
+- **出力形式** を指定する（例:「output/report.md に Markdown で」「1500 字以内で」）
+- **観点・制約** を補足する（例:「主要 3 社を比較」「商用利用前提で」）
+- 参照すべき URL があれば添える
+
+依頼が曖昧だと、エージェントが確認を返して `waiting_human` で一時停止することがあります。
+
+### 添付ファイル
+
+ダイアログのドロップゾーンにファイルをドラッグ&ドロップ、またはクリックで選択して添付できます。添付したファイルはワークスペースの `input/` に保存され、エージェントが読み込めます。依頼文で「input のファイルを読んで」と明示すると確実です。
+
+## 詳細設定
+
+「詳細設定を開く」を押すと、次の項目を調整できます。
+
+### タスクタイプ（piece）
+
+`自動選択` のままにすると、依頼内容から最適な piece が自動で選ばれます。特定の piece で実行したいときだけ、ドロップダウンから選んで固定します。piece については [piece を使う・作る](./05-pieces.md) を参照。
+
+### プロファイル / 優先度
+
+- **プロファイル**: `auto` / `fast` / `quality` — どの種類のワーカーで実行するか
+- **優先度**: `low` / `medium` / `high` — ワーカーが拾う順番に影響します
+
+### 出力形式
+
+`markdown` / `text` / `json` から選べます。最終回答の形式の指針になります。
+
+### 質問ポリシー（ask policy）
+
+エージェントが不明点をどれくらい確認してくるかを決めます。
+
+- **low（少なめ）**: できるだけ自分で判断して進める（デフォルト）
+- **high（積極的に質問）**: 不明点があれば止まって確認する
+
+### MCP / Skills のトグル
+
+- **MCP ツールを無効化（トークン節約）**: このタスクでは外部サービス連携（MCP）のツールを使いません。詳しくは [MCP 連携](./13-mcp.md)
+- **Skills を無効化**: このタスクでは Skills を読み込みません。詳しくは [Skills を使う](./11-skills.md)
+
+どちらも、不要なツール定義を外してトークンを節約したいときに使います。
+
+### ブラウザセッション
+
+有効なブラウザセッションが登録されている場合のみ表示されます。選ぶと、エージェントがそのサイト用の保存済みログインを使ってブラウズします。
+
+## 公開範囲（可視性）
+
+作成したタスクを誰が見られるかを設定します。
+
+| 選択肢 | 見られる範囲 |
+|---|---|
+| 非公開 | 自分のみ（管理者は閲覧可） |
+| 組織 | 同じ組織（Gitea organization）のメンバー |
+| 公開 | ログイン済みの全ユーザー |
+
+「組織」は Gitea でログインしていて、所属組織がある場合のみ選べます。組織が複数あるときは共有先を選択できます。
+
+## 定期実行
+
+「定期実行」にチェックを入れると、毎日 / 毎週 / 毎月 / cron 式 / 一度きり の自動実行を設定できます。詳しくは [スケジュール実行](./06-schedules.md) を参照。
+
+## 作成したあと
+
+「Task 作成」を押すとタスクは `queued`（順番待ち）で登録され、ワーカーが拾うと数秒で `running`（実行中）に変わります。
+
+そこから先 — エージェントの動きをリアルタイムで見たり、途中で指示を追加したりする方法は [実行中のタスクを見る・介入する](./03-running.md) を参照してください。
@@ -0,0 +1,65 @@
+---
+id: running
+title: 実行中のタスクを見る・介入する
+category: basic
+order: 30
+keywords: [チャット, ストリーミング, ツールコール, 割り込み, interjection, ブラウザ, SSH, 進捗]
+---
+
+タスクが動き出すと、その様子をリアルタイムで観察でき、必要なら途中で口を出せます。
+
+## チャットで実行をリアルタイムに見る
+
+タスクを開くと中央に **チャットペイン** が表示されます。実行中はここに、エージェントの動きがライブで流れます。
+
+- **テキストのストリーミング**: エージェントが生成中の文章が、書かれるそばから表示されます（末尾にカーソルが点滅）。長いプロンプトを処理中のときは進捗バー（`Processing 〇〇%`）が出ます
+- **ツール呼び出し**: ツールを使うと、行としてインラインに表示されます。各行をクリックすると **args（引数）と result（結果）が展開** され、成功は ✓、失敗は ✕ で色分けされます。所要時間やキャッシュヒットも表示されます
+- **思考（thinking）ブロック**: エージェントの内部的な考えも、まとまりとして表示されます
+
+実行中はヘッダーに `running`（サブタスク待ちのときは `subtasks`）のバッジが点滅します。
+
+## 進捗・タイムラインで振り返る
+
+詳細パネルには時系列のビューもあります。
+
+- **進捗 / Activity**: 各ステップで何のツールをどんな引数で呼び、何を生成したかを時系列で確認できます
+- **タイムライン**: movement ごとにまとまった流れを追えます
+
+チャットが「会話の見え方」だとすれば、こちらは「作業ログの見え方」です。
+
+## 実行中に指示を追加する（割り込み / interjection）
+
+エージェントが動いている最中でも、メッセージを送って指示を追加できます。これを **割り込み（interjection）** と呼びます。
+
+### 送れるタイミング
+
+タスクが **`running`・`dispatching`・`waiting_subtasks`** のときに送れます。コンポーザー上部に「エージェント実行中 — メッセージで指示を送れます」と表示され、送信ボタンが **「割り込み」** に変わります（赤い「停止」ボタンと並びます）。
+
+### いつ効くか
+
+割り込みメッセージは **エージェントの loop の合間に注入** されます。つまり、いま生成している途中の応答を中断するわけではなく、**次の loop ステップの先頭で読まれて反映** されます。送ってすぐ反応がなくても、現在のステップが一区切りつけば取り込まれます。
+
+使いどころの例:
+
+- 「やっぱり対象を 3 社に絞って」と方針を修正する
+- 「output ではなく要約だけでいい」と成果物の形を変える
+- 追加の参考情報や URL を渡す
+
+なお、`dispatching`（ジョブ割り当て中）の一瞬は入力が一時的にロックされます。
+
+## 止める
+
+赤い **「停止」ボタン** を押すと、次のツール呼び出しのチェックポイントでエージェントが停止します。
+
+## ブラウザ・SSH の専用タブ
+
+タスクの種類によっては、実行中に専用タブが現れます。
+
+- **ブラウザ**: エージェントがブラウザ操作を行うと、ライブビュー（noVNC）でその画面をリアルタイムに見られます
+- **SSH（コンソール）**: SSH コンソールのセッションが開いているときに表示される端末です。AI と人間が同じ PTY を共有し、双方の入出力をリアルタイムに見られます。詳しくは [SSH 連携](./14-ssh.md) を参照
+
+## サブタスク待ち
+
+エージェントが並列の子タスクを起動すると、状態が `waiting_subtasks` になり、子タスクの進捗がまとめて表示されます。仕組みの詳細は [サブタスク](./10-subtasks.md) を参照してください。
+
+完了後にファイルや最終回答を受け取る方法は [結果を受け取る](./04-results.md) を参照してください。
@@ -0,0 +1,62 @@
+---
+id: results
+title: 結果を受け取る
+category: basic
+order: 40
+keywords: [ファイル, output, プレビュー, PDF, 印刷, ダウンロード, フィードバック]
+---
+
+タスクが完了すると、最終回答に加えて、エージェントが作ったファイルを受け取れます。
+
+## ファイルタブ
+
+詳細パネルの **ファイルタブ** で、ワークスペース内のファイルを閲覧できます。上部のセクション切り替えで 3 つの領域を行き来します。
+
+| セクション | 内容 |
+|---|---|
+| input | あなたが添付したファイル |
+| output | エージェントが作った成果物（主にここ） |
+| logs | 実行ログ（activity.log や Web 取得履歴など） |
+
+ファイル名をクリックするとプレビューが開きます。
+
+## プレビューする
+
+プレビューはファイル形式ごとに最適な表示になります。
+
+- **Markdown (.md)**: 整形表示。見出しから目次サイドバーが自動生成され、コードはハイライト、Mermaid 図も描画されます
+- **CSV**: 表として表示
+- **JSONL**: 1 行 1 レコードを表に整形（status / outcome などはバッジ表示）
+- **画像**: そのまま表示
+- **PDF**: 埋め込みビューアで表示
+
+output 配下の Markdown を編集できる場合は、プレビュー右上に **「編集」** ボタンが出ます。
+
+## Markdown を PDF にする
+
+Markdown ファイルのプレビューを開くと、右上に **「PDF / 印刷」ボタン** が表示されます。押すと整形済みの印刷用ページが新しいタブで開き、ブラウザの印刷ダイアログが自動で立ち上がります。
+
+ここで **送信先を「PDF に保存」** にすれば、レポートやドキュメントを PDF として書き出せます。そのまま印刷することもできます。
+
+ヒント: ボタンが反応しないときは、ブラウザのポップアップブロックを解除してください（新規タブを開いて印刷するため）。
+
+## ダウンロードする
+
+ファイルタブの各エントリからは、ファイルの実体をダウンロードできます。output に書き出された成果物（レポート・CSV・画像など）はここから手元に保存します。
+
+## フィードバックを返す
+
+タスクが `succeeded` または `failed` で終わると、概要（Overview）タブに **フィードバック** パネルが現れます。
+
+1. **👍 良かった** か **👎 改善が必要** を選ぶ
+2. 表示される **タグ** から当てはまるものを選ぶ（評価によって選択肢が変わります）
+   - 👍 例: 「出力の精度が高い」「フォーマットが適切」「指示をよく理解していた」「速度が適切だった」
+   - 👎 例: 「出力の精度が低い」「指示と違う結果になった」「不要な作業をしていた」「途中で止まった / ASK が多すぎた」
+3. 必要なら自由記述のコメントを添えて送信する
+
+送信後も「変更」から内容を編集できます。このフィードバックは、エージェントの振る舞いを良くしていくための入力になります。
+
+## 関連
+
+- 依頼の書き方で結果は大きく変わります → [タスクを作って実行する](./02-tasks.md)
+- 実行中の様子を見る・途中で指示する → [実行中のタスクを見る・介入する](./03-running.md)
@@ -0,0 +1,72 @@
+---
+id: pieces
+title: Piece を選ぶ・作る
+category: basic
+order: 50
+keywords: [piece, タスクタイプ, 自動分類, piece-builder, movement]
+---
+
+# Piece を選ぶ・作る
+
+Piece は「タスクの種類ごとの実行手順」を定義したものです。エージェントは選ばれた Piece に従って動くため、依頼内容に合った Piece が使われることが品質の鍵になります。
+
+## Piece とは
+
+1 つの Piece は **movement（フェーズ）の並び** で構成されます。各 movement には「使ってよいツール（`allowed_tools`）」「ファイル編集の可否（`edit`）」「次の movement への遷移条件（`rules`）」が定義されています。`allowed_tools` に載っていないツールは、その movement では LLM に一切提示されません。
+
+シンプルな Piece は単一 movement（例: `chat`）、調査系は「分解 → 集約 → 検証」のように複数 movement を持ちます。
+
+## Piece はどう選ばれるか
+
+タスク作成時に「タスクタイプ」を **auto** のままにすると、LLM ベースの分類器が依頼文と全 Piece の説明を見て、最適な Piece を 1 つ自動で選びます。手動で特定の Piece を指定することもできます。
+
+分類器の挙動（`piece-classifier`）:
+
+- **デフォルトは `chat`** — 特化型 Piece に明確に該当しない依頼はすべて `chat` で処理されます
+- 特化型 Piece が選ばれるのは、依頼が「スライド作成 → slide」「データ加工 → data-process」「構造化された調査レポート → research」「ブレスト → brainstorming」のように **強く** 該当する場合のみ
+- 迷ったときも `chat` が選ばれます
+- 各 Piece の `triggers.keywords` は分類の **ヒント** として渡されます（キーワード一致だけで確定はしません）
+
+意図しない Piece が選ばれるときは、依頼文を書き換えて狙いを明確にする（例:「ブレストして」と書く）か、手動でタスクタイプを指定してください。タスク作成の詳細は [タスクを作る](02-tasks.md) を参照。
+
+## ユーザー向け Piece カタログ
+
+| Piece | 何をするか |
+|---|---|
+| `chat` | 汎用デフォルト。質問・調査・コード生成・文書作成・データ処理など、特化型に該当しない依頼を 1 つの movement で処理する |
+| `general` | 汎用タスク実行。ファイル編集・コード生成・翻訳・文書作成など、主目的がファイル生成・編集のタスク。最後のフォールバックとしても機能する |
+| `research` | Web 検索やファイル読み込みによる情報収集と、収集情報の分析・構造化レポート作成。比較分析・トレンド調査・文献サーベイ向け |
+| `data-process` | CSV / JSON / TSV / SQL など構造化データの加工・集計・変換・フィルタリング |
+| `office-process` | Excel / Word / PowerPoint / PDF の読み取り・編集・変換・文書生成。売上集計・議事録作成・PDF 読み取りなど |
+| `slide` | pptxgenjs を使い、PowerPoint で再編集可能な .pptx をゼロから生成する。プレゼン・LT・提案資料向け |
+| `brainstorming` | 複数の視点から並列にアイデア・選択肢を検討し、推奨方針を導く |
+| `sns-research` | X (Twitter) / Reddit / Hacker News などの SNS から意見・評判・議論を収集してレポート化 |
+| `ssh-ops` | SSH 経由でリモートホストに単発オペレーションを実行（health check / config push / log fetch） |
+| `ssh-console` | 人間と AI が 1 つの PTY セッションを共有する対話的 SSH コンソール。長時間作業や TUI（vim / top / tmux / tail 等）向け |
+| `piece-builder` | Piece の設計・作成・編集を行う専用エージェント。「Piece を作って」「ワークフローを自動化したい」に対応 |
+
+`ssh-ops` / `ssh-console` は admin が `config.yaml` で SSH を有効化し、接続登録・grant が済んでいる場合のみ使えます。詳細は [SSH 連携](14-ssh.md) を参照。
+
+> このほか組織が独自に追加した Piece もここに加わります。利用可能なツールの一覧は [ツール一覧](16-tools.md) を参照。
+
+## カスタム Piece を作る（admin / パワーユーザー）
+
+### 方法 1: piece-builder に依頼する
+
+タスクを作成し、「○○用の Piece を作って」と書きます。`piece-builder` が選ばれ、要件をヒアリングしながら movement 構成・ツール選定・遷移ルールを設計して Piece を保存します。既存 Piece の改良で済む場合はそれを優先します。
+
+### 方法 2: Pieces ページで手動編集する
+
+admin は TopBar → Pieces から Piece の一覧・閲覧・新規作成・編集ができます。YAML を直接編集して保存すると `pieces/{name}.yaml` に反映されます。
+
+### 方法 3: 自分専用に fork する
+
+組み込み Piece を少しだけ変えたい場合、ユーザーフォルダ配下に同名の Piece を置くと、自分のタスクではそちらが優先されます。組み込み定義はそのまま残ります。
+
+## Piece を編集するときの勘所
+
+- `description` は分類器が読みます。「○○をする。選ぶべき場合: … / 選ぶべきでない場合: …」の形式が効きます
+- `instruction`（指示書）は長く書いて構いません。手順・避けるべきこと・終了方法を明示するとエージェントの動きが安定します
+- movement の開始時に、その movement の `allowed_tools` と 1 行サマリが自動で system prompt に注入されます。指示書にツール一覧を重複して書く必要はありません
+- 必要なツールは `allowed_tools` に列挙します。MCP ツールをまとめて許可するなら `mcp__*` を追加します
+- LLM が `allowed_tools` にないツールを呼ぶとエラーで弾かれます。その場合は Piece を編集してツールを追加してください（[困ったときは](08-troubleshooting.md) 参照）
@@ -0,0 +1,61 @@
+---
+id: schedules
+title: スケジュールで自動実行
+category: basic
+order: 60
+keywords: [スケジュール, 定期実行, cron, daily, weekly, タイムゾーン]
+---
+
+# スケジュールで自動実行
+
+決まった時刻にタスクを自動実行したいときは、スケジュールを登録します。「週次ニュースまとめ」「日次レポート生成」のような定期処理に向いています。
+
+## スケジュールを作る
+
+TopBar → スケジュール ページを開き、「新しいスケジュール」を押します。左がスケジュール一覧、右が詳細・編集ペインの 2 カラム構成です。
+
+入力する主な項目:
+
+- **種別** — Agent（LLM が Piece を実行）か Script（登録済みの user script を直接呼び出し、LLM 不要）
+- **タイトル** — 一覧での表示名（任意）
+- **プロンプト** — Agent の場合、エージェントに送るメッセージ（必須）
+- **Piece** — `auto`（LLM が自動選択）または特定の Piece を指定。[Piece を選ぶ・作る](05-pieces.md) 参照
+- **出力フォーマット** — markdown / plain / json
+- **タイプ**（スケジュール種別）と時刻
+- **公開範囲** — Private / Organization / Public（ログインユーザーのみ）
+
+保存すると一覧に追加され、次回実行予定時刻が表示されます。
+
+## スケジュールの 5 タイプ
+
+| タイプ | 設定する内容 |
+|---|---|
+| 毎日 (daily) | 時刻（時・分）を指定し、毎日その時刻に実行 |
+| 毎週 (weekly) | 曜日と時刻を指定 |
+| 毎月 (monthly) | 日付（1〜31）と時刻を指定 |
+| Cron | Cron 式（`分 時 日 月 曜日`）で柔軟に指定。例: `0 7 * * *` = 毎日 07:00 |
+| 一回 (once) | 指定した日時に 1 回だけ実行。実行後は自動で停止する |
+
+> **時刻はすべて UTC です。** 毎日 / 毎週 / 毎月 / Cron の時刻入力欄や一覧のプレビューは UTC 表記になります（一覧の「次回実行」表示は日本時間に変換されます）。一回タイプの日時指定だけはローカル時刻で入力します。日本時間 09:00 に動かしたい場合は UTC 00:00 を指定してください。
+
+毎日・毎週・毎月はプレビューに「毎日 07:00 (UTC)」のように換算結果が表示されるので、保存前に確認できます。
+
+## 重複実行はスキップされる
+
+スケジューラは約 1 分ごとに実行予定を確認します。実行時刻が来ても、**同じスケジュールの前回ジョブがまだ進行中**（queued / dispatching / running / waiting_human / waiting_subtasks のいずれか）の場合、その回はスキップされ、次回実行時刻だけが更新されます。長時間かかるタスクが二重に走ることはありません。
+
+## Agent と Script の違い
+
+- **Agent** — 通常のタスクと同じく、選ばれた Piece を LLM が実行します。`auto` を指定すると実行時に分類器が実 Piece を解決します（解決できないときは `chat` にフォールバック）。
+- **Script** — ユーザーフォルダの `scripts/` または `browser-macros/` に登録済みのスクリプトを LLM を介さず直接実行します。スクリプト名と、必要なら params（JSON object）を指定します。実行結果は output/ とログに保存されます。Script はユーザー単位の機能のため owner が必要で、管理者が user script を有効化している場合のみ動きます。
+
+## スケジュールの管理
+
+スケジュール ページの一覧から、各スケジュールに対して以下を操作できます。
+
+- **今すぐ実行** — 次回予定を待たずに即時トリガー
+- **停止 / 再開** — 一時的に無効化（停止中は実行されない）
+- **編集** — 内容・タイミングの変更
+- **削除**
+
+一覧上部のフィルタ（すべて / 有効 / 停止中）と検索で絞り込めます。タスクの作成全般は [タスクを作る](02-tasks.md) を参照してください。
@@ -0,0 +1,69 @@
+---
+id: notifications
+title: 通知を受け取る
+category: basic
+order: 70
+keywords: [通知, ブラウザ通知, Web Push, プッシュ通知, Service Worker, VAPID]
+---
+
+# 通知を受け取る
+
+タスクの開始・完了・失敗・回答待ちをブラウザ通知で受け取れます。通知は **自分が owner のタスクのみ** が対象です。設定は TopBar → 設定 → 通知 で行います。
+
+通知の仕組みは 2 種類あります。
+
+## V1: ブラウザ通知（前面表示）
+
+V1 は OS / ブラウザの Notification API を使う通知です。**タブが開いていてフォーカスがあるときのみ** 発火します（タブを閉じている・別アプリを見ているときは届きません）。
+
+### 有効化の手順
+
+1. 設定 → 通知 を開く
+2. 「ブラウザ通知を有効化」を押し、ブラウザの許可ダイアログで許可する
+3. 許可後に表示される「通知を受け取る (マスター ON/OFF)」で受信のオン・オフを切り替えられる
+4. 「テスト通知 (ページ内)」で動作確認できる
+
+許可をブラウザ側で拒否した場合は、アドレスバー左の設定アイコンから「通知」を許可に変更してください。状態は画面上に「有効化済み」「一時停止中」「ブラウザで拒否」「未許可」として表示されます。
+
+## V2: モバイル / バックグラウンド通知（Web Push）
+
+V2 は Service Worker と Web Push を使う通知です。**タブやブラウザを閉じていても** サーバーから直接プッシュが届きます。管理者が V2 を有効化している環境でのみ利用できます。
+
+### 購読の手順
+
+1. 設定 → 通知 を開く（V1 のマスター ON が前提）
+2. 「📱 モバイル / バックグラウンド通知 (V2)」セクションで「このデバイスで購読」を押す
+3. 購読中になると「✅ このデバイスで購読中」と表示され、購読デバイス一覧に端末が追加される
+4. 「テスト通知 (サーバー経由)」で動作確認できる
+
+デバイスごとに購読します。複数の端末・ブラウザから購読でき、一覧から個別に「解除」できます。「購読を解除」で現在のデバイスの購読を取り消せます。
+
+### プラットフォームの条件
+
+- **HTTPS が必須** です。V2 は HTTPS でホストされたサイトでのみ確実に動作します
+- **iOS Safari** では、まず「共有 → ホーム画面に追加」でアプリ（PWA）としてインストールし、ホーム画面のアイコンから開いた状態で購読する必要があります
+- Web Push API に対応していないブラウザでは V2 セクションに非対応の旨が表示されます
+
+## 通知するイベント
+
+V1・V2 共通で、以下のイベントごとに受信のオン・オフを切り替えられます。
+
+- タスク開始 (running)
+- タスク完了 (succeeded)
+- タスク失敗 (failed / aborted)
+- ユーザー回答待ち (waiting_human)
+
+これらのトグルはマスター ON のときのみ操作できます。
+
+## プライバシー: 詳細を含めるか
+
+V2 が利用できる環境では、「通知にタスクの詳細（タイトル・piece 名）を含める」トグルがあります。
+
+- **OFF（デフォルト）** — 「タスク #N 完了」のように最小限の内容のみ
+- **ON** — タスクのタイトルや piece 名を通知本文に含める
+
+共有端末やロック画面に出る通知の内容が気になる場合は OFF のままにしてください。
+
+## 管理者向けの設定
+
+V2（Web Push）の有効化には、サーバー側で `config.yaml` の `notifications.push.enabled: true` 設定と VAPID 鍵が必要です（鍵は初回起動時に自動生成されます）。サーバー側設定の概要は [設定](17-settings.md)、管理操作は [管理者向け](19-admin.md) を参照してください。
@@ -0,0 +1,63 @@
+---
+id: troubleshooting
+title: 困ったときは
+category: basic
+order: 80
+keywords: [トラブル, エラー, 失敗, waiting, スタック, 再試行]
+---
+
+# 困ったときは
+
+よくある状況とその対処をまとめます。解決しない場合は、ヘルプ画面の **「AI に聞く」** から help アシスタントに症状を伝えるか、管理者に問い合わせてください。
+
+## タスクが「回答待ち（waiting_human）」で止まっている
+
+エージェントが依頼の曖昧な点を確認したい、または作業を進めるために情報が必要なときに、この状態になります。
+
+**対処**: タスク詳細のチャットパネルに「エージェントからの確認」が表示されているので、**質問に回答を送る** とタスクが再開します。回答すべき内容が分からない場合は、不足している情報（対象ファイル・期待する出力形式など）を補足してください。
+
+なお、確認の回数には上限があり、上限に達すると回答待ちのままにはならず終了することがあります。その場合は、依頼文を具体化して新しいタスクを作り直すのが確実です。
+
+## タスクが「サブタスク待ち（waiting_subtasks）」で止まっている
+
+そのタスクが生成した子タスク（サブタスク）の完了を待っている状態です。
+
+**対処**: タスク詳細の **サブタスク タブ** で子タスクの一覧と状態を確認します。子タスクが失敗していれば、その失敗理由を確認して解消します。子タスクが進行中なら、完了すれば親タスクは自動で再開します。サブタスクの仕組みは [サブタスク](10-subtasks.md) を参照。
+
+## タスクが失敗した（failed）/ 再試行について
+
+タスクは失敗しても、設定された最大試行回数まで自動で再キューされて再実行されます。再実行時には前回の失敗内容が引き継ぎコンテキストとして渡され、同じ作業の重複を避けようとします。
+
+**対処**:
+
+- タスク詳細の概要・タイムラインでエラー内容を確認する
+- 入力ファイルや依頼文に問題があれば修正して新しいタスクを作る
+- 最大試行回数を使い切っても失敗し続ける場合は、依頼を分割するか、より能力の高いモデルでの実行を管理者に相談する
+
+## エージェントが「ログインを要求された」と返す
+
+タスク中のブラウザ操作（BrowseWeb）で、保存済みのログイン情報が期限切れになっているとこのメッセージが返ります。
+
+**対処**: 設定 → ユーザーフォルダ → ブラウザセッション で対象セッションを開き、「再ログイン」して保存し直します。詳しくは [ユーザーフォルダ](09-userfolder.md) を参照。ログイン情報（cookie）は時間が経つと失効するため、定期的なメンテナンスが必要です。
+
+## 成果物が output/ にあるはずなのに見えない
+
+**対処**:
+
+- タスク詳細の **Files タブ** で「output」セクションを選んでいるか確認し、リフレッシュでファイルツリーを再取得する
+- 大きすぎるテキストはプレビューが切り詰められることがあります。元ファイルはダウンロードして確認してください
+
+成果物の見方は [成果物を見る](04-results.md) を参照。
+
+## ログの場所
+
+調査の手がかりはログにあります。
+
+- タスクごとのアクティビティ・ダウンロード履歴などは、タスク詳細の **Files タブ → logs/** にあります（[成果物を見る](04-results.md) 参照）
+- サーバー全体のログは管理者が `scripts/server.sh logs` で確認できます。詳しく見たいときは `LOG_LEVEL=debug` で再起動します
+
+## 「AI に聞く」を使う
+
+ヘルプ画面の「AI に聞く」ボタンを押すと、help アシスタント（help piece）への質問タスクが作られます。MAESTRO の使い方・設定・エラーの意味など、画面の操作で迷ったときや原因の当たりを付けたいときに使ってください。
+
+具体的な操作手順の確認には [タスクを実行する](03-running.md) も合わせて参照してください。それでも解決しない場合は管理者に問い合わせてください。
@@ -0,0 +1,105 @@
+---
+id: userfolder
+title: User Folder（自分の資産）
+category: advanced
+order: 90
+keywords: [User Folder, AGENTS.md, notes, scripts, browser-macros, templates, browser-sessions]
+---
+
+# User Folder（自分の資産）
+
+User Folder は、ユーザーごとに永続化される個人の資産置き場です。エージェントへの恒久指示、共有メモ、自作スクリプト、ブラウザ自動化、ログイン済みセッションなどがここに集まり、タスクをまたいで「あなた仕様」のエージェントを作り込めます。
+
+TopBar → **ユーザーフォルダ** タブで開きます。左にサブフォルダのツリー、右にファイルエディタ（または専用パネル）という 2 カラム構成です。
+
+## サブフォルダ一覧
+
+| サブフォルダ | 役割 | 編集者 |
+|---|---|---|
+| AGENTS.md | タスク起動時に system prompt へ注入される恒久指示 | ユーザー |
+| notes/ | 共有可能な Markdown メモ（エージェントが検索・参照） | ユーザー |
+| scripts/ | 汎用 Node スクリプト（RunUserScript で実行） | ユーザー / エージェント |
+| browser-macros/ | Playwright ブラウザマクロ | ユーザー / エージェント |
+| templates/ | 定型文・雛形（`{{var}}` プレースホルダ） | ユーザー |
+| recordings/ | BrowseWeb の操作トレース（JSON） | エージェント |
+| pets/ | Chat 画面に表示するキャラクター | ユーザー |
+| browser-sessions/ | 保存済みログインプロファイル（cookie / storage） | ユーザー |
+| mcp/ | MCP サーバーの登録・接続管理 | ユーザー |
+| skills/ | スキル（参照知識・手順書）の管理 | ユーザー |
+| ssh-connections/ | SSH 接続定義・暗号鍵 | ユーザー |
+| Subscribed Notes | 他ユーザーが公開した notes の購読 | ユーザー |
+| trash/ | 削除ファイルの退避先（自動 cleanup） | 自動 |
+| memory/ | エージェントの永続事実置き場（UI からは閲覧のみ） | エージェント |
+
+## AGENTS.md
+
+毎タスクの system prompt 冒頭へ全文注入される、あなた専用の恒久指示です。トーン・口調・必ず守ってほしいルール・出力フォーマットの好みを書きます。
+
+例:
+
+```markdown
+- 回答は常に日本語、技術用語は英単語可
+- コードレビューは根拠を必ず示す
+- 出典が必要なときは URL を明記
+```
+
+設定方法:
+
+1. ユーザーフォルダ → **AGENTS.md**
+2. テキストエリアに記述
+3. 保存
+
+最大 64 KB。注入トークンを節約するため、詳細は memory/ に分散し AGENTS.md は短く保つのがコツです（→「[メモリと学習](12-memory.md)」）。
+
+## notes/
+
+他のエージェントや他ユーザーと共有したい情報を Markdown で書く場所です。visibility（公開範囲）を設定でき、エージェントは `SearchNotes` / `ReadNote` / `WriteNote` でアクセスします。notes はフォルダ階層を持てます（`notes/<folder>/<file>.md`）。
+
+## scripts/（汎用 Node）
+
+繰り返し処理を Node スクリプトとして保存します。エージェントは `RunUserScript`（kind: script）で実行します。Chromium は起動せず、`main({ params })` シグネチャです。データ整形・API 呼び出し・計算・ファイル変換などに向きます。
+
+作成方法:
+
+1. ユーザーフォルダ → **scripts** → 新規ファイルフォーム
+2. ファイル名（`.js`）と内容を入力 → 作成
+
+「○○するスクリプトを作って」とエージェントに頼むと自動生成されることもあります。
+
+## browser-macros/（Playwright）
+
+ログイン済みブラウザを使った Web 操作を自動化します。`RunUserScript`（kind: browser-macro）で実行され、`main({ context, params })` の `context` は Playwright の BrowserContext です。`session_profile_id` を指定すると保存済みログイン（browser-sessions/）を復元してから実行します。
+
+recordings/ の操作トレースから「Save as Script」でマクロ化することもできます。
+
+> scripts/ は外部 API を呼ぶ汎用処理、browser-macros/ は Web UI を操作する処理、と使い分けます。混ぜないこと。
+
+## templates/（定型文・雛形）
+
+`{{var}}` プレースホルダ付きの雛形です。エージェントは `ReadUserTemplate` で本文を読むか、`RenderUserTemplate` で frontmatter の `params` を埋めた結果を取得します。週次レポートや議事録など、定型フォーマットがあるタスクで効きます。
+
+## browser-sessions/
+
+CAPTCHA / 2FA を越えて取得した cookie / storage を user-scoped に暗号化保存します。browser-macros から `session_profile_id` で参照します。ログインは noVNC 画面でログイン → save の流れで行います。
+
+## mcp/ / skills/ / ssh-connections/
+
+- **mcp/**: MCP サーバーの登録・接続・ツール一覧取得。credentials は暗号化保存（→「[MCP 連携](13-mcp.md)」）
+- **skills/**: スキル（参照知識・手順書）の作成・URL インストール・編集。Settings → Skills と同じ画面（→「[Skills](11-skills.md)」）
+- **ssh-connections/**: SSH 接続の登録。秘密鍵は envelope encryption、ホストキーは TOFU で確認後に固定（→「[SSH 連携](14-ssh.md)」）
+
+## recordings/ / Subscribed Notes / trash/
+
+- **recordings/**: BrowseWeb 呼び出しで `recordTo` を指定すると、成功アクションがタスク終了時に JSON として書き出されます。「Save as Script」でマクロ化できます
+- **Subscribed Notes**: 他ユーザーが公開している notes を購読・発見します。inject モードは LLM コンテキストへ自動注入、search モードは `SearchNotes` で横断検索できます
+- **trash/**: 削除ファイルの退避先。ハードデリートはせず一定期間後に自動 cleanup されます。閲覧は read-only
+
+## memory/
+
+エージェントの永続事実置き場です。User Folder からは閲覧のみで、編集は Settings → メモリと学習 から行います（→「[メモリと学習](12-memory.md)」）。
+
+## ファイルの作成・編集
+
+- 作成できるのは **scripts / browser-macros / templates** の 3 つ（左ツリーで選択 → 新規ファイルフォーム）
+- 既存ファイルはツリーから選んでエディタで編集 → 保存
+- AGENTS.md・browser-sessions・mcp・skills・pets・ssh-connections・Subscribed Notes は専用パネルで操作します
@@ -0,0 +1,69 @@
+---
+id: subtasks
+title: サブタスクと並列実行
+category: advanced
+order: 100
+keywords: [サブタスク, SpawnSubTask, 並列, waiting_subtasks, research-sub, 分解]
+---
+
+# サブタスクと並列実行
+
+大きな仕事は、エージェントが複数のサブタスクに分解して並列実行できます。「5 社を比較調査して」のように独立した調査項目が並ぶタスクで効果的です。
+
+## どう動くか
+
+エージェントは `SpawnSubTask` ツールを呼んでサブタスクをキューに追加します。複数回呼べば複数のサブタスクが並列にスケジュールされます。各サブタスクには独立した専用ワークスペースが割り当てられ、別ジョブとして実行されます。
+
+サブタスクを 1 つ以上生成すると、親タスクは **waiting_subtasks** 状態に入ります。すべての子が完了すると親が再開し、子の成果をまとめて最終出力を作ります。
+
+ジョブの状態遷移については「[タスクの実行と監視](03-running.md)」を参照してください。
+
+## SpawnSubTask の引数
+
+| 引数 | 説明 |
+|---|---|
+| title | サブタスクのタイトル（簡潔に） |
+| instruction | 何を調査・実行し、どんな形式で `output/` に書くかの具体的な指示 |
+| piece | 使用するピース（省略時は `general`） |
+
+`piece` には `general` / `research` / `brainstorming` / `orchestrated` / `data-process` / `office-process` などを指定できます。指定したピースが見つからない場合はエラーになります。
+
+調査系のサブタスクには、専用ピース **research-sub**（dig → analyze → verify の 3 ステップ）が使われます。research-sub はそれ以上のサブタスク分解を行わず、調査をその場で完結させます。
+
+## サブタスクの確認
+
+タスク詳細の **サブタスク** タブで進捗を確認できます。
+
+- ヘッダーに「N/M 完了」のカウンタが出る
+- 各サブタスクはカード表示で、ステータス・出力ファイル・ログ・入力ファイルを開ける
+- Chat 画面ではインラインのサブタスクカードとして進捗が流れる
+
+各子は独立ワークスペースを持つため、成果物（`output/`）も子ごとに分かれて配信されます。
+
+## 待機中の入力（割り込み）
+
+親が waiting_subtasks の間でも、Chat 画面から親へメッセージを送れます（割り込み = interjection）。送ったメッセージは、エージェントが次のイテレーションで取り込みます。
+
+- 割り込みが効くのは **running** と **waiting_subtasks** の間
+- 入力欄がロックされるのはジョブ割り当て中（dispatching）のみ
+- 割り込みは親タスクに対して行われ、実行中の個々の子タスクには直接届きません
+
+## 分解の上限
+
+無限再帰や暴走を防ぐため、`config.yaml` の `subtasks` セクションで上限を設定します（キーはスネークケース）。
+
+```yaml
+subtasks:
+  max_depth: 2        # SpawnSubTask のネスト最大深度（デフォルト 2、0 で分解禁止）
+  max_per_parent: 10  # 1 ジョブが生成できるサブタスクの最大数（デフォルト 10）
+```
+
+- `max_depth: 0` にすると分解そのものを無効化できます
+- 深度上限に達したジョブでは SpawnSubTask が提示されず、エージェントは自力で処理します
+- `max_per_parent` を超える生成はできません
+
+## TIP
+
+> サブタスクは「独立して並列実行できる」項目に向きます。前の結果に依存する逐次処理は、1 つのタスク内の movement 遷移で扱う方が確実です（→「[ピースの仕組み](05-pieces.md)」）。
+
+> サブタスクへの instruction には、成果物を `output/` にどう書くかまで具体的に指定すると、親がまとめやすくなります。
@@ -0,0 +1,76 @@
+---
+id: skills
+title: Skills（スキル）
+category: advanced
+order: 110
+keywords: [Skills, スキル, インストール, Git URL, ReadSkill, per-task]
+---
+
+# Skills（スキル）
+
+スキルは、エージェントが必要に応じて読み込む **参照知識**（手順書・ガイド・規約）です。「この API はこう叩く」「このレポートはこの体裁で書く」といった再利用可能なノウハウを 1 つにまとめておけます。
+
+## スキルとピースの違い
+
+スキルとピース（→「[ピースの仕組み](05-pieces.md)」）は役割が違います。
+
+| | スキル | ピース |
+|---|---|---|
+| 何か | 参照知識・手順書 | タスクの種類（実行テンプレート） |
+| 役割 | エージェントが読んで参考にする | movement の流れと使えるツールを定義 |
+| エージェントの操作 | `ReadSkill` で全文取得 / `ListSkills` で一覧 | piece 自体がワークフローを駆動 |
+
+スキルは「知識」、ピースは「進め方」と覚えてください。
+
+## エージェントからの利用
+
+利用可能なスキルは、movement 開始時に system prompt の **Skills Index** として一覧注入されます。エージェントは概要を見て「これは使える」と判断したら `ReadSkill({ name })` で全文を読み込みます。`ListSkills` で一覧、`InstallSkill` でタスク中に新規インストールもできます。
+
+## スキルの追加（Settings → Skills）
+
+Settings → **Skills**（またはユーザーフォルダ → skills）で管理します。2 カラムの list + detail 構成です。
+
+### 手動作成
+
+1. **+ New Skill**
+2. **Name**: 小文字英数字・ハイフン・アンダースコアのみ
+3. **Content**: SKILL.md の全文（frontmatter + 本文）
+4. **Scope**: Personal（個人）/ System（全ユーザー共有、admin のみ）
+5. **Create**
+
+### URL からインストール
+
+左パネル上部の「Install from URL...」に Git URL を入力 → **Install**。個人スコープ（user）でインストールされます。
+
+### 編集・削除
+
+一覧から選ぶと右に詳細（説明・トリガー・本文・セキュリティ検査結果）が出ます。**Edit** / **Delete** で更新できます。system スコープのスキルは admin のみ編集可能です。
+
+## セキュリティ検査
+
+インストール・作成時にスキル内容がセキュリティスキャンされます。
+
+- **HIGH** の検知があると **ブロック**（インストール不可）
+- **MEDIUM** は警告付きで通過
+- 詳細画面に検知行（パターン・該当箇所）が表示されます
+
+## スキルをタスク単位で無効化
+
+タスク作成ダイアログ（→「[タスクの作り方](02-tasks.md)」）に **「Skills を無効化」** チェックがあります。
+
+- ON にすると、そのタスクでは Skills Index を注入しません
+- スキルが不要なタスクでトークンを節約したいときに使います
+
+## 上限
+
+スキルにはサイズ・件数の上限があります（`config.yaml` の `skills` セクション、未指定時はデフォルト値）。
+
+| 項目 | デフォルト |
+|---|---|
+| 個人スキル数 | 50 |
+| スキル本文サイズ | 64 KB |
+| ディレクトリ形式の合計サイズ | 5 MB |
+| system スキル数 | 100 |
+| Skills Index の最大文字数 | 2000 |
+
+ディレクトリ形式（`scripts/` などを含む）のスキルは、ファイル数 100・階層 3 段までという追加制限があります。
@@ -0,0 +1,81 @@
+---
+id: memory
+title: メモリと学習
+category: advanced
+order: 120
+keywords: [メモリ, memory, MEMORY.md, 学習, Memory & Learning]
+---
+
+# メモリと学習
+
+エージェントは、ユーザーごとの **メモリ** を保持します。あなたの好み・役割・プロジェクトの文脈・参照資料を覚えておくことで、毎回ゼロから説明しなくても「あなたを理解した」状態で動けます。
+
+## メモリの構造
+
+メモリは `data/users/{userId}/memory/` 配下に置かれ、2 つの要素で構成されます。
+
+### MEMORY.md（インデックス）
+
+エントリの一覧（description 行のリンク集）です。**タスク起動時に system prompt へ自動注入**されます（注入サイズには上限あり）。エージェントは、まず一覧で「何を覚えているか」を把握します。
+
+### 個別エントリ（{name}.md）
+
+1 ファイル = 1 エントリ。frontmatter（name / type / description）+ 本文の構造です。本文はインデックスには載らず、エージェントが必要に応じて `ReadUserMemory` で読み込みます。
+
+## メモリの 4 タイプ
+
+| type | 用途 |
+|---|---|
+| user | あなた固有の好み・役割 |
+| feedback | 過去のフィードバック・教訓 |
+| project | プロジェクト別の文脈 |
+| reference | 参照資料・外部情報 |
+
+## どう使われるか
+
+エージェントは毎セッションで MEMORY.md のインデックスを参照し、関連しそうなエントリを `ReadUserMemory` で開いて作業に反映します。書き込みは `UpdateUserMemory` ツールで行われ、「これは覚えておくべき」と判断した内容を自動で記録します。
+
+手動で書いたメモリは Reflection が動いていなくても確実に注入されるため、「いつも忘れられる」と感じる指示はメモリに 1 件書くのが確実です。
+
+## メモリの閲覧・編集（Settings → Memory & Learning）
+
+Settings → **メモリと学習** で管理します。2 つのパネルが縦に並びます。
+
+### メモリエントリ
+
+- 既存エントリの一覧（name・type バッジ・概要・本文プレビュー）
+- **+ 新しいエントリ** で追加。編集モーダルで以下を入力:
+  - **名前**（新規時のみ。英数字・ハイフン・アンダースコア）
+  - **概要**（一覧に出る 1 行説明）
+  - **タイプ**（user / feedback / project / reference）
+  - **本文**（Markdown またはプレーンテキスト）
+- 各行の **編集** / **削除** ボタンで更新
+
+メモリは User Folder の memory/ タブからは閲覧のみで、編集はこの画面で行います（→「[User Folder](09-userfolder.md)」）。
+
+### Reflection タイムライン
+
+自動学習（Reflection）の実行履歴です。各行を展開すると、推論・変更前後の差分・revert コントロールを確認できます。
+
+- バッジ: `N mem`（メモリ変更数）/ `piece`（piece 編集あり）/ 結果（適用済み・一部適用・学習なし・却下・失敗）
+- **revert**: 気に入らない変更はスナップショット単位で変更前に戻せる
+- 下部に 30 日間のサマリ（合計実行回数・適用率・学習なし率・Tokens・Piece 編集数）
+
+## Reflection との関係
+
+メモリエントリは、手動だけでなく **Reflection（自動学習）** によっても追加・更新されます。タスク完了後に専用ワーカーが振り返り、メモリ更新を提案します。完全自動 apply はデフォルト OFF です。
+
+仕組み・有効化・rejection の詳細は「[自動学習（Reflection）](18-reflection.md)」を参照してください。
+
+## メモリと AGENTS.md の使い分け
+
+User Folder の AGENTS.md（→「[User Folder](09-userfolder.md)」）は全文が毎回注入される固定の恒久指示、メモリはインデックスのみ注入し本文は必要時に読む構造です。
+
+- **AGENTS.md**: 短く要約された必須ルール・トーン・出力フォーマットの好み
+- **メモリ**: 個別の人物・プロジェクト・経験的に得た知見（数を増やせる）
+
+## TIP
+
+> 「いつも忘れられる」と感じたら、その情報を 1 件メモリに書いて 2〜3 回タスクを回す。手動メモリは Reflection の有無に関わらず確実に注入される。
+
+> メモリが増えすぎてインデックスが肥大化したら、不要なエントリは削除する。注入トークンの節約になる。
@@ -0,0 +1,112 @@
+---
+id: mcp
+title: MCP サーバー連携
+category: advanced
+order: 130
+keywords: [MCP, Model Context Protocol, サーバー, ツール連携, 外部連携]
+---
+
+## MCP 連携でできること
+
+MCP (Model Context Protocol) は、外部サービスのツールをエージェントに開放するための標準プロトコルです。MCP サーバーを登録すると、そのサーバーが提供するツールが `mcp__<serverId>__<toolName>` という名前でエージェントに見えるようになり、タスク実行中に呼び出せます。
+
+たとえば Gmail / Google Calendar / Drive / Notion / Canva などの MCP サーバーを登録しておくと、これらのアクションをエージェントのタスクから直接実行できます。
+
+## サーバーを登録する
+
+登録方法は 2 経路あります。
+
+- 個人用: TopBar → ユーザーフォルダ → MCP サーバー タブ → 「+ 追加」。`owner_id` が自分にセットされ、他のユーザーからは見えません。
+- 全体共有 (admin): admin が同じ画面の「全体のサーバー」セクションから登録すると、組織全員が使えます。
+
+登録時に入力する主な項目:
+
+- id / name: 識別子と表示名 (例 `gmail` / `Gmail`)
+- URL: MCP サーバーのエンドポイント
+- 認証方式: OAuth または API key
+
+### 認証方式
+
+| 方式 | 用途 | 特徴 |
+|---|---|---|
+| OAuth | ユーザー権限で動くサービス (Google 系・Notion・Canva 等) | ユーザーごとに token を持つ。登録後に「連携」ボタンでブラウザ認証 |
+| API key | 共通アカウントで OK なサービス | 静的トークンを 1 度登録すれば全員が使える |
+
+### 通信方式について
+
+現行実装の MCP クライアントは HTTP ベースの transport (Streamable HTTP) で MCP サーバーに接続します。サーバー側はこの方式に対応した URL を提供してください。ローカル subprocess を起動する stdio transport は現時点では未対応です。
+
+## MCP_ENCRYPTION_KEY が必須
+
+MCP サブシステムは、サーバー起動時に環境変数 `MCP_ENCRYPTION_KEY` が設定されている必要があります。token や API key の暗号化に使われ、未設定だと MCP 機能全体が無効化されます。
+
+```bash
+export MCP_ENCRYPTION_KEY="$(openssl rand -base64 32)"
+```
+
+機密値なので `config.yaml` ではなくデプロイ環境の環境変数で渡してください。
+
+## Piece への露出 (依存ゲーティング)
+
+エージェントが MCP ツールを呼べるのは、その Piece の `allowed_tools` に `mcp__*` ワイルドカードが入っている場合だけです。
+
+```yaml
+allowed_tools:
+  - Read
+  - WebSearch
+  - 'mcp__*'          # 全 MCP ツールを許可
+```
+
+特定サーバーだけ許可したい場合は接頭辞で絞ります。
+
+```yaml
+allowed_tools:
+  - 'mcp__gmail__*'   # Gmail サーバーのツールのみ
+```
+
+汎用の chat piece はデフォルトで `mcp__*` を含むため、通常のチャットタスクからは自動で MCP ツールを使えます。Piece の `allowed_tools` の考え方は [piece を使う・作る](./05-pieces.md) を参照してください。
+
+### タスク作成時の連携チェック
+
+タスク作成時、選んだ Piece が必要とする MCP サーバーにまだ連携していない場合は警告が表示され、その場で連携できます。未連携のまま作成すると、タスクは連携待ちで停止し、連携完了後に再開します。
+
+## タスクごとに MCP を無効化する
+
+MCP ツールの定義は LLM への送信トークンを消費します。MCP を使わないタスクでは、タスク作成ダイアログの
+
+> MCP ツールを無効化 (トークン節約)
+
+チェックボックスを ON にすると、そのタスクでは MCP ツールが一切提示されません。トークン節約や挙動の単純化に有効です。タスク作成の詳細は [タスクを作って実行する](./02-tasks.md) を参照してください。
+
+## ランタイム設定 (admin)
+
+MCP の動作に関わる共通設定は 設定 → MCP & Connections → MCP Runtime にあります (admin 専用)。`config.yaml` では `mcp` セクションに対応します。
+
+| 設定キー (snake_case) | 意味 | デフォルト |
+|---|---|---|
+| `call_timeout_seconds` | 1 回の MCP ツール呼び出しの最大時間 (秒) | 60 |
+| `tool_cache_ttl_seconds` | サーバーから取得したツール一覧のキャッシュ時間 (秒) | 600 |
+| `oauth_pending_ttl_minutes` | OAuth 認可フローの pending 保持時間 (分) | 10 |
+| `max_binary_size_mb` | バイナリ出力 1 ファイルの最大サイズ (MB) | 20 |
+| `max_output_files_per_job` | 1 ジョブで保存できるバイナリ出力数 | 10 |
+| `max_output_size_mb_per_job` | 1 ジョブのバイナリ出力合計上限 (MB) | 200 |
+| `allow_private_addresses` | private 網に置いた自前 MCP サーバーへの接続を許可 | false |
+
+設定画面の詳細は [設定](./17-settings.md) を参照してください。
+
+## 生の MCP レスポンスはログに残る
+
+MCP ツール呼び出しの生レスポンスは、各ジョブのワークスペース配下に保存されます。
+
+- `logs/mcp/{serverId}/{toolName}-{timestamp}-{hash}.json` — 個別レスポンスの全文
+- `logs/mcp-history.jsonl` — 1 行サマリの追記ログ
+
+デバッグや監査の際にこれらを確認できます。
+
+## トラブルシューティング
+
+- ツールが見えない: 未連携 (OAuth)、`MCP_ENCRYPTION_KEY` 未設定、または Piece の `allowed_tools` に `mcp__*` が無い、のいずれか
+- private IP / localhost への接続が拒否される: SSRF チェックによるもの。自前サーバーなら `mcp.allow_private_addresses: true` で許可
+- OAuth token の期限切れ: 該当サーバーを再連携する
+
+より詳しい仕様は `docs/mcp.md` を参照してください。
@@ -0,0 +1,86 @@
+---
+id: ssh
+title: SSH リモート操作
+category: advanced
+order: 140
+keywords: [SSH, リモート, exec, アップロード, コンソール, PTY, デプロイ]
+---
+
+## SSH でできること
+
+MAESTRO は、エージェントが SSH 経由でリモートホストを操作するための 2 つの仕組みを持ちます。どちらも admin が有効化し、接続を登録してから使います。
+
+| 仕組み | 用途 | 対応 piece |
+|---|---|---|
+| ssh-ops | 単発コマンド実行・ファイル転送 (health check / config push / log fetch) | `ssh-ops` |
+| ssh-console | 対話的な PTY シェル (vim / tmux / tail など長時間作業) | `ssh-console` |
+
+いずれもデフォルトでは無効です。admin が `config.yaml` で有効化し (`ssh.enabled: true`、コンソールは加えて `ssh.console.enabled: true`)、SSH 接続を登録したうえでジョブの所有者に grant を付与する必要があります。詳しくは [管理者ガイド](./19-admin.md) を参照してください。
+
+## ssh-ops: 単発実行とファイル転送
+
+`ssh-ops` piece は次の 3 軸をカバーする ops 向け piece です。
+
+- Health check: `uptime` / `df -h` / `free -m` / プロセス状態 / `journalctl` などで状態を確認
+- Config push: ローカルで作った設定を `SshUpload` で配信し、`SshExec` でリロード
+- Log fetch: `SshDownload` でリモートのログを取得し、ローカルで grep / 集計 / 分析
+
+使うツール: `SshExec`(単発コマンド) / `SshUpload` / `SshDownload` / `SshListConnections`。結果は `output/report.md` にまとめられます。機密値はコマンド文字列に直接書かず、レポートにも記録しません。
+
+リモートへの書き込みは接続ごとの `remote_path_prefix` 配下に限られ、違反は `path_not_allowed` で拒否されます。出力が大きすぎてコマンド結果が `truncated` になる場合は、`SshDownload` でファイル経由に切り替えます。
+
+## ssh-console: 対話的な PTY シェル
+
+`ssh-console` piece は、AI と人間が共有する 1 つの PTY セッションをタスクに開きます。両者がコマンドを打ち、同じ画面出力を見られます。次のようなケースに向きます。
+
+- ログを tail しながらの作業
+- vim / top / less / tmux など TUI が必要な操作
+- 複数ラウンドにわたる対話的な調査
+
+使うツール (3 つ):
+
+- `SshConsoleEnsure` — セッションを開く (冪等)
+- `SshConsoleSend` — キー入力を送る (`\n` 改行、`\x03` Ctrl-C などの制御文字も送れる)
+- `SshConsoleSnapshot` — 現在の画面 / scrollback を取得
+
+ファイル転送 (`SshUpload` / `SshDownload`) は SFTP 経路で動き、PTY セッションとは独立しています。設定を置いてからコンソールでリロードコマンドを送る、といった組み合わせが可能です。
+
+コンソールはアイドルや最大時間で自動クローズされます (既定でアイドル 30 分、最大 4 時間)。
+
+### コンソールを開く・見る
+
+`ssh-console` piece でタスクを実行すると、エージェントがコンソールセッションを開きます。アクティブなセッションがある間、タスク詳細に「SSH」タブが現れ、ここでターミナル画面をリアルタイムに見て、人間が直接コマンドを打つこともできます。タスク詳細での見方・介入は [実行中のタスクを見る・介入する](./03-running.md) を参照してください。
+
+## SSH 接続プロファイルを登録する
+
+接続は TopBar → ユーザーフォルダ → SSH 接続 から登録します。
+
+1. 「+ 新規作成」で接続を作成 (label / host / user など)
+2. 鍵の公開鍵をリモートの `authorized_keys` に登録
+3. 「Test」を押してホストキーを検証する (TOFU: 初回接続で見たキーを記録)
+
+ホストキー検証 (TOFU) を済ませないと、エージェント側は `host_key_not_verified` で停止します。検証後にキーが変わっていた場合は `host_key_mismatch` となり、MITM の疑いとして自動リトライせず中断します。
+
+接続には個人接続と、admin が登録する全体接続があります。全体接続を使うには admin の grant が必要です。
+
+## どう動かすか
+
+1. admin が SSH を有効化し、接続と grant を整える
+2. ユーザーが該当接続を登録 (個人接続の場合) して Test でホストキーを検証
+3. `ssh-ops` または `ssh-console` を使うタスクを作成して実行
+4. ssh-console の場合はタスク詳細の SSH タブで画面を確認・操作
+
+Piece の選び方や `allowed_tools` の考え方は [piece を使う・作る](./05-pieces.md) を参照してください。
+
+## よくあるエラー
+
+| エラーコード | 意味 | 対処 |
+|---|---|---|
+| `host_key_not_verified` | TOFU 未完了 | UI の Test で検証 |
+| `host_key_mismatch` | ホストキー不一致 (MITM 疑い) | 自動リトライしない。管理者に確認 |
+| `command_rejected` | allow/deny リストで拒否 | admin に許可パターン追加を相談 (ローカル回避しない) |
+| `path_not_allowed` | `remote_path_prefix` 外への書き込み | 許可パス内に変更 |
+| `no_grant` / `access_denied` | 権限不足 | admin に grant 追加を依頼 |
+| `abuse_locked` | 連続失敗でロック | admin に force-unlock を依頼 |
+
+詳しい運用手順は `docs/ssh.md` を参照してください。
@@ -0,0 +1,71 @@
+---
+id: llm-gateway
+title: LLM Gateway 連携
+category: advanced
+order: 150
+keywords: [LLM Gateway, LiteLLM, プロキシ, モデル, Virtual Keys]
+---
+
+## LLM Gateway とは
+
+LLM Gateway は、複数の物理 GPU / llama-server バックエンドへの呼び出しを 1 か所に集約する OpenAI 互換のプロキシです。MAESTRO は自身を Gateway として動かせるほか、外部の LiteLLM Proxy を Gateway として使うこともできます。
+
+主な価値:
+
+- ルーティングの一元化: 複数バックエンドへ least-busy で振り分け、空いている GPU に送る
+- 仮想キー管理: チームごとに発行する API キー (virtual key) で利用を分離・追跡
+- 観測性: すべての LLM 呼び出しが 1 か所に集まる
+
+直接接続 (各 worker が GPU を直に叩く) でも 1 インスタンス内のロードバランスはできますが、複数の MAESTRO が同じ GPU プールを共有すると互いの占有を知らずに衝突します。Gateway を間に挟むとこれを解消できます。個人利用や専有 GPU しか使わない場合は Gateway は不要です。
+
+## どこで設定するか
+
+admin は 設定 → LLM → Gateway Server で同一プロセス Gateway を設定します (admin 専用)。設定変更は hot reload され、サーバー再起動は不要です。設定画面全般は [設定](./17-settings.md) を参照してください。
+
+このフォームには 2 つのブロックがあります。
+
+- Enable Gateway トグル + ステータスバッジ
+- Backends — 物理バックエンドのリスト
+- Virtual Keys — 仮想キーの発行・rotate・revoke
+
+`config.yaml` では `gateway` セクションに対応します (キーは snake_case)。
+
+### Backends
+
+バックエンドを 1 件以上追加します。各行のフィールド:
+
+| フィールド | 意味 |
+|---|---|
+| `id` | バックエンド識別子 (例 `gpu-rtx-a`)。`x-aao-backend-id` / `/v1/models` に現れる |
+| `endpoint` | llama-server の URL (例 `http://gpu-host:8080/v1`) |
+| `model` | 厳密一致ルーティングに使うモデル名 (例 `qwen3:8b`) |
+| `max_slots` | 同時スロット数 (llama-server の `-np` と合わせる) |
+| `api_key` | バックエンドが bearer を要求する場合のみ (任意) |
+
+注意: フォームに入力した `api_key` は `config.yaml` に平文で保存されます。`${VAR}` 形式の環境変数参照を使いたい場合は、フォームではなく `config.yaml` を直接編集してください (フォーム保存では literal 文字列になります)。
+
+## Virtual Keys
+
+Gateway を経由してアクセスするためのクライアント側 bearer キーです。Gateway Server フォーム内の Virtual Keys セクションで発行・管理します。
+
+要点:
+
+- 形式は `sk-aao-*`。発行時に生キーが一度だけ表示され、以後は再表示できません (失くしたら rotate / revoke + 再発行)
+- DB には hash のみ保存される
+- チーム単位で発行し、`allowed_models` でモデルを絞れる
+- 月次 token 予算 (`tokens_budget`) と RPM レート制限 (`rate_limit_rpm`) を設定可能。超過時はそれぞれ HTTP 402 / 429 で拒否される
+- rotate は新キー発行 + 旧キー失効をアトミックに行う
+
+`config.yaml` の `gateway.virtual_keys[]` に書いたキーは起動時に DB へ idempotent に import されます (bootstrap / バックアップ用途)。通常の運用では UI / admin API での発行が推奨です。
+
+## 外部 LiteLLM Proxy を使う場合
+
+MAESTRO 内蔵 Gateway の代わりに、リファレンス実装の LiteLLM Proxy を Gateway として使うこともできます。クライアント側 (MAESTRO worker) は Gateway の URL と virtual key を worker の `endpoint` / `api_key` に設定するだけです。
+
+LiteLLM の構築手順・モデル定義・料金体系・Enterprise 機能といった運用詳細はこのページには含めていません。`docs/aao-gateway-overview.md` (内蔵 Gateway の機能概要と運用パターン) および LiteLLM の公式ドキュメントを参照してください。
+
+## 監視
+
+Gateway / Worker いずれも Prometheus 互換の `/metrics` を公開できます (デフォルト有効)。team / backend / key prefix などのラベルで per-team の利用量・レイテンシ・バックエンド稼働を集計できます。`/metrics` は機密情報を含むため、内部ネットワークに限定して公開してください。
+
+詳細な metric 一覧・Grafana クエリ例・scrape 設定は `docs/aao-gateway-overview.md` を参照してください。
@@ -0,0 +1,58 @@
+---
+id: tools
+title: ツールリファレンス
+category: advanced
+order: 160
+keywords: [ツール, tools, リファレンス, ReadToolDoc, 一覧]
+---
+
+## ツールとは
+
+ツールは、エージェントがタスクの中で使う「できること」です。ファイルの読み書き、Web 検索、ブラウザ操作、ドキュメント解析など、エージェントは LLM の推論とツール呼び出しを交互に繰り返してタスクを進めます。
+
+どのツールが使えるかは Piece の `allowed_tools` で決まります。`allowed_tools` に載っていないツールはエージェントに一切提示されません。Piece とツールの関係は [piece を使う・作る](./05-pieces.md) を参照してください。
+
+movement の開始時には、その movement で使えるツールの一覧と 1 行サマリが自動でエージェントに提示されます。Piece の指示文にツールの使い方を書く必要はありません。
+
+## カテゴリ別の概要
+
+以下はカテゴリの全体像です。網羅的なツール一覧ではありません (ツールは追加・変更されるため、最新の一覧は後述の方法で確認してください)。
+
+| カテゴリ | できること | 例 |
+|---|---|---|
+| ファイル / シェル | ワークスペースのファイル操作とコマンド実行 | Read / Write / Edit / Bash / Glob / Grep |
+| Web / 検索 | Web 検索・取得・ダウンロード | WebSearch / WebFetch / DownloadFile |
+| ブラウザ | 実ブラウザでのページ操作 | BrowseWeb |
+| Office / ドキュメント | Excel / Word / PDF / PPTX の解析 | ReadExcel / ReadPdf / ReadDocx |
+| データ | SQLite データベース操作 | SQLite |
+| 知識検索 | ドキュメントの取り込みと検索 | SearchKnowledge / ListDocuments |
+| 画像 | 画像の読み取り・注釈 | ReadImage / AnnotateImage |
+| レビュー | LLM による一括レビュー | BatchReviewTextWithLLM |
+| スライド | PPTX スライド生成 | AddSlide / BuildPptx / SetTheme |
+| チェックリスト | タスク内の進捗チェックリスト | CreateChecklist / CheckItem |
+| ノート / テンプレート | 共有ノート・ユーザーテンプレート | SearchNotes / ReadNote / RenderUserTemplate |
+| SSH | リモート実行・転送・対話コンソール | SshExec / SshUpload / SshConsoleSend |
+| オーケストレーション | サブタスクの生成 | SpawnSubTask |
+| 地図 | 場所検索・経路・逆ジオコーディング | SearchPlaces / GetDirections |
+| メディア | 文字起こし・動画字幕 | TranscribeAudio / GetYouTubeTranscript |
+| その他 | X(旧Twitter)検索・Amazon 検索など | XSearch / SearchAmazon |
+
+SSH 系の詳しい使い方は [SSH リモート操作](./14-ssh.md) を参照してください。
+
+## 常時利用できるメタツール
+
+一部のツールは Piece の `allowed_tools` に関係なく常に利用できます。
+
+- `ReadToolDoc` — 任意のツールの詳細ドキュメント (手順・引数・gotcha) を取得する。例: `ReadToolDoc({ name: "BrowseWeb" })`
+- `ReadSkill` — Skill の本文を取得する
+
+各ツールの function definition は 1 文に圧縮されているため、詳しい使い方はこの `ReadToolDoc` で取得する設計です。
+
+## 最新の一覧と詳細を見る
+
+ツールは追加・名称変更されることがあります。常に最新の状態を確認するには次を使ってください。
+
+- 設定 → Tools (admin 専用): カテゴリ別にツールの有効化・上限・外部サービス連携を設定。Web & Search / Browser Runtime / Media & Documents / External Services などのセクションに分かれます。設定画面の見方は [設定](./17-settings.md) を参照
+- ReadToolDoc: 個々のツールの完全な仕様。エージェント自身も実行中にこれを参照します
+
+このページのカテゴリ表はあくまで概要です。「どのツールが今このタスクで使えるか」は Piece の `allowed_tools` と admin の Tools 設定で決まります。
@@ -0,0 +1,124 @@
+---
+id: settings
+title: システム設定
+category: admin
+order: 170
+keywords: [設定, Settings, 管理者, Workers, Tools, Save & Apply]
+---
+
+# システム設定 (admin)
+
+設定画面は MAESTRO の挙動を `config.yaml` に書き込むための UI です。TopBar → **設定** タブで開きます。左にセクションのサイドバー、右に選択中セクションの編集フォームという 2 ペイン構成です。
+
+YAML キーは **スネークケース** (`max_concurrency`)、コード内は **キャメルケース** (`maxConcurrency`) で、`src/config.ts` の `transformKeys` が自動変換します。UI から保存しても YAML はスネークケースのまま保たれます。
+
+## 画面の構成
+
+- **左サイドバー** — セクションをグループ単位で並べる。グループは `User` / `System` / `LLM` / `Agent Runtime` / `Tools` / `MCP & Connections` / `SSH` の 7 つ
+- **右フォーム** — 選択したセクションの設定項目。ほとんどはその場で編集するインラインフォーム
+- `User` グループ以外は **admin 専用**。一般ユーザーには表示されない (`adminOnly`)
+
+## セクション一覧
+
+サイドバーのグループとセクションは以下の通りです。
+
+### User グループ (全ユーザー)
+
+| セクション | 内容 |
+|-----------|------|
+| Preferences | 自分の新規タスクのデフォルト公開範囲などの個人設定 |
+| 🔔 Notifications | ブラウザ通知 / Web Push の購読設定 |
+| 🧠 Memory & Learning | memory エントリの編集と Reflection 履歴の閲覧・revert |
+
+通知の詳細は [ブラウザ通知](#notifications)、memory の詳細は [メモリと学習](#memory) を参照。
+
+### System グループ (admin)
+
+| セクション | 内容 |
+|-----------|------|
+| Branding | アプリ名・ロゴ・アクセント色などの見た目 |
+| Paths & Storage | `storage.*` の作業ディレクトリ・ユーザーフォルダ・アップロード上限 |
+| Execution | `concurrency` (全 worker 合計の並列度)・`max_movements`・`retry.*` |
+
+### LLM グループ (admin)
+
+| セクション | 内容 |
+|-----------|------|
+| Workers | `llm.workers[]` — ジョブ実行時に呼ぶ LLM 接続の定義 |
+| Gateway Server | この MAESTRO 自身を OpenAI 互換 Gateway として公開 + Virtual Keys |
+| Metrics | Prometheus exporter (`llm.metrics` / `gateway.metrics`) |
+
+Gateway の運用は [LLM Gateway 連携](#llm-gateway) を参照。
+
+### Agent Runtime グループ (admin)
+
+| セクション | 内容 |
+|-----------|------|
+| Ask / Subtasks | ASK 上限・サブタスクの制御 |
+| Context | コンテキスト使用率の警告閾値 (warn / prompt / force_transition) |
+| Safety | `max_iterations`・`max_revisits`・history 要約などの自爆防止 |
+| Reflection | タスク完了後の自動学習。詳細は [Reflection の調整](#reflection) |
+
+### Tools グループ (admin)
+
+| セクション | 内容 |
+|-----------|------|
+| Web & Search | WebSearch / WebFetch / search_filter |
+| Browser Runtime | Playwright BrowseWeb のタイムアウト・channel など |
+| Media & Documents | Vision / OCR / 音声 / Office ファイルの上限 |
+| External Services | X / Maps / Amazon などの外部 API キー |
+| Legacy Knowledge | 旧 DKS 設定 (新規 namespace は MCP に移行) |
+
+### MCP & Connections グループ (admin)
+
+| セクション | 内容 |
+|-----------|------|
+| MCP Runtime | MCP のグローバル runtime / quota 設定 |
+
+個々の MCP server は User Folder 側で管理します。詳細は [MCP 連携](#mcp) を参照。
+
+### SSH グループ (admin)
+
+| セクション | 内容 |
+|-----------|------|
+| Admin SSH | グローバル接続・grant・監査ログ・マスターキーローテーション |
+
+詳細は [SSH リモート操作](#ssh) を参照。
+
+## Save & Apply の流れ
+
+フォームの値を変更しても、すぐには反映されません。
+
+1. 値を変更すると、画面下部の **保存バー** が琥珀色に変わり「未保存: N 項目」と表示される
+2. **Save & Apply** ボタンで `/api/config` に PATCH 送信。成功すると「保存しました」トースト
+3. やり直したいときは **Discard Changes** でフェッチ済みの値に戻す
+
+注意点:
+
+- 未保存のまま別タブへ移動しようとすると確認ダイアログが出る (`useUnsavedGuard`)
+- 保存は **ETag ベースの楽観ロック**。他の管理者が先に保存していると「設定が他で変更されました。再読み込みしますか？」と表示される
+- Preferences / Notifications / Memory & Learning の 3 つは個人 API で保存するため、この共通保存バーは出ない (各フォーム内で完結)
+
+## 反映タイミング
+
+ほとんどの設定は `ConfigManager` の変更イベントを各サブシステムが購読しているため **サーバ再起動なしで反映** されます。例外は再起動が必要なもの:
+
+- `auth.providers.*` (認証プロバイダ)
+- `db_path`
+- `port`
+
+## センシティブ値の扱い
+
+`llm.workers[].api_key` や `auth.providers.*.client_secret` などのシークレットは、`/api/config` の GET で実値を返さずマスクされます。UI 上は「変更なし」または「env: ENV_NAME」として表示され、保存時に既存値を保持します。
+
+## 環境変数オーバーライド
+
+一部のキーは環境変数で上書きできます: `OLLAMA_BASE_URL`, `OLLAMA_MODEL`, `WORKTREE_DIR`, `CONCURRENCY`, `DB_PATH`, `PORT`, `LOG_LEVEL`。env で上書きされたフィールドはフォーム上でも「環境変数で上書き中」と示されます。
+
+## TIP
+
+> 開発時は `LOG_LEVEL=debug`、本番は `info` を推奨。
+
+> Workers のモデルドロップダウンが空のときは endpoint が応答していない可能性。network / firewall を確認。
+
+> ユーザー管理・権限・安全性の調整は [ユーザー管理 / 安全性](#admin) を参照。
@@ -0,0 +1,81 @@
+---
+id: reflection
+title: Reflection の調整
+category: admin
+order: 180
+keywords: [Reflection, 学習, 自動改善, memory, piece]
+---
+
+# Reflection の調整 (admin)
+
+**Reflection (Hermes mode)** は、タスクが終わるたびに安いモデルでそのジョブを振り返り、ユーザーの memory や piece への更新を提案する仕組みです。これにより、エージェントが同じユーザーの好みや過去の失敗を学習し、徐々に賢くなっていきます。
+
+コストと安全性のトレードオフがあるため **デフォルトでは無効** で、admin が明示的に有効化・調整します。
+
+## 何をするのか
+
+1. 通常ジョブが `succeeded` / `failed` / `aborted` のいずれかで終了する
+2. 裏で `task_kind='reflection'` の新規ジョブが作られる
+3. `roles: [reflection]` を持つ専用 worker が、cheap なモデルでそれを拾う
+4. reflection ハンドラがユーザーの memory・activity log サマリ・タスクコメント・feedback を読み、`submit_reflection` で更新案を出す
+5. 意味検証 (validator) を通過した変更だけが memory / piece に atomic に適用される
+6. 全変更は snapshot として保存され、後から revert 可能
+
+LLM が「学ぶことはない」と判断した場合は何も変更しません (abstain)。これが正常な多数派です。
+
+## 有効化と調整
+
+設定 → **Agent Runtime → Reflection** で操作します。
+
+### 有効化
+
+- **Reflection を有効化（自動適用）** チェックボックス — これが全体スイッチ (`reflection.enabled`)。デフォルト OFF
+- 有効化しても、`roles: [reflection]` を持つ worker が LLM → Workers に無いとジョブは enqueue されず、フォーム上に警告が出ます。cheap モデル + `roles: [reflection]` の worker を 1 つ追加してください
+
+### 主な調整項目
+
+`config.yaml` の `reflection.*` (スネークケース) として保存されます。
+
+| 項目 | キー | デフォルト | 意味 |
+|------|------|-----------|------|
+| 専用 worker を必須にする | `worker_required` | true | reflection worker が無ければスキップ |
+| Max memory changes per job | `max_memory_changes_per_job` | 3 | 1 ジョブで書ける memory entry 上限 |
+| Max entry body bytes | `max_entry_body_bytes` | 8192 | memory entry 本文の最大バイト |
+| Piece edit cooldown (hours) | `piece_edit_cooldown_hours` | 24 | 同じ piece への連続編集の cooldown |
+| Per-user daily budget (tokens) | `per_user_daily_budget_tokens` | 200000 | 1 ユーザー / 1 日の token 上限 |
+| Snapshot retention (days) | `snapshot_retention_days` | 90 | snapshot の保持日数 |
+| Abstain rate floor | `abstain_rate_floor` | 0.3 | abstain 率がこれを下回ると過剰学習として warn |
+
+## built-in piece は触らない
+
+Reflection が piece への変更を提案しても、**組み込み piece (`pieces/{name}.yaml`) は決して書き換えません**。代わりに `data/users/{userId}/pieces/{name}.yaml` への **silent fork** を作り、そちらを編集します。fork の frontmatter には `forked_from_commit` が記録され、本家との差分を追えます。
+
+さらに cooldown による暴走防止が働きます:
+
+- `piece_edit_cooldown_hours` (デフォルト 24h) 以内は同じ piece を再編集しない
+- ウィンドウ内の編集回数にも上限がある (デフォルト 2 回 / 24h)
+
+これにより「Reflection が毎タスク piece を書き換えて挙動が安定しない」事故を防ぎます。
+
+## 結果の確認
+
+学習結果は次の 2 か所で見えます。
+
+- **設定 → 🧠 Memory & Learning** — memory の現在値、Reflection の適用履歴、各履歴の **revert ボタン**。詳細は [メモリと学習](#memory) を参照
+- **タスク詳細の概要タブ** — そのタスクの Reflection が実際に変更を加えた場合だけ **🧠 Learned N things** バッジが出る (piece も編集した場合は「+ piece edit」付き)
+
+revert は before snapshot から memory / piece を書き戻します。ユーザー自身の編集を上書きしないよう CAS (Compare-and-Swap) ベースで安全に実装されています。
+
+## 運用の指針
+
+- まず `enabled: false` のまま運用し、タスクが十分溜まってから有効化する。空のユーザーで回しても学ぶものがない
+- cheap モデルを専用 worker に割り当ててコストを抑える
+- 適用が多すぎる (abstain 率が `abstain_rate_floor` を下回る) と warn がログに出る。`max_memory_changes_per_job` を下げて様子を見る
+- 緊急停止は `reflection.enabled: false`。進行中のジョブは完走するが、新規 enqueue は止まる
+- 気に入らない学習は履歴の revert で気軽に戻せる。信用しきれないうちは「ダメなら戻す」運用が安全
+
+## TIP
+
+> Reflection は通常タスクごとに 1 回追加で LLM 呼び出しを行う。コスト倍増を避けるため必ず cheap モデルの専用 worker を使う。
+
+> `worker_required: true` のままにしておけば、worker を止めるだけで Reflection を一時停止できる。
@@ -0,0 +1,120 @@
+---
+id: admin
+title: ユーザー管理 / 安全性
+category: admin
+order: 190
+keywords: [ユーザー管理, 権限, admin, 安全性, bash, sandbox, 監査]
+---
+
+# ユーザー管理 / 安全性 (admin)
+
+このページは admin が行う運用作業をまとめます。ユーザーの承認・権限付与、公開範囲モデル、そしてエージェントの安全制御 (Bash 実行・監査ログ) です。
+
+## ユーザー管理
+
+TopBar → **ユーザー** タブで開きます。左にユーザー一覧、右に選択ユーザーの詳細という 2 ペイン構成です。
+
+### 一覧とフィルタ
+
+- 上部に「すべて / Admin / User」のフィルタチップ。承認待ちのユーザーが居る場合のみ **承認待ち** チップも出る
+- 名前 / メールで検索できる
+- ユーザーは OAuth ログイン時に自動作成される。手動追加 UI はない (「OAuth ログインを行うとここに表示されます」)
+
+### ロール
+
+ユーザーは 2 つのロールのいずれかを持ちます。詳細パネルの「ロールと権限」で切り替えます。
+
+| ロール | できること |
+|--------|-----------|
+| Admin | 全ての設定変更・ユーザー管理・システム操作 |
+| User | タスク作成・実行など通常の利用。管理操作は不可 |
+
+### ステータスと承認
+
+| ステータス | 意味 |
+|-----------|------|
+| 承認待ち (pending) | 初回ログイン直後。まだ利用できない |
+| アクティブ (active) | 利用可能 |
+| 無効 (disabled) | ログイン不可に制限された状態 |
+
+詳細パネルのヘッダにあるボタンで状態を変えます。
+
+- **pending のユーザー** → 「承認」ボタンで active に
+- **active のユーザー** → 「無効化」ボタンで disabled に
+- **disabled のユーザー** → 「有効化」ボタンで active に戻す
+- 「削除」ボタンでユーザーを完全に削除 (確認ダイアログあり)
+
+> 最初の管理者をブートストラップするときは、DB を直接操作する手もあります: `UPDATE users SET role='admin', status='active' WHERE email='[email protected]'`。以降は別 admin がこの画面で昇格できます。
+
+### 所属組織
+
+Gitea でログインしたユーザーは、所属する Gitea organization が詳細パネルの「所属 Gitea 組織」に表示されます。これが下記の公開範囲「org」の判定に使われます。
+
+## 公開範囲・権限モデル
+
+タスク・スケジュール・ジョブは `owner_id` / `visibility` を持ち、3 段階の公開範囲を取ります。
+
+| 公開範囲 | 見える人 |
+|----------|---------|
+| private | owner + admin |
+| org | 同じ Gitea organization のメンバー |
+| public | 全ログインユーザー |
+
+ポイント:
+
+- **admin は全件閲覧可能**。ただし編集・削除は owner または admin のみ
+- 権限チェックは `buildVisibilityWhere(user, alias)` を一覧・取得クエリに差し込む形で一元化されている
+- 親 → 子へ公開範囲がコピーされる (タスク → その spawn job、スケジュール → spawn job、親 job → 子 subtask)
+
+## 安全性: Bash 実行モード
+
+エージェントの `Bash` ツールの隔離は、`config.yaml` の **2 つの独立したキー**で制御します。どちらも設定 UI には出ない **config ファイル専用キー**です（危険なセキュリティ姿勢キーは UI トグルにせず、config 直編集 + 再起動を要求する方針）。
+
+- `safety.bash_sandbox` — **隔離機構**を選ぶ。`auto`（既定）/ `always` / `off`
+- `safety.bash_unrestricted` — **コマンド許可リストを適用するか**だけを制御（既定 `false`）。bwrap が走るかどうかは制御しない（それは `bash_sandbox` の役割）
+
+### 隔離機構 (`safety.bash_sandbox`, 既定 `auto`)
+
+| 値 | 挙動 |
+|----|------|
+| `auto`（既定） | bwrap があれば bwrap サンドボックス、無ければ hardened フォールバック |
+| `always` | bwrap を強制。bwrap 不在なら**起動失敗**（本番推奨） |
+| `off` | bwrap を使わず exec（**env スクラブは維持**）。デバッグ用・非推奨 |
+
+### bwrap サンドボックス（`auto`+bwrap / `always`）
+
+- 書き込み可能は **そのタスクのワークスペースのみ**。`/usr` `/bin` 等は read-only bind。他タスクの workspace やホスト `/home` は mount されず横断アクセス不可
+- ユーザー名前空間・PID・IPC・UTS・cgroup・**ネットワーク**を unshare
+- **各 Bash コールは独立したサンドボックス**（揮発 `/tmp`・毎回新しい名前空間）。コマンド間で残るのは workspace だけ
+- **環境変数**: `--clearenv` 後に `PATH`/`HOME`/`LANG` 等の最小 allowlist のみ注入。`MCP_ENCRYPTION_KEY` 等のシークレットはサンドボックス内から見えない
+- **ネットワーク**: `--unshare-net` で遮断。外向き通信は SSRF ガード付きの WebFetch / DownloadFile / MCP 経由に一本化
+- **前提**: user namespace が有効 + `bwrap`。`always` は起動時に動作確認し、利用不可ならエラーで起動中止 (`Bash sandboxing requires bwrap but it is not available`)
+
+### hardened フォールバック（bwrap 不在時の `auto` / `off`）
+
+- 許可リスト照合（`bash_unrestricted: false` のとき）+ パススコープチェック（相対 `..` での workspace 外参照も拒否）+ env スクラブ付き exec
+- プロセス単位の FS / ネットワーク名前空間分離は無く、bwrap より弱い多層防御。**本番は `always` 運用を推奨**
+
+### コマンド許可リスト (`safety.bash_unrestricted`, 既定 `false`)
+
+- `false`: 許可リストで照合し、ワークスペース外を触るコマンドはパススコープで拒否。ブロックはツール結果に返り `logs/` に記録
+- `true`: 許可リストを撤廃し任意コマンド名を実行可能。**ただし FS / env / ネットワークの隔離は `bash_sandbox` が決めるので引き続き有効**
+
+### パッケージのインストール
+
+- `pip install` / `npm install` は**全モードで拒否**される（各コールが独立サンドボックスのためインストールは永続しない）。ブロック時はプリインストール済みパッケージ一覧を返す
+- 必要な Python パッケージは `runtime/python-requirements.txt` にプリベイクされ、システム python（read-only bind）から import 可能。追加が必要なら同ファイルに足して再プロビジョニングする（手順: `docs/operations/bash-sandbox-provisioning.md`）
+
+> 本番は `bash_sandbox: always` + パッケージのプリベイクを推奨。bwrap が使えないホストでは `auto`（hardened フォールバック）になるが、テナント間分離は弱くなる点に注意。
+
+## 監査ログ
+
+- ジョブ実行に関する操作は `audit_log` テーブル (`action` / `actor` / `detail` / `created_at`) に記録される
+- Bash の実行履歴はワークスペースの `logs/` 配下に残る (ブロックされた試行も含む)
+- SSH ツールの呼び出しは別途、SSH 専用の監査ログに記録される (設定 → SSH → Audit Log)。詳細は [SSH リモート操作](./14-ssh.md) を参照
+
+## TIP
+
+> 公開範囲・worker・各種上限の設定そのものは [システム設定](./17-settings.md) 側で行う。このページは「誰が・何を・どこまで」の運用判断に集中する。
+
+> 承認待ちユーザーが溜まると一覧上部に件数が出る。放置せず承認 / 無効化で捌く。