diff --git a/.cursor/skills/delete-merged-branches/SKILL.md b/.cursor/skills/delete-merged-branches/SKILL.md
deleted file mode 100644
index 012b0f3d..00000000
--- a/.cursor/skills/delete-merged-branches/SKILL.md
+++ /dev/null
@@ -1,96 +0,0 @@
----
-name: delete-merged-branches
-description: >
-  指定した基準ブランチ（develop / main など）に取り込まれたローカルおよび origin 上の
-  リモートブランチを安全に削除する。通常 merge は祖先判定、squash/rebase merge は
-  GitHub のマージ済み PR の headRefOid 一致で判定。あわせて、基準ブランチ向けに
-  **リポジトリ全体**のクローズ済み（未マージ）PR のリモートブランチも削除候補にする
-  （基準以外向けの sub-PR や GitHub Copilot 等が作ってクローズしたブランチも掃除できる）。"マージ済みブランチを削除",
-  "delete merged branches", "ローカル/リモートブランチを掃除", "ブランチ整理" などで使う。
----
-
-# マージ済みローカル・リモートブランチの削除
-
-`git branch --merged` は祖先関係のみ見るため、squash/rebase merge では未マージ扱いになる。本スキルでは祖先判定に加え、GitHub の merged PR の `headRefOid` 一致でローカル・リモート両方の削除対象を安全に決める。あわせて、**クローズされた（未マージ）PR** のブランチは**リモートのみ**削除候補とする（ローカルは対象にしない）。クローズ PR は `gh pr list --state closed` でリポジトリ全体から取得するため、基準以外のブランチ向けに作られた sub-PR（例: copilot/sub-pr-\*）も候補になる。主 remote は `origin` を前提とする。
-
-## 推奨: スクリプトで一括実行
-
-事前に `git fetch origin --prune` と `gh auth status` が通ることを確認したうえで、以下で候補列挙・確認・削除まで行う。
-
-```bash
-git fetch origin --prune
-./scripts/delete-merged-branches.sh [基準ブランチ] [--dry-run]
-```
-
-- **基準ブランチ**: 省略時はローカルに `develop` があれば `develop`、なければ `origin/HEAD` の短縮名（例: main）。
-- **--dry-run**: 削除はせず、削除候補一覧と理由だけ表示する。
-- **非対話で実行する場合**（CI やエージェントから確認なしで削除する場合）: `echo y | ./scripts/delete-merged-branches.sh` で確認プロンプトに自動で `y` を送る。
-
-スクリプトは (1) merged PR を `gh pr list --state merged --base <基準>` で一括取得し `headRefName` / `headRefOid` で照合する。(2) クローズ済み未マージ PR を `gh pr list --state closed`（**--base なし**、リポジトリ全体）から `mergedAt == null` かつ同一リポジトリ（fork は `isCrossRepository` で除外）で抽出する。ローカル候補は祖先 or merged PR の headRefOid 一致のみ。リモート専用候補は「merged PR で tip 一致」に加え、**クローズ済み未マージ PR については** origin の tip が当該 PR の `headRefOid` と一致する場合のみ（かつ `mergedAt == null`）削除候補に含め、さらに同名ブランチに open PR がある場合は削除しない。確認後にローカル削除 → リモート削除の順で実行する。
-
-## 手動で行う場合（フォールバック）
-
-スクリプトを使わないときは以下を参考にする。
-
-1. **事前確認**  
-   `git fetch origin --prune` と `gh auth status`。主 remote が `origin` でない場合はユーザーに確認する。
-
-2. **基準ブランチ**  
-   ユーザー指定 > ローカル `develop` > `origin/HEAD` の短縮名。`base_remote=origin/<基準>` が存在しない場合は中断して確認。
-
-3. **merged PR の一括取得**  
-   ブランチごとに `gh pr list` を叩かず、1 回だけ取得する。
-
-   ```bash
-   gh pr list --state merged --base "$base_branch" --limit 200 --json headRefName,headRefOid,number
-   ```
-
-4. **ローカル候補**  
-   `git for-each-ref refs/heads --format='%(refname:short)'` で一覧。現在ブランチ・基準・main/master/develop・origin/HEAD 先は除外。各ブランチについて:
-   - `git merge-base --is-ancestor <branch> "$base_remote"` で成功 → 削除可（merged by ancestry）
-   - 失敗時は上記 JSON からそのブランチ名の `headRefOid` を探し、`$(git rev-parse <branch>)` と一致する場合のみ削除可（merged PR #N）。
-
-5. **リモート専用候補**  
-   `git for-each-ref refs/remotes/origin --format='%(refname:short)' | sed 's|^origin/||'` で一覧。保護ブランチ・ローカルに存在するブランチは除外。(a) merged PR の JSON でそのブランチの `headRefOid` が origin の tip と一致する場合。(b) 別途 `gh pr list --state closed`（--base なし）から `mergedAt == null` かつ同一リポジトリの PR の `headRefName` と `headRefOid` を取得し、**origin の tip が headRefOid と一致する**リモートブランチのみ対象とする。このとき、同名ブランチに open PR がある場合は削除しない（基準以外向けの sub-PR や Copilot ブランチを含む）。
-
-6. **削除**  
-   候補を提示し確認後、ローカルは `git branch -d`（必要なら `-D`）、リモートは `git push origin --delete <branch>`。
-
-## 報告形式
-
-```markdown
-基準ブランチ: develop
-
-Deleted (local):
-
-- `feature/foo` - merged by ancestry
-- `feature/bar` - merged PR #123 (squash/rebase-safe)
-
-Deleted (remote):
-
-- `feature/qux` - merged PR #124 (remote-only)
-- `sub` - closed PR #XXX (remote-only)
-
-削除: ローカル 2 件、リモート 2 件
-```
-
-削除件数を必ず添える。
-
-## 現状把握（調査時）
-
-リモートブランチ一覧と PR 状態を確認する例:
-
-```bash
-git fetch origin --prune
-git for-each-ref refs/remotes/origin --format='%(refname:short)' | sed 's|^origin/||' | grep -v '^HEAD$' | sort
-# 各ブランチの PR 状態: gh pr list --state all --head <branch> --limit 1 --json state,number,mergedAt,baseRefName
-```
-
-削除候補の洗い出しには `./scripts/delete-merged-branches.sh --dry-run` が使える。
-
-## 注意点
-
-- merged PR があっても、ローカルまたはリモートの tip が `headRefOid` と一致しない場合は削除しない（merge 後に進んだ可能性あり）。
-- クローズ済み未マージ PR のブランチは**リモート削除のみ**対象。ローカルに同じ名前のブランチがあっても、merged でない限りローカルは削除しない（安全のため）。
-- 主 remote が `origin` でない構成では手順を流用するかユーザーに確認する。
-- `gh` が使えない場合は、祖先で merged と判定できるローカルブランチと、その同名の `origin` 上のリモートブランチを ancestry ベースでのみ削除し、PR の `headRefOid` による squash/rebase 判定およびクローズ済み PR の取得は行わない。
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 5cac2639..adf3a918 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -30,7 +30,7 @@
 
 - [ ] テストがすべてパスする
 - [ ] Lint エラーがない
-- [ ] 必要に応じてドキュメントを更新した
+- [ ] 必要に応じてドキュメントを更新した（英語正本 + 該当する場合は `.ja.md` ペア）
 - [ ] コミットメッセージが Conventional Commits に従っている
 
 ## スクリーンショット（UI 変更がある場合）
diff --git a/.github/actions/setup-toolchain/README.md b/.github/actions/setup-toolchain/README.md
new file mode 100644
index 00000000..3db91560
--- /dev/null
+++ b/.github/actions/setup-toolchain/README.md
@@ -0,0 +1,242 @@
+# `setup-toolchain` action
+
+リポジトリの CI ワークフローで繰り返し使われる「Node → Bun → bun install」を
+1 つの composite action にまとめ、GitHub API の一過性失敗（典型:
+`oven-sh/setup-bun@v2` が `api.github.com/repos/oven-sh/bun/git/refs/tags` で
+401 を返す等）に自動でリトライをかける。Issue
+[#937](https://github.com/otomatty/zedi/issues/937) で導入。
+
+Composite action that bundles the repository's standard CI setup (Node +
+Bun + `bun install`) and wraps the GitHub API-dependent steps with retry
+semantics. Targets the transient `setup-bun` / `bun install` failures
+captured in Issue [#937](https://github.com/otomatty/zedi/issues/937)
+(e.g. one-shot 401 from `api.github.com`).
+
+---
+
+## ⚠️ `actions/checkout` は caller 側 / `actions/checkout` belongs to the caller
+
+ローカル composite action の `action.yml` は **リポジトリが workspace に
+checkout された後** でないと解決できない。本 action 内部に
+`actions/checkout` を含めると chicken-and-egg になるので、caller が先に
+`actions/checkout` を実行する必要がある。**checkout 自体も Issue #937 で
+flake が観測されている**ため、caller 側でも `Wandalen/wretry.action@v3`
+でラップすることを推奨する（後述のテンプレ参照）。
+
+GitHub Actions resolves a local composite action by reading its `action.yml`
+**from the workspace, which only exists after `actions/checkout`**. The
+composite cannot bootstrap itself, so callers must check out first.
+Because checkout itself has been observed to flake (see Issue #937),
+callers should wrap `actions/checkout` with `Wandalen/wretry.action@v3`
+(template below).
+
+---
+
+## ファイル構成 / Files
+
+| ファイル / file | 役割 / role                                            |
+| --------------- | ------------------------------------------------------ |
+| `action.yml`    | composite action 定義 / composite action definition    |
+| `README.md`     | 使用方法・引数の文書化 / usage and input documentation |
+
+呼び出し元 / called from: `.github/workflows/ci.yml`,
+`.github/workflows/deploy-dev.yml`, `.github/workflows/deploy-prod.yml`,
+`.github/workflows/nightly-mutation.yml`.
+
+---
+
+## なぜ必要か / Why
+
+CI の各ジョブは `${{ github.token }}` を使う JS アクション
+（`actions/checkout` / `actions/setup-node` / `oven-sh/setup-bun`）を独立に
+実行する。GitHub バックエンド側の一時的な 401 / 5xx でジョブごとに**ランダム
+に 1 つだけ落ちる**事象が観測された（Issue #937、PR #936 の run 1b0dc51 /
+c5694c1 を参照）。ワークフロー自身にはリトライ機構が無く、コードに問題が
+無くても手動 re-run が必要になる。
+
+本 composite action は内部で
+[`Wandalen/wretry.action@v3`](https://github.com/Wandalen/wretry.action)
+を使い、`setup-node` / `setup-bun` を `attempt_limit: 3` /
+`attempt_delay: 5000ms` でラップする。`bun install` も shell レベルでの
+リトライ（5s → 10s バックオフ、最大 3 回）を持つ。通常は 1 発で成功するため
+オーバーヘッドは数秒以内に収まる想定。
+
+Each CI job independently invokes JS actions (`actions/checkout` /
+`actions/setup-node` / `oven-sh/setup-bun`) that authenticate against the
+GitHub API with `${{ github.token }}`. When the GitHub backend returns a
+transient 401 / 5xx, **a random single job per PR fails at setup**
+(see Issue #937 — PR #936 runs 1b0dc51 / c5694c1). There is no built-in
+retry, so contributors had to manually re-run unaffected code.
+
+This action wraps `setup-node` / `setup-bun` with
+[`Wandalen/wretry.action@v3`](https://github.com/Wandalen/wretry.action)
+(`attempt_limit: 3`, `attempt_delay: 5000ms`) and adds shell-level retry
+for `bun install` (5s → 10s backoff, up to 3 attempts). The happy path
+still completes on the first attempt, so overhead in the steady state is
+just a few seconds.
+
+---
+
+## 使用例 / Usage
+
+### 1. 標準ジョブ / Standard job (root install)
+
+ほとんどの CI ジョブはこのテンプレで置き換え可能。checkout / Node / Bun /
+`bun install --frozen-lockfile` すべてがリトライ付きで実行される。
+
+Most CI jobs can use this two-block template. Checkout / Node / Bun /
+root `bun install --frozen-lockfile` all run with retry.
+
+```yaml
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout (with retry)
+        uses: Wandalen/wretry.action@v3
+        with:
+          action: actions/checkout@v6.0.2
+          attempt_limit: 3
+          attempt_delay: 5000
+
+      - uses: ./.github/actions/setup-toolchain
+
+      - run: bun run lint
+```
+
+### 2. 履歴が必要なジョブ / Jobs that need full git history
+
+PR のベースとの diff を取る `drizzle-migration-check` や `security` などは
+checkout の `with:` で `fetch-depth: 0` を渡す。
+
+Jobs that diff against the PR base (e.g. `drizzle-migration-check` /
+`security`) pass `fetch-depth: 0` to the inner checkout:
+
+```yaml
+steps:
+  - name: Checkout (with retry)
+    uses: Wandalen/wretry.action@v3
+    with:
+      action: actions/checkout@v6.0.2
+      with: |
+        fetch-depth: 0
+      attempt_limit: 3
+      attempt_delay: 5000
+
+  - uses: ./.github/actions/setup-toolchain
+```
+
+### 3. Node のみのジョブ / Node-only jobs
+
+`drizzle-migration-check` / `drizzle-schema-drift-check` のように Node
+スクリプトだけ動かすジョブは `setup-bun: "false"` を渡せば Bun のセット
+アップと `bun install` を丸ごとスキップできる。
+
+Node-only jobs (e.g. `drizzle-migration-check` /
+`drizzle-schema-drift-check`) can skip the Bun setup and the root install
+entirely:
+
+```yaml
+steps:
+  - name: Checkout (with retry)
+    uses: Wandalen/wretry.action@v3
+    with:
+      action: actions/checkout@v6.0.2
+      attempt_limit: 3
+      attempt_delay: 5000
+
+  - uses: ./.github/actions/setup-toolchain
+    with:
+      setup-bun: "false"
+```
+
+### 4. ワークスペース個別 install / Workspace-only install
+
+`server/mcp` のようにルートでは install せず特定ワークスペースだけ install
+するジョブは `install-deps: "false"` を渡し、後段で個別に install する。
+
+For jobs that skip the root install and instead install inside a specific
+workspace (e.g. `server/mcp`):
+
+```yaml
+steps:
+  - name: Checkout (with retry)
+    uses: Wandalen/wretry.action@v3
+    with:
+      action: actions/checkout@v6.0.2
+      attempt_limit: 3
+      attempt_delay: 5000
+
+  - uses: ./.github/actions/setup-toolchain
+    with:
+      install-deps: "false"
+
+  - name: Install MCP dependencies
+    working-directory: server/mcp
+    run: bun install --frozen-lockfile
+```
+
+---
+
+## 入力 / Inputs
+
+| name           | required | default  | 説明 / description                                                                                                                                                                                                           |
+| -------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `setup-bun`    | no       | `"true"` | `"false"` で Bun のセットアップと `bun install` を丸ごとスキップ。 / Set to `"false"` to skip Bun setup and the root install entirely.                                                                                       |
+| `bun-version`  | no       | `"1.3"`  | `oven-sh/setup-bun` に渡す Bun のバージョン指定子。 / Bun version spec forwarded to `oven-sh/setup-bun`.                                                                                                                     |
+| `install-deps` | no       | `"true"` | `"false"` でルートの `bun install --frozen-lockfile` をスキップ。`setup-bun: "false"` のときは実質無効。 / Set to `"false"` to skip the root `bun install --frozen-lockfile`. Implicitly disabled when `setup-bun: "false"`. |
+
+`actions/checkout` の `fetch-depth` などは caller 側で `Wandalen/wretry.action`
+の `with:` に渡す（上記サンプル参照）。`fetch-depth` などのパラメータは
+本 composite action では扱わない。
+
+`actions/checkout` arguments (`fetch-depth`, etc.) are passed by the caller
+on the `Wandalen/wretry.action` block — they are not inputs of this
+composite action (see samples above).
+
+---
+
+## リトライ仕様 / Retry semantics
+
+| ステップ / step                 | リトライ実装 / retry mechanism          | 試行回数 / attempts | 待機 / delay                                |
+| ------------------------------- | --------------------------------------- | ------------------- | ------------------------------------------- |
+| `actions/checkout@v6.0.2`       | caller 側 / `Wandalen/wretry.action@v3` | 3                   | 5000 ms                                     |
+| `actions/setup-node@v6`         | `Wandalen/wretry.action@v3`             | 3                   | 5000 ms                                     |
+| `oven-sh/setup-bun@v2`          | `Wandalen/wretry.action@v3`             | 3                   | 5000 ms                                     |
+| `bun install --frozen-lockfile` | shell 内ループ / inline shell loop      | 3                   | 5s → 10s（線形バックオフ / linear backoff） |
+
+3 回全てが失敗した場合はステップ／ジョブを失敗させる。通常は 1 回目で成功
+するためステップ時間はほぼ増えない。If all attempts fail, the step exits
+non-zero — expected to be rare since the steady-state path succeeds on the
+first try.
+
+---
+
+## 外部依存 / External dependencies
+
+- [`Wandalen/wretry.action@v3`](https://github.com/Wandalen/wretry.action)
+  — `uses:` 形式のアクションをリトライ付きで実行する composite ラッパー。
+  Dependabot の `github-actions` ecosystem 対象（既存設定で自動更新）。
+  / Composite wrapper that retries `uses:`-style actions. Tracked by the
+  repository's existing `github-actions` Dependabot configuration.
+
+シェルレベルのコマンドリトライには既に `nick-fields/retry@v4` を使っているが
+（`deploy-*.yml`）、本 action のターゲットは `uses:` の JS アクションなので
+`wretry` のほうが適切。
+
+`nick-fields/retry@v4` is already used elsewhere for shell-command retries
+(`deploy-*.yml`), but it cannot wrap `uses:` invocations — hence `wretry`.
+
+---
+
+## 関連 / References
+
+- Issue [#937](https://github.com/otomatty/zedi/issues/937) — 本 action の
+  導入経緯 / origin issue
+- PR [#936](https://github.com/otomatty/zedi/pull/936) — 再現事象の出元 /
+  source of the observed flake
+- [`oven-sh/setup-bun` README](https://github.com/oven-sh/setup-bun) —
+  `token` input は `${{ github.token }}` がデフォルト
+- [`actions/runner#4295`](https://github.com/actions/runner/issues/4295)
+  — `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24` 関連の既知問題（Issue #937
+  Proposal B として今後再評価）
diff --git a/.github/actions/setup-toolchain/action.yml b/.github/actions/setup-toolchain/action.yml
new file mode 100644
index 00000000..09fe6fa2
--- /dev/null
+++ b/.github/actions/setup-toolchain/action.yml
@@ -0,0 +1,130 @@
+# `.github/actions/setup-toolchain` — Composite action that performs the
+# repository's common setup (Node + Bun + bun install) with retry on transient
+# GitHub API failures. See Issue #937 for the original symptoms (e.g.
+# `setup-bun` getting a one-shot 401 from `api.github.com/repos/oven-sh/bun/
+# git/refs/tags`).
+#
+# 注意 / Note: `actions/checkout` は本 composite action には含めない。
+# ローカル composite action はリポジトリが workspace に展開された後でないと
+# 解決できないため、checkout を内部に持つと chicken-and-egg になる。caller
+# 側で先に `actions/checkout`（必要なら `Wandalen/wretry.action` でラップ）
+# を呼ぶこと。詳しくは `README.md` を参照。
+#
+# We intentionally exclude `actions/checkout` from this composite action.
+# A local composite action's `action.yml` only becomes resolvable AFTER the
+# repository is checked out, so including checkout would be chicken-and-egg.
+# Callers must run `actions/checkout` first (wrap it with
+# `Wandalen/wretry.action` to also get checkout-level retry). See `README.md`.
+#
+# CI ワークフロー (`ci.yml` / `deploy-dev.yml` / `deploy-prod.yml` /
+# `nightly-mutation.yml`) で繰り返し使われる「Node → Bun → bun install」を
+# まとめ、GitHub API の一過性失敗（401 など）に対してリトライを効かせる。
+# 詳細は Issue #937 を参照。
+name: Setup toolchain
+description: >
+  Install Node + Bun and run `bun install` with retry on transient GitHub
+  API failures (Issue #937). Caller must run `actions/checkout` first.
+  / Node + Bun のセットアップと `bun install` を GitHub API の一過性失敗に
+  強いリトライ付きで実行する共通 setup (Issue #937)。caller が先に
+  `actions/checkout` を実行している必要がある。
+
+inputs:
+  setup-bun:
+    description: >
+      `"false"` を渡すと Bun のセットアップをスキップする（Node しか使わない
+      ジョブ向け）。`"false"` 指定時は `install-deps` も実質無効化される。
+      / Set to `"false"` to skip Bun setup (for Node-only jobs). When
+      Bun is skipped, `install-deps` is effectively disabled too.
+    required: false
+    default: "true"
+  bun-version:
+    description: >
+      `oven-sh/setup-bun` に渡す Bun のバージョン指定子。デフォルトは
+      リポジトリ全体で揃えている `"1.3"`。
+      / Bun version spec forwarded to `oven-sh/setup-bun`. Defaults to
+      the repo-wide `"1.3"`.
+    required: false
+    default: "1.3"
+  install-deps:
+    description: >
+      `"false"` を渡すとルートの `bun install --frozen-lockfile` をスキップする。
+      `server/mcp` など個別ワークスペースで install するジョブ向け。
+      / Set to `"false"` to skip the root `bun install --frozen-lockfile`,
+      useful for jobs that install dependencies inside a specific workspace
+      (e.g. `server/mcp`).
+    required: false
+    default: "true"
+
+runs:
+  using: composite
+  steps:
+    # `Wandalen/wretry.action` は `uses:` 形式のアクションを丸ごとリトライする
+    # composite ラッパー。`setup-node` / `setup-bun` はいずれも
+    # `${{ github.token }}` を使って GitHub API を叩く JS アクションなので、
+    # GitHub バックエンドの一時的な 401/5xx で落ちることがある（Issue #937）。
+    #
+    # `Wandalen/wretry.action` is a composite wrapper that retries the inner
+    # `uses:` action up to `attempt_limit` times. `setup-node` / `setup-bun`
+    # are JS actions that authenticate against the GitHub API via
+    # `${{ github.token }}`, and have been observed to fail intermittently
+    # on transient 401/5xx responses (Issue #937).
+    - name: Setup Node (with retry)
+      uses: Wandalen/wretry.action@v3
+      with:
+        action: actions/setup-node@v6
+        with: |
+          node-version-file: .nvmrc
+        attempt_limit: 3
+        attempt_delay: 5000
+
+    - name: Setup Bun (with retry)
+      if: inputs.setup-bun == 'true'
+      uses: Wandalen/wretry.action@v3
+      with:
+        action: oven-sh/setup-bun@v2
+        # `token` を明示的に渡さないと、`Wandalen/wretry.action` 経由のネスト
+        # 呼び出しで `setup-bun` のデフォルト式 `${{ github.token }}` が解決
+        # されず "Bad credentials" (401) で恒常的に失敗する（Issue #937 で
+        # 解こうとした症状が、皮肉にも wretry 経由だと逆に再現する）。
+        #
+        # Pass `token` explicitly. When `setup-bun` is invoked through
+        # `Wandalen/wretry.action`, the action.yml default expression
+        # `${{ github.token }}` does not resolve in the nested context and
+        # the API call to api.github.com hits a persistent "Bad credentials"
+        # 401 (the very symptom Issue #937 sought to fix, ironically
+        # reproduced by the wrapper unless the token is forwarded by hand).
+        with: |
+          bun-version: ${{ inputs.bun-version }}
+          token: ${{ github.token }}
+        attempt_limit: 3
+        attempt_delay: 5000
+
+    # `bun install` の失敗は GitHub API ではなく npm レジストリ側の一過性問題
+    # が主な要因。`Wandalen/wretry.action` でラップする必要はないので、シェル
+    # で素直に再試行する。バックオフは 5s → 10s（線形）→ 失敗扱いで終了。
+    #
+    # Retry `bun install` from shell rather than wretry — the failure mode
+    # here is npm-registry / network flake rather than GitHub API auth, and
+    # shell-level retry keeps the composite action simpler. Backoff is
+    # 5s / 10s (linear), then the step fails.
+    - name: Install dependencies (with retry)
+      if: inputs.install-deps == 'true' && inputs.setup-bun == 'true'
+      shell: bash
+      run: |
+        set -uo pipefail
+        attempts=3
+        for i in $(seq 1 $attempts); do
+          echo "::group::bun install (attempt $i/$attempts)"
+          if bun install --frozen-lockfile; then
+            echo "::endgroup::"
+            exit 0
+          fi
+          echo "::endgroup::"
+          if [ "$i" -lt "$attempts" ]; then
+            sleep_seconds=$((i * 5))
+            echo "::warning::bun install attempt $i failed; sleeping ${sleep_seconds}s before retry"
+            sleep "$sleep_seconds"
+          fi
+        done
+        echo "::error::bun install --frozen-lockfile failed after $attempts attempts"
+        exit 1
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index cd5747bb..78b8698d 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -22,21 +22,21 @@ jobs:
     if: github.event_name != 'pull_request' || !github.event.pull_request.draft
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6.0.2
-
-      - uses: actions/setup-node@v6
-        with:
-          node-version-file: ".nvmrc"
-
-      - uses: oven-sh/setup-bun@v2
+      - name: Checkout (with retry)
+        uses: Wandalen/wretry.action@v3
         with:
-          bun-version: "1.3"
+          action: actions/checkout@v6.0.2
+          attempt_limit: 3
+          attempt_delay: 5000
 
-      - run: bun install --frozen-lockfile
+      - uses: ./.github/actions/setup-toolchain
 
       - name: Check formatting
         run: bun run format:check
 
+      - name: Check documentation pairs
+        run: bun run docs:check-pairs
+
       - name: Run linter
         run: bun run lint
 
@@ -45,17 +45,14 @@ jobs:
     if: github.event_name != 'pull_request' || !github.event.pull_request.draft
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6.0.2
-
-      - uses: actions/setup-node@v6
-        with:
-          node-version-file: ".nvmrc"
-
-      - uses: oven-sh/setup-bun@v2
+      - name: Checkout (with retry)
+        uses: Wandalen/wretry.action@v3
         with:
-          bun-version: "1.3"
+          action: actions/checkout@v6.0.2
+          attempt_limit: 3
+          attempt_delay: 5000
 
-      - run: bun install --frozen-lockfile
+      - uses: ./.github/actions/setup-toolchain
 
       - name: Run knip
         run: bun run knip
@@ -65,17 +62,14 @@ jobs:
     if: github.event_name != 'pull_request' || !github.event.pull_request.draft
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6.0.2
-
-      - uses: actions/setup-node@v6
+      - name: Checkout (with retry)
+        uses: Wandalen/wretry.action@v3
         with:
-          node-version-file: ".nvmrc"
+          action: actions/checkout@v6.0.2
+          attempt_limit: 3
+          attempt_delay: 5000
 
-      - uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: "1.3"
-
-      - run: bun install --frozen-lockfile
+      - uses: ./.github/actions/setup-toolchain
 
       - run: bunx tsc --noEmit
 
@@ -96,17 +90,14 @@ jobs:
     if: github.event_name != 'pull_request' || !github.event.pull_request.draft
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6.0.2
-
-      - uses: actions/setup-node@v6
-        with:
-          node-version-file: ".nvmrc"
-
-      - uses: oven-sh/setup-bun@v2
+      - name: Checkout (with retry)
+        uses: Wandalen/wretry.action@v3
         with:
-          bun-version: "1.3"
+          action: actions/checkout@v6.0.2
+          attempt_limit: 3
+          attempt_delay: 5000
 
-      - run: bun install --frozen-lockfile
+      - uses: ./.github/actions/setup-toolchain
 
       - run: bun run test:coverage
 
@@ -143,17 +134,14 @@ jobs:
     if: github.event_name != 'pull_request' || !github.event.pull_request.draft
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6.0.2
-
-      - uses: actions/setup-node@v6
-        with:
-          node-version-file: ".nvmrc"
-
-      - uses: oven-sh/setup-bun@v2
+      - name: Checkout (with retry)
+        uses: Wandalen/wretry.action@v3
         with:
-          bun-version: "1.3"
+          action: actions/checkout@v6.0.2
+          attempt_limit: 3
+          attempt_delay: 5000
 
-      - run: bun install --frozen-lockfile
+      - uses: ./.github/actions/setup-toolchain
 
       - run: bun run build
 
@@ -205,17 +193,14 @@ jobs:
     if: github.event_name != 'pull_request' || !github.event.pull_request.draft
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6.0.2
-
-      - uses: actions/setup-node@v6
-        with:
-          node-version-file: ".nvmrc"
-
-      - uses: oven-sh/setup-bun@v2
+      - name: Checkout (with retry)
+        uses: Wandalen/wretry.action@v3
         with:
-          bun-version: "1.3"
+          action: actions/checkout@v6.0.2
+          attempt_limit: 3
+          attempt_delay: 5000
 
-      - run: bun install --frozen-lockfile
+      - uses: ./.github/actions/setup-toolchain
 
       # Playwright のブラウザバイナリ + 必要な OS 依存を入れる。
       # Install Playwright's browser binaries plus the matching OS deps.
@@ -238,17 +223,14 @@ jobs:
     if: github.event_name != 'pull_request' || !github.event.pull_request.draft
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6.0.2
-
-      - uses: actions/setup-node@v6
+      - name: Checkout (with retry)
+        uses: Wandalen/wretry.action@v3
         with:
-          node-version-file: ".nvmrc"
+          action: actions/checkout@v6.0.2
+          attempt_limit: 3
+          attempt_delay: 5000
 
-      - uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: "1.3"
-
-      - run: bun install --frozen-lockfile
+      - uses: ./.github/actions/setup-toolchain
 
       # Bun workspaces are not used due to Railway build constraints.
       # Consider migrating to workspaces if Railway adds Bun workspace support.
@@ -273,15 +255,22 @@ jobs:
     if: github.event_name == 'pull_request' && !github.event.pull_request.draft
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6.0.2
+      # PR ベースとの diff を取るため履歴を全部取得する。
+      # Need full history so the script can diff against the PR base.
+      - name: Checkout (with retry)
+        uses: Wandalen/wretry.action@v3
         with:
-          # PR ベースとの diff を取るため履歴を全部取得する。
-          # Need full history so the script can diff against the PR base.
-          fetch-depth: 0
+          action: actions/checkout@v6.0.2
+          with: |
+            fetch-depth: 0
+          attempt_limit: 3
+          attempt_delay: 5000
 
-      - uses: actions/setup-node@v6
+      - uses: ./.github/actions/setup-toolchain
         with:
-          node-version-file: ".nvmrc"
+          # Node スクリプトしか実行しないため Bun は不要。
+          # The job only runs a Node script, so Bun is unnecessary.
+          setup-bun: "false"
 
       - name: Run drizzle migration consistency check
         env:
@@ -305,11 +294,18 @@ jobs:
     if: github.event_name != 'pull_request' || !github.event.pull_request.draft
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6.0.2
+      - name: Checkout (with retry)
+        uses: Wandalen/wretry.action@v3
+        with:
+          action: actions/checkout@v6.0.2
+          attempt_limit: 3
+          attempt_delay: 5000
 
-      - uses: actions/setup-node@v6
+      - uses: ./.github/actions/setup-toolchain
         with:
-          node-version-file: ".nvmrc"
+          # Node スクリプトしか実行しないため Bun は不要。
+          # The job only runs Node scripts, so Bun is unnecessary.
+          setup-bun: "false"
 
       - name: Unit-test drift extractors (regex + allowlist logic)
         run: node --test scripts/check-drizzle-schema-drift.test.mjs
@@ -322,15 +318,18 @@ jobs:
     if: github.event_name != 'pull_request' || !github.event.pull_request.draft
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6.0.2
-
-      - uses: actions/setup-node@v6
+      - name: Checkout (with retry)
+        uses: Wandalen/wretry.action@v3
         with:
-          node-version-file: ".nvmrc"
+          action: actions/checkout@v6.0.2
+          attempt_limit: 3
+          attempt_delay: 5000
 
-      - uses: oven-sh/setup-bun@v2
+      - uses: ./.github/actions/setup-toolchain
         with:
-          bun-version: "1.3"
+          # server/mcp 配下で個別に install するため、ルートの install は不要。
+          # The job installs deps inside server/mcp instead of the root.
+          install-deps: "false"
 
       # server/mcp is not part of the root Bun workspace; install its
       # dependencies locally before type-checking and testing.
@@ -357,17 +356,14 @@ jobs:
       - name: Record job start time
         run: echo "MUTATION_START=$(date +%s)" >> "$GITHUB_ENV"
 
-      - uses: actions/checkout@v6.0.2
-
-      - uses: actions/setup-node@v6
-        with:
-          node-version-file: ".nvmrc"
-
-      - uses: oven-sh/setup-bun@v2
+      - name: Checkout (with retry)
+        uses: Wandalen/wretry.action@v3
         with:
-          bun-version: "1.3"
+          action: actions/checkout@v6.0.2
+          attempt_limit: 3
+          attempt_delay: 5000
 
-      - run: bun install --frozen-lockfile
+      - uses: ./.github/actions/setup-toolchain
 
       # Golden list of files with stable mutation scores (Phase 1/2 of Epic #468).
       # 安定したスコアを持つファイルを段階的に追加し、PR で退行を早めに検知する。
@@ -400,19 +396,16 @@ jobs:
     if: github.event_name != 'pull_request' || !github.event.pull_request.draft
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6.0.2
-        with:
-          fetch-depth: 0
-
-      - uses: actions/setup-node@v6
-        with:
-          node-version-file: ".nvmrc"
-
-      - uses: oven-sh/setup-bun@v2
+      - name: Checkout (with retry)
+        uses: Wandalen/wretry.action@v3
         with:
-          bun-version: "1.3"
+          action: actions/checkout@v6.0.2
+          with: |
+            fetch-depth: 0
+          attempt_limit: 3
+          attempt_delay: 5000
 
-      - run: bun install --frozen-lockfile
+      - uses: ./.github/actions/setup-toolchain
 
       # Dependabot handles vulnerability alerts, but this catches issues in CI.
       # Dependabot は脆弱性アラートを担うが、CI でも依存関係を監査する。
diff --git a/.github/workflows/deploy-dev.yml b/.github/workflows/deploy-dev.yml
index dafa01b8..8a335356 100644
--- a/.github/workflows/deploy-dev.yml
+++ b/.github/workflows/deploy-dev.yml
@@ -17,15 +17,13 @@ jobs:
     runs-on: ubuntu-latest
     environment: development
     steps:
-      - uses: actions/checkout@v6.0.2
-      - uses: actions/setup-node@v6
+      - name: Checkout (with retry)
+        uses: Wandalen/wretry.action@v3
         with:
-          node-version-file: ".nvmrc"
-      - uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: "1.3"
-      - name: Install dependencies
-        run: bun install --frozen-lockfile
+          action: actions/checkout@v6.0.2
+          attempt_limit: 3
+          attempt_delay: 5000
+      - uses: ./.github/actions/setup-toolchain
       - name: Run migrations
         working-directory: server/api
         run: bunx drizzle-kit migrate
@@ -95,15 +93,15 @@ jobs:
     runs-on: ubuntu-latest
     environment: development
     steps:
-      - uses: actions/checkout@v6.0.2
-      - uses: actions/setup-node@v6
-        with:
-          node-version-file: ".nvmrc"
-      - uses: oven-sh/setup-bun@v2
+      - name: Checkout (with retry)
+        uses: Wandalen/wretry.action@v3
         with:
-          bun-version: "1.3"
-      - name: Install & Build
-        run: bun install --frozen-lockfile && bun run build
+          action: actions/checkout@v6.0.2
+          attempt_limit: 3
+          attempt_delay: 5000
+      - uses: ./.github/actions/setup-toolchain
+      - name: Build
+        run: bun run build
         env:
           VITE_API_BASE_URL: ${{ vars.API_BASE_URL }}
           VITE_REALTIME_URL: ${{ vars.REALTIME_URL }}
diff --git a/.github/workflows/deploy-prod.yml b/.github/workflows/deploy-prod.yml
index 9dd07a26..048d1852 100644
--- a/.github/workflows/deploy-prod.yml
+++ b/.github/workflows/deploy-prod.yml
@@ -20,15 +20,13 @@ jobs:
     runs-on: ubuntu-latest
     environment: production
     steps:
-      - uses: actions/checkout@v6.0.2
-      - uses: actions/setup-node@v6
+      - name: Checkout (with retry)
+        uses: Wandalen/wretry.action@v3
         with:
-          node-version-file: ".nvmrc"
-      - uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: "1.3"
-      - name: Install dependencies
-        run: bun install --frozen-lockfile
+          action: actions/checkout@v6.0.2
+          attempt_limit: 3
+          attempt_delay: 5000
+      - uses: ./.github/actions/setup-toolchain
       - name: Run migrations
         working-directory: server/api
         run: bunx drizzle-kit migrate
@@ -97,15 +95,15 @@ jobs:
     runs-on: ubuntu-latest
     environment: production
     steps:
-      - uses: actions/checkout@v6.0.2
-      - uses: actions/setup-node@v6
+      - name: Checkout (with retry)
+        uses: Wandalen/wretry.action@v3
         with:
-          node-version-file: ".nvmrc"
-      - uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: "1.3"
-      - name: Install & Build
-        run: bun install --frozen-lockfile && bun run build
+          action: actions/checkout@v6.0.2
+          attempt_limit: 3
+          attempt_delay: 5000
+      - uses: ./.github/actions/setup-toolchain
+      - name: Build
+        run: bun run build
         env:
           VITE_API_BASE_URL: ${{ vars.API_BASE_URL }}
           VITE_REALTIME_URL: ${{ vars.REALTIME_URL }}
@@ -155,21 +153,26 @@ jobs:
     runs-on: ubuntu-latest
     environment: production
     steps:
-      - uses: actions/checkout@v6.0.2
-      - uses: actions/setup-node@v6
-        with:
-          node-version-file: ".nvmrc"
-      - uses: oven-sh/setup-bun@v2
+      - name: Checkout (with retry)
+        uses: Wandalen/wretry.action@v3
         with:
-          bun-version: "1.3"
-      - name: Install & Build Admin
+          action: actions/checkout@v6.0.2
+          attempt_limit: 3
+          attempt_delay: 5000
+      # ルートには wrangler 用の依存が必要なので setup-toolchain の install を
+      # そのまま使う。admin/ 側は workspace 個別の install が必要なので別ステップ。
+      # Root install (handled by setup-toolchain) provides wrangler. The admin
+      # workspace needs its own install step (separate from the root).
+      - uses: ./.github/actions/setup-toolchain
+      - name: Install admin dependencies
         working-directory: admin
-        run: bun install --frozen-lockfile && bun run build
+        run: bun install --frozen-lockfile
+      - name: Build Admin
+        working-directory: admin
+        run: bun run build
         env:
           VITE_API_BASE_URL: ${{ vars.API_BASE_URL }}
           VITE_MAIN_APP_URL: ${{ vars.MAIN_APP_URL || 'https://zedi-note.app' }}
-      - name: Install root dependencies (for wrangler)
-        run: bun install --frozen-lockfile
       # Retry on transient Cloudflare Pages API 5xx (e.g. 503 no healthy upstream).
       # wrangler CLI reads CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID from env (see wrangler docs).
       - name: Deploy Admin to Cloudflare Pages
diff --git a/.github/workflows/nightly-mutation.yml b/.github/workflows/nightly-mutation.yml
index c974349b..29587d43 100644
--- a/.github/workflows/nightly-mutation.yml
+++ b/.github/workflows/nightly-mutation.yml
@@ -19,17 +19,14 @@ jobs:
     name: Mutation (full)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6.0.2
-
-      - uses: actions/setup-node@v6
-        with:
-          node-version-file: ".nvmrc"
-
-      - uses: oven-sh/setup-bun@v2
+      - name: Checkout (with retry)
+        uses: Wandalen/wretry.action@v3
         with:
-          bun-version: "1.3"
+          action: actions/checkout@v6.0.2
+          attempt_limit: 3
+          attempt_delay: 5000
 
-      - run: bun install --frozen-lockfile
+      - uses: ./.github/actions/setup-toolchain
 
       - name: Run mutation tests (full scope)
         run: bun run test:mutation
diff --git a/AGENTS.md b/AGENTS.md
index 53825d46..ab24e613 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,6 +15,8 @@ Cursor, Claude Code, GitHub Copilot, Codex 等すべてのエージェントが
   _Delete obsolete explanations (including local files) to avoid stale context._
 - **`docs/` を勝手に読まない**。ユーザーが `@ファイル` で添付したファイルは読む（`.cursor/rules/specification-and-docs.mdc`）。  
   _Do not browse `docs/` unless the user attaches a file via `@`._
+- **公開入口 Markdown（README / CONTRIBUTING 等）** — 英語が正本、日本語は `.ja.md` ペアで完全版を維持する。更新時は同一 PR で両方を揃える。詳細は [`DOCUMENTATION.md`](DOCUMENTATION.md)（gitignored な `docs/` とは別）。  
+  _User-facing GitHub entry docs: English canonical + `.ja.md` Japanese pair; update both in the same PR. See `DOCUMENTATION.md` (not the gitignored `docs/` tree)._
 
 ## 技術スタック
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 5ffa64e8..534f58ce 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,38 +1,89 @@
 # Zedi - Claude Code ガイドライン
 
+LLM のコーディングでよく起きるミスを減らすための行動指針。必要に応じてプロジェクト固有の指示と併用する。
+
 > **共通ガイドライン**: エージェント共通のルールは [AGENTS.md](./AGENTS.md) を参照。
-> 本ファイルは Claude Code 固有の補足事項を記載する。
+> 本ファイルは Claude Code 向けの行動指針と、同ファイルだけで押さえるべき補足を記載する。
+
+**トレードオフ:** 本ガイドは速度より慎重さを優先する。些末なタスクでは状況に応じて判断してよい。
+
+## 1. 実装前に考える
+
+**推測しない。混乱を隠さない。トレードオフを明示する。**
+
+実装に入る前に:
+
+- 前提は明示する。不明点があれば質問する。
+- 解釈が複数ある場合は、黙って選ばず提示する。
+- より単純な方法があれば述べる。必要なら反論する。
+- 不明瞭な点があれば止まる。何が分からないかを名指しして質問する。
+
+## 2. シンプルさを最優先
+
+**問題を解く最小限のコード。推測的な実装はしない。**
+
+- 依頼されていない機能は追加しない。
+- 一度しか使わないコードに抽象化を作らない。
+- 求められていない「柔軟性」や「設定可能さ」を入れない。
+- 起こり得ない状況向けのエラーハンドリングは書かない。
+- 200 行書いて 50 行で済むなら、書き直す。
+
+自問する: 「シニアエンジニアなら過剰だと言うか？」 なら、簡素化する。
+
+## 3. 変更は最小限に
+
+**触るのは必要な箇所だけ。片付けるのは自分が散らかした分だけ。**
+
+既存コードを編集するとき:
+
+- 隣接コード・コメント・フォーマットを「改善」しない。
+- 壊れていないものをリファクタしない。
+- 自分なら別の書き方をしても、既存スタイルに合わせる。
+- 無関係なデッドコードに気づいたら、削除せず言及する。
+
+自分の変更で不要になったもの:
+
+- 自分の変更で未使用になった import / 変数 / 関数は削除する。
+- もともと存在していたデッドコードは、依頼がない限り削除しない。
+
+判断基準: 変更した各行が、ユーザーの依頼に直接つながっていること。
+
+## 4. 目標から逆算して進める
+
+**成功基準を定義し、検証できるまで繰り返す。**
+
+タスクを検証可能な目標に変換する:
+
+- 「バリデーション追加」→ 不正入力のテストを書き、通るように実装する
+- 「バグ修正」→ 再現テストを書き、通るように修正する
+- 「X をリファクタ」→ 前後でテストが通ることを確認する
+
+複数ステップのタスクでは、短い計画を示す:
+
+```
+1. [ステップ] → 検証: [確認方法]
+2. [ステップ] → 検証: [確認方法]
+3. [ステップ] → 検証: [確認方法]
+```
 
-## 技術スタック
+成功基準が明確なら自律的に進められる。「動けばよい」だけでは、都度確認が必要になる。
 
-- **フロント**: React, TypeScript, Vite
-- **ランタイム**: Bun
-- **API**: `server/api`（Bun）
-- **Lint**: ESLint, Prettier
-- **テスト**: Vitest（単体）, Playwright（E2E）
+---
 
-## コードスタイル・レビュー観点
+**本ガイドが機能しているサイン:** diff の不要な変更が減る、過剰実装による書き直しが減る、実装前に確認質問が出る。
 
-- TypeScript を厳格に使用する。`any` は避け、型を明示する。
-- export する関数・型・インターフェースには TSDoc / JSDoc を付与する。
-- コメントやドキュメントは、原則として日本語と英語の両方を併記する。
-- テスト駆動開発（TDD）を徹底する。新規コンポーネント・API は**実装の前に**テストを書き、そのテストが通るように実装する。品質指標・仕様の置き場は [AGENTS.md](./AGENTS.md) と [SPECIFICATION_POLICY.md](./SPECIFICATION_POLICY.md) を参照。
-- `bun run lint` と `bun run format:check` が通る状態を維持する。
-- 既存のディレクトリ構成・命名規則（`server/api`, `server/hocuspocus`, `admin` など）に合わせる。
+---
 
-## PR レビュー時のチェック
+## プロジェクト固有の補足
 
-- セキュリティやパフォーマンスに影響しそうな変更がないか。
-- 公開 API や型の破壊的変更がないか。
-- エラーハンドリングとログが適切か。
-- 日本語・英語のコメント・ドキュメントがプロジェクトのトーンに合っているか。
+詳細（技術スタック、TDD、コードスタイル、PR 規約、ワークスペース構成など）は [AGENTS.md](./AGENTS.md) を正とする。ここでは Claude Code 利用時に特に踏み外しやすい点だけを補足する。
 
-## DB スキーマ変更
+### TDD との接続
 
-- TS スキーマ (`server/api/src/schema/**`) を変更した PR では必ず `server/api/drizzle/NNNN_*.sql` を新規追加し、`server/api/drizzle/meta/_journal.json` にもエントリを追記する。詳細は [AGENTS.md §「DB スキーマ変更」](./AGENTS.md#db-スキーマ変更必読--database-schema-changes-must-read) を参照。
-- CI の `drizzle-migration-check` ジョブが PR でスキーマ変更と SQL 追加のペアを強制する。
+- 新規コンポーネント・API は**実装前に**テストを書く（[AGENTS.md § テスト](./AGENTS.md#テストtdd)）。
+- 品質指標・仕様の置き場は [AGENTS.md](./AGENTS.md) と [SPECIFICATION_POLICY.md](./SPECIFICATION_POLICY.md) を参照。
 
-## その他
+### DB スキーマ変更
 
-- 変更が大きい場合は小さな PR に分けることを推奨する。
-- 環境変数やシークレットはリポジトリに含めず、`.env.example` で必要なキー名だけ示す。
+- TS スキーマ (`server/api/src/schema/**`) を変更した PR では、必ず `server/api/drizzle/NNNN_*.sql` を追加し、`server/api/drizzle/meta/_journal.json` にエントリを追記する。
+- 詳細と CI ガード（`drizzle-migration-check`）は [AGENTS.md § DB スキーマ変更](./AGENTS.md#db-スキーマ変更必読--database-schema-changes-must-read) を参照。
diff --git a/CONTRIBUTING.ja.md b/CONTRIBUTING.ja.md
new file mode 100644
index 00000000..7309d860
--- /dev/null
+++ b/CONTRIBUTING.ja.md
@@ -0,0 +1,363 @@
+> **言語:** [English](CONTRIBUTING.md) | 日本語
+
+# Zedi へのコントリビューション
+
+このガイドでは、プロジェクトへの貢献方法について説明します。
+
+## 📋 Table of Contents
+
+- [Contributing to Zedi](#contributing-to-zedi)
+  - [📋 Table of Contents](#-table-of-contents)
+  - [Code of Conduct](#code-of-conduct)
+  - [Getting Started](#getting-started)
+    - [1. リポジトリをフォーク](#1-リポジトリをフォーク)
+    - [2. ローカルにクローン](#2-ローカルにクローン)
+    - [3. 依存関係をインストール](#3-依存関係をインストール)
+    - [4. 開発サーバーを起動](#4-開発サーバーを起動)
+    - [5. upstream を設定](#5-upstream-を設定)
+  - [Development Workflow](#development-workflow)
+    - [ブランチ命名規則](#ブランチ命名規則)
+    - [開発フロー](#開発フロー)
+  - [Pull Request Process](#pull-request-process)
+    - [PR を作成する前に](#pr-を作成する前に)
+    - [PR テンプレート](#pr-テンプレート)
+    - [レビュープロセス](#レビュープロセス)
+  - [Coding Standards](#coding-standards)
+    - [TypeScript](#typescript)
+    - [React](#react)
+    - [ファイル構成](#ファイル構成)
+    - [スタイリング](#スタイリング)
+  - [Commit Message Guidelines](#commit-message-guidelines)
+    - [フォーマット](#フォーマット)
+    - [Type](#type)
+    - [例](#例)
+  - [Reporting Bugs](#reporting-bugs)
+    - [Issue に含める情報](#issue-に含める情報)
+    - [テンプレート](#テンプレート)
+  - [Suggesting Features](#suggesting-features)
+    - [提案に含める情報](#提案に含める情報)
+  - [Questions?](#questions)
+
+---
+
+## Code of Conduct
+
+このプロジェクトでは、すべての参加者に対して敬意を持ち、インクルーシブな環境を維持することを求めています。ハラスメントや差別的な行為は許容されません。
+
+---
+
+## Getting Started
+
+### 1. リポジトリをフォーク
+
+GitHub 上でこのリポジトリをフォークしてください。
+
+### 2. ローカルにクローン
+
+```bash
+git clone https://github.com/<your-username>/zedi.git
+cd zedi
+```
+
+### 3. セットアップ
+
+```bash
+# セットアップスクリプトを実行（推奨）
+bash scripts/setup.sh
+
+# または手動で
+bun install
+```
+
+### 4. upstream を設定
+
+```bash
+git remote add upstream https://github.com/otomatty/zedi.git
+```
+
+### 5. 開発サーバーを起動
+
+```bash
+bun run dev
+```
+
+---
+
+## Development Workflow
+
+### ブランチ命名規則
+
+| Type          | Format                                                                                                   | Example                 |
+| ------------- | -------------------------------------------------------------------------------------------------------- | ----------------------- |
+| Feature       | `feature/description`                                                                                    | `feature/add-backlinks` |
+| Bug Fix       | `fix/description`                                                                                        | `fix/search-crash`      |
+| Refactor      | `refactor/description`                                                                                   | `refactor/editor-hooks` |
+| Documentation | `chore/description` または `documentation/description`（`docs/` はフォルダ名と誤解されやすいため避ける） | `chore/update-readme`   |
+
+### 開発フロー
+
+> 📖 **ブランチ・PR・マージ方法**: ルートの [AGENTS.md](./AGENTS.md) を参照してください。
+
+1. **develop ブランチから最新を取得**
+
+   ```bash
+   git fetch origin
+   git checkout develop
+   git pull origin develop
+   ```
+
+2. **機能ブランチを作成**
+
+   ```bash
+   git checkout -b feature/your-feature
+   ```
+
+3. **変更を実装**
+   - コードを書く
+   - テストを追加
+   - ドキュメントを更新（英語正本 + 該当する場合は `.ja.md` ペア — [DOCUMENTATION.ja.md](./DOCUMENTATION.ja.md) 参照）
+
+4. **テストとコード品質チェック**
+
+   ```bash
+   # ユニットテスト
+   bun run test
+
+   # E2E テスト
+   bun run test:e2e
+
+   # Lint
+   bun run lint
+
+   # コードフォーマット
+   bun run format
+
+   # フォーマットチェック（CI で実行されるのと同じ）
+   bun run format:check
+   ```
+
+   > **Note:** コミット時に [husky](https://typicode.github.io/husky/) + [lint-staged](https://github.com/lint-staged/lint-staged) が自動的にリント・フォーマットを実行します。
+   > コミットメッセージは [Conventional Commits](https://www.conventionalcommits.org/) に従う必要があります（[commitlint](https://commitlint.js.org/) で検証）。
+
+5. **コミットしてプッシュ**
+
+   ```bash
+   git add .
+   git commit -m "feat: add backlinks feature"
+   git push origin feature/your-feature
+   ```
+
+6. **Pull Request を作成**
+   - ベースブランチ: `develop`
+   - CIが自動的に実行され、すべてのチェックが通ることを確認
+
+---
+
+## Pull Request Process
+
+### PR を作成する前に
+
+- [ ] テストがすべてパスすることを確認
+- [ ] Lint エラーがないことを確認
+- [ ] 関連する Issue があればリンク
+- [ ] 必要に応じてドキュメントを更新（英語正本 + 該当する場合は `.ja.md` ペア）
+
+### PR テンプレート
+
+```markdown
+## 概要
+
+変更内容の簡単な説明
+
+## 変更点
+
+- 変更点 1
+- 変更点 2
+
+## テスト方法
+
+この変更をテストする手順
+
+## スクリーンショット（UI 変更がある場合）
+
+## 関連 Issue
+
+Closes #123
+```
+
+### レビュープロセス
+
+1. PR を作成すると、メンテナーがレビューします
+2. フィードバックがあれば対応してください
+3. 承認されたらマージされます
+
+---
+
+## Coding Standards
+
+### TypeScript
+
+- 型定義を明示的に行う
+- `any` の使用は避ける
+- 関数には戻り値の型を指定
+
+```typescript
+// ✅ Good
+function getPage(id: string): Page | undefined {
+  return pages.find((p) => p.id === id);
+}
+
+// ❌ Bad
+function getPage(id) {
+  return pages.find((p) => p.id === id);
+}
+```
+
+### React
+
+- 関数コンポーネントを使用
+- カスタムフックで ロジックを分離
+- Props には明示的な型定義
+
+```typescript
+// ✅ Good
+interface PageCardProps {
+  page: Page;
+  onClick: (id: string) => void;
+}
+
+export function PageCard({ page, onClick }: PageCardProps) {
+  return <div onClick={() => onClick(page.id)}>{page.title}</div>;
+}
+```
+
+### ファイル構成
+
+```
+src/
+├── components/
+│   └── feature/
+│       ├── FeatureComponent.tsx
+│       └── FeatureComponent.test.tsx
+├── hooks/
+│   └── useFeature.ts
+└── lib/
+    └── featureUtils.ts
+```
+
+### スタイリング
+
+- Tailwind CSS を使用
+- shadcn/ui コンポーネントを活用
+- カスタムスタイルは最小限に
+
+---
+
+## Commit Message Guidelines
+
+[Conventional Commits](https://www.conventionalcommits.org/) に従います。
+
+### フォーマット
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+### Type
+
+| Type       | Description                                          |
+| ---------- | ---------------------------------------------------- |
+| `feat`     | 新機能                                               |
+| `fix`      | バグ修正                                             |
+| `docs`     | ドキュメントのみの変更                               |
+| `style`    | コードの意味に影響しない変更（空白、フォーマット等） |
+| `refactor` | バグ修正でも機能追加でもないコード変更               |
+| `perf`     | パフォーマンス改善                                   |
+| `test`     | テストの追加・修正                                   |
+| `chore`    | ビルドプロセスやツールの変更                         |
+
+### 例
+
+```bash
+feat(editor): add WikiLink autocomplete
+fix(search): resolve crash on empty query
+docs(readme): update installation instructions
+refactor(hooks): simplify usePageQueries
+```
+
+---
+
+## Reporting Bugs
+
+バグを見つけた場合は、Issue を作成してください。
+
+### Issue に含める情報
+
+1. **概要** — 何が問題か
+2. **再現手順** — 問題を再現する方法
+3. **期待する動作** — どう動作すべきか
+4. **実際の動作** — 実際に何が起きたか
+5. **環境**
+   - OS とバージョン
+   - ブラウザとバージョン
+   - Zedi のバージョン
+6. **スクリーンショット** — 可能であれば
+
+### テンプレート
+
+```markdown
+## バグの概要
+
+検索結果をクリックしてもページが開かない
+
+## 再現手順
+
+1. Cmd+K で検索を開く
+2. 「テスト」と入力
+3. 検索結果をクリック
+
+## 期待する動作
+
+クリックしたページが開く
+
+## 実際の動作
+
+何も起きない
+
+## 環境
+
+- OS: macOS Sonoma 14.2
+- Browser: Chrome 120
+- Zedi: v0.1.0
+
+## スクリーンショット
+
+[スクリーンショットをここに貼り付け]
+```
+
+---
+
+## Suggesting Features
+
+新機能のアイデアがあれば、Issue を作成してください。
+
+### 提案に含める情報
+
+1. **概要** — 何を追加したいか
+2. **動機** — なぜこの機能が必要か
+3. **詳細** — 機能の詳しい説明
+4. **代替案** — 検討した他の方法
+
+---
+
+## Questions?
+
+質問がある場合は、Issue を作成するか、Discussions でお気軽にお問い合わせください。
+
+---
+
+Thank you for contributing to Zedi! 🎉
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0ad08e41..302206fd 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,81 +1,61 @@
+> **Language:** English | [日本語](CONTRIBUTING.ja.md)
+
 # Contributing to Zedi
 
-Zedi へのコントリビューションに興味を持っていただきありがとうございます！
+Thank you for your interest in contributing to Zedi!
 
-このガイドでは、プロジェクトへの貢献方法について説明します。
+This guide explains how to contribute to the project.
 
 ## 📋 Table of Contents
 
-- [Contributing to Zedi](#contributing-to-zedi)
-  - [📋 Table of Contents](#-table-of-contents)
-  - [Code of Conduct](#code-of-conduct)
-  - [Getting Started](#getting-started)
-    - [1. リポジトリをフォーク](#1-リポジトリをフォーク)
-    - [2. ローカルにクローン](#2-ローカルにクローン)
-    - [3. 依存関係をインストール](#3-依存関係をインストール)
-    - [4. 開発サーバーを起動](#4-開発サーバーを起動)
-    - [5. upstream を設定](#5-upstream-を設定)
-  - [Development Workflow](#development-workflow)
-    - [ブランチ命名規則](#ブランチ命名規則)
-    - [開発フロー](#開発フロー)
-  - [Pull Request Process](#pull-request-process)
-    - [PR を作成する前に](#pr-を作成する前に)
-    - [PR テンプレート](#pr-テンプレート)
-    - [レビュープロセス](#レビュープロセス)
-  - [Coding Standards](#coding-standards)
-    - [TypeScript](#typescript)
-    - [React](#react)
-    - [ファイル構成](#ファイル構成)
-    - [スタイリング](#スタイリング)
-  - [Commit Message Guidelines](#commit-message-guidelines)
-    - [フォーマット](#フォーマット)
-    - [Type](#type)
-    - [例](#例)
-  - [Reporting Bugs](#reporting-bugs)
-    - [Issue に含める情報](#issue-に含める情報)
-    - [テンプレート](#テンプレート)
-  - [Suggesting Features](#suggesting-features)
-    - [提案に含める情報](#提案に含める情報)
-  - [Questions?](#questions)
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Workflow](#development-workflow)
+- [Pull Request Process](#pull-request-process)
+- [Coding Standards](#coding-standards)
+- [Commit Message Guidelines](#commit-message-guidelines)
+- [Reporting Bugs](#reporting-bugs)
+- [Suggesting Features](#suggesting-features)
+- [Questions?](#questions)
 
 ---
 
 ## Code of Conduct
 
-このプロジェクトでは、すべての参加者に対して敬意を持ち、インクルーシブな環境を維持することを求めています。ハラスメントや差別的な行為は許容されません。
+We expect all participants to treat each other with respect and maintain an inclusive environment. Harassment and discriminatory behavior are not tolerated.
 
 ---
 
 ## Getting Started
 
-### 1. リポジトリをフォーク
+### 1. Fork the repository
 
-GitHub 上でこのリポジトリをフォークしてください。
+Fork this repository on GitHub.
 
-### 2. ローカルにクローン
+### 2. Clone locally
 
 ```bash
 git clone https://github.com/<your-username>/zedi.git
 cd zedi
 ```
 
-### 3. セットアップ
+### 3. Setup
 
 ```bash
-# セットアップスクリプトを実行（推奨）
+# Recommended: run setup script
 bash scripts/setup.sh
 
-# または手動で
+# Or manually
 bun install
 ```
 
-### 4. upstream を設定
+### 4. Configure upstream
 
 ```bash
 git remote add upstream https://github.com/otomatty/zedi.git
 ```
 
-### 5. 開発サーバーを起動
+### 5. Start the dev server
 
 ```bash
 bun run dev
@@ -85,20 +65,20 @@ bun run dev
 
 ## Development Workflow
 
-### ブランチ命名規則
+### Branch naming
 
-| Type          | Format                                                                                                   | Example                 |
-| ------------- | -------------------------------------------------------------------------------------------------------- | ----------------------- |
-| Feature       | `feature/description`                                                                                    | `feature/add-backlinks` |
-| Bug Fix       | `fix/description`                                                                                        | `fix/search-crash`      |
-| Refactor      | `refactor/description`                                                                                   | `refactor/editor-hooks` |
-| Documentation | `chore/description` または `documentation/description`（`docs/` はフォルダ名と誤解されやすいため避ける） | `chore/update-readme`   |
+| Type          | Format                                                                                                 | Example                 |
+| ------------- | ------------------------------------------------------------------------------------------------------ | ----------------------- |
+| Feature       | `feature/description`                                                                                  | `feature/add-backlinks` |
+| Bug Fix       | `fix/description`                                                                                      | `fix/search-crash`      |
+| Refactor      | `refactor/description`                                                                                 | `refactor/editor-hooks` |
+| Documentation | `chore/description` or `documentation/description` (avoid `docs/` — easily confused with folder names) | `chore/update-readme`   |
 
-### 開発フロー
+### Development flow
 
-> 📖 **ブランチ・PR・マージ方法**: ルートの [AGENTS.md](./AGENTS.md) を参照してください。
+> 📖 **Branches, PRs, and merge policy**: See root [AGENTS.md](./AGENTS.md).
 
-1. **develop ブランチから最新を取得**
+1. **Sync latest from `develop`**
 
    ```bash
    git fetch origin
@@ -106,40 +86,40 @@ bun run dev
    git pull origin develop
    ```
 
-2. **機能ブランチを作成**
+2. **Create a feature branch**
 
    ```bash
    git checkout -b feature/your-feature
    ```
 
-3. **変更を実装**
-   - コードを書く
-   - テストを追加
-   - ドキュメントを更新
+3. **Implement changes**
+   - Write code
+   - Add tests
+   - Update documentation (English canonical + Japanese `.ja.md` pair when applicable — see [DOCUMENTATION.md](./DOCUMENTATION.md))
 
-4. **テストとコード品質チェック**
+4. **Run tests and quality checks**
 
    ```bash
-   # ユニットテスト
+   # Unit tests
    bun run test
 
-   # E2E テスト
+   # E2E tests
    bun run test:e2e
 
    # Lint
    bun run lint
 
-   # コードフォーマット
+   # Format
    bun run format
 
-   # フォーマットチェック（CI で実行されるのと同じ）
+   # Format check (same as CI)
    bun run format:check
    ```
 
-   > **Note:** コミット時に [husky](https://typicode.github.io/husky/) + [lint-staged](https://github.com/lint-staged/lint-staged) が自動的にリント・フォーマットを実行します。
-   > コミットメッセージは [Conventional Commits](https://www.conventionalcommits.org/) に従う必要があります（[commitlint](https://commitlint.js.org/) で検証）。
+   > **Note:** [husky](https://typicode.github.io/husky/) + [lint-staged](https://github.com/lint-staged/lint-staged) run lint and format on commit.
+   > Commit messages must follow [Conventional Commits](https://www.conventionalcommits.org/) ([commitlint](https://commitlint.js.org/) validates them).
 
-5. **コミットしてプッシュ**
+5. **Commit and push**
 
    ```bash
    git add .
@@ -147,49 +127,49 @@ bun run dev
    git push origin feature/your-feature
    ```
 
-6. **Pull Request を作成**
-   - ベースブランチ: `develop`
-   - CIが自動的に実行され、すべてのチェックが通ることを確認
+6. **Open a Pull Request**
+   - Base branch: `develop`
+   - CI runs automatically — ensure all checks pass
 
 ---
 
 ## Pull Request Process
 
-### PR を作成する前に
+### Before opening a PR
 
-- [ ] テストがすべてパスすることを確認
-- [ ] Lint エラーがないことを確認
-- [ ] 関連する Issue があればリンク
-- [ ] 必要に応じてドキュメントを更新
+- [ ] All tests pass
+- [ ] No lint errors
+- [ ] Link related Issues if any
+- [ ] Update documentation when needed (EN canonical + JA pair if applicable)
 
-### PR テンプレート
+### PR template
 
 ```markdown
-## 概要
+## Summary
 
-変更内容の簡単な説明
+Brief description of changes
 
-## 変更点
+## Changes
 
-- 変更点 1
-- 変更点 2
+- Change 1
+- Change 2
 
-## テスト方法
+## How to test
 
-この変更をテストする手順
+Steps to verify this change
 
-## スクリーンショット（UI 変更がある場合）
+## Screenshots (if UI changes)
 
-## 関連 Issue
+## Related Issue
 
 Closes #123
 ```
 
-### レビュープロセス
+### Review process
 
-1. PR を作成すると、メンテナーがレビューします
-2. フィードバックがあれば対応してください
-3. 承認されたらマージされます
+1. Maintainers review your PR after you open it
+2. Address feedback as needed
+3. Merge after approval
 
 ---
 
@@ -197,9 +177,9 @@ Closes #123
 
 ### TypeScript
 
-- 型定義を明示的に行う
-- `any` の使用は避ける
-- 関数には戻り値の型を指定
+- Use explicit types
+- Avoid `any`
+- Specify return types on functions
 
 ```typescript
 // ✅ Good
@@ -215,9 +195,9 @@ function getPage(id) {
 
 ### React
 
-- 関数コンポーネントを使用
-- カスタムフックで ロジックを分離
-- Props には明示的な型定義
+- Use function components
+- Extract logic into custom hooks
+- Explicit prop types
 
 ```typescript
 // ✅ Good
@@ -231,7 +211,7 @@ export function PageCard({ page, onClick }: PageCardProps) {
 }
 ```
 
-### ファイル構成
+### File layout
 
 ```
 src/
@@ -245,19 +225,19 @@ src/
     └── featureUtils.ts
 ```
 
-### スタイリング
+### Styling
 
-- Tailwind CSS を使用
-- shadcn/ui コンポーネントを活用
-- カスタムスタイルは最小限に
+- Use Tailwind CSS
+- Prefer shadcn/ui components
+- Keep custom styles minimal
 
 ---
 
 ## Commit Message Guidelines
 
-[Conventional Commits](https://www.conventionalcommits.org/) に従います。
+We follow [Conventional Commits](https://www.conventionalcommits.org/).
 
-### フォーマット
+### Format
 
 ```
 <type>(<scope>): <description>
@@ -269,18 +249,18 @@ src/
 
 ### Type
 
-| Type       | Description                                          |
-| ---------- | ---------------------------------------------------- |
-| `feat`     | 新機能                                               |
-| `fix`      | バグ修正                                             |
-| `docs`     | ドキュメントのみの変更                               |
-| `style`    | コードの意味に影響しない変更（空白、フォーマット等） |
-| `refactor` | バグ修正でも機能追加でもないコード変更               |
-| `perf`     | パフォーマンス改善                                   |
-| `test`     | テストの追加・修正                                   |
-| `chore`    | ビルドプロセスやツールの変更                         |
+| Type       | Description                              |
+| ---------- | ---------------------------------------- |
+| `feat`     | New feature                              |
+| `fix`      | Bug fix                                  |
+| `docs`     | Documentation only                       |
+| `style`    | Formatting, no code meaning change       |
+| `refactor` | Code change that is not a fix or feature |
+| `perf`     | Performance improvement                  |
+| `test`     | Add or update tests                      |
+| `chore`    | Build process or tooling                 |
 
-### 例
+### Examples
 
 ```bash
 feat(editor): add WikiLink autocomplete
@@ -293,70 +273,70 @@ refactor(hooks): simplify usePageQueries
 
 ## Reporting Bugs
 
-バグを見つけた場合は、Issue を作成してください。
+Open an Issue when you find a bug.
 
-### Issue に含める情報
+### Include in the Issue
 
-1. **概要** — 何が問題か
-2. **再現手順** — 問題を再現する方法
-3. **期待する動作** — どう動作すべきか
-4. **実際の動作** — 実際に何が起きたか
-5. **環境**
-   - OS とバージョン
-   - ブラウザとバージョン
-   - Zedi のバージョン
-6. **スクリーンショット** — 可能であれば
+1. **Summary** — What is wrong
+2. **Steps to reproduce**
+3. **Expected behavior**
+4. **Actual behavior**
+5. **Environment**
+   - OS and version
+   - Browser and version
+   - Zedi version
+6. **Screenshots** — If possible
 
-### テンプレート
+### Template
 
 ```markdown
-## バグの概要
+## Bug summary
 
-検索結果をクリックしてもページが開かない
+Clicking a search result does not open the page
 
-## 再現手順
+## Steps to reproduce
 
-1. Cmd+K で検索を開く
-2. 「テスト」と入力
-3. 検索結果をクリック
+1. Open search with Cmd+K
+2. Type "test"
+3. Click a result
 
-## 期待する動作
+## Expected behavior
 
-クリックしたページが開く
+The clicked page opens
 
-## 実際の動作
+## Actual behavior
 
-何も起きない
+Nothing happens
 
-## 環境
+## Environment
 
 - OS: macOS Sonoma 14.2
 - Browser: Chrome 120
 - Zedi: v0.1.0
 
-## スクリーンショット
+## Screenshots
 
-[スクリーンショットをここに貼り付け]
+[Paste screenshot here]
 ```
 
 ---
 
 ## Suggesting Features
 
-新機能のアイデアがあれば、Issue を作成してください。
+Open an Issue for feature ideas.
 
-### 提案に含める情報
+### Include in the proposal
 
-1. **概要** — 何を追加したいか
-2. **動機** — なぜこの機能が必要か
-3. **詳細** — 機能の詳しい説明
-4. **代替案** — 検討した他の方法
+1. **Summary** — What you want to add
+2. **Motivation** — Why it is needed
+3. **Details** — Detailed description
+4. **Alternatives** — Other approaches considered
 
 ---
 
 ## Questions?
 
-質問がある場合は、Issue を作成するか、Discussions でお気軽にお問い合わせください。
+Open an Issue or ask in Discussions.
 
 ---
 
diff --git a/DOCUMENTATION.ja.md b/DOCUMENTATION.ja.md
new file mode 100644
index 00000000..abe19672
--- /dev/null
+++ b/DOCUMENTATION.ja.md
@@ -0,0 +1,68 @@
+> **言語:** [English](DOCUMENTATION.md) | 日本語
+
+# 公開ドキュメント方針
+
+本リポジトリでは、**GitHub 上のユーザー向け入口ドキュメント**を英語（正本）と **日本語完全版**（`.ja.md` ペア）で管理する。これは [SPECIFICATION_POLICY.md](SPECIFICATION_POLICY.md) とは別物である。API 契約や振る舞いの正は **TSDoc/JSDoc とテスト** にあり、Markdown ツリーには書かない。
+
+## 対象
+
+| 英語（デフォルト）                                               | 日本語ペア                                                             |
+| ---------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| [README.md](README.md)                                           | [README.ja.md](README.ja.md)                                           |
+| [CONTRIBUTING.md](CONTRIBUTING.md)                               | [CONTRIBUTING.ja.md](CONTRIBUTING.ja.md)                               |
+| [SECURITY.md](SECURITY.md)                                       | [SECURITY.ja.md](SECURITY.ja.md)                                       |
+| [DOCUMENTATION.md](DOCUMENTATION.md)                             | [DOCUMENTATION.ja.md](DOCUMENTATION.ja.md)                             |
+| [extension/README.md](extension/README.md)                       | [extension/README.ja.md](extension/README.ja.md)                       |
+| [server/mcp/README.md](server/mcp/README.md)                     | [server/mcp/README.ja.md](server/mcp/README.ja.md)                     |
+| [admin/README.md](admin/README.md)                               | [admin/README.ja.md](admin/README.ja.md)                               |
+| [terraform/cloudflare/README.md](terraform/cloudflare/README.md) | [terraform/cloudflare/README.ja.md](terraform/cloudflare/README.ja.md) |
+
+**対象外:** [AGENTS.md](AGENTS.md)、[SPECIFICATION_POLICY.md](SPECIFICATION_POLICY.md)、[CLAUDE.md](CLAUDE.md)、[CHANGELOG.md](CHANGELOG.md)、Git 追跡外のローカル `docs/`。
+
+## 命名規則
+
+- GitHub が自動表示するのは `README.md` など英語ファイル。
+- 日本語完全版は同じベース名 + `.ja.md`（例: `README.ja.md`）。
+
+## 言語バナー（必須）
+
+各ファイルの先頭:
+
+**英語:**
+
+```markdown
+> **Language:** English | [日本語](README.ja.md)
+```
+
+**日本語:**
+
+```markdown
+> **言語:** [English](README.md) | 日本語
+```
+
+ペアファイルへの相対リンクを使う。サブディレクトリでは同じフォルダ内のペアを指す。
+
+## 更新手順
+
+1. **英語が正本** — 新規・変更は英語を先に書く。
+2. **同一 PR** — `.ja.md` ペアも同じ Pull Request で更新する（完全版ペア）。
+3. ドキュメントのみの大きな PR では、本文に `Doc parity: EN updated, JA follows in this PR` と記載する。
+
+## 公開ドキュメントに書く内容
+
+- プロジェクト概要、セットアップ、コントリビューション、セキュリティ報告
+- 詳細な契約は TSDoc / テストを参照する旨の誘導
+
+## 書かない内容
+
+- モジュールの受入条件・非目標（→ TSDoc）
+- 振る舞いの詳細仕様（→ テスト）
+- 長文の下書き（→ ローカル専用の gitignored `docs/` のみ）
+
+## CI チェック
+
+```bash
+bun run docs:check-pairs
+```
+
+ペアファイルの存在と言語バナーを検証する。
diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md
new file mode 100644
index 00000000..3042f7d5
--- /dev/null
+++ b/DOCUMENTATION.md
@@ -0,0 +1,68 @@
+> **Language:** English | [日本語](DOCUMENTATION.ja.md)
+
+# Public documentation policy
+
+This repository keeps **user-facing GitHub entry docs** in English (canonical) with **full Japanese pairs** (`.ja.md`). This is separate from [SPECIFICATION_POLICY.md](SPECIFICATION_POLICY.md): API contracts and behavior live in **TSDoc/JSDoc and tests**, not in Markdown trees.
+
+## Scope
+
+| English (default)                                                | Japanese pair                                                          |
+| ---------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| [README.md](README.md)                                           | [README.ja.md](README.ja.md)                                           |
+| [CONTRIBUTING.md](CONTRIBUTING.md)                               | [CONTRIBUTING.ja.md](CONTRIBUTING.ja.md)                               |
+| [SECURITY.md](SECURITY.md)                                       | [SECURITY.ja.md](SECURITY.ja.md)                                       |
+| [DOCUMENTATION.md](DOCUMENTATION.md)                             | [DOCUMENTATION.ja.md](DOCUMENTATION.ja.md)                             |
+| [extension/README.md](extension/README.md)                       | [extension/README.ja.md](extension/README.ja.md)                       |
+| [server/mcp/README.md](server/mcp/README.md)                     | [server/mcp/README.ja.md](server/mcp/README.ja.md)                     |
+| [admin/README.md](admin/README.md)                               | [admin/README.ja.md](admin/README.ja.md)                               |
+| [terraform/cloudflare/README.md](terraform/cloudflare/README.md) | [terraform/cloudflare/README.ja.md](terraform/cloudflare/README.ja.md) |
+
+**Out of scope:** [AGENTS.md](AGENTS.md), [SPECIFICATION_POLICY.md](SPECIFICATION_POLICY.md), [CLAUDE.md](CLAUDE.md), [CHANGELOG.md](CHANGELOG.md), gitignored local `docs/`.
+
+## Naming
+
+- GitHub shows `README.md` (etc.) by default — always English.
+- Japanese full versions use the same basename + `.ja.md` (e.g. `README.ja.md`).
+
+## Language banner (required)
+
+First lines of each file:
+
+**English:**
+
+```markdown
+> **Language:** English | [日本語](README.ja.md)
+```
+
+**Japanese:**
+
+```markdown
+> **言語:** [English](README.md) | 日本語
+```
+
+Use relative links to the paired file. In subdirectories, link to the sibling pair in the same folder.
+
+## Update workflow
+
+1. **English is canonical** — write or change English first.
+2. **Same PR** — update the `.ja.md` pair in the same pull request (full parity).
+3. For large doc-only PRs, note in the PR body: `Doc parity: EN updated, JA follows in this PR`.
+
+## What belongs in public docs
+
+- Project overview, setup, contribution, security reporting
+- Pointers to TSDoc/tests for detailed contracts
+
+## What does not belong here
+
+- Module acceptance criteria or non-goals (→ TSDoc)
+- Detailed behavior specs (→ tests)
+- Long drafts (→ local gitignored `docs/` only)
+
+## CI check
+
+```bash
+bun run docs:check-pairs
+```
+
+Verifies pair files exist and language banners are present.
diff --git a/README.ja.md b/README.ja.md
new file mode 100644
index 00000000..6cdad858
--- /dev/null
+++ b/README.ja.md
@@ -0,0 +1,387 @@
+> **言語:** [English](README.md) | 日本語
+
+<p align="center">
+  <img src="public/favicon.svg" alt="Zedi Logo" width="120" height="120" />
+</p>
+
+<h1 align="center">Zedi</h1>
+
+<p align="center">
+  <strong>Zero-Friction Knowledge Network</strong><br />
+  思考を宇宙のように拡張する、AIネイティブなナレッジアプリ
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> •
+  <a href="#demo">Demo</a> •
+  <a href="#getting-started">Getting Started</a> •
+  <a href="#tech-stack">Tech Stack</a> •
+  <a href="#roadmap">Roadmap</a> •
+  <a href="#contributing">Contributing</a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/status-alpha-orange" alt="Status: Alpha" />
+  <img src="https://img.shields.io/badge/license-BSL%201.1-blue" alt="License: BSL 1.1" />
+  <img src="https://img.shields.io/badge/PRs-welcome-brightgreen" alt="PRs Welcome" />
+</p>
+
+---
+
+## 🌟 Overview
+
+**Zedi** は、「書くストレス」と「整理する義務」からあなたを解放するナレッジアプリです。
+
+従来のメモアプリでは、情報をフォルダに分類し、手動でリンクを作成する必要がありました。Zedi は AI による足場生成（Scaffolding）と WikiLink によるネットワーク構造で、思考を自然に拡張させます。
+
+### 💡 デザイン原則
+
+- **Speed & Flow** — 起動0秒、保存不要。思考の速度で書ける
+- **Context over Folder** — フォルダ不要。時間とリンクで自然に整理
+- **Atomic & Constraint** — 1ページ1アイデア。小さく繋げる
+- **Scaffolding by AI** — AIが知識の足場を自動生成
+- **Dormant Seeds** — 未整理のメモも「発芽待ちの種」として許容
+
+---
+
+## ✨ Features
+
+### 📅 Date Grid
+
+日付ごとにグループ化されたページをグリッド表示。「いつ何を書いたか」が一目瞭然。
+
+### 🔗 WikiLinks
+
+`[[ページタイトル]]` 記法で簡単にページ間リンク。オートコンプリート付きで既存ページにすばやくアクセス。
+
+### 🤖 AI Wiki Generator
+
+キーワードを選択して AI に解説を生成させると、関連トピックへのリンクも自動挿入。知識のネットワークが自動的に広がります。
+
+### 🌐 Web Clipper
+
+URL を入力するだけで Web ページの本文を自動抽出。あとから自分のペースでキーワードをリンク化できます。
+
+### 🔍 Global Search
+
+`Cmd+K` / `Ctrl+K` で全文検索を起動。キーワードを含むページを瞬時に発見。
+
+### 🔀 Linked Pages
+
+ページ下部に関連ページを自動表示：
+
+- **Outgoing Links** — このページからリンクしている先
+- **Backlinks** — このページにリンクしている元
+- **2-hop Links** — リンク先のリンク先まで辿れる
+
+### ⌨️ Keyboard Shortcuts
+
+- `Cmd/Ctrl + K` — グローバル検索
+- `Cmd/Ctrl + N` — 新規ページ作成
+- `Cmd/Ctrl + H` — ホーム画面へ
+- `Cmd/Ctrl + /` — ショートカット一覧
+
+### 📝 Markdown Editor
+
+Tiptap ベースのリッチエディタ。Markdown ショートカットでシームレスに書ける。
+
+- `# ` → 見出し
+- `- ` → 箇条書き
+- `> ` → 引用
+- `**text**` → 太字
+- `` ` `` → コードブロック
+
+---
+
+## 🎬 Demo
+
+> 🚧 **Coming Soon** — スクリーンショットとデモ動画を準備中です
+
+<!--
+Demo screenshots: place assets under public/ when available. Tracked prose lives in source (TSDoc); optional local docs/ is gitignored — see AGENTS.md.
+-->
+
+---
+
+## 🚀 Getting Started
+
+### 前提条件
+
+- [Bun](https://bun.sh/) v1.0 以上（必須）
+- [Node.js](https://nodejs.org/) v24 以上（任意。CI・一部スクリプトで使用。`.nvmrc` / `engines.node` 参照）
+
+### クイックスタート
+
+```bash
+# リポジトリをクローン
+git clone https://github.com/otomatty/zedi.git
+cd zedi
+
+# セットアップスクリプトを実行（依存関係インストール + Git hooks 設定 + 検証）
+bash scripts/setup.sh
+
+# 開発サーバーを起動
+bun run dev
+```
+
+### 手動セットアップ
+
+```bash
+git clone https://github.com/otomatty/zedi.git
+cd zedi
+bun install
+bun run dev
+```
+
+ブラウザで http://localhost:30000 を開いてください（デフォルトポート）。
+
+### ポート設定
+
+複数のアプリを並列で開発する場合、ポートを変更できます：
+
+```bash
+# 方法1: 環境変数で指定
+VITE_PORT=30001 bun run dev
+
+# 方法2: .env.local ファイルを作成
+echo "VITE_PORT=30001" > .env.local
+bun run dev
+```
+
+ポートが使用中の場合は、自動的に次の利用可能なポートが使用されます。
+
+### Dockerを使った並列開発（オプション）
+
+複数のアプリケーションインスタンスを並列で開発する場合、Dockerを使用できます：
+
+```bash
+# Dockerイメージをビルド
+bun run docker:build
+
+# すべてのインスタンスを起動（3つ同時に起動）
+bun run docker:up
+
+# バックグラウンドで起動
+bun run docker:up:d
+
+# 停止
+bun run docker:down
+
+# ログを確認
+bun run docker:logs
+```
+
+起動後、以下のURLでアクセスできます：
+
+- インスタンス1: http://localhost:30000
+- インスタンス2: http://localhost:30001
+- インスタンス3: http://localhost:30002
+
+Docker で複数インスタンスを動かす場合は、ポートをずらして起動する（チーム内で手順を共有する）。
+
+> **Note:** Dockerを使う場合、最低8GBのRAM（推奨: 16GB以上）が必要です。軽量な並列開発が必要な場合は、環境変数によるポート設定の方が適しています。
+
+### デスクトップアプリ（Tauri）
+
+Zedi は [Tauri 2.0](https://v2.tauri.app/) によるデスクトップアプリとしても起動できます。
+
+#### 前提条件（Desktop）
+
+- [Rust](https://www.rust-lang.org/tools/install) (rustup で stable を導入)
+- **Windows**: Microsoft C++ Build Tools + Windows 11 SDK
+- **macOS**: Xcode Command Line Tools (`xcode-select --install`)
+- **Linux**: `libwebkit2gtk-4.1-dev`, `build-essential`, `libssl-dev` 等（[詳細](https://v2.tauri.app/guides/prerequisites/)）
+
+#### デスクトップアプリの起動
+
+```bash
+# 開発モード（Vite dev server + Tauri WebView）
+bun run tauri:dev
+
+# プロダクションビルド（インストーラー生成）
+bun run tauri:build
+```
+
+- **Claude Code sidecar** ([Issue #456](https://github.com/otomatty/zedi/issues/456)): `externalBin` 用の sidecar は `src-tauri/binaries/` に配置する。初回 `tauri:dev` で自動ビルド、手動は `bun run sidecar:build`。
+
+> **Windows + Git Bash の場合**: MSVC のビルドツールが PATH に含まれていない場合、
+> Developer Command Prompt for VS 2022 から実行するか、
+> `.bashrc` に `LIB`, `INCLUDE`, `PATH` を設定してください。
+> 詳細は [Issue #49](https://github.com/otomatty/zedi/issues/49) を参照。
+> **Note**: デスクトップ版は現在 Phase D（開発中）です。ストレージは暫定的に IndexedDB を使用しており、
+> Tauri 固有のストレージ (SQLite) は [#50](https://github.com/otomatty/zedi/issues/50) で対応予定です。
+
+### 環境変数の設定（オプション）
+
+AI 機能・認証・API 連携を使う場合は、`.env.local` を作成してください。サンプルは [.env.example](.env.example) を参照してください。
+
+```bash
+# REST API（Hono on Bun: server/api）。フロントから叩く API のベース URL。
+VITE_API_BASE_URL=http://localhost:3000
+
+# リアルタイム共同編集（Hocuspocus / Y.js: server/hocuspocus）
+VITE_REALTIME_URL=ws://localhost:1234   # 本番は wss://realtime.zedi-note.app など
+
+# Pro プラン課金（Polar、オプション）
+# VITE_POLAR_PRO_MONTHLY_PRODUCT_ID=...
+# VITE_POLAR_PRO_YEARLY_PRODUCT_ID=...
+```
+
+サーバー側（`server/api`）では Better Auth 用の `BETTER_AUTH_SECRET` / `BETTER_AUTH_URL`、PostgreSQL 接続情報、Polar の `POLAR_ACCESS_TOKEN`、メール送信用 `RESEND_API_KEY` などを設定します。詳細は [.env.example](.env.example) を参照してください。
+
+> **Note:** 環境変数なしでもフロント単体はローカルで動作します（一部データは IndexedDB に保存）。AI 機能はアプリの設定画面から各プロバイダの API キーを入力して使用できます。
+
+---
+
+## 🛠 Tech Stack
+
+| Category          | Technology                                                                                                 |
+| ----------------- | ---------------------------------------------------------------------------------------------------------- |
+| **Frontend**      | React 19 + TypeScript 6 / React Router v7                                                                  |
+| **Build Tool**    | Vite 8 (`@vitejs/plugin-react-swc`) / Bun                                                                  |
+| **Desktop**       | Tauri 2.0 (Rust) — `src-tauri/`                                                                            |
+| **Editor**        | Tiptap 3 (ProseMirror) — tables / math (KaTeX) / code (lowlight) / collaboration (Y.js)                    |
+| **Styling**       | Tailwind CSS v4 + shadcn/ui (Radix UI primitives) / `next-themes`                                          |
+| **State / Data**  | Zustand 5 + TanStack Query 5 / React Hook Form + Zod                                                       |
+| **i18n**          | i18next + react-i18next                                                                                    |
+| **Visualization** | Recharts / `@xyflow/react` (React Flow) / Mermaid / KaTeX / Tesseract.js (OCR)                             |
+| **Auth**          | [Better Auth](https://better-auth.com/) (OAuth / セッション cookie)                                        |
+| **API**           | `server/api` — Hono on Bun + Drizzle ORM (PostgreSQL)                                                      |
+| **Database**      | PostgreSQL (Drizzle migrations: `server/api/drizzle/`) / IndexedDB (local・ブラウザ)                       |
+| **Realtime**      | `server/hocuspocus` — Hocuspocus (Y.js) によるリアルタイム共同編集                                         |
+| **MCP**           | `server/mcp` — Claude Code 連携（stdio / HTTP、詳細は [server/mcp/README.ja.md](server/mcp/README.ja.md)） |
+| **Storage**       | AWS S3（API 経由でアップロード、`@aws-sdk/client-s3`）                                                     |
+| **Billing**       | [Polar](https://polar.sh/) (`@polar-sh/sdk`) — Pro プラン                                                  |
+| **Email**         | Resend                                                                                                     |
+| **AI**            | OpenAI / Anthropic / Google Gemini（OpenRouter で価格情報を取得）                                          |
+| **Browser Ext.**  | `extension/` — Manifest v3 (Chrome 拡張)                                                                   |
+| **Admin**         | `admin/` — 別 Vite + React アプリ                                                                          |
+| **Workspaces**    | Bun workspaces: `packages/ui`（shadcn）, `packages/claude-sidecar` / `admin`                               |
+| **Deploy**        | Cloudflare Pages（フロント） + Railway（`server/api`, `hocuspocus`, `mcp`） / Terraform (Cloudflare)       |
+| **CI/CD**         | GitHub Actions（lint / typecheck / test / mutation / deploy）                                              |
+| **Testing**       | Vitest 4 + Testing Library / Playwright / Stryker（Mutation Testing）                                      |
+| **Tooling**       | ESLint 9 / Prettier / Husky + lint-staged / commitlint / Knip                                              |
+
+---
+
+## 🗺 Roadmap
+
+### ✅ 完了
+
+- [x] React + Vite 基盤構築
+- [x] ページの CRUD 操作
+- [x] Date Grid UI
+- [x] WikiLink 機能（サジェスト付き）
+- [x] AI Wiki Generator
+- [x] Web Clipper
+- [x] Global Search
+- [x] キーボードショートカット
+- [x] Better Auth による認証（OAuth / セッション cookie）
+- [x] Markdown エクスポート
+- [x] Backlinks / 2-hop Links 表示
+- [x] Linked Pages カード表示
+
+ロードマップの詳細は Issue / Discussions を参照してください。
+
+---
+
+## 🧪 Testing
+
+```bash
+# ユニットテスト
+bun run test
+
+# E2E テスト
+bun run test:e2e
+
+# テストカバレッジ
+bun run test:coverage
+
+# Mutation testing（Stryker; 品質の第一指標は Mutation スコア）
+bun run test:mutation:dry
+bun run test:mutation
+```
+
+品質指標・テスト方針・仕様の書き方は [AGENTS.md](AGENTS.md) と [SPECIFICATION_POLICY.md](SPECIFICATION_POLICY.md) を参照してください。
+
+---
+
+## 📁 Project Structure
+
+```
+src/                     # フロントエンド本体（React + Vite）
+├── components/          # React コンポーネント（editor / page / search / layout / ui ほか）
+├── hooks/               # カスタムフック
+├── lib/                 # ユーティリティ（`claudeCode/` = Tauri↔Claude Code ブリッジ）
+├── pages/               # ルートに対応するページコンポーネント（React Router v7）
+├── stores/              # Zustand ストア
+└── types/               # TypeScript 型定義
+
+src-tauri/               # Tauri 2.0 デスクトップバックエンド（Rust）
+├── src/
+│   ├── main.rs          # デスクトップ エントリポイント
+│   ├── lib.rs           # Tauri アプリ本体・Commands 定義
+│   └── claude_sidecar.rs # Claude Code sidecar プロセス管理（Issue #456）
+├── binaries/            # externalBin（`bun run sidecar:build`、gitignore）
+├── capabilities/        # セキュリティ権限定義
+├── icons/               # アプリアイコン（各 OS 用）
+├── Cargo.toml           # Rust 依存管理
+└── tauri.conf.json      # Tauri 設定
+
+server/                  # Railway で個別デプロイされる Bun プロジェクト群
+├── api/                 # REST / Auth API（Hono on Bun + Better Auth + Drizzle ORM）
+├── hocuspocus/          # リアルタイム共同編集サーバー（Hocuspocus / Y.js）
+└── mcp/                 # MCP サーバー — Claude Code 連携（stdio / HTTP）。詳細は [server/mcp/README.ja.md](server/mcp/README.ja.md)
+
+packages/                # Bun workspaces（共有ライブラリ）
+├── ui/                  # `@zedi/ui` — shadcn/ui ベースの共有 UI コンポーネント
+└── claude-sidecar/      # Tauri sidecar 用 Claude Code クライアント
+
+admin/                   # 管理画面アプリ（別 Vite + React + Tailwind / `@zedi/ui` 利用）
+extension/               # ブラウザ拡張（Manifest v3、Web Clipper）
+server/api/drizzle/      # PostgreSQL マイグレーション（drizzle-kit が読む正本 / source of truth）
+terraform/cloudflare/    # Cloudflare 関連インフラ定義
+e2e/                     # Playwright E2E テスト
+scripts/                 # セットアップ / sidecar ビルド / Stryker / 拡張ビルド等のスクリプト
+.github/workflows/       # GitHub Actions（lint / typecheck / test / mutation / deploy）
+```
+
+---
+
+## 🤝 Contributing
+
+コントリビューションを歓迎します！
+
+1. このリポジトリをフォーク
+2. `develop`ブランチから機能ブランチを作成 (`git checkout -b feature/amazing-feature`)
+3. 変更をコミット (`git commit -m 'feat: add amazing feature'`)
+4. ブランチをプッシュ (`git push origin feature/amazing-feature`)
+5. `develop`ブランチに対して Pull Request を作成
+
+詳細は [CONTRIBUTING.ja.md](CONTRIBUTING.ja.md) と [AGENTS.md](AGENTS.md)（ブランチ・PR・マージ方法）を参照してください。
+
+---
+
+## 📄 License
+
+このプロジェクトは **Business Source License 1.1 (BSL 1.1)** の下で公開されています（Source-Available）。商用の競合サービスとしての提供は制限されますが、個人利用・社内利用・改変・再配布は許可されています。初回公開から **4 年後** に [Mozilla Public License 2.0 (MPL 2.0)](https://www.mozilla.org/en-US/MPL/2.0/) へ自動変換されます。詳細は [LICENSE](LICENSE) を参照してください。
+
+---
+
+## 🙏 Acknowledgments
+
+- [Tiptap](https://tiptap.dev/) — エディタフレームワーク（ProseMirror）
+- [shadcn/ui](https://ui.shadcn.com/) / [Radix UI](https://www.radix-ui.com/) — UI コンポーネント
+- [Hocuspocus](https://hocuspocus.dev/) / [Y.js](https://yjs.dev/) — リアルタイム共同編集
+- [Better Auth](https://better-auth.com/) — 認証（OAuth / セッション cookie）
+- [Hono](https://hono.dev/) — API フレームワーク（Bun 上）
+- [Drizzle ORM](https://orm.drizzle.team/) — TypeScript ORM
+- [Polar](https://polar.sh/) — Pro プランの課金基盤
+- [Tauri](https://tauri.app/) — クロスプラットフォーム デスクトップ
+- [Cloudflare Pages](https://pages.cloudflare.com/) / [Railway](https://railway.com/) — ホスティング
+
+---
+
+<p align="center">
+  Made with ❤️ by Saedgewell
+</p>
diff --git a/README.md b/README.md
index 53ceea84..32df5797 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,5 @@
+> **Language:** English | [日本語](README.ja.md)
+
 <p align="center">
   <img src="public/favicon.svg" alt="Zedi Logo" width="120" height="120" />
 </p>
@@ -6,7 +8,7 @@
 
 <p align="center">
   <strong>Zero-Friction Knowledge Network</strong><br />
-  思考を宇宙のように拡張する、AIネイティブなナレッジアプリ
+  An AI-native knowledge app that expands your thinking like the universe
 </p>
 
 <p align="center">
@@ -28,17 +30,17 @@
 
 ## 🌟 Overview
 
-**Zedi** は、「書くストレス」と「整理する義務」からあなたを解放するナレッジアプリです。
+**Zedi** is a knowledge app that frees you from the stress of writing and the obligation to organize.
 
-従来のメモアプリでは、情報をフォルダに分類し、手動でリンクを作成する必要がありました。Zedi は AI による足場生成（Scaffolding）と WikiLink によるネットワーク構造で、思考を自然に拡張させます。
+Traditional note apps force you to classify information into folders and create links by hand. Zedi uses AI scaffolding and a WikiLink network so your thinking can grow naturally.
 
-### 💡 デザイン原則
+### 💡 Design Principles
 
-- **Speed & Flow** — 起動0秒、保存不要。思考の速度で書ける
-- **Context over Folder** — フォルダ不要。時間とリンクで自然に整理
-- **Atomic & Constraint** — 1ページ1アイデア。小さく繋げる
-- **Scaffolding by AI** — AIが知識の足場を自動生成
-- **Dormant Seeds** — 未整理のメモも「発芽待ちの種」として許容
+- **Speed & Flow** — Zero startup delay, no manual save. Write at the speed of thought
+- **Context over Folder** — No folders. Organize naturally through time and links
+- **Atomic & Constraint** — One idea per page. Connect small pieces
+- **Scaffolding by AI** — AI automatically builds scaffolding for your knowledge
+- **Dormant Seeds** — Unorganized notes are allowed as seeds waiting to sprout
 
 ---
 
@@ -46,54 +48,54 @@
 
 ### 📅 Date Grid
 
-日付ごとにグループ化されたページをグリッド表示。「いつ何を書いたか」が一目瞭然。
+Pages grouped by date in a grid view. See at a glance when you wrote what.
 
 ### 🔗 WikiLinks
 
-`[[ページタイトル]]` 記法で簡単にページ間リンク。オートコンプリート付きで既存ページにすばやくアクセス。
+Link pages with `[[Page Title]]` syntax. Autocomplete helps you reach existing pages quickly.
 
 ### 🤖 AI Wiki Generator
 
-キーワードを選択して AI に解説を生成させると、関連トピックへのリンクも自動挿入。知識のネットワークが自動的に広がります。
+Select a keyword and let AI generate an explanation with related topic links inserted automatically. Your knowledge network grows on its own.
 
 ### 🌐 Web Clipper
 
-URL を入力するだけで Web ページの本文を自動抽出。あとから自分のペースでキーワードをリンク化できます。
+Enter a URL to extract the page body automatically. Link keywords at your own pace later.
 
 ### 🔍 Global Search
 
-`Cmd+K` / `Ctrl+K` で全文検索を起動。キーワードを含むページを瞬時に発見。
+Press `Cmd+K` / `Ctrl+K` for full-text search. Find pages containing your keywords instantly.
 
 ### 🔀 Linked Pages
 
-ページ下部に関連ページを自動表示：
+Related pages appear at the bottom of each page:
 
-- **Outgoing Links** — このページからリンクしている先
-- **Backlinks** — このページにリンクしている元
-- **2-hop Links** — リンク先のリンク先まで辿れる
+- **Outgoing Links** — Pages this page links to
+- **Backlinks** — Pages that link here
+- **2-hop Links** — Follow links from linked pages
 
 ### ⌨️ Keyboard Shortcuts
 
-- `Cmd/Ctrl + K` — グローバル検索
-- `Cmd/Ctrl + N` — 新規ページ作成
-- `Cmd/Ctrl + H` — ホーム画面へ
-- `Cmd/Ctrl + /` — ショートカット一覧
+- `Cmd/Ctrl + K` — Global search
+- `Cmd/Ctrl + N` — Create new page
+- `Cmd/Ctrl + H` — Go home
+- `Cmd/Ctrl + /` — Shortcut list
 
 ### 📝 Markdown Editor
 
-Tiptap ベースのリッチエディタ。Markdown ショートカットでシームレスに書ける。
+Tiptap-based rich editor with seamless Markdown shortcuts:
 
-- `# ` → 見出し
-- `- ` → 箇条書き
-- `> ` → 引用
-- `**text**` → 太字
-- `` ` `` → コードブロック
+- `# ` → Heading
+- `- ` → Bullet list
+- `> ` → Blockquote
+- `**text**` → Bold
+- `` ` `` → Code block
 
 ---
 
 ## 🎬 Demo
 
-> 🚧 **Coming Soon** — スクリーンショットとデモ動画を準備中です
+> 🚧 **Coming Soon** — Screenshots and demo video are in preparation
 
 <!--
 Demo screenshots: place assets under public/ when available. Tracked prose lives in source (TSDoc); optional local docs/ is gitignored — see AGENTS.md.
@@ -103,26 +105,26 @@ Demo screenshots: place assets under public/ when available. Tracked prose lives
 
 ## 🚀 Getting Started
 
-### 前提条件
+### Prerequisites
 
-- [Bun](https://bun.sh/) v1.0 以上（必須）
-- [Node.js](https://nodejs.org/) v24 以上（任意。CI・一部スクリプトで使用。`.nvmrc` / `engines.node` 参照）
+- [Bun](https://bun.sh/) v1.0 or later (required)
+- [Node.js](https://nodejs.org/) v24 or later (optional; used by CI and some scripts — see `.nvmrc` / `engines.node`)
 
-### クイックスタート
+### Quick Start
 
 ```bash
-# リポジトリをクローン
+# Clone the repository
 git clone https://github.com/otomatty/zedi.git
 cd zedi
 
-# セットアップスクリプトを実行（依存関係インストール + Git hooks 設定 + 検証）
+# Run setup (install deps + Git hooks + verification)
 bash scripts/setup.sh
 
-# 開発サーバーを起動
+# Start the dev server
 bun run dev
 ```
 
-### 手動セットアップ
+### Manual Setup
 
 ```bash
 git clone https://github.com/otomatty/zedi.git
@@ -131,252 +133,249 @@ bun install
 bun run dev
 ```
 
-ブラウザで http://localhost:30000 を開いてください（デフォルトポート）。
+Open http://localhost:30000 in your browser (default port).
 
-### ポート設定
+### Port Configuration
 
-複数のアプリを並列で開発する場合、ポートを変更できます：
+When running multiple app instances in parallel, you can change the port:
 
 ```bash
-# 方法1: 環境変数で指定
+# Option 1: environment variable
 VITE_PORT=30001 bun run dev
 
-# 方法2: .env.local ファイルを作成
+# Option 2: .env.local file
 echo "VITE_PORT=30001" > .env.local
 bun run dev
 ```
 
-ポートが使用中の場合は、自動的に次の利用可能なポートが使用されます。
+If the port is in use, the next available port is chosen automatically.
 
-### Dockerを使った並列開発（オプション）
+### Parallel Development with Docker (Optional)
 
-複数のアプリケーションインスタンスを並列で開発する場合、Dockerを使用できます：
+To run multiple application instances in parallel:
 
 ```bash
-# Dockerイメージをビルド
+# Build Docker image
 bun run docker:build
 
-# すべてのインスタンスを起動（3つ同時に起動）
+# Start all instances (3 at once)
 bun run docker:up
 
-# バックグラウンドで起動
+# Start in background
 bun run docker:up:d
 
-# 停止
+# Stop
 bun run docker:down
 
-# ログを確認
+# View logs
 bun run docker:logs
 ```
 
-起動後、以下のURLでアクセスできます：
+After startup, access:
 
-- インスタンス1: http://localhost:30000
-- インスタンス2: http://localhost:30001
-- インスタンス3: http://localhost:30002
+- Instance 1: http://localhost:30000
+- Instance 2: http://localhost:30001
+- Instance 3: http://localhost:30002
 
-Docker で複数インスタンスを動かす場合は、ポートをずらして起動する（チーム内で手順を共有する）。
+When running multiple Docker instances, offset ports as needed (share the procedure within your team).
 
-> **Note:** Dockerを使う場合、最低8GBのRAM（推奨: 16GB以上）が必要です。軽量な並列開発が必要な場合は、環境変数によるポート設定の方が適しています。
+> **Note:** Docker requires at least 8 GB RAM (16 GB+ recommended). For lightweight parallel dev, port configuration via environment variables is simpler.
 
-### デスクトップアプリ（Tauri）
+### Desktop App (Tauri)
 
-Zedi は [Tauri 2.0](https://v2.tauri.app/) によるデスクトップアプリとしても起動できます。
+Zedi can also run as a desktop app via [Tauri 2.0](https://v2.tauri.app/).
 
-#### 前提条件（Desktop）
+#### Desktop Prerequisites
 
-- [Rust](https://www.rust-lang.org/tools/install) (rustup で stable を導入)
+- [Rust](https://www.rust-lang.org/tools/install) (install stable via rustup)
 - **Windows**: Microsoft C++ Build Tools + Windows 11 SDK
 - **macOS**: Xcode Command Line Tools (`xcode-select --install`)
-- **Linux**: `libwebkit2gtk-4.1-dev`, `build-essential`, `libssl-dev` 等（[詳細](https://v2.tauri.app/guides/prerequisites/)）
+- **Linux**: `libwebkit2gtk-4.1-dev`, `build-essential`, `libssl-dev`, etc. ([details](https://v2.tauri.app/guides/prerequisites/))
 
-#### デスクトップアプリの起動
+#### Running the Desktop App
 
 ```bash
-# 開発モード（Vite dev server + Tauri WebView）
+# Dev mode (Vite dev server + Tauri WebView)
 bun run tauri:dev
 
-# プロダクションビルド（インストーラー生成）
+# Production build (generates installer)
 bun run tauri:build
 ```
 
-- **Claude Code sidecar** ([Issue #456](https://github.com/otomatty/zedi/issues/456)): Tauri bundles a compiled helper under `src-tauri/binaries/` (`externalBin`). On first `bun run tauri:dev`, a missing binary is built automatically; run `bun run sidecar:build` manually if needed. / `externalBin` 用の sidecar は `src-tauri/binaries/` に配置する。初回 `tauri:dev` で自動ビルド、手動は `bun run sidecar:build`。
+- **Claude Code sidecar** ([Issue #456](https://github.com/otomatty/zedi/issues/456)): Tauri bundles a compiled helper under `src-tauri/binaries/` (`externalBin`). On first `bun run tauri:dev`, a missing binary is built automatically; run `bun run sidecar:build` manually if needed.
 
-> **Windows + Git Bash の場合**: MSVC のビルドツールが PATH に含まれていない場合、
-> Developer Command Prompt for VS 2022 から実行するか、
-> `.bashrc` に `LIB`, `INCLUDE`, `PATH` を設定してください。
-> 詳細は [Issue #49](https://github.com/otomatty/zedi/issues/49) を参照。
-> **Note**: デスクトップ版は現在 Phase D（開発中）です。ストレージは暫定的に IndexedDB を使用しており、
-> Tauri 固有のストレージ (SQLite) は [#50](https://github.com/otomatty/zedi/issues/50) で対応予定です。
+> **Windows + Git Bash**: If MSVC build tools are not on PATH, run from Developer Command Prompt for VS 2022 or set `LIB`, `INCLUDE`, and `PATH` in `.bashrc`. See [Issue #49](https://github.com/otomatty/zedi/issues/49).
+>
+> **Note**: The desktop edition is currently Phase D (in development). Storage temporarily uses IndexedDB; Tauri-native storage (SQLite) is planned in [#50](https://github.com/otomatty/zedi/issues/50).
 
-### 環境変数の設定（オプション）
+### Environment Variables (Optional)
 
-AI 機能・認証・API 連携を使う場合は、`.env.local` を作成してください。サンプルは [.env.example](.env.example) を参照してください。
+For AI features, authentication, and API integration, create `.env.local`. See [.env.example](.env.example).
 
 ```bash
-# REST API（Hono on Bun: server/api）。フロントから叩く API のベース URL。
+# REST API (Hono on Bun: server/api). Base URL the frontend calls.
 VITE_API_BASE_URL=http://localhost:3000
 
-# リアルタイム共同編集（Hocuspocus / Y.js: server/hocuspocus）
-VITE_REALTIME_URL=ws://localhost:1234   # 本番は wss://realtime.zedi-note.app など
+# Real-time collaboration (Hocuspocus / Y.js: server/hocuspocus)
+VITE_REALTIME_URL=ws://localhost:1234   # Production: wss://realtime.zedi-note.app etc.
 
-# Pro プラン課金（Polar、オプション）
+# Pro plan billing (Polar, optional)
 # VITE_POLAR_PRO_MONTHLY_PRODUCT_ID=...
 # VITE_POLAR_PRO_YEARLY_PRODUCT_ID=...
 ```
 
-サーバー側（`server/api`）では Better Auth 用の `BETTER_AUTH_SECRET` / `BETTER_AUTH_URL`、PostgreSQL 接続情報、Polar の `POLAR_ACCESS_TOKEN`、メール送信用 `RESEND_API_KEY` などを設定します。詳細は [.env.example](.env.example) を参照してください。
+On the server (`server/api`), configure Better Auth (`BETTER_AUTH_SECRET` / `BETTER_AUTH_URL`), PostgreSQL, Polar `POLAR_ACCESS_TOKEN`, email `RESEND_API_KEY`, etc. See [.env.example](.env.example).
 
-> **Note:** 環境変数なしでもフロント単体はローカルで動作します（一部データは IndexedDB に保存）。AI 機能はアプリの設定画面から各プロバイダの API キーを入力して使用できます。
+> **Note:** The frontend runs locally without env vars (some data in IndexedDB). AI features can use provider API keys entered in the app settings.
 
 ---
 
 ## 🛠 Tech Stack
 
-| Category          | Technology                                                                                           |
-| ----------------- | ---------------------------------------------------------------------------------------------------- |
-| **Frontend**      | React 19 + TypeScript 6 / React Router v7                                                            |
-| **Build Tool**    | Vite 8 (`@vitejs/plugin-react-swc`) / Bun                                                            |
-| **Desktop**       | Tauri 2.0 (Rust) — `src-tauri/`                                                                      |
-| **Editor**        | Tiptap 3 (ProseMirror) — tables / math (KaTeX) / code (lowlight) / collaboration (Y.js)              |
-| **Styling**       | Tailwind CSS v4 + shadcn/ui (Radix UI primitives) / `next-themes`                                    |
-| **State / Data**  | Zustand 5 + TanStack Query 5 / React Hook Form + Zod                                                 |
-| **i18n**          | i18next + react-i18next                                                                              |
-| **Visualization** | Recharts / `@xyflow/react` (React Flow) / Mermaid / KaTeX / Tesseract.js (OCR)                       |
-| **Auth**          | [Better Auth](https://better-auth.com/) (OAuth / セッション cookie)                                  |
-| **API**           | `server/api` — Hono on Bun + Drizzle ORM (PostgreSQL)                                                |
-| **Database**      | PostgreSQL (Drizzle migrations: `server/api/drizzle/`) / IndexedDB (local・ブラウザ)                 |
-| **Realtime**      | `server/hocuspocus` — Hocuspocus (Y.js) によるリアルタイム共同編集                                   |
-| **MCP**           | `server/mcp` — Claude Code 連携（stdio / HTTP、詳細は [server/mcp/README.md](server/mcp/README.md)） |
-| **Storage**       | AWS S3（API 経由でアップロード、`@aws-sdk/client-s3`）                                               |
-| **Billing**       | [Polar](https://polar.sh/) (`@polar-sh/sdk`) — Pro プラン                                            |
-| **Email**         | Resend                                                                                               |
-| **AI**            | OpenAI / Anthropic / Google Gemini（OpenRouter で価格情報を取得）                                    |
-| **Browser Ext.**  | `extension/` — Manifest v3 (Chrome 拡張)                                                             |
-| **Admin**         | `admin/` — 別 Vite + React アプリ                                                                    |
-| **Workspaces**    | Bun workspaces: `packages/ui`（shadcn）, `packages/claude-sidecar` / `admin`                         |
-| **Deploy**        | Cloudflare Pages（フロント） + Railway（`server/api`, `hocuspocus`, `mcp`） / Terraform (Cloudflare) |
-| **CI/CD**         | GitHub Actions（lint / typecheck / test / mutation / deploy）                                        |
-| **Testing**       | Vitest 4 + Testing Library / Playwright / Stryker（Mutation Testing）                                |
-| **Tooling**       | ESLint 9 / Prettier / Husky + lint-staged / commitlint / Knip                                        |
+| Category          | Technology                                                                                              |
+| ----------------- | ------------------------------------------------------------------------------------------------------- |
+| **Frontend**      | React 19 + TypeScript 6 / React Router v7                                                               |
+| **Build Tool**    | Vite 8 (`@vitejs/plugin-react-swc`) / Bun                                                               |
+| **Desktop**       | Tauri 2.0 (Rust) — `src-tauri/`                                                                         |
+| **Editor**        | Tiptap 3 (ProseMirror) — tables / math (KaTeX) / code (lowlight) / collaboration (Y.js)                 |
+| **Styling**       | Tailwind CSS v4 + shadcn/ui (Radix UI primitives) / `next-themes`                                       |
+| **State / Data**  | Zustand 5 + TanStack Query 5 / React Hook Form + Zod                                                    |
+| **i18n**          | i18next + react-i18next                                                                                 |
+| **Visualization** | Recharts / `@xyflow/react` (React Flow) / Mermaid / KaTeX / Tesseract.js (OCR)                          |
+| **Auth**          | [Better Auth](https://better-auth.com/) (OAuth / session cookies)                                       |
+| **API**           | `server/api` — Hono on Bun + Drizzle ORM (PostgreSQL)                                                   |
+| **Database**      | PostgreSQL (Drizzle migrations: `server/api/drizzle/`) / IndexedDB (local browser)                      |
+| **Realtime**      | `server/hocuspocus` — Hocuspocus (Y.js) real-time collaboration                                         |
+| **MCP**           | `server/mcp` — Claude Code integration (stdio / HTTP; see [server/mcp/README.md](server/mcp/README.md)) |
+| **Storage**       | AWS S3 (upload via API, `@aws-sdk/client-s3`)                                                           |
+| **Billing**       | [Polar](https://polar.sh/) (`@polar-sh/sdk`) — Pro plan                                                 |
+| **Email**         | Resend                                                                                                  |
+| **AI**            | OpenAI / Anthropic / Google Gemini (pricing via OpenRouter)                                             |
+| **Browser Ext.**  | `extension/` — Manifest v3 (Chrome extension)                                                           |
+| **Admin**         | `admin/` — separate Vite + React app                                                                    |
+| **Workspaces**    | Bun workspaces: `packages/ui` (shadcn), `packages/claude-sidecar` / `admin`                             |
+| **Deploy**        | Cloudflare Pages (frontend) + Railway (`server/api`, `hocuspocus`, `mcp`) / Terraform (Cloudflare)      |
+| **CI/CD**         | GitHub Actions (lint / typecheck / test / mutation / deploy)                                            |
+| **Testing**       | Vitest 4 + Testing Library / Playwright / Stryker (mutation testing)                                    |
+| **Tooling**       | ESLint 9 / Prettier / Husky + lint-staged / commitlint / Knip                                           |
 
 ---
 
 ## 🗺 Roadmap
 
-### ✅ 完了
+### ✅ Completed
 
-- [x] React + Vite 基盤構築
-- [x] ページの CRUD 操作
+- [x] React + Vite foundation
+- [x] Page CRUD
 - [x] Date Grid UI
-- [x] WikiLink 機能（サジェスト付き）
+- [x] WikiLinks (with suggestions)
 - [x] AI Wiki Generator
 - [x] Web Clipper
 - [x] Global Search
-- [x] キーボードショートカット
-- [x] Better Auth による認証（OAuth / セッション cookie）
-- [x] Markdown エクスポート
-- [x] Backlinks / 2-hop Links 表示
-- [x] Linked Pages カード表示
+- [x] Keyboard shortcuts
+- [x] Better Auth (OAuth / session cookies)
+- [x] Markdown export
+- [x] Backlinks / 2-hop Links
+- [x] Linked Pages cards
 
-ロードマップの詳細は Issue / Discussions を参照してください。
+See Issues / Discussions for roadmap details.
 
 ---
 
 ## 🧪 Testing
 
 ```bash
-# ユニットテスト
+# Unit tests
 bun run test
 
-# E2E テスト
+# E2E tests
 bun run test:e2e
 
-# テストカバレッジ
+# Coverage
 bun run test:coverage
 
-# Mutation testing（Stryker; 品質の第一指標は Mutation スコア）
+# Mutation testing (Stryker; mutation score is the primary quality metric)
 bun run test:mutation:dry
 bun run test:mutation
 ```
 
-品質指標・テスト方針・仕様の書き方は [AGENTS.md](AGENTS.md) と [SPECIFICATION_POLICY.md](SPECIFICATION_POLICY.md) を参照してください。
+Quality metrics, testing policy, and how to write specifications: [AGENTS.md](AGENTS.md) and [SPECIFICATION_POLICY.md](SPECIFICATION_POLICY.md).
 
 ---
 
 ## 📁 Project Structure
 
 ```
-src/                     # フロントエンド本体（React + Vite）
-├── components/          # React コンポーネント（editor / page / search / layout / ui ほか）
-├── hooks/               # カスタムフック
-├── lib/                 # ユーティリティ（`claudeCode/` = Tauri↔Claude Code ブリッジ）
-├── pages/               # ルートに対応するページコンポーネント（React Router v7）
-├── stores/              # Zustand ストア
-└── types/               # TypeScript 型定義
-
-src-tauri/               # Tauri 2.0 デスクトップバックエンド（Rust）
+src/                     # Frontend (React + Vite)
+├── components/          # React components (editor / page / search / layout / ui etc.)
+├── hooks/               # Custom hooks
+├── lib/                 # Utilities (`claudeCode/` = Tauri↔Claude Code bridge)
+├── pages/               # Route page components (React Router v7)
+├── stores/              # Zustand stores
+└── types/               # TypeScript types
+
+src-tauri/               # Tauri 2.0 desktop backend (Rust)
 ├── src/
-│   ├── main.rs          # デスクトップ エントリポイント
-│   ├── lib.rs           # Tauri アプリ本体・Commands 定義
-│   └── claude_sidecar.rs # Claude Code sidecar プロセス管理（Issue #456）
-├── binaries/            # externalBin（`bun run sidecar:build`、gitignore）
-├── capabilities/        # セキュリティ権限定義
-├── icons/               # アプリアイコン（各 OS 用）
-├── Cargo.toml           # Rust 依存管理
-└── tauri.conf.json      # Tauri 設定
-
-server/                  # Railway で個別デプロイされる Bun プロジェクト群
-├── api/                 # REST / Auth API（Hono on Bun + Better Auth + Drizzle ORM）
-├── hocuspocus/          # リアルタイム共同編集サーバー（Hocuspocus / Y.js）
-└── mcp/                 # MCP サーバー — Claude Code 連携（stdio / HTTP）。詳細は [server/mcp/README.md](server/mcp/README.md)
-
-packages/                # Bun workspaces（共有ライブラリ）
-├── ui/                  # `@zedi/ui` — shadcn/ui ベースの共有 UI コンポーネント
-└── claude-sidecar/      # Tauri sidecar 用 Claude Code クライアント
-
-admin/                   # 管理画面アプリ（別 Vite + React + Tailwind / `@zedi/ui` 利用）
-extension/               # ブラウザ拡張（Manifest v3、Web Clipper）
-server/api/drizzle/      # PostgreSQL マイグレーション（drizzle-kit が読む正本 / source of truth）
-terraform/cloudflare/    # Cloudflare 関連インフラ定義
-e2e/                     # Playwright E2E テスト
-scripts/                 # セットアップ / sidecar ビルド / Stryker / 拡張ビルド等のスクリプト
-.github/workflows/       # GitHub Actions（lint / typecheck / test / mutation / deploy）
+│   ├── main.rs          # Desktop entry point
+│   ├── lib.rs           # Tauri app + command definitions
+│   └── claude_sidecar.rs # Claude Code sidecar process (Issue #456)
+├── binaries/            # externalBin (`bun run sidecar:build`, gitignored)
+├── capabilities/        # Security capability definitions
+├── icons/               # App icons (per OS)
+├── Cargo.toml           # Rust dependencies
+└── tauri.conf.json      # Tauri config
+
+server/                  # Bun projects deployed separately on Railway
+├── api/                 # REST / Auth API (Hono on Bun + Better Auth + Drizzle ORM)
+├── hocuspocus/          # Real-time collaboration (Hocuspocus / Y.js)
+└── mcp/                 # MCP server — Claude Code (stdio / HTTP). See [server/mcp/README.md](server/mcp/README.md)
+
+packages/                # Bun workspaces (shared libraries)
+├── ui/                  # `@zedi/ui` — shadcn/ui shared components
+└── claude-sidecar/      # Claude Code client for Tauri sidecar
+
+admin/                   # Admin SPA (separate Vite + React + Tailwind / `@zedi/ui`)
+extension/               # Browser extension (Manifest v3, Web Clipper)
+server/api/drizzle/      # PostgreSQL migrations (drizzle-kit source of truth)
+terraform/cloudflare/    # Cloudflare infrastructure
+e2e/                     # Playwright E2E tests
+scripts/                 # Setup / sidecar build / Stryker / extension build scripts
+.github/workflows/       # GitHub Actions (lint / typecheck / test / mutation / deploy)
 ```
 
 ---
 
 ## 🤝 Contributing
 
-コントリビューションを歓迎します！
+Contributions are welcome!
 
-1. このリポジトリをフォーク
-2. `develop`ブランチから機能ブランチを作成 (`git checkout -b feature/amazing-feature`)
-3. 変更をコミット (`git commit -m 'feat: add amazing feature'`)
-4. ブランチをプッシュ (`git push origin feature/amazing-feature`)
-5. `develop`ブランチに対して Pull Request を作成
+1. Fork this repository
+2. Create a feature branch from `develop` (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request against `develop`
 
-詳細は [CONTRIBUTING.md](CONTRIBUTING.md) と [AGENTS.md](AGENTS.md)（ブランチ・PR・マージ方法）を参照してください。
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) (branch, PR, and merge policy).
 
 ---
 
 ## 📄 License
 
-このプロジェクトは **Business Source License 1.1 (BSL 1.1)** の下で公開されています（Source-Available）。商用の競合サービスとしての提供は制限されますが、個人利用・社内利用・改変・再配布は許可されています。初回公開から **4 年後** に [Mozilla Public License 2.0 (MPL 2.0)](https://www.mozilla.org/en-US/MPL/2.0/) へ自動変換されます。詳細は [LICENSE](LICENSE) を参照してください。
+This project is released under the **Business Source License 1.1 (BSL 1.1)** (source-available). Commercial competing services are restricted; personal use, internal use, modification, and redistribution are allowed. It automatically converts to [Mozilla Public License 2.0 (MPL 2.0)](https://www.mozilla.org/en-US/MPL/2.0/) **four years** after first publication. See [LICENSE](LICENSE).
 
 ---
 
 ## 🙏 Acknowledgments
 
-- [Tiptap](https://tiptap.dev/) — エディタフレームワーク（ProseMirror）
-- [shadcn/ui](https://ui.shadcn.com/) / [Radix UI](https://www.radix-ui.com/) — UI コンポーネント
-- [Hocuspocus](https://hocuspocus.dev/) / [Y.js](https://yjs.dev/) — リアルタイム共同編集
-- [Better Auth](https://better-auth.com/) — 認証（OAuth / セッション cookie）
-- [Hono](https://hono.dev/) — API フレームワーク（Bun 上）
+- [Tiptap](https://tiptap.dev/) — Editor framework (ProseMirror)
+- [shadcn/ui](https://ui.shadcn.com/) / [Radix UI](https://www.radix-ui.com/) — UI components
+- [Hocuspocus](https://hocuspocus.dev/) / [Y.js](https://yjs.dev/) — Real-time collaboration
+- [Better Auth](https://better-auth.com/) — Authentication (OAuth / session cookies)
+- [Hono](https://hono.dev/) — API framework (on Bun)
 - [Drizzle ORM](https://orm.drizzle.team/) — TypeScript ORM
-- [Polar](https://polar.sh/) — Pro プランの課金基盤
-- [Tauri](https://tauri.app/) — クロスプラットフォーム デスクトップ
-- [Cloudflare Pages](https://pages.cloudflare.com/) / [Railway](https://railway.com/) — ホスティング
+- [Polar](https://polar.sh/) — Pro plan billing
+- [Tauri](https://tauri.app/) — Cross-platform desktop
+- [Cloudflare Pages](https://pages.cloudflare.com/) / [Railway](https://railway.com/) — Hosting
 
 ---
 
diff --git a/SECURITY.ja.md b/SECURITY.ja.md
new file mode 100644
index 00000000..715cabd2
--- /dev/null
+++ b/SECURITY.ja.md
@@ -0,0 +1,56 @@
+> **言語:** [English](SECURITY.md) | 日本語
+
+# セキュリティポリシー
+
+## サポート対象バージョン
+
+現在サポートされているバージョン:
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.1.x   | :white_check_mark: |
+
+## 脆弱性の報告
+
+セキュリティの脆弱性を発見した場合は、**公開の Issue として報告しないでください**。
+
+### 報告方法
+
+1. **メールで報告**: security@example.com（プロジェクトのセキュリティ連絡先に置き換えてください）
+2. **GitHub Security Advisories**: リポジトリの Security タブから Private vulnerability reporting を使用
+
+### 報告に含める情報
+
+- 脆弱性の詳細な説明
+- 再現手順
+- 影響を受けるバージョン
+- 可能であれば、修正案
+
+### 対応プロセス
+
+1. **確認**: 報告を受け取ったら、48時間以内に確認の連絡をします
+2. **調査**: 脆弱性を調査し、影響範囲を評価します
+3. **修正**: 優先度に応じて修正を行います
+4. **公開**: 修正がリリースされた後、適切なタイミングで脆弱性を公開します
+
+### セキュリティ上の考慮事項
+
+#### API キーの取り扱い
+
+- AI プロバイダの API キーは、アプリ設定から入力した場合ローカルに暗号化して保存されます
+- BYOK（Bring Your Own Key）: 推論のために Zedi サーバーへキーを送信しません
+
+#### データの保存
+
+- ローカルのみの利用ではブラウザの IndexedDB を使用する場合があります
+- 認証済みユーザーのデータは PostgreSQL（`server/api` 経由）に保存されます
+- リモート通信はすべて HTTPS で暗号化されます
+
+#### 認証
+
+- 認証には [Better Auth](https://better-auth.com/)（OAuth / セッション cookie）を使用しています
+- OAuth プロバイダ利用時、パスワードはアプリケーションコードでは取り扱いません
+
+---
+
+Zedi のセキュリティ向上にご協力いただきありがとうございます 🔒
diff --git a/SECURITY.md b/SECURITY.md
index 6bf44398..dccfd3aa 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -1,8 +1,10 @@
+> **Language:** English | [日本語](SECURITY.ja.md)
+
 # Security Policy
 
 ## Supported Versions
 
-現在サポートされているバージョン:
+Currently supported versions:
 
 | Version | Supported          |
 | ------- | ------------------ |
@@ -10,44 +12,44 @@
 
 ## Reporting a Vulnerability
 
-セキュリティの脆弱性を発見した場合は、**公開の Issue として報告しないでください**。
+If you discover a security vulnerability, **do not report it as a public Issue**.
 
-### 報告方法
+### How to report
 
-1. **メールで報告**: security@example.com (プロジェクトのセキュリティメールアドレスに置き換えてください)
-2. **GitHub Security Advisories**: リポジトリの Security タブから Private vulnerability reporting を使用
+1. **Email**: security@example.com (replace with the project security contact)
+2. **GitHub Security Advisories**: Use Private vulnerability reporting from the repository Security tab
 
-### 報告に含める情報
+### What to include
 
-- 脆弱性の詳細な説明
-- 再現手順
-- 影響を受けるバージョン
-- 可能であれば、修正案
+- Detailed description of the vulnerability
+- Steps to reproduce
+- Affected versions
+- Suggested fix, if available
 
-### 対応プロセス
+### Response process
 
-1. **確認**: 報告を受け取ったら、48時間以内に確認の連絡をします
-2. **調査**: 脆弱性を調査し、影響範囲を評価します
-3. **修正**: 優先度に応じて修正を行います
-4. **公開**: 修正がリリースされた後、適切なタイミングで脆弱性を公開します
+1. **Acknowledgment**: We confirm receipt within 48 hours
+2. **Investigation**: We assess impact and scope
+3. **Fix**: We patch according to severity
+4. **Disclosure**: We publish details after a fix is released, at an appropriate time
 
-### セキュリティ上の考慮事項
+### Security considerations
 
-#### API キーの取り扱い
+#### API keys
 
-- AI 機能用の API キーはローカルに暗号化して保存されます
-- API キーがサーバーに送信されることはありません（BYOK: Bring Your Own Key）
+- AI provider API keys are stored encrypted locally when configured in the app
+- BYOK (Bring Your Own Key): keys are not sent to Zedi servers for inference
 
-#### データの保存
+#### Data storage
 
-- ローカルデータは SQLite (sql.js) に保存されます
-- 認証済みユーザーのデータは Turso クラウドに同期されます
-- すべての通信は HTTPS で暗号化されます
+- Local-only mode may use IndexedDB in the browser
+- Authenticated user data is stored in PostgreSQL (via `server/api`)
+- All remote communication uses HTTPS
 
-#### 認証
+#### Authentication
 
-- 認証には Clerk を使用しています
-- パスワードはアプリケーション側では一切取り扱いません
+- Authentication uses [Better Auth](https://better-auth.com/) (OAuth / session cookies)
+- Passwords are not handled by application code when using OAuth providers
 
 ---
 
diff --git a/admin/README.ja.md b/admin/README.ja.md
new file mode 100644
index 00000000..6264b98e
--- /dev/null
+++ b/admin/README.ja.md
@@ -0,0 +1,48 @@
+> **言語:** [English](README.md) | 日本語
+
+# Zedi 管理画面
+
+管理者用 SPA（admin.zedi-note.app）。認証基盤と AI モデル管理を提供。
+
+## 開発
+
+```bash
+# 初回のみ
+cd admin && npm install
+
+# 起動（ポート 30001、API は ZEDI_API_PROXY_TARGET でプロキシ）
+npm run dev
+```
+
+ルートから:
+
+```bash
+npm run dev:admin
+```
+
+## ローカル動作確認
+
+バックエンド（`docker-compose -f docker-compose.dev.yml up --build`）起動後、管理画面を起動し、以下を確認する。
+
+- [ ] `http://localhost:30001` で管理画面が表示される
+- [ ] ログイン（Google/GitHub）後、管理者ユーザーなら AI モデル一覧が表示される
+- [ ] 非管理者なら「管理者権限がありません」等の案内が出る
+- [ ] モデルのトグル・ティア変更・同期が動作する
+
+## ビルド
+
+```bash
+cd admin && npm install && npm run build
+```
+
+出力は `admin/dist`。本番は Terraform で管理する Cloudflare Pages プロジェクト `zedi-admin` に対して、GitHub Actions `deploy-prod.yml` から自動デプロイする。
+
+## 環境変数
+
+- **開発:** `.env` に `ZEDI_API_PROXY_TARGET=http://localhost:3000` を設定すると `/api` がその API にプロキシされる。
+- **本番:** GitHub Actions の production environment から `VITE_API_BASE_URL=https://api.zedi-note.app` を渡してビルドする。`VITE_MAIN_APP_URL` は `https://zedi-note.app` を使用する。
+
+## 仕様
+
+- 挙動・契約は **ソースの TSDoc** とテストを正とする（[`SPECIFICATION_POLICY.md`](../SPECIFICATION_POLICY.md)）。
+- [Issue #141 — AIモデル管理](https://github.com/otomatty/zedi/issues/141)
diff --git a/admin/README.md b/admin/README.md
index 5c15cb21..8c397e57 100644
--- a/admin/README.md
+++ b/admin/README.md
@@ -1,46 +1,48 @@
-# Zedi 管理画面
+> **Language:** English | [日本語](README.ja.md)
 
-管理者用 SPA（admin.zedi-note.app）。認証基盤と AI モデル管理を提供。
+# Zedi Admin
 
-## 開発
+Admin SPA (admin.zedi-note.app). Provides authentication and AI model management.
+
+## Development
 
 ```bash
-# 初回のみ
+# First time only
 cd admin && npm install
 
-# 起動（ポート 30001、API は ZEDI_API_PROXY_TARGET でプロキシ）
+# Start (port 30001; API proxied via ZEDI_API_PROXY_TARGET)
 npm run dev
 ```
 
-ルートから:
+From repository root:
 
 ```bash
 npm run dev:admin
 ```
 
-## ローカル動作確認
+## Local verification
 
-バックエンド（`docker-compose -f docker-compose.dev.yml up --build`）起動後、管理画面を起動し、以下を確認する。
+After starting the backend (`docker-compose -f docker-compose.dev.yml up --build`), start the admin app and verify:
 
-- [ ] `http://localhost:30001` で管理画面が表示される
-- [ ] ログイン（Google/GitHub）後、管理者ユーザーなら AI モデル一覧が表示される
-- [ ] 非管理者なら「管理者権限がありません」等の案内が出る
-- [ ] モデルのトグル・ティア変更・同期が動作する
+- [ ] Admin UI loads at `http://localhost:30001`
+- [ ] After login (Google/GitHub), admin users see the AI model list
+- [ ] Non-admin users see an "insufficient permissions" message
+- [ ] Model toggle, tier change, and sync work
 
-## ビルド
+## Build
 
 ```bash
 cd admin && npm install && npm run build
 ```
 
-出力は `admin/dist`。本番は Terraform で管理する Cloudflare Pages プロジェクト `zedi-admin` に対して、GitHub Actions `deploy-prod.yml` から自動デプロイする。
+Output is `admin/dist`. Production deploys to Cloudflare Pages project `zedi-admin` via GitHub Actions `deploy-prod.yml` (managed by Terraform).
 
-## 環境変数
+## Environment variables
 
-- **開発:** `.env` に `ZEDI_API_PROXY_TARGET=http://localhost:3000` を設定すると `/api` がその API にプロキシされる。
-- **本番:** GitHub Actions の production environment から `VITE_API_BASE_URL=https://api.zedi-note.app` を渡してビルドする。`VITE_MAIN_APP_URL` は `https://zedi-note.app` を使用する。
+- **Development:** Set `ZEDI_API_PROXY_TARGET=http://localhost:3000` in `.env` to proxy `/api` to that API.
+- **Production:** GitHub Actions production environment passes `VITE_API_BASE_URL=https://api.zedi-note.app` at build time. `VITE_MAIN_APP_URL` is `https://zedi-note.app`.
 
-## 仕様
+## Specification
 
-- 挙動・契約は **ソースの TSDoc** とテストを正とする（[`SPECIFICATION_POLICY.md`](../SPECIFICATION_POLICY.md)）。
-- [Issue #141 — AIモデル管理](https://github.com/otomatty/zedi/issues/141)
+- Behavior and contracts are defined in **source TSDoc** and tests ([`SPECIFICATION_POLICY.md`](../SPECIFICATION_POLICY.md)).
+- [Issue #141 — AI model management](https://github.com/otomatty/zedi/issues/141)
diff --git a/bun.lock b/bun.lock
index 5ad7318c..df345c36 100644
--- a/bun.lock
+++ b/bun.lock
@@ -5,7 +5,7 @@
     "": {
       "name": "vite_react_shadcn_ts",
       "dependencies": {
-        "@anthropic-ai/sdk": "^0.96.0",
+        "@anthropic-ai/sdk": "^0.98.0",
         "@dagrejs/dagre": "^3.0.0",
         "@google/genai": "^2.0.1",
         "@google/generative-ai": "^0.24.1",
@@ -88,11 +88,12 @@
         "dompurify": "^3.3.3",
         "embla-carousel-react": "^8.6.0",
         "highlight.js": "^11.11.1",
+        "html2pdf.js": "^0.14.0",
         "i18next": "^26.0.1",
         "i18next-browser-languagedetector": "^8.2.1",
         "idb-keyval": "^6.2.2",
         "input-otp": "^1.4.2",
-        "katex": "^0.16.28",
+        "katex": "^0.17.0",
         "lowlight": "^3.3.0",
         "lucide-react": "^1.7.0",
         "mermaid": "^11.12.2",
@@ -153,7 +154,7 @@
         "bun-types": "^1.3.9",
         "cross-env": "^10.1.0",
         "eslint": "^9.39.4",
-        "eslint-plugin-jsdoc": "^62.8.0",
+        "eslint-plugin-jsdoc": "^63.0.0",
         "eslint-plugin-react": "^7.37.5",
         "eslint-plugin-react-hooks": "^7.0.1",
         "eslint-plugin-react-refresh": "^0.5.2",
@@ -309,7 +310,7 @@
 
     "@anthropic-ai/claude-agent-sdk-win32-x64": ["@anthropic-ai/claude-agent-sdk-win32-x64@0.3.143", "", { "os": "win32", "cpu": "x64" }, "sha512-46L2mkskvIRfwzHP3p0uUE5u9Oc7Eb/DRVmXuGNk5Z8jiahlDSv0SHP1vnWSWw5nWIu4DWOKyXZelRmYc9LxCg=="],
 
-    "@anthropic-ai/sdk": ["@anthropic-ai/sdk@0.96.0", "", { "dependencies": { "json-schema-to-ts": "^3.1.1", "standardwebhooks": "^1.0.0" }, "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" }, "optionalPeers": ["zod"], "bin": { "anthropic-ai-sdk": "bin/cli" } }, "sha512-KlCsODtTyb17bLUVCSDC2HtSvAbJf60sEiPEax9dInF+aDF92vS4TZJ5XD7YCQXNb1/5icYaw8Y7wMjPlIV9Zg=="],
+    "@anthropic-ai/sdk": ["@anthropic-ai/sdk@0.98.0", "", { "dependencies": { "json-schema-to-ts": "^3.1.1", "standardwebhooks": "^1.0.0" }, "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" }, "optionalPeers": ["zod"], "bin": { "anthropic-ai-sdk": "bin/cli" } }, "sha512-N7aXtCvC5g6T1Y4V29lJjceu/zTkVkIZF0jdBvagr0TRFHuKeImffalGWEfqZKrvjH+IQbzJWw6TmSmUzrlMgg=="],
 
     "@asamuzakjp/css-color": ["@asamuzakjp/css-color@5.0.1", "", { "dependencies": { "@csstools/css-calc": "^3.1.1", "@csstools/css-color-parser": "^4.0.2", "@csstools/css-parser-algorithms": "^4.0.0", "@csstools/css-tokenizer": "^4.0.0", "lru-cache": "^11.2.6" } }, "sha512-2SZFvqMyvboVV1d15lMf7XiI3m7SDqXUuKaTymJYLN6dSGadqp+fVojqJlVoMlbZnlTmu3S0TLwLTJpvBMO1Aw=="],
 
@@ -487,7 +488,7 @@
 
     "@epic-web/invariant": ["@epic-web/invariant@1.0.0", "", {}, "sha512-lrTPqgvfFQtR/eY/qkIzp98OGdNJu0m5ji3q/nJI8v3SXkRKEnWiOxMmbvcSoAIzv/cGiuvRy57k4suKQSAdwA=="],
 
-    "@es-joy/jsdoccomment": ["@es-joy/jsdoccomment@0.84.0", "", { "dependencies": { "@types/estree": "^1.0.8", "@typescript-eslint/types": "^8.54.0", "comment-parser": "1.4.5", "esquery": "^1.7.0", "jsdoc-type-pratt-parser": "~7.1.1" } }, "sha512-0xew1CxOam0gV5OMjh2KjFQZsKL2bByX1+q4j3E73MpYIdyUxcZb/xQct9ccUb+ve5KGUYbCUxyPnYB7RbuP+w=="],
+    "@es-joy/jsdoccomment": ["@es-joy/jsdoccomment@0.86.0", "", { "dependencies": { "@types/estree": "^1.0.8", "@typescript-eslint/types": "^8.58.0", "comment-parser": "1.4.6", "esquery": "^1.7.0", "jsdoc-type-pratt-parser": "~7.2.0" } }, "sha512-ukZmRQ81WiTpDWO6D/cTBM7XbrNtutHKvAVnZN/8pldAwLoJArGOvkNyxPTBGsPjsoaQBJxlH+tE2TNA/92Qgw=="],
 
     "@es-joy/resolve.exports": ["@es-joy/resolve.exports@1.2.0", "", {}, "sha512-Q9hjxWI5xBM+qW2enxfe8wDKdFWMfd0Z29k5ZJnuBqD/CasY5Zryj09aCA6owbGATWz+39p5uIdaHXpopOcG8g=="],
 
@@ -1425,8 +1426,12 @@
 
     "@types/node": ["@types/node@25.3.5", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-oX8xrhvpiyRCQkG1MFchB09f+cXftgIXb3a7UUa4Y3wpmZPw5tyZGTLWhlESOLq1Rq6oDlc8npVU2/9xiCuXMA=="],
 
+    "@types/pako": ["@types/pako@2.0.4", "", {}, "sha512-VWDCbrLeVXJM9fihYodcLiIv0ku+AlOa/TQ1SvYOaBuyrSKgEcro95LJyIsJ4vSo6BXIxOKxiJAat04CmST9Fw=="],
+
     "@types/pg": ["@types/pg@8.18.0", "", { "dependencies": { "@types/node": "*", "pg-protocol": "*", "pg-types": "^2.2.0" } }, "sha512-gT+oueVQkqnj6ajGJXblFR4iavIXWsGAFCk3dP4Kki5+a9R4NMt0JARdk6s8cUKcfUoqP5dAtDSLU8xYUTFV+Q=="],
 
+    "@types/raf": ["@types/raf@3.4.3", "", {}, "sha512-c4YAvMedbPZ5tEyxzQdMoOhhJ4RD3rngZIdwC2/qDN3d7JpEhB6fiBRKVY1lg5B7Wk+uPBjn5f39j1/2MY1oOw=="],
+
     "@types/react": ["@types/react@19.2.14", "", { "dependencies": { "csstype": "^3.2.2" } }, "sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w=="],
 
     "@types/react-dom": ["@types/react-dom@19.2.3", "", { "peerDependencies": { "@types/react": "^19.2.0" } }, "sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ=="],
@@ -1459,7 +1464,7 @@
 
     "@typescript-eslint/type-utils": ["@typescript-eslint/type-utils@8.38.0", "", { "dependencies": { "@typescript-eslint/types": "8.38.0", "@typescript-eslint/typescript-estree": "8.38.0", "@typescript-eslint/utils": "8.38.0", "debug": "^4.3.4", "ts-api-utils": "^2.1.0" }, "peerDependencies": { "eslint": "^8.57.0 || ^9.0.0", "typescript": ">=4.8.4 <5.9.0" } }, "sha512-c7jAvGEZVf0ao2z+nnz8BUaHZD09Agbh+DY7qvBQqLiz8uJzRgVPj5YvOh8I8uEiH8oIUGIfHzMwUcGVco/SJg=="],
 
-    "@typescript-eslint/types": ["@typescript-eslint/types@8.56.1", "", {}, "sha512-dbMkdIUkIkchgGDIv7KLUpa0Mda4IYjo4IAMJUZ+3xNoUXxMsk9YtKpTHSChRS85o+H9ftm51gsK1dZReY9CVw=="],
+    "@typescript-eslint/types": ["@typescript-eslint/types@8.59.4", "", {}, "sha512-F1o7WJcCq+bc8dwcO/YsSEOudAH8RDtaOhM6wcAQhcUsFhnWQl81JKy48q1hoxAU0qrzM89+31GYh1515Zde3Q=="],
 
     "@typescript-eslint/typescript-estree": ["@typescript-eslint/typescript-estree@8.38.0", "", { "dependencies": { "@typescript-eslint/project-service": "8.38.0", "@typescript-eslint/tsconfig-utils": "8.38.0", "@typescript-eslint/types": "8.38.0", "@typescript-eslint/visitor-keys": "8.38.0", "debug": "^4.3.4", "fast-glob": "^3.3.2", "is-glob": "^4.0.3", "minimatch": "^9.0.4", "semver": "^7.6.0", "ts-api-utils": "^2.1.0" }, "peerDependencies": { "typescript": ">=4.8.4 <5.9.0" } }, "sha512-fooELKcAKzxux6fA6pxOflpNS0jc+nOQEEOipXFNjSlBS6fqrJOVY/whSn70SScHrcJ2LDsxWrneFoWYSVfqhQ=="],
 
@@ -1559,6 +1564,8 @@
 
     "balanced-match": ["balanced-match@4.0.4", "", {}, "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA=="],
 
+    "base64-arraybuffer": ["base64-arraybuffer@1.0.2", "", {}, "sha512-I3yl4r9QB5ZRY3XuJVEPfc2XhZO6YweFPI+UovAzn+8/hb3oJ6lnysaFcjVpkCPfVWFUDvoZ8kmVDP7WyRtYtQ=="],
+
     "base64-js": ["base64-js@1.5.1", "", {}, "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA=="],
 
     "baseline-browser-mapping": ["baseline-browser-mapping@2.9.19", "", { "bin": { "baseline-browser-mapping": "dist/cli.js" } }, "sha512-ipDqC8FrAl/76p2SSWKSI+H9tFwm7vYqXQrItCuiVPt26Km0jS+NzSsBWAaBusvSbQcfJG+JitdMm+wZAgTYqg=="],
@@ -1605,6 +1612,8 @@
 
     "caniuse-lite": ["caniuse-lite@1.0.30001769", "", {}, "sha512-BCfFL1sHijQlBGWBMuJyhZUhzo7wer5sVj9hqekB/7xn0Ypy+pER/edCYQm4exbXj4WiySGp40P8UuTh6w1srg=="],
 
+    "canvg": ["canvg@3.0.11", "", { "dependencies": { "@babel/runtime": "^7.12.5", "@types/raf": "^3.4.0", "core-js": "^3.8.3", "raf": "^3.4.1", "regenerator-runtime": "^0.13.7", "rgbcolor": "^1.0.1", "stackblur-canvas": "^2.0.0", "svg-pathdata": "^6.0.3" } }, "sha512-5ON+q7jCTgMp9cjpu4Jo6XbvfYwSB2Ow3kzHKfIyJfaCAOHLbdKPQqGKgfED/R5B+3TFFfe8pegYA+b423SRyA=="],
+
     "ccount": ["ccount@2.0.1", "", {}, "sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg=="],
 
     "chai": ["chai@6.2.2", "", {}, "sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg=="],
@@ -1647,7 +1656,7 @@
 
     "commander": ["commander@14.0.3", "", {}, "sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw=="],
 
-    "comment-parser": ["comment-parser@1.4.5", "", {}, "sha512-aRDkn3uyIlCFfk5NUA+VdwMmMsh8JGhc4hapfV4yxymHGQ3BVskMQfoXGpCo5IoBuQ9tS5iiVKhCpTcB4pW4qw=="],
+    "comment-parser": ["comment-parser@1.4.6", "", {}, "sha512-ObxuY6vnbWTN6Od72xfwN9DbzC7Y2vv8u1Soi9ahRKL37gb6y1qk6/dgjs+3JWuXJHWvsg3BXIwzd/rkmAwavg=="],
 
     "compare-func": ["compare-func@2.0.0", "", { "dependencies": { "array-ify": "^1.0.0", "dot-prop": "^5.1.0" } }, "sha512-zHig5N+tPWARooBnb0Zx1MFcdfpyJrfTJ3Y5L+IFvUm8rM74hHz66z0gw0x4tijh5CorKkKUCnW82R2vmpeCRA=="],
 
@@ -1671,6 +1680,8 @@
 
     "cookie-signature": ["cookie-signature@1.2.2", "", {}, "sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg=="],
 
+    "core-js": ["core-js@3.49.0", "", {}, "sha512-es1U2+YTtzpwkxVLwAFdSpaIMyQaq0PBgm3YD1W3Qpsn1NAmO3KSgZfu+oGSWVu6NvLHoHCV/aYcsE5wiB7ALg=="],
+
     "cors": ["cors@2.8.6", "", { "dependencies": { "object-assign": "^4", "vary": "^1" } }, "sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw=="],
 
     "cose-base": ["cose-base@1.0.3", "", { "dependencies": { "layout-base": "^1.0.0" } }, "sha512-s9whTXInMSgAp/NVXVNuVxVKzGH2qck3aQlVHxDCdAEPgtMKwc4Wq6/QKhgdEdgbLSi9rBTAcPoRa6JpiG4ksg=="],
@@ -1687,6 +1698,8 @@
 
     "cross-spawn": ["cross-spawn@7.0.6", "", { "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", "which": "^2.0.1" } }, "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA=="],
 
+    "css-line-break": ["css-line-break@2.1.0", "", { "dependencies": { "utrie": "^1.0.2" } }, "sha512-FHcKFCZcAha3LwfVBhCQbW2nCNbkZXn7KVUJcsT5/P8YmfsVja0FMPJr0B903j/E69HUphKiV9iQArX8SDYA4w=="],
+
     "css-tree": ["css-tree@3.2.1", "", { "dependencies": { "mdn-data": "2.27.1", "source-map-js": "^1.2.1" } }, "sha512-X7sjQzceUhu1u7Y/ylrRZFU2FS6LRiFVp6rKLPg23y3x3c3DOKAwuXGDp+PAGjh6CSnCjYeAul8pcT8bAl+lSA=="],
 
     "css.escape": ["css.escape@1.5.1", "", {}, "sha512-YUifsXXuknHlUsmlgyY0PKzgPOr7/FjCePfHNt0jxm83wHZi44VDMQ7/fGNkjY3/jV1MC+1CmZbaHzugyeRtpg=="],
@@ -1891,7 +1904,7 @@
 
     "eslint": ["eslint@9.39.4", "", { "dependencies": { "@eslint-community/eslint-utils": "^4.8.0", "@eslint-community/regexpp": "^4.12.1", "@eslint/config-array": "^0.21.2", "@eslint/config-helpers": "^0.4.2", "@eslint/core": "^0.17.0", "@eslint/eslintrc": "^3.3.5", "@eslint/js": "9.39.4", "@eslint/plugin-kit": "^0.4.1", "@humanfs/node": "^0.16.6", "@humanwhocodes/module-importer": "^1.0.1", "@humanwhocodes/retry": "^0.4.2", "@types/estree": "^1.0.6", "ajv": "^6.14.0", "chalk": "^4.0.0", "cross-spawn": "^7.0.6", "debug": "^4.3.2", "escape-string-regexp": "^4.0.0", "eslint-scope": "^8.4.0", "eslint-visitor-keys": "^4.2.1", "espree": "^10.4.0", "esquery": "^1.5.0", "esutils": "^2.0.2", "fast-deep-equal": "^3.1.3", "file-entry-cache": "^8.0.0", "find-up": "^5.0.0", "glob-parent": "^6.0.2", "ignore": "^5.2.0", "imurmurhash": "^0.1.4", "is-glob": "^4.0.0", "json-stable-stringify-without-jsonify": "^1.0.1", "lodash.merge": "^4.6.2", "minimatch": "^3.1.5", "natural-compare": "^1.4.0", "optionator": "^0.9.3" }, "peerDependencies": { "jiti": "*" }, "optionalPeers": ["jiti"], "bin": { "eslint": "bin/eslint.js" } }, "sha512-XoMjdBOwe/esVgEvLmNsD3IRHkm7fbKIUGvrleloJXUZgDHig2IPWNniv+GwjyJXzuNqVjlr5+4yVUZjycJwfQ=="],
 
-    "eslint-plugin-jsdoc": ["eslint-plugin-jsdoc@62.8.0", "", { "dependencies": { "@es-joy/jsdoccomment": "~0.84.0", "@es-joy/resolve.exports": "1.2.0", "are-docs-informative": "^0.0.2", "comment-parser": "1.4.5", "debug": "^4.4.3", "escape-string-regexp": "^4.0.0", "espree": "^11.1.0", "esquery": "^1.7.0", "html-entities": "^2.6.0", "object-deep-merge": "^2.0.0", "parse-imports-exports": "^0.2.4", "semver": "^7.7.4", "spdx-expression-parse": "^4.0.0", "to-valid-identifier": "^1.0.0" }, "peerDependencies": { "eslint": "^7.0.0 || ^8.0.0 || ^9.0.0 || ^10.0.0" } }, "sha512-hu3r9/6JBmPG6wTcqtYzgZAnjEG2eqRUATfkFscokESg1VDxZM21ZaMire0KjeMwfj+SXvgB4Rvh5LBuesj92w=="],
+    "eslint-plugin-jsdoc": ["eslint-plugin-jsdoc@63.0.0", "", { "dependencies": { "@es-joy/jsdoccomment": "~0.86.0", "@es-joy/resolve.exports": "1.2.0", "are-docs-informative": "^0.0.2", "comment-parser": "1.4.6", "debug": "^4.4.3", "escape-string-regexp": "^4.0.0", "espree": "^11.2.0", "esquery": "^1.7.0", "html-entities": "^2.6.0", "object-deep-merge": "^2.0.0", "parse-imports-exports": "^0.2.4", "semver": "^7.8.0", "spdx-expression-parse": "^4.0.0", "to-valid-identifier": "^1.0.0" }, "peerDependencies": { "eslint": "^7.0.0 || ^8.0.0 || ^9.0.0 || ^10.0.0" } }, "sha512-eDHuVGyZydr4BKgjXouU7bsn5qaqUlObXBSWRJk3vXcQgXVFnrwWIqpP7uBhRX9NQpk6NIIFyRc6F6omZNi/8g=="],
 
     "eslint-plugin-react": ["eslint-plugin-react@7.37.5", "", { "dependencies": { "array-includes": "^3.1.8", "array.prototype.findlast": "^1.2.5", "array.prototype.flatmap": "^1.3.3", "array.prototype.tosorted": "^1.1.4", "doctrine": "^2.1.0", "es-iterator-helpers": "^1.2.1", "estraverse": "^5.3.0", "hasown": "^2.0.2", "jsx-ast-utils": "^2.4.1 || ^3.0.0", "minimatch": "^3.1.2", "object.entries": "^1.1.9", "object.fromentries": "^2.0.8", "object.values": "^1.2.1", "prop-types": "^15.8.1", "resolve": "^2.0.0-next.5", "semver": "^6.3.1", "string.prototype.matchall": "^4.0.12", "string.prototype.repeat": "^1.0.0" }, "peerDependencies": { "eslint": "^3 || ^4 || ^5 || ^6 || ^7 || ^8 || ^9.7" } }, "sha512-Qteup0SqU15kdocexFNAJMvCJEfa2xUKNV4CC1xsVMrIIqEy3SQ/rqyxCWNzfrd3/ldy6HMlD2e0JDVpDg2qIA=="],
 
@@ -1949,6 +1962,8 @@
 
     "fast-levenshtein": ["fast-levenshtein@2.0.6", "", {}, "sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw=="],
 
+    "fast-png": ["fast-png@6.4.0", "", { "dependencies": { "@types/pako": "^2.0.3", "iobuffer": "^5.3.2", "pako": "^2.1.0" } }, "sha512-kAqZq1TlgBjZcLr5mcN6NP5Rv4V2f22z00c3g8vRrwkcqjerx7BEhPbOnWCPqaHUl2XWQBJQvOT/FQhdMT7X/Q=="],
+
     "fast-sha256": ["fast-sha256@1.3.0", "", {}, "sha512-n11RGP/lrWEFI/bWdygLxhI+pVeo1ZYIVwvvPkW7azl/rOy+F3HYRZ2K5zeE9mmkhQppyv9sQFx0JM9UabnpPQ=="],
 
     "fast-string-truncated-width": ["fast-string-truncated-width@3.0.3", "", {}, "sha512-0jjjIEL6+0jag3l2XWWizO64/aZVtpiGE3t0Zgqxv0DPuxiMjvB3M24fCyhZUO4KomJQPj3LTSUnDP3GpdwC0g=="],
@@ -1967,6 +1982,8 @@
 
     "fetch-blob": ["fetch-blob@3.2.0", "", { "dependencies": { "node-domexception": "^1.0.0", "web-streams-polyfill": "^3.0.3" } }, "sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ=="],
 
+    "fflate": ["fflate@0.8.3", "", {}, "sha512-tbZNuJrLwGUp3zshBtdy4W+ORxZuIh8a5ilyIEQDC5rY1f3U20JMry0Ll3WBzU58EZKsEuJFXhb5gwv8CsPvgA=="],
+
     "figures": ["figures@6.1.0", "", { "dependencies": { "is-unicode-supported": "^2.0.0" } }, "sha512-d+l3qxjSesT4V7v2fh+QnmFnUWv9lSpjarhShNTgBOfA0ttejbQUAlHLitbjkoRiDulW0OPoQPYIGhIC8ohejg=="],
 
     "file-entry-cache": ["file-entry-cache@8.0.0", "", { "dependencies": { "flat-cache": "^4.0.0" } }, "sha512-XXTUwCvisa5oacNGRP9SfNtYBNAMi+RPwBFmblZEF7N7swHYQS6/Zfk7SRwx4D5j3CH211YNRco1DEMNVfZCnQ=="],
@@ -2093,6 +2110,10 @@
 
     "html-url-attributes": ["html-url-attributes@3.0.1", "", {}, "sha512-ol6UPyBWqsrO6EJySPz2O7ZSr856WDrEzM5zMqp+FJJLGMW35cLYmmZnl0vztAZxRUoNZJFTCohfjuIJ8I4QBQ=="],
 
+    "html2canvas": ["html2canvas@1.4.1", "", { "dependencies": { "css-line-break": "^2.1.0", "text-segmentation": "^1.0.3" } }, "sha512-fPU6BHNpsyIhr8yyMpTLLxAbkaK8ArIBcmZIRiBLiDhjeqvXolaEmDGmELFuX9I4xDcaKKcJl+TKZLqruBbmWA=="],
+
+    "html2pdf.js": ["html2pdf.js@0.14.0", "", { "dependencies": { "dompurify": "^3.3.1", "html2canvas": "^1.0.0", "jspdf": "^4.0.0" } }, "sha512-yvNJgE/8yru2UeGflkPdjW8YEY+nDH5X7/2WG4uiuSCwYiCp8PZ8EKNiTAa6HxJ1NjC51fZSIEq6xld5CADKBQ=="],
+
     "http-errors": ["http-errors@2.0.1", "", { "dependencies": { "depd": "~2.0.0", "inherits": "~2.0.4", "setprototypeof": "~1.2.0", "statuses": "~2.0.2", "toidentifier": "~1.0.1" } }, "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ=="],
 
     "https-proxy-agent": ["https-proxy-agent@7.0.6", "", { "dependencies": { "agent-base": "^7.1.2", "debug": "4" } }, "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw=="],
@@ -2131,6 +2152,8 @@
 
     "internmap": ["internmap@2.0.3", "", {}, "sha512-5Hh7Y1wQbvY5ooGgPbDaL5iYLAPzMTUrjMulskHLH6wnv/A+1q5rgEaiuqEjB+oxGXIVZs1FF+R/KPN3ZSQYYg=="],
 
+    "iobuffer": ["iobuffer@5.4.0", "", {}, "sha512-DRebOWuqDvxunfkNJAlc3IzWIPD5xVxwUNbHr7xKB8E6aLJxIPfNX3CoMJghcFjpv6RWQsrcJbghtEwSPoJqMA=="],
+
     "ip-address": ["ip-address@10.1.0", "", {}, "sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q=="],
 
     "ipaddr.js": ["ipaddr.js@1.9.1", "", {}, "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g=="],
@@ -2243,7 +2266,7 @@
 
     "js-yaml": ["js-yaml@4.1.1", "", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA=="],
 
-    "jsdoc-type-pratt-parser": ["jsdoc-type-pratt-parser@7.1.1", "", {}, "sha512-/2uqY7x6bsrpi3i9LVU6J89352C0rpMk0as8trXxCtvd4kPk1ke/Eyif6wqfSLvoNJqcDG9Vk4UsXgygzCt2xA=="],
+    "jsdoc-type-pratt-parser": ["jsdoc-type-pratt-parser@7.2.0", "", {}, "sha512-dh140MMgjyg3JhJZY/+iEzW+NO5xR2gpbDFKHqotCmexElVntw7GjWjt511+C/Ef02RU5TKYrJo/Xlzk+OLaTw=="],
 
     "jsdom": ["jsdom@29.0.0", "", { "dependencies": { "@asamuzakjp/css-color": "^5.0.1", "@asamuzakjp/dom-selector": "^7.0.2", "@bramus/specificity": "^2.4.2", "@csstools/css-syntax-patches-for-csstree": "^1.1.1", "@exodus/bytes": "^1.15.0", "css-tree": "^3.2.1", "data-urls": "^7.0.0", "decimal.js": "^10.6.0", "html-encoding-sniffer": "^6.0.0", "is-potential-custom-element-name": "^1.0.1", "lru-cache": "^11.2.7", "parse5": "^8.0.0", "saxes": "^6.0.0", "symbol-tree": "^3.2.4", "tough-cookie": "^6.0.1", "undici": "^7.24.3", "w3c-xmlserializer": "^5.0.0", "webidl-conversions": "^8.0.1", "whatwg-mimetype": "^5.0.0", "whatwg-url": "^16.0.1", "xml-name-validator": "^5.0.0" }, "peerDependencies": { "canvas": "^3.0.0" }, "optionalPeers": ["canvas"] }, "sha512-9FshNB6OepopZ08unmmGpsF7/qCjxGPbo3NbgfJAnPeHXnsODE9WWffXZtRFRFe0ntzaAOcSKNJFz8wiyvF1jQ=="],
 
@@ -2267,13 +2290,15 @@
 
     "json5": ["json5@2.2.3", "", { "bin": { "json5": "lib/cli.js" } }, "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg=="],
 
+    "jspdf": ["jspdf@4.2.1", "", { "dependencies": { "@babel/runtime": "^7.28.6", "fast-png": "^6.2.0", "fflate": "^0.8.1" }, "optionalDependencies": { "canvg": "^3.0.11", "core-js": "^3.6.0", "dompurify": "^3.3.1", "html2canvas": "^1.0.0-rc.5" } }, "sha512-YyAXyvnmjTbR4bHQRLzex3CuINCDlQnBqoSYyjJwTP2x9jDLuKDzy7aKUl0hgx3uhcl7xzg32agn5vlie6HIlQ=="],
+
     "jsx-ast-utils": ["jsx-ast-utils@3.3.5", "", { "dependencies": { "array-includes": "^3.1.6", "array.prototype.flat": "^1.3.1", "object.assign": "^4.1.4", "object.values": "^1.1.6" } }, "sha512-ZZow9HBI5O6EPgSJLUb8n2NKgmVWTwCvHGwFuJlMjvLFqlGG6pjirPhtdsseaLZjSibD8eegzmYpUZwoIlj2cQ=="],
 
     "jwa": ["jwa@2.0.1", "", { "dependencies": { "buffer-equal-constant-time": "^1.0.1", "ecdsa-sig-formatter": "1.0.11", "safe-buffer": "^5.0.1" } }, "sha512-hRF04fqJIP8Abbkq5NKGN0Bbr3JxlQ+qhZufXVr0DvujKy93ZCbXZMHDL4EOtodSbCWxOqR8MS1tXA5hwqCXDg=="],
 
     "jws": ["jws@4.0.1", "", { "dependencies": { "jwa": "^2.0.1", "safe-buffer": "^5.0.1" } }, "sha512-EKI/M/yqPncGUUh44xz0PxSidXFr/+r0pA70+gIYhjv+et7yxM+s29Y+VGDkovRofQem0fs7Uvf4+YmAdyRduA=="],
 
-    "katex": ["katex@0.16.28", "", { "dependencies": { "commander": "^8.3.0" }, "bin": { "katex": "cli.js" } }, "sha512-YHzO7721WbmAL6Ov1uzN/l5mY5WWWhJBSW+jq4tkfZfsxmo1hu6frS0EOswvjBUnWE6NtjEs48SFn5CQESRLZg=="],
+    "katex": ["katex@0.17.0", "", { "dependencies": { "commander": "^8.3.0" }, "bin": { "katex": "cli.js" } }, "sha512-Vdw0ATsQ9V+LuegM/BTwQqV/6cTl5lbGcIrU+BCgLxyf6bo38ybOr372tuSIxir3CN720flu1meYR6XzNMwQnw=="],
 
     "keyv": ["keyv@4.5.4", "", { "dependencies": { "json-buffer": "3.0.1" } }, "sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw=="],
 
@@ -2573,6 +2598,8 @@
 
     "package-manager-detector": ["package-manager-detector@1.6.0", "", {}, "sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA=="],
 
+    "pako": ["pako@2.1.0", "", {}, "sha512-w+eufiZ1WuJYgPXbV/PO3NCMEc3xqylkKHzp8bxp1uW4qaSNQUkwmLLEc3kKsfz8lpV1F8Ht3U1Cm+9Srog2ug=="],
+
     "parent-module": ["parent-module@1.0.1", "", { "dependencies": { "callsites": "^3.0.0" } }, "sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g=="],
 
     "parse-entities": ["parse-entities@4.0.2", "", { "dependencies": { "@types/unist": "^2.0.0", "character-entities-legacy": "^3.0.0", "character-reference-invalid": "^2.0.0", "decode-named-character-reference": "^1.0.0", "is-alphanumerical": "^2.0.0", "is-decimal": "^2.0.0", "is-hexadecimal": "^2.0.0" } }, "sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw=="],
@@ -2605,6 +2632,8 @@
 
     "pdfjs-dist": ["pdfjs-dist@5.7.284", "", { "optionalDependencies": { "@napi-rs/canvas": "^0.1.100" } }, "sha512-h4EdYQczmGhbOlqc3PPZwxevn7ApdWPbovAuWXOB/DjIyigSnwfy2oze7c6mRcSr9XgLp3eN3EeL4DyySTPMFw=="],
 
+    "performance-now": ["performance-now@2.1.0", "", {}, "sha512-7EAHlyLHI56VEIdK57uwHdHKIaAGbnXPiw0yWbarQZOKaKpvUIgW0jWRVLiatnM+XXlSwsanIBH/hzGMJulMow=="],
+
     "pg": ["pg@8.19.0", "", { "dependencies": { "pg-connection-string": "^2.11.0", "pg-pool": "^3.12.0", "pg-protocol": "^1.12.0", "pg-types": "2.2.0", "pgpass": "1.0.5" }, "optionalDependencies": { "pg-cloudflare": "^1.3.0" }, "peerDependencies": { "pg-native": ">=3.0.1" }, "optionalPeers": ["pg-native"] }, "sha512-QIcLGi508BAHkQ3pJNptsFz5WQMlpGbuBGBaIaXsWK8mel2kQ/rThYI+DbgjUvZrIr7MiuEuc9LcChJoEZK1xQ=="],
 
     "pg-cloudflare": ["pg-cloudflare@1.3.0", "", {}, "sha512-6lswVVSztmHiRtD6I8hw4qP/nDm1EJbKMRhf3HCYaqud7frGysPv7FYJ5noZQdhQtN2xJnimfMtvQq21pdbzyQ=="],
@@ -2731,6 +2760,8 @@
 
     "queue-microtask": ["queue-microtask@1.2.3", "", {}, "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A=="],
 
+    "raf": ["raf@3.4.1", "", { "dependencies": { "performance-now": "^2.1.0" } }, "sha512-Sq4CW4QhwOHE8ucn6J34MqtZCeWFP2aQSmrlroYgqAV1PjStIhJXxYuTgUIfkEk7zTLjmIjLmU5q+fbD1NnOJA=="],
+
     "range-parser": ["range-parser@1.2.1", "", {}, "sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg=="],
 
     "raw-body": ["raw-body@3.0.2", "", { "dependencies": { "bytes": "~3.1.2", "http-errors": "~2.0.1", "iconv-lite": "~0.7.0", "unpipe": "~1.0.0" } }, "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA=="],
@@ -2807,6 +2838,8 @@
 
     "reusify": ["reusify@1.0.4", "", {}, "sha512-U9nH88a3fc/ekCF1l0/UP1IosiuIjyTh7hBvXVMHYgVcfGvt897Xguj2UOLDeI5BG2m7/uwyaLVT6fbtCwTyzw=="],
 
+    "rgbcolor": ["rgbcolor@1.0.1", "", {}, "sha512-9aZLIrhRaD97sgVhtJOW6ckOEh6/GnvQtdVNfdZ6s67+3/XwLS9lBcQYzEEhYVeUowN7pRzMLsyGhK2i/xvWbw=="],
+
     "rimraf": ["rimraf@5.0.10", "", { "dependencies": { "glob": "^10.3.7" }, "bin": { "rimraf": "dist/esm/bin.mjs" } }, "sha512-l0OE8wL34P4nJH/H2ffoaniAokM2qSmrtXHmlpvYr5AVVX8msAyW0l8NVJFDxlSK4u3Uh/f41cQheDVdnYijwQ=="],
 
     "robust-predicates": ["robust-predicates@3.0.2", "", {}, "sha512-IXgzBWvWQwE6PrDI05OvmXUIruQTcoMDzRsOd5CDvHCVLcLHMTSYvOK5Cm46kWqlV3yAbuSpBZdJ5oP5OUoStg=="],
@@ -2901,6 +2934,8 @@
 
     "stackback": ["stackback@0.0.2", "", {}, "sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw=="],
 
+    "stackblur-canvas": ["stackblur-canvas@2.7.0", "", {}, "sha512-yf7OENo23AGJhBriGx0QivY5JP6Y1HbrrDI6WLt6C5auYZXlQrheoY8hD4ibekFKz1HOfE48Ww8kMWMnJD/zcQ=="],
+
     "standardwebhooks": ["standardwebhooks@1.0.0", "", { "dependencies": { "@stablelib/base64": "^1.0.0", "fast-sha256": "^1.3.0" } }, "sha512-BbHGOQK9olHPMvQNHWul6MYlrRTAOKn03rOe4A8O3CLWhNf4YHBqq2HJKKC+sfqpxiBY52pNeesD6jIiLDz8jg=="],
 
     "statuses": ["statuses@2.0.2", "", {}, "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw=="],
@@ -2947,6 +2982,8 @@
 
     "supports-preserve-symlinks-flag": ["supports-preserve-symlinks-flag@1.0.0", "", {}, "sha512-ot0WnXS9fgdkgIcePe6RHNk1WA8+muPa6cSjeR3V8K27q9BB1rTE3R1p7Hv0z1ZyAc8s6Vvv8DIyWf681MAt0w=="],
 
+    "svg-pathdata": ["svg-pathdata@6.0.3", "", {}, "sha512-qsjeeq5YjBZ5eMdFuUa4ZosMLxgr5RZ+F+Y1OrDhuOCEInRMA3x74XdBtggJcj9kOeInz0WE+LgCPDkZFlBYJw=="],
+
     "symbol-tree": ["symbol-tree@3.2.4", "", {}, "sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw=="],
 
     "tailwind-merge": ["tailwind-merge@3.5.0", "", {}, "sha512-I8K9wewnVDkL1NTGoqWmVEIlUcB9gFriAEkXkfCjX5ib8ezGxtR3xD7iZIxrfArjEsH7F1CHD4RFUtxefdqV/A=="],
@@ -2961,6 +2998,8 @@
 
     "tesseract.js-core": ["tesseract.js-core@7.0.0", "", {}, "sha512-WnNH518NzmbSq9zgTPeoF8c+xmilS8rFIl1YKbk/ptuuc7p6cLNELNuPAzcmsYw450ca6bLa8j3t0VAtq435Vw=="],
 
+    "text-segmentation": ["text-segmentation@1.0.3", "", { "dependencies": { "utrie": "^1.0.2" } }, "sha512-iOiPUo/BGnZ6+54OsWxZidGCsdU8YbE4PSpdPinp7DeMtUJNJBoJ/ouUSTJjHkh1KntHaltHl/gDs2FC4i5+Nw=="],
+
     "thenify": ["thenify@3.3.1", "", { "dependencies": { "any-promise": "^1.0.0" } }, "sha512-RVZSIV5IG10Hk3enotrhvz0T9em6cyHBLkH/YAZuKqd8hRkKhSfCGIcP2KUY0EPxndzANBmNllzWPwak+bheSw=="],
 
     "thenify-all": ["thenify-all@1.6.0", "", { "dependencies": { "thenify": ">= 3.1.0 < 4" } }, "sha512-RNxQH/qI8/t3thXJDwcstUO4zeqo64+Uy/+sNVRBx4Xn2OX+OZ9oP+iJnNFqplFra2ZUVeKCSa2oVWi3T4uVmA=="],
@@ -3075,6 +3114,8 @@
 
     "util-deprecate": ["util-deprecate@1.0.2", "", {}, "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw=="],
 
+    "utrie": ["utrie@1.0.2", "", { "dependencies": { "base64-arraybuffer": "^1.0.2" } }, "sha512-1MLa5ouZiOmQzUbjbu9VmjLzn1QLXBhwpUa7kdLUQK+KQ5KA9I1vk5U4YHe/X2Ch7PYnJfWuWT+VbuxbGwljhw=="],
+
     "uuid": ["uuid@14.0.0", "", { "bin": { "uuid": "dist-node/bin/uuid" } }, "sha512-Qo+uWgilfSmAhXCMav1uYFynlQO7fMFiMVZsQqZRMIXp0O7rR7qjkj+cPvBHLgBqi960QCoo/PH2/6ZtVqKvrg=="],
 
     "vary": ["vary@1.1.2", "", {}, "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg=="],
@@ -3361,6 +3402,8 @@
 
     "@typescript-eslint/project-service/@typescript-eslint/types": ["@typescript-eslint/types@8.38.0", "", {}, "sha512-wzkUfX3plUqij4YwWaJyqhiPE5UCRVlFpKn1oCRn2O1bJ592XxWJj8ROQ3JD5MYXLORW84063z3tZTb/cs4Tyw=="],
 
+    "@typescript-eslint/scope-manager/@typescript-eslint/types": ["@typescript-eslint/types@8.56.1", "", {}, "sha512-dbMkdIUkIkchgGDIv7KLUpa0Mda4IYjo4IAMJUZ+3xNoUXxMsk9YtKpTHSChRS85o+H9ftm51gsK1dZReY9CVw=="],
+
     "@typescript-eslint/scope-manager/@typescript-eslint/visitor-keys": ["@typescript-eslint/visitor-keys@8.56.1", "", { "dependencies": { "@typescript-eslint/types": "8.56.1", "eslint-visitor-keys": "^5.0.0" } }, "sha512-KiROIzYdEV85YygXw6BI/Dx4fnBlFQu6Mq4QE4MOH9fFnhohw6wX/OAvDY2/C+ut0I3RSPKenvZJIVYqJNkhEw=="],
 
     "@typescript-eslint/type-utils/@typescript-eslint/types": ["@typescript-eslint/types@8.38.0", "", {}, "sha512-wzkUfX3plUqij4YwWaJyqhiPE5UCRVlFpKn1oCRn2O1bJ592XxWJj8ROQ3JD5MYXLORW84063z3tZTb/cs4Tyw=="],
@@ -3375,6 +3418,8 @@
 
     "@typescript-eslint/typescript-estree/semver": ["semver@7.7.2", "", { "bin": "bin/semver.js" }, "sha512-RF0Fw+rO5AMf9MAyaRXI4AV0Ulj5lMHqVxxdSgiVbixSCXoEmmX/jk0CuJw4+3SqroYO9VoUh+HcuJivvtJemA=="],
 
+    "@typescript-eslint/utils/@typescript-eslint/types": ["@typescript-eslint/types@8.56.1", "", {}, "sha512-dbMkdIUkIkchgGDIv7KLUpa0Mda4IYjo4IAMJUZ+3xNoUXxMsk9YtKpTHSChRS85o+H9ftm51gsK1dZReY9CVw=="],
+
     "@typescript-eslint/utils/@typescript-eslint/typescript-estree": ["@typescript-eslint/typescript-estree@8.56.1", "", { "dependencies": { "@typescript-eslint/project-service": "8.56.1", "@typescript-eslint/tsconfig-utils": "8.56.1", "@typescript-eslint/types": "8.56.1", "@typescript-eslint/visitor-keys": "8.56.1", "debug": "^4.4.3", "minimatch": "^10.2.2", "semver": "^7.7.3", "tinyglobby": "^0.2.15", "ts-api-utils": "^2.4.0" }, "peerDependencies": { "typescript": ">=4.8.4 <6.0.0" } }, "sha512-qzUL1qgalIvKWAf9C1HpvBjif+Vm6rcT5wZd4VoMb9+Km3iS3Cv9DY6dMRMDtPnwRAFyAi7YXJpTIEXLvdfPxg=="],
 
     "@typescript-eslint/visitor-keys/@typescript-eslint/types": ["@typescript-eslint/types@8.38.0", "", {}, "sha512-wzkUfX3plUqij4YwWaJyqhiPE5UCRVlFpKn1oCRn2O1bJ592XxWJj8ROQ3JD5MYXLORW84063z3tZTb/cs4Tyw=="],
@@ -3403,6 +3448,8 @@
 
     "bun-types/@types/node": ["@types/node@22.16.5", "", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-bJFoMATwIGaxxx8VJPeM8TonI8t579oRvgAuT8zFugJsJZgzqv0Fu8Mhp68iecjzG7cnN3mO2dJQ5uUM2EFrgQ=="],
 
+    "canvg/@babel/runtime": ["@babel/runtime@7.29.2", "", {}, "sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g=="],
+
     "chokidar/glob-parent": ["glob-parent@5.1.2", "", { "dependencies": { "is-glob": "^4.0.1" } }, "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow=="],
 
     "cmdk/@radix-ui/react-dialog": ["@radix-ui/react-dialog@1.1.14", "", { "dependencies": { "@radix-ui/primitive": "1.1.2", "@radix-ui/react-compose-refs": "1.1.2", "@radix-ui/react-context": "1.1.2", "@radix-ui/react-dismissable-layer": "1.1.10", "@radix-ui/react-focus-guards": "1.1.2", "@radix-ui/react-focus-scope": "1.1.7", "@radix-ui/react-id": "1.1.1", "@radix-ui/react-portal": "1.1.9", "@radix-ui/react-presence": "1.1.4", "@radix-ui/react-primitive": "2.1.3", "@radix-ui/react-slot": "1.2.3", "@radix-ui/react-use-controllable-state": "1.2.2", "aria-hidden": "^1.2.4", "react-remove-scroll": "^2.6.3" }, "peerDependencies": { "@types/react": "*", "@types/react-dom": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" } }, "sha512-+CpweKjqpzTmwRwcYECQcNYbI8V9VSQt0SNFKeEBLgfucbsLssU6Ppq7wUdNXEGb573bMjFhVjKVll8rmV6zMw=="],
@@ -3435,6 +3482,8 @@
 
     "eslint-plugin-jsdoc/espree": ["espree@11.2.0", "", { "dependencies": { "acorn": "^8.16.0", "acorn-jsx": "^5.3.2", "eslint-visitor-keys": "^5.0.1" } }, "sha512-7p3DrVEIopW1B1avAGLuCSh1jubc01H2JHc8B4qqGblmg5gI9yumBgACjWo4JlIc04ufug4xJ3SQI8HkS/Rgzw=="],
 
+    "eslint-plugin-jsdoc/semver": ["semver@7.8.1", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-rkVq3IXh+4FDGch+KwzX3aV9W3kO54GyEgpvBzSyctDA6Xtd7RJQV1xmXbeQp5v7+VzLOfVqiutSE6GICgPFvg=="],
+
     "eslint-plugin-react/minimatch": ["minimatch@3.1.5", "", { "dependencies": { "brace-expansion": "^1.1.7" } }, "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w=="],
 
     "eslint-plugin-react/semver": ["semver@6.3.1", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA=="],
@@ -3463,6 +3512,8 @@
 
     "jsdom/whatwg-mimetype": ["whatwg-mimetype@5.0.0", "", {}, "sha512-sXcNcHOC51uPGF0P/D4NVtrkjSU2fNsm9iog4ZvZJsL3rjoDAzXZhkm2MWt1y+PUdggKAYVoMAIYcs78wJ51Cw=="],
 
+    "jspdf/@babel/runtime": ["@babel/runtime@7.29.2", "", {}, "sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g=="],
+
     "katex/commander": ["commander@8.3.0", "", {}, "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww=="],
 
     "knip/jiti": ["jiti@2.6.1", "", { "bin": { "jiti": "lib/jiti-cli.mjs" } }, "sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ=="],
diff --git a/e2e/wiki-compose.spec.ts b/e2e/wiki-compose.spec.ts
new file mode 100644
index 00000000..b9fd897d
--- /dev/null
+++ b/e2e/wiki-compose.spec.ts
@@ -0,0 +1,316 @@
+/**
+ * Wiki Compose P2 happy-path E2E (issue #950).
+ *
+ * Compose の入口 → brief → 調査確認 → 構成 → 執筆 → 完了の流れを Playwright で
+ * 検証する。実 LLM / 実 API は使わず、`page.route` で `/api/pages/.../compose-sessions`
+ * 系を全てモックして wire 形式 (SSE) を再生する。
+ *
+ * Drives the Compose split-screen UI through every interrupt point using a
+ * fully mocked SSE stream. Pins both the wire contract (the UI consumes the
+ * SSE shapes correctly) and the user-facing happy path without depending on
+ * a running API backend with real LLM access.
+ */
+import { test, expect } from "./auth-mock";
+import type { Page, Route } from "@playwright/test";
+
+const NOTE_ID = "11111111-1111-4111-8111-111111111111";
+const PAGE_ID = "22222222-2222-4222-8222-222222222222";
+const SESSION_ID = "33333333-3333-4333-8333-333333333333";
+
+const PAGE_SNAPSHOT = {
+  pageId: PAGE_ID,
+  title: "Photosynthesis",
+  body: "",
+  hasContent: false,
+};
+
+const BRIEF_QUESTION_ID = "qid-1";
+const BRIEF_OPTION_ID = "oid-1";
+const SOURCE_ID = "src:demo";
+const SECTION_ID = "sec-overview";
+
+/**
+ * Encode a sequence of SSE-formatted events as a Uint8Array body. Each event
+ * gets `event:` + `data:` lines and a blank-line terminator.
+ */
+function sseBody(events: Array<{ type: string; payload: unknown }>): Uint8Array {
+  const parts = events.map(
+    ({ type, payload }) => `event: ${type}\ndata: ${JSON.stringify(payload)}\n\n`,
+  );
+  return new TextEncoder().encode(parts.join(""));
+}
+
+let runCount = 0;
+
+/** Per-run event sequences served by the mocked SSE endpoint. */
+function eventsForRun(n: number): Array<{ type: string; payload: unknown }> {
+  // Run 1: initial run → halt at Brief interrupt.
+  // Run 2: after Brief resume → halt at Research interrupt.
+  // Run 3: after Research resume → halt at Outline interrupt.
+  // Run 4: after Outline resume → stream Draft and complete.
+  switch (n) {
+    case 1:
+      return [
+        {
+          type: "started",
+          payload: { type: "started", sessionId: SESSION_ID, graphId: "wiki-compose" },
+        },
+        {
+          type: "compose_phase",
+          payload: { type: "compose_phase", phase: "brief", status: "entered" },
+        },
+        {
+          type: "interrupt",
+          payload: {
+            type: "interrupt",
+            payload: {
+              kind: "human_review_brief",
+              questions: [
+                {
+                  id: BRIEF_QUESTION_ID,
+                  question: "What's the audience for this article?",
+                  rationale: "Helps the agent calibrate depth.",
+                  required: false,
+                  options: [
+                    { id: BRIEF_OPTION_ID, label: "General readers" },
+                    { id: "oid-2", label: "Specialists" },
+                  ],
+                },
+              ],
+              pageSnapshot: PAGE_SNAPSHOT,
+            },
+          },
+        },
+        { type: "done", payload: { type: "done", status: "interrupted" } },
+      ];
+    case 2:
+      return [
+        {
+          type: "started",
+          payload: { type: "started", sessionId: SESSION_ID, graphId: "wiki-compose" },
+        },
+        {
+          type: "compose_phase",
+          payload: { type: "compose_phase", phase: "research", status: "entered" },
+        },
+        {
+          type: "interrupt",
+          payload: {
+            type: "interrupt",
+            payload: {
+              kind: "human_review_research",
+              batch: {
+                id: "batch-1",
+                iteration: 0,
+                queries: [],
+                sources: [],
+                evaluation: null,
+                createdAt: new Date().toISOString(),
+              },
+              pendingSources: [
+                {
+                  id: SOURCE_ID,
+                  kind: "web",
+                  title: "Photosynthesis — Britannica",
+                  url: "https://example.com/photosynthesis",
+                  snippet: "Photosynthesis converts light energy…",
+                },
+              ],
+            },
+          },
+        },
+        { type: "done", payload: { type: "done", status: "interrupted" } },
+      ];
+    case 3:
+      return [
+        {
+          type: "started",
+          payload: { type: "started", sessionId: SESSION_ID, graphId: "wiki-compose" },
+        },
+        {
+          type: "compose_phase",
+          payload: { type: "compose_phase", phase: "structure", status: "entered" },
+        },
+        {
+          type: "interrupt",
+          payload: {
+            type: "interrupt",
+            payload: {
+              kind: "human_review_outline",
+              outline: [
+                {
+                  id: SECTION_ID,
+                  heading: "Overview",
+                  depth: 1,
+                  intent: "Brief introduction",
+                },
+              ],
+              approvedSources: [
+                {
+                  id: SOURCE_ID,
+                  kind: "web",
+                  title: "Photosynthesis — Britannica",
+                  url: "https://example.com/photosynthesis",
+                  snippet: "Photosynthesis converts light energy…",
+                },
+              ],
+            },
+          },
+        },
+        { type: "done", payload: { type: "done", status: "interrupted" } },
+      ];
+    case 4:
+      return [
+        {
+          type: "started",
+          payload: { type: "started", sessionId: SESSION_ID, graphId: "wiki-compose" },
+        },
+        {
+          type: "compose_phase",
+          payload: { type: "compose_phase", phase: "draft", status: "entered" },
+        },
+        {
+          type: "compose_section",
+          payload: {
+            type: "compose_section",
+            sectionId: SECTION_ID,
+            heading: "Overview",
+            status: "started",
+            index: 1,
+            total: 1,
+          },
+        },
+        { type: "token", payload: { type: "token", node: "draft_sections", content: "Photo" } },
+        {
+          type: "token",
+          payload: { type: "token", node: "draft_sections", content: "synthesis." },
+        },
+        {
+          type: "compose_section",
+          payload: {
+            type: "compose_section",
+            sectionId: SECTION_ID,
+            heading: "Overview",
+            status: "completed",
+            index: 1,
+            total: 1,
+          },
+        },
+        {
+          type: "compose_phase",
+          payload: { type: "compose_phase", phase: "completed", status: "entered" },
+        },
+        { type: "done", payload: { type: "done", status: "completed" } },
+      ];
+    default:
+      return [{ type: "done", payload: { type: "done", status: "completed" } }];
+  }
+}
+
+/** Install the Compose API mocks (create / get / run / resume / cancel). */
+async function installComposeMocks(page: Page): Promise<void> {
+  runCount = 0;
+
+  // POST /compose-sessions — create.
+  await page.route(`**/api/pages/${PAGE_ID}/compose-sessions`, async (route: Route) => {
+    if (route.request().method() === "POST") {
+      await route.fulfill({
+        status: 201,
+        contentType: "application/json",
+        body: JSON.stringify({
+          session: {
+            id: SESSION_ID,
+            pageId: PAGE_ID,
+            userId: "user-1",
+            graphId: "wiki-compose",
+            backend: "zedi_managed",
+            phase: "init",
+            status: "pending",
+            metadata: null,
+            lastError: null,
+            closedAt: null,
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+          },
+        }),
+      });
+      return;
+    }
+    await route.fallback();
+  });
+
+  // POST /compose-sessions/:id/run — SSE.
+  await page.route(
+    `**/api/pages/${PAGE_ID}/compose-sessions/${SESSION_ID}/run`,
+    async (route: Route) => {
+      runCount += 1;
+      const body = sseBody(eventsForRun(runCount));
+      await route.fulfill({
+        status: 200,
+        headers: { "content-type": "text/event-stream", "cache-control": "no-cache" },
+        body: Buffer.from(body),
+      });
+    },
+  );
+
+  // PATCH /compose-sessions/:id/resume.
+  await page.route(
+    `**/api/pages/${PAGE_ID}/compose-sessions/${SESSION_ID}/resume`,
+    async (route: Route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ status: "interrupted", output: null }),
+      });
+    },
+  );
+}
+
+test.describe("Wiki Compose P2 happy path", () => {
+  test.setTimeout(60_000);
+
+  test("walks Brief → Research → Outline → Draft → Completed", async ({ page }) => {
+    await installComposeMocks(page);
+
+    await page.goto(`/notes/${NOTE_ID}/${PAGE_ID}/compose`);
+
+    await page.getByTestId("compose-start").click();
+
+    // Brief interrupt — question card appears.
+    const briefCard = page.getByTestId(`brief-card-${BRIEF_QUESTION_ID}`);
+    await expect(briefCard).toBeVisible();
+    await expect(page.getByText("What's the audience for this article?")).toBeVisible();
+
+    // Pick an option and submit.
+    await page.getByTestId(`brief-option-${BRIEF_OPTION_ID}`).click();
+    await page.getByTestId("submit-brief").click();
+
+    // Research interrupt — source review card appears.
+    const sourceRow = page.getByTestId(`source-row-${SOURCE_ID}`);
+    await expect(sourceRow).toBeVisible({ timeout: 10000 });
+
+    // Approve all sources and continue.
+    await page.getByTestId("research-submit").click();
+
+    // Outline interrupt — outline row appears.
+    const outlineRow = page.getByTestId(`outline-row-${SECTION_ID}`);
+    await expect(outlineRow).toBeVisible({ timeout: 10000 });
+
+    // Approve outline and continue.
+    await page.getByTestId("outline-submit").click();
+
+    // Draft phase — phase stepper advances to completed and the editor pane
+    // renders the streamed body.
+    await expect(page.getByTestId("phase-step-completed")).toHaveAttribute("aria-current", "step", {
+      timeout: 10000,
+    });
+    await expect(page.getByTestId(`editor-section-${SECTION_ID}`)).toContainText(
+      "Photosynthesis.",
+      { timeout: 10000 },
+    );
+
+    // Back button returns to the page.
+    await page.getByTestId("compose-back").click();
+    await expect(page).toHaveURL(`/notes/${NOTE_ID}/${PAGE_ID}`);
+  });
+});
diff --git a/e2e/wiki-link-ghost-completion.spec.ts b/e2e/wiki-link-ghost-completion.spec.ts
new file mode 100644
index 00000000..d5675b78
--- /dev/null
+++ b/e2e/wiki-link-ghost-completion.spec.ts
@@ -0,0 +1,221 @@
+/**
+ * E2E tests for the inline ghost completion (issue #930, parent #924 §4).
+ * インラインゴースト補完の E2E テスト（issue #930、親 #924 §4）。
+ *
+ * 受け入れ条件を End-to-End で固定する:
+ * - 既存ページ名の接頭辞を本文中で 2 文字以上タイプすると薄色のゴーストが
+ *   カーソル右に出る
+ * - Tab で確定すると `[data-wiki-link]` の Wiki Link マークが付与される
+ * - Escape または接頭辞が外れたらゴーストが消える
+ * - コードブロック / インラインコード内では発火しない
+ * - `[[` 入力中はゴースト補完が表示されない（`[[` サジェストが優先）
+ * - 1 文字ではゴーストが出ない（≥2 文字ルール）
+ * - サジェスト非アクティブ時の Tab は通常通り（リスト indent などを壊さない）
+ *
+ * Locks the acceptance criteria of issue #930 against the live editor.
+ */
+import { test, expect, type Page } from "./auth-mock";
+
+const GHOST_SELECTOR = ".wiki-link-ghost-completion";
+
+/**
+ * Seed a single candidate page so the ghost completion has something to match.
+ * ゴーストが match できるように候補ページを 1 枚作る。
+ */
+async function seedCandidatePage(
+  page: Page,
+  helpers: { createNewPage: (page: Page) => Promise<{ noteId: string; pageId: string }> },
+  title: string,
+): Promise<void> {
+  await helpers.createNewPage(page);
+  await page.getByPlaceholder("タイトル").fill(title);
+  // タイトル保存（debounce 500ms + バッファ）が走るまで待つ。
+  // Wait for the debounced (500ms) title save to flush.
+  await page.waitForTimeout(1500);
+}
+
+/**
+ * Locator for the editor (Tiptap root).
+ * エディタ本体のロケータ。
+ */
+function editorLocator(page: Page) {
+  return page.locator(".tiptap").first();
+}
+
+test.describe("Inline Ghost Completion (issue #930)", () => {
+  test.setTimeout(90_000);
+
+  test.beforeEach(async ({ page, helpers }) => {
+    await helpers.goToHome(page);
+  });
+
+  test("shows the ghost suffix when the typed word prefix-matches a candidate", async ({
+    page,
+    helpers,
+  }) => {
+    await seedCandidatePage(page, helpers, "Ghost Target");
+
+    // 新しい源ページを作って候補一覧が読み込まれるのを待つ。
+    // Open a fresh page so candidates load fresh from the cache.
+    await helpers.createNewPage(page);
+    await page.getByPlaceholder("タイトル").fill("Source");
+    await page.waitForTimeout(800);
+
+    const editor = editorLocator(page);
+    await editor.click();
+    await page.keyboard.type("Gho");
+
+    // Ghost suffix appears with the remainder of the title.
+    // ゴーストにタイトルの残り部分が出る。
+    const ghost = page.locator(GHOST_SELECTOR);
+    await expect(ghost).toBeVisible();
+    await expect(ghost).toHaveText("st Target");
+  });
+
+  test("confirms with Tab — turns the typed prefix into a wiki link", async ({ page, helpers }) => {
+    await seedCandidatePage(page, helpers, "Ghost Target");
+    await helpers.createNewPage(page);
+    await page.getByPlaceholder("タイトル").fill("Source Confirm");
+    await page.waitForTimeout(800);
+
+    const editor = editorLocator(page);
+    await editor.click();
+    await page.keyboard.type("Gho");
+
+    await expect(page.locator(GHOST_SELECTOR)).toBeVisible();
+    await page.keyboard.press("Tab");
+
+    // Ghost is gone and a wiki-link mark covers the full title.
+    // ゴーストが消え、Wiki Link マークがタイトル全体を覆う。
+    await expect(page.locator(GHOST_SELECTOR)).toHaveCount(0);
+    const wikiLink = editor.locator('[data-wiki-link][data-title="Ghost Target"]');
+    await expect(wikiLink).toBeVisible();
+    await expect(wikiLink).toHaveAttribute("data-exists", "true");
+  });
+
+  test("Escape dismisses the ghost but keeps the typed text", async ({ page, helpers }) => {
+    await seedCandidatePage(page, helpers, "Ghost Target");
+    await helpers.createNewPage(page);
+    await page.getByPlaceholder("タイトル").fill("Source Escape");
+    await page.waitForTimeout(800);
+
+    const editor = editorLocator(page);
+    await editor.click();
+    await page.keyboard.type("Gho");
+
+    await expect(page.locator(GHOST_SELECTOR)).toBeVisible();
+    await page.keyboard.press("Escape");
+    await expect(page.locator(GHOST_SELECTOR)).toHaveCount(0);
+
+    // The user's typed prefix stays in the editor (Escape only kills the
+    // preview, not the input). The wiki-link mark must NOT be applied.
+    // 入力済みの接頭辞は残り、Wiki Link マークは付かない。
+    await expect(editor).toContainText("Gho");
+    await expect(editor.locator('[data-wiki-link][data-title="Ghost Target"]')).toHaveCount(0);
+  });
+
+  test("does not fire on a single character (≥2 chars rule)", async ({ page, helpers }) => {
+    await seedCandidatePage(page, helpers, "Ghost Target");
+    await helpers.createNewPage(page);
+    await page.getByPlaceholder("タイトル").fill("Source Length");
+    await page.waitForTimeout(800);
+
+    const editor = editorLocator(page);
+    await editor.click();
+    await page.keyboard.type("G");
+    await expect(page.locator(GHOST_SELECTOR)).toHaveCount(0);
+
+    await page.keyboard.type("h");
+    // Now at 2 chars → ghost should appear.
+    // 2 文字に達したのでゴーストが出る。
+    await expect(page.locator(GHOST_SELECTOR)).toBeVisible();
+  });
+
+  test("does not fire inside a code block", async ({ page, helpers }) => {
+    await seedCandidatePage(page, helpers, "Ghost Target");
+    await helpers.createNewPage(page);
+    await page.getByPlaceholder("タイトル").fill("Source CodeBlock");
+    await page.waitForTimeout(800);
+
+    const editor = editorLocator(page);
+    await editor.click();
+    // Markdown shortcut for a code block (CodeBlockLowlight registers triple
+    // backtick + Enter as the input rule). After this the cursor sits inside
+    // the code block.
+    // ` ``` ` + Enter で code block に入る。以降 code block 内なのでゴースト不発火。
+    await page.keyboard.type("```");
+    await page.keyboard.press("Enter");
+    await page.keyboard.type("Gho");
+    await expect(page.locator(GHOST_SELECTOR)).toHaveCount(0);
+  });
+
+  test("does not fire inside inline code", async ({ page, helpers }) => {
+    // 受け入れ条件: インラインコード（バッククォート 1 つ）内ではゴースト不発火。
+    // 内部では `wikiLink` マークが付けられない（`excludes: "code"` 相当）ため、
+    // サジェストも出さない契約。
+    // Acceptance: ghost must not fire inside inline code (single backticks)
+    // since the WikiLink mark cannot apply there.
+    await seedCandidatePage(page, helpers, "Ghost Target");
+    await helpers.createNewPage(page);
+    await page.getByPlaceholder("タイトル").fill("Source InlineCode");
+    await page.waitForTimeout(800);
+
+    const editor = editorLocator(page);
+    await editor.click();
+    // Open an inline code span via Markdown input rule: typing "`Gho`" turns
+    // the text between backticks into inline code. We type the opening
+    // backtick + the prefix first to land the caret inside the active code
+    // mark, which mirrors what users do mid-line.
+    // Markdown 入力規則で「`Gho`」と打って `Gho` をインラインコードにする。
+    // 開きバッククォート + 接頭辞を打鍵した時点でキャレットは `code` マーク
+    // 内にあるので、その状態でゴーストが出ないことを確認する。
+    await page.keyboard.type("`Gho`");
+    // Move the caret back inside the code span and type another matching char.
+    // キャレットをインラインコード内に戻して 1 文字追加し、再度抑止を確認する。
+    await page.keyboard.press("ArrowLeft");
+    await page.keyboard.type("s");
+    await expect(page.locator(GHOST_SELECTOR)).toHaveCount(0);
+  });
+
+  test("does not fire while the `[[` suggestion popup is active", async ({ page, helpers }) => {
+    await seedCandidatePage(page, helpers, "Ghost Target");
+    await helpers.createNewPage(page);
+    await page.getByPlaceholder("タイトル").fill("Source Brackets");
+    await page.waitForTimeout(800);
+
+    const editor = editorLocator(page);
+    await editor.click();
+    await page.keyboard.type("[[Gho");
+    // The `[[` suggestion popup owns this range, the ghost must stay hidden.
+    // `[[` サジェストがこの範囲を担当しているので、ゴーストは出ない。
+    await expect(page.locator(GHOST_SELECTOR)).toHaveCount(0);
+  });
+
+  test("Tab still indents list items when no ghost is active (regression guard)", async ({
+    page,
+    helpers,
+  }) => {
+    // We are not seeding candidates so the ghost never activates; if it did,
+    // it would also suppress Tab. This test pins the "Tab passes through"
+    // contract that protects existing list indent behaviour.
+    // 候補なしにしてゴーストを発火させない状態で Tab を打鍵し、リストの
+    // ネスト動作が壊れないこと（Tab 素通し）を保証する。
+    await helpers.createNewPage(page);
+    await page.getByPlaceholder("タイトル").fill("Tab Passthrough");
+    await page.waitForTimeout(800);
+
+    const editor = editorLocator(page);
+    await editor.click();
+    // Start a bullet list.
+    // 箇条書きリストを開始する。
+    await page.keyboard.type("- first item");
+    await page.keyboard.press("Enter");
+    await page.keyboard.type("nested");
+    await page.keyboard.press("Home");
+    await page.keyboard.press("Tab");
+
+    // After Tab, the second item is nested → nested `<ul>` exists.
+    // Tab 後、2 つ目の `li` が入れ子になり `ul ul` が現れる。
+    await expect(editor.locator("ul ul")).toHaveCount(1);
+  });
+});
diff --git a/extension/README.ja.md b/extension/README.ja.md
new file mode 100644
index 00000000..79472b3f
--- /dev/null
+++ b/extension/README.ja.md
@@ -0,0 +1,69 @@
+> **言語:** [English](README.md) | 日本語
+
+# Zedi Web Clipper
+
+Chrome 拡張機能。ワンクリックで Web ページを Zedi に保存する。
+
+## 機能
+
+- **ワンクリック保存**: ポップアップまたはコンテキストメニューから現在のページを保存
+- **ショートカット**: `Ctrl+Shift+S`（mac: `Command+Shift+S`）で保存
+- **OAuth 2.0 + PKCE**: Zedi アカウントへの安全な接続
+
+## インストール
+
+### 本番環境
+
+1. [Chrome ウェブストア](https://chrome.google.com/webstore) からインストール（公開後）
+2. または、Zedi から「拡張機能を接続」で案内される手順に従う
+
+### 開発検証
+
+本番以外の環境（例: dev.zedi-note.app）で拡張を試す場合:
+
+1. ルートで以下を実行し、dev 用 config を生成:
+   ```bash
+   bun run prepare:extension:dev
+   ```
+2. Chrome で `chrome://extensions` を開く
+3. 「デベロッパーモード」を ON
+4. 「パッケージ化されていない拡張機能を読み込む」→ この `extension/` フォルダを選択
+
+## ビルド時環境切り替え
+
+拡張は **1 つのベース URL** で認証ページ（`/auth/extension`）と API（`/api/ext/*`）にアクセスする。
+
+| 環境 | コマンド                         | ベース URL                |
+| ---- | -------------------------------- | ------------------------- |
+| 本番 | `bun run prepare:extension:prod` | https://zedi-note.app     |
+| 開発 | `bun run prepare:extension:dev`  | https://dev.zedi-note.app |
+
+- 本番 zip 作成前に `prepare:extension:prod` を実行してから `extension/` を zip する。
+- 開発者は `prepare:extension:dev` で dev 環境用に切り替える。
+
+## ファイル構成
+
+```plaintext
+extension/
+  config.js         # popup 用（prepare-extension.js が生成。手動編集しない）
+  config.worker.js  # background 用（同上）
+  constants.js      # 共有定数（popup と background から読み込み）
+  manifest.json     # 拡張マニフェスト
+  popup.html        # ポップアップ UI
+  popup.js          # ポップアップロジック
+  background.js     # サービスワーカー（コンテキストメニュー・ショートカット）
+  README.ja.md      # 本ファイル
+```
+
+## 前提条件
+
+- Zedi アカウント（https://zedi-note.app または dev.zedi-note.app）
+- 保存対象 URL は `http://` または `https://` のみ。`localhost`・`chrome://`・プライベート IP は不可。
+
+## サーバー側 CORS
+
+拡張から API を呼ぶには、API の `CORS_ORIGIN` に拡張の origin を明示する必要があります。Chrome の `chrome://extensions` で拡張 ID を確認し、`CORS_ORIGIN` に `chrome-extension://<そのID>` を追加してください（カンマ区切り）。
+
+## ライセンス
+
+本リポジトリのルート `LICENSE` に準拠。
diff --git a/extension/README.md b/extension/README.md
index e5324018..bfa6716e 100644
--- a/extension/README.md
+++ b/extension/README.md
@@ -1,83 +1,69 @@
-# Zedi Web Clipper
+> **Language:** English | [日本語](README.ja.md)
 
-Chrome 拡張機能。ワンクリックで Web ページを Zedi に保存する。
+# Zedi Web Clipper
 
 Chrome extension for saving web pages to Zedi with one click.
 
-## 機能 / Features
+## Features
 
-- **ワンクリック保存 (One-click save)**: ポップアップまたはコンテキストメニューから現在のページを保存
-- **ショートカット (Shortcut)**: `Ctrl+Shift+S` (mac: `Command+Shift+S`) で保存
-- **OAuth 2.0 + PKCE**: Zedi アカウントへの安全な接続
+- **One-click save**: Save the current page from the popup or context menu
+- **Shortcut**: `Ctrl+Shift+S` (mac: `Command+Shift+S`) to save
+- **OAuth 2.0 + PKCE**: Secure connection to your Zedi account
 
-## インストール / Installation
+## Installation
 
-### 本番環境 (Production)
+### Production
 
-1. [Chrome ウェブストア](https://chrome.google.com/webstore) からインストール（公開後）  
-   Install from the [Chrome Web Store](https://chrome.google.com/webstore) (after publication)
-2. または、Zedi から「拡張機能を接続」で案内される手順に従う  
-   Or follow the instructions from "Connect Extension" in Zedi
+1. Install from the [Chrome Web Store](https://chrome.google.com/webstore) (after publication)
+2. Or follow the instructions from "Connect Extension" in Zedi
 
-### 開発検証 (Development)
+### Development
 
-本番以外の環境（例: dev.zedi-note.app）で拡張を試す場合:  
 To test the extension in a non-production environment (e.g., dev.zedi-note.app):
 
-1. ルートで以下を実行し、dev 用 config を生成:  
-   Run the following at the repository root to generate dev config:
+1. Run the following at the repository root to generate dev config:
    ```bash
    bun run prepare:extension:dev
    ```
-2. Chrome で `chrome://extensions` を開く  
-   Open `chrome://extensions` in Chrome
-3. 「デベロッパーモード」を ON  
-   Enable "Developer mode"
-4. 「パッケージ化されていない拡張機能を読み込む」→ この `extension/` フォルダを選択  
-   Click "Load unpacked" and select this `extension/` folder
+2. Open `chrome://extensions` in Chrome
+3. Enable "Developer mode"
+4. Click "Load unpacked" and select this `extension/` folder
 
-## ビルド時環境切り替え / Build-time Config
+## Build-time Config
 
-拡張は **1 つのベース URL** で認証ページ (`/auth/extension`) と API (`/api/ext/*`) にアクセスする。  
 The extension accesses the auth page (`/auth/extension`) and API (`/api/ext/*`) via **a single base URL**.
 
-| 環境 | コマンド                         | ベース URL                |
-| ---- | -------------------------------- | ------------------------- |
-| 本番 | `bun run prepare:extension:prod` | https://zedi-note.app     |
-| 開発 | `bun run prepare:extension:dev`  | https://dev.zedi-note.app |
+| Environment | Command                          | Base URL                  |
+| ----------- | -------------------------------- | ------------------------- |
+| Production  | `bun run prepare:extension:prod` | https://zedi-note.app     |
+| Development | `bun run prepare:extension:dev`  | https://dev.zedi-note.app |
 
-- 本番 zip 作成前に `prepare:extension:prod` を実行してから `extension/` を zip する。  
-  Before creating a production zip, run `prepare:extension:prod` then zip the `extension/` folder.
-- 開発者は `prepare:extension:dev` で dev 環境用に切り替える。  
-  Developers should run `prepare:extension:dev` to switch to the dev environment.
+- Before creating a production zip, run `prepare:extension:prod` then zip the `extension/` folder.
+- Developers should run `prepare:extension:dev` to switch to the dev environment.
 
-## ファイル構成 / File Structure
+## File Structure
 
 ```plaintext
 extension/
-  config.js         # popup 用（prepare-extension.js が生成。手動編集しない） / For popup (generated by prepare-extension.js; do not edit manually)
-  config.worker.js  # background 用（同上） / For background (same as above)
-  constants.js      # 共有定数（popup と background から読み込み） / Shared constants (loaded from popup and background)
-  manifest.json     # 拡張マニフェスト / Extension manifest
-  popup.html        # ポップアップ UI / Popup UI
-  popup.js          # ポップアップロジック / Popup logic
-  background.js     # サービスワーカー（コンテキストメニュー・ショートカット） / Service worker (context menu & shortcuts)
-  README.md         # 本ファイル / This file
+  config.js         # For popup (generated by prepare-extension.js; do not edit manually)
+  config.worker.js  # For background (same as above)
+  constants.js      # Shared constants (loaded from popup and background)
+  manifest.json     # Extension manifest
+  popup.html        # Popup UI
+  popup.js          # Popup logic
+  background.js     # Service worker (context menu & shortcuts)
+  README.md         # This file
 ```
 
-## 前提条件 / Prerequisites
+## Prerequisites
 
-- Zedi アカウント（https://zedi-note.app または dev.zedi-note.app）  
-  A Zedi account (https://zedi-note.app or dev.zedi-note.app)
-- 保存対象 URL は `http://` または `https://` のみ。`localhost`・`chrome://`・プライベート IP は不可。  
-  Clippable URLs must use `http://` or `https://` only. `localhost`, `chrome://`, and private IPs are not allowed.
+- A Zedi account (https://zedi-note.app or dev.zedi-note.app)
+- Clippable URLs must use `http://` or `https://` only. `localhost`, `chrome://`, and private IPs are not allowed.
 
-## サーバー側 CORS / Server CORS
+## Server CORS
 
-拡張から API を呼ぶには、API の `CORS_ORIGIN` に拡張の origin を明示する必要があります。Chrome の `chrome://extensions` で拡張 ID を確認し、`CORS_ORIGIN` に `chrome-extension://<そのID>` を追加してください（カンマ区切り）。  
 To allow the extension to call the API, add the extension origin to the server's `CORS_ORIGIN` (e.g. `chrome-extension://<extension-id>` from Chrome's extensions page).
 
-## ライセンス / License
+## License
 
-本リポジトリのルート `LICENSE` に準拠。  
 Follows the root `LICENSE` of this repository.
diff --git a/knip.json b/knip.json
index 9b816fd7..d4b235d5 100644
--- a/knip.json
+++ b/knip.json
@@ -33,7 +33,7 @@
       "project": ["src/**/*.ts"]
     },
     "server/api": {
-      "entry": ["scripts/**/*.ts"],
+      "entry": ["scripts/**/*.ts", "src/agents/index.ts"],
       "project": ["src/**/*.{ts,tsx}", "scripts/**/*.ts"]
     },
     "server/hocuspocus": {
@@ -103,7 +103,10 @@
     "wrangler",
     "@tauri-apps/plugin-shell",
     "@tauri-apps/plugin-store",
-    "@tauri-apps/plugin-updater"
+    "@tauri-apps/plugin-updater",
+    "@langchain/openai",
+    "@langchain/anthropic",
+    "@langchain/google-genai"
   ],
   "ignoreExportsUsedInFile": {
     "interface": true,
diff --git a/package.json b/package.json
index 391d296c..1cfd120b 100644
--- a/package.json
+++ b/package.json
@@ -36,6 +36,7 @@
     "lint": "eslint .",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
+    "docs:check-pairs": "node scripts/check-doc-pairs.mjs",
     "preview": "vite preview",
     "test": "vitest",
     "test:run": "vitest run && vitest run --config packages/shared/vitest.config.ts && vitest run --config packages/ui/vitest.config.ts && vitest run --config packages/claude-sidecar/vitest.config.ts && vitest run --config server/hocuspocus/vitest.config.ts && vitest run --config server/mcp/vitest.config.ts && vitest run --config admin/vitest.config.ts",
@@ -90,7 +91,7 @@
     "lodash-es": ">=4.18.0"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.96.0",
+    "@anthropic-ai/sdk": "^0.98.0",
     "@dagrejs/dagre": "^3.0.0",
     "@google/genai": "^2.0.1",
     "@google/generative-ai": "^0.24.1",
@@ -173,11 +174,12 @@
     "dompurify": "^3.3.3",
     "embla-carousel-react": "^8.6.0",
     "highlight.js": "^11.11.1",
+    "html2pdf.js": "^0.14.0",
     "i18next": "^26.0.1",
     "i18next-browser-languagedetector": "^8.2.1",
     "idb-keyval": "^6.2.2",
     "input-otp": "^1.4.2",
-    "katex": "^0.16.28",
+    "katex": "^0.17.0",
     "lowlight": "^3.3.0",
     "lucide-react": "^1.7.0",
     "mermaid": "^11.12.2",
@@ -238,7 +240,7 @@
     "bun-types": "^1.3.9",
     "cross-env": "^10.1.0",
     "eslint": "^9.39.4",
-    "eslint-plugin-jsdoc": "^62.8.0",
+    "eslint-plugin-jsdoc": "^63.0.0",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.5.2",
diff --git a/scripts/check-doc-pairs.mjs b/scripts/check-doc-pairs.mjs
new file mode 100644
index 00000000..c1d3eb50
--- /dev/null
+++ b/scripts/check-doc-pairs.mjs
@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * Verifies English/Japanese documentation pairs and required language banners.
+ * Run: bun run docs:check-pairs
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const ROOT = join(import.meta.dirname, "..");
+
+/** @type {{ en: string; ja: string }[]} */
+const DOC_PAIRS = [
+  { en: "README.md", ja: "README.ja.md" },
+  { en: "CONTRIBUTING.md", ja: "CONTRIBUTING.ja.md" },
+  { en: "SECURITY.md", ja: "SECURITY.ja.md" },
+  { en: "DOCUMENTATION.md", ja: "DOCUMENTATION.ja.md" },
+  { en: "extension/README.md", ja: "extension/README.ja.md" },
+  { en: "server/mcp/README.md", ja: "server/mcp/README.ja.md" },
+  { en: "admin/README.md", ja: "admin/README.ja.md" },
+  {
+    en: "terraform/cloudflare/README.md",
+    ja: "terraform/cloudflare/README.ja.md",
+  },
+];
+
+const EN_BANNER = /> \*\*Language:\*\* English \|/m;
+const JA_BANNER = /> \*\*言語:\*\*/m;
+
+/** @param {string} relPath */
+function readDoc(relPath) {
+  const abs = join(ROOT, relPath);
+  if (!existsSync(abs)) {
+    return null;
+  }
+  return readFileSync(abs, "utf8");
+}
+
+/** @param {string[]} errors */
+function main() {
+  const errors = [];
+
+  for (const { en, ja } of DOC_PAIRS) {
+    const enContent = readDoc(en);
+    const jaContent = readDoc(ja);
+
+    if (enContent === null) {
+      errors.push(`Missing English doc: ${en}`);
+      continue;
+    }
+    if (jaContent === null) {
+      errors.push(`Missing Japanese pair: ${ja} (expected pair for ${en})`);
+      continue;
+    }
+
+    if (!EN_BANNER.test(enContent)) {
+      errors.push(`${en}: missing language banner (expected "> **Language:** English | ...")`);
+    }
+    if (!JA_BANNER.test(jaContent)) {
+      errors.push(`${ja}: missing language banner (expected "> **言語:** ...")`);
+    }
+
+    const jaBase = ja.split("/").pop() ?? ja;
+    if (!enContent.includes(`](${jaBase})`) && !enContent.includes(`](${ja})`)) {
+      errors.push(`${en}: banner should link to ${ja}`);
+    }
+
+    const enBase = en.split("/").pop() ?? en;
+    if (!jaContent.includes(`](${enBase})`) && !jaContent.includes(`](${en})`)) {
+      errors.push(`${ja}: banner should link to ${en}`);
+    }
+  }
+
+  if (errors.length > 0) {
+    console.error("Documentation pair check failed:\n");
+    for (const e of errors) {
+      console.error(`  - ${e}`);
+    }
+    process.exit(1);
+  }
+
+  console.log(`OK: ${DOC_PAIRS.length} documentation pairs verified.`);
+}
+
+main();
diff --git a/scripts/delete-merged-branches.sh b/scripts/delete-merged-branches.sh
index 81f313b7..2319ddc0 100644
--- a/scripts/delete-merged-branches.sh
+++ b/scripts/delete-merged-branches.sh
@@ -1,255 +1,3 @@
 #!/usr/bin/env bash
-# 基準ブランチにマージ済みのローカルブランチと origin 上のリモートブランチを安全に削除する。
-# 使用例: ./scripts/delete-merged-branches.sh [基準ブランチ] [--dry-run]
-
-set -e
-
-DRY_RUN=false
-BASE_BRANCH=""
-for arg in "$@"; do
-  if [ "$arg" = "--dry-run" ]; then
-    DRY_RUN=true
-  elif [ -z "$BASE_BRANCH" ]; then
-    BASE_BRANCH="$arg"
-  fi
-done
-
-echo "Fetching and pruning remote refs..."
-git fetch origin --prune
-
-origin_default="$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@')"
-if [ -z "$BASE_BRANCH" ]; then
-  if git rev-parse --verify develop >/dev/null 2>&1; then
-    BASE_BRANCH="develop"
-  else
-    BASE_BRANCH="${origin_default:-main}"
-  fi
-fi
-base_remote="origin/$BASE_BRANCH"
-if ! git rev-parse --verify "$base_remote" >/dev/null 2>&1; then
-  echo "Error: base branch ref $base_remote does not exist." >&2
-  exit 1
-fi
-current_branch="$(git branch --show-current)"
-# 保護ブランチ: 基準・main/master/develop・現在・origin のデフォルト
-protected="$BASE_BRANCH main master develop $current_branch $origin_default"
-
-is_protected() {
-  local b="$1"
-  for p in $protected; do
-    [ "$b" = "$p" ] && return 0
-  done
-  return 1
-}
-
-merged_file=""
-closed_unmerged_file=""
-if command -v gh >/dev/null 2>&1; then
-  merged_file="$(mktemp 2>/dev/null || echo "/tmp/merged-prs.$$")"
-  closed_unmerged_file="$(mktemp 2>/dev/null || echo "/tmp/closed-unmerged-prs.$$")"
-  trap 'rm -f "$merged_file" "$closed_unmerged_file"' EXIT
-  gh pr list --state merged --base "$BASE_BRANCH" --limit 200 --json headRefName,headRefOid,number \
-    --jq '.[] | "\(.headRefName)\t\(.headRefOid)\t\(.number)"' 2>/dev/null >"$merged_file" || true
-  # クローズ済み（未マージ）PR のブランチ名・headRefOid・番号。--base は付けずリポジトリ全体から取得。同一リポジトリの PR のみ（fork を除外）。
-  # origin tip と headRefOid が一致する場合のみ削除候補にする（クローズ後に push されたブランチを誤削除しないため）。
-  gh pr list --state closed --limit 500 --json headRefName,headRefOid,number,mergedAt,isCrossRepository \
-    --jq '.[] | select(.mergedAt == null and (.isCrossRepository | not)) | "\(.headRefName)\t\(.headRefOid)\t\(.number)"' 2>/dev/null >"$closed_unmerged_file" || true
-fi
-
-# merged 一覧から branch の oid と number を取得（1行 "oid number" を返す）。見つからない場合は何も出力せず return 0（set -e で落ちないように）
-get_merged_oid_and_num() {
-  local branch="$1"
-  if [ -z "$merged_file" ] || [ ! -s "$merged_file" ]; then
-    return 0
-  fi
-  local oid num
-  oid="$(awk -v b="$branch" 'BEGIN{FS="\t"} $1==b {print $2; exit}' "$merged_file" 2>/dev/null)"
-  num="$(awk -v b="$branch" 'BEGIN{FS="\t"} $1==b {print $3; exit}' "$merged_file" 2>/dev/null)"
-  [ -z "$oid" ] && return 0
-  echo "$oid $num"
-}
-
-# リモート専用の削除候補用：branch の oid と number を取得
-get_closed_unmerged_oid_and_num() {
-  local branch="$1"
-  if [ -z "$closed_unmerged_file" ] || [ ! -s "$closed_unmerged_file" ]; then
-    return 0
-  fi
-  local oid num
-  oid="$(awk -v b="$branch" 'BEGIN{FS="\t"} $1==b {print $2; exit}' "$closed_unmerged_file" 2>/dev/null)"
-  num="$(awk -v b="$branch" 'BEGIN{FS="\t"} $1==b {print $3; exit}' "$closed_unmerged_file" 2>/dev/null)"
-  [ -z "$oid" ] && return 0
-  echo "$oid $num"
-}
-
-# 指定ブランチに open PR があるか（同名の open PR があると削除しない）。gh が使えない場合は未実行。
-has_open_pr() {
-  local branch="$1"
-  [ -z "$merged_file" ] && return 1
-  local count
-  if ! count="$(gh pr list --state open --head "$branch" --limit 1 --json number --jq 'length' 2>/dev/null)"; then
-    return 0
-  fi
-  [ "${count:-0}" -gt 0 ] && return 0
-  return 1
-}
-
-echo "Base branch: $BASE_BRANCH ($base_remote)"
-echo "Current branch: $current_branch"
-[ "$DRY_RUN" = true ] && echo "(dry-run: no branches will be deleted)"
-echo ""
-
-deleted_remote_only=""
-
-# ローカル削除候補を列挙（branch:reason の行を蓄積）
-local_candidates=""
-remote_delete_names=""
-
-while IFS= read -r branch; do
-  [ -z "$branch" ] && continue
-  is_protected "$branch" && continue
-  reason=""
-  oid_num=""
-  if git merge-base --is-ancestor "$branch" "$base_remote" 2>/dev/null; then
-    reason="merged by ancestry"
-  else
-    oid_num="$(get_merged_oid_and_num "$branch")"
-    if [ -n "$oid_num" ]; then
-      tip="$(git rev-parse "$branch" 2>/dev/null)"
-      oid="${oid_num%% *}"
-      num="${oid_num#* }"
-      if [ "$oid" = "$tip" ]; then
-        reason="merged PR #${num} (squash/rebase-safe)"
-      fi
-    fi
-  fi
-  if [ -n "$reason" ]; then
-    local_candidates="${local_candidates}${local_candidates:+$'\n'}${branch}:${reason}"
-    if git rev-parse --verify "origin/$branch" >/dev/null 2>&1; then
-      remote_tip="$(git rev-parse "origin/$branch" 2>/dev/null)"
-      safe_remote=false
-      if git merge-base --is-ancestor "origin/$branch" "$base_remote" 2>/dev/null; then
-        safe_remote=true
-      elif [ -n "$oid_num" ]; then
-        oid="${oid_num%% *}"
-        [ "$oid" = "$remote_tip" ] && safe_remote=true
-      fi
-      if [ "$safe_remote" = true ]; then
-        if [ -z "$merged_file" ] || ! has_open_pr "$branch"; then
-          remote_delete_names="${remote_delete_names}${remote_delete_names:+$'\n'}${branch}:local:${reason}"
-        fi
-      fi
-    fi
-  fi
-done < <(git for-each-ref refs/heads --format='%(refname:short)')
-
-# リモート専用の削除候補（ローカルに ref が無く、origin にあり）
-# (1) merged PR で tip 一致 → 削除可
-# (2) クローズ済み未マージ PR のブランチ（GitHub Copilot 等が作ってクローズしたブランチ）→ origin tip が headRefOid と一致する場合のみ削除可
-while IFS= read -r ref; do
-  if [ -z "$ref" ] || [ "$ref" = "HEAD" ]; then
-    continue
-  fi
-  is_protected "$ref" && continue
-  git rev-parse --verify "refs/heads/$ref" >/dev/null 2>&1 && continue
-  if ! git rev-parse --verify "origin/$ref" >/dev/null 2>&1; then
-    continue
-  fi
-  oid_num="$(get_merged_oid_and_num "$ref")"
-  if [ -n "$oid_num" ]; then
-    tip="$(git rev-parse "origin/$ref" 2>/dev/null)"
-    oid="${oid_num%% *}"
-    num="${oid_num#* }"
-    if [ "$oid" = "$tip" ]; then
-      if [ -z "$merged_file" ] || ! has_open_pr "$ref"; then
-        deleted_remote_only="${deleted_remote_only}${deleted_remote_only:+$'\n'}${ref}:merged PR #${num} (remote-only)"
-        remote_delete_names="${remote_delete_names}${remote_delete_names:+$'\n'}${ref}:remote-only:merged PR #${num} (remote-only)"
-      fi
-    fi
-  else
-    closed_oid_num="$(get_closed_unmerged_oid_and_num "$ref")"
-    if [ -n "$closed_oid_num" ]; then
-      if [ -z "$merged_file" ] || ! has_open_pr "$ref"; then
-      tip="$(git rev-parse "origin/$ref" 2>/dev/null)"
-      closed_oid="${closed_oid_num%% *}"
-      closed_num="${closed_oid_num#* }"
-        if [ "$closed_oid" = "$tip" ]; then
-          deleted_remote_only="${deleted_remote_only}${deleted_remote_only:+$'\n'}${ref}:closed PR #${closed_num} (remote-only)"
-          remote_delete_names="${remote_delete_names}${remote_delete_names:+$'\n'}${ref}:remote-only:closed PR #${closed_num} (remote-only)"
-        fi
-      fi
-    fi
-  fi
-done < <(git for-each-ref refs/remotes/origin --format='%(refname:short)' | sed 's|^origin/||')
-
-# 報告用に削除予定を表示
-report_local=""
-report_remote=""
-count_local=0
-
-while IFS= read -r line; do
-  [ -z "$line" ] && continue
-  branch="${line%%:*}"
-  reason="${line#*:}"
-  report_local="${report_local}${report_local:+$'\n'}- \`${branch}\` - ${reason}"
-  ((count_local++)) || true
-done <<< "$local_candidates"
-
-# リモート削除候補はすべて表示（:local と :remote-only の両方）
-while IFS= read -r line; do
-  [ -z "$line" ] && continue
-  name="${line%%:*}"
-  rest="${line#*:}"
-  rest="${rest#*:}" # branch:local:reason or branch:remote-only:reason -> reason
-  report_remote="${report_remote}${report_remote:+$'\n'}- \`${name}\` - ${rest}"
-done <<< "$remote_delete_names"
-
-total_remote=0
-while IFS= read -r line; do
-  [ -z "$line" ] && continue
-  ((total_remote++)) || true
-done <<< "$remote_delete_names"
-
-if [ -z "$report_local" ] && [ -z "$report_remote" ]; then
-  echo "No branches to delete."
-  exit 0
-fi
-
-echo "--- Candidates ---"
-[ -n "$report_local" ] && echo "Deleted (local):" && echo "$report_local" && echo ""
-[ -n "$report_remote" ] && echo "Deleted (remote):" && echo "$report_remote" && echo ""
-
-if [ "$DRY_RUN" = true ]; then
-  echo "Dry-run: would delete $count_local local branch(es) and $total_remote remote branch(es)."
-  exit 0
-fi
-
-echo "Delete $count_local local and $total_remote remote branch(es)? [y/N]"
-read -r confirm
-case "$confirm" in
-  [yY]|[yY][eE][sS]) ;;
-  *) echo "Aborted."; exit 0 ;;
-esac
-
-deleted_local_count=0
-while IFS= read -r line; do
-  [ -z "$line" ] && continue
-  branch="${line%%:*}"
-  if git branch -d "$branch" 2>/dev/null || git branch -D "$branch" 2>/dev/null; then
-    ((deleted_local_count++)) || true
-  fi
-done <<< "$local_candidates"
-
-deleted_remote_count=0
-while IFS= read -r line; do
-  [ -z "$line" ] && continue
-  name="${line%%:*}"
-  if git rev-parse --verify "origin/$name" >/dev/null 2>&1; then
-    if git push origin --delete "$name" 2>/dev/null; then
-      ((deleted_remote_count++)) || true
-    fi
-  fi
-done <<< "$remote_delete_names"
-
-echo ""
-echo "Done. Deleted $deleted_local_count local and $deleted_remote_count remote branch(es)."
+# 後方互換ラッパー。実体はグローバル Skill に移行済み。
+exec "${DELETE_MERGED_BRANCHES_SCRIPT:-$HOME/.cursor/skills/delete-merged-branches/scripts/delete-merged-branches.sh}" "$@"
diff --git a/server/api/.env.example b/server/api/.env.example
index 061ff561..26e3af07 100644
--- a/server/api/.env.example
+++ b/server/api/.env.example
@@ -46,3 +46,8 @@ GITHUB_DISPATCH_REPOSITORY=
 #   内部 URL を設定してはいけない。未設定時はリンク行を省略する。
 ADMIN_BASE_URL=
 MONITORING_NOTIFY_EMAIL=
+
+# Wiki Compose BYOK — AES-256-GCM key for `user_ai_credentials` (#951).
+# 32 raw bytes as Base64 or 64-char hex. Never commit the real value.
+# Wiki Compose BYOK 用。`user_ai_credentials` の at-rest 暗号化鍵（32 バイト）。
+USER_AI_CREDENTIALS_ENCRYPTION_KEY=
diff --git a/server/api/bun.lock b/server/api/bun.lock
index 6e068565..fff6c61d 100644
--- a/server/api/bun.lock
+++ b/server/api/bun.lock
@@ -8,6 +8,12 @@
         "@aws-sdk/client-s3": "^3.1002.0",
         "@aws-sdk/s3-request-presigner": "^3.1002.0",
         "@hono/node-server": "^2.0.0",
+        "@langchain/anthropic": "^1.4.0",
+        "@langchain/core": "^1.1.48",
+        "@langchain/google-genai": "^2.1.31",
+        "@langchain/langgraph": "^1.3.2",
+        "@langchain/langgraph-checkpoint-postgres": "^1.0.1",
+        "@langchain/openai": "^1.4.7",
         "@mozilla/readability": "^0.6.0",
         "@polar-sh/sdk": "^0.47.0",
         "@react-email/components": "^1.0.11",
@@ -33,6 +39,7 @@
         "resend": "^6.10.0",
         "yjs": "^13.6.30",
         "youtubei.js": "^17.0.1",
+        "zod": "^4.4.3",
       },
       "devDependencies": {
         "@types/jsdom": "^28.0.0",
@@ -49,6 +56,8 @@
     },
   },
   "packages": {
+    "@anthropic-ai/sdk": ["@anthropic-ai/sdk@0.95.2", "", { "dependencies": { "json-schema-to-ts": "^3.1.1", "standardwebhooks": "^1.0.0" }, "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" }, "optionalPeers": ["zod"], "bin": { "anthropic-ai-sdk": "bin/cli" } }, "sha512-Egddwo3sheo1PzUrMkZnH6VkQYwS0h/b/i8vSK8Ta9M45UQipAMeDFH57dYuDAfXMEUUGeKw6CMlremgMZgrSQ=="],
+
     "@asamuzakjp/css-color": ["@asamuzakjp/css-color@5.0.1", "", { "dependencies": { "@csstools/css-calc": "^3.1.1", "@csstools/css-color-parser": "^4.0.2", "@csstools/css-parser-algorithms": "^4.0.0", "@csstools/css-tokenizer": "^4.0.0", "lru-cache": "^11.2.6" } }, "sha512-2SZFvqMyvboVV1d15lMf7XiI3m7SDqXUuKaTymJYLN6dSGadqp+fVojqJlVoMlbZnlTmu3S0TLwLTJpvBMO1Aw=="],
 
     "@asamuzakjp/dom-selector": ["@asamuzakjp/dom-selector@7.0.3", "", { "dependencies": { "@asamuzakjp/nwsapi": "^2.3.9", "bidi-js": "^1.0.3", "css-tree": "^3.2.1", "is-potential-custom-element-name": "^1.0.1", "lru-cache": "^11.2.7" } }, "sha512-Q6mU0Z6bfj6YvnX2k9n0JxiIwrCFN59x/nWmYQnAqP000ruX/yV+5bp/GRcF5T8ncvfwJQ7fgfP74DlpKExILA=="],
@@ -139,6 +148,8 @@
 
     "@aws/lambda-invoke-store": ["@aws/lambda-invoke-store@0.2.3", "", {}, "sha512-oLvsaPMTBejkkmHhjf09xTgk71mOqyr/409NKhRIL08If7AhVfUsJhVsx386uJaqNd42v9kWamQ9lFbkoC2dYw=="],
 
+    "@babel/runtime": ["@babel/runtime@7.29.2", "", {}, "sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g=="],
+
     "@better-auth/core": ["@better-auth/core@1.5.3", "", { "dependencies": { "@standard-schema/spec": "^1.1.0", "zod": "^4.3.6" }, "peerDependencies": { "@better-auth/utils": "0.3.1", "@better-fetch/fetch": "1.1.21", "@cloudflare/workers-types": ">=4", "better-call": "1.3.2", "jose": "^6.1.0", "kysely": "^0.28.5", "nanostores": "^1.0.1" }, "optionalPeers": ["@cloudflare/workers-types"] }, "sha512-fORsQjNZ6BQ7o96xMe7elz3Y4Y8DsqXmQrdyzt289G9rmzX4auwBCPTtE2cXTRTYGiVvH9bv0b97t1Uo/OWynQ=="],
 
     "@better-auth/drizzle-adapter": ["@better-auth/drizzle-adapter@1.5.3", "", { "peerDependencies": { "@better-auth/core": "1.5.3", "@better-auth/utils": "^0.3.0", "drizzle-orm": ">=0.41.0" } }, "sha512-dib9V1vpwDu+TKLC+L+8Q5bLNS0uE3JCT4pGotw52pnpiQF8msoMK4eEfri19f8DtNltpb2F2yzyIsTugBBYNQ=="],
@@ -157,6 +168,8 @@
 
     "@bufbuild/protobuf": ["@bufbuild/protobuf@2.11.0", "", {}, "sha512-sBXGT13cpmPR5BMgHE6UEEfEaShh5Ror6rfN3yEK5si7QVrtZg8LEPQb0VVhiLRUslD2yLnXtnRzG035J/mZXQ=="],
 
+    "@cfworker/json-schema": ["@cfworker/json-schema@4.1.1", "", {}, "sha512-gAmrUZSGtKc3AiBL71iNWxDsyUC5uMaKKGdvzYsBoTW/xi42JQHl7eKV2OYzCUqvc+D2RCcf7EXY2iCyFIk6og=="],
+
     "@chevrotain/cst-dts-gen": ["@chevrotain/cst-dts-gen@10.5.0", "", { "dependencies": { "@chevrotain/gast": "10.5.0", "@chevrotain/types": "10.5.0", "lodash": "4.17.21" } }, "sha512-lhmC/FyqQ2o7pGK4Om+hzuDrm9rhFYIJ/AXoQBeongmn870Xeb0L6oGEiuR8nohFNL5sMaQEJWCxr1oIVIVXrw=="],
 
     "@chevrotain/gast": ["@chevrotain/gast@10.5.0", "", { "dependencies": { "@chevrotain/types": "10.5.0", "lodash": "4.17.21" } }, "sha512-pXdMJ9XeDAbgOWKuD1Fldz4ieCs6+nLNmyVhe2gZVqoO7v8HXuHYs5OV2EzUtbuai37TlOAQHrTDvxMnvMJz3A=="],
@@ -245,12 +258,32 @@
 
     "@fastify/otel": ["@fastify/otel@0.18.0", "", { "dependencies": { "@opentelemetry/core": "^2.0.0", "@opentelemetry/instrumentation": "^0.212.0", "@opentelemetry/semantic-conventions": "^1.28.0", "minimatch": "^10.2.4" }, "peerDependencies": { "@opentelemetry/api": "^1.9.0" } }, "sha512-3TASCATfw+ctICSb4ymrv7iCm0qJ0N9CarB+CZ7zIJ7KqNbwI5JjyDL1/sxoC0ccTO1Zyd1iQ+oqncPg5FJXaA=="],
 
+    "@google/generative-ai": ["@google/generative-ai@0.24.1", "", {}, "sha512-MqO+MLfM6kjxcKoy0p1wRzG3b4ZZXtPI+z2IE26UogS2Cm/XHO+7gGRBh6gcJsOiIVoH93UwKvW4HdgiOZCy9Q=="],
+
     "@hono/node-server": ["@hono/node-server@2.0.0", "", { "peerDependencies": { "hono": "^4" } }, "sha512-n3GfHwwCvHCkGmOwKfxUPOlbfzuO64Sbc5XC4NGPIXxkuOnJrdgExdRKmHfF924r914WRJPT397GdqLvdYTeyQ=="],
 
     "@ioredis/commands": ["@ioredis/commands@1.5.1", "", {}, "sha512-JH8ZL/ywcJyR9MmJ5BNqZllXNZQqQbnVZOqpPQqE1vHiFgAw4NHbvE0FOduNU8IX9babitBT46571OnPTT0Zcw=="],
 
     "@jridgewell/sourcemap-codec": ["@jridgewell/sourcemap-codec@1.5.5", "", {}, "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og=="],
 
+    "@langchain/anthropic": ["@langchain/anthropic@1.4.0", "", { "dependencies": { "@anthropic-ai/sdk": "^0.95.1", "zod": "^3.25.76 || ^4" }, "peerDependencies": { "@langchain/core": "^1.1.47" } }, "sha512-rs1yVydrHjyiD31uChdCnKZpmDuKa0Bpz8Raiy9GvqnqmfXPMe0oOrap/2paE+NRSinDbtax8mMpP/yv8EbO1A=="],
+
+    "@langchain/core": ["@langchain/core@1.1.48", "", { "dependencies": { "@cfworker/json-schema": "^4.0.2", "@standard-schema/spec": "^1.1.0", "js-tiktoken": "^1.0.12", "langsmith": ">=0.5.0 <1.0.0", "mustache": "^4.2.0", "p-queue": "^6.6.2", "zod": "^3.25.76 || ^4" } }, "sha512-fQU6Guyb1pwc2fEplmA8FPbKfOMAofjnyJzExevro0FxEiuGHE18Ov/ZHmT9trWCDTZRI9eW1VIc6aChxV8pAQ=="],
+
+    "@langchain/google-genai": ["@langchain/google-genai@2.1.31", "", { "dependencies": { "@google/generative-ai": "^0.24.1" }, "peerDependencies": { "@langchain/core": "^1.1.47" } }, "sha512-lHIJGtZab0jqoufKRPXyHHg1nLXrE74LXd0ftgibWEACc1SpSLu6XwtA23+dX4l7Q/YeSgb9n40YJx5k00/fqw=="],
+
+    "@langchain/langgraph": ["@langchain/langgraph@1.3.2", "", { "dependencies": { "@langchain/langgraph-checkpoint": "^1.0.2", "@langchain/langgraph-sdk": "~1.9.4", "@langchain/protocol": "^0.0.15", "@standard-schema/spec": "1.1.0", "uuid": "^10.0.0" }, "peerDependencies": { "@langchain/core": "^1.1.44", "zod": "^3.25.32 || ^4.2.0", "zod-to-json-schema": "^3.x" }, "optionalPeers": ["zod-to-json-schema"] }, "sha512-SL7Ktsr681R7da+1b2MVOWEbaCoFJOXEJPTGOjg4JIG4C7quWbTYC8DzxhcCxte6D/8cGp0rYDBnbKLXEpNqlA=="],
+
+    "@langchain/langgraph-checkpoint": ["@langchain/langgraph-checkpoint@1.0.2", "", { "dependencies": { "uuid": "^10.0.0" }, "peerDependencies": { "@langchain/core": "^1.1.44" } }, "sha512-F4E5Tr0nt8FGghgdscJtHw+ABzChOHeI80R7Y1pjIHdiJom6c2ieo76vL+FWiny80JmoGqhrVAEIWrw0cXKPxg=="],
+
+    "@langchain/langgraph-checkpoint-postgres": ["@langchain/langgraph-checkpoint-postgres@1.0.1", "", { "dependencies": { "pg": "^8.12.0" }, "peerDependencies": { "@langchain/core": "^1.0.1", "@langchain/langgraph-checkpoint": "^1.0.0" } }, "sha512-cRXOLYZc0egMjyAQfBblWXdoBS+WKwEbCEuE+/f88XHJ1bq5jVz7aycbpjF/7F5EykG7xmybQOz5eUdg3neRzg=="],
+
+    "@langchain/langgraph-sdk": ["@langchain/langgraph-sdk@1.9.5", "", { "dependencies": { "@langchain/protocol": "^0.0.15", "@types/json-schema": "^7.0.15", "p-queue": "^9.0.1", "p-retry": "^7.1.1", "uuid": "^13.0.0" }, "peerDependencies": { "@langchain/core": "^1.1.44", "react": "^18 || ^19", "react-dom": "^18 || ^19", "svelte": "^4.0.0 || ^5.0.0", "vue": "^3.0.0" }, "optionalPeers": ["react", "react-dom", "svelte", "vue"] }, "sha512-NMcz1rEKuVz07ZqcSzNJZCZR9FppRNh+/YWjCKtwZ7a/WNytDEAh26qXTtmDQZ7+J+1nEXhHym1wZDrOxA99wg=="],
+
+    "@langchain/openai": ["@langchain/openai@1.4.7", "", { "dependencies": { "js-tiktoken": "^1.0.12", "openai": "^6.37.0", "zod": "^3.25.76 || ^4" }, "peerDependencies": { "@langchain/core": "^1.1.48" } }, "sha512-i1YLV4pWbGC6W8m0ZNpLObJuf1nyU4o8aWyX4AF9fHn7eM67HfIJWQ5n5XzcCpuSa41otrxA9jvH5XRKwI1qDA=="],
+
+    "@langchain/protocol": ["@langchain/protocol@0.0.15", "", {}, "sha512-MllvbpMjqHevUm+v94M422mH7XKN+wGCvJRBVROTWBotEDOATYB4Ktk2UheYP859y9o2LlhtPek5t1T9eyfAbQ=="],
+
     "@mozilla/readability": ["@mozilla/readability@0.6.0", "", {}, "sha512-juG5VWh4qAivzTAeMzvY9xs9HY5rAcr2E4I7tiSSCokRFi7XIZCAu92ZkSTsIj1OPceCifL3cpfteP3pDT9/QQ=="],
 
     "@mrleebo/prisma-ast": ["@mrleebo/prisma-ast@0.13.1", "", { "dependencies": { "chevrotain": "^10.5.0", "lilconfig": "^2.1.0" } }, "sha512-XyroGQXcHrZdvmrGJvsA9KNeOOgGMg1Vg9OlheUsBOSKznLMDl+YChxbkboRHvtFYJEMRYmlV3uoo/njCw05iw=="],
@@ -623,6 +656,8 @@
 
     "@types/jsdom": ["@types/jsdom@28.0.0", "", { "dependencies": { "@types/node": "*", "@types/tough-cookie": "*", "parse5": "^7.0.0", "undici-types": "^7.21.0" } }, "sha512-A8TBQQC/xAOojy9kM8E46cqT00sF0h7dWjV8t8BJhUi2rG6JRh7XXQo/oLoENuZIQEpXsxLccLCnknyQd7qssQ=="],
 
+    "@types/json-schema": ["@types/json-schema@7.0.15", "", {}, "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA=="],
+
     "@types/linkify-it": ["@types/linkify-it@5.0.0", "", {}, "sha512-sVDA58zAw4eWAffKOaQH5/5j3XeayukzDk+ewSsnv3p4yJEZHCCzMDiZM8e0OUrRvmpGZ85jf4yDHkHsgBNr9Q=="],
 
     "@types/markdown-it": ["@types/markdown-it@14.1.2", "", { "dependencies": { "@types/linkify-it": "^5", "@types/mdurl": "^2" } }, "sha512-promo4eFwuiW+TfGxhi+0x3czqTYJkG8qB17ZUJiVF10Xm7NLVRSLUsfRTU/6h1e24VvRnXCx+hG7li58lkzog=="],
@@ -679,6 +714,8 @@
 
     "balanced-match": ["balanced-match@4.0.4", "", {}, "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA=="],
 
+    "base64-js": ["base64-js@1.5.1", "", {}, "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA=="],
+
     "better-auth": ["better-auth@1.5.3", "", { "dependencies": { "@better-auth/core": "1.5.3", "@better-auth/kysely-adapter": "1.5.3", "@better-auth/memory-adapter": "1.5.3", "@better-auth/telemetry": "1.5.3", "@better-auth/utils": "0.3.1", "@better-fetch/fetch": "1.1.21", "@noble/ciphers": "^2.1.1", "@noble/hashes": "^2.0.1", "better-call": "1.3.2", "defu": "^6.1.4", "jose": "^6.1.3", "kysely": "^0.28.11", "nanostores": "^1.1.1", "zod": "^4.3.6" }, "peerDependencies": { "@better-auth/drizzle-adapter": "1.5.3", "@better-auth/mongo-adapter": "1.5.3", "@better-auth/prisma-adapter": "1.5.3", "@lynx-js/react": "*", "@prisma/client": "^5.0.0 || ^6.0.0 || ^7.0.0", "@sveltejs/kit": "^2.0.0", "@tanstack/react-start": "^1.0.0", "@tanstack/solid-start": "^1.0.0", "better-sqlite3": "^12.0.0", "drizzle-kit": ">=0.31.4", "drizzle-orm": ">=0.41.0", "mongodb": "^6.0.0 || ^7.0.0", "mysql2": "^3.0.0", "next": "^14.0.0 || ^15.0.0 || ^16.0.0", "pg": "^8.0.0", "prisma": "^5.0.0 || ^6.0.0 || ^7.0.0", "react": "^18.0.0 || ^19.0.0", "react-dom": "^18.0.0 || ^19.0.0", "solid-js": "^1.0.0", "svelte": "^4.0.0 || ^5.0.0", "vitest": "^2.0.0 || ^3.0.0 || ^4.0.0", "vue": "^3.0.0" }, "optionalPeers": ["@better-auth/drizzle-adapter", "@better-auth/mongo-adapter", "@better-auth/prisma-adapter", "@lynx-js/react", "@prisma/client", "@sveltejs/kit", "@tanstack/react-start", "@tanstack/solid-start", "better-sqlite3", "drizzle-kit", "drizzle-orm", "mongodb", "mysql2", "next", "pg", "prisma", "react", "react-dom", "solid-js", "svelte", "vitest", "vue"] }, "sha512-E+9kA9GMX1+gT3FfMCqRz0NufT4X/+tNhpOsHW1jLmyPZKinkHtfZkUffSBnG5qGkvfBaH/slT5c1fKttnmF5w=="],
 
     "better-call": ["better-call@1.3.2", "", { "dependencies": { "@better-auth/utils": "^0.3.1", "@better-fetch/fetch": "^1.1.21", "rou3": "^0.7.12", "set-cookie-parser": "^3.0.1" }, "peerDependencies": { "zod": "^4.0.0" }, "optionalPeers": ["zod"] }, "sha512-4cZIfrerDsNTn3cm+MhLbUePN0gdwkhSXEuG7r/zuQ8c/H7iU0/jSK5TD3FW7U0MgKHce/8jGpPYNO4Ve+4NBw=="],
@@ -767,6 +804,8 @@
 
     "estree-walker": ["estree-walker@3.0.3", "", { "dependencies": { "@types/estree": "^1.0.0" } }, "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g=="],
 
+    "eventemitter3": ["eventemitter3@4.0.7", "", {}, "sha512-8guHBZCwKnFhYdHr2ysuRWErTwhoN2X8XELRlrRwpmfeY2jjuUN4taQMsULKUVo1K4DvZl+0pgfyoysHxvmvEw=="],
+
     "expect-type": ["expect-type@1.3.0", "", {}, "sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA=="],
 
     "exsolve": ["exsolve@1.0.8", "", {}, "sha512-LmDxfWXwcTArk8fUEnOfSZpHOJ6zOMUJKOtFLFqJLoKJetuQG874Uc7/Kki7zFLzYybmZhp1M7+98pfMqeX8yA=="],
@@ -821,6 +860,8 @@
 
     "ioredis": ["ioredis@5.10.0", "", { "dependencies": { "@ioredis/commands": "1.5.1", "cluster-key-slot": "^1.1.0", "debug": "^4.3.4", "denque": "^2.1.0", "lodash.defaults": "^4.2.0", "lodash.isarguments": "^3.1.0", "redis-errors": "^1.2.0", "redis-parser": "^3.0.0", "standard-as-callback": "^2.1.0" } }, "sha512-HVBe9OFuqs+Z6n64q09PQvP1/R4Bm+30PAyyD4wIEqssh3v9L21QjCVk4kRLucMBcDokJTcLjsGeVRlq/nH6DA=="],
 
+    "is-network-error": ["is-network-error@1.3.2", "", {}, "sha512-PhBY86zaxNZUuWP6h13Vu5oFe0XY6/UlKzQnYFELzGVHygP3MxmvTfYSG7GN3aIab/iWudSMgjSnG9Dq+nHrgA=="],
+
     "is-potential-custom-element-name": ["is-potential-custom-element-name@1.0.1", "", {}, "sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ=="],
 
     "is-property": ["is-property@1.0.2", "", {}, "sha512-Ks/IoX00TtClbGQr4TWXemAnktAQvYB7HzcCxDGqEZU6oCmb2INHuOoKxbtR+HFkmYWBKv/dOZtGRiAjDhj92g=="],
@@ -833,10 +874,16 @@
 
     "jose": ["jose@6.2.1", "", {}, "sha512-jUaKr1yrbfaImV7R2TN/b3IcZzsw38/chqMpo2XJ7i2F8AfM/lA4G1goC3JVEwg0H7UldTmSt3P68nt31W7/mw=="],
 
+    "js-tiktoken": ["js-tiktoken@1.0.21", "", { "dependencies": { "base64-js": "^1.5.1" } }, "sha512-biOj/6M5qdgx5TKjDnFT1ymSpM5tbd3ylwDtrQvFQSu0Z7bBYko2dF+W/aUkXUPuk6IVpRxk/3Q2sHOzGlS36g=="],
+
     "jsdom": ["jsdom@29.0.0", "", { "dependencies": { "@asamuzakjp/css-color": "^5.0.1", "@asamuzakjp/dom-selector": "^7.0.2", "@bramus/specificity": "^2.4.2", "@csstools/css-syntax-patches-for-csstree": "^1.1.1", "@exodus/bytes": "^1.15.0", "css-tree": "^3.2.1", "data-urls": "^7.0.0", "decimal.js": "^10.6.0", "html-encoding-sniffer": "^6.0.0", "is-potential-custom-element-name": "^1.0.1", "lru-cache": "^11.2.7", "parse5": "^8.0.0", "saxes": "^6.0.0", "symbol-tree": "^3.2.4", "tough-cookie": "^6.0.1", "undici": "^7.24.3", "w3c-xmlserializer": "^5.0.0", "webidl-conversions": "^8.0.1", "whatwg-mimetype": "^5.0.0", "whatwg-url": "^16.0.1", "xml-name-validator": "^5.0.0" }, "peerDependencies": { "canvas": "^3.0.0" }, "optionalPeers": ["canvas"] }, "sha512-9FshNB6OepopZ08unmmGpsF7/qCjxGPbo3NbgfJAnPeHXnsODE9WWffXZtRFRFe0ntzaAOcSKNJFz8wiyvF1jQ=="],
 
+    "json-schema-to-ts": ["json-schema-to-ts@3.1.1", "", { "dependencies": { "@babel/runtime": "^7.18.3", "ts-algebra": "^2.0.0" } }, "sha512-+DWg8jCJG2TEnpy7kOm/7/AxaYoaRbjVB4LFZLySZlWn8exGs3A4OLJR966cVvU26N7X9TWxl+Jsw7dzAqKT6g=="],
+
     "kysely": ["kysely@0.28.11", "", {}, "sha512-zpGIFg0HuoC893rIjYX1BETkVWdDnzTzF5e0kWXJFg5lE0k1/LfNWBejrcnOFu8Q2Rfq/hTDTU7XLUM8QOrpzg=="],
 
+    "langsmith": ["langsmith@0.7.2", "", { "dependencies": { "p-queue": "6.6.2" }, "peerDependencies": { "@opentelemetry/api": "*", "@opentelemetry/exporter-trace-otlp-proto": "*", "@opentelemetry/sdk-trace-base": "*", "openai": "*", "ws": ">=7" }, "optionalPeers": ["@opentelemetry/api", "@opentelemetry/exporter-trace-otlp-proto", "@opentelemetry/sdk-trace-base", "openai", "ws"] }, "sha512-3dZUwQDJluxi2ih5eIygFODtlrQKrs3Tua0Ck3l+DAUkSGFkB1Dc0JPqkGbqiVSN+TQDElnkev/ydAOAz6jndA=="],
+
     "leac": ["leac@0.6.0", "", {}, "sha512-y+SqErxb8h7nE/fiEX07jsbuhrpO9lL8eca7/Y1nuWV2moNlXhyd59iDGcRf6moVyDMbmTNzL40SUyrFU/yDpg=="],
 
     "lib0": ["lib0@0.2.117", "", { "dependencies": { "isomorphic.js": "^0.2.4" }, "bin": { "0serve": "bin/0serve.js", "0gentesthtml": "bin/gentesthtml.js", "0ecdsa-generate-keypair": "bin/0ecdsa-generate-keypair.js" } }, "sha512-DeXj9X5xDCjgKLU/7RR+/HQEVzuuEUiwldwOGsHK/sfAfELGWEyTcf0x+uOvCvK3O2zPmZePXWL85vtia6GyZw=="],
@@ -879,6 +926,8 @@
 
     "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
 
+    "mustache": ["mustache@4.2.0", "", { "bin": { "mustache": "bin/mustache" } }, "sha512-71ippSywq5Yb7/tVYyGbkBggbU8H3u5Rz56fH60jGFgr8uHwxs+aSKeqmluIVzM0m0kB7xQjKS6qPfd0b2ZoqQ=="],
+
     "mysql2": ["mysql2@3.15.3", "", { "dependencies": { "aws-ssl-profiles": "^1.1.1", "denque": "^2.1.0", "generate-function": "^2.3.1", "iconv-lite": "^0.7.0", "long": "^5.2.1", "lru.min": "^1.0.0", "named-placeholders": "^1.1.3", "seq-queue": "^0.0.5", "sqlstring": "^2.3.2" } }, "sha512-FBrGau0IXmuqg4haEZRBfHNWB5mUARw6hNwPDXXGg0XzVJ50mr/9hb267lvpVMnhZ1FON3qNd4Xfcez1rbFwSg=="],
 
     "named-placeholders": ["named-placeholders@1.1.6", "", { "dependencies": { "lru.min": "^1.1.0" } }, "sha512-Tz09sEL2EEuv5fFowm419c1+a/jSMiBjI9gHxVLrVdbUkkNUUfjsVYs9pVZu5oCon/kmRh9TfLEObFtkVxmY0w=="],
@@ -895,8 +944,18 @@
 
     "ohash": ["ohash@2.0.11", "", {}, "sha512-RdR9FQrFwNBNXAr4GixM8YaRZRJ5PUWbKYbE5eOsrwAjJW0q2REGcf79oYPsLyskQCZG1PLN+S/K1V00joZAoQ=="],
 
+    "openai": ["openai@6.39.0", "", { "peerDependencies": { "ws": "^8.18.0", "zod": "^3.25 || ^4.0" }, "optionalPeers": ["ws", "zod"], "bin": { "openai": "bin/cli" } }, "sha512-O61LIsimY3acVabwvomwFhwrnN36yvHY2quIfy9keEcFytGgWeV35yLHQ6NVMLSBxRpHmcg2yuhCnlu2HT4pLQ=="],
+
     "orderedmap": ["orderedmap@2.1.1", "", {}, "sha512-TvAWxi0nDe1j/rtMcWcIj94+Ffe6n7zhow33h40SKxmsmozs6dz/e+EajymfoFcHd7sxNn8yHM8839uixMOV6g=="],
 
+    "p-finally": ["p-finally@1.0.0", "", {}, "sha512-LICb2p9CB7FS+0eR1oqWnHhp0FljGLZCWBE9aix0Uye9W8LTQPwMTYVGWQWIw9RdQiDg4+epXQODwIYJtSJaow=="],
+
+    "p-queue": ["p-queue@6.6.2", "", { "dependencies": { "eventemitter3": "^4.0.4", "p-timeout": "^3.2.0" } }, "sha512-RwFpb72c/BhQLEXIZ5K2e+AhgNVmIejGlTgiB9MzZ0e93GRvqZ7uSi0dvRF7/XIXDeNkra2fNHBxTyPDGySpjQ=="],
+
+    "p-retry": ["p-retry@7.1.1", "", { "dependencies": { "is-network-error": "^1.1.0" } }, "sha512-J5ApzjyRkkf601HpEeykoiCvzHQjWxPAHhyjFcEUP2SWq0+35NKh8TLhpLw+Dkq5TZBFvUM6UigdE9hIVYTl5w=="],
+
+    "p-timeout": ["p-timeout@3.2.0", "", { "dependencies": { "p-finally": "^1.0.0" } }, "sha512-rhIwUycgwwKcP9yTOOFK/AKsAopjjCakVqLHePO3CC6Mir1Z99xT+R63jZxAT5lFZLa2inS5h+ZS2GvR99/FBg=="],
+
     "parse5": ["parse5@7.3.0", "", { "dependencies": { "entities": "^6.0.0" } }, "sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw=="],
 
     "parseley": ["parseley@0.12.1", "", { "dependencies": { "leac": "^0.6.0", "peberminta": "^0.9.0" } }, "sha512-e6qHKe3a9HWr0oMRVDTRhKce+bRO8VGQR3NyVwcjwrbhMmFCX9KszEV35+rn4AdilFAq9VPxP/Fe1wC9Qjd2lw=="],
@@ -1089,6 +1148,8 @@
 
     "tr46": ["tr46@6.0.0", "", { "dependencies": { "punycode": "^2.3.1" } }, "sha512-bLVMLPtstlZ4iMQHpFHTR7GAGj2jxi8Dg0s2h2MafAE4uSWF98FC/3MomU51iQAMf8/qDUbKWf5GxuvvVcXEhw=="],
 
+    "ts-algebra": ["ts-algebra@2.0.0", "", {}, "sha512-FPAhNPFMrkwz76P7cdjdmiShwMynZYN6SgOujD1urY4oNm80Ou9oMdmbR45LotcKOXoy7wSmHkRFE6Mxbrhefw=="],
+
     "tslib": ["tslib@2.8.1", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
 
     "tsx": ["tsx@4.21.0", "", { "dependencies": { "esbuild": "~0.27.0", "get-tsconfig": "^4.7.5" }, "optionalDependencies": { "fsevents": "~2.3.3" }, "bin": { "tsx": "dist/cli.mjs" } }, "sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw=="],
@@ -1139,7 +1200,7 @@
 
     "zeptomatch": ["zeptomatch@2.1.0", "", { "dependencies": { "grammex": "^3.1.11", "graphmatch": "^1.1.0" } }, "sha512-KiGErG2J0G82LSpniV0CtIzjlJ10E04j02VOudJsPyPwNZgGnRKQy7I1R7GMyg/QswnE4l7ohSGrQbQbjXPPDA=="],
 
-    "zod": ["zod@4.3.6", "", {}, "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg=="],
+    "zod": ["zod@4.4.3", "", {}, "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ=="],
 
     "@aws-crypto/sha1-browser/@smithy/util-utf8": ["@smithy/util-utf8@2.3.0", "", { "dependencies": { "@smithy/util-buffer-from": "^2.2.0", "tslib": "^2.6.2" } }, "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A=="],
 
@@ -1211,14 +1272,24 @@
 
     "@aws-sdk/util-user-agent-node/@smithy/node-config-provider": ["@smithy/node-config-provider@4.3.11", "", { "dependencies": { "@smithy/property-provider": "^4.2.11", "@smithy/shared-ini-file-loader": "^4.4.6", "@smithy/types": "^4.13.0", "tslib": "^2.6.2" } }, "sha512-xD17eE7kaLgBBGf5CZQ58hh2YmwK1Z0O8YhffwB/De2jsL0U3JklmhVYJ9Uf37OtUDLF2gsW40Xwwag9U869Gg=="],
 
+    "@better-auth/core/zod": ["zod@4.3.6", "", {}, "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg=="],
+
     "@esbuild-kit/core-utils/esbuild": ["esbuild@0.18.20", "", { "optionalDependencies": { "@esbuild/android-arm": "0.18.20", "@esbuild/android-arm64": "0.18.20", "@esbuild/android-x64": "0.18.20", "@esbuild/darwin-arm64": "0.18.20", "@esbuild/darwin-x64": "0.18.20", "@esbuild/freebsd-arm64": "0.18.20", "@esbuild/freebsd-x64": "0.18.20", "@esbuild/linux-arm": "0.18.20", "@esbuild/linux-arm64": "0.18.20", "@esbuild/linux-ia32": "0.18.20", "@esbuild/linux-loong64": "0.18.20", "@esbuild/linux-mips64el": "0.18.20", "@esbuild/linux-ppc64": "0.18.20", "@esbuild/linux-riscv64": "0.18.20", "@esbuild/linux-s390x": "0.18.20", "@esbuild/linux-x64": "0.18.20", "@esbuild/netbsd-x64": "0.18.20", "@esbuild/openbsd-x64": "0.18.20", "@esbuild/sunos-x64": "0.18.20", "@esbuild/win32-arm64": "0.18.20", "@esbuild/win32-ia32": "0.18.20", "@esbuild/win32-x64": "0.18.20" }, "bin": { "esbuild": "bin/esbuild" } }, "sha512-ceqxoedUrcayh7Y7ZX6NdbbDzGROiyVBgC4PriJThBKSVPWnnFHZAkfI1lJT8QFkOwH4qOS2SJkS4wvpGl8BpA=="],
 
     "@fastify/otel/@opentelemetry/instrumentation": ["@opentelemetry/instrumentation@0.212.0", "", { "dependencies": { "@opentelemetry/api-logs": "0.212.0", "import-in-the-middle": "^2.0.6", "require-in-the-middle": "^8.0.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-IyXmpNnifNouMOe0I/gX7ENfv2ZCNdYTF0FpCsoBcpbIHzk81Ww9rQTYTnvghszCg7qGrIhNvWC8dhEifgX9Jg=="],
 
+    "@langchain/core/zod": ["zod@4.3.6", "", {}, "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg=="],
+
+    "@langchain/langgraph-sdk/p-queue": ["p-queue@9.3.0", "", { "dependencies": { "eventemitter3": "^5.0.4", "p-timeout": "^7.0.0" } }, "sha512-7NED7xhQ74Ngp4JP/2e0VZHp7vSWfJfqeiR92jPgxsz6m0Se4P03YoTKa9dDXyZ3r6P616gUXttrB6nnHYKang=="],
+
+    "@langchain/langgraph-sdk/uuid": ["uuid@13.0.2", "", { "bin": { "uuid": "dist-node/bin/uuid" } }, "sha512-vzi9uRZ926x4XV73S/4qQaTwPXM2JBj6/6lI/byHH1jOpCzb0zDbfytgA9LcN/hzb2l7WQSQnxITOVx5un/wGw=="],
+
     "@opentelemetry/instrumentation-http/@opentelemetry/core": ["@opentelemetry/core@2.6.1", "", { "dependencies": { "@opentelemetry/semantic-conventions": "^1.29.0" }, "peerDependencies": { "@opentelemetry/api": ">=1.0.0 <1.10.0" } }, "sha512-8xHSGWpJP9wBxgBpnqGL0R3PbdWQndL1Qp50qrg71+B28zK5OQmUgcDKLJgzyAAV38t4tOyLMGDD60LneR5W8g=="],
 
     "@opentelemetry/instrumentation-pg/@types/pg": ["@types/pg@8.15.6", "", { "dependencies": { "@types/node": "*", "pg-protocol": "*", "pg-types": "^2.2.0" } }, "sha512-NoaMtzhxOrubeL/7UZuNTrejB4MPAJ0RpxZqXQf2qXuVlTPuG6Y8p4u9dKRaue4yjmC7ZhzVO2/Yyyn25znrPQ=="],
 
+    "@polar-sh/sdk/zod": ["zod@4.3.6", "", {}, "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg=="],
+
     "@prisma/dev/@hono/node-server": ["@hono/node-server@1.19.9", "", { "peerDependencies": { "hono": "^4" } }, "sha512-vHL6w3ecZsky+8P5MD+eFfaGTyCeOHUIFYMGpQGbrBTSmNNoxv0if69rEZ5giu36weC5saFuznL411gRX7bJDw=="],
 
     "@prisma/dev/hono": ["hono@4.11.4", "", {}, "sha512-U7tt8JsyrxSRKspfhtLET79pU8K+tInj5QZXs1jSugO1Vq5dFj3kmZsRldo29mTBfcjDRVRXrEZ6LS63Cog9ZA=="],
@@ -1307,6 +1378,8 @@
 
     "better-auth/jose": ["jose@6.1.3", "", {}, "sha512-0TpaTfihd4QMNwrz/ob2Bp7X04yuxJkjRGi4aKmOqwhov54i6u79oCv7T+C7lo70MKH6BesI3vscD1yb/yzKXQ=="],
 
+    "better-auth/zod": ["zod@4.3.6", "", {}, "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg=="],
+
     "dom-serializer/entities": ["entities@4.5.0", "", {}, "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw=="],
 
     "happy-dom/entities": ["entities@7.0.1", "", {}, "sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA=="],
@@ -1399,6 +1472,10 @@
 
     "@fastify/otel/@opentelemetry/instrumentation/import-in-the-middle": ["import-in-the-middle@2.0.6", "", { "dependencies": { "acorn": "^8.15.0", "acorn-import-attributes": "^1.9.5", "cjs-module-lexer": "^2.2.0", "module-details-from-path": "^1.0.4" } }, "sha512-3vZV3jX0XRFW3EJDTwzWoZa+RH1b8eTTx6YOCjglrLyPuepwoBti1k3L2dKwdCUrnVEfc5CuRuGstaC/uQJJaw=="],
 
+    "@langchain/langgraph-sdk/p-queue/eventemitter3": ["eventemitter3@5.0.4", "", {}, "sha512-mlsTRyGaPBjPedk6Bvw+aqbsXDtoAyAzm5MO7JgU+yVRyMQ5O8bD4Kcci7BS85f93veegeCPkL8R4GLClnjLFw=="],
+
+    "@langchain/langgraph-sdk/p-queue/p-timeout": ["p-timeout@7.0.1", "", {}, "sha512-AxTM2wDGORHGEkPCt8yqxOTMgpfbEHqF51f/5fJCmwFC3C/zNcGT63SymH2ttOAaiIws2zVg4+izQCjrakcwHg=="],
+
     "@opentelemetry/instrumentation-pg/@types/pg/pg-protocol": ["pg-protocol@1.13.0", "", {}, "sha512-zzdvXfS6v89r6v7OcFCHfHlyG/wvry1ALxZo4LqgUoy7W9xhBDMaqOuMiF3qEV45VqsN6rdlcehHrfDtlCPc8w=="],
 
     "@prisma/instrumentation/@opentelemetry/instrumentation/@opentelemetry/api-logs": ["@opentelemetry/api-logs@0.207.0", "", { "dependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-lAb0jQRVyleQQGiuuvCOTDVspc14nx6XJjP4FspJ1sNARo3Regq4ZZbrc3rN4b1TYSuUCvgH+UXUPug4SLOqEQ=="],
diff --git a/server/api/drizzle/0031_add_wiki_compose_sessions.sql b/server/api/drizzle/0031_add_wiki_compose_sessions.sql
new file mode 100644
index 00000000..d15dc68a
--- /dev/null
+++ b/server/api/drizzle/0031_add_wiki_compose_sessions.sql
@@ -0,0 +1,57 @@
+-- 0031: Add `wiki_compose_sessions` — meta-row table for Wiki Compose runs.
+-- Wiki Compose (LangGraph) の実行メタテーブルを追加する。
+--
+-- 1 行 = 1 セッション。session.id は LangGraph の thread_id として再利用される。
+-- LangGraph の checkpoint 系テーブル (checkpoints / checkpoint_blobs /
+-- checkpoint_writes) は `PostgresSaver.setup()` 側で別管理するため、本
+-- migration では作成しない。
+--
+-- One row per compose run. The session id doubles as the LangGraph
+-- `thread_id`. The internal `checkpoints*` tables are owned by
+-- `PostgresSaver.setup()` and intentionally excluded from this migration.
+--
+-- Issue: otomatty/zedi#948 (P0 — LangGraph 基盤)
+--
+-- Idempotent / re-run safety: CREATE TABLE/INDEX IF NOT EXISTS and the FK ADD
+-- block is wrapped in a duplicate-object guard.
+
+CREATE TABLE IF NOT EXISTS "wiki_compose_sessions" (
+    "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+    "page_id" uuid NOT NULL,
+    "user_id" text NOT NULL,
+    "graph_id" text NOT NULL,
+    "phase" text DEFAULT 'init' NOT NULL,
+    "backend" text DEFAULT 'zedi_managed' NOT NULL,
+    "status" text DEFAULT 'pending' NOT NULL,
+    "metadata" jsonb,
+    "last_error" text,
+    "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+    "updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+    "closed_at" timestamp with time zone
+);
+--> statement-breakpoint
+DO $$ BEGIN
+    ALTER TABLE "wiki_compose_sessions"
+        ADD CONSTRAINT "wiki_compose_sessions_page_id_pages_id_fk"
+        FOREIGN KEY ("page_id") REFERENCES "pages"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION
+    WHEN duplicate_object THEN NULL;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+    ALTER TABLE "wiki_compose_sessions"
+        ADD CONSTRAINT "wiki_compose_sessions_user_id_users_id_fk"
+        FOREIGN KEY ("user_id") REFERENCES "user"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION
+    WHEN duplicate_object THEN NULL;
+END $$;
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "idx_wiki_compose_sessions_page_id"
+    ON "wiki_compose_sessions" ("page_id");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "idx_wiki_compose_sessions_user_id"
+    ON "wiki_compose_sessions" ("user_id");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "idx_wiki_compose_sessions_page_active_updated"
+    ON "wiki_compose_sessions" ("page_id", "updated_at" DESC)
+    WHERE "status" IN ('pending', 'running', 'interrupted');
diff --git a/server/api/drizzle/0032_add_user_ai_credentials.sql b/server/api/drizzle/0032_add_user_ai_credentials.sql
new file mode 100644
index 00000000..f82bec19
--- /dev/null
+++ b/server/api/drizzle/0032_add_user_ai_credentials.sql
@@ -0,0 +1,35 @@
+-- 0032: Encrypted BYOK API credentials for Wiki Compose (#951).
+-- Wiki Compose BYOK 用のユーザー API キー（サーバー側暗号化保管）。
+--
+-- Plaintext keys are never stored. See `userAiCredentials` schema TSDoc.
+-- 平文キーは保存しない。`user_ai_credentials` の TSDoc を参照。
+--
+-- Issue: otomatty/zedi#951
+
+CREATE TABLE IF NOT EXISTS "user_ai_credentials" (
+    "id" text PRIMARY KEY NOT NULL,
+    "user_id" text NOT NULL,
+    "provider" text NOT NULL,
+    "encrypted_api_key" text NOT NULL,
+    "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+    "updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+DO $$ BEGIN
+    ALTER TABLE "user_ai_credentials"
+        ADD CONSTRAINT "user_ai_credentials_user_id_users_id_fk"
+        FOREIGN KEY ("user_id") REFERENCES "user"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION
+    WHEN duplicate_object THEN NULL;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+    ALTER TABLE "user_ai_credentials"
+        ADD CONSTRAINT "user_ai_credentials_provider_valid"
+        CHECK ("provider" IN ('anthropic', 'openai', 'google'));
+EXCEPTION
+    WHEN duplicate_object THEN NULL;
+END $$;
+--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "idx_user_ai_credentials_user_provider"
+    ON "user_ai_credentials" ("user_id", "provider");
diff --git a/server/api/drizzle/meta/_journal.json b/server/api/drizzle/meta/_journal.json
index 24641874..440645b9 100644
--- a/server/api/drizzle/meta/_journal.json
+++ b/server/api/drizzle/meta/_journal.json
@@ -211,6 +211,20 @@
       "when": 1779840000000,
       "tag": "0030_add_notes_tag_filter_bar",
       "breakpoints": true
+    },
+    {
+      "idx": 30,
+      "version": "7",
+      "when": 1779926400000,
+      "tag": "0031_add_wiki_compose_sessions",
+      "breakpoints": true
+    },
+    {
+      "idx": 31,
+      "version": "7",
+      "when": 1780012800000,
+      "tag": "0032_add_user_ai_credentials",
+      "breakpoints": true
     }
   ]
 }
diff --git a/server/api/package.json b/server/api/package.json
index 32f47341..48cdd7ce 100644
--- a/server/api/package.json
+++ b/server/api/package.json
@@ -20,6 +20,12 @@
     "@aws-sdk/client-s3": "^3.1002.0",
     "@aws-sdk/s3-request-presigner": "^3.1002.0",
     "@hono/node-server": "^2.0.0",
+    "@langchain/anthropic": "^1.4.0",
+    "@langchain/core": "^1.1.48",
+    "@langchain/google-genai": "^2.1.31",
+    "@langchain/langgraph": "^1.3.2",
+    "@langchain/langgraph-checkpoint-postgres": "^1.0.1",
+    "@langchain/openai": "^1.4.7",
     "@mozilla/readability": "^0.6.0",
     "@polar-sh/sdk": "^0.47.0",
     "@react-email/components": "^1.0.11",
@@ -44,7 +50,8 @@
     "react-dom": "^19.2.4",
     "resend": "^6.10.0",
     "yjs": "^13.6.30",
-    "youtubei.js": "^17.0.1"
+    "youtubei.js": "^17.0.1",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/jsdom": "^28.0.0",
diff --git a/server/api/src/__tests__/agents/core/composeBackendValidation.test.ts b/server/api/src/__tests__/agents/core/composeBackendValidation.test.ts
new file mode 100644
index 00000000..5595cbcc
--- /dev/null
+++ b/server/api/src/__tests__/agents/core/composeBackendValidation.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { HTTPException } from "hono/http-exception";
+import { assertComposeBackendReady } from "../../../agents/core/composeBackendValidation.js";
+
+const mockGetUserAiCredentialPlaintext = vi.fn();
+
+vi.mock("../../../services/userAiCredentialService.js", () => ({
+  getUserAiCredentialPlaintext: (...args: unknown[]) => mockGetUserAiCredentialPlaintext(...args),
+}));
+
+describe("assertComposeBackendReady", () => {
+  const db = {} as never;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockGetUserAiCredentialPlaintext.mockResolvedValue("sk-user");
+  });
+
+  it("no-ops for zedi_managed", async () => {
+    await assertComposeBackendReady({
+      backend: "zedi_managed",
+      graphId: "wiki-compose",
+      userId: "u1",
+      tier: "free",
+      db,
+    });
+    expect(mockGetUserAiCredentialPlaintext).not.toHaveBeenCalled();
+  });
+
+  it("allows BYOK backend without static env model provider mismatch (#972)", async () => {
+    await assertComposeBackendReady({
+      backend: "user_openai",
+      graphId: "wiki-compose-research",
+      userId: "u1",
+      tier: "free",
+      db,
+    });
+    expect(mockGetUserAiCredentialPlaintext).toHaveBeenCalledWith("u1", "openai", db);
+  });
+
+  it("skips credential check for model-less graphs (wiki-maintenance)", async () => {
+    await assertComposeBackendReady({
+      backend: "user_anthropic",
+      graphId: "wiki-maintenance",
+      userId: "u1",
+      tier: "free",
+      db,
+    });
+    expect(mockGetUserAiCredentialPlaintext).not.toHaveBeenCalled();
+  });
+
+  it("throws 400 when credential is missing", async () => {
+    mockGetUserAiCredentialPlaintext.mockResolvedValue(null);
+    await expect(
+      assertComposeBackendReady({
+        backend: "user_anthropic",
+        graphId: "wiki-compose-research",
+        userId: "u1",
+        tier: "free",
+        db,
+      }),
+    ).rejects.toBeInstanceOf(HTTPException);
+  });
+});
diff --git a/server/api/src/__tests__/agents/core/llm/modelFactory.test.ts b/server/api/src/__tests__/agents/core/llm/modelFactory.test.ts
new file mode 100644
index 00000000..b584580c
--- /dev/null
+++ b/server/api/src/__tests__/agents/core/llm/modelFactory.test.ts
@@ -0,0 +1,111 @@
+/**
+ * Tests for compose backend validation and BYOK API key resolution (#951).
+ */
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import {
+  assertSupportedComposeBackend,
+  assertSupportedBackendP0,
+  createZediChatModel,
+  UnsupportedBackendError,
+  MissingUserCredentialError,
+  BackendProviderMismatchError,
+} from "../../../../agents/core/llm/modelFactory.js";
+
+const mockValidateModelAccess = vi.fn();
+const mockGetUserAiCredentialPlaintext = vi.fn();
+
+vi.mock("../../../../services/usageService.js", () => ({
+  validateModelAccess: (...args: unknown[]) => mockValidateModelAccess(...args),
+}));
+
+vi.mock("../../../../services/userAiCredentialService.js", () => ({
+  getUserAiCredentialPlaintext: (...args: unknown[]) => mockGetUserAiCredentialPlaintext(...args),
+}));
+
+describe("assertSupportedComposeBackend", () => {
+  it.each(["zedi_managed", "user_anthropic", "user_openai", "user_google"] as const)(
+    "accepts %s",
+    (backend) => {
+      expect(assertSupportedComposeBackend(backend)).toBe(backend);
+      expect(assertSupportedBackendP0(backend)).toBe(backend);
+    },
+  );
+
+  it.each(["byok", "byo_runner", "unknown", "", "ZEDI_MANAGED"])(
+    "throws UnsupportedBackendError for %s",
+    (backend) => {
+      expect(() => assertSupportedComposeBackend(backend)).toThrow(UnsupportedBackendError);
+    },
+  );
+});
+
+describe("createZediChatModel backend resolution", () => {
+  const db = {} as never;
+  const baseInput = {
+    modelId: "openai:gpt-4o-mini",
+    userId: "user-1",
+    tier: "free" as const,
+    db,
+    feature: "wiki_compose:test",
+    temperature: 0.2,
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockValidateModelAccess.mockResolvedValue({
+      provider: "openai",
+      apiModelId: "gpt-4o-mini",
+      inputCostUnits: 1,
+      outputCostUnits: 2,
+    });
+  });
+
+  afterEach(() => {
+    delete process.env.OPENAI_API_KEY;
+  });
+
+  it("resolves zedi_managed from process.env", async () => {
+    process.env.OPENAI_API_KEY = "sk-system";
+    const model = await createZediChatModel({
+      ...baseInput,
+      backend: "zedi_managed",
+    });
+    expect(model).toBeDefined();
+    expect(mockGetUserAiCredentialPlaintext).not.toHaveBeenCalled();
+  });
+
+  it("resolves user_openai from stored credential", async () => {
+    mockGetUserAiCredentialPlaintext.mockResolvedValue("sk-user");
+    const model = await createZediChatModel({
+      ...baseInput,
+      backend: "user_openai",
+    });
+    expect(model).toBeDefined();
+    expect(mockGetUserAiCredentialPlaintext).toHaveBeenCalledWith("user-1", "openai", db);
+  });
+
+  it("throws MissingUserCredentialError when BYOK key is absent", async () => {
+    mockGetUserAiCredentialPlaintext.mockResolvedValue(null);
+    await expect(
+      createZediChatModel({
+        ...baseInput,
+        backend: "user_openai",
+      }),
+    ).rejects.toThrow(MissingUserCredentialError);
+  });
+
+  it("throws BackendProviderMismatchError when model provider differs from backend", async () => {
+    mockValidateModelAccess.mockResolvedValue({
+      provider: "anthropic",
+      apiModelId: "claude-3-5-sonnet-20241022",
+      inputCostUnits: 1,
+      outputCostUnits: 2,
+    });
+    await expect(
+      createZediChatModel({
+        ...baseInput,
+        backend: "user_openai",
+      }),
+    ).rejects.toThrow(BackendProviderMismatchError);
+  });
+});
diff --git a/server/api/src/__tests__/agents/core/llm/resolveComposeModelId.test.ts b/server/api/src/__tests__/agents/core/llm/resolveComposeModelId.test.ts
new file mode 100644
index 00000000..391da670
--- /dev/null
+++ b/server/api/src/__tests__/agents/core/llm/resolveComposeModelId.test.ts
@@ -0,0 +1,53 @@
+/**
+ * Tests for BYOK-aware compose model id resolution (#951).
+ */
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import { resolveComposeModelId } from "../../../../agents/core/llm/resolveComposeModelId.js";
+
+const mockDb = {
+  select: vi.fn(),
+};
+
+function chainLimit(rows: unknown[]) {
+  const chain = {
+    from: vi.fn().mockReturnThis(),
+    where: vi.fn().mockReturnThis(),
+    orderBy: vi.fn().mockReturnThis(),
+    limit: vi.fn().mockResolvedValue(rows),
+  };
+  return chain;
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  delete process.env.WIKI_COMPOSE_ORCHESTRATOR_MODEL_ID;
+  delete process.env.WIKI_COMPOSE_DRAFT_MODEL_ID;
+});
+
+afterEach(() => {
+  delete process.env.WIKI_COMPOSE_ORCHESTRATOR_MODEL_ID;
+  delete process.env.WIKI_COMPOSE_DRAFT_MODEL_ID;
+});
+
+describe("resolveComposeModelId", () => {
+  it("returns cheapest active OpenAI model for user_openai backend", async () => {
+    mockDb.select.mockReturnValueOnce(chainLimit([{ id: "openai:gpt-4o-mini" }]));
+    const id = await resolveComposeModelId("orchestrator", "user_openai", "free", mockDb as never);
+    expect(id).toBe("openai:gpt-4o-mini");
+  });
+
+  it("ignores env override when provider mismatches BYOK backend", async () => {
+    process.env.WIKI_COMPOSE_ORCHESTRATOR_MODEL_ID = "claude-3-5-haiku";
+    mockDb.select
+      .mockReturnValueOnce(chainLimit([{ id: "claude-3-5-haiku", provider: "anthropic" }]))
+      .mockReturnValueOnce(chainLimit([{ id: "openai:gpt-4o-mini" }]));
+    const id = await resolveComposeModelId("orchestrator", "user_openai", "free", mockDb as never);
+    expect(id).toBe("openai:gpt-4o-mini");
+  });
+
+  it("keeps zedi_managed default when no DB row matches", async () => {
+    mockDb.select.mockReturnValueOnce(chainLimit([]));
+    const id = await resolveComposeModelId("orchestrator", "zedi_managed", "free", mockDb as never);
+    expect(id).toBe("claude-3-5-haiku");
+  });
+});
diff --git a/server/api/src/__tests__/agents/core/llm/usageCallback.test.ts b/server/api/src/__tests__/agents/core/llm/usageCallback.test.ts
new file mode 100644
index 00000000..d1764078
--- /dev/null
+++ b/server/api/src/__tests__/agents/core/llm/usageCallback.test.ts
@@ -0,0 +1,65 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { recordZediUsage } from "../../../../agents/core/llm/usageCallback.js";
+
+const mockRecordUsage = vi.fn();
+const mockCalculateCost = vi.fn();
+
+vi.mock("../../../../services/usageService.js", () => ({
+  calculateCost: (...args: unknown[]) => mockCalculateCost(...args),
+  recordUsage: (...args: unknown[]) => mockRecordUsage(...args),
+}));
+
+describe("recordZediUsage", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockCalculateCost.mockReturnValue(42);
+  });
+
+  it("records zero costUnits for user_key (BYOK audit only)", async () => {
+    const db = {} as never;
+    const result = await recordZediUsage({
+      db,
+      userId: "u1",
+      modelId: "openai:gpt-4o-mini",
+      feature: "wiki_compose:test",
+      usage: { inputTokens: 100, outputTokens: 50 },
+      inputCostUnits: 10,
+      outputCostUnits: 20,
+      apiMode: "user_key",
+    });
+    expect(result.costUnits).toBe(0);
+    expect(mockRecordUsage).toHaveBeenCalledWith(
+      "u1",
+      "openai:gpt-4o-mini",
+      "wiki_compose:test",
+      { inputTokens: 100, outputTokens: 50 },
+      0,
+      "user_key",
+      db,
+    );
+  });
+
+  it("records calculated costUnits for system mode", async () => {
+    const db = {} as never;
+    const result = await recordZediUsage({
+      db,
+      userId: "u1",
+      modelId: "openai:gpt-4o-mini",
+      feature: "wiki_compose:test",
+      usage: { inputTokens: 100, outputTokens: 50 },
+      inputCostUnits: 10,
+      outputCostUnits: 20,
+      apiMode: "system",
+    });
+    expect(result.costUnits).toBe(42);
+    expect(mockRecordUsage).toHaveBeenCalledWith(
+      "u1",
+      "openai:gpt-4o-mini",
+      "wiki_compose:test",
+      { inputTokens: 100, outputTokens: 50 },
+      42,
+      "system",
+      db,
+    );
+  });
+});
diff --git a/server/api/src/__tests__/agents/core/llm/zediChatModel.test.ts b/server/api/src/__tests__/agents/core/llm/zediChatModel.test.ts
new file mode 100644
index 00000000..4b050773
--- /dev/null
+++ b/server/api/src/__tests__/agents/core/llm/zediChatModel.test.ts
@@ -0,0 +1,294 @@
+/**
+ * `ZediChatModel` のテスト。mock provider を注入し、`/api/ai/chat` と同じ usage
+ * 記録経路を通っていることを確認する。`recordUsage` 自体は `usageService.test.ts`
+ * 側で検証済みなので、本ファイルでは DB チェーンの呼び出し回数・cost 計算結果を
+ * 主に見る。
+ *
+ * Tests for {@link ZediChatModel}. Injects fake `callProvider` / `streamProvider`
+ * and asserts (1) the provider was called with the converted message shape,
+ * (2) `recordUsage` is invoked exactly once per call, (3) the LangChain
+ * `_generate` / `_streamResponseChunks` outputs surface usage metadata.
+ */
+import { describe, it, expect } from "vitest";
+import { HumanMessage, SystemMessage, AIMessage } from "@langchain/core/messages";
+import { ZediChatModel } from "../../../../agents/core/llm/zediChatModel.js";
+import { createMockDb } from "../../../createMockDb.js";
+import type {
+  AIChatOptions,
+  AIMessage as ZediAIMessage,
+  AIProviderType,
+  Database,
+} from "../../../../types/index.js";
+
+function asDb(results: unknown[]) {
+  const { db, chains } = createMockDb(results);
+  return { db: db as unknown as Database, chains };
+}
+
+interface CallSpy {
+  provider: AIProviderType;
+  apiKey: string;
+  model: string;
+  messages: ZediAIMessage[];
+  options: AIChatOptions;
+}
+
+function buildModel(
+  callResult: {
+    content: string;
+    usage: { inputTokens: number; outputTokens: number };
+    finishReason: string;
+  },
+  spy: { calls: CallSpy[] },
+) {
+  const { db, chains } = asDb([undefined, undefined]);
+  const model = new ZediChatModel({
+    provider: "openai",
+    apiKey: "test-key",
+    apiModelId: "gpt-test",
+    modelRowId: "model-1",
+    inputCostUnits: 10,
+    outputCostUnits: 30,
+    userId: "user-1",
+    tier: "free",
+    db,
+    feature: "wiki_compose:test",
+    callProvider: async (provider, apiKey, model, messages, options = {}) => {
+      spy.calls.push({ provider, apiKey, model, messages, options });
+      return callResult;
+    },
+    streamProvider: async function* () {
+      // Unused in non-streaming tests.
+    },
+  });
+  return { model, db, chains };
+}
+
+describe("ZediChatModel._generate", () => {
+  it("calls the injected provider with converted messages and records usage", async () => {
+    const spy = { calls: [] as CallSpy[] };
+    const { model, chains } = buildModel(
+      {
+        content: "Hello, world!",
+        usage: { inputTokens: 100, outputTokens: 50 },
+        finishReason: "stop",
+      },
+      spy,
+    );
+
+    const result = await model.invoke([new SystemMessage("Be concise."), new HumanMessage("Hi")]);
+
+    // Provider called exactly once with converted role/content.
+    // プロバイダは 1 回だけ呼ばれ、role と content が変換済みである。
+    expect(spy.calls).toHaveLength(1);
+    const call = spy.calls[0];
+    expect(call?.provider).toBe("openai");
+    expect(call?.model).toBe("gpt-test");
+    expect(call?.messages).toEqual([
+      { role: "system", content: "Be concise." },
+      { role: "user", content: "Hi" },
+    ]);
+
+    // usage was persisted: insert(aiUsageLogs) + insert(aiMonthlyUsage upsert).
+    // usage 記録 (aiUsageLogs + aiMonthlyUsage の 2 チェーン) が走っている。
+    expect(chains.length).toBe(2);
+    expect(chains[0]?.startMethod).toBe("insert");
+    expect(chains[1]?.startMethod).toBe("insert");
+
+    const valuesArg = chains[0]?.ops.find((op) => op.method === "values")?.args[0] as
+      | Record<string, unknown>
+      | undefined;
+    expect(valuesArg?.modelId).toBe("model-1");
+    expect(valuesArg?.feature).toBe("wiki_compose:test");
+    expect(valuesArg?.inputTokens).toBe(100);
+    expect(valuesArg?.outputTokens).toBe(50);
+    // calculateCost: (100/1000)*10 + (50/1000)*30 = 1 + 1.5 = 2.5 → ceil → 3
+    expect(valuesArg?.costUnits).toBe(3);
+    expect(valuesArg?.apiMode).toBe("system");
+
+    // LangChain message exposes usage in response_metadata.
+    // LangChain メッセージ側にも usage 情報が乗る。
+    expect(result.content).toBe("Hello, world!");
+    expect(result.response_metadata?.usage).toMatchObject({
+      inputTokens: 100,
+      outputTokens: 50,
+      costUnits: 3,
+    });
+  });
+
+  it("treats AI messages as 'assistant' role when converting", async () => {
+    const spy = { calls: [] as CallSpy[] };
+    const { model } = buildModel(
+      {
+        content: "next",
+        usage: { inputTokens: 0, outputTokens: 0 },
+        finishReason: "stop",
+      },
+      spy,
+    );
+
+    await model.invoke([new HumanMessage("Q1"), new AIMessage("A1"), new HumanMessage("Q2")]);
+
+    expect(spy.calls[0]?.messages).toEqual([
+      { role: "user", content: "Q1" },
+      { role: "assistant", content: "A1" },
+      { role: "user", content: "Q2" },
+    ]);
+  });
+
+  it("uses 'user_key' apiMode when constructed with apiMode='user_key' (BYOK forward-compat)", async () => {
+    const spy = { calls: [] as CallSpy[] };
+    const { db, chains } = asDb([undefined, undefined]);
+    const model = new ZediChatModel({
+      provider: "anthropic",
+      apiKey: "byok-key",
+      apiModelId: "claude-test",
+      modelRowId: "model-2",
+      inputCostUnits: 20,
+      outputCostUnits: 60,
+      userId: "u",
+      tier: "pro",
+      db,
+      feature: "wiki_compose:byok",
+      apiMode: "user_key",
+      callProvider: async (provider, apiKey, model, messages, options = {}) => {
+        spy.calls.push({ provider, apiKey, model, messages, options });
+        return {
+          content: "ok",
+          usage: { inputTokens: 0, outputTokens: 0 },
+          finishReason: "stop",
+        };
+      },
+      streamProvider: async function* () {},
+    });
+    void db;
+
+    await model.invoke([new HumanMessage("hi")]);
+
+    const valuesArg = chains[0]?.ops.find((op) => op.method === "values")?.args[0] as
+      | Record<string, unknown>
+      | undefined;
+    expect(valuesArg?.apiMode).toBe("user_key");
+  });
+});
+
+describe("ZediChatModel._streamResponseChunks", () => {
+  it("streams provider chunks and records usage with chars/4 fallback", async () => {
+    const { db, chains } = asDb([undefined, undefined]);
+    const model = new ZediChatModel({
+      provider: "google",
+      apiKey: "k",
+      apiModelId: "gemini-test",
+      modelRowId: "model-3",
+      inputCostUnits: 1,
+      outputCostUnits: 2,
+      userId: "user-x",
+      tier: "free",
+      db,
+      feature: "wiki_compose:stream",
+      callProvider: async () => ({
+        content: "",
+        usage: { inputTokens: 0, outputTokens: 0 },
+        finishReason: "stop",
+      }),
+      streamProvider: async function* () {
+        yield { content: "Hello, " };
+        yield { content: "world!" };
+        yield { done: true, finishReason: "stop" };
+      },
+    });
+
+    const stream = await model.stream([new HumanMessage("Tell me a story")]);
+    const chunks: string[] = [];
+    for await (const chunk of stream) {
+      chunks.push(typeof chunk.content === "string" ? chunk.content : "");
+    }
+
+    // Provider emitted two text chunks → those surface to the caller plus a
+    // final "" chunk that carries aggregated usage_metadata.
+    // プロバイダの 2 件のテキストチャンクが届き、最後に空 content + usage チャンクが届く。
+    expect(chunks).toEqual(["Hello, ", "world!", ""]);
+
+    // Usage was recorded with the chars/4 estimator.
+    // chars/4 推定で usage 記録が走る。
+    expect(chains.length).toBe(2);
+    const valuesArg = chains[0]?.ops.find((op) => op.method === "values")?.args[0] as
+      | Record<string, unknown>
+      | undefined;
+
+    // prompt: "Tell me a story" = 15 chars → ceil(15/4) = 4
+    // response: "Hello, world!" = 13 chars → ceil(13/4) = 4
+    expect(valuesArg?.inputTokens).toBe(4);
+    expect(valuesArg?.outputTokens).toBe(4);
+    // (4/1000)*1 + (4/1000)*2 = 0.012 → ceil → 1
+    expect(valuesArg?.costUnits).toBe(1);
+  });
+
+  it("uses 'incomplete' finishReason when the provider stream ends without done=true", async () => {
+    const { db, chains } = asDb([undefined, undefined]);
+    const model = new ZediChatModel({
+      provider: "openai",
+      apiKey: "k",
+      apiModelId: "m",
+      modelRowId: "m",
+      inputCostUnits: 0,
+      outputCostUnits: 0,
+      userId: "u",
+      tier: "free",
+      db,
+      feature: "x",
+      streamProvider: async function* () {
+        yield { content: "partial" };
+        // No done chunk before generator returns.
+      },
+    });
+
+    const lastChunks: unknown[] = [];
+    const stream = await model.stream([new HumanMessage("hi")]);
+    for await (const chunk of stream) lastChunks.push(chunk);
+    const last = lastChunks[lastChunks.length - 1] as {
+      response_metadata?: { finishReason?: string };
+    };
+    expect(last.response_metadata?.finishReason).toBe("incomplete");
+    expect(chains.length).toBe(0);
+  });
+
+  it("does not record usage when the provider stream throws", async () => {
+    const { db, chains } = asDb([undefined, undefined]);
+    const model = new ZediChatModel({
+      provider: "openai",
+      apiKey: "k",
+      apiModelId: "m",
+      modelRowId: "m",
+      inputCostUnits: 1,
+      outputCostUnits: 2,
+      userId: "u",
+      tier: "free",
+      db,
+      feature: "x",
+      streamProvider: async function* () {
+        yield { content: "partial" };
+        throw new Error("provider 502");
+      },
+    });
+
+    const stream = await model.stream([new HumanMessage("hi")]);
+    await expect(async () => {
+      for await (const _chunk of stream) {
+        /* drain */
+      }
+    }).rejects.toThrow("provider 502");
+    expect(chains.length).toBe(0);
+  });
+});
+
+describe("ZediChatModel._llmType", () => {
+  it("identifies the model family as 'zedi-chat'", () => {
+    const spy = { calls: [] as CallSpy[] };
+    const { model } = buildModel(
+      { content: "", usage: { inputTokens: 0, outputTokens: 0 }, finishReason: "stop" },
+      spy,
+    );
+    expect(model._llmType()).toBe("zedi-chat");
+  });
+});
diff --git a/server/api/src/__tests__/agents/core/tools/tools.test.ts b/server/api/src/__tests__/agents/core/tools/tools.test.ts
new file mode 100644
index 00000000..63ec45f7
--- /dev/null
+++ b/server/api/src/__tests__/agents/core/tools/tools.test.ts
@@ -0,0 +1,104 @@
+/**
+ * Tools (web_search / wiki_search / fetch_article / image_search) のスキーマと
+ * `bindTools` 互換性を確認するテスト。`wiki_search` / `web_search` /
+ * `fetch_article` は #949 で本実装に置き換わったため、sentinel 応答テストは
+ * 削除し、graph context 欠落時のエラー shape（JSON envelope `{ ok:false }`）を
+ * 確認する単体テストに差し替えた。詳細な挙動は
+ * `__tests__/agents/subgraphs/research/tools/*.test.ts` 側で検証する。
+ *
+ * Pin the public surface of the shared tool set so subgraph PRs cannot silently
+ * rename or restructure a tool. Stub `image_search` still returns a sentinel;
+ * other tools return JSON envelopes (parsed back by their caller nodes).
+ */
+import { describe, expect, it } from "vitest";
+import {
+  fetchArticleInputSchema,
+  fetchArticleTool,
+  FETCH_ARTICLE_TOOL_NAME,
+  imageSearchInputSchema,
+  imageSearchTool,
+  IMAGE_SEARCH_TOOL_NAME,
+  SHARED_TOOLS,
+  webSearchInputSchema,
+  webSearchTool,
+  WEB_SEARCH_TOOL_NAME,
+  wikiSearchInputSchema,
+  wikiSearchTool,
+  WIKI_SEARCH_TOOL_NAME,
+} from "../../../../agents/core/tools/index.js";
+
+describe("tool names", () => {
+  it("are stable and unique across the shared set", () => {
+    const names = [
+      WEB_SEARCH_TOOL_NAME,
+      WIKI_SEARCH_TOOL_NAME,
+      FETCH_ARTICLE_TOOL_NAME,
+      IMAGE_SEARCH_TOOL_NAME,
+    ];
+    expect(new Set(names).size).toBe(names.length);
+    expect(WEB_SEARCH_TOOL_NAME).toBe("web_search");
+    expect(WIKI_SEARCH_TOOL_NAME).toBe("wiki_search");
+    expect(FETCH_ARTICLE_TOOL_NAME).toBe("fetch_article");
+    expect(IMAGE_SEARCH_TOOL_NAME).toBe("image_search");
+  });
+});
+
+describe("input schemas", () => {
+  it("web_search requires a non-empty query", () => {
+    expect(webSearchInputSchema.safeParse({ query: "" }).success).toBe(false);
+    expect(webSearchInputSchema.safeParse({ query: "ripgrep" }).success).toBe(true);
+  });
+  it("web_search rejects limit > 10", () => {
+    expect(webSearchInputSchema.safeParse({ query: "x", limit: 11 }).success).toBe(false);
+  });
+  it("wiki_search rejects limit > 20", () => {
+    expect(wikiSearchInputSchema.safeParse({ query: "x", limit: 21 }).success).toBe(false);
+  });
+  it("fetch_article rejects non-http URLs", () => {
+    expect(fetchArticleInputSchema.safeParse({ url: "ftp://x/y" }).success).toBe(false);
+    expect(fetchArticleInputSchema.safeParse({ url: "https://x/y" }).success).toBe(true);
+  });
+  it("fetch_article clamps previewLength to 500..8000", () => {
+    expect(
+      fetchArticleInputSchema.safeParse({ url: "https://x", previewLength: 100 }).success,
+    ).toBe(false);
+    expect(
+      fetchArticleInputSchema.safeParse({ url: "https://x", previewLength: 4000 }).success,
+    ).toBe(true);
+  });
+  it("image_search rejects page > 10", () => {
+    expect(imageSearchInputSchema.safeParse({ query: "x", page: 11 }).success).toBe(false);
+  });
+});
+
+describe("SHARED_TOOLS", () => {
+  it("contains all four shared tools in a stable order", () => {
+    expect(SHARED_TOOLS.map((t) => t.name)).toEqual([
+      WEB_SEARCH_TOOL_NAME,
+      WIKI_SEARCH_TOOL_NAME,
+      FETCH_ARTICLE_TOOL_NAME,
+      IMAGE_SEARCH_TOOL_NAME,
+    ]);
+  });
+});
+
+describe("tool bodies — minimal envelopes", () => {
+  it("wiki_search returns a JSON envelope and reports missing context", async () => {
+    const raw = (await wikiSearchTool.invoke({ query: "ripgrep" })) as unknown;
+    expect(typeof raw).toBe("string");
+    const parsed = JSON.parse(raw as string) as { ok: boolean; error?: string };
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error).toBe("missing_graph_context");
+  });
+  it("web_search returns a JSON envelope and reports missing context", async () => {
+    const raw = (await webSearchTool.invoke({ query: "ripgrep" })) as unknown;
+    expect(typeof raw).toBe("string");
+    const parsed = JSON.parse(raw as string) as { ok: boolean; error?: string };
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error).toBe("missing_graph_context");
+  });
+  it("image_search still returns the not-implemented sentinel (#949 scope)", async () => {
+    const out = (await imageSearchTool.invoke({ query: "cat" })) as unknown;
+    expect(out).toMatch(/IMAGE_SEARCH_NOT_IMPLEMENTED/);
+  });
+});
diff --git a/server/api/src/__tests__/agents/core/types/executionBackend.test.ts b/server/api/src/__tests__/agents/core/types/executionBackend.test.ts
new file mode 100644
index 00000000..e3bcdb1f
--- /dev/null
+++ b/server/api/src/__tests__/agents/core/types/executionBackend.test.ts
@@ -0,0 +1,46 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+const mockGetUserAiCredentialPlaintext = vi.fn();
+
+vi.mock("../../../../services/userAiCredentialService.js", () => ({
+  getUserAiCredentialPlaintext: (...args: unknown[]) => mockGetUserAiCredentialPlaintext(...args),
+}));
+
+import {
+  resolveWebSearchExecutionBackend,
+  resolveWebSearchExecutionBackendForRun,
+} from "../../../../agents/core/types/executionBackend.js";
+
+describe("resolveWebSearchExecutionBackend", () => {
+  it("uses zedi_managed for zedi_managed sessions", () => {
+    expect(resolveWebSearchExecutionBackend("zedi_managed", "openai")).toBe("zedi_managed");
+  });
+
+  it("uses session backend when provider matches", () => {
+    expect(resolveWebSearchExecutionBackend("user_openai", "openai")).toBe("user_openai");
+  });
+
+  it("uses cross-provider BYOK credential when session is another provider", () => {
+    expect(resolveWebSearchExecutionBackend("user_anthropic", "openai")).toBe("user_openai");
+  });
+});
+
+describe("resolveWebSearchExecutionBackendForRun", () => {
+  beforeEach(() => {
+    mockGetUserAiCredentialPlaintext.mockReset();
+  });
+
+  it("falls back to zedi_managed when cross-provider credential is missing", async () => {
+    mockGetUserAiCredentialPlaintext.mockResolvedValue(null);
+    await expect(
+      resolveWebSearchExecutionBackendForRun("user_anthropic", "openai", "user-1", {} as never),
+    ).resolves.toBe("zedi_managed");
+  });
+
+  it("uses cross-provider BYOK when credential exists", async () => {
+    mockGetUserAiCredentialPlaintext.mockResolvedValue("sk-openai");
+    await expect(
+      resolveWebSearchExecutionBackendForRun("user_anthropic", "openai", "user-1", {} as never),
+    ).resolves.toBe("user_openai");
+  });
+});
diff --git a/server/api/src/__tests__/agents/graphs/ingest/formatResearchForIngest.test.ts b/server/api/src/__tests__/agents/graphs/ingest/formatResearchForIngest.test.ts
new file mode 100644
index 00000000..fcb0afea
--- /dev/null
+++ b/server/api/src/__tests__/agents/graphs/ingest/formatResearchForIngest.test.ts
@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import { formatResearchForIngest } from "../../../../agents/graphs/ingest/nodes/formatResearchForIngest.js";
+import type { IngestPlannerStateType } from "../../../../agents/graphs/ingest/state.js";
+
+function baseState(): IngestPlannerStateType {
+  return {
+    messages: [],
+    phase: "ingest:prepare",
+    pageId: "",
+    userId: "u1",
+    article: { title: "T", url: "https://a/", excerpt: "body" },
+    candidates: [],
+    userSchema: null,
+    ingestPlan: null,
+    iteration: 1,
+    maxIterations: 3,
+    queries: [],
+    pendingSources: [],
+    lastEvaluation: null,
+    exitReason: null,
+    batches: [
+      {
+        id: "b1",
+        iteration: 1,
+        queries: [],
+        sources: [],
+        evaluation: { score: 0.9, rationale: "ok", missingAspects: [] },
+        createdAt: "2026-01-01T00:00:00.000Z",
+      },
+    ],
+    approvedResearch: [
+      {
+        id: "src:1",
+        kind: "fetched",
+        title: "Research hit",
+        url: "https://hit/",
+        excerpt: "Details from web",
+      },
+    ],
+    rejectedResearch: [],
+    additionalRequest: null,
+  };
+}
+
+describe("formatResearchForIngest", () => {
+  it("includes approved sources and evaluation in the prompt block", () => {
+    const block = formatResearchForIngest(baseState());
+    expect(block).toContain("APPROVED RESEARCH SOURCES");
+    expect(block).toContain("src:1");
+    expect(block).toContain("Research hit");
+    expect(block).toContain("RESEARCH EVALUATION");
+    expect(block).toContain("score: 0.9");
+  });
+
+  it("returns empty string when no research output exists", () => {
+    const state = baseState();
+    state.approvedResearch = [];
+    state.batches = [];
+    expect(formatResearchForIngest(state)).toBe("");
+  });
+});
diff --git a/server/api/src/__tests__/agents/graphs/ingest/ingestPlannerGraph.test.ts b/server/api/src/__tests__/agents/graphs/ingest/ingestPlannerGraph.test.ts
new file mode 100644
index 00000000..9c0fb11d
--- /dev/null
+++ b/server/api/src/__tests__/agents/graphs/ingest/ingestPlannerGraph.test.ts
@@ -0,0 +1,212 @@
+/**
+ * Ingest planner graph (#952) — research subgraph wiring + routing tests.
+ * ingest プランナーグラフ — 調査 subgraph 配線とルーティングのテスト。
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const {
+  prepareIngest,
+  planIngest,
+  planQueries,
+  webSearch,
+  wikiSearch,
+  fetchArticles,
+  evaluateSufficiency,
+  refineQueries,
+  compileBatch,
+} = vi.hoisted(() => ({
+  prepareIngest: vi.fn(),
+  planIngest: vi.fn(),
+  planQueries: vi.fn(),
+  webSearch: vi.fn(),
+  wikiSearch: vi.fn(),
+  fetchArticles: vi.fn(),
+  evaluateSufficiency: vi.fn(),
+  refineQueries: vi.fn(),
+  compileBatch: vi.fn(),
+}));
+
+vi.mock("../../../../agents/graphs/ingest/nodes/index.js", async () => {
+  const real = await vi.importActual<
+    typeof import("../../../../agents/graphs/ingest/nodes/index.js")
+  >("../../../../agents/graphs/ingest/nodes/index.js");
+  return { ...real, prepareIngest, planIngest };
+});
+
+vi.mock("../../../../agents/subgraphs/research/nodes/index.js", async () => {
+  const real = await vi.importActual<
+    typeof import("../../../../agents/subgraphs/research/nodes/index.js")
+  >("../../../../agents/subgraphs/research/nodes/index.js");
+  return {
+    ...real,
+    planQueries,
+    webSearch,
+    wikiSearch,
+    fetchArticles,
+    evaluateSufficiency,
+    refineQueries,
+    compileBatch,
+  };
+});
+
+import { GraphRunner } from "../../../../agents/runner/graphRunner.js";
+import { __resetRegistryForTests } from "../../../../agents/registry/graphRegistry.js";
+import {
+  INGEST_PLANNER_GRAPH_ID,
+  registerIngestPlannerGraph,
+} from "../../../../agents/graphs/ingest/index.js";
+import type { GraphContext } from "../../../../agents/core/types/graphContext.js";
+import type { Database } from "../../../../types/index.js";
+import { MemorySaver } from "@langchain/langgraph";
+
+function fakeContext(threadId: string): GraphContext {
+  return {
+    threadId,
+    sessionId: threadId,
+    userId: "user-1",
+    pageId: "",
+    graphId: INGEST_PLANNER_GRAPH_ID,
+    backend: "zedi_managed",
+    tier: "free",
+    db: {} as Database,
+    feature: "ingest_graph:test",
+    userEmail: null,
+  };
+}
+
+const articleInput = {
+  title: "Test Article",
+  url: "https://example.com/a",
+  excerpt: "Body text about testing.",
+};
+
+const candidatesInput = [{ id: "page-1", title: "Existing", excerpt: "Old content" }];
+
+function defaultMocks() {
+  prepareIngest.mockImplementation(async () => ({
+    article: articleInput,
+    candidates: candidatesInput,
+    phase: "ingest:prepare",
+  }));
+
+  planQueries.mockImplementation(async () => ({
+    queries: [{ id: "q1", query: "topic", channels: ["web"] }],
+    maxIterations: 3,
+    iteration: 0,
+    phase: "research:plan",
+  }));
+  webSearch.mockImplementation(async () => ({
+    pendingSources: [{ id: "src:1", kind: "web", title: "Hit", url: "https://hit/" }],
+  }));
+  wikiSearch.mockImplementation(async () => ({ pendingSources: [] }));
+  fetchArticles.mockImplementation(async () => ({ pendingSources: [] }));
+  evaluateSufficiency.mockImplementation(async (state: { iteration: number }) => ({
+    lastEvaluation: { score: 0.9, rationale: "ok", missingAspects: [] },
+    iteration: state.iteration + 1,
+    phase: "research:evaluated",
+  }));
+  compileBatch.mockImplementation(
+    async (state: {
+      iteration: number;
+      queries: unknown[];
+      pendingSources: unknown[];
+      lastEvaluation: unknown;
+    }) => ({
+      batches: [
+        {
+          id: "batch-1",
+          iteration: state.iteration,
+          queries: state.queries,
+          sources: state.pendingSources,
+          evaluation: state.lastEvaluation,
+          createdAt: "2026-01-01T00:00:00.000Z",
+        },
+      ],
+      exitReason: "score_threshold",
+      phase: "research:compile",
+    }),
+  );
+
+  planIngest.mockImplementation(async () => ({
+    ingestPlan: {
+      action: "merge",
+      reason: "Same topic",
+      targetPageId: "page-1",
+    },
+    phase: "ingest:planned",
+  }));
+}
+
+describe("ingestPlannerGraph — research subgraph connection", () => {
+  beforeEach(() => {
+    __resetRegistryForTests();
+    registerIngestPlannerGraph();
+    prepareIngest.mockReset();
+    planIngest.mockReset();
+    planQueries.mockReset();
+    webSearch.mockReset();
+    wikiSearch.mockReset();
+    fetchArticles.mockReset();
+    evaluateSufficiency.mockReset();
+    refineQueries.mockReset();
+    compileBatch.mockReset();
+    defaultMocks();
+  });
+
+  afterEach(() => {
+    __resetRegistryForTests();
+  });
+
+  it("runs prepare_ingest then research nodes before halting at human_review_research", async () => {
+    const runner = new GraphRunner();
+    const result = await runner.invoke(
+      {
+        graphId: INGEST_PLANNER_GRAPH_ID,
+        context: fakeContext("thread-ingest-1"),
+        checkpointer: new MemorySaver(),
+        recursionLimit: 60,
+      },
+      {
+        kind: "input",
+        value: { article: articleInput, candidates: candidatesInput },
+      },
+    );
+
+    expect(result.status).toBe("interrupted");
+    expect(prepareIngest).toHaveBeenCalledTimes(1);
+    expect(planQueries).toHaveBeenCalledTimes(1);
+    expect(compileBatch).toHaveBeenCalledTimes(1);
+    expect(planIngest).not.toHaveBeenCalled();
+  });
+
+  it("reaches plan_ingest after research HITL resume", async () => {
+    const checkpointer = new MemorySaver();
+    const runner = new GraphRunner();
+    const ctx = fakeContext("thread-ingest-2");
+
+    await runner.invoke(
+      {
+        graphId: INGEST_PLANNER_GRAPH_ID,
+        context: ctx,
+        checkpointer,
+        recursionLimit: 60,
+      },
+      { kind: "input", value: { article: articleInput, candidates: candidatesInput } },
+    );
+
+    const resumed = await runner.resume(
+      {
+        graphId: INGEST_PLANNER_GRAPH_ID,
+        context: ctx,
+        checkpointer,
+        recursionLimit: 60,
+      },
+      { approvedSourceIds: ["src:1"] },
+    );
+
+    expect(resumed.status).toBe("completed");
+    expect(planIngest).toHaveBeenCalledTimes(1);
+    const output = resumed.output as { ingestPlan?: { action?: string } };
+    expect(output.ingestPlan?.action).toBe("merge");
+  });
+});
diff --git a/server/api/src/__tests__/agents/graphs/ingest/planIngestModel.test.ts b/server/api/src/__tests__/agents/graphs/ingest/planIngestModel.test.ts
new file mode 100644
index 00000000..d41c4c61
--- /dev/null
+++ b/server/api/src/__tests__/agents/graphs/ingest/planIngestModel.test.ts
@@ -0,0 +1,99 @@
+/**
+ * `plan_ingest` must resolve models through BYOK-aware `resolveComposeModelId`.
+ */
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+
+const mockResolveComposeModelId = vi.fn();
+const mockCreateZediChatModel = vi.fn();
+
+vi.mock("../../../../agents/core/llm/resolveComposeModelId.js", () => ({
+  resolveComposeModelId: (...args: unknown[]) => mockResolveComposeModelId(...args),
+}));
+
+vi.mock("../../../../agents/core/llm/modelFactory.js", () => ({
+  createZediChatModel: (...args: unknown[]) => mockCreateZediChatModel(...args),
+}));
+
+vi.mock("../../../../services/ingestPlanner.js", () => ({
+  buildIngestPlannerPrompt: () => [{ role: "user" as const, content: "plan me" }],
+  parseIngestPlanValue: () => ({
+    action: "skip" as const,
+    reason: "test",
+  }),
+}));
+
+import { planIngest } from "../../../../agents/graphs/ingest/nodes/planIngest.js";
+import { GRAPH_CONTEXT_CONFIG_KEY } from "../../../../agents/core/types/graphContext.js";
+import type { GraphContext } from "../../../../agents/core/types/graphContext.js";
+import type { Database } from "../../../../types/index.js";
+
+describe("planIngest model resolution", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockResolveComposeModelId.mockResolvedValue("openai:gpt-4o-mini");
+    mockCreateZediChatModel.mockResolvedValue({
+      withStructuredOutput: () => ({
+        invoke: async () => ({
+          action: "skip",
+          reason: "ok",
+        }),
+      }),
+    });
+  });
+
+  it("uses resolveComposeModelId for user_openai backend", async () => {
+    const ctx: GraphContext = {
+      threadId: "t1",
+      sessionId: "t1",
+      userId: "user-1",
+      userEmail: null,
+      pageId: "",
+      graphId: "ingest-planner",
+      backend: "user_openai",
+      tier: "free",
+      db: {} as Database,
+      feature: "ingest_graph:test",
+    };
+    const config = {
+      configurable: { [GRAPH_CONTEXT_CONFIG_KEY]: ctx },
+    } as LangGraphRunnableConfig;
+
+    await planIngest(
+      {
+        article: { title: "T", url: "https://example.com", excerpt: "e" },
+        candidates: [],
+        approvedResearch: [],
+        rejectedResearch: [],
+        pendingSources: [],
+        batches: [],
+        phase: "ingest:prepare",
+        pageId: "",
+        userId: "user-1",
+        userSchema: null,
+        maxIterations: 3,
+        iteration: 0,
+        queries: [],
+        lastEvaluation: null,
+        exitReason: null,
+        additionalRequest: null,
+        ingestPlan: null,
+        messages: [],
+      },
+      config,
+    );
+
+    expect(mockResolveComposeModelId).toHaveBeenCalledWith(
+      "orchestrator",
+      "user_openai",
+      "free",
+      ctx.db,
+    );
+    expect(mockCreateZediChatModel).toHaveBeenCalledWith(
+      expect.objectContaining({
+        modelId: "openai:gpt-4o-mini",
+        backend: "user_openai",
+      }),
+    );
+  });
+});
diff --git a/server/api/src/__tests__/agents/graphs/wikiCompose/wikiComposeGraph.test.ts b/server/api/src/__tests__/agents/graphs/wikiCompose/wikiComposeGraph.test.ts
new file mode 100644
index 00000000..a242cbaa
--- /dev/null
+++ b/server/api/src/__tests__/agents/graphs/wikiCompose/wikiComposeGraph.test.ts
@@ -0,0 +1,360 @@
+/**
+ * Wiki Compose orchestrator graph (#950, #953) — wiring + interrupt tests.
+ *
+ * 受け入れ条件 #1 / #6 / 技術 #1:
+ * - `wikiComposeGraph` が P1 subgraph を組み込んでいる (channels 共有で表現)
+ * - Brief → research → outline → draft の happy path が動く
+ * - 各 interrupt 位置で halt し、resume で次フェーズに進む
+ *
+ * Mocks every LLM-backed node so the test pins the graph wiring rather than
+ * model quality. MemorySaver is used as a checkpointer so interrupts can
+ * resume on the same thread id.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const {
+  briefDialogue,
+  structureDialogue,
+  draftSections,
+  planQueries,
+  webSearch,
+  wikiSearch,
+  fetchArticles,
+  evaluateSufficiency,
+  refineQueries,
+  compileBatch,
+} = vi.hoisted(() => ({
+  briefDialogue: vi.fn(),
+  structureDialogue: vi.fn(),
+  draftSections: vi.fn(),
+  planQueries: vi.fn(),
+  webSearch: vi.fn(),
+  wikiSearch: vi.fn(),
+  fetchArticles: vi.fn(),
+  evaluateSufficiency: vi.fn(),
+  refineQueries: vi.fn(),
+  compileBatch: vi.fn(),
+}));
+
+// Real nodes preserved: humanReviewBrief, humanReviewOutline, completed,
+// humanReviewResearch (interrupts must be exercised, not mocked away).
+// Real interrupt/projection nodes are kept; only LLM-backed nodes are mocked.
+vi.mock("../../../../agents/graphs/wikiCompose/nodes/index.js", async () => {
+  const real = await vi.importActual<
+    typeof import("../../../../agents/graphs/wikiCompose/nodes/index.js")
+  >("../../../../agents/graphs/wikiCompose/nodes/index.js");
+  return {
+    ...real,
+    briefDialogue,
+    structureDialogue,
+    draftSections,
+  };
+});
+
+vi.mock("../../../../agents/subgraphs/research/nodes/index.js", async () => {
+  const real = await vi.importActual<
+    typeof import("../../../../agents/subgraphs/research/nodes/index.js")
+  >("../../../../agents/subgraphs/research/nodes/index.js");
+  return {
+    ...real,
+    planQueries,
+    webSearch,
+    wikiSearch,
+    fetchArticles,
+    evaluateSufficiency,
+    refineQueries,
+    compileBatch,
+  };
+});
+
+import { GraphRunner } from "../../../../agents/runner/graphRunner.js";
+import { __resetRegistryForTests } from "../../../../agents/registry/graphRegistry.js";
+import {
+  WIKI_COMPOSE_GRAPH_ID,
+  registerWikiComposeGraph,
+} from "../../../../agents/graphs/wikiCompose/index.js";
+import type { GraphContext } from "../../../../agents/core/types/graphContext.js";
+import type { Database } from "../../../../types/index.js";
+import { MemorySaver } from "@langchain/langgraph";
+
+function fakeContext(threadId: string): GraphContext {
+  return {
+    threadId,
+    sessionId: threadId,
+    userId: "user-1",
+    pageId: "page-1",
+    graphId: WIKI_COMPOSE_GRAPH_ID,
+    backend: "zedi_managed",
+    tier: "free",
+    db: {} as Database,
+    feature: "wiki_compose:test",
+    userEmail: null,
+  };
+}
+
+function defaultMocks() {
+  briefDialogue.mockImplementation(async () => ({
+    briefQuestions: [
+      {
+        id: "q-1",
+        question: "What scope?",
+        options: [
+          { id: "opt-a", label: "broad" },
+          { id: "opt-b", label: "narrow" },
+        ],
+        required: false,
+      },
+    ],
+    pageSnapshot: { pageId: "page-1", title: "Hello", body: "", hasContent: false },
+    phase: "brief:await_user",
+  }));
+
+  planQueries.mockImplementation(async () => ({
+    queries: [{ id: "q1", query: "topic", channels: ["web"] }],
+    maxIterations: 3,
+    iteration: 0,
+    lastEvaluation: null,
+    exitReason: null,
+    phase: "research:plan",
+  }));
+  webSearch.mockImplementation(async () => ({
+    pendingSources: [{ id: "src:abc", kind: "web", title: "A", url: "https://a/" }],
+  }));
+  wikiSearch.mockImplementation(async () => ({ pendingSources: [] }));
+  fetchArticles.mockImplementation(async () => ({ pendingSources: [] }));
+  evaluateSufficiency.mockImplementation(async (state: { iteration: number }) => ({
+    lastEvaluation: { score: 0.9, rationale: "ok", missingAspects: [] },
+    iteration: state.iteration + 1,
+    phase: "research:evaluated",
+  }));
+  compileBatch.mockImplementation(
+    async (state: {
+      iteration: number;
+      queries: unknown[];
+      pendingSources: unknown[];
+      lastEvaluation: unknown;
+    }) => ({
+      batches: [
+        {
+          id: "batch-1",
+          iteration: state.iteration,
+          queries: state.queries,
+          sources: state.pendingSources,
+          evaluation: state.lastEvaluation,
+          createdAt: "2026-01-01T00:00:00.000Z",
+        },
+      ],
+      exitReason: "score_threshold",
+      phase: "research:compile",
+    }),
+  );
+
+  structureDialogue.mockImplementation(async () => ({
+    outlineProposal: [
+      { id: "sec-1", heading: "Overview", depth: 1, intent: "intro" },
+      { id: "sec-2", heading: "Details", depth: 1, intent: "deep dive" },
+    ],
+    phase: "structure:await_user",
+  }));
+
+  draftSections.mockImplementation(async () => ({
+    draftedSections: [
+      {
+        sectionId: "sec-1",
+        heading: "Overview",
+        body: "Body 1 [#1]",
+        citedSourceIds: ["src:abc"],
+        completedAt: "2026-01-01T00:00:01.000Z",
+      },
+      {
+        sectionId: "sec-2",
+        heading: "Details",
+        body: "Body 2",
+        citedSourceIds: [],
+        completedAt: "2026-01-01T00:00:02.000Z",
+      },
+    ],
+    phase: "draft:completed",
+  }));
+}
+
+describe("wikiComposeGraph — orchestrator wiring", () => {
+  beforeEach(() => {
+    __resetRegistryForTests();
+    registerWikiComposeGraph();
+    briefDialogue.mockReset();
+    structureDialogue.mockReset();
+    draftSections.mockReset();
+    planQueries.mockReset();
+    webSearch.mockReset();
+    wikiSearch.mockReset();
+    fetchArticles.mockReset();
+    evaluateSufficiency.mockReset();
+    refineQueries.mockReset();
+    compileBatch.mockReset();
+    defaultMocks();
+  });
+  afterEach(() => {
+    __resetRegistryForTests();
+  });
+
+  it("halts at the Brief interrupt on first run", async () => {
+    const runner = new GraphRunner();
+    const result = await runner.invoke(
+      {
+        graphId: WIKI_COMPOSE_GRAPH_ID,
+        context: fakeContext("thread-brief"),
+        checkpointer: new MemorySaver(),
+        recursionLimit: 120,
+      },
+      { kind: "input", value: { messages: [{ role: "user", content: "title: Hello" }] } },
+    );
+
+    expect(result.status).toBe("interrupted");
+    expect(briefDialogue).toHaveBeenCalledTimes(1);
+    // Should not have advanced past Brief before user resumes.
+    // Brief 確定前に research が走らないことを担保する。
+    expect(planQueries).not.toHaveBeenCalled();
+  });
+
+  it("advances to the research interrupt after Brief resume", async () => {
+    const checkpointer = new MemorySaver();
+    const runner = new GraphRunner();
+    const ctx = fakeContext("thread-research");
+
+    await runner.invoke(
+      { graphId: WIKI_COMPOSE_GRAPH_ID, context: ctx, checkpointer, recursionLimit: 120 },
+      { kind: "input", value: { messages: [{ role: "user", content: "title: Hello" }] } },
+    );
+
+    const resumed = await runner.resume(
+      { graphId: WIKI_COMPOSE_GRAPH_ID, context: ctx, checkpointer, recursionLimit: 120 },
+      { answers: [], appendToExisting: false },
+    );
+
+    expect(resumed.status).toBe("interrupted");
+    expect(planQueries).toHaveBeenCalledTimes(1);
+    expect(compileBatch).toHaveBeenCalledTimes(1);
+    // Structure has not started yet — outline must wait for research approval.
+    // research 承認前に structure_dialogue が呼ばれないことを担保。
+    expect(structureDialogue).not.toHaveBeenCalled();
+  });
+
+  it("reaches Draft after research and outline resumes", async () => {
+    const checkpointer = new MemorySaver();
+    const runner = new GraphRunner();
+    const ctx = fakeContext("thread-draft");
+
+    // 1. Initial run halts at human_review_brief.
+    await runner.invoke(
+      { graphId: WIKI_COMPOSE_GRAPH_ID, context: ctx, checkpointer, recursionLimit: 120 },
+      { kind: "input", value: { messages: [{ role: "user", content: "title: Hello" }] } },
+    );
+    // 2. Brief resume → halts at human_review_research.
+    await runner.resume(
+      { graphId: WIKI_COMPOSE_GRAPH_ID, context: ctx, checkpointer, recursionLimit: 120 },
+      { answers: [], appendToExisting: false },
+    );
+    // 3. Research resume → halts at human_review_outline.
+    const outlineHalt = await runner.resume(
+      { graphId: WIKI_COMPOSE_GRAPH_ID, context: ctx, checkpointer, recursionLimit: 120 },
+      { approvedSourceIds: ["src:abc"] },
+    );
+    expect(outlineHalt.status).toBe("interrupted");
+    expect(structureDialogue).toHaveBeenCalledTimes(1);
+    expect(draftSections).not.toHaveBeenCalled();
+
+    // 4. Outline resume → runs Draft → completed.
+    const finalRun = await runner.resume(
+      { graphId: WIKI_COMPOSE_GRAPH_ID, context: ctx, checkpointer, recursionLimit: 120 },
+      {
+        sections: [
+          { id: "sec-1", heading: "Overview", depth: 1, intent: "intro" },
+          { id: "sec-2", heading: "Details", depth: 1, intent: "deep dive" },
+        ],
+      },
+    );
+    expect(finalRun.status).toBe("completed");
+    expect(draftSections).toHaveBeenCalledTimes(1);
+
+    const finalState = finalRun.output as {
+      completion?: { markdown?: string; sections?: unknown[] };
+    };
+    expect(finalState.completion).toBeTruthy();
+    expect(finalState.completion?.sections).toHaveLength(2);
+    expect(finalState.completion?.markdown).toMatch(/Overview/);
+    expect(finalState.completion?.markdown).toMatch(/Details/);
+  });
+
+  it("skips research when Brief emits zero questions (P5)", async () => {
+    briefDialogue.mockImplementation(async () => ({
+      briefQuestions: [],
+      pageSnapshot: { pageId: "page-1", title: "Self-evident Title", body: "", hasContent: false },
+      phase: "brief:await_user",
+    }));
+
+    const checkpointer = new MemorySaver();
+    const runner = new GraphRunner();
+    const ctx = fakeContext("thread-skip-research");
+
+    await runner.invoke(
+      { graphId: WIKI_COMPOSE_GRAPH_ID, context: ctx, checkpointer, recursionLimit: 120 },
+      { kind: "input", value: { messages: [{ role: "user", content: "title: Obvious" }] } },
+    );
+
+    const afterBrief = await runner.resume(
+      { graphId: WIKI_COMPOSE_GRAPH_ID, context: ctx, checkpointer, recursionLimit: 120 },
+      { answers: [], appendToExisting: false },
+    );
+
+    expect(afterBrief.status).toBe("interrupted");
+    expect(planQueries).not.toHaveBeenCalled();
+    expect(compileBatch).not.toHaveBeenCalled();
+    expect(structureDialogue).toHaveBeenCalledTimes(1);
+  });
+
+  it("halts at conflict_resolution when many sources are rejected (P5)", async () => {
+    webSearch.mockImplementation(async () => ({
+      pendingSources: [
+        { id: "src:a", kind: "web", title: "A", url: "https://a/" },
+        { id: "src:b", kind: "web", title: "B", url: "https://b/" },
+        { id: "src:c", kind: "web", title: "C", url: "https://c/" },
+      ],
+    }));
+
+    const checkpointer = new MemorySaver();
+    const runner = new GraphRunner();
+    const ctx = fakeContext("thread-conflict");
+
+    await runner.invoke(
+      { graphId: WIKI_COMPOSE_GRAPH_ID, context: ctx, checkpointer, recursionLimit: 120 },
+      { kind: "input", value: { messages: [{ role: "user", content: "title: Hello" }] } },
+    );
+    await runner.resume(
+      { graphId: WIKI_COMPOSE_GRAPH_ID, context: ctx, checkpointer, recursionLimit: 120 },
+      { answers: [], appendToExisting: false },
+    );
+
+    const conflictHalt = await runner.resume(
+      { graphId: WIKI_COMPOSE_GRAPH_ID, context: ctx, checkpointer, recursionLimit: 120 },
+      {
+        approvedSourceIds: ["src:a"],
+        rejectedSourceIds: ["src:b", "src:c"],
+      },
+    );
+
+    expect(conflictHalt.status).toBe("interrupted");
+    const interruptState = conflictHalt.output as {
+      __interrupt__?: Array<{ value: { kind?: string } }>;
+    };
+    expect(interruptState.__interrupt__?.[0]?.value?.kind).toBe("conflict_resolution");
+    expect(structureDialogue).not.toHaveBeenCalled();
+
+    const afterConflict = await runner.resume(
+      { graphId: WIKI_COMPOSE_GRAPH_ID, context: ctx, checkpointer, recursionLimit: 120 },
+      { acknowledged: true },
+    );
+    expect(afterConflict.status).toBe("interrupted");
+    expect(structureDialogue).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/server/api/src/__tests__/agents/graphs/wikiCompose/wikiComposeRouting.test.ts b/server/api/src/__tests__/agents/graphs/wikiCompose/wikiComposeRouting.test.ts
new file mode 100644
index 00000000..139f5984
--- /dev/null
+++ b/server/api/src/__tests__/agents/graphs/wikiCompose/wikiComposeRouting.test.ts
@@ -0,0 +1,97 @@
+/**
+ * Wiki Compose P5 routing predicates (#953).
+ * Wiki Compose P5 ルーティング述語のテスト (#953)。
+ */
+import { describe, expect, it } from "vitest";
+import {
+  routeAfterBrief,
+  routeAfterResearch,
+  shouldResolveResearchConflicts,
+} from "../../../../agents/graphs/wikiCompose/routing.js";
+import type { WikiComposeStateType } from "../../../../agents/graphs/wikiCompose/state.js";
+
+function minimalState(overrides: Partial<WikiComposeStateType> = {}): WikiComposeStateType {
+  return {
+    messages: [],
+    phase: "init",
+    pageId: "page-1",
+    userId: "user-1",
+    chatSeed: null,
+    pageSnapshot: null,
+    briefQuestions: [],
+    brief: null,
+    briefDegraded: false,
+    iteration: 0,
+    maxIterations: 3,
+    queries: [],
+    pendingSources: [],
+    lastEvaluation: null,
+    exitReason: null,
+    batches: [],
+    approvedResearch: [],
+    rejectedResearch: [],
+    additionalRequest: null,
+    researchConflicts: [],
+    outlineProposal: [],
+    approvedOutline: null,
+    draftedSections: [],
+    completion: null,
+    ...overrides,
+  };
+}
+
+describe("routeAfterBrief", () => {
+  it("routes to skip_research when Brief emitted zero questions", () => {
+    expect(routeAfterBrief(minimalState({ briefQuestions: [] }))).toBe("skip_research");
+  });
+
+  it("routes to skip_research when chatSeed carries a pre-approved outline", () => {
+    expect(
+      routeAfterBrief(
+        minimalState({
+          briefQuestions: [{ id: "q1", question: "Scope?", options: [], required: false }],
+          chatSeed: { outline: "## Intro\n- point", conversationText: "hi" },
+        }),
+      ),
+    ).toBe("skip_research");
+  });
+
+  it("routes to research when Brief is empty due to LLM degradation flag", () => {
+    expect(routeAfterBrief(minimalState({ briefQuestions: [], briefDegraded: true }))).toBe(
+      "research",
+    );
+  });
+
+  it("routes to research when Brief has questions and no chat outline seed", () => {
+    expect(
+      routeAfterBrief(
+        minimalState({
+          briefQuestions: [{ id: "q1", question: "Audience?", options: [], required: true }],
+          chatSeed: null,
+        }),
+      ),
+    ).toBe("research");
+  });
+});
+
+describe("routeAfterResearch / shouldResolveResearchConflicts", () => {
+  it("detects conflict when ≥2 rejected and ≥1 approved", () => {
+    const state = minimalState({
+      approvedResearch: [{ id: "a", kind: "web", title: "A" }],
+      rejectedResearch: [
+        { id: "b", kind: "web", title: "B" },
+        { id: "c", kind: "web", title: "C" },
+      ],
+    });
+    expect(shouldResolveResearchConflicts(state)).toBe(true);
+    expect(routeAfterResearch(state)).toBe("conflict_resolution");
+  });
+
+  it("routes to structure when rejections are below threshold", () => {
+    const state = minimalState({
+      approvedResearch: [{ id: "a", kind: "web", title: "A" }],
+      rejectedResearch: [{ id: "b", kind: "web", title: "B" }],
+    });
+    expect(routeAfterResearch(state)).toBe("structure");
+  });
+});
diff --git a/server/api/src/__tests__/agents/graphs/wikiMaintenance/wikiMaintenanceGraph.test.ts b/server/api/src/__tests__/agents/graphs/wikiMaintenance/wikiMaintenanceGraph.test.ts
new file mode 100644
index 00000000..e51657c0
--- /dev/null
+++ b/server/api/src/__tests__/agents/graphs/wikiMaintenance/wikiMaintenanceGraph.test.ts
@@ -0,0 +1,101 @@
+/**
+ * Wiki maintenance graph (#953) — wiring + scan node tests.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { scanBrokenLinks, scanStubPages } = vi.hoisted(() => ({
+  scanBrokenLinks: vi.fn(),
+  scanStubPages: vi.fn(),
+}));
+
+vi.mock("../../../../agents/graphs/wikiMaintenance/nodes/index.js", async () => {
+  const real = await vi.importActual<
+    typeof import("../../../../agents/graphs/wikiMaintenance/nodes/index.js")
+  >("../../../../agents/graphs/wikiMaintenance/nodes/index.js");
+  return { ...real, scanBrokenLinks, scanStubPages };
+});
+
+import { GraphRunner } from "../../../../agents/runner/graphRunner.js";
+import { __resetRegistryForTests } from "../../../../agents/registry/graphRegistry.js";
+import {
+  WIKI_MAINTENANCE_GRAPH_ID,
+  registerWikiMaintenanceGraph,
+} from "../../../../agents/graphs/wikiMaintenance/index.js";
+import type { GraphContext } from "../../../../agents/core/types/graphContext.js";
+import type { Database } from "../../../../types/index.js";
+
+function fakeContext(threadId: string): GraphContext {
+  return {
+    threadId,
+    sessionId: threadId,
+    userId: "user-1",
+    pageId: "page-1",
+    graphId: WIKI_MAINTENANCE_GRAPH_ID,
+    backend: "zedi_managed",
+    tier: "free",
+    db: {} as Database,
+    feature: "wiki_maintenance:test",
+    userEmail: null,
+  };
+}
+
+describe("wikiMaintenanceGraph", () => {
+  beforeEach(() => {
+    __resetRegistryForTests();
+    registerWikiMaintenanceGraph();
+    scanBrokenLinks.mockReset();
+    scanStubPages.mockReset();
+    scanBrokenLinks.mockImplementation(async () => ({
+      brokenLinkFindings: [
+        {
+          rule: "broken_link",
+          severity: "error",
+          pageIds: ["p1", "p2"],
+          detail: { sourceId: "p1" },
+        },
+      ],
+      phase: "maintenance:broken_links_scanned",
+    }));
+    scanStubPages.mockImplementation(async () => ({
+      stubPageFindings: [
+        {
+          rule: "stub_page",
+          severity: "info",
+          pageIds: ["p3"],
+          detail: { title: "Draft" },
+        },
+      ],
+      phase: "maintenance:stub_pages_scanned",
+    }));
+  });
+
+  afterEach(() => {
+    __resetRegistryForTests();
+  });
+
+  it("runs scan → plan and completes with a maintenance plan", async () => {
+    const runner = new GraphRunner();
+    const result = await runner.invoke(
+      {
+        graphId: WIKI_MAINTENANCE_GRAPH_ID,
+        context: fakeContext("maint-1"),
+        checkpointer: false,
+        recursionLimit: 20,
+      },
+      { kind: "input", value: {} },
+    );
+
+    expect(result.status).toBe("completed");
+    expect(scanBrokenLinks).toHaveBeenCalledTimes(1);
+    expect(scanStubPages).toHaveBeenCalledTimes(1);
+
+    const out = result.output as {
+      maintenancePlan?: { brokenLinkCount: number; stubPageCount: number; findings: unknown[] };
+      phase?: string;
+    };
+    expect(out.phase).toBe("maintenance:planned");
+    expect(out.maintenancePlan?.brokenLinkCount).toBe(1);
+    expect(out.maintenancePlan?.stubPageCount).toBe(1);
+    expect(out.maintenancePlan?.findings).toHaveLength(2);
+  });
+});
diff --git a/server/api/src/__tests__/agents/runner/graphRunner.test.ts b/server/api/src/__tests__/agents/runner/graphRunner.test.ts
new file mode 100644
index 00000000..3538248a
--- /dev/null
+++ b/server/api/src/__tests__/agents/runner/graphRunner.test.ts
@@ -0,0 +1,181 @@
+/**
+ * GraphRunner のテスト。registry にスタブ graph を登録した状態で invoke /
+ * streamEvents が registry を介して動くことを確認する。実 LangGraph を起動して
+ * `END` ノードまで走らせるため、ここではモック graph ではなく `stubGraph` を使う。
+ *
+ * Tests for {@link GraphRunner}: registry resolution, invoke happy path,
+ * streamEvents iteration, and resume payload shape. Uses the real
+ * `wiki-compose-stub` graph (no external IO) instead of a hand-rolled mock so
+ * the test stays close to production runtime behaviour.
+ */
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { GraphRunner } from "../../../agents/runner/graphRunner.js";
+import {
+  GraphNotRegisteredError,
+  __resetRegistryForTests,
+  registerGraph,
+} from "../../../agents/registry/graphRegistry.js";
+import { STUB_GRAPH_ID, registerStubGraph } from "../../../agents/registry/stubGraph.js";
+import type { GraphContext } from "../../../agents/core/types/graphContext.js";
+import type { Database } from "../../../types/index.js";
+
+function fakeContext(): GraphContext {
+  return {
+    threadId: "thread-1",
+    sessionId: "thread-1",
+    userId: "user-1",
+    pageId: "page-1",
+    graphId: STUB_GRAPH_ID,
+    backend: "zedi_managed",
+    tier: "free",
+    db: {} as Database,
+    feature: "test",
+    userEmail: null,
+  };
+}
+
+describe("GraphRunner.invoke", () => {
+  beforeEach(() => {
+    __resetRegistryForTests();
+    registerStubGraph();
+  });
+  afterEach(() => {
+    __resetRegistryForTests();
+  });
+
+  it("executes the stub graph end-to-end and marks the run completed", async () => {
+    const runner = new GraphRunner();
+    const result = await runner.invoke(
+      {
+        graphId: STUB_GRAPH_ID,
+        context: fakeContext(),
+        checkpointer: false,
+      },
+      { kind: "input", value: { messages: [] } },
+    );
+
+    expect(result.status).toBe("completed");
+    // The stub graph sets `phase` to "completed" in its single node.
+    // スタブグラフは noop ノードで phase を completed にする。
+    expect((result.output as { phase?: string })?.phase).toBe("completed");
+  });
+
+  it("throws GraphNotRegisteredError for an unknown graphId", async () => {
+    const runner = new GraphRunner();
+    await expect(
+      runner.invoke(
+        { graphId: "does-not-exist", context: fakeContext(), checkpointer: false },
+        { kind: "input", value: {} },
+      ),
+    ).rejects.toBeInstanceOf(GraphNotRegisteredError);
+  });
+
+  it("passes thread_id and the zedi graph context through configurable", async () => {
+    let capturedConfig: unknown;
+    registerGraph({
+      id: "spy-graph",
+      version: "0.0.0",
+      phase: "spy",
+      description: "captures the runnable config",
+      factory: () => ({
+        async invoke(_input: unknown, options: unknown) {
+          capturedConfig = options;
+          return { ok: true };
+        },
+        async stream() {
+          throw new Error("not used");
+        },
+        streamEvents() {
+          throw new Error("not used");
+        },
+      }),
+    });
+
+    const runner = new GraphRunner();
+    await runner.invoke(
+      { graphId: "spy-graph", context: fakeContext(), checkpointer: false },
+      { kind: "input", value: {} },
+    );
+
+    const cfg = capturedConfig as {
+      configurable: Record<string, unknown>;
+      recursionLimit: number;
+    };
+    expect(cfg.configurable.thread_id).toBe("thread-1");
+    expect(cfg.configurable.zediGraphContext).toMatchObject({
+      threadId: "thread-1",
+      userId: "user-1",
+      pageId: "page-1",
+    });
+    expect(cfg.recursionLimit).toBe(25);
+  });
+});
+
+describe("GraphRunner.streamEvents", () => {
+  beforeEach(() => {
+    __resetRegistryForTests();
+    registerStubGraph();
+  });
+  afterEach(() => {
+    __resetRegistryForTests();
+  });
+
+  it("returns an async iterable that emits at least one event", async () => {
+    const runner = new GraphRunner();
+    const events = runner.streamEvents(
+      { graphId: STUB_GRAPH_ID, context: fakeContext(), checkpointer: false },
+      { kind: "input", value: { messages: [] } },
+    );
+
+    const collected: unknown[] = [];
+    for await (const ev of events) {
+      collected.push(ev);
+    }
+    // The stub graph is small but always produces multiple lifecycle events
+    // (chain_start / chain_end at minimum). We only assert non-empty so the
+    // test is robust against LangGraph version changes.
+    // LangGraph のバージョン差を吸収するため、件数だけ確認する。
+    expect(collected.length).toBeGreaterThan(0);
+  });
+});
+
+describe("GraphRunner.resume", () => {
+  beforeEach(() => {
+    __resetRegistryForTests();
+  });
+  afterEach(() => {
+    __resetRegistryForTests();
+  });
+
+  it("invokes the graph with a Command({ resume }) payload", async () => {
+    let captured: unknown;
+    registerGraph({
+      id: "resume-spy",
+      version: "0.0.0",
+      phase: "spy",
+      description: "captures resume payloads",
+      factory: () => ({
+        async invoke(input: unknown) {
+          captured = input;
+          return {};
+        },
+        async stream() {
+          throw new Error("not used");
+        },
+        streamEvents() {
+          throw new Error("not used");
+        },
+      }),
+    });
+
+    const runner = new GraphRunner();
+    await runner.resume(
+      { graphId: "resume-spy", context: fakeContext(), checkpointer: false },
+      { answer: "yes" },
+    );
+
+    expect(captured).toBeDefined();
+    // LangGraph `Command` carries a `resume` field that holds the user payload.
+    expect((captured as { resume?: unknown }).resume).toEqual({ answer: "yes" });
+  });
+});
diff --git a/server/api/src/__tests__/agents/runner/sseMapper.test.ts b/server/api/src/__tests__/agents/runner/sseMapper.test.ts
new file mode 100644
index 00000000..942da2e8
--- /dev/null
+++ b/server/api/src/__tests__/agents/runner/sseMapper.test.ts
@@ -0,0 +1,185 @@
+/**
+ * sseMapper のテスト。LangGraph 風イベントから `SseEvent` への変換を確認する。
+ *
+ * Pure-function tests for {@link mapLangGraphEvent} and the small builder
+ * helpers. The mapper is the sole place that translates LangGraph's runtime
+ * event shape into wire SSE; pinning it here keeps the wire contract stable.
+ */
+import { describe, expect, it } from "vitest";
+import {
+  doneEvent,
+  errorEvent,
+  mapLangGraphEvent,
+  startedEvent,
+  statusEvent,
+  usageEvent,
+  type LangGraphRuntimeEvent,
+} from "../../../agents/runner/sseMapper.js";
+
+describe("startedEvent / statusEvent / usageEvent / doneEvent / errorEvent", () => {
+  it("startedEvent omits phase when not provided", () => {
+    expect(startedEvent("s1", "g1")).toEqual({
+      type: "started",
+      sessionId: "s1",
+      graphId: "g1",
+    });
+  });
+
+  it("startedEvent includes phase when provided", () => {
+    expect(startedEvent("s1", "g1", "init")).toEqual({
+      type: "started",
+      sessionId: "s1",
+      graphId: "g1",
+      phase: "init",
+    });
+  });
+
+  it("statusEvent passes through message", () => {
+    expect(statusEvent("draft", "writing")).toEqual({
+      type: "status",
+      phase: "draft",
+      message: "writing",
+    });
+  });
+
+  it("usageEvent forwards all numeric fields", () => {
+    expect(usageEvent({ inputTokens: 1, outputTokens: 2, costUnits: 3, usagePercent: 4 })).toEqual({
+      type: "usage",
+      inputTokens: 1,
+      outputTokens: 2,
+      costUnits: 3,
+      usagePercent: 4,
+    });
+  });
+
+  it("doneEvent forwards status", () => {
+    expect(doneEvent("interrupted")).toEqual({ type: "done", status: "interrupted" });
+  });
+
+  it("errorEvent forwards retryable flag", () => {
+    expect(errorEvent("boom", true)).toEqual({
+      type: "error",
+      message: "boom",
+      retryable: true,
+    });
+  });
+});
+
+describe("mapLangGraphEvent", () => {
+  it("maps on_chat_model_stream to a token event with node name", () => {
+    const ev: LangGraphRuntimeEvent = {
+      event: "on_chat_model_stream",
+      data: { chunk: { content: "Hello" } },
+      metadata: { langgraph_node: "draft" },
+    };
+    expect(mapLangGraphEvent(ev)).toEqual([{ type: "token", node: "draft", content: "Hello" }]);
+  });
+
+  it("drops empty chat model stream chunks", () => {
+    const ev: LangGraphRuntimeEvent = {
+      event: "on_chat_model_stream",
+      data: { chunk: { content: "" } },
+    };
+    expect(mapLangGraphEvent(ev)).toEqual([]);
+  });
+
+  it("maps on_tool_start to a tool_start event", () => {
+    const ev: LangGraphRuntimeEvent = {
+      event: "on_tool_start",
+      name: "web_search",
+      data: { input: { query: "ripgrep" } },
+    };
+    expect(mapLangGraphEvent(ev)).toEqual([
+      { type: "tool_start", tool: "web_search", input: { query: "ripgrep" } },
+    ]);
+  });
+
+  it("maps on_tool_end with output length", () => {
+    const ev: LangGraphRuntimeEvent = {
+      event: "on_tool_end",
+      name: "web_search",
+      data: { output: "result text" },
+    };
+    expect(mapLangGraphEvent(ev)).toEqual([
+      { type: "tool_end", tool: "web_search", outputLength: "result text".length },
+    ]);
+  });
+
+  it("maps on_tool_end with error string", () => {
+    const ev: LangGraphRuntimeEvent = {
+      event: "on_tool_end",
+      name: "fetch_article",
+      data: { error: "blocked" },
+    };
+    expect(mapLangGraphEvent(ev)).toEqual([
+      { type: "tool_end", tool: "fetch_article", error: "blocked" },
+    ]);
+  });
+
+  it("maps on_chain_end with phase to a status event", () => {
+    const ev: LangGraphRuntimeEvent = {
+      event: "on_chain_end",
+      data: { output: { phase: "completed" } },
+    };
+    expect(mapLangGraphEvent(ev)).toEqual([{ type: "status", phase: "completed" }]);
+  });
+
+  it("returns an empty array for unrecognised events", () => {
+    expect(mapLangGraphEvent({ event: "on_unknown_event" })).toEqual([]);
+  });
+
+  it("maps on_custom_event compose_phase to a typed compose_phase event", () => {
+    const ev: LangGraphRuntimeEvent = {
+      event: "on_custom_event",
+      name: "compose_phase",
+      data: { phase: "structure", status: "entered" },
+    };
+    expect(mapLangGraphEvent(ev)).toEqual([
+      { type: "compose_phase", phase: "structure", status: "entered" },
+    ]);
+  });
+
+  it("maps on_custom_event compose_phase conflict to a typed compose_phase event", () => {
+    const ev: LangGraphRuntimeEvent = {
+      event: "on_custom_event",
+      name: "compose_phase",
+      data: { phase: "conflict", status: "entered" },
+    };
+    expect(mapLangGraphEvent(ev)).toEqual([
+      { type: "compose_phase", phase: "conflict", status: "entered" },
+    ]);
+  });
+
+  it("drops compose_phase with an unknown phase value", () => {
+    const ev: LangGraphRuntimeEvent = {
+      event: "on_custom_event",
+      name: "compose_phase",
+      data: { phase: "bogus", status: "entered" },
+    };
+    expect(mapLangGraphEvent(ev)).toEqual([]);
+  });
+
+  it("maps on_custom_event compose_section to a typed compose_section event", () => {
+    const ev: LangGraphRuntimeEvent = {
+      event: "on_custom_event",
+      name: "compose_section",
+      data: {
+        sectionId: "sec-1",
+        heading: "Overview",
+        status: "started",
+        index: 1,
+        total: 3,
+      },
+    };
+    expect(mapLangGraphEvent(ev)).toEqual([
+      {
+        type: "compose_section",
+        sectionId: "sec-1",
+        heading: "Overview",
+        status: "started",
+        index: 1,
+        total: 3,
+      },
+    ]);
+  });
+});
diff --git a/server/api/src/__tests__/agents/subgraphs/research/nodes/compileBatch.test.ts b/server/api/src/__tests__/agents/subgraphs/research/nodes/compileBatch.test.ts
new file mode 100644
index 00000000..005c3cb9
--- /dev/null
+++ b/server/api/src/__tests__/agents/subgraphs/research/nodes/compileBatch.test.ts
@@ -0,0 +1,86 @@
+/**
+ * `compileBatch` unit tests. Pure projection node; no LLM. We verify:
+ * - `exitReason` = "score_threshold" when score >= 0.75.
+ * - `exitReason` = "max_iterations" otherwise.
+ * - Batch fields are populated from state.
+ * - `dispatchCustomEvent` is called via the runnable config.
+ */
+import { describe, expect, it, vi } from "vitest";
+
+// The dispatch helper requires a proper LangChain callback manager which we
+// don't set up here (`compileBatch` is a pure projection). Stub it so the
+// node can dispatch into a no-op without a real callback runtime.
+// dispatch ヘルパは callback manager 必須なので test では no-op に差し替える。
+const { dispatchResearchBatch } = vi.hoisted(() => ({
+  dispatchResearchBatch: vi.fn(async () => undefined),
+}));
+vi.mock("../../../../../agents/subgraphs/research/nodes/shared/dispatchSseCustom.js", () => ({
+  dispatchResearchBatch,
+  dispatchResearchEvaluation: vi.fn(),
+  dispatchResearchIteration: vi.fn(),
+}));
+
+import { compileBatch } from "../../../../../agents/subgraphs/research/nodes/compileBatch.js";
+import type { ResearchLoopStateType } from "../../../../../agents/subgraphs/research/state.js";
+import type { ResearchBatch } from "../../../../../agents/subgraphs/research/types.js";
+
+function state(overrides: Partial<ResearchLoopStateType>): ResearchLoopStateType {
+  return {
+    messages: [],
+    phase: "research:evaluated",
+    pageId: "page-1",
+    userId: "user-1",
+    iteration: 2,
+    maxIterations: 3,
+    queries: [{ id: "q1", query: "q", channels: ["web"] }],
+    pendingSources: [
+      { id: "src:a", kind: "web", title: "A", url: "https://a/" },
+      { id: "src:b", kind: "web", title: "B", url: "https://b/" },
+    ],
+    lastEvaluation: null,
+    exitReason: null,
+    batches: [],
+    approvedResearch: [],
+    rejectedResearch: [],
+    additionalRequest: null,
+    ...overrides,
+  };
+}
+
+describe("compileBatch", () => {
+  it("uses score_threshold when last score >= 0.75", async () => {
+    const dispatcher = vi.fn();
+    const config = {
+      configurable: { callbacks: undefined },
+      callbacks: { handlers: [], inheritableHandlers: [], dispatchCustomEvent: dispatcher },
+    };
+    const update = await compileBatch(
+      state({ lastEvaluation: { score: 0.85, rationale: "ok", missingAspects: [] } }),
+      // Loose config type — node only reads callback runtime, which LangGraph
+      // wires through the surrounding `streamEvents` / `invoke` call.
+      config as never,
+    );
+    expect(update.exitReason).toBe("score_threshold");
+    const batches = update.batches as ResearchBatch[] | undefined;
+    expect(batches?.length).toBe(1);
+    expect(batches?.[0]?.sources.length).toBe(2);
+    expect(batches?.[0]?.iteration).toBe(2);
+  });
+
+  it("uses max_iterations when no eval or score below threshold", async () => {
+    const update = await compileBatch(
+      state({ lastEvaluation: { score: 0.5, rationale: "weak", missingAspects: ["x"] } }),
+      { configurable: {} } as never,
+    );
+    expect(update.exitReason).toBe("max_iterations");
+  });
+
+  it("handles null evaluation gracefully", async () => {
+    const update = await compileBatch(state({ lastEvaluation: null }), {
+      configurable: {},
+    } as never);
+    expect(update.exitReason).toBe("max_iterations");
+    const batches = update.batches as ResearchBatch[] | undefined;
+    expect(batches?.[0]?.evaluation).toBeNull();
+  });
+});
diff --git a/server/api/src/__tests__/agents/subgraphs/research/nodes/planQueries.test.ts b/server/api/src/__tests__/agents/subgraphs/research/nodes/planQueries.test.ts
new file mode 100644
index 00000000..17b89978
--- /dev/null
+++ b/server/api/src/__tests__/agents/subgraphs/research/nodes/planQueries.test.ts
@@ -0,0 +1,120 @@
+/**
+ * `planQueries` unit tests. Focus on the additional-research detection branch
+ * (codex review #956 P1): the node MUST read from `state.additionalRequest`
+ * (not `state.messages[0]`) so the documented `body.input.kind` translation
+ * by the route layer survives.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { createZediChatModel } = vi.hoisted(() => ({ createZediChatModel: vi.fn() }));
+
+vi.mock("../../../../../agents/core/llm/modelFactory.js", async () => {
+  const actual = await vi.importActual<
+    typeof import("../../../../../agents/core/llm/modelFactory.js")
+  >("../../../../../agents/core/llm/modelFactory.js");
+  return {
+    ...actual,
+    createZediChatModel: (...args: unknown[]) =>
+      createZediChatModel(...(args as Parameters<typeof actual.createZediChatModel>)),
+  };
+});
+
+// Stub dispatch helpers so the node can run without a real callback manager.
+vi.mock("../../../../../agents/subgraphs/research/nodes/shared/dispatchSseCustom.js", () => ({
+  dispatchResearchIteration: vi.fn(async () => undefined),
+  dispatchResearchEvaluation: vi.fn(async () => undefined),
+  dispatchResearchBatch: vi.fn(async () => undefined),
+}));
+
+import { planQueries } from "../../../../../agents/subgraphs/research/nodes/planQueries.js";
+import { GRAPH_CONTEXT_CONFIG_KEY } from "../../../../../agents/core/types/graphContext.js";
+import type { GraphContext } from "../../../../../agents/core/types/graphContext.js";
+import type { Database } from "../../../../../types/index.js";
+import type { ResearchLoopStateType } from "../../../../../agents/subgraphs/research/state.js";
+
+function fakeContext(): GraphContext {
+  return {
+    threadId: "t",
+    sessionId: "t",
+    userId: "u-1",
+    pageId: "p-1",
+    graphId: "wiki-compose-research",
+    backend: "zedi_managed",
+    tier: "free",
+    db: {} as Database,
+    feature: "wiki_compose:research",
+    userEmail: null,
+  };
+}
+
+function state(overrides: Partial<ResearchLoopStateType>): ResearchLoopStateType {
+  return {
+    messages: [],
+    phase: "init",
+    pageId: "p-1",
+    userId: "u-1",
+    iteration: 0,
+    maxIterations: 3,
+    queries: [],
+    pendingSources: [],
+    lastEvaluation: null,
+    exitReason: null,
+    batches: [],
+    approvedResearch: [],
+    rejectedResearch: [],
+    additionalRequest: null,
+    ...overrides,
+  };
+}
+
+function fakeModel(structuredReturn: () => Promise<unknown>) {
+  const runnable = { invoke: vi.fn(async () => structuredReturn()) };
+  return { withStructuredOutput: vi.fn(() => runnable) };
+}
+
+beforeEach(() => {
+  createZediChatModel.mockReset();
+  createZediChatModel.mockResolvedValue(
+    fakeModel(async () => ({
+      queries: [{ query: "q1", channels: ["web"] }],
+    })),
+  );
+});
+afterEach(() => {
+  createZediChatModel.mockReset();
+});
+
+describe("planQueries — additional research detection", () => {
+  const config = { configurable: { [GRAPH_CONTEXT_CONFIG_KEY]: fakeContext() } };
+
+  it("clamps maxIterations to 1..5 (default 3)", async () => {
+    const update = await planQueries(state({ maxIterations: 99 }), config as never);
+    expect(update.maxIterations).toBe(5);
+  });
+
+  it("consumes state.additionalRequest and seeds carried-over sources", async () => {
+    const update = await planQueries(
+      state({
+        additionalRequest: {
+          instruction: "go deeper on benchmarks",
+          carryOverApprovedIds: ["src:abc", "wiki:p-7"],
+        },
+      }),
+      config as never,
+    );
+    // additionalRequest is cleared after first read so a defensive re-plan
+    // does not loop on the same instruction.
+    expect(update.additionalRequest).toBeNull();
+    // pendingSources seeded from carryOverApprovedIds (id-prefix → kind).
+    expect(update.pendingSources).toEqual([
+      expect.objectContaining({ id: "src:abc", kind: "fetched" }),
+      expect.objectContaining({ id: "wiki:p-7", kind: "wiki" }),
+    ]);
+  });
+
+  it("does NOT reset pendingSources when there is no additionalRequest", async () => {
+    const update = await planQueries(state({ additionalRequest: null }), config as never);
+    // Standard initial run leaves pendingSources untouched.
+    expect(update.pendingSources).toBeUndefined();
+  });
+});
diff --git a/server/api/src/__tests__/agents/subgraphs/research/researchGraph.conditional.test.ts b/server/api/src/__tests__/agents/subgraphs/research/researchGraph.conditional.test.ts
new file mode 100644
index 00000000..ac8fa778
--- /dev/null
+++ b/server/api/src/__tests__/agents/subgraphs/research/researchGraph.conditional.test.ts
@@ -0,0 +1,93 @@
+/**
+ * `shouldRefine` 純粋関数の table-driven テスト。issue #949 受け入れ条件 #2:
+ * 「conditional edge (refine vs compile) の単体テストがある」。
+ *
+ * Table-driven tests for `shouldRefine` — the conditional edge predicate after
+ * `evaluate_sufficiency`. We avoid spinning up a `StateGraph` here because the
+ * predicate is pure; the wiring is exercised by the loop / interrupt tests.
+ */
+import { describe, expect, it } from "vitest";
+import { shouldRefine } from "../../../../agents/subgraphs/research/researchGraph.js";
+import type { ResearchLoopStateType } from "../../../../agents/subgraphs/research/state.js";
+
+function state(overrides: Partial<ResearchLoopStateType>): ResearchLoopStateType {
+  return {
+    messages: [],
+    phase: "research:evaluated",
+    pageId: "page-1",
+    userId: "user-1",
+    iteration: 1,
+    maxIterations: 3,
+    queries: [],
+    pendingSources: [],
+    lastEvaluation: null,
+    exitReason: null,
+    batches: [],
+    approvedResearch: [],
+    rejectedResearch: [],
+    additionalRequest: null,
+    ...overrides,
+  };
+}
+
+describe("shouldRefine", () => {
+  it("compiles when score >= 0.75 even if iterations remain", () => {
+    expect(
+      shouldRefine(
+        state({
+          iteration: 1,
+          maxIterations: 5,
+          lastEvaluation: { score: 0.75, rationale: "ok", missingAspects: [] },
+        }),
+      ),
+    ).toBe("compile");
+  });
+
+  it("compiles when score is high above the threshold", () => {
+    expect(
+      shouldRefine(
+        state({
+          iteration: 1,
+          maxIterations: 5,
+          lastEvaluation: { score: 0.95, rationale: "great", missingAspects: [] },
+        }),
+      ),
+    ).toBe("compile");
+  });
+
+  it("refines when score is below threshold and iterations remain", () => {
+    expect(
+      shouldRefine(
+        state({
+          iteration: 1,
+          maxIterations: 3,
+          lastEvaluation: { score: 0.5, rationale: "weak", missingAspects: ["x"] },
+        }),
+      ),
+    ).toBe("refine");
+  });
+
+  it("compiles at the hard iteration cap even if score is low", () => {
+    expect(
+      shouldRefine(
+        state({
+          iteration: 3,
+          maxIterations: 3,
+          lastEvaluation: { score: 0.4, rationale: "weak", missingAspects: ["x", "y"] },
+        }),
+      ),
+    ).toBe("compile");
+  });
+
+  it("compiles past the cap (defence against off-by-one)", () => {
+    expect(shouldRefine(state({ iteration: 4, maxIterations: 3 }))).toBe("compile");
+  });
+
+  it("refines when there's no evaluation yet and iterations remain", () => {
+    // Defensive: if evaluate_sufficiency hasn't run, treat as "not enough yet".
+    // evaluation 未走の保険 — まだ充足してないとみなす。
+    expect(shouldRefine(state({ iteration: 0, maxIterations: 3, lastEvaluation: null }))).toBe(
+      "refine",
+    );
+  });
+});
diff --git a/server/api/src/__tests__/agents/subgraphs/research/researchGraph.interrupt.test.ts b/server/api/src/__tests__/agents/subgraphs/research/researchGraph.interrupt.test.ts
new file mode 100644
index 00000000..aadfb110
--- /dev/null
+++ b/server/api/src/__tests__/agents/subgraphs/research/researchGraph.interrupt.test.ts
@@ -0,0 +1,144 @@
+/**
+ * issue #949 受け入れ条件 #3:
+ * 「ループ終了後 interrupt 位置で graph が停止する」。
+ *
+ * Verifies that `wiki-compose-research` halts at `human_review_research` with
+ * a structurally-correct payload after the loop exits (single iteration when
+ * evaluation crosses the threshold).
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const {
+  planQueries,
+  webSearch,
+  wikiSearch,
+  fetchArticles,
+  evaluateSufficiency,
+  refineQueries,
+  compileBatch,
+} = vi.hoisted(() => ({
+  planQueries: vi.fn(),
+  webSearch: vi.fn(),
+  wikiSearch: vi.fn(),
+  fetchArticles: vi.fn(),
+  evaluateSufficiency: vi.fn(),
+  refineQueries: vi.fn(),
+  compileBatch: vi.fn(),
+}));
+
+// The real `human_review_research` calls `interrupt()` which we want to
+// exercise; everything else is mocked to keep the test deterministic.
+vi.mock("../../../../agents/subgraphs/research/nodes/index.js", async () => {
+  const real = await vi.importActual<
+    typeof import("../../../../agents/subgraphs/research/nodes/index.js")
+  >("../../../../agents/subgraphs/research/nodes/index.js");
+  return {
+    ...real,
+    planQueries,
+    webSearch,
+    wikiSearch,
+    fetchArticles,
+    evaluateSufficiency,
+    refineQueries,
+    compileBatch,
+  };
+});
+
+import { GraphRunner } from "../../../../agents/runner/graphRunner.js";
+import { __resetRegistryForTests } from "../../../../agents/registry/graphRegistry.js";
+import {
+  RESEARCH_GRAPH_ID,
+  registerResearchLoopGraph,
+} from "../../../../agents/subgraphs/research/index.js";
+import type { GraphContext } from "../../../../agents/core/types/graphContext.js";
+import type { Database } from "../../../../types/index.js";
+import { MemorySaver } from "@langchain/langgraph";
+
+function fakeContext(): GraphContext {
+  return {
+    threadId: "thread-interrupt",
+    sessionId: "thread-interrupt",
+    userId: "user-1",
+    pageId: "page-1",
+    graphId: RESEARCH_GRAPH_ID,
+    backend: "zedi_managed",
+    tier: "free",
+    db: {} as Database,
+    feature: "wiki_compose:research",
+    userEmail: null,
+  };
+}
+
+describe("researchLoopSubgraph — interrupt at human_review_research", () => {
+  beforeEach(() => {
+    __resetRegistryForTests();
+    registerResearchLoopGraph();
+    planQueries.mockReset();
+    webSearch.mockReset();
+    wikiSearch.mockReset();
+    fetchArticles.mockReset();
+    evaluateSufficiency.mockReset();
+    refineQueries.mockReset();
+    compileBatch.mockReset();
+  });
+  afterEach(() => {
+    __resetRegistryForTests();
+  });
+
+  it("halts at human_review_research after a single-iteration loop", async () => {
+    planQueries.mockImplementation(async () => ({
+      queries: [{ id: "q1", query: "init", channels: ["web"] }],
+      maxIterations: 3,
+      iteration: 0,
+      lastEvaluation: null,
+      exitReason: null,
+      phase: "research:plan",
+    }));
+    webSearch.mockImplementation(async () => ({
+      pendingSources: [{ id: "src:abc", kind: "web", title: "A", url: "https://a/" }],
+    }));
+    wikiSearch.mockImplementation(async () => ({ pendingSources: [] }));
+    fetchArticles.mockImplementation(async () => ({ pendingSources: [] }));
+    evaluateSufficiency.mockImplementation(async (state, _c) => ({
+      lastEvaluation: { score: 0.9, rationale: "ok", missingAspects: [] },
+      iteration: state.iteration + 1,
+      phase: "research:evaluated",
+    }));
+    compileBatch.mockImplementation(async (state, _c) => ({
+      batches: [
+        {
+          id: "batch-1",
+          iteration: state.iteration,
+          queries: state.queries,
+          sources: state.pendingSources,
+          evaluation: state.lastEvaluation,
+          createdAt: "2026-01-01T00:00:00.000Z",
+        },
+      ],
+      exitReason: "score_threshold",
+      phase: "research:compile",
+    }));
+
+    const runner = new GraphRunner();
+    const result = await runner.invoke(
+      {
+        graphId: RESEARCH_GRAPH_ID,
+        context: fakeContext(),
+        // Interrupt resume requires a checkpointer; use MemorySaver for tests.
+        // interrupt の再開には checkpointer が必要。テストでは MemorySaver を使う。
+        checkpointer: new MemorySaver(),
+        recursionLimit: 60,
+      },
+      { kind: "input", value: { messages: [{ role: "user", content: "brief" }] } },
+    );
+
+    expect(result.status).toBe("interrupted");
+    // GraphRunner extracts the node name from the interrupt error if available;
+    // structural check is enough since LangGraph version churn can change the
+    // exact attribute name.
+    // interruptedAt はバージョン差で空になり得るので、最低限 status を担保する。
+    if (result.interruptedAt !== undefined) {
+      expect(result.interruptedAt).toMatch(/human_review_research|interrupt/i);
+    }
+  });
+});
diff --git a/server/api/src/__tests__/agents/subgraphs/research/researchGraph.loop.test.ts b/server/api/src/__tests__/agents/subgraphs/research/researchGraph.loop.test.ts
new file mode 100644
index 00000000..b2e1600c
--- /dev/null
+++ b/server/api/src/__tests__/agents/subgraphs/research/researchGraph.loop.test.ts
@@ -0,0 +1,241 @@
+/**
+ * issue #949 受け入れ条件 #1:
+ * 「subgraph が maxIterations まで自律ループする Vitest がある」。
+ *
+ * Tests that the compiled `wiki-compose-research` graph loops exactly
+ * `maxIterations` times when `evaluate_sufficiency` keeps returning a low
+ * score, and exits at `compile_batch` with `exitReason: "max_iterations"`.
+ *
+ * Strategy: mock the nodes barrel (`./nodes/index.js`) so each LLM-bound node
+ * is a deterministic `vi.fn()`. We invoke the real `registerResearchLoopGraph`
+ * factory through `GraphRunner` so edges + reducers + checkpointer integration
+ * are exercised end-to-end, but the network-touching bits are replaced.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// `vi.mock` is hoisted to the top of the module, so the captured `vi.fn()`
+// instances must be hoisted alongside it via `vi.hoisted()`. Otherwise the
+// factory closes over `undefined` variables.
+// vi.mock のホイストに合わせて、参照する vi.fn() も vi.hoisted で揚げる。
+const {
+  planQueries,
+  webSearch,
+  wikiSearch,
+  fetchArticles,
+  evaluateSufficiency,
+  refineQueries,
+  compileBatch,
+  humanReviewResearch,
+} = vi.hoisted(() => ({
+  planQueries: vi.fn(),
+  webSearch: vi.fn(),
+  wikiSearch: vi.fn(),
+  fetchArticles: vi.fn(),
+  evaluateSufficiency: vi.fn(),
+  refineQueries: vi.fn(),
+  compileBatch: vi.fn(),
+  humanReviewResearch: vi.fn(),
+}));
+
+vi.mock("../../../../agents/subgraphs/research/nodes/index.js", async () => {
+  // shouldRefine is the *real* pure function so the conditional edge actually
+  // routes by the values we feed in via the mocked evaluate_sufficiency.
+  // shouldRefine だけは本物を呼び、条件分岐の挙動を実際に確かめる。
+  const real = await vi.importActual<
+    typeof import("../../../../agents/subgraphs/research/nodes/index.js")
+  >("../../../../agents/subgraphs/research/nodes/index.js");
+  return {
+    ...real,
+    planQueries,
+    webSearch,
+    wikiSearch,
+    fetchArticles,
+    evaluateSufficiency,
+    refineQueries,
+    compileBatch,
+    humanReviewResearch,
+  };
+});
+
+import { GraphRunner } from "../../../../agents/runner/graphRunner.js";
+import {
+  __resetRegistryForTests,
+  registerGraph,
+} from "../../../../agents/registry/graphRegistry.js";
+import {
+  RESEARCH_GRAPH_ID,
+  registerResearchLoopGraph,
+} from "../../../../agents/subgraphs/research/index.js";
+import type { GraphContext } from "../../../../agents/core/types/graphContext.js";
+import type { Database } from "../../../../types/index.js";
+
+function fakeContext(graphId: string): GraphContext {
+  return {
+    threadId: "thread-loop",
+    sessionId: "thread-loop",
+    userId: "user-1",
+    pageId: "page-1",
+    graphId,
+    backend: "zedi_managed",
+    tier: "free",
+    db: {} as Database,
+    feature: "wiki_compose:research",
+    userEmail: null,
+  };
+}
+
+describe("researchLoopSubgraph — autonomous loop", () => {
+  beforeEach(() => {
+    __resetRegistryForTests();
+    registerResearchLoopGraph();
+    planQueries.mockReset();
+    webSearch.mockReset();
+    wikiSearch.mockReset();
+    fetchArticles.mockReset();
+    evaluateSufficiency.mockReset();
+    refineQueries.mockReset();
+    compileBatch.mockReset();
+    humanReviewResearch.mockReset();
+  });
+  afterEach(() => {
+    __resetRegistryForTests();
+  });
+
+  it("loops exactly `maxIterations` times when evaluation never reaches threshold", async () => {
+    const maxIterations = 3;
+
+    planQueries.mockImplementation(async (_state, _config) => ({
+      queries: [{ id: "q-init", query: "init", channels: ["web"] }],
+      maxIterations,
+      iteration: 0,
+      lastEvaluation: null,
+      exitReason: null,
+      phase: "research:plan",
+    }));
+    webSearch.mockImplementation(async (_state, _config) => ({
+      pendingSources: [{ id: "src:a", kind: "web", title: "A", url: "https://a/" }],
+    }));
+    wikiSearch.mockImplementation(async (_state, _config) => ({ pendingSources: [] }));
+    fetchArticles.mockImplementation(async (_state, _config) => ({ pendingSources: [] }));
+
+    // evaluate_sufficiency post-increments iteration; we mirror that here.
+    let evaluatedTimes = 0;
+    evaluateSufficiency.mockImplementation(async (state, _config) => {
+      evaluatedTimes += 1;
+      return {
+        lastEvaluation: { score: 0.1, rationale: "weak", missingAspects: ["x"] },
+        iteration: state.iteration + 1,
+        phase: "research:evaluated",
+      };
+    });
+
+    refineQueries.mockImplementation(async (state, _config) => ({
+      queries: [
+        { id: `q-${state.iteration}`, query: `refined-${state.iteration}`, channels: ["web"] },
+      ],
+      phase: "research:refine",
+    }));
+
+    compileBatch.mockImplementation(async (state, _config) => ({
+      batches: [
+        {
+          id: "batch-1",
+          iteration: state.iteration,
+          queries: state.queries,
+          sources: state.pendingSources,
+          evaluation: state.lastEvaluation,
+          createdAt: "2026-01-01T00:00:00.000Z",
+        },
+      ],
+      exitReason: "max_iterations",
+      phase: "research:compile",
+    }));
+
+    // human_review_research interrupts; we shortcut here by returning a normal
+    // update so the loop test focuses on iteration accounting, not HITL.
+    // HITL は別テストで検証する。ループ計測のため interrupt を回避。
+    humanReviewResearch.mockImplementation(async (_state, _config) => ({
+      approvedResearch: [],
+      rejectedResearch: [],
+      phase: "completed",
+    }));
+
+    const runner = new GraphRunner();
+    const result = await runner.invoke(
+      {
+        graphId: RESEARCH_GRAPH_ID,
+        context: fakeContext(RESEARCH_GRAPH_ID),
+        checkpointer: false,
+        recursionLimit: 60,
+      },
+      { kind: "input", value: { messages: [{ role: "user", content: "brief" }] } },
+    );
+
+    expect(result.status).toBe("completed");
+    // evaluate runs N times where N === maxIterations (initial run + each refine).
+    // evaluate は maxIterations 回走る（初回 + refine ごと）。
+    expect(evaluatedTimes).toBe(maxIterations);
+    expect(refineQueries).toHaveBeenCalledTimes(maxIterations - 1);
+    expect(compileBatch).toHaveBeenCalledTimes(1);
+    expect(humanReviewResearch).toHaveBeenCalledTimes(1);
+  });
+
+  it("exits early when evaluation crosses the 0.75 threshold", async () => {
+    planQueries.mockImplementation(async (_s, _c) => ({
+      queries: [{ id: "q1", query: "init", channels: ["web"] }],
+      maxIterations: 5,
+      iteration: 0,
+      lastEvaluation: null,
+      exitReason: null,
+      phase: "research:plan",
+    }));
+    webSearch.mockImplementation(async () => ({ pendingSources: [] }));
+    wikiSearch.mockImplementation(async () => ({ pendingSources: [] }));
+    fetchArticles.mockImplementation(async () => ({ pendingSources: [] }));
+    evaluateSufficiency.mockImplementation(async (state, _c) => ({
+      lastEvaluation: { score: 0.9, rationale: "great", missingAspects: [] },
+      iteration: state.iteration + 1,
+      phase: "research:evaluated",
+    }));
+    refineQueries.mockImplementation(async () => ({ queries: [], phase: "research:refine" }));
+    compileBatch.mockImplementation(async (state, _c) => ({
+      batches: [
+        {
+          id: "batch-early",
+          iteration: state.iteration,
+          queries: state.queries,
+          sources: state.pendingSources,
+          evaluation: state.lastEvaluation,
+          createdAt: "2026-01-01T00:00:00.000Z",
+        },
+      ],
+      exitReason: "score_threshold",
+      phase: "research:compile",
+    }));
+    humanReviewResearch.mockImplementation(async () => ({
+      approvedResearch: [],
+      rejectedResearch: [],
+      phase: "completed",
+    }));
+
+    const runner = new GraphRunner();
+    const result = await runner.invoke(
+      {
+        graphId: RESEARCH_GRAPH_ID,
+        context: fakeContext(RESEARCH_GRAPH_ID),
+        checkpointer: false,
+        recursionLimit: 60,
+      },
+      { kind: "input", value: { messages: [{ role: "user", content: "brief" }] } },
+    );
+
+    expect(result.status).toBe("completed");
+    // Single iteration: evaluate once, refine never, compile once.
+    expect(evaluateSufficiency).toHaveBeenCalledTimes(1);
+    expect(refineQueries).not.toHaveBeenCalled();
+    expect(compileBatch).toHaveBeenCalledTimes(1);
+  });
+});
+
+// Lint guard so a stray top-level registerGraph call cannot pollute the registry.
+void registerGraph;
diff --git a/server/api/src/__tests__/agents/subgraphs/research/researchGraph.modelGuard.test.ts b/server/api/src/__tests__/agents/subgraphs/research/researchGraph.modelGuard.test.ts
new file mode 100644
index 00000000..cc73f668
--- /dev/null
+++ b/server/api/src/__tests__/agents/subgraphs/research/researchGraph.modelGuard.test.ts
@@ -0,0 +1,169 @@
+/**
+ * issue #949 受け入れ条件 #6:
+ * 「全 LLM 呼び出しが `ZediChatModel` 経由」。
+ *
+ * Mocks the `createZediChatModel` factory and asserts that every LLM-bound
+ * node (`plan_queries`, `evaluate_sufficiency`, `refine_queries`) calls the
+ * factory at least once during a real (non-mocked-node) loop. The tools are
+ * still mocked at the barrel level so we don't make network calls.
+ *
+ * Note: this does NOT test for the *absence* of other LLM clients — that's a
+ * code-review concern. The factory call count check catches the most common
+ * regression (a node reaching for a provider client directly).
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { createZediChatModel } = vi.hoisted(() => ({ createZediChatModel: vi.fn() }));
+
+vi.mock("../../../../agents/core/llm/modelFactory.js", async () => {
+  const actual = await vi.importActual<
+    typeof import("../../../../agents/core/llm/modelFactory.js")
+  >("../../../../agents/core/llm/modelFactory.js");
+  return {
+    ...actual,
+    createZediChatModel: (...args: unknown[]) =>
+      createZediChatModel(...(args as Parameters<typeof actual.createZediChatModel>)),
+  };
+});
+
+// Mock the tools so they don't try to hit anything real. We test their bodies
+// individually elsewhere.
+// tools は別テストで検証するので、本テストでは empty 応答で済ます。
+vi.mock("../../../../agents/core/tools/webSearch.js", async () => {
+  const { tool } = await import("@langchain/core/tools");
+  const { z } = await import("zod");
+  return {
+    WEB_SEARCH_TOOL_NAME: "web_search",
+    webSearchInputSchema: z.object({ query: z.string(), limit: z.number().optional() }),
+    webSearchTool: tool(async () => JSON.stringify({ ok: true, results: [] }), {
+      name: "web_search",
+      description: "stub",
+      schema: z.object({ query: z.string(), limit: z.number().optional() }),
+    }),
+  };
+});
+vi.mock("../../../../agents/core/tools/wikiSearch.js", async () => {
+  const { tool } = await import("@langchain/core/tools");
+  const { z } = await import("zod");
+  return {
+    WIKI_SEARCH_TOOL_NAME: "wiki_search",
+    wikiSearchInputSchema: z.object({ query: z.string(), limit: z.number().optional() }),
+    wikiSearchTool: tool(async () => JSON.stringify({ ok: true, results: [] }), {
+      name: "wiki_search",
+      description: "stub",
+      schema: z.object({ query: z.string(), limit: z.number().optional() }),
+    }),
+  };
+});
+vi.mock("../../../../agents/core/tools/fetchArticle.js", async () => {
+  const { tool } = await import("@langchain/core/tools");
+  const { z } = await import("zod");
+  return {
+    FETCH_ARTICLE_TOOL_NAME: "fetch_article",
+    fetchArticleInputSchema: z.object({ url: z.string(), previewLength: z.number().optional() }),
+    fetchArticleTool: tool(async () => JSON.stringify({ ok: false, url: "", error: "stub" }), {
+      name: "fetch_article",
+      description: "stub",
+      schema: z.object({ url: z.string(), previewLength: z.number().optional() }),
+    }),
+  };
+});
+
+import { GraphRunner } from "../../../../agents/runner/graphRunner.js";
+import { __resetRegistryForTests } from "../../../../agents/registry/graphRegistry.js";
+import {
+  RESEARCH_GRAPH_ID,
+  registerResearchLoopGraph,
+} from "../../../../agents/subgraphs/research/index.js";
+import { MemorySaver } from "@langchain/langgraph";
+import type { GraphContext } from "../../../../agents/core/types/graphContext.js";
+import type { Database } from "../../../../types/index.js";
+
+function fakeContext(): GraphContext {
+  return {
+    threadId: "thread-guard",
+    sessionId: "thread-guard",
+    userId: "user-1",
+    pageId: "page-1",
+    graphId: RESEARCH_GRAPH_ID,
+    backend: "zedi_managed",
+    tier: "free",
+    db: {} as Database,
+    feature: "wiki_compose:research",
+    userEmail: null,
+  };
+}
+
+/** Build a fake ZediChatModel-shaped object with a `withStructuredOutput` chain. */
+function fakeModel(structuredReturn: () => Promise<unknown>) {
+  const runnable = {
+    invoke: vi.fn(async (_messages: unknown) => structuredReturn()),
+  };
+  return {
+    withStructuredOutput: vi.fn((_schema: unknown, _opts?: unknown) => runnable),
+  };
+}
+
+describe("researchLoopSubgraph — all LLM calls go through ZediChatModel", () => {
+  beforeEach(() => {
+    __resetRegistryForTests();
+    registerResearchLoopGraph();
+    createZediChatModel.mockReset();
+  });
+  afterEach(() => {
+    __resetRegistryForTests();
+  });
+
+  it("invokes createZediChatModel for plan, evaluate, and refine", async () => {
+    // Plan returns 2 queries (1 web, 1 wiki) so web_search + wiki_search both fire.
+    // Evaluate returns score 0.1 forcing one refine, then evaluate returns 0.9.
+    let evaluateCall = 0;
+    createZediChatModel.mockImplementation(async (input: { feature: string }) => {
+      if (input.feature.endsWith(":plan")) {
+        return fakeModel(async () => ({
+          queries: [
+            { query: "q-web", channels: ["web"] },
+            { query: "q-wiki", channels: ["wiki"] },
+          ],
+        }));
+      }
+      if (input.feature.endsWith(":evaluate")) {
+        evaluateCall += 1;
+        const score = evaluateCall >= 2 ? 0.9 : 0.1;
+        return fakeModel(async () => ({
+          score,
+          rationale: "auto",
+          missingAspects: score < 0.75 ? ["x"] : [],
+        }));
+      }
+      if (input.feature.endsWith(":refine")) {
+        return fakeModel(async () => ({
+          queries: [{ query: "q-refined", channels: ["web"] }],
+        }));
+      }
+      throw new Error(`unexpected feature ${input.feature}`);
+    });
+
+    const runner = new GraphRunner();
+    await runner.invoke(
+      {
+        graphId: RESEARCH_GRAPH_ID,
+        context: fakeContext(),
+        checkpointer: new MemorySaver(),
+        recursionLimit: 60,
+      },
+      { kind: "input", value: { messages: [{ role: "user", content: "brief" }] } },
+    );
+
+    const features = createZediChatModel.mock.calls.map(
+      (call) => (call[0] as { feature: string }).feature,
+    );
+    expect(features).toContain("wiki_compose:research:plan");
+    expect(features).toContain("wiki_compose:research:evaluate");
+    expect(features).toContain("wiki_compose:research:refine");
+    // No raw aiProviders / OpenAI / Anthropic clients should be imported by the
+    // research-loop nodes; only `createZediChatModel` is mocked. If a node ever
+    // imports a provider SDK directly, this test will still pass — code review
+    // is the second line of defence.
+  });
+});
diff --git a/server/api/src/__tests__/agents/subgraphs/research/researchGraph.resume.test.ts b/server/api/src/__tests__/agents/subgraphs/research/researchGraph.resume.test.ts
new file mode 100644
index 00000000..756245d4
--- /dev/null
+++ b/server/api/src/__tests__/agents/subgraphs/research/researchGraph.resume.test.ts
@@ -0,0 +1,238 @@
+/**
+ * issue #949 受け入れ条件 #4:
+ * 「resume で approvedResearch が state に反映される」。
+ *
+ * Drives the graph to interrupt at `human_review_research`, then resumes with
+ * a structured `{ approvedSourceIds, rejectedSourceIds }` payload and asserts
+ * that the final state's `approvedResearch` and `rejectedResearch` arrays
+ * reflect the choice.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const {
+  planQueries,
+  webSearch,
+  wikiSearch,
+  fetchArticles,
+  evaluateSufficiency,
+  refineQueries,
+  compileBatch,
+} = vi.hoisted(() => ({
+  planQueries: vi.fn(),
+  webSearch: vi.fn(),
+  wikiSearch: vi.fn(),
+  fetchArticles: vi.fn(),
+  evaluateSufficiency: vi.fn(),
+  refineQueries: vi.fn(),
+  compileBatch: vi.fn(),
+}));
+
+vi.mock("../../../../agents/subgraphs/research/nodes/index.js", async () => {
+  const real = await vi.importActual<
+    typeof import("../../../../agents/subgraphs/research/nodes/index.js")
+  >("../../../../agents/subgraphs/research/nodes/index.js");
+  return {
+    ...real,
+    planQueries,
+    webSearch,
+    wikiSearch,
+    fetchArticles,
+    evaluateSufficiency,
+    refineQueries,
+    compileBatch,
+  };
+});
+
+import { GraphRunner } from "../../../../agents/runner/graphRunner.js";
+import { __resetRegistryForTests } from "../../../../agents/registry/graphRegistry.js";
+import {
+  RESEARCH_GRAPH_ID,
+  registerResearchLoopGraph,
+} from "../../../../agents/subgraphs/research/index.js";
+import { getRegisteredGraph } from "../../../../agents/registry/graphRegistry.js";
+import type { GraphContext } from "../../../../agents/core/types/graphContext.js";
+import type { Database } from "../../../../types/index.js";
+import { Command, MemorySaver } from "@langchain/langgraph";
+
+function fakeContext(): GraphContext {
+  return {
+    threadId: "thread-resume",
+    sessionId: "thread-resume",
+    userId: "user-1",
+    pageId: "page-1",
+    graphId: RESEARCH_GRAPH_ID,
+    backend: "zedi_managed",
+    tier: "free",
+    db: {} as Database,
+    feature: "wiki_compose:research",
+    userEmail: null,
+  };
+}
+
+describe("researchLoopSubgraph — resume projects approvedResearch", () => {
+  beforeEach(() => {
+    __resetRegistryForTests();
+    registerResearchLoopGraph();
+    planQueries.mockReset();
+    webSearch.mockReset();
+    wikiSearch.mockReset();
+    fetchArticles.mockReset();
+    evaluateSufficiency.mockReset();
+    refineQueries.mockReset();
+    compileBatch.mockReset();
+  });
+  afterEach(() => {
+    __resetRegistryForTests();
+  });
+
+  it("populates approvedResearch / rejectedResearch from the resume payload", async () => {
+    const pending = [
+      { id: "src:a", kind: "web" as const, title: "A", url: "https://a/" },
+      { id: "src:b", kind: "web" as const, title: "B", url: "https://b/" },
+      { id: "wiki:p", kind: "wiki" as const, title: "P", pageId: "p", noteId: "n" },
+    ];
+
+    planQueries.mockImplementation(async () => ({
+      queries: [{ id: "q1", query: "init", channels: ["web"] }],
+      maxIterations: 3,
+      iteration: 0,
+      lastEvaluation: null,
+      exitReason: null,
+      phase: "research:plan",
+    }));
+    webSearch.mockImplementation(async () => ({ pendingSources: pending.slice(0, 2) }));
+    wikiSearch.mockImplementation(async () => ({ pendingSources: pending.slice(2) }));
+    fetchArticles.mockImplementation(async () => ({ pendingSources: [] }));
+    evaluateSufficiency.mockImplementation(async (state, _c) => ({
+      lastEvaluation: { score: 0.9, rationale: "ok", missingAspects: [] },
+      iteration: state.iteration + 1,
+      phase: "research:evaluated",
+    }));
+    compileBatch.mockImplementation(async (state, _c) => ({
+      batches: [
+        {
+          id: "batch-1",
+          iteration: state.iteration,
+          queries: state.queries,
+          sources: state.pendingSources,
+          evaluation: state.lastEvaluation,
+          createdAt: "2026-01-01T00:00:00.000Z",
+        },
+      ],
+      exitReason: "score_threshold",
+      phase: "research:compile",
+    }));
+
+    // GraphRunner.resume goes through `invoke` internally; we drive the same
+    // sequence here so we can read the final compiled state after resume.
+    // GraphRunner.resume を経由しつつ、最終 state を読むために自前で
+    // compiled graph を組み立てる（registry + checkpointer 経由は同じ）。
+    const registered = getRegisteredGraph(RESEARCH_GRAPH_ID);
+    if (!registered) throw new Error("graph not registered");
+    const checkpointer = new MemorySaver();
+    const compiled = registered.factory({ checkpointer }) as {
+      invoke: (input: unknown, options: unknown) => Promise<unknown>;
+      getState?: (options: unknown) => Promise<unknown>;
+    };
+
+    const config = {
+      configurable: {
+        thread_id: "thread-resume",
+        zediGraphContext: fakeContext(),
+      },
+      recursionLimit: 60,
+    };
+
+    // 1st invoke runs to the interrupt. LangGraph 1.x surfaces interrupts as
+    // a `__interrupt__: Interrupt[]` array on the returned state instead of
+    // throwing, so we check for that shape.
+    // LangGraph 1.x では interrupt は throw されず、結果 state の
+    // `__interrupt__` 配列に乗る。throw 経路ではなく field を見る。
+    const firstResult = (await compiled.invoke(
+      { messages: [{ role: "user", content: "brief" }] },
+      config,
+    )) as { __interrupt__?: Array<{ value: unknown }> };
+    expect(Array.isArray(firstResult.__interrupt__)).toBe(true);
+    expect(firstResult.__interrupt__?.length).toBeGreaterThan(0);
+
+    // 2nd invoke resumes with the approval payload.
+    const finalState = (await compiled.invoke(
+      new Command({
+        resume: {
+          approvedSourceIds: ["src:a", "wiki:p"],
+          rejectedSourceIds: ["src:b"],
+        },
+      }),
+      config,
+    )) as {
+      approvedResearch: Array<{ id: string }>;
+      rejectedResearch: Array<{ id: string }>;
+      phase: string;
+    };
+
+    expect(finalState.approvedResearch.map((s) => s.id).sort()).toEqual(["src:a", "wiki:p"].sort());
+    expect(finalState.rejectedResearch.map((s) => s.id)).toEqual(["src:b"]);
+    expect(finalState.phase).toBe("completed");
+  });
+
+  it("rejects an ill-formed resume payload", async () => {
+    planQueries.mockImplementation(async () => ({
+      queries: [{ id: "q1", query: "init", channels: ["web"] }],
+      maxIterations: 3,
+      iteration: 0,
+      lastEvaluation: null,
+      exitReason: null,
+      phase: "research:plan",
+    }));
+    webSearch.mockImplementation(async () => ({ pendingSources: [] }));
+    wikiSearch.mockImplementation(async () => ({ pendingSources: [] }));
+    fetchArticles.mockImplementation(async () => ({ pendingSources: [] }));
+    evaluateSufficiency.mockImplementation(async (state, _c) => ({
+      lastEvaluation: { score: 0.9, rationale: "ok", missingAspects: [] },
+      iteration: state.iteration + 1,
+      phase: "research:evaluated",
+    }));
+    compileBatch.mockImplementation(async (state, _c) => ({
+      batches: [
+        {
+          id: "batch-bad",
+          iteration: state.iteration,
+          queries: state.queries,
+          sources: state.pendingSources,
+          evaluation: state.lastEvaluation,
+          createdAt: "2026-01-01T00:00:00.000Z",
+        },
+      ],
+      exitReason: "score_threshold",
+      phase: "research:compile",
+    }));
+
+    const runner = new GraphRunner();
+    const checkpointer = new MemorySaver();
+    const ctx = fakeContext();
+    // Use a fresh thread id so interrupt/resume state doesn't collide with
+    // the previous test in the same MemorySaver instance.
+    // テスト間で thread_id を分けて checkpointer 衝突を避ける。
+    const isolated = { ...ctx, threadId: "thread-resume-bad", sessionId: "thread-resume-bad" };
+
+    // First call: should interrupt.
+    const first = await runner.invoke(
+      {
+        graphId: RESEARCH_GRAPH_ID,
+        context: isolated,
+        checkpointer,
+        recursionLimit: 60,
+      },
+      { kind: "input", value: { messages: [{ role: "user", content: "brief" }] } },
+    );
+    expect(first.status).toBe("interrupted");
+
+    // Resume with a payload that fails `researchResumeSchema` validation.
+    const bad = await runner.resume(
+      { graphId: RESEARCH_GRAPH_ID, context: isolated, checkpointer, recursionLimit: 60 },
+      { approvedSourceIds: [42] as unknown as string[] },
+    );
+    expect(bad.status).toBe("failed");
+    expect(bad.error).toBeDefined();
+  });
+});
diff --git a/server/api/src/__tests__/agents/subgraphs/research/tools/fetchArticle.test.ts b/server/api/src/__tests__/agents/subgraphs/research/tools/fetchArticle.test.ts
new file mode 100644
index 00000000..4b979059
--- /dev/null
+++ b/server/api/src/__tests__/agents/subgraphs/research/tools/fetchArticle.test.ts
@@ -0,0 +1,95 @@
+/**
+ * `fetchArticleTool` unit tests. Covers:
+ * - SSRF rejection: `isClipUrlAllowedAfterDns` returns false → `{ ok:false, error:"url_blocked" }`.
+ * - Happy path: `extractArticleFromUrl` returns an article → success envelope.
+ * - Extractor throw → error envelope (no rethrow).
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { isClipUrlAllowedAfterDns, extractArticleFromUrl } = vi.hoisted(() => ({
+  isClipUrlAllowedAfterDns: vi.fn(),
+  extractArticleFromUrl: vi.fn(),
+}));
+
+vi.mock("../../../../../lib/clipUrlPolicy.js", () => ({
+  isClipUrlAllowedAfterDns: (...args: unknown[]) =>
+    isClipUrlAllowedAfterDns(
+      ...(args as Parameters<
+        typeof import("../../../../../lib/clipUrlPolicy.js").isClipUrlAllowedAfterDns
+      >),
+    ),
+}));
+
+vi.mock("../../../../../lib/articleExtractor.js", async () => {
+  const actual = await vi.importActual<typeof import("../../../../../lib/articleExtractor.js")>(
+    "../../../../../lib/articleExtractor.js",
+  );
+  return {
+    ...actual,
+    extractArticleFromUrl: (...args: unknown[]) =>
+      extractArticleFromUrl(
+        ...(args as Parameters<
+          typeof import("../../../../../lib/articleExtractor.js").extractArticleFromUrl
+        >),
+      ),
+  };
+});
+
+import { fetchArticleTool } from "../../../../../agents/core/tools/fetchArticle.js";
+
+beforeEach(() => {
+  isClipUrlAllowedAfterDns.mockReset();
+  extractArticleFromUrl.mockReset();
+});
+afterEach(() => {
+  isClipUrlAllowedAfterDns.mockReset();
+  extractArticleFromUrl.mockReset();
+});
+
+describe("fetchArticleTool", () => {
+  it("rejects blocked URLs without calling the extractor", async () => {
+    isClipUrlAllowedAfterDns.mockResolvedValueOnce(false);
+    const raw = await fetchArticleTool.invoke({ url: "http://internal/" });
+    expect(extractArticleFromUrl).not.toHaveBeenCalled();
+    const parsed = JSON.parse(raw as string) as { ok: boolean; error?: string };
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error).toBe("url_blocked");
+  });
+
+  it("returns an article envelope on success", async () => {
+    isClipUrlAllowedAfterDns.mockResolvedValueOnce(true);
+    extractArticleFromUrl.mockResolvedValueOnce({
+      finalUrl: "https://final/",
+      title: "T",
+      thumbnailUrl: null,
+      tiptapJson: { type: "doc" },
+      contentText: "body",
+      contentHash: "abc",
+    });
+    const raw = await fetchArticleTool.invoke({ url: "https://x/", previewLength: 1000 });
+    const parsed = JSON.parse(raw as string) as {
+      ok: boolean;
+      finalUrl: string;
+      title: string;
+      excerpt: string;
+      contentHash: string;
+    };
+    expect(parsed.ok).toBe(true);
+    expect(parsed.finalUrl).toBe("https://final/");
+    expect(parsed.title).toBe("T");
+    expect(parsed.excerpt).toBe("body");
+    expect(parsed.contentHash).toBe("abc");
+    expect(extractArticleFromUrl).toHaveBeenCalledWith(
+      expect.objectContaining({ url: "https://x/", previewLength: 1000 }),
+    );
+  });
+
+  it("wraps extractor errors in a non-throwing envelope", async () => {
+    isClipUrlAllowedAfterDns.mockResolvedValueOnce(true);
+    extractArticleFromUrl.mockRejectedValueOnce(new Error("network fail"));
+    const raw = await fetchArticleTool.invoke({ url: "https://x/" });
+    const parsed = JSON.parse(raw as string) as { ok: boolean; error?: string };
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error).toBe("network fail");
+  });
+});
diff --git a/server/api/src/__tests__/agents/subgraphs/research/tools/webSearch.test.ts b/server/api/src/__tests__/agents/subgraphs/research/tools/webSearch.test.ts
new file mode 100644
index 00000000..f2cb7c85
--- /dev/null
+++ b/server/api/src/__tests__/agents/subgraphs/research/tools/webSearch.test.ts
@@ -0,0 +1,84 @@
+/**
+ * `webSearchTool` unit tests. Covers:
+ * - Missing graph context → JSON envelope `{ ok:false, error:"missing_graph_context" }`.
+ * - No OpenAI/Google model configured → `{ ok:true, results:[], note:"web_search_unavailable" }`
+ *   (the Anthropic-fallback path documented in the tool's JSDoc).
+ *
+ * We don't fully exercise the LLM path here — `researchGraph.modelGuard.test.ts`
+ * already verifies that the tool routes through `createZediChatModel`, and the
+ * structured-output shape is covered indirectly by the loop test. Adding a
+ * full network mock would be brittle for marginal value.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { resolveWebSearchModelId } = vi.hoisted(() => ({ resolveWebSearchModelId: vi.fn() }));
+
+vi.mock("../../../../../agents/core/tools/resolveWebSearchModel.js", () => ({
+  resolveWebSearchModelId: (...args: unknown[]) =>
+    resolveWebSearchModelId(
+      ...(args as Parameters<
+        typeof import("../../../../../agents/core/tools/resolveWebSearchModel.js").resolveWebSearchModelId
+      >),
+    ),
+}));
+
+import { webSearchTool } from "../../../../../agents/core/tools/webSearch.js";
+import { GRAPH_CONTEXT_CONFIG_KEY } from "../../../../../agents/core/types/graphContext.js";
+import type { GraphContext } from "../../../../../agents/core/types/graphContext.js";
+import type { Database } from "../../../../../types/index.js";
+
+function ctxConfig(): { configurable: Record<string, unknown> } {
+  return {
+    configurable: {
+      [GRAPH_CONTEXT_CONFIG_KEY]: {
+        threadId: "t",
+        sessionId: "t",
+        userId: "u-1",
+        pageId: "p-1",
+        graphId: "wiki-compose-research",
+        backend: "zedi_managed",
+        tier: "free",
+        db: {} as Database,
+        feature: "wiki_compose:research",
+        userEmail: null,
+      } satisfies GraphContext,
+    },
+  };
+}
+
+beforeEach(() => {
+  resolveWebSearchModelId.mockReset();
+});
+afterEach(() => {
+  resolveWebSearchModelId.mockReset();
+});
+
+describe("webSearchTool", () => {
+  it("reports missing_graph_context when called without configurable", async () => {
+    const raw = await webSearchTool.invoke({ query: "ripgrep" });
+    const parsed = JSON.parse(raw as string) as { ok: boolean; error?: string };
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error).toBe("missing_graph_context");
+  });
+
+  it("returns the documented fallback when no managed web-search model is configured", async () => {
+    resolveWebSearchModelId.mockResolvedValueOnce(null);
+    const raw = await webSearchTool.invoke({ query: "ripgrep" }, ctxConfig());
+    const parsed = JSON.parse(raw as string) as {
+      ok: boolean;
+      results: unknown[];
+      note?: string;
+    };
+    expect(parsed.ok).toBe(true);
+    expect(parsed.results).toEqual([]);
+    expect(parsed.note).toBe("web_search_unavailable");
+  });
+
+  it("returns an error envelope when model resolution itself throws", async () => {
+    resolveWebSearchModelId.mockRejectedValueOnce(new Error("db unreachable"));
+    const raw = await webSearchTool.invoke({ query: "x" }, ctxConfig());
+    const parsed = JSON.parse(raw as string) as { ok: boolean; error?: string };
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error).toMatch(/web_search_model_resolution_failed:db unreachable/);
+  });
+});
diff --git a/server/api/src/__tests__/agents/subgraphs/research/tools/wikiSearch.test.ts b/server/api/src/__tests__/agents/subgraphs/research/tools/wikiSearch.test.ts
new file mode 100644
index 00000000..d696231f
--- /dev/null
+++ b/server/api/src/__tests__/agents/subgraphs/research/tools/wikiSearch.test.ts
@@ -0,0 +1,110 @@
+/**
+ * `wikiSearchTool` unit tests. Covers:
+ * - Missing graph context → JSON envelope `{ ok:false, error:"missing_graph_context" }`.
+ * - Happy path: forwards `userId` / `userEmail` to `searchUserWikiPages` and
+ *   maps hits to the on-wire `Source` envelope with stable `wiki:<pageId>` ids.
+ * - Service error → JSON envelope `{ ok:false, error }`.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { searchUserWikiPages } = vi.hoisted(() => ({ searchUserWikiPages: vi.fn() }));
+vi.mock("../../../../../services/wikiSearchService.js", () => ({
+  searchUserWikiPages: (...args: unknown[]) =>
+    searchUserWikiPages(
+      ...(args as Parameters<
+        typeof import("../../../../../services/wikiSearchService.js").searchUserWikiPages
+      >),
+    ),
+}));
+
+import { wikiSearchTool } from "../../../../../agents/core/tools/wikiSearch.js";
+import { GRAPH_CONTEXT_CONFIG_KEY } from "../../../../../agents/core/types/graphContext.js";
+import type { GraphContext } from "../../../../../agents/core/types/graphContext.js";
+import type { Database } from "../../../../../types/index.js";
+
+function ctxConfig(overrides: Partial<GraphContext> = {}): {
+  configurable: Record<string, unknown>;
+} {
+  return {
+    configurable: {
+      [GRAPH_CONTEXT_CONFIG_KEY]: {
+        threadId: "t",
+        sessionId: "t",
+        userId: "u-1",
+        pageId: "p-1",
+        graphId: "wiki-compose-research",
+        backend: "zedi_managed",
+        tier: "free",
+        db: {} as Database,
+        feature: "wiki_compose:research",
+        userEmail: "alice@example.com",
+        ...overrides,
+      } satisfies GraphContext,
+    },
+  };
+}
+
+beforeEach(() => {
+  searchUserWikiPages.mockReset();
+});
+afterEach(() => {
+  searchUserWikiPages.mockReset();
+});
+
+describe("wikiSearchTool", () => {
+  it("reports missing_graph_context when called without configurable", async () => {
+    const raw = await wikiSearchTool.invoke({ query: "ripgrep" });
+    expect(typeof raw).toBe("string");
+    const parsed = JSON.parse(raw as string) as { ok: boolean; error?: string };
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error).toBe("missing_graph_context");
+  });
+
+  it("forwards userId / userEmail and maps service hits to wiki sources", async () => {
+    searchUserWikiPages.mockResolvedValueOnce([
+      {
+        pageId: "page-1",
+        noteId: "note-1",
+        title: "Alpha",
+        contentPreview: "preview",
+        updatedAt: "2026-01-01T00:00:00.000Z",
+      },
+    ]);
+    const raw = await wikiSearchTool.invoke(
+      { query: "alpha", limit: 7 },
+      ctxConfig({ userId: "u-7", userEmail: "u7@x.com" }),
+    );
+    expect(searchUserWikiPages).toHaveBeenCalledWith(
+      expect.anything(),
+      "u-7",
+      "u7@x.com",
+      "alpha",
+      "shared",
+      7,
+    );
+    const parsed = JSON.parse(raw as string) as {
+      ok: boolean;
+      results: Array<{ id: string; kind: string; pageId: string; noteId: string; title: string }>;
+    };
+    expect(parsed.ok).toBe(true);
+    expect(parsed.results).toEqual([
+      {
+        id: "wiki:page-1",
+        kind: "wiki",
+        title: "Alpha",
+        pageId: "page-1",
+        noteId: "note-1",
+        snippet: "preview",
+      },
+    ]);
+  });
+
+  it("returns an error envelope when the service throws", async () => {
+    searchUserWikiPages.mockRejectedValueOnce(new Error("db down"));
+    const raw = await wikiSearchTool.invoke({ query: "x" }, ctxConfig());
+    const parsed = JSON.parse(raw as string) as { ok: boolean; error?: string; results: unknown[] };
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error).toBe("db down");
+    expect(parsed.results).toEqual([]);
+  });
+});
diff --git a/server/api/src/__tests__/routes/composeSessionPersistence.test.ts b/server/api/src/__tests__/routes/composeSessionPersistence.test.ts
new file mode 100644
index 00000000..47c09952
--- /dev/null
+++ b/server/api/src/__tests__/routes/composeSessionPersistence.test.ts
@@ -0,0 +1,32 @@
+/**
+ * Tests for terminal-status persistence on Wiki Compose sessions.
+ */
+import { describe, it, expect } from "vitest";
+import { persistOutcomeIfStillRunning } from "../../routes/composeSessionPersistence.js";
+import { createMockDb } from "../createMockDb.js";
+
+describe("persistOutcomeIfStillRunning", () => {
+  it("returns false without updating when no running row matches", async () => {
+    const { db, chains } = createMockDb([[]]);
+    const updated = await persistOutcomeIfStillRunning(db as never, "sess-cancelled", {
+      status: "completed",
+      lastError: null,
+    });
+    expect(updated).toBe(false);
+    const updateChain = chains.find((c) => c.startMethod === "update");
+    expect(updateChain?.ops.some((op) => op.method === "where")).toBe(true);
+  });
+
+  it("returns true when a running row is updated", async () => {
+    const { db, chains } = createMockDb([[{ id: "sess-running" }]]);
+    const updated = await persistOutcomeIfStillRunning(db as never, "sess-running", {
+      status: "failed",
+      lastError: "boom",
+    });
+    expect(updated).toBe(true);
+    const setOp = chains
+      .find((c) => c.startMethod === "update")
+      ?.ops.find((op) => op.method === "set");
+    expect((setOp?.args[0] as { status?: string })?.status).toBe("failed");
+  });
+});
diff --git a/server/api/src/__tests__/routes/composeSessionProjection.test.ts b/server/api/src/__tests__/routes/composeSessionProjection.test.ts
new file mode 100644
index 00000000..30d1a00a
--- /dev/null
+++ b/server/api/src/__tests__/routes/composeSessionProjection.test.ts
@@ -0,0 +1,86 @@
+/**
+ * `composeSessionProjection` のユニットテスト (#950)。
+ * Unit tests for `composeSessionProjection`.
+ */
+import { describe, expect, it } from "vitest";
+import { projectComposeStateValues } from "../../routes/composeSessionProjection.js";
+
+describe("projectComposeStateValues", () => {
+  it("projects a Brief interrupt from __interrupt__", () => {
+    const projection = projectComposeStateValues({
+      __interrupt__: [
+        {
+          value: {
+            kind: "human_review_brief",
+            questions: [{ id: "q1", question: "Scope?", required: false, options: [] }],
+            pageSnapshot: { pageId: "p1", title: "T", body: "", hasContent: false },
+          },
+        },
+      ],
+    });
+    expect(projection.phase).toBe("brief");
+    expect(projection.briefQuestions).toHaveLength(1);
+    expect(projection.pageSnapshot).toMatchObject({ title: "T" });
+  });
+
+  it("keeps interrupt-derived phase when row phase is also present", () => {
+    const projection = projectComposeStateValues({
+      phase: "brief:await_user",
+      __interrupt__: [
+        {
+          value: {
+            kind: "human_review_research",
+            batch: null,
+            pendingSources: [],
+          },
+        },
+      ],
+    });
+    expect(projection.phase).toBe("research");
+  });
+
+  it("projects a conflict_resolution interrupt (#953)", () => {
+    const projection = projectComposeStateValues({
+      approvedResearch: [{ id: "src:a", kind: "web", title: "A" }],
+      __interrupt__: [
+        {
+          value: {
+            kind: "conflict_resolution",
+            conflicts: {
+              approved: [{ id: "src:a", title: "A" }],
+              rejected: [
+                { id: "src:b", title: "B" },
+                { id: "src:c", title: "C" },
+              ],
+              rationale: "Mixed approval",
+            },
+          },
+        },
+      ],
+    });
+    expect(projection.phase).toBe("conflict");
+    expect(projection.researchConflictSummary).toMatchObject({ rationale: "Mixed approval" });
+    expect(projection.approvedSources).toHaveLength(1);
+  });
+
+  it("projects completion markdown from checkpoint values", () => {
+    const projection = projectComposeStateValues({
+      phase: "completed",
+      completion: {
+        markdown: "## A\n\nBody",
+        sections: [
+          {
+            sectionId: "sec-1",
+            heading: "A",
+            body: "Body",
+            citedSourceIds: [],
+            completedAt: "2026-01-01T00:00:00.000Z",
+          },
+        ],
+      },
+    });
+    expect(projection.completedMarkdown).toBe("## A\n\nBody");
+    expect(projection.draftedSections).toHaveLength(1);
+    expect(projection.phase).toBe("completed");
+  });
+});
diff --git a/server/api/src/__tests__/routes/composeSessions.test.ts b/server/api/src/__tests__/routes/composeSessions.test.ts
new file mode 100644
index 00000000..e40e4359
--- /dev/null
+++ b/server/api/src/__tests__/routes/composeSessions.test.ts
@@ -0,0 +1,428 @@
+/**
+ * composeSessions ルートのテスト（認可・CRUD・backend ガード）。
+ *
+ * Tests for `/api/pages/:pageId/compose-sessions[/:id]`. Focuses on the parts
+ * that have to be right before a real graph is wired up: input validation,
+ * page access enforcement (issue #823 note-role only), DB row shape, and the
+ * backend whitelist.
+ *
+ * `run` / `resume` の SSE 経路は LangGraph 実体に依存するため、本テストでは
+ * CRUD と 4xx パスに絞っている。SSE の整合性は `sseMapper` 単体テストと
+ * `graphRunner` 単体テストでカバー済み。
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type { Context, Next } from "hono";
+import type { AppEnv } from "../../types/index.js";
+
+vi.mock("../../middleware/auth.js", () => ({
+  authRequired: async (c: Context<AppEnv>, next: Next) => {
+    const userId = c.req.header("x-test-user-id");
+    if (!userId) return c.json({ message: "Unauthorized" }, 401);
+    c.set("userId", userId);
+    await next();
+  },
+}));
+
+vi.mock("../../middleware/rateLimit.js", () => ({
+  rateLimit: () => async (_c: Context<AppEnv>, next: Next) => {
+    await next();
+  },
+}));
+
+vi.mock("../../services/subscriptionService.js", () => ({
+  getUserTier: async () => "free" as const,
+}));
+
+const mockGetUserAiCredentialPlaintext = vi.fn();
+
+const mockValidateModelAccess = vi.fn();
+
+vi.mock("../../services/usageService.js", () => ({
+  validateModelAccess: (...args: unknown[]) => mockValidateModelAccess(...args),
+}));
+
+vi.mock("../../services/userAiCredentialService.js", () => ({
+  getUserAiCredentialPlaintext: (...args: unknown[]) => mockGetUserAiCredentialPlaintext(...args),
+}));
+
+import { Hono } from "hono";
+import composeSessionRoutes from "../../routes/composeSessions.js";
+import { errorHandler } from "../../middleware/errorHandler.js";
+import { createMockDb } from "../createMockDb.js";
+import { __resetRegistryForTests, registerGraph } from "../../agents/registry/graphRegistry.js";
+
+const OWNER_ID = "owner-1";
+const PAGE_ID = "page-1";
+const NOTE_ID = "note-1";
+const GRAPH_ID = "test-graph";
+
+function authHeaders(userId: string = OWNER_ID) {
+  return {
+    "x-test-user-id": userId,
+    "Content-Type": "application/json",
+  };
+}
+
+function mockNote() {
+  return {
+    id: NOTE_ID,
+    ownerId: OWNER_ID,
+    title: "n",
+    visibility: "private" as const,
+    editPermission: "owner_only" as const,
+    isOfficial: false,
+    viewCount: 0,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    isDeleted: false,
+  };
+}
+
+/**
+ * assertPageEditAccess の SELECT 並び:
+ *   1: pages row, 2: caller email, 3: findActiveNoteById.
+ * assertPageViewAccess も同じ並びだが、editPermission のチェックが追加で発生する。
+ */
+function pageAccessPrefix() {
+  return [
+    [{ id: PAGE_ID, ownerId: OWNER_ID, noteId: NOTE_ID }],
+    [{ email: "owner@example.com" }],
+    [mockNote()],
+  ];
+}
+
+function createComposeApp(dbResults: unknown[]) {
+  const { db, chains } = createMockDb(dbResults);
+  const app = new Hono<AppEnv>();
+  app.use("*", async (c, next) => {
+    c.set("db", db as unknown as AppEnv["Variables"]["db"]);
+    await next();
+  });
+  app.onError(errorHandler);
+  app.route("/api/pages", composeSessionRoutes);
+  return { app, chains };
+}
+
+beforeEach(() => {
+  mockGetUserAiCredentialPlaintext.mockReset();
+  mockValidateModelAccess.mockReset();
+  mockValidateModelAccess.mockResolvedValue({
+    provider: "anthropic",
+    apiModelId: "claude-3-5-haiku",
+    inputCostUnits: 1,
+    outputCostUnits: 2,
+  });
+  __resetRegistryForTests();
+  // Register a graph the routes can resolve. Body is irrelevant for CRUD tests.
+  registerGraph({
+    id: GRAPH_ID,
+    version: "0.0.0",
+    phase: "test",
+    description: "test graph",
+    factory: () => ({
+      invoke: async () => ({}),
+      stream: async () => undefined,
+      streamEvents: () => undefined,
+    }),
+  });
+});
+
+describe("POST /api/pages/:pageId/compose-sessions", () => {
+  it("rejects requests without auth", async () => {
+    const { app } = createComposeApp([]);
+    const res = await app.request(`/api/pages/${PAGE_ID}/compose-sessions`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ graphId: GRAPH_ID }),
+    });
+    expect(res.status).toBe(401);
+  });
+
+  it("returns 400 when graphId is missing", async () => {
+    const { app } = createComposeApp([
+      ...pageAccessPrefix(),
+      // No further DB chains; route fails before insert.
+    ]);
+    const res = await app.request(`/api/pages/${PAGE_ID}/compose-sessions`, {
+      method: "POST",
+      headers: authHeaders(),
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it("returns 400 when graphId is unknown", async () => {
+    const { app } = createComposeApp([...pageAccessPrefix()]);
+    const res = await app.request(`/api/pages/${PAGE_ID}/compose-sessions`, {
+      method: "POST",
+      headers: authHeaders(),
+      body: JSON.stringify({ graphId: "never-registered" }),
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it("returns 400 for unsupported backend (legacy byok name)", async () => {
+    const { app } = createComposeApp([...pageAccessPrefix()]);
+    const res = await app.request(`/api/pages/${PAGE_ID}/compose-sessions`, {
+      method: "POST",
+      headers: authHeaders(),
+      body: JSON.stringify({ graphId: GRAPH_ID, backend: "byok" }),
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it("returns 400 for user_openai when credential is missing", async () => {
+    mockGetUserAiCredentialPlaintext.mockResolvedValue(null);
+    mockValidateModelAccess.mockResolvedValue({
+      provider: "openai",
+      apiModelId: "gpt-4o-mini",
+      inputCostUnits: 1,
+      outputCostUnits: 2,
+    });
+    const { app } = createComposeApp([...pageAccessPrefix()]);
+    const res = await app.request(`/api/pages/${PAGE_ID}/compose-sessions`, {
+      method: "POST",
+      headers: authHeaders(),
+      body: JSON.stringify({ graphId: GRAPH_ID, backend: "user_openai" }),
+    });
+    expect(res.status).toBe(400);
+    expect(mockGetUserAiCredentialPlaintext).toHaveBeenCalledWith(
+      OWNER_ID,
+      "openai",
+      expect.anything(),
+    );
+  });
+
+  it("creates a session with user_openai when credential exists", async () => {
+    mockGetUserAiCredentialPlaintext.mockResolvedValue("sk-user");
+    mockValidateModelAccess.mockResolvedValue({
+      provider: "openai",
+      apiModelId: "gpt-4o-mini",
+      inputCostUnits: 1,
+      outputCostUnits: 2,
+    });
+    const createdRow = {
+      id: "sess-byok",
+      pageId: PAGE_ID,
+      userId: OWNER_ID,
+      graphId: GRAPH_ID,
+      phase: "init",
+      backend: "user_openai",
+      status: "pending",
+      metadata: null,
+      lastError: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+      closedAt: null,
+    };
+    const { app } = createComposeApp([...pageAccessPrefix(), [createdRow]]);
+    const res = await app.request(`/api/pages/${PAGE_ID}/compose-sessions`, {
+      method: "POST",
+      headers: authHeaders(),
+      body: JSON.stringify({ graphId: GRAPH_ID, backend: "user_openai" }),
+    });
+    expect(res.status).toBe(201);
+    const body = (await res.json()) as { session: { backend: string } };
+    expect(body.session.backend).toBe("user_openai");
+  });
+
+  it("creates a session row with the resolved backend defaulting to zedi_managed", async () => {
+    const createdRow = {
+      id: "sess-1",
+      pageId: PAGE_ID,
+      userId: OWNER_ID,
+      graphId: GRAPH_ID,
+      phase: "init",
+      backend: "zedi_managed",
+      status: "pending",
+      metadata: null,
+      lastError: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+      closedAt: null,
+    };
+    const { app, chains } = createComposeApp([
+      ...pageAccessPrefix(),
+      [createdRow], // insert().values().returning()
+    ]);
+    const res = await app.request(`/api/pages/${PAGE_ID}/compose-sessions`, {
+      method: "POST",
+      headers: authHeaders(),
+      body: JSON.stringify({ graphId: GRAPH_ID }),
+    });
+    expect(res.status).toBe(201);
+    const body = (await res.json()) as { session: { id: string; backend: string } };
+    expect(body.session.id).toBe("sess-1");
+    expect(body.session.backend).toBe("zedi_managed");
+    // 4 DB chains: 3 access checks + 1 insert.
+    expect(chains.length).toBe(4);
+    expect(chains[3]?.startMethod).toBe("insert");
+  });
+});
+
+describe("GET /api/pages/:pageId/compose-sessions/:id", () => {
+  it("returns 404 when the session row is not found", async () => {
+    const { app } = createComposeApp([
+      ...pageAccessPrefix(),
+      [], // select() returning no rows
+    ]);
+    const res = await app.request(`/api/pages/${PAGE_ID}/compose-sessions/missing`, {
+      headers: authHeaders(),
+    });
+    expect(res.status).toBe(404);
+  });
+
+  it("returns the session row when found", async () => {
+    const row = {
+      id: "sess-2",
+      pageId: PAGE_ID,
+      userId: OWNER_ID,
+      graphId: GRAPH_ID,
+      phase: "init",
+      backend: "zedi_managed",
+      status: "pending",
+      metadata: null,
+      lastError: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+      closedAt: null,
+    };
+    const { app } = createComposeApp([...pageAccessPrefix(), [row]]);
+    const res = await app.request(`/api/pages/${PAGE_ID}/compose-sessions/sess-2`, {
+      headers: authHeaders(),
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { session: { id: string } };
+    expect(body.session.id).toBe("sess-2");
+  });
+});
+
+describe("DELETE /api/pages/:pageId/compose-sessions/:id", () => {
+  it("returns 404 when the session does not exist", async () => {
+    const { app } = createComposeApp([...pageAccessPrefix(), []]);
+    const res = await app.request(`/api/pages/${PAGE_ID}/compose-sessions/none`, {
+      method: "DELETE",
+      headers: authHeaders(),
+    });
+    expect(res.status).toBe(404);
+  });
+
+  it("is a no-op when the session is already completed", async () => {
+    const { app, chains } = createComposeApp([
+      ...pageAccessPrefix(),
+      [{ id: "sess-x", status: "completed" }],
+    ]);
+    const res = await app.request(`/api/pages/${PAGE_ID}/compose-sessions/sess-x`, {
+      method: "DELETE",
+      headers: authHeaders(),
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { status: string };
+    expect(body.status).toBe("completed");
+    // 4 chains: 3 page-access + 1 select. No update chain triggered.
+    expect(chains.filter((c) => c.startMethod === "update").length).toBe(0);
+  });
+
+  it("returns 400 when resume revalidates an unsupported backend", async () => {
+    const interruptedRow = {
+      id: "sess-resume-backend",
+      pageId: PAGE_ID,
+      userId: OWNER_ID,
+      graphId: GRAPH_ID,
+      phase: "init",
+      backend: "byok",
+      status: "interrupted",
+      metadata: null,
+      lastError: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+      closedAt: null,
+    };
+    const { app, chains } = createComposeApp([...pageAccessPrefix(), [interruptedRow]]);
+
+    const res = await app.request(
+      `/api/pages/${PAGE_ID}/compose-sessions/sess-resume-backend/resume`,
+      {
+        method: "PATCH",
+        headers: authHeaders(),
+        body: JSON.stringify({ resume: { ok: true } }),
+      },
+    );
+    expect(res.status).toBe(400);
+    expect(chains.filter((c) => c.startMethod === "update").length).toBe(0);
+  });
+
+  it("marks session failed when resume throws GraphNotRegisteredError", async () => {
+    const interruptedRow = {
+      id: "sess-resume-fail",
+      pageId: PAGE_ID,
+      userId: OWNER_ID,
+      graphId: "graph-removed",
+      phase: "init",
+      backend: "zedi_managed",
+      status: "interrupted",
+      metadata: null,
+      lastError: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+      closedAt: null,
+    };
+    const { app, chains } = createComposeApp([
+      ...pageAccessPrefix(),
+      [interruptedRow],
+      [interruptedRow], // atomic claim → running
+      [], // GraphNotRegisteredError recovery → failed update (no row if already terminal)
+    ]);
+
+    const res = await app.request(
+      `/api/pages/${PAGE_ID}/compose-sessions/sess-resume-fail/resume`,
+      {
+        method: "PATCH",
+        headers: authHeaders(),
+        body: JSON.stringify({ resume: { ok: true } }),
+      },
+    );
+    expect(res.status).toBe(400);
+
+    const failedUpdate = chains
+      .filter((c) => c.startMethod === "update")
+      .map((c) => c.ops.find((op) => op.method === "set")?.args[0] as { status?: string })
+      .find((set) => set?.status === "failed");
+    expect(failedUpdate?.status).toBe("failed");
+  });
+
+  it("cancels an active session", async () => {
+    const { app, chains } = createComposeApp([
+      ...pageAccessPrefix(),
+      [{ id: "sess-y", status: "running" }],
+      [{ status: "cancelled" }], // guarded update → returning
+    ]);
+    const res = await app.request(`/api/pages/${PAGE_ID}/compose-sessions/sess-y`, {
+      method: "DELETE",
+      headers: authHeaders(),
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { status: string };
+    expect(body.status).toBe("cancelled");
+    const updateChain = chains.find((c) => c.startMethod === "update");
+    const setOp = updateChain?.ops.find((op) => op.method === "set");
+    expect((setOp?.args[0] as { status?: string })?.status).toBe("cancelled");
+  });
+
+  it("does not overwrite completed when cancel races with graph finish", async () => {
+    const { app, chains } = createComposeApp([
+      ...pageAccessPrefix(),
+      [{ id: "sess-race", status: "running" }],
+      [], // guarded cancel update — no row (status already completed)
+      [{ status: "completed" }], // re-read after failed cancel
+    ]);
+    const res = await app.request(`/api/pages/${PAGE_ID}/compose-sessions/sess-race`, {
+      method: "DELETE",
+      headers: authHeaders(),
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { status: string };
+    expect(body.status).toBe("completed");
+    expect(chains.filter((c) => c.startMethod === "update").length).toBe(1);
+  });
+});
diff --git a/server/api/src/__tests__/services/ingestPlanner.test.ts b/server/api/src/__tests__/services/ingestPlanner.test.ts
index 7c3e9afe..91d7339b 100644
--- a/server/api/src/__tests__/services/ingestPlanner.test.ts
+++ b/server/api/src/__tests__/services/ingestPlanner.test.ts
@@ -9,6 +9,7 @@ import {
   extractJsonFromResponse,
   IngestPlanParseError,
   parseIngestPlanResponse,
+  parseIngestPlanValue,
   planIngest,
   type CallProviderAdapter,
   type CandidatePage,
@@ -57,6 +58,16 @@ describe("extractJsonFromResponse", () => {
   });
 });
 
+describe("parseIngestPlanValue", () => {
+  it("validates structured objects without JSON round-trip", () => {
+    const plan = parseIngestPlanValue({
+      action: "skip",
+      reason: "no value",
+    });
+    expect(plan.action).toBe("skip");
+  });
+});
+
 describe("parseIngestPlanResponse", () => {
   const validIds = new Set(sampleCandidates.map((c) => c.id));
 
diff --git a/server/api/src/__tests__/services/userAiCredentialCrypto.test.ts b/server/api/src/__tests__/services/userAiCredentialCrypto.test.ts
new file mode 100644
index 00000000..bd93fe7b
--- /dev/null
+++ b/server/api/src/__tests__/services/userAiCredentialCrypto.test.ts
@@ -0,0 +1,36 @@
+import { describe, expect, it, beforeEach, afterEach } from "vitest";
+import {
+  decryptUserAiCredential,
+  encryptUserAiCredential,
+  resetUserAiCredentialEncryptionKeyCache,
+} from "../../services/userAiCredentialCrypto.js";
+
+/** 32-byte test key (hex). */
+const TEST_KEY_HEX = "a".repeat(64);
+
+describe("userAiCredentialCrypto", () => {
+  beforeEach(() => {
+    resetUserAiCredentialEncryptionKeyCache();
+    process.env.USER_AI_CREDENTIALS_ENCRYPTION_KEY = TEST_KEY_HEX;
+  });
+
+  afterEach(() => {
+    delete process.env.USER_AI_CREDENTIALS_ENCRYPTION_KEY;
+    resetUserAiCredentialEncryptionKeyCache();
+  });
+
+  it("round-trips encrypt and decrypt", () => {
+    const plain = "sk-test-key-12345";
+    const blob = encryptUserAiCredential(plain);
+    expect(blob).not.toContain(plain);
+    expect(decryptUserAiCredential(blob)).toBe(plain);
+  });
+
+  it("produces distinct ciphertext for the same plaintext", () => {
+    const a = encryptUserAiCredential("same");
+    const b = encryptUserAiCredential("same");
+    expect(a).not.toBe(b);
+    expect(decryptUserAiCredential(a)).toBe("same");
+    expect(decryptUserAiCredential(b)).toBe("same");
+  });
+});
diff --git a/server/api/src/__tests__/services/wikiSearchService.test.ts b/server/api/src/__tests__/services/wikiSearchService.test.ts
new file mode 100644
index 00000000..bf8315e9
--- /dev/null
+++ b/server/api/src/__tests__/services/wikiSearchService.test.ts
@@ -0,0 +1,115 @@
+/**
+ * `searchUserWikiPages` unit tests using the proxy mock DB. We assert:
+ * - Empty query returns `[]` without touching the DB.
+ * - `scope="own"` calls `getDefaultNoteOrNull` and short-circuits when null.
+ * - `scope="shared"` runs the user-scoped SQL and maps rows to `WikiSearchHit`.
+ * - `limit` is clamped to 1..100.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { getDefaultNoteOrNull } = vi.hoisted(() => ({ getDefaultNoteOrNull: vi.fn() }));
+
+vi.mock("../../services/defaultNoteService.js", () => ({
+  getDefaultNoteOrNull: (...args: unknown[]) =>
+    getDefaultNoteOrNull(
+      ...(args as Parameters<
+        typeof import("../../services/defaultNoteService.js").getDefaultNoteOrNull
+      >),
+    ),
+}));
+
+import { searchUserWikiPages } from "../../services/wikiSearchService.js";
+import { createMockDb } from "../createMockDb.js";
+import type { Database } from "../../types/index.js";
+
+beforeEach(() => {
+  getDefaultNoteOrNull.mockReset();
+});
+afterEach(() => {
+  getDefaultNoteOrNull.mockReset();
+});
+
+describe("searchUserWikiPages", () => {
+  it("returns [] for empty query without DB access", async () => {
+    const { db, chains } = createMockDb([]);
+    const out = await searchUserWikiPages(
+      db as unknown as Database,
+      "u-1",
+      null,
+      "  ",
+      "shared",
+      10,
+    );
+    expect(out).toEqual([]);
+    expect(chains.length).toBe(0);
+    expect(getDefaultNoteOrNull).not.toHaveBeenCalled();
+  });
+
+  it("scope=own short-circuits when there is no default note", async () => {
+    getDefaultNoteOrNull.mockResolvedValueOnce(null);
+    const { db, chains } = createMockDb([]);
+    const out = await searchUserWikiPages(db as unknown as Database, "u-1", null, "x", "own", 10);
+    expect(out).toEqual([]);
+    expect(chains.length).toBe(0);
+  });
+
+  it("scope=shared executes the SQL and maps rows", async () => {
+    const rows = {
+      rows: [
+        {
+          id: "page-1",
+          note_id: "note-1",
+          title: "T1",
+          content_preview: "P1",
+          updated_at: "2026-01-01T00:00:00Z",
+        },
+        {
+          id: "page-2",
+          note_id: "note-2",
+          title: null,
+          content_preview: null,
+          updated_at: "2026-01-02T00:00:00Z",
+        },
+      ],
+    };
+    const { db, chains } = createMockDb([rows]);
+    const out = await searchUserWikiPages(
+      db as unknown as Database,
+      "u-1",
+      "alice@example.com",
+      "alpha",
+      "shared",
+      5,
+    );
+    expect(chains.length).toBe(1);
+    expect(chains[0]?.startMethod).toBe("execute");
+    expect(out).toEqual([
+      {
+        pageId: "page-1",
+        noteId: "note-1",
+        title: "T1",
+        contentPreview: "P1",
+        updatedAt: "2026-01-01T00:00:00Z",
+      },
+      {
+        pageId: "page-2",
+        noteId: "note-2",
+        title: null,
+        contentPreview: null,
+        updatedAt: "2026-01-02T00:00:00Z",
+      },
+    ]);
+  });
+
+  it("clamps limit to 1..100", async () => {
+    getDefaultNoteOrNull.mockResolvedValueOnce({ id: "n-default" });
+    const { db } = createMockDb([{ rows: [] }]);
+    await searchUserWikiPages(db as unknown as Database, "u-1", null, "x", "own", 9999);
+    // No throw is the assertion here; the proxy mock doesn't expose the SQL
+    // template's bound `limit` directly, but `safeLimit` is computed before the
+    // query is issued so this exercises the clamping branch.
+    // clamp は execute 前に評価される。proxy mock では bind 値を読み出せないため、
+    // 例外が出ないことだけ確認する。
+    expect(true).toBe(true);
+  });
+});
diff --git a/server/api/src/agents/core/checkpoint/index.ts b/server/api/src/agents/core/checkpoint/index.ts
new file mode 100644
index 00000000..6bd832e0
--- /dev/null
+++ b/server/api/src/agents/core/checkpoint/index.ts
@@ -0,0 +1,41 @@
+/**
+ * Resolve a LangGraph checkpointer for a compose-session run.
+ *
+ * P0 でルートが checkpointer を取得する際の単一入口。本番 (Railway) では
+ * `DATABASE_URL` / `POSTGRES_URL` が必ず設定されているため `PostgresSaver` を
+ * 返し、テストや CI のように DB 接続情報が無い環境では `false` を返して
+ * LangGraph の checkpoint 機構を無効化する。
+ *
+ * Returns either the process-wide `PostgresSaver` (when a DATABASE_URL is
+ * available) or `false`. The route layer passes the result through to
+ * `GraphRunner`, which forwards it to `StateGraph.compile({ checkpointer })`.
+ * `false` keeps tests and the smoke-test path runnable without DDL.
+ *
+ * Issue: otomatty/zedi#948
+ */
+import type { BaseCheckpointSaver } from "@langchain/langgraph";
+import {
+  ensurePostgresCheckpointerSetup,
+  getPostgresCheckpointer,
+} from "./postgresCheckpointer.js";
+
+/**
+ * `DATABASE_URL` または `POSTGRES_URL` が設定されているなら `PostgresSaver` を
+ * 返し、`setup()` をプロセス内で 1 度だけ実行する。未設定なら `false`。
+ *
+ * Returns the singleton `PostgresSaver` when a DB connection string is
+ * available (and ensures `setup()` has run); otherwise returns `false` to opt
+ * out of checkpointing.
+ */
+export async function resolveCheckpointerForRun(): Promise<BaseCheckpointSaver | false> {
+  if (!process.env.DATABASE_URL && !process.env.POSTGRES_URL) {
+    return false;
+  }
+  await ensurePostgresCheckpointerSetup();
+  return getPostgresCheckpointer();
+}
+
+export {
+  ensurePostgresCheckpointerSetup,
+  getPostgresCheckpointer,
+} from "./postgresCheckpointer.js";
diff --git a/server/api/src/agents/core/checkpoint/postgresCheckpointer.ts b/server/api/src/agents/core/checkpoint/postgresCheckpointer.ts
new file mode 100644
index 00000000..50824f56
--- /dev/null
+++ b/server/api/src/agents/core/checkpoint/postgresCheckpointer.ts
@@ -0,0 +1,78 @@
+/**
+ * `PostgresSaver` wrapper for the Wiki Compose graph runtime.
+ *
+ * LangGraph 公式の `PostgresSaver` を Zedi が使う 1 つの connection string に
+ * 束ねるだけの薄いラッパー。`checkpoints` / `checkpoint_blobs` / `checkpoint_writes`
+ * の 3 テーブルは `setup()` が動的に作る (U4 で別管理)。本ラッパーは
+ * `DATABASE_URL` または `POSTGRES_URL` から接続文字列を取得し、プロセスローカル
+ * にシングルトンを保持する。
+ *
+ * Singleton wrapper around LangGraph's `PostgresSaver`. The saver owns its own
+ * `checkpoints*` tables — they are created by `setup()` and intentionally are
+ * NOT part of Drizzle's migration set, so Drizzle never tries to diff them.
+ */
+import { PostgresSaver } from "@langchain/langgraph-checkpoint-postgres";
+
+let cached: PostgresSaver | null = null;
+let setupOnce: Promise<void> | null = null;
+
+/**
+ * `DATABASE_URL` (preferred) or `POSTGRES_URL` を返す。両方未設定なら例外。
+ *
+ * Return the Postgres connection string used by the rest of the API. Throws
+ * when neither variable is set so misconfigured deployments fail loudly
+ * instead of silently writing to an in-memory store.
+ */
+function readConnectionString(): string {
+  const value = process.env.DATABASE_URL ?? process.env.POSTGRES_URL;
+  if (!value || !value.trim()) {
+    throw new Error("DATABASE_URL or POSTGRES_URL must be set to use PostgresSaver");
+  }
+  return value;
+}
+
+/**
+ * `PostgresSaver` を `(プロセス, schema)` 単位でシングルトン化する。
+ *
+ * Returns a process-wide singleton `PostgresSaver`. `setup()` is intentionally
+ * NOT awaited here — callers that need DDL applied should call
+ * {@link ensurePostgresCheckpointerSetup} once at boot. Keeping creation
+ * separate from setup means tests can construct the saver without touching the
+ * database.
+ *
+ * @param schema  Postgres schema for checkpoint tables (default "public").
+ */
+export function getPostgresCheckpointer(schema: string = "public"): PostgresSaver {
+  if (cached) return cached;
+  cached = PostgresSaver.fromConnString(readConnectionString(), { schema });
+  return cached;
+}
+
+/**
+ * `PostgresSaver.setup()` をプロセス内で 1 度だけ実行する。複数の compose
+ * セッションが並行起動しても DDL は 1 回しか走らない。
+ *
+ * Idempotent `setup()` runner. Subsequent calls return the cached promise so
+ * concurrent compose-session starts do not race to create the checkpoint
+ * tables.
+ */
+export async function ensurePostgresCheckpointerSetup(schema: string = "public"): Promise<void> {
+  if (!setupOnce) {
+    const saver = getPostgresCheckpointer(schema);
+    setupOnce = saver.setup().catch((error: unknown) => {
+      setupOnce = null;
+      throw error;
+    });
+  }
+  return setupOnce;
+}
+
+/**
+ * テスト用にキャッシュを破棄する。本番コードからは呼ばない。
+ *
+ * Drops the cached singleton. Test-only.
+ */
+export function __resetPostgresCheckpointerForTests(): void {
+  cached = null;
+  setupOnce = null;
+}
diff --git a/server/api/src/agents/core/composeBackendValidation.ts b/server/api/src/agents/core/composeBackendValidation.ts
new file mode 100644
index 00000000..b2856532
--- /dev/null
+++ b/server/api/src/agents/core/composeBackendValidation.ts
@@ -0,0 +1,48 @@
+/**
+ * Pre-flight BYOK checks for Wiki Compose session creation (#951).
+ * Wiki Compose セッション作成前の BYOK 事前チェック（#951）。
+ *
+ * Static env model ids are not validated here — provider matching is enforced at
+ * runtime via {@link resolveComposeModelId}. This function only verifies that
+ * the user has a stored credential when the graph will call an LLM.
+ *
+ * 静的 env モデル id との provider 照合は行わない。実行時の
+ * `resolveComposeModelId` が provider 整合を担保する。本関数は LLM を呼ぶ
+ * グラフで credential が存在するかだけを確認する。
+ */
+import { HTTPException } from "hono/http-exception";
+import type { Database, UserTier } from "../../types/index.js";
+import { getComposeModelIdsForGraph } from "./composeModelConfig.js";
+import {
+  backendToCredentialProvider,
+  isUserByokBackend,
+  type ExecutionBackend,
+} from "./types/executionBackend.js";
+import { getUserAiCredentialPlaintext } from "../../services/userAiCredentialService.js";
+
+/**
+ * Ensure a BYOK backend has stored credentials when the target graph uses LLMs.
+ * LLM を使うグラフ向け BYOK backend に credential が存在するか検証する。
+ */
+export async function assertComposeBackendReady(input: {
+  backend: ExecutionBackend;
+  graphId: string;
+  userId: string;
+  tier: UserTier;
+  db: Database;
+}): Promise<void> {
+  if (!isUserByokBackend(input.backend)) return;
+
+  const modelIds = getComposeModelIdsForGraph(input.graphId);
+  // Model-less graphs (e.g. wiki-maintenance) never call `createZediChatModel`.
+  // LLM を呼ばないグラフ（wiki-maintenance 等）は credential 不要。
+  if (modelIds.length === 0) return;
+
+  const expectedProvider = backendToCredentialProvider(input.backend);
+  const key = await getUserAiCredentialPlaintext(input.userId, expectedProvider, input.db);
+  if (!key?.trim()) {
+    throw new HTTPException(400, {
+      message: `No API credential configured for backend "${input.backend}"`,
+    });
+  }
+}
diff --git a/server/api/src/agents/core/composeModelConfig.test.ts b/server/api/src/agents/core/composeModelConfig.test.ts
new file mode 100644
index 00000000..33b65561
--- /dev/null
+++ b/server/api/src/agents/core/composeModelConfig.test.ts
@@ -0,0 +1,12 @@
+/**
+ * `getComposeModelIdsForGraph` unit tests — BYOK validation inputs (#953).
+ */
+import { describe, expect, it } from "vitest";
+import { getComposeModelIdsForGraph } from "./composeModelConfig.js";
+import { WIKI_MAINTENANCE_GRAPH_ID } from "../graphs/wikiMaintenance/index.js";
+
+describe("getComposeModelIdsForGraph", () => {
+  it("returns no model ids for wiki-maintenance (lint-only graph)", () => {
+    expect(getComposeModelIdsForGraph(WIKI_MAINTENANCE_GRAPH_ID)).toEqual([]);
+  });
+});
diff --git a/server/api/src/agents/core/composeModelConfig.ts b/server/api/src/agents/core/composeModelConfig.ts
new file mode 100644
index 00000000..e635bb1e
--- /dev/null
+++ b/server/api/src/agents/core/composeModelConfig.ts
@@ -0,0 +1,34 @@
+/**
+ * Resolve LLM model row ids used by Wiki Compose graphs (for BYOK validation).
+ * Wiki Compose グラフが使うモデル行 ID を解決する（BYOK 検証用）。
+ */
+import { WIKI_COMPOSE_GRAPH_ID } from "../graphs/wikiCompose/index.js";
+import { WIKI_MAINTENANCE_GRAPH_ID } from "../graphs/wikiMaintenance/index.js";
+import { getOrchestratorModelId } from "../subgraphs/research/nodes/planQueries.js";
+import { RESEARCH_GRAPH_ID } from "../subgraphs/research/index.js";
+import { INGEST_PLANNER_GRAPH_ID } from "../graphs/ingest/index.js";
+
+const DRAFT_MODEL_ENV = "WIKI_COMPOSE_DRAFT_MODEL_ID";
+const DRAFT_MODEL_FALLBACK = "claude-3-5-sonnet";
+
+function getDraftModelId(): string {
+  return process.env[DRAFT_MODEL_ENV]?.trim() || DRAFT_MODEL_FALLBACK;
+}
+
+/**
+ * Model row ids (`ai_models.id`) that a compose graph run will call via `createZediChatModel`.
+ * `createZediChatModel` 経由で呼ばれるモデル行 ID 一覧。
+ */
+export function getComposeModelIdsForGraph(graphId: string): string[] {
+  // Lint-only graph — no `createZediChatModel` calls; BYOK must not require orchestrator keys.
+  if (graphId === WIKI_MAINTENANCE_GRAPH_ID) return [];
+  if (graphId === WIKI_COMPOSE_GRAPH_ID) {
+    const orchestrator = getOrchestratorModelId();
+    const draft = getDraftModelId();
+    return orchestrator === draft ? [orchestrator] : [orchestrator, draft];
+  }
+  if (graphId === RESEARCH_GRAPH_ID || graphId === INGEST_PLANNER_GRAPH_ID) {
+    return [getOrchestratorModelId()];
+  }
+  return [getOrchestratorModelId()];
+}
diff --git a/server/api/src/agents/core/llm/modelFactory.ts b/server/api/src/agents/core/llm/modelFactory.ts
new file mode 100644
index 00000000..be9f4883
--- /dev/null
+++ b/server/api/src/agents/core/llm/modelFactory.ts
@@ -0,0 +1,177 @@
+/**
+ * Build a {@link ZediChatModel} for a Wiki Compose run.
+ *
+ * 1 つの compose セッションぶんの `ZediChatModel` を組み立てるファクトリ。
+ * `validateModelAccess` で tier ゲートと cost 単価を解決し、backend に応じて
+ * API キーを解決して `ZediChatModel` に注入する。
+ *
+ * Resolves model access (tier check + cost units) and provider credentials,
+ * then constructs a `ZediChatModel`. Centralising this lets BYOK paths branch in
+ * one place instead of every subgraph.
+ */
+import { getProviderApiKeyName } from "../../../services/aiProviders.js";
+import { getUserAiCredentialPlaintext } from "../../../services/userAiCredentialService.js";
+import { validateModelAccess } from "../../../services/usageService.js";
+import type { AIProviderType, ApiMode, Database, UserTier } from "../../../types/index.js";
+import {
+  backendToCredentialProvider,
+  isExecutionBackend,
+  isUserByokBackend,
+  SUPPORTED_COMPOSE_BACKENDS,
+  type ExecutionBackend,
+} from "../types/executionBackend.js";
+import { ZediChatModel, type ExtraProviderOptions } from "./zediChatModel.js";
+
+/**
+ * `createZediChatModel` の入力。
+ * Input for {@link createZediChatModel}.
+ */
+export interface CreateZediChatModelInput {
+  modelId: string;
+  userId: string;
+  tier: UserTier;
+  db: Database;
+  feature: string;
+  backend: ExecutionBackend;
+  apiKey?: string;
+  temperature?: number;
+  maxTokens?: number;
+  extraProviderOptions?: ExtraProviderOptions;
+}
+
+/**
+ * Thrown when a caller hands in a backend that is not yet wired up.
+ * 未対応 backend が渡されたときに投げる。
+ */
+export class UnsupportedBackendError extends Error {
+  readonly code = "UNSUPPORTED_BACKEND";
+  readonly backend: string;
+  constructor(backend: string) {
+    super(`Execution backend "${backend}" is not supported for Wiki Compose.`);
+    this.name = "UnsupportedBackendError";
+    this.backend = backend;
+  }
+}
+
+/**
+ * Thrown when BYOK backend is selected but no credential is stored.
+ * BYOK だが credential 未登録のときに投げる。
+ */
+export class MissingUserCredentialError extends Error {
+  readonly code = "MISSING_USER_CREDENTIAL";
+  readonly backend: ExecutionBackend;
+  constructor(backend: ExecutionBackend) {
+    super(`No API credential configured for backend "${backend}"`);
+    this.name = "MissingUserCredentialError";
+    this.backend = backend;
+  }
+}
+
+/**
+ * Thrown when the model's provider does not match the BYOK backend.
+ * モデル provider と BYOK backend が一致しないときに投げる。
+ */
+export class BackendProviderMismatchError extends Error {
+  readonly code = "BACKEND_PROVIDER_MISMATCH";
+  readonly backend: ExecutionBackend;
+  readonly provider: AIProviderType;
+  constructor(backend: ExecutionBackend, provider: AIProviderType) {
+    super(`Backend "${backend}" does not match model provider "${provider}"`);
+    this.name = "BackendProviderMismatchError";
+    this.backend = backend;
+    this.provider = provider;
+  }
+}
+
+/**
+ * Validate that the requested `backend` is supported for Wiki Compose (#951).
+ */
+export function assertSupportedComposeBackend(backend: string): ExecutionBackend {
+  if (!isExecutionBackend(backend) || !SUPPORTED_COMPOSE_BACKENDS.includes(backend)) {
+    throw new UnsupportedBackendError(backend);
+  }
+  return backend;
+}
+
+/**
+ * @deprecated Use {@link assertSupportedComposeBackend}. Kept for barrel exports.
+ */
+export const assertSupportedBackendP0 = assertSupportedComposeBackend;
+
+/**
+ * Build a {@link ZediChatModel} ready to be plugged into a LangGraph node.
+ */
+export async function createZediChatModel(input: CreateZediChatModelInput): Promise<ZediChatModel> {
+  const backend = assertSupportedComposeBackend(input.backend);
+
+  const modelInfo = await validateModelAccess(input.modelId, input.tier, input.db);
+  const provider = modelInfo.provider as AIProviderType;
+
+  if (isUserByokBackend(backend)) {
+    const expected = backendToCredentialProvider(backend);
+    if (provider !== expected) {
+      throw new BackendProviderMismatchError(backend, provider);
+    }
+  }
+
+  const apiKey = await resolveApiKey({
+    backend,
+    provider,
+    userId: input.userId,
+    db: input.db,
+    overrideKey: input.apiKey,
+  });
+  const apiMode: ApiMode = isUserByokBackend(backend) ? "user_key" : "system";
+
+  return new ZediChatModel({
+    provider,
+    apiKey,
+    apiModelId: modelInfo.apiModelId,
+    modelRowId: input.modelId,
+    inputCostUnits: modelInfo.inputCostUnits,
+    outputCostUnits: modelInfo.outputCostUnits,
+    userId: input.userId,
+    tier: input.tier,
+    db: input.db,
+    feature: input.feature,
+    apiMode,
+    temperature: input.temperature,
+    maxTokens: input.maxTokens,
+    extraProviderOptions: input.extraProviderOptions,
+  });
+}
+
+interface ResolveApiKeyInput {
+  backend: ExecutionBackend;
+  provider: AIProviderType;
+  userId: string;
+  db: Database;
+  overrideKey: string | undefined;
+}
+
+async function resolveApiKey(input: ResolveApiKeyInput): Promise<string> {
+  const { backend, provider, userId, db, overrideKey } = input;
+
+  if (backend === "zedi_managed") {
+    const envName = getProviderApiKeyName(provider);
+    const key = process.env[envName];
+    if (!key) {
+      throw new Error(`API key not configured: ${envName}`);
+    }
+    return key;
+  }
+
+  if (isUserByokBackend(backend)) {
+    if (overrideKey?.trim()) {
+      return overrideKey.trim();
+    }
+    const credentialProvider = backendToCredentialProvider(backend);
+    const stored = await getUserAiCredentialPlaintext(userId, credentialProvider, db);
+    if (!stored?.trim()) {
+      throw new MissingUserCredentialError(backend);
+    }
+    return stored.trim();
+  }
+
+  throw new UnsupportedBackendError(backend);
+}
diff --git a/server/api/src/agents/core/llm/resolveComposeModelId.ts b/server/api/src/agents/core/llm/resolveComposeModelId.ts
new file mode 100644
index 00000000..77ad8d2e
--- /dev/null
+++ b/server/api/src/agents/core/llm/resolveComposeModelId.ts
@@ -0,0 +1,124 @@
+/**
+ * Resolve `ai_models.id` for Wiki Compose nodes so BYOK backends use a matching provider.
+ *
+ * Wiki Compose の LLM ノード用 model id 解決。BYOK backend では provider が一致する
+ * active モデルを選び、`BackendProviderMismatchError` でセッション全体が落ちるのを防ぐ。
+ */
+import { and, asc, eq } from "drizzle-orm";
+import { aiModels } from "../../../schema/index.js";
+import type { Database, UserTier } from "../../../types/index.js";
+import {
+  backendToCredentialProvider,
+  isUserByokBackend,
+  type ExecutionBackend,
+} from "../types/executionBackend.js";
+import type { UserAiCredentialProvider } from "../../../schema/userAiCredentials.js";
+
+/** Orchestrator nodes (plan / evaluate / refine / brief / structure). */
+export type ComposeModelRole = "orchestrator" | "draft";
+
+const ROLE_ENV: Record<ComposeModelRole, string> = {
+  orchestrator: "WIKI_COMPOSE_ORCHESTRATOR_MODEL_ID",
+  draft: "WIKI_COMPOSE_DRAFT_MODEL_ID",
+};
+
+/** Static fallbacks when the DB has no active row (dev / smoke tests). */
+const ROLE_FALLBACK: Record<
+  ComposeModelRole,
+  Record<UserAiCredentialProvider, string> & { default: string }
+> = {
+  orchestrator: {
+    anthropic: "claude-3-5-haiku",
+    openai: "openai:gpt-4o-mini",
+    google: "google:gemini-2.0-flash",
+    default: "claude-3-5-haiku",
+  },
+  draft: {
+    anthropic: "claude-3-5-sonnet",
+    openai: "openai:gpt-4o-mini",
+    google: "google:gemini-2.0-flash",
+    default: "claude-3-5-sonnet",
+  },
+};
+
+function tierFilter(tier: UserTier) {
+  if (tier === "pro") return undefined;
+  return eq(aiModels.tierRequired, "free");
+}
+
+async function modelIdIfAccessible(
+  db: Database,
+  tier: UserTier,
+  modelId: string,
+  requiredProvider: UserAiCredentialProvider | null,
+): Promise<string | null> {
+  const tierClause = tierFilter(tier);
+  const [row] = await db
+    .select({ id: aiModels.id, provider: aiModels.provider })
+    .from(aiModels)
+    .where(
+      and(
+        eq(aiModels.id, modelId),
+        eq(aiModels.isActive, true),
+        ...(tierClause ? [tierClause] : []),
+      ),
+    )
+    .limit(1);
+  if (!row) return null;
+  if (requiredProvider && row.provider !== requiredProvider) return null;
+  return row.id;
+}
+
+async function cheapestActiveModelId(
+  db: Database,
+  tier: UserTier,
+  provider: UserAiCredentialProvider,
+): Promise<string | null> {
+  const tierClause = tierFilter(tier);
+  const [row] = await db
+    .select({ id: aiModels.id })
+    .from(aiModels)
+    .where(
+      and(
+        eq(aiModels.isActive, true),
+        eq(aiModels.provider, provider),
+        ...(tierClause ? [tierClause] : []),
+      ),
+    )
+    .orderBy(asc(aiModels.inputCostUnits), asc(aiModels.outputCostUnits))
+    .limit(1);
+  return row?.id ?? null;
+}
+
+function requiredProvider(backend: ExecutionBackend): UserAiCredentialProvider | null {
+  if (isUserByokBackend(backend)) {
+    return backendToCredentialProvider(backend);
+  }
+  return null;
+}
+
+/**
+ * Pick an `ai_models.id` for orchestrator or draft nodes.
+ * BYOK: provider must match the session backend; `zedi_managed`: env override or Anthropic default.
+ */
+export async function resolveComposeModelId(
+  role: ComposeModelRole,
+  backend: ExecutionBackend,
+  tier: UserTier,
+  db: Database,
+): Promise<string> {
+  const provider = requiredProvider(backend);
+  const envOverride = process.env[ROLE_ENV[role]]?.trim();
+  if (envOverride) {
+    const resolved = await modelIdIfAccessible(db, tier, envOverride, provider);
+    if (resolved) return resolved;
+  }
+
+  if (provider) {
+    const fromDb = await cheapestActiveModelId(db, tier, provider);
+    if (fromDb) return fromDb;
+    return ROLE_FALLBACK[role][provider];
+  }
+
+  return ROLE_FALLBACK[role].default;
+}
diff --git a/server/api/src/agents/core/llm/usageCallback.ts b/server/api/src/agents/core/llm/usageCallback.ts
new file mode 100644
index 00000000..d023f5ad
--- /dev/null
+++ b/server/api/src/agents/core/llm/usageCallback.ts
@@ -0,0 +1,132 @@
+/**
+ * Usage attribution helpers for `ZediChatModel`.
+ *
+ * `ZediChatModel` の usage 記録ヘルパー。LangGraph 経路でもチャットページと
+ * 同じ `recordUsage` + `calculateCost` を通すための薄いアダプタ。BaseChatModel
+ * の callback 機構を使わずに同期的に呼ぶ理由は、(1) graph 側の retry / 再実行で
+ * cost を二重計上したくない、(2) 計算ロジックを単体テストしやすくするため。
+ *
+ * Thin adapter that routes LangGraph LLM usage through the same
+ * `recordUsage` / `calculateCost` path as the chat endpoint. Kept as a plain
+ * function instead of a LangChain callback so it can be unit-tested without
+ * spinning up the callback system and so retries do not double-count.
+ */
+import type { BaseMessage } from "@langchain/core/messages";
+import { calculateCost, recordUsage } from "../../../services/usageService.js";
+import type {
+  AIMessage as ZediAIMessage,
+  ApiMode,
+  Database,
+  TokenUsage,
+} from "../../../types/index.js";
+
+/**
+ * `recordZediUsage` の入力。
+ * Input for {@link recordZediUsage}.
+ *
+ * @property db          Drizzle DB ハンドル。Drizzle DB handle.
+ * @property userId      実行ユーザー ID。Executing user id.
+ * @property modelId     `ai_models.id`。実モデル行 ID（API モデル名ではない）。
+ *                       Database `ai_models.id` (not the provider model name).
+ * @property feature     `ai_usage_logs.feature` のラベル。`recordUsage` feature label.
+ * @property usage       消費したトークン数。Token consumption.
+ * @property inputCostUnits  モデルの input 単価（1k tokens あたり cost_units）。
+ *                            Per-1k input cost in cost units.
+ * @property outputCostUnits モデルの output 単価（1k tokens あたり cost_units）。
+ *                            Per-1k output cost in cost units.
+ * @property apiMode     "system" / "user_key"。BYOK 導入後は "user_key" を渡す。
+ *                       Future-proof flag for BYOK; pass "system" in P0.
+ */
+export interface RecordZediUsageInput {
+  db: Database;
+  userId: string;
+  modelId: string;
+  feature: string;
+  usage: TokenUsage;
+  inputCostUnits: number;
+  outputCostUnits: number;
+  apiMode: ApiMode;
+}
+
+/**
+ * `recordZediUsage` の結果。クライアントに返したり SSE に流したりするのに使う。
+ * Result of {@link recordZediUsage}; suitable to surface via SSE.
+ */
+export interface RecordZediUsageResult {
+  inputTokens: number;
+  outputTokens: number;
+  costUnits: number;
+}
+
+/**
+ * 1 回の LLM 呼び出しぶんの usage を計算して `ai_usage_logs` と `ai_monthly_usage`
+ * に書き込む。LangGraph 経由でも `/api/ai/chat` と同等の課金を成立させる。
+ *
+ * Compute usage cost for a single LLM invocation and persist it via
+ * `recordUsage`. Used by `ZediChatModel` after each provider call.
+ */
+export async function recordZediUsage(input: RecordZediUsageInput): Promise<RecordZediUsageResult> {
+  const rawCostUnits = calculateCost(input.usage, input.inputCostUnits, input.outputCostUnits);
+  // BYOK (#951): audit usage in logs but do not consume Zedi monthly CU.
+  const costUnits = input.apiMode === "user_key" ? 0 : rawCostUnits;
+  await recordUsage(
+    input.userId,
+    input.modelId,
+    input.feature,
+    input.usage,
+    costUnits,
+    input.apiMode,
+    input.db,
+  );
+  return {
+    inputTokens: input.usage.inputTokens,
+    outputTokens: input.usage.outputTokens,
+    costUnits,
+  };
+}
+
+/**
+ * LangChain の `BaseMessage[]` を Zedi の `AIMessage[]` に変換する。
+ * Convert LangChain `BaseMessage[]` to the legacy `AIMessage[]` shape that
+ * `callProvider` / `streamProvider` expect.
+ *
+ * 既存の `aiProviders` 系 API は `role: "user" | "assistant" | "system"` の
+ * 単純な dict 配列を取るため、本関数で type を取り出して文字列化する。Content が
+ * 配列 (multi-modal) の場合は text ブロックのみ連結し、画像等は将来拡張。
+ *
+ * Until the providers gain multi-modal support, this helper concatenates text
+ * blocks from a `BaseMessage` and drops non-text content blocks.
+ */
+export function toZediMessages(messages: BaseMessage[]): ZediAIMessage[] {
+  return messages.map((m) => {
+    const role = messageTypeToRole(m.getType());
+    return { role, content: stringifyContent(m.content) };
+  });
+}
+
+function messageTypeToRole(type: string): ZediAIMessage["role"] {
+  // LangChain message types: "human" | "ai" | "system" | "tool" | "function" | ...
+  // LangChain のメッセージ型を AIProviders が期待する role 文字列に正規化する。
+  if (type === "system") return "system";
+  if (type === "ai") return "assistant";
+  // Treat tool / function / generic / human messages as user-side input to the
+  // model. The providers do not have a richer notion in P0.
+  // tool / function 等は P0 ではユーザー側入力として扱う。
+  return "user";
+}
+
+function stringifyContent(content: BaseMessage["content"]): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const parts: string[] = [];
+  for (const block of content) {
+    if (typeof block === "string") {
+      parts.push(block);
+    } else if (block && typeof block === "object" && "type" in block && block.type === "text") {
+      // LangChain content blocks: prefer `.text`; fall back to `.value` if present.
+      const text = (block as { text?: unknown }).text;
+      if (typeof text === "string") parts.push(text);
+    }
+  }
+  return parts.join("");
+}
diff --git a/server/api/src/agents/core/llm/zediChatModel.ts b/server/api/src/agents/core/llm/zediChatModel.ts
new file mode 100644
index 00000000..01466e1f
--- /dev/null
+++ b/server/api/src/agents/core/llm/zediChatModel.ts
@@ -0,0 +1,378 @@
+/**
+ * `ZediChatModel` — LangGraph 経路で使う LangChain `BaseChatModel` 実装。
+ *
+ * `ZediChatModel` is the bridge between LangGraph and Zedi's existing
+ * `aiProviders` + `usageService` stack. Every LLM call inside an agent goes
+ * through this class so that:
+ *
+ * 1. `callProvider` / `streamProvider` (legacy) stays the single network
+ *    boundary to OpenAI / Anthropic / Google; the LangGraph layer never holds
+ *    a provider SDK directly.
+ *    全 LLM 呼び出しは `callProvider` / `streamProvider` を通る。LangGraph 層は
+ *    プロバイダ SDK を直接握らない。
+ *
+ * 2. `validateModelAccess` + `recordUsage` are invoked exactly once per call,
+ *    matching the accounting behaviour of `/api/ai/chat` so monthly budgets
+ *    and feature labels stay consistent.
+ *    `/api/ai/chat` と同じく `validateModelAccess` / `recordUsage` を 1 呼び出し
+ *    あたり 1 回ずつ通す。月次予算と feature ラベルの整合性を保証する。
+ *
+ * 3. P0 (#948) supports backend = `zedi_managed` only. BYOK arrives in #951;
+ *    the constructor accepts an `apiKey` opaquely so the future path can
+ *    inject user-supplied credentials without changing the class shape.
+ *    P0 は backend = `zedi_managed` のみサポート。BYOK は #951 で対応するが、
+ *    本クラスは `apiKey` を不透明に受け取る形にして将来差し替え可能にしてある。
+ *
+ * Note on streaming: `_streamResponseChunks` reuses `streamProvider` and
+ * accumulates tokens locally. Usage is recorded after the stream ends with the
+ * cheap `chars/4` token estimator, identical to `routes/ai/chat.ts`. The estimate
+ * is intentionally not pre-billed before the call — we charge on the way out.
+ *
+ * @see {@link callProvider} / {@link streamProvider}
+ * @see https://github.com/otomatty/zedi/issues/948
+ */
+import {
+  BaseChatModel,
+  type BaseChatModelCallOptions,
+  type BaseChatModelParams,
+} from "@langchain/core/language_models/chat_models";
+import type { CallbackManagerForLLMRun } from "@langchain/core/callbacks/manager";
+import type { BaseMessage } from "@langchain/core/messages";
+import { AIMessage, AIMessageChunk } from "@langchain/core/messages";
+import { ChatGenerationChunk, type ChatResult } from "@langchain/core/outputs";
+import { callProvider, streamProvider } from "../../../services/aiProviders.js";
+import { calculateCost } from "../../../services/usageService.js";
+import type {
+  AIChatOptions,
+  AIProviderType,
+  ApiMode,
+  Database,
+  UserTier,
+} from "../../../types/index.js";
+import { recordZediUsage, toZediMessages, type RecordZediUsageResult } from "./usageCallback.js";
+
+/**
+ * `callProvider` / `streamProvider` のインジェクション型。テストでは fake を
+ * 渡し、本番では `aiProviders` から取得した関数をそのまま渡す。
+ *
+ * Pluggable provider callers; tests inject fakes, production wires the real
+ * `callProvider` / `streamProvider`.
+ */
+export interface CallProviderFn {
+  (...args: Parameters<typeof callProvider>): ReturnType<typeof callProvider>;
+}
+export interface StreamProviderFn {
+  (...args: Parameters<typeof streamProvider>): ReturnType<typeof streamProvider>;
+}
+
+/**
+ * `ZediChatModel` を構築するためのパラメータ。
+ * Constructor input for {@link ZediChatModel}.
+ *
+ * @property provider          AIProviderType。OpenAI / Anthropic / Google.
+ * @property apiKey            プロバイダ向け API キー。P0 では `zedi_managed` 鍵が入る。
+ *                             Provider API key (zedi_managed in P0, BYOK in #951).
+ * @property apiModelId        プロバイダ側モデル ID（例: `gpt-4o-mini`）。
+ *                             Provider model id (`ai_models.modelId`).
+ * @property modelRowId        DB 上の `ai_models.id`。`recordUsage` で使う。
+ *                             `ai_models.id` (DB row id) used by `recordUsage`.
+ * @property inputCostUnits    入力 1k tokens あたりの cost units。
+ *                             Input cost units per 1k tokens.
+ * @property outputCostUnits   出力 1k tokens あたりの cost units。
+ *                             Output cost units per 1k tokens.
+ * @property userId            実行ユーザー ID。Executing user id.
+ * @property tier              ユーザー tier（参照用。validate 済みの想定）。User tier (already validated).
+ * @property db                Drizzle DB ハンドル。Drizzle DB handle.
+ * @property feature           `recordUsage` の feature ラベル。`recordUsage` feature label.
+ * @property apiMode           "system" / "user_key"。P0 では "system"。BYOK 時に切替。
+ * @property callProvider      `callProvider` の差し替え（任意）。Optional override.
+ * @property streamProvider    `streamProvider` の差し替え（任意）。Optional override.
+ * @property extraProviderOptions  `callProvider` / `streamProvider` に追加で渡す
+ *                                 オプション。`useWebSearch` / `useGoogleSearch` /
+ *                                 `webSearchOptions` などプロバイダ固有ノブを
+ *                                 LangGraph ノードから通すための薄い pass-through。
+ *                                 Per-provider pass-through options merged into
+ *                                 the `AIChatOptions` bag passed to
+ *                                 `callProvider` / `streamProvider`. Lets nodes
+ *                                 enable provider-side web search etc. without
+ *                                 widening the constructor surface for every
+ *                                 future knob.
+ */
+export interface ZediChatModelParams extends BaseChatModelParams {
+  provider: AIProviderType;
+  apiKey: string;
+  apiModelId: string;
+  modelRowId: string;
+  inputCostUnits: number;
+  outputCostUnits: number;
+  userId: string;
+  tier: UserTier;
+  db: Database;
+  feature: string;
+  apiMode?: ApiMode;
+  callProvider?: CallProviderFn;
+  streamProvider?: StreamProviderFn;
+  /** モデル呼び出しオプション。temperature / maxTokens 等。Provider options. */
+  temperature?: number;
+  maxTokens?: number;
+  extraProviderOptions?: ExtraProviderOptions;
+}
+
+/**
+ * `callProvider` / `streamProvider` に追加で渡すプロバイダ固有オプションの
+ * サブセット。`AIChatOptions` から `feature`/`temperature`/`maxTokens`/`stream`
+ * を除いた pass-through ノブ群（web 検索フラグ等）。
+ *
+ * Subset of {@link AIChatOptions} containing provider-specific knobs that
+ * subgraphs may need to flip per call (e.g. `useWebSearch` for the research
+ * loop's `web_search` tool). Kept narrow so the model class doesn't accept
+ * arbitrary call options that would bypass usage accounting.
+ */
+export type ExtraProviderOptions = Pick<
+  AIChatOptions,
+  "useWebSearch" | "useGoogleSearch" | "webSearchOptions"
+>;
+
+/**
+ * Concrete `BaseChatModel` implementation routing through Zedi providers.
+ * Zedi の providers 経由で呼び出す `BaseChatModel` 実装。
+ */
+export class ZediChatModel extends BaseChatModel<BaseChatModelCallOptions> {
+  /** LangChain serialization namespace. LangChain シリアライズ識別子。 */
+  static lc_name(): string {
+    return "ZediChatModel";
+  }
+
+  private readonly provider: AIProviderType;
+  private readonly apiKey: string;
+  private readonly apiModelId: string;
+  private readonly modelRowId: string;
+  private readonly inputCostUnits: number;
+  private readonly outputCostUnits: number;
+  private readonly userId: string;
+  private readonly tier: UserTier;
+  private readonly db: Database;
+  private readonly feature: string;
+  private readonly apiMode: ApiMode;
+  private readonly callProviderFn: CallProviderFn;
+  private readonly streamProviderFn: StreamProviderFn;
+  private readonly temperature?: number;
+  private readonly maxTokens?: number;
+  private readonly extraProviderOptions?: ExtraProviderOptions;
+
+  constructor(fields: ZediChatModelParams) {
+    super(fields);
+    this.provider = fields.provider;
+    this.apiKey = fields.apiKey;
+    this.apiModelId = fields.apiModelId;
+    this.modelRowId = fields.modelRowId;
+    this.inputCostUnits = fields.inputCostUnits;
+    this.outputCostUnits = fields.outputCostUnits;
+    this.userId = fields.userId;
+    this.tier = fields.tier;
+    this.db = fields.db;
+    this.feature = fields.feature;
+    this.apiMode = fields.apiMode ?? "system";
+    this.callProviderFn = fields.callProvider ?? callProvider;
+    this.streamProviderFn = fields.streamProvider ?? streamProvider;
+    this.temperature = fields.temperature;
+    this.maxTokens = fields.maxTokens;
+    this.extraProviderOptions = fields.extraProviderOptions;
+  }
+
+  /**
+   * LangChain 側のモデル種別識別子。LangSmith 等のトレースで使う。
+   * LangChain `_llmType` identifier.
+   */
+  _llmType(): string {
+    return "zedi-chat";
+  }
+
+  /**
+   * 非ストリーミング呼び出し。`callProvider` → cost 計算 → `recordUsage`。
+   * Non-streaming generation path.
+   */
+  async _generate(
+    messages: BaseMessage[],
+    _options: this["ParsedCallOptions"],
+    runManager?: CallbackManagerForLLMRun,
+  ): Promise<ChatResult> {
+    const zediMessages = toZediMessages(messages);
+    const result = await this.callProviderFn(
+      this.provider,
+      this.apiKey,
+      this.apiModelId,
+      zediMessages,
+      {
+        temperature: this.temperature,
+        maxTokens: this.maxTokens,
+        feature: this.feature,
+        ...this.extraProviderOptions,
+      },
+    );
+
+    const usage = await recordZediUsage({
+      db: this.db,
+      userId: this.userId,
+      modelId: this.modelRowId,
+      feature: this.feature,
+      usage: result.usage,
+      inputCostUnits: this.inputCostUnits,
+      outputCostUnits: this.outputCostUnits,
+      apiMode: this.apiMode,
+    });
+
+    void this.tier;
+    void runManager;
+
+    const aiMessage = new AIMessage({
+      content: result.content,
+      response_metadata: {
+        finishReason: result.finishReason,
+        usage: {
+          inputTokens: usage.inputTokens,
+          outputTokens: usage.outputTokens,
+          costUnits: usage.costUnits,
+        },
+      },
+    });
+
+    return {
+      generations: [
+        {
+          text: result.content,
+          message: aiMessage,
+          generationInfo: { finishReason: result.finishReason },
+        },
+      ],
+      llmOutput: {
+        tokenUsage: {
+          promptTokens: usage.inputTokens,
+          completionTokens: usage.outputTokens,
+          totalTokens: usage.inputTokens + usage.outputTokens,
+        },
+        costUnits: usage.costUnits,
+        finishReason: result.finishReason,
+      },
+    };
+  }
+
+  /**
+   * ストリーミング呼び出し。`streamProvider` の async generator を `ChatGenerationChunk`
+   * に変換しつつ、累積トークンを cost 算出のために保持する。`/api/ai/chat` の挙動
+   * と同じく `chars/4` を fallback 推定とする（プロバイダ側がトークン数を返さない
+   * パスでも課金破綻させない）。
+   *
+   * Streaming generation; mirrors `routes/ai/chat.ts` token-accounting fallback
+   * by estimating with `chars/4` when the provider does not surface usage in a
+   * streaming response.
+   */
+  async *_streamResponseChunks(
+    messages: BaseMessage[],
+    _options: this["ParsedCallOptions"],
+    runManager?: CallbackManagerForLLMRun,
+  ): AsyncGenerator<ChatGenerationChunk> {
+    const zediMessages = toZediMessages(messages);
+    const gen = this.streamProviderFn(this.provider, this.apiKey, this.apiModelId, zediMessages, {
+      temperature: this.temperature,
+      maxTokens: this.maxTokens,
+      feature: this.feature,
+      ...this.extraProviderOptions,
+    });
+
+    let accumulated = "";
+    let finishReason: string | undefined;
+    let done = false;
+
+    for await (const chunk of gen) {
+      if (chunk.content) {
+        accumulated += chunk.content;
+        const chatChunk = new ChatGenerationChunk({
+          text: chunk.content,
+          message: new AIMessageChunk({ content: chunk.content }),
+        });
+        // LangChain callback / SSE 向けにトークン delta を先に流す。
+        // Surface incremental tokens to LangChain callback consumers so any
+        // `streamEvents` listener (e.g. SSE mapper) sees deltas before usage.
+        await runManager?.handleLLMNewToken(
+          chunk.content,
+          undefined,
+          undefined,
+          undefined,
+          undefined,
+          {
+            chunk: chatChunk,
+          },
+        );
+        yield chatChunk;
+      }
+      if (chunk.done) {
+        finishReason = chunk.finishReason;
+        done = true;
+        break;
+      }
+    }
+
+    const promptLength = zediMessages.reduce((sum, m) => sum + m.content.length, 0);
+    const inputTokens = Math.ceil(promptLength / 4);
+    const outputTokens = Math.ceil(accumulated.length / 4);
+
+    let usage: RecordZediUsageResult;
+    if (done) {
+      try {
+        usage = await recordZediUsage({
+          db: this.db,
+          userId: this.userId,
+          modelId: this.modelRowId,
+          feature: this.feature,
+          usage: { inputTokens, outputTokens },
+          inputCostUnits: this.inputCostUnits,
+          outputCostUnits: this.outputCostUnits,
+          apiMode: this.apiMode,
+        });
+      } catch (err) {
+        // Billing failure must not mask a successful stream.
+        // 課金記録失敗で成功ストリームを潰さない。
+        console.error("Failed to record streaming usage", err);
+        usage = {
+          inputTokens,
+          outputTokens,
+          costUnits:
+            this.apiMode === "user_key"
+              ? 0
+              : calculateCost(
+                  { inputTokens, outputTokens },
+                  this.inputCostUnits,
+                  this.outputCostUnits,
+                ),
+        };
+      }
+    } else {
+      // Stream ended without `done` — expose metadata only, no DB billing (chat.ts 同様).
+      // `done` 未到達で終了した incomplete ストリームは DB 課金しない。
+      usage = { inputTokens, outputTokens, costUnits: 0 };
+    }
+
+    // Final chunk surfaces aggregate usage so downstream consumers (sseMapper,
+    // LangChain callbacks) can read totals from a single ChatGenerationChunk.
+    // 集計 usage を最終チャンクで返し、sseMapper 等が 1 箇所から読めるようにする。
+    yield new ChatGenerationChunk({
+      text: "",
+      message: new AIMessageChunk({
+        content: "",
+        response_metadata: {
+          finishReason: finishReason ?? (done ? "stop" : "incomplete"),
+        },
+        usage_metadata: {
+          input_tokens: usage.inputTokens,
+          output_tokens: usage.outputTokens,
+          total_tokens: usage.inputTokens + usage.outputTokens,
+        },
+      }),
+      generationInfo: {
+        finishReason: finishReason ?? (done ? "stop" : "incomplete"),
+        costUnits: usage.costUnits,
+      },
+    });
+  }
+}
diff --git a/server/api/src/agents/core/state/baseState.ts b/server/api/src/agents/core/state/baseState.ts
new file mode 100644
index 00000000..c6cd1b31
--- /dev/null
+++ b/server/api/src/agents/core/state/baseState.ts
@@ -0,0 +1,73 @@
+/**
+ * Base LangGraph state shared by all Wiki Compose subgraphs.
+ *
+ * 全 Wiki Compose subgraph で共通利用する LangGraph state。各 subgraph (#949,
+ * #950, ...) はこの annotation を `Annotation.Root({...BaseState.spec, ...})`
+ * で拡張する想定。messages reducer は `messagesStateReducer` を使い、tool 結果や
+ * ai 応答の追記をフラットに扱う。
+ *
+ * The Wiki Compose family of subgraphs (P1 research, P2 outline, P3 draft …)
+ * all need a messages history plus a few cross-cutting fields. `BaseState`
+ * defines that shared shell; downstream graphs spread its `spec` into their
+ * own `Annotation.Root({...})` to extend it.
+ */
+import { Annotation, messagesStateReducer } from "@langchain/langgraph";
+import type { BaseMessage } from "@langchain/core/messages";
+
+/**
+ * 共通 state スキーマ。
+ * Shared state schema.
+ *
+ * - `messages` — LangGraph 規約に従い、reducer で append する。
+ * - `phase`    — 現在のフェーズ名（subgraph 横断の進行管理）。
+ * - `pageId`   — 対象ページ。サブグラフが書き戻し対象を見失わないために state にも持つ。
+ * - `userId`   — 実行ユーザー。tool が page アクセス権チェックを行う際に参照する。
+ */
+export const BaseState = Annotation.Root({
+  /**
+   * 会話履歴 + tool 結果。`messagesStateReducer` で append マージする。
+   * Conversation + tool messages, accumulated via `messagesStateReducer`.
+   */
+  messages: Annotation<BaseMessage[]>({
+    reducer: messagesStateReducer,
+    default: () => [],
+  }),
+  /**
+   * 現在のフェーズ識別子。subgraph 間遷移で書き換えられる。
+   * Current phase identifier; rewritten when transitioning between subgraphs.
+   */
+  phase: Annotation<string>({
+    reducer: (_prev, next) => next,
+    default: () => "init",
+  }),
+  /**
+   * 対象ページ ID。
+   * Target page id.
+   */
+  pageId: Annotation<string>({
+    reducer: (prev, next) => next ?? prev,
+    default: () => "",
+  }),
+  /**
+   * 実行ユーザー ID。
+   * Executing user id.
+   */
+  userId: Annotation<string>({
+    reducer: (prev, next) => next ?? prev,
+    default: () => "",
+  }),
+});
+
+/**
+ * `BaseState` の `State` 型エイリアス。subgraph 側でも `typeof BaseState.State` で
+ * 取得できるが、よく使うため再 export する。
+ *
+ * Convenience type alias for `typeof BaseState.State`.
+ */
+export type BaseStateType = typeof BaseState.State;
+
+/**
+ * `BaseState` の `Update` 型エイリアス。ノードの返却型として使う。
+ * Convenience type alias for `typeof BaseState.Update`.
+ */
+export type BaseStateUpdate = typeof BaseState.Update;
diff --git a/server/api/src/agents/core/tools/fetchArticle.ts b/server/api/src/agents/core/tools/fetchArticle.ts
new file mode 100644
index 00000000..b7c316b3
--- /dev/null
+++ b/server/api/src/agents/core/tools/fetchArticle.ts
@@ -0,0 +1,104 @@
+/**
+ * `fetch_article` tool — fetches and Readability-extracts a URL into a
+ * preview-sized excerpt.
+ *
+ * LangGraph tool wrapping {@link extractArticleFromUrl}. SSRF-guarded with the
+ * same `isClipUrlAllowedAfterDns` check that `/api/clip` and `clipServerFetch`
+ * use. Returns a JSON-stringified envelope `{ ok, ...fields | error }`. Errors
+ * (block, fetch timeout, parse failure) never throw — the caller node maps
+ * `ok:false` to a removed source so a single bad URL does not abort the
+ * research iteration.
+ *
+ * `extractArticleFromUrl` を tool 化した版。SSRF 防御は `clipUrlPolicy` の
+ * `isClipUrlAllowedAfterDns` を流用する。失敗時は `{ ok:false, error }` を
+ * JSON 文字列で返す（throw しない）ことで、調査ループの 1 イテレーションが
+ * 1 件の URL 不調で停止しないようにする。
+ */
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+import { extractArticleFromUrl, ClipFetchBlockedError } from "../../../lib/articleExtractor.js";
+import { isClipUrlAllowedAfterDns } from "../../../lib/clipUrlPolicy.js";
+
+/** Tool name. */
+export const FETCH_ARTICLE_TOOL_NAME = "fetch_article" as const;
+
+/**
+ * Input schema. URL は http/https のみ。previewLength は 500〜8000。
+ * Input schema; URL must be http/https, `previewLength` clamps to 500..8000.
+ */
+export const fetchArticleInputSchema = z.object({
+  url: z
+    .string()
+    .url()
+    .refine((u) => /^https?:\/\//i.test(u), "URL must use http or https")
+    .describe("Article URL. 記事 URL。"),
+  previewLength: z
+    .number()
+    .int()
+    .min(500)
+    .max(8000)
+    .optional()
+    .describe("Extracted excerpt length (default 4000). 抜粋長 (既定 4000)。"),
+});
+
+/**
+ * 成功時 JSON 包絡型。失敗時は `{ ok:false, error }` で返す。
+ *
+ * Success envelope; failure shape is `{ ok:false, error }`. The caller node
+ * always `JSON.parse`s and branches on `ok`.
+ */
+interface FetchArticleSuccess {
+  ok: true;
+  url: string;
+  finalUrl: string;
+  title: string;
+  excerpt: string;
+  contentHash: string;
+  thumbnailUrl: string | null;
+}
+
+interface FetchArticleFailure {
+  ok: false;
+  url: string;
+  error: string;
+}
+
+export const fetchArticleTool = tool(
+  async (input) => {
+    const url = input.url;
+    const previewLength = input.previewLength ?? 4000;
+    if (!(await isClipUrlAllowedAfterDns(url))) {
+      const fail: FetchArticleFailure = { ok: false, url, error: "url_blocked" };
+      return JSON.stringify(fail);
+    }
+    try {
+      const article = await extractArticleFromUrl({ url, previewLength });
+      const ok: FetchArticleSuccess = {
+        ok: true,
+        url,
+        finalUrl: article.finalUrl,
+        title: article.title,
+        excerpt: article.contentText,
+        contentHash: article.contentHash,
+        thumbnailUrl: article.thumbnailUrl,
+      };
+      return JSON.stringify(ok);
+    } catch (err) {
+      const error =
+        err instanceof ClipFetchBlockedError
+          ? "url_blocked"
+          : err instanceof Error
+            ? err.message
+            : String(err);
+      const fail: FetchArticleFailure = { ok: false, url, error };
+      return JSON.stringify(fail);
+    }
+  },
+  {
+    name: FETCH_ARTICLE_TOOL_NAME,
+    description:
+      "Fetch and extract the main article body from a URL. Returns title, content, and source metadata. " +
+      "URL から本文を抽出し、タイトル・本文・メタ情報を返す。",
+    schema: fetchArticleInputSchema,
+  },
+);
diff --git a/server/api/src/agents/core/tools/imageSearch.ts b/server/api/src/agents/core/tools/imageSearch.ts
new file mode 100644
index 00000000..e43b748d
--- /dev/null
+++ b/server/api/src/agents/core/tools/imageSearch.ts
@@ -0,0 +1,46 @@
+/**
+ * `image_search` tool stub.
+ *
+ * Wiki Compose の thumbnail 提案フェーズ向け画像検索 tool。実装は `services/imageSearch.ts`
+ * の Google Custom Search 経由に置き換え予定。P0 はスキーマと名前だけ確定する。
+ *
+ * Image search tool stub. Real implementation will reuse `services/imageSearch.ts`
+ * (Google Custom Search). P0 only nails down name + schema.
+ */
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+
+/** Tool name. */
+export const IMAGE_SEARCH_TOOL_NAME = "image_search" as const;
+
+const STUB_RESPONSE_PREFIX = "IMAGE_SEARCH_NOT_IMPLEMENTED";
+
+/**
+ * Input schema. `query` 必須、`limit` 1〜10、`page` 1〜10。
+ * Input schema.
+ */
+export const imageSearchInputSchema = z.object({
+  query: z.string().min(1).describe("Image search query. 画像検索クエリ。"),
+  limit: z.number().int().min(1).max(10).optional().describe("Max results. 最大件数。"),
+  page: z.number().int().min(1).max(10).optional().describe("Page number. ページ番号。"),
+});
+
+/**
+ * P0 stub. Real implementation reads `GOOGLE_CSE_API_KEY` /
+ * `GOOGLE_CSE_ENGINE_ID` (matching `services/imageSearch.ts`).
+ *
+ * P0 スタブ。実装は既存の Google CSE 環境変数を流用する。
+ */
+export const imageSearchTool = tool(
+  async (input) => {
+    const summary = `${STUB_RESPONSE_PREFIX} query=${JSON.stringify(input.query)}`;
+    return summary;
+  },
+  {
+    name: IMAGE_SEARCH_TOOL_NAME,
+    description:
+      "Search images for a query and return preview URLs + source attribution. " +
+      "画像を検索しプレビュー URL と帰属情報を返す。",
+    schema: imageSearchInputSchema,
+  },
+);
diff --git a/server/api/src/agents/core/tools/index.ts b/server/api/src/agents/core/tools/index.ts
new file mode 100644
index 00000000..687a0c22
--- /dev/null
+++ b/server/api/src/agents/core/tools/index.ts
@@ -0,0 +1,36 @@
+/**
+ * Tool registry for Wiki Compose subgraphs.
+ *
+ * 全 subgraph で共有する LangGraph tool 一式。subgraph は本ファイルから tool を
+ * import し、`model.bindTools([...])` で束ねて利用する。各 tool の本体は P0 では
+ * スタブだが、bind 経路と zod schema は実装と同じ形に固定してある。
+ *
+ * Aggregate barrel exposing the shared tool set. Subgraphs import individual
+ * tools from here and bind them with `bindTools`. P0 ships stubs; the schemas
+ * are frozen so swapping in real implementations is non-breaking.
+ */
+export { WEB_SEARCH_TOOL_NAME, webSearchInputSchema, webSearchTool } from "./webSearch.js";
+export { WIKI_SEARCH_TOOL_NAME, wikiSearchInputSchema, wikiSearchTool } from "./wikiSearch.js";
+export {
+  FETCH_ARTICLE_TOOL_NAME,
+  fetchArticleInputSchema,
+  fetchArticleTool,
+} from "./fetchArticle.js";
+export { IMAGE_SEARCH_TOOL_NAME, imageSearchInputSchema, imageSearchTool } from "./imageSearch.js";
+
+import { webSearchTool } from "./webSearch.js";
+import { wikiSearchTool } from "./wikiSearch.js";
+import { fetchArticleTool } from "./fetchArticle.js";
+import { imageSearchTool } from "./imageSearch.js";
+
+/**
+ * P0 で共有 tool として bind 可能な配列。subgraph がそのまま `bindTools` に渡せる。
+ *
+ * Convenience array of all shared tools, ready for `bindTools([...])`.
+ */
+export const SHARED_TOOLS = [
+  webSearchTool,
+  wikiSearchTool,
+  fetchArticleTool,
+  imageSearchTool,
+] as const;
diff --git a/server/api/src/agents/core/tools/resolveWebSearchModel.ts b/server/api/src/agents/core/tools/resolveWebSearchModel.ts
new file mode 100644
index 00000000..f4ad2fe9
--- /dev/null
+++ b/server/api/src/agents/core/tools/resolveWebSearchModel.ts
@@ -0,0 +1,109 @@
+/**
+ * `resolveWebSearchModel` — pick the LLM model the `web_search` tool should run.
+ *
+ * `webSearchTool` は provider 内蔵の web 検索 (`useWebSearch` for OpenAI,
+ * `useGoogleSearch` for Google) を呼ぶため、Anthropic-only な選択では成立しない。
+ * 本ヘルパは次の優先順で model を選ぶ:
+ *
+ * 1. `process.env.WIKI_COMPOSE_WEB_SEARCH_MODEL_ID` (explicit override; `ai_models.id`)
+ *    — 必ず active かつ tier 通過することを DB 側で確認する（coderabbit review #956:
+ *    不正な override で `createZediChatModel` が失敗してエラー envelope になる
+ *    のを防ぐ）。
+ * 2. `ai_models` の active な OpenAI モデルで最安 (`input_cost_units` ASC, `output_cost_units` ASC)
+ * 3. `ai_models` の active な Google モデルで最安
+ * 4. 何も無ければ `null` を返す（ツール側は empty result + note を返す）。
+ *
+ * Returns the `ai_models.id` so `createZediChatModel({ modelId })` can validate
+ * tier access and resolve the API key uniformly. Centralising the choice in one
+ * helper keeps the tool body small and makes the Anthropic-fallback policy
+ * easy to revisit.
+ *
+ * The `tier` argument filters out `tierRequired === "pro"` rows for free users,
+ * so a free-tier caller never sees `web_search_unavailable_for_tier` surface as
+ * an error — they cleanly fall back to "no results" + note (coderabbit #956).
+ */
+import { and, asc, eq, inArray } from "drizzle-orm";
+import { aiModels } from "../../../schema/index.js";
+import type { Database, UserTier } from "../../../types/index.js";
+
+const ENV_OVERRIDE = "WIKI_COMPOSE_WEB_SEARCH_MODEL_ID";
+
+/**
+ * Tier-aware predicate: `free` users only see `tierRequired = "free"` models;
+ * `pro` users see both.
+ *
+ * tier ガード。`free` ユーザは `tierRequired = "free"` のモデルだけ見える。
+ */
+function tierFilter(tier: UserTier) {
+  if (tier === "pro") return undefined;
+  return eq(aiModels.tierRequired, "free");
+}
+
+/**
+ * Resolve the model id used by `webSearchTool`. Returns `null` when no
+ * suitable model exists (e.g. Anthropic-only seed, or the env override is
+ * not active / not accessible to the caller's tier). Pure read-only DB query.
+ */
+export async function resolveWebSearchModelId(
+  db: Database,
+  tier: UserTier,
+): Promise<string | null> {
+  const override = process.env[ENV_OVERRIDE]?.trim();
+  if (override) {
+    // Validate the override before returning: it must be active and
+    // accessible to the caller's tier, otherwise `createZediChatModel`
+    // would throw and surface as an `ok:false` envelope instead of the
+    // intended graceful unavailable path.
+    // override も active + tier 通過性を DB で検証する。
+    const tierClause = tierFilter(tier);
+    const [row] = await db
+      .select({ id: aiModels.id })
+      .from(aiModels)
+      .where(
+        and(
+          eq(aiModels.id, override),
+          eq(aiModels.isActive, true),
+          ...(tierClause ? [tierClause] : []),
+        ),
+      )
+      .limit(1);
+    if (row) return row.id;
+    // Override resolved but unusable → fall through to the standard lookup
+    // rather than returning the broken id.
+    // override が使えない場合は通常検索にフォールバックする。
+  }
+
+  const tierClause = tierFilter(tier);
+  const rows = await db
+    .select({
+      id: aiModels.id,
+      provider: aiModels.provider,
+      inputCostUnits: aiModels.inputCostUnits,
+      outputCostUnits: aiModels.outputCostUnits,
+    })
+    .from(aiModels)
+    .where(
+      and(
+        eq(aiModels.isActive, true),
+        inArray(aiModels.provider, ["openai", "google"]),
+        ...(tierClause ? [tierClause] : []),
+      ),
+    )
+    .orderBy(asc(aiModels.inputCostUnits), asc(aiModels.outputCostUnits));
+
+  if (rows.length === 0) return null;
+
+  const [first] = rows;
+  if (!first) return null;
+
+  // Prefer OpenAI only among cheapest rows (cost tie-break), since `useWebSearch`
+  // is well-tested in `aiProviders.ts`.
+  // 最安行の中でのみ OpenAI を優先（`aiProviders.ts` の useWebSearch 経路が安定）。
+  const cheapestInput = first.inputCostUnits;
+  const cheapestOutput = first.outputCostUnits;
+  const cheapest = rows.filter(
+    (r) => r.inputCostUnits === cheapestInput && r.outputCostUnits === cheapestOutput,
+  );
+  const preferred = cheapest.find((r) => r.provider === "openai") ?? cheapest[0];
+  return preferred?.id ?? null;
+}
diff --git a/server/api/src/agents/core/tools/webSearch.ts b/server/api/src/agents/core/tools/webSearch.ts
new file mode 100644
index 00000000..623726fa
--- /dev/null
+++ b/server/api/src/agents/core/tools/webSearch.ts
@@ -0,0 +1,258 @@
+/**
+ * `web_search` tool — runs a provider-internal web search and returns a
+ * structured `{title,url,snippet}` list.
+ *
+ * Provider routing (issue #949):
+ * - `process.env.WIKI_COMPOSE_WEB_SEARCH_MODEL_ID` (`ai_models.id` override) >
+ * - cheapest active OpenAI model (`useWebSearch`) >
+ * - cheapest active Google model (`useGoogleSearch`).
+ *
+ * If the session was created with `backend === "zedi_managed"` but no suitable
+ * model exists (Anthropic-only seed, or no API keys configured), the tool
+ * returns `{ ok:true, results:[], note:"web_search_unavailable" }` so the
+ * `evaluate_sufficiency` node can carry on instead of throwing. The fallback
+ * is intentional: `evaluate_sufficiency` already handles empty results, and
+ * raising would tank the whole loop on a misconfigured env.
+ *
+ * LLM 呼び出しは `createZediChatModel` 経由で行うため、usage 記録は P0 で
+ * 確立した課金経路にそのまま乗る。`extraProviderOptions` で `useWebSearch` /
+ * `useGoogleSearch` を pass-through する。
+ *
+ * The LLM call goes through `createZediChatModel`, so usage attribution flows
+ * through the existing `recordUsage` path established in P0 (#948).
+ */
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+import { eq } from "drizzle-orm";
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { GRAPH_CONTEXT_CONFIG_KEY, type GraphContext } from "../types/graphContext.js";
+import { resolveWebSearchExecutionBackendForRun } from "../types/executionBackend.js";
+import { createZediChatModel } from "../llm/modelFactory.js";
+import { resolveWebSearchModelId } from "./resolveWebSearchModel.js";
+import type { ExtraProviderOptions } from "../llm/zediChatModel.js";
+import { aiModels } from "../../../schema/index.js";
+
+/** Tool name shared across subgraphs. 全 subgraph 共通の tool 名。 */
+export const WEB_SEARCH_TOOL_NAME = "web_search" as const;
+
+/**
+ * Input schema (zod). `query` は必須、`limit` は 1〜10、`recencyDays` は省略可。
+ * Input schema; `query` required, `limit` 1..10, `recencyDays` optional.
+ */
+export const webSearchInputSchema = z.object({
+  query: z.string().min(1).describe("Search query string. 検索クエリ。"),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(10)
+    .optional()
+    .describe("Max results (default 5). 最大件数 (既定 5)。"),
+  recencyDays: z
+    .number()
+    .int()
+    .min(1)
+    .optional()
+    .describe("Restrict to results within N days. N 日以内の結果に限定。"),
+});
+
+const webSearchResultSchema = z.object({
+  results: z
+    .array(
+      z.object({
+        title: z.string().min(1),
+        url: z.string().url(),
+        snippet: z.string().optional(),
+      }),
+    )
+    .max(10),
+});
+
+const SYSTEM_PROMPT =
+  "You are a web search assistant. Use the provider's native web search to find " +
+  "fresh, relevant pages for the user's query. Reply with JSON only, matching the " +
+  "provided schema. Do not invent URLs; only include sources you actually retrieved.";
+
+function buildUserPrompt(query: string, limit: number, recencyDays: number | undefined): string {
+  const constraints: string[] = [];
+  if (recencyDays !== undefined) constraints.push(`Restrict to the last ${recencyDays} days.`);
+  constraints.push(`Return at most ${limit} results.`);
+  return [`Query: ${query}`, ...constraints].join("\n");
+}
+
+/** Hit shape emitted on the wire (serialised as JSON). */
+interface WebSearchToolHit {
+  /**
+   * Stable Source id: `src:<sha256(url)>`. Shared with `kind:"fetched"` so the
+   * reducer (`mergeSourcesById`) upgrades the row in place when Readability
+   * succeeds on the same URL.
+   * web/fetched は同じ id 体系 (`src:<sha>`) を使うことで reducer が in-place
+   * 昇格できる（codex review #956 P2 / gemini #4）。
+   */
+  id: string;
+  kind: "web";
+  title: string;
+  url: string;
+  snippet?: string;
+}
+
+interface WebSearchSuccess {
+  ok: true;
+  results: WebSearchToolHit[];
+  /** Optional explanatory note (e.g. fallback path). */
+  note?: string;
+}
+
+interface WebSearchFailure {
+  ok: false;
+  error: string;
+  results: [];
+}
+
+export const webSearchTool = tool(
+  async (input, config?: LangGraphRunnableConfig) => {
+    const ctx = readGraphContext(config);
+    if (!ctx) {
+      return JSON.stringify({
+        ok: false,
+        error: "missing_graph_context",
+        results: [],
+      } satisfies WebSearchFailure);
+    }
+    const limit = input.limit ?? 5;
+    const recencyDays = input.recencyDays;
+
+    let modelId: string | null;
+    try {
+      modelId = await resolveWebSearchModelId(ctx.db, ctx.tier);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return JSON.stringify({
+        ok: false,
+        error: `web_search_model_resolution_failed:${message}`,
+        results: [],
+      } satisfies WebSearchFailure);
+    }
+
+    if (!modelId) {
+      // No OpenAI/Google model configured. Return empty results so the loop
+      // can carry on; `evaluate_sufficiency` is tolerant of empty channels.
+      // OpenAI / Google モデルが見つからない場合は空結果 + note を返す。
+      return JSON.stringify({
+        ok: true,
+        results: [],
+        note: "web_search_unavailable",
+      } satisfies WebSearchSuccess);
+    }
+
+    try {
+      const provider = await detectProviderForModelId(ctx, modelId);
+      const extraProviderOptions = providerOptions(provider);
+      const webSearchBackend = await resolveWebSearchExecutionBackendForRun(
+        ctx.backend,
+        provider,
+        ctx.userId,
+        ctx.db,
+      );
+      const model = await createZediChatModel({
+        modelId,
+        userId: ctx.userId,
+        tier: ctx.tier,
+        db: ctx.db,
+        feature: `${ctx.feature}:web_search`,
+        backend: webSearchBackend,
+        temperature: 0.2,
+        maxTokens: 1024,
+        extraProviderOptions,
+      });
+      const structured = model.withStructuredOutput(webSearchResultSchema, {
+        name: "web_search_results",
+      });
+      const parsed = await structured.invoke([
+        { role: "system", content: SYSTEM_PROMPT },
+        { role: "user", content: buildUserPrompt(input.query, limit, recencyDays) },
+      ]);
+      const results: WebSearchToolHit[] = await Promise.all(
+        parsed.results.slice(0, limit).map(async (r) => ({
+          id: `src:${await sha256Hex(r.url)}`,
+          kind: "web",
+          title: r.title,
+          url: r.url,
+          snippet: r.snippet,
+        })),
+      );
+      return JSON.stringify({ ok: true, results } satisfies WebSearchSuccess);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return JSON.stringify({
+        ok: false,
+        error: message,
+        results: [],
+      } satisfies WebSearchFailure);
+    }
+  },
+  {
+    name: WEB_SEARCH_TOOL_NAME,
+    description:
+      "Search the public web for fresh information. Returns top results with title + snippet + url. " +
+      "公開 Web を検索し、タイトル・抜粋・URL を返す。",
+    schema: webSearchInputSchema,
+  },
+);
+
+function readGraphContext(config: LangGraphRunnableConfig | undefined): GraphContext | null {
+  const configurable = config?.configurable as Record<string, unknown> | undefined;
+  const candidate = configurable?.[GRAPH_CONTEXT_CONFIG_KEY];
+  if (!candidate || typeof candidate !== "object") return null;
+  return candidate as GraphContext;
+}
+
+/**
+ * Look up the provider for a given `ai_models.id`. We could reuse
+ * `validateModelAccess` but that throws for tier-blocked models and we don't
+ * want a tier check here (the call is at the `web_search` feature, billed to
+ * the user regardless of which model is picked).
+ *
+ * Returns "openai" / "google" / "anthropic". Throws if the model is missing.
+ */
+async function detectProviderForModelId(
+  ctx: GraphContext,
+  modelId: string,
+): Promise<"openai" | "anthropic" | "google"> {
+  const [row] = await ctx.db
+    .select({ provider: aiModels.provider })
+    .from(aiModels)
+    .where(eq(aiModels.id, modelId))
+    .limit(1);
+  if (!row) throw new Error(`Model not found: ${modelId}`);
+  if (row.provider === "openai" || row.provider === "anthropic" || row.provider === "google") {
+    return row.provider;
+  }
+  throw new Error(`Unknown provider for model ${modelId}: ${row.provider}`);
+}
+
+function providerOptions(provider: "openai" | "anthropic" | "google"): ExtraProviderOptions {
+  if (provider === "openai") {
+    return { useWebSearch: true, webSearchOptions: { search_context_size: "medium" } };
+  }
+  if (provider === "google") {
+    return { useGoogleSearch: true };
+  }
+  // Anthropic is not selected by `resolveWebSearchModelId`; this is defensive
+  // for the env-override branch. The structured prompt still works, just
+  // without provider-side search.
+  return {};
+}
+
+/**
+ * `sha256` hex digest of a string. Used to mint stable `Source.id` for web
+ * search hits so a URL appearing in iteration N upgrades to `kind:"fetched"`
+ * in iteration N+1 in place.
+ */
+async function sha256Hex(input: string): Promise<string> {
+  const enc = new TextEncoder().encode(input);
+  const buf = await crypto.subtle.digest("SHA-256", enc);
+  return Array.from(new Uint8Array(buf))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
diff --git a/server/api/src/agents/core/tools/wikiSearch.ts b/server/api/src/agents/core/tools/wikiSearch.ts
new file mode 100644
index 00000000..be4e12fe
--- /dev/null
+++ b/server/api/src/agents/core/tools/wikiSearch.ts
@@ -0,0 +1,105 @@
+/**
+ * `wiki_search` tool — searches the executing user's own wiki pages by keyword.
+ *
+ * LangGraph tool wrapping {@link searchUserWikiPages}. Reads `db` / `userId` /
+ * `userEmail` from `config.configurable[GRAPH_CONTEXT_CONFIG_KEY]` so the call
+ * is implicitly scoped to the caller — never trust `query` for authorisation,
+ * trust the runtime context. Returns a JSON string array of `Source`-shaped
+ * rows (`kind:"wiki"`); the calling node parses it back.
+ *
+ * `routes/search.ts` の `scope=shared` 相当ロジック (`wikiSearchService`) を
+ * tool 経由で再利用する。ユーザー所有 + 受諾済みメンバー + ドメインルールを
+ * 横断する Wiki 検索を、`GraphContext` から取得した `userId` / `userEmail` で
+ * 安全に絞り込む。本ファイルは #949 で stub を本実装に差し替えた版。
+ */
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { GRAPH_CONTEXT_CONFIG_KEY, type GraphContext } from "../types/graphContext.js";
+import { searchUserWikiPages } from "../../../services/wikiSearchService.js";
+
+/** Tool name. */
+export const WIKI_SEARCH_TOOL_NAME = "wiki_search" as const;
+
+/**
+ * Input schema. `query` は必須、`limit` は 1〜20。
+ * Input schema.
+ */
+export const wikiSearchInputSchema = z.object({
+  query: z.string().min(1).describe("Title / body keyword. タイトル・本文キーワード。"),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(20)
+    .optional()
+    .describe("Max results (default 10). 最大件数 (既定 10)。"),
+});
+
+/** Hit shape emitted on the wire (serialised as JSON). */
+interface WikiSearchToolHit {
+  /** Stable Source id: `wiki:<pageId>`. */
+  id: string;
+  kind: "wiki";
+  title: string;
+  pageId: string;
+  noteId: string;
+  snippet?: string;
+}
+
+/**
+ * 実装本体。`config.configurable` から graph context を引き、wikiSearchService
+ * を呼び出す。tool runtime に context が乗っていない場合（典型的にはユニット
+ * テストでの誤呼び出し）は `{ ok:false, error:"missing_graph_context" }` を
+ * 返して呼び出し側がそのまま JSON.parse できる形を維持する。
+ *
+ * Read the `GraphContext` from the runtime config and invoke the service.
+ * Returns a JSON-string wrapped envelope so caller nodes can `JSON.parse`
+ * unconditionally — including the error branch, so a missing context does
+ * not blow up the entire iteration.
+ */
+export const wikiSearchTool = tool(
+  async (input, config?: LangGraphRunnableConfig) => {
+    const ctx = readGraphContext(config);
+    if (!ctx) {
+      return JSON.stringify({ ok: false, error: "missing_graph_context", results: [] });
+    }
+    const limit = input.limit ?? 10;
+    try {
+      const hits = await searchUserWikiPages(
+        ctx.db,
+        ctx.userId,
+        ctx.userEmail,
+        input.query,
+        "shared",
+        limit,
+      );
+      const results: WikiSearchToolHit[] = hits.map((h) => ({
+        id: `wiki:${h.pageId}`,
+        kind: "wiki",
+        title: h.title ?? "(untitled)",
+        pageId: h.pageId,
+        noteId: h.noteId,
+        snippet: h.contentPreview ?? undefined,
+      }));
+      return JSON.stringify({ ok: true, results });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return JSON.stringify({ ok: false, error: message, results: [] });
+    }
+  },
+  {
+    name: WIKI_SEARCH_TOOL_NAME,
+    description:
+      "Search the executing user's own wiki pages by keyword. Returns matching page ids + titles + excerpts. " +
+      "実行ユーザーの Wiki ページを検索し、ID・タイトル・抜粋を返す。",
+    schema: wikiSearchInputSchema,
+  },
+);
+
+function readGraphContext(config: LangGraphRunnableConfig | undefined): GraphContext | null {
+  const configurable = config?.configurable as Record<string, unknown> | undefined;
+  const candidate = configurable?.[GRAPH_CONTEXT_CONFIG_KEY];
+  if (!candidate || typeof candidate !== "object") return null;
+  return candidate as GraphContext;
+}
diff --git a/server/api/src/agents/core/types/executionBackend.ts b/server/api/src/agents/core/types/executionBackend.ts
new file mode 100644
index 00000000..ea7189b9
--- /dev/null
+++ b/server/api/src/agents/core/types/executionBackend.ts
@@ -0,0 +1,143 @@
+import type { UserAiCredentialProvider } from "../../../schema/userAiCredentials.js";
+import { getUserAiCredentialPlaintext } from "../../../services/userAiCredentialService.js";
+import type { Database } from "../../../types/index.js";
+
+/**
+ * Execution backend identifies where the LangGraph agent runs and which
+ * credential mode applies.
+ *
+ * 実行バックエンド。LangGraph エージェントが「どこで・誰の鍵で」走るかを表す。
+ *
+ * - `zedi_managed` — Zedi がプロビジョニングしたシステム API キーで API
+ *   ホスト内で実行。月次 CU は `recordUsage` で消費する。
+ * - `user_anthropic` / `user_openai` / `user_google` — ユーザーがサーバーに
+ *   登録した暗号化 API キーで実行（BYOK, #951）。Zedi CU は消費しない。
+ * - `byo_runner` — ユーザー所有ランナー（将来）。未対応で予約。
+ *
+ * `byok` は P0 スケッチ名；P3 では provider 別 backend に分割した。
+ */
+export type ExecutionBackend =
+  | "zedi_managed"
+  | "user_anthropic"
+  | "user_openai"
+  | "user_google"
+  | "byo_runner";
+
+/** BYOK backends that map 1:1 to a stored credential provider. */
+export type UserByokExecutionBackend = "user_anthropic" | "user_openai" | "user_google";
+
+/**
+ * Backends accepted for Wiki Compose session create / run (#951).
+ * Wiki Compose で受け入れる backend 一覧。
+ */
+export const SUPPORTED_COMPOSE_BACKENDS: ReadonlyArray<ExecutionBackend> = [
+  "zedi_managed",
+  "user_anthropic",
+  "user_openai",
+  "user_google",
+];
+
+/**
+ * @deprecated P0 名。`SUPPORTED_COMPOSE_BACKENDS` を使用すること。
+ * Alias kept for imports that still reference the P0 symbol.
+ */
+export const SUPPORTED_BACKENDS_P0: ReadonlyArray<ExecutionBackend> = SUPPORTED_COMPOSE_BACKENDS;
+
+/**
+ * 与えられた値が `ExecutionBackend` の文字列かどうかを判定する。
+ * Type guard for `ExecutionBackend`.
+ */
+export function isExecutionBackend(value: unknown): value is ExecutionBackend {
+  return (
+    value === "zedi_managed" ||
+    value === "user_anthropic" ||
+    value === "user_openai" ||
+    value === "user_google" ||
+    value === "byo_runner"
+  );
+}
+
+/**
+ * True when the backend uses a user-supplied API key (BYOK).
+ * ユーザー API キー backend かどうか。
+ */
+export function isUserByokBackend(backend: ExecutionBackend): backend is UserByokExecutionBackend {
+  return backend === "user_anthropic" || backend === "user_openai" || backend === "user_google";
+}
+
+/**
+ * Map a BYOK execution backend to the credential provider id.
+ * BYOK backend から credential provider へ変換。
+ */
+export function backendToCredentialProvider(
+  backend: UserByokExecutionBackend,
+): UserAiCredentialProvider {
+  switch (backend) {
+    case "user_anthropic":
+      return "anthropic";
+    case "user_openai":
+      return "openai";
+    case "user_google":
+      return "google";
+  }
+}
+
+/**
+ * Map credential provider to the compose execution backend id.
+ */
+export function credentialProviderToBackend(
+  provider: UserAiCredentialProvider,
+): UserByokExecutionBackend {
+  switch (provider) {
+    case "anthropic":
+      return "user_anthropic";
+    case "openai":
+      return "user_openai";
+    case "google":
+      return "user_google";
+  }
+}
+
+/**
+ * Execution backend for `web_search` given the session backend and resolved model provider.
+ *
+ * - `zedi_managed` sessions always bill web search to Zedi (system keys).
+ * - BYOK sessions use the user's key when the web-search model provider matches, or when
+ *   the user has a stored credential for that provider (cross-provider research).
+ */
+export function resolveWebSearchExecutionBackend(
+  sessionBackend: ExecutionBackend,
+  modelProvider: UserAiCredentialProvider,
+): ExecutionBackend {
+  if (!isUserByokBackend(sessionBackend)) {
+    return "zedi_managed";
+  }
+  const sessionProvider = backendToCredentialProvider(sessionBackend);
+  if (sessionProvider === modelProvider) {
+    return sessionBackend;
+  }
+  return credentialProviderToBackend(modelProvider);
+}
+
+/**
+ * Resolve web-search billing backend after verifying cross-provider BYOK keys exist.
+ * クロスプロバイダ BYOK 時は credential の有無を確認してから backend を決める。
+ */
+export async function resolveWebSearchExecutionBackendForRun(
+  sessionBackend: ExecutionBackend,
+  modelProvider: UserAiCredentialProvider,
+  userId: string,
+  db: Database,
+): Promise<ExecutionBackend> {
+  const candidate = resolveWebSearchExecutionBackend(sessionBackend, modelProvider);
+  if (!isUserByokBackend(sessionBackend) || candidate === sessionBackend) {
+    return candidate;
+  }
+  if (!isUserByokBackend(candidate)) {
+    return "zedi_managed";
+  }
+  const crossProvider = backendToCredentialProvider(candidate);
+  const key = await getUserAiCredentialPlaintext(userId, crossProvider, db);
+  if (key?.trim()) return candidate;
+  return "zedi_managed";
+}
diff --git a/server/api/src/agents/core/types/graphContext.ts b/server/api/src/agents/core/types/graphContext.ts
new file mode 100644
index 00000000..a17572bd
--- /dev/null
+++ b/server/api/src/agents/core/types/graphContext.ts
@@ -0,0 +1,53 @@
+/**
+ * Graph execution context passed via `LangGraphRunnableConfig.configurable`.
+ *
+ * グラフ実行コンテキスト。`GraphRunner` がノードや tool に渡す共有情報をまとめる。
+ * LangGraph の `configurable` には `thread_id` と `pageId`・`userId` 等の識別子を
+ * 載せ、`callbacks` には `ZediChatModel` の usage 記録コールバックを載せる。
+ *
+ * Shared per-run context that the `GraphRunner` propagates into LangGraph
+ * `configurable`. Includes the LangGraph `thread_id` plus Zedi-specific
+ * identifiers required by `ZediChatModel` for usage attribution.
+ */
+import type { Database, UserTier } from "../../../types/index.js";
+import type { ExecutionBackend } from "./executionBackend.js";
+
+/**
+ * グラフ実行 1 回ぶんのコンテキスト。
+ * Per-execution graph context.
+ *
+ * @property threadId  LangGraph 内 thread_id（compose session id を流用）。
+ *                     LangGraph thread id; reuse compose-session id.
+ * @property userId    実行ユーザー ID。Executing user id.
+ * @property pageId    対象ページ ID。Target page id.
+ * @property sessionId compose_session 行 ID（threadId と同じ値が来る想定）。
+ *                     compose session row id (currently equals threadId).
+ * @property graphId   実行する graph の論理名 (registry key)。Logical graph id.
+ * @property backend   実行 backend (P0 は `zedi_managed` のみ)。Execution backend.
+ * @property tier      ユーザー tier（usage 上限判定で使う）。User tier for budget checks.
+ * @property db        Drizzle DB ハンドル。Drizzle DB handle.
+ * @property feature   `recordUsage` の feature ラベル。`recordUsage` feature label.
+ * @property userEmail 実行ユーザーのメール（domain ベース共有スコープ判定で使う）。
+ *                     Executing user's email; used by `wikiSearchService` to
+ *                     apply the `note_domain_access` predicate without an
+ *                     extra DB roundtrip per tool call.
+ */
+export interface GraphContext {
+  threadId: string;
+  userId: string;
+  pageId: string;
+  sessionId: string;
+  graphId: string;
+  backend: ExecutionBackend;
+  tier: UserTier;
+  db: Database;
+  feature: string;
+  userEmail: string | null;
+}
+
+/**
+ * LangGraph の `configurable` バッグへ載せるキー。tool / node から `config.configurable`
+ * 経由でアクセスする際は必ず本キー名を使う。
+ * Single key namespace on `configurable` to fetch a {@link GraphContext}.
+ */
+export const GRAPH_CONTEXT_CONFIG_KEY = "zediGraphContext" as const;
diff --git a/server/api/src/agents/core/types/index.ts b/server/api/src/agents/core/types/index.ts
new file mode 100644
index 00000000..c32d4d62
--- /dev/null
+++ b/server/api/src/agents/core/types/index.ts
@@ -0,0 +1,37 @@
+/**
+ * Barrel for `agents/core/types/*`. Keeps import sites stable as new types are
+ * added; callers should import from this file rather than the individual
+ * modules.
+ *
+ * `agents/core/types/*` のバレル。呼び出し側は個別ファイルではなく本ファイル
+ * から import することで、サブモジュール構成の変更に追従しやすくする。
+ */
+export {
+  type ExecutionBackend,
+  type UserByokExecutionBackend,
+  isExecutionBackend,
+  isUserByokBackend,
+  backendToCredentialProvider,
+  credentialProviderToBackend,
+  SUPPORTED_COMPOSE_BACKENDS,
+  SUPPORTED_BACKENDS_P0,
+} from "./executionBackend.js";
+export { type GraphContext, GRAPH_CONTEXT_CONFIG_KEY } from "./graphContext.js";
+export {
+  type SseEvent,
+  type SseStartedEvent,
+  type SseStatusEvent,
+  type SseTokenEvent,
+  type SseToolStartEvent,
+  type SseToolEndEvent,
+  type SseUsageEvent,
+  type SseInterruptEvent,
+  type SseDoneEvent,
+  type SseErrorEvent,
+  type SseResearchIterationEvent,
+  type SseResearchEvaluationEvent,
+  type SseResearchBatchEvent,
+  type SseComposePhaseEvent,
+  type SseComposeSectionEvent,
+  SSE_EVENT_NAMES,
+} from "./sseEvents.js";
diff --git a/server/api/src/agents/core/types/sseEvents.ts b/server/api/src/agents/core/types/sseEvents.ts
new file mode 100644
index 00000000..73bf4e78
--- /dev/null
+++ b/server/api/src/agents/core/types/sseEvents.ts
@@ -0,0 +1,250 @@
+/**
+ * Wire-level SSE event types emitted from `POST /api/pages/:pageId/compose-sessions/:id/run`.
+ *
+ * compose-session 実行ストリームが SSE で吐く wire イベント型。フロントエンドは
+ * `event: <type>` でフィルタリングし、`data` を本ファイルの discriminated union
+ * として扱う。`sseMapper.ts` が LangGraph の生イベントから本型へ変換する。
+ *
+ * Discriminated union of SSE payloads sent by the compose-session run endpoint.
+ * The frontend treats `data` as a JSON document and discriminates on `type`.
+ * `sseMapper.ts` converts LangGraph runtime events into this shape.
+ */
+
+/**
+ * セッション開始通知。クライアントがプログレス UI を初期化するための合図。
+ * Emitted once when the run starts; lets the client initialise progress UI.
+ */
+export interface SseStartedEvent {
+  type: "started";
+  sessionId: string;
+  graphId: string;
+  phase?: string;
+}
+
+/**
+ * フェーズ遷移通知。subgraph が次フェーズに進んだとき。
+ * Phase transition (e.g. "research" → "draft").
+ */
+export interface SseStatusEvent {
+  type: "status";
+  phase: string;
+  message?: string;
+}
+
+/**
+ * LLM テキストトークン。compose の本文ドラフトをインクリメンタル描画する用途。
+ * Token delta from the underlying chat model for incremental rendering.
+ */
+export interface SseTokenEvent {
+  type: "token";
+  /** ノード名（draft / outline 等）。Node label, e.g. "draft". */
+  node?: string;
+  content: string;
+}
+
+/**
+ * Tool 呼び出し開始。UI 上の「検索中…」「記事取得中…」表示用。
+ * Tool invocation started.
+ */
+export interface SseToolStartEvent {
+  type: "tool_start";
+  tool: string;
+  /** zod でバリデート済みの入力。Validated tool input. */
+  input?: Record<string, unknown>;
+}
+
+/**
+ * Tool 呼び出し終了。
+ * Tool invocation finished.
+ */
+export interface SseToolEndEvent {
+  type: "tool_end";
+  tool: string;
+  /** クライアントには内容を晒さず長さだけ載せる用途で `outputLength` を許容。 */
+  outputLength?: number;
+  error?: string;
+}
+
+/**
+ * Usage 更新通知。トークン課金後に走る。
+ * Usage snapshot emitted after `recordUsage`.
+ */
+export interface SseUsageEvent {
+  type: "usage";
+  inputTokens: number;
+  outputTokens: number;
+  costUnits: number;
+  usagePercent: number;
+}
+
+/**
+ * Human-in-the-loop interrupt。次の resume で再開可能なポイント。
+ * Human-in-the-loop interrupt point; resumable via PATCH resume.
+ */
+export interface SseInterruptEvent {
+  type: "interrupt";
+  /** クライアントに渡す任意の追加情報。Optional payload describing the interrupt. */
+  payload?: unknown;
+}
+
+/**
+ * 終了イベント。`status` でステータスを伝達。
+ * Terminal event; carries the final status.
+ */
+export interface SseDoneEvent {
+  type: "done";
+  status: "completed" | "interrupted" | "failed";
+}
+
+/**
+ * エラーイベント。`SseDoneEvent` とは別に詳細を伝える。
+ * Error event with provider-side message; pair with a `done` with status="failed".
+ */
+export interface SseErrorEvent {
+  type: "error";
+  message: string;
+  /** リトライ可能か（ネットワーク等）。Whether the client can retry. */
+  retryable?: boolean;
+}
+
+/**
+ * 調査ループ subgraph (#949) の iteration 通知。`plan_queries` / `refine_queries`
+ * 終了時に 1 件発火し、UI が「N 回目を計画中…」と「N 回目を refine 中…」を
+ * 出し分けられるよう `status` を持つ。
+ *
+ * Per-iteration heartbeat from the research loop subgraph. Emitted by
+ * `plan_queries` (`status:"planned"`) and `refine_queries` (`status:"refined"`).
+ */
+export interface SseResearchIterationEvent {
+  type: "research_iteration";
+  /** 0-based iteration index at dispatch time. */
+  iteration: number;
+  /** Phase that produced this iteration's query set. */
+  status: "planned" | "refined";
+  /** Number of queries planned for this iteration. */
+  queryCount: number;
+}
+
+/**
+ * 調査ループ subgraph (#949) の充足度評価通知。`evaluate_sufficiency` 終了時に
+ * 1 件発火。0..1 のスコアと欠落数を含むが、`rationale` も同梱して UI が
+ * tooltip 等で利用できるようにする。
+ *
+ * Sufficiency evaluation result. Emitted by `evaluate_sufficiency`; carries the
+ * 0..1 score, a short rationale, and the missing-aspect count.
+ */
+export interface SseResearchEvaluationEvent {
+  type: "research_evaluation";
+  /** Iteration index after post-increment in `evaluate_sufficiency`. */
+  iteration: number;
+  /** 0..1. ≥ 0.75 → loop exits next. */
+  score: number;
+  /** Short natural-language rationale. */
+  rationale: string;
+  /** Count of missing aspects (full list lives in state, not on the wire). */
+  missingAspectsCount: number;
+}
+
+/**
+ * 調査ループ subgraph (#949) のバッチ完成通知。`compile_batch` 終了時に 1 件
+ * 発火。バッチ本体は state に乗っているので wire 上は ID + サマリのみ。
+ *
+ * One-shot batch summary emitted by `compile_batch`. The full batch lives in
+ * state; this event only carries the id + counts so the frontend knows when to
+ * fetch / render.
+ */
+export interface SseResearchBatchEvent {
+  type: "research_batch";
+  /** Stable batch uuid. */
+  batchId: string;
+  /** Iteration that produced the batch. */
+  iteration: number;
+  /** Snapshot size at compile time. */
+  sourceCount: number;
+  /** Last evaluation score (null only if compile fired before any evaluate). */
+  score: number | null;
+  /** Reason the loop exited. */
+  exitReason: "score_threshold" | "max_iterations";
+}
+
+/**
+ * Wiki Compose 全体グラフ (#950) のフェーズ進捗通知。Brief → Research → Structure
+ * → Draft → Completed の遷移時に 1 件ずつ発火し、フロントの PhaseStepper の
+ * 進行表示に使う。`status` フィールドで「開始」「完了」を区別する。
+ *
+ * Orchestrator phase transition event. Emitted on enter / exit of each
+ * top-level phase so the frontend phase stepper can advance without
+ * inspecting state.
+ */
+export interface SseComposePhaseEvent {
+  type: "compose_phase";
+  /** Phase name (matches state.phase). */
+  phase: "brief" | "research" | "conflict" | "structure" | "draft" | "completed";
+  /** Lifecycle hint within the phase. */
+  status: "entered" | "completed";
+}
+
+/**
+ * Wiki Compose 全体グラフ (#950) のセクション ドラフト進捗通知。`draftSections`
+ * が 1 セクションを書き始める前 / 書き終わった後にそれぞれ 1 件発火する。
+ *
+ * Per-section draft progress event. Emitted by `draft_sections` at the start
+ * and end of each section so the editor pane can highlight the section that
+ * is currently streaming.
+ */
+export interface SseComposeSectionEvent {
+  type: "compose_section";
+  /** Matches `OutlineSection.id`. */
+  sectionId: string;
+  /** Final / running heading. */
+  heading: string;
+  /** Lifecycle: `started` before streaming, `completed` after the body is finalised. */
+  status: "started" | "completed";
+  /** 1-based index of this section within the outline. */
+  index: number;
+  /** Total number of sections in the outline. */
+  total: number;
+}
+
+/**
+ * Wire-level SSE union.
+ */
+export type SseEvent =
+  | SseStartedEvent
+  | SseStatusEvent
+  | SseTokenEvent
+  | SseToolStartEvent
+  | SseToolEndEvent
+  | SseUsageEvent
+  | SseInterruptEvent
+  | SseDoneEvent
+  | SseErrorEvent
+  | SseResearchIterationEvent
+  | SseResearchEvaluationEvent
+  | SseResearchBatchEvent
+  | SseComposePhaseEvent
+  | SseComposeSectionEvent;
+
+/**
+ * SSE event 名（`event:` 行に流す名前）。`SseEvent["type"]` と同値だが、
+ * 文字列リテラルとして引きやすいよう列挙する。
+ *
+ * SSE event names mirroring `SseEvent["type"]`, exposed as a const so writers
+ * can `event: SSE_EVENT_NAMES.token` without re-spelling literals.
+ */
+export const SSE_EVENT_NAMES = {
+  started: "started",
+  status: "status",
+  token: "token",
+  toolStart: "tool_start",
+  toolEnd: "tool_end",
+  usage: "usage",
+  interrupt: "interrupt",
+  done: "done",
+  error: "error",
+  researchIteration: "research_iteration",
+  researchEvaluation: "research_evaluation",
+  researchBatch: "research_batch",
+  composePhase: "compose_phase",
+  composeSection: "compose_section",
+} as const satisfies Record<string, SseEvent["type"]>;
diff --git a/server/api/src/agents/graphs/ingest/index.ts b/server/api/src/agents/graphs/ingest/index.ts
new file mode 100644
index 00000000..dfafbbfc
--- /dev/null
+++ b/server/api/src/agents/graphs/ingest/index.ts
@@ -0,0 +1,17 @@
+export {
+  INGEST_PLANNER_GRAPH_ID,
+  INGEST_PLANNER_GRAPH_VERSION,
+  registerIngestPlannerGraph,
+} from "./ingestPlannerGraph.js";
+export {
+  IngestPlannerState,
+  type IngestPlannerStateType,
+  type IngestPlannerStateUpdate,
+} from "./state.js";
+export type {
+  IngestAction,
+  IngestPlan,
+  IngestConflict,
+  CandidatePage,
+  IngestArticleSummary,
+} from "./types.js";
diff --git a/server/api/src/agents/graphs/ingest/ingestPlannerGraph.ts b/server/api/src/agents/graphs/ingest/ingestPlannerGraph.ts
new file mode 100644
index 00000000..c5ec4cd6
--- /dev/null
+++ b/server/api/src/agents/graphs/ingest/ingestPlannerGraph.ts
@@ -0,0 +1,80 @@
+/**
+ * Wiki Compose P4 — `ingestPlannerGraph` (issue #952).
+ *
+ * 記事クリップ ingest フロー。`prepare_ingest` の後に P1 調査ループ
+ * （`researchLoopSubgraph` と同じノード / tools / `shouldRefine`）を組み込み、
+ * `human_review_research` のあと `plan_ingest` で merge / create / skip を決定する。
+ *
+ * Ingest planner graph: seeds clip context, runs the shared research loop
+ * (same nodes/tools as Compose), then emits an ingest plan via ZediChatModel.
+ */
+import { END, START, StateGraph } from "@langchain/langgraph";
+import { registerGraph, type GraphFactory } from "../../registry/graphRegistry.js";
+import { shouldRefine } from "../../subgraphs/research/researchGraph.js";
+import {
+  planQueries,
+  webSearch,
+  wikiSearch,
+  fetchArticles,
+  evaluateSufficiency,
+  refineQueries,
+  compileBatch,
+  humanReviewResearch,
+} from "../../subgraphs/research/nodes/index.js";
+import { IngestPlannerState } from "./state.js";
+import { prepareIngest, planIngest } from "./nodes/index.js";
+
+/** Registered graph id. / 登録グラフ ID。 */
+export const INGEST_PLANNER_GRAPH_ID = "ingest-planner" as const;
+/** Registered graph version. / 登録グラフのバージョン。 */
+export const INGEST_PLANNER_GRAPH_VERSION = "1.0.0";
+
+const factory: GraphFactory = ({ checkpointer }) => {
+  const builder = new StateGraph(IngestPlannerState)
+    .addNode("prepare_ingest", prepareIngest)
+    .addNode("plan_ingest", planIngest)
+    .addEdge(START, "prepare_ingest")
+    // Research loop (same wiring as `researchLoopSubgraph` / `wireResearchLoopSubgraph`).
+    .addNode("plan_queries", planQueries)
+    .addNode("web_search", webSearch)
+    .addNode("wiki_search", wikiSearch)
+    .addNode("fetch_articles", fetchArticles)
+    .addNode("evaluate_sufficiency", evaluateSufficiency)
+    .addNode("refine_queries", refineQueries)
+    .addNode("compile_batch", compileBatch)
+    .addNode("human_review_research", humanReviewResearch)
+    .addEdge("prepare_ingest", "plan_queries")
+    .addEdge("plan_queries", "web_search")
+    .addEdge("plan_queries", "wiki_search")
+    .addEdge("web_search", "fetch_articles")
+    .addEdge("wiki_search", "fetch_articles")
+    .addEdge("fetch_articles", "evaluate_sufficiency")
+    .addConditionalEdges("evaluate_sufficiency", shouldRefine, {
+      refine: "refine_queries",
+      compile: "compile_batch",
+    })
+    .addEdge("refine_queries", "web_search")
+    .addEdge("refine_queries", "wiki_search")
+    .addEdge("compile_batch", "human_review_research")
+    .addEdge("human_review_research", "plan_ingest")
+    .addEdge("plan_ingest", END);
+
+  return checkpointer ? builder.compile({ checkpointer }) : builder.compile();
+};
+
+/**
+ * Register the ingest planner graph. Idempotent; call from `app.ts` bootstrap.
+ * ingest プランナーグラフを登録する。`app.ts` 起動時に呼ぶ（冪等）。
+ */
+export function registerIngestPlannerGraph(): void {
+  registerGraph({
+    id: INGEST_PLANNER_GRAPH_ID,
+    version: INGEST_PLANNER_GRAPH_VERSION,
+    phase: "ingest",
+    description:
+      "Wiki Compose P4: ingest clip planner. Runs the P1 research loop (shared nodes/tools) " +
+      "then plans merge/create/skip via ZediChatModel. Interrupt at human_review_research; " +
+      "resume payload matches wiki-compose-research. Coexists with POST /api/ingest/plan (#595).",
+    factory,
+  });
+}
diff --git a/server/api/src/agents/graphs/ingest/nodes/formatResearchForIngest.ts b/server/api/src/agents/graphs/ingest/nodes/formatResearchForIngest.ts
new file mode 100644
index 00000000..68d860b0
--- /dev/null
+++ b/server/api/src/agents/graphs/ingest/nodes/formatResearchForIngest.ts
@@ -0,0 +1,38 @@
+/**
+ * Formats approved research + latest batch evaluation for the ingest planner prompt.
+ * 採用調査ソースと最新 batch 評価を ingest プランナープロンプト用に整形する。
+ */
+import type { IngestPlannerStateType } from "../state.js";
+
+/**
+ * Build a markdown block summarizing research loop output for `plan_ingest`.
+ * `plan_ingest` 向けに調査ループ出力を markdown ブロックにまとめる。
+ */
+export function formatResearchForIngest(state: IngestPlannerStateType): string {
+  const lines: string[] = [];
+
+  if (state.approvedResearch.length > 0) {
+    lines.push("## APPROVED RESEARCH SOURCES");
+    for (const s of state.approvedResearch) {
+      const loc = s.url ?? s.finalUrl ?? (s.pageId ? `wiki:${s.pageId}` : s.id);
+      lines.push(`- [${s.id}] ${s.title} (${s.kind}) ${loc}`);
+      const preview = s.excerpt ?? s.snippet;
+      if (preview) {
+        lines.push(`  preview: ${preview.slice(0, 400)}`);
+      }
+    }
+  }
+
+  const latest = state.batches[state.batches.length - 1];
+  if (latest?.evaluation) {
+    lines.push("", "## RESEARCH EVALUATION (latest batch)");
+    lines.push(`score: ${latest.evaluation.score}`);
+    lines.push(`rationale: ${latest.evaluation.rationale}`);
+    if (latest.evaluation.missingAspects?.length) {
+      lines.push(`missing: ${latest.evaluation.missingAspects.join("; ")}`);
+    }
+  }
+
+  if (lines.length === 0) return "";
+  return `\n\n${lines.join("\n")}`;
+}
diff --git a/server/api/src/agents/graphs/ingest/nodes/index.ts b/server/api/src/agents/graphs/ingest/nodes/index.ts
new file mode 100644
index 00000000..7e2cde52
--- /dev/null
+++ b/server/api/src/agents/graphs/ingest/nodes/index.ts
@@ -0,0 +1,2 @@
+export { prepareIngest } from "./prepareIngest.js";
+export { planIngest } from "./planIngest.js";
diff --git a/server/api/src/agents/graphs/ingest/nodes/planIngest.ts b/server/api/src/agents/graphs/ingest/nodes/planIngest.ts
new file mode 100644
index 00000000..6470f299
--- /dev/null
+++ b/server/api/src/agents/graphs/ingest/nodes/planIngest.ts
@@ -0,0 +1,85 @@
+/**
+ * `plan_ingest` — structured ingest plan after the shared research loop (#952).
+ *
+ * 調査ループ完了後、クリップ記事と候補ページから merge / create / skip を決める。
+ * LLM 呼び出しは `createZediChatModel` 経由（`ingestPlanner.ts` のプロンプトを再利用）。
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { z } from "zod";
+import { createZediChatModel } from "../../../core/llm/modelFactory.js";
+import { resolveComposeModelId } from "../../../core/llm/resolveComposeModelId.js";
+import { getGraphContext } from "../../../subgraphs/research/nodes/shared/getGraphContext.js";
+import {
+  buildIngestPlannerPrompt,
+  parseIngestPlanValue,
+} from "../../../../services/ingestPlanner.js";
+import type { IngestPlannerStateType, IngestPlannerStateUpdate } from "../state.js";
+import { formatResearchForIngest } from "./formatResearchForIngest.js";
+
+const ingestPlanSchema = z.object({
+  action: z.enum(["merge", "create", "skip"]),
+  reason: z.string().min(1),
+  targetPageId: z.string().optional(),
+  title: z.string().optional(),
+  summary: z.string().optional(),
+  conflicts: z
+    .array(
+      z.object({
+        claim: z.string().min(1),
+        existing: z.string().min(1),
+        note: z.string().optional(),
+      }),
+    )
+    .optional(),
+});
+
+/**
+ * Produce {@link IngestPlan} via ZediChatModel after research completes.
+ */
+export async function planIngest(
+  state: IngestPlannerStateType,
+  config: LangGraphRunnableConfig,
+): Promise<IngestPlannerStateUpdate> {
+  const ctx = getGraphContext(config);
+  if (!state.article) {
+    throw new Error("plan_ingest: article is missing from state");
+  }
+
+  const messages = buildIngestPlannerPrompt({
+    article: state.article,
+    candidates: state.candidates,
+    userSchema: state.userSchema ?? undefined,
+  });
+  const researchBlock = formatResearchForIngest(state);
+  if (researchBlock.length > 0) {
+    const last = messages[messages.length - 1];
+    if (last?.role === "user") {
+      last.content = `${last.content}${researchBlock}`;
+    } else {
+      messages.push({ role: "user", content: researchBlock.trimStart() });
+    }
+  }
+
+  const modelId = await resolveComposeModelId("orchestrator", ctx.backend, ctx.tier, ctx.db);
+  const model = await createZediChatModel({
+    modelId,
+    userId: ctx.userId,
+    tier: ctx.tier,
+    db: ctx.db,
+    feature: `${ctx.feature}:plan_ingest`,
+    backend: ctx.backend,
+    temperature: 0.2,
+    maxTokens: 1024,
+  });
+
+  const structured = model.withStructuredOutput(ingestPlanSchema, { name: "plan_ingest" });
+  const raw = await structured.invoke(messages.map((m) => ({ role: m.role, content: m.content })));
+
+  const validCandidateIds = new Set(state.candidates.map((c) => c.id));
+  const ingestPlan = parseIngestPlanValue(raw, { validCandidateIds });
+
+  return {
+    ingestPlan,
+    phase: "ingest:planned",
+  };
+}
diff --git a/server/api/src/agents/graphs/ingest/nodes/prepareIngest.ts b/server/api/src/agents/graphs/ingest/nodes/prepareIngest.ts
new file mode 100644
index 00000000..5ca4579e
--- /dev/null
+++ b/server/api/src/agents/graphs/ingest/nodes/prepareIngest.ts
@@ -0,0 +1,80 @@
+/**
+ * `prepare_ingest` — seeds article / candidates and messages for the research loop.
+ *
+ * `POST /api/ingest/graph/run` の input を state に投影し、続く
+ * `researchLoopSubgraph`（共有ノード配線）が参照する `messages` を組み立てる。
+ */
+import { HumanMessage } from "@langchain/core/messages";
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { getGraphContext } from "../../../subgraphs/research/nodes/shared/getGraphContext.js";
+import type { IngestPlannerStateType, IngestPlannerStateUpdate } from "../state.js";
+
+function clampMaxIterations(raw: number): number {
+  if (!Number.isFinite(raw)) return 3;
+  const truncated = Math.trunc(raw);
+  return Math.min(Math.max(truncated, 1), 5);
+}
+
+/**
+ * Project graph run input into ingest + research seed state.
+ *
+ * LangGraph merges `POST /run` input keys that match state annotations (`article`,
+ * `candidates`, `userSchema`, `maxIterations`) before this node runs.
+ */
+export async function prepareIngest(
+  state: IngestPlannerStateType,
+  config: LangGraphRunnableConfig,
+): Promise<IngestPlannerStateUpdate> {
+  const ctx = getGraphContext(config);
+
+  const article = state.article;
+  if (!article?.title?.trim() || !article.url?.trim() || typeof article.excerpt !== "string") {
+    throw new Error("prepare_ingest: article { title, url, excerpt } is required");
+  }
+
+  const candidates = state.candidates;
+  const userSchema = state.userSchema;
+  const maxIterations = clampMaxIterations(state.maxIterations);
+
+  for (const [i, c] of candidates.entries()) {
+    if (!c?.id?.trim() || typeof c.title !== "string" || !c.title.trim()) {
+      throw new Error(`prepare_ingest: candidates[${i}] requires non-empty { id, title }`);
+    }
+    if (c.excerpt != null && typeof c.excerpt !== "string") {
+      throw new Error(`prepare_ingest: candidates[${i}].excerpt must be a string when provided`);
+    }
+  }
+
+  const candidateBlock =
+    candidates.length === 0
+      ? "(no candidates)"
+      : candidates
+          .map(
+            (c, i) =>
+              `[${i + 1}] id=${c.id}\n    title: ${c.title}\n    excerpt: ${(c.excerpt ?? "").slice(0, 400)}`,
+          )
+          .join("\n\n");
+
+  const brief = [
+    "[Ingest clip]",
+    `title: ${article.title}`,
+    `url: ${article.url}`,
+    "",
+    "excerpt:",
+    article.excerpt.slice(0, 4000),
+    "",
+    "## CANDIDATES",
+    candidateBlock,
+  ].join("\n");
+
+  return {
+    article,
+    candidates,
+    userSchema,
+    maxIterations,
+    userId: ctx.userId,
+    pageId: ctx.pageId,
+    phase: "ingest:prepare",
+    messages: [new HumanMessage(brief)],
+  };
+}
diff --git a/server/api/src/agents/graphs/ingest/state.ts b/server/api/src/agents/graphs/ingest/state.ts
new file mode 100644
index 00000000..f812e8a1
--- /dev/null
+++ b/server/api/src/agents/graphs/ingest/state.ts
@@ -0,0 +1,103 @@
+/**
+ * `IngestPlannerState` — LangGraph state for the Ingest planner graph (#952).
+ *
+ * `ResearchLoopState` の channel 群を superset として保持し、
+ * `wireResearchLoopSubgraph` で P1 調査ループを組み込む。記事クリップ用の
+ * `article` / `candidates` / `ingestPlan` を追加する。
+ *
+ * Extends research-loop channels so {@link wireResearchLoopSubgraph} can share
+ * nodes with Compose. Adds ingest-specific fields for clip planning.
+ */
+import { Annotation } from "@langchain/langgraph";
+import { BaseState } from "../../core/state/baseState.js";
+import type {
+  AdditionalResearchRequest,
+  Evaluation,
+  ExitReason,
+  PlannedQuery,
+  ResearchBatch,
+  Source,
+} from "../../subgraphs/research/types.js";
+import type { CandidatePage, IngestArticleSummary, IngestPlan } from "./types.js";
+
+function mergeSourcesById(prev: Source[], next: Source[] | undefined): Source[] {
+  if (!next || next.length === 0) return prev;
+  const order: string[] = [];
+  const map = new Map<string, Source>();
+  for (const s of prev) {
+    if (!map.has(s.id)) order.push(s.id);
+    map.set(s.id, s);
+  }
+  for (const s of next) {
+    if (!map.has(s.id)) order.push(s.id);
+    map.set(s.id, s);
+  }
+  return order.map((id) => map.get(id) as Source);
+}
+
+export const IngestPlannerState = Annotation.Root({
+  ...BaseState.spec,
+
+  // ── Ingest clip input ─────────────────────────────────────────────────────
+  article: Annotation<IngestArticleSummary | null>({
+    reducer: (prev, next) => (next === undefined ? prev : next),
+    default: () => null,
+  }),
+  candidates: Annotation<CandidatePage[]>({
+    reducer: (_prev, next) => next,
+    default: () => [],
+  }),
+  userSchema: Annotation<string | null>({
+    reducer: (prev, next) => (next === undefined ? prev : next),
+    default: () => null,
+  }),
+  ingestPlan: Annotation<IngestPlan | null>({
+    reducer: (prev, next) => (next === undefined ? prev : next),
+    default: () => null,
+  }),
+
+  // ── Research mirror (matches ResearchLoopState) ───────────────────────────
+  iteration: Annotation<number>({
+    reducer: (_prev, next) => next,
+    default: () => 0,
+  }),
+  maxIterations: Annotation<number>({
+    reducer: (prev, next) => next ?? prev,
+    default: () => 3,
+  }),
+  queries: Annotation<PlannedQuery[]>({
+    reducer: (_prev, next) => next,
+    default: () => [],
+  }),
+  pendingSources: Annotation<Source[]>({
+    reducer: mergeSourcesById,
+    default: () => [],
+  }),
+  lastEvaluation: Annotation<Evaluation | null>({
+    reducer: (_prev, next) => next,
+    default: () => null,
+  }),
+  exitReason: Annotation<ExitReason | null>({
+    reducer: (_prev, next) => next,
+    default: () => null,
+  }),
+  batches: Annotation<ResearchBatch[]>({
+    reducer: (prev, next) => (next === undefined ? prev : [...prev, ...next]),
+    default: () => [],
+  }),
+  approvedResearch: Annotation<Source[]>({
+    reducer: (_prev, next) => next,
+    default: () => [],
+  }),
+  rejectedResearch: Annotation<Source[]>({
+    reducer: (_prev, next) => next,
+    default: () => [],
+  }),
+  additionalRequest: Annotation<AdditionalResearchRequest | null>({
+    reducer: (prev, next) => (next === undefined ? prev : next),
+    default: () => null,
+  }),
+});
+
+export type IngestPlannerStateType = typeof IngestPlannerState.State;
+export type IngestPlannerStateUpdate = typeof IngestPlannerState.Update;
diff --git a/server/api/src/agents/graphs/ingest/types.ts b/server/api/src/agents/graphs/ingest/types.ts
new file mode 100644
index 00000000..a6bbd3da
--- /dev/null
+++ b/server/api/src/agents/graphs/ingest/types.ts
@@ -0,0 +1,13 @@
+/**
+ * Ingest planner graph types (issue #952).
+ *
+ * `ingestPlanner.ts` サービス型の graph 用エイリアス。サービス層を正とし、
+ * graph state は同じ shape を参照する。
+ */
+export type {
+  IngestAction,
+  IngestPlan,
+  IngestConflict,
+  CandidatePage,
+  IngestArticleSummary,
+} from "../../../services/ingestPlanner.js";
diff --git a/server/api/src/agents/graphs/wikiCompose/index.ts b/server/api/src/agents/graphs/wikiCompose/index.ts
new file mode 100644
index 00000000..f919153e
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/index.ts
@@ -0,0 +1,47 @@
+/**
+ * Wiki Compose orchestrator graph (#950) — public barrel.
+ *
+ * 全体グラフの外向け window。`app.ts` / `agents/index.ts` からこのファイル経由で
+ * `WIKI_COMPOSE_GRAPH_ID` と `registerWikiComposeGraph` を引く。直接ノードを
+ * import したいテストは `./nodes/index.js` を見る。
+ */
+export {
+  WIKI_COMPOSE_GRAPH_ID,
+  WIKI_COMPOSE_GRAPH_VERSION,
+  registerWikiComposeGraph,
+} from "./wikiComposeGraph.js";
+export {
+  WikiComposeState,
+  type WikiComposeStateType,
+  type WikiComposeStateUpdate,
+} from "./state.js";
+export type {
+  BriefAnswer,
+  BriefOption,
+  BriefQuestion,
+  BriefResult,
+  BriefResumeInput,
+  ApprovedOutline,
+  ComposeCompletion,
+  DraftedSection,
+  OutlineResumeInput,
+  OutlineSection,
+  PageSnapshot,
+  WikiComposeInterruptPayload,
+  ResearchConflictSummary,
+} from "./types.js";
+export {
+  briefResumeSchema,
+  type BriefResumeParsed,
+  outlineResumeSchema,
+  type OutlineResumeParsed,
+  conflictResumeSchema,
+  type ConflictResumeParsed,
+} from "./resumeSchemas.js";
+export {
+  routeAfterBrief,
+  routeAfterResearch,
+  shouldResolveResearchConflicts,
+  type BriefRoute,
+  type ResearchRoute,
+} from "./routing.js";
diff --git a/server/api/src/agents/graphs/wikiCompose/nodes/briefDialogue.ts b/server/api/src/agents/graphs/wikiCompose/nodes/briefDialogue.ts
new file mode 100644
index 00000000..7b5e8df8
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/nodes/briefDialogue.ts
@@ -0,0 +1,171 @@
+/**
+ * `brief_dialogue` — Wiki Compose orchestrator entry node (#950).
+ *
+ * Brief フェーズの最初のノード。ページタイトル + 既存本文プレビューから、
+ * 0〜7 件の構造化質問を Orchestrator LLM に生成させる。`compose_phase` SSE を
+ * `entered` で発火し、生成後は `briefQuestions` を state に書き、`phase` を
+ * `brief:await_user` にして次の `human_review_brief` interrupt に進む。
+ *
+ * Brief never opens a free-form chat — it always emits the question cards
+ * that the frontend renders (the user fills them in and resumes). The node
+ * also loads the page snapshot exactly once at session start so downstream
+ * phases can read it without re-querying.
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { createZediChatModel } from "../../../core/llm/modelFactory.js";
+import { resolveComposeModelId } from "../../../core/llm/resolveComposeModelId.js";
+import { getGraphContext } from "../../../subgraphs/research/nodes/shared/getGraphContext.js";
+import { loadPageSnapshot } from "./shared/loadPageSnapshot.js";
+import { dispatchComposePhase } from "./shared/dispatch.js";
+import type { WikiComposeStateType, WikiComposeStateUpdate } from "../state.js";
+import type { BriefQuestion } from "../types.js";
+
+/**
+ * Schema for the LLM's structured output. The Orchestrator is told it MAY
+ * return zero questions when the title is unambiguous (e.g. a single specific
+ * proper noun with existing content). Hard cap at 7 to keep the UI scannable.
+ */
+export const briefQuestionsSchema = z.object({
+  questions: z
+    .array(
+      z.object({
+        question: z.string().min(1).max(200),
+        rationale: z.string().max(200).optional(),
+        options: z
+          .array(
+            z.object({
+              label: z.string().min(1).max(80),
+              hint: z.string().max(160).optional(),
+            }),
+          )
+          .max(6)
+          .default([]),
+        required: z.boolean().default(false),
+      }),
+    )
+    .min(0)
+    .max(7),
+});
+
+const SYSTEM_PROMPT =
+  "You are the orchestrator for Wiki Compose, an AI agent that helps a user " +
+  "co-author a wiki article. Given a page title (and optional existing body), " +
+  "decide what Brief questions (if any) you need to ask before research. " +
+  "Constraints:\n" +
+  "1. Output 0..7 questions. Prefer FEWER questions; only ask what is needed " +
+  "to disambiguate scope, audience, or depth.\n" +
+  "2. Each question MUST be answerable via option chips when reasonable " +
+  "(2..6 options). Free-text is always allowed on top, so don't add a " +
+  "trailing 'other' option.\n" +
+  "3. If the existing body is non-empty, you may include a question that " +
+  "asks whether to append or replace.\n" +
+  "4. Mark a question 'required: true' ONLY when leaving it unanswered would " +
+  "make the article unwritable. Most questions should be optional.\n" +
+  "Respond as JSON only.";
+
+function buildUserPrompt(
+  title: string,
+  body: string,
+  chatSeed?: { outline: string; conversationText: string; userSchema?: string } | null,
+): string {
+  const parts: string[] = [`[Page title]`, title || "(no title yet)"];
+  if (body.trim()) {
+    parts.push(
+      "",
+      "[Existing body excerpt — first ~600 chars]",
+      body.slice(0, 600),
+      body.length > 600 ? `\n(…truncated; total ${body.length} chars)` : "",
+    );
+  } else {
+    parts.push("", "(Page body is empty.)");
+  }
+  if (chatSeed?.outline?.trim()) {
+    parts.push("", "[User-approved outline from chat]", chatSeed.outline.trim().slice(0, 2000));
+  }
+  if (chatSeed?.conversationText?.trim()) {
+    parts.push(
+      "",
+      "[Chat transcript excerpt]",
+      chatSeed.conversationText.trim().slice(0, 4000),
+      chatSeed.conversationText.length > 4000
+        ? `\n(…truncated; total ${chatSeed.conversationText.length} chars)`
+        : "",
+    );
+  }
+  if (chatSeed?.userSchema?.trim()) {
+    parts.push("", "[User wiki schema]", chatSeed.userSchema.trim().slice(0, 1500));
+  }
+  return parts.join("\n");
+}
+
+/**
+ * `brief_dialogue` node — generates the Brief question cards and stamps the
+ * `pageSnapshot` into state.
+ */
+export async function briefDialogue(
+  state: WikiComposeStateType,
+  config: LangGraphRunnableConfig,
+): Promise<WikiComposeStateUpdate> {
+  const ctx = getGraphContext(config);
+
+  await dispatchComposePhase({ phase: "brief", status: "entered" }, config);
+
+  // Load the snapshot once. Subsequent phases read from state, never the DB.
+  // セッション開始時に 1 度だけ読み、以後は state を参照する。
+  const snapshot = state.pageSnapshot ?? (await loadPageSnapshot(ctx.db, ctx.pageId));
+
+  const modelId = await resolveComposeModelId("orchestrator", ctx.backend, ctx.tier, ctx.db);
+  const model = await createZediChatModel({
+    modelId,
+    userId: ctx.userId,
+    tier: ctx.tier,
+    db: ctx.db,
+    feature: `${ctx.feature}:brief`,
+    backend: ctx.backend,
+    temperature: 0.3,
+    maxTokens: 1024,
+  });
+  const structured = model.withStructuredOutput(briefQuestionsSchema, { name: "brief_dialogue" });
+
+  // `structured.invoke` returns the zod input type (pre-default), so we
+  // accept it as-is and apply fallbacks at the projection step below.
+  let raw: z.input<typeof briefQuestionsSchema>;
+  let briefDegraded = false;
+  try {
+    raw = await structured.invoke([
+      { role: "system", content: SYSTEM_PROMPT },
+      {
+        role: "user",
+        content: buildUserPrompt(snapshot.title, snapshot.body, state.chatSeed),
+      },
+    ]);
+  } catch {
+    // Defensive fallback: if the LLM call fails, emit an empty Brief so the
+    // user can still proceed straight to research. `briefDegraded` prevents
+    // `routeAfterBrief` from skipping research on this path (#953).
+    // LLM 失敗時は Brief 0 件で先へ進ませる。`briefDegraded` で調査スキップと区別する。
+    raw = { questions: [] };
+    briefDegraded = true;
+  }
+
+  const briefQuestions: BriefQuestion[] = raw.questions.map((q) => ({
+    id: randomUUID(),
+    question: q.question,
+    rationale: q.rationale,
+    options: (q.options ?? []).map((o) => ({
+      id: randomUUID(),
+      label: o.label,
+      hint: o.hint,
+    })),
+    required: Boolean(q.required),
+  }));
+
+  return {
+    pageSnapshot: snapshot,
+    briefQuestions,
+    briefDegraded,
+    phase: "brief:await_user",
+  };
+}
diff --git a/server/api/src/agents/graphs/wikiCompose/nodes/completed.ts b/server/api/src/agents/graphs/wikiCompose/nodes/completed.ts
new file mode 100644
index 00000000..ab535017
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/nodes/completed.ts
@@ -0,0 +1,66 @@
+/**
+ * `completed` — Wiki Compose terminal node (#950).
+ *
+ * Draft フェーズ後の最終ノード。`draftedSections` を `approvedOutline` の順に
+ * 並べ替えて Markdown を組み立て、`completion` に書き込む。citation source は
+ * `approvedResearch` から実際に引用された分だけ抽出する。`compose_phase` SSE
+ * を `completed` で発火し、ストリームを終了する。
+ *
+ * Pure projection node. Sequences `draftedSections` by `approvedOutline`
+ * order, concatenates them with `## heading` lines, and collates the cited
+ * sources for the final compose output. No LLM call.
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { dispatchComposePhase } from "./shared/dispatch.js";
+import type { WikiComposeStateType, WikiComposeStateUpdate } from "../state.js";
+import type { ComposeCompletion, DraftedSection, Source } from "../types.js";
+
+/** `completed` node — final projection. */
+export async function completed(
+  state: WikiComposeStateType,
+  config: LangGraphRunnableConfig,
+): Promise<WikiComposeStateUpdate> {
+  const outline = state.approvedOutline?.sections ?? [];
+  const draftById = new Map<string, DraftedSection>();
+  for (const d of state.draftedSections) draftById.set(d.sectionId, d);
+
+  // Walk the outline so the final order matches the user's approved layout
+  // even if `draftedSections` was filled in a different order (mid-flight
+  // re-draft, etc.).
+  // ユーザー承認済みアウトラインの順に並べる。
+  const ordered: DraftedSection[] = [];
+  for (const section of outline) {
+    const drafted = draftById.get(section.id);
+    if (drafted) ordered.push(drafted);
+  }
+
+  const lines: string[] = [];
+  for (const section of outline) {
+    const drafted = draftById.get(section.id);
+    if (!drafted) continue;
+    const prefix = "#".repeat(Math.min(3, Math.max(2, section.depth + 1)));
+    lines.push(`${prefix} ${section.heading}`);
+    lines.push("");
+    lines.push(drafted.body);
+    lines.push("");
+  }
+  const markdown = lines.join("\n").trim() + "\n";
+
+  const citedIds = new Set<string>();
+  for (const d of ordered) for (const id of d.citedSourceIds) citedIds.add(id);
+  const citedSources: Source[] = state.approvedResearch.filter((s) => citedIds.has(s.id));
+
+  const completion: ComposeCompletion = {
+    markdown,
+    sections: ordered,
+    citedSources,
+    completedAt: new Date().toISOString(),
+  };
+
+  await dispatchComposePhase({ phase: "completed", status: "entered" }, config);
+
+  return {
+    completion,
+    phase: "completed",
+  };
+}
diff --git a/server/api/src/agents/graphs/wikiCompose/nodes/conflictResolution.ts b/server/api/src/agents/graphs/wikiCompose/nodes/conflictResolution.ts
new file mode 100644
index 00000000..36a27d2d
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/nodes/conflictResolution.ts
@@ -0,0 +1,49 @@
+/**
+ * `conflict_resolution` — HITL step when research approval left conflicting
+ * sources (#953).
+ *
+ * 調査承認で採用・却下が混在し矛盾が疑われるとき、Structure の前に 1 回だけ
+ * 中断してユーザーに確認させる。resume 後は `researchConflicts` をクリアして
+ * Structure へ進む。
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { interrupt } from "@langchain/langgraph";
+import { conflictResumeSchema } from "../resumeSchemas.js";
+import type { WikiComposeStateType, WikiComposeStateUpdate } from "../state.js";
+import type { ResearchConflictSummary, WikiComposeInterruptPayload } from "../types.js";
+import { shouldResolveResearchConflicts } from "../routing.js";
+
+function buildConflictSummary(state: WikiComposeStateType): ResearchConflictSummary {
+  return {
+    approved: state.approvedResearch.map((s) => ({ id: s.id, title: s.title })),
+    rejected: state.rejectedResearch.map((s) => ({ id: s.id, title: s.title })),
+    rationale:
+      "Multiple sources were rejected while others were kept. Confirm you want to proceed " +
+      "with the approved set before generating the outline.",
+  };
+}
+
+/**
+ * Halts when {@link shouldResolveResearchConflicts} was true at the prior edge;
+ * on resume clears the conflict flag and advances to Structure.
+ */
+export async function conflictResolution(
+  state: WikiComposeStateType,
+  _config: LangGraphRunnableConfig,
+): Promise<WikiComposeStateUpdate> {
+  if (!shouldResolveResearchConflicts(state)) {
+    return { phase: "conflict:skipped" };
+  }
+
+  const payload: WikiComposeInterruptPayload = {
+    kind: "conflict_resolution",
+    conflicts: buildConflictSummary(state),
+  };
+  const resumeValue: unknown = interrupt(payload);
+  conflictResumeSchema.parse(resumeValue);
+
+  return {
+    researchConflicts: [],
+    phase: "conflict:resolved",
+  };
+}
diff --git a/server/api/src/agents/graphs/wikiCompose/nodes/draftSections.ts b/server/api/src/agents/graphs/wikiCompose/nodes/draftSections.ts
new file mode 100644
index 00000000..3d0767ac
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/nodes/draftSections.ts
@@ -0,0 +1,234 @@
+/**
+ * `draft_sections` — Wiki Compose Draft phase node (#950).
+ *
+ * 承認済みアウトラインの各セクションを LLM ストリーミングで本文化する。
+ * セクションごとに `compose_section { status: "started" }` を発火し、LLM の
+ * `streamEvents` 経由でトークンが SSE `token` イベントとして流れる
+ * （`sseMapper.mapChatModelStream` が拾う）。1 セクション完了ごとに
+ * `compose_section { status: "completed" }` を出し、`draftedSections` に追記する。
+ *
+ * Sequential per-section streaming: each section is streamed as a single
+ * `stream()` call so the SSE wire produces a `token` event per chunk under
+ * the `draft_sections` node label, which the frontend uses to incrementally
+ * paint into the EditorPane.
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { createZediChatModel } from "../../../core/llm/modelFactory.js";
+import { resolveComposeModelId } from "../../../core/llm/resolveComposeModelId.js";
+import { getGraphContext } from "../../../subgraphs/research/nodes/shared/getGraphContext.js";
+import { dispatchComposePhase, dispatchComposeSection } from "./shared/dispatch.js";
+import type { WikiComposeStateType, WikiComposeStateUpdate } from "../state.js";
+import type { DraftedSection, OutlineSection, Source } from "../types.js";
+
+const SECTION_SYSTEM_PROMPT =
+  "You are a co-author writing one section of a wiki article. Constraints:\n" +
+  "1. Output Markdown body ONLY — do NOT repeat the heading line.\n" +
+  "2. Stay focused on the section's intent. Do not introduce content that " +
+  "belongs to a sibling section.\n" +
+  "3. Cite sources inline as `[#N]` referring to the numbered approved " +
+  "research list. Only cite sources that genuinely support the claim.\n" +
+  "4. Aim for ~250–500 words. Use sub-headings only when depth=2 is " +
+  "specified for sub-sections within the same draft pass.\n" +
+  "5. Plain Markdown; no HTML, no YAML frontmatter.";
+
+function numberedSourceList(sources: Source[], allowedIds?: string[]): string[] {
+  const allow = allowedIds && allowedIds.length > 0 ? new Set(allowedIds) : null;
+  return sources
+    .filter((s) => !allow || allow.has(s.id))
+    .map((s, i) => {
+      const tag = s.kind.toUpperCase();
+      const url = s.finalUrl ?? s.url ?? "";
+      const blurb = s.excerpt ?? s.snippet ?? "";
+      const tail = blurb ? `\n   ${blurb.slice(0, 240)}` : "";
+      return `[#${i + 1}] (${tag}) ${s.title}${url ? ` — ${url}` : ""}${tail}`;
+    });
+}
+
+function buildSectionPrompt(args: {
+  pageTitle: string;
+  section: OutlineSection;
+  outline: OutlineSection[];
+  briefSummary: string;
+  sources: Source[];
+}): string {
+  const { pageTitle, section, outline, briefSummary, sources } = args;
+  const outlineList = outline.map((s) => {
+    const indent = "  ".repeat(Math.max(0, s.depth - 1));
+    const marker = s.id === section.id ? "→" : "•";
+    return `${indent}${marker} ${s.heading} — ${s.intent}`;
+  });
+  const sourceLines = numberedSourceList(sources, section.sourceIds);
+  return [
+    `[Page title]`,
+    pageTitle,
+    "",
+    "[Brief summary]",
+    briefSummary,
+    "",
+    "[Full outline — '→' marks the section you are writing]",
+    ...outlineList,
+    "",
+    "[Section to write]",
+    `heading: ${section.heading}`,
+    `depth: ${section.depth}`,
+    `intent: ${section.intent}`,
+    "",
+    `[Approved sources (${sourceLines.length})]`,
+    ...(sourceLines.length > 0 ? sourceLines : ["(no sources — write conservatively)"]),
+  ].join("\n");
+}
+
+/**
+ * Sum the chunks of a streamed chat result into a single string. We rely on
+ * the LangGraph runtime to also emit each chunk as an `on_chat_model_stream`
+ * event so the SSE mapper produces `token` events the frontend reads.
+ *
+ * ストリーミングの最終結果を 1 本の文字列にまとめる。途中チャンクは
+ * runtime が `on_chat_model_stream` event として吐くので、SSE には別経路で
+ * `token` event が流れる。
+ */
+function chunkContent(chunk: unknown): string {
+  if (!chunk || typeof chunk !== "object") return "";
+  const content = (chunk as { content?: unknown }).content;
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((part) => {
+        if (typeof part === "string") return part;
+        if (
+          part &&
+          typeof part === "object" &&
+          typeof (part as { text?: unknown }).text === "string"
+        ) {
+          return (part as { text: string }).text;
+        }
+        return "";
+      })
+      .join("");
+  }
+  return "";
+}
+
+/** `draft_sections` node — sequential per-section LLM streaming. */
+export async function draftSections(
+  state: WikiComposeStateType,
+  config: LangGraphRunnableConfig,
+): Promise<WikiComposeStateUpdate> {
+  const ctx = getGraphContext(config);
+
+  await dispatchComposePhase({ phase: "draft", status: "entered" }, config);
+
+  const outline = state.approvedOutline?.sections ?? [];
+  if (outline.length === 0) {
+    // Defensive: humanReviewOutline already rejects empty arrays, but if we
+    // somehow arrive here with nothing to write, skip Draft cleanly.
+    // 通常は到達不能だが防御。空アウトラインなら Draft をスキップ。
+    return { draftedSections: [], phase: "draft:completed" };
+  }
+
+  const modelId = await resolveComposeModelId("draft", ctx.backend, ctx.tier, ctx.db);
+  const model = await createZediChatModel({
+    modelId,
+    userId: ctx.userId,
+    tier: ctx.tier,
+    db: ctx.db,
+    feature: `${ctx.feature}:draft`,
+    backend: ctx.backend,
+    temperature: 0.6,
+    maxTokens: 2048,
+  });
+
+  const pageTitle = state.pageSnapshot?.title ?? "(untitled)";
+  const briefSummary = state.brief?.summary ?? "(no brief)";
+  const drafted: DraftedSection[] = [];
+
+  for (let i = 0; i < outline.length; i++) {
+    const section = outline[i] as OutlineSection;
+    await dispatchComposeSection(
+      {
+        sectionId: section.id,
+        heading: section.heading,
+        status: "started",
+        index: i + 1,
+        total: outline.length,
+      },
+      config,
+    );
+
+    let body = "";
+    try {
+      const stream = await model.stream([
+        { role: "system", content: SECTION_SYSTEM_PROMPT },
+        {
+          role: "user",
+          content: buildSectionPrompt({
+            pageTitle,
+            section,
+            outline,
+            briefSummary,
+            sources: state.approvedResearch,
+          }),
+        },
+      ]);
+      for await (const chunk of stream) {
+        body += chunkContent(chunk);
+      }
+    } catch (err) {
+      // Per-section failure must not abort the whole Draft. Surface the
+      // failure as an inline note inside the section body so the user sees
+      // what happened without losing earlier sections.
+      // セクション 1 件の失敗で Draft 全体を止めない。エラーは本文に追記。
+      const message = err instanceof Error ? err.message : String(err);
+      body = body || `*(Section draft failed: ${message})*`;
+    }
+
+    const citedIds = collectCitedSourceIds(body, state.approvedResearch, section.sourceIds);
+    drafted.push({
+      sectionId: section.id,
+      heading: section.heading,
+      body: body.trim(),
+      citedSourceIds: citedIds,
+      completedAt: new Date().toISOString(),
+    });
+
+    await dispatchComposeSection(
+      {
+        sectionId: section.id,
+        heading: section.heading,
+        status: "completed",
+        index: i + 1,
+        total: outline.length,
+      },
+      config,
+    );
+  }
+
+  return {
+    draftedSections: drafted,
+    phase: "draft:completed",
+  };
+}
+
+/**
+ * Best-effort extraction of cited source ids from `[#N]` markers in the body.
+ * Maps each `[#N]` back to the corresponding source by 1-based index over the
+ * allowed-source subset.
+ *
+ * 本文中の `[#N]` 形式の引用マーカーから citedSourceIds を抽出する。
+ */
+function collectCitedSourceIds(
+  body: string,
+  sources: Source[],
+  allowedIds: string[] | undefined,
+): string[] {
+  const allow = allowedIds && allowedIds.length > 0 ? new Set(allowedIds) : null;
+  const candidates = sources.filter((s) => !allow || allow.has(s.id));
+  const matches = new Set<string>();
+  for (const m of body.matchAll(/\[#(\d+)\]/g)) {
+    const n = Number(m[1]);
+    if (!Number.isFinite(n) || n < 1 || n > candidates.length) continue;
+    const candidate = candidates[n - 1];
+    if (candidate) matches.add(candidate.id);
+  }
+  return Array.from(matches);
+}
diff --git a/server/api/src/agents/graphs/wikiCompose/nodes/humanReviewBrief.ts b/server/api/src/agents/graphs/wikiCompose/nodes/humanReviewBrief.ts
new file mode 100644
index 00000000..cde00cfe
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/nodes/humanReviewBrief.ts
@@ -0,0 +1,91 @@
+/**
+ * `human_review_brief` — Wiki Compose Brief interrupt node (#950).
+ *
+ * Brief 質問群を `interrupt(value)` でユーザーに渡し、`PATCH .../resume` の
+ * 結果を `briefResumeSchema` で検証して `brief` を state に確定する。
+ * 既存本文ありで「追記」を選んだ場合は `appendToExisting=true` が立ち、Draft
+ * フェーズがそれを読んで挙動を切り替える。`researchMaxIterations` (1..5) が
+ * 指定されていれば、後段の Research subgraph に渡るようミラーする。
+ *
+ * Halts the graph at the Brief interrupt and projects the user's answers into
+ * `state.brief`. The resume payload's `researchMaxIterations` (when present)
+ * is mirrored to `state.researchMaxIterations` so the research subgraph node
+ * picks it up via its own state slot when invoked.
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { interrupt } from "@langchain/langgraph";
+import { briefResumeSchema } from "../resumeSchemas.js";
+import type { WikiComposeStateType, WikiComposeStateUpdate } from "../state.js";
+import type {
+  BriefAnswer,
+  BriefResult,
+  PageSnapshot,
+  WikiComposeInterruptPayload,
+} from "../types.js";
+
+const EMPTY_SNAPSHOT: PageSnapshot = { pageId: "", title: "", body: "", hasContent: false };
+
+/**
+ * Build the natural-language Brief summary that downstream nodes embed in
+ * their prompts. Keeps the structure stable so prompt-snapshot tests don't
+ * churn on LLM upgrades.
+ *
+ * Brief 確定回答を Markdown で要約する。後段プロンプトに渡す書式を 1 箇所に集約する。
+ */
+function summariseBrief(answers: BriefAnswer[], questions: Map<string, string>): string {
+  if (answers.length === 0) return "(no brief provided)";
+  const lines: string[] = [];
+  for (const a of answers) {
+    const q = questions.get(a.questionId) ?? "(unknown question)";
+    const parts: string[] = [];
+    if (a.selectedOptionIds.length > 0) parts.push(`selected=${a.selectedOptionIds.join(", ")}`);
+    if (a.freeText && a.freeText.trim()) parts.push(`note=${a.freeText.trim()}`);
+    lines.push(`- ${q} → ${parts.join(" | ") || "(no answer)"}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * `human_review_brief` node — interrupt + resume projection.
+ */
+export async function humanReviewBrief(
+  state: WikiComposeStateType,
+  _config: LangGraphRunnableConfig,
+): Promise<WikiComposeStateUpdate> {
+  const payload: WikiComposeInterruptPayload = {
+    kind: "human_review_brief",
+    questions: state.briefQuestions,
+    pageSnapshot: state.pageSnapshot ?? EMPTY_SNAPSHOT,
+  };
+  const resumeValue: unknown = interrupt(payload);
+  const parsed = briefResumeSchema.parse(resumeValue);
+
+  // Index questions by id so we can produce a stable, readable summary.
+  // 質問テキストを id → text で引けるよう、ループの外で 1 度だけ Map 化する。
+  const questionMap = new Map<string, string>();
+  for (const q of state.briefQuestions) questionMap.set(q.id, q.question);
+
+  const answers: BriefAnswer[] = parsed.answers.map((a) => ({
+    questionId: a.questionId,
+    selectedOptionIds: a.selectedOptionIds,
+    ...(a.freeText !== undefined ? { freeText: a.freeText } : {}),
+  }));
+
+  const brief: BriefResult = {
+    answers,
+    summary: summariseBrief(answers, questionMap),
+    appendToExisting: Boolean(parsed.appendToExisting),
+  };
+
+  const update: WikiComposeStateUpdate = {
+    brief,
+    phase: "brief:completed",
+  };
+  if (parsed.researchMaxIterations !== undefined) {
+    // Mirror onto the canonical research subgraph channel name so the
+    // composed research node picks it up via shared state.
+    // research subgraph と共有する `maxIterations` チャネルに反映する。
+    update.maxIterations = parsed.researchMaxIterations;
+  }
+  return update;
+}
diff --git a/server/api/src/agents/graphs/wikiCompose/nodes/humanReviewOutline.ts b/server/api/src/agents/graphs/wikiCompose/nodes/humanReviewOutline.ts
new file mode 100644
index 00000000..919d921c
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/nodes/humanReviewOutline.ts
@@ -0,0 +1,46 @@
+/**
+ * `human_review_outline` — Wiki Compose Structure interrupt node (#950).
+ *
+ * Orchestrator が提案したアウトラインを `interrupt(value)` でユーザーに渡し、
+ * `outlineResumeSchema` で検証して `approvedOutline` を state に確定する。
+ * ユーザーは並び替え・タイトル変更・depth 変更・サブセクション削除が可能
+ * （フロントの outline editor で全部行う）。承認後は Draft フェーズへ。
+ *
+ * Halts at the outline interrupt and projects the user-edited outline back
+ * into state. Validation throws on empty outlines so Draft cannot be entered
+ * with nothing to write.
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { interrupt } from "@langchain/langgraph";
+import { outlineResumeSchema } from "../resumeSchemas.js";
+import type { WikiComposeStateType, WikiComposeStateUpdate } from "../state.js";
+import type { ApprovedOutline, WikiComposeInterruptPayload } from "../types.js";
+
+/** `human_review_outline` node — interrupt + resume projection. */
+export async function humanReviewOutline(
+  state: WikiComposeStateType,
+  _config: LangGraphRunnableConfig,
+): Promise<WikiComposeStateUpdate> {
+  const payload: WikiComposeInterruptPayload = {
+    kind: "human_review_outline",
+    outline: state.outlineProposal,
+    approvedSources: state.approvedResearch,
+  };
+  const resumeValue: unknown = interrupt(payload);
+  const parsed = outlineResumeSchema.parse(resumeValue);
+
+  const approvedOutline: ApprovedOutline = {
+    sections: parsed.sections.map((s) => ({
+      id: s.id,
+      heading: s.heading,
+      depth: s.depth,
+      intent: s.intent,
+      ...(s.sourceIds !== undefined ? { sourceIds: s.sourceIds } : {}),
+    })),
+  };
+
+  return {
+    approvedOutline,
+    phase: "structure:completed",
+  };
+}
diff --git a/server/api/src/agents/graphs/wikiCompose/nodes/index.ts b/server/api/src/agents/graphs/wikiCompose/nodes/index.ts
new file mode 100644
index 00000000..80d4a7b7
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/nodes/index.ts
@@ -0,0 +1,14 @@
+/**
+ * Barrel for Wiki Compose orchestrator graph nodes (#950).
+ *
+ * `wikiComposeGraph.ts` から個別ファイルを import せずに済むようまとめる。
+ * テストでも単一の mock point として使う。
+ */
+export { briefDialogue } from "./briefDialogue.js";
+export { humanReviewBrief } from "./humanReviewBrief.js";
+export { structureDialogue } from "./structureDialogue.js";
+export { humanReviewOutline } from "./humanReviewOutline.js";
+export { draftSections } from "./draftSections.js";
+export { completed } from "./completed.js";
+export { skipResearch } from "./skipResearch.js";
+export { conflictResolution } from "./conflictResolution.js";
diff --git a/server/api/src/agents/graphs/wikiCompose/nodes/shared/dispatch.ts b/server/api/src/agents/graphs/wikiCompose/nodes/shared/dispatch.ts
new file mode 100644
index 00000000..9ee4f584
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/nodes/shared/dispatch.ts
@@ -0,0 +1,41 @@
+/**
+ * Typed wrappers over `dispatchCustomEvent` for the Wiki Compose orchestrator
+ * graph (#950).
+ *
+ * `dispatchCustomEvent` を経由して `compose_phase` / `compose_section` の
+ * custom event を発火する薄いラッパ。`sseMapper.mapCustomEvent` がペイロード
+ * shape を検証するため、ここでは型付きで dispatch するだけで良い。
+ */
+import { dispatchCustomEvent } from "@langchain/core/callbacks/dispatch";
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+
+/** Payload shape for `compose_phase` custom events. */
+export interface ComposePhasePayload {
+  phase: "brief" | "research" | "structure" | "draft" | "completed";
+  status: "entered" | "completed";
+}
+
+/** Payload shape for `compose_section` custom events. */
+export interface ComposeSectionPayload {
+  sectionId: string;
+  heading: string;
+  status: "started" | "completed";
+  index: number;
+  total: number;
+}
+
+/** Dispatch a `compose_phase` SSE custom event. */
+export async function dispatchComposePhase(
+  payload: ComposePhasePayload,
+  config: LangGraphRunnableConfig,
+): Promise<void> {
+  await dispatchCustomEvent("compose_phase", payload, config);
+}
+
+/** Dispatch a `compose_section` SSE custom event. */
+export async function dispatchComposeSection(
+  payload: ComposeSectionPayload,
+  config: LangGraphRunnableConfig,
+): Promise<void> {
+  await dispatchCustomEvent("compose_section", payload, config);
+}
diff --git a/server/api/src/agents/graphs/wikiCompose/nodes/shared/loadPageSnapshot.ts b/server/api/src/agents/graphs/wikiCompose/nodes/shared/loadPageSnapshot.ts
new file mode 100644
index 00000000..2cb365f2
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/nodes/shared/loadPageSnapshot.ts
@@ -0,0 +1,54 @@
+/**
+ * Loads a {@link PageSnapshot} for the Wiki Compose orchestrator graph (#950).
+ *
+ * `briefDialogue` ノードが session 開始時に 1 度だけ呼ぶ。`pages` / `page_versions`
+ * テーブルから現在のタイトル・本文を取得し、Brief 質問生成 / 追記モード判定に
+ * 利用できる軽量レコードを返す。失敗時は空タイトル + 空本文の安全な fallback
+ * を返す（Brief 自体は無タイトルでも 0 件質問で進めるよう設計してある）。
+ *
+ * Reads the target page's current title + body so Brief can suggest informed
+ * questions and Draft can know whether to append vs replace. Falls back to a
+ * zero-content snapshot when the page row cannot be loaded (rare; the route
+ * layer already verified view access before invoking the graph).
+ */
+import { eq } from "drizzle-orm";
+import { pages } from "../../../../../schema/pages.js";
+import type { Database } from "../../../../../types/index.js";
+import type { PageSnapshot } from "../../types.js";
+
+/**
+ * Fetch a page snapshot. The function is intentionally narrow — it only reads
+ * the fields the orchestrator nodes need, so it doesn't drag the full page
+ * accessor service into the agent runtime.
+ */
+export async function loadPageSnapshot(db: Database, pageId: string): Promise<PageSnapshot> {
+  try {
+    const [row] = await db
+      .select({ id: pages.id, title: pages.title, contentPreview: pages.contentPreview })
+      .from(pages)
+      .where(eq(pages.id, pageId))
+      .limit(1);
+    if (!row) return emptySnapshot(pageId);
+    // `pages.content_preview` holds the latest persisted markdown-like preview
+    // of the body (the live document lives in Hocuspocus). For the orchestrator
+    // it's enough to know whether content exists and surface a short excerpt;
+    // we don't need the full Yjs binary.
+    // `pages.content_preview` は本文のプレビュー文字列を保持している（実体は
+    // Hocuspocus）。Brief / Draft の判断には十分なので、ここで読む。
+    const body = typeof row.contentPreview === "string" ? row.contentPreview : "";
+    return {
+      pageId: row.id,
+      title: row.title ?? "",
+      body,
+      hasContent: body.trim().length > 0,
+    };
+  } catch {
+    // Defence in depth: a transient DB error must not crash the whole graph.
+    // The Brief node tolerates an empty snapshot (it just asks broader questions).
+    return emptySnapshot(pageId);
+  }
+}
+
+function emptySnapshot(pageId: string): PageSnapshot {
+  return { pageId, title: "", body: "", hasContent: false };
+}
diff --git a/server/api/src/agents/graphs/wikiCompose/nodes/skipResearch.ts b/server/api/src/agents/graphs/wikiCompose/nodes/skipResearch.ts
new file mode 100644
index 00000000..b95433c0
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/nodes/skipResearch.ts
@@ -0,0 +1,22 @@
+/**
+ * `skip_research` — bypasses the P1 research loop when Brief routing decides
+ * research adds little value (#953).
+ *
+ * Brief ルーティングで調査をスキップするときのノード。`approvedResearch` を
+ * 空にし、exitReason を `brief_skip` にして Structure フェーズへ進む。
+ */
+import type { WikiComposeStateUpdate } from "../state.js";
+
+/**
+ * Project a no-op research outcome so downstream Structure can run without
+ * an extra HITL at `human_review_research`.
+ */
+export async function skipResearch(): Promise<WikiComposeStateUpdate> {
+  return {
+    approvedResearch: [],
+    rejectedResearch: [],
+    batches: [],
+    exitReason: "brief_skip",
+    phase: "research:skipped",
+  };
+}
diff --git a/server/api/src/agents/graphs/wikiCompose/nodes/structureDialogue.ts b/server/api/src/agents/graphs/wikiCompose/nodes/structureDialogue.ts
new file mode 100644
index 00000000..27cd3002
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/nodes/structureDialogue.ts
@@ -0,0 +1,130 @@
+/**
+ * `structure_dialogue` — Wiki Compose Structure phase node (#950).
+ *
+ * Brief 確定回答と採用調査ソースを材料に、3〜10 セクションのアウトライン
+ * 案を Orchestrator LLM に生成させる。Draft フェーズが書きやすい粒度
+ * （= 各セクションが独立して 1 LLM 呼びぶんに収まる）を狙う。生成後は
+ * `outlineProposal` に置き、`compose_phase: { phase: "structure", status: "entered" }`
+ * を発火して `human_review_outline` interrupt に進む。
+ *
+ * Builds an outline proposal that the user can edit before Draft. The
+ * prompt is intentionally narrow on shape (heading + intent) so the
+ * frontend's drag-and-drop editor has stable rows to work with.
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { createZediChatModel } from "../../../core/llm/modelFactory.js";
+import { resolveComposeModelId } from "../../../core/llm/resolveComposeModelId.js";
+import { getGraphContext } from "../../../subgraphs/research/nodes/shared/getGraphContext.js";
+import { dispatchComposePhase } from "./shared/dispatch.js";
+import type { WikiComposeStateType, WikiComposeStateUpdate } from "../state.js";
+import type { OutlineSection } from "../types.js";
+
+/**
+ * Structured output schema. 3..10 sections, depth 1..3, each with a short
+ * intent so the user can spot redundant or off-topic items at a glance.
+ */
+export const outlineProposalSchema = z.object({
+  sections: z
+    .array(
+      z.object({
+        heading: z.string().min(1).max(120),
+        depth: z.number().int().min(1).max(3).default(1),
+        intent: z.string().min(1).max(280),
+      }),
+    )
+    .min(3)
+    .max(10),
+});
+
+const SYSTEM_PROMPT =
+  "You are the orchestrator for Wiki Compose. Produce a section outline for " +
+  "the wiki page based on the Brief answers and the approved research " +
+  "sources. Constraints:\n" +
+  "1. 3..10 sections. Each MUST be writable in a single ~600-word pass.\n" +
+  "2. Use depth=1 for top-level h2 sections, depth=2 for h3 sub-sections.\n" +
+  "3. Each section MUST include a one-sentence `intent` describing what to " +
+  "cover. The user reads this to decide whether to keep / reorder / drop.\n" +
+  "4. Do not include 'Introduction' or 'Conclusion' boilerplate unless the " +
+  "topic genuinely benefits from one.\n" +
+  "Output JSON only.";
+
+function buildUserPrompt(state: WikiComposeStateType): string {
+  const title = state.pageSnapshot?.title ?? "(untitled)";
+  const briefSummary = state.brief?.summary ?? "(no brief provided)";
+  const sources = state.approvedResearch.slice(0, 20).map((s, i) => {
+    const kind = s.kind.toUpperCase();
+    return `[${i + 1}] (${kind}) ${s.title}`;
+  });
+  const sourceBlock = sources.length > 0 ? sources.join("\n") : "(no approved research sources)";
+  return [
+    `[Page title]`,
+    title,
+    "",
+    "[Brief summary]",
+    briefSummary,
+    "",
+    `[Approved research sources: ${state.approvedResearch.length}]`,
+    sourceBlock,
+  ].join("\n");
+}
+
+/** `structure_dialogue` node — proposes the outline. */
+export async function structureDialogue(
+  state: WikiComposeStateType,
+  config: LangGraphRunnableConfig,
+): Promise<WikiComposeStateUpdate> {
+  const ctx = getGraphContext(config);
+
+  await dispatchComposePhase({ phase: "structure", status: "entered" }, config);
+
+  const modelId = await resolveComposeModelId("orchestrator", ctx.backend, ctx.tier, ctx.db);
+  const model = await createZediChatModel({
+    modelId,
+    userId: ctx.userId,
+    tier: ctx.tier,
+    db: ctx.db,
+    feature: `${ctx.feature}:structure`,
+    backend: ctx.backend,
+    temperature: 0.4,
+    maxTokens: 2048,
+  });
+  const structured = model.withStructuredOutput(outlineProposalSchema, {
+    name: "structure_dialogue",
+  });
+
+  // `structured.invoke` returns the zod input type (pre-default); we apply
+  // fallbacks (`depth ?? 1`) at the projection step below.
+  let raw: z.input<typeof outlineProposalSchema>;
+  try {
+    raw = await structured.invoke([
+      { role: "system", content: SYSTEM_PROMPT },
+      { role: "user", content: buildUserPrompt(state) },
+    ]);
+  } catch {
+    // Defensive fallback: emit a minimal 3-section outline so the user can
+    // edit-rather-than-blank-out when the LLM fails (rare). Heading text
+    // intentionally generic so the user is prompted to rename.
+    // LLM 失敗時は 3 セクションの仮アウトラインを返してフローを止めない。
+    raw = {
+      sections: [
+        { heading: "Overview", depth: 1, intent: "Brief introduction to the topic." },
+        { heading: "Key points", depth: 1, intent: "Main facts and context." },
+        { heading: "References", depth: 1, intent: "Sources and further reading." },
+      ],
+    };
+  }
+
+  const outline: OutlineSection[] = raw.sections.map((s) => ({
+    id: randomUUID(),
+    heading: s.heading,
+    depth: s.depth ?? 1,
+    intent: s.intent,
+  }));
+
+  return {
+    outlineProposal: outline,
+    phase: "structure:await_user",
+  };
+}
diff --git a/server/api/src/agents/graphs/wikiCompose/resumeSchemas.ts b/server/api/src/agents/graphs/wikiCompose/resumeSchemas.ts
new file mode 100644
index 00000000..dec5f9d4
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/resumeSchemas.ts
@@ -0,0 +1,78 @@
+/**
+ * Resume payload validators for the Wiki Compose orchestrator graph (#950).
+ *
+ * 各 interrupt 点で `PATCH /api/pages/:pageId/compose-sessions/:id/resume` が
+ * 受け取る `body.resume` の shape を zod で検証する。Brief / Outline それぞれ
+ * 専用のスキーマを持つ（Research は subgraph 側の `researchResumeSchema` を流用）。
+ *
+ * Validates the resume payload submitted via the resume endpoint at each
+ * orchestrator interrupt point. The route layer hands `body.resume` to the
+ * graph and these schemas catch malformed payloads before they pollute state.
+ */
+import { z } from "zod";
+
+/**
+ * Resume payload for `human_review_brief`.
+ *
+ * - `answers` — 必須。空配列でも可（Brief をスキップしたケース）。
+ * - `appendToExisting` — 本文ありページで「追記」を選んだ場合 true。
+ * - `researchMaxIterations` — Brief 内で 1..5 にユーザーが調整した場合のみ。
+ *
+ * Validates the resume payload at the Brief interrupt. `answers` is required
+ * even when empty (the user may explicitly skip Brief by submitting an empty
+ * array). Default for `appendToExisting` is `false` (replace-mode is the
+ * historical Wiki Compose behaviour); `researchMaxIterations` is clamped to
+ * 1..5 by the schema so the graph never sees an out-of-range value.
+ */
+export const briefResumeSchema = z.object({
+  answers: z
+    .array(
+      z.object({
+        questionId: z.string().min(1),
+        selectedOptionIds: z.array(z.string().min(1)).default([]),
+        freeText: z.string().optional(),
+      }),
+    )
+    .default([]),
+  appendToExisting: z.boolean().optional().default(false),
+  researchMaxIterations: z.number().int().min(1).max(5).optional(),
+});
+
+export type BriefResumeParsed = z.infer<typeof briefResumeSchema>;
+
+/**
+ * Resume payload for `human_review_outline`.
+ *
+ * - `sections` — 確定アウトライン。空配列は許容しない（最低 1 セクションは必要）。
+ *
+ * Validates the resume payload at the outline interrupt. The user must
+ * approve at least one section — an empty outline is rejected so Draft does
+ * not try to render an article with no sections.
+ */
+export const outlineResumeSchema = z.object({
+  sections: z
+    .array(
+      z.object({
+        id: z.string().min(1),
+        heading: z.string().min(1),
+        depth: z.number().int().min(1).max(3),
+        intent: z.string().default(""),
+        sourceIds: z.array(z.string().min(1)).optional(),
+      }),
+    )
+    .min(1),
+});
+
+export type OutlineResumeParsed = z.infer<typeof outlineResumeSchema>;
+
+/**
+ * Resume payload for `conflict_resolution` (#953).
+ *
+ * User acknowledges conflicting sources and opts to continue with the approved set.
+ */
+export const conflictResumeSchema = z.object({
+  acknowledged: z.literal(true),
+  note: z.string().optional(),
+});
+
+export type ConflictResumeParsed = z.infer<typeof conflictResumeSchema>;
diff --git a/server/api/src/agents/graphs/wikiCompose/routing.ts b/server/api/src/agents/graphs/wikiCompose/routing.ts
new file mode 100644
index 00000000..ed3e3a06
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/routing.ts
@@ -0,0 +1,56 @@
+/**
+ * Wiki Compose P5 — conditional routing predicates (#953).
+ *
+ * `wikiComposeGraph` の conditional edge が呼ぶ純関数群。LLM や DB に触れず、
+ * state のみから次ノードを決めるため Vitest で単体テストしやすい。
+ *
+ * Pure routing functions for orchestrator conditional edges. No I/O — only
+ * state inspection — so each branch is covered by focused unit tests.
+ *
+ * ## Non-goals (本 Issue では実装しない)
+ * - `media_curator` subgraph（画像スロット分岐）は outline 側のメタデータ設計後に追加。
+ * - Draft 3 回失敗時の `escalate_to_orchestrator` は retry カウンタ設計が必要なため保留。
+ * - pgvector による Wiki Linker 強化は別 Epic。
+ *
+ * ## Extension points
+ * - `routeAfterBrief`: `chatSeed` / Brief 0 件以外のシグナル（例: 明示 `skipResearch`）を足せる。
+ * - `routeAfterResearch`: `researchResumeSchema.flagConflicts` 等の明示フラグと併用可能。
+ * - `routeAfterOutline`: 将来 `OutlineSection.mediaSlots` で `media_curator` へ分岐。
+ */
+import type { WikiComposeStateType } from "./state.js";
+
+/** Edge label after `human_review_brief`. */
+export type BriefRoute = "research" | "skip_research";
+
+/** Edge label after `human_review_research`. */
+export type ResearchRoute = "structure" | "conflict_resolution";
+
+/**
+ * Brief 完了後に調査ループへ進むか Structure へ直行するか。
+ *
+ * Skips research when the Brief intentionally emitted zero questions (title
+ * already clear) or when chat seeded a pre-approved outline. When
+ * `briefDegraded` is set (LLM failure fallback), always run research.
+ */
+export function routeAfterBrief(state: WikiComposeStateType): BriefRoute {
+  if (state.chatSeed?.outline?.trim()) return "skip_research";
+  if (state.briefQuestions.length === 0 && !state.briefDegraded) return "skip_research";
+  return "research";
+}
+
+/**
+ * 調査 HITL 後に矛盾解消ノードへ寄せるか Structure へ進むか。
+ *
+ * Heuristic: user approved some sources but rejected two or more — signals
+ * contradictory evidence worth a dedicated resolution step before outline.
+ */
+export function shouldResolveResearchConflicts(state: WikiComposeStateType): boolean {
+  return state.rejectedResearch.length >= 2 && state.approvedResearch.length >= 1;
+}
+
+/**
+ * Research フェーズ完了後の分岐ラベル。
+ */
+export function routeAfterResearch(state: WikiComposeStateType): ResearchRoute {
+  return shouldResolveResearchConflicts(state) ? "conflict_resolution" : "structure";
+}
diff --git a/server/api/src/agents/graphs/wikiCompose/state.ts b/server/api/src/agents/graphs/wikiCompose/state.ts
new file mode 100644
index 00000000..d8f604f7
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/state.ts
@@ -0,0 +1,229 @@
+/**
+ * `WikiComposeState` — orchestrator-level LangGraph state for Wiki Compose
+ * P2 (#950).
+ *
+ * Wiki Compose 全体グラフの state。`BaseState` (messages / phase / pageId /
+ * userId) を継承しつつ、`ResearchLoopState` の channel 群 (`iteration` /
+ * `pendingSources` / `approvedResearch` 等) を superset として保持することで、
+ * 既存の `researchLoopSubgraph` をそのまま **subgraph as node** として組み込み、
+ * state を自動的に共有させる。Brief / Structure / Draft の各フェーズ専用の
+ * フィールド (`briefQuestions`, `brief`, `outlineProposal`, `approvedOutline`,
+ * `draftedSections`, `completion`) を追加で持つ。
+ *
+ * Extends both `BaseState` and the research subgraph's channels so the compiled
+ * research graph composes as a regular node (LangGraph maps state automatically
+ * when channel names + reducers match). Each phase writes only to its own
+ * slice; reducers are last-write-wins for scalars and id-keyed merge for arrays.
+ *
+ * Issue: otomatty/zedi#950
+ */
+import { Annotation } from "@langchain/langgraph";
+import { BaseState } from "../../core/state/baseState.js";
+import type {
+  AdditionalResearchRequest,
+  Evaluation,
+  ExitReason,
+  PlannedQuery,
+  ResearchBatch,
+  Source,
+} from "../../subgraphs/research/types.js";
+import type {
+  ApprovedOutline,
+  BriefQuestion,
+  BriefResult,
+  ComposeChatSeed,
+  ComposeCompletion,
+  DraftedSection,
+  OutlineSection,
+  PageSnapshot,
+} from "./types.js";
+
+/**
+ * `pendingSources` 用 reducer。id 単位で dedup し、後勝ちで上書きする。
+ * Source merge by id with last-write-wins; mirrors the research subgraph.
+ */
+function mergeSourcesById(prev: Source[], next: Source[] | undefined): Source[] {
+  if (!next || next.length === 0) return prev;
+  const order: string[] = [];
+  const map = new Map<string, Source>();
+  for (const s of prev) {
+    if (!map.has(s.id)) order.push(s.id);
+    map.set(s.id, s);
+  }
+  for (const s of next) {
+    if (!map.has(s.id)) order.push(s.id);
+    map.set(s.id, s);
+  }
+  return order.map((id) => map.get(id) as Source);
+}
+
+/**
+ * `draftedSections` 用 reducer。`sectionId` 単位で last-write-wins し、
+ * 同じセクションを再ドラフトしたときに重複行が増えないようにする。
+ *
+ * Merge drafted sections by `sectionId`.
+ */
+function mergeSectionsById(
+  prev: DraftedSection[],
+  next: DraftedSection[] | undefined,
+): DraftedSection[] {
+  if (!next || next.length === 0) return prev;
+  const order: string[] = [];
+  const map = new Map<string, DraftedSection>();
+  for (const s of prev) {
+    if (!map.has(s.sectionId)) order.push(s.sectionId);
+    map.set(s.sectionId, s);
+  }
+  for (const s of next) {
+    if (!map.has(s.sectionId)) order.push(s.sectionId);
+    map.set(s.sectionId, s);
+  }
+  return order.map((id) => map.get(id) as DraftedSection);
+}
+
+/**
+ * Wiki Compose orchestrator state schema.
+ *
+ * Channel groups:
+ * 1. `BaseState` — messages, phase, pageId, userId.
+ * 2. Research mirror — superset of `ResearchLoopState` channels so the
+ *    compiled research subgraph composes as a node and state flows through.
+ * 3. Brief — `pageSnapshot`, `briefQuestions`, `brief`.
+ * 4. Structure — `outlineProposal`, `approvedOutline`.
+ * 5. Draft / completion — `draftedSections`, `completion`.
+ */
+export const WikiComposeState = Annotation.Root({
+  ...BaseState.spec,
+
+  // ── Brief phase ───────────────────────────────────────────────────────────
+  /**
+   * チャット由来 seed（outline + 会話）。AI Chat / Promote to Wiki からの
+   * 初回 `POST /run` input でセットする (#950)。
+   *
+   * Chat → Compose seed (outline + conversation). Set on the first `POST /run`
+   * input when the user arrives from AI Chat / Promote to Wiki (#950).
+   */
+  chatSeed: Annotation<ComposeChatSeed | null>({
+    reducer: (prev, next) => (next === undefined ? prev : next),
+    default: () => null,
+  }),
+  /** Page snapshot loaded once at session start. */
+  pageSnapshot: Annotation<PageSnapshot | null>({
+    reducer: (prev, next) => (next === undefined ? prev : next),
+    default: () => null,
+  }),
+  /** Brief 質問群（0..7）。`briefDialogue` が一度だけ全置換する。 */
+  briefQuestions: Annotation<BriefQuestion[]>({
+    reducer: (_prev, next) => next,
+    default: () => [],
+  }),
+  /** Brief 確定結果。`humanReviewBrief` が resume payload を投影する。 */
+  brief: Annotation<BriefResult | null>({
+    reducer: (prev, next) => (next === undefined ? prev : next),
+    default: () => null,
+  }),
+  /**
+   * True when `brief_dialogue` used the LLM error fallback (empty questions).
+   * Routing must not treat this as an intentional "skip research" signal (#953).
+   *
+   * `brief_dialogue` が LLM 失敗フォールバックで空質問になったとき true。
+   * ルーティングで調査スキップと混同しない。
+   */
+  briefDegraded: Annotation<boolean>({
+    reducer: (_prev, next) => next,
+    default: () => false,
+  }),
+
+  // ── Research mirror (matches ResearchLoopState exactly) ──────────────────
+  /** 現在のループ回数（research subgraph が書く）。 */
+  iteration: Annotation<number>({
+    reducer: (_prev, next) => next,
+    default: () => 0,
+  }),
+  /** ループ上限（Brief で 1..5 にユーザー設定可、デフォルト 3）。 */
+  maxIterations: Annotation<number>({
+    reducer: (prev, next) => next ?? prev,
+    default: () => 3,
+  }),
+  /** Research subgraph 内の直近クエリ。 */
+  queries: Annotation<PlannedQuery[]>({
+    reducer: (_prev, next) => next,
+    default: () => [],
+  }),
+  /** 蓄積調査ソース（research subgraph が書く）。 */
+  pendingSources: Annotation<Source[]>({
+    reducer: mergeSourcesById,
+    default: () => [],
+  }),
+  /** 直近の評価。 */
+  lastEvaluation: Annotation<Evaluation | null>({
+    reducer: (_prev, next) => next,
+    default: () => null,
+  }),
+  /** 終了理由。 */
+  exitReason: Annotation<ExitReason | null>({
+    reducer: (_prev, next) => next,
+    default: () => null,
+  }),
+  /** 各ループの compile_batch スナップショット。 */
+  batches: Annotation<ResearchBatch[]>({
+    reducer: (prev, next) => (next === undefined ? prev : [...prev, ...next]),
+    default: () => [],
+  }),
+  /** 採用ソース。`human_review_research` が resume 値から projection する。 */
+  approvedResearch: Annotation<Source[]>({
+    reducer: (_prev, next) => next,
+    default: () => [],
+  }),
+  /** 除外ソース。 */
+  rejectedResearch: Annotation<Source[]>({
+    reducer: (_prev, next) => next,
+    default: () => [],
+  }),
+  /** 追加調査リクエスト（route 経由で投入）。 */
+  additionalRequest: Annotation<AdditionalResearchRequest | null>({
+    reducer: (prev, next) => (next === undefined ? prev : next),
+    default: () => null,
+  }),
+  /**
+   * P5 conflict-resolution marker. Populated before `conflict_resolution` interrupt;
+   * cleared on resume. Routing uses `rejectedResearch` counts; this channel is for
+   * future explicit conflict metadata from evaluate / resume payloads.
+   *
+   * P5 矛盾解消用マーカー。将来 evaluate や resume から明示的な矛盾リストを載せる。
+   */
+  researchConflicts: Annotation<string[]>({
+    reducer: (_prev, next) => next,
+    default: () => [],
+  }),
+
+  // ── Structure phase ──────────────────────────────────────────────────────
+  /** Orchestrator が提案する初期アウトライン。 */
+  outlineProposal: Annotation<OutlineSection[]>({
+    reducer: (_prev, next) => next,
+    default: () => [],
+  }),
+  /** ユーザー承認後の確定アウトライン。 */
+  approvedOutline: Annotation<ApprovedOutline | null>({
+    reducer: (prev, next) => (next === undefined ? prev : next),
+    default: () => null,
+  }),
+
+  // ── Draft / completion ───────────────────────────────────────────────────
+  /** 確定済みセクション本文。`draftSections` が 1 セクションずつ append する。 */
+  draftedSections: Annotation<DraftedSection[]>({
+    reducer: mergeSectionsById,
+    default: () => [],
+  }),
+  /** 完了サマリ。`completed` ノードが書く。 */
+  completion: Annotation<ComposeCompletion | null>({
+    reducer: (prev, next) => (next === undefined ? prev : next),
+    default: () => null,
+  }),
+});
+
+/** `WikiComposeState.State` のショートカット。 */
+export type WikiComposeStateType = typeof WikiComposeState.State;
+
+/** `WikiComposeState.Update` のショートカット。ノードの戻り値型。 */
+export type WikiComposeStateUpdate = typeof WikiComposeState.Update;
diff --git a/server/api/src/agents/graphs/wikiCompose/types.ts b/server/api/src/agents/graphs/wikiCompose/types.ts
new file mode 100644
index 00000000..520cd4db
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/types.ts
@@ -0,0 +1,234 @@
+/**
+ * Shared value types for the Wiki Compose orchestrator graph (#950 / P2).
+ *
+ * Wiki Compose 全体グラフが扱う値型。
+ * `WikiComposeState` (state.ts) と各ノードが参照する。
+ *
+ * Pure data types referenced by `WikiComposeState` and the orchestrator nodes.
+ * Kept separate from `Annotation.Root` so non-LangGraph modules (frontend
+ * wire types, vitest fixtures) can import without pulling LangGraph runtime.
+ */
+
+import type { Source } from "../../subgraphs/research/types.js";
+
+/** Re-exported here so orchestrator nodes can import everything from one barrel. */
+export type { Source };
+
+/**
+ * チャットから Compose に入ったときの任意 seed (#950)。
+ * 初回 `POST /run` の input とセッション行 `metadata` に載せる。
+ *
+ * Optional chat context seeded when entering Compose from AI Chat (#950).
+ * Passed on the first graph `input` and stored on the session row metadata.
+ */
+export interface ComposeChatSeed {
+  outline: string;
+  conversationText: string;
+  userSchema?: string;
+  conversationId?: string;
+}
+
+/**
+ * Brief フェーズで Orchestrator が生成する 1 つの構造化質問。
+ *
+ * One structured Brief question. Brief never opens a free-form chat; the
+ * frontend renders this as a question card with selectable options + an
+ * optional free-text addendum. `0..7` questions are emitted (the Orchestrator
+ * decides; `0` means "skip Brief entirely").
+ */
+export interface BriefQuestion {
+  /** Stable uuid. */
+  id: string;
+  /** Question text shown to the user. */
+  question: string;
+  /**
+   * Optional rationale shown as helper text. Surfaced so the user understands
+   * why each question matters.
+   */
+  rationale?: string;
+  /**
+   * Answer choices (option chips). When empty, the UI renders a single
+   * free-text input. The frontend always allows a free-text addendum on top
+   * of any chip selection.
+   */
+  options: BriefOption[];
+  /** Whether the user MUST answer this question to proceed. */
+  required: boolean;
+}
+
+/** One selectable option chip in a {@link BriefQuestion}. */
+export interface BriefOption {
+  /** Stable id within the question (used by the resume payload). */
+  id: string;
+  /** Display label. */
+  label: string;
+  /** Optional follow-up hint shown when this option is selected. */
+  hint?: string;
+}
+
+/**
+ * User's reply to a single Brief question. Resume payload value.
+ *
+ * Brief 質問への 1 件分の回答（resume payload の単位）。
+ */
+export interface BriefAnswer {
+  /** Question id this answer responds to. */
+  questionId: string;
+  /** Selected option ids (may be empty when only free-text is provided). */
+  selectedOptionIds: string[];
+  /** Optional free-text addendum (always allowed). */
+  freeText?: string;
+}
+
+/**
+ * Aggregated Brief result projected into state after the user resumes.
+ *
+ * Brief 完了時に state に投影される確定回答セット。`structureDialogue` と
+ * `researchPhase` がプロンプト構築時にここを読む。
+ */
+export interface BriefResult {
+  /** Question/answer pairs in their original order. */
+  answers: BriefAnswer[];
+  /**
+   * Free-form natural-language summary derived from the answers. Used by
+   * downstream nodes so they do not have to re-traverse the Q&A pairs.
+   */
+  summary: string;
+  /**
+   * Optional addition mode flag — populated when the page already has body
+   * content and the user chose "append" instead of "replace". The draft
+   * phase reads this to decide whether to write into a fresh document or to
+   * merge with the existing body.
+   */
+  appendToExisting: boolean;
+}
+
+/**
+ * Page snapshot loaded at session start. Used by Brief to surface the
+ * current page state and by Draft to know whether to append vs replace.
+ *
+ * セッション開始時に読み込むページのスナップショット。Brief / Draft が参照する。
+ */
+export interface PageSnapshot {
+  pageId: string;
+  /** Wiki page title. */
+  title: string;
+  /** Existing body markdown (may be empty). */
+  body: string;
+  /** True when `body.trim().length > 0`. */
+  hasContent: boolean;
+}
+
+/**
+ * Structure フェーズで生成された 1 つのアウトライン項目。
+ *
+ * Single outline node. The orchestrator emits a flat or 1-level nested list;
+ * the frontend supports drag-and-drop reordering before approval.
+ */
+export interface OutlineSection {
+  /** Stable uuid. */
+  id: string;
+  /** Section heading text (without `# ` prefix). */
+  heading: string;
+  /** Heading depth (1 = top-level h2, 2 = h3, …; the page title itself is h1). */
+  depth: number;
+  /**
+   * Short description / what to cover. Surfaced as helper text in the outline
+   * editor and consumed by the draft node as the section brief.
+   */
+  intent: string;
+  /**
+   * Optional list of source ids (from `approvedResearch`) that the user
+   * marked as relevant for this section. Populated post-approval via the
+   * outline resume payload.
+   */
+  sourceIds?: string[];
+}
+
+/**
+ * Outline approved by the user via the `human_review_outline` interrupt.
+ *
+ * `humanReviewOutline` が resume payload を投影して作る。Draft フェーズが
+ * 各セクションを順に LLM ストリームで書き起こす。
+ */
+export interface ApprovedOutline {
+  /** Final ordered sections (after user edits). */
+  sections: OutlineSection[];
+}
+
+/**
+ * Section draft result. One per outline section, filled in by
+ * `draft_sections` as it streams.
+ *
+ * 確定済みの 1 セクション分本文。各セクションは LLM トークンストリームで
+ * 書き起こされ、確定後に本配列へ append される。
+ */
+export interface DraftedSection {
+  /** Matches {@link OutlineSection.id}. */
+  sectionId: string;
+  /** Final heading (may differ if user renamed mid-flight). */
+  heading: string;
+  /** Final markdown body for the section (excluding the heading). */
+  body: string;
+  /** Source ids cited in this section (subset of `approvedResearch`). */
+  citedSourceIds: string[];
+  /** ISO timestamp when the section completed. */
+  completedAt: string;
+}
+
+/**
+ * Final compose output stamped onto state at the `completed` node.
+ *
+ * 完了時のサマリ。フロントは `/notes/:noteId/:pageId` に戻るときの最終本文を
+ * ここから読む。
+ */
+export interface ComposeCompletion {
+  /** Final markdown body (sections joined). */
+  markdown: string;
+  /** Sections in their final order. */
+  sections: DraftedSection[];
+  /** Approved sources collated for citation export. */
+  citedSources: Source[];
+  /** ISO timestamp at completion. */
+  completedAt: string;
+}
+
+/**
+ * Discriminated union of the values emitted by the orchestrator's interrupt
+ * nodes. Surfaces on the wire as `SseInterruptEvent.payload`.
+ *
+ * 各 interrupt ノードが `interrupt(value)` で渡すペイロード。フロントは
+ * `kind` で分岐して UI を出し分ける。
+ */
+/** Lightweight conflict summary for the P5 `conflict_resolution` interrupt. */
+export interface ResearchConflictSummary {
+  approved: Array<{ id: string; title: string }>;
+  rejected: Array<{ id: string; title: string }>;
+  rationale: string;
+}
+
+export type WikiComposeInterruptPayload =
+  | { kind: "human_review_brief"; questions: BriefQuestion[]; pageSnapshot: PageSnapshot }
+  | { kind: "human_review_research"; batchId: string | null; pendingSources: Source[] }
+  | { kind: "human_review_outline"; outline: OutlineSection[]; approvedSources: Source[] }
+  | { kind: "conflict_resolution"; conflicts: ResearchConflictSummary };
+
+/**
+ * Resume payloads expected at each interrupt point. Each is validated at the
+ * node boundary via the matching zod schema in `resumeSchemas.ts`.
+ *
+ * 各 interrupt 点の resume payload TS 型。実体は zod で検証する。
+ */
+export interface BriefResumeInput {
+  answers: BriefAnswer[];
+  /** True when the user chose "append to existing body" (U2). */
+  appendToExisting?: boolean;
+  /** Optional override for the research loop's max iterations (1..5). */
+  researchMaxIterations?: number;
+}
+
+/** Resume payload for the outline interrupt. */
+export interface OutlineResumeInput {
+  /** Final outline (reordered / edited by the user). */
+  sections: OutlineSection[];
+}
diff --git a/server/api/src/agents/graphs/wikiCompose/wikiComposeGraph.ts b/server/api/src/agents/graphs/wikiCompose/wikiComposeGraph.ts
new file mode 100644
index 00000000..137295ed
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/wikiComposeGraph.ts
@@ -0,0 +1,144 @@
+/**
+ * Wiki Compose P2/P5 — `wikiComposeGraph` orchestrator (#950, #953).
+ *
+ * Brief → (optional Research) → (optional Conflict resolution) → Structure →
+ * Draft → Completed の全体フローを担う LangGraph オーケストレータ。
+ *
+ * P5 adds conditional edges:
+ * - After Brief: skip research when questions are empty or chat seeded an outline.
+ * - After Research HITL: conflict resolution when many sources were rejected.
+ *
+ * Top-level orchestrator. Research nodes are inlined so state channels are shared
+ * and interrupts halt the same `thread_id`. See `routing.ts` for branch predicates.
+ *
+ * Pipeline:
+ *
+ * ```
+ * START → brief_dialogue → human_review_brief
+ *   ├─[research]→ plan_queries → … → human_review_research
+ *   └─[skip_research]→ skip_research ────────────────┐
+ *                                                    ↓
+ * human_review_research ─┬─[structure]──────────────┤
+ *                        └─[conflict_resolution]→ conflict_resolution
+ *                                                    ↓
+ *                              structure_dialogue → human_review_outline
+ *                              → draft_sections → completed → END
+ * ```
+ *
+ * ## Non-goals (P5 / #953)
+ * - `media_curator` subgraph, draft failure escalation, session TTL GC — tracked separately.
+ *
+ * ## Extension points
+ * - Add `routeAfterOutline` for image-slot sections.
+ * - Register sibling graphs via `GraphRegistry` (`wiki-maintenance`, template compose, …).
+ */
+import { END, START, StateGraph } from "@langchain/langgraph";
+import { WikiComposeState } from "./state.js";
+import {
+  registerGraph,
+  type GraphFactory,
+  type GraphFactoryInput,
+  type CompiledGraphLike,
+} from "../../registry/graphRegistry.js";
+import {
+  planQueries,
+  webSearch,
+  wikiSearch,
+  fetchArticles,
+  evaluateSufficiency,
+  refineQueries,
+  compileBatch,
+  humanReviewResearch,
+} from "../../subgraphs/research/nodes/index.js";
+import {
+  briefDialogue,
+  humanReviewBrief,
+  structureDialogue,
+  humanReviewOutline,
+  draftSections,
+  completed,
+  skipResearch,
+  conflictResolution,
+} from "./nodes/index.js";
+import { shouldRefine } from "../../subgraphs/research/researchGraph.js";
+import { routeAfterBrief, routeAfterResearch } from "./routing.js";
+
+/** Registered graph id. */
+export const WIKI_COMPOSE_GRAPH_ID = "wiki-compose" as const;
+/** Registered graph version. Bump when behaviour changes meaningfully. */
+export const WIKI_COMPOSE_GRAPH_VERSION = "1.1.0";
+
+const factory: GraphFactory = ({ checkpointer }: GraphFactoryInput): CompiledGraphLike => {
+  const builder = new StateGraph(WikiComposeState)
+    // Brief phase
+    .addNode("brief_dialogue", briefDialogue)
+    .addNode("human_review_brief", humanReviewBrief)
+    .addNode("skip_research", skipResearch)
+    // Research phase (inlined research subgraph nodes, sharing state)
+    .addNode("plan_queries", planQueries)
+    .addNode("web_search", webSearch)
+    .addNode("wiki_search", wikiSearch)
+    .addNode("fetch_articles", fetchArticles)
+    .addNode("evaluate_sufficiency", evaluateSufficiency)
+    .addNode("refine_queries", refineQueries)
+    .addNode("compile_batch", compileBatch)
+    .addNode("human_review_research", humanReviewResearch)
+    .addNode("conflict_resolution", conflictResolution)
+    // Structure phase
+    .addNode("structure_dialogue", structureDialogue)
+    .addNode("human_review_outline", humanReviewOutline)
+    // Draft + completion
+    .addNode("draft_sections", draftSections)
+    .addNode("completed", completed)
+    // Edges
+    .addEdge(START, "brief_dialogue")
+    .addEdge("brief_dialogue", "human_review_brief")
+    .addConditionalEdges("human_review_brief", routeAfterBrief, {
+      research: "plan_queries",
+      skip_research: "skip_research",
+    })
+    .addEdge("skip_research", "structure_dialogue")
+    // Research loop (mirrors researchLoopSubgraph wiring).
+    .addEdge("plan_queries", "web_search")
+    .addEdge("plan_queries", "wiki_search")
+    .addEdge("web_search", "fetch_articles")
+    .addEdge("wiki_search", "fetch_articles")
+    .addEdge("fetch_articles", "evaluate_sufficiency")
+    .addConditionalEdges("evaluate_sufficiency", shouldRefine, {
+      refine: "refine_queries",
+      compile: "compile_batch",
+    })
+    .addEdge("refine_queries", "web_search")
+    .addEdge("refine_queries", "wiki_search")
+    .addEdge("compile_batch", "human_review_research")
+    .addConditionalEdges("human_review_research", routeAfterResearch, {
+      structure: "structure_dialogue",
+      conflict_resolution: "conflict_resolution",
+    })
+    .addEdge("conflict_resolution", "structure_dialogue")
+    // Structure phase.
+    .addEdge("structure_dialogue", "human_review_outline")
+    .addEdge("human_review_outline", "draft_sections")
+    // Draft + completion.
+    .addEdge("draft_sections", "completed")
+    .addEdge("completed", END);
+
+  return checkpointer ? builder.compile({ checkpointer }) : builder.compile();
+};
+
+/**
+ * Register the Wiki Compose orchestrator graph. Idempotent.
+ */
+export function registerWikiComposeGraph(): void {
+  registerGraph({
+    id: WIKI_COMPOSE_GRAPH_ID,
+    version: WIKI_COMPOSE_GRAPH_VERSION,
+    phase: "orchestrator",
+    description:
+      "Wiki Compose P2+P5 orchestrator. Brief → optional research → optional conflict resolution → " +
+      "structure → draft → completed. Conditional: skip research (empty Brief / chat outline seed), " +
+      "conflict resolution (≥2 rejected sources with ≥1 approved). Interrupts: brief, research, " +
+      "conflict (conditional), outline.",
+    factory,
+  });
+}
diff --git a/server/api/src/agents/graphs/wikiMaintenance/index.ts b/server/api/src/agents/graphs/wikiMaintenance/index.ts
new file mode 100644
index 00000000..59a890c3
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiMaintenance/index.ts
@@ -0,0 +1,15 @@
+/**
+ * Wiki maintenance graph — public barrel (#953).
+ * Wikiメンテナンスグラフの公開バレル（#953）。
+ */
+export {
+  WIKI_MAINTENANCE_GRAPH_ID,
+  WIKI_MAINTENANCE_GRAPH_VERSION,
+  registerWikiMaintenanceGraph,
+} from "./wikiMaintenanceGraph.js";
+export {
+  WikiMaintenanceState,
+  type WikiMaintenanceStateType,
+  type WikiMaintenanceStateUpdate,
+} from "./state.js";
+export type { MaintenanceFinding, MaintenancePlan } from "./types.js";
diff --git a/server/api/src/agents/graphs/wikiMaintenance/nodes/index.ts b/server/api/src/agents/graphs/wikiMaintenance/nodes/index.ts
new file mode 100644
index 00000000..e7353ef1
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiMaintenance/nodes/index.ts
@@ -0,0 +1,3 @@
+export { scanBrokenLinks } from "./scanBrokenLinks.js";
+export { scanStubPages } from "./scanStubPages.js";
+export { planMaintenance } from "./planMaintenance.js";
diff --git a/server/api/src/agents/graphs/wikiMaintenance/nodes/planMaintenance.ts b/server/api/src/agents/graphs/wikiMaintenance/nodes/planMaintenance.ts
new file mode 100644
index 00000000..43bc927f
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiMaintenance/nodes/planMaintenance.ts
@@ -0,0 +1,21 @@
+/**
+ * `plan_maintenance` — aggregates scan results into a single plan object.
+ */
+import type { WikiMaintenanceStateType, WikiMaintenanceStateUpdate } from "../state.js";
+import type { MaintenancePlan } from "../types.js";
+
+export async function planMaintenance(
+  state: WikiMaintenanceStateType,
+): Promise<WikiMaintenanceStateUpdate> {
+  const findings = [...state.brokenLinkFindings, ...state.stubPageFindings];
+  const plan: MaintenancePlan = {
+    brokenLinkCount: state.brokenLinkFindings.length,
+    stubPageCount: state.stubPageFindings.length,
+    findings,
+    plannedAt: new Date().toISOString(),
+  };
+  return {
+    maintenancePlan: plan,
+    phase: "maintenance:planned",
+  };
+}
diff --git a/server/api/src/agents/graphs/wikiMaintenance/nodes/scanBrokenLinks.ts b/server/api/src/agents/graphs/wikiMaintenance/nodes/scanBrokenLinks.ts
new file mode 100644
index 00000000..c007124e
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiMaintenance/nodes/scanBrokenLinks.ts
@@ -0,0 +1,26 @@
+/**
+ * `scan_broken_links` — runs the broken-link lint rule for the session owner.
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { runBrokenLinkRule } from "../../../../services/lintEngine/rules/brokenLink.js";
+import { getGraphContext } from "../../../subgraphs/research/nodes/shared/getGraphContext.js";
+import type { WikiMaintenanceStateUpdate } from "../state.js";
+import type { MaintenanceFinding } from "../types.js";
+
+export async function scanBrokenLinks(
+  _state: unknown,
+  config: LangGraphRunnableConfig,
+): Promise<WikiMaintenanceStateUpdate> {
+  const ctx = getGraphContext(config);
+  const result = await runBrokenLinkRule(ctx.userId, ctx.db);
+  const brokenLinkFindings: MaintenanceFinding[] = result.findings.map((f) => ({
+    rule: "broken_link",
+    severity: f.severity,
+    pageIds: f.pageIds,
+    detail: f.detail as Record<string, unknown>,
+  }));
+  return {
+    brokenLinkFindings,
+    phase: "maintenance:broken_links_scanned",
+  };
+}
diff --git a/server/api/src/agents/graphs/wikiMaintenance/nodes/scanStubPages.ts b/server/api/src/agents/graphs/wikiMaintenance/nodes/scanStubPages.ts
new file mode 100644
index 00000000..1c4c27b6
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiMaintenance/nodes/scanStubPages.ts
@@ -0,0 +1,54 @@
+/**
+ * `scan_stub_pages` — detects pages with very little stored preview text.
+ *
+ * Full Y.Doc bodies live in Hocuspocus; `pages.content_preview` is the best
+ * server-side heuristic for "stub" pages without pulling every document.
+ */
+import { and, asc, eq, or, isNull, sql } from "drizzle-orm";
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { pages } from "../../../../schema/pages.js";
+import { getGraphContext } from "../../../subgraphs/research/nodes/shared/getGraphContext.js";
+import type { WikiMaintenanceStateUpdate } from "../state.js";
+import type { MaintenanceFinding } from "../types.js";
+
+/** Minimum trimmed preview length to treat a page as non-stub. */
+const STUB_PREVIEW_MAX_LEN = 40;
+
+export async function scanStubPages(
+  _state: unknown,
+  config: LangGraphRunnableConfig,
+): Promise<WikiMaintenanceStateUpdate> {
+  const ctx = getGraphContext(config);
+  const rows = await ctx.db
+    .select({ id: pages.id, title: pages.title })
+    .from(pages)
+    .where(
+      and(
+        eq(pages.ownerId, ctx.userId),
+        eq(pages.isDeleted, false),
+        or(
+          isNull(pages.contentPreview),
+          sql`length(trim(${pages.contentPreview})) < ${STUB_PREVIEW_MAX_LEN}`,
+        ),
+      ),
+    )
+    .orderBy(asc(pages.id))
+    .limit(200);
+
+  const stubPageFindings: MaintenanceFinding[] = rows.map((p) => ({
+    rule: "stub_page",
+    severity: "info",
+    pageIds: [p.id],
+    detail: {
+      title: p.title ?? "(無題 / untitled)",
+      suggestion:
+        "プレビューが空または極端に短いです。本文の拡充やスタブへのリンクを検討してください / " +
+        "Page preview is empty or very short. Consider expanding or linking this stub.",
+    },
+  }));
+
+  return {
+    stubPageFindings,
+    phase: "maintenance:stub_pages_scanned",
+  };
+}
diff --git a/server/api/src/agents/graphs/wikiMaintenance/state.ts b/server/api/src/agents/graphs/wikiMaintenance/state.ts
new file mode 100644
index 00000000..218ac601
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiMaintenance/state.ts
@@ -0,0 +1,33 @@
+/**
+ * `WikiMaintenanceState` — LangGraph state for wiki maintenance (#953).
+ */
+import { Annotation } from "@langchain/langgraph";
+import { BaseState } from "../../core/state/baseState.js";
+import type { MaintenanceFinding, MaintenancePlan } from "./types.js";
+
+export const WikiMaintenanceState = Annotation.Root({
+  ...BaseState.spec,
+  brokenLinkFindings: Annotation<MaintenanceFinding[]>({
+    reducer: (_prev, next) => next,
+    default: () => [],
+  }),
+  stubPageFindings: Annotation<MaintenanceFinding[]>({
+    reducer: (_prev, next) => next,
+    default: () => [],
+  }),
+  maintenancePlan: Annotation<MaintenancePlan | null>({
+    reducer: (prev, next) => (next === undefined ? prev : next),
+    default: () => null,
+  }),
+});
+
+/**
+ * Materialized state shape for wiki maintenance graph execution.
+ * Wiki メンテナンス graph 実行時の確定 state 形状。
+ */
+export type WikiMaintenanceStateType = typeof WikiMaintenanceState.State;
+/**
+ * Partial update returned by wiki maintenance nodes.
+ * Wiki メンテナンス各ノードが返す部分更新。
+ */
+export type WikiMaintenanceStateUpdate = typeof WikiMaintenanceState.Update;
diff --git a/server/api/src/agents/graphs/wikiMaintenance/types.ts b/server/api/src/agents/graphs/wikiMaintenance/types.ts
new file mode 100644
index 00000000..eb8d2e20
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiMaintenance/types.ts
@@ -0,0 +1,25 @@
+/**
+ * Value types for the Wiki maintenance graph (#953).
+ *
+ * Wiki メンテナンス graph が扱う検出結果・プランの型。LangGraph state から分離し、
+ * テスト fixture が runtime を import しなくて済むようにする。
+ */
+
+/** One lint-style finding projected into graph state. */
+export interface MaintenanceFinding {
+  rule: "broken_link" | "stub_page";
+  severity: "error" | "warn" | "info";
+  pageIds: string[];
+  detail: Record<string, unknown>;
+}
+
+/**
+ * Aggregated maintenance plan emitted at the end of the graph.
+ */
+export interface MaintenancePlan {
+  brokenLinkCount: number;
+  stubPageCount: number;
+  findings: MaintenanceFinding[];
+  /** ISO timestamp when the plan was assembled. */
+  plannedAt: string;
+}
diff --git a/server/api/src/agents/graphs/wikiMaintenance/wikiMaintenanceGraph.ts b/server/api/src/agents/graphs/wikiMaintenance/wikiMaintenanceGraph.ts
new file mode 100644
index 00000000..8d1378ca
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiMaintenance/wikiMaintenanceGraph.ts
@@ -0,0 +1,51 @@
+/**
+ * Wiki Compose P5 — `wikiMaintenanceGraph` (#953).
+ *
+ * リンク切れ検出・スタブページ検出を順に走らせ、メンテナンスプランを返す。
+ * Compose orchestrator とは独立した graphId で `GraphRegistry` に登録する。
+ *
+ * Linear graph: `scan_broken_links` → `scan_stub_pages` → `plan_maintenance` → END.
+ * No HITL interrupts in P5 — future versions may add repair subgraphs per finding.
+ *
+ * ## Non-goals
+ * - Automatic link repair or page creation (human or a future repair graph).
+ * - Full Y.Doc body analysis (uses `content_preview` heuristic only).
+ *
+ * ## Extension points
+ * - Additional scan nodes (orphan, ghost_many, stale) via parallel fan-out.
+ * - Conditional routing when `brokenLinkCount === 0` to skip LLM planning steps.
+ */
+import { END, START, StateGraph } from "@langchain/langgraph";
+import { registerGraph, type GraphFactory } from "../../registry/graphRegistry.js";
+import { WikiMaintenanceState } from "./state.js";
+import { scanBrokenLinks, scanStubPages, planMaintenance } from "./nodes/index.js";
+
+/** Registered graph id. */
+export const WIKI_MAINTENANCE_GRAPH_ID = "wiki-maintenance" as const;
+export const WIKI_MAINTENANCE_GRAPH_VERSION = "1.0.0";
+
+const factory: GraphFactory = ({ checkpointer }) => {
+  const builder = new StateGraph(WikiMaintenanceState)
+    .addNode("scan_broken_links", scanBrokenLinks)
+    .addNode("scan_stub_pages", scanStubPages)
+    .addNode("plan_maintenance", planMaintenance)
+    .addEdge(START, "scan_broken_links")
+    .addEdge("scan_broken_links", "scan_stub_pages")
+    .addEdge("scan_stub_pages", "plan_maintenance")
+    .addEdge("plan_maintenance", END);
+
+  return checkpointer ? builder.compile({ checkpointer }) : builder.compile();
+};
+
+/** Register the wiki maintenance graph. Idempotent; call from `app.ts` bootstrap. */
+export function registerWikiMaintenanceGraph(): void {
+  registerGraph({
+    id: WIKI_MAINTENANCE_GRAPH_ID,
+    version: WIKI_MAINTENANCE_GRAPH_VERSION,
+    phase: "maintenance",
+    description:
+      "Wiki maintenance P5: scan broken links (lint rule) and stub pages (short content_preview), " +
+      "then emit a MaintenancePlan. No interrupts; suitable for background / admin runs.",
+    factory,
+  });
+}
diff --git a/server/api/src/agents/index.ts b/server/api/src/agents/index.ts
new file mode 100644
index 00000000..01970925
--- /dev/null
+++ b/server/api/src/agents/index.ts
@@ -0,0 +1,140 @@
+/**
+ * Wiki Compose agent infrastructure — public barrel.
+ *
+ * `server/api` の他レイヤから agent モジュールを参照する際の唯一の入口。サブ
+ * パス (`agents/runner/...` 等) を直接 import するより、本ファイル経由で抽象を
+ * 維持することで、内部リファクタの影響範囲を限定する。
+ *
+ * Single entry barrel for the agent subsystem. External callers (routes,
+ * services, scripts) import from here so internal directory shuffles do not
+ * cascade across the codebase.
+ *
+ * Issue: otomatty/zedi#948
+ */
+export {
+  ZediChatModel,
+  type ZediChatModelParams,
+  type CallProviderFn,
+  type StreamProviderFn,
+} from "./core/llm/zediChatModel.js";
+export {
+  createZediChatModel,
+  assertSupportedComposeBackend,
+  assertSupportedBackendP0,
+  MissingUserCredentialError,
+  BackendProviderMismatchError,
+  UnsupportedBackendError,
+  type CreateZediChatModelInput,
+} from "./core/llm/modelFactory.js";
+export {
+  recordZediUsage,
+  toZediMessages,
+  type RecordZediUsageInput,
+  type RecordZediUsageResult,
+} from "./core/llm/usageCallback.js";
+export {
+  getPostgresCheckpointer,
+  ensurePostgresCheckpointerSetup,
+  resolveCheckpointerForRun,
+} from "./core/checkpoint/index.js";
+export { BaseState, type BaseStateType, type BaseStateUpdate } from "./core/state/baseState.js";
+export {
+  SHARED_TOOLS,
+  webSearchTool,
+  wikiSearchTool,
+  fetchArticleTool,
+  imageSearchTool,
+} from "./core/tools/index.js";
+export * from "./core/types/index.js";
+export {
+  registerGraph,
+  getRegisteredGraph,
+  listRegisteredGraphs,
+  GraphNotRegisteredError,
+  type GraphFactory,
+  type GraphFactoryInput,
+  type RegisteredGraph,
+} from "./registry/graphRegistry.js";
+export { STUB_GRAPH_ID, registerStubGraph } from "./registry/stubGraph.js";
+export {
+  GraphRunner,
+  type RunInput,
+  type RunPayload,
+  type RunResult,
+} from "./runner/graphRunner.js";
+export {
+  mapLangGraphEvent,
+  startedEvent,
+  statusEvent,
+  usageEvent,
+  doneEvent,
+  errorEvent,
+  type LangGraphRuntimeEvent,
+} from "./runner/sseMapper.js";
+export {
+  RESEARCH_GRAPH_ID,
+  RESEARCH_GRAPH_VERSION,
+  registerResearchLoopGraph,
+  shouldRefine,
+  ResearchLoopState,
+  type ResearchLoopStateType,
+  type ResearchLoopStateUpdate,
+  type Source as ResearchSource,
+  type PlannedQuery,
+  type Evaluation,
+  type ResearchBatch,
+  type ExitReason,
+  type ResearchResumeInput,
+  researchResumeSchema,
+  type ResearchResumeParsed,
+  type HumanReviewInterruptPayload,
+} from "./subgraphs/research/index.js";
+export {
+  INGEST_PLANNER_GRAPH_ID,
+  INGEST_PLANNER_GRAPH_VERSION,
+  registerIngestPlannerGraph,
+  IngestPlannerState,
+  type IngestPlannerStateType,
+  type IngestPlannerStateUpdate,
+} from "./graphs/ingest/index.js";
+export {
+  WIKI_MAINTENANCE_GRAPH_ID,
+  WIKI_MAINTENANCE_GRAPH_VERSION,
+  registerWikiMaintenanceGraph,
+  WikiMaintenanceState,
+  type WikiMaintenanceStateType,
+  type WikiMaintenanceStateUpdate,
+  type MaintenanceFinding,
+  type MaintenancePlan,
+} from "./graphs/wikiMaintenance/index.js";
+export {
+  routeAfterBrief,
+  routeAfterResearch,
+  shouldResolveResearchConflicts,
+  type BriefRoute,
+  type ResearchRoute,
+} from "./graphs/wikiCompose/routing.js";
+export {
+  WIKI_COMPOSE_GRAPH_ID,
+  WIKI_COMPOSE_GRAPH_VERSION,
+  registerWikiComposeGraph,
+  WikiComposeState,
+  type WikiComposeStateType,
+  type WikiComposeStateUpdate,
+  briefResumeSchema,
+  type BriefResumeParsed,
+  outlineResumeSchema,
+  type OutlineResumeParsed,
+  type BriefAnswer,
+  type BriefOption,
+  type BriefQuestion,
+  type BriefResult,
+  type BriefResumeInput,
+  type ApprovedOutline,
+  type ComposeCompletion,
+  type DraftedSection,
+  type OutlineResumeInput,
+  type OutlineSection,
+  type PageSnapshot,
+  type WikiComposeInterruptPayload,
+} from "./graphs/wikiCompose/index.js";
diff --git a/server/api/src/agents/registry/graphRegistry.ts b/server/api/src/agents/registry/graphRegistry.ts
new file mode 100644
index 00000000..eb76b4ff
--- /dev/null
+++ b/server/api/src/agents/registry/graphRegistry.ts
@@ -0,0 +1,118 @@
+/**
+ * Graph registry — maps a logical `graphId` to a factory that produces a
+ * compiled LangGraph.
+ *
+ * Wiki Compose は複数のグラフ (P1 調査, P2 outline, P3 draft, ...) を
+ * `graphId` で切り替える。本ファイルは「論理 ID → コンパイル済みグラフを
+ * 返すファクトリ」のマップを 1 つに集約し、route 層・GraphRunner からは
+ * registry を介してのみグラフを引く。
+ *
+ * Each compose session is parameterised by a `graphId` so the platform can
+ * evolve P1..P4 subgraphs independently. The registry is the only place where
+ * `graphId → graph` mapping lives — routes and the runner depend on it, never
+ * on concrete graph modules.
+ */
+import type { BaseCheckpointSaver } from "@langchain/langgraph";
+
+/**
+ * LangGraph `compile()` の戻り値はジェネリック型パラメータが多すぎて registry
+ * 側で完全に再現できない。registry は run / streamEvents / invoke の呼び出し
+ * できる最小契約だけ要求する構造的な型を使う。
+ *
+ * `CompiledGraph` from LangGraph is heavily generic; pinning all type
+ * parameters in the registry would force every subgraph to re-export them.
+ * The registry only relies on the runtime methods used by `GraphRunner`, so
+ * a structural type covers our needs without leaking generic parameters.
+ */
+export interface CompiledGraphLike {
+  invoke(input: unknown, options?: unknown): Promise<unknown>;
+  stream(input: unknown, options?: unknown): Promise<unknown>;
+  streamEvents(input: unknown, options: unknown): unknown;
+}
+
+/**
+ * グラフファクトリ。1 セッションごとに呼ばれ、必要なら checkpointer を bake する。
+ * Graph factory: called once per session; may consume the runtime checkpointer.
+ *
+ * @param ctx.checkpointer  実行時に GraphRunner が注入する LangGraph saver。
+ *                          The checkpointer injected by the runner at execution time.
+ * @returns CompiledGraph   `compile()` 済みのグラフインスタンス。
+ *                          Compiled graph instance returned by `StateGraph.compile()`.
+ */
+export interface GraphFactoryInput {
+  checkpointer: BaseCheckpointSaver | boolean;
+}
+export interface GraphFactory {
+  (input: GraphFactoryInput): CompiledGraphLike;
+}
+
+/**
+ * グラフ定義のメタ情報。registry が外部に公開する unit。
+ * Registered graph descriptor.
+ *
+ * @property id           論理 ID。Route layer / DB の `graphId` カラム。
+ * @property version      バージョン文字列。デプロイ間で挙動が変わった時に bump。
+ * @property phase        グラフが属するフェーズ識別子（"research", "draft" 等）。
+ * @property description  Human-readable 説明。Admin UI 等で利用。
+ * @property factory      コンパイル済みグラフを返すファクトリ。
+ */
+export interface RegisteredGraph {
+  id: string;
+  version: string;
+  phase: string;
+  description: string;
+  factory: GraphFactory;
+}
+
+const registry = new Map<string, RegisteredGraph>();
+
+/**
+ * Register a graph. Calling twice with the same id replaces the previous entry
+ * (intended for hot-reload during dev / test).
+ *
+ * グラフを登録する。同じ id を 2 度登録すると上書きされる（dev / test 向け）。
+ */
+export function registerGraph(graph: RegisteredGraph): void {
+  registry.set(graph.id, graph);
+}
+
+/**
+ * Look up a registered graph by id.
+ * 登録済みグラフを id で取得する。未登録なら undefined。
+ */
+export function getRegisteredGraph(id: string): RegisteredGraph | undefined {
+  return registry.get(id);
+}
+
+/**
+ * 全登録グラフを列挙する。管理画面・デバッグ用。
+ * Enumerate all registered graphs.
+ */
+export function listRegisteredGraphs(): RegisteredGraph[] {
+  return Array.from(registry.values());
+}
+
+/**
+ * テスト用：レジストリをクリアする。
+ * Test-only: clear the registry.
+ */
+export function __resetRegistryForTests(): void {
+  registry.clear();
+}
+
+/**
+ * `graphId` 未登録時の例外。route 層で 400 に変換する。
+ *
+ * Thrown by the runner when a session references an unknown `graphId`. The
+ * route layer should translate this into a 400, since the value comes from
+ * client input.
+ */
+export class GraphNotRegisteredError extends Error {
+  readonly code = "GRAPH_NOT_REGISTERED";
+  readonly graphId: string;
+  constructor(graphId: string) {
+    super(`No graph registered with id="${graphId}"`);
+    this.name = "GraphNotRegisteredError";
+    this.graphId = graphId;
+  }
+}
diff --git a/server/api/src/agents/registry/stubGraph.ts b/server/api/src/agents/registry/stubGraph.ts
new file mode 100644
index 00000000..33710a45
--- /dev/null
+++ b/server/api/src/agents/registry/stubGraph.ts
@@ -0,0 +1,42 @@
+/**
+ * Stub Wiki Compose graph used by the P0 plumbing.
+ *
+ * `wiki-compose-stub` グラフ。P0 (#948) 段階で `GraphRunner` がレジストリ経由で
+ * グラフを実行できることを確認するための最小グラフ。1 ノードで `phase` を
+ * "completed" にして終了する。本物の調査・outline・draft グラフは #949 以降で
+ * 別 graphId として登録する。
+ *
+ * Minimal compiled graph for P0 wiring tests. Real Wiki Compose subgraphs land
+ * in #949+ under separate ids; this stub stays as a smoke-test fixture.
+ */
+import { END, START, StateGraph } from "@langchain/langgraph";
+import { BaseState } from "../core/state/baseState.js";
+import { registerGraph, type GraphFactory } from "./graphRegistry.js";
+
+/** Registered id for the stub graph. スタブグラフの登録 ID。 */
+export const STUB_GRAPH_ID = "wiki-compose-stub" as const;
+
+const stubFactory: GraphFactory = ({ checkpointer }) => {
+  const builder = new StateGraph(BaseState)
+    .addNode("noop", async (_state) => ({ phase: "completed" }))
+    .addEdge(START, "noop")
+    .addEdge("noop", END);
+  return builder.compile({ checkpointer });
+};
+
+/**
+ * Register the stub graph. Called from app bootstrap so the runner can resolve
+ * it via `graphId="wiki-compose-stub"`.
+ *
+ * スタブグラフを登録する。app 起動時に 1 度呼ぶ。
+ */
+export function registerStubGraph(): void {
+  registerGraph({
+    id: STUB_GRAPH_ID,
+    version: "0.1.0",
+    phase: "stub",
+    description:
+      "P0 wiring smoke test graph. Marks the session 'completed' and exits. Not for production composing.",
+    factory: stubFactory,
+  });
+}
diff --git a/server/api/src/agents/runner/graphRunner.ts b/server/api/src/agents/runner/graphRunner.ts
new file mode 100644
index 00000000..54262a60
--- /dev/null
+++ b/server/api/src/agents/runner/graphRunner.ts
@@ -0,0 +1,197 @@
+/**
+ * `GraphRunner` — orchestrates LangGraph runs for compose sessions.
+ *
+ * compose-session の実行を司るランナー。route 層が `start` / `streamEvents` /
+ * `resume` を呼ぶ際の入口で、(1) registry からグラフを引く、(2) checkpointer を
+ * 注入する、(3) `GraphContext` を `configurable` に詰める、を一手に引き受ける。
+ *
+ * Single entry point that the route layer uses to start, stream, or resume a
+ * compose session. Owning the checkpointer + registry handoff in one place
+ * keeps individual route handlers thin.
+ */
+import { Command, type BaseCheckpointSaver } from "@langchain/langgraph";
+import { getRegisteredGraph, GraphNotRegisteredError } from "../registry/graphRegistry.js";
+import type { GraphContext } from "../core/types/graphContext.js";
+import { GRAPH_CONTEXT_CONFIG_KEY } from "../core/types/graphContext.js";
+
+/**
+ * `GraphRunner` 共通入力。`context.threadId` を LangGraph `thread_id` に対応させる。
+ * Common input passed to all `GraphRunner` methods.
+ *
+ * @property graphId       Registry に登録済みの論理 ID。Registered logical id.
+ * @property context       Per-execution context propagated into `configurable`.
+ * @property checkpointer  LangGraph checkpoint saver。Postgres or memory.
+ * @property recursionLimit  LangGraph 再帰深度上限（既定 25）。Recursion limit.
+ */
+export interface RunInput {
+  graphId: string;
+  context: GraphContext;
+  checkpointer: BaseCheckpointSaver | boolean;
+  recursionLimit?: number;
+}
+
+/**
+ * `start` / `resume` の payload を共通化するためのユニオン。`Command` を直接
+ * 渡すか、ノードへの input オブジェクトを渡すかを区別する。
+ *
+ * Discriminates between "kick the graph with an input object" and "resume from
+ * an interrupt via `Command`".
+ */
+export type RunPayload = { kind: "input"; value: unknown } | { kind: "command"; value: Command };
+
+/**
+ * 1 セッションの最終結果。successful run なら output、interrupt で停止したら
+ * `interruptedAt` のノード名を持つ。
+ *
+ * Terminal result of a single run.
+ */
+export interface RunResult {
+  status: "completed" | "interrupted" | "failed";
+  output?: unknown;
+  interruptedAt?: string;
+  error?: string;
+}
+
+/**
+ * `GraphRunner` の実体。stateless で、毎呼び出しごとに registry + checkpointer
+ * を解決する。
+ *
+ * Stateless runner; resolves registry + checkpointer per call so the same
+ * instance can serve many concurrent sessions.
+ */
+export class GraphRunner {
+  /**
+   * グラフを 1 回 invoke して結果を返す。ストリーミング不要なテストや、graph
+   * の起動時セルフチェック用の薄い経路。
+   *
+   * One-shot `invoke`. Useful for tests and any non-streaming caller.
+   */
+  async invoke(input: RunInput, payload: RunPayload): Promise<RunResult> {
+    const graph = this.resolveGraph(input.graphId, input.checkpointer);
+    const config = this.buildConfig(input);
+    try {
+      const result = await graph.invoke(this.unwrapPayload(payload), config);
+      // LangGraph ≥ 1.x: interrupts surface as a `__interrupt__` array on the
+      // returned state, NOT as a thrown error. Detect that shape and translate
+      // to `{ status: "interrupted" }`. Legacy throw-based GraphInterrupt is
+      // also handled below for safety (kept for forward-compat / version skew).
+      // LangGraph 1.x では interrupt は throw されず、結果 state の
+      // `__interrupt__` フィールドに乗る。ここで検出して status を訳す。
+      if (hasInterruptOnResult(result)) {
+        return { status: "interrupted", output: result };
+      }
+      return { status: "completed", output: result };
+    } catch (err) {
+      // Interrupts surface as throws in some older LangGraph paths; keep the
+      // catch for safety so a version that re-introduces the throw doesn't
+      // regress to a failed run.
+      // 古い LangGraph パスでは throw する可能性があるので catch を残す。
+      if (isInterruptError(err)) {
+        return { status: "interrupted", interruptedAt: extractInterruptNode(err) };
+      }
+      return { status: "failed", error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+
+  /**
+   * `streamEvents(version: "v2")` のラッパー。route 層から SSE に流すための
+   * AsyncIterable を返す。`mapLangGraphEvent` でフィルタリングする想定だが、本層
+   * では生イベントをそのまま流す（マッピング責務は呼び出し側）。
+   *
+   * Streams LangGraph runtime events. The caller (route layer) typically pipes
+   * the result through `mapLangGraphEvent` from `sseMapper.ts`.
+   */
+  streamEvents(input: RunInput, payload: RunPayload): AsyncIterable<unknown> {
+    const graph = this.resolveGraph(input.graphId, input.checkpointer);
+    const config = this.buildConfig(input);
+    // `streamEvents` returns an `IterableReadableStream<...>`; we return it as
+    // `AsyncIterable<unknown>` to keep the runner's surface area provider-agnostic.
+    return graph.streamEvents(this.unwrapPayload(payload), {
+      ...config,
+      version: "v2",
+    }) as unknown as AsyncIterable<unknown>;
+  }
+
+  /**
+   * `Command({ resume: ... })` を流して中断点から再開する。`patchState` は
+   * `resume.value` に対する追加情報（ユーザー入力など）を載せる用途。
+   *
+   * Resume a previously-interrupted run by submitting a `Command({ resume })`
+   * keyed by the session's `thread_id`.
+   */
+  async resume(
+    input: RunInput,
+    resumeValue: unknown,
+    options?: { stream?: false },
+  ): Promise<RunResult>;
+  async resume(
+    input: RunInput,
+    resumeValue: unknown,
+    options: { stream: true },
+  ): Promise<AsyncIterable<unknown>>;
+  async resume(
+    input: RunInput,
+    resumeValue: unknown,
+    options?: { stream?: boolean },
+  ): Promise<RunResult | AsyncIterable<unknown>> {
+    const command = new Command({ resume: resumeValue });
+    if (options?.stream) {
+      return this.streamEvents(input, { kind: "command", value: command });
+    }
+    return this.invoke(input, { kind: "command", value: command });
+  }
+
+  private resolveGraph(graphId: string, checkpointer: BaseCheckpointSaver | boolean) {
+    const registered = getRegisteredGraph(graphId);
+    if (!registered) throw new GraphNotRegisteredError(graphId);
+    return registered.factory({ checkpointer });
+  }
+
+  private buildConfig(input: RunInput) {
+    return {
+      configurable: {
+        thread_id: input.context.threadId,
+        [GRAPH_CONTEXT_CONFIG_KEY]: input.context,
+      },
+      recursionLimit: input.recursionLimit ?? 25,
+    };
+  }
+
+  private unwrapPayload(payload: RunPayload): unknown {
+    return payload.kind === "command" ? payload.value : payload.value;
+  }
+}
+
+/**
+ * LangGraph の interrupt 例外判定。`isGraphInterrupt` を直接 import すると
+ * 循環依存のリスクがあるため、本ファイルでは structural にチェックする。
+ *
+ * Structural check for LangGraph `GraphInterrupt`. We avoid importing the
+ * symbol directly to keep this module decoupled from LangGraph internals.
+ */
+function isInterruptError(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const name = (err as { name?: unknown }).name;
+  return typeof name === "string" && /Interrupt/.test(name);
+}
+
+function extractInterruptNode(err: unknown): string | undefined {
+  if (!err || typeof err !== "object") return undefined;
+  const node = (err as { node?: unknown }).node;
+  return typeof node === "string" ? node : undefined;
+}
+
+/**
+ * LangGraph ≥ 1.x leaves a `__interrupt__: Interrupt[]` array on the final
+ * state when an `interrupt(value)` call is awaiting resume. This helper
+ * surfaces that for `GraphRunner.invoke` / `.resume` so they can return
+ * `{ status: "interrupted" }` without inspecting the LangChain payload type.
+ *
+ * LangGraph 1.x の `__interrupt__` フィールドを検出する。型は意図的に緩い
+ * （構造的）にしてバージョン差を吸収する。
+ */
+function hasInterruptOnResult(result: unknown): boolean {
+  if (!result || typeof result !== "object") return false;
+  const arr = (result as { __interrupt__?: unknown }).__interrupt__;
+  return Array.isArray(arr) && arr.length > 0;
+}
diff --git a/server/api/src/agents/runner/sseMapper.ts b/server/api/src/agents/runner/sseMapper.ts
new file mode 100644
index 00000000..5c6b6eb9
--- /dev/null
+++ b/server/api/src/agents/runner/sseMapper.ts
@@ -0,0 +1,302 @@
+/**
+ * `sseMapper` — translate LangGraph runtime events into wire SSE events.
+ *
+ * LangGraph の `streamEvents` 出力を本リポジトリの `SseEvent` discriminated union
+ * に変換する純粋関数群。route 層は `mapLangGraphEvent` の結果を `streamSSE` で
+ * `event:` ＋ `data:` の 2 行として書き出す。テストしやすいよう、I/O を持たない
+ * 同期関数として実装する。
+ *
+ * Pure-function mappers from LangGraph runtime events to {@link SseEvent}. The
+ * route layer is responsible for actually writing to the SSE response; this
+ * file only describes the shape transformation so unit tests can pin it.
+ */
+import type {
+  SseComposePhaseEvent,
+  SseComposeSectionEvent,
+  SseEvent,
+  SseResearchBatchEvent,
+  SseResearchEvaluationEvent,
+  SseResearchIterationEvent,
+} from "../core/types/sseEvents.js";
+
+/**
+ * 起動時 SSE。`event: started` で投げる。
+ * Initial SSE event emitted before the graph starts.
+ */
+export function startedEvent(sessionId: string, graphId: string, phase?: string): SseEvent {
+  return phase
+    ? { type: "started", sessionId, graphId, phase }
+    : { type: "started", sessionId, graphId };
+}
+
+/**
+ * フェーズ遷移 SSE。
+ * Phase transition SSE.
+ */
+export function statusEvent(phase: string, message?: string): SseEvent {
+  return message ? { type: "status", phase, message } : { type: "status", phase };
+}
+
+/**
+ * Usage SSE。`ZediChatModel` の usage 計算後に流す。
+ * Usage SSE emitted right after `recordZediUsage`.
+ */
+export function usageEvent(input: {
+  inputTokens: number;
+  outputTokens: number;
+  costUnits: number;
+  usagePercent: number;
+}): SseEvent {
+  return { type: "usage", ...input };
+}
+
+/**
+ * 終了 SSE。`status` で完了 / 中断 / 失敗を区別する。
+ * Terminal SSE describing how the run ended.
+ */
+export function doneEvent(status: "completed" | "interrupted" | "failed"): SseEvent {
+  return { type: "done", status };
+}
+
+/**
+ * エラー SSE。`retryable` は省略可。
+ * Error SSE; `retryable` defaults to undefined.
+ */
+export function errorEvent(message: string, retryable?: boolean): SseEvent {
+  return retryable === undefined
+    ? { type: "error", message }
+    : { type: "error", message, retryable };
+}
+
+/**
+ * LangGraph `streamEvents` から取れる最小限の event 形。本マッパは LangChain の
+ * 詳細型を取り込みすぎないよう、必要なフィールドだけを `unknown` で構造的に
+ * 受け取る。
+ *
+ * Minimal structural type for a LangGraph runtime event so the mapper does not
+ * couple to the full LangChain event union. The runner casts the LangGraph
+ * event to this shape before calling {@link mapLangGraphEvent}.
+ */
+export interface LangGraphRuntimeEvent {
+  event: string;
+  name?: string;
+  data?: unknown;
+  metadata?: Record<string, unknown>;
+  tags?: string[];
+}
+
+/**
+ * LangGraph 1 イベント → SseEvent[]。1 入力が複数の SSE event に展開されうるため
+ * 配列で返す。`null` を返したくない設計（呼び出し側のフィルタ条件を 1 箇所に
+ * 集約するため空配列を許容）。
+ *
+ * Returns 0..N {@link SseEvent} for one LangGraph event. Callers iterate and
+ * write each one to the SSE stream. Empty array signals "skip this event".
+ */
+export function mapLangGraphEvent(event: LangGraphRuntimeEvent): SseEvent[] {
+  switch (event.event) {
+    case "on_chat_model_stream":
+      return mapChatModelStream(event);
+    case "on_tool_start":
+      return mapToolStart(event);
+    case "on_tool_end":
+      return mapToolEnd(event);
+    case "on_chain_end":
+      return mapChainEnd(event);
+    case "on_custom_event":
+      return mapCustomEvent(event);
+    default:
+      return [];
+  }
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function mapChatModelStream(event: LangGraphRuntimeEvent): SseEvent[] {
+  const data = asRecord(event.data);
+  if (!data) return [];
+  const chunk = asRecord(data.chunk);
+  if (!chunk) return [];
+  const content = chunk.content;
+  if (typeof content !== "string" || content.length === 0) return [];
+  const node =
+    typeof event.metadata?.langgraph_node === "string"
+      ? (event.metadata.langgraph_node as string)
+      : undefined;
+  return node ? [{ type: "token", node, content }] : [{ type: "token", content }];
+}
+
+function mapToolStart(event: LangGraphRuntimeEvent): SseEvent[] {
+  const tool = event.name;
+  if (!tool) return [];
+  const data = asRecord(event.data);
+  const input = data && asRecord(data.input);
+  return input ? [{ type: "tool_start", tool, input }] : [{ type: "tool_start", tool }];
+}
+
+function mapToolEnd(event: LangGraphRuntimeEvent): SseEvent[] {
+  const tool = event.name;
+  if (!tool) return [];
+  const data = asRecord(event.data);
+  const output = data?.output;
+  const outputLength =
+    typeof output === "string" ? output.length : output === undefined ? undefined : 0;
+  const errorRaw = data?.error;
+  const error =
+    errorRaw instanceof Error
+      ? errorRaw.message
+      : typeof errorRaw === "string"
+        ? errorRaw
+        : undefined;
+  const base = { type: "tool_end" as const, tool };
+  const withLen = outputLength === undefined ? base : { ...base, outputLength };
+  return error ? [{ ...withLen, error }] : [withLen];
+}
+
+function mapChainEnd(event: LangGraphRuntimeEvent): SseEvent[] {
+  // Only emit a status / interrupt update when the chain end belongs to the
+  // top-level graph. Nested chain ends would generate noise.
+  // トップレベル graph の終了のみ拾う。ネストした chain は無視する。
+  const data = asRecord(event.data);
+  if (!data) return [];
+  const output = asRecord(data.output);
+  if (!output) return [];
+  const events: SseEvent[] = [];
+
+  // LangGraph ≥ 1.x: interrupts surface as a `__interrupt__: Interrupt[]`
+  // array on the final state, not as a throw. Convert each entry to its own
+  // `interrupt` SSE event so the frontend sees the same wire shape it would
+  // get from the legacy throw path. Route layer reads `interrupt` events to
+  // flip the session status to "interrupted".
+  // LangGraph 1.x の `__interrupt__` 配列を SSE interrupt イベントに変換する。
+  const interrupts = (output as { __interrupt__?: unknown }).__interrupt__;
+  if (Array.isArray(interrupts) && interrupts.length > 0) {
+    for (const entry of interrupts) {
+      const value =
+        entry && typeof entry === "object" ? (entry as { value?: unknown }).value : undefined;
+      events.push({ type: "interrupt", payload: value });
+    }
+  }
+
+  const phase = typeof output.phase === "string" ? output.phase : undefined;
+  if (phase) events.push({ type: "status", phase });
+  return events;
+}
+
+/**
+ * Map `on_custom_event` (LangGraph's hook for `dispatchCustomEvent` from
+ * `@langchain/core/callbacks/dispatch`) to typed Sse events. Used by the
+ * research loop subgraph (#949) to surface `research_iteration` /
+ * `research_evaluation` / `research_batch` without inventing a new transport.
+ *
+ * `dispatchCustomEvent(name, data, config)` で吐かれる runtime event を SSE に
+ * 変換する。`event.name` でイベント種別を分岐し、`event.data` は信頼せず構造
+ * 的に検証してから dispatch する（ペイロードが壊れていれば空配列を返して
+ * フロントを壊さない）。
+ */
+function mapCustomEvent(event: LangGraphRuntimeEvent): SseEvent[] {
+  const name = event.name;
+  if (!name) return [];
+  const data = asRecord(event.data);
+  if (!data) return [];
+  switch (name) {
+    case "research_iteration":
+      return mapResearchIteration(data);
+    case "research_evaluation":
+      return mapResearchEvaluation(data);
+    case "research_batch":
+      return mapResearchBatch(data);
+    case "compose_phase":
+      return mapComposePhase(data);
+    case "compose_section":
+      return mapComposeSection(data);
+    default:
+      // Unknown custom event names are dropped silently; emitting them as `status`
+      // would risk leaking implementation detail to the wire.
+      // 未知 name は静かに捨てる。`status` 等に流すと内部詳細が漏れる。
+      return [];
+  }
+}
+
+function mapResearchIteration(data: Record<string, unknown>): SseResearchIterationEvent[] {
+  const iteration = typeof data.iteration === "number" ? data.iteration : null;
+  const status = data.status === "planned" || data.status === "refined" ? data.status : null;
+  const queryCount = typeof data.queryCount === "number" ? data.queryCount : null;
+  if (iteration === null || status === null || queryCount === null) return [];
+  return [{ type: "research_iteration", iteration, status, queryCount }];
+}
+
+function mapResearchEvaluation(data: Record<string, unknown>): SseResearchEvaluationEvent[] {
+  const iteration = typeof data.iteration === "number" ? data.iteration : null;
+  const score = typeof data.score === "number" ? data.score : null;
+  const rationale = typeof data.rationale === "string" ? data.rationale : null;
+  const missingAspectsCount =
+    typeof data.missingAspectsCount === "number" ? data.missingAspectsCount : null;
+  if (iteration === null || score === null || rationale === null || missingAspectsCount === null) {
+    return [];
+  }
+  return [{ type: "research_evaluation", iteration, score, rationale, missingAspectsCount }];
+}
+
+function mapComposePhase(data: Record<string, unknown>): SseComposePhaseEvent[] {
+  const phase = data.phase;
+  const status = data.status;
+  if (
+    phase !== "brief" &&
+    phase !== "research" &&
+    phase !== "conflict" &&
+    phase !== "structure" &&
+    phase !== "draft" &&
+    phase !== "completed"
+  ) {
+    return [];
+  }
+  if (status !== "entered" && status !== "completed") return [];
+  return [{ type: "compose_phase", phase, status }];
+}
+
+function mapComposeSection(data: Record<string, unknown>): SseComposeSectionEvent[] {
+  const sectionId = typeof data.sectionId === "string" ? data.sectionId : null;
+  const heading = typeof data.heading === "string" ? data.heading : null;
+  const status = data.status === "started" || data.status === "completed" ? data.status : null;
+  const index = typeof data.index === "number" ? data.index : null;
+  const total = typeof data.total === "number" ? data.total : null;
+  if (
+    sectionId === null ||
+    heading === null ||
+    status === null ||
+    index === null ||
+    total === null
+  ) {
+    return [];
+  }
+  return [{ type: "compose_section", sectionId, heading, status, index, total }];
+}
+
+function mapResearchBatch(data: Record<string, unknown>): SseResearchBatchEvent[] {
+  const batchId = typeof data.batchId === "string" ? data.batchId : null;
+  const iteration = typeof data.iteration === "number" ? data.iteration : null;
+  const sourceCount = typeof data.sourceCount === "number" ? data.sourceCount : null;
+  const score = data.score === null || typeof data.score === "number" ? data.score : null;
+  const exitReason =
+    data.exitReason === "score_threshold" || data.exitReason === "max_iterations"
+      ? data.exitReason
+      : null;
+  if (batchId === null || iteration === null || sourceCount === null || exitReason === null) {
+    return [];
+  }
+  return [
+    {
+      type: "research_batch",
+      batchId,
+      iteration,
+      sourceCount,
+      score,
+      exitReason,
+    },
+  ];
+}
diff --git a/server/api/src/agents/subgraphs/research/index.ts b/server/api/src/agents/subgraphs/research/index.ts
new file mode 100644
index 00000000..b624e5e8
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/index.ts
@@ -0,0 +1,28 @@
+/**
+ * Wiki Compose research-loop subgraph (#949) — public barrel.
+ *
+ * 調査ループ subgraph の外向け window。`app.ts` / `agents/index.ts` から
+ * このファイル経由で `RESEARCH_GRAPH_ID` と `registerResearchLoopGraph` を
+ * 引く。直接ノードを import したいテストは `./nodes/index.js` を見る。
+ */
+export {
+  RESEARCH_GRAPH_ID,
+  RESEARCH_GRAPH_VERSION,
+  registerResearchLoopGraph,
+  shouldRefine,
+} from "./researchGraph.js";
+export {
+  ResearchLoopState,
+  type ResearchLoopStateType,
+  type ResearchLoopStateUpdate,
+} from "./state.js";
+export type {
+  Source,
+  PlannedQuery,
+  Evaluation,
+  ResearchBatch,
+  ExitReason,
+  ResearchResumeInput,
+} from "./types.js";
+export { researchResumeSchema, type ResearchResumeParsed } from "./resumeSchema.js";
+export type { HumanReviewInterruptPayload } from "./nodes/humanReviewResearch.js";
diff --git a/server/api/src/agents/subgraphs/research/nodes/compileBatch.ts b/server/api/src/agents/subgraphs/research/nodes/compileBatch.ts
new file mode 100644
index 00000000..b9561dfc
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/nodes/compileBatch.ts
@@ -0,0 +1,59 @@
+/**
+ * `compile_batch` — pure projection node that produces a {@link ResearchBatch}
+ * from the current state and emits a `research_batch` SSE custom event.
+ *
+ * pure な projection ノード。`pendingSources` のスナップショットを 1 件の
+ * {@link ResearchBatch} に固めて `batches` に append し、`exitReason` を確定する。
+ * LLM 呼び出しは行わない。
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { randomUUID } from "node:crypto";
+import { dispatchResearchBatch } from "./shared/dispatchSseCustom.js";
+import type { ResearchLoopStateType, ResearchLoopStateUpdate } from "../state.js";
+import type { ExitReason, ResearchBatch } from "../types.js";
+
+/**
+ * `compile_batch` node — pure projection that freezes the current state into a
+ * UI-facing {@link ResearchBatch}, appends it to `state.batches`, and dispatches
+ * the `research_batch` SSE custom event.
+ *
+ * `compile_batch` ノード本体。`pendingSources` のスナップショットを 1 件の
+ * {@link ResearchBatch} に固めて `batches` に append し、`exitReason` を確定する。
+ *
+ * @param state  Current research-loop state.
+ * @param config LangGraph runnable config (carries `GraphContext` + callbacks).
+ * @returns Partial state update: `{ batches: [newBatch], exitReason, phase }`.
+ */
+export async function compileBatch(
+  state: ResearchLoopStateType,
+  config: LangGraphRunnableConfig,
+): Promise<ResearchLoopStateUpdate> {
+  const score = state.lastEvaluation?.score ?? null;
+  const exitReason: ExitReason =
+    score !== null && score >= 0.75 ? "score_threshold" : "max_iterations";
+  const batch: ResearchBatch = {
+    id: randomUUID(),
+    iteration: state.iteration,
+    queries: state.queries,
+    sources: state.pendingSources,
+    evaluation: state.lastEvaluation,
+    createdAt: new Date().toISOString(),
+  };
+
+  await dispatchResearchBatch(
+    {
+      batchId: batch.id,
+      iteration: batch.iteration,
+      sourceCount: batch.sources.length,
+      score,
+      exitReason,
+    },
+    config,
+  );
+
+  return {
+    batches: [batch],
+    exitReason,
+    phase: "research:compile",
+  };
+}
diff --git a/server/api/src/agents/subgraphs/research/nodes/evaluateSufficiency.ts b/server/api/src/agents/subgraphs/research/nodes/evaluateSufficiency.ts
new file mode 100644
index 00000000..9411f7b2
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/nodes/evaluateSufficiency.ts
@@ -0,0 +1,116 @@
+/**
+ * `evaluate_sufficiency` — scores the current `pendingSources` against the
+ * brief, post-increments `iteration`, and emits a `research_evaluation` SSE
+ * custom event.
+ *
+ * 現在の `pendingSources` が brief を満たしているかを LLM で評価し、
+ * `score` (0..1) と `missingAspects` を返す。post-increment した `iteration`
+ * を返すことで、後段の `shouldRefine` がループ終了条件
+ * (`score >= 0.75 || iteration >= maxIterations`) を正しく判定できる。
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { z } from "zod";
+import { createZediChatModel } from "../../../core/llm/modelFactory.js";
+import { resolveComposeModelId } from "../../../core/llm/resolveComposeModelId.js";
+import { getGraphContext } from "./shared/getGraphContext.js";
+import { dispatchResearchEvaluation } from "./shared/dispatchSseCustom.js";
+import type { ResearchLoopStateType, ResearchLoopStateUpdate } from "../state.js";
+import type { Evaluation } from "../types.js";
+
+export const evaluationSchema = z.object({
+  score: z.number().min(0).max(1),
+  rationale: z.string().min(1).max(500),
+  missingAspects: z.array(z.string().min(1)).max(5),
+});
+
+const SYSTEM_PROMPT =
+  "You are evaluating whether the research sources collected so far are sufficient " +
+  "to write the requested wiki article. Score 0..1 (≥0.75 means 'good enough'), " +
+  "give a short rationale, and list up to 5 missing aspects. Output JSON only.";
+
+function buildUserPrompt(state: ResearchLoopStateType): string {
+  const brief = state.messages
+    .map((m) => {
+      const raw = (m as { content?: unknown }).content;
+      return typeof raw === "string" ? raw : "";
+    })
+    .filter((s) => s.length > 0)
+    .join("\n\n");
+  const sourceLines = state.pendingSources.map((s, i) => {
+    const tag = s.kind === "fetched" ? "FETCHED" : s.kind === "wiki" ? "WIKI" : "WEB";
+    const body = s.excerpt ?? s.snippet ?? "(no preview)";
+    return `[${i + 1}] ${tag} ${s.title}\n${body}`;
+  });
+  return [
+    "[Brief]",
+    brief || "(empty brief — assume general coverage)",
+    "",
+    `[Sources collected: ${state.pendingSources.length}]`,
+    ...sourceLines,
+    "",
+    `Iteration so far: ${state.iteration} / ${state.maxIterations}`,
+  ].join("\n");
+}
+
+/**
+ * `evaluate_sufficiency` node — scores the gathered sources against the brief,
+ * post-increments `iteration`, and dispatches the `research_evaluation` SSE
+ * custom event. The conditional edge {@link shouldRefine} reads
+ * `lastEvaluation.score` + `iteration` to decide refine vs compile.
+ *
+ * 充足度評価ノード本体。LLM で `{ score, rationale, missingAspects }` を
+ * 構造化出力で得て、`iteration` を 1 進めて返す。
+ *
+ * @param state  Current research-loop state.
+ * @param config LangGraph runnable config (carries `GraphContext` + callbacks).
+ * @returns Partial state update: `{ lastEvaluation, iteration, phase }`.
+ */
+export async function evaluateSufficiency(
+  state: ResearchLoopStateType,
+  config: LangGraphRunnableConfig,
+): Promise<ResearchLoopStateUpdate> {
+  const ctx = getGraphContext(config);
+
+  const modelId = await resolveComposeModelId("orchestrator", ctx.backend, ctx.tier, ctx.db);
+  const model = await createZediChatModel({
+    modelId,
+    userId: ctx.userId,
+    tier: ctx.tier,
+    db: ctx.db,
+    feature: `${ctx.feature}:evaluate`,
+    backend: ctx.backend,
+    temperature: 0.1,
+    // 1024 leaves enough room for a verbose `rationale` + `missingAspects`
+    // array without truncating mid-JSON (gemini review #956).
+    maxTokens: 1024,
+  });
+  const structured = model.withStructuredOutput(evaluationSchema, {
+    name: "research_evaluation",
+  });
+  const parsed = await structured.invoke([
+    { role: "system", content: SYSTEM_PROMPT },
+    { role: "user", content: buildUserPrompt(state) },
+  ]);
+  const evaluation: Evaluation = {
+    score: parsed.score,
+    rationale: parsed.rationale,
+    missingAspects: parsed.missingAspects,
+  };
+  const nextIteration = state.iteration + 1;
+
+  await dispatchResearchEvaluation(
+    {
+      iteration: nextIteration,
+      score: evaluation.score,
+      rationale: evaluation.rationale,
+      missingAspectsCount: evaluation.missingAspects.length,
+    },
+    config,
+  );
+
+  return {
+    lastEvaluation: evaluation,
+    iteration: nextIteration,
+    phase: "research:evaluated",
+  };
+}
diff --git a/server/api/src/agents/subgraphs/research/nodes/fetchArticles.ts b/server/api/src/agents/subgraphs/research/nodes/fetchArticles.ts
new file mode 100644
index 00000000..d936a694
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/nodes/fetchArticles.ts
@@ -0,0 +1,109 @@
+/**
+ * `fetch_articles` node — Readability-extracts the top web URLs from
+ * `pendingSources` into excerpts and upgrades each source's `kind` from
+ * `web` to `fetched` IN PLACE via the id-keyed reducer.
+ *
+ * Web 検索結果のうち URL を持つ上位 N 件 (既定 5) を `fetchArticleTool` で取得。
+ * SSRF / fetch 失敗時は `{ ok:false }` を返すだけで throw しないため、1 件の
+ * 失敗で iteration が止まらない。
+ *
+ * In-place upgrade contract (codex review #956 / gemini #4):
+ * - web rows mint id = `src:<sha256(originalUrl)>` (in `webSearch.ts`).
+ * - fetched rows reuse that SAME id (carry the source row's `id` over) so the
+ *   reducer overwrites the web row with the fetched row in place. The
+ *   redirect-resolved URL goes to `finalUrl`; `url` stays equal to the
+ *   original so id derivation remains stable across iterations.
+ * - Failed fetches leave the web row untouched; a future iteration may retry.
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { fetchArticleTool } from "../../../core/tools/fetchArticle.js";
+import type { ResearchLoopStateType, ResearchLoopStateUpdate } from "../state.js";
+import type { Source } from "../types.js";
+
+interface FetchArticleSuccess {
+  ok: true;
+  url: string;
+  finalUrl: string;
+  title: string;
+  excerpt: string;
+  contentHash: string;
+  thumbnailUrl: string | null;
+}
+
+interface FetchArticleFailure {
+  ok: false;
+  url: string;
+  error: string;
+}
+
+const PER_ITERATION_FETCH_LIMIT = 5;
+
+/**
+ * `fetch_articles` node — Readability-extracts up to {@link PER_ITERATION_FETCH_LIMIT}
+ * pending `web` rows in parallel and emits `kind:"fetched"` upgrades. The
+ * reducer ({@link mergeSourcesById}) overwrites each upgraded row in place
+ * because fetched sources carry the same `src:<sha>` id as the originating
+ * web row (codex review #956 P2 / gemini #4).
+ *
+ * fetch_articles ノード本体。pending な `web` 行を最大 N 件並列で取得し、
+ * `kind:"fetched"` に in-place 昇格させる。
+ *
+ * @param state  Current research-loop state.
+ * @param config LangGraph runnable config (carries `GraphContext` + callbacks).
+ * @returns Partial state update: `{ pendingSources: upgradedRows[] }`.
+ */
+export async function fetchArticles(
+  state: ResearchLoopStateType,
+  config: LangGraphRunnableConfig,
+): Promise<ResearchLoopStateUpdate> {
+  // Only fetch `web` rows. `fetched` rows share the same id (`src:<sha>`) so
+  // any web hit already promoted in a prior iteration has been overwritten by
+  // the reducer and is no longer present as `kind:"web"`.
+  // web 行のみ対象。同 URL の fetched 行は同じ id を持つため、過去 iteration で
+  // 昇格済みのものは reducer が上書きしており、ここでは現れない。
+  const candidates = state.pendingSources
+    .filter((s) => s.kind === "web" && typeof s.url === "string" && s.url.length > 0)
+    .slice(0, PER_ITERATION_FETCH_LIMIT);
+
+  if (candidates.length === 0) return { pendingSources: [] };
+
+  const settled = await Promise.allSettled(
+    candidates.map((s) =>
+      fetchArticleTool.invoke({ url: s.url as string, previewLength: 4000 }, config),
+    ),
+  );
+
+  const upgraded: Source[] = [];
+  const fetchedAt = new Date().toISOString();
+  for (let i = 0; i < settled.length; i++) {
+    const r = settled[i];
+    if (!r || r.status !== "fulfilled") continue;
+    const candidate = candidates[i];
+    if (!candidate) continue;
+    const raw = r.value;
+    if (typeof raw !== "string") continue;
+    let envelope: FetchArticleSuccess | FetchArticleFailure;
+    try {
+      envelope = JSON.parse(raw) as FetchArticleSuccess | FetchArticleFailure;
+    } catch {
+      continue;
+    }
+    if (!envelope.ok) continue;
+    // Carry the candidate's id over so the reducer upgrades the row in place.
+    // `url` stays equal to the original; the redirect-resolved URL is stored
+    // separately on `finalUrl` (codex review #956 P2).
+    // candidate.id を引き継いで reducer に in-place 昇格させる。url は元のまま、
+    // リダイレクト後は finalUrl に。
+    upgraded.push({
+      id: candidate.id,
+      kind: "fetched",
+      title: envelope.title,
+      url: candidate.url,
+      finalUrl: envelope.finalUrl,
+      excerpt: envelope.excerpt,
+      contentHash: envelope.contentHash,
+      fetchedAt,
+    });
+  }
+  return { pendingSources: upgraded };
+}
diff --git a/server/api/src/agents/subgraphs/research/nodes/humanReviewResearch.ts b/server/api/src/agents/subgraphs/research/nodes/humanReviewResearch.ts
new file mode 100644
index 00000000..61205bc4
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/nodes/humanReviewResearch.ts
@@ -0,0 +1,79 @@
+/**
+ * `human_review_research` — HITL stop point. Calls `interrupt(...)` to halt
+ * the graph and surfaces the latest batch + pending sources to the client.
+ * On resume, validates the `{ approvedSourceIds, rejectedSourceIds, note }`
+ * payload and projects `approvedResearch` / `rejectedResearch` into state.
+ *
+ * HITL 中断ノード。`interrupt()` でグラフを停止し、UI には最新バッチと
+ * pendingSources を渡す。resume 時、`PATCH .../resume` 経由で送られてくる
+ * `{ approvedSourceIds, rejectedSourceIds?, note? }` を `researchResumeSchema`
+ * で検証し、`approvedResearch` / `rejectedResearch` を state に確定する。
+ * バリデーション失敗は throw され、`graphRunner` が `{ status:"failed" }` を
+ * 返して route 層が 4xx を返す。
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { interrupt } from "@langchain/langgraph";
+import { researchResumeSchema } from "../resumeSchema.js";
+import type { ResearchLoopStateType, ResearchLoopStateUpdate } from "../state.js";
+import type { ResearchBatch, Source } from "../types.js";
+
+/**
+ * Payload value passed to `interrupt()`. Surfaces as `SseInterruptEvent.payload`
+ * on the wire so the frontend can render the approval UI without an extra fetch.
+ *
+ * Frontend renders this directly; do not include fields that would be unsafe
+ * to expose (e.g. raw DB ids without an authorisation re-check).
+ */
+export interface HumanReviewInterruptPayload {
+  kind: "human_review_research";
+  batch: ResearchBatch | null;
+  pendingSources: Source[];
+}
+
+/**
+ * `human_review_research` node — HITL interrupt point. Halts the graph via
+ * LangGraph `interrupt(payload)` to surface the latest batch + pending sources
+ * to the client; on resume, validates the `{ approvedSourceIds,
+ * rejectedSourceIds?, note? }` payload with {@link researchResumeSchema} and
+ * projects approved/rejected sources into the state.
+ *
+ * HITL 中断ノード本体。`interrupt()` でグラフを停止し、resume 時に
+ * resume payload を検証して `approvedResearch` / `rejectedResearch` を確定する。
+ *
+ * @param state   Current research-loop state.
+ * @param _config LangGraph runnable config (unused but required by the node
+ *                signature).
+ * @returns Partial state update on resume: `{ approvedResearch, rejectedResearch,
+ *          phase: "completed" }`.
+ * @throws  zod `ZodError` if the resume payload is malformed; surfaces as a
+ *          failed run via `GraphRunner`.
+ */
+export async function humanReviewResearch(
+  state: ResearchLoopStateType,
+  _config: LangGraphRunnableConfig,
+): Promise<ResearchLoopStateUpdate> {
+  const latestBatch = state.batches[state.batches.length - 1] ?? null;
+  const payload: HumanReviewInterruptPayload = {
+    kind: "human_review_research",
+    batch: latestBatch,
+    pendingSources: state.pendingSources,
+  };
+
+  // `interrupt(value)` halts execution; the return value is whatever the
+  // resume command (`Command({ resume })`) supplies, which the route layer
+  // builds from `PATCH /resume`'s body.resume field.
+  // interrupt はグラフを停止し、resume 時に再開して値を返す。
+  const resumeValue: unknown = interrupt(payload);
+  const parsed = researchResumeSchema.parse(resumeValue);
+
+  const approvedIds = new Set(parsed.approvedSourceIds);
+  const rejectedIds = new Set(parsed.rejectedSourceIds ?? []);
+  const approvedResearch = state.pendingSources.filter((s) => approvedIds.has(s.id));
+  const rejectedResearch = state.pendingSources.filter((s) => rejectedIds.has(s.id));
+
+  return {
+    approvedResearch,
+    rejectedResearch,
+    phase: "completed",
+  };
+}
diff --git a/server/api/src/agents/subgraphs/research/nodes/index.ts b/server/api/src/agents/subgraphs/research/nodes/index.ts
new file mode 100644
index 00000000..bb85dc15
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/nodes/index.ts
@@ -0,0 +1,16 @@
+/**
+ * Barrel for research-loop subgraph nodes.
+ *
+ * `researchGraph.ts` から個別ファイルを import せずに済むようにまとめる。
+ * テストでも `vi.mock("...nodes/index.js", { planQueries: vi.fn() ... })`
+ * のように単一の mock point として使う。
+ */
+export { planQueries } from "./planQueries.js";
+export { webSearch } from "./webSearch.js";
+export { wikiSearch } from "./wikiSearch.js";
+export { fetchArticles } from "./fetchArticles.js";
+export { evaluateSufficiency } from "./evaluateSufficiency.js";
+export { refineQueries } from "./refineQueries.js";
+export { compileBatch } from "./compileBatch.js";
+export { humanReviewResearch } from "./humanReviewResearch.js";
+export { shouldRefine } from "../shouldRefine.js";
diff --git a/server/api/src/agents/subgraphs/research/nodes/planQueries.ts b/server/api/src/agents/subgraphs/research/nodes/planQueries.ts
new file mode 100644
index 00000000..a760722d
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/nodes/planQueries.ts
@@ -0,0 +1,156 @@
+/**
+ * `plan_queries` — generates the initial query set for the research loop.
+ *
+ * 調査ループの最初のノード。Brief / 指示メッセージから 1〜8 件の調査クエリを
+ * 生成し、`maxIterations` を 1..5 にクランプする。"additional_research" 入力で
+ * 既存セッションの追加調査として呼ばれた場合、`iteration / lastEvaluation /
+ * exitReason` をリセットし、`carryOverApprovedIds` で `pendingSources` を初期化
+ * する（issue #949 の追加調査 API パス）。
+ *
+ * Initial node. Emits a structured query list via `ZediChatModel
+ * .withStructuredOutput`. Honours an "additional_research" input shape so the
+ * same graph id can serve re-runs without a separate route.
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { createZediChatModel } from "../../../core/llm/modelFactory.js";
+import { resolveComposeModelId } from "../../../core/llm/resolveComposeModelId.js";
+import { getGraphContext } from "./shared/getGraphContext.js";
+import { dispatchResearchIteration } from "./shared/dispatchSseCustom.js";
+import type { ResearchLoopStateType, ResearchLoopStateUpdate } from "../state.js";
+import type { PlannedQuery, Source } from "../types.js";
+
+/**
+ * @deprecated Use {@link resolveComposeModelId} with graph context. Kept for tests importing the symbol.
+ */
+export function getOrchestratorModelId(): string {
+  return process.env.WIKI_COMPOSE_ORCHESTRATOR_MODEL_ID?.trim() || "claude-3-5-haiku";
+}
+
+/** Schema for the LLM's structured output. */
+export const planQueriesSchema = z.object({
+  queries: z
+    .array(
+      z.object({
+        query: z.string().min(1),
+        rationale: z.string().optional(),
+        channels: z.array(z.enum(["web", "wiki"])).min(1),
+      }),
+    )
+    .min(1)
+    .max(8),
+});
+
+const SYSTEM_PROMPT =
+  "You are an orchestrator planning research queries for a wiki article. " +
+  "Given the user's brief, propose 1-6 search queries that cover distinct angles. " +
+  "Each query MUST specify at least one channel from ['web','wiki']. " +
+  "Prefer 'wiki' for queries likely answered by the user's own knowledge base " +
+  "and 'web' for queries needing fresh public information. Output JSON only.";
+
+import type { AdditionalResearchRequest } from "../types.js";
+
+function clampMaxIterations(raw: unknown): number {
+  if (typeof raw !== "number" || !Number.isFinite(raw)) return 3;
+  const truncated = Math.trunc(raw);
+  return Math.min(Math.max(truncated, 1), 5);
+}
+
+function briefFromState(
+  state: ResearchLoopStateType,
+  additional: AdditionalResearchRequest | null,
+): string {
+  if (additional) {
+    const parts = ["[Additional research request]", additional.instruction];
+    if (additional.brief) parts.push("", "[Original brief]", additional.brief);
+    return parts.join("\n");
+  }
+  // Fall back to concatenating all text content of `messages`. Empty string is
+  // valid — the LLM will still produce default coverage queries.
+  return state.messages
+    .map((m) => {
+      const raw = (m as { content?: unknown }).content;
+      return typeof raw === "string" ? raw : "";
+    })
+    .filter((s) => s.length > 0)
+    .join("\n\n");
+}
+
+/**
+ * `plan_queries` node implementation. Exported for direct unit testing.
+ *
+ * 単体テストから直接呼べるよう export する。
+ */
+export async function planQueries(
+  state: ResearchLoopStateType,
+  config: LangGraphRunnableConfig,
+): Promise<ResearchLoopStateUpdate> {
+  const ctx = getGraphContext(config);
+  // Detect additional-research input from the dedicated state field. The route
+  // layer translates `body.input.kind === "additional_research"` into this
+  // shape so LangGraph's strict state schema does not drop unknown top-level
+  // input keys (codex review #956 P1).
+  // 追加調査の検出は state.additionalRequest 専用フィールドで行う。
+  const additional = state.additionalRequest ?? null;
+  const brief = briefFromState(state, additional);
+
+  // Resolve maxIterations: input override > existing state > default(3); clamp 1..5.
+  // maxIterations は既存 state を優先しつつ 1..5 にクランプ。
+  const maxIterations = clampMaxIterations(state.maxIterations ?? 3);
+
+  const modelId = await resolveComposeModelId("orchestrator", ctx.backend, ctx.tier, ctx.db);
+  const model = await createZediChatModel({
+    modelId,
+    userId: ctx.userId,
+    tier: ctx.tier,
+    db: ctx.db,
+    feature: `${ctx.feature}:plan`,
+    backend: ctx.backend,
+    temperature: 0.4,
+    maxTokens: 1024,
+  });
+  const structured = model.withStructuredOutput(planQueriesSchema, { name: "plan_queries" });
+  const planned = await structured.invoke([
+    { role: "system", content: SYSTEM_PROMPT },
+    { role: "user", content: brief || "(no brief provided; produce 2 broad coverage queries)" },
+  ]);
+
+  const queries: PlannedQuery[] = planned.queries.map((q) => ({
+    id: randomUUID(),
+    query: q.query,
+    rationale: q.rationale,
+    channels: q.channels,
+  }));
+
+  const carriedSources: Source[] = additional?.carryOverApprovedIds
+    ? additional.carryOverApprovedIds.map((id) => ({
+        id,
+        kind: id.startsWith("wiki:") ? "wiki" : "fetched",
+        title: "(carried over)",
+      }))
+    : [];
+
+  await dispatchResearchIteration(
+    { iteration: 0, status: "planned", queryCount: queries.length },
+    config,
+  );
+
+  const update: ResearchLoopStateUpdate = {
+    queries,
+    maxIterations,
+    iteration: 0,
+    lastEvaluation: null,
+    exitReason: null,
+    phase: "research:plan",
+    // Consume the additional-research seed so a subsequent re-plan inside the
+    // same session (defensive) does not loop on the same instruction.
+    // 追加調査リクエストは 1 度読んだら null にクリアする。
+    additionalRequest: null,
+  };
+  if (additional) {
+    // Additional-research re-run: reset accumulators except for explicit carryover.
+    update.pendingSources = carriedSources;
+  }
+  return update;
+}
diff --git a/server/api/src/agents/subgraphs/research/nodes/refineQueries.ts b/server/api/src/agents/subgraphs/research/nodes/refineQueries.ts
new file mode 100644
index 00000000..c2c9b755
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/nodes/refineQueries.ts
@@ -0,0 +1,93 @@
+/**
+ * `refine_queries` — replaces `queries` with a refined batch based on the
+ * latest evaluation's `missingAspects`. Loops back to `web_search`.
+ *
+ * 直近 evaluation の `missingAspects` を基に次ループのクエリを生成し、
+ * `queries` を全置換する。`iteration` は `evaluate_sufficiency` で既に
+ * post-increment 済みなので、ここでは触らない。
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { randomUUID } from "node:crypto";
+import { createZediChatModel } from "../../../core/llm/modelFactory.js";
+import { resolveComposeModelId } from "../../../core/llm/resolveComposeModelId.js";
+import { getGraphContext } from "./shared/getGraphContext.js";
+import { dispatchResearchIteration } from "./shared/dispatchSseCustom.js";
+import { planQueriesSchema } from "./planQueries.js";
+import type { ResearchLoopStateType, ResearchLoopStateUpdate } from "../state.js";
+import type { PlannedQuery } from "../types.js";
+
+const SYSTEM_PROMPT =
+  "You are refining a research query plan. Given the previous queries, the " +
+  "sources gathered, and the missing aspects flagged by evaluation, propose " +
+  "1-6 NEW queries that fill those gaps. Avoid repeating prior queries. " +
+  "Each query MUST specify at least one channel from ['web','wiki']. " +
+  "Output JSON only.";
+
+function buildUserPrompt(state: ResearchLoopStateType): string {
+  const evaluation = state.lastEvaluation;
+  const missing = evaluation?.missingAspects ?? [];
+  const prior = state.queries.map((q) => `- ${q.query} (${q.channels.join("/")})`);
+  const sourceTitles = state.pendingSources.map((s) => `- [${s.kind}] ${s.title}`);
+  return [
+    `[Iteration ${state.iteration} / ${state.maxIterations}]`,
+    `Previous evaluation score: ${evaluation?.score ?? "n/a"}`,
+    "",
+    "[Missing aspects to address]",
+    ...(missing.length ? missing.map((m) => `- ${m}`) : ["(none flagged; broaden coverage)"]),
+    "",
+    "[Prior queries (avoid duplicates)]",
+    ...prior,
+    "",
+    `[Sources gathered so far: ${state.pendingSources.length}]`,
+    ...sourceTitles,
+  ].join("\n");
+}
+
+/**
+ * `refine_queries` node — replaces `state.queries` with a fresh batch that
+ * addresses `lastEvaluation.missingAspects`, then dispatches
+ * `research_iteration { status: "refined" }`. Loops back to the search
+ * fan-out via the graph edge.
+ *
+ * リファインノード本体。直近の評価結果を元に次イテレーションのクエリを生成する。
+ *
+ * @param state  Current research-loop state.
+ * @param config LangGraph runnable config (carries `GraphContext` + callbacks).
+ * @returns Partial state update: `{ queries: newQueries, phase }`.
+ */
+export async function refineQueries(
+  state: ResearchLoopStateType,
+  config: LangGraphRunnableConfig,
+): Promise<ResearchLoopStateUpdate> {
+  const ctx = getGraphContext(config);
+
+  const modelId = await resolveComposeModelId("orchestrator", ctx.backend, ctx.tier, ctx.db);
+  const model = await createZediChatModel({
+    modelId,
+    userId: ctx.userId,
+    tier: ctx.tier,
+    db: ctx.db,
+    feature: `${ctx.feature}:refine`,
+    backend: ctx.backend,
+    temperature: 0.5,
+    maxTokens: 1024,
+  });
+  const structured = model.withStructuredOutput(planQueriesSchema, { name: "refine_queries" });
+  const planned = await structured.invoke([
+    { role: "system", content: SYSTEM_PROMPT },
+    { role: "user", content: buildUserPrompt(state) },
+  ]);
+  const queries: PlannedQuery[] = planned.queries.map((q) => ({
+    id: randomUUID(),
+    query: q.query,
+    rationale: q.rationale,
+    channels: q.channels,
+  }));
+
+  await dispatchResearchIteration(
+    { iteration: state.iteration, status: "refined", queryCount: queries.length },
+    config,
+  );
+
+  return { queries, phase: "research:refine" };
+}
diff --git a/server/api/src/agents/subgraphs/research/nodes/shared/dispatchSseCustom.ts b/server/api/src/agents/subgraphs/research/nodes/shared/dispatchSseCustom.ts
new file mode 100644
index 00000000..02da4b9a
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/nodes/shared/dispatchSseCustom.ts
@@ -0,0 +1,58 @@
+/**
+ * Typed wrapper over `dispatchCustomEvent` for the research loop subgraph.
+ *
+ * `dispatchCustomEvent(name, data, config)` を typesafe に呼ぶための薄いラッパ。
+ * `sseMapper` の `mapCustomEvent` がペイロード shape を検証するので、ノード
+ * 側は本ヘルパ経由で型付きで dispatch するだけで良い。
+ */
+import { dispatchCustomEvent } from "@langchain/core/callbacks/dispatch";
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+
+/** Payload shape for `research_iteration` custom events. */
+export interface ResearchIterationPayload {
+  iteration: number;
+  status: "planned" | "refined";
+  queryCount: number;
+}
+
+/** Payload shape for `research_evaluation` custom events. */
+export interface ResearchEvaluationPayload {
+  iteration: number;
+  score: number;
+  rationale: string;
+  missingAspectsCount: number;
+}
+
+/** Payload shape for `research_batch` custom events. */
+export interface ResearchBatchPayload {
+  batchId: string;
+  iteration: number;
+  sourceCount: number;
+  score: number | null;
+  exitReason: "score_threshold" | "max_iterations";
+}
+
+/**
+ * Per-event helpers. We use 3 narrow functions instead of a generic union so
+ * accidentally swapping payload shapes raises a TS error at the call site.
+ */
+export async function dispatchResearchIteration(
+  payload: ResearchIterationPayload,
+  config: LangGraphRunnableConfig,
+): Promise<void> {
+  await dispatchCustomEvent("research_iteration", payload, config);
+}
+
+export async function dispatchResearchEvaluation(
+  payload: ResearchEvaluationPayload,
+  config: LangGraphRunnableConfig,
+): Promise<void> {
+  await dispatchCustomEvent("research_evaluation", payload, config);
+}
+
+export async function dispatchResearchBatch(
+  payload: ResearchBatchPayload,
+  config: LangGraphRunnableConfig,
+): Promise<void> {
+  await dispatchCustomEvent("research_batch", payload, config);
+}
diff --git a/server/api/src/agents/subgraphs/research/nodes/shared/getGraphContext.ts b/server/api/src/agents/subgraphs/research/nodes/shared/getGraphContext.ts
new file mode 100644
index 00000000..4f820f31
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/nodes/shared/getGraphContext.ts
@@ -0,0 +1,48 @@
+/**
+ * Tiny helper that pulls the {@link GraphContext} out of LangGraph's
+ * `RunnableConfig.configurable` bag.
+ *
+ * 各ノードが `config.configurable[GRAPH_CONTEXT_CONFIG_KEY]` を引く時の
+ * boilerplate を 1 箇所に寄せるためのユーティリティ。`GraphRunner` が必ず
+ * セットするので production 経路では undefined にならないが、ユニットテスト
+ * で誤って忘れたケースを早期に検出するため throw する。
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import {
+  GRAPH_CONTEXT_CONFIG_KEY,
+  type GraphContext,
+} from "../../../../core/types/graphContext.js";
+
+/**
+ * Returns the `GraphContext` injected by `GraphRunner.buildConfig`. Throws
+ * when missing or malformed so misconfigured callers fail loudly with a
+ * pointed error rather than running with default / undefined credentials and
+ * exploding deep inside `createZediChatModel` / `recordUsage`.
+ *
+ * `GraphRunner.buildConfig` が唯一の正規生成者だが、テスト誤用や手動構築の
+ * 防御として、必須フィールドの存在 (`userId`, `db`, `feature`) を浅く検証する。
+ * Zod 等の重い依存は導入しない — 単一のプロデューサで保証している契約への
+ * 二次防衛なので、shape check で十分（coderabbit review #956）。
+ */
+export function getGraphContext(config: LangGraphRunnableConfig | undefined): GraphContext {
+  const configurable = config?.configurable as Record<string, unknown> | undefined;
+  const candidate = configurable?.[GRAPH_CONTEXT_CONFIG_KEY];
+  if (!candidate || typeof candidate !== "object") {
+    throw new Error(
+      `Missing GraphContext on config.configurable["${GRAPH_CONTEXT_CONFIG_KEY}"]; ` +
+        "GraphRunner is responsible for populating it.",
+    );
+  }
+  const ctx = candidate as Partial<GraphContext>;
+  const missing: string[] = [];
+  if (typeof ctx.userId !== "string" || ctx.userId.length === 0) missing.push("userId");
+  if (!ctx.db) missing.push("db");
+  if (typeof ctx.feature !== "string" || ctx.feature.length === 0) missing.push("feature");
+  if (missing.length > 0) {
+    throw new Error(
+      `GraphContext is missing required fields: ${missing.join(", ")}. ` +
+        "Check GraphRunner.buildConfig.",
+    );
+  }
+  return ctx as GraphContext;
+}
diff --git a/server/api/src/agents/subgraphs/research/nodes/webSearch.ts b/server/api/src/agents/subgraphs/research/nodes/webSearch.ts
new file mode 100644
index 00000000..076cecf0
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/nodes/webSearch.ts
@@ -0,0 +1,72 @@
+/**
+ * `web_search` node — runs the `webSearchTool` for each query whose channels
+ * include "web". Sources from the tool merge into `pendingSources` via the
+ * reducer's id-keyed dedup.
+ *
+ * web チャンネル指定のクエリごとに `webSearchTool` を並列実行し、結果を
+ * `pendingSources` にマージする。tool 側で `{ ok:false }` が返っても throw せず
+ * skip するので、1 クエリの失敗が iteration を止めない。
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { webSearchTool } from "../../../core/tools/webSearch.js";
+import type { ResearchLoopStateType, ResearchLoopStateUpdate } from "../state.js";
+import type { Source } from "../types.js";
+
+interface WebSearchToolEnvelope {
+  ok: boolean;
+  results?: Array<{
+    id: string;
+    kind: "web";
+    title: string;
+    url: string;
+    snippet?: string;
+  }>;
+}
+
+/**
+ * `web_search` node — fans out the `webSearchTool` over every query whose
+ * `channels` include "web". Tool failures are swallowed (skipped) so one bad
+ * query never aborts the iteration.
+ *
+ * web 検索ノード本体。web チャンネル指定のクエリごとに `webSearchTool` を
+ * 並列実行し、結果を `pendingSources` にマージする。
+ *
+ * @param state  Current research-loop state.
+ * @param config LangGraph runnable config (tool invocation requires it so
+ *               `GraphContext` can flow to the tool).
+ * @returns Partial state update: `{ pendingSources: collectedRows[] }`.
+ */
+export async function webSearch(
+  state: ResearchLoopStateType,
+  config: LangGraphRunnableConfig,
+): Promise<ResearchLoopStateUpdate> {
+  const targets = state.queries.filter((q) => q.channels.includes("web"));
+  if (targets.length === 0) return { pendingSources: [] };
+
+  const settled = await Promise.allSettled(
+    targets.map((q) => webSearchTool.invoke({ query: q.query, limit: 5 }, config)),
+  );
+  const collected: Source[] = [];
+  for (const r of settled) {
+    if (r.status !== "fulfilled") continue;
+    const raw = r.value;
+    if (typeof raw !== "string") continue;
+    let envelope: WebSearchToolEnvelope;
+    try {
+      envelope = JSON.parse(raw) as WebSearchToolEnvelope;
+    } catch {
+      continue;
+    }
+    if (!envelope.ok || !envelope.results) continue;
+    for (const hit of envelope.results) {
+      collected.push({
+        id: hit.id,
+        kind: "web",
+        title: hit.title,
+        url: hit.url,
+        snippet: hit.snippet,
+      });
+    }
+  }
+  return { pendingSources: collected };
+}
diff --git a/server/api/src/agents/subgraphs/research/nodes/wikiSearch.ts b/server/api/src/agents/subgraphs/research/nodes/wikiSearch.ts
new file mode 100644
index 00000000..8a38aa79
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/nodes/wikiSearch.ts
@@ -0,0 +1,74 @@
+/**
+ * `wiki_search` node — runs the `wikiSearchTool` for each query whose channels
+ * include "wiki", returning internal page hits with stable `wiki:<pageId>` ids.
+ *
+ * wiki チャンネル指定のクエリごとに `wikiSearchTool` を並列実行する。
+ * `GraphContext.userId` から所有・受諾済みメンバー・ドメインルールで絞り込む
+ * のは tool 内部で済んでいる（`wikiSearchService.searchUserWikiPages`）。
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { wikiSearchTool } from "../../../core/tools/wikiSearch.js";
+import type { ResearchLoopStateType, ResearchLoopStateUpdate } from "../state.js";
+import type { Source } from "../types.js";
+
+interface WikiSearchToolEnvelope {
+  ok: boolean;
+  results?: Array<{
+    id: string;
+    kind: "wiki";
+    title: string;
+    pageId: string;
+    noteId: string;
+    snippet?: string;
+  }>;
+}
+
+/**
+ * `wiki_search` node — fans out the `wikiSearchTool` over every query whose
+ * `channels` include "wiki". Authorisation (own / accepted-member / domain
+ * rule) is enforced inside the tool via `searchUserWikiPages`, scoped by
+ * `GraphContext.userId` + `userEmail`.
+ *
+ * wiki 検索ノード本体。wiki チャンネル指定のクエリごとに `wikiSearchTool` を
+ * 並列実行し、内部ページのヒットを `pendingSources` にマージする。
+ *
+ * @param state  Current research-loop state.
+ * @param config LangGraph runnable config (tool invocation requires it so
+ *               `GraphContext` can flow to the tool).
+ * @returns Partial state update: `{ pendingSources: collectedRows[] }`.
+ */
+export async function wikiSearch(
+  state: ResearchLoopStateType,
+  config: LangGraphRunnableConfig,
+): Promise<ResearchLoopStateUpdate> {
+  const targets = state.queries.filter((q) => q.channels.includes("wiki"));
+  if (targets.length === 0) return { pendingSources: [] };
+
+  const settled = await Promise.allSettled(
+    targets.map((q) => wikiSearchTool.invoke({ query: q.query, limit: 5 }, config)),
+  );
+  const collected: Source[] = [];
+  for (const r of settled) {
+    if (r.status !== "fulfilled") continue;
+    const raw = r.value;
+    if (typeof raw !== "string") continue;
+    let envelope: WikiSearchToolEnvelope;
+    try {
+      envelope = JSON.parse(raw) as WikiSearchToolEnvelope;
+    } catch {
+      continue;
+    }
+    if (!envelope.ok || !envelope.results) continue;
+    for (const hit of envelope.results) {
+      collected.push({
+        id: hit.id,
+        kind: "wiki",
+        title: hit.title,
+        pageId: hit.pageId,
+        noteId: hit.noteId,
+        snippet: hit.snippet,
+      });
+    }
+  }
+  return { pendingSources: collected };
+}
diff --git a/server/api/src/agents/subgraphs/research/researchGraph.ts b/server/api/src/agents/subgraphs/research/researchGraph.ts
new file mode 100644
index 00000000..bfb91d73
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/researchGraph.ts
@@ -0,0 +1,86 @@
+/**
+ * Wiki Compose P1 — `researchLoopSubgraph` (issue #949).
+ *
+ * 自律調査ループ subgraph。`plan_queries` → `(web_search ∥ wiki_search)` →
+ * `fetch_articles` → `evaluate_sufficiency` を 1 イテレーションとし、
+ * `shouldRefine` の判定で `refine_queries` (= 次ループ) か `compile_batch` →
+ * `human_review_research` (= HITL 中断) のいずれかに分岐する。終了条件:
+ * `score >= 0.75` OR `iteration >= maxIterations` (default 3, clamp 1..5)。
+ *
+ * Cyclic LangGraph with a parallel fan-out (`web_search ∥ wiki_search`) and a
+ * conditional edge after `evaluate_sufficiency`. The HITL stop is implemented
+ * via `interrupt(value)` inside `human_review_research` so the resume payload
+ * (`{ approvedSourceIds, rejectedSourceIds, note }`) flows back into the same
+ * node which projects it into `approvedResearch` / `rejectedResearch`.
+ */
+import { END, START, StateGraph } from "@langchain/langgraph";
+import { ResearchLoopState } from "./state.js";
+import { registerGraph, type GraphFactory } from "../../registry/graphRegistry.js";
+import {
+  planQueries,
+  webSearch,
+  wikiSearch,
+  fetchArticles,
+  evaluateSufficiency,
+  refineQueries,
+  compileBatch,
+  humanReviewResearch,
+} from "./nodes/index.js";
+
+import { shouldRefine } from "./shouldRefine.js";
+
+export { shouldRefine };
+
+/** Registered graph id. */
+export const RESEARCH_GRAPH_ID = "wiki-compose-research" as const;
+/** Registered graph version. Bump when behaviour changes meaningfully. */
+export const RESEARCH_GRAPH_VERSION = "1.0.0";
+
+const factory: GraphFactory = ({ checkpointer }) => {
+  const builder = new StateGraph(ResearchLoopState)
+    .addNode("plan_queries", planQueries)
+    .addNode("web_search", webSearch)
+    .addNode("wiki_search", wikiSearch)
+    .addNode("fetch_articles", fetchArticles)
+    .addNode("evaluate_sufficiency", evaluateSufficiency)
+    .addNode("refine_queries", refineQueries)
+    .addNode("compile_batch", compileBatch)
+    .addNode("human_review_research", humanReviewResearch)
+    .addEdge(START, "plan_queries")
+    .addEdge("plan_queries", "web_search")
+    .addEdge("plan_queries", "wiki_search")
+    .addEdge("web_search", "fetch_articles")
+    .addEdge("wiki_search", "fetch_articles")
+    .addEdge("fetch_articles", "evaluate_sufficiency")
+    .addConditionalEdges("evaluate_sufficiency", shouldRefine, {
+      refine: "refine_queries",
+      compile: "compile_batch",
+    })
+    .addEdge("refine_queries", "web_search")
+    .addEdge("refine_queries", "wiki_search")
+    .addEdge("compile_batch", "human_review_research")
+    .addEdge("human_review_research", END);
+
+  return checkpointer ? builder.compile({ checkpointer }) : builder.compile();
+};
+
+/**
+ * Register the research loop graph. Called once at app bootstrap alongside
+ * other graph factories. Idempotent across calls.
+ *
+ * `app.ts` から `registerStubGraph()` と並べて呼ぶ。再登録は registry が
+ * 上書きで吸収する。
+ */
+export function registerResearchLoopGraph(): void {
+  registerGraph({
+    id: RESEARCH_GRAPH_ID,
+    version: RESEARCH_GRAPH_VERSION,
+    phase: "research",
+    description:
+      "Wiki Compose P1: autonomous research loop. Plans queries, runs web + wiki search, " +
+      "fetches articles, evaluates sufficiency, optionally refines and re-loops up to " +
+      "maxIterations (1..5, default 3), then interrupts at human_review_research for " +
+      "HITL source approval. Resume payload: { approvedSourceIds, rejectedSourceIds?, note? }.",
+    factory,
+  });
+}
diff --git a/server/api/src/agents/subgraphs/research/resumeSchema.ts b/server/api/src/agents/subgraphs/research/resumeSchema.ts
new file mode 100644
index 00000000..adffb7f7
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/resumeSchema.ts
@@ -0,0 +1,45 @@
+/**
+ * Resume payload validator for `human_review_research`.
+ *
+ * `PATCH /api/pages/:pageId/compose-sessions/:id/resume` 経由で送られてくる
+ * `body.resume` のうち、`graphId === "wiki-compose-research"` 向けの shape を
+ * zod で検証する。失敗時は throw され、`graphRunner` が `{ status: "failed" }`
+ * を返して route 層が 4xx を返す。
+ *
+ * Validates the resume payload that the route layer hands to the interrupted
+ * graph. Throws on invalid input so the runner short-circuits to "failed",
+ * preventing partial projections of an ill-formed payload into state.
+ */
+import { z } from "zod";
+
+/**
+ * Resume payload zod schema.
+ *
+ * - `approvedSourceIds` — 必須。空配列も許容（=全 reject）。
+ * - `rejectedSourceIds` — 任意。重複は除去して扱う。
+ * - `note` — 任意の自由記述。HITL 側のメモ用。
+ *
+ * Schema for the human-in-the-loop approval payload. `approvedSourceIds` is
+ * required (empty array means "reject all"); `rejectedSourceIds` defaults to
+ * the empty array; `note` is free-form metadata.
+ */
+export const researchResumeSchema = z
+  .object({
+    approvedSourceIds: z.array(z.string().min(1)),
+    rejectedSourceIds: z.array(z.string().min(1)).optional().default([]),
+    note: z.string().optional(),
+  })
+  .superRefine((value, ctx) => {
+    const rejected = new Set(value.rejectedSourceIds);
+    const overlap = value.approvedSourceIds.filter((id) => rejected.has(id));
+    if (overlap.length > 0) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["rejectedSourceIds"],
+        message: `approvedSourceIds and rejectedSourceIds must not overlap: ${overlap.join(", ")}`,
+      });
+    }
+  });
+
+/** Inferred TS type for the parsed resume payload. */
+export type ResearchResumeParsed = z.infer<typeof researchResumeSchema>;
diff --git a/server/api/src/agents/subgraphs/research/shouldRefine.ts b/server/api/src/agents/subgraphs/research/shouldRefine.ts
new file mode 100644
index 00000000..1368b1ee
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/shouldRefine.ts
@@ -0,0 +1,18 @@
+/**
+ * Research loop exit predicate (`evaluate_sufficiency` → refine | compile).
+ */
+import type { ResearchLoopStateType } from "./state.js";
+
+/**
+ * 終了条件判定。`evaluate_sufficiency` の直後に呼ばれる。
+ *
+ * - `score >= 0.75` → `"compile"`
+ * - `iteration >= maxIterations` → `"compile"`
+ * - otherwise → `"refine"`
+ */
+export function shouldRefine(state: ResearchLoopStateType): "refine" | "compile" {
+  const score = state.lastEvaluation?.score;
+  if (typeof score === "number" && score >= 0.75) return "compile";
+  if (state.iteration >= state.maxIterations) return "compile";
+  return "refine";
+}
diff --git a/server/api/src/agents/subgraphs/research/state.ts b/server/api/src/agents/subgraphs/research/state.ts
new file mode 100644
index 00000000..425459bf
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/state.ts
@@ -0,0 +1,122 @@
+/**
+ * `ResearchLoopState` — LangGraph state for the Wiki Compose research loop (#949).
+ *
+ * 調査ループ subgraph の state。`BaseState` を継承し、ループ制御 (`iteration`,
+ * `maxIterations`, `exitReason`)、調査結果 (`pendingSources`, `batches`)、評価
+ * (`lastEvaluation`)、HITL 結果 (`approvedResearch`, `rejectedResearch`) を持つ。
+ *
+ * Extends `BaseState` with loop control, accumulated sources, evaluation, and
+ * post-interrupt human review output. Reducers favour idempotency:
+ * - `pendingSources` merges by stable `Source.id` so refining the same URL
+ *   upgrades it in place from `kind:"web"` to `kind:"fetched"` instead of
+ *   doubling.
+ * - `batches` appends so the frontend can show a full history.
+ * - All scalar fields use `next ?? prev` so partial updates don't blank state.
+ */
+import { Annotation } from "@langchain/langgraph";
+import { BaseState } from "../../core/state/baseState.js";
+import type {
+  AdditionalResearchRequest,
+  Evaluation,
+  ExitReason,
+  PlannedQuery,
+  ResearchBatch,
+  Source,
+} from "./types.js";
+
+/**
+ * `pendingSources` 用 reducer。id 単位で dedup し、後勝ちで上書きする。
+ * fetch_articles が `web` → `fetched` への昇格をした際にも、同じ id で送ると
+ * 1 行にまとまる。
+ *
+ * Merge sources by `id` with last-write-wins semantics so the loop can upgrade
+ * a `kind:"web"` row to `kind:"fetched"` without duplication. Order is
+ * preserved by first appearance.
+ */
+function mergeSourcesById(prev: Source[], next: Source[] | undefined): Source[] {
+  if (!next || next.length === 0) return prev;
+  const order: string[] = [];
+  const map = new Map<string, Source>();
+  for (const s of prev) {
+    if (!map.has(s.id)) order.push(s.id);
+    map.set(s.id, s);
+  }
+  for (const s of next) {
+    if (!map.has(s.id)) order.push(s.id);
+    map.set(s.id, s);
+  }
+  return order.map((id) => map.get(id) as Source);
+}
+
+/**
+ * Research loop state schema. Subgraph nodes update slices of this.
+ *
+ * 調査ループ state スキーマ。各ノードがこの slice を返して更新する。
+ */
+export const ResearchLoopState = Annotation.Root({
+  ...BaseState.spec,
+
+  /** 現在のループ回数（0 基点。`evaluate_sufficiency` で +1）。 */
+  iteration: Annotation<number>({
+    reducer: (_prev, next) => next,
+    default: () => 0,
+  }),
+  /** ループ回数上限（1..5、デフォルト 3）。`plan_queries` で clamp 確定。 */
+  maxIterations: Annotation<number>({
+    reducer: (prev, next) => next ?? prev,
+    default: () => 3,
+  }),
+  /** 直近のクエリリスト。`plan_queries` / `refine_queries` が全置換する。 */
+  queries: Annotation<PlannedQuery[]>({
+    reducer: (_prev, next) => next,
+    default: () => [],
+  }),
+  /** 蓄積ソース。`mergeSourcesById` で dedup マージ。 */
+  pendingSources: Annotation<Source[]>({
+    reducer: mergeSourcesById,
+    default: () => [],
+  }),
+  /** 直近の評価。 */
+  lastEvaluation: Annotation<Evaluation | null>({
+    reducer: (_prev, next) => next,
+    default: () => null,
+  }),
+  /** 終了理由。 */
+  exitReason: Annotation<ExitReason | null>({
+    reducer: (_prev, next) => next,
+    default: () => null,
+  }),
+  /** 各ループの compile_batch スナップショット。append。 */
+  batches: Annotation<ResearchBatch[]>({
+    reducer: (prev, next) => (next === undefined ? prev : [...prev, ...next]),
+    default: () => [],
+  }),
+  /** 採用ソース。`human_review_research` が resume 値から projection する。 */
+  approvedResearch: Annotation<Source[]>({
+    reducer: (_prev, next) => next,
+    default: () => [],
+  }),
+  /** 除外ソース。 */
+  rejectedResearch: Annotation<Source[]>({
+    reducer: (_prev, next) => next,
+    default: () => [],
+  }),
+  /**
+   * 追加調査リクエスト。`POST /run` の `body.input.kind === "additional_research"`
+   * を route 層が詰め直す（LangGraph は未定義の top-level input キーを落とすため
+   * 仲介フィールドが必要）。`plan_queries` が消費後 `null` にクリアする。
+   *
+   * Additional-research seed populated by the route from `body.input`; cleared
+   * to null by `plan_queries` after one read.
+   */
+  additionalRequest: Annotation<AdditionalResearchRequest | null>({
+    reducer: (prev, next) => (next === undefined ? prev : next),
+    default: () => null,
+  }),
+});
+
+/** `ResearchLoopState.State` のショートカット。 */
+export type ResearchLoopStateType = typeof ResearchLoopState.State;
+
+/** `ResearchLoopState.Update` のショートカット。ノードの戻り値型。 */
+export type ResearchLoopStateUpdate = typeof ResearchLoopState.Update;
diff --git a/server/api/src/agents/subgraphs/research/types.ts b/server/api/src/agents/subgraphs/research/types.ts
new file mode 100644
index 00000000..036df588
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/types.ts
@@ -0,0 +1,162 @@
+/**
+ * Shared value types for the Wiki Compose research loop subgraph (#949).
+ *
+ * 調査ループ subgraph の値型。`ResearchLoopState`（{@link ./state.ts}）の
+ * 各フィールドが参照する。
+ *
+ * Pure data types referenced by `ResearchLoopState`. Kept separate from the
+ * `Annotation.Root` definition so node modules can import the types without
+ * pulling LangGraph's runtime symbols into their compilation graph.
+ */
+
+/**
+ * 1 ソースを表す軽量レコード。Web 検索結果 / Wiki 検索結果 / Readability で
+ * 取得した記事本文プレビュー、いずれも同じ shape にまとめる。
+ *
+ * `id` は安定する単一値で、reducer が dedup するキーになる:
+ * - `src:<sha256(url)>` — web / fetched で **共通** に使う。同じ URL を後段で
+ *   Readability に通すと、reducer (`mergeSourcesById`) が新値で上書きして
+ *   `kind: "web"` → `kind: "fetched"` にインプレース昇格する。リダイレクト後の
+ *   `finalUrl` は別フィールド (`finalUrl`) に格納し、id は常に **元 URL** の
+ *   sha256 で安定させる（codex review #956: URL 正規化の問題対策）。
+ * - `wiki:<pageId>` — Wiki ページ。pageId 自体が安定 ID なので hash は不要。
+ *
+ * A single research source. Web and fetched share the SAME `id` scheme
+ * (`src:<sha256(originalUrl)>`) so the reducer dedups them across iterations
+ * — fetched literally overwrites the matching web row by id. `finalUrl` is
+ * stored separately so redirect / canonicalisation does not break dedup
+ * (codex review #956).
+ */
+export interface Source {
+  /** Stable id (`src:<sha256(url)>` for web/fetched, `wiki:<pageId>` for wiki). */
+  id: string;
+  /** Discriminator. `fetched` upgrades `web` after Readability succeeds. */
+  kind: "web" | "wiki" | "fetched";
+  /** Human-readable title. */
+  title: string;
+  /**
+   * Original URL of the search hit. Present for `web` / `fetched`.
+   * Stable across the loop — `id` is derived from this value, NOT from
+   * `finalUrl`, so redirect URLs do not break id-based dedup.
+   * 元の URL。`fetched` でも `finalUrl` ではなくこちらを id 計算に使う。
+   */
+  url?: string;
+  /**
+   * Post-redirect / Readability-resolved canonical URL.
+   * Present only for `kind === "fetched"`. Used for display / citation; not
+   * used for dedup so a redirect chain does not split a single article into
+   * two state rows.
+   * リダイレクト後の URL（表示・引用用、dedup には使わない）。
+   */
+  finalUrl?: string;
+  /** Snippet from the search result (pre-fetch). */
+  snippet?: string;
+  /** Readability excerpt (post-fetch). Populated for `kind === "fetched"`. */
+  excerpt?: string;
+  /** Internal wiki page id. Populated for `kind === "wiki"`. */
+  pageId?: string;
+  /** Internal wiki note id. Populated for `kind === "wiki"`. */
+  noteId?: string;
+  /** Content hash (sha256 of body). Populated for `kind === "fetched"`. */
+  contentHash?: string;
+  /** ISO timestamp. Populated for `kind === "fetched"`. */
+  fetchedAt?: string;
+}
+
+/**
+ * Orchestrator LLM が組み立てた 1 つの調査クエリ。
+ * `channels` は web / wiki どちらに投げるかを指定する。
+ *
+ * A single planned research query. `channels` decides which search node(s)
+ * the query is dispatched to.
+ */
+export interface PlannedQuery {
+  /** Stable uuid for traceability. */
+  id: string;
+  /** Free-form query string. */
+  query: string;
+  /** Optional model rationale; surfaced for debug only. */
+  rationale?: string;
+  /** Dispatch channels. Non-empty. */
+  channels: Array<"web" | "wiki">;
+}
+
+/**
+ * `evaluate_sufficiency` ノードの出力。`score >= 0.75` で `compile_batch` 側へ
+ * 分岐する（{@link ./researchGraph.ts} の `shouldRefine`）。
+ *
+ * Output of `evaluate_sufficiency`. The conditional edge uses
+ * `score >= 0.75` as the exit predicate.
+ */
+export interface Evaluation {
+  /** 0..1. ≥ 0.75 → exit; otherwise refine. */
+  score: number;
+  /** Short natural-language rationale for the score. */
+  rationale: string;
+  /** Up to 5 short labels for what's still missing. */
+  missingAspects: string[];
+}
+
+/**
+ * `compile_batch` が組み立てる UI 提示用のバッチ。1 ループぶんのスナップショット。
+ *
+ * UI-facing batch produced by `compile_batch`. One per loop iteration; the
+ * frontend reads the latest one when the graph interrupts at
+ * `human_review_research`.
+ */
+export interface ResearchBatch {
+  /** Stable uuid. */
+  id: string;
+  /** Iteration index that produced this batch (0-based). */
+  iteration: number;
+  /** Queries that were dispatched in this iteration. */
+  queries: PlannedQuery[];
+  /** Snapshot of `pendingSources` at compile time. */
+  sources: Source[];
+  /** Last evaluation. `null` only if compile is forced before any evaluate. */
+  evaluation: Evaluation | null;
+  /** ISO timestamp at compile time. */
+  createdAt: string;
+}
+
+/**
+ * ループ終了理由。`compile_batch` で確定し、HITL に渡される。
+ *
+ * Reason the loop exited; set by `compile_batch`.
+ */
+export type ExitReason =
+  | "score_threshold"
+  | "max_iterations"
+  | "manual_stop"
+  /** Orchestrator skipped the research loop after Brief (#953). */
+  | "brief_skip";
+
+/**
+ * `human_review_research` ノードが期待する resume payload の TS 型。
+ * 実体は `resumeSchema.ts` の zod で検証する。
+ *
+ * TS shape of the resume payload accepted by `human_review_research`. The
+ * runtime validator lives in `resumeSchema.ts`.
+ */
+export interface ResearchResumeInput {
+  approvedSourceIds: string[];
+  rejectedSourceIds?: string[];
+  note?: string;
+}
+
+/**
+ * 追加調査リクエスト。`POST /run` の `body.input.kind === "additional_research"`
+ * を route 層が `state.additionalRequest` に詰め替えて graph に渡す。
+ * `plan_queries` が消費した後 `null` にクリアする。
+ *
+ * Additional-research seed. The route translates the documented
+ * `body.input.kind === "additional_research"` payload into this field so
+ * `plan_queries` can detect it from state (LangGraph drops unknown top-level
+ * input keys, so a free-form `kind` field would not survive the boundary).
+ * Cleared to `null` after `plan_queries` consumes it.
+ */
+export interface AdditionalResearchRequest {
+  instruction: string;
+  carryOverApprovedIds?: string[];
+  brief?: string;
+}
diff --git a/server/api/src/app.ts b/server/api/src/app.ts
index 0fff3411..9e15bc16 100644
--- a/server/api/src/app.ts
+++ b/server/api/src/app.ts
@@ -43,12 +43,34 @@ import lintRoutes from "./routes/lint.js";
 import activityRoutes from "./routes/activity.js";
 import onboardingRoutes from "./routes/onboarding.js";
 import internalRoutes from "./routes/internal.js";
+import composeSessionRoutes from "./routes/composeSessions.js";
+import userAiCredentialRoutes from "./routes/userAiCredentials.js";
+import { registerStubGraph } from "./agents/registry/stubGraph.js";
+import { registerResearchLoopGraph } from "./agents/subgraphs/research/index.js";
+import { registerWikiComposeGraph } from "./agents/graphs/wikiCompose/index.js";
+import { registerIngestPlannerGraph } from "./agents/graphs/ingest/index.js";
+import { registerWikiMaintenanceGraph } from "./agents/graphs/wikiMaintenance/index.js";
 
 /**
  * Creates and configures the Hono API app (routes, CORS, etc.).
  * Hono APIアプリを作成・設定する（ルート・CORS等）。
  */
 export function createApp(): Hono<AppEnv> {
+  // Wiki Compose graphs を registry に登録する。いずれも idempotent。
+  // - `wiki-compose-stub` — P0 smoke test (#948)
+  // - `wiki-compose-research` — P1 自律調査ループ (#949)
+  // - `wiki-compose` — P2 全体オーケストレータ (#950)
+  // - `ingest-planner` — P4 ingest + shared research loop (#952)
+  // - `wiki-maintenance` — P5 broken links + stub scan (#953)
+  //
+  // Register all Wiki Compose graphs. Calls are idempotent across hot
+  // reloads (registry uses `Map#set` so the latest registration wins).
+  registerStubGraph();
+  registerResearchLoopGraph();
+  registerWikiComposeGraph();
+  registerIngestPlannerGraph();
+  registerWikiMaintenanceGraph();
+
   const app = new Hono<AppEnv>();
   const wildcard = isWildcardCors();
   const allowedOrigins = getAllowedOrigins();
@@ -122,6 +144,9 @@ export function createApp(): Hono<AppEnv> {
   // Users
   app.route("/api/users", userRoutes);
 
+  // BYOK credentials for Wiki Compose (#951)
+  app.route("/api/user/ai-credentials", userAiCredentialRoutes);
+
   // Onboarding wizard completion + status
   // セットアップウィザード完了・状況取得
   app.route("/api/onboarding", onboardingRoutes);
@@ -136,6 +161,10 @@ export function createApp(): Hono<AppEnv> {
   // Page Snapshots (version history)
   app.route("/api/pages", pageSnapshotRoutes);
 
+  // Wiki Compose sessions (LangGraph runs) — issue #948.
+  // `/api/pages/:pageId/compose-sessions[/:id[/run|/resume]]`
+  app.route("/api/pages", composeSessionRoutes);
+
   // Sync
   app.route("/api/sync/pages", syncPageRoutes);
 
diff --git a/server/api/src/routes/composeSessionPersistence.ts b/server/api/src/routes/composeSessionPersistence.ts
new file mode 100644
index 00000000..91d68049
--- /dev/null
+++ b/server/api/src/routes/composeSessionPersistence.ts
@@ -0,0 +1,36 @@
+/**
+ * Wiki Compose session terminal-status persistence helpers.
+ *
+ * Run / resume handlers must not overwrite a user-initiated `cancelled` row when
+ * the graph finishes after DELETE.
+ */
+import { and, eq } from "drizzle-orm";
+import { wikiComposeSessions } from "../schema/wikiComposeSessions.js";
+import type { WikiComposeSessionStatus } from "../schema/wikiComposeSessions.js";
+import type { AppEnv } from "../types/index.js";
+
+/**
+ * 実行中 (`running`) のセッションだけを終端ステータスへ更新する。
+ *
+ * @returns 行が更新されたら true / `true` when a row was updated.
+ */
+export async function persistOutcomeIfStillRunning(
+  db: AppEnv["Variables"]["db"],
+  sessionId: string,
+  outcome: {
+    status: WikiComposeSessionStatus;
+    lastError: string | null;
+  },
+): Promise<boolean> {
+  const [row] = await db
+    .update(wikiComposeSessions)
+    .set({
+      status: outcome.status,
+      lastError: outcome.status === "failed" ? outcome.lastError : null,
+      closedAt: outcome.status === "interrupted" ? null : new Date(),
+      updatedAt: new Date(),
+    })
+    .where(and(eq(wikiComposeSessions.id, sessionId), eq(wikiComposeSessions.status, "running")))
+    .returning({ id: wikiComposeSessions.id });
+  return row !== undefined;
+}
diff --git a/server/api/src/routes/composeSessionProjection.ts b/server/api/src/routes/composeSessionProjection.ts
new file mode 100644
index 00000000..ec4b9544
--- /dev/null
+++ b/server/api/src/routes/composeSessionProjection.ts
@@ -0,0 +1,193 @@
+/**
+ * Project LangGraph checkpoint state into Compose UI slices (#950).
+ *
+ * `GET /compose-sessions/:id` が interrupted / completed 行を再開するとき、
+ * チェックポイントから Brief 質問・アウトライン等を復元する。
+ *
+ * Maps persisted graph state (including `__interrupt__`) into a JSON shape the
+ * frontend hook can merge without replaying `POST /run`.
+ */
+import { GRAPH_CONTEXT_CONFIG_KEY } from "../agents/core/types/graphContext.js";
+import type { GraphContext } from "../agents/core/types/graphContext.js";
+import { resolveCheckpointerForRun } from "../agents/core/checkpoint/index.js";
+import { getRegisteredGraph } from "../agents/registry/graphRegistry.js";
+import type { WikiComposeSessionStatus } from "../schema/wikiComposeSessions.js";
+
+/**
+ * `GET /compose-sessions/:id` が返す UI projection。
+ * Wire projection returned by `GET /compose-sessions/:id`.
+ */
+export interface ComposeSessionUiProjection {
+  phase?: string;
+  briefQuestions?: unknown[];
+  pageSnapshot?: unknown;
+  pendingSources?: unknown[];
+  latestBatch?: unknown;
+  approvedSources?: unknown[];
+  /** P5 conflict-resolution interrupt summary (#953). / P5 conflict-resolution 割り込み要約。 */
+  researchConflictSummary?: unknown;
+  outlineProposal?: unknown[];
+  draftedSections?: unknown[];
+  completedMarkdown?: string | null;
+}
+
+function phaseFromSessionRow(phase: string, status: WikiComposeSessionStatus): string {
+  if (status === "completed") return "completed";
+  if (phase.startsWith("brief")) return "brief";
+  if (phase.startsWith("research")) return "research";
+  if (phase.startsWith("conflict")) return "conflict";
+  if (phase.startsWith("structure")) return "structure";
+  if (phase.startsWith("draft")) return "draft";
+  return "brief";
+}
+
+/**
+ * Build UI projection from a LangGraph state snapshot (values + interrupts).
+ */
+export function projectComposeStateValues(
+  state: Record<string, unknown>,
+): ComposeSessionUiProjection {
+  const projection: ComposeSessionUiProjection = {};
+
+  if (Array.isArray(state.briefQuestions)) {
+    projection.briefQuestions = state.briefQuestions;
+  }
+  if (state.pageSnapshot && typeof state.pageSnapshot === "object") {
+    projection.pageSnapshot = state.pageSnapshot;
+  }
+  if (Array.isArray(state.pendingSources)) {
+    projection.pendingSources = state.pendingSources;
+  }
+  if (Array.isArray(state.batches) && state.batches.length > 0) {
+    projection.latestBatch = state.batches[state.batches.length - 1];
+  }
+  if (Array.isArray(state.approvedResearch)) {
+    projection.approvedSources = state.approvedResearch;
+  }
+  if (Array.isArray(state.outlineProposal) && state.outlineProposal.length > 0) {
+    projection.outlineProposal = state.outlineProposal;
+  } else {
+    const approved = state.approvedOutline as { sections?: unknown[] } | undefined;
+    if (approved?.sections?.length) {
+      projection.outlineProposal = approved.sections;
+    }
+  }
+
+  if (Array.isArray(state.draftedSections) && state.draftedSections.length > 0) {
+    projection.draftedSections = state.draftedSections;
+  }
+
+  const completion = state.completion;
+  if (completion && typeof completion === "object") {
+    const c = completion as { markdown?: string; sections?: unknown[] };
+    if (typeof c.markdown === "string") {
+      projection.completedMarkdown = c.markdown;
+    }
+    if (Array.isArray(c.sections)) {
+      projection.draftedSections = c.sections;
+    }
+  }
+
+  const interrupts = state.__interrupt__;
+  if (Array.isArray(interrupts) && interrupts.length > 0) {
+    const entry = interrupts[0];
+    const value =
+      entry && typeof entry === "object" ? (entry as { value?: unknown }).value : undefined;
+    if (value && typeof value === "object" && "kind" in value) {
+      const payload = value as {
+        kind: string;
+        questions?: unknown[];
+        pageSnapshot?: unknown;
+        batch?: unknown;
+        pendingSources?: unknown[];
+        outline?: unknown[];
+        approvedSources?: unknown[];
+        conflicts?: unknown;
+      };
+      switch (payload.kind) {
+        case "human_review_brief":
+          if (payload.questions) projection.briefQuestions = payload.questions;
+          if (payload.pageSnapshot) projection.pageSnapshot = payload.pageSnapshot;
+          projection.phase = "brief";
+          break;
+        case "human_review_research":
+          if (payload.batch) projection.latestBatch = payload.batch;
+          if (payload.pendingSources) projection.pendingSources = payload.pendingSources;
+          projection.phase = "research";
+          break;
+        case "human_review_outline":
+          if (payload.outline) projection.outlineProposal = payload.outline;
+          if (payload.approvedSources) projection.approvedSources = payload.approvedSources;
+          projection.phase = "structure";
+          break;
+        case "conflict_resolution":
+          if (payload.conflicts) projection.researchConflictSummary = payload.conflicts;
+          if (Array.isArray(state.approvedResearch)) {
+            projection.approvedSources = state.approvedResearch;
+          }
+          projection.phase = "conflict";
+          break;
+        default:
+          break;
+      }
+    }
+  }
+
+  // Interrupt-derived phase wins; row `phase` is only a fallback.
+  // interrupt 由来の phase を優先し、行の phase はフォールバックのみ。
+  if (typeof state.phase === "string" && projection.phase === undefined) {
+    projection.phase = state.phase.startsWith("completed")
+      ? "completed"
+      : phaseFromSessionRow(state.phase, "interrupted");
+  }
+
+  return projection;
+}
+
+/**
+ * チェックポイントから UI projection を読み込む。利用不可時は `null`。
+ * Load checkpoint projection for a compose session row, or `null` when unavailable.
+ */
+export async function loadComposeSessionProjection(input: {
+  sessionId: string;
+  pageId: string;
+  graphId: string;
+  status: WikiComposeSessionStatus;
+  phase: string;
+  context: GraphContext;
+}): Promise<ComposeSessionUiProjection | null> {
+  if (input.status !== "interrupted" && input.status !== "completed" && input.status !== "failed") {
+    return null;
+  }
+
+  const checkpointer = await resolveCheckpointerForRun();
+  if (checkpointer === false) return null;
+
+  const registered = getRegisteredGraph(input.graphId);
+  if (!registered) return null;
+
+  const graph = registered.factory({ checkpointer }) as {
+    getState?: (config: unknown) => Promise<{ values?: Record<string, unknown> } | undefined>;
+  };
+  if (typeof graph.getState !== "function") return null;
+
+  const config = {
+    configurable: {
+      thread_id: input.sessionId,
+      [GRAPH_CONTEXT_CONFIG_KEY]: input.context,
+    },
+  };
+
+  try {
+    const snap = await graph.getState(config);
+    const values = snap?.values;
+    if (!values || typeof values !== "object") return null;
+    const projection = projectComposeStateValues(values);
+    if (!projection.phase) {
+      projection.phase = phaseFromSessionRow(input.phase, input.status);
+    }
+    return projection;
+  } catch {
+    return null;
+  }
+}
diff --git a/server/api/src/routes/composeSessions.ts b/server/api/src/routes/composeSessions.ts
new file mode 100644
index 00000000..0e1aa642
--- /dev/null
+++ b/server/api/src/routes/composeSessions.ts
@@ -0,0 +1,607 @@
+/**
+ * `/api/pages/:pageId/compose-sessions` — Wiki Compose session API.
+ *
+ * Wiki Compose の P0 ルートスケルトン。`wiki_compose_sessions` テーブルの CRUD と、
+ * `GraphRunner` 経由でのグラフ実行 (run / resume) を提供する。SSE 形式は
+ * `agents/core/types/sseEvents.ts` の `SseEvent` に従う。本ファイル自体は graph
+ * 中立で、入力 / 再開ペイロードの shape は各 graph のノードが zod で検証する。
+ *
+ * - `POST   /api/pages/:pageId/compose-sessions`              — Create
+ * - `GET    /api/pages/:pageId/compose-sessions/:id`          — Read
+ * - `POST   /api/pages/:pageId/compose-sessions/:id/run`      — SSE
+ * - `PATCH  /api/pages/:pageId/compose-sessions/:id/resume`   — Resume from interrupt
+ * - `DELETE /api/pages/:pageId/compose-sessions/:id`          — Cancel
+ *
+ * # Per-graph contracts
+ *
+ * `wiki-compose-research` (#949 / P1):
+ * - `POST /run` body.input shapes:
+ *   - Initial run: `{ messages?: [...], maxIterations?: number }` (or any
+ *     object; the graph reads `state.messages` set by LangGraph from
+ *     `body.input`).
+ *   - Additional research (re-run on a *new* session of the same graph id):
+ *     `{ kind: "additional_research", instruction: string, brief?: string,
+ *        carryOverApprovedIds?: string[] }`
+ *     The `plan_queries` node detects this shape, resets the loop, and seeds
+ *     `pendingSources` from `carryOverApprovedIds`.
+ * - `PATCH /resume` body.resume shape:
+ *   `{ approvedSourceIds: string[], rejectedSourceIds?: string[], note?: string }`
+ *   (validated by `researchResumeSchema`; ill-formed payload fails the run.)
+ *
+ * Issue: otomatty/zedi#948 (P0), otomatty/zedi#949 (P1)
+ */
+import { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { streamSSE } from "hono/streaming";
+import { and, eq, inArray } from "drizzle-orm";
+import { authRequired } from "../middleware/auth.js";
+import { rateLimit } from "../middleware/rateLimit.js";
+import { assertPageEditAccess, assertPageViewAccess } from "../services/pageAccessService.js";
+import { wikiComposeSessions } from "../schema/wikiComposeSessions.js";
+import type { WikiComposeSessionStatus } from "../schema/wikiComposeSessions.js";
+import { getUserTier } from "../services/subscriptionService.js";
+import { GraphRunner } from "../agents/runner/graphRunner.js";
+import {
+  doneEvent,
+  errorEvent,
+  mapLangGraphEvent,
+  startedEvent,
+  statusEvent,
+  type LangGraphRuntimeEvent,
+} from "../agents/runner/sseMapper.js";
+import { GraphNotRegisteredError, getRegisteredGraph } from "../agents/registry/graphRegistry.js";
+import {
+  assertSupportedComposeBackend,
+  UnsupportedBackendError,
+} from "../agents/core/llm/modelFactory.js";
+import { assertComposeBackendReady } from "../agents/core/composeBackendValidation.js";
+import { SSE_EVENT_NAMES, type SseEvent } from "../agents/core/types/sseEvents.js";
+import { GRAPH_CONTEXT_CONFIG_KEY } from "../agents/core/types/graphContext.js";
+import { resolveCheckpointerForRun } from "../agents/core/checkpoint/index.js";
+import { RESEARCH_GRAPH_ID } from "../agents/subgraphs/research/index.js";
+import { WIKI_COMPOSE_GRAPH_ID } from "../agents/graphs/wikiCompose/index.js";
+import { WIKI_MAINTENANCE_GRAPH_ID } from "../agents/graphs/wikiMaintenance/index.js";
+import type { AppEnv } from "../types/index.js";
+import { persistOutcomeIfStillRunning } from "./composeSessionPersistence.js";
+import { loadComposeSessionProjection } from "./composeSessionProjection.js";
+
+/**
+ * Translate the documented `body.input.kind === "additional_research"` shape
+ * into a state-compatible payload for the research graph. LangGraph's strict
+ * state schema drops top-level input keys that have no annotation; without
+ * this translation the `kind` / `instruction` / `carryOverApprovedIds` fields
+ * would silently vanish and the loop would behave like a normal initial run.
+ * (codex review #956 P1.)
+ *
+ * For graphs other than `wiki-compose-research`, the input passes through
+ * unchanged.
+ */
+function translateGraphInput(graphId: string, raw: unknown): unknown {
+  if (graphId !== RESEARCH_GRAPH_ID) return raw;
+  if (!raw || typeof raw !== "object") return raw;
+  const r = raw as {
+    kind?: unknown;
+    instruction?: unknown;
+    carryOverApprovedIds?: unknown;
+    brief?: unknown;
+  };
+  if (r.kind !== "additional_research") return raw;
+  const instruction = typeof r.instruction === "string" ? r.instruction : "";
+  const carryOverApprovedIds = Array.isArray(r.carryOverApprovedIds)
+    ? r.carryOverApprovedIds.filter((x): x is string => typeof x === "string")
+    : undefined;
+  const brief = typeof r.brief === "string" ? r.brief : undefined;
+  return {
+    additionalRequest: { instruction, carryOverApprovedIds, brief },
+  };
+}
+
+/**
+ * Per-graph recursion limit. LangGraph's default of 25 is enough for the stub
+ * graph but tight for `wiki-compose-research`, which runs up to ~5 iterations
+ * × ~6 nodes ≈ 30 node executions. The full `wiki-compose` orchestrator (#950)
+ * adds Brief + Structure + Draft (up to ~10 sections × 1 node) on top of the
+ * inlined research loop, so it needs a larger budget still.
+ *
+ * 調査ループは最大 5 イテレーション × 約 6 ノード = ~30 node 実行になり得るため、
+ * 既定の 25 では不足する。orchestrator (`wiki-compose`) は更に Brief / Structure /
+ * Draft フェーズ + 最大 10 セクションを足すので 120 に引き上げる。
+ */
+function recursionLimitFor(graphId: string): number | undefined {
+  if (graphId === RESEARCH_GRAPH_ID) return 60;
+  if (graphId === WIKI_COMPOSE_GRAPH_ID) return 120;
+  if (graphId === WIKI_MAINTENANCE_GRAPH_ID) return 40;
+  return undefined;
+}
+
+const app = new Hono<AppEnv>();
+
+/**
+ * POST body — create session.
+ *
+ * @property graphId   Registry に登録されたグラフ ID。Registered graph id.
+ * @property backend   Execution backend (省略時は `zedi_managed`)。Defaults to zedi_managed.
+ * @property metadata  自由形式メタデータ。Free-form metadata.
+ */
+interface CreateSessionBody {
+  graphId?: string;
+  backend?: string;
+  metadata?: Record<string, unknown>;
+}
+
+interface RunSessionBody {
+  /** 初期入力（最初の messages 等）。任意。 */
+  input?: unknown;
+}
+
+interface ResumeSessionBody {
+  /**
+   * Interrupt に渡す再開値。HITL の場合は通常ユーザー応答。
+   *
+   * Per-graph contract (validated inside the graph's HITL node):
+   * - `wiki-compose-research` (#949):
+   *   `{ approvedSourceIds: string[], rejectedSourceIds?: string[], note?: string }`
+   *
+   * Per-graph contract; the graph node validates the shape and rejects on
+   * mismatch. The route itself is shape-agnostic.
+   */
+  resume: unknown;
+}
+
+// ── POST / — create ─────────────────────────────────────────────────────────
+app.post("/:pageId/compose-sessions", authRequired, rateLimit(), async (c) => {
+  const pageId = c.req.param("pageId");
+  const userId = c.get("userId");
+  const db = c.get("db");
+
+  await assertPageEditAccess(db, pageId, userId);
+
+  let body: CreateSessionBody;
+  try {
+    body = await c.req.json<CreateSessionBody>();
+  } catch {
+    body = {};
+  }
+
+  const graphId =
+    typeof body.graphId === "string" && body.graphId.trim() ? body.graphId.trim() : undefined;
+  if (!graphId) {
+    throw new HTTPException(400, { message: "graphId is required" });
+  }
+  if (!getRegisteredGraph(graphId)) {
+    throw new HTTPException(400, { message: `Unknown graphId: ${graphId}` });
+  }
+
+  let backend: ReturnType<typeof assertSupportedComposeBackend>;
+  try {
+    backend = assertSupportedComposeBackend(body.backend ?? "zedi_managed");
+  } catch (err) {
+    if (err instanceof UnsupportedBackendError) {
+      throw new HTTPException(400, { message: err.message });
+    }
+    throw err;
+  }
+
+  const tier = await getUserTier(userId, db);
+  await assertComposeBackendReady({ backend, graphId, userId, tier, db });
+
+  const [row] = await db
+    .insert(wikiComposeSessions)
+    .values({
+      pageId,
+      userId,
+      graphId,
+      backend,
+      status: "pending",
+      metadata: body.metadata ?? null,
+    })
+    .returning();
+  if (!row) throw new HTTPException(500, { message: "Failed to create session" });
+
+  return c.json({ session: row }, 201);
+});
+
+// ── GET /:id — read ─────────────────────────────────────────────────────────
+app.get("/:pageId/compose-sessions/:id", authRequired, async (c) => {
+  const pageId = c.req.param("pageId");
+  const id = c.req.param("id");
+  const userId = c.get("userId");
+  const db = c.get("db");
+
+  await assertPageViewAccess(db, pageId, userId);
+
+  const [row] = await db
+    .select()
+    .from(wikiComposeSessions)
+    .where(and(eq(wikiComposeSessions.id, id), eq(wikiComposeSessions.pageId, pageId)))
+    .limit(1);
+  if (!row) throw new HTTPException(404, { message: "Session not found" });
+
+  const tier = await getUserTier(userId, db);
+
+  // Stale / unsupported backend rows must still be readable; skip projection
+  // instead of turning GET into a 500 (CodeRabbit P1 on reload path).
+  // 古い backend 行でもセッション行は返し、projection だけ省略する。
+  let projection = null;
+  try {
+    const backend = assertSupportedComposeBackend(row.backend);
+    projection = await loadComposeSessionProjection({
+      sessionId: row.id,
+      pageId: row.pageId,
+      graphId: row.graphId,
+      status: row.status,
+      phase: row.phase,
+      context: {
+        threadId: row.id,
+        sessionId: row.id,
+        userId,
+        userEmail: c.get("userEmail") ?? null,
+        pageId: row.pageId,
+        graphId: row.graphId,
+        backend,
+        tier,
+        db,
+        feature: `wiki_compose:${row.graphId}`,
+      },
+    });
+  } catch (err) {
+    if (!(err instanceof UnsupportedBackendError)) {
+      throw err;
+    }
+  }
+
+  return c.json({ session: row, projection });
+});
+
+// ── POST /:id/run — SSE run ─────────────────────────────────────────────────
+app.post("/:pageId/compose-sessions/:id/run", authRequired, rateLimit(), async (c) => {
+  const pageId = c.req.param("pageId");
+  const id = c.req.param("id");
+  const userId = c.get("userId");
+  const userEmail = c.get("userEmail") ?? null;
+  const db = c.get("db");
+
+  await assertPageEditAccess(db, pageId, userId);
+
+  const [session] = await db
+    .select()
+    .from(wikiComposeSessions)
+    .where(and(eq(wikiComposeSessions.id, id), eq(wikiComposeSessions.pageId, pageId)))
+    .limit(1);
+  if (!session) throw new HTTPException(404, { message: "Session not found" });
+
+  if (
+    session.status === "completed" ||
+    session.status === "cancelled" ||
+    session.status === "interrupted"
+  ) {
+    throw new HTTPException(409, {
+      message:
+        session.status === "interrupted"
+          ? "Session is interrupted; use PATCH /resume"
+          : `Session is ${session.status}`,
+    });
+  }
+
+  let body: RunSessionBody;
+  try {
+    body = await c.req.json<RunSessionBody>();
+  } catch {
+    body = {};
+  }
+
+  const tier = await getUserTier(userId, db);
+  const runner = new GraphRunner();
+
+  // Backend revalidation: row may have been created under a backend that is
+  // no longer permitted (future BYOK downgrade scenarios). Fail fast here.
+  // 行作成後に backend サポートが変わった場合への保険。
+  try {
+    assertSupportedComposeBackend(session.backend);
+  } catch (err) {
+    if (err instanceof UnsupportedBackendError) {
+      throw new HTTPException(400, { message: err.message });
+    }
+    throw err;
+  }
+
+  // Atomically claim the session so concurrent POST /run cannot both pass a
+  // read-then-write race and double-bill LLM usage.
+  const [claimed] = await db
+    .update(wikiComposeSessions)
+    .set({ status: "running" satisfies WikiComposeSessionStatus, updatedAt: new Date() })
+    .where(
+      and(
+        eq(wikiComposeSessions.id, id),
+        eq(wikiComposeSessions.pageId, pageId),
+        inArray(wikiComposeSessions.status, ["pending", "failed"]),
+      ),
+    )
+    .returning();
+  if (!claimed) {
+    throw new HTTPException(409, {
+      message:
+        session.status === "running"
+          ? "Session is already running"
+          : `Session is ${session.status}`,
+    });
+  }
+
+  return streamSSE(c, async (stream) => {
+    const send = async (ev: SseEvent) => {
+      await stream.writeSSE({ event: ev.type, data: JSON.stringify(ev) });
+    };
+
+    let finalStatus: WikiComposeSessionStatus = "failed";
+    let lastError: string | null = null;
+    let persisted = false;
+
+    const persistSession = async () => {
+      if (persisted) return;
+      persisted = true;
+      await persistOutcomeIfStillRunning(db, id, {
+        status: finalStatus,
+        lastError,
+      });
+    };
+
+    stream.onAbort(() => {
+      if (persisted) return;
+      // Preserve terminal outcomes decided before the client disconnected.
+      if (finalStatus !== "completed" && finalStatus !== "interrupted") {
+        finalStatus = "failed";
+        lastError = lastError ?? "Client disconnected";
+      }
+      void persistSession();
+    });
+
+    // `DATABASE_URL` が設定された本番経路では `PostgresSaver` を取得して
+    // checkpoint 保存・再開を有効化する。テスト / CI では未設定なので `false`
+    // を返し、LangGraph の checkpoint 機構を無効化したまま smoke-test で走る。
+    const checkpointer = await resolveCheckpointerForRun();
+
+    try {
+      await send(startedEvent(id, session.graphId, session.phase));
+
+      const recursionLimit = recursionLimitFor(session.graphId);
+      const events = runner.streamEvents(
+        {
+          graphId: session.graphId,
+          checkpointer,
+          ...(recursionLimit !== undefined ? { recursionLimit } : {}),
+          context: {
+            threadId: id,
+            sessionId: id,
+            userId,
+            userEmail,
+            pageId,
+            graphId: session.graphId,
+            backend: assertSupportedComposeBackend(session.backend),
+            tier,
+            db,
+            feature: `wiki_compose:${session.graphId}`,
+          },
+        },
+        { kind: "input", value: translateGraphInput(session.graphId, body.input ?? {}) },
+      );
+
+      for await (const raw of events) {
+        const ev = raw as LangGraphRuntimeEvent;
+        for (const mapped of mapLangGraphEvent(ev)) {
+          // LangGraph ≥ 1.x emits interrupts as a `__interrupt__` field on the
+          // final `on_chain_end` event rather than as a throw; sseMapper turns
+          // those into `SseInterruptEvent` rows. Treat any emitted interrupt
+          // event as terminal — flip status to "interrupted" so the route
+          // persists `closedAt=null` and surfaces resume affordance.
+          // LangGraph 1.x では interrupt は throw されず on_chain_end の output
+          // 内で来る。sseMapper が interrupt SSE に変換するので、ここでは
+          // emitted した時点で finalStatus を interrupted にする。
+          if (mapped.type === "interrupt") {
+            finalStatus = "interrupted";
+          }
+          await send(mapped);
+        }
+      }
+
+      // Only promote to "completed" if the stream did NOT emit an interrupt
+      // event above. Without this guard, an interrupt detected inside the
+      // for-await loop would be silently overwritten to "completed" once the
+      // stream drains (codex review #956 / coderabbit critical finding).
+      // ストリーム完走時点で interrupted を上書きしないよう、明示的にガードする。
+      if (finalStatus !== "interrupted") {
+        finalStatus = "completed";
+      }
+    } catch (err) {
+      // Legacy throw path (LangGraph might re-introduce, version skew etc.).
+      // 古い throw 経路の保険として残す。
+      if (isInterruptError(err)) {
+        finalStatus = "interrupted";
+        await send({ type: "interrupt", payload: extractInterruptPayload(err) });
+      } else {
+        finalStatus = "failed";
+        lastError = err instanceof Error ? err.message : String(err);
+        await send(errorEvent(lastError));
+      }
+    } finally {
+      if (finalStatus === "completed") {
+        await send(statusEvent("completed"));
+      }
+      await send(doneEvent(finalStatus));
+      await persistSession();
+
+      // Hush unused-import warning when running without exporting names; keeps the
+      // import grouped with the SSE writes for readability.
+      void SSE_EVENT_NAMES;
+      void GRAPH_CONTEXT_CONFIG_KEY;
+    }
+  });
+});
+
+// ── PATCH /:id/resume ───────────────────────────────────────────────────────
+app.patch("/:pageId/compose-sessions/:id/resume", authRequired, rateLimit(), async (c) => {
+  const pageId = c.req.param("pageId");
+  const id = c.req.param("id");
+  const userId = c.get("userId");
+  const userEmail = c.get("userEmail") ?? null;
+  const db = c.get("db");
+
+  await assertPageEditAccess(db, pageId, userId);
+
+  const [session] = await db
+    .select()
+    .from(wikiComposeSessions)
+    .where(and(eq(wikiComposeSessions.id, id), eq(wikiComposeSessions.pageId, pageId)))
+    .limit(1);
+  if (!session) throw new HTTPException(404, { message: "Session not found" });
+  if (session.status !== "interrupted") {
+    throw new HTTPException(409, { message: "Session is not interrupted" });
+  }
+
+  let body: ResumeSessionBody;
+  try {
+    body = await c.req.json<ResumeSessionBody>();
+  } catch {
+    throw new HTTPException(400, { message: "Invalid JSON body" });
+  }
+
+  const tier = await getUserTier(userId, db);
+  const runner = new GraphRunner();
+
+  try {
+    assertSupportedComposeBackend(session.backend);
+  } catch (err) {
+    if (err instanceof UnsupportedBackendError) {
+      throw new HTTPException(400, { message: err.message });
+    }
+    throw err;
+  }
+
+  const [claimed] = await db
+    .update(wikiComposeSessions)
+    .set({ status: "running", updatedAt: new Date() })
+    .where(
+      and(
+        eq(wikiComposeSessions.id, id),
+        eq(wikiComposeSessions.pageId, pageId),
+        eq(wikiComposeSessions.status, "interrupted"),
+      ),
+    )
+    .returning();
+  if (!claimed) {
+    throw new HTTPException(409, { message: "Session is not interrupted" });
+  }
+
+  // Resume relies on the checkpointer to fetch the suspended thread; production
+  // routes load `PostgresSaver` here, tests/smoke runs get `false`.
+  const checkpointer = await resolveCheckpointerForRun();
+
+  let result;
+  try {
+    const recursionLimit = recursionLimitFor(session.graphId);
+    result = await runner.resume(
+      {
+        graphId: session.graphId,
+        checkpointer,
+        ...(recursionLimit !== undefined ? { recursionLimit } : {}),
+        context: {
+          threadId: id,
+          sessionId: id,
+          userId,
+          userEmail,
+          pageId,
+          graphId: session.graphId,
+          backend: assertSupportedComposeBackend(session.backend),
+          tier,
+          db,
+          feature: `wiki_compose:${session.graphId}`,
+        },
+      },
+      body.resume,
+    );
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    await persistOutcomeIfStillRunning(db, id, {
+      status: "failed",
+      lastError: message,
+    });
+    if (err instanceof GraphNotRegisteredError || err instanceof UnsupportedBackendError) {
+      throw new HTTPException(400, { message: err.message });
+    }
+    throw err;
+  }
+
+  const status: WikiComposeSessionStatus =
+    result.status === "completed"
+      ? "completed"
+      : result.status === "interrupted"
+        ? "interrupted"
+        : "failed";
+
+  await persistOutcomeIfStillRunning(db, id, {
+    status,
+    lastError: status === "failed" ? (result.error ?? null) : null,
+  });
+
+  return c.json({ status, output: result.output ?? null });
+});
+
+// ── DELETE /:id — cancel ────────────────────────────────────────────────────
+app.delete("/:pageId/compose-sessions/:id", authRequired, async (c) => {
+  const pageId = c.req.param("pageId");
+  const id = c.req.param("id");
+  const userId = c.get("userId");
+  const db = c.get("db");
+
+  await assertPageEditAccess(db, pageId, userId);
+
+  const [row] = await db
+    .select({ id: wikiComposeSessions.id, status: wikiComposeSessions.status })
+    .from(wikiComposeSessions)
+    .where(and(eq(wikiComposeSessions.id, id), eq(wikiComposeSessions.pageId, pageId)))
+    .limit(1);
+  if (!row) throw new HTTPException(404, { message: "Session not found" });
+
+  if (row.status === "completed" || row.status === "cancelled") {
+    return c.json({ status: row.status });
+  }
+
+  const cancellable: WikiComposeSessionStatus[] = ["pending", "running", "interrupted", "failed"];
+
+  const [cancelled] = await db
+    .update(wikiComposeSessions)
+    .set({
+      status: "cancelled" satisfies WikiComposeSessionStatus,
+      closedAt: new Date(),
+      updatedAt: new Date(),
+    })
+    .where(and(eq(wikiComposeSessions.id, id), inArray(wikiComposeSessions.status, cancellable)))
+    .returning({ status: wikiComposeSessions.status });
+
+  if (cancelled) {
+    return c.json({ status: "cancelled" });
+  }
+
+  // Graph may have finished (e.g. `completed`) between the initial read and this update.
+  const [latest] = await db
+    .select({ status: wikiComposeSessions.status })
+    .from(wikiComposeSessions)
+    .where(and(eq(wikiComposeSessions.id, id), eq(wikiComposeSessions.pageId, pageId)))
+    .limit(1);
+
+  return c.json({ status: latest?.status ?? row.status });
+});
+
+function isInterruptError(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const name = (err as { name?: unknown }).name;
+  return typeof name === "string" && /Interrupt/.test(name);
+}
+
+function extractInterruptPayload(err: unknown): unknown {
+  if (!err || typeof err !== "object") return undefined;
+  return (
+    (err as { value?: unknown; payload?: unknown }).payload ?? (err as { value?: unknown }).value
+  );
+}
+
+export default app;
diff --git a/server/api/src/routes/ingest.ts b/server/api/src/routes/ingest.ts
index e90c3838..533b45d0 100644
--- a/server/api/src/routes/ingest.ts
+++ b/server/api/src/routes/ingest.ts
@@ -1,16 +1,23 @@
 /**
- * /api/ingest — LLM Wiki ingest flow (P1, otomatty/zedi#595).
+ * /api/ingest — LLM Wiki ingest flow (P1 #595, graph P4 #952).
  *
  * POST /api/ingest/plan — dry-run: given a URL, propose how the article should
  * be merged / created / skipped in the user's existing Wiki. Does NOT write
  * to the database. The corresponding apply endpoint is tracked as a follow-up
  * and will reuse the plan shape returned here.
  *
+ * POST /api/ingest/graph/run — invoke graph `ingest-planner` (#952): shared
+ * research loop + structured ingest plan via ZediChatModel. See route TSDoc below.
+ *
+ * POST /api/ingest/graph/resume — resume an interrupted `ingest-planner` run
+ * (HITL at `human_review_research`) using the same `threadId`.
+ *
  * LLM Wiki の ingest フロー。プラン生成までの dry-run エンドポイント。
  * DB への書き込みは行わず、プレビュー用のプラン JSON を返す。
  * apply（実適用）エンドポイントは後続 PR で追加する。
  */
 import { Hono } from "hono";
+import { randomUUID } from "node:crypto";
 import { HTTPException } from "hono/http-exception";
 import { sql } from "drizzle-orm";
 import { authRequired } from "../middleware/auth.js";
@@ -34,9 +41,149 @@ import { pages } from "../schema/pages.js";
 import { pageContents } from "../schema/pageContents.js";
 import { recordActivity } from "../services/activityLogService.js";
 import type { AppEnv, AIProviderType } from "../types/index.js";
+import { GraphRunner } from "../agents/runner/graphRunner.js";
+import { INGEST_PLANNER_GRAPH_ID } from "../agents/graphs/ingest/index.js";
+import type { IngestArticleSummary } from "../services/ingestPlanner.js";
+import { assertSupportedComposeBackend } from "../agents/core/llm/modelFactory.js";
+import { assertComposeBackendReady } from "../agents/core/composeBackendValidation.js";
+import { resolveCheckpointerForRun } from "../agents/core/checkpoint/index.js";
+import { getRegisteredGraph } from "../agents/registry/graphRegistry.js";
+import type { BaseCheckpointSaver } from "@langchain/langgraph";
+import type { ExecutionBackend } from "../agents/core/types/executionBackend.js";
 
 const app = new Hono<AppEnv>();
 
+const INGEST_GRAPH_RECURSION_LIMIT = 60;
+
+/**
+ * Map graph runner failures caused by client/input validation to HTTP 4xx.
+ */
+function httpStatusForGraphFailure(error: string | undefined): 400 | 500 {
+  if (!error) return 500;
+  const clientish =
+    /prepare_ingest|plan_ingest|invalid|required|expected|approvedSourceIds|zod|resume/i.test(
+      error,
+    );
+  return clientish ? 400 : 500;
+}
+
+function assertGraphRunArticle(article: IngestArticleSummary): void {
+  if (!article.title?.trim() || !article.url?.trim() || typeof article.excerpt !== "string") {
+    throw new HTTPException(400, { message: "article { title, url, excerpt } is required" });
+  }
+}
+
+/**
+ * LangGraph `thread_id` scoped per user so shared checkpoint storage cannot collide.
+ * 共有 checkpoint 上での thread_id 衝突を防ぐため userId でスコープする。
+ */
+function scopedIngestGraphThreadId(userId: string, clientThreadId: string): string {
+  return `${userId}:${clientThreadId}`;
+}
+
+function normalizeGraphCandidates(raw: CandidatePage[] | undefined): CandidatePage[] {
+  if (!Array.isArray(raw)) return [];
+  const out: CandidatePage[] = [];
+  for (const entry of raw) {
+    if (typeof entry?.id !== "string" || !entry.id.trim()) continue;
+    if (typeof entry.title !== "string") continue;
+    if (typeof entry.excerpt !== "string") continue;
+    out.push({
+      id: entry.id.trim(),
+      title: entry.title,
+      excerpt: entry.excerpt,
+    });
+  }
+  return out;
+}
+
+/**
+ * Read `userId` stored in an ingest-planner checkpoint, if any.
+ * ingest-planner checkpoint に保存された `userId` を読む（あれば）。
+ */
+async function readIngestCheckpointUserId(
+  threadId: string,
+  checkpointer: BaseCheckpointSaver,
+): Promise<string | null> {
+  const registered = getRegisteredGraph(INGEST_PLANNER_GRAPH_ID);
+  if (!registered) return null;
+  const graph = registered.factory({ checkpointer }) as {
+    getState?: (config: unknown) => Promise<{ values?: Record<string, unknown> } | undefined>;
+  };
+  if (typeof graph.getState !== "function") return null;
+  try {
+    const snap = await graph.getState({ configurable: { thread_id: threadId } });
+    const owner = snap?.values?.userId;
+    return typeof owner === "string" && owner.length > 0 ? owner : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Reject cross-user access when reusing a `threadId` tied to another user's checkpoint.
+ * 他ユーザーの checkpoint に紐づく `threadId` 再利用を拒否する。
+ */
+async function assertIngestThreadAccessible(
+  threadId: string,
+  userId: string,
+  checkpointer: BaseCheckpointSaver | false,
+): Promise<void> {
+  if (checkpointer === false) return;
+  const owner = await readIngestCheckpointUserId(threadId, checkpointer);
+  if (owner !== null && owner !== userId) {
+    throw new HTTPException(403, { message: "threadId is not accessible" });
+  }
+}
+
+/**
+ * True when the ingest-planner checkpoint is halted at a HITL interrupt.
+ * ingest-planner が HITL で停止しているか。
+ */
+async function ingestThreadHasPendingInterrupt(
+  threadId: string,
+  checkpointer: BaseCheckpointSaver,
+): Promise<boolean> {
+  const registered = getRegisteredGraph(INGEST_PLANNER_GRAPH_ID);
+  if (!registered) return false;
+  const graph = registered.factory({ checkpointer }) as {
+    getState?: (config: unknown) => Promise<
+      | {
+          tasks?: Array<{ interrupts?: unknown[] }>;
+        }
+      | undefined
+    >;
+  };
+  if (typeof graph.getState !== "function") return false;
+  try {
+    const snap = await graph.getState({ configurable: { thread_id: threadId } });
+    const tasks = snap?.tasks;
+    if (!Array.isArray(tasks)) return false;
+    return tasks.some((t) => Array.isArray(t.interrupts) && t.interrupts.length > 0);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Reject `POST /graph/run` when the thread is waiting on `POST /graph/resume`.
+ * 中断済み thread に fresh input を流すと HITL をバイパスするため拒否する。
+ */
+async function assertIngestThreadReadyForRun(
+  threadId: string,
+  checkpointer: BaseCheckpointSaver | false,
+): Promise<void> {
+  if (checkpointer === false) return;
+  const owner = await readIngestCheckpointUserId(threadId, checkpointer);
+  if (owner === null) return;
+  const pending = await ingestThreadHasPendingInterrupt(threadId, checkpointer);
+  if (pending) {
+    throw new HTTPException(409, {
+      message: "Graph is interrupted; use POST /api/ingest/graph/resume",
+    });
+  }
+}
+
 /**
  * リクエストボディ。
  * Request body for POST /api/ingest/plan.
@@ -271,6 +418,228 @@ app.post("/plan", authRequired, rateLimit(), async (c) => {
   });
 });
 
+/**
+ * Request body for `POST /api/ingest/graph/run` (#952).
+ */
+interface IngestGraphRunBody {
+  /** Optional stable thread id for checkpoint resume (defaults to new UUID). */
+  threadId?: string;
+  backend?: ExecutionBackend;
+  article?: IngestArticleSummary;
+  candidates?: CandidatePage[];
+  userSchema?: string;
+  maxIterations?: number;
+}
+
+/**
+ * Request body for `POST /api/ingest/graph/resume` (#952).
+ */
+interface IngestGraphResumeBody {
+  threadId: string;
+  backend?: ExecutionBackend;
+  resume: unknown;
+}
+
+/**
+ * POST /api/ingest/graph/run — LangGraph `ingest-planner` execution (#952).
+ *
+ * **Integration with `POST /api/ingest/plan` (#595)**
+ *
+ * - `/plan` remains the URL-first production path: server-side article extraction,
+ *   candidate SQL search, and `callProvider` via `ingestPlanner.ts` (no research loop).
+ * - `/graph/run` expects the caller to supply `article` + `candidates` (typically the
+ *   same shapes `/plan` returns) and runs graph id {@link INGEST_PLANNER_GRAPH_ID}:
+ *   `prepare_ingest` → shared P1 research nodes → `plan_ingest` (ZediChatModel).
+ * - Both endpoints return the same {@link IngestPlan} JSON shape on success.
+ * - Apply persistence stays on `POST /api/ingest/apply` for either path.
+ *
+ * **Resume**
+ *
+ * When the graph halts at `human_review_research`, the response includes `threadId`
+ * (client-visible id; checkpoint `thread_id` is scoped as `{userId}:{threadId}`).
+ * Call `POST /api/ingest/graph/resume` with the same `threadId` and research resume payload
+ * (`{ approvedSourceIds, rejectedSourceIds?, note? }`, same as compose research).
+ */
+app.post("/graph/run", authRequired, rateLimit(), async (c) => {
+  const userId = c.get("userId");
+  const userEmail = c.get("userEmail") ?? null;
+  const db = c.get("db");
+
+  let body: IngestGraphRunBody;
+  try {
+    body = await c.req.json<IngestGraphRunBody>();
+  } catch {
+    throw new HTTPException(400, { message: "Invalid JSON body" });
+  }
+
+  if (!body.article) {
+    throw new HTTPException(400, { message: "article { title, url, excerpt } is required" });
+  }
+  assertGraphRunArticle(body.article);
+
+  const candidates = normalizeGraphCandidates(body.candidates);
+  const clientThreadId =
+    typeof body.threadId === "string" && body.threadId.trim() ? body.threadId.trim() : randomUUID();
+  const threadId = scopedIngestGraphThreadId(userId, clientThreadId);
+
+  let backend: ExecutionBackend;
+  try {
+    backend = assertSupportedComposeBackend(body.backend ?? "zedi_managed");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "unsupported backend";
+    throw new HTTPException(400, { message: msg });
+  }
+
+  const tier = await getUserTier(userId, db);
+  await assertComposeBackendReady({
+    backend,
+    graphId: INGEST_PLANNER_GRAPH_ID,
+    userId,
+    tier,
+    db,
+  });
+
+  const checkpointer = await resolveCheckpointerForRun();
+  await assertIngestThreadAccessible(threadId, userId, checkpointer);
+  await assertIngestThreadReadyForRun(threadId, checkpointer);
+  const runner = new GraphRunner();
+  const result = await runner.invoke(
+    {
+      graphId: INGEST_PLANNER_GRAPH_ID,
+      checkpointer,
+      recursionLimit: INGEST_GRAPH_RECURSION_LIMIT,
+      context: {
+        threadId,
+        sessionId: threadId,
+        userId,
+        userEmail,
+        pageId: "",
+        graphId: INGEST_PLANNER_GRAPH_ID,
+        backend,
+        tier,
+        db,
+        feature: "ingest_graph:run",
+      },
+    },
+    {
+      kind: "input",
+      value: {
+        article: body.article,
+        candidates,
+        userSchema: body.userSchema ?? null,
+        maxIterations: body.maxIterations,
+      },
+    },
+  );
+
+  if (result.status === "failed") {
+    const status = httpStatusForGraphFailure(result.error);
+    throw new HTTPException(status, { message: result.error ?? "Graph run failed" });
+  }
+
+  const output = result.output as
+    | {
+        ingestPlan?: unknown;
+        __interrupt__?: unknown[];
+      }
+    | undefined;
+
+  return c.json({
+    status: result.status,
+    threadId: clientThreadId,
+    graphId: INGEST_PLANNER_GRAPH_ID,
+    plan: output?.ingestPlan ?? null,
+    output,
+  });
+});
+
+/**
+ * POST /api/ingest/graph/resume — resume `ingest-planner` after research HITL (#952).
+ */
+app.post("/graph/resume", authRequired, rateLimit(), async (c) => {
+  const userId = c.get("userId");
+  const userEmail = c.get("userEmail") ?? null;
+  const db = c.get("db");
+
+  let body: IngestGraphResumeBody;
+  try {
+    body = await c.req.json<IngestGraphResumeBody>();
+  } catch {
+    throw new HTTPException(400, { message: "Invalid JSON body" });
+  }
+
+  if (typeof body.threadId !== "string" || !body.threadId.trim()) {
+    throw new HTTPException(400, { message: "threadId is required" });
+  }
+  if (!Object.prototype.hasOwnProperty.call(body, "resume")) {
+    throw new HTTPException(400, { message: "resume is required" });
+  }
+  const clientThreadId = body.threadId.trim();
+  const threadId = scopedIngestGraphThreadId(userId, clientThreadId);
+
+  let backend: ExecutionBackend;
+  try {
+    backend = assertSupportedComposeBackend(body.backend ?? "zedi_managed");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "unsupported backend";
+    throw new HTTPException(400, { message: msg });
+  }
+
+  const tier = await getUserTier(userId, db);
+  await assertComposeBackendReady({
+    backend,
+    graphId: INGEST_PLANNER_GRAPH_ID,
+    userId,
+    tier,
+    db,
+  });
+
+  const checkpointer = await resolveCheckpointerForRun();
+  if (checkpointer === false) {
+    throw new HTTPException(503, {
+      message: "Graph resume requires DATABASE_URL checkpointing",
+    });
+  }
+
+  await assertIngestThreadAccessible(threadId, userId, checkpointer);
+  const runner = new GraphRunner();
+  const result = await runner.resume(
+    {
+      graphId: INGEST_PLANNER_GRAPH_ID,
+      checkpointer,
+      recursionLimit: INGEST_GRAPH_RECURSION_LIMIT,
+      context: {
+        threadId,
+        sessionId: threadId,
+        userId,
+        userEmail,
+        pageId: "",
+        graphId: INGEST_PLANNER_GRAPH_ID,
+        backend,
+        tier,
+        db,
+        feature: "ingest_graph:resume",
+      },
+    },
+    body.resume,
+  );
+
+  if (result.status === "failed") {
+    const status = httpStatusForGraphFailure(result.error);
+    throw new HTTPException(status, { message: result.error ?? "Graph resume failed" });
+  }
+
+  const output = result.output as { ingestPlan?: unknown } | undefined;
+
+  return c.json({
+    status: result.status,
+    threadId: clientThreadId,
+    graphId: INGEST_PLANNER_GRAPH_ID,
+    plan: output?.ingestPlan ?? null,
+    output,
+  });
+});
+
 /**
  * Request body for POST /api/ingest/apply.
  * Ingest プラン適用リクエストボディ。
diff --git a/server/api/src/routes/search.ts b/server/api/src/routes/search.ts
index d419a60b..16af35df 100644
--- a/server/api/src/routes/search.ts
+++ b/server/api/src/routes/search.ts
@@ -41,8 +41,7 @@ import { Hono } from "hono";
 import { sql } from "drizzle-orm";
 import { authRequired } from "../middleware/auth.js";
 import type { AppEnv } from "../types/index.js";
-import { extractEmailDomain } from "../lib/freeEmailDomains.js";
-import { getDefaultNoteOrNull } from "../services/defaultNoteService.js";
+import { searchUserWikiPages } from "../services/wikiSearchService.js";
 
 function escapeLike(input: string): string {
   return input.replace(/\\/g, "\\\\").replace(/%/g, "\\%").replace(/_/g, "\\_");
@@ -79,123 +78,40 @@ app.get("/", authRequired, async (c) => {
   const limit = clampLimit(c.req.query("limit"));
   const pattern = `%${escapeLike(query)}%`;
 
-  // 検索条件用にだけ `content_text` を WHERE に登場させるが、SELECT には含めない。
-  // SELECT に流すと API 経由でページ本文が丸ごと露出し得る（PR #873 review:
-  // CodeRabbit）。クライアントが消費するのは `content_preview` のみ。
+  // ページ検索は `services/wikiSearchService.ts` に切り出した純粋関数を経由する。
+  // SQL は元 route と同一を維持しつつ、tool / subgraph (#949) からも再利用可能に
+  // するための移譲。`content_text` を SELECT に出さないポリシー、scope=shared での
+  // owner / accepted member / domain rule 結合、`scope=own` の default-note 絞り込み
+  // はすべて service 側で踏襲する。
   //
-  // `content_text` is used in the WHERE clause for matching but is NOT in the
-  // SELECT list — otherwise the API would leak full page bodies (PR #873 review:
-  // CodeRabbit). Clients only consume `content_preview`.
-  const searchColumns = sql`p.id, p.title, p.content_preview, p.updated_at, p.note_id`;
-
-  const normalizedEmail = typeof userEmailRaw === "string" ? userEmailRaw.trim().toLowerCase() : "";
-  const emailDomain = extractEmailDomain(normalizedEmail);
-
-  const domainPredicate =
-    emailDomain !== null
-      ? sql`OR EXISTS (
-          SELECT 1
-          FROM notes n
-          INNER JOIN note_domain_access nda ON nda.note_id = n.id
-          WHERE n.id = p.note_id
-            AND n.is_deleted = false
-            AND nda.is_deleted = false
-            AND nda.domain = ${emailDomain}
-        )`
-      : sql``;
-
-  let pageRows: unknown[] = [];
-
-  if (scope === "shared") {
-    const sharedResults = await db.execute(sql`
-      SELECT ${searchColumns}
-      FROM pages p
-      LEFT JOIN page_contents pc ON pc.page_id = p.id
-      WHERE p.is_deleted = false
-        AND (
-          EXISTS (
-            SELECT 1 FROM notes n
-            WHERE n.id = p.note_id AND n.is_deleted = false AND n.owner_id = ${userId}
-          )
-          OR EXISTS (
-            SELECT 1
-            FROM notes n
-            INNER JOIN note_members nm ON nm.note_id = n.id
-            INNER JOIN "user" u ON LOWER(u.email) = LOWER(nm.member_email)
-            WHERE n.id = p.note_id
-              AND u.id = ${userId}
-              AND nm.status = 'accepted'
-              AND nm.is_deleted = false
-              AND n.is_deleted = false
-          )
-          ${domainPredicate}
-        )
-        AND (
-          p.title ILIKE ${pattern}
-          OR pc.content_text ILIKE ${pattern}
-        )
-      ORDER BY p.updated_at DESC
-      LIMIT ${limit}
-    `);
-    pageRows = sharedResults.rows;
-  } else {
-    const defaultNote = await getDefaultNoteOrNull(db, userId);
-    if (!defaultNote) {
-      // デフォルトノートが無い場合でもハイライト検索は走り得るので、ページ部だけ空配列に。
-      // Even without a default note, highlight search can still run, so only the
-      // page branch short-circuits here.
-      const highlightRows = await runPdfHighlightSearch(db, userId, pattern, limit);
-      return c.json({ results: highlightRows });
-    }
-    const ownResults = await db.execute(sql`
-      SELECT ${searchColumns}
-      FROM pages p
-      LEFT JOIN page_contents pc ON pc.page_id = p.id
-      WHERE p.is_deleted = false
-        AND p.note_id = ${defaultNote.id}
-        AND (
-          p.title ILIKE ${pattern}
-          OR pc.content_text ILIKE ${pattern}
-        )
-      ORDER BY p.updated_at DESC
-      LIMIT ${limit}
-    `);
-    pageRows = ownResults.rows;
-  }
-
-  // 契約フィールドのみを明示マップして response に流す。SQL の SELECT に直接含まれない
-  // カラム (owner_id / thumbnail_url / source_url) は明示的に null/undefined で埋めて
-  // 型 (`SearchPageResultRow`) との整合を取る。raw row を spread で流すと将来 SELECT
-  // を増やしたとき静かに API が漏れるので、PR #873 review (CodeRabbit) で明示化した。
-  //
-  // Map only the contracted fields explicitly. We do not spread raw SQL rows
-  // because any future SELECT addition would silently widen the API payload
-  // (PR #873 review: CodeRabbit). Columns not in the current SELECT are
-  // emitted as `null`/`undefined` to stay aligned with `SearchPageResultRow`.
-  const taggedPageRows = pageRows.map((row) => {
-    const r = row as {
-      id: string;
-      note_id: string;
-      title: string | null;
-      content_preview: string | null;
-      updated_at: string;
-    };
-    return {
-      kind: "page" as const,
-      id: r.id,
-      note_id: r.note_id,
-      // `owner_id` / `thumbnail_url` / `source_url` は将来 SELECT に追加する想定の
-      // プレースホルダ。現状の SQL では返らないので明示的に null/undefined を入れる。
-      // Placeholders for columns not yet in SELECT; emitted explicitly so the
-      // payload shape stays stable for the discriminated union.
-      owner_id: null,
-      title: r.title,
-      content_preview: r.content_preview,
-      thumbnail_url: null,
-      source_url: null,
-      updated_at: r.updated_at,
-    };
-  });
+  // Page search is delegated to `wikiSearchService.searchUserWikiPages` so the
+  // research-loop subgraph (#949) can call the same data set without going
+  // through Hono context. The SQL is preserved verbatim; the previously-reviewed
+  // safety properties (no full body in SELECT, default-note scoping, domain
+  // predicate) live in the service module now.
+  const userEmail = typeof userEmailRaw === "string" ? userEmailRaw : null;
+  const pageHits =
+    scope === "shared"
+      ? await searchUserWikiPages(db, userId, userEmail, query, "shared", limit)
+      : await searchUserWikiPages(db, userId, userEmail, query, "own", limit);
+
+  // `scope=own` でデフォルトノートが無いユーザーは pageHits === [] になる。
+  // ハイライト検索は所有さえあれば走り得るので、ページ無しでも続行する。
+  // For `scope=own` with no default note, `pageHits` is empty; highlight search
+  // is still meaningful since highlights are owner-keyed.
+  const taggedPageRows = pageHits.map((hit) => ({
+    kind: "page" as const,
+    id: hit.pageId,
+    note_id: hit.noteId,
+    // `owner_id` / `thumbnail_url` / `source_url` は将来 SELECT に追加する想定の
+    // プレースホルダ。Placeholders for columns not yet in SELECT.
+    owner_id: null,
+    title: hit.title,
+    content_preview: hit.contentPreview,
+    thumbnail_url: null,
+    source_url: null,
+    updated_at: hit.updatedAt,
+  }));
 
   const highlightRows = await runPdfHighlightSearch(db, userId, pattern, limit);
 
diff --git a/server/api/src/routes/userAiCredentials.ts b/server/api/src/routes/userAiCredentials.ts
new file mode 100644
index 00000000..5688a391
--- /dev/null
+++ b/server/api/src/routes/userAiCredentials.ts
@@ -0,0 +1,81 @@
+/**
+ * `/api/user/ai-credentials` — BYOK credential registration (#951).
+ *
+ * 平文 API キーはレスポンスに含めない。POST body で受け取り暗号化して保存する。
+ * Plaintext keys are never returned; POST accepts a key and stores ciphertext only.
+ */
+import { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { authRequired } from "../middleware/auth.js";
+import { rateLimit } from "../middleware/rateLimit.js";
+import type { AppEnv } from "../types/index.js";
+import type { UserAiCredentialProvider } from "../schema/userAiCredentials.js";
+import {
+  deleteUserAiCredential,
+  isUserAiCredentialStorageEnabled,
+  listUserAiCredentialAvailability,
+  upsertUserAiCredential,
+} from "../services/userAiCredentialService.js";
+
+const PROVIDERS: readonly UserAiCredentialProvider[] = ["anthropic", "openai", "google"];
+
+function parseProvider(value: unknown): UserAiCredentialProvider {
+  if (typeof value !== "string" || !PROVIDERS.includes(value as UserAiCredentialProvider)) {
+    throw new HTTPException(400, {
+      message: `provider must be one of: ${PROVIDERS.join(", ")}`,
+    });
+  }
+  return value as UserAiCredentialProvider;
+}
+
+const app = new Hono<AppEnv>();
+
+/** GET — list configured providers (no secrets). */
+app.get("/", authRequired, async (c) => {
+  const userId = c.get("userId");
+  const db = c.get("db");
+  const storageEnabled = isUserAiCredentialStorageEnabled();
+  const providers = storageEnabled
+    ? await listUserAiCredentialAvailability(userId, db)
+    : PROVIDERS.map((provider) => ({ provider, configured: false }));
+  return c.json({ storageEnabled, providers });
+});
+
+/** PUT — upsert encrypted credential for a provider. */
+app.put("/:provider", authRequired, rateLimit(), async (c) => {
+  if (!isUserAiCredentialStorageEnabled()) {
+    throw new HTTPException(503, {
+      message: "Server-side credential storage is not configured",
+    });
+  }
+  const userId = c.get("userId");
+  const db = c.get("db");
+  const provider = parseProvider(c.req.param("provider"));
+  let body: { apiKey?: string };
+  try {
+    body = await c.req.json<{ apiKey?: string }>();
+  } catch {
+    throw new HTTPException(400, { message: "Invalid JSON body" });
+  }
+  const apiKey = typeof body.apiKey === "string" ? body.apiKey : "";
+  try {
+    await upsertUserAiCredential(userId, provider, apiKey, db);
+  } catch (err) {
+    if (err instanceof Error && err.message === "API key is required") {
+      throw new HTTPException(400, { message: err.message });
+    }
+    throw err;
+  }
+  return c.json({ ok: true, provider });
+});
+
+/** DELETE — remove a stored credential. */
+app.delete("/:provider", authRequired, rateLimit(), async (c) => {
+  const userId = c.get("userId");
+  const db = c.get("db");
+  const provider = parseProvider(c.req.param("provider"));
+  const removed = await deleteUserAiCredential(userId, provider, db);
+  return c.json({ ok: true, provider, removed });
+});
+
+export default app;
diff --git a/server/api/src/schema/index.ts b/server/api/src/schema/index.ts
index 954e2721..76f30be1 100644
--- a/server/api/src/schema/index.ts
+++ b/server/api/src/schema/index.ts
@@ -103,6 +103,18 @@ export {
   type ActivityKind,
   type ActivityActor,
 } from "./activityLog.js";
+export {
+  wikiComposeSessions,
+  type WikiComposeSession,
+  type NewWikiComposeSession,
+  type WikiComposeSessionStatus,
+} from "./wikiComposeSessions.js";
+export {
+  userAiCredentials,
+  type UserAiCredential,
+  type NewUserAiCredential,
+  type UserAiCredentialProvider,
+} from "./userAiCredentials.js";
 
 export {
   usersRelations,
diff --git a/server/api/src/schema/userAiCredentials.ts b/server/api/src/schema/userAiCredentials.ts
new file mode 100644
index 00000000..029b67b0
--- /dev/null
+++ b/server/api/src/schema/userAiCredentials.ts
@@ -0,0 +1,44 @@
+import { pgTable, text, timestamp, uniqueIndex } from "drizzle-orm/pg-core";
+import { users } from "./users.js";
+
+/**
+ * Provider ids stored for BYOK credentials (matches {@link AIProviderType} subset).
+ * BYOK 用 credential の provider 識別子（`AIProviderType` のサブセット）。
+ */
+export type UserAiCredentialProvider = "anthropic" | "openai" | "google";
+
+/**
+ * Server-side encrypted user API keys for Wiki Compose BYOK (#951).
+ *
+ * 平文 API キーは保存しない。`encrypted_api_key` は AES-256-GCM で暗号化した
+ * blob（IV + auth tag + ciphertext）を Base64 で格納する。復号鍵は環境変数
+ * `USER_AI_CREDENTIALS_ENCRYPTION_KEY`（32 バイト）のみが保持する。
+ *
+ * Plaintext API keys are never stored. `encrypted_api_key` holds a Base64 blob
+ * (IV + auth tag + ciphertext) from AES-256-GCM. Only
+ * `USER_AI_CREDENTIALS_ENCRYPTION_KEY` (32 bytes) can decrypt at runtime.
+ *
+ * @see {@link encryptUserAiCredential} / {@link decryptUserAiCredential}
+ */
+export const userAiCredentials = pgTable(
+  "user_ai_credentials",
+  {
+    id: text("id").primaryKey(),
+    userId: text("user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    provider: text("provider", { enum: ["anthropic", "openai", "google"] }).notNull(),
+    /** AES-256-GCM encrypted secret (never plaintext). 平文ではない暗号化 blob。 */
+    encryptedApiKey: text("encrypted_api_key").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+  },
+  (table) => [
+    uniqueIndex("idx_user_ai_credentials_user_provider").on(table.userId, table.provider),
+  ],
+);
+
+/** Selected row type for `user_ai_credentials`. `user_ai_credentials` の取得行型。 */
+export type UserAiCredential = typeof userAiCredentials.$inferSelect;
+/** Insert type for `user_ai_credentials`. `user_ai_credentials` の挿入型。 */
+export type NewUserAiCredential = typeof userAiCredentials.$inferInsert;
diff --git a/server/api/src/schema/wikiComposeSessions.ts b/server/api/src/schema/wikiComposeSessions.ts
new file mode 100644
index 00000000..f02ba196
--- /dev/null
+++ b/server/api/src/schema/wikiComposeSessions.ts
@@ -0,0 +1,127 @@
+/**
+ * `wiki_compose_sessions` — メタデータテーブル。1 行 = 1 つの compose 実行。
+ *
+ * Meta-row table for Wiki Compose runs. Each row represents a single user-
+ * initiated compose session for a page; LangGraph's internal `checkpoints*`
+ * tables (owned by `PostgresSaver.setup()`) hold the per-step graph state and
+ * stay outside Drizzle's migration set on purpose.
+ *
+ * The session id is reused as the LangGraph `thread_id`, so callers can
+ * stream / resume by passing the same UUID to both subsystems.
+ *
+ * Issue: #948 (P0 — LangGraph 基盤)
+ */
+import { pgTable, uuid, text, timestamp, index, jsonb } from "drizzle-orm/pg-core";
+import { sql } from "drizzle-orm";
+import { users } from "./users.js";
+import { pages } from "./pages.js";
+
+/**
+ * Compose セッションの状態遷移。
+ *
+ * - `pending`     — 行作成済み、run 未開始。Created but never started.
+ * - `running`     — run 中。Streaming or in-flight.
+ * - `interrupted` — interrupt で停止中。resume 可。Paused at an interrupt; resumable.
+ * - `completed`   — 正常終了。Successfully finished.
+ * - `failed`      — 異常終了。Failed with an error.
+ * - `cancelled`   — ユーザーが DELETE で取り消した。User-cancelled.
+ */
+export type WikiComposeSessionStatus =
+  | "pending"
+  | "running"
+  | "interrupted"
+  | "completed"
+  | "failed"
+  | "cancelled";
+
+/**
+ * Compose セッションのメタテーブル。
+ * Wiki Compose session metadata table.
+ */
+export const wikiComposeSessions = pgTable(
+  "wiki_compose_sessions",
+  {
+    /**
+     * Session UUID。LangGraph `thread_id` としても再利用する。
+     * Session UUID; also used as the LangGraph `thread_id`.
+     */
+    id: uuid("id").primaryKey().defaultRandom(),
+    /**
+     * 対象ページ ID。
+     * Page id this session writes against.
+     */
+    pageId: uuid("page_id")
+      .notNull()
+      .references(() => pages.id, { onDelete: "cascade" }),
+    /**
+     * 実行ユーザー ID。
+     * Executing user id.
+     */
+    userId: text("user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    /**
+     * 登録済みグラフの論理 ID（registry key）。
+     * Registered graph logical id (registry key).
+     */
+    graphId: text("graph_id").notNull(),
+    /**
+     * 直近フェーズ。subgraph 横断の進捗を 1 カラムで表現する軽量フィールド。
+     * Last-known phase identifier (mirrors LangGraph state's `phase` field).
+     */
+    phase: text("phase").notNull().default("init"),
+    /**
+     * 実行 backend。`zedi_managed` または `user_*`（#951 BYOK）。セッション作成時に固定。
+     * Execution backend; `zedi_managed` or `user_*` BYOK backends (#951), fixed at create.
+     */
+    backend: text("backend").notNull().default("zedi_managed"),
+    /**
+     * セッション状態。`WikiComposeSessionStatus` を文字列で保持する。
+     * Status of the session as text (see {@link WikiComposeSessionStatus}).
+     */
+    status: text("status").$type<WikiComposeSessionStatus>().notNull().default("pending"),
+    /**
+     * クライアント由来のメタ情報（モデル ID、初期入力サマリ等）。
+     * Free-form metadata supplied by the client at creation time.
+     */
+    metadata: jsonb("metadata"),
+    /**
+     * 失敗時のエラーメッセージ。失敗状態以外では null。
+     * Last error message; only populated when `status = 'failed'`.
+     */
+    lastError: text("last_error"),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+    /**
+     * 完了時刻。`completed` / `failed` / `cancelled` 遷移時にセット。
+     * Closed-out timestamp; set when leaving an in-flight state.
+     */
+    closedAt: timestamp("closed_at", { withTimezone: true }),
+  },
+  (table) => [
+    /**
+     * `GET /api/pages/:pageId/compose-sessions/:id` の参照経路用インデックス。
+     * Lookup index for fetching a session belonging to a specific page.
+     */
+    index("idx_wiki_compose_sessions_page_id").on(table.pageId),
+    /**
+     * ユーザー単位の一覧用インデックス（管理画面・利用状況集計）。
+     * Per-user listing index for admin / usage dashboards.
+     */
+    index("idx_wiki_compose_sessions_user_id").on(table.userId),
+    /**
+     * "ページごとに新しい順" 列挙用部分複合インデックス。
+     * Partial composite index for "list sessions for a page newest-first".
+     * Restricting to non-terminal statuses keeps the index small for the
+     * common UI query of "what's currently active for this page?".
+     */
+    index("idx_wiki_compose_sessions_page_active_updated")
+      .on(table.pageId, table.updatedAt.desc())
+      .where(sql`${table.status} IN ('pending', 'running', 'interrupted')`),
+  ],
+);
+
+/** Select type. */
+export type WikiComposeSession = typeof wikiComposeSessions.$inferSelect;
+/** Insert type. */
+export type NewWikiComposeSession = typeof wikiComposeSessions.$inferInsert;
diff --git a/server/api/src/services/ingestPlanner.ts b/server/api/src/services/ingestPlanner.ts
index 24b6d3c7..e8f28d12 100644
--- a/server/api/src/services/ingestPlanner.ts
+++ b/server/api/src/services/ingestPlanner.ts
@@ -264,27 +264,19 @@ function parseConflicts(value: unknown): IngestConflict[] | undefined {
 }
 
 /**
- * LLM の生応答を厳格にパース・バリデーションして {@link IngestPlan} を返す。
- * Strictly validates an LLM raw response and returns a typed {@link IngestPlan}.
+ * Validates a parsed ingest plan object (structured LLM output or `JSON.parse` result).
+ * パース済み ingest プランオブジェクトを検証する（structured output または JSON.parse 結果）。
  *
- * @param raw - LLM の生テキスト応答。Raw LLM text response.
- * @param options - 候補ページ ID の集合（merge 時の整合性チェック用）。Set of candidate IDs.
- * @returns 検証済みプラン。Validated ingest plan.
- * @throws {@link IngestPlanParseError} when JSON is malformed or fields are invalid.
+ * @param parsed - Already-parsed plan object. / パース済みプランオブジェクト。
+ * @param options - Optional candidate id set for merge target validation.
+ *                  / merge 先検証用の候補 ID 集合（任意）。
+ * @throws {@link IngestPlanParseError} when fields are invalid.
+ *         / フィールドが不正な場合。
  */
-export function parseIngestPlanResponse(
-  raw: string,
+export function parseIngestPlanValue(
+  parsed: unknown,
   options: { validCandidateIds?: ReadonlySet<string> } = {},
 ): IngestPlan {
-  const jsonText = extractJsonFromResponse(raw);
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(jsonText);
-  } catch (err) {
-    const reason = err instanceof Error ? err.message : String(err);
-    throw new IngestPlanParseError(`Invalid JSON in LLM response: ${reason}`);
-  }
-
   if (!isRecord(parsed)) {
     throw new IngestPlanParseError("Plan must be a JSON object");
   }
@@ -332,6 +324,28 @@ export function parseIngestPlanResponse(
   return plan;
 }
 
+/**
+ * LLM の生応答を厳格にパース・バリデーションして {@link IngestPlan} を返す。
+ *
+ * @param raw - LLM の生テキスト応答。Raw LLM text response.
+ * @param options - 候補ページ ID の集合（merge 時の整合性チェック用）。Set of candidate IDs.
+ * @throws {@link IngestPlanParseError} when JSON is malformed or fields are invalid.
+ */
+export function parseIngestPlanResponse(
+  raw: string,
+  options: { validCandidateIds?: ReadonlySet<string> } = {},
+): IngestPlan {
+  const jsonText = extractJsonFromResponse(raw);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(jsonText);
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new IngestPlanParseError(`Invalid JSON in LLM response: ${reason}`);
+  }
+  return parseIngestPlanValue(parsed, options);
+}
+
 /**
  * LLM ドライバの型。provider / model / apiKey を束ねたコールバック。
  * LLM driver interface — a callback that wraps provider / model / apiKey.
diff --git a/server/api/src/services/userAiCredentialCrypto.ts b/server/api/src/services/userAiCredentialCrypto.ts
new file mode 100644
index 00000000..e2070760
--- /dev/null
+++ b/server/api/src/services/userAiCredentialCrypto.ts
@@ -0,0 +1,91 @@
+/**
+ * AES-256-GCM encryption for `user_ai_credentials.encrypted_api_key` (#951).
+ *
+ * `user_ai_credentials` 用の at-rest 暗号化。鍵管理方針:
+ *
+ * - **鍵の所在**: 本番・開発とも `USER_AI_CREDENTIALS_ENCRYPTION_KEY` 環境変数
+ *   のみ（32 バイト raw、Base64 または hex で指定）。DB・ログ・クライアントへ
+ *   鍵を書き込まない。
+ * - **ローテーション**: 新鍵を設定したうえで既存行を再保存（upsert）する運用。
+ *   旧鍵での復号に失敗した行は利用者がキーを再登録する。
+ * - **形式**: `base64(iv[12] || authTag[16] || ciphertext)` — クライアント
+ *   `src/lib/encryption.ts` とは別鍵・別用途（ブラウザ localStorage 用）。
+ *
+ * Key management:
+ * - **Source of truth**: env `USER_AI_CREDENTIALS_ENCRYPTION_KEY` only (32 raw
+ *   bytes as Base64 or hex). Never persist the key in DB, logs, or the client.
+ * - **Rotation**: set a new env key and re-upsert credentials; rows that fail
+ *   decrypt require the user to re-register.
+ * - **Wire format**: `base64(iv[12] || authTag[16] || ciphertext)` — distinct
+ *   from browser `src/lib/encryption.ts` (localStorage, per-device key).
+ */
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+
+const ALGORITHM = "aes-256-gcm";
+const IV_LENGTH = 12;
+const AUTH_TAG_LENGTH = 16;
+const KEY_LENGTH = 32;
+
+let cachedKey: Buffer | null = null;
+
+/**
+ * Load the 32-byte encryption key from the environment (memoized).
+ * 環境変数から 32 バイト鍵を読み込む（メモ化）。
+ */
+export function getUserAiCredentialEncryptionKey(): Buffer {
+  if (cachedKey) return cachedKey;
+  const raw = process.env.USER_AI_CREDENTIALS_ENCRYPTION_KEY?.trim();
+  if (!raw) {
+    throw new Error("USER_AI_CREDENTIALS_ENCRYPTION_KEY is not configured");
+  }
+  let key: Buffer;
+  if (/^[0-9a-fA-F]{64}$/.test(raw)) {
+    key = Buffer.from(raw, "hex");
+  } else {
+    key = Buffer.from(raw, "base64");
+  }
+  if (key.length !== KEY_LENGTH) {
+    throw new Error(
+      `USER_AI_CREDENTIALS_ENCRYPTION_KEY must decode to ${KEY_LENGTH} bytes (got ${key.length})`,
+    );
+  }
+  cachedKey = key;
+  return key;
+}
+
+/** Reset cached key (tests only). テスト用にキャッシュをクリア。 */
+export function resetUserAiCredentialEncryptionKeyCache(): void {
+  cachedKey = null;
+}
+
+/**
+ * Encrypt a plaintext API key for storage.
+ * 平文 API キーを DB 保存用に暗号化する。
+ */
+export function encryptUserAiCredential(plaintext: string): string {
+  const key = getUserAiCredentialEncryptionKey();
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+  const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+  const combined = Buffer.concat([iv, authTag, encrypted]);
+  return combined.toString("base64");
+}
+
+/**
+ * Decrypt a stored credential blob.
+ * 保存済み blob を復号する。
+ */
+export function decryptUserAiCredential(ciphertext: string): string {
+  const key = getUserAiCredentialEncryptionKey();
+  const combined = Buffer.from(ciphertext, "base64");
+  if (combined.length < IV_LENGTH + AUTH_TAG_LENGTH + 1) {
+    throw new Error("Invalid encrypted credential blob");
+  }
+  const iv = combined.subarray(0, IV_LENGTH);
+  const authTag = combined.subarray(IV_LENGTH, IV_LENGTH + AUTH_TAG_LENGTH);
+  const encrypted = combined.subarray(IV_LENGTH + AUTH_TAG_LENGTH);
+  const decipher = createDecipheriv(ALGORITHM, key, iv);
+  decipher.setAuthTag(authTag);
+  return Buffer.concat([decipher.update(encrypted), decipher.final()]).toString("utf8");
+}
diff --git a/server/api/src/services/userAiCredentialService.ts b/server/api/src/services/userAiCredentialService.ts
new file mode 100644
index 00000000..4fe9f646
--- /dev/null
+++ b/server/api/src/services/userAiCredentialService.ts
@@ -0,0 +1,133 @@
+/**
+ * CRUD for encrypted user AI credentials (#951).
+ * 暗号化されたユーザー AI 認証情報の CRUD。
+ */
+import { and, eq } from "drizzle-orm";
+import { userAiCredentials, type UserAiCredentialProvider } from "../schema/userAiCredentials.js";
+import type { Database } from "../types/index.js";
+import {
+  decryptUserAiCredential,
+  encryptUserAiCredential,
+  getUserAiCredentialEncryptionKey,
+} from "./userAiCredentialCrypto.js";
+
+/** Public availability shape (no secrets). 秘密情報を含まない利用可否。 */
+export interface UserAiCredentialAvailability {
+  provider: UserAiCredentialProvider;
+  configured: boolean;
+}
+
+const ALL_PROVIDERS: readonly UserAiCredentialProvider[] = ["anthropic", "openai", "google"];
+
+/**
+ * Whether server-side credential storage is configured (encryption key present).
+ * サーバー側 credential 保管が有効か（暗号化鍵が設定されているか）。
+ */
+export function isUserAiCredentialStorageEnabled(): boolean {
+  try {
+    getUserAiCredentialEncryptionKey();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * List which providers have a stored credential for the user.
+ * ユーザーが登録済みの provider 一覧（キー本体は返さない）。
+ */
+export async function listUserAiCredentialAvailability(
+  userId: string,
+  db: Database,
+): Promise<UserAiCredentialAvailability[]> {
+  if (!isUserAiCredentialStorageEnabled()) {
+    return ALL_PROVIDERS.map((provider) => ({ provider, configured: false }));
+  }
+  const rows = await db
+    .select({ provider: userAiCredentials.provider })
+    .from(userAiCredentials)
+    .where(eq(userAiCredentials.userId, userId));
+  const configured = new Set(rows.map((r) => r.provider));
+  return ALL_PROVIDERS.map((provider) => ({
+    provider,
+    configured: configured.has(provider),
+  }));
+}
+
+/**
+ * Upsert an encrypted API key for a provider.
+ * provider 向け API キーを暗号化して upsert する。
+ */
+export async function upsertUserAiCredential(
+  userId: string,
+  provider: UserAiCredentialProvider,
+  apiKey: string,
+  db: Database,
+): Promise<void> {
+  const trimmed = apiKey.trim();
+  if (!trimmed) {
+    throw new Error("API key is required");
+  }
+  const encryptedApiKey = encryptUserAiCredential(trimmed);
+  const id = `${userId}:${provider}`;
+  const now = new Date();
+  await db
+    .insert(userAiCredentials)
+    .values({
+      id,
+      userId,
+      provider,
+      encryptedApiKey,
+      createdAt: now,
+      updatedAt: now,
+    })
+    .onConflictDoUpdate({
+      target: [userAiCredentials.userId, userAiCredentials.provider],
+      set: {
+        encryptedApiKey,
+        updatedAt: now,
+      },
+    });
+}
+
+/**
+ * Remove a stored credential.
+ * 保存済み credential を削除する。
+ */
+export async function deleteUserAiCredential(
+  userId: string,
+  provider: UserAiCredentialProvider,
+  db: Database,
+): Promise<boolean> {
+  const result = await db
+    .delete(userAiCredentials)
+    .where(and(eq(userAiCredentials.userId, userId), eq(userAiCredentials.provider, provider)))
+    .returning({ id: userAiCredentials.id });
+  return result.length > 0;
+}
+
+/**
+ * Decrypt the stored API key for a provider (server-only).
+ * provider の API キーを復号する（サーバー内部専用）。
+ */
+export async function getUserAiCredentialPlaintext(
+  userId: string,
+  provider: UserAiCredentialProvider,
+  db: Database,
+): Promise<string | null> {
+  if (!isUserAiCredentialStorageEnabled()) return null;
+
+  const [row] = await db
+    .select()
+    .from(userAiCredentials)
+    .where(and(eq(userAiCredentials.userId, userId), eq(userAiCredentials.provider, provider)))
+    .limit(1);
+  if (!row) return null;
+  try {
+    return decryptUserAiCredential(row.encryptedApiKey);
+  } catch {
+    // Master key rotated or corrupted blob — treat as missing so callers return 400.
+    // マスター鍵ローテーション等で復号不能な行は未設定扱い。
+    return null;
+  }
+}
diff --git a/server/api/src/services/wikiSearchService.ts b/server/api/src/services/wikiSearchService.ts
new file mode 100644
index 00000000..0e1f16b7
--- /dev/null
+++ b/server/api/src/services/wikiSearchService.ts
@@ -0,0 +1,176 @@
+/**
+ * Wiki ページ ILIKE 検索サービス。
+ *
+ * `routes/search.ts` (`/api/search`) のページ検索ロジックを純粋関数として
+ * 切り出したもの。Hono コンテキストへの依存を消し、tool / subgraph から
+ * `db` / `userId` / `userEmail` を引数で受け取れるようにする。SQL は元 route
+ * と一致させ、CodeRabbit / codex の review 指摘 (PR #873) が指す
+ * - 「`content_text` を SELECT に晒さない」
+ * - 「呼び出し元 default note への絞り込み」
+ * - 「scope=shared での owner / accepted member / domain rule 結合」
+ * をすべて踏襲する。
+ *
+ * Pure service version of the page-search branch in `routes/search.ts`. The
+ * route remains the HTTP entry point, but tools (`wikiSearchTool` for the
+ * Wiki Compose research subgraph, #949) need to query the same data set
+ * without going through Hono context. The SQL itself is held identical to the
+ * route so the previously-reviewed safety properties (no full body in SELECT,
+ * domain-rule support, default-note scoping) carry over.
+ */
+import { sql } from "drizzle-orm";
+import type { Database } from "../types/index.js";
+import { extractEmailDomain } from "../lib/freeEmailDomains.js";
+import { getDefaultNoteOrNull } from "./defaultNoteService.js";
+
+/**
+ * 検索スコープ。`own` は呼び出し元のデフォルトノート配下のページのみ、
+ * `shared` はアクセス可能な全ノート横断（route のスコープ契約と同じ）。
+ *
+ * Scope contract mirrors `/api/search?scope=...`:
+ * - `own`: pages under the caller's default note only.
+ * - `shared`: pages across any note the caller can access (owner, accepted
+ *   member, or domain rule).
+ */
+export type WikiSearchScope = "own" | "shared";
+
+/**
+ * 1 件の検索ヒット。ページ ID + ノート ID + タイトル + 抜粋。
+ *
+ * One search hit. snake_case is intentional in {@link Source} but here we use
+ * camelCase to keep the service Pure-TS-shaped; the caller (tool / subgraph)
+ * remaps to whatever wire format it wants.
+ */
+export interface WikiSearchHit {
+  pageId: string;
+  noteId: string;
+  title: string | null;
+  contentPreview: string | null;
+  updatedAt: string;
+}
+
+/**
+ * 内部用: ILIKE 用に `%` `_` `\` をエスケープする。
+ *
+ * Escape SQL LIKE meta-characters so user input is treated as a literal.
+ */
+function escapeLike(input: string): string {
+  return input.replace(/\\/g, "\\\\").replace(/%/g, "\\%").replace(/_/g, "\\_");
+}
+
+/**
+ * ユーザーの Wiki ページを ILIKE で検索する。空クエリは空配列を返す。
+ *
+ * Search the user's wiki pages by ILIKE. Empty query returns an empty array.
+ * `limit` is clamped to 1..100 to match the route behaviour.
+ *
+ * @param db        Drizzle DB ハンドル。
+ * @param userId    実行ユーザー ID。
+ * @param userEmail 実行ユーザーのメール（`shared` スコープでドメインルール
+ *                  予測子に使う。null なら domain predicate を出さない）。
+ * @param query     検索クエリ。`%` / `_` は自動エスケープ。
+ * @param scope     "own" or "shared"（既定 "shared"）。
+ * @param limit     最大件数 (default 10, max 100)。
+ */
+export async function searchUserWikiPages(
+  db: Database,
+  userId: string,
+  userEmail: string | null,
+  query: string,
+  scope: WikiSearchScope = "shared",
+  limit = 10,
+): Promise<WikiSearchHit[]> {
+  const trimmed = query.trim();
+  if (!trimmed) return [];
+
+  const normalizedLimit = Number.isFinite(limit) ? Math.trunc(limit) : 10;
+  const safeLimit = Math.min(Math.max(normalizedLimit, 1), 100);
+  const pattern = `%${escapeLike(trimmed)}%`;
+
+  // `content_text` を WHERE には残しつつ SELECT に出さない方針は route と同じ
+  // (#873 review)。プレビューは `content_preview` カラムを返す。
+  const searchColumns = sql`p.id, p.title, p.content_preview, p.updated_at, p.note_id`;
+
+  if (scope === "own") {
+    const defaultNote = await getDefaultNoteOrNull(db, userId);
+    if (!defaultNote) return [];
+    const result = await db.execute(sql`
+      SELECT ${searchColumns}
+      FROM pages p
+      LEFT JOIN page_contents pc ON pc.page_id = p.id
+      WHERE p.is_deleted = false
+        AND p.note_id = ${defaultNote.id}
+        AND (
+          p.title ILIKE ${pattern}
+          OR pc.content_text ILIKE ${pattern}
+        )
+      ORDER BY p.updated_at DESC
+      LIMIT ${safeLimit}
+    `);
+    return result.rows.map(rowToHit);
+  }
+
+  const normalizedEmail = typeof userEmail === "string" ? userEmail.trim().toLowerCase() : "";
+  const emailDomain = extractEmailDomain(normalizedEmail);
+
+  const domainPredicate =
+    emailDomain !== null
+      ? sql`OR EXISTS (
+          SELECT 1
+          FROM notes n
+          INNER JOIN note_domain_access nda ON nda.note_id = n.id
+          WHERE n.id = p.note_id
+            AND n.is_deleted = false
+            AND nda.is_deleted = false
+            AND nda.domain = ${emailDomain}
+        )`
+      : sql``;
+
+  const result = await db.execute(sql`
+    SELECT ${searchColumns}
+    FROM pages p
+    LEFT JOIN page_contents pc ON pc.page_id = p.id
+    WHERE p.is_deleted = false
+      AND (
+        EXISTS (
+          SELECT 1 FROM notes n
+          WHERE n.id = p.note_id AND n.is_deleted = false AND n.owner_id = ${userId}
+        )
+        OR EXISTS (
+          SELECT 1
+          FROM notes n
+          INNER JOIN note_members nm ON nm.note_id = n.id
+          INNER JOIN "user" u ON LOWER(u.email) = LOWER(nm.member_email)
+          WHERE n.id = p.note_id
+            AND u.id = ${userId}
+            AND nm.status = 'accepted'
+            AND nm.is_deleted = false
+            AND n.is_deleted = false
+        )
+        ${domainPredicate}
+      )
+      AND (
+        p.title ILIKE ${pattern}
+        OR pc.content_text ILIKE ${pattern}
+      )
+      ORDER BY p.updated_at DESC
+      LIMIT ${safeLimit}
+  `);
+  return result.rows.map(rowToHit);
+}
+
+function rowToHit(row: unknown): WikiSearchHit {
+  const r = row as {
+    id: string;
+    note_id: string;
+    title: string | null;
+    content_preview: string | null;
+    updated_at: string | Date;
+  };
+  return {
+    pageId: r.id,
+    noteId: r.note_id,
+    title: r.title,
+    contentPreview: r.content_preview,
+    updatedAt: r.updated_at instanceof Date ? r.updated_at.toISOString() : String(r.updated_at),
+  };
+}
diff --git a/server/mcp/README.ja.md b/server/mcp/README.ja.md
new file mode 100644
index 00000000..dedea822
--- /dev/null
+++ b/server/mcp/README.ja.md
@@ -0,0 +1,293 @@
+> **言語:** [English](README.md) | 日本語
+
+# Zedi MCP Server
+
+Zedi の Model Context Protocol (MCP) サーバー。Claude Code などの外部 MCP クライアントから Zedi のページ / ノート / 検索 / クリップといったデータを操作できるツールを公開する。
+
+---
+
+## 概要
+
+- **stdio transport** (`zedi-mcp-stdio`): ローカルの Claude Code などに登録する用の stdio エントリポイント。環境変数または `~/.config/zedi/mcp.json` からトークンを読む。
+- **HTTP transport** (`zedi-mcp-http`): Railway などにデプロイして、リモートからも MCP 接続を受け付けるストリーマブル HTTP サーバー。`Authorization: Bearer <MCP JWT>` ヘッダでユーザを識別する。
+- **CLI** (`zedi-mcp-cli`): PKCE フローで MCP JWT を取得し、ユーザー設定ファイルに保存する補助 CLI。
+
+関連 PR / Issue: #554, #555, #556, #558.
+
+---
+
+## 前提条件
+
+- Zedi の API サーバー (`server/api`) が起動済みで到達できる URL を持っていること
+  - デフォルト: `https://api.zedi.app`
+  - ローカル開発では `http://localhost:3000` など
+- Zedi のユーザーアカウント（Better Auth でログイン済み）
+- Bun v1.3 以上（開発時） / Node.js v20 以上（stdio 実行時）
+
+---
+
+## インストール
+
+リポジトリ内で開発する場合:
+
+```bash
+cd server/mcp
+bun install
+bun run build   # dist/stdio.js, dist/http.js, dist/cli/login.js を生成
+```
+
+ワンショットで stdio や CLI を試したいだけなら、`bunx` で直接起動することもできる（未公開パッケージのため、現時点ではローカルビルドを前提）:
+
+```bash
+cd server/mcp && bun run build
+node dist/stdio.js          # stdio サーバー
+node dist/cli/login.js      # CLI (login / whoami)
+```
+
+---
+
+## 1. MCP トークンの発行
+
+MCP サーバーは Zedi API が発行する JWT（`scope`: `mcp:read` / `mcp:write`）を使って認可する。トークンを手に入れる方法は 2 通り。
+
+### 1a. 手動スクリプトで発行する（開発者向け）
+
+```bash
+cd server/api
+# スコープ指定なし = mcp:read + mcp:write
+bun run scripts/issue-mcp-token.ts <userId>
+
+# スコープを絞る
+bun run scripts/issue-mcp-token.ts <userId> mcp:read
+bun run scripts/issue-mcp-token.ts <userId> mcp:read,mcp:write
+```
+
+必要な環境変数（ルート `.env` から自動読込）:
+
+| 変数                 | 用途                        |
+| -------------------- | --------------------------- |
+| `BETTER_AUTH_SECRET` | JWT 署名鍵（必須）          |
+| `MCP_JWT_EXP_DAYS`   | 有効期限（日数、省略時 30） |
+
+出力は JSON で、`access_token` フィールドに JWT が入っている。手動スクリプトは CI 用・運用者用。開発者本人が普段使うなら下の PKCE ログインを推奨する。
+
+### 1b. PKCE フローでログインする（通常ユーザー向け）
+
+Zedi API に `/mcp/authorize` と `/api/mcp/session` が実装されている環境なら、付属 CLI を使って OAuth 的に JWT を取得できる。
+
+```bash
+cd server/mcp && bun run build
+
+# デフォルト (https://api.zedi.app) に対してログイン
+node dist/cli/login.js login
+
+# API URL を明示する場合
+node dist/cli/login.js login --api-url http://localhost:3000
+
+# ログイン済みトークンでプロフィールを確認
+node dist/cli/login.js whoami
+```
+
+CLI はブラウザを開いて `/mcp/authorize?...` に飛ばし、ユーザーが Zedi 側で承認するとローカルコールバックに `code` を受け取る。続けて `/api/mcp/session` に `code_verifier` とともに POST し、返ってきた `access_token` を以下に保存する:
+
+- macOS / Linux: `$XDG_CONFIG_HOME/zedi/mcp.json`（未設定時は `~/.config/zedi/mcp.json`）
+- Windows: `%APPDATA%\zedi\mcp.json`
+
+ファイルのパーミッションは `0600` で書き込まれる。
+
+---
+
+## 2. Claude Code に stdio サーバーを登録する
+
+Claude Code の設定ファイル（`~/.claude.json`）の `mcpServers` に以下のように追記する。
+
+### 2a. ログイン済み（config ファイル利用）パターン
+
+`zedi-mcp-cli login` を済ませていれば、stdio サーバーは自動的に `~/.config/zedi/mcp.json` から `apiUrl` と `token` を読むので、環境変数の設定は不要。
+
+```json
+{
+  "mcpServers": {
+    "zedi": {
+      "command": "node",
+      "args": ["/absolute/path/to/zedi/server/mcp/dist/stdio.js"]
+    }
+  }
+}
+```
+
+### 2b. 環境変数で渡すパターン（CI や複数アカウント切り替え向け）
+
+```json
+{
+  "mcpServers": {
+    "zedi": {
+      "command": "node",
+      "args": ["/absolute/path/to/zedi/server/mcp/dist/stdio.js"],
+      "env": {
+        "ZEDI_API_URL": "https://api.zedi.app",
+        "ZEDI_MCP_TOKEN": "<paste access_token here>"
+      }
+    }
+  }
+}
+```
+
+環境変数は config ファイルより優先される。どちらも未設定なら stdio サーバーはエラーを stderr に出して終了する。
+
+登録後、Claude Code を再起動すると `zedi_get_current_user` 等のツールが使えるようになる。確認方法:
+
+```
+> zedi_get_current_user を呼び出してみて
+```
+
+成功すれば JSON 形式のユーザー情報が返る。
+
+---
+
+## 3. HTTP サーバーを Railway にデプロイする
+
+リモートから Claude Code に MCP を接続したい場合は、`server/mcp` ディレクトリを Railway サービスとして切り出し、HTTP transport をデプロイする。
+
+### 3a. Railway 側の設定
+
+1. 新規サービスを作成し、**Root Directory** を `server/mcp` に設定する（付属 `railway.json` と `Dockerfile` が自動で使われる）。
+2. 環境変数:
+
+   | 変数           | 必須 | 用途                                                                                          |
+   | -------------- | ---- | --------------------------------------------------------------------------------------------- |
+   | `ZEDI_API_URL` | 推奨 | バックエンド REST API の URL。例: `http://api.railway.internal:3000` / `https://api.zedi.app` |
+   | `PORT`         | 任意 | 待ち受けポート（デフォルト `3100`、Railway は自動で注入）                                     |
+   | `MCP_HOST`     | 任意 | バインドホスト（デフォルト `0.0.0.0`）                                                        |
+
+3. **Healthcheck**: `railway.json` にて `/health` を 30 秒タイムアウトで監視する設定を同梱済み。
+4. **Start command**: `node dist/http.js`（Dockerfile の `CMD` と `railway.json` の `startCommand` で二重指定済み）。
+
+デプロイ後、クライアントからの接続先は `https://<railway-domain>/mcp` になる。ヘルスチェック用に `/health` も利用可。
+
+### 3b. クライアント側（HTTP transport 経由で使う場合）
+
+Claude Code の `mcpServers` では、HTTP transport 向け設定を使う。`Authorization` ヘッダに JWT を入れる点に注意。
+
+```json
+{
+  "mcpServers": {
+    "zedi-remote": {
+      "type": "http",
+      "url": "https://<railway-domain>/mcp",
+      "headers": {
+        "Authorization": "Bearer <paste access_token here>"
+      }
+    }
+  }
+}
+```
+
+サーバーはステートレス（リクエストごとに新しい `McpServer` を生成）なので、同じ JWT を複数クライアントから同時に使ってもセッションが競合しない。
+
+---
+
+## 4. 公開されているツール
+
+すべて Zedi API（`server/api`）を `HttpZediClient` 経由で呼び出す。入出力の厳密な型は `src/tools/index.ts` の Zod スキーマを参照（これが唯一の正 / source of truth）。
+
+### ユーザー
+
+| ツール名                | 概要                                                |
+| ----------------------- | --------------------------------------------------- |
+| `zedi_get_current_user` | 認証済みユーザーの `id` / `email` / `name` を返す。 |
+
+### ページ
+
+| ツール名           | 概要                                                                                           |
+| ------------------ | ---------------------------------------------------------------------------------------------- |
+| `zedi_get_page`    | 単一ページの本文（`content_text`）とメタデータを読み取り専用で取得。Y.Doc バイト列は含まない。 |
+| `zedi_create_page` | 新規ページを作成（Y.Doc は空）。                                                               |
+| `zedi_delete_page` | ページをソフトデリートする。                                                                   |
+
+> Issue #889 Phase 5 で MCP からはページ本文の更新ツール（`zedi_update_page_content`）のみが廃止されました。ノート作成・メンバー追加など他の書き込み系ツールは引き続き利用可能です。ページ本文の編集は Zedi クライアント（Hocuspocus 経由のリアルタイム編集）から行ってください。
+
+### ノート
+
+| ツール名           | 概要                                                               |
+| ------------------ | ------------------------------------------------------------------ |
+| `zedi_list_notes`  | 自分がオーナーまたはメンバーのノート一覧。                         |
+| `zedi_get_note`    | ノート詳細（ページ一覧・自分のロール含む）を返す。                 |
+| `zedi_create_note` | 新規ノートを作成（デフォルトは private + owner-only edit）。       |
+| `zedi_update_note` | ノートのメタデータ（title / visibility / edit_permission）を更新。 |
+| `zedi_delete_note` | ノートをソフトデリート。                                           |
+
+### ノート内ページ
+
+| ツール名                     | 概要                                                       |
+| ---------------------------- | ---------------------------------------------------------- |
+| `zedi_list_note_pages`       | ノート内ページを並び順で返す。                             |
+| `zedi_add_page_to_note`      | 既存ページをノートに追加、または新規ページを作成して追加。 |
+| `zedi_remove_page_from_note` | ノートからページをはずす（ページ自体は残る）。             |
+| `zedi_reorder_note_pages`    | ノート内ページの並びを `page_ids` で全指定して並べ替え。   |
+
+### ノートメンバー
+
+| ツール名                  | 概要                                               |
+| ------------------------- | -------------------------------------------------- |
+| `zedi_list_note_members`  | ノートメンバー一覧（ロール・承諾ステータス付き）。 |
+| `zedi_add_note_member`    | email でメンバーを招待。                           |
+| `zedi_update_note_member` | メンバーのロールを更新。                           |
+| `zedi_remove_note_member` | メンバーを削除。                                   |
+
+### 検索 / クリップ
+
+| ツール名        | 概要                                                                     |
+| --------------- | ------------------------------------------------------------------------ |
+| `zedi_search`   | タイトルと本文で全文検索。`scope: own` or `shared`、`limit` を指定可能。 |
+| `zedi_clip_url` | 公開 URL を Readability で整形し、新規ページとして保存。                 |
+
+計 20 ツール。ツール名の一覧は `src/tools/index.ts` の `ALL_TOOL_NAMES` にも定義済み。
+
+---
+
+## 5. トラブルシューティング
+
+### "No token configured" が stderr に出て stdio サーバーが終了する
+
+`ZEDI_MCP_TOKEN` 環境変数も `~/.config/zedi/mcp.json` もどちらも存在しない状態。`zedi-mcp-cli login` を実行するか、`~/.claude.json` の `env` にトークンを書く。
+
+### ツール呼び出しが 401 / 403 を返す
+
+- トークンの有効期限が切れている（`MCP_JWT_EXP_DAYS` 日で失効）。`zedi-mcp-cli login` でトークンを再発行する。
+- スコープが足りない。書き込み系ツール（`zedi_create_note`, `zedi_add_page_to_note` など）は `mcp:write` を要求する。`issue-mcp-token.ts` の第 2 引数に `mcp:read,mcp:write` を渡す、もしくは CLI ログイン時に既定の `mcp:read,mcp:write` で発行する。なお Issue #889 Phase 5 以降、ページ本文の更新ツールは MCP から削除されている。
+- `ZEDI_API_URL` の指す API サーバーと、トークンを発行した API サーバーが別物（署名鍵が違う）。同じ環境で発行したトークンを使うこと。
+
+### HTTP transport に接続できない / Claude Code から見えない
+
+- `curl https://<railway-domain>/health` が `{ "ok": true, ... }` を返すか確認。返らない場合はデプロイが立ち上がっていない。
+- Claude Code の設定で `type: "http"` と `Authorization` ヘッダが両方指定されているか確認。
+- Railway の内部通信を使うとき、`ZEDI_API_URL` は内部 URL（`http://api.railway.internal:3000` 等）を指す必要がある。外向き URL を設定すると自己呼び出しでループする可能性がある。
+
+### HTTPS でない stdio 出力でクライアントが壊れる
+
+stdio transport では JSON-RPC が stdout に流れるため、**ログは必ず stderr に出している**。独自パッチで stdout に `console.log` を追加しないこと。
+
+---
+
+## 6. 開発
+
+```bash
+cd server/mcp
+
+bun install
+bun run dev:stdio     # tsx watch src/stdio.ts
+bun run dev:http      # tsx watch src/http.ts
+bun run typecheck     # tsc --noEmit
+bun run test          # vitest run
+```
+
+テストは `src/__tests__/` 以下。ツール追加時は必ず Zod スキーマと Vitest のテストを合わせて追加すること（TDD / リポジトリ共通方針は [AGENTS.md](../../AGENTS.md) を参照）。
+
+---
+
+## Related
+
+- `server/api` — MCP JWT 発行・認可エンドポイント（`/mcp/authorize`, `/api/mcp/session`）を提供する。
+- `server/hocuspocus` — ページ本文（Y.Doc）のリアルタイム同期サーバー。
+- Issues: [#554](https://github.com/otomatty/zedi/issues/554), [#555](https://github.com/otomatty/zedi/issues/555), [#556](https://github.com/otomatty/zedi/issues/556), [#558](https://github.com/otomatty/zedi/issues/558).
diff --git a/server/mcp/README.md b/server/mcp/README.md
index 0b744755..da85a303 100644
--- a/server/mcp/README.md
+++ b/server/mcp/README.md
@@ -1,109 +1,109 @@
-# Zedi MCP Server
+> **Language:** English | [日本語](README.ja.md)
 
-Zedi の Model Context Protocol (MCP) サーバー。Claude Code などの外部 MCP クライアントから Zedi のページ / ノート / 検索 / クリップといったデータを操作できるツールを公開する。
+# Zedi MCP Server
 
-Model Context Protocol (MCP) server for Zedi. Exposes Zedi pages, notes, search, and clipping as MCP tools so that external clients (e.g. Claude Code) can read and write your Zedi workspace.
+Model Context Protocol (MCP) server for Zedi. Exposes MCP tools so external clients (e.g. Claude Code) can read and write pages, notes, search, and clips in your Zedi workspace.
 
 ---
 
-## 概要 / Overview
+## Overview
 
-- **stdio transport** (`zedi-mcp-stdio`): ローカルの Claude Code などに登録する用の stdio エントリポイント。環境変数または `~/.config/zedi/mcp.json` からトークンを読む。
-- **HTTP transport** (`zedi-mcp-http`): Railway などにデプロイして、リモートからも MCP 接続を受け付けるストリーマブル HTTP サーバー。`Authorization: Bearer <MCP JWT>` ヘッダでユーザを識別する。
-- **CLI** (`zedi-mcp-cli`): PKCE フローで MCP JWT を取得し、ユーザー設定ファイルに保存する補助 CLI。
+- **stdio transport** (`zedi-mcp-stdio`): stdio entry point for local Claude Code registration. Reads tokens from environment variables or `~/.config/zedi/mcp.json`.
+- **HTTP transport** (`zedi-mcp-http`): Streamable HTTP server for Railway deployment. Identifies users via `Authorization: Bearer <MCP JWT>`.
+- **CLI** (`zedi-mcp-cli`): Helper CLI that obtains an MCP JWT via PKCE and saves it to the user config file.
 
 Related PRs / issues: #554, #555, #556, #558.
 
 ---
 
-## 前提条件 / Prerequisites
+## Prerequisites
 
-- Zedi の API サーバー (`server/api`) が起動済みで到達できる URL を持っていること
-  - デフォルト: `https://api.zedi.app`
-  - ローカル開発では `http://localhost:3000` など
-- Zedi のユーザーアカウント (Cognito 経由でログイン済み)
-- Bun v1.3 以上 (開発時) / Node.js v20 以上 (stdio 実行時)
+- Zedi API server (`server/api`) running and reachable
+  - Default: `https://api.zedi.app`
+  - Local dev: `http://localhost:3000`, etc.
+- Zedi user account (logged in via Better Auth)
+- Bun v1.3+ (development) / Node.js v20+ (stdio runtime)
 
 ---
 
-## インストール / Install
+## Install
 
-リポジトリ内で開発する場合:
+When developing in the repository:
 
 ```bash
 cd server/mcp
 bun install
-bun run build   # dist/stdio.js, dist/http.js, dist/cli/login.js を生成
+bun run build   # Generates dist/stdio.js, dist/http.js, dist/cli/login.js
 ```
 
-ワンショットで stdio や CLI を試したいだけなら、`bunx` で直接起動することもできる (未公開パッケージのため、現時点ではローカルビルドを前提):
+To try stdio or CLI in one shot (local build required; package not published yet):
 
 ```bash
 cd server/mcp && bun run build
-node dist/stdio.js          # stdio サーバー
+node dist/stdio.js          # stdio server
 node dist/cli/login.js      # CLI (login / whoami)
 ```
 
 ---
 
-## 1. MCP トークンの発行 / Issuing an MCP token
+## 1. Issuing an MCP token
 
-MCP サーバーは Zedi API が発行する JWT (`scope`: `mcp:read` / `mcp:write`) を使って認可する。トークンを手に入れる方法は 2 通り。
+The MCP server authorizes with JWTs issued by the Zedi API (`scope`: `mcp:read` / `mcp:write`). Two ways to obtain a token:
 
-### 1a. 手動スクリプトで発行する (開発者向け)
+### 1a. Manual script (developers / operators)
 
 ```bash
 cd server/api
-# スコープ指定なし = mcp:read + mcp:write
+# No scope argument = mcp:read + mcp:write
 bun run scripts/issue-mcp-token.ts <userId>
 
-# スコープを絞る
+# Restrict scopes
 bun run scripts/issue-mcp-token.ts <userId> mcp:read
 bun run scripts/issue-mcp-token.ts <userId> mcp:read,mcp:write
 ```
 
-必要な環境変数 (ルート `.env` から自動読込):
+Required environment variables (auto-loaded from root `.env`):
 
-| 変数                 | 用途                       |
-| -------------------- | -------------------------- |
-| `BETTER_AUTH_SECRET` | JWT 署名鍵 (必須)          |
-| `MCP_JWT_EXP_DAYS`   | 有効期限 (日数、省略時 30) |
+| Variable             | Purpose                                |
+| -------------------- | -------------------------------------- |
+| `BETTER_AUTH_SECRET` | JWT signing key (required)             |
+| `MCP_JWT_EXP_DAYS`   | Expiry in days (default 30 if omitted) |
 
-出力は JSON で、`access_token` フィールドに JWT が入っている。手動スクリプトは CI 用・運用者用。開発者本人が普段使うなら下の PKCE ログインを推奨する。
+Output is JSON with the JWT in `access_token`. The manual script is for CI and operators. For day-to-day use, prefer PKCE login below.
 
-### 1b. PKCE フローでログインする (通常ユーザー向け)
+### 1b. PKCE login (regular users)
 
-Zedi API に `/mcp/authorize` と `/api/mcp/session` が実装されている環境なら、付属 CLI を使って OAuth 的に JWT を取得できる。
+When `/mcp/authorize` and `/api/mcp/session` are available on the API, use the bundled CLI:
 
 ```bash
 cd server/mcp && bun run build
 
-# デフォルト (https://api.zedi.app) に対してログイン
+# Login against default (https://api.zedi.app)
 node dist/cli/login.js login
 
-# API URL を明示する場合
+# Explicit API URL
 node dist/cli/login.js login --api-url http://localhost:3000
 
-# ログイン済みトークンでプロフィールを確認
+# Verify saved token
 node dist/cli/login.js whoami
 ```
 
-CLI はブラウザを開いて `/mcp/authorize?...` に飛ばし、ユーザーが Zedi 側で承認するとローカルコールバックに `code` を受け取る。続けて `/api/mcp/session` に `code_verifier` とともに POST し、返ってきた `access_token` を以下に保存する:
+The CLI opens a browser to `/mcp/authorize?...`. After approval, it receives `code` on a local callback, POSTs to `/api/mcp/session` with `code_verifier`, and saves `access_token` to:
 
-- macOS / Linux: `$XDG_CONFIG_HOME/zedi/mcp.json` (未設定時は `~/.config/zedi/mcp.json`)
+- macOS / Linux: `$XDG_CONFIG_HOME/zedi/mcp.json` (default `~/.config/zedi/mcp.json`)
 - Windows: `%APPDATA%\zedi\mcp.json`
 
-ファイルのパーミッションは `0600` で書き込まれる。
+File permissions are written as `0600`.
 
 ---
 
-## 2. Claude Code に stdio サーバーを登録する / Register the stdio server in Claude Code
+## 2. Register the stdio server in Claude Code
 
-Claude Code の設定ファイル (`~/.claude.json`) の `mcpServers` に以下のように追記する。
+Add to `mcpServers` in Claude Code config (`~/.claude.json`):
 
-### 2a. ログイン済み (config ファイル利用) パターン
+### 2a. Logged in (config file)
 
-`zedi-mcp-cli login` を済ませていれば、stdio サーバーは自動的に `~/.config/zedi/mcp.json` から `apiUrl` と `token` を読むので、環境変数の設定は不要。
+After `zedi-mcp-cli login`, stdio reads `apiUrl` and `token` from `~/.config/zedi/mcp.json` — no env vars needed.
 
 ```json
 {
@@ -116,7 +116,7 @@ Claude Code の設定ファイル (`~/.claude.json`) の `mcpServers` に以下
 }
 ```
 
-### 2b. 環境変数で渡すパターン (CI や複数アカウント切り替え向け)
+### 2b. Environment variables (CI / multiple accounts)
 
 ```json
 {
@@ -133,39 +133,41 @@ Claude Code の設定ファイル (`~/.claude.json`) の `mcpServers` に以下
 }
 ```
 
-環境変数は config ファイルより優先される。どちらも未設定なら stdio サーバーはエラーを stderr に出して終了する。
+Environment variables override the config file. If neither is set, stdio exits with an error on stderr.
 
-登録後、Claude Code を再起動すると `zedi_get_current_user` 等のツールが使えるようになる。確認方法:
+After registration, restart Claude Code. Tools such as `zedi_get_current_user` should appear. Verify:
 
 ```
-> zedi_get_current_user を呼び出してみて
+> Call zedi_get_current_user
 ```
 
-成功すれば JSON 形式のユーザー情報が返る。
+Success returns user info as JSON.
 
 ---
 
-## 3. HTTP サーバーを Railway にデプロイする / Deploy HTTP transport on Railway
+## 3. Deploy HTTP transport on Railway
+
+For remote MCP access, deploy `server/mcp` as a Railway service with HTTP transport.
+
+### 3a. Railway configuration
 
-リモートから Claude Code に MCP を接続したい場合は、`server/mcp` ディレクトリを Railway サービスとして切り出し、HTTP transport をデプロイする。
+1. Create a service with **Root Directory** `server/mcp` (uses bundled `railway.json` and `Dockerfile`).
+2. Environment variables:
 
-### 3a. Railway 側の設定
+   | Variable       | Required    | Purpose                                                                                 |
+   | -------------- | ----------- | --------------------------------------------------------------------------------------- |
+   | `ZEDI_API_URL` | Recommended | Backend REST API URL, e.g. `http://api.railway.internal:3000` or `https://api.zedi.app` |
+   | `PORT`         | Optional    | Listen port (default `3100`; Railway injects automatically)                             |
+   | `MCP_HOST`     | Optional    | Bind host (default `0.0.0.0`)                                                           |
 
-1. 新規サービスを作成し、**Root Directory** を `server/mcp` に設定する (付属 `railway.json` と `Dockerfile` が自動で使われる)。
-2. 環境変数:
-   | 変数 | 必須 | 用途 |
-   | ---- | ---- | ---- |
-   | `ZEDI_API_URL` | 推奨 | バックエンド REST API の URL。例: `http://api.railway.internal:3000` (内部通信) / `https://api.zedi.app` (公開) |
-   | `PORT` | 任意 | 待ち受けポート (デフォルト `3100`、Railway は自動で注入) |
-   | `MCP_HOST` | 任意 | バインドホスト (デフォルト `0.0.0.0`) |
-3. **Healthcheck**: `railway.json` にて `/health` を 30 秒タイムアウトで監視する設定を同梱済み。
-4. **Start command**: `node dist/http.js` (Dockerfile の `CMD` と `railway.json` の `startCommand` で二重指定済み)。
+3. **Healthcheck**: `railway.json` monitors `/health` with 30s timeout.
+4. **Start command**: `node dist/http.js` (set in Dockerfile `CMD` and `railway.json`).
 
-デプロイ後、クライアントからの接続先は `https://<railway-domain>/mcp` になる。ヘルスチェック用に `/health` も利用可。
+Client endpoint: `https://<railway-domain>/mcp`. Health: `/health`.
 
-### 3b. クライアント側 (HTTP transport 経由で使う場合)
+### 3b. Client (HTTP transport)
 
-Claude Code の `mcpServers` では、HTTP transport 向け設定を使う。`Authorization` ヘッダに JWT を入れる点に注意。
+Use HTTP transport settings in Claude Code `mcpServers`. Set `Authorization` header with JWT:
 
 ```json
 {
@@ -181,96 +183,94 @@ Claude Code の `mcpServers` では、HTTP transport 向け設定を使う。`Au
 }
 ```
 
-サーバーはステートレス (リクエストごとに新しい `McpServer` を生成) なので、同じ JWT を複数クライアントから同時に使ってもセッションが競合しない。
+The server is stateless (new `McpServer` per request), so the same JWT can be used from multiple clients without session conflicts.
 
 ---
 
-## 4. 公開されているツール / Available tools
+## 4. Available tools
 
-すべて Zedi API (`server/api`) を `HttpZediClient` 経由で呼び出す。入出力の厳密な型は `src/tools/index.ts` の Zod スキーマを参照 (これが唯一の正 / source of truth)。
+All tools call the Zedi API (`server/api`) via `HttpZediClient`. Exact input/output types are in Zod schemas in `src/tools/index.ts` (source of truth).
 
-### ユーザー
+### User
 
-| ツール名                | 概要                                                |
+| Tool                    | Summary                                             |
 | ----------------------- | --------------------------------------------------- |
-| `zedi_get_current_user` | 認証済みユーザーの `id` / `email` / `name` を返す。 |
+| `zedi_get_current_user` | Returns authenticated user `id` / `email` / `name`. |
 
-### ページ
+### Pages
 
-| ツール名           | 概要                                                                                           |
-| ------------------ | ---------------------------------------------------------------------------------------------- |
-| `zedi_get_page`    | 単一ページの本文 (`content_text`) とメタデータを読み取り専用で取得。Y.Doc バイト列は含まない。 |
-| `zedi_create_page` | 新規ページを作成 (Y.Doc は空)。                                                                |
-| `zedi_delete_page` | ページをソフトデリートする。                                                                   |
+| Tool               | Summary                                                                          |
+| ------------------ | -------------------------------------------------------------------------------- |
+| `zedi_get_page`    | Read-only page body (`content_text`) and metadata. Does not include Y.Doc bytes. |
+| `zedi_create_page` | Create a new page (empty Y.Doc).                                                 |
+| `zedi_delete_page` | Soft-delete a page.                                                              |
 
-> Issue #889 Phase 5 で MCP からはページ本文の更新ツール (`zedi_update_page_content`) のみが廃止されました。ノート作成・メンバー追加など他の書き込み系ツールは引き続き利用可能です。ページ本文の編集は Zedi クライアント (Hocuspocus 経由のリアルタイム編集) から行ってください。
->
-> _Issue #889 Phase 5 retired only the page-body update tool (`zedi_update_page_content`) from the MCP surface. Other mutating tools (note creation, membership, etc.) remain available. To edit a page body, use the Zedi web/desktop client which writes through Hocuspocus._
+> Issue #889 Phase 5 removed only the page-body update tool (`zedi_update_page_content`) from MCP. Other write tools (note creation, membership, etc.) remain. Edit page bodies via the Zedi client (Hocuspocus real-time editing).
 
-### ノート
+### Notes
 
-| ツール名           | 概要                                                               |
-| ------------------ | ------------------------------------------------------------------ |
-| `zedi_list_notes`  | 自分がオーナーまたはメンバーのノート一覧。                         |
-| `zedi_get_note`    | ノート詳細 (ページ一覧・自分のロール含む) を返す。                 |
-| `zedi_create_note` | 新規ノートを作成 (デフォルトは private + owner-only edit)。        |
-| `zedi_update_note` | ノートのメタデータ (title / visibility / edit_permission) を更新。 |
-| `zedi_delete_note` | ノートをソフトデリート。                                           |
+| Tool               | Summary                                                      |
+| ------------------ | ------------------------------------------------------------ |
+| `zedi_list_notes`  | Notes where you are owner or member.                         |
+| `zedi_get_note`    | Note details including pages and your role.                  |
+| `zedi_create_note` | Create a note (default private + owner-only edit).           |
+| `zedi_update_note` | Update note metadata (title / visibility / edit_permission). |
+| `zedi_delete_note` | Soft-delete a note.                                          |
 
-### ノート内ページ
+### Note pages
 
-| ツール名                     | 概要                                                       |
-| ---------------------------- | ---------------------------------------------------------- |
-| `zedi_list_note_pages`       | ノート内ページを並び順で返す。                             |
-| `zedi_add_page_to_note`      | 既存ページをノートに追加、または新規ページを作成して追加。 |
-| `zedi_remove_page_from_note` | ノートからページをはずす (ページ自体は残る)。              |
-| `zedi_reorder_note_pages`    | ノート内ページの並びを `page_ids` で全指定して並べ替え。   |
+| Tool                         | Summary                               |
+| ---------------------------- | ------------------------------------- |
+| `zedi_list_note_pages`       | Pages in a note in order.             |
+| `zedi_add_page_to_note`      | Add existing page or create and add.  |
+| `zedi_remove_page_from_note` | Remove page from note (page remains). |
+| `zedi_reorder_note_pages`    | Reorder with full `page_ids` list.    |
 
-### ノートメンバー
+### Note members
 
-| ツール名                  | 概要                                              |
-| ------------------------- | ------------------------------------------------- |
-| `zedi_list_note_members`  | ノートメンバー一覧 (ロール・承諾ステータス付き)。 |
-| `zedi_add_note_member`    | email でメンバーを招待。                          |
-| `zedi_update_note_member` | メンバーのロールを更新。                          |
-| `zedi_remove_note_member` | メンバーを削除。                                  |
+| Tool                      | Summary                                  |
+| ------------------------- | ---------------------------------------- |
+| `zedi_list_note_members`  | Members with role and acceptance status. |
+| `zedi_add_note_member`    | Invite member by email.                  |
+| `zedi_update_note_member` | Update member role.                      |
+| `zedi_remove_note_member` | Remove member.                           |
 
-### 検索 / クリップ
+### Search / clip
 
-| ツール名        | 概要                                                                     |
-| --------------- | ------------------------------------------------------------------------ |
-| `zedi_search`   | タイトルと本文で全文検索。`scope: own` or `shared`、`limit` を指定可能。 |
-| `zedi_clip_url` | 公開 URL を Readability で整形し、新規ページとして保存。                 |
+| Tool            | Summary                                                                |
+| --------------- | ---------------------------------------------------------------------- |
+| `zedi_search`   | Full-text search on title and body. `scope: own` or `shared`, `limit`. |
+| `zedi_clip_url` | Fetch public URL via Readability and save as new page.                 |
 
-計 20 ツール。ツール名の一覧は `src/tools/index.ts` の `ALL_TOOL_NAMES` にも定義済み。
+20 tools total. See `ALL_TOOL_NAMES` in `src/tools/index.ts`.
 
 ---
 
-## 5. トラブルシューティング / Troubleshooting
+## 5. Troubleshooting
 
-### "No token configured" が stderr に出て stdio サーバーが終了する
+### "No token configured" on stderr and stdio exits
 
-`ZEDI_MCP_TOKEN` 環境変数も `~/.config/zedi/mcp.json` もどちらも存在しない状態。`zedi-mcp-cli login` を実行するか、`~/.claude.json` の `env` にトークンを書く。
+Neither `ZEDI_MCP_TOKEN` nor `~/.config/zedi/mcp.json` is set. Run `zedi-mcp-cli login` or set token in `~/.claude.json` `env`.
 
-### ツール呼び出しが 401 / 403 を返す
+### Tool calls return 401 / 403
 
-- トークンの有効期限が切れている (`MCP_JWT_EXP_DAYS` 日で失効)。`zedi-mcp-cli login` でトークンを再発行する。
-- スコープが足りない。書き込み系ツール (`zedi_create_note`, `zedi_add_page_to_note` など) は `mcp:write` を要求する。`issue-mcp-token.ts` の第 2 引数に `mcp:read,mcp:write` を渡す、もしくは CLI ログイン時に既定の `mcp:read,mcp:write` で発行する。なお Issue #889 Phase 5 以降、ページ本文の更新ツールは MCP から削除されている。
-- `ZEDI_API_URL` の指す API サーバーと、トークンを発行した API サーバーが別物 (署名鍵が違う)。同じ環境で発行したトークンを使うこと。
+- Token expired (`MCP_JWT_EXP_DAYS`). Re-run `zedi-mcp-cli login`.
+- Insufficient scope. Write tools require `mcp:write`. Issue `mcp:read,mcp:write` via `issue-mcp-token.ts` or CLI login defaults.
+- `ZEDI_API_URL` points to a different API than the one that issued the token (signing key mismatch).
 
-### HTTP transport に接続できない / Claude Code から見えない
+### Cannot connect to HTTP transport
 
-- `curl https://<railway-domain>/health` が `{ "ok": true, ... }` を返すか確認。返らない場合はデプロイが立ち上がっていない。
-- Claude Code の設定で `type: "http"` と `Authorization` ヘッダが両方指定されているか確認。
-- Railway の内部通信を使うとき、`ZEDI_API_URL` は内部 URL (`http://api.railway.internal:3000` 等) を指す必要がある。外向き URL を設定すると自己呼び出しでループする可能性がある。
+- Verify `curl https://<railway-domain>/health` returns `{ "ok": true, ... }`.
+- Confirm Claude Code config has `type: "http"` and `Authorization` header.
+- For Railway internal API, set `ZEDI_API_URL` to internal URL (e.g. `http://api.railway.internal:3000`).
 
-### HTTPS でない stdio 出力でクライアントが壊れる
+### Do not log to stdout on stdio
 
-stdio transport では JSON-RPC が stdout に流れるため、**ログは必ず stderr に出している**。独自パッチで stdout に `console.log` を追加しないこと。
+JSON-RPC uses stdout. Logs go to stderr only. Do not add `console.log` to stdout in patches.
 
 ---
 
-## 6. 開発 / Development
+## 6. Development
 
 ```bash
 cd server/mcp
@@ -282,12 +282,12 @@ bun run typecheck     # tsc --noEmit
 bun run test          # vitest run
 ```
 
-テストは `src/__tests__/` 以下。ツール追加時は必ず Zod スキーマと Vitest のテストを合わせて追加すること (TDD / リポジトリ共通方針は [AGENTS.md](../../AGENTS.md) を参照)。
+Tests live under `src/__tests__/`. When adding tools, add Zod schemas and Vitest tests (TDD — see [AGENTS.md](../../AGENTS.md)).
 
 ---
 
 ## Related
 
-- `server/api` — MCP JWT 発行・認可エンドポイント (`/mcp/authorize`, `/api/mcp/session`) を提供する。
-- `server/hocuspocus` — ページ本文 (Y.Doc) のリアルタイム同期サーバー。
-- Issues: [#554](https://github.com/otomatty/zedi/issues/554), [#555](https://github.com/otomatty/zedi/issues/555), [#556](https://github.com/otomatty/zedi/issues/556), [#558](https://github.com/otomatty/zedi/issues/558).
+- `server/api` — MCP JWT issuance and auth endpoints (`/mcp/authorize`, `/api/mcp/session`)
+- `server/hocuspocus` — Real-time Y.Doc sync for page bodies
+- Issues: [#554](https://github.com/otomatty/zedi/issues/554), [#555](https://github.com/otomatty/zedi/issues/555), [#556](https://github.com/otomatty/zedi/issues/556), [#558](https://github.com/otomatty/zedi/issues/558)
diff --git a/src/App.tsx b/src/App.tsx
index 82cacb58..85a55049 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -32,6 +32,7 @@ import SearchResults from "./pages/SearchResults";
 import NotFound from "./pages/NotFound";
 import NoteView from "./pages/NoteView";
 import NotePageView from "./pages/NotePageView";
+import WikiComposePage from "./pages/WikiComposePage";
 import NoteSettings from "./pages/NoteSettings";
 import GeneralSection from "./pages/NoteSettings/sections/GeneralSection";
 import VisibilitySection from "./pages/NoteSettings/sections/VisibilitySection";
@@ -290,6 +291,13 @@ const App = () => (
                       </Route>
                       <Route path="/notes/:noteId/members" element={<LegacyMembersRedirect />} />
                       <Route path="/notes/:noteId/:pageId" element={<NotePageView />} />
+                      {/* Wiki Compose split-screen UI (issue #950).
+                          Optional `:sessionId` keeps one route element so URL
+                          persistence does not remount and abort the first SSE run. */}
+                      <Route
+                        path="/notes/:noteId/:pageId/compose/:sessionId?"
+                        element={<WikiComposePage />}
+                      />
                       {/* Legacy path — redirect `/notes/:noteId/pages/:pageId` to
                           the shorter `/notes/:noteId/:pageId`.
                           旧パス `/notes/:noteId/pages/:pageId` を短縮形にリダイレクト。 */}
diff --git a/src/components/ai-chat/AIChatWikiLink.tsx b/src/components/ai-chat/AIChatWikiLink.tsx
index 47736784..df417f85 100644
--- a/src/components/ai-chat/AIChatWikiLink.tsx
+++ b/src/components/ai-chat/AIChatWikiLink.tsx
@@ -92,7 +92,31 @@ export function AIChatWikiLink({ title }: AIChatWikiLinkProps) {
         e.preventDefault();
         return;
       }
-      navigateWikiLinkByTitle(normalizedTitle);
+      // Issue #931: Cmd/Ctrl+クリックは新タブ意図として渡す。`<button>` は
+      // ネイティブリンクではないので、修飾キーの判定はここで行う。
+      // Issue #931: forward Cmd/Ctrl+click as a new-tab intent. The ghost
+      // trigger is a `<button>` rather than an anchor, so the browser does
+      // not honor modifier keys for us — we detect them explicitly.
+      const newTab = e.metaKey || e.ctrlKey;
+      navigateWikiLinkByTitle(normalizedTitle, { newTab });
+    },
+    [normalizedTitle, navigateWikiLinkByTitle],
+  );
+
+  // Issue #931: 中クリック（button === 1）も新タブ扱い。`<button>` 要素は
+  // 中クリックで `click` イベントを発火しないため `onAuxClick` で受ける。
+  // Issue #931: middle-click on the ghost trigger should also open in a new
+  // tab. `<button>` does not fire `click` for the middle button, so we hook
+  // `onAuxClick`.
+  const handleGhostTriggerAuxClick = useCallback(
+    (e: React.MouseEvent) => {
+      if (e.button !== 1) return;
+      if (preventClickRef.current) {
+        e.preventDefault();
+        return;
+      }
+      e.preventDefault();
+      navigateWikiLinkByTitle(normalizedTitle, { newTab: true });
     },
     [normalizedTitle, navigateWikiLinkByTitle],
   );
@@ -159,6 +183,7 @@ export function AIChatWikiLink({ title }: AIChatWikiLinkProps) {
             type="button"
             className="text-muted-foreground decoration-muted-foreground/60 inline cursor-pointer rounded border-0 bg-transparent px-0.5 font-medium underline decoration-dashed underline-offset-2"
             onClick={handleGhostTriggerClick}
+            onAuxClick={handleGhostTriggerAuxClick}
             {...touchProps}
           >
             [[{normalizedTitle}]]
diff --git a/src/components/ai-chat/PromoteToWikiDialog.tsx b/src/components/ai-chat/PromoteToWikiDialog.tsx
index 25b59dc8..5923edff 100644
--- a/src/components/ai-chat/PromoteToWikiDialog.tsx
+++ b/src/components/ai-chat/PromoteToWikiDialog.tsx
@@ -22,7 +22,7 @@ import { callAIService } from "@/lib/aiService";
 import { loadAISettings } from "@/lib/aiSettings";
 import { useCreatePage } from "@/hooks/usePageQueries";
 import { useWikiSchema } from "@/hooks/useWikiSchema";
-import type { PendingChatPageGenerationState } from "@/types/chatPageGeneration";
+import { navigateToWikiCompose } from "@/lib/wikiCompose/navigation";
 import { EntityRow } from "./EntityRow";
 
 /**
@@ -258,19 +258,18 @@ function PromoteToWikiDialogBody({
       if (!firstCreated) throw new Error("no pages created");
 
       const firstEntity = selectedEntities[created.indexOf(firstCreated)];
-      const pending: PendingChatPageGenerationState = {
-        outline: `- ${firstEntity.summary}`,
-        conversationText,
-        userSchema: schemaData?.content,
-        conversationId,
-      };
       toast({ title: t("aiChat.notifications.promoteSuccess") });
       onClose();
-      // Issue #889 Phase 3: `/pages/:id` 撤去のため `/notes/:noteId/:pageId` に遷移。
-      // Issue #889 Phase 3: route to `/notes/:noteId/:pageId` after `/pages/:id`
-      // was retired.
-      navigate(`/notes/${firstCreated.noteId}/${firstCreated.id}`, {
-        state: { pendingChatPageGeneration: pending },
+      navigateToWikiCompose({
+        navigate,
+        noteId: firstCreated.noteId,
+        pageId: firstCreated.id,
+        seed: {
+          outline: `- ${firstEntity.summary}`,
+          conversationText,
+          userSchema: schemaData?.content,
+          conversationId,
+        },
       });
     } catch {
       toast({ title: t("aiChat.notifications.promoteFailed"), variant: "destructive" });
diff --git a/src/components/editor/FloatingWikiLinkInputBar.test.tsx b/src/components/editor/FloatingWikiLinkInputBar.test.tsx
new file mode 100644
index 00000000..9abad436
--- /dev/null
+++ b/src/components/editor/FloatingWikiLinkInputBar.test.tsx
@@ -0,0 +1,222 @@
+import React from "react";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { act, render, screen, fireEvent } from "@testing-library/react";
+
+// react-i18next を素通りモック（他テストと同じパターン）。
+// Mirror the lightweight i18n stub used elsewhere in this file's siblings.
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock("@/hooks/useWikiLinkCandidates", () => ({
+  useWikiLinkCandidates: () => ({ pages: [], isLoading: false }),
+}));
+
+vi.mock("@/hooks/usePageQueries", () => ({
+  useWikiLinkExistsChecker: () => ({
+    checkExistence: vi.fn().mockResolvedValue({
+      pageTitles: new Set(),
+      referencedTitles: new Set(),
+      pageTitleToId: new Map(),
+    }),
+  }),
+  useCheckGhostLinkReferenced: () => ({ checkReferenced: vi.fn().mockResolvedValue(false) }),
+}));
+
+vi.mock("@zedi/ui", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@zedi/ui")>();
+  return {
+    ...actual,
+    useIsMobile: vi.fn(() => true),
+  };
+});
+
+import type { Editor } from "@tiptap/core";
+import { useIsMobile } from "@zedi/ui";
+import { FloatingWikiLinkInputBar } from "./FloatingWikiLinkInputBar";
+import { PageActionHubFab } from "./PageActionHub/PageActionHubFab";
+
+/**
+ * 最小限のエディタモック。`WikiLinkInputBar` が `disabled={!editor}` で
+ * 入力欄を無効化するため、focus 動作を確かめるには truthy なエディタ
+ * オブジェクトが必要。
+ *
+ * Minimal editor mock — the bar disables its input when `editor` is null,
+ * so we need *some* truthy editor to test focus behavior.
+ */
+function createDummyEditor(): Editor {
+  return {
+    state: { selection: { from: 0, to: 0 } },
+    chain: () => ({
+      focus: () => ({
+        insertContentAt: () => ({
+          setTextSelection: () => ({ run: vi.fn() }),
+          run: vi.fn(),
+        }),
+        run: vi.fn(),
+      }),
+    }),
+    commands: { focus: vi.fn() },
+  } as unknown as Editor;
+}
+
+interface MockVisualViewport {
+  height: number;
+  offsetTop: number;
+  addEventListener: (type: string, cb: EventListener) => void;
+  removeEventListener: (type: string, cb: EventListener) => void;
+  dispatchEvent: ReturnType<typeof vi.fn>;
+}
+
+function installMockVisualViewport(): {
+  setMetrics: (next: { height: number; offsetTop?: number }) => void;
+  fire: (type: string) => void;
+  restore: () => void;
+} {
+  const listeners = new Map<string, Set<EventListener>>();
+  const vv: MockVisualViewport = {
+    height: 800,
+    offsetTop: 0,
+    addEventListener: (type, cb) => {
+      let set = listeners.get(type);
+      if (!set) {
+        set = new Set();
+        listeners.set(type, set);
+      }
+      set.add(cb);
+    },
+    removeEventListener: (type, cb) => {
+      listeners.get(type)?.delete(cb);
+    },
+    dispatchEvent: vi.fn(),
+  };
+  const original = Object.getOwnPropertyDescriptor(window, "visualViewport");
+  Object.defineProperty(window, "visualViewport", { configurable: true, value: vv });
+  const originalInnerHeight = window.innerHeight;
+  Object.defineProperty(window, "innerHeight", { configurable: true, value: 800 });
+  return {
+    setMetrics: ({ height, offsetTop = 0 }) => {
+      vv.height = height;
+      vv.offsetTop = offsetTop;
+    },
+    fire: (type) => {
+      const set = listeners.get(type);
+      if (!set) return;
+      for (const cb of set) cb(new Event(type));
+    },
+    restore: () => {
+      if (original) {
+        Object.defineProperty(window, "visualViewport", original);
+      } else {
+        delete (window as unknown as { visualViewport?: unknown }).visualViewport;
+      }
+      Object.defineProperty(window, "innerHeight", {
+        configurable: true,
+        value: originalInnerHeight,
+      });
+    },
+  };
+}
+
+describe("FloatingWikiLinkInputBar - visualViewport 追従 / virtual keyboard tracking", () => {
+  let env: ReturnType<typeof installMockVisualViewport>;
+
+  beforeEach(() => {
+    env = installMockVisualViewport();
+    vi.mocked(useIsMobile).mockReturnValue(true);
+  });
+
+  afterEach(() => {
+    env.restore();
+  });
+
+  it("初期状態ではキーボードオフセットを適用せず通常配置 / does not apply a keyboard offset before focus", () => {
+    render(<FloatingWikiLinkInputBar editor={createDummyEditor()} pageId="p1" pageNoteId={null} />);
+    const wrapper = screen.getByTestId("floating-wiki-link-input-bar");
+    expect(wrapper.style.bottom).toBe("");
+  });
+
+  it("入力欄フォーカス時にキーボード高さ分だけ bottom をオフセットする / lifts the bar by the keyboard height once the input is focused", () => {
+    env.setMetrics({ height: 460 });
+    render(<FloatingWikiLinkInputBar editor={createDummyEditor()} pageId="p1" pageNoteId={null} />);
+    const wrapper = screen.getByTestId("floating-wiki-link-input-bar");
+    const input = screen.getByTestId("wiki-link-input-bar-input");
+
+    act(() => {
+      input.focus();
+    });
+
+    // window.innerHeight 800 − vv.height 460 − offsetTop 0 = 340px
+    expect(wrapper.style.bottom).toBe("340px");
+  });
+
+  it("キーボード高さ変化（resize）に追従する / follows visualViewport resize while focused", () => {
+    render(<FloatingWikiLinkInputBar editor={createDummyEditor()} pageId="p1" pageNoteId={null} />);
+    const wrapper = screen.getByTestId("floating-wiki-link-input-bar");
+    const input = screen.getByTestId("wiki-link-input-bar-input");
+
+    act(() => {
+      input.focus();
+    });
+    expect(wrapper.style.bottom).toBe("");
+
+    act(() => {
+      env.setMetrics({ height: 500 });
+      env.fire("resize");
+    });
+    expect(wrapper.style.bottom).toBe("300px");
+
+    // 横向き等でさらに変わるケース。
+    // Orientation change / keyboard variant swap — value updates again.
+    act(() => {
+      env.setMetrics({ height: 600 });
+      env.fire("resize");
+    });
+    expect(wrapper.style.bottom).toBe("200px");
+  });
+
+  it("blur 後もキーボードが残る間はオフセットを維持し、閉じたら戻る / keeps the offset until the keyboard closes, not on input blur", () => {
+    env.setMetrics({ height: 500 });
+    render(<FloatingWikiLinkInputBar editor={createDummyEditor()} pageId="p1" pageNoteId={null} />);
+    const wrapper = screen.getByTestId("floating-wiki-link-input-bar");
+    const input = screen.getByTestId("wiki-link-input-bar-input");
+
+    act(() => {
+      input.focus();
+    });
+    expect(wrapper.style.bottom).toBe("300px");
+
+    act(() => {
+      fireEvent.blur(input, { relatedTarget: null });
+    });
+    expect(wrapper.style.bottom).toBe("300px");
+
+    act(() => {
+      env.setMetrics({ height: 800 });
+      env.fire("resize");
+    });
+    expect(wrapper.style.bottom).toBe("");
+  });
+
+  it("デスクトップで FAB クリックしてもキーボード追従を開始しない / does not start keyboard tracking when the FAB is clicked on desktop", async () => {
+    vi.mocked(useIsMobile).mockReturnValue(false);
+    env.setMetrics({ height: 460 });
+
+    render(
+      <FloatingWikiLinkInputBar
+        editor={createDummyEditor()}
+        pageId="p1"
+        pageNoteId={null}
+        trailingAction={<PageActionHubFab canEdit isSignedIn onOpen={vi.fn()} />}
+      />,
+    );
+
+    const wrapper = screen.getByTestId("floating-wiki-link-input-bar");
+    expect(wrapper.style.bottom).toBe("");
+
+    await act(async () => {
+      screen.getByTestId("page-action-hub-fab").click();
+    });
+    expect(wrapper.style.bottom).toBe("");
+  });
+});
diff --git a/src/components/editor/FloatingWikiLinkInputBar.tsx b/src/components/editor/FloatingWikiLinkInputBar.tsx
new file mode 100644
index 00000000..68bdabf3
--- /dev/null
+++ b/src/components/editor/FloatingWikiLinkInputBar.tsx
@@ -0,0 +1,85 @@
+import React from "react";
+import { cn, useIsMobile } from "@zedi/ui";
+import Container from "@/components/layout/Container";
+import { useVirtualKeyboardOffset } from "@/hooks/useVirtualKeyboardOffset";
+import { WikiLinkInputBar, type WikiLinkInputBarProps } from "./WikiLinkInputBar";
+
+/** 画面下部固定バーの下余白（モバイルのボトムナビ・safe-area 込み）。 / Bottom inset for the fixed bar on mobile. */
+export const FLOATING_WIKI_LINK_BAR_PADDING_BOTTOM =
+  "calc(env(safe-area-inset-bottom) + var(--app-bottom-nav-height, 0px) + 0.5rem)";
+
+/** デスクトップ向けの下余白。画面下端から少し浮かせる。 / Desktop bottom inset — lifts the bar above the viewport edge. */
+export const FLOATING_WIKI_LINK_BAR_PADDING_BOTTOM_DESKTOP =
+  "calc(env(safe-area-inset-bottom) + 1.5rem)";
+
+export interface FloatingWikiLinkInputBarProps extends WikiLinkInputBarProps {
+  /** 入力バー右隣に並べるアクション（例: PageActionHub FAB）。 / Trailing control beside the input bar. */
+  trailingAction?: React.ReactNode;
+}
+
+/**
+ * `WikiLinkInputBar` を `Container` 幅で画面下部に固定配置するラッパー。
+ * エディター本文と同じ max-width / 横 padding に揃え、入力バーは FAB 以外の
+ * 残り幅を自動的に埋める。`TiptapEditor` から呼び出してエディタ画面でのみ
+ * マウントする（読み取り専用画面・公開閲覧では呼び出さない）。
+ *
+ * モバイル向けには `visualViewport` API を常時監視し、仮想キーボードが
+ * 表示されている間だけ bottom インセットを動的に上乗せして、入力バーと
+ * 候補リストが常にキーボード上に見える状態を保つ（issue #927）。FAB クリック
+ * 時に input の blur で一瞬下端へ戻る問題を避けるため、追従条件を input
+ * focus ではなく viewport 上のキーボード有無に合わせる。デスクトップでは
+ * 追従しない。
+ *
+ * Fixed-position wrapper that mounts {@link WikiLinkInputBar} at the bottom
+ * inside {@link Container}, matching the editor column width. The input grows
+ * to fill the row while the trailing action keeps its fixed size. `TiptapEditor`
+ * decides when to mount the wrapper so the bar appears only on the editor
+ * screen (read-only / public views skip it).
+ *
+ * For mobile (issue #927), the wrapper always tracks `visualViewport` and
+ * adds the keyboard-covered area as a `bottom` offset while the on-screen
+ * keyboard is visible. Tracking is keyed off the viewport inset — not input
+ * focus — so tapping the adjacent FAB does not briefly snap the bar back to
+ * the resting position before the keyboard finishes closing. Desktop skips
+ * keyboard tracking entirely.
+ */
+export const FloatingWikiLinkInputBar: React.FC<FloatingWikiLinkInputBarProps> = ({
+  trailingAction,
+  ...props
+}) => {
+  const isMobile = useIsMobile();
+  const keyboardOffset = useVirtualKeyboardOffset(isMobile);
+
+  // キーボードが出ているときは下部ナビ・safe-area の余白は無効化する
+  // （キーボードに既に隠れているため）。0.5rem だけ視覚的なすき間を確保。
+  // When the keyboard is up the bottom-nav and safe-area paddings are
+  // hidden behind the keyboard anyway, so collapse them to a single 0.5rem
+  // gap to keep the bar visually pinned to the keyboard top edge.
+  const isKeyboardOpen = isMobile && keyboardOffset > 0;
+  const bottomStyle = isKeyboardOpen ? `${keyboardOffset}px` : undefined;
+
+  return (
+    <div
+      data-testid="floating-wiki-link-input-bar"
+      className={cn(
+        "pointer-events-none fixed right-0 bottom-0 left-0 z-40",
+        !isKeyboardOpen && "pb-[var(--floating-bar-pb)] md:pb-[var(--floating-bar-pb-md)]",
+      )}
+      style={
+        {
+          bottom: bottomStyle,
+          "--floating-bar-pb": FLOATING_WIKI_LINK_BAR_PADDING_BOTTOM,
+          "--floating-bar-pb-md": FLOATING_WIKI_LINK_BAR_PADDING_BOTTOM_DESKTOP,
+          ...(isKeyboardOpen ? { paddingBottom: "0.5rem" } : {}),
+        } as React.CSSProperties
+      }
+    >
+      <Container className="pointer-events-auto flex items-end gap-2">
+        <WikiLinkInputBar {...props} fillWidth className="min-w-0 flex-1" />
+        {trailingAction}
+      </Container>
+    </div>
+  );
+};
+
+export default FloatingWikiLinkInputBar;
diff --git a/src/components/editor/PageActionHub/PageActionHub.test.tsx b/src/components/editor/PageActionHub/PageActionHub.test.tsx
new file mode 100644
index 00000000..a3b70418
--- /dev/null
+++ b/src/components/editor/PageActionHub/PageActionHub.test.tsx
@@ -0,0 +1,182 @@
+import React, { useRef, useEffect } from "react";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { useIsMobile } from "@zedi/ui";
+import { PageActionHub } from "./PageActionHub";
+import type { PageActionContext, PageActionHubHandle } from "./types";
+
+vi.mock("@zedi/ui", async () => {
+  const actual = await vi.importActual<typeof import("@zedi/ui")>("@zedi/ui");
+  return {
+    ...actual,
+    useIsMobile: vi.fn(() => false),
+  };
+});
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => {
+      const map: Record<string, string> = {
+        "editor.pageActionHub.title": "Page actions",
+        "editor.pageActionHub.back": "Back",
+        "editor.pageActionHub.close": "Close",
+        "editor.pageActionHub.emptyState": "No actions available",
+        "editor.pageActionHub.actions.thumbnailSearch.label": "Search image",
+        "editor.pageActionHub.actions.thumbnailSearch.description": "Search and insert",
+        "editor.pageActionHub.actions.thumbnailSearch.loading": "Searching images...",
+        "editor.pageActionHub.actions.thumbnailSearch.empty": "No candidates found",
+        "editor.pageActionHub.actions.thumbnailSearch.next": "Next",
+        "editor.pageActionHub.actions.thumbnailSearch.retry": "Retry",
+        "editor.pageActionHub.actions.thumbnailGenerate.label": "Generate with AI",
+        "editor.pageActionHub.actions.thumbnailGenerate.description": "Generate and insert",
+        "editor.pageActionHub.actions.thumbnailGenerate.loading": "Generating image...",
+        "editor.pageActionHub.actions.thumbnailGenerate.retry": "Regenerate",
+        "editor.pageActionHub.actions.thumbnailGenerate.missingTitle": "Please enter a title",
+        "editor.pageActionHub.actions.wikiCompose.label": "Wiki Compose",
+        "editor.pageActionHub.actions.wikiCompose.description": "Co-author with AI",
+        "editor.pageActionHub.actions.wikiCompose.start": "Open Wiki Compose",
+        "editor.pageActionHub.actions.wikiCompose.unavailable": "Unavailable",
+      };
+      return map[key] ?? key;
+    },
+    i18n: { language: "en" },
+  }),
+}));
+
+const makeCtx = (overrides: Partial<PageActionContext> = {}): PageActionContext => ({
+  pageTitle: "Test Page",
+  isReadOnly: false,
+  isSignedIn: true,
+  hasThumbnail: false,
+  insertThumbnail: vi.fn(),
+  ...overrides,
+});
+
+/**
+ * テストハーネス: `hubRef` を生やしてレンダー直後に `open()` できるようにする。
+ * Test harness: assigns hubRef and exposes `open()` for tests via a button.
+ */
+const Harness: React.FC<{
+  ctx: PageActionContext;
+  onMount?: (handle: PageActionHubHandle) => void;
+}> = ({ ctx, onMount }) => {
+  const ref = useRef<PageActionHubHandle | null>(null);
+  useEffect(() => {
+    if (ref.current && onMount) onMount(ref.current);
+  }, [onMount]);
+  return (
+    <>
+      <button type="button" data-testid="open-trigger" onClick={() => ref.current?.open()}>
+        open
+      </button>
+      <PageActionHub ctx={ctx} hubRef={ref} />
+    </>
+  );
+};
+
+describe("PageActionHub", () => {
+  beforeEach(() => {
+    vi.mocked(useIsMobile).mockReturnValue(false);
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({ items: [], nextCursor: null }),
+      }),
+    );
+  });
+
+  it("初期は閉じており Dialog 要素は描画されない / closed initially renders no dialog", () => {
+    render(<Harness ctx={makeCtx()} />);
+    expect(screen.queryByRole("dialog")).not.toBeInTheDocument();
+  });
+
+  it("デスクトップでは Dialog として開く / opens as Dialog on desktop", async () => {
+    vi.mocked(useIsMobile).mockReturnValue(false);
+    const user = userEvent.setup();
+    render(<Harness ctx={makeCtx()} />);
+
+    await user.click(screen.getByTestId("open-trigger"));
+
+    expect(await screen.findByRole("dialog")).toBeInTheDocument();
+    expect(screen.getByText("Page actions")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /Search image/ })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /Generate with AI/ })).toBeInTheDocument();
+  });
+
+  it("モバイルでは Drawer として開く / opens as Drawer on mobile", async () => {
+    vi.mocked(useIsMobile).mockReturnValue(true);
+    const user = userEvent.setup();
+    render(<Harness ctx={makeCtx()} />);
+
+    await user.click(screen.getByTestId("open-trigger"));
+
+    // Drawer (vaul) ロールも dialog なので、ハブ専用のラッパーを data-testid で識別する
+    // Drawer (vaul) also uses role="dialog"; identify via our wrapper testid.
+    expect(await screen.findByTestId("page-action-hub-drawer")).toBeInTheDocument();
+    expect(screen.getByText("Page actions")).toBeInTheDocument();
+  });
+
+  it("カードクリックで詳細ビューに遷移する / clicking a card navigates to detail", async () => {
+    const user = userEvent.setup();
+    render(<Harness ctx={makeCtx()} />);
+
+    await user.click(screen.getByTestId("open-trigger"));
+    await user.click(screen.getByRole("button", { name: /Search image/ }));
+
+    // 詳細ビューでは一覧の他カードが消える
+    // The list cards disappear when the detail view is active.
+    expect(screen.queryByRole("button", { name: /Generate with AI/ })).not.toBeInTheDocument();
+    // 戻るボタンが出る
+    // Back button appears.
+    expect(screen.getByRole("button", { name: "Back" })).toBeInTheDocument();
+  });
+
+  it("Back で list に戻る / Back button returns to list", async () => {
+    const user = userEvent.setup();
+    render(<Harness ctx={makeCtx()} />);
+
+    await user.click(screen.getByTestId("open-trigger"));
+    await user.click(screen.getByRole("button", { name: /Search image/ }));
+    await user.click(screen.getByRole("button", { name: "Back" }));
+
+    expect(screen.getByRole("button", { name: /Generate with AI/ })).toBeInTheDocument();
+  });
+
+  it("空ガード: 利用不可コンテキストでは emptyState を表示 / empty state when no actions available", async () => {
+    const user = userEvent.setup();
+    render(<Harness ctx={makeCtx({ hasThumbnail: true })} />);
+
+    await user.click(screen.getByTestId("open-trigger"));
+
+    expect(await screen.findByText("No actions available")).toBeInTheDocument();
+  });
+
+  it("ハンドルの close() で閉じ、再オープン時は list / close() then reopen lands on list", async () => {
+    let handle: PageActionHubHandle | null = null;
+    const onMount = (h: PageActionHubHandle) => {
+      handle = h;
+    };
+    const user = userEvent.setup();
+    render(<Harness ctx={makeCtx()} onMount={onMount} />);
+
+    await user.click(screen.getByTestId("open-trigger"));
+    await user.click(screen.getByRole("button", { name: /Search image/ }));
+
+    await waitFor(() => expect(handle).not.toBeNull());
+
+    // close() を呼ぶ
+    // Call close() through the imperative handle.
+    handle?.close();
+
+    await waitFor(() => {
+      expect(screen.queryByRole("dialog")).not.toBeInTheDocument();
+    });
+
+    // 再オープン → list に戻っているはず
+    // Reopen and confirm the list view is shown (not the previous detail view).
+    await user.click(screen.getByTestId("open-trigger"));
+    expect(await screen.findByRole("button", { name: /Generate with AI/ })).toBeInTheDocument();
+  });
+});
diff --git a/src/components/editor/PageActionHub/PageActionHub.tsx b/src/components/editor/PageActionHub/PageActionHub.tsx
new file mode 100644
index 00000000..e6558c40
--- /dev/null
+++ b/src/components/editor/PageActionHub/PageActionHub.tsx
@@ -0,0 +1,111 @@
+import React, { useEffect, useMemo } from "react";
+import type { MutableRefObject } from "react";
+import { useTranslation } from "react-i18next";
+import { ChevronLeft } from "lucide-react";
+import {
+  Button,
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  Drawer,
+  DrawerContent,
+  DrawerHeader,
+  DrawerTitle,
+  useIsMobile,
+} from "@zedi/ui";
+import { PageActionList } from "./PageActionList";
+import { usePageActionHub } from "./usePageActionHub";
+import { getAvailablePageActions, getPageActionById } from "./registry";
+import type { PageActionContext, PageActionHubHandle } from "./types";
+
+/**
+ * `PageActionHub` のレンダリングに必要な props。
+ * Render-time props for `PageActionHub`.
+ */
+export interface PageActionHubProps {
+  ctx: PageActionContext;
+  /**
+   * 親 (FAB) からハブを開閉するための ref。`insertAtCursorRef` と同様、
+   * マウント後に `useEffect` で `ref.current` に handle を代入する。
+   *
+   * Imperative handle so the FAB can open/close the hub. Mirrors the
+   * `insertAtCursorRef` pattern of assigning into `ref.current` on mount.
+   */
+  hubRef?: MutableRefObject<PageActionHubHandle | null>;
+}
+
+/**
+ * ページ編集画面用のアクションハブ。デスクトップでは Dialog、モバイルでは
+ * Drawer に切り替えてアクション一覧 (list) と詳細 (detail) の二階建てを表示する。
+ *
+ * Page-edit action hub. Renders as a Dialog on desktop and a Drawer on
+ * mobile, with a two-step navigation (list → detail) inside.
+ */
+export const PageActionHub: React.FC<PageActionHubProps> = ({ ctx, hubRef }) => {
+  const { t } = useTranslation();
+  const isMobile = useIsMobile();
+  const { isOpen, view, open, close, selectAction, backToList, handleOpenChange } =
+    usePageActionHub();
+
+  const availableActions = useMemo(() => getAvailablePageActions(ctx), [ctx]);
+
+  // 親からハブを命令的に開閉できるよう ref に handle を代入する。
+  // Expose imperative open/close to the parent through the ref.
+  useEffect(() => {
+    if (!hubRef) return;
+    hubRef.current = { open, close };
+    return () => {
+      hubRef.current = null;
+    };
+  }, [hubRef, open, close]);
+
+  const detailAction = view.kind === "detail" ? getPageActionById(view.actionId) : undefined;
+  const headerLabel =
+    view.kind === "detail" && detailAction
+      ? t(detailAction.labelI18nKey)
+      : t("editor.pageActionHub.title");
+
+  const body =
+    view.kind === "detail" && detailAction ? (
+      <detailAction.Component ctx={ctx} onClose={close} onBackToList={backToList} />
+    ) : (
+      <PageActionList ctx={ctx} actions={availableActions} onSelect={selectAction} />
+    );
+
+  const header =
+    view.kind === "detail" ? (
+      <div className="flex items-center gap-2">
+        <Button type="button" size="sm" variant="ghost" className="-ml-2" onClick={backToList}>
+          <ChevronLeft className="mr-1 h-4 w-4" />
+          {t("editor.pageActionHub.back")}
+        </Button>
+      </div>
+    ) : null;
+
+  if (isMobile) {
+    return (
+      <Drawer open={isOpen} onOpenChange={handleOpenChange}>
+        <DrawerContent data-testid="page-action-hub-drawer">
+          <DrawerHeader>
+            <DrawerTitle>{headerLabel}</DrawerTitle>
+            {header}
+          </DrawerHeader>
+          <div className="px-4 pb-6">{body}</div>
+        </DrawerContent>
+      </Drawer>
+    );
+  }
+
+  return (
+    <Dialog open={isOpen} onOpenChange={handleOpenChange}>
+      <DialogContent className="sm:max-w-lg" data-testid="page-action-hub-dialog">
+        <DialogHeader>
+          <DialogTitle>{headerLabel}</DialogTitle>
+          {header}
+        </DialogHeader>
+        <div>{body}</div>
+      </DialogContent>
+    </Dialog>
+  );
+};
diff --git a/src/components/editor/PageActionHub/PageActionHubFab.test.tsx b/src/components/editor/PageActionHub/PageActionHubFab.test.tsx
new file mode 100644
index 00000000..533ebb4b
--- /dev/null
+++ b/src/components/editor/PageActionHub/PageActionHubFab.test.tsx
@@ -0,0 +1,43 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { PageActionHubFab } from "./PageActionHubFab";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => {
+      const map: Record<string, string> = {
+        "editor.pageActionHub.openAriaLabel": "Open page actions",
+      };
+      return map[key] ?? key;
+    },
+    i18n: { language: "en" },
+  }),
+}));
+
+describe("PageActionHubFab", () => {
+  it("canEdit かつ isSignedIn のときボタンを描画 / renders the button when allowed", () => {
+    render(<PageActionHubFab canEdit isSignedIn onOpen={vi.fn()} />);
+    expect(screen.getByTestId("page-action-hub-fab")).toBeInTheDocument();
+    expect(screen.getByLabelText("Open page actions")).toBeInTheDocument();
+  });
+
+  it("canEdit=false では null を返す / returns null when not editable", () => {
+    const { container } = render(<PageActionHubFab canEdit={false} isSignedIn onOpen={vi.fn()} />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("isSignedIn=false では null を返す / returns null when signed out", () => {
+    const { container } = render(<PageActionHubFab canEdit isSignedIn={false} onOpen={vi.fn()} />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("クリックで onOpen を呼ぶ / clicking calls onOpen", async () => {
+    const user = userEvent.setup();
+    const onOpen = vi.fn();
+    render(<PageActionHubFab canEdit isSignedIn onOpen={onOpen} />);
+
+    await user.click(screen.getByTestId("page-action-hub-fab"));
+    expect(onOpen).toHaveBeenCalled();
+  });
+});
diff --git a/src/components/editor/PageActionHub/PageActionHubFab.tsx b/src/components/editor/PageActionHub/PageActionHubFab.tsx
new file mode 100644
index 00000000..1d5c60ee
--- /dev/null
+++ b/src/components/editor/PageActionHub/PageActionHubFab.tsx
@@ -0,0 +1,61 @@
+import React from "react";
+import { Menu } from "lucide-react";
+import { useTranslation } from "react-i18next";
+import { Button, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, cn } from "@zedi/ui";
+
+/** 入力バーと FAB の高さを揃えるための共有値。 / Shared height aligned with the Wiki Link input bar. */
+export const PAGE_ACTION_HUB_FAB_SIZE_CLASS = "h-12 w-12";
+
+interface PageActionHubFabProps {
+  /** クリック時に `PageActionHub.open()` を叩くためのハンドラ。 / Opens the hub. */
+  onOpen: () => void;
+  /** 編集権限がなければ FAB 自体を出さない。 / Hides the FAB when the page is read-only. */
+  canEdit: boolean;
+  /** 未サインインでは出さない。 / Hides the FAB when signed out. */
+  isSignedIn: boolean;
+}
+
+/**
+ * ノートページ編集画面専用の単一ボタン FAB。クリックで `PageActionHub` を開く。
+ * 既存 `FloatingActionButton`（ノート一覧でメニュー型として使用）とは独立した
+ * コンポーネントで、Phase 1 では新規ページ作成や WebClipper の起動は担わない。
+ *
+ * Single-button FAB used on the note page editor screen. Clicking it opens
+ * the `PageActionHub`. Independent from the existing menu-style
+ * `FloatingActionButton` used on the note-list screen.
+ */
+export const PageActionHubFab: React.FC<PageActionHubFabProps> = ({
+  onOpen,
+  canEdit,
+  isSignedIn,
+}) => {
+  const { t } = useTranslation();
+  if (!canEdit || !isSignedIn) return null;
+
+  return (
+    <TooltipProvider delayDuration={300}>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button
+            data-testid="page-action-hub-fab"
+            aria-label={t("editor.pageActionHub.openAriaLabel")}
+            onClick={onOpen}
+            variant="ghost"
+            className={cn(
+              "pointer-events-auto shrink-0 rounded-full p-0",
+              PAGE_ACTION_HUB_FAB_SIZE_CLASS,
+              "bg-secondary/80 text-secondary-foreground shadow-lg backdrop-blur-sm",
+              "border border-transparent",
+              "transition-colors duration-150",
+              "hover:bg-secondary hover:text-secondary-foreground",
+              "[&_svg]:size-5",
+            )}
+          >
+            <Menu />
+          </Button>
+        </TooltipTrigger>
+        <TooltipContent side="top">{t("editor.pageActionHub.openAriaLabel")}</TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  );
+};
diff --git a/src/components/editor/PageActionHub/PageActionList.test.tsx b/src/components/editor/PageActionHub/PageActionList.test.tsx
new file mode 100644
index 00000000..453253de
--- /dev/null
+++ b/src/components/editor/PageActionHub/PageActionList.test.tsx
@@ -0,0 +1,77 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { Image as ImageIcon, Wand2 } from "lucide-react";
+import { PageActionList } from "./PageActionList";
+import type { PageAction, PageActionContext } from "./types";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => {
+      const map: Record<string, string> = {
+        "editor.pageActionHub.emptyState": "No actions available",
+        "editor.pageActionHub.actions.thumbnailSearch.label": "Search image",
+        "editor.pageActionHub.actions.thumbnailSearch.description": "Search and insert",
+        "editor.pageActionHub.actions.thumbnailGenerate.label": "Generate with AI",
+        "editor.pageActionHub.actions.thumbnailGenerate.description": "Generate and insert",
+      };
+      return map[key] ?? key;
+    },
+    i18n: { language: "en" },
+  }),
+}));
+
+const ctx: PageActionContext = {
+  pageTitle: "Test Page",
+  isReadOnly: false,
+  isSignedIn: true,
+  hasThumbnail: false,
+  insertThumbnail: vi.fn(),
+};
+
+const StubComponent: React.FC = () => null;
+
+const actions: PageAction[] = [
+  {
+    id: "thumbnail.search",
+    labelI18nKey: "editor.pageActionHub.actions.thumbnailSearch.label",
+    descriptionI18nKey: "editor.pageActionHub.actions.thumbnailSearch.description",
+    icon: ImageIcon,
+    category: "thumbnail",
+    insertStrategy: "head",
+    isAvailable: () => true,
+    Component: StubComponent,
+  },
+  {
+    id: "thumbnail.generate",
+    labelI18nKey: "editor.pageActionHub.actions.thumbnailGenerate.label",
+    descriptionI18nKey: "editor.pageActionHub.actions.thumbnailGenerate.description",
+    icon: Wand2,
+    category: "thumbnail",
+    insertStrategy: "head",
+    isAvailable: () => true,
+    Component: StubComponent,
+  },
+];
+
+describe("PageActionList", () => {
+  it("利用可能なアクションをカード表示する / renders one button per action", () => {
+    render(<PageActionList ctx={ctx} actions={actions} onSelect={vi.fn()} />);
+    expect(screen.getByRole("button", { name: /Search image/ })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /Generate with AI/ })).toBeInTheDocument();
+  });
+
+  it("カードクリックで onSelect(id) を呼ぶ / clicking calls onSelect with the id", async () => {
+    const user = userEvent.setup();
+    const onSelect = vi.fn();
+    render(<PageActionList ctx={ctx} actions={actions} onSelect={onSelect} />);
+
+    await user.click(screen.getByRole("button", { name: /Search image/ }));
+    expect(onSelect).toHaveBeenCalledWith("thumbnail.search");
+  });
+
+  it("空配列のときは emptyState を表示 / shows empty state when no actions", () => {
+    render(<PageActionList ctx={ctx} actions={[]} onSelect={vi.fn()} />);
+    expect(screen.getByText("No actions available")).toBeInTheDocument();
+  });
+});
diff --git a/src/components/editor/PageActionHub/PageActionList.tsx b/src/components/editor/PageActionHub/PageActionList.tsx
new file mode 100644
index 00000000..b736b2dd
--- /dev/null
+++ b/src/components/editor/PageActionHub/PageActionList.tsx
@@ -0,0 +1,61 @@
+import React from "react";
+import { useTranslation } from "react-i18next";
+import { cn } from "@zedi/ui";
+import type { PageAction, PageActionContext } from "./types";
+
+interface PageActionListProps {
+  ctx: PageActionContext;
+  actions: ReadonlyArray<PageAction>;
+  onSelect: (actionId: string) => void;
+}
+
+/**
+ * Step 1: 一覧グリッド。レジストリで `isAvailable` を通過したアクションを
+ * アイコン + ラベル + 説明のカードで表示する。クリックで詳細ビューに遷移する。
+ *
+ * Step 1 of the hub: grid of action cards. Renders the actions that passed
+ * the registry `isAvailable` gate as icon + label + description, and bubbles
+ * selection up via `onSelect(actionId)`.
+ */
+export const PageActionList: React.FC<PageActionListProps> = ({ ctx: _ctx, actions, onSelect }) => {
+  const { t } = useTranslation();
+
+  if (actions.length === 0) {
+    return (
+      <div className="text-muted-foreground py-6 text-center text-sm">
+        {t("editor.pageActionHub.emptyState")}
+      </div>
+    );
+  }
+
+  return (
+    <div className="grid grid-cols-1 gap-2 sm:grid-cols-2">
+      {actions.map((action) => {
+        const Icon = action.icon;
+        const label = t(action.labelI18nKey);
+        const description = action.descriptionI18nKey ? t(action.descriptionI18nKey) : null;
+        return (
+          <button
+            key={action.id}
+            type="button"
+            onClick={() => onSelect(action.id)}
+            className={cn(
+              "border-border bg-background hover:bg-accent",
+              "flex items-start gap-3 rounded-md border p-3 text-left transition-colors",
+            )}
+          >
+            <span className="bg-muted text-foreground flex h-9 w-9 shrink-0 items-center justify-center rounded-md">
+              <Icon className="h-4 w-4" />
+            </span>
+            <span className="flex min-w-0 flex-col gap-0.5">
+              <span className="text-sm font-medium">{label}</span>
+              {description && (
+                <span className="text-muted-foreground text-xs leading-snug">{description}</span>
+              )}
+            </span>
+          </button>
+        );
+      })}
+    </div>
+  );
+};
diff --git a/src/components/editor/PageActionHub/actions/ThumbnailGenerateAction.test.tsx b/src/components/editor/PageActionHub/actions/ThumbnailGenerateAction.test.tsx
new file mode 100644
index 00000000..0bfecd22
--- /dev/null
+++ b/src/components/editor/PageActionHub/actions/ThumbnailGenerateAction.test.tsx
@@ -0,0 +1,140 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { ThumbnailGenerateAction } from "./ThumbnailGenerateAction";
+import type { PageActionContext } from "../types";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => {
+      const map: Record<string, string> = {
+        "editor.pageActionHub.actions.thumbnailGenerate.loading": "Generating image...",
+        "editor.pageActionHub.actions.thumbnailGenerate.retry": "Regenerate",
+        "editor.pageActionHub.actions.thumbnailGenerate.missingTitle": "Please enter a title",
+      };
+      return map[key] ?? key;
+    },
+    i18n: { language: "en" },
+  }),
+}));
+
+function makeCtx(overrides: Partial<PageActionContext> = {}): PageActionContext {
+  return {
+    pageTitle: "Test Page",
+    isReadOnly: false,
+    isSignedIn: true,
+    hasThumbnail: false,
+    insertThumbnail: vi.fn(),
+    ...overrides,
+  };
+}
+
+const baseHandlers = () => ({
+  onClose: vi.fn(),
+  onBackToList: vi.fn(),
+});
+
+describe("ThumbnailGenerateAction", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("マウント時に画像生成 API を自動で呼ぶ / fires the generate request on mount", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ imageUrl: "https://example.com/img.png", mimeType: "image/png" }),
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    render(<ThumbnailGenerateAction ctx={makeCtx()} {...baseHandlers()} />);
+
+    await waitFor(() => {
+      expect(fetchMock).toHaveBeenCalledWith(
+        expect.stringContaining("/api/thumbnail/image-generate"),
+        expect.objectContaining({
+          method: "POST",
+          credentials: "include",
+        }),
+      );
+    });
+  });
+
+  it("成功すると insertThumbnail と onClose が呼ばれる / on success inserts and closes", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({ imageUrl: "https://example.com/img.png", mimeType: "image/png" }),
+      }),
+    );
+    const ctx = makeCtx();
+    const handlers = baseHandlers();
+    render(<ThumbnailGenerateAction ctx={ctx} {...handlers} />);
+
+    await waitFor(() => {
+      expect(ctx.insertThumbnail).toHaveBeenCalledWith(
+        "https://example.com/img.png",
+        "Test Page",
+        "https://example.com/img.png",
+      );
+    });
+    await waitFor(() => {
+      expect(handlers.onClose).toHaveBeenCalled();
+    });
+  });
+
+  it("エラー時は retry が表示されクリックで再リクエスト / shows retry on error and retries", async () => {
+    const fetchMock = vi.fn();
+    fetchMock.mockResolvedValueOnce({
+      ok: false,
+      status: 500,
+      json: async () => ({ error: "boom" }),
+    });
+    fetchMock.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ imageUrl: "https://example.com/img2.png", mimeType: "image/png" }),
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const user = userEvent.setup();
+    const ctx = makeCtx();
+    render(<ThumbnailGenerateAction ctx={ctx} {...baseHandlers()} />);
+
+    const retry = await screen.findByRole("button", { name: "Regenerate" });
+    await user.click(retry);
+
+    await waitFor(() => {
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  it("タイトルが空のときは fetch せず警告 / no fetch and warns when title is empty", async () => {
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+    render(<ThumbnailGenerateAction ctx={makeCtx({ pageTitle: "   " })} {...baseHandlers()} />);
+
+    await screen.findByText("Please enter a title");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  describe("when generation has already started once", () => {
+    beforeEach(() => {
+      vi.stubGlobal(
+        "fetch",
+        vi.fn().mockResolvedValue({
+          ok: true,
+          json: async () => ({ imageUrl: "https://example.com/img.png", mimeType: "image/png" }),
+        }),
+      );
+    });
+
+    it("StrictMode の二重マウントでも 1 回のみ生成する / dedup multi-effect calls", async () => {
+      const ctx = makeCtx();
+      const { unmount } = render(<ThumbnailGenerateAction ctx={ctx} {...baseHandlers()} />);
+
+      await waitFor(() => {
+        expect(ctx.insertThumbnail).toHaveBeenCalledTimes(1);
+      });
+      unmount();
+    });
+  });
+});
diff --git a/src/components/editor/PageActionHub/actions/ThumbnailGenerateAction.tsx b/src/components/editor/PageActionHub/actions/ThumbnailGenerateAction.tsx
new file mode 100644
index 00000000..ee92b473
--- /dev/null
+++ b/src/components/editor/PageActionHub/actions/ThumbnailGenerateAction.tsx
@@ -0,0 +1,90 @@
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { Loader2 } from "lucide-react";
+import { Button } from "@zedi/ui";
+import { useTranslation } from "react-i18next";
+import { useThumbnailImageGenerate } from "@/components/editor/TiptapEditor/useThumbnailImageGenerate";
+import type { PageActionComponentProps } from "../types";
+
+/**
+ * 「AI で画像生成」アクションの詳細ビュー。マウント時に画像生成 API を自動で
+ * 呼び出し、成功すれば `useThumbnailImageGenerate` 内で `ctx.insertThumbnail`
+ * が叩かれた後にハブを閉じる。失敗時はエラーと再試行ボタンを表示する。
+ *
+ * Detail view for the "thumbnail.generate" action. Auto-fires generation on
+ * mount; on success `useThumbnailImageGenerate` calls `ctx.insertThumbnail`
+ * internally and this component then closes the hub. On failure it shows an
+ * error and a retry button.
+ */
+export const ThumbnailGenerateAction: React.FC<PageActionComponentProps> = ({ ctx, onClose }) => {
+  const { t } = useTranslation();
+  const trimmedTitle = ctx.pageTitle.trim();
+  const { generateImage, isGenerating } = useThumbnailImageGenerate(
+    trimmedTitle,
+    ctx.isSignedIn,
+    ctx.insertThumbnail,
+  );
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+  const initialFireRef = useRef(false);
+  // `generateImage` 解決前にユーザがハブを閉じてコンポーネントがアンマウントすると
+  // 後段の setState / onClose が「unmounted な相手」に走り、警告および挙動異常を
+  // 招くため、ref で生存中のみ処理する。
+  // The user can close the hub before `generateImage` resolves; without this
+  // guard the subsequent setState / onClose would target an unmounted
+  // component, producing warnings and double-close behavior.
+  const isMountedRef = useRef(true);
+
+  useEffect(() => {
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+    };
+  }, []);
+
+  const runGenerate = useCallback(async () => {
+    const err = await generateImage();
+    if (!isMountedRef.current) return;
+    setErrorMessage(err);
+    if (!err) {
+      onClose();
+    }
+  }, [generateImage, onClose]);
+
+  useEffect(() => {
+    if (initialFireRef.current) return;
+    if (!trimmedTitle) return;
+    initialFireRef.current = true;
+    // ユーザが詳細ビューに入った時点で 1 回だけ生成 API を叩く一回限りのキック。
+    // 同期的な setState は走らず、`generateImage` の Promise 解決後に状態が
+    // 更新される（cascading render は発生しない）。
+    // One-shot kick: when the user opens this detail view, fire the generate
+    // API exactly once. No setState runs synchronously inside this effect —
+    // it only updates after the `generateImage` promise resolves.
+    // eslint-disable-next-line react-hooks/set-state-in-effect -- one-shot kick on detail view mount, setState only after awaited fetch
+    void runGenerate();
+  }, [trimmedTitle, runGenerate]);
+
+  // 表示用のエラーメッセージ。タイトル未入力時はそれをそのまま使う。
+  // Resolve the error message to render: empty title falls back to the hint.
+  const displayedError = !trimmedTitle
+    ? t("editor.pageActionHub.actions.thumbnailGenerate.missingTitle")
+    : errorMessage;
+
+  return (
+    <div className="space-y-3">
+      {isGenerating && (
+        <div className="text-muted-foreground flex items-center gap-2 text-sm">
+          <Loader2 className="h-4 w-4 animate-spin" />
+          {t("editor.pageActionHub.actions.thumbnailGenerate.loading")}
+        </div>
+      )}
+      {displayedError && <div className="text-destructive text-sm">{displayedError}</div>}
+      {!isGenerating && errorMessage && trimmedTitle && (
+        <div>
+          <Button type="button" size="sm" variant="outline" onClick={runGenerate}>
+            {t("editor.pageActionHub.actions.thumbnailGenerate.retry")}
+          </Button>
+        </div>
+      )}
+    </div>
+  );
+};
diff --git a/src/components/editor/PageActionHub/actions/ThumbnailSearchAction.test.tsx b/src/components/editor/PageActionHub/actions/ThumbnailSearchAction.test.tsx
new file mode 100644
index 00000000..44eb22ce
--- /dev/null
+++ b/src/components/editor/PageActionHub/actions/ThumbnailSearchAction.test.tsx
@@ -0,0 +1,168 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { ThumbnailSearchAction } from "./ThumbnailSearchAction";
+import type { PageActionContext } from "../types";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => {
+      const map: Record<string, string> = {
+        "editor.pageActionHub.actions.thumbnailSearch.loading": "Searching images...",
+        "editor.pageActionHub.actions.thumbnailSearch.empty": "No candidates found",
+        "editor.pageActionHub.actions.thumbnailSearch.next": "Next",
+        "editor.pageActionHub.actions.thumbnailSearch.retry": "Retry",
+      };
+      return map[key] ?? key;
+    },
+    i18n: { language: "en" },
+  }),
+}));
+
+function makeCtx(overrides: Partial<PageActionContext> = {}): PageActionContext {
+  return {
+    pageTitle: "Test Page",
+    isReadOnly: false,
+    isSignedIn: true,
+    hasThumbnail: false,
+    insertThumbnail: vi.fn(),
+    ...overrides,
+  };
+}
+
+const baseHandlers = () => ({
+  onClose: vi.fn(),
+  onBackToList: vi.fn(),
+});
+
+describe("ThumbnailSearchAction", () => {
+  beforeEach(() => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({ items: [], nextCursor: null }),
+      }),
+    );
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("マウント時に検索 API を自動で呼ぶ / fires the search request on mount", async () => {
+    const ctx = makeCtx();
+    const handlers = baseHandlers();
+    render(<ThumbnailSearchAction ctx={ctx} {...handlers} />);
+
+    await waitFor(() => {
+      expect(fetch).toHaveBeenCalledWith(
+        expect.stringContaining("/api/thumbnail/image-search?query=Test+Page&limit=10"),
+        expect.objectContaining({ credentials: "include" }),
+      );
+    });
+  });
+
+  it("候補が返ると一覧表示する / renders returned candidates", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          items: [
+            {
+              id: "1",
+              previewUrl: "https://example.com/p.jpg",
+              imageUrl: "https://example.com/f.jpg",
+              alt: "Cat",
+              sourceName: "Unsplash",
+              sourceUrl: "https://example.com",
+            },
+          ],
+          nextCursor: null,
+        }),
+      }),
+    );
+
+    render(<ThumbnailSearchAction ctx={makeCtx()} {...baseHandlers()} />);
+
+    await screen.findByAltText("Cat");
+    expect(screen.getByText("Unsplash")).toBeInTheDocument();
+  });
+
+  it("候補クリックで insertThumbnail と onClose を呼ぶ / clicking a candidate inserts and closes", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          items: [
+            {
+              id: "1",
+              previewUrl: "https://example.com/p.jpg",
+              imageUrl: "https://example.com/f.jpg",
+              alt: "Cat",
+              sourceName: "Unsplash",
+              sourceUrl: "https://example.com",
+            },
+          ],
+          nextCursor: null,
+        }),
+      }),
+    );
+    const user = userEvent.setup();
+    const ctx = makeCtx();
+    const handlers = baseHandlers();
+    render(<ThumbnailSearchAction ctx={ctx} {...handlers} />);
+
+    await user.click(await screen.findByAltText("Cat"));
+
+    expect(ctx.insertThumbnail).toHaveBeenCalledWith(
+      "https://example.com/f.jpg",
+      "Cat",
+      "https://example.com/p.jpg",
+    );
+    expect(handlers.onClose).toHaveBeenCalled();
+  });
+
+  it("空の場合は empty メッセージを出す / shows empty state when no candidates returned", async () => {
+    render(<ThumbnailSearchAction ctx={makeCtx()} {...baseHandlers()} />);
+    await screen.findByText("No candidates found");
+  });
+
+  it("Next ボタンで cursor つき再リクエスト / next button paginates with cursor", async () => {
+    const fetchMock = vi.fn();
+    fetchMock.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        items: [
+          {
+            id: "1",
+            previewUrl: "p1",
+            imageUrl: "f1",
+            alt: "a1",
+            sourceName: "s1",
+            sourceUrl: "u1",
+          },
+        ],
+        nextCursor: "c2",
+      }),
+    });
+    fetchMock.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ items: [], nextCursor: null }),
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const user = userEvent.setup();
+    render(<ThumbnailSearchAction ctx={makeCtx()} {...baseHandlers()} />);
+
+    await screen.findByAltText("a1");
+    await user.click(screen.getByRole("button", { name: "Next" }));
+
+    await waitFor(() => {
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+      expect(fetchMock.mock.calls[1]?.[0]).toContain("cursor=c2");
+    });
+  });
+});
diff --git a/src/components/editor/PageActionHub/actions/ThumbnailSearchAction.tsx b/src/components/editor/PageActionHub/actions/ThumbnailSearchAction.tsx
new file mode 100644
index 00000000..637c584a
--- /dev/null
+++ b/src/components/editor/PageActionHub/actions/ThumbnailSearchAction.tsx
@@ -0,0 +1,154 @@
+import React, { useCallback, useEffect, useRef } from "react";
+import { Loader2 } from "lucide-react";
+import { Button } from "@zedi/ui";
+import { useTranslation } from "react-i18next";
+import { sanitizeLinkUrl } from "@/lib/markdownToTiptapHelpers";
+import { getThumbnailApiBaseUrl } from "@/components/editor/TiptapEditor/thumbnailApiHelpers";
+import { useThumbnailImageSearch } from "@/components/editor/TiptapEditor/useThumbnailImageSearch";
+import type { ThumbnailCandidate } from "@/components/editor/TiptapEditor/thumbnailTypes";
+import type { PageActionComponentProps } from "../types";
+
+/**
+ * 「画像を検索」アクションの詳細ビュー。マウント時にタイトルで自動検索し、
+ * 候補クリックで `ctx.insertThumbnail` を呼んでハブを閉じる。
+ *
+ * Detail view for the "thumbnail.search" action. Auto-fires a search on
+ * mount, and on candidate click forwards to `ctx.insertThumbnail` then closes
+ * the hub.
+ */
+export const ThumbnailSearchAction: React.FC<PageActionComponentProps> = ({ ctx, onClose }) => {
+  const { t } = useTranslation();
+  const trimmedTitle = ctx.pageTitle.trim();
+  const search = useThumbnailImageSearch(trimmedTitle, ctx.isSignedIn, getThumbnailApiBaseUrl());
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const initialLoadFiredRef = useRef(false);
+
+  // 詳細ビューに入った時点で初回検索を 1 回だけ走らせる（StrictMode の二重実行ガード）。
+  // Fire the initial load exactly once when the detail view mounts (StrictMode guard).
+  useEffect(() => {
+    if (initialLoadFiredRef.current) return;
+    initialLoadFiredRef.current = true;
+    void search.loadCandidates();
+  }, [search]);
+
+  const handleSelectCandidate = useCallback(
+    (candidate: ThumbnailCandidate) => {
+      ctx.insertThumbnail(candidate.imageUrl, candidate.alt, candidate.previewUrl);
+      onClose();
+    },
+    [ctx, onClose],
+  );
+
+  const handleWheel = useCallback((event: React.WheelEvent<HTMLDivElement>) => {
+    const container = scrollRef.current;
+    if (!container) return;
+    if (Math.abs(event.deltaY) <= Math.abs(event.deltaX)) return;
+    const maxScrollLeft = container.scrollWidth - container.clientWidth;
+    const newScrollLeft = Math.min(Math.max(0, container.scrollLeft + event.deltaY), maxScrollLeft);
+    if (newScrollLeft !== container.scrollLeft) {
+      container.scrollLeft = newScrollLeft;
+      event.preventDefault();
+    }
+  }, []);
+
+  const handleNextPage = useCallback(() => {
+    if (!search.nextCursor || search.isLoading) return;
+    void search.loadCandidates(search.nextCursor);
+  }, [search]);
+
+  const handleRetry = useCallback(() => {
+    void search.loadCandidates();
+  }, [search]);
+
+  return (
+    <div className="space-y-3">
+      {search.isLoading && (
+        <div className="text-muted-foreground flex items-center gap-2 text-sm">
+          <Loader2 className="h-4 w-4 animate-spin" />
+          {t("editor.pageActionHub.actions.thumbnailSearch.loading")}
+        </div>
+      )}
+      {search.errorMessage && (
+        <div className="space-y-2">
+          <div className="text-destructive text-sm">{search.errorMessage}</div>
+          <Button type="button" size="sm" variant="outline" onClick={handleRetry}>
+            {t("editor.pageActionHub.actions.thumbnailSearch.retry")}
+          </Button>
+        </div>
+      )}
+      {!search.isLoading && !search.errorMessage && search.candidates.length === 0 && (
+        <div className="text-muted-foreground text-sm">
+          {t("editor.pageActionHub.actions.thumbnailSearch.empty")}
+        </div>
+      )}
+
+      {search.candidates.length > 0 && (
+        <div
+          ref={scrollRef}
+          onWheel={handleWheel}
+          className="flex snap-x snap-mandatory gap-3 overflow-x-auto pb-1"
+        >
+          {search.candidates.map((candidate) => {
+            const safeAuthorUrl = candidate.authorUrl ? sanitizeLinkUrl(candidate.authorUrl) : null;
+            const safeSourceUrl = candidate.sourceUrl ? sanitizeLinkUrl(candidate.sourceUrl) : null;
+            return (
+              <div key={candidate.id} className="flex shrink-0 snap-start flex-col gap-1 text-left">
+                <button
+                  type="button"
+                  onClick={() => handleSelectCandidate(candidate)}
+                  className="bg-background rounded-md border p-1 text-left"
+                >
+                  <img
+                    src={candidate.previewUrl}
+                    alt={candidate.alt}
+                    className="h-24 w-auto rounded object-cover sm:h-32"
+                    loading="lazy"
+                  />
+                </button>
+                <div className="text-muted-foreground text-[11px]">
+                  {candidate.authorName ? (
+                    <>
+                      {safeAuthorUrl ? (
+                        <a
+                          href={safeAuthorUrl}
+                          target="_blank"
+                          rel="noopener noreferrer"
+                          className="underline underline-offset-2"
+                        >
+                          {candidate.authorName}
+                        </a>
+                      ) : (
+                        <span>{candidate.authorName}</span>
+                      )}{" "}
+                      /{" "}
+                    </>
+                  ) : null}
+                  {safeSourceUrl ? (
+                    <a
+                      href={safeSourceUrl}
+                      target="_blank"
+                      rel="noopener noreferrer"
+                      className="underline underline-offset-2"
+                    >
+                      {candidate.sourceName}
+                    </a>
+                  ) : (
+                    <span>{candidate.sourceName}</span>
+                  )}
+                </div>
+              </div>
+            );
+          })}
+        </div>
+      )}
+
+      {search.nextCursor && !search.isLoading && (
+        <div>
+          <Button type="button" size="sm" variant="outline" onClick={handleNextPage}>
+            {t("editor.pageActionHub.actions.thumbnailSearch.next")}
+          </Button>
+        </div>
+      )}
+    </div>
+  );
+};
diff --git a/src/components/editor/PageActionHub/actions/WikiComposeAction.tsx b/src/components/editor/PageActionHub/actions/WikiComposeAction.tsx
new file mode 100644
index 00000000..b39454fc
--- /dev/null
+++ b/src/components/editor/PageActionHub/actions/WikiComposeAction.tsx
@@ -0,0 +1,51 @@
+/**
+ * `wiki.compose` PageActionHub detail view (#950).
+ *
+ * 分割画面 Compose へ遷移する。`ctx.wikiComposeHref` が無いときは説明のみ表示。
+ *
+ * Opens the Wiki Compose split-screen when `ctx.wikiComposeHref` is set.
+ */
+import React, { useCallback } from "react";
+import { useNavigate } from "react-router-dom";
+import { Sparkles } from "lucide-react";
+import { Button } from "@zedi/ui";
+import { useTranslation } from "react-i18next";
+import type { PageActionComponentProps } from "../types";
+
+/** Detail view for the wiki.compose hub action. */
+export const WikiComposeAction: React.FC<PageActionComponentProps> = ({ ctx, onClose }) => {
+  const { t } = useTranslation();
+  const navigate = useNavigate();
+  const href = ctx.wikiComposeHref?.trim() ?? "";
+
+  const handleStart = useCallback(() => {
+    if (!href) return;
+    navigate(href);
+    onClose();
+  }, [href, navigate, onClose]);
+
+  if (!href) {
+    return (
+      <p className="text-muted-foreground text-sm">
+        {t("editor.pageActionHub.actions.wikiCompose.unavailable")}
+      </p>
+    );
+  }
+
+  return (
+    <div className="flex flex-col gap-4">
+      <p className="text-muted-foreground text-sm">
+        {t("editor.pageActionHub.actions.wikiCompose.description")}
+      </p>
+      <Button
+        type="button"
+        className="gap-2"
+        onClick={handleStart}
+        data-testid="wiki-compose-start"
+      >
+        <Sparkles className="h-4 w-4" />
+        {t("editor.pageActionHub.actions.wikiCompose.start")}
+      </Button>
+    </div>
+  );
+};
diff --git a/src/components/editor/PageActionHub/registry.test.ts b/src/components/editor/PageActionHub/registry.test.ts
new file mode 100644
index 00000000..654ba083
--- /dev/null
+++ b/src/components/editor/PageActionHub/registry.test.ts
@@ -0,0 +1,98 @@
+import { describe, it, expect, vi } from "vitest";
+import { PAGE_ACTIONS, getAvailablePageActions, getPageActionById } from "./registry";
+import type { PageActionContext } from "./types";
+
+function makeCtx(overrides: Partial<PageActionContext> = {}): PageActionContext {
+  return {
+    pageTitle: "Test Page",
+    isReadOnly: false,
+    isSignedIn: true,
+    hasThumbnail: false,
+    insertThumbnail: vi.fn(),
+    ...overrides,
+  };
+}
+
+describe("PageActionHub registry", () => {
+  it("登録されているアクション ID / exposes registered action ids", () => {
+    const ids = PAGE_ACTIONS.map((a) => a.id);
+    expect(ids).toEqual(["thumbnail.search", "thumbnail.generate", "wiki.compose"]);
+  });
+
+  it("サムネイル系は insertStrategy=head / thumbnail actions are head-insert", () => {
+    for (const action of PAGE_ACTIONS.filter((a) => a.category === "thumbnail")) {
+      expect(action.insertStrategy).toBe("head");
+      expect(action.category).toBe("thumbnail");
+    }
+  });
+
+  describe.each(["thumbnail.search", "thumbnail.generate"] as const)(
+    "%s availability gates",
+    (id) => {
+      const action = PAGE_ACTIONS.find((a) => a.id === id);
+      if (!action) throw new Error(`missing ${id}`);
+
+      it("通常条件では利用可 / available under normal conditions", () => {
+        expect(action.isAvailable(makeCtx())).toBe(true);
+      });
+
+      it("isReadOnly では不可 / blocked when read-only", () => {
+        expect(action.isAvailable(makeCtx({ isReadOnly: true }))).toBe(false);
+      });
+
+      it("isSignedIn=false では不可 / blocked when signed out", () => {
+        expect(action.isAvailable(makeCtx({ isSignedIn: false }))).toBe(false);
+      });
+
+      it("hasThumbnail=true では不可 / blocked when thumbnail already exists", () => {
+        expect(action.isAvailable(makeCtx({ hasThumbnail: true }))).toBe(false);
+      });
+
+      it("タイトルが空白のみのときは不可 / blocked when title is empty/whitespace", () => {
+        expect(action.isAvailable(makeCtx({ pageTitle: "   " }))).toBe(false);
+        expect(action.isAvailable(makeCtx({ pageTitle: "" }))).toBe(false);
+      });
+    },
+  );
+
+  it("getAvailablePageActions は利用可能なアクションのみ返す / returns only available actions", () => {
+    const allow = getAvailablePageActions(makeCtx({ wikiComposeHref: "/notes/n/p/compose" }));
+    expect(allow.map((a) => a.id)).toEqual([
+      "thumbnail.search",
+      "thumbnail.generate",
+      "wiki.compose",
+    ]);
+
+    const blockedReadOnly = getAvailablePageActions(makeCtx({ isReadOnly: true }));
+    expect(blockedReadOnly).toEqual([]);
+
+    const blockedThumb = getAvailablePageActions(
+      makeCtx({ hasThumbnail: true, wikiComposeHref: "/notes/n/p/compose" }),
+    );
+    expect(blockedThumb.map((a) => a.id)).toEqual(["wiki.compose"]);
+  });
+
+  describe("wiki.compose availability gates", () => {
+    const action = PAGE_ACTIONS.find((a) => a.id === "wiki.compose");
+    if (!action) throw new Error("missing wiki.compose");
+
+    it("wikiComposeHref があるとき利用可 / available when compose href is set", () => {
+      expect(action.isAvailable(makeCtx({ wikiComposeHref: "/notes/n/p/compose" }))).toBe(true);
+    });
+
+    it("wikiComposeHref が無いときは不可 / blocked without compose href", () => {
+      expect(action.isAvailable(makeCtx())).toBe(false);
+    });
+
+    it("タイトルが空のときは不可 / blocked when title is empty", () => {
+      expect(
+        action.isAvailable(makeCtx({ pageTitle: "", wikiComposeHref: "/notes/n/p/compose" })),
+      ).toBe(false);
+    });
+  });
+
+  it("getPageActionById は一致 ID の記述を返し、未知 ID は undefined / lookup behavior", () => {
+    expect(getPageActionById("thumbnail.search")?.id).toBe("thumbnail.search");
+    expect(getPageActionById("unknown.id")).toBeUndefined();
+  });
+});
diff --git a/src/components/editor/PageActionHub/registry.ts b/src/components/editor/PageActionHub/registry.ts
new file mode 100644
index 00000000..b4288885
--- /dev/null
+++ b/src/components/editor/PageActionHub/registry.ts
@@ -0,0 +1,88 @@
+import { Image as ImageIcon, Sparkles, Wand2 } from "lucide-react";
+import { ThumbnailSearchAction } from "./actions/ThumbnailSearchAction";
+import { ThumbnailGenerateAction } from "./actions/ThumbnailGenerateAction";
+import { WikiComposeAction } from "./actions/WikiComposeAction";
+import type { PageAction, PageActionContext } from "./types";
+
+/**
+ * アクションが共通で要求するゲート条件。サムネイル系は読み取り専用・未サインイン・
+ * サムネイル既存・空タイトルのいずれでも非表示にする。
+ *
+ * Shared availability gate for thumbnail actions: hidden when read-only,
+ * signed out, thumbnail already present, or title empty/whitespace.
+ */
+function isThumbnailActionAvailable(ctx: PageActionContext): boolean {
+  if (ctx.isReadOnly) return false;
+  if (!ctx.isSignedIn) return false;
+  if (ctx.hasThumbnail) return false;
+  if (ctx.pageTitle.trim().length === 0) return false;
+  return true;
+}
+
+/**
+ * Wiki Compose 入口。タイトルがあり、Compose URL が組み立て可能なときのみ表示。
+ * Available when the page has a title and a Compose route is configured.
+ */
+function isWikiComposeActionAvailable(ctx: PageActionContext): boolean {
+  if (ctx.isReadOnly) return false;
+  if (!ctx.isSignedIn) return false;
+  if (ctx.pageTitle.trim().length === 0) return false;
+  if (!ctx.wikiComposeHref?.trim()) return false;
+  return true;
+}
+
+/**
+ * Phase 1 で利用可能なアクション一覧。配列順序が一覧グリッド上の表示順を兼ねる。
+ * 後続フェーズで WebClipper / Mermaid / AI / テンプレートを末尾に追加していく。
+ *
+ * Phase 1 registry. Order matches the visual order of the list grid; future
+ * phases append WebClipper / Mermaid / AI summarizer / templates after these.
+ */
+export const PAGE_ACTIONS: ReadonlyArray<PageAction> = [
+  {
+    id: "thumbnail.search",
+    labelI18nKey: "editor.pageActionHub.actions.thumbnailSearch.label",
+    descriptionI18nKey: "editor.pageActionHub.actions.thumbnailSearch.description",
+    icon: ImageIcon,
+    category: "thumbnail",
+    insertStrategy: "head",
+    isAvailable: isThumbnailActionAvailable,
+    Component: ThumbnailSearchAction,
+  },
+  {
+    id: "thumbnail.generate",
+    labelI18nKey: "editor.pageActionHub.actions.thumbnailGenerate.label",
+    descriptionI18nKey: "editor.pageActionHub.actions.thumbnailGenerate.description",
+    icon: Wand2,
+    category: "thumbnail",
+    insertStrategy: "head",
+    isAvailable: isThumbnailActionAvailable,
+    Component: ThumbnailGenerateAction,
+  },
+  {
+    id: "wiki.compose",
+    labelI18nKey: "editor.pageActionHub.actions.wikiCompose.label",
+    descriptionI18nKey: "editor.pageActionHub.actions.wikiCompose.description",
+    icon: Sparkles,
+    category: "ai",
+    insertStrategy: "custom",
+    isAvailable: isWikiComposeActionAvailable,
+    Component: WikiComposeAction,
+  },
+];
+
+/**
+ * `ctx` に対して `isAvailable` を通過したアクションのみを返す。
+ * Returns only actions whose `isAvailable` gate passes for the given `ctx`.
+ */
+export function getAvailablePageActions(ctx: PageActionContext): PageAction[] {
+  return PAGE_ACTIONS.filter((action) => action.isAvailable(ctx));
+}
+
+/**
+ * ID で記述を引く。未知 ID は undefined。
+ * Look up a registered action by id, or undefined if not registered.
+ */
+export function getPageActionById(id: string): PageAction | undefined {
+  return PAGE_ACTIONS.find((action) => action.id === id);
+}
diff --git a/src/components/editor/PageActionHub/types.ts b/src/components/editor/PageActionHub/types.ts
new file mode 100644
index 00000000..62a8a5da
--- /dev/null
+++ b/src/components/editor/PageActionHub/types.ts
@@ -0,0 +1,90 @@
+import type { LucideIcon } from "lucide-react";
+import type React from "react";
+
+/**
+ * ハブ内で表示するアクションの呼び出しコンテキスト。`useTiptapEditorController`
+ * 内で組み立て、`PageActionHub` に渡される。レジストリの `isAvailable` ゲートと
+ * 各アクションコンポーネントの両方が参照する。
+ *
+ * Runtime context passed to PageActionHub actions. Assembled inside
+ * `useTiptapEditorController` and forwarded to `PageActionHub`. Consumed both
+ * by the registry's `isAvailable` gates and by each action component.
+ */
+export interface PageActionContext {
+  /** 編集中ページのタイトル。検索/生成のクエリに使用する。 / Editing page title used as the search/generate query. */
+  pageTitle: string;
+  /** 読み取り専用モードかどうか。 / Whether the editor is in read-only mode. */
+  isReadOnly: boolean;
+  /** サインイン済みかどうか。 / Whether the viewer is signed in. */
+  isSignedIn: boolean;
+  /** 既にサムネイルが本文先頭に挿入済みかどうか。 / Whether the page already has a thumbnail. */
+  hasThumbnail: boolean;
+  /**
+   * 本文先頭にサムネイル画像を挿入するハンドラ。既存
+   * `useThumbnailController` が返す `handleInsertThumbnailImage` を委譲する。
+   *
+   * Inserts the chosen thumbnail at the top of the editor document. Delegates
+   * to the existing `useThumbnailController`'s `handleInsertThumbnailImage`.
+   */
+  insertThumbnail: (imageUrl: string, alt: string, previewUrl?: string) => void;
+  /**
+   * Wiki Compose 画面 URL。ノートネイティブページでのみ設定される (#950)。
+   * Route to the Wiki Compose split-screen; set only on note-native pages.
+   */
+  wikiComposeHref?: string;
+}
+
+/**
+ * 一覧→詳細のビュー状態。`{ kind: "list" }` を初期値とし、ユーザがカードを
+ * クリックすると `{ kind: "detail", actionId }` に遷移する。
+ *
+ * Two-step view state. Starts as `{ kind: "list" }`; selecting a card moves
+ * to `{ kind: "detail", actionId }`.
+ */
+export type PageActionView = { kind: "list" } | { kind: "detail"; actionId: string };
+
+/**
+ * `PageActionHub` を親から命令的に開閉するためのハンドル。`insertAtCursorRef`
+ * と同パターンで `useEffect` 内で `ref.current` に代入される。
+ *
+ * Imperative handle exposed by `PageActionHub`. Parent components (FAB)
+ * assign the handle through a ref, mirroring the `insertAtCursorRef` pattern.
+ */
+export interface PageActionHubHandle {
+  open: () => void;
+  close: () => void;
+}
+
+/**
+ * 各アクションコンポーネントが受け取る共通 props。
+ * Common props passed to every action component rendered inside the hub.
+ */
+export interface PageActionComponentProps {
+  ctx: PageActionContext;
+  /** ハブ全体を閉じる（成功時等に使用）。 / Close the entire hub. */
+  onClose: () => void;
+  /** 一覧ビューに戻る。 / Pop back to the list view. */
+  onBackToList: () => void;
+}
+
+/**
+ * レジストリに登録されるアクション記述。`Component` が詳細ビューを描画する。
+ * `insertStrategy` は Phase 1 では宣言のみで、実際の挿入位置は各アクション
+ * コンポーネントが委譲する `ctx.insertThumbnail` 等の中で決まる。汎用 dispatch
+ * ヘルパは後続フェーズで導入する。
+ *
+ * Registry descriptor for a hub action. `Component` renders the detail view.
+ * `insertStrategy` is purely descriptive in Phase 1 — actual insert positions
+ * are decided inside the methods on `ctx` (e.g. `insertThumbnail`). A generic
+ * dispatcher will arrive in later phases once a second strategy is needed.
+ */
+export interface PageAction {
+  id: string;
+  labelI18nKey: string;
+  descriptionI18nKey?: string;
+  icon: LucideIcon;
+  category: "thumbnail" | "import" | "ai" | "template" | "other";
+  insertStrategy: "cursor" | "head" | "custom";
+  isAvailable: (ctx: PageActionContext) => boolean;
+  Component: React.ComponentType<PageActionComponentProps>;
+}
diff --git a/src/components/editor/PageActionHub/usePageActionHub.test.ts b/src/components/editor/PageActionHub/usePageActionHub.test.ts
new file mode 100644
index 00000000..5fab928f
--- /dev/null
+++ b/src/components/editor/PageActionHub/usePageActionHub.test.ts
@@ -0,0 +1,66 @@
+import { describe, it, expect } from "vitest";
+import { act, renderHook } from "@testing-library/react";
+import { usePageActionHub } from "./usePageActionHub";
+
+describe("usePageActionHub", () => {
+  it("初期状態は閉じておりビューは list / starts closed on the list view", () => {
+    const { result } = renderHook(() => usePageActionHub());
+    expect(result.current.isOpen).toBe(false);
+    expect(result.current.view).toEqual({ kind: "list" });
+  });
+
+  it("open() で isOpen=true かつ list にリセット / open() opens and resets to list", () => {
+    const { result } = renderHook(() => usePageActionHub());
+    act(() => {
+      result.current.selectAction("thumbnail.search");
+    });
+    expect(result.current.view).toEqual({ kind: "detail", actionId: "thumbnail.search" });
+
+    act(() => {
+      result.current.open();
+    });
+    expect(result.current.isOpen).toBe(true);
+    expect(result.current.view).toEqual({ kind: "list" });
+  });
+
+  it("selectAction(id) は detail に遷移 / selectAction navigates to detail", () => {
+    const { result } = renderHook(() => usePageActionHub());
+    act(() => {
+      result.current.open();
+      result.current.selectAction("thumbnail.generate");
+    });
+    expect(result.current.view).toEqual({ kind: "detail", actionId: "thumbnail.generate" });
+  });
+
+  it("backToList() で list に戻る / backToList returns to list", () => {
+    const { result } = renderHook(() => usePageActionHub());
+    act(() => {
+      result.current.open();
+      result.current.selectAction("thumbnail.search");
+      result.current.backToList();
+    });
+    expect(result.current.view).toEqual({ kind: "list" });
+  });
+
+  it("handleOpenChange(false) は閉じてビューも list に戻す / closing resets view", () => {
+    const { result } = renderHook(() => usePageActionHub());
+    act(() => {
+      result.current.open();
+      result.current.selectAction("thumbnail.search");
+      result.current.handleOpenChange(false);
+    });
+    expect(result.current.isOpen).toBe(false);
+    expect(result.current.view).toEqual({ kind: "list" });
+  });
+
+  it("close() でも閉じてビューが list に戻る / close() resets view", () => {
+    const { result } = renderHook(() => usePageActionHub());
+    act(() => {
+      result.current.open();
+      result.current.selectAction("thumbnail.generate");
+      result.current.close();
+    });
+    expect(result.current.isOpen).toBe(false);
+    expect(result.current.view).toEqual({ kind: "list" });
+  });
+});
diff --git a/src/components/editor/PageActionHub/usePageActionHub.ts b/src/components/editor/PageActionHub/usePageActionHub.ts
new file mode 100644
index 00000000..5101f6ae
--- /dev/null
+++ b/src/components/editor/PageActionHub/usePageActionHub.ts
@@ -0,0 +1,49 @@
+import { useCallback, useState } from "react";
+import type { PageActionView } from "./types";
+
+/**
+ * `PageActionHub` の純粋な状態マシン。レジストリには依存せず、開閉と
+ * 一覧/詳細ビューの遷移のみを担う。閉じる操作（X / Esc / Drawer ドラッグダウン）
+ * は常に view を list に戻し、次回オープン時に詳細ビューが残らないようにする。
+ *
+ * Pure state machine for `PageActionHub`. Has no registry knowledge — owns
+ * only open/close state and the list/detail view transition. Any close action
+ * resets the view to `list` so reopening always lands on the list.
+ */
+export function usePageActionHub() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [view, setView] = useState<PageActionView>({ kind: "list" });
+
+  const open = useCallback(() => {
+    setView({ kind: "list" });
+    setIsOpen(true);
+  }, []);
+
+  const close = useCallback(() => {
+    setIsOpen(false);
+    setView({ kind: "list" });
+  }, []);
+
+  const selectAction = useCallback((actionId: string) => {
+    setView({ kind: "detail", actionId });
+  }, []);
+
+  const backToList = useCallback(() => {
+    setView({ kind: "list" });
+  }, []);
+
+  const handleOpenChange = useCallback((next: boolean) => {
+    setIsOpen(next);
+    if (!next) setView({ kind: "list" });
+  }, []);
+
+  return {
+    isOpen,
+    view,
+    open,
+    close,
+    selectAction,
+    backToList,
+    handleOpenChange,
+  };
+}
diff --git a/src/components/editor/PageEditor/usePdfExport.test.tsx b/src/components/editor/PageEditor/usePdfExport.test.tsx
new file mode 100644
index 00000000..49859138
--- /dev/null
+++ b/src/components/editor/PageEditor/usePdfExport.test.tsx
@@ -0,0 +1,96 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
+
+const { mockDownloadPdf, mockToast } = vi.hoisted(() => ({
+  mockDownloadPdf: vi.fn(),
+  mockToast: vi.fn(),
+}));
+
+vi.mock("@/lib/tiptapToHtml", () => ({
+  downloadPdf: (...args: unknown[]) => mockDownloadPdf(...args),
+}));
+
+vi.mock("@zedi/ui", () => ({
+  useToast: () => ({ toast: mockToast }),
+}));
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string, fallback?: string) => {
+      if (typeof fallback === "string") return fallback;
+      return key;
+    },
+  }),
+}));
+
+import { usePdfExport } from "./usePdfExport";
+
+function HookHarness({
+  title,
+  content,
+  sourceUrl,
+}: {
+  title: string;
+  content: string;
+  sourceUrl?: string | null;
+}) {
+  const { handleExportPdf } = usePdfExport(title, content, sourceUrl ?? null);
+  return (
+    <button type="button" onClick={handleExportPdf}>
+      export
+    </button>
+  );
+}
+
+describe("usePdfExport", () => {
+  beforeEach(() => {
+    mockDownloadPdf.mockReset();
+    mockToast.mockReset();
+  });
+
+  it("delegates to downloadPdf with title / content / sourceUrl and i18n options", async () => {
+    mockDownloadPdf.mockResolvedValueOnce(undefined);
+    render(<HookHarness title="My Page" content="{}" sourceUrl="https://example.com/article" />);
+
+    fireEvent.click(screen.getByText("export"));
+
+    await waitFor(() => {
+      expect(mockDownloadPdf).toHaveBeenCalledTimes(1);
+    });
+    const [title, content, sourceUrl, options] = mockDownloadPdf.mock.calls[0] ?? [];
+    expect(title).toBe("My Page");
+    expect(content).toBe("{}");
+    expect(sourceUrl).toBe("https://example.com/article");
+    expect(options).toMatchObject({
+      defaultTitle: "notes.untitledPage",
+      attributionLabel: "editor.pdfExport.sourceAttribution",
+    });
+  });
+
+  it("fires the success toast after downloadPdf resolves", async () => {
+    mockDownloadPdf.mockResolvedValueOnce(undefined);
+    render(<HookHarness title="t" content="c" sourceUrl={null} />);
+
+    fireEvent.click(screen.getByText("export"));
+
+    await waitFor(() => {
+      expect(mockToast).toHaveBeenCalledWith({
+        title: "editor.pdfExport.downloaded",
+      });
+    });
+  });
+
+  it("fires a destructive toast when downloadPdf rejects", async () => {
+    mockDownloadPdf.mockRejectedValueOnce(new Error("boom"));
+    render(<HookHarness title="t" content="c" sourceUrl={null} />);
+
+    fireEvent.click(screen.getByText("export"));
+
+    await waitFor(() => {
+      expect(mockToast).toHaveBeenCalledWith({
+        title: "editor.pdfExport.failed",
+        variant: "destructive",
+      });
+    });
+  });
+});
diff --git a/src/components/editor/PageEditor/usePdfExport.ts b/src/components/editor/PageEditor/usePdfExport.ts
new file mode 100644
index 00000000..257235c2
--- /dev/null
+++ b/src/components/editor/PageEditor/usePdfExport.ts
@@ -0,0 +1,48 @@
+import { useCallback } from "react";
+import { useTranslation } from "react-i18next";
+import { useToast } from "@zedi/ui";
+import { downloadPdf } from "@/lib/tiptapToHtml";
+
+/**
+ * `usePdfExport` の戻り値。Markdown エクスポート系フックと同じ形でハンドラだけを返す。
+ * Return type of {@link usePdfExport}. Matches the shape of the Markdown export
+ * hooks (handlers only) so menu wiring stays symmetric.
+ */
+interface UsePdfExportReturn {
+  handleExportPdf: () => Promise<void>;
+}
+
+/**
+ * ページエディタの「PDFで出力」アクションを駆動するフック。クライアント側で
+ * Tiptap JSON を HTML 化し、html2pdf.js で PDF をダウンロードする。成功 /
+ * 失敗時にはトーストを発火する。
+ *
+ * Hook that drives the page editor's "Export PDF" action. Converts Tiptap
+ * JSON to HTML in the browser and triggers an html2pdf.js download. Emits a
+ * success or destructive toast depending on the outcome.
+ */
+export function usePdfExport(
+  title: string,
+  content: string,
+  sourceUrl?: string | null,
+): UsePdfExportReturn {
+  const { t } = useTranslation();
+  const { toast } = useToast();
+
+  const handleExportPdf = useCallback(async () => {
+    try {
+      await downloadPdf(title, content, sourceUrl, {
+        defaultTitle: t("notes.untitledPage"),
+        attributionLabel: t("editor.pdfExport.sourceAttribution"),
+      });
+      toast({ title: t("editor.pdfExport.downloaded") });
+    } catch {
+      toast({
+        title: t("editor.pdfExport.failed"),
+        variant: "destructive",
+      });
+    }
+  }, [title, content, sourceUrl, toast, t]);
+
+  return { handleExportPdf };
+}
diff --git a/src/components/editor/TiptapEditor.tsx b/src/components/editor/TiptapEditor.tsx
index 2e7dff46..47e7f991 100644
--- a/src/components/editor/TiptapEditor.tsx
+++ b/src/components/editor/TiptapEditor.tsx
@@ -1,20 +1,24 @@
-import React from "react";
+import React, { useCallback, useRef } from "react";
 import { useTranslation } from "react-i18next";
 import { EditorContent } from "@tiptap/react";
-import { cn } from "@zedi/ui";
+import { cn, useIsMobile } from "@zedi/ui";
 import { MermaidGeneratorDialog } from "./MermaidGeneratorDialog";
 import { CreatePageDialog } from "./TiptapEditor/CreatePageDialog";
 import type { TiptapEditorProps } from "./TiptapEditor/types";
 import { StorageSetupDialog } from "./TiptapEditor/StorageSetupDialog";
 import { DragOverlay } from "./TiptapEditor/DragOverlay";
 import { WikiLinkSuggestionLayer } from "./TiptapEditor/WikiLinkSuggestionLayer";
+import { FloatingWikiLinkInputBar } from "./FloatingWikiLinkInputBar";
 import { WikiLinkHoverCardLayer } from "./TiptapEditor/WikiLinkHoverCardLayer";
 import { TagSuggestionLayer } from "./TiptapEditor/TagSuggestionLayer";
 import { SlashSuggestionLayer } from "./TiptapEditor/SlashSuggestionLayer";
 import { EditorBubbleMenu } from "./TiptapEditor/EditorBubbleMenu";
+import { MobileSelectionSheet } from "./TiptapEditor/MobileSelectionSheet";
 import { TableBubbleMenu } from "./TiptapEditor/TableBubbleMenu";
-import { EditorRecommendationBar } from "@/components/editor/TiptapEditor/EditorRecommendationBar";
+import { PageActionHub } from "@/components/editor/PageActionHub/PageActionHub";
 import { useTiptapEditorController } from "./TiptapEditor/useTiptapEditorController";
+import { useBubbleMenuWikiLink } from "./TiptapEditor/useBubbleMenuWikiLink";
+import { useEditorWikiLinkShortcuts } from "@/hooks/useEditorWikiLinkShortcuts";
 import { SlashAgentLoadingOverlay } from "./TiptapEditor/SlashAgentLoadingOverlay";
 
 // Re-export types for consumers
@@ -39,14 +43,18 @@ const TiptapEditor: React.FC<TiptapEditorProps> = ({
   collaborationConfig,
   focusContentRef,
   insertAtCursorRef,
+  pageActionHubRef,
   initialContent,
   onInitialContentApplied,
   isWikiGenerating = false,
   wikiContentForCollab,
   onWikiContentApplied,
   pageNoteId = null,
+  wikiComposeHref,
+  bottomBarTrailingAction,
 }) => {
   const { t } = useTranslation();
+  const isMobile = useIsMobile();
   const resolvedPlaceholder = placeholder ?? t("editor.startWritingPlaceholder");
   const {
     editor,
@@ -81,8 +89,7 @@ const TiptapEditor: React.FC<TiptapEditorProps> = ({
     pendingCreatePageTitle,
     handleConfirmCreate,
     handleCancelCreate,
-    hasThumbnail,
-    handleInsertThumbnailImage,
+    pageActionContext,
     storageSetupDialogOpen,
     setStorageSetupDialogOpen,
     handleGoToStorageSettings,
@@ -104,12 +111,35 @@ const TiptapEditor: React.FC<TiptapEditorProps> = ({
     onContentError,
     focusContentRef,
     insertAtCursorRef,
+    pageActionHubRef,
     initialContent,
     onInitialContentApplied,
     isWikiGenerating,
     wikiContentForCollab,
     onWikiContentApplied,
     pageNoteId,
+    wikiComposeHref,
+  });
+
+  // 入力バーへフォーカスを移すための imperative ハンドル（issue #928 §Cmd+K）。
+  // 入力バー側の `useEffect` がここに focus 関数を割り当てる。
+  // Imperative handle that the bar populates with a focus function (issue
+  // #928 / Cmd+K).
+  const focusInputBarRef = useRef<(() => void) | null>(null);
+
+  // `Cmd/Ctrl+Shift+L` の実体。既存のバブルメニュー実装をそのまま再利用し、
+  // 「選択範囲を Wiki Link 化」操作のロジックを 1 箇所に集約する。
+  // Cmd/Ctrl+Shift+L is wired to the existing bubble-menu conversion so the
+  // "selection → wiki link" logic lives in a single place.
+  const { convertToWikiLink } = useBubbleMenuWikiLink({ editor, pageId });
+  const focusInputBar = useCallback(() => {
+    focusInputBarRef.current?.();
+  }, []);
+  useEditorWikiLinkShortcuts({
+    editor,
+    focusInputBar,
+    convertSelectionToWikiLink: convertToWikiLink,
+    isReadOnly,
   });
 
   return (
@@ -140,7 +170,16 @@ const TiptapEditor: React.FC<TiptapEditorProps> = ({
       <EditorContent editor={editor} />
       {editor && !isReadOnly && (
         <>
-          <EditorBubbleMenu editor={editor} pageId={pageId} />
+          {/*
+            BubbleMenu はモバイルでは仮想キーボードと干渉するため非表示にし、
+            代わりにキーボード直上のシート (MobileSelectionSheet) で同等の
+            装飾アクションを提供する（issue #924 §2 / #929）。
+            The bubble menu collides with the on-screen keyboard on phones,
+            so we hide it on mobile and route the same actions through the
+            keyboard-aware sheet instead (issue #924 §2 / #929).
+          */}
+          {!isMobile && <EditorBubbleMenu editor={editor} pageId={pageId} />}
+          {isMobile && <MobileSelectionSheet editor={editor} pageId={pageId} />}
           <TableBubbleMenu editor={editor} />
         </>
       )}
@@ -194,19 +233,26 @@ const TiptapEditor: React.FC<TiptapEditorProps> = ({
         onConfirm={handleConfirmCreate}
         onCancel={handleCancelCreate}
       />
-      {showToolbar && (
-        <EditorRecommendationBar
-          pageTitle={pageTitle}
-          isReadOnly={isReadOnly}
-          hasThumbnail={hasThumbnail}
-          onSelectThumbnail={handleInsertThumbnailImage}
-        />
-      )}
+      {showToolbar && <PageActionHub ctx={pageActionContext} hubRef={pageActionHubRef} />}
       <StorageSetupDialog
         open={storageSetupDialogOpen}
         onOpenChange={setStorageSetupDialogOpen}
         onConfirm={handleGoToStorageSettings}
       />
+      {!isReadOnly && (
+        // FAB 左にピル型 Wiki Link 入力バーを常時表示する（issue #924 §2 / #926）。
+        // 役割はゴーストリンク作成 + 入力中の既存ページ候補提示の二役 UI。
+        // Always-on pill input bar mounted to the left of the FAB (issue
+        // #924 §2 / #926). Doubles as ghost-link creation and existing-link
+        // insertion via the shared suggestion popup.
+        <FloatingWikiLinkInputBar
+          editor={editor}
+          pageId={pageId}
+          pageNoteId={resolvedPageNoteId}
+          focusInputBarRef={focusInputBarRef}
+          trailingAction={bottomBarTrailingAction}
+        />
+      )}
     </div>
   );
 };
diff --git a/src/components/editor/TiptapEditor/EditorRecommendationBar.test.tsx b/src/components/editor/TiptapEditor/EditorRecommendationBar.test.tsx
deleted file mode 100644
index 78cbb60a..00000000
--- a/src/components/editor/TiptapEditor/EditorRecommendationBar.test.tsx
+++ /dev/null
@@ -1,133 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import { render, screen } from "@testing-library/react";
-import userEvent from "@testing-library/user-event";
-import { useAuth } from "@/hooks/useAuth";
-import { EditorRecommendationBar } from "./EditorRecommendationBar";
-
-vi.mock("@/hooks/useAuth", () => ({
-  useAuth: vi.fn(),
-}));
-
-const editorRecommendation: Record<string, string> = {
-  labelRecommendation: "おすすめ",
-  labelThumbnails: "サムネイル候補",
-  next: "次へ",
-  back: "戻る",
-  close: "閉じる",
-};
-vi.mock("react-i18next", () => ({
-  useTranslation: () => ({
-    t: (key: string) => {
-      if (key.startsWith("editor.recommendation.")) {
-        const sub = key.replace("editor.recommendation.", "");
-        return editorRecommendation[sub] ?? key;
-      }
-      return key;
-    },
-    i18n: { language: "ja" },
-  }),
-}));
-
-const defaultProps = {
-  pageTitle: "Test Page",
-  isReadOnly: false,
-  hasThumbnail: false,
-  onSelectThumbnail: vi.fn(),
-};
-
-describe("EditorRecommendationBar", () => {
-  beforeEach(() => {
-    vi.mocked(useAuth).mockReturnValue({
-      isSignedIn: true,
-    } as never);
-    vi.clearAllMocks();
-  });
-
-  it("renders nothing when isReadOnly is true", () => {
-    const { container } = render(<EditorRecommendationBar {...defaultProps} isReadOnly={true} />);
-    expect(container).toBeEmptyDOMElement();
-  });
-
-  it("renders nothing when hasThumbnail is true", () => {
-    const { container } = render(<EditorRecommendationBar {...defaultProps} hasThumbnail={true} />);
-    expect(container).toBeEmptyDOMElement();
-  });
-
-  it("renders bar with おすすめ and action buttons when canSearch", () => {
-    render(<EditorRecommendationBar {...defaultProps} />);
-    expect(screen.getByText("おすすめ")).toBeInTheDocument();
-    expect(screen.getByRole("button", { name: "画像を検索" })).toBeInTheDocument();
-    expect(screen.getByRole("button", { name: /AIで生成/ })).toBeInTheDocument();
-    expect(screen.getByText("タイトルから画像を検索または生成します")).toBeInTheDocument();
-  });
-
-  it("hides bar when close button is clicked", async () => {
-    const user = userEvent.setup();
-    const { container } = render(<EditorRecommendationBar {...defaultProps} />);
-    expect(screen.getByText("おすすめ")).toBeInTheDocument();
-
-    await user.click(screen.getByRole("button", { name: "閉じる" }));
-
-    expect(screen.queryByText("おすすめ")).not.toBeInTheDocument();
-    expect(container.querySelector(".fixed.bottom-0")).not.toBeInTheDocument();
-  });
-
-  it("shows 画像を検索 and 戻る after opening thumbnail picker", async () => {
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockResolvedValue({
-        ok: true,
-        json: async () => ({ items: [], nextCursor: null }),
-      }),
-    );
-    const user = userEvent.setup();
-    render(<EditorRecommendationBar {...defaultProps} />);
-
-    await user.click(screen.getByRole("button", { name: "画像を検索" }));
-
-    expect(screen.getByText("サムネイル候補")).toBeInTheDocument();
-    expect(screen.getByRole("button", { name: "戻る" })).toBeInTheDocument();
-
-    vi.unstubAllGlobals();
-  });
-
-  it("calls onSelectThumbnail when a candidate is selected", async () => {
-    const user = userEvent.setup();
-    const onSelectThumbnail = vi.fn();
-
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockResolvedValue({
-        ok: true,
-        json: async () => ({
-          items: [
-            {
-              id: "1",
-              previewUrl: "https://example.com/preview.jpg",
-              imageUrl: "https://example.com/full.jpg",
-              alt: "Alt",
-              sourceName: "Source",
-              sourceUrl: "https://example.com",
-            },
-          ],
-          nextCursor: null,
-        }),
-      }),
-    );
-
-    render(<EditorRecommendationBar {...defaultProps} onSelectThumbnail={onSelectThumbnail} />);
-    await user.click(screen.getByRole("button", { name: "画像を検索" }));
-
-    await screen.findByText("Source");
-
-    await user.click(screen.getByAltText("Alt"));
-
-    expect(onSelectThumbnail).toHaveBeenCalledWith(
-      "https://example.com/full.jpg",
-      "Alt",
-      "https://example.com/preview.jpg",
-    );
-
-    vi.unstubAllGlobals();
-  });
-});
diff --git a/src/components/editor/TiptapEditor/EditorRecommendationBar.tsx b/src/components/editor/TiptapEditor/EditorRecommendationBar.tsx
deleted file mode 100644
index 27dac388..00000000
--- a/src/components/editor/TiptapEditor/EditorRecommendationBar.tsx
+++ /dev/null
@@ -1,67 +0,0 @@
-import React from "react";
-import Container from "@/components/layout/Container";
-import type { EditorRecommendationBarProps } from "./EditorRecommendationBarTypes";
-import { useEditorRecommendationBar } from "./useEditorRecommendationBar";
-import { EditorRecommendationBarHeader } from "./EditorRecommendationBarHeader";
-import { EditorRecommendationBarActions } from "./EditorRecommendationBarActions";
-import { EditorRecommendationBarGenerating } from "./EditorRecommendationBarGenerating";
-import { EditorRecommendationBarThumbnails } from "./EditorRecommendationBarThumbnails";
-
-/**
- *
- */
-export /**
- *
- */
-const EditorRecommendationBar: React.FC<EditorRecommendationBarProps> = (props) => {
-  /**
-   *
-   */
-  const state = useEditorRecommendationBar(props);
-
-  if (!state.canSearch) return null;
-  if (state.isDismissed) return null;
-
-  return (
-    <div className="border-border bg-background/95 supports-[backdrop-filter]:bg-background/60 fixed right-0 bottom-0 left-0 z-50 border-t backdrop-blur">
-      <Container className="flex flex-col gap-2 py-2">
-        <EditorRecommendationBarHeader
-          headerLabel={state.headerLabel}
-          mode={state.mode}
-          nextCursor={state.nextCursor}
-          isLoading={state.isLoading}
-          onNextPage={state.handleNextPage}
-          onBackToActions={state.handleBackToActions}
-          onDismiss={state.dismiss}
-        />
-
-        {state.mode === "actions" && (
-          <EditorRecommendationBarActions
-            onOpenThumbnailPicker={state.handleOpenThumbnailPicker}
-            onGenerateImage={state.handleGenerateImage}
-            isLoading={state.isLoading}
-          />
-        )}
-
-        {state.mode === "generating" && (
-          <EditorRecommendationBarGenerating
-            isLoading={state.isLoading}
-            errorMessage={state.errorMessage}
-            onBackToActions={state.handleBackToActions}
-          />
-        )}
-
-        {state.mode === "thumbnails" && (
-          <EditorRecommendationBarThumbnails
-            candidates={state.candidates}
-            isLoading={state.isLoading}
-            errorMessage={state.errorMessage}
-            scrollRef={state.scrollRef}
-            onWheel={state.handleWheel}
-            onSelectCandidate={state.handleSelectCandidate}
-          />
-        )}
-      </Container>
-    </div>
-  );
-};
diff --git a/src/components/editor/TiptapEditor/EditorRecommendationBarActions.test.tsx b/src/components/editor/TiptapEditor/EditorRecommendationBarActions.test.tsx
deleted file mode 100644
index f8ba8ced..00000000
--- a/src/components/editor/TiptapEditor/EditorRecommendationBarActions.test.tsx
+++ /dev/null
@@ -1,58 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-import { render, screen } from "@testing-library/react";
-import userEvent from "@testing-library/user-event";
-import { EditorRecommendationBarActions } from "./EditorRecommendationBarActions";
-
-describe("EditorRecommendationBarActions", () => {
-  it("renders 画像を検索 and AIで生成 buttons and description", () => {
-    render(
-      <EditorRecommendationBarActions
-        onOpenThumbnailPicker={vi.fn()}
-        onGenerateImage={vi.fn()}
-        isLoading={false}
-      />,
-    );
-    expect(screen.getByRole("button", { name: "画像を検索" })).toBeInTheDocument();
-    expect(screen.getByRole("button", { name: /AIで生成/ })).toBeInTheDocument();
-    expect(screen.getByText("タイトルから画像を検索または生成します")).toBeInTheDocument();
-  });
-
-  it("calls onOpenThumbnailPicker when 画像を検索 is clicked", async () => {
-    const user = userEvent.setup();
-    const onOpenThumbnailPicker = vi.fn();
-    render(
-      <EditorRecommendationBarActions
-        onOpenThumbnailPicker={onOpenThumbnailPicker}
-        onGenerateImage={vi.fn()}
-        isLoading={false}
-      />,
-    );
-    await user.click(screen.getByRole("button", { name: "画像を検索" }));
-    expect(onOpenThumbnailPicker).toHaveBeenCalledTimes(1);
-  });
-
-  it("calls onGenerateImage when AIで生成 is clicked", async () => {
-    const user = userEvent.setup();
-    const onGenerateImage = vi.fn();
-    render(
-      <EditorRecommendationBarActions
-        onOpenThumbnailPicker={vi.fn()}
-        onGenerateImage={onGenerateImage}
-        isLoading={false}
-      />,
-    );
-    await user.click(screen.getByRole("button", { name: /AIで生成/ }));
-    expect(onGenerateImage).toHaveBeenCalledTimes(1);
-  });
-
-  it("disables AIで生成 button when isLoading", () => {
-    render(
-      <EditorRecommendationBarActions
-        onOpenThumbnailPicker={vi.fn()}
-        onGenerateImage={vi.fn()}
-        isLoading={true}
-      />,
-    );
-    expect(screen.getByRole("button", { name: /AIで生成/ })).toBeDisabled();
-  });
-});
diff --git a/src/components/editor/TiptapEditor/EditorRecommendationBarActions.tsx b/src/components/editor/TiptapEditor/EditorRecommendationBarActions.tsx
deleted file mode 100644
index 4e62a7f3..00000000
--- a/src/components/editor/TiptapEditor/EditorRecommendationBarActions.tsx
+++ /dev/null
@@ -1,39 +0,0 @@
-import React from "react";
-import { Image as ImageIcon, Wand2 } from "lucide-react";
-import { Button } from "@zedi/ui";
-
-interface EditorRecommendationBarActionsProps {
-  onOpenThumbnailPicker: () => void;
-  onGenerateImage: () => void;
-  isLoading: boolean;
-}
-
-/**
- *
- */
-export /**
- *
- */
-const EditorRecommendationBarActions: React.FC<EditorRecommendationBarActionsProps> = ({
-  onOpenThumbnailPicker,
-  onGenerateImage,
-  isLoading,
-}) => (
-  <div className="flex items-center gap-2">
-    <Button type="button" size="sm" variant="outline" onClick={onOpenThumbnailPicker}>
-      <ImageIcon className="mr-1 h-4 w-4" />
-      画像を検索
-    </Button>
-    <Button
-      type="button"
-      size="sm"
-      variant="outline"
-      onClick={onGenerateImage}
-      disabled={isLoading}
-    >
-      <Wand2 className="mr-1 h-4 w-4" />
-      AIで生成
-    </Button>
-    <span className="text-muted-foreground text-xs">タイトルから画像を検索または生成します</span>
-  </div>
-);
diff --git a/src/components/editor/TiptapEditor/EditorRecommendationBarGenerating.test.tsx b/src/components/editor/TiptapEditor/EditorRecommendationBarGenerating.test.tsx
deleted file mode 100644
index d064f473..00000000
--- a/src/components/editor/TiptapEditor/EditorRecommendationBarGenerating.test.tsx
+++ /dev/null
@@ -1,42 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-import { render, screen } from "@testing-library/react";
-import userEvent from "@testing-library/user-event";
-import { EditorRecommendationBarGenerating } from "./EditorRecommendationBarGenerating";
-
-describe("EditorRecommendationBarGenerating", () => {
-  it("shows loading message when isLoading", () => {
-    render(
-      <EditorRecommendationBarGenerating
-        isLoading={true}
-        errorMessage={null}
-        onBackToActions={vi.fn()}
-      />,
-    );
-    expect(screen.getByText("画像を生成中...")).toBeInTheDocument();
-  });
-
-  it("shows error message when errorMessage is set", () => {
-    render(
-      <EditorRecommendationBarGenerating
-        isLoading={false}
-        errorMessage="エラーが発生しました"
-        onBackToActions={vi.fn()}
-      />,
-    );
-    expect(screen.getByText("エラーが発生しました")).toBeInTheDocument();
-  });
-
-  it("shows 戻る button when not loading and no error", async () => {
-    const onBackToActions = vi.fn();
-    render(
-      <EditorRecommendationBarGenerating
-        isLoading={false}
-        errorMessage={null}
-        onBackToActions={onBackToActions}
-      />,
-    );
-    expect(screen.getByRole("button", { name: "戻る" })).toBeInTheDocument();
-    await userEvent.setup().click(screen.getByRole("button", { name: "戻る" }));
-    expect(onBackToActions).toHaveBeenCalledTimes(1);
-  });
-});
diff --git a/src/components/editor/TiptapEditor/EditorRecommendationBarGenerating.tsx b/src/components/editor/TiptapEditor/EditorRecommendationBarGenerating.tsx
deleted file mode 100644
index e327dfac..00000000
--- a/src/components/editor/TiptapEditor/EditorRecommendationBarGenerating.tsx
+++ /dev/null
@@ -1,39 +0,0 @@
-import React from "react";
-import { ChevronLeft, Loader2 } from "lucide-react";
-import { Button } from "@zedi/ui";
-
-interface EditorRecommendationBarGeneratingProps {
-  isLoading: boolean;
-  errorMessage: string | null;
-  onBackToActions: () => void;
-}
-
-/**
- *
- */
-export /**
- *
- */
-const EditorRecommendationBarGenerating: React.FC<EditorRecommendationBarGeneratingProps> = ({
-  isLoading,
-  errorMessage,
-  onBackToActions,
-}) => (
-  <div className="space-y-2">
-    {isLoading && (
-      <div className="text-muted-foreground flex items-center gap-2 text-xs">
-        <Loader2 className="h-4 w-4 animate-spin" />
-        画像を生成中...
-      </div>
-    )}
-    {errorMessage && <div className="text-destructive text-xs">{errorMessage}</div>}
-    {!isLoading && (
-      <div className="flex items-center gap-2">
-        <Button type="button" size="sm" variant="ghost" onClick={onBackToActions}>
-          <ChevronLeft className="mr-1 h-4 w-4" />
-          戻る
-        </Button>
-      </div>
-    )}
-  </div>
-);
diff --git a/src/components/editor/TiptapEditor/EditorRecommendationBarHeader.test.tsx b/src/components/editor/TiptapEditor/EditorRecommendationBarHeader.test.tsx
deleted file mode 100644
index f077cabb..00000000
--- a/src/components/editor/TiptapEditor/EditorRecommendationBarHeader.test.tsx
+++ /dev/null
@@ -1,87 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-import { render, screen } from "@testing-library/react";
-import userEvent from "@testing-library/user-event";
-import { EditorRecommendationBarHeader } from "./EditorRecommendationBarHeader";
-
-const editorRecommendation: Record<string, string> = {
-  next: "次へ",
-  back: "戻る",
-  close: "閉じる",
-};
-vi.mock("react-i18next", () => ({
-  useTranslation: () => ({
-    t: (key: string) => {
-      if (key.startsWith("editor.recommendation.")) {
-        const sub = key.replace("editor.recommendation.", "");
-        return editorRecommendation[sub] ?? key;
-      }
-      return key;
-    },
-    i18n: { language: "ja" },
-  }),
-}));
-
-describe("EditorRecommendationBarHeader", () => {
-  const defaultProps = {
-    headerLabel: "おすすめ",
-    mode: "actions" as const,
-    nextCursor: null as string | null,
-    isLoading: false,
-    onNextPage: vi.fn(),
-    onBackToActions: vi.fn(),
-    onDismiss: vi.fn(),
-  };
-
-  it("renders header label", () => {
-    render(<EditorRecommendationBarHeader {...defaultProps} />);
-    expect(screen.getByText("おすすめ")).toBeInTheDocument();
-  });
-
-  it("shows 次へ and 戻る when mode is thumbnails", () => {
-    render(
-      <EditorRecommendationBarHeader {...defaultProps} mode="thumbnails" nextCursor="cursor1" />,
-    );
-    expect(screen.getByRole("button", { name: "次へ" })).toBeInTheDocument();
-    expect(screen.getByRole("button", { name: "戻る" })).toBeInTheDocument();
-  });
-
-  it("disables 次へ when nextCursor is null or isLoading", () => {
-    const { rerender } = render(
-      <EditorRecommendationBarHeader {...defaultProps} mode="thumbnails" nextCursor={null} />,
-    );
-    expect(screen.getByRole("button", { name: "次へ" })).toBeDisabled();
-
-    rerender(
-      <EditorRecommendationBarHeader
-        {...defaultProps}
-        mode="thumbnails"
-        nextCursor="c"
-        isLoading={true}
-      />,
-    );
-    expect(screen.getByRole("button", { name: "次へ" })).toBeDisabled();
-  });
-
-  it("calls onDismiss when 閉じる is clicked", async () => {
-    const user = userEvent.setup();
-    const onDismiss = vi.fn();
-    render(<EditorRecommendationBarHeader {...defaultProps} onDismiss={onDismiss} />);
-    await user.click(screen.getByRole("button", { name: "閉じる" }));
-    expect(onDismiss).toHaveBeenCalledTimes(1);
-  });
-
-  it("calls onBackToActions when 戻る is clicked", async () => {
-    const user = userEvent.setup();
-    const onBackToActions = vi.fn();
-    render(
-      <EditorRecommendationBarHeader
-        {...defaultProps}
-        mode="thumbnails"
-        nextCursor="c"
-        onBackToActions={onBackToActions}
-      />,
-    );
-    await user.click(screen.getByRole("button", { name: "戻る" }));
-    expect(onBackToActions).toHaveBeenCalledTimes(1);
-  });
-});
diff --git a/src/components/editor/TiptapEditor/EditorRecommendationBarHeader.tsx b/src/components/editor/TiptapEditor/EditorRecommendationBarHeader.tsx
deleted file mode 100644
index b67b5fb0..00000000
--- a/src/components/editor/TiptapEditor/EditorRecommendationBarHeader.tsx
+++ /dev/null
@@ -1,74 +0,0 @@
-import React from "react";
-import { useTranslation } from "react-i18next";
-import { ChevronLeft, Sparkles, X } from "lucide-react";
-import { Button } from "@zedi/ui";
-import type { RecommendationMode } from "./EditorRecommendationBarTypes";
-
-interface EditorRecommendationBarHeaderProps {
-  headerLabel: string;
-  mode: RecommendationMode;
-  nextCursor: string | null;
-  isLoading: boolean;
-  onNextPage: () => void;
-  onBackToActions: () => void;
-  onDismiss: () => void;
-}
-
-/**
- *
- */
-export /**
- *
- */
-const EditorRecommendationBarHeader: React.FC<EditorRecommendationBarHeaderProps> = ({
-  headerLabel,
-  mode,
-  nextCursor,
-  isLoading,
-  onNextPage,
-  onBackToActions,
-  onDismiss,
-}) => {
-  /**
-   *
-   */
-  const { t } = useTranslation();
-  return (
-    <div className="flex items-center justify-between">
-      <div className="text-muted-foreground flex items-center gap-2 text-xs">
-        <Sparkles className="h-4 w-4" />
-        <span>{headerLabel}</span>
-      </div>
-      <div className="flex items-center gap-2">
-        {mode === "thumbnails" && (
-          <>
-            <Button
-              type="button"
-              size="sm"
-              variant="outline"
-              onClick={onNextPage}
-              disabled={!nextCursor || isLoading}
-            >
-              {t("editor.recommendation.next")}
-            </Button>
-            <Button type="button" size="sm" variant="ghost" onClick={onBackToActions}>
-              <ChevronLeft className="mr-1 h-4 w-4" />
-              {t("editor.recommendation.back")}
-            </Button>
-          </>
-        )}
-        {(mode === "actions" || mode === "thumbnails") && (
-          <Button
-            type="button"
-            size="sm"
-            variant="ghost"
-            onClick={onDismiss}
-            aria-label={t("editor.recommendation.close")}
-          >
-            <X className="h-4 w-4" />
-          </Button>
-        )}
-      </div>
-    </div>
-  );
-};
diff --git a/src/components/editor/TiptapEditor/EditorRecommendationBarThumbnails.test.tsx b/src/components/editor/TiptapEditor/EditorRecommendationBarThumbnails.test.tsx
deleted file mode 100644
index 38cfcdd7..00000000
--- a/src/components/editor/TiptapEditor/EditorRecommendationBarThumbnails.test.tsx
+++ /dev/null
@@ -1,98 +0,0 @@
-import React from "react";
-import { describe, it, expect, vi } from "vitest";
-import { render, screen } from "@testing-library/react";
-import userEvent from "@testing-library/user-event";
-import { EditorRecommendationBarThumbnails } from "./EditorRecommendationBarThumbnails";
-import type { ThumbnailCandidate } from "./EditorRecommendationBarTypes";
-
-const createRef = () => React.createRef<HTMLDivElement | null>();
-
-describe("EditorRecommendationBarThumbnails", () => {
-  const defaultProps = {
-    candidates: [] as ThumbnailCandidate[],
-    isLoading: false,
-    errorMessage: null as string | null,
-    scrollRef: createRef(),
-    onWheel: vi.fn(),
-    onSelectCandidate: vi.fn(),
-  };
-
-  it("shows loading message when isLoading", () => {
-    render(<EditorRecommendationBarThumbnails {...defaultProps} isLoading={true} />);
-    expect(screen.getByText("画像を検索中...")).toBeInTheDocument();
-  });
-
-  it("shows error message when errorMessage is set", () => {
-    render(
-      <EditorRecommendationBarThumbnails {...defaultProps} errorMessage="検索に失敗しました" />,
-    );
-    expect(screen.getByText("検索に失敗しました")).toBeInTheDocument();
-  });
-
-  it("shows empty state when no candidates", () => {
-    render(<EditorRecommendationBarThumbnails {...defaultProps} />);
-    expect(screen.getByText("候補が見つかりませんでした")).toBeInTheDocument();
-  });
-
-  it("renders candidates and calls onSelectCandidate when one is clicked", async () => {
-    const user = userEvent.setup();
-    const onSelectCandidate = vi.fn();
-    const candidates: ThumbnailCandidate[] = [
-      {
-        id: "1",
-        previewUrl: "https://example.com/p.jpg",
-        imageUrl: "https://example.com/full.jpg",
-        alt: "Test alt",
-        sourceName: "Source",
-        sourceUrl: "https://example.com/source",
-      },
-    ];
-    render(
-      <EditorRecommendationBarThumbnails
-        {...defaultProps}
-        candidates={candidates}
-        onSelectCandidate={onSelectCandidate}
-      />,
-    );
-    expect(screen.getByAltText("Test alt")).toBeInTheDocument();
-    expect(screen.getByText("Source")).toBeInTheDocument();
-    await user.click(screen.getByAltText("Test alt"));
-    expect(onSelectCandidate).toHaveBeenCalledWith(candidates[0]);
-  });
-
-  it("renders author name as link when authorUrl is set", () => {
-    const candidates: ThumbnailCandidate[] = [
-      {
-        id: "1",
-        previewUrl: "https://p",
-        imageUrl: "https://img",
-        alt: "Alt",
-        sourceName: "Source",
-        sourceUrl: "https://s",
-        authorName: "Author",
-        authorUrl: "https://author.com",
-      },
-    ];
-    render(<EditorRecommendationBarThumbnails {...defaultProps} candidates={candidates} />);
-    const authorLink = screen.getByRole("link", { name: "Author" });
-    expect(authorLink).toBeInTheDocument();
-    expect(authorLink).toHaveAttribute("href", "https://author.com");
-  });
-
-  it("renders author name as span when authorUrl is not set", () => {
-    const candidates: ThumbnailCandidate[] = [
-      {
-        id: "1",
-        previewUrl: "https://p",
-        imageUrl: "https://img",
-        alt: "Alt",
-        sourceName: "Source",
-        sourceUrl: "https://s",
-        authorName: "Author Only",
-      },
-    ];
-    render(<EditorRecommendationBarThumbnails {...defaultProps} candidates={candidates} />);
-    expect(screen.getByText("Author Only")).toBeInTheDocument();
-    expect(screen.queryByRole("link", { name: "Author Only" })).not.toBeInTheDocument();
-  });
-});
diff --git a/src/components/editor/TiptapEditor/EditorRecommendationBarThumbnails.tsx b/src/components/editor/TiptapEditor/EditorRecommendationBarThumbnails.tsx
deleted file mode 100644
index 03c4d924..00000000
--- a/src/components/editor/TiptapEditor/EditorRecommendationBarThumbnails.tsx
+++ /dev/null
@@ -1,107 +0,0 @@
-import React from "react";
-import { Loader2 } from "lucide-react";
-import { sanitizeLinkUrl } from "@/lib/markdownToTiptapHelpers";
-import type { ThumbnailCandidate } from "./EditorRecommendationBarTypes";
-
-interface EditorRecommendationBarThumbnailsProps {
-  candidates: ThumbnailCandidate[];
-  isLoading: boolean;
-  errorMessage: string | null;
-  scrollRef: React.RefObject<HTMLDivElement | null>;
-  onWheel: (event: React.WheelEvent<HTMLDivElement>) => void;
-  onSelectCandidate: (candidate: ThumbnailCandidate) => void;
-}
-
-/**
- *
- */
-export /**
- *
- */
-const EditorRecommendationBarThumbnails: React.FC<EditorRecommendationBarThumbnailsProps> = ({
-  candidates,
-  isLoading,
-  errorMessage,
-  scrollRef,
-  onWheel,
-  onSelectCandidate,
-}) => (
-  <div className="space-y-2">
-    {isLoading && (
-      <div className="text-muted-foreground flex items-center gap-2 text-xs">
-        <Loader2 className="h-4 w-4 animate-spin" />
-        画像を検索中...
-      </div>
-    )}
-    {errorMessage && <div className="text-destructive text-xs">{errorMessage}</div>}
-    {!isLoading && !errorMessage && candidates.length === 0 && (
-      <div className="text-muted-foreground text-xs">候補が見つかりませんでした</div>
-    )}
-
-    {candidates.length > 0 && (
-      <div
-        ref={scrollRef}
-        onWheel={onWheel}
-        className="flex snap-x snap-mandatory gap-3 overflow-x-auto pb-1"
-      >
-        {candidates.map((candidate) => {
-          /**
-           *
-           */
-          const safeAuthorUrl = candidate.authorUrl ? sanitizeLinkUrl(candidate.authorUrl) : null;
-          /**
-           *
-           */
-          const safeSourceUrl = candidate.sourceUrl ? sanitizeLinkUrl(candidate.sourceUrl) : null;
-          return (
-            <div key={candidate.id} className="flex shrink-0 snap-start flex-col gap-1 text-left">
-              <button
-                type="button"
-                onClick={() => onSelectCandidate(candidate)}
-                className="bg-background rounded-md border p-1 text-left"
-              >
-                <img
-                  src={candidate.previewUrl}
-                  alt={candidate.alt}
-                  className="h-16 w-auto rounded object-cover sm:h-24"
-                  loading="lazy"
-                />
-              </button>
-              <div className="text-muted-foreground text-[10px]">
-                {candidate.authorName ? (
-                  <>
-                    {safeAuthorUrl ? (
-                      <a
-                        href={safeAuthorUrl}
-                        target="_blank"
-                        rel="noopener noreferrer"
-                        className="underline underline-offset-2"
-                      >
-                        {candidate.authorName}
-                      </a>
-                    ) : (
-                      <span>{candidate.authorName}</span>
-                    )}{" "}
-                    /{" "}
-                  </>
-                ) : null}
-                {safeSourceUrl ? (
-                  <a
-                    href={safeSourceUrl}
-                    target="_blank"
-                    rel="noopener noreferrer"
-                    className="underline underline-offset-2"
-                  >
-                    {candidate.sourceName}
-                  </a>
-                ) : (
-                  <span>{candidate.sourceName}</span>
-                )}
-              </div>
-            </div>
-          );
-        })}
-      </div>
-    )}
-  </div>
-);
diff --git a/src/components/editor/TiptapEditor/EditorRecommendationBarTypes.ts b/src/components/editor/TiptapEditor/EditorRecommendationBarTypes.ts
deleted file mode 100644
index 5c866de6..00000000
--- a/src/components/editor/TiptapEditor/EditorRecommendationBarTypes.ts
+++ /dev/null
@@ -1,19 +0,0 @@
-export interface ThumbnailCandidate {
-  id: string;
-  previewUrl: string;
-  imageUrl: string;
-  alt: string;
-  sourceName: string;
-  sourceUrl: string;
-  authorName?: string;
-  authorUrl?: string;
-}
-
-export interface EditorRecommendationBarProps {
-  pageTitle: string;
-  isReadOnly: boolean;
-  hasThumbnail: boolean;
-  onSelectThumbnail: (imageUrl: string, alt: string, previewUrl?: string) => void;
-}
-
-export type RecommendationMode = "actions" | "thumbnails" | "generating";
diff --git a/src/components/editor/TiptapEditor/MobileSelectionSheet.test.tsx b/src/components/editor/TiptapEditor/MobileSelectionSheet.test.tsx
new file mode 100644
index 00000000..45fe3b13
--- /dev/null
+++ b/src/components/editor/TiptapEditor/MobileSelectionSheet.test.tsx
@@ -0,0 +1,252 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen, act, fireEvent } from "@testing-library/react";
+import type { Editor } from "@tiptap/core";
+
+// `react-i18next` を素通りモック。
+// Pass-through i18n mock.
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+// `useBubbleMenuWikiLink` は内部で API 問い合わせが走るためここでは無効化し、
+// テストの主目的（表示/非表示・ボタン配線）に集中する。
+// Stub out wiki-link existence checking so we can focus on visibility and
+// the button wiring without spinning up the page-queries hook.
+vi.mock("@/hooks/usePageQueries", () => ({
+  useWikiLinkExistsChecker: () => ({
+    checkExistence: vi.fn().mockResolvedValue({
+      pageTitles: new Set(),
+      referencedTitles: new Set(),
+      pageTitleToId: new Map(),
+    }),
+  }),
+}));
+
+// キーボードオフセットは別の hook で検証済みのため、本コンポーネントの
+// テストでは固定値を返すモックに置き換える。
+// Keyboard offset is exercised by its own hook test; here we stub it so we
+// can assert the sheet just applies the value verbatim.
+let mockKeyboardOffset = 0;
+vi.mock("@/hooks/useVirtualKeyboardOffset", () => ({
+  useVirtualKeyboardOffset: () => mockKeyboardOffset,
+}));
+
+import { MobileSelectionSheet } from "./MobileSelectionSheet";
+
+interface EditorMockOptions {
+  selectionEmpty?: boolean;
+  hasFocus?: boolean;
+  isEditable?: boolean;
+  activeMarks?: ReadonlySet<string>;
+}
+
+/**
+ * 表示判定とボタン配線を検証するための最小エディタモック。
+ * - `on/off` で `selectionUpdate` / `focus` / `blur` を購読できる
+ * - `setActive`/`setHasFocus` でテストから内部状態を切り替えて `fireEvents` で通知
+ * - `chain().focus().toggleX().run()` のチェーンを vi.fn() で観測する
+ *
+ * Minimal editor mock for the visibility logic and button wiring. Supports
+ * subscribing to selectionUpdate / focus / blur, mutating state, and
+ * observing chain command invocations via vi.fn().
+ */
+function createMockEditor(initial: EditorMockOptions = {}) {
+  let selectionEmpty = initial.selectionEmpty ?? false;
+  let hasFocus = initial.hasFocus ?? true;
+  let isEditable = initial.isEditable ?? true;
+  let activeMarks = new Set<string>(initial.activeMarks ?? []);
+  const listeners = new Map<string, Set<() => void>>();
+
+  const run = vi.fn();
+  const chainable = {
+    focus: vi.fn(() => chainable),
+    toggleBold: vi.fn(() => chainable),
+    toggleItalic: vi.fn(() => chainable),
+    toggleStrike: vi.fn(() => chainable),
+    toggleCode: vi.fn(() => chainable),
+    deleteRange: vi.fn(() => chainable),
+    insertContent: vi.fn(() => chainable),
+    unsetWikiLink: vi.fn(() => chainable),
+    run,
+  };
+
+  const editor = {
+    isActive: (name: string) => activeMarks.has(name),
+    get isEditable() {
+      return isEditable;
+    },
+    state: {
+      get selection() {
+        return { empty: selectionEmpty, from: 0, to: 0 };
+      },
+      doc: { textBetween: () => "selected" },
+    },
+    view: { hasFocus: () => hasFocus },
+    chain: () => chainable,
+    on(event: string, cb: () => void) {
+      let set = listeners.get(event);
+      if (!set) {
+        set = new Set();
+        listeners.set(event, set);
+      }
+      set.add(cb);
+    },
+    off(event: string, cb: () => void) {
+      listeners.get(event)?.delete(cb);
+    },
+  } as unknown as Editor;
+
+  const fire = (event: string) => {
+    const set = listeners.get(event);
+    if (!set) return;
+    for (const cb of set) cb();
+  };
+
+  return {
+    editor,
+    chainable,
+    runMock: run,
+    setSelectionEmpty(v: boolean) {
+      selectionEmpty = v;
+    },
+    setHasFocus(v: boolean) {
+      hasFocus = v;
+    },
+    setIsEditable(v: boolean) {
+      isEditable = v;
+    },
+    setActiveMarks(marks: Iterable<string>) {
+      activeMarks = new Set(marks);
+    },
+    fire,
+    listenerCount(event: string) {
+      return listeners.get(event)?.size ?? 0;
+    },
+  };
+}
+
+describe("MobileSelectionSheet", () => {
+  beforeEach(() => {
+    mockKeyboardOffset = 0;
+  });
+
+  it("選択が空かつ wikiLink でないときは描画しない / does not render with empty non-wikiLink selection", () => {
+    const m = createMockEditor({ selectionEmpty: true, hasFocus: true });
+    render(<MobileSelectionSheet editor={m.editor} />);
+    expect(screen.queryByTestId("mobile-selection-sheet")).not.toBeInTheDocument();
+  });
+
+  it("選択があるときに描画する / renders when there is a non-empty selection", () => {
+    const m = createMockEditor({ selectionEmpty: false, hasFocus: true });
+    render(<MobileSelectionSheet editor={m.editor} />);
+    expect(screen.getByTestId("mobile-selection-sheet")).toBeInTheDocument();
+  });
+
+  it("選択が空でも wikiLink アクティブなら描画する / shows on caret inside a wikiLink", () => {
+    const m = createMockEditor({
+      selectionEmpty: true,
+      hasFocus: true,
+      activeMarks: new Set(["wikiLink"]),
+    });
+    render(<MobileSelectionSheet editor={m.editor} />);
+    expect(screen.getByTestId("mobile-selection-sheet")).toBeInTheDocument();
+  });
+
+  it("コードブロック内では描画しない / hides while caret is inside a codeBlock", () => {
+    const m = createMockEditor({
+      selectionEmpty: false,
+      hasFocus: true,
+      activeMarks: new Set(["codeBlock"]),
+    });
+    render(<MobileSelectionSheet editor={m.editor} />);
+    expect(screen.queryByTestId("mobile-selection-sheet")).not.toBeInTheDocument();
+  });
+
+  it("エディタが編集不可なら描画しない / hides while the editor is not editable", () => {
+    const m = createMockEditor({ selectionEmpty: false, isEditable: false });
+    render(<MobileSelectionSheet editor={m.editor} />);
+    expect(screen.queryByTestId("mobile-selection-sheet")).not.toBeInTheDocument();
+  });
+
+  it("選択解除イベントで閉じる / closes when the user clears the selection", () => {
+    const m = createMockEditor({ selectionEmpty: false, hasFocus: true });
+    render(<MobileSelectionSheet editor={m.editor} />);
+    expect(screen.getByTestId("mobile-selection-sheet")).toBeInTheDocument();
+
+    act(() => {
+      m.setSelectionEmpty(true);
+      m.fire("selectionUpdate");
+    });
+
+    expect(screen.queryByTestId("mobile-selection-sheet")).not.toBeInTheDocument();
+  });
+
+  it("blur で閉じ、focus で再表示する / hides on blur and shows again on focus", () => {
+    const m = createMockEditor({ selectionEmpty: false, hasFocus: true });
+    render(<MobileSelectionSheet editor={m.editor} />);
+    expect(screen.getByTestId("mobile-selection-sheet")).toBeInTheDocument();
+
+    act(() => {
+      m.setHasFocus(false);
+      m.fire("blur");
+    });
+    expect(screen.queryByTestId("mobile-selection-sheet")).not.toBeInTheDocument();
+
+    act(() => {
+      m.setHasFocus(true);
+      m.fire("focus");
+    });
+    expect(screen.getByTestId("mobile-selection-sheet")).toBeInTheDocument();
+  });
+
+  it("unmount でエディタリスナーを解除する / detaches editor listeners on unmount", () => {
+    const m = createMockEditor({ selectionEmpty: false });
+    const { unmount } = render(<MobileSelectionSheet editor={m.editor} />);
+    expect(m.listenerCount("selectionUpdate")).toBeGreaterThan(0);
+    unmount();
+    expect(m.listenerCount("selectionUpdate")).toBe(0);
+    expect(m.listenerCount("focus")).toBe(0);
+    expect(m.listenerCount("blur")).toBe(0);
+  });
+
+  it("editor が null のときは何も描画しない / renders nothing when editor is null", () => {
+    render(<MobileSelectionSheet editor={null} />);
+    expect(screen.queryByTestId("mobile-selection-sheet")).not.toBeInTheDocument();
+  });
+
+  it("キーボード高さ分だけ bottom をオフセットする / lifts the sheet by the keyboard offset", () => {
+    mockKeyboardOffset = 320;
+    const m = createMockEditor({ selectionEmpty: false, hasFocus: true });
+    render(<MobileSelectionSheet editor={m.editor} />);
+    const sheet = screen.getByTestId("mobile-selection-sheet");
+    expect(sheet.style.bottom).toBe("320px");
+  });
+
+  it("Bold / Italic / Strike / Code / WikiLink の 5 アクションを描画する / renders the five required actions", () => {
+    const m = createMockEditor({ selectionEmpty: false, hasFocus: true });
+    render(<MobileSelectionSheet editor={m.editor} />);
+    expect(screen.getByRole("button", { name: /bold/i })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /italic/i })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /strike/i })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /code/i })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /wiki link/i })).toBeInTheDocument();
+  });
+
+  it("Bold ボタンで toggleBold が呼ばれる / clicking Bold runs toggleBold", () => {
+    const m = createMockEditor({ selectionEmpty: false, hasFocus: true });
+    render(<MobileSelectionSheet editor={m.editor} />);
+    fireEvent.click(screen.getByRole("button", { name: /bold/i }));
+    expect(m.chainable.toggleBold).toHaveBeenCalled();
+    expect(m.runMock).toHaveBeenCalled();
+  });
+
+  it("wikiLink アクティブ時は解除ボタンを出す / shows the unset button when caret is inside a wikiLink", () => {
+    const m = createMockEditor({
+      selectionEmpty: true,
+      hasFocus: true,
+      activeMarks: new Set(["wikiLink"]),
+    });
+    render(<MobileSelectionSheet editor={m.editor} />);
+    expect(screen.getByRole("button", { name: /unset wiki link/i })).toBeInTheDocument();
+  });
+});
diff --git a/src/components/editor/TiptapEditor/MobileSelectionSheet.tsx b/src/components/editor/TiptapEditor/MobileSelectionSheet.tsx
new file mode 100644
index 00000000..db5796c2
--- /dev/null
+++ b/src/components/editor/TiptapEditor/MobileSelectionSheet.tsx
@@ -0,0 +1,166 @@
+import React, { useCallback } from "react";
+import type { Editor } from "@tiptap/core";
+import { Bold, Italic, Strikethrough, Code, Link2, Link2Off } from "lucide-react";
+import { useVirtualKeyboardOffset } from "@/hooks/useVirtualKeyboardOffset";
+import { BubbleMenuButton } from "./BubbleMenuButton";
+import { useBubbleMenuWikiLink } from "./useBubbleMenuWikiLink";
+import { useMobileSelectionVisible } from "./useMobileSelectionVisible";
+
+/**
+ * `MobileSelectionSheet` の props。モバイルで本文を選択中のとき、画面下端
+ * （キーボードがあればその直上）にシートを表示するために、操作対象の
+ * エディタと現在のページ id を受け取る。`pageId` は WikiLink 変換時の
+ * `referenced` 判定 / 自己参照除外に使う。
+ *
+ * Props for {@link MobileSelectionSheet}. The host (`TiptapEditor`) mounts
+ * the sheet only on mobile and passes the editor plus the editing page id.
+ * `pageId` is forwarded to the wiki-link converter so the resulting mark
+ * carries the correct `referenced` flag and skips self-references.
+ */
+export interface MobileSelectionSheetProps {
+  /** 操作対象のエディタ。`null` の間は何も描画しない。 / Target editor; renders nothing while `null`. */
+  editor: Editor | null;
+  /** 現在のページ id。WikiLink 変換時の参照スコープに使う。 / Current page id used by the wiki-link converter. */
+  pageId?: string;
+}
+
+/**
+ * モバイルで本文を選択中のとき、キーボード直上に固定表示するシート。
+ * デスクトップの `EditorBubbleMenu` は仮想キーボードと干渉するため
+ * モバイルでは非表示にし、その代替としてこのシートを表示する
+ * （issue #924 §2 / #929）。
+ *
+ * 表示条件は `EditorBubbleMenu` の `shouldShow` と同一で、選択が空で
+ * かつ `wikiLink` マーク外、または `codeBlock` 内、または編集不可・
+ * 非フォーカスの場合は描画しない（`useMobileSelectionVisible` に委譲）。
+ *
+ * 仮想キーボードの追従は `useVirtualKeyboardOffset` を使い、シートが
+ * 表示されている間だけ `visualViewport` のリスナーを登録する
+ * （issue #927 と同じ仕組み）。
+ *
+ * 提供アクション（最小セット）: Wiki Link 化（または解除）/ Bold /
+ * Italic / Code / Strike。最終的なボタン一覧は要望に応じて段階的に
+ * 拡張する想定。
+ *
+ * Sheet pinned to the bottom edge (and tracking the virtual keyboard via
+ * `visualViewport`) that replaces the desktop bubble menu on mobile. The
+ * bubble menu collides with the on-screen keyboard on phones, so it is
+ * hidden on mobile and this sheet takes over for the same set of editing
+ * actions (issue #924 §2 / #929). Visibility mirrors the bubble menu's
+ * `shouldShow` predicate (see `useMobileSelectionVisible`). Initial action
+ * set per the issue: convert/unset wiki link plus Bold / Italic / Code /
+ * Strike — additional toolbar items can be folded in as the UX evolves.
+ */
+export const MobileSelectionSheet: React.FC<MobileSelectionSheetProps> = ({ editor, pageId }) => {
+  const visible = useMobileSelectionVisible(editor);
+  const keyboardOffset = useVirtualKeyboardOffset(visible);
+  const { isWikiLinkSelection, convertToWikiLink, unsetWikiLink, isConverting } =
+    useBubbleMenuWikiLink({ editor, pageId });
+
+  const toggleBold = useCallback(() => {
+    if (!editor) return;
+    editor.chain().focus().toggleBold().run();
+  }, [editor]);
+
+  const toggleItalic = useCallback(() => {
+    if (!editor) return;
+    editor.chain().focus().toggleItalic().run();
+  }, [editor]);
+
+  const toggleStrike = useCallback(() => {
+    if (!editor) return;
+    editor.chain().focus().toggleStrike().run();
+  }, [editor]);
+
+  const toggleCode = useCallback(() => {
+    if (!editor) return;
+    editor.chain().focus().toggleCode().run();
+  }, [editor]);
+
+  if (!editor || !visible) return null;
+
+  // キーボードが出ているときは safe-area 余白は不要（キーボードが既に
+  // その領域を占有しているため）。0.25rem だけ視覚的なすき間を確保。
+  // When the keyboard is up, the safe-area padding is hidden behind the
+  // keyboard anyway; collapse it to a small gap to keep the sheet pinned
+  // to the keyboard's top edge.
+  const isKeyboardOpen = keyboardOffset > 0;
+  const bottomStyle = isKeyboardOpen ? `${keyboardOffset}px` : undefined;
+  const paddingBottomStyle = isKeyboardOpen
+    ? "0.25rem"
+    : "calc(env(safe-area-inset-bottom) + var(--app-bottom-nav-height, 0px) + 0.25rem)";
+
+  return (
+    <div
+      data-testid="mobile-selection-sheet"
+      role="toolbar"
+      aria-label="モバイル選択シート"
+      className="border-border bg-popover fixed inset-x-0 z-40 flex items-center justify-center gap-1 border-t px-2 pt-1 shadow-[0_-4px_12px_rgba(0,0,0,0.08)]"
+      style={{
+        bottom: bottomStyle,
+        paddingBottom: paddingBottomStyle,
+      }}
+    >
+      <BubbleMenuButton
+        onClick={toggleBold}
+        isActive={editor.isActive("bold")}
+        aria-label="Bold"
+        title="Bold"
+      >
+        <Bold className="h-5 w-5" />
+      </BubbleMenuButton>
+
+      <BubbleMenuButton
+        onClick={toggleItalic}
+        isActive={editor.isActive("italic")}
+        aria-label="Italic"
+        title="Italic"
+      >
+        <Italic className="h-5 w-5" />
+      </BubbleMenuButton>
+
+      <BubbleMenuButton
+        onClick={toggleStrike}
+        isActive={editor.isActive("strike")}
+        aria-label="Strike"
+        title="Strike"
+      >
+        <Strikethrough className="h-5 w-5" />
+      </BubbleMenuButton>
+
+      <BubbleMenuButton
+        onClick={toggleCode}
+        isActive={editor.isActive("code")}
+        aria-label="Code"
+        title="Inline code"
+      >
+        <Code className="h-5 w-5" />
+      </BubbleMenuButton>
+
+      <div className="bg-border mx-1 h-5 w-px" />
+
+      {isWikiLinkSelection ? (
+        <BubbleMenuButton
+          onClick={unsetWikiLink}
+          isActive
+          aria-label="Unset Wiki Link"
+          title="Unset Wiki Link"
+        >
+          <Link2Off className="h-5 w-5" />
+        </BubbleMenuButton>
+      ) : (
+        <BubbleMenuButton
+          onClick={convertToWikiLink}
+          isActive={false}
+          disabled={isConverting}
+          aria-label="Wiki Link"
+          title="Convert to Wiki Link"
+        >
+          <Link2 className="h-5 w-5" />
+        </BubbleMenuButton>
+      )}
+    </div>
+  );
+};
+
+export default MobileSelectionSheet;
diff --git a/src/components/editor/TiptapEditor/WikiLinkSuggestionLayer.tsx b/src/components/editor/TiptapEditor/WikiLinkSuggestionLayer.tsx
index 2ad47c0a..7c06287e 100644
--- a/src/components/editor/TiptapEditor/WikiLinkSuggestionLayer.tsx
+++ b/src/components/editor/TiptapEditor/WikiLinkSuggestionLayer.tsx
@@ -27,13 +27,18 @@ interface WikiLinkSuggestionLayerProps {
 }
 
 /**
- * WikiLink サジェスト UI のフローティング層。`useWikiLinkCandidates` で
- * スコープ（個人 / ノート）に応じた候補ページを取得し、`WikiLinkSuggestion`
- * に渡す。Issue #713 Phase 4。
+ * WikiLink サジェスト UI のフローティング層（本文中の `[[` 用）。
+ * `useWikiLinkCandidates` でスコープ（個人 / ノート）に応じた候補ページを
+ * 取得し、共通プレゼンテーションである `WikiLinkSuggestion` に流す。
+ * 確定時の範囲置換は `onSelect` 側（`useSuggestionEffects`）で行う。
+ * Issue #713 Phase 4 / Issue #925（共通化）。
  *
- * Floating layer for the WikiLink suggestion popup. Fetches scope-aware
- * candidate pages via `useWikiLinkCandidates` and forwards them to
- * `WikiLinkSuggestion`. See issue #713 Phase 4.
+ * Floating layer that mounts the shared `WikiLinkSuggestion` over the
+ * editor for the in-body `[[` flow. Scope-aware candidates come from
+ * `useWikiLinkCandidates`, and range replacement on confirm is handled
+ * by the caller's `onSelect`. The input bar (#924 §2) reuses the same
+ * presentation component via its own host. See issues #713 Phase 4 and
+ * #925.
  */
 export const WikiLinkSuggestionLayer: React.FC<WikiLinkSuggestionLayerProps> = ({
   editor,
@@ -58,9 +63,7 @@ export const WikiLinkSuggestionLayer: React.FC<WikiLinkSuggestionLayerProps> = (
     >
       <WikiLinkSuggestion
         ref={suggestionRef}
-        editor={editor}
         query={suggestionState.query}
-        range={suggestionState.range}
         onSelect={onSelect}
         onClose={onClose}
         pages={pages}
diff --git a/src/components/editor/TiptapEditor/editorConfig.ts b/src/components/editor/TiptapEditor/editorConfig.ts
index 8dc4c091..4ae7b755 100644
--- a/src/components/editor/TiptapEditor/editorConfig.ts
+++ b/src/components/editor/TiptapEditor/editorConfig.ts
@@ -37,7 +37,13 @@ import {
   type SlashSuggestionState,
 } from "../extensions/slashSuggestionPlugin";
 import { TagSuggestionPlugin, type TagSuggestionState } from "../extensions/tagSuggestionPlugin";
+import {
+  WikiLinkGhostCompletionPlugin,
+  type WikiLinkGhostCompletionCandidate,
+  type WikiLinkGhostCompletionState,
+} from "../extensions/wikiLinkGhostCompletionPlugin";
 import { HeadingLevelClamp } from "./headingLevelClampExtension";
+import { MermaidCodeBlockNormalize } from "./mermaidCodeBlockNormalizeExtension";
 import type { Extension } from "@tiptap/core";
 import type * as Y from "yjs";
 import type { Awareness } from "y-protocols/awareness";
@@ -105,7 +111,7 @@ export interface CollaborationExtensionsOptions {
  */
 export interface EditorExtensionsOptions {
   placeholder: string;
-  onLinkClick: (title: string) => void;
+  onLinkClick: (title: string, options?: { newTab?: boolean }) => void;
   /**
    * Click handler for tag marks (`#name`). Receives the tag name without `#`
    * so the caller can navigate to the corresponding page. See issue #725.
@@ -123,6 +129,26 @@ export interface EditorExtensionsOptions {
    * changes. See issue #767 (Phase 2).
    */
   onTagSuggestionStateChange: (state: TagSuggestionState) => void;
+  /**
+   * 既存ページタイトルとプレフィックス一致するインライン・ゴースト補完
+   * （issue #930）に渡す候補ソース。`useWikiLinkCandidates` の結果を ref で
+   * 包んで `() => ref.current` の形で渡すことを想定する。
+   *
+   * Inline ghost completion (issue #930) candidate source. Expected to be a
+   * getter over the latest `useWikiLinkCandidates` snapshot held in a ref so
+   * the editor instance does not have to be re-created when candidates
+   * update.
+   */
+  getGhostCompletionCandidates?: () => ReadonlyArray<WikiLinkGhostCompletionCandidate>;
+  /**
+   * Optional state observer for the ghost completion plugin (telemetry /
+   * tests). Confirmation is handled inside the plugin so most callers do
+   * not need this.
+   *
+   * ゴースト補完の状態通知（任意、テレメトリ・テスト用途）。確定処理は
+   * プラグイン内で完結するため通常は省略可。
+   */
+  onGhostCompletionStateChange?: (state: WikiLinkGhostCompletionState) => void;
   imageUploadOptions: Partial<ImageUploadOptions>;
   imageOptions: Partial<StorageImageOptions>;
   /** When set, enables Y.js collaboration and caret; StarterKit history is disabled */
@@ -139,11 +165,15 @@ export interface EditorExtensionsOptions {
 
 interface CommonEditorExtensionsOptions {
   placeholder?: string;
-  onLinkClick: (title: string) => void;
+  onLinkClick: (title: string, options?: { newTab?: boolean }) => void;
   onTagClick?: (name: string) => void;
   onStateChange?: (state: WikiLinkSuggestionState) => void;
   onSlashStateChange?: (state: SlashSuggestionState) => void;
   onTagSuggestionStateChange?: (state: TagSuggestionState) => void;
+  /** Inline ghost completion candidates (issue #930). / ゴースト補完候補ソース */
+  getGhostCompletionCandidates?: () => ReadonlyArray<WikiLinkGhostCompletionCandidate>;
+  /** Optional ghost completion state observer (issue #930). / ゴースト補完状態通知 */
+  onGhostCompletionStateChange?: (state: WikiLinkGhostCompletionState) => void;
   imageUploadOptions?: Partial<ImageUploadOptions>;
   imageOptions?: Partial<StorageImageOptions>;
   fileReference?: EditorExtensionsOptions["fileReference"];
@@ -272,6 +302,17 @@ function createCommonEditorExtensions(options: CommonEditorExtensionsOptions): E
           TagSuggestionPlugin.configure({
             onStateChange: options.onTagSuggestionStateChange ?? (() => undefined),
           }),
+          // --- Inline ghost completion (issue #930) ---
+          // 登録順は WikiLinkSuggestion → TagSuggestion → Ghost にすることで、
+          // 同一トランザクション内で `[[` / `#` のサジェスト状態が先に更新され、
+          // Ghost 側の `apply` がそれらの最新 `active` を参照して自己抑止できる。
+          // Order matters: registered after WikiLinkSuggestion and
+          // TagSuggestion so the ghost's `apply` can read their updated
+          // `active` flags within the same transaction and suppress itself.
+          WikiLinkGhostCompletionPlugin.configure({
+            getCandidates: options.getGhostCompletionCandidates ?? (() => []),
+            onStateChange: options.onGhostCompletionStateChange ?? (() => undefined),
+          }),
         ]
       : []),
     // --- Image ---
@@ -298,6 +339,13 @@ function createCommonEditorExtensions(options: CommonEditorExtensionsOptions): E
     // --- 統合メディア挿入プレースホルダー（/image、/video スラッシュコマンド） ---
     MediaPlaceholderExtension,
     Mermaid,
+    // ``` ```mermaid ``` ``` 由来の codeBlock を mermaid ノードに正規化する。
+    // Mermaid 拡張より後に登録することで、変換先の `mermaid` ノードがスキーマに
+    // 存在することを保証する（Issue #945）。
+    // Lazy-migrate legacy `codeBlock(language=mermaid)` to `mermaid` nodes.
+    // Registered after `Mermaid` so the target node is guaranteed to be in the
+    // schema (Issue #945).
+    MermaidCodeBlockNormalize,
     // --- YouTube Embed ---
     YouTubeEmbed,
     McpResource,
@@ -339,6 +387,8 @@ export function createEditorExtensions(options: EditorExtensionsOptions): Extens
     onStateChange: options.onStateChange,
     onSlashStateChange: options.onSlashStateChange,
     onTagSuggestionStateChange: options.onTagSuggestionStateChange,
+    getGhostCompletionCandidates: options.getGhostCompletionCandidates,
+    onGhostCompletionStateChange: options.onGhostCompletionStateChange,
     imageUploadOptions: options.imageUploadOptions,
     imageOptions: options.imageOptions,
     fileReference: options.fileReference,
diff --git a/src/components/editor/TiptapEditor/mermaidCodeBlockNormalizeExtension.test.ts b/src/components/editor/TiptapEditor/mermaidCodeBlockNormalizeExtension.test.ts
new file mode 100644
index 00000000..b06d6eae
--- /dev/null
+++ b/src/components/editor/TiptapEditor/mermaidCodeBlockNormalizeExtension.test.ts
@@ -0,0 +1,195 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { Editor } from "@tiptap/core";
+import StarterKit from "@tiptap/starter-kit";
+import { Mermaid } from "../extensions/MermaidExtension";
+import { MermaidCodeBlockNormalize } from "./mermaidCodeBlockNormalizeExtension";
+
+/**
+ * `MermaidCodeBlockNormalize` は、エディタロード時に `codeBlock` +
+ * `language: "mermaid"` を `mermaid` ノードへ自動変換することを検証する。
+ *
+ * `MermaidCodeBlockNormalize` should rewrite legacy `codeBlock` nodes with
+ * `language: "mermaid"` into dedicated `mermaid` nodes on editor load.
+ */
+describe("MermaidCodeBlockNormalize", () => {
+  const editors: Editor[] = [];
+
+  afterEach(() => {
+    for (const ed of editors) {
+      ed.destroy();
+    }
+    editors.length = 0;
+  });
+
+  /**
+   * 共通のエディタ生成ヘルパー。`MermaidNodeView` は React に依存するため、
+   * NodeView を取り外したテスト用 Mermaid 拡張を用意して使う。
+   *
+   * Builds an Editor with `MermaidCodeBlockNormalize` plus a NodeView-less
+   * Mermaid node (the real NodeView relies on React rendering inside the DOM,
+   * which isn't needed for these unit tests).
+   */
+  function createEditor(content: unknown): Editor {
+    const el = document.createElement("div");
+    const editor = new Editor({
+      element: el,
+      extensions: [
+        StarterKit.configure({
+          heading: { levels: [2, 3, 4, 5] },
+        }),
+        Mermaid.extend({
+          addNodeView: () => null as unknown as never,
+        }),
+        MermaidCodeBlockNormalize,
+      ],
+      content,
+    });
+    editors.push(editor);
+    return editor;
+  }
+
+  it("rewrites a legacy codeBlock(language=mermaid) into a mermaid node on load", async () => {
+    const editor = createEditor({
+      type: "doc",
+      content: [
+        {
+          type: "codeBlock",
+          attrs: { language: "mermaid" },
+          content: [{ type: "text", text: "graph TD\nA-->B" }],
+        },
+      ],
+    });
+
+    await new Promise<void>((resolve) => queueMicrotask(() => resolve()));
+
+    const first = editor.state.doc.firstChild;
+    expect(first?.type.name).toBe("mermaid");
+    expect(first?.attrs.code).toBe("graph TD\nA-->B");
+  });
+
+  it("does not touch code blocks with a different language", async () => {
+    const editor = createEditor({
+      type: "doc",
+      content: [
+        {
+          type: "codeBlock",
+          attrs: { language: "ts" },
+          content: [{ type: "text", text: "const x = 1;" }],
+        },
+      ],
+    });
+
+    await new Promise<void>((resolve) => queueMicrotask(() => resolve()));
+
+    const first = editor.state.doc.firstChild;
+    expect(first?.type.name).toBe("codeBlock");
+    expect(first?.attrs.language).toBe("ts");
+  });
+
+  it("strips trailing newlines from the converted source", async () => {
+    const editor = createEditor({
+      type: "doc",
+      content: [
+        {
+          type: "codeBlock",
+          attrs: { language: "mermaid" },
+          content: [{ type: "text", text: "graph TD\nA-->B\n\n" }],
+        },
+      ],
+    });
+
+    await new Promise<void>((resolve) => queueMicrotask(() => resolve()));
+
+    expect(editor.state.doc.firstChild?.attrs.code).toBe("graph TD\nA-->B");
+  });
+
+  it("rewrites multiple mermaid code blocks in the same document", async () => {
+    const editor = createEditor({
+      type: "doc",
+      content: [
+        {
+          type: "codeBlock",
+          attrs: { language: "mermaid" },
+          content: [{ type: "text", text: "graph TD" }],
+        },
+        {
+          type: "paragraph",
+          content: [{ type: "text", text: "between" }],
+        },
+        {
+          type: "codeBlock",
+          attrs: { language: "mermaid" },
+          content: [{ type: "text", text: "sequenceDiagram" }],
+        },
+      ],
+    });
+
+    await new Promise<void>((resolve) => queueMicrotask(() => resolve()));
+
+    // Tiptap がトレーリング paragraph を補う可能性があるため、最初の 3 ノードだけ
+    // 厳密に検証する。両方のコードブロックが正しい順序で `mermaid` ノードに
+    // 変換されていることだけ確認する。
+    // Tiptap may append a trailing empty paragraph; assert only the first
+    // three children so both mermaid blocks are validated in order.
+    const doc = editor.state.doc;
+    expect(doc.childCount).toBeGreaterThanOrEqual(3);
+    expect(doc.child(0).type.name).toBe("mermaid");
+    expect(doc.child(0).attrs.code).toBe("graph TD");
+    expect(doc.child(1).type.name).toBe("paragraph");
+    expect(doc.child(2).type.name).toBe("mermaid");
+    expect(doc.child(2).attrs.code).toBe("sequenceDiagram");
+  });
+
+  it("normalises a code block that is later switched to `mermaid` at runtime", async () => {
+    const editor = createEditor({
+      type: "doc",
+      content: [
+        {
+          type: "codeBlock",
+          attrs: { language: "ts" },
+          content: [{ type: "text", text: "graph TD" }],
+        },
+      ],
+    });
+    await new Promise<void>((resolve) => queueMicrotask(() => resolve()));
+    expect(editor.state.doc.firstChild?.type.name).toBe("codeBlock");
+
+    // `appendTransaction` 経路で言語属性を変更すると、再度走査されて mermaid に変換される。
+    // Changing the language attribute fires `appendTransaction`, which then
+    // rewrites the codeBlock to a mermaid node.
+    const codeBlockType = editor.schema.nodes.codeBlock;
+    expect(codeBlockType).toBeDefined();
+    editor.view.dispatch(editor.state.tr.setNodeMarkup(0, codeBlockType, { language: "mermaid" }));
+
+    expect(editor.state.doc.firstChild?.type.name).toBe("mermaid");
+    expect(editor.state.doc.firstChild?.attrs.code).toBe("graph TD");
+  });
+
+  // CodeRabbit のレビュー (PR #946) で指摘された undo 履歴混入バグの回帰テスト。
+  // 正規化トランザクションが undo 履歴に積まれると、Cmd+Z で `mermaid` → `codeBlock`
+  // に戻り、次の編集で再度プラグインが変換するループになる。
+  // Regression test for the CodeRabbit finding on PR #946: normalisation
+  // transactions must not enter the undo history, otherwise Cmd+Z would
+  // revert `mermaid` back to `codeBlock` and the plugin would re-convert it
+  // on the next edit, causing an undo/redo bounce.
+  it("does not push the migration transaction onto the undo history", async () => {
+    const editor = createEditor({
+      type: "doc",
+      content: [
+        {
+          type: "codeBlock",
+          attrs: { language: "mermaid" },
+          content: [{ type: "text", text: "graph TD" }],
+        },
+      ],
+    });
+    await new Promise<void>((resolve) => queueMicrotask(() => resolve()));
+    expect(editor.state.doc.firstChild?.type.name).toBe("mermaid");
+
+    // Tiptap (StarterKit) の undo コマンドを実行しても、正規化は元に戻らない。
+    // Invoking the editor's undo command must not roll the migration back.
+    editor.commands.undo();
+    expect(editor.state.doc.firstChild?.type.name).toBe("mermaid");
+    expect(editor.state.doc.firstChild?.attrs.code).toBe("graph TD");
+  });
+});
diff --git a/src/components/editor/TiptapEditor/mermaidCodeBlockNormalizeExtension.ts b/src/components/editor/TiptapEditor/mermaidCodeBlockNormalizeExtension.ts
new file mode 100644
index 00000000..c206f779
--- /dev/null
+++ b/src/components/editor/TiptapEditor/mermaidCodeBlockNormalizeExtension.ts
@@ -0,0 +1,151 @@
+import { Extension } from "@tiptap/core";
+import type { EditorState, Transaction } from "@tiptap/pm/state";
+import { Plugin, PluginKey } from "@tiptap/pm/state";
+
+/**
+ * `MermaidCodeBlockNormalize` のプラグインキー。拡張再初期化のたびに
+ * `PluginKey` を作り直さないようトップレベルで定義する。
+ *
+ * Plugin key for `MermaidCodeBlockNormalize`. Declared at module scope so it
+ * is stable across extension re-initialisations.
+ */
+const mermaidCodeBlockNormalizeKey = new PluginKey("mermaidCodeBlockNormalize");
+
+/**
+ * ノード型名が `codeBlock`（または互換の `code_block`）かを判定する。
+ * Returns whether a ProseMirror node type name represents a code block.
+ */
+function isCodeBlockType(typeName: string): boolean {
+  return typeName === "codeBlock" || typeName === "code_block";
+}
+
+/**
+ * 与えられたノードの `language` 属性が `"mermaid"`（大文字小文字無視）かを判定する。
+ * Returns whether the node's `language` attribute selects the Mermaid renderer.
+ */
+function isMermaidLanguage(attrs: Record<string, unknown> | null | undefined): boolean {
+  const value = attrs?.language;
+  if (typeof value !== "string") return false;
+  return value.trim().toLowerCase() === "mermaid";
+}
+
+/**
+ * `state.doc` を 1 度走査し、`language: "mermaid"` の codeBlock を `mermaid`
+ * ノードに置換するトランザクションを構築する。対象がなければ `null` を返す。
+ *
+ * Walk the document once and build a transaction that replaces every
+ * `codeBlock` with `language: "mermaid"` by a dedicated `mermaid` node.
+ * Returns `null` when nothing needs to change so the caller can skip dispatch.
+ *
+ * 走査は降順 (`-pos`) で置換することにより、先に置換した範囲のオフセット変動が
+ * 後続の置換位置に影響しないようにしている（Issue #945）。
+ *
+ * Replacements are applied in descending document order so that splicing
+ * earlier in the tree does not invalidate the positions of later targets
+ * (Issue #945).
+ *
+ * @param state - 走査対象のエディタ状態 / Editor state to scan.
+ * @returns 変換トランザクション、または変換不要なら null / Transaction or `null`.
+ */
+function buildMermaidNormalizeTr(state: EditorState): Transaction | null {
+  const mermaidType = state.schema.nodes.mermaid;
+  // mermaid ノードがスキーマに存在しない（プレビュー用拡張セット等）場合は何もしない。
+  // Bail out gracefully when the `mermaid` node is not part of the schema
+  // (e.g. lightweight preview extension sets).
+  if (!mermaidType) return null;
+
+  type Target = { pos: number; nodeSize: number; code: string };
+  const targets: Target[] = [];
+
+  state.doc.descendants((node, pos) => {
+    if (!isCodeBlockType(node.type.name)) {
+      // 内部に codeBlock がさらに入れ子になることは無いが、ネストブロック（list 等）の
+      // 走査を続けるため true を返す。
+      // Continue descending into other block types (lists, tables, etc.).
+      return true;
+    }
+    if (!isMermaidLanguage(node.attrs)) {
+      // 非 mermaid の codeBlock 配下にはこれ以上探す対象がない。
+      // No mermaid targets nest inside non-mermaid code blocks.
+      return false;
+    }
+    targets.push({ pos, nodeSize: node.nodeSize, code: node.textContent });
+    return false;
+  });
+
+  if (targets.length === 0) return null;
+
+  let tr: Transaction | null = null;
+  // 末尾から置換することでオフセットの巻き戻りを避ける。
+  // Replace from the end backwards to keep positions stable across edits.
+  for (let i = targets.length - 1; i >= 0; i -= 1) {
+    const { pos, nodeSize, code } = targets[i];
+    // 末尾の改行は描画時のノイズになるため除去する（pasted/imported source も同様）。
+    // Strip trailing newlines so the rendered diagram does not have stray
+    // whitespace, matching the paste-side `transformMermaidCodeBlocksInContent`.
+    const trimmedCode = code.replace(/\n+$/u, "");
+    const mermaidNode = mermaidType.create({ code: trimmedCode });
+    if (!tr) {
+      tr = state.tr;
+      // 自動的なフォーマット移行（lazy migration）はユーザー操作ではないため、
+      // undo 履歴に積まない。これを忘れると Cmd+Z で `mermaid` → `codeBlock` に
+      // 戻ってしまい、再度プラグインが変換してループする恐れがある。
+      // The lazy migration is a passive normalisation, not a user edit, so it
+      // must stay out of the undo stack—otherwise Cmd+Z would revert the
+      // `mermaid` node back to a `codeBlock`, only for the plugin to convert
+      // it again on the next transaction (potential undo/redo bounce).
+      tr.setMeta("addToHistory", false);
+    }
+    tr.replaceWith(pos, pos + nodeSize, mermaidNode);
+  }
+  return tr;
+}
+
+/**
+ * 既存ドキュメント内の Mermaid フェンス由来の `codeBlock` を、エディタ表示時に
+ * `mermaid` ノードへ正規化する Tiptap 拡張。
+ *
+ * Tiptap extension that lazily migrates legacy `codeBlock` nodes with
+ * `language: "mermaid"` to dedicated `mermaid` nodes. The transform runs once
+ * on view mount (because the initial document does not always pass through
+ * `appendTransaction`) and additionally on each transaction so that runtime
+ * language changes (e.g. via the code-block language selector) also pick up
+ * the conversion.
+ *
+ * Y.js 協調編集環境でも、変換トランザクションは通常のドキュメント編集として
+ * 他クライアントへ同期される（意図した lazy migration）。
+ *
+ * Under Y.js collaborative editing the rewrite is a regular doc transaction
+ * and therefore propagates to peers as expected.
+ *
+ * 参考: `HeadingLevelClamp`（`headingLevelClampExtension.ts`）。
+ * See `HeadingLevelClamp` for the structural template (Issue #945).
+ */
+export const MermaidCodeBlockNormalize = Extension.create({
+  name: "mermaidCodeBlockNormalize",
+  addProseMirrorPlugins() {
+    return [
+      new Plugin({
+        key: mermaidCodeBlockNormalizeKey,
+        view(view) {
+          queueMicrotask(() => {
+            if (view.isDestroyed) return;
+            const tr = buildMermaidNormalizeTr(view.state);
+            if (tr) {
+              view.dispatch(tr);
+            }
+          });
+          return {};
+        },
+        appendTransaction(transactions, _oldState, newState) {
+          // `docChanged` の無いトランザクション（選択変更など）は対象外。
+          // Skip transactions that don't touch the doc (selection-only changes).
+          if (!transactions.some((tr) => tr.docChanged)) {
+            return null;
+          }
+          return buildMermaidNormalizeTr(newState);
+        },
+      }),
+    ];
+  },
+});
diff --git a/src/components/editor/TiptapEditor/thumbnailTypes.ts b/src/components/editor/TiptapEditor/thumbnailTypes.ts
new file mode 100644
index 00000000..ebd77818
--- /dev/null
+++ b/src/components/editor/TiptapEditor/thumbnailTypes.ts
@@ -0,0 +1,20 @@
+/**
+ * サムネイル候補の表現。`useThumbnailImageSearch` が `/api/thumbnail/image-search`
+ * のレスポンス `items` を反映する型として用い、`PageActionHub` の検索アクションも
+ * 同じ型を介してエディタに渡す。
+ *
+ * Thumbnail candidate descriptor used by `useThumbnailImageSearch` to mirror
+ * the `items` payload from `/api/thumbnail/image-search`, and shared with the
+ * `PageActionHub` thumbnail-search action when forwarding selections to the
+ * editor.
+ */
+export interface ThumbnailCandidate {
+  id: string;
+  previewUrl: string;
+  imageUrl: string;
+  alt: string;
+  sourceName: string;
+  sourceUrl: string;
+  authorName?: string;
+  authorUrl?: string;
+}
diff --git a/src/components/editor/TiptapEditor/types.ts b/src/components/editor/TiptapEditor/types.ts
index e0db69e7..8a70bf83 100644
--- a/src/components/editor/TiptapEditor/types.ts
+++ b/src/components/editor/TiptapEditor/types.ts
@@ -1,6 +1,7 @@
-import type { MutableRefObject } from "react";
+import type { MutableRefObject, ReactNode } from "react";
 import type * as Y from "yjs";
 import type { Awareness } from "y-protocols/awareness";
+import type { PageActionHubHandle } from "../PageActionHub/types";
 
 /**
  * リアルタイムコラボレーション用の設定（useCollaboration の戻り値から渡す）
@@ -54,6 +55,13 @@ export interface TiptapEditorProps {
    * Accepts any content that TipTap's `insertContent` can handle (e.g. array of JSON nodes).
    */
   insertAtCursorRef?: MutableRefObject<((content: unknown) => boolean) | null>;
+  /**
+   * `PageActionHub` を親（FAB）から開閉するための ref。editor の他の ref と
+   * 同じく、ハブのマウント時に `ref.current` に handle が代入される。
+   * Ref to imperatively open/close the `PageActionHub` from a parent FAB.
+   * Assigned by the hub on mount, mirroring the `insertAtCursorRef` pattern.
+   */
+  pageActionHubRef?: MutableRefObject<PageActionHubHandle | null>;
   /** URL から作成時など、Y.Doc が空のときに一度だけ反映する Tiptap JSON 文字列 */
   initialContent?: string;
   /** initialContent をエディタに反映したあとに呼ぶ */
@@ -74,6 +82,16 @@ export interface TiptapEditorProps {
    * Phase 4.
    */
   pageNoteId?: string | null;
+  /**
+   * Wiki Compose 画面 URL。PageActionHub の `wiki.compose` と同経路 (#950)。
+   * Route to the Wiki Compose UI; used by PageActionHub `wiki.compose`.
+   */
+  wikiComposeHref?: string;
+  /**
+   * 画面下部の Wiki Link 入力バー右隣に並べるアクション（例: PageActionHub FAB）。
+   * Trailing control rendered beside the floating Wiki Link input bar.
+   */
+  bottomBarTrailingAction?: ReactNode;
 }
 
 /**
diff --git a/src/components/editor/TiptapEditor/useBubbleMenuWikiLink.ts b/src/components/editor/TiptapEditor/useBubbleMenuWikiLink.ts
index 09f8d33a..11f02e22 100644
--- a/src/components/editor/TiptapEditor/useBubbleMenuWikiLink.ts
+++ b/src/components/editor/TiptapEditor/useBubbleMenuWikiLink.ts
@@ -11,7 +11,15 @@ import { useWikiLinkExistsChecker } from "@/hooks/usePageQueries";
  * existence checks (and to exclude self-references).
  */
 export interface UseBubbleMenuWikiLinkOptions {
-  editor: Editor;
+  /**
+   * 操作対象のエディタ。`null` の間（初期化前など）は `convertToWikiLink` /
+   * `unsetWikiLink` は no-op、`isWikiLinkSelection` は `false` を返す。
+   *
+   * Target editor. While `null` (e.g. during initialization), the returned
+   * `convertToWikiLink` / `unsetWikiLink` are no-ops and
+   * `isWikiLinkSelection` is `false`.
+   */
+  editor: Editor | null;
   pageId?: string;
 }
 
@@ -53,9 +61,10 @@ export function useBubbleMenuWikiLink({
   const [isConverting, setIsConverting] = useState(false);
   const convertingRef = useRef(false);
 
-  const isWikiLinkSelection = editor.isActive("wikiLink");
+  const isWikiLinkSelection = editor?.isActive("wikiLink") ?? false;
 
   const convertToWikiLink = useCallback(async () => {
+    if (!editor) return;
     if (convertingRef.current) return;
 
     const { from, to } = editor.state.selection;
@@ -113,6 +122,7 @@ export function useBubbleMenuWikiLink({
   }, [editor, pageId, checkExistence]);
 
   const unsetWikiLink = useCallback(() => {
+    if (!editor) return;
     editor.chain().focus().unsetWikiLink().run();
   }, [editor]);
 
diff --git a/src/components/editor/TiptapEditor/useEditorRecommendationBar.test.ts b/src/components/editor/TiptapEditor/useEditorRecommendationBar.test.ts
deleted file mode 100644
index 24e6e920..00000000
--- a/src/components/editor/TiptapEditor/useEditorRecommendationBar.test.ts
+++ /dev/null
@@ -1,129 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { renderHook, act } from "@testing-library/react";
-import { useEditorRecommendationBar } from "./useEditorRecommendationBar";
-
-vi.mock("@/hooks/useAuth", () => ({
-  useAuth: vi.fn(),
-}));
-
-const editorRecommendationLabels: Record<string, string> = {
-  labelRecommendation: "おすすめ",
-  labelThumbnails: "サムネイル候補",
-  generating: "画像を生成中",
-};
-vi.mock("react-i18next", () => ({
-  useTranslation: () => ({
-    t: (key: string) => {
-      if (key.startsWith("editor.recommendation.")) {
-        const sub = key.replace("editor.recommendation.", "");
-        return editorRecommendationLabels[sub] ?? key;
-      }
-      return key;
-    },
-    i18n: { language: "ja" },
-  }),
-}));
-
-import { useAuth } from "@/hooks/useAuth";
-
-const defaultProps = {
-  pageTitle: "Test Page",
-  isReadOnly: false,
-  hasThumbnail: false,
-  onSelectThumbnail: vi.fn(),
-};
-
-describe("useEditorRecommendationBar", () => {
-  beforeEach(() => {
-    vi.stubEnv("VITE_API_BASE_URL", "https://api.test.example.com");
-    vi.mocked(useAuth).mockReturnValue({ isSignedIn: true } as never);
-    vi.clearAllMocks();
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockResolvedValue({
-        ok: true,
-        json: async () => ({ items: [], nextCursor: null }),
-      }),
-    );
-  });
-
-  afterEach(() => {
-    vi.unstubAllGlobals();
-    vi.unstubAllEnvs();
-  });
-
-  it("canSearch is false when isReadOnly", () => {
-    const { result } = renderHook(() =>
-      useEditorRecommendationBar({ ...defaultProps, isReadOnly: true }),
-    );
-    expect(result.current.canSearch).toBe(false);
-  });
-
-  it("canSearch is false when hasThumbnail", () => {
-    const { result } = renderHook(() =>
-      useEditorRecommendationBar({ ...defaultProps, hasThumbnail: true }),
-    );
-    expect(result.current.canSearch).toBe(false);
-  });
-
-  it("canSearch is true when not read-only and no thumbnail", () => {
-    const { result } = renderHook(() => useEditorRecommendationBar(defaultProps));
-    expect(result.current.canSearch).toBe(true);
-    expect(result.current.mode).toBe("actions");
-    expect(result.current.headerLabel).toBe("おすすめ");
-  });
-
-  it("dismiss sets isDismissed", () => {
-    const { result } = renderHook(() => useEditorRecommendationBar(defaultProps));
-    expect(result.current.isDismissed).toBe(false);
-    act(() => {
-      result.current.dismiss();
-    });
-    expect(result.current.isDismissed).toBe(true);
-  });
-
-  it("handleOpenThumbnailPicker switches to thumbnails mode", () => {
-    const { result } = renderHook(() => useEditorRecommendationBar(defaultProps));
-    expect(result.current.mode).toBe("actions");
-    act(() => {
-      result.current.handleOpenThumbnailPicker();
-    });
-    expect(result.current.mode).toBe("thumbnails");
-    expect(result.current.headerLabel).toBe("サムネイル候補");
-  });
-
-  it("handleBackToActions switches back to actions", () => {
-    const { result } = renderHook(() => useEditorRecommendationBar(defaultProps));
-    act(() => {
-      result.current.handleOpenThumbnailPicker();
-    });
-    expect(result.current.mode).toBe("thumbnails");
-    act(() => {
-      result.current.handleBackToActions();
-    });
-    expect(result.current.mode).toBe("actions");
-  });
-
-  it("handleSelectCandidate calls onSelectThumbnail and resets mode", () => {
-    const onSelectThumbnail = vi.fn();
-    const { result } = renderHook(() =>
-      useEditorRecommendationBar({
-        ...defaultProps,
-        onSelectThumbnail,
-      }),
-    );
-    const candidate = {
-      id: "1",
-      previewUrl: "https://p",
-      imageUrl: "https://img",
-      alt: "Alt",
-      sourceName: "S",
-      sourceUrl: "https://s",
-    };
-    act(() => {
-      result.current.handleSelectCandidate(candidate);
-    });
-    expect(onSelectThumbnail).toHaveBeenCalledWith("https://img", "Alt", "https://p");
-    expect(result.current.mode).toBe("actions");
-  });
-});
diff --git a/src/components/editor/TiptapEditor/useEditorRecommendationBar.ts b/src/components/editor/TiptapEditor/useEditorRecommendationBar.ts
deleted file mode 100644
index 6b17cc11..00000000
--- a/src/components/editor/TiptapEditor/useEditorRecommendationBar.ts
+++ /dev/null
@@ -1,122 +0,0 @@
-import { useCallback, useMemo, useRef, useState } from "react";
-import { useTranslation } from "react-i18next";
-import type {
-  EditorRecommendationBarProps,
-  RecommendationMode,
-  ThumbnailCandidate,
-} from "./EditorRecommendationBarTypes";
-import { getThumbnailApiBaseUrl } from "./thumbnailApiHelpers";
-import { useThumbnailImageSearch } from "./useThumbnailImageSearch";
-import { useThumbnailImageGenerate } from "./useThumbnailImageGenerate";
-import { useAuth } from "@/hooks/useAuth";
-
-export function useEditorRecommendationBar({
-  pageTitle,
-  isReadOnly,
-  hasThumbnail,
-  onSelectThumbnail,
-}: EditorRecommendationBarProps) {
-  const { t } = useTranslation();
-  const { isSignedIn } = useAuth();
-  const [isDismissed, setIsDismissed] = useState(false);
-  const [mode, setMode] = useState<RecommendationMode>("actions");
-  const [generatingErrorMessage, setGeneratingErrorMessage] = useState<string | null>(null);
-  const scrollRef = useRef<HTMLDivElement>(null);
-
-  const trimmedTitle = pageTitle.trim();
-  const thumbnailApiBaseUrl = getThumbnailApiBaseUrl();
-  const canSearch = !isReadOnly && !hasThumbnail;
-
-  const search = useThumbnailImageSearch(trimmedTitle, isSignedIn, thumbnailApiBaseUrl);
-  const { generateImage, isGenerating } = useThumbnailImageGenerate(
-    trimmedTitle,
-    isSignedIn,
-    onSelectThumbnail,
-  );
-
-  const isLoading = search.isLoading || isGenerating;
-  const errorMessage = mode === "generating" ? generatingErrorMessage : search.errorMessage;
-
-  const handleWheel = useCallback((event: React.WheelEvent<HTMLDivElement>) => {
-    const container = scrollRef.current;
-    if (!container) return;
-    if (Math.abs(event.deltaY) <= Math.abs(event.deltaX)) return;
-    const maxScrollLeft = container.scrollWidth - container.clientWidth;
-    const newScrollLeft = Math.min(Math.max(0, container.scrollLeft + event.deltaY), maxScrollLeft);
-    if (newScrollLeft !== container.scrollLeft) {
-      container.scrollLeft = newScrollLeft;
-      event.preventDefault();
-    }
-  }, []);
-
-  const handleOpenThumbnailPicker = useCallback(() => {
-    if (!canSearch) return;
-    setMode("thumbnails");
-    if (search.lastQueryRef.current !== trimmedTitle) {
-      search.resetSearch();
-      void search.loadCandidates();
-    } else if (search.candidates.length === 0 && !search.isLoading) {
-      void search.loadCandidates();
-    }
-  }, [canSearch, search, trimmedTitle]);
-
-  const handleBackToActions = useCallback(() => {
-    setMode("actions");
-    search.setErrorMessage(null);
-    setGeneratingErrorMessage(null);
-  }, [search]);
-
-  const handleSelectCandidate = useCallback(
-    (candidate: ThumbnailCandidate) => {
-      onSelectThumbnail(candidate.imageUrl, candidate.alt, candidate.previewUrl);
-      setMode("actions");
-      search.setErrorMessage(null);
-    },
-    [onSelectThumbnail, search],
-  );
-
-  const handleNextPage = useCallback(() => {
-    if (!search.nextCursor || isLoading) return;
-    void search.loadCandidates(search.nextCursor);
-  }, [isLoading, search]);
-
-  const handleGenerateImage = useCallback(async () => {
-    if (isGenerating) return;
-    setGeneratingErrorMessage(null);
-    setMode("generating");
-    const err = await generateImage();
-    if (err) {
-      setGeneratingErrorMessage(err);
-    } else {
-      setMode("actions");
-    }
-  }, [generateImage, isGenerating]);
-
-  const dismiss = useCallback(() => setIsDismissed(true), []);
-
-  const headerLabel = useMemo(() => {
-    if (mode === "generating") return t("editor.recommendation.generating");
-    return mode === "actions"
-      ? t("editor.recommendation.labelRecommendation")
-      : t("editor.recommendation.labelThumbnails");
-  }, [mode, t]);
-
-  return {
-    canSearch,
-    isDismissed,
-    mode,
-    headerLabel,
-    isLoading,
-    errorMessage,
-    candidates: search.candidates,
-    nextCursor: search.nextCursor,
-    scrollRef,
-    handleWheel,
-    handleOpenThumbnailPicker,
-    handleBackToActions,
-    handleSelectCandidate,
-    handleNextPage,
-    handleGenerateImage,
-    dismiss,
-  };
-}
diff --git a/src/components/editor/TiptapEditor/useEditorSetup.ts b/src/components/editor/TiptapEditor/useEditorSetup.ts
index 4ddda0d8..03615886 100644
--- a/src/components/editor/TiptapEditor/useEditorSetup.ts
+++ b/src/components/editor/TiptapEditor/useEditorSetup.ts
@@ -12,6 +12,7 @@ import type { Editor } from "@tiptap/core";
 import type { WikiLinkSuggestionState } from "../extensions/wikiLinkSuggestionPlugin";
 import type { SlashSuggestionState } from "../extensions/slashSuggestionPlugin";
 import type { TagSuggestionState } from "../extensions/tagSuggestionPlugin";
+import type { WikiLinkGhostCompletionCandidate } from "../extensions/wikiLinkGhostCompletionPlugin";
 import type { WikiLinkSuggestionHandle } from "../extensions/WikiLinkSuggestion";
 import type { TagSuggestionHandle } from "../extensions/TagSuggestion";
 import type { SlashSuggestionHandle } from "./SlashSuggestionLayer";
@@ -54,7 +55,7 @@ interface UseEditorSetupOptions {
   collaborationConfig: TiptapEditorProps["collaborationConfig"];
   editorRef: MutableRefObject<Editor | null>;
   lastSelectionRef: MutableRefObject<{ from: number; to: number } | null>;
-  handleLinkClick: (title: string) => void;
+  handleLinkClick: (title: string, options?: { newTab?: boolean }) => void;
   handleStateChange: (state: WikiLinkSuggestionState) => void;
   handleSlashStateChange: (state: SlashSuggestionState) => void;
   handleTagSuggestionStateChange: (state: TagSuggestionState) => void;
@@ -74,6 +75,15 @@ interface UseEditorSetupOptions {
   workspaceRoot: string | null;
   /** Current note id for Tauri workspace registry reads (Issue #461). */
   noteId: string | null;
+  /**
+   * インライン・ゴースト補完（issue #930）に渡す候補一覧の getter。ref ベースで
+   * 最新値を返すことで、候補が更新されても `useEditor` を再実行せずに済む。
+   *
+   * Getter returning the latest candidate list for inline ghost completion
+   * (issue #930). Ref-based so `useEditor` does not need to re-run when the
+   * candidate snapshot changes.
+   */
+  getGhostCompletionCandidates: () => ReadonlyArray<WikiLinkGhostCompletionCandidate>;
 }
 
 /**
@@ -110,6 +120,7 @@ export function useEditorSetup(options: UseEditorSetupOptions) {
     tagSuggestionRef,
     workspaceRoot,
     noteId,
+    getGhostCompletionCandidates,
   } = options;
 
   const isEditorInitializedRef = useRef(false);
@@ -197,6 +208,7 @@ export function useEditorSetup(options: UseEditorSetupOptions) {
           getWorkspaceRoot: () => workspaceRootRef.current,
           getNoteId: () => noteIdRef.current,
         },
+        getGhostCompletionCandidates,
       }),
       /* eslint-enable react-hooks/refs */
       content: useCollaborationMode ? undefined : initialParsedContent,
diff --git a/src/components/editor/TiptapEditor/useMobileSelectionVisible.ts b/src/components/editor/TiptapEditor/useMobileSelectionVisible.ts
new file mode 100644
index 00000000..189f1919
--- /dev/null
+++ b/src/components/editor/TiptapEditor/useMobileSelectionVisible.ts
@@ -0,0 +1,72 @@
+import { useCallback, useSyncExternalStore } from "react";
+import type { Editor } from "@tiptap/core";
+
+/**
+ * `MobileSelectionSheet` の表示判定を計算する内部フック。
+ *
+ * デスクトップ用 `EditorBubbleMenu` の `shouldShow` と同じ条件を素直に
+ * 移植している（issue #929 §「BubbleMenu はキーボードと干渉するため
+ * モバイルでは非表示」）。
+ *
+ * - 編集可能 (`isEditable`)
+ * - エディタにフォーカスがある (`view.hasFocus()`)
+ * - 選択が空ではない、または `wikiLink` マーク内にキャレットがある
+ * - `codeBlock` 内にキャレットがない
+ *
+ * `selectionUpdate` / `focus` / `blur` / `transaction` を購読して
+ * エディタ状態の変化を React に反映する。`useSyncExternalStore` を
+ * 使うことで「subscribe / unsubscribe」と「現在値の読み出し」を
+ * React の規約通り分離し、effect 内で `setState` を呼ばずに済む
+ * （`react-hooks/set-state-in-effect`）。
+ *
+ * Computes visibility for {@link MobileSelectionSheet}. Mirrors the
+ * `shouldShow` predicate used by the desktop `EditorBubbleMenu` so the
+ * mobile sheet appears in the exact same situations the bubble menu would
+ * on desktop (issue #929: the bubble menu is hidden on mobile because it
+ * collides with the on-screen keyboard). Uses `useSyncExternalStore` so
+ * subscribe / read are split per React's contract and we don't call
+ * `setState` inside an effect body (`react-hooks/set-state-in-effect`).
+ *
+ * @param editor - 操作対象のエディタ。`null` の間は常に `false`。 / Editor instance, or `null` while initializing.
+ * @returns シートを表示すべきか。 / Whether the mobile sheet should be visible.
+ */
+export function useMobileSelectionVisible(editor: Editor | null): boolean {
+  const subscribe = useCallback(
+    (onChange: () => void) => {
+      if (!editor) return noop;
+      editor.on("selectionUpdate", onChange);
+      editor.on("focus", onChange);
+      editor.on("blur", onChange);
+      editor.on("transaction", onChange);
+      return () => {
+        editor.off("selectionUpdate", onChange);
+        editor.off("focus", onChange);
+        editor.off("blur", onChange);
+        editor.off("transaction", onChange);
+      };
+    },
+    [editor],
+  );
+
+  const getSnapshot = useCallback(() => computeVisible(editor), [editor]);
+
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+
+function computeVisible(editor: Editor | null): boolean {
+  if (!editor) return false;
+  if (!editor.isEditable) return false;
+  if (!editor.view?.hasFocus?.()) return false;
+  if (editor.isActive("codeBlock")) return false;
+  if (!editor.state.selection.empty) return true;
+  return editor.isActive("wikiLink");
+}
+
+function noop(): void {
+  // no-op cleanup used while editor is null.
+}
+
+function getServerSnapshot(): boolean {
+  // SSR: editors are never focused. / SSR has no editor focus.
+  return false;
+}
diff --git a/src/components/editor/TiptapEditor/useThumbnailImageSearch.ts b/src/components/editor/TiptapEditor/useThumbnailImageSearch.ts
index 49b63dc5..e026dc75 100644
--- a/src/components/editor/TiptapEditor/useThumbnailImageSearch.ts
+++ b/src/components/editor/TiptapEditor/useThumbnailImageSearch.ts
@@ -1,5 +1,5 @@
 import { useCallback, useMemo, useRef, useState } from "react";
-import type { ThumbnailCandidate } from "./EditorRecommendationBarTypes";
+import type { ThumbnailCandidate } from "./thumbnailTypes";
 
 export function useThumbnailImageSearch(
   trimmedTitle: string,
diff --git a/src/components/editor/TiptapEditor/useTiptapEditorController.ts b/src/components/editor/TiptapEditor/useTiptapEditorController.ts
index 825fc292..f783a33f 100644
--- a/src/components/editor/TiptapEditor/useTiptapEditorController.ts
+++ b/src/components/editor/TiptapEditor/useTiptapEditorController.ts
@@ -1,12 +1,15 @@
-import { useRef, useState, type MutableRefObject, type RefObject } from "react";
+import { useEffect, useMemo, useRef, useState, type MutableRefObject, type RefObject } from "react";
 import type { Editor } from "@tiptap/core";
 import type { WikiLinkSuggestionState } from "../extensions/wikiLinkSuggestionPlugin";
 import type { SlashSuggestionState } from "../extensions/slashSuggestionPlugin";
 import type { TagSuggestionState } from "../extensions/tagSuggestionPlugin";
+import type { WikiLinkGhostCompletionCandidate } from "../extensions/wikiLinkGhostCompletionPlugin";
 import type { WikiLinkSuggestionHandle } from "../extensions/WikiLinkSuggestion";
 import type { TagSuggestionHandle } from "../extensions/TagSuggestion";
 import type { SlashSuggestionHandle } from "./SlashSuggestionLayer";
+import { useAuth } from "@/hooks/useAuth";
 import { useGeneralSettings } from "@/hooks/useGeneralSettings";
+import { useWikiLinkCandidates } from "@/hooks/useWikiLinkCandidates";
 import { useWikiLinkNavigation } from "./useWikiLinkNavigation";
 import { useEditorSetup } from "./useEditorSetup";
 import { useSuggestionEffects } from "./useSuggestionEffects";
@@ -17,6 +20,7 @@ import { useImageUploadController } from "./useImageUploadController";
 import { useClaudeAgentSlashAvailability } from "./useClaudeAgentSlashAvailability";
 import { useNoteWorkspaceOptional } from "@/contexts/NoteWorkspaceContext";
 import type { TiptapEditorProps } from "./types";
+import type { PageActionContext } from "../PageActionHub/types";
 
 function useEditorControllers(args: {
   content: string;
@@ -68,6 +72,16 @@ function useEditorControllers(args: {
    * checks (issue #713 Phase 4).
    */
   pageNoteId: string | null;
+  /**
+   * インライン・ゴースト補完（issue #930）に渡す候補一覧の getter。
+   * `useTiptapEditorController` で `useWikiLinkCandidates(pageNoteId)` を
+   * ref に保持し `() => ref.current` を渡す。
+   *
+   * Getter returning the latest candidate list for inline ghost completion
+   * (issue #930). Held as a ref in `useTiptapEditorController` to avoid
+   * editor re-creation on candidate updates.
+   */
+  getGhostCompletionCandidates: () => ReadonlyArray<WikiLinkGhostCompletionCandidate>;
 }) {
   const { editor, handleInsertMermaid, isEditorInitializedRef } = useEditorSetup({
     content: args.content,
@@ -98,6 +112,7 @@ function useEditorControllers(args: {
     tagSuggestionRef: args.tagSuggestionRef,
     workspaceRoot: args.workspaceRoot,
     noteId: args.noteId,
+    getGhostCompletionCandidates: args.getGhostCompletionCandidates,
   });
 
   const suggestionUi = useSuggestionEffects({
@@ -150,14 +165,17 @@ export function useTiptapEditorController({
   collaborationConfig,
   focusContentRef,
   insertAtCursorRef,
+  pageActionHubRef,
   initialContent,
   onInitialContentApplied,
   isWikiGenerating = false,
   wikiContentForCollab,
   onWikiContentApplied,
   pageNoteId = null,
+  wikiComposeHref,
 }: TiptapEditorProps) {
   const { editorFontSizePx } = useGeneralSettings();
+  const { isSignedIn } = useAuth();
   const noteWorkspace = useNoteWorkspaceOptional();
   const workspaceRoot = noteWorkspace?.workspaceRoot ?? null;
   const noteIdForWorkspace = noteWorkspace?.noteId ?? null;
@@ -171,6 +189,17 @@ export function useTiptapEditorController({
     handleConfirmCreate,
     handleCancelCreate,
   } = useWikiLinkNavigation({ pageNoteId });
+  // Inline ghost completion (issue #930): keep the latest candidate list in a
+  // ref so the ProseMirror plugin can read it on every transaction without
+  // forcing `useEditor` to re-run when candidates change.
+  // インライン・ゴースト補完（issue #930）の候補一覧を ref に保持。
+  // 候補更新で `useEditor` が再実行されないように getter 経由で渡す。
+  const { pages: ghostCompletionCandidates } = useWikiLinkCandidates(pageNoteId);
+  const ghostCompletionCandidatesRef =
+    useRef<ReadonlyArray<WikiLinkGhostCompletionCandidate>>(ghostCompletionCandidates);
+  useEffect(() => {
+    ghostCompletionCandidatesRef.current = ghostCompletionCandidates;
+  }, [ghostCompletionCandidates]);
   const [mermaidDialogOpen, setMermaidDialogOpen] = useState(false);
   const {
     storageSettings,
@@ -242,6 +271,7 @@ export function useTiptapEditorController({
     workspaceRoot,
     noteId: noteIdForWorkspace,
     pageNoteId,
+    getGhostCompletionCandidates: () => ghostCompletionCandidatesRef.current,
   });
   const { handleInsertThumbnailImage } = useThumbnailController(
     editorRef,
@@ -249,6 +279,20 @@ export function useTiptapEditorController({
     storageSettings,
   );
 
+  // PageActionHub に渡すコンテキスト。レジストリゲートと各アクションが参照する。
+  // Context object passed to PageActionHub; consumed by registry gates and actions.
+  const pageActionContext: PageActionContext = useMemo(
+    () => ({
+      pageTitle,
+      isReadOnly,
+      isSignedIn,
+      hasThumbnail,
+      insertThumbnail: handleInsertThumbnailImage,
+      wikiComposeHref,
+    }),
+    [pageTitle, isReadOnly, isSignedIn, hasThumbnail, handleInsertThumbnailImage, wikiComposeHref],
+  );
+
   return {
     editor: editorControllers.editor,
     editorFontSizePx,
@@ -293,5 +337,7 @@ export function useTiptapEditorController({
     claudeWorkspaceRoot: noteWorkspace?.workspaceRoot ?? null,
     claudeWorkspaceNoteId: noteWorkspace?.noteId ?? null,
     pageNoteId,
+    pageActionHubRef,
+    pageActionContext,
   };
 }
diff --git a/src/components/editor/TiptapEditor/useWikiLinkNavigation.test.ts b/src/components/editor/TiptapEditor/useWikiLinkNavigation.test.ts
index 6ec297b1..d66b38bc 100644
--- a/src/components/editor/TiptapEditor/useWikiLinkNavigation.test.ts
+++ b/src/components/editor/TiptapEditor/useWikiLinkNavigation.test.ts
@@ -178,6 +178,193 @@ describe("useWikiLinkNavigation", () => {
     expect(result.current.pendingCreatePageTitle).toBe(null);
   });
 
+  // Issue #931: 既存個人ページに対する Cmd/Ctrl+クリックは、クリック時に
+  // 同期で `window.open("about:blank")` を呼んでユーザーアクティベーション
+  // を確保し、ページ解決後にそのタブの `location.href` を差し替える。
+  // ルータは呼ばないこと。
+  // Issue #931: Cmd/Ctrl+click on an existing personal page opens an
+  // `about:blank` tab synchronously to preserve user activation and
+  // updates its `location.href` once the page resolves. The router must
+  // not be invoked.
+  it("既存個人ページに対する newTab クリックは about:blank を同期で開き、解決後に location を上書きする", async () => {
+    const mockWindow = { location: { href: "" }, close: vi.fn() };
+    const openSpy = vi.spyOn(window, "open").mockReturnValue(mockWindow as unknown as Window);
+    vi.mocked(usePageByTitle).mockImplementation(
+      (title: string) =>
+        ({
+          data:
+            title === "Existing Page"
+              ? { id: "existing-id", title: "Existing Page", noteId: DEFAULT_NOTE_ID }
+              : undefined,
+          isFetched: title !== "",
+        }) as ReturnType<typeof usePageByTitle>,
+    );
+
+    const { result } = renderHook(() => useWikiLinkNavigation(), {
+      wrapper: createHookWrapper(),
+    });
+
+    act(() => {
+      result.current.handleLinkClick("Existing Page", { newTab: true });
+    });
+
+    // The blank tab is reserved synchronously inside the click handler.
+    expect(openSpy).toHaveBeenCalledWith("about:blank", "_blank", "noopener,noreferrer");
+
+    await waitFor(() => {
+      expect(mockWindow.location.href).toBe(`/notes/${DEFAULT_NOTE_ID}/existing-id`);
+    });
+    expect(mockNavigate).not.toHaveBeenCalled();
+    expect(mockWindow.close).not.toHaveBeenCalled();
+
+    openSpy.mockRestore();
+  });
+
+  // Issue #931: ゴーストリンクを Cmd/Ctrl+クリックすると、クリック時に
+  // about:blank タブを確保 → 確認ダイアログを表示 → 確定後にそのタブの
+  // `location.href` を新規ページに差し替える。
+  // Issue #931: Cmd/Ctrl+click on a ghost link reserves an `about:blank`
+  // tab during the user gesture, shows the confirm dialog, and rewrites
+  // the tab's `location.href` after the mutation succeeds.
+  it("newTab で開いたゴーストリンクは Dialog 確定で about:blank の location を上書きする", async () => {
+    const mockWindow = { location: { href: "" }, close: vi.fn() };
+    const openSpy = vi.spyOn(window, "open").mockReturnValue(mockWindow as unknown as Window);
+    mockMutateAsync.mockResolvedValue({ id: "new-page-id", noteId: DEFAULT_NOTE_ID });
+    vi.mocked(usePageByTitle).mockImplementation(
+      (title: string) =>
+        ({
+          data: undefined,
+          isFetched: title !== "",
+        }) as ReturnType<typeof usePageByTitle>,
+    );
+
+    const { result } = renderHook(() => useWikiLinkNavigation(), {
+      wrapper: createHookWrapper(),
+    });
+
+    act(() => {
+      result.current.handleLinkClick("Brand New", { newTab: true });
+    });
+    expect(openSpy).toHaveBeenCalledWith("about:blank", "_blank", "noopener,noreferrer");
+
+    await waitFor(() => {
+      expect(result.current.createPageDialogOpen).toBe(true);
+      expect(result.current.pendingCreatePageTitle).toBe("Brand New");
+    });
+
+    await act(async () => {
+      await result.current.handleConfirmCreate();
+    });
+
+    expect(mockMutateAsync).toHaveBeenCalledWith({ title: "Brand New", content: "" });
+    expect(mockWindow.location.href).toBe(`/notes/${DEFAULT_NOTE_ID}/new-page-id`);
+    expect(mockNavigate).not.toHaveBeenCalled();
+    expect(result.current.createPageDialogOpen).toBe(false);
+    expect(mockWindow.close).not.toHaveBeenCalled();
+
+    openSpy.mockRestore();
+  });
+
+  // Issue #931: newTab で開いたゴーストをキャンセルすると、確保済みの
+  // about:blank タブを閉じる。次の通常クリックでは navigate にフォール
+  // バックすること。
+  // Issue #931: cancelling a new-tab ghost dialog must close the reserved
+  // `about:blank` tab and leave subsequent normal clicks untouched.
+  it("newTab ゴーストをキャンセルすると about:blank を閉じ、次の通常クリックは navigate にフォールバックする", async () => {
+    const cancelledWindow = { location: { href: "" }, close: vi.fn() };
+    const openSpy = vi.spyOn(window, "open").mockReturnValue(cancelledWindow as unknown as Window);
+    mockMutateAsync.mockResolvedValue({ id: "second-id", noteId: DEFAULT_NOTE_ID });
+    vi.mocked(usePageByTitle).mockImplementation(
+      (title: string) =>
+        ({
+          data: undefined,
+          isFetched: title !== "",
+        }) as ReturnType<typeof usePageByTitle>,
+    );
+
+    const { result } = renderHook(() => useWikiLinkNavigation(), {
+      wrapper: createHookWrapper(),
+    });
+
+    act(() => {
+      result.current.handleLinkClick("Ghost A", { newTab: true });
+    });
+    // 初回クリックでは about:blank を確保する。
+    // The initial click reserves an `about:blank` tab.
+    expect(openSpy).toHaveBeenCalledTimes(1);
+    expect(openSpy).toHaveBeenCalledWith("about:blank", "_blank", "noopener,noreferrer");
+    await waitFor(() => {
+      expect(result.current.createPageDialogOpen).toBe(true);
+    });
+    act(() => {
+      result.current.handleCancelCreate();
+    });
+    // キャンセル時は確保したタブを閉じる。
+    // Cancel closes the reserved tab.
+    expect(cancelledWindow.close).toHaveBeenCalledTimes(1);
+
+    openSpy.mockClear();
+    act(() => {
+      result.current.handleLinkClick("Ghost B");
+    });
+    // newTab なしのクリックは window.open を呼ばない。
+    // A normal click must not invoke `window.open`.
+    expect(openSpy).not.toHaveBeenCalled();
+    await waitFor(() => {
+      expect(result.current.createPageDialogOpen).toBe(true);
+      expect(result.current.pendingCreatePageTitle).toBe("Ghost B");
+    });
+
+    await act(async () => {
+      await result.current.handleConfirmCreate();
+    });
+
+    expect(mockNavigate).toHaveBeenCalledWith(`/notes/${DEFAULT_NOTE_ID}/second-id`, {
+      replace: false,
+      flushSync: true,
+    });
+
+    openSpy.mockRestore();
+  });
+
+  // Issue #931: ミューテーション失敗時は確保した about:blank を閉じる。
+  // Issue #931: a failed mutation must close the reserved blank tab so
+  // the user is not left with a stray popup.
+  it("newTab ゴーストでミューテーションが失敗したら about:blank を閉じる", async () => {
+    const mockWindow = { location: { href: "" }, close: vi.fn() };
+    const openSpy = vi.spyOn(window, "open").mockReturnValue(mockWindow as unknown as Window);
+    const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    mockMutateAsync.mockRejectedValue(new Error("network down"));
+    vi.mocked(usePageByTitle).mockImplementation(
+      (title: string) =>
+        ({
+          data: undefined,
+          isFetched: title !== "",
+        }) as ReturnType<typeof usePageByTitle>,
+    );
+
+    const { result } = renderHook(() => useWikiLinkNavigation(), {
+      wrapper: createHookWrapper(),
+    });
+
+    act(() => {
+      result.current.handleLinkClick("Fails", { newTab: true });
+    });
+    await waitFor(() => {
+      expect(result.current.createPageDialogOpen).toBe(true);
+    });
+
+    await act(async () => {
+      await result.current.handleConfirmCreate();
+    });
+
+    expect(mockWindow.close).toHaveBeenCalledTimes(1);
+    expect(mockWindow.location.href).toBe("");
+
+    openSpy.mockRestore();
+    consoleErrorSpy.mockRestore();
+  });
+
   it("re-clicking a just-created title navigates immediately without reopening dialog", async () => {
     mockMutateAsync.mockResolvedValue({ id: "new-page-id", noteId: DEFAULT_NOTE_ID });
     const byTitleCache: Record<string, { id: string; title: string; noteId: string } | undefined> =
@@ -299,6 +486,39 @@ describe("useWikiLinkNavigation", () => {
       expect(result.current.pendingCreatePageTitle).toBe(null);
     });
 
+    // Issue #931: Cmd/Ctrl+クリックや中クリックでは、クリック時に同期で
+    // `about:blank` を確保 → 解決後に `location.href` を上書きする。
+    // ルータは呼ばないこと。
+    // Issue #931: modifier / middle-click clicks reserve an `about:blank`
+    // tab synchronously and rewrite its `location.href` once the note
+    // page resolves. The router must not be invoked.
+    it("既存ノートページに対する newTab クリックは about:blank を同期で開き、解決後に location を上書きする", async () => {
+      const mockWindow = { location: { href: "" }, close: vi.fn() };
+      const openSpy = vi.spyOn(window, "open").mockReturnValue(mockWindow as unknown as Window);
+      vi.mocked(useNoteTitleIndex).mockReturnValue({
+        data: [{ id: "note-page-1", title: "Note Page A", isDeleted: false, updatedAt: 0 }],
+        isFetched: true,
+        isLoading: false,
+      } as unknown as ReturnType<typeof useNoteTitleIndex>);
+
+      const { result } = renderHook(() => useWikiLinkNavigation({ pageNoteId: noteId }), {
+        wrapper: createHookWrapper(),
+      });
+
+      act(() => {
+        result.current.handleLinkClick("Note Page A", { newTab: true });
+      });
+      expect(openSpy).toHaveBeenCalledWith("about:blank", "_blank", "noopener,noreferrer");
+
+      await waitFor(() => {
+        expect(mockWindow.location.href).toBe(`/notes/${noteId}/note-page-1`);
+      });
+      expect(mockNavigate).not.toHaveBeenCalled();
+      expect(mockWindow.close).not.toHaveBeenCalled();
+
+      openSpy.mockRestore();
+    });
+
     it("削除済みノートページと同一タイトルのクリックでは、ダイアログを開いて新規作成フローに入る", async () => {
       vi.mocked(useNoteTitleIndex).mockReturnValue({
         data: [{ id: "tombstone", title: "Archived", isDeleted: true, updatedAt: 0 }],
diff --git a/src/components/editor/TiptapEditor/useWikiLinkNavigation.ts b/src/components/editor/TiptapEditor/useWikiLinkNavigation.ts
index 61d70f50..c3acc71f 100644
--- a/src/components/editor/TiptapEditor/useWikiLinkNavigation.ts
+++ b/src/components/editor/TiptapEditor/useWikiLinkNavigation.ts
@@ -18,8 +18,20 @@ interface UseWikiLinkNavigationOptions {
   pageNoteId: string | null;
 }
 
+/**
+ * クリック時の追加オプション。`newTab` が `true` のときは `window.open` で
+ * 新タブを開き、現在のタブの URL は変更しない（Issue #931）。
+ *
+ * Click options. When `newTab` is `true`, navigation opens the destination
+ * in a new tab via `window.open` and the current tab is left untouched
+ * (Issue #931).
+ */
+interface WikiLinkNavigationOptions {
+  newTab?: boolean;
+}
+
 interface UseWikiLinkNavigationReturn {
-  handleLinkClick: (title: string) => void;
+  handleLinkClick: (title: string, options?: WikiLinkNavigationOptions) => void;
   createPageDialogOpen: boolean;
   pendingCreatePageTitle: string | null;
   handleConfirmCreate: () => Promise<void>;
@@ -145,7 +157,31 @@ export function useWikiLinkNavigation(
   const isFetched = pageNoteId === null ? personalResolved.isFetched : noteLookup.isFetched;
 
   // Pending link action
-  const pendingLinkActionRef = useRef<{ title: string } | null>(null);
+  // Issue #931: `newTab` を保持して既存ページ解決 / ダイアログ確定の両方で
+  // window.open ⇔ navigate を切り替える。
+  // Issue #931: persist the `newTab` intent so both the existing-page
+  // resolution and the create-dialog confirmation can switch between
+  // `window.open` and `navigate`.
+  const pendingLinkActionRef = useRef<{ title: string; newTab: boolean } | null>(null);
+  // ダイアログ確定時に `window.open` を使うかを保存する。Cmd+クリックで
+  // ゴーストリンクを開いた場合、ダイアログを通常通り表示しつつ確定後の
+  // 遷移だけ新タブにする（Issue #931）。
+  // Tracks whether the create-dialog confirmation should open the new
+  // page in a new tab. Preserved separately from `pendingLinkActionRef`
+  // because that ref is cleared once navigation resolution finishes.
+  const pendingCreatePageNewTabRef = useRef<boolean>(false);
+  // Issue #931: ユーザー操作の同期スタック内で `window.open("about:blank")`
+  // を呼んで取得しておく WindowProxy。後続の `useEffect` / `await` 後の
+  // `window.open` はブラウザのポップアップブロッカ（特に Safari / Firefox）
+  // でユーザーアクティベーション切れと判定されるため、クリック時に空タブを
+  // 確保しておき、解決後に `location.href` を差し替える方式を採用する。
+  //
+  // Pre-opened `about:blank` WindowProxy captured during the synchronous
+  // click handler. Calling `window.open` after a `useEffect` or `await`
+  // boundary loses transient user activation, so Safari and Firefox block
+  // the popup. Opening synchronously here and updating `location.href`
+  // once the navigation target resolves preserves the gesture.
+  const pendingNewTabWindowRef = useRef<Window | null>(null);
 
   // Create page confirmation dialog state
   const [createPageDialogOpen, setCreatePageDialogOpen] = useState(false);
@@ -153,18 +189,54 @@ export function useWikiLinkNavigation(
 
   // Handle link click - navigate to page or create new
   // WikiLinkクリック時は常に既存ページの存在をチェック（byTitle キャッシュに依存、createdPageIdsRef は廃止）
-  const handleLinkClick = useCallback((title: string) => {
-    pendingLinkActionRef.current = { title };
+  const handleLinkClick = useCallback((title: string, options?: WikiLinkNavigationOptions) => {
+    const newTab = options?.newTab ?? false;
+    if (newTab) {
+      // Issue #931: ユーザー操作中に同期で空タブを開く。ポップアップが
+      // ブロックされた場合は `null` が返るので後続処理は skip する。
+      // Issue #931: open the blank tab synchronously while the user
+      // gesture is still live. If the popup is blocked, `window.open`
+      // returns `null` and downstream handlers silently no-op.
+      pendingNewTabWindowRef.current = window.open("about:blank", "_blank", "noopener,noreferrer");
+    }
+    pendingLinkActionRef.current = { title, newTab };
     setLinkTitleToFind(title);
   }, []);
 
+  /**
+   * 確保した about:blank タブに最終 URL を設定する。`null` の場合（ブロック
+   * 済み）は何もしない。
+   *
+   * Assign the final URL to the previously opened `about:blank` tab.
+   * No-op when popup was blocked (`null`).
+   */
+  const navigateNewTab = useCallback((targetUrl: string) => {
+    const w = pendingNewTabWindowRef.current;
+    pendingNewTabWindowRef.current = null;
+    if (w) {
+      w.location.href = targetUrl;
+    }
+  }, []);
+
+  /**
+   * 確保した about:blank タブを閉じる（キャンセル / 失敗 / note-scope no-op 用）。
+   *
+   * Close the reserved `about:blank` tab. Used by cancel, failed
+   * mutations, and the note-scope no-op confirmation path.
+   */
+  const closePendingNewTabWindow = useCallback(() => {
+    const w = pendingNewTabWindowRef.current;
+    pendingNewTabWindowRef.current = null;
+    w?.close();
+  }, []);
+
   // Navigate when found page changes
   useEffect(() => {
     const handleNavigation = async () => {
       // linkTitleToFindが設定されていない場合は何もしない
       if (!linkTitleToFind || !pendingLinkActionRef.current) return;
 
-      const { title } = pendingLinkActionRef.current;
+      const { title, newTab } = pendingLinkActionRef.current;
 
       // タイトルが一致しない場合は何もしない
       if (linkTitleToFind !== title) return;
@@ -183,12 +255,30 @@ export function useWikiLinkNavigation(
         // After Issue #889 Phase 3 retired `/pages/:id`, navigation always
         // targets `/notes/:noteId/:pageId`. Both resolution paths populate
         // `foundPage.noteId` so this branch unifies cleanly.
-        navigate(`/notes/${foundPage.noteId}/${foundPage.id}`, {
-          replace: false,
-          flushSync: true,
-        });
+        const targetUrl = `/notes/${foundPage.noteId}/${foundPage.id}`;
+        if (newTab) {
+          // Issue #931: クリック時に同期で開いた about:blank タブの location を
+          // 上書きする。`window.open` をここで呼ぶとポップアップブロッカに
+          // 引っかかるため不可（Safari / Firefox）。
+          // Issue #931: rewrite the pre-opened `about:blank` tab. Calling
+          // `window.open` here would be blocked by Safari/Firefox popup
+          // policies because the user gesture has expired.
+          navigateNewTab(targetUrl);
+        } else {
+          navigate(targetUrl, {
+            replace: false,
+            flushSync: true,
+          });
+        }
       } else {
-        // ページが見つからなかった場合は確認ダイアログを表示
+        // ページが見つからなかった場合は確認ダイアログを表示。
+        // 新タブ意図はダイアログ確定時に消費するので別 ref に退避する（Issue #931）。
+        // 確保済みの about:blank タブはダイアログの確定／キャンセル時に
+        // 消費／クローズされる。
+        // Stash the new-tab intent so the create-dialog confirmation can
+        // honor it later (Issue #931). The reserved `about:blank` window
+        // is consumed on confirm or closed on cancel.
+        pendingCreatePageNewTabRef.current = newTab;
         setPendingCreatePageTitle(title);
         setCreatePageDialogOpen(true);
       }
@@ -199,7 +289,7 @@ export function useWikiLinkNavigation(
     };
 
     handleNavigation();
-  }, [foundPage, isFetched, linkTitleToFind, navigate, pageNoteId]);
+  }, [foundPage, isFetched, linkTitleToFind, navigate, navigateNewTab, pageNoteId]);
 
   // Handle create page confirmation
   // 新規ページ作成は `useCreatePage` 経由でデフォルトノートまたは指定ノートに
@@ -215,9 +305,14 @@ export function useWikiLinkNavigation(
   const handleConfirmCreate = useCallback(async () => {
     if (!pendingCreatePageTitle) return;
     if (pageNoteId) {
-      // ノートスコープ内での新規作成は未対応。今は何もせずダイアログを閉じる。
+      // ノートスコープ内での新規作成は未対応。確保済み about:blank タブは
+      // 閉じてダイアログだけ閉じる。
+      // Note-scope creation is not yet wired up. Close the reserved blank
+      // tab so the user is not left with an empty popup.
+      closePendingNewTabWindow();
       setCreatePageDialogOpen(false);
       setPendingCreatePageTitle(null);
+      pendingCreatePageNewTabRef.current = false;
       return;
     }
 
@@ -228,19 +323,48 @@ export function useWikiLinkNavigation(
       });
       setCreatePageDialogOpen(false);
       setPendingCreatePageTitle(null);
-      navigate(`/notes/${newPage.noteId}/${newPage.id}`, {
-        replace: false,
-        flushSync: true,
-      });
+      const targetUrl = `/notes/${newPage.noteId}/${newPage.id}`;
+      const newTab = pendingCreatePageNewTabRef.current;
+      pendingCreatePageNewTabRef.current = false;
+      if (newTab) {
+        // Issue #931: クリック時に確保した about:blank タブの location を
+        // 上書きする。await 後に `window.open` を呼ぶとポップアップブロッカ
+        // でブロックされる（Safari / Firefox / Chrome の strict 設定）。
+        // Issue #931: rewrite the pre-opened blank tab. A fresh
+        // `window.open` after `await` is treated as a gesture-less popup
+        // and blocked.
+        navigateNewTab(targetUrl);
+      } else {
+        navigate(targetUrl, {
+          replace: false,
+          flushSync: true,
+        });
+      }
     } catch (error) {
+      // ミューテーション失敗時は確保しておいた about:blank タブを閉じて
+      // 空白タブが残らないようにする。
+      // Close the reserved blank tab on failure to avoid leaving a stray
+      // popup behind.
+      closePendingNewTabWindow();
       console.error("Failed to create page:", error);
     }
-  }, [pendingCreatePageTitle, createPageMutation, navigate, pageNoteId]);
+  }, [
+    pendingCreatePageTitle,
+    createPageMutation,
+    navigate,
+    navigateNewTab,
+    closePendingNewTabWindow,
+    pageNoteId,
+  ]);
 
   const handleCancelCreate = useCallback(() => {
+    // 確保済み about:blank タブを閉じる（Issue #931）。
+    // Close the reserved blank tab so cancelling does not leave a popup.
+    closePendingNewTabWindow();
     setCreatePageDialogOpen(false);
     setPendingCreatePageTitle(null);
-  }, []);
+    pendingCreatePageNewTabRef.current = false;
+  }, [closePendingNewTabWindow]);
 
   return {
     handleLinkClick,
diff --git a/src/components/editor/WikiGeneratorButton.tsx b/src/components/editor/WikiGeneratorButton.tsx
index c26a825b..5998109b 100644
--- a/src/components/editor/WikiGeneratorButton.tsx
+++ b/src/components/editor/WikiGeneratorButton.tsx
@@ -17,16 +17,40 @@ import { isAIConfigured } from "@/lib/aiSettings";
 interface WikiGeneratorButtonProps {
   title: string;
   hasContent: boolean;
-  /** 生成を開始するコールバック */
+  /**
+   * インラインWiki生成（旧 useWikiGenerator）のコールバック。`composeHref` を
+   * 渡したときは Compose 画面に遷移するため呼ばれない。Inline generation
+   * callback (legacy path); skipped when `composeHref` is provided.
+   */
   onGenerate: () => void;
   /** 現在の生成ステータス */
   status: WikiGeneratorStatus;
   disabled?: boolean;
+  /**
+   * Wiki Compose 画面の遷移先 URL。指定時はクリックで navigate し、本文ありでも
+   * ボタンを表示する (Compose は追記モードをサポートするため、issue #950 U2)。
+   *
+   * When provided, the button navigates to the Wiki Compose split-screen UI
+   * instead of calling `onGenerate`, and visibility no longer requires
+   * `hasContent === false` (Compose supports the append-mode flow per #950 U2).
+   */
+  composeHref?: string;
 }
 
 /**
- * Wiki 生成ボタン。タイトルがあり、本文が未入力のときだけ表示する。
- * Wiki generation button shown only when the note has a title and no body yet.
+ * Wiki 生成ボタン。
+ *
+ * - `composeHref` 未指定（旧経路）: タイトルがあり本文が未入力のときだけ表示し、
+ *   クリックで `onGenerate` を呼ぶ。
+ * - `composeHref` 指定（新経路, #950）: タイトルがあれば本文有無に関わらず表示し、
+ *   クリックで Compose 画面に navigate する。
+ *
+ * Wiki generation button.
+ *
+ * - Without `composeHref` (legacy): shows only when there is a title and no
+ *   body content; click invokes the inline `onGenerate` callback.
+ * - With `composeHref` (issue #950): shows whenever there is a title (Compose
+ *   handles append vs replace internally); click navigates to the Compose UI.
  */
 export const WikiGeneratorButton: React.FC<WikiGeneratorButtonProps> = ({
   title,
@@ -34,17 +58,27 @@ export const WikiGeneratorButton: React.FC<WikiGeneratorButtonProps> = ({
   onGenerate,
   status,
   disabled = false,
+  composeHref,
 }) => {
   const navigate = useNavigate();
   const location = useLocation();
   const [showNotConfiguredDialog, setShowNotConfiguredDialog] = React.useState(false);
 
-  // タイトルがない、または本文がある場合はボタンを非表示
-  const shouldShowButton = title.trim() !== "" && !hasContent;
+  // タイトルがない場合は常に非表示。
+  // Compose 経路では本文ありでも表示する (#950 U2: append default)。
+  // 旧経路では本文ありなら非表示 (inline generation はページを上書きするため)。
+  const hasTitle = title.trim() !== "";
+  const shouldShowButton = composeHref ? hasTitle : hasTitle && !hasContent;
 
   const isGenerating = status === "generating";
 
   const handleClick = async () => {
+    // Compose 経路: 認可チェック不要（Compose 画面で実行する）。
+    // Compose path: no AI-config check; the Compose UI handles it server-side.
+    if (composeHref) {
+      navigate(composeHref);
+      return;
+    }
     // AI が利用可能か確認（api_server モードでは API キー不要）。
     // Check AI availability (no API key required in api_server mode).
     const configured = await isAIConfigured();
@@ -87,7 +121,7 @@ export const WikiGeneratorButton: React.FC<WikiGeneratorButtonProps> = ({
           </Button>
         </TooltipTrigger>
         <TooltipContent>
-          <p>AIでWikipedia風の解説を生成</p>
+          <p>{composeHref ? "AI と対話しながら Wiki を作成" : "AIでWikipedia風の解説を生成"}</p>
         </TooltipContent>
       </Tooltip>
 
diff --git a/src/components/editor/WikiLinkInputBar.test.tsx b/src/components/editor/WikiLinkInputBar.test.tsx
new file mode 100644
index 00000000..cb0b6923
--- /dev/null
+++ b/src/components/editor/WikiLinkInputBar.test.tsx
@@ -0,0 +1,449 @@
+import React from "react";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { act, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import type { Editor } from "@tiptap/core";
+
+// `react-i18next` の `useTranslation` をスタブして、JSON キーをそのまま返す
+// ように振る舞わせる。これにより i18n プロバイダを用意せずに表示文字列の
+// アサーションができる（他テストでも採用されている軽量パターン）。
+// Stub `useTranslation` so it returns the key verbatim; lets us assert on
+// rendered strings without setting up the i18n provider (matches the lightweight
+// pattern used elsewhere in this repo).
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+const mockUseWikiLinkCandidates = vi.fn();
+vi.mock("@/hooks/useWikiLinkCandidates", () => ({
+  useWikiLinkCandidates: (noteId: string | null) => mockUseWikiLinkCandidates(noteId),
+}));
+
+const mockCheckExistence = vi.fn();
+const mockCheckReferenced = vi.fn();
+const mockUseWikiLinkExistsChecker = vi.fn(() => ({ checkExistence: mockCheckExistence }));
+vi.mock("@/hooks/usePageQueries", () => ({
+  useWikiLinkExistsChecker: (options: unknown) => mockUseWikiLinkExistsChecker(options),
+  useCheckGhostLinkReferenced: () => ({ checkReferenced: mockCheckReferenced }),
+}));
+
+import { WikiLinkInputBar } from "./WikiLinkInputBar";
+
+interface MockChainReturn {
+  focus: ReturnType<typeof vi.fn>;
+  insertContentAt: ReturnType<typeof vi.fn>;
+  setTextSelection: ReturnType<typeof vi.fn>;
+  run: ReturnType<typeof vi.fn>;
+}
+
+interface MockEditor extends Editor {
+  chainReturn: MockChainReturn;
+  commandsReturn: { focus: ReturnType<typeof vi.fn> };
+}
+
+function createMockEditor(
+  options: { selectionFrom?: number; selectionTo?: number } = {},
+): MockEditor {
+  const { selectionFrom = 5, selectionTo = 5 } = options;
+  const run = vi.fn();
+  const focusChain: ReturnType<typeof vi.fn> = vi.fn().mockReturnThis();
+  const insertContentAt: ReturnType<typeof vi.fn> = vi.fn().mockReturnThis();
+  const setTextSelection: ReturnType<typeof vi.fn> = vi.fn().mockReturnThis();
+  const chainReturn: MockChainReturn = {
+    focus: focusChain,
+    insertContentAt,
+    setTextSelection,
+    run,
+  };
+  const commandsReturn = { focus: vi.fn() };
+  const editor = {
+    state: {
+      selection: { from: selectionFrom, to: selectionTo },
+    },
+    chain: vi.fn(() => chainReturn),
+    commands: commandsReturn,
+    chainReturn,
+    commandsReturn,
+  } as unknown as MockEditor;
+  return editor;
+}
+
+describe("WikiLinkInputBar - 基本表示 / basic rendering", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockUseWikiLinkCandidates.mockReturnValue({ pages: [], isLoading: false });
+    mockUseWikiLinkExistsChecker.mockImplementation(() => ({
+      checkExistence: mockCheckExistence,
+    }));
+    mockCheckExistence.mockResolvedValue({
+      pageTitles: new Set(),
+      referencedTitles: new Set(),
+      pageTitleToId: new Map(),
+    });
+    mockCheckReferenced.mockResolvedValue(false);
+  });
+
+  it("プレースホルダ『ページを作成』と aria-label を持つ入力欄を描画する / renders the input with the placeholder + aria-label i18n keys", () => {
+    const editor = createMockEditor();
+    render(<WikiLinkInputBar editor={editor} pageId="p1" pageNoteId={null} />);
+
+    const input = screen.getByTestId("wiki-link-input-bar-input") as HTMLInputElement;
+    // i18n キーは `useTranslation` モックで素通りするため、キー自体が
+    // placeholder / aria-label として現れる。値そのものは `common.json` 側の
+    // テキスト。Accessible-name の i18n key 連結が崩れていないことを担保する。
+    // The `useTranslation` mock passes keys through, so the placeholder and
+    // aria-label show up as the i18n keys themselves. Pinning both keys keeps
+    // the accessible-name spec from silently regressing.
+    expect(input.placeholder).toBe("common.wikiLinkInputBar.placeholder");
+    expect(input.getAttribute("aria-label")).toBe("common.wikiLinkInputBar.ariaLabel");
+  });
+
+  it("入力が空のときはサジェストを描画しない / does not render the suggestion list when input is empty", () => {
+    const editor = createMockEditor();
+    mockUseWikiLinkCandidates.mockReturnValue({
+      pages: [{ id: "p-alpha", title: "Alpha", isDeleted: false }],
+      isLoading: false,
+    });
+    render(<WikiLinkInputBar editor={editor} pageId="p1" pageNoteId={null} />);
+
+    // 入力が空のうちは候補ポップアップを開かない（フォーカス前と同じ挙動）。
+    // While the input is empty, suggestions stay hidden — same as when the bar
+    // has not been focused at all.
+    expect(screen.queryByTestId("wiki-link-suggestion")).not.toBeInTheDocument();
+  });
+
+  it("入力したクエリで `useWikiLinkCandidates` の候補を絞り、サジェストを開く / opens the suggestion popup once the user types", async () => {
+    const user = userEvent.setup();
+    const editor = createMockEditor();
+    mockUseWikiLinkCandidates.mockReturnValue({
+      pages: [
+        { id: "p-alpha", title: "Alpha", isDeleted: false },
+        { id: "p-beta", title: "Beta", isDeleted: false },
+      ],
+      isLoading: false,
+    });
+    render(<WikiLinkInputBar editor={editor} pageId="p1" pageNoteId={null} />);
+
+    await user.type(screen.getByTestId("wiki-link-input-bar-input"), "Al");
+
+    expect(screen.getByTestId("wiki-link-suggestion")).toBeInTheDocument();
+    expect(screen.getByText("Alpha")).toBeInTheDocument();
+  });
+});
+
+describe("WikiLinkInputBar - 確定挙動 / confirm behavior", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockUseWikiLinkCandidates.mockReturnValue({ pages: [], isLoading: false });
+    mockUseWikiLinkExistsChecker.mockImplementation(() => ({
+      checkExistence: mockCheckExistence,
+    }));
+    mockCheckExistence.mockResolvedValue({
+      pageTitles: new Set(),
+      referencedTitles: new Set(),
+      pageTitleToId: new Map(),
+    });
+    mockCheckReferenced.mockResolvedValue(false);
+  });
+
+  it("Enter で完全一致が無いときはゴーストリンクを退避位置に挿入する / Enter inserts a ghost wiki link at the saved cursor when no exact match", async () => {
+    const user = userEvent.setup();
+    const editor = createMockEditor({ selectionFrom: 12, selectionTo: 12 });
+    mockCheckReferenced.mockResolvedValue(true);
+    render(<WikiLinkInputBar editor={editor} pageId="p1" pageNoteId={null} />);
+
+    const input = screen.getByTestId("wiki-link-input-bar-input");
+    await user.click(input);
+    // クリック時点で editor.state.selection を退避していることを担保するため、
+    // 入力中に editor.state.selection を変えてみる（フォーカス前位置で挿入される
+    // ことを確認）。
+    // Mutate `editor.state.selection` after focus to ensure the bar reuses the
+    // saved position rather than reading current state at confirm time.
+    (editor.state.selection as { from: number; to: number }).from = 999;
+    (editor.state.selection as { from: number; to: number }).to = 999;
+    await user.type(input, "New Topic");
+    await user.keyboard("{Enter}");
+
+    // `insertLink` は `void` で fire-and-forget するため、確定処理が次の
+    // microtask で完了するのを `waitFor` で待つ。
+    // The confirm path is fire-and-forget (`void insertLink(...)`), so we
+    // need `waitFor` to flush the resolved promise before asserting.
+    await waitFor(() => {
+      expect(editor.chainReturn.insertContentAt).toHaveBeenCalled();
+    });
+    expect(mockCheckExistence).toHaveBeenCalledWith(["New Topic"], "p1");
+    expect(mockCheckReferenced).toHaveBeenCalledWith("New Topic", "p1");
+    expect(editor.chainReturn.insertContentAt).toHaveBeenCalledWith(12, [
+      {
+        type: "text",
+        marks: [
+          {
+            type: "wikiLink",
+            attrs: { title: "New Topic", exists: false, referenced: true, targetId: null },
+          },
+        ],
+        text: "[[New Topic]]",
+      },
+    ]);
+    expect(editor.chainReturn.run).toHaveBeenCalled();
+  });
+
+  it("Enter で入力が候補と完全一致したら既存ページリンクを挿入する / Enter falls back to the existing page link on exact match", async () => {
+    const user = userEvent.setup();
+    const editor = createMockEditor({ selectionFrom: 3, selectionTo: 3 });
+    mockUseWikiLinkCandidates.mockReturnValue({
+      pages: [{ id: "p-alpha", title: "Alpha", isDeleted: false }],
+      isLoading: false,
+    });
+    mockCheckExistence.mockResolvedValue({
+      pageTitles: new Set(["alpha"]),
+      referencedTitles: new Set(),
+      pageTitleToId: new Map([["alpha", "p-alpha"]]),
+    });
+
+    render(<WikiLinkInputBar editor={editor} pageId="p1" pageNoteId={null} />);
+
+    const input = screen.getByTestId("wiki-link-input-bar-input");
+    await user.click(input);
+    await user.type(input, "Alpha");
+    await user.keyboard("{Enter}");
+
+    await waitFor(() => {
+      expect(editor.chainReturn.insertContentAt).toHaveBeenCalled();
+    });
+    expect(editor.chainReturn.insertContentAt).toHaveBeenCalledWith(3, [
+      {
+        type: "text",
+        marks: [
+          {
+            type: "wikiLink",
+            attrs: { title: "Alpha", exists: true, referenced: false, targetId: "p-alpha" },
+          },
+        ],
+        text: "[[Alpha]]",
+      },
+    ]);
+    // ghost ではないので `checkReferenced` は呼ばれない。
+    // No ghost branch → `checkReferenced` is not consulted.
+    expect(mockCheckReferenced).not.toHaveBeenCalled();
+  });
+
+  it("候補クリックでも既存ページリンクを挿入し入力欄をクリアする / clicking a suggestion inserts the existing-page link and clears the input", async () => {
+    const user = userEvent.setup();
+    const editor = createMockEditor({ selectionFrom: 7, selectionTo: 7 });
+    mockUseWikiLinkCandidates.mockReturnValue({
+      pages: [{ id: "p-alpha", title: "Alpha", isDeleted: false }],
+      isLoading: false,
+    });
+    mockCheckExistence.mockResolvedValue({
+      pageTitles: new Set(["alpha"]),
+      referencedTitles: new Set(),
+      pageTitleToId: new Map([["alpha", "p-alpha"]]),
+    });
+
+    render(<WikiLinkInputBar editor={editor} pageId="p1" pageNoteId={null} />);
+
+    const input = screen.getByTestId("wiki-link-input-bar-input") as HTMLInputElement;
+    await user.click(input);
+    await user.type(input, "Al");
+
+    await user.click(screen.getByText("Alpha"));
+
+    await waitFor(() => {
+      expect(editor.chainReturn.insertContentAt).toHaveBeenCalled();
+    });
+    expect(editor.chainReturn.insertContentAt).toHaveBeenCalledWith(7, [
+      {
+        type: "text",
+        marks: [
+          {
+            type: "wikiLink",
+            attrs: { title: "Alpha", exists: true, referenced: false, targetId: "p-alpha" },
+          },
+        ],
+        text: "[[Alpha]]",
+      },
+    ]);
+    await waitFor(() => {
+      expect(input.value).toBe("");
+    });
+  });
+
+  it("確定後にエディタへフォーカスを戻す / restores editor focus after confirming", async () => {
+    const user = userEvent.setup();
+    const editor = createMockEditor({ selectionFrom: 2, selectionTo: 2 });
+    render(<WikiLinkInputBar editor={editor} pageId="p1" pageNoteId={null} />);
+
+    const input = screen.getByTestId("wiki-link-input-bar-input");
+    await user.click(input);
+    await user.type(input, "Topic");
+    await user.keyboard("{Enter}");
+
+    // 挿入チェーンの `focus()` で確実にエディタへ戻る。
+    // The insertion chain's `focus()` ensures editor focus is restored.
+    await waitFor(() => {
+      expect(editor.chainReturn.focus).toHaveBeenCalled();
+    });
+  });
+});
+
+describe("WikiLinkInputBar - ガード / guards", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockUseWikiLinkCandidates.mockReturnValue({ pages: [], isLoading: false });
+    mockUseWikiLinkExistsChecker.mockImplementation(() => ({
+      checkExistence: mockCheckExistence,
+    }));
+  });
+
+  it("editor が null のときは何もしない / no-op when editor is null", async () => {
+    const user = userEvent.setup();
+    render(<WikiLinkInputBar editor={null} pageId="p1" pageNoteId={null} />);
+
+    const input = screen.getByTestId("wiki-link-input-bar-input");
+    await user.type(input, "Whatever");
+    await user.keyboard("{Enter}");
+
+    // editor が存在しないので外部依存は呼ばれない。
+    // External dependencies are untouched without an editor.
+    expect(mockCheckExistence).not.toHaveBeenCalled();
+    expect(mockCheckReferenced).not.toHaveBeenCalled();
+  });
+
+  it("空白だけの入力では確定処理を行わない / does not confirm an all-whitespace input", async () => {
+    const user = userEvent.setup();
+    const editor = createMockEditor();
+    render(<WikiLinkInputBar editor={editor} pageId="p1" pageNoteId={null} />);
+
+    const input = screen.getByTestId("wiki-link-input-bar-input");
+    await user.click(input);
+    await user.type(input, "   ");
+    await user.keyboard("{Enter}");
+
+    expect(editor.chain).not.toHaveBeenCalled();
+  });
+
+  it("Escape で入力欄をクリアしエディタへフォーカスを戻す / Escape clears the bar and refocuses the editor", async () => {
+    const user = userEvent.setup();
+    const editor = createMockEditor();
+    render(<WikiLinkInputBar editor={editor} pageId="p1" pageNoteId={null} />);
+
+    const input = screen.getByTestId("wiki-link-input-bar-input") as HTMLInputElement;
+    await user.click(input);
+    await user.type(input, "Stuff");
+    await user.keyboard("{Escape}");
+
+    expect(input.value).toBe("");
+    expect(editor.commandsReturn.focus).toHaveBeenCalled();
+  });
+});
+
+describe("WikiLinkInputBar - 外部フォーカス / external focus", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockUseWikiLinkCandidates.mockReturnValue({ pages: [], isLoading: false });
+    mockUseWikiLinkExistsChecker.mockImplementation(() => ({
+      checkExistence: mockCheckExistence,
+    }));
+    mockCheckExistence.mockResolvedValue({
+      pageTitles: new Set(),
+      referencedTitles: new Set(),
+      pageTitleToId: new Map(),
+    });
+    mockCheckReferenced.mockResolvedValue(false);
+  });
+
+  it("`focusInputBarRef` 経由で input にフォーカスを移せる / lets the parent focus the input via `focusInputBarRef` (issue #928 / Cmd+K)", () => {
+    const editor = createMockEditor();
+    const focusInputBarRef: React.MutableRefObject<(() => void) | null> = { current: null };
+    render(
+      <WikiLinkInputBar
+        editor={editor}
+        pageId="p1"
+        pageNoteId={null}
+        focusInputBarRef={focusInputBarRef}
+      />,
+    );
+
+    // マウント時点で割り当てられている。
+    // The handle is wired on mount.
+    expect(typeof focusInputBarRef.current).toBe("function");
+
+    act(() => {
+      focusInputBarRef.current?.();
+    });
+
+    const input = screen.getByTestId("wiki-link-input-bar-input");
+    expect(document.activeElement).toBe(input);
+  });
+
+  it("unmount で ref が null に戻る / clears the ref on unmount to avoid dangling references", () => {
+    const editor = createMockEditor();
+    const focusInputBarRef: React.MutableRefObject<(() => void) | null> = { current: null };
+    const { unmount } = render(
+      <WikiLinkInputBar
+        editor={editor}
+        pageId="p1"
+        pageNoteId={null}
+        focusInputBarRef={focusInputBarRef}
+      />,
+    );
+
+    expect(focusInputBarRef.current).not.toBeNull();
+    unmount();
+    expect(focusInputBarRef.current).toBeNull();
+  });
+});
+
+describe("WikiLinkInputBar - スコープ転送 / scope forwarding", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockUseWikiLinkExistsChecker.mockImplementation(() => ({
+      checkExistence: mockCheckExistence,
+    }));
+    mockCheckExistence.mockResolvedValue({
+      pageTitles: new Set(),
+      referencedTitles: new Set(),
+      pageTitleToId: new Map(),
+    });
+    mockCheckReferenced.mockResolvedValue(false);
+  });
+
+  it("ノートスコープでは候補ページを `notePages` として exists checker に渡す / forwards note-scope candidates as `notePages` so the Enter fallback can resolve same-note pages (Codex P1, PR #934)", () => {
+    const editor = createMockEditor();
+    const notePages = [
+      { id: "p-alpha", title: "Alpha", isDeleted: false },
+      { id: "p-beta", title: "Beta", isDeleted: false },
+    ];
+    mockUseWikiLinkCandidates.mockReturnValue({ pages: notePages, isLoading: false });
+
+    render(<WikiLinkInputBar editor={editor} pageId="p1" pageNoteId="note-1" />);
+
+    // `useWikiLinkExistsChecker` がノートスコープで呼ばれるとき、候補ページを
+    // `notePages` として渡していないと checker が空集合を返し、Enter による
+    // 完全一致フォールバックが効かなくなる（同名既存ページがあってもゴーストを
+    // 挿入してしまう）。
+    // Without forwarding `notePages` in note scope the checker returns empty
+    // sets and the Enter exact-match fallback silently inserts a ghost link
+    // even when an existing same-note page matches.
+    expect(mockUseWikiLinkExistsChecker).toHaveBeenCalledWith({
+      pageNoteId: "note-1",
+      notePages,
+    });
+  });
+
+  it("個人スコープでは `notePages` を渡さず checker 既定の個人ページ取得に任せる / leaves `notePages` undefined for personal scope to keep the checker's `getPagesSummary` path", () => {
+    const editor = createMockEditor();
+    mockUseWikiLinkCandidates.mockReturnValue({
+      pages: [{ id: "p-alpha", title: "Alpha", isDeleted: false }],
+      isLoading: false,
+    });
+
+    render(<WikiLinkInputBar editor={editor} pageId="p1" pageNoteId={null} />);
+
+    expect(mockUseWikiLinkExistsChecker).toHaveBeenCalledWith({
+      pageNoteId: null,
+      notePages: undefined,
+    });
+  });
+});
diff --git a/src/components/editor/WikiLinkInputBar.tsx b/src/components/editor/WikiLinkInputBar.tsx
new file mode 100644
index 00000000..afbe7f8b
--- /dev/null
+++ b/src/components/editor/WikiLinkInputBar.tsx
@@ -0,0 +1,163 @@
+import React, { useEffect, useRef, type MutableRefObject } from "react";
+import type { Editor } from "@tiptap/core";
+import { cn } from "@zedi/ui";
+import { useTranslation } from "react-i18next";
+import { WikiLinkSuggestion } from "./extensions/WikiLinkSuggestion";
+import { useWikiLinkInputBar } from "./useWikiLinkInputBar";
+
+/**
+ * `WikiLinkInputBar` の props。FAB 左に常時表示されるピル型入力バーを
+ * 駆動するために必要な最小限の依存（編集中エディタ、ページ id、所属ノート
+ * id）だけを受け取る。マウントは呼び出し側の責務（通常は `TiptapEditor` 内）。
+ *
+ * Props for the FAB-adjacent WikiLink input bar (#924 §2, #926). Takes only
+ * the bare minimum — the active editor, the editing page id, and the owning
+ * note id used to scope suggestions. The host (`TiptapEditor`) decides when
+ * to mount the bar.
+ */
+export interface WikiLinkInputBarProps {
+  /**
+   * 操作対象のエディタ。`null` の間（初期化前）は入力を受け付けない。
+   * The editor the bar inserts into. `null` while the editor is being
+   * initialized; the bar disables itself in that state.
+   */
+  editor: Editor | null;
+  /** 編集中ページの id。referenced チェック / 自己参照除外のスコープに使う。 / Current page id for the referenced lookups. */
+  pageId?: string;
+  /**
+   * 編集中ページが所属するノート id。`null` は個人ページ、文字列はノート
+   * ネイティブページ。`useWikiLinkCandidates` のスコープに直接渡す。
+   * Owning note id. Forwarded to `useWikiLinkCandidates` to scope the
+   * candidate list (personal vs. same-note). See issue #713 Phase 4.
+   */
+  pageNoteId: string | null;
+  /** 追加でルートに付ける className。 / Optional class name for the outer container. */
+  className?: string;
+  /**
+   * `true` のとき input を親 flex 行の残り幅いっぱいに広げる（画面下部固定
+   * バー + Container レイアウト向け）。既定は従来の固定幅ピル。
+   *
+   * When `true`, the input stretches to fill the remaining width in a flex row
+   * (used by the fixed bottom bar inside `Container`). Defaults to the legacy
+   * fixed-width pill.
+   */
+  fillWidth?: boolean;
+  /**
+   * バーの input にフォーカスを移すための imperative ハンドル。`focusContentRef`
+   * 等と同じ `MutableRefObject<(() => void) | null>` 規約。`useEditorWikiLinkShortcuts`
+   * の `Cmd/Ctrl+K` 経由で外部からフォーカスを移すために使う（issue #928）。
+   *
+   * Imperative handle for focusing the bar's input. Follows the project's
+   * `MutableRefObject<(() => void) | null>` convention (same as
+   * `focusContentRef`). Used by `useEditorWikiLinkShortcuts` to focus the
+   * bar via `Cmd/Ctrl+K` (issue #928).
+   */
+  focusInputBarRef?: MutableRefObject<(() => void) | null>;
+}
+
+/**
+ * FAB 左に常時表示されるピル型入力バー。役割はゴーストリンク作成を主目的と
+ * しつつ、入力中に既存ページ候補を提示して既存リンク挿入もできる二役 UI
+ * （issue #924 §2 / #926）。フォーカス時にエディタのカーソル位置を退避し、
+ * 確定（Enter / 候補クリック）でその位置に Wiki Link を挿入してから
+ * エディタへフォーカスを戻す。状態管理は `useWikiLinkInputBar` フックに
+ * 委譲する。
+ *
+ * Pill-shaped input bar mounted next to the FAB. Primary purpose is creating
+ * ghost wiki links; typing also shows existing-page suggestions for
+ * inserting resolved links. On focus the bar saves the editor cursor so the
+ * link lands where the user was writing; on confirm it inserts and returns
+ * focus to the editor. Stateful logic lives in {@link useWikiLinkInputBar}.
+ * See parent issue #924 §2 and sub-issue #926.
+ */
+export const WikiLinkInputBar: React.FC<WikiLinkInputBarProps> = ({
+  editor,
+  pageId,
+  pageNoteId,
+  className,
+  fillWidth = false,
+  focusInputBarRef,
+}) => {
+  const { t } = useTranslation();
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  // imperative ハンドル: 親（TiptapEditor 経由のショートカットフック）が
+  // バーの input にフォーカスを移すための関数を ref に割り当てる。unmount
+  // 時に null クリアして dangling reference を残さない。
+  // Imperative handle: parent (the shortcut hook wired through TiptapEditor)
+  // gets a function to focus the bar's input. Cleared on unmount to avoid
+  // dangling references.
+  useEffect(() => {
+    if (!focusInputBarRef) return;
+    focusInputBarRef.current = () => {
+      inputRef.current?.focus();
+    };
+    return () => {
+      focusInputBarRef.current = null;
+    };
+  }, [focusInputBarRef]);
+
+  const {
+    value,
+    setValue,
+    pages,
+    showSuggestions,
+    suggestionRef,
+    handleFocus,
+    handleBlur,
+    handleKeyDown,
+    handleSuggestionSelect,
+    handleSuggestionClose,
+  } = useWikiLinkInputBar({ editor, pageId, pageNoteId });
+
+  return (
+    <div
+      className={cn("pointer-events-auto flex flex-col items-stretch gap-2", className)}
+      data-testid="wiki-link-input-bar"
+    >
+      {showSuggestions && (
+        // mousedown を抑止することで候補クリック時に入力欄が blur せず、
+        // クリック→確定の流れがそのまま走るようにする（リスト全体に効く）。
+        // input の `onBlur` が先に発火するとリストが unmount され、後続の
+        // click イベントが届かない問題を回避する。
+        // Prevent the default mousedown action so clicking a candidate does
+        // not blur the input — without this the list would unmount on blur
+        // and the click event would never reach the candidate row.
+        <div className="self-stretch" onMouseDown={(e) => e.preventDefault()}>
+          <WikiLinkSuggestion
+            ref={suggestionRef}
+            query={value}
+            pages={pages}
+            onSelect={handleSuggestionSelect}
+            onClose={handleSuggestionClose}
+          />
+        </div>
+      )}
+      <input
+        ref={inputRef}
+        data-testid="wiki-link-input-bar-input"
+        type="text"
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        onFocus={handleFocus}
+        onBlur={handleBlur}
+        onKeyDown={handleKeyDown}
+        placeholder={t("common.wikiLinkInputBar.placeholder")}
+        aria-label={t("common.wikiLinkInputBar.ariaLabel")}
+        disabled={!editor}
+        className={cn(
+          "h-12 rounded-full px-5",
+          fillWidth ? "w-full min-w-0" : "w-[min(20rem,calc(100vw-7rem))]",
+          "bg-secondary/80 text-secondary-foreground placeholder:text-muted-foreground",
+          "shadow-lg backdrop-blur-sm",
+          "border border-transparent",
+          "focus:border-ring focus:bg-secondary focus:ring-ring/40 focus:ring-2 focus:outline-none",
+          "transition-colors duration-150",
+          "disabled:cursor-not-allowed disabled:opacity-50",
+        )}
+      />
+    </div>
+  );
+};
+
+export default WikiLinkInputBar;
diff --git a/src/components/editor/extensions/MarkdownPasteExtension.test.ts b/src/components/editor/extensions/MarkdownPasteExtension.test.ts
index ab562d99..156bc004 100644
--- a/src/components/editor/extensions/MarkdownPasteExtension.test.ts
+++ b/src/components/editor/extensions/MarkdownPasteExtension.test.ts
@@ -318,3 +318,103 @@ describe("MarkdownPaste extension - wiki links", () => {
     expect(mockEditor.commands.insertContent).not.toHaveBeenCalled();
   });
 });
+
+// ---------------------------------------------------------------------------
+// Mermaid コードブロックペーストの統合テスト / Mermaid code block paste integration tests
+// ---------------------------------------------------------------------------
+
+describe("MarkdownPaste extension - mermaid code blocks", () => {
+  /**
+   * `@tiptap/markdown` の `parse` が Mermaid フェンスを `codeBlock` +
+   * `language: "mermaid"` として返す挙動をモックする。
+   * Mocks `@tiptap/markdown` parsing a mermaid fence into a `codeBlock`
+   * node with `language: "mermaid"`.
+   */
+  function createMermaidParse(code: string) {
+    return vi.fn(() => ({
+      type: "doc",
+      content: [
+        {
+          type: "codeBlock",
+          attrs: { language: "mermaid" },
+          content: [{ type: "text", text: code }],
+        },
+      ],
+    }));
+  }
+
+  it("converts a pasted mermaid fence into a mermaid node", () => {
+    const code = "graph TD\n  A-->B";
+    const { handlePaste, mockEditor } = getHandlePaste({
+      parse: createMermaidParse(code),
+    });
+
+    const event = createMockPasteEvent("```mermaid\ngraph TD\n  A-->B\n```");
+    expect(handlePaste(null, event, null)).toBe(true);
+
+    const inserted = mockEditor.commands.insertContent.mock.calls[0]?.[0] as {
+      content: Array<{ type: string; attrs?: { code?: string } }>;
+    };
+    expect(inserted.content[0]).toEqual({
+      type: "mermaid",
+      attrs: { code },
+    });
+  });
+
+  it("leaves non-mermaid fenced code blocks untouched", () => {
+    const parsed = {
+      type: "doc",
+      content: [
+        {
+          type: "codeBlock",
+          attrs: { language: "ts" },
+          content: [{ type: "text", text: "const x = 1" }],
+        },
+      ],
+    };
+    const { handlePaste, mockEditor } = getHandlePaste({
+      parse: vi.fn(() => parsed),
+    });
+
+    const event = createMockPasteEvent("```ts\nconst x = 1\n```");
+    expect(handlePaste(null, event, null)).toBe(true);
+    expect(mockEditor.commands.insertContent).toHaveBeenCalledWith(parsed);
+  });
+
+  it("handles mermaid fences mixed with wiki links in one paste", () => {
+    const { handlePaste, mockEditor } = getHandlePaste({
+      parse: vi.fn(() => ({
+        type: "doc",
+        content: [
+          {
+            type: "paragraph",
+            content: [{ type: "text", text: "see [[Ref]]" }],
+          },
+          {
+            type: "codeBlock",
+            attrs: { language: "mermaid" },
+            content: [{ type: "text", text: "graph TD" }],
+          },
+        ],
+      })),
+    });
+
+    const event = createMockPasteEvent("see [[Ref]]\n\n```mermaid\ngraph TD\n```");
+    expect(handlePaste(null, event, null)).toBe(true);
+
+    const inserted = mockEditor.commands.insertContent.mock.calls[0]?.[0] as {
+      content: Array<{
+        type: string;
+        attrs?: { code?: string };
+        content?: Array<{ marks?: Array<{ type: string }> }>;
+      }>;
+    };
+    // Wiki link がマーク付きで残り、Mermaid ブロックが `mermaid` ノードに置換される。
+    // Wiki link survives as a marked text node, mermaid block becomes a mermaid node.
+    expect(inserted.content[0].content?.[1]?.marks?.[0]?.type).toBe("wikiLink");
+    expect(inserted.content[1]).toEqual({
+      type: "mermaid",
+      attrs: { code: "graph TD" },
+    });
+  });
+});
diff --git a/src/components/editor/extensions/MarkdownPasteExtension.ts b/src/components/editor/extensions/MarkdownPasteExtension.ts
index d5889453..f87fbf2a 100644
--- a/src/components/editor/extensions/MarkdownPasteExtension.ts
+++ b/src/components/editor/extensions/MarkdownPasteExtension.ts
@@ -4,6 +4,10 @@ import {
   containsWikiLinkPattern,
   transformWikiLinksInContent,
 } from "./transformWikiLinksInContent";
+import {
+  containsMermaidFence,
+  transformMermaidCodeBlocksInContent,
+} from "./transformMermaidCodeBlocksInContent";
 
 /**
  * ProseMirror プラグインキー（拡張再初期化時の再生成を避けるためトップレベルで定義）。
@@ -80,11 +84,20 @@ export const MarkdownPaste = Extension.create({
               // 後処理で `wikiLink` マークを付与する。
               // `@tiptap/markdown` leaves `[[...]]` as plain text, so post-process
               // the parsed JSON to apply the `wikiLink` mark.
-              const content = hasWikiLink
+              let content = hasWikiLink
                 ? transformWikiLinksInContent(
                     parsed as Parameters<typeof transformWikiLinksInContent>[0],
                   )
-                : parsed;
+                : (parsed as Parameters<typeof transformWikiLinksInContent>[0]);
+              // ```mermaid``` フェンスは `@tiptap/markdown` が `codeBlock` ノード
+              // （`language: "mermaid"`）として生成するので、後処理で専用の
+              // `mermaid` ノードに置換してダイアグラム描画に回す。
+              // `@tiptap/markdown` parses ```mermaid``` fences into `codeBlock`
+              // nodes with `language: "mermaid"`; convert them to dedicated
+              // `mermaid` nodes here so they render as diagrams downstream.
+              if (containsMermaidFence(text)) {
+                content = transformMermaidCodeBlocksInContent(content);
+              }
               return editor.commands.insertContent(content);
             } catch {
               // パース失敗時は ProseMirror のデフォルトペースト処理にフォールバック
diff --git a/src/components/editor/extensions/WikiLinkExtension.test.ts b/src/components/editor/extensions/WikiLinkExtension.test.ts
index 96a9e15c..18210088 100644
--- a/src/components/editor/extensions/WikiLinkExtension.test.ts
+++ b/src/components/editor/extensions/WikiLinkExtension.test.ts
@@ -76,6 +76,134 @@ describe("WikiLinkExtension paste rule", () => {
     });
   });
 
+  // Issue #931: WikiLink クリックハンドラが Cmd/Ctrl+クリックと中クリックを
+  // 「新タブ意図」として伝搬することを検証する。`addProseMirrorPlugins`
+  // から取り出した Plugin spec を直接実行して、`onLinkClick` 呼び出しの
+  // 第 2 引数を検証する。
+  // Issue #931: verify that the wiki-link click handler propagates
+  // Cmd/Ctrl+click and middle-click as a "new tab" intent. Drives the
+  // Plugin spec directly so we can assert the second argument of
+  // `onLinkClick`.
+  describe("WikiLink click handler (issue #931)", () => {
+    type LinkClick = (title: string, options?: { newTab?: boolean }) => void;
+    type HandleClick = (view: unknown, pos: number, event: MouseEvent) => boolean | undefined;
+    type AuxClick = (view: unknown, event: MouseEvent) => boolean | undefined;
+
+    function buildPlugin(onLinkClick: LinkClick) {
+      const extension = WikiLink.configure({});
+      const addProseMirrorPlugins = extension.config.addProseMirrorPlugins;
+      if (typeof addProseMirrorPlugins !== "function") {
+        throw new Error("addProseMirrorPlugins must be a function");
+      }
+      const context: Record<string, unknown> = {
+        ...extension,
+        options: { HTMLAttributes: {}, onLinkClick },
+        parent: undefined,
+      };
+      const plugins = addProseMirrorPlugins.call(context) as Array<{
+        spec: {
+          props: {
+            handleClick?: HandleClick;
+            handleDOMEvents?: { auxclick?: AuxClick };
+          };
+        };
+      }>;
+      return plugins[0];
+    }
+
+    function makeWikiLinkSpan(title: string): HTMLElement {
+      const span = document.createElement("span");
+      span.setAttribute("data-wiki-link", "");
+      span.setAttribute("data-title", title);
+      document.body.appendChild(span);
+      return span;
+    }
+
+    it("通常クリックでは newTab: false を伝える", () => {
+      const onLinkClick = vi.fn();
+      const plugin = buildPlugin(onLinkClick);
+      const span = makeWikiLinkSpan("Some Page");
+      const event = new MouseEvent("click", { bubbles: true, cancelable: true });
+      Object.defineProperty(event, "target", { value: span });
+
+      const handled = plugin.spec.props.handleClick?.(null, 0, event);
+
+      expect(handled).toBe(true);
+      expect(onLinkClick).toHaveBeenCalledWith("Some Page", { newTab: false });
+      span.remove();
+    });
+
+    it("Cmd+クリック (metaKey) では newTab: true を伝える", () => {
+      const onLinkClick = vi.fn();
+      const plugin = buildPlugin(onLinkClick);
+      const span = makeWikiLinkSpan("Cmd Page");
+      const event = new MouseEvent("click", { bubbles: true, cancelable: true, metaKey: true });
+      Object.defineProperty(event, "target", { value: span });
+
+      plugin.spec.props.handleClick?.(null, 0, event);
+
+      expect(onLinkClick).toHaveBeenCalledWith("Cmd Page", { newTab: true });
+      span.remove();
+    });
+
+    it("Ctrl+クリック (ctrlKey) では newTab: true を伝える", () => {
+      const onLinkClick = vi.fn();
+      const plugin = buildPlugin(onLinkClick);
+      const span = makeWikiLinkSpan("Ctrl Page");
+      const event = new MouseEvent("click", { bubbles: true, cancelable: true, ctrlKey: true });
+      Object.defineProperty(event, "target", { value: span });
+
+      plugin.spec.props.handleClick?.(null, 0, event);
+
+      expect(onLinkClick).toHaveBeenCalledWith("Ctrl Page", { newTab: true });
+      span.remove();
+    });
+
+    it("中クリック (button === 1) では auxclick 経由で newTab: true を伝える", () => {
+      const onLinkClick = vi.fn();
+      const plugin = buildPlugin(onLinkClick);
+      const span = makeWikiLinkSpan("Middle Page");
+      const event = new MouseEvent("auxclick", { bubbles: true, cancelable: true, button: 1 });
+      Object.defineProperty(event, "target", { value: span });
+
+      const handled = plugin.spec.props.handleDOMEvents?.auxclick?.(null, event);
+
+      expect(handled).toBe(true);
+      expect(onLinkClick).toHaveBeenCalledWith("Middle Page", { newTab: true });
+      span.remove();
+    });
+
+    it("中クリック以外の auxclick (button !== 1) は無視する", () => {
+      const onLinkClick = vi.fn();
+      const plugin = buildPlugin(onLinkClick);
+      const span = makeWikiLinkSpan("Right Page");
+      // 右クリック (button === 2) は新タブ対象外。
+      const event = new MouseEvent("auxclick", { bubbles: true, cancelable: true, button: 2 });
+      Object.defineProperty(event, "target", { value: span });
+
+      const handled = plugin.spec.props.handleDOMEvents?.auxclick?.(null, event);
+
+      expect(handled).toBe(false);
+      expect(onLinkClick).not.toHaveBeenCalled();
+      span.remove();
+    });
+
+    it("wiki-link 要素以外のクリックは無視する", () => {
+      const onLinkClick = vi.fn();
+      const plugin = buildPlugin(onLinkClick);
+      const plain = document.createElement("p");
+      document.body.appendChild(plain);
+      const event = new MouseEvent("click", { bubbles: true, cancelable: true });
+      Object.defineProperty(event, "target", { value: plain });
+
+      const handled = plugin.spec.props.handleClick?.(null, 0, event);
+
+      expect(handled).toBe(false);
+      expect(onLinkClick).not.toHaveBeenCalled();
+      plain.remove();
+    });
+  });
+
   describe("WikiLink extension configuration", () => {
     it("should have addPasteRules defined", () => {
       const extension = WikiLink.configure({});
diff --git a/src/components/editor/extensions/WikiLinkExtension.ts b/src/components/editor/extensions/WikiLinkExtension.ts
index 784f476b..30f194a7 100644
--- a/src/components/editor/extensions/WikiLinkExtension.ts
+++ b/src/components/editor/extensions/WikiLinkExtension.ts
@@ -36,13 +36,45 @@ function extractWikiLinkTitle(fullMatch: string): string | null {
   return title || null;
 }
 
+/**
+ * WikiLink クリック時の追加オプション（Issue #931）。
+ * `newTab` が `true` のときは新タブで遷移する。
+ *
+ * Click options forwarded to `onLinkClick` (Issue #931). `newTab` indicates
+ * that the destination should open in a new tab (Cmd/Ctrl+click or middle
+ * click).
+ */
+export interface WikiLinkClickOptions {
+  newTab?: boolean;
+}
+
 /**
  * Options for the WikiLink mark extension.
  * WikiLink マーク拡張のオプション。
  */
 export interface WikiLinkOptions {
   HTMLAttributes: Record<string, unknown>;
-  onLinkClick?: (title: string) => void;
+  onLinkClick?: (title: string, options?: WikiLinkClickOptions) => void;
+}
+
+/**
+ * クリックイベントから wiki-link 要素を辿り、関連するタイトルを取り出す。
+ * 該当しない場合は `null`。`handleClick` (左クリック) と `handleDOMEvents.auxclick`
+ * (中クリック) で共有する。
+ *
+ * Resolve the wiki-link DOM target for a click event. Returns the matching
+ * element and its `data-title`, or `null` if the click landed outside of a
+ * wiki-link mark. Shared between left-click and middle-click handlers.
+ */
+function findWikiLinkTarget(
+  target: EventTarget | null,
+): { element: HTMLElement; title: string } | null {
+  if (!(target instanceof Element)) return null;
+  const element = target.closest("[data-wiki-link]") as HTMLElement | null;
+  if (!element) return null;
+  const title = element.getAttribute("data-title");
+  if (!title) return null;
+  return { element, title };
 }
 
 // Link status types:
@@ -197,22 +229,38 @@ export const WikiLink = Mark.create<WikiLinkOptions>({
           handleClick: (_view, _pos, event) => {
             if (!onLinkClick) return false;
 
-            const target = event.target as HTMLElement;
-
-            // Check if clicked on a wiki-link element
-            const wikiLinkElement = target.closest("[data-wiki-link]") as HTMLElement | null;
-            if (!wikiLinkElement) return false;
+            const hit = findWikiLinkTarget(event.target);
+            if (!hit) return false;
 
-            const title = wikiLinkElement.getAttribute("data-title");
-
-            if (title) {
+            // Issue #931: Cmd/Ctrl+クリックは新タブで開く。span 要素は
+            // ネイティブリンクではないため、いずれの場合も自前で navigate / open
+            // を呼ぶ必要があり、`preventDefault` は両ケースで実行する。
+            // Issue #931: Cmd/Ctrl+click opens in a new tab. The wiki-link
+            // span is not a native anchor, so both branches navigate via the
+            // callback and we always call `preventDefault`.
+            const newTab = event.metaKey || event.ctrlKey;
+            event.preventDefault();
+            event.stopPropagation();
+            onLinkClick(hit.title, { newTab });
+            return true;
+          },
+          handleDOMEvents: {
+            // Issue #931: 中クリック（マウスホイールクリック）も新タブ扱い。
+            // ProseMirror の `handleClick` は左クリックのみ発火するため、
+            // 中クリックは `auxclick` で別途処理する。
+            // Issue #931: middle-click also opens in a new tab. ProseMirror's
+            // `handleClick` only fires for the primary button, so we register
+            // an `auxclick` listener to catch button === 1.
+            auxclick: (_view, event) => {
+              if (!onLinkClick) return false;
+              if (event.button !== 1) return false;
+              const hit = findWikiLinkTarget(event.target);
+              if (!hit) return false;
               event.preventDefault();
               event.stopPropagation();
-              onLinkClick(title);
+              onLinkClick(hit.title, { newTab: true });
               return true;
-            }
-
-            return false;
+            },
           },
         },
       }),
diff --git a/src/components/editor/extensions/WikiLinkSuggestion.test.tsx b/src/components/editor/extensions/WikiLinkSuggestion.test.tsx
new file mode 100644
index 00000000..48bc5644
--- /dev/null
+++ b/src/components/editor/extensions/WikiLinkSuggestion.test.tsx
@@ -0,0 +1,231 @@
+import React, { createRef } from "react";
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, act, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import {
+  WikiLinkSuggestion,
+  type WikiLinkSuggestionHandle,
+  type WikiLinkSuggestionPage,
+  type SuggestionItem,
+} from "./WikiLinkSuggestion";
+
+/**
+ * 入力バー（#924 §2）と本文中 `[[` サジェスト（#925）両方で再利用される
+ * 共通コンポーネントとしての受け入れ条件をテストする。マウント位置や
+ * 呼び出し元コンテキスト（Editor / range）に依存しない pure presentation
+ * であることを保証する。
+ *
+ * Locks in the contract of the shared `WikiLinkSuggestion` component used
+ * by both the FAB input bar (#924 §2) and the in-body `[[` suggestion
+ * popup (#925). The component must remain mount-agnostic — no Editor or
+ * range coupling — so the same instance can be wrapped by either host.
+ */
+
+function makePage(overrides: Partial<WikiLinkSuggestionPage> = {}): WikiLinkSuggestionPage {
+  return {
+    id: overrides.id ?? "p-1",
+    title: overrides.title ?? "Untitled",
+    isDeleted: overrides.isDeleted ?? false,
+  };
+}
+
+/**
+ * `useImperativeHandle` 経由の `onKeyDown` を呼び出すヘルパ。
+ * Helper to invoke the imperative `onKeyDown` exposed via the ref.
+ */
+function fireKey(ref: React.RefObject<WikiLinkSuggestionHandle | null>, key: string): boolean {
+  const handle = ref.current;
+  if (!handle) throw new Error("WikiLinkSuggestion ref is not attached");
+  let handled = false;
+  act(() => {
+    handled = handle.onKeyDown(new KeyboardEvent("keydown", { key }));
+  });
+  return handled;
+}
+
+describe("WikiLinkSuggestion - 候補の描画 / item rendering", () => {
+  it("既存ページ候補をクエリに一致した順に最大 5 件まで描画する / renders up to 5 matching pages", () => {
+    const pages: WikiLinkSuggestionPage[] = [
+      makePage({ id: "p-1", title: "Alpha" }),
+      makePage({ id: "p-2", title: "Beta" }),
+      makePage({ id: "p-3", title: "Gamma" }),
+      makePage({ id: "p-4", title: "Delta" }),
+      makePage({ id: "p-5", title: "Epsilon" }),
+      makePage({ id: "p-6", title: "Zeta" }),
+    ];
+
+    render(<WikiLinkSuggestion query="" onSelect={vi.fn()} onClose={vi.fn()} pages={pages} />);
+
+    // 6 件あっても "create new" を入れずに 5 件で打ち切る。
+    // With 6 candidates and an empty query, exactly the first 5 are shown.
+    expect(screen.getAllByRole("button")).toHaveLength(5);
+    expect(screen.getByText("Alpha")).toBeInTheDocument();
+    expect(screen.queryByText("Zeta")).not.toBeInTheDocument();
+  });
+
+  it("クエリに一致しないページは表示しない / filters by query (case-insensitive substring)", () => {
+    const pages = [
+      makePage({ id: "p-1", title: "React Hooks" }),
+      makePage({ id: "p-2", title: "TypeScript Guide" }),
+    ];
+
+    render(<WikiLinkSuggestion query="react" onSelect={vi.fn()} onClose={vi.fn()} pages={pages} />);
+
+    expect(screen.getByText("React Hooks")).toBeInTheDocument();
+    expect(screen.queryByText("TypeScript Guide")).not.toBeInTheDocument();
+  });
+
+  it("isDeleted のページは候補から除外する / excludes deleted pages", () => {
+    const pages = [
+      makePage({ id: "p-1", title: "Active" }),
+      makePage({ id: "p-2", title: "Archived", isDeleted: true }),
+    ];
+
+    render(<WikiLinkSuggestion query="" onSelect={vi.fn()} onClose={vi.fn()} pages={pages} />);
+
+    expect(screen.getByText("Active")).toBeInTheDocument();
+    expect(screen.queryByText("Archived")).not.toBeInTheDocument();
+  });
+
+  it("完全一致が無い場合は『新規作成』エントリを末尾に追加する / appends a create entry when no exact match", () => {
+    const pages = [makePage({ id: "p-1", title: "Existing" })];
+
+    render(
+      <WikiLinkSuggestion query="New Page" onSelect={vi.fn()} onClose={vi.fn()} pages={pages} />,
+    );
+
+    expect(screen.getByText('"New Page" を作成')).toBeInTheDocument();
+  });
+
+  it("完全一致するページがあれば『新規作成』エントリは出さない / hides create entry on exact title match", () => {
+    const pages = [makePage({ id: "p-1", title: "Alpha" })];
+
+    render(<WikiLinkSuggestion query="Alpha" onSelect={vi.fn()} onClose={vi.fn()} pages={pages} />);
+
+    expect(screen.getByText("Alpha")).toBeInTheDocument();
+    expect(screen.queryByText(/を作成$/)).not.toBeInTheDocument();
+  });
+
+  it("候補も新規作成エントリも無いときは null を返す / renders nothing with no items", () => {
+    const { container } = render(
+      <WikiLinkSuggestion query="" onSelect={vi.fn()} onClose={vi.fn()} pages={[]} />,
+    );
+    expect(container.firstChild).toBeNull();
+  });
+
+  it("ポジショニング class を一切付けない（マウント位置は呼び出し側の責務）/ does not impose absolute/fixed positioning", () => {
+    render(
+      <WikiLinkSuggestion
+        query=""
+        onSelect={vi.fn()}
+        onClose={vi.fn()}
+        pages={[makePage({ title: "Alpha" })]}
+      />,
+    );
+
+    // ルート要素に position 系のクラスを持たないことを確認する。これにより
+    // 入力バー（fixed）と本文中 `[[`（absolute）どちらの host にも適合する。
+    // The root must not carry position classes so it can be wrapped in
+    // either the input bar's `fixed` container or the editor's `absolute`
+    // overlay without bleeding through.
+    const root = screen.getByTestId("wiki-link-suggestion");
+    expect(root.className).not.toMatch(/\b(absolute|fixed|relative|sticky)\b/);
+  });
+});
+
+describe("WikiLinkSuggestion - 確定 / キーボード操作 / selection + keyboard", () => {
+  it("クリックで onSelect に対応する item が渡る / clicking a row fires onSelect with that item", async () => {
+    const user = userEvent.setup();
+    const onSelect = vi.fn<(item: SuggestionItem) => void>();
+    const pages = [makePage({ id: "p-1", title: "Alpha" }), makePage({ id: "p-2", title: "Beta" })];
+
+    render(<WikiLinkSuggestion query="" onSelect={onSelect} onClose={vi.fn()} pages={pages} />);
+
+    await user.click(screen.getByText("Beta"));
+    expect(onSelect).toHaveBeenCalledWith({ id: "p-2", title: "Beta", exists: true });
+  });
+
+  it("新規作成行をクリックすると exists=false の item が渡る / clicking create row fires create item", async () => {
+    const user = userEvent.setup();
+    const onSelect = vi.fn<(item: SuggestionItem) => void>();
+    render(<WikiLinkSuggestion query="Fresh" onSelect={onSelect} onClose={vi.fn()} pages={[]} />);
+
+    await user.click(screen.getByText('"Fresh" を作成'));
+    expect(onSelect).toHaveBeenCalledWith({ id: "create-new", title: "Fresh", exists: false });
+  });
+
+  it("ArrowDown / ArrowUp で選択行が循環する / ArrowDown and ArrowUp wrap around the list", async () => {
+    const ref = createRef<WikiLinkSuggestionHandle>();
+    const onSelect = vi.fn<(item: SuggestionItem) => void>();
+    const pages = [makePage({ id: "p-1", title: "Alpha" }), makePage({ id: "p-2", title: "Beta" })];
+
+    render(
+      <WikiLinkSuggestion ref={ref} query="" onSelect={onSelect} onClose={vi.fn()} pages={pages} />,
+    );
+    // 初回マウント時の選択状態が確定する（先頭行に `bg-accent` が付く）まで待つ。
+    // `queueMicrotask` などの内部実装に依存せず、観測可能な副作用で同期する。
+    // Wait for the initial selection to settle by observing the highlight
+    // class on the first row, avoiding coupling to the internal
+    // `queueMicrotask` mechanism (gemini / CodeRabbit review feedback).
+    await waitFor(() => {
+      const buttons = screen.getAllByRole("button");
+      expect(buttons[0].className).toMatch(/\bbg-accent\b/);
+    });
+
+    // 最初は先頭が選択されている。Enter で確定して確認。
+    // First item highlighted initially; confirm by pressing Enter.
+    expect(fireKey(ref, "Enter")).toBe(true);
+    expect(onSelect).toHaveBeenLastCalledWith({ id: "p-1", title: "Alpha", exists: true });
+
+    // ArrowDown で 2 番目へ。
+    // ArrowDown moves selection to the second row.
+    expect(fireKey(ref, "ArrowDown")).toBe(true);
+    expect(fireKey(ref, "Enter")).toBe(true);
+    expect(onSelect).toHaveBeenLastCalledWith({ id: "p-2", title: "Beta", exists: true });
+
+    // 末尾で ArrowDown すると先頭に戻る（循環）。
+    // ArrowDown from last item wraps back to the first row.
+    expect(fireKey(ref, "ArrowDown")).toBe(true);
+    expect(fireKey(ref, "Enter")).toBe(true);
+    expect(onSelect).toHaveBeenLastCalledWith({ id: "p-1", title: "Alpha", exists: true });
+
+    // 先頭で ArrowUp すると末尾に飛ぶ。
+    // ArrowUp from first item wraps to the last row.
+    expect(fireKey(ref, "ArrowUp")).toBe(true);
+    expect(fireKey(ref, "Enter")).toBe(true);
+    expect(onSelect).toHaveBeenLastCalledWith({ id: "p-2", title: "Beta", exists: true });
+  });
+
+  it("Escape で onClose が呼ばれる / Escape closes the popup", () => {
+    const ref = createRef<WikiLinkSuggestionHandle>();
+    const onClose = vi.fn();
+    render(
+      <WikiLinkSuggestion
+        ref={ref}
+        query=""
+        onSelect={vi.fn()}
+        onClose={onClose}
+        pages={[makePage()]}
+      />,
+    );
+
+    expect(fireKey(ref, "Escape")).toBe(true);
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("未処理のキーでは false を返し既定挙動を妨げない / returns false for unhandled keys", () => {
+    const ref = createRef<WikiLinkSuggestionHandle>();
+    render(
+      <WikiLinkSuggestion
+        ref={ref}
+        query=""
+        onSelect={vi.fn()}
+        onClose={vi.fn()}
+        pages={[makePage()]}
+      />,
+    );
+
+    expect(fireKey(ref, "a")).toBe(false);
+    expect(fireKey(ref, "Tab")).toBe(false);
+  });
+});
diff --git a/src/components/editor/extensions/WikiLinkSuggestion.tsx b/src/components/editor/extensions/WikiLinkSuggestion.tsx
index 41d09867..686050c6 100644
--- a/src/components/editor/extensions/WikiLinkSuggestion.tsx
+++ b/src/components/editor/extensions/WikiLinkSuggestion.tsx
@@ -1,5 +1,4 @@
 import { forwardRef, useEffect, useImperativeHandle, useState, useCallback } from "react";
-import { Editor } from "@tiptap/core";
 import { cn } from "@zedi/ui";
 import { FileText, Plus } from "lucide-react";
 
@@ -25,11 +24,45 @@ export interface WikiLinkSuggestionPage {
   isDeleted?: boolean;
 }
 
-interface WikiLinkSuggestionProps {
-  editor: Editor;
+/**
+ * `WikiLinkSuggestion` の props。本コンポーネントは
+ *
+ * - 本文中の `[[` サジェスト（`WikiLinkSuggestionLayer`、絶対配置）
+ * - FAB 横のリンク入力バー（#924 §2、固定配置）
+ *
+ * の両方で再利用するため、マウント位置（fixed / absolute）や
+ * Editor / ProseMirror の range などの呼び出し元コンテキストには一切
+ * 依存しない。確定処理（範囲置換 / リンク挿入 / 入力バークリア）は
+ * すべて `onSelect` の呼び出し側に委ねる。
+ *
+ * Props for `WikiLinkSuggestion`. Kept deliberately free of editor /
+ * range / positioning concerns so the same component can back both the
+ * in-body `[[` suggestion (absolutely positioned over the editor) and
+ * the FAB-adjacent input bar (#924 §2, fixed near the keyboard). The
+ * host owns mounting + post-select side effects (range replacement,
+ * link insertion, clearing the input bar). See issue #925.
+ */
+export interface WikiLinkSuggestionProps {
+  /**
+   * 現在の入力クエリ。`[[` サジェストの場合は `[[` の後ろのテキスト、入力バー
+   * の場合は入力欄の値をそのまま渡す。
+   * Current input query — the text after `[[` for the in-body popup, or
+   * the input bar value verbatim.
+   */
   query: string;
-  range: { from: number; to: number };
+  /**
+   * 候補行 / 「新規作成」行が確定したときに呼ばれる。`item.exists` で既存
+   * ページか新規作成かを判別する。
+   * Invoked when an existing or create-new row is confirmed; `item.exists`
+   * distinguishes the two branches.
+   */
   onSelect: (item: SuggestionItem) => void;
+  /**
+   * Escape などでサジェストを閉じたいときに呼ばれる。クローズ後の挙動は
+   * 呼び出し側に任せる（プラグイン状態のリセット、入力バーのフォーカス制御等）。
+   * Fired when the popup should close. Host decides what closing means
+   * (plugin meta reset for the editor host; input-bar blur for the bar).
+   */
   onClose: () => void;
   /**
    * サジェスト候補として渡されるページ一覧。呼び出し側で WikiLink のスコープ
@@ -154,6 +187,7 @@ export const WikiLinkSuggestion = forwardRef<WikiLinkSuggestionHandle, WikiLinkS
           {items.map((item, index) => (
             <button
               key={item.id}
+              type="button"
               onClick={() => selectItem(index)}
               className={cn(
                 "flex w-full items-center gap-2 rounded-md px-3 py-2 text-left text-sm transition-colors",
diff --git a/src/components/editor/extensions/transformMermaidCodeBlocksInContent.test.ts b/src/components/editor/extensions/transformMermaidCodeBlocksInContent.test.ts
new file mode 100644
index 00000000..2c215c98
--- /dev/null
+++ b/src/components/editor/extensions/transformMermaidCodeBlocksInContent.test.ts
@@ -0,0 +1,355 @@
+import { describe, expect, it } from "vitest";
+import {
+  containsMermaidFence,
+  transformMermaidCodeBlocksInContent,
+} from "./transformMermaidCodeBlocksInContent";
+
+describe("containsMermaidFence", () => {
+  it("returns true for a fenced mermaid block", () => {
+    expect(containsMermaidFence("```mermaid\ngraph TD\nA-->B\n```")).toBe(true);
+  });
+
+  it("matches uppercase / mixed case language identifiers", () => {
+    expect(containsMermaidFence("```Mermaid\ngraph TD\n```")).toBe(true);
+    expect(containsMermaidFence("```MERMAID\ngraph TD\n```")).toBe(true);
+  });
+
+  it("tolerates leading whitespace and spaces after the fence", () => {
+    expect(containsMermaidFence("   ```   mermaid\nx\n```")).toBe(true);
+  });
+
+  it("returns false for non-mermaid fences", () => {
+    expect(containsMermaidFence("```ts\nconsole.log()\n```")).toBe(false);
+  });
+
+  it("returns false when the language is just a prefix of 'mermaid'", () => {
+    // `mer` は `mermaid` の接頭辞だが別言語として扱う。`\b` で完全一致のみマッチする。
+    // `mer` happens to be a prefix of `mermaid` but is a different language;
+    // the `\b` word-boundary anchor keeps the check strict.
+    expect(containsMermaidFence("```mer\nx\n```")).toBe(false);
+  });
+
+  it("returns false for inline backticks", () => {
+    expect(containsMermaidFence("see `mermaid` for details")).toBe(false);
+  });
+
+  it("returns false for empty string", () => {
+    expect(containsMermaidFence("")).toBe(false);
+  });
+});
+
+describe("transformMermaidCodeBlocksInContent", () => {
+  it("replaces a top-level mermaid codeBlock with a mermaid node", () => {
+    const doc = {
+      type: "doc",
+      content: [
+        {
+          type: "codeBlock",
+          attrs: { language: "mermaid" },
+          content: [{ type: "text", text: "graph TD\n  A-->B" }],
+        },
+      ],
+    };
+
+    expect(transformMermaidCodeBlocksInContent(doc)).toEqual({
+      type: "doc",
+      content: [
+        {
+          type: "mermaid",
+          attrs: { code: "graph TD\n  A-->B" },
+        },
+      ],
+    });
+  });
+
+  it("supports the snake-cased `code_block` variant", () => {
+    const doc = {
+      type: "doc",
+      content: [
+        {
+          type: "code_block",
+          attrs: { language: "mermaid" },
+          content: [{ type: "text", text: "graph LR\n  X-->Y" }],
+        },
+      ],
+    };
+
+    expect(transformMermaidCodeBlocksInContent(doc)).toEqual({
+      type: "doc",
+      content: [
+        {
+          type: "mermaid",
+          attrs: { code: "graph LR\n  X-->Y" },
+        },
+      ],
+    });
+  });
+
+  it("treats the language attribute case-insensitively", () => {
+    const doc = {
+      type: "doc",
+      content: [
+        {
+          type: "codeBlock",
+          attrs: { language: "Mermaid" },
+          content: [{ type: "text", text: "graph TD\nA-->B" }],
+        },
+      ],
+    };
+
+    const result = transformMermaidCodeBlocksInContent(doc) as unknown as {
+      content: Array<{ type: string; attrs: { code: string } }>;
+    };
+    expect(result.content[0].type).toBe("mermaid");
+    expect(result.content[0].attrs.code).toBe("graph TD\nA-->B");
+  });
+
+  it("does not touch non-mermaid code blocks", () => {
+    const doc = {
+      type: "doc",
+      content: [
+        {
+          type: "codeBlock",
+          attrs: { language: "ts" },
+          content: [{ type: "text", text: "console.log()" }],
+        },
+      ],
+    };
+
+    expect(transformMermaidCodeBlocksInContent(doc)).toEqual(doc);
+  });
+
+  it("does not touch code blocks without a language attribute", () => {
+    const doc = {
+      type: "doc",
+      content: [
+        {
+          type: "codeBlock",
+          content: [{ type: "text", text: "graph TD" }],
+        },
+      ],
+    };
+
+    expect(transformMermaidCodeBlocksInContent(doc)).toEqual(doc);
+  });
+
+  it("concatenates multiple text nodes within a code block", () => {
+    const doc = {
+      type: "doc",
+      content: [
+        {
+          type: "codeBlock",
+          attrs: { language: "mermaid" },
+          content: [
+            { type: "text", text: "graph TD" },
+            { type: "hardBreak" },
+            { type: "text", text: "A-->B" },
+          ],
+        },
+      ],
+    };
+
+    const result = transformMermaidCodeBlocksInContent(doc) as unknown as {
+      content: Array<{ type: string; attrs: { code: string } }>;
+    };
+    expect(result.content[0]).toEqual({
+      type: "mermaid",
+      attrs: { code: "graph TD\nA-->B" },
+    });
+  });
+
+  it("produces an empty code string when the code block has no children", () => {
+    const doc = {
+      type: "doc",
+      content: [
+        {
+          type: "codeBlock",
+          attrs: { language: "mermaid" },
+        },
+      ],
+    };
+
+    expect(transformMermaidCodeBlocksInContent(doc)).toEqual({
+      type: "doc",
+      content: [
+        {
+          type: "mermaid",
+          attrs: { code: "" },
+        },
+      ],
+    });
+  });
+
+  it("strips trailing newlines from the extracted source", () => {
+    const doc = {
+      type: "doc",
+      content: [
+        {
+          type: "codeBlock",
+          attrs: { language: "mermaid" },
+          content: [{ type: "text", text: "graph TD\nA-->B\n\n" }],
+        },
+      ],
+    };
+
+    const result = transformMermaidCodeBlocksInContent(doc) as unknown as {
+      content: Array<{ attrs: { code: string } }>;
+    };
+    expect(result.content[0].attrs.code).toBe("graph TD\nA-->B");
+  });
+
+  it("transforms mermaid code blocks nested inside lists", () => {
+    const doc = {
+      type: "doc",
+      content: [
+        {
+          type: "bulletList",
+          content: [
+            {
+              type: "listItem",
+              content: [
+                {
+                  type: "codeBlock",
+                  attrs: { language: "mermaid" },
+                  content: [{ type: "text", text: "graph TD" }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = transformMermaidCodeBlocksInContent(doc) as unknown as {
+      content: Array<{
+        content: Array<{
+          content: Array<{ type: string; attrs?: { code?: string } }>;
+        }>;
+      }>;
+    };
+    expect(result.content[0].content[0].content[0]).toEqual({
+      type: "mermaid",
+      attrs: { code: "graph TD" },
+    });
+  });
+
+  it("returns unchanged content when no mermaid block exists", () => {
+    const doc = {
+      type: "doc",
+      content: [
+        {
+          type: "paragraph",
+          content: [{ type: "text", text: "plain text" }],
+        },
+      ],
+    };
+
+    expect(transformMermaidCodeBlocksInContent(doc)).toEqual(doc);
+  });
+
+  it("does not mutate the input object", () => {
+    const doc = {
+      type: "doc",
+      content: [
+        {
+          type: "codeBlock",
+          attrs: { language: "mermaid" },
+          content: [{ type: "text", text: "graph TD" }],
+        },
+      ],
+    };
+    const snapshot = JSON.parse(JSON.stringify(doc));
+
+    transformMermaidCodeBlocksInContent(doc);
+
+    expect(doc).toEqual(snapshot);
+  });
+
+  // ディープクローンを削除し、変更が無いノードは同一参照のまま返す構造共有方式に
+  // した（gemini-code-assist のレビュー、PR #946 高優先）。大きなドキュメントで
+  // 不要なメモリ確保と GC 圧を避けるため、参照同値性で検証する。
+  // The transform now returns the original reference when nothing changes
+  // (structural sharing) instead of deep-cloning up front, per the high-priority
+  // gemini-code-assist review on PR #946. Verify via reference equality.
+  it("returns the same reference when there is no mermaid block", () => {
+    const doc = {
+      type: "doc",
+      content: [
+        {
+          type: "paragraph",
+          content: [{ type: "text", text: "plain" }],
+        },
+      ],
+    };
+
+    expect(transformMermaidCodeBlocksInContent(doc)).toBe(doc);
+  });
+
+  it("shares structure for unaffected sibling subtrees", () => {
+    const untouchedList = {
+      type: "bulletList",
+      content: [
+        {
+          type: "listItem",
+          content: [
+            {
+              type: "paragraph",
+              content: [{ type: "text", text: "item" }],
+            },
+          ],
+        },
+      ],
+    };
+    const doc = {
+      type: "doc",
+      content: [
+        untouchedList,
+        {
+          type: "codeBlock",
+          attrs: { language: "mermaid" },
+          content: [{ type: "text", text: "graph TD" }],
+        },
+      ],
+    };
+
+    const result = transformMermaidCodeBlocksInContent(doc) as unknown as {
+      content: Array<unknown>;
+    };
+    // ルートと content 配列は新しく作られるが、変更されていない兄弟は同一参照を共有する。
+    // The root and content array are reallocated, but unchanged siblings share refs.
+    expect(result).not.toBe(doc);
+    expect(result.content[0]).toBe(untouchedList);
+  });
+
+  it("transforms multiple mermaid code blocks in the same document", () => {
+    const doc = {
+      type: "doc",
+      content: [
+        {
+          type: "codeBlock",
+          attrs: { language: "mermaid" },
+          content: [{ type: "text", text: "graph TD" }],
+        },
+        {
+          type: "paragraph",
+          content: [{ type: "text", text: "between" }],
+        },
+        {
+          type: "codeBlock",
+          attrs: { language: "mermaid" },
+          content: [{ type: "text", text: "sequenceDiagram" }],
+        },
+      ],
+    };
+
+    const result = transformMermaidCodeBlocksInContent(doc) as unknown as {
+      content: Array<{ type: string; attrs?: { code?: string } }>;
+    };
+    expect(result.content[0]).toEqual({ type: "mermaid", attrs: { code: "graph TD" } });
+    expect(result.content[1].type).toBe("paragraph");
+    expect(result.content[2]).toEqual({
+      type: "mermaid",
+      attrs: { code: "sequenceDiagram" },
+    });
+  });
+});
diff --git a/src/components/editor/extensions/transformMermaidCodeBlocksInContent.ts b/src/components/editor/extensions/transformMermaidCodeBlocksInContent.ts
new file mode 100644
index 00000000..caf1b194
--- /dev/null
+++ b/src/components/editor/extensions/transformMermaidCodeBlocksInContent.ts
@@ -0,0 +1,174 @@
+/**
+ * Markdown のフェンス言語 `mermaid` で書かれたコードブロック（Tiptap JSON 上では
+ * `codeBlock` + `attrs.language === "mermaid"`）を、専用の `mermaid` ノードに
+ * 変換するためのユーティリティ。
+ *
+ * Utility that converts Markdown fenced code blocks tagged with the language
+ * identifier `mermaid` (represented as `codeBlock` nodes with
+ * `attrs.language === "mermaid"` in the Tiptap JSON tree) into dedicated
+ * `mermaid` nodes so they render as SVG diagrams via the existing
+ * `MermaidNodeView`.
+ *
+ * `@tiptap/markdown` はフェンス言語にかかわらず `codeBlock` を生成するため、
+ * Wiki リンクの後処理（`transformWikiLinksInContent`）と同様に、パース後の
+ * ProseMirror JSON を走査して該当ノードを差し替える。
+ *
+ * Since `@tiptap/markdown` always produces a `codeBlock` regardless of fence
+ * language, we post-process the parsed ProseMirror JSON—mirroring the pattern
+ * used by `transformWikiLinksInContent`—and replace matching code blocks with
+ * `mermaid` nodes.
+ */
+
+/**
+ * ProseMirror のマーク定義（最小限の構造）。
+ * Minimal shape of a ProseMirror mark definition.
+ */
+interface MarkJSON {
+  type: string;
+  attrs?: Record<string, unknown>;
+}
+
+/**
+ * ProseMirror のノード定義（最小限の構造）。
+ * Minimal shape of a ProseMirror node.
+ */
+interface NodeJSON {
+  type: string;
+  text?: string;
+  attrs?: Record<string, unknown>;
+  marks?: MarkJSON[];
+  content?: NodeJSON[];
+}
+
+/**
+ * 与えられたコードブロックノードの `language` 属性が "mermaid" を示すかを判定する。
+ * 大文字小文字を無視（`"Mermaid"` / `"MERMAID"` も対象）し、前後の空白はトリムする。
+ *
+ * Returns whether a code block node's `language` attribute refers to mermaid.
+ * The comparison is case-insensitive (so `"Mermaid"` / `"MERMAID"` also match)
+ * and surrounding whitespace is trimmed.
+ *
+ * @param attrs - codeBlock ノードの属性 / Attributes of the codeBlock node.
+ */
+function isMermaidLanguage(attrs: Record<string, unknown> | undefined): boolean {
+  const language = attrs?.language;
+  if (typeof language !== "string") return false;
+  return language.trim().toLowerCase() === "mermaid";
+}
+
+/**
+ * ノード配列内の `text` ノードを連結して 1 つの文字列にする。
+ * Mermaid のソースコードは複数の `text` ノードに分かれている場合があるため、
+ * `hardBreak` を改行に展開しつつ平坦化する。
+ *
+ * Concatenate the textual content of a node's children. Mermaid source code
+ * may be split across multiple `text` nodes; `hardBreak` nodes are expanded
+ * to newlines so the resulting string is suitable as raw Mermaid source.
+ *
+ * @param nodes - 抽出対象のノード配列 / Child nodes to flatten.
+ * @returns 連結したテキスト / The concatenated text.
+ */
+function extractCodeText(nodes: NodeJSON[] | undefined): string {
+  if (!nodes || nodes.length === 0) return "";
+  let result = "";
+  for (const node of nodes) {
+    if (node.type === "text") {
+      result += node.text ?? "";
+      continue;
+    }
+    if (node.type === "hardBreak") {
+      result += "\n";
+      continue;
+    }
+    if (node.content && node.content.length > 0) {
+      result += extractCodeText(node.content);
+    }
+  }
+  return result;
+}
+
+/**
+ * 1 つのノードに対して、Mermaid コードブロックを `mermaid` ノードに置換する。
+ * テキスト末尾の改行は表示時のノイズになるため削除する。子ノードに変更が
+ * 無い場合は同一参照を返し、構造共有によって不要な配列・オブジェクト生成を
+ * 避ける（入力は不変）。
+ *
+ * Replace a `codeBlock` with `language: "mermaid"` by an equivalent `mermaid`
+ * node, or recurse into the node's children otherwise. Trailing newlines in
+ * the extracted source are stripped because Mermaid does not require them and
+ * they would otherwise leak into the rendered diagram's caption area. The
+ * function returns the original reference whenever no descendant was rewritten,
+ * which lets callers rely on referential equality to detect changes and avoids
+ * unnecessary allocations (the input is never mutated either way).
+ *
+ * @param node - 走査対象のノード / The node to inspect.
+ * @returns 変換後のノード / The (possibly transformed) node.
+ */
+function transformNode(node: NodeJSON): NodeJSON {
+  if ((node.type === "codeBlock" || node.type === "code_block") && isMermaidLanguage(node.attrs)) {
+    const code = extractCodeText(node.content).replace(/\n+$/u, "");
+    return {
+      type: "mermaid",
+      attrs: { code },
+    };
+  }
+
+  const content = node.content;
+  if (!content || content.length === 0) {
+    return node;
+  }
+
+  let changedContent: NodeJSON[] | null = null;
+  for (let i = 0; i < content.length; i += 1) {
+    const child = content[i];
+    const transformed = transformNode(child);
+    if (transformed !== child) {
+      // 最初の変更を検出した時点で配列を複製し、先行する未変更ノードをコピーする。
+      // Lazily clone the array on the first change, preserving prior children.
+      if (!changedContent) {
+        changedContent = content.slice(0, i);
+      }
+      changedContent.push(transformed);
+    } else if (changedContent) {
+      changedContent.push(child);
+    }
+  }
+
+  return changedContent ? { ...node, content: changedContent } : node;
+}
+
+/**
+ * ProseMirror JSON ドキュメント全体を走査し、`language === "mermaid"` の
+ * コードブロックを `mermaid` ノードに置換した新しいドキュメントを返す。
+ * 入力は不変。変換対象が無い場合は同一参照を返す。
+ *
+ * Walk a ProseMirror JSON document, replacing every `codeBlock` whose
+ * `language` is `"mermaid"` (case-insensitive) with a `mermaid` node so it
+ * renders as a diagram. The input is not mutated. When no mermaid block is
+ * found, the original reference is returned unchanged—`transformNode` only
+ * allocates along the path of actual changes, so large pasted/loaded docs
+ * without diagrams incur zero copying.
+ *
+ * @param content - `editor.markdown.parse()` などで得た ProseMirror JSON。
+ *                  Document JSON produced by e.g. `editor.markdown.parse()`.
+ * @returns 変換後の JSON（入力は不変）/ Transformed JSON (input untouched).
+ */
+export function transformMermaidCodeBlocksInContent<T extends NodeJSON>(content: T): T {
+  return transformNode(content) as T;
+}
+
+/**
+ * テキストに `mermaid` フェンスらしき記法が含まれているか軽量に判定する。
+ * `MarkdownPasteExtension` で「Mermaid 変換を試みるべきか」のショートカット判定に使う。
+ *
+ * Lightweight predicate that tells whether a string contains a fenced
+ * code block whose info string starts with `mermaid` (case-insensitive). Used
+ * by `MarkdownPasteExtension` as a fast pre-check before running the full
+ * post-parse transform.
+ *
+ * @param text - 判定対象のテキスト / Text to inspect.
+ * @returns Mermaid フェンスが含まれていれば true / true if a mermaid fence is present.
+ */
+export function containsMermaidFence(text: string): boolean {
+  return /^[\t ]{0,3}```[\t ]*mermaid\b/im.test(text);
+}
diff --git a/src/components/editor/extensions/wikiLinkGhostCompletionPlugin.test.ts b/src/components/editor/extensions/wikiLinkGhostCompletionPlugin.test.ts
new file mode 100644
index 00000000..bc3f4a97
--- /dev/null
+++ b/src/components/editor/extensions/wikiLinkGhostCompletionPlugin.test.ts
@@ -0,0 +1,666 @@
+/**
+ * Tests for the inline ghost completion ProseMirror plugin (issue #930,
+ * parent #924 §4).
+ * インラインゴースト補完用 ProseMirror プラグインのテスト（issue #930、
+ * 親 #924 §4）。
+ *
+ * Same TDD-friendly approach as `tagSuggestionPlugin.test.ts`: build a minimal
+ * ProseMirror schema (paragraph / heading / blockquote / list / table cell /
+ * code block, plus `code` and `wikiLink` marks) and feed transactions directly
+ * so we can pin trigger / dismissal behaviour without spinning up a real
+ * Tiptap editor. Confirmation logic is exercised via `buildConfirmTransaction`
+ * which is a pure function over `EditorState`.
+ *
+ * `tagSuggestionPlugin.test.ts` と同じく最小スキーマと直接 transaction 適用
+ * でプラグインの挙動を固定する。確定パスは pure な
+ * `buildConfirmTransaction` で検証する（view 構築不要）。
+ */
+
+import type { Plugin } from "@tiptap/pm/state";
+import { EditorState, TextSelection } from "@tiptap/pm/state";
+import { Schema } from "@tiptap/pm/model";
+import { describe, expect, it, vi } from "vitest";
+import {
+  WikiLinkGhostCompletionPlugin,
+  wikiLinkGhostCompletionPluginKey,
+  buildConfirmTransaction,
+  buildGhostCompletionWidget,
+  type WikiLinkGhostCompletionCandidate,
+  type WikiLinkGhostCompletionState,
+  type WikiLinkGhostCompletionOptions,
+} from "./wikiLinkGhostCompletionPlugin";
+import { WikiLinkSuggestionPlugin, wikiLinkSuggestionPluginKey } from "./wikiLinkSuggestionPlugin";
+import { TagSuggestionPlugin, tagSuggestionPluginKey } from "./tagSuggestionPlugin";
+import { SlashSuggestionPlugin, slashSuggestionPluginKey } from "./slashSuggestionPlugin";
+
+/**
+ * Minimal schema covering every node / mark the plugin needs to reason about.
+ * 本プラグインが判定する全ノード / マークを最小スキーマで再現。
+ */
+const schema = new Schema({
+  nodes: {
+    doc: { content: "block+" },
+    paragraph: {
+      group: "block",
+      content: "text*",
+      toDOM: () => ["p", 0],
+    },
+    heading: {
+      group: "block",
+      content: "text*",
+      attrs: { level: { default: 2 } },
+      toDOM: (n) => [`h${n.attrs.level as number}`, 0],
+    },
+    blockquote: {
+      group: "block",
+      content: "block+",
+      toDOM: () => ["blockquote", 0],
+    },
+    bullet_list: {
+      group: "block",
+      content: "list_item+",
+      toDOM: () => ["ul", 0],
+    },
+    list_item: {
+      content: "paragraph block*",
+      toDOM: () => ["li", 0],
+    },
+    table: {
+      group: "block",
+      content: "table_row+",
+      toDOM: () => ["table", ["tbody", 0]],
+    },
+    table_row: {
+      content: "table_cell+",
+      toDOM: () => ["tr", 0],
+    },
+    table_cell: {
+      content: "paragraph+",
+      toDOM: () => ["td", 0],
+    },
+    code_block: {
+      group: "block",
+      content: "text*",
+      code: true,
+      defining: true,
+      marks: "",
+      toDOM: () => ["pre", ["code", 0]],
+    },
+    // Used to verify ancestor-based suppression ("title / caption / 本文外").
+    // 「タイトル / キャプション / 本文外」の祖先抑止を検証するためのノード。
+    title: {
+      group: "block",
+      content: "text*",
+      toDOM: () => ["h1", 0],
+    },
+    caption: {
+      group: "block",
+      content: "text*",
+      toDOM: () => ["figcaption", 0],
+    },
+    text: { group: "inline" },
+  },
+  marks: {
+    code: {
+      code: true,
+      toDOM: () => ["code", 0],
+    },
+    wikiLink: {
+      attrs: {
+        title: { default: null },
+        exists: { default: true },
+        referenced: { default: false },
+        targetId: { default: null },
+      },
+      toDOM: () => ["span", { "data-wiki-link": "" }, 0],
+    },
+  },
+});
+
+/**
+ * Pulls the bare ProseMirror plugin out of the Tiptap extension wrapper so we
+ * can install it on a hand-built `EditorState`. Same pattern as
+ * `tagSuggestionPlugin.test.ts`.
+ *
+ * Tiptap 拡張ラッパーから素の ProseMirror プラグインを取り出す。
+ */
+function getPlugin(options: WikiLinkGhostCompletionOptions): Plugin {
+  const extension = WikiLinkGhostCompletionPlugin.configure(options);
+  const addPlugins = extension.config.addProseMirrorPlugins;
+  if (!addPlugins) throw new Error("addProseMirrorPlugins missing");
+  const plugins = addPlugins.call({ options } as never);
+  return plugins[0];
+}
+
+interface BuildOpts {
+  candidates?: ReadonlyArray<WikiLinkGhostCompletionCandidate>;
+  onStateChange?: (s: WikiLinkGhostCompletionState) => void;
+  allowedNodeTypes?: ReadonlySet<string>;
+}
+
+function buildPlugin(opts: BuildOpts = {}): Plugin {
+  return getPlugin({
+    getCandidates: () => opts.candidates ?? [],
+    onStateChange: opts.onStateChange,
+    allowedNodeTypes: opts.allowedNodeTypes,
+  });
+}
+
+/**
+ * Place caret at end of inline content in the given block.
+ * 指定ブロックのインライン末尾にキャレットを置く。
+ */
+function caretAtEnd(state: EditorState, text: string): EditorState {
+  const tr = state.tr.setSelection(TextSelection.create(state.doc, 1 + text.length));
+  return state.apply(tr);
+}
+
+function makeParagraphState(text: string, plugin: Plugin): EditorState {
+  const doc = schema.node("doc", null, [
+    schema.node("paragraph", null, text ? [schema.text(text)] : []),
+  ]);
+  const state = EditorState.create({ doc, schema, plugins: [plugin] });
+  return caretAtEnd(state, text);
+}
+
+function makeHeadingState(text: string, plugin: Plugin): EditorState {
+  const doc = schema.node("doc", null, [
+    schema.node("heading", { level: 2 }, text ? [schema.text(text)] : []),
+  ]);
+  const state = EditorState.create({ doc, schema, plugins: [plugin] });
+  return caretAtEnd(state, text);
+}
+
+function makeBlockquoteState(text: string, plugin: Plugin): EditorState {
+  const doc = schema.node("doc", null, [
+    schema.node("blockquote", null, [
+      schema.node("paragraph", null, text ? [schema.text(text)] : []),
+    ]),
+  ]);
+  const state = EditorState.create({ doc, schema, plugins: [plugin] });
+  // doc(0)/blockquote(1)/paragraph(1)/text… → caret at 2 + text.length.
+  // ネスト 2 段なので caret 位置は 2 + text.length。
+  const tr = state.tr.setSelection(TextSelection.create(state.doc, 2 + text.length));
+  return state.apply(tr);
+}
+
+function makeListItemState(text: string, plugin: Plugin): EditorState {
+  const doc = schema.node("doc", null, [
+    schema.node("bullet_list", null, [
+      schema.node("list_item", null, [
+        schema.node("paragraph", null, text ? [schema.text(text)] : []),
+      ]),
+    ]),
+  ]);
+  const state = EditorState.create({ doc, schema, plugins: [plugin] });
+  // doc/bullet_list(1)/list_item(1)/paragraph(1)/text…
+  // ネスト 3 段なので caret 位置は 3 + text.length。
+  const tr = state.tr.setSelection(TextSelection.create(state.doc, 3 + text.length));
+  return state.apply(tr);
+}
+
+function makeTableCellState(text: string, plugin: Plugin): EditorState {
+  const doc = schema.node("doc", null, [
+    schema.node("table", null, [
+      schema.node("table_row", null, [
+        schema.node("table_cell", null, [
+          schema.node("paragraph", null, text ? [schema.text(text)] : []),
+        ]),
+      ]),
+    ]),
+  ]);
+  const state = EditorState.create({ doc, schema, plugins: [plugin] });
+  // doc/table(1)/table_row(1)/table_cell(1)/paragraph(1)/text…
+  // ネスト 4 段なので caret 位置は 4 + text.length。
+  const tr = state.tr.setSelection(TextSelection.create(state.doc, 4 + text.length));
+  return state.apply(tr);
+}
+
+function makeCodeBlockState(text: string, plugin: Plugin): EditorState {
+  const doc = schema.node("doc", null, [
+    schema.node("code_block", null, text ? [schema.text(text)] : []),
+  ]);
+  const state = EditorState.create({ doc, schema, plugins: [plugin] });
+  return caretAtEnd(state, text);
+}
+
+function makeInlineCodeState(text: string, plugin: Plugin): EditorState {
+  const codeMark = schema.marks.code.create();
+  const doc = schema.node("doc", null, [
+    schema.node("paragraph", null, text ? [schema.text(text, [codeMark])] : []),
+  ]);
+  const state = EditorState.create({ doc, schema, plugins: [plugin] });
+  return caretAtEnd(state, text);
+}
+
+function makeTitleNodeState(text: string, plugin: Plugin): EditorState {
+  const doc = schema.node("doc", null, [
+    schema.node("title", null, text ? [schema.text(text)] : []),
+  ]);
+  const state = EditorState.create({ doc, schema, plugins: [plugin] });
+  return caretAtEnd(state, text);
+}
+
+function makeCaptionNodeState(text: string, plugin: Plugin): EditorState {
+  const doc = schema.node("doc", null, [
+    schema.node("caption", null, text ? [schema.text(text)] : []),
+  ]);
+  const state = EditorState.create({ doc, schema, plugins: [plugin] });
+  return caretAtEnd(state, text);
+}
+
+function makeInsideWikiLinkState(text: string, plugin: Plugin): EditorState {
+  const linkMark = schema.marks.wikiLink.create({
+    title: "Existing",
+    exists: true,
+    referenced: false,
+    targetId: null,
+  });
+  const doc = schema.node("doc", null, [
+    schema.node("paragraph", null, text ? [schema.text(text, [linkMark])] : []),
+  ]);
+  const state = EditorState.create({ doc, schema, plugins: [plugin] });
+  return caretAtEnd(state, text);
+}
+
+const TARGETS = [
+  { id: "id-ghost", title: "Ghost Target" },
+  { id: "id-another", title: "Another Note" },
+  { id: "id-technique", title: "技術メモ" },
+] as const satisfies ReadonlyArray<WikiLinkGhostCompletionCandidate>;
+
+describe("wikiLinkGhostCompletionPlugin — initial state", () => {
+  it("initialises as inactive", () => {
+    const plugin = buildPlugin();
+    const state = makeParagraphState("", plugin);
+    const pluginState = wikiLinkGhostCompletionPluginKey.getState(state);
+    expect(pluginState).toMatchObject({
+      active: false,
+      range: null,
+      query: "",
+      candidate: null,
+      suffix: "",
+    });
+  });
+});
+
+describe("wikiLinkGhostCompletionPlugin — activation", () => {
+  it("activates when the typed word prefix-matches a candidate title", () => {
+    const plugin = buildPlugin({ candidates: TARGETS });
+    const state = makeParagraphState("Gho", plugin);
+    const pluginState = wikiLinkGhostCompletionPluginKey.getState(state);
+
+    expect(pluginState?.active).toBe(true);
+    expect(pluginState?.query).toBe("Gho");
+    expect(pluginState?.candidate).toMatchObject({ id: "id-ghost", title: "Ghost Target" });
+    expect(pluginState?.suffix).toBe("st Target");
+    expect(pluginState?.range).toEqual({ from: 1, to: 4 });
+  });
+
+  it("preserves the candidate's casing in the suffix even if the user typed lowercase", () => {
+    const plugin = buildPlugin({ candidates: TARGETS });
+    const state = makeParagraphState("gho", plugin);
+    const pluginState = wikiLinkGhostCompletionPluginKey.getState(state);
+    expect(pluginState?.active).toBe(true);
+    expect(pluginState?.suffix).toBe("st Target");
+    expect(pluginState?.query).toBe("gho");
+  });
+
+  it("matches CJK candidates", () => {
+    const plugin = buildPlugin({ candidates: TARGETS });
+    const state = makeParagraphState("技", plugin);
+    // 1 char only → ≥2 rule rejects.
+    // 1 文字なので 2 文字以上ルールにより不発火。
+    expect(wikiLinkGhostCompletionPluginKey.getState(state)?.active).toBe(false);
+
+    const state2 = makeParagraphState("技術", plugin);
+    const ps = wikiLinkGhostCompletionPluginKey.getState(state2);
+    expect(ps?.active).toBe(true);
+    expect(ps?.suffix).toBe("メモ");
+    expect(ps?.candidate?.id).toBe("id-technique");
+  });
+
+  it("fires on heading, blockquote, list item, and table cell", () => {
+    const cases: Array<(t: string, p: Plugin) => EditorState> = [
+      makeHeadingState,
+      makeBlockquoteState,
+      makeListItemState,
+      makeTableCellState,
+    ];
+    for (const make of cases) {
+      const plugin = buildPlugin({ candidates: TARGETS });
+      const state = make("Gho", plugin);
+      const ps = wikiLinkGhostCompletionPluginKey.getState(state);
+      expect(ps?.active, `expected active in ${make.name}`).toBe(true);
+      expect(ps?.suffix).toBe("st Target");
+    }
+  });
+
+  it("calls onStateChange with the activation state", () => {
+    const onStateChange = vi.fn();
+    const plugin = buildPlugin({ candidates: TARGETS, onStateChange });
+    makeParagraphState("Gho", plugin);
+    expect(onStateChange).toHaveBeenCalled();
+    const calls = onStateChange.mock.calls;
+    const last = calls[calls.length - 1]?.[0] as WikiLinkGhostCompletionState;
+    expect(last.active).toBe(true);
+    expect(last.candidate?.title).toBe("Ghost Target");
+  });
+});
+
+describe("wikiLinkGhostCompletionPlugin — minimum length and word boundary", () => {
+  it("does not activate for a single-character word", () => {
+    const plugin = buildPlugin({ candidates: TARGETS });
+    const state = makeParagraphState("G", plugin);
+    expect(wikiLinkGhostCompletionPluginKey.getState(state)?.active).toBe(false);
+  });
+
+  it("does not activate when there are no candidate matches", () => {
+    const plugin = buildPlugin({ candidates: TARGETS });
+    const state = makeParagraphState("Xyz", plugin);
+    expect(wikiLinkGhostCompletionPluginKey.getState(state)?.active).toBe(false);
+  });
+
+  it("does not activate for an exact match (no suffix to show)", () => {
+    const plugin = buildPlugin({
+      candidates: [{ id: "x", title: "Hello" }],
+    });
+    const state = makeParagraphState("Hello", plugin);
+    expect(wikiLinkGhostCompletionPluginKey.getState(state)?.active).toBe(false);
+  });
+
+  it("only considers the current word (post-whitespace)", () => {
+    const plugin = buildPlugin({ candidates: TARGETS });
+    const state = makeParagraphState("hello Gho", plugin);
+    const ps = wikiLinkGhostCompletionPluginKey.getState(state);
+    expect(ps?.active).toBe(true);
+    expect(ps?.query).toBe("Gho");
+    // "hello " is 6 chars → typed word starts at pos 7.
+    // 直前の "hello " が 6 文字なので入力中の単語は pos 7 から始まる。
+    expect(ps?.range).toEqual({ from: 7, to: 10 });
+  });
+
+  it("rejects words that start with `[`, `]`, `#`, `@`, or `/`", () => {
+    const plugin = buildPlugin({ candidates: TARGETS });
+    for (const leader of ["[", "]", "#", "@", "/"]) {
+      const state = makeParagraphState(`${leader}Gho`, plugin);
+      expect(
+        wikiLinkGhostCompletionPluginKey.getState(state)?.active,
+        `expected inactive for leader "${leader}"`,
+      ).toBe(false);
+    }
+  });
+});
+
+describe("wikiLinkGhostCompletionPlugin — code block / inline code suppression", () => {
+  it("does not activate inside a code block", () => {
+    const plugin = buildPlugin({ candidates: TARGETS });
+    const state = makeCodeBlockState("Gho", plugin);
+    expect(wikiLinkGhostCompletionPluginKey.getState(state)?.active).toBe(false);
+  });
+
+  it("does not activate inside an inline `code` mark", () => {
+    const plugin = buildPlugin({ candidates: TARGETS });
+    const state = makeInlineCodeState("Gho", plugin);
+    expect(wikiLinkGhostCompletionPluginKey.getState(state)?.active).toBe(false);
+  });
+});
+
+describe("wikiLinkGhostCompletionPlugin — out-of-body suppression", () => {
+  it("does not activate inside a `title` node", () => {
+    const plugin = buildPlugin({ candidates: TARGETS });
+    const state = makeTitleNodeState("Gho", plugin);
+    expect(wikiLinkGhostCompletionPluginKey.getState(state)?.active).toBe(false);
+  });
+
+  it("does not activate inside a `caption` node", () => {
+    const plugin = buildPlugin({ candidates: TARGETS });
+    const state = makeCaptionNodeState("Gho", plugin);
+    expect(wikiLinkGhostCompletionPluginKey.getState(state)?.active).toBe(false);
+  });
+
+  it("does not activate inside an existing `wikiLink` mark", () => {
+    const plugin = buildPlugin({ candidates: TARGETS });
+    const state = makeInsideWikiLinkState("Gho", plugin);
+    expect(wikiLinkGhostCompletionPluginKey.getState(state)?.active).toBe(false);
+  });
+});
+
+describe("wikiLinkGhostCompletionPlugin — coordination with other suggesters", () => {
+  it("is suppressed when the `[[` suggestion plugin is active", () => {
+    // We install both plugins so the `apply` of the wiki suggestion plugin
+    // populates its own state before ours runs.
+    // 両プラグインを併設し、wiki サジェスト側の `apply` でその状態が立ってから
+    // 本プラグインの `apply` が走る順序を再現する。
+    const ghost = buildPlugin({ candidates: TARGETS });
+    const wikiExt = WikiLinkSuggestionPlugin.configure({});
+    const addWikiPlugins = wikiExt.config.addProseMirrorPlugins;
+    if (!addWikiPlugins) throw new Error("WikiLinkSuggestionPlugin.addProseMirrorPlugins missing");
+    const wikiPlugin = addWikiPlugins.call({ options: {} } as never)[0];
+
+    const doc = schema.node("doc", null, [schema.node("paragraph", null, [schema.text("[[Gho")])]);
+    let state = EditorState.create({ doc, schema, plugins: [wikiPlugin, ghost] });
+    state = state.apply(state.tr.setSelection(TextSelection.create(state.doc, 6)));
+
+    // Wiki link suggestion must be active for this assertion to be meaningful.
+    // この assertion が意味を持つよう、Wiki サジェスト側が active であることを担保。
+    expect(wikiLinkSuggestionPluginKey.getState(state)?.active).toBe(true);
+    // Ghost completion must be suppressed.
+    // ゴースト補完は抑止されているべき。
+    expect(wikiLinkGhostCompletionPluginKey.getState(state)?.active).toBe(false);
+  });
+
+  it("is suppressed when the `#` tag suggestion plugin is active", () => {
+    const ghost = buildPlugin({ candidates: TARGETS });
+    const tagExt = TagSuggestionPlugin.configure({});
+    const addTagPlugins = tagExt.config.addProseMirrorPlugins;
+    if (!addTagPlugins) throw new Error("TagSuggestionPlugin.addProseMirrorPlugins missing");
+    const tagPlugin = addTagPlugins.call({ options: {} } as never)[0];
+
+    const doc = schema.node("doc", null, [schema.node("paragraph", null, [schema.text("#Gho")])]);
+    let state = EditorState.create({ doc, schema, plugins: [tagPlugin, ghost] });
+    state = state.apply(state.tr.setSelection(TextSelection.create(state.doc, 5)));
+
+    expect(tagSuggestionPluginKey.getState(state)?.active).toBe(true);
+    expect(wikiLinkGhostCompletionPluginKey.getState(state)?.active).toBe(false);
+  });
+
+  it("is suppressed when the `/` slash suggestion plugin is active (even mid-arg)", () => {
+    // SlashSuggestionPlugin は空白を含むクエリでも active を維持するため、
+    // 「`/cmd Ghost`」のような入力ではスラッシュメニューとゴーストが衝突しうる。
+    // ここでは両プラグインを同居させ、スラッシュ active 中はゴーストが立たない
+    // ことを保証する（Codex PR レビュー指摘）。
+    // SlashSuggestionPlugin stays active across whitespace, so an input like
+    // `/cmd Ghost` could double-fire the ghost. This test pins the mutual
+    // exclusion contract added in response to the PR review.
+    const ghost = buildPlugin({ candidates: TARGETS });
+    const slashExt = SlashSuggestionPlugin.configure({});
+    const addSlashPlugins = slashExt.config.addProseMirrorPlugins;
+    if (!addSlashPlugins) throw new Error("SlashSuggestionPlugin.addProseMirrorPlugins missing");
+    const slashPlugin = addSlashPlugins.call({ options: {} } as never)[0];
+
+    const doc = schema.node("doc", null, [
+      schema.node("paragraph", null, [schema.text("/cmd Gho")]),
+    ]);
+    let state = EditorState.create({ doc, schema, plugins: [slashPlugin, ghost] });
+    state = state.apply(state.tr.setSelection(TextSelection.create(state.doc, 9)));
+
+    // Slash サジェスト側が active であることを前提に、ゴーストは抑止される。
+    // Slash side must be active for this assertion to be meaningful.
+    expect(slashSuggestionPluginKey.getState(state)?.active).toBe(true);
+    expect(wikiLinkGhostCompletionPluginKey.getState(state)?.active).toBe(false);
+  });
+});
+
+describe("wikiLinkGhostCompletionPlugin — dismissal", () => {
+  it("turns off when the typed prefix no longer matches", () => {
+    const plugin = buildPlugin({ candidates: TARGETS });
+    let state = makeParagraphState("Gho", plugin);
+    expect(wikiLinkGhostCompletionPluginKey.getState(state)?.active).toBe(true);
+
+    state = state.apply(state.tr.insertText("x", 4));
+    expect(wikiLinkGhostCompletionPluginKey.getState(state)?.active).toBe(false);
+  });
+
+  it("turns off when selection becomes a non-empty range", () => {
+    const plugin = buildPlugin({ candidates: TARGETS });
+    let state = makeParagraphState("Gho", plugin);
+    expect(wikiLinkGhostCompletionPluginKey.getState(state)?.active).toBe(true);
+
+    state = state.apply(state.tr.setSelection(TextSelection.create(state.doc, 1, 4)));
+    expect(wikiLinkGhostCompletionPluginKey.getState(state)?.active).toBe(false);
+  });
+
+  it("close meta clears the active state and notifies subscribers", () => {
+    const onStateChange = vi.fn();
+    const plugin = buildPlugin({ candidates: TARGETS, onStateChange });
+    let state = makeParagraphState("Gho", plugin);
+    expect(wikiLinkGhostCompletionPluginKey.getState(state)?.active).toBe(true);
+    onStateChange.mockClear();
+
+    state = state.apply(state.tr.setMeta(wikiLinkGhostCompletionPluginKey, { close: true }));
+    const ps = wikiLinkGhostCompletionPluginKey.getState(state);
+    expect(ps?.active).toBe(false);
+    expect(ps?.candidate).toBeNull();
+    expect(onStateChange).toHaveBeenCalledWith(ps);
+  });
+});
+
+describe("wikiLinkGhostCompletionPlugin — candidate filtering and tie-breaking", () => {
+  it("ignores soft-deleted candidates", () => {
+    const plugin = buildPlugin({
+      candidates: [{ id: "x", title: "Ghost Town", isDeleted: true }],
+    });
+    const state = makeParagraphState("Gho", plugin);
+    expect(wikiLinkGhostCompletionPluginKey.getState(state)?.active).toBe(false);
+  });
+
+  it("breaks ties by shortest title", () => {
+    const plugin = buildPlugin({
+      candidates: [
+        { id: "long", title: "Tested Across Suite" },
+        { id: "short", title: "Tested" },
+        { id: "mid", title: "Tested Path" },
+      ],
+    });
+    const state = makeParagraphState("Tes", plugin);
+    const ps = wikiLinkGhostCompletionPluginKey.getState(state);
+    expect(ps?.active).toBe(true);
+    expect(ps?.candidate?.id).toBe("short");
+    expect(ps?.suffix).toBe("ted");
+  });
+});
+
+describe("wikiLinkGhostCompletionPlugin — decorations", () => {
+  it("renders a widget decoration at the end of the typed range when active", () => {
+    const plugin = buildPlugin({ candidates: TARGETS });
+    const state = makeParagraphState("Gho", plugin);
+    const ps = wikiLinkGhostCompletionPluginKey.getState(state);
+    expect(ps?.active).toBe(true);
+
+    const decos = ps?.decorations.find(0, state.doc.content.size) ?? [];
+    expect(decos).toHaveLength(1);
+    // Widget decorations have `from === to` at the insertion point.
+    // widget の from === to が widget 位置。
+    expect(decos[0].from).toBe(4);
+    expect(decos[0].to).toBe(4);
+  });
+
+  it("returns an empty decoration set when inactive", () => {
+    const plugin = buildPlugin({ candidates: TARGETS });
+    const state = makeParagraphState("Xyz", plugin);
+    const ps = wikiLinkGhostCompletionPluginKey.getState(state);
+    expect(ps?.active).toBe(false);
+    const decos = ps?.decorations.find(0, state.doc.content.size) ?? [];
+    expect(decos).toHaveLength(0);
+  });
+});
+
+describe("buildGhostCompletionWidget", () => {
+  it("renders a span with the correct class, suffix, target id, and non-editable flag", () => {
+    const span = buildGhostCompletionWidget("st Target", { id: "id-ghost", title: "Ghost Target" });
+    expect(span.tagName).toBe("SPAN");
+    expect(span.className).toBe("wiki-link-ghost-completion");
+    expect(span.textContent).toBe("st Target");
+    expect(span.getAttribute("data-ghost-completion")).toBe("true");
+    expect(span.getAttribute("data-target-id")).toBe("id-ghost");
+    expect(span.getAttribute("contenteditable")).toBe("false");
+  });
+});
+
+describe("buildConfirmTransaction", () => {
+  it("replaces the typed range with the full title carrying a wikiLink mark", () => {
+    const plugin = buildPlugin({ candidates: TARGETS });
+    const state = makeParagraphState("Gho", plugin);
+    const ps = wikiLinkGhostCompletionPluginKey.getState(state);
+    if (!ps?.active || !ps.range || !ps.candidate) {
+      throw new Error("expected plugin state to be active with range + candidate");
+    }
+
+    const tr = buildConfirmTransaction(state, ps.range, ps.candidate);
+    if (!tr) throw new Error("expected non-null confirm transaction");
+    const next = state.apply(tr);
+
+    // After confirm, the paragraph contains the full title with a wikiLink mark.
+    // 確定後、段落はフルタイトル + wikiLink マークを持つ。
+    const para = next.doc.firstChild;
+    if (!para) throw new Error("expected doc to have a child");
+    expect(para.textContent).toBe("Ghost Target");
+    const firstText = para.firstChild;
+    if (!firstText) throw new Error("expected paragraph to have a text node");
+    const wikiMark = firstText.marks.find((m) => m.type === schema.marks.wikiLink);
+    expect(wikiMark).toBeDefined();
+    expect(wikiMark?.attrs).toMatchObject({
+      title: "Ghost Target",
+      exists: true,
+      referenced: false,
+      targetId: "id-ghost",
+    });
+
+    // Plugin state collapses to inactive on the same transaction (close meta).
+    // 同じ transaction の close メタで非アクティブに倒れる。
+    expect(wikiLinkGhostCompletionPluginKey.getState(next)?.active).toBe(false);
+
+    // Cursor lands right after the inserted title.
+    // 挿入直後（"Ghost Target".length = 12 → pos 1 + 12 = 13）に caret。
+    expect(next.selection.from).toBe(13);
+    expect(next.selection.to).toBe(13);
+
+    // Stored marks cleared so the next keystroke is not styled as a wikiLink.
+    // 直後のキーストロークがマークを引き継がないことを保証。
+    expect(next.storedMarks ?? []).toEqual([]);
+  });
+
+  it("returns null if the schema lacks a wikiLink mark", () => {
+    const slimSchema = new Schema({
+      nodes: {
+        doc: { content: "paragraph+" },
+        paragraph: { content: "text*", toDOM: () => ["p", 0] },
+        text: {},
+      },
+      marks: {},
+    });
+    const doc = slimSchema.node("doc", null, [
+      slimSchema.node("paragraph", null, [slimSchema.text("Gho")]),
+    ]);
+    const state = EditorState.create({ doc, schema: slimSchema });
+    const tr = buildConfirmTransaction(
+      state,
+      { from: 1, to: 4 },
+      { id: "x", title: "Ghost Target" },
+    );
+    expect(tr).toBeNull();
+  });
+});
+
+describe("WikiLinkGhostCompletionPlugin — extension wiring", () => {
+  it("declares the expected extension name", () => {
+    expect(WikiLinkGhostCompletionPlugin.name).toBe("wikiLinkGhostCompletion");
+  });
+
+  it("uses an empty default candidate list when no getCandidates is supplied", () => {
+    const ext = WikiLinkGhostCompletionPlugin.configure();
+    expect(ext.options.getCandidates()).toEqual([]);
+    expect(ext.options.onStateChange).toBeUndefined();
+  });
+});
diff --git a/src/components/editor/extensions/wikiLinkGhostCompletionPlugin.ts b/src/components/editor/extensions/wikiLinkGhostCompletionPlugin.ts
new file mode 100644
index 00000000..3f095dc2
--- /dev/null
+++ b/src/components/editor/extensions/wikiLinkGhostCompletionPlugin.ts
@@ -0,0 +1,595 @@
+import { Extension } from "@tiptap/core";
+import { Plugin, PluginKey, TextSelection } from "@tiptap/pm/state";
+import type { EditorState, Transaction } from "@tiptap/pm/state";
+import type { MarkType, ResolvedPos } from "@tiptap/pm/model";
+import { Decoration, DecorationSet } from "@tiptap/pm/view";
+import type { EditorView } from "@tiptap/pm/view";
+import { wikiLinkSuggestionPluginKey } from "./wikiLinkSuggestionPlugin";
+import { tagSuggestionPluginKey } from "./tagSuggestionPlugin";
+import { slashSuggestionPluginKey } from "./slashSuggestionPlugin";
+
+/**
+ * Lightweight candidate page descriptor consumed by the ghost completion plugin.
+ * ゴースト補完プラグインが必要とする候補ページの最小情報。
+ *
+ * Mirrors the subset of `useWikiLinkCandidates` result shape that the plugin
+ * actually needs: id (for resolving the target page on confirm), title (for
+ * matching + ghost rendering), and an optional `isDeleted` flag so soft-deleted
+ * pages can be skipped at match time.
+ *
+ * `useWikiLinkCandidates` の戻り値のうち本プラグインが必要とする部分集合。
+ * `id`（確定時のターゲット解決）、`title`（マッチ + ゴースト表示）、削除済み
+ * ページを除外するための `isDeleted` を含む。
+ */
+export interface WikiLinkGhostCompletionCandidate {
+  id: string;
+  title: string;
+  isDeleted?: boolean;
+}
+
+/**
+ * Plugin state for the inline ghost completion.
+ * インラインゴースト補完のプラグイン状態。
+ *
+ * - `active`: ゴーストを表示中か / whether the ghost suffix is rendered.
+ * - `range`: 入力中の単語のドキュメント内範囲。確定時に置換に使う /
+ *            range covering the typed word; used as the replacement range on confirm.
+ * - `query`: 入力された接頭辞そのもの（タイプ時の大小区別を保持） /
+ *            the raw prefix the user typed (preserves case).
+ * - `candidate`: 一致した候補ページ（id + 完全な title） /
+ *                matched candidate (id + full title).
+ * - `suffix`: ゴーストとして表示する残り部分。`candidate.title.slice(query.length)` /
+ *             remainder shown as ghost = `candidate.title.slice(query.length)`.
+ * - `decorations`: ゴースト widget を含む装飾セット /
+ *                  decoration set holding the ghost widget.
+ */
+export interface WikiLinkGhostCompletionState {
+  active: boolean;
+  range: { from: number; to: number } | null;
+  query: string;
+  candidate: WikiLinkGhostCompletionCandidate | null;
+  suffix: string;
+  decorations: DecorationSet;
+}
+
+/**
+ * ProseMirror plugin key for {@link WikiLinkGhostCompletionPlugin}.
+ * {@link WikiLinkGhostCompletionPlugin} 用の ProseMirror プラグインキー。
+ */
+export const wikiLinkGhostCompletionPluginKey = new PluginKey<WikiLinkGhostCompletionState>(
+  "wikiLinkGhostCompletion",
+);
+
+/**
+ * Options for {@link WikiLinkGhostCompletionPlugin}.
+ * {@link WikiLinkGhostCompletionPlugin} のオプション。
+ */
+export interface WikiLinkGhostCompletionOptions {
+  /**
+   * Returns the latest candidate list. Called on every transaction (cheap;
+   * a linear prefix scan over the array is performed). The host should keep
+   * a ref to `useWikiLinkCandidates` output and return `ref.current` here so
+   * the editor instance does not have to be re-created when candidates change.
+   *
+   * 最新の候補一覧を返す。トランザクションごとに呼ばれる（線形 prefix scan を
+   * 行う）。ホストは `useWikiLinkCandidates` の戻り値を ref に保持し
+   * `ref.current` を返すことで、候補更新時にエディタを作り直さずに済む。
+   */
+  getCandidates: () => ReadonlyArray<WikiLinkGhostCompletionCandidate>;
+
+  /**
+   * Notifies the host on every state transition. Optional; the plugin handles
+   * confirmation internally so most hosts do not need to observe state.
+   *
+   * 状態遷移ごとに呼ばれる任意のコールバック。確定処理はプラグイン内で完結
+   * するため、ほとんどの呼び出し側は購読不要。
+   */
+  onStateChange?: (state: WikiLinkGhostCompletionState) => void;
+
+  /**
+   * Allow-list of parent node `type.name` values where the ghost may fire.
+   * Defaults to body-text containers (paragraph, heading, list items,
+   * blockquote, table cells). Configurable for tests.
+   *
+   * ゴーストを発火させて良い親ノード名のセット。本文系（段落・見出し・
+   * リスト・引用・テーブル）が既定。テストでの差し替えを可能にする。
+   */
+  allowedNodeTypes?: ReadonlySet<string>;
+}
+
+/**
+ * Default allow-listed parent node types for ghost activation.
+ * ゴースト発火を許容する親ノード名（既定）。
+ *
+ * Issue #930 acceptance criteria call for: paragraph / heading / list items /
+ * blockquote / table cells. We include both `code_block` style node names and
+ * Tiptap's PascalCase variants nowhere — the deny path uses
+ * `parent.type.spec.code` (covers any code-marked node) so only the explicit
+ * body types need to live here. Task items inherit `listItem` for body content
+ * but Tiptap names the node `taskItem`, so list both.
+ *
+ * 受け入れ条件に合わせて、本文系ノードのみを許容する。コード系は
+ * `parent.type.spec.code` の判定で別途排除するため、本セットには含めない。
+ */
+const DEFAULT_ALLOWED_NODE_TYPES: ReadonlySet<string> = new Set([
+  "paragraph",
+  "heading",
+  "listItem",
+  "list_item",
+  "taskItem",
+  "task_item",
+  "blockquote",
+  "tableCell",
+  "table_cell",
+  "tableHeader",
+  "table_header",
+]);
+
+/**
+ * Ancestor node names that disqualify the ghost completion even when the
+ * direct parent passes the allow-list. Mirrors the issue spec: "title /
+ * caption / 本文外". `code_block` is defensive — `parent.type.spec.code` is
+ * the primary guard.
+ *
+ * 直接の親が許容リストを満たしていても、祖先がこれらのいずれかなら不発火。
+ * Issue #930 の「タイトル / キャプション等の本文外」に対応。`code_block` は
+ * 念のための保険（メインの判定は `parent.type.spec.code`）。
+ */
+const EXCLUDED_ANCESTOR_NODE_TYPES: ReadonlySet<string> = new Set([
+  "title",
+  "caption",
+  "codeBlock",
+  "code_block",
+]);
+
+/**
+ * CSS class applied to the ghost widget DOM. Styled in `src/index.css`.
+ * ゴースト widget DOM に付与する CSS クラス。スタイルは `src/index.css`。
+ */
+const GHOST_CLASS = "wiki-link-ghost-completion";
+
+/**
+ * `data-*` attribute used by mouse/touch event delegation to detect a tap on
+ * the ghost suffix. Centralised so tests and CSS hooks stay in sync.
+ *
+ * ゴースト suffix のタップ判定で `closest()` する際の `data-*` 属性。
+ */
+const GHOST_DATA_ATTR = "data-ghost-completion";
+
+/**
+ * Empty (inactive) state factory. Used in every dismissal branch so the shape
+ * is consistent and ProseMirror does not retain a stale decoration set.
+ *
+ * 非アクティブ状態の生成ヘルパー。あらゆる dismiss 経路で同じ形を返すため。
+ */
+function createInactiveState(): WikiLinkGhostCompletionState {
+  return {
+    active: false,
+    range: null,
+    query: "",
+    candidate: null,
+    suffix: "",
+    decorations: DecorationSet.empty,
+  };
+}
+
+/**
+ * Collapse to inactive state without spamming `onStateChange` when the state
+ * was already inactive. Used by every dismissal branch in `apply` to keep the
+ * cyclomatic complexity manageable.
+ *
+ * 非アクティブに倒すヘルパー。前回も非アクティブなら no-op で `onStateChange`
+ * を再通知しない。`apply` の dismissal 分岐を一本化して複雑度を抑える。
+ */
+function deactivate(
+  prev: WikiLinkGhostCompletionState,
+  onStateChange: ((s: WikiLinkGhostCompletionState) => void) | undefined,
+): WikiLinkGhostCompletionState {
+  if (!prev.active) return prev;
+  const next = createInactiveState();
+  onStateChange?.(next);
+  return next;
+}
+
+/**
+ * Reasons that disqualify the cursor context from showing a ghost completion.
+ * Returns the first match, or `null` if the context is OK. Bundles the
+ * boundary-only checks that depend on the schema / selection but not on the
+ * candidate list, so `apply` can fast-bail.
+ *
+ * カーソル状況がゴーストを出すべきでない理由を返す（OK なら `null`）。
+ * 候補一覧に依存しない境界系の判定だけをまとめて、`apply` の早期 return に使う。
+ */
+function findContextSuppression(
+  newState: EditorState,
+  allowedNodeTypes: ReadonlySet<string>,
+): string | null {
+  const { selection, schema } = newState;
+  if (!selection.empty) return "range-selection";
+
+  if (wikiLinkSuggestionPluginKey.getState(newState)?.active) return "wiki-suggestion-active";
+  if (tagSuggestionPluginKey.getState(newState)?.active) return "tag-suggestion-active";
+  // Slash サジェストが開いている間は同時に発火させない。`SlashSuggestionPlugin`
+  // は空白を含むクエリでも active を保つため (`/(^|\\s)\\/([^\\n]*)$/`)、
+  // 「`/cmd Ghost`」のような入力でゴーストと UI が二重に出るのを抑止する。
+  // また Tab を奪われずスラッシュメニュー側のキー操作を維持する。
+  // Mutually exclude with the slash menu: `SlashSuggestionPlugin` stays
+  // active across spaces, so `/cmd Ghost` would otherwise double-fire the
+  // ghost widget and steal Tab from the slash command flow.
+  if (slashSuggestionPluginKey.getState(newState)?.active) return "slash-suggestion-active";
+
+  const { $from } = selection;
+  if ($from.parent.type.spec.code) return "code-block";
+  if (isInsideInlineCode($from, schema.marks)) return "inline-code";
+  if (isInsideExcludedAncestor($from)) return "excluded-ancestor";
+  if (!allowedNodeTypes.has($from.parent.type.name)) return "disallowed-parent";
+
+  const wikiLinkMark = schema.marks.wikiLink;
+  if (wikiLinkMark && wikiLinkMark.isInSet($from.marks())) return "inside-wiki-link";
+
+  return null;
+}
+
+/**
+ * Extract the current typed word from the paragraph-local text before the
+ * caret. Returns `null` when the word is missing, too short, contains a
+ * non-text node placeholder, or starts with a character reserved for another
+ * suggestion flow.
+ *
+ * カーソル直前の段落ローカルテキストから「現在タイプ中の単語」を抽出する。
+ * 単語がない / 2 文字未満 / 非テキストノード混在 / 他フローの先導文字始まり
+ * の場合は `null` を返す。
+ */
+function extractTypedWord($from: ResolvedPos): string | null {
+  const textBefore = $from.parent.textBetween(0, $from.parentOffset, null, "");
+  const match = textBefore.match(/(\S+)$/);
+  if (!match) return null;
+  const word = match[1];
+  if (word.includes("")) return null;
+  if (word.length < 2) return null;
+  const first = word[0];
+  if (first === "[" || first === "]" || first === "#" || first === "@" || first === "/") {
+    return null;
+  }
+  return word;
+}
+
+/**
+ * Find the best prefix-matching candidate for a typed word. Filters out
+ * soft-deleted pages and exact matches (no remainder to show), and breaks
+ * ties by shortest title — the most likely intended completion.
+ *
+ * 入力済み接頭辞に対する最良の候補を返す。削除済み・完全一致を除外し、
+ * 同 prefix の複数候補は最短タイトル優先で選ぶ。
+ */
+function findBestCandidate(
+  typedWord: string,
+  pages: ReadonlyArray<WikiLinkGhostCompletionCandidate>,
+): WikiLinkGhostCompletionCandidate | null {
+  const lowered = typedWord.toLowerCase();
+  let best: WikiLinkGhostCompletionCandidate | null = null;
+  for (const p of pages) {
+    if (p.isDeleted) continue;
+    if (p.title.length <= typedWord.length) continue;
+    if (!p.title.toLowerCase().startsWith(lowered)) continue;
+    if (!best || p.title.length < best.title.length) {
+      best = p;
+    }
+  }
+  return best;
+}
+
+/**
+ * Walk the resolved position to detect whether the caret sits inside an inline
+ * `code` mark. Mirrors the helper used in `tagSuggestionPlugin`.
+ *
+ * カーソル位置がインライン `code` マーク内にあるかを判定する。
+ * `tagSuggestionPlugin` の同名ヘルパーと同じロジック。
+ */
+function isInsideInlineCode($from: ResolvedPos, schemaMarks: Record<string, MarkType>): boolean {
+  const codeMark = schemaMarks.code;
+  if (!codeMark) return false;
+  return Boolean(codeMark.isInSet($from.marks()));
+}
+
+/**
+ * Walk ancestors to detect title/caption/code_block containers that disqualify
+ * the ghost even when the inner block looks permissible.
+ *
+ * 祖先ノードを辿って、ゴーストを出してはいけないコンテナ内（タイトル・
+ * キャプション・コードブロック）かを判定する。
+ */
+function isInsideExcludedAncestor($from: ResolvedPos): boolean {
+  for (let depth = $from.depth; depth >= 0; depth--) {
+    const name = $from.node(depth).type.name;
+    if (EXCLUDED_ANCESTOR_NODE_TYPES.has(name)) return true;
+  }
+  return false;
+}
+
+/**
+ * Builds the DOM node rendered as a ProseMirror widget decoration for the
+ * ghost suffix. Kept as a free function so tests can call it without spinning
+ * up a view, and so the mousedown/touchstart event delegation can target a
+ * stable `[data-ghost-completion="true"]` selector.
+ *
+ * ゴースト suffix を描画する DOM を生成する。テストでビューなしに呼べるよう
+ * 自由関数化し、タップ判定で `[data-ghost-completion="true"]` セレクタが
+ * 安定して効くようにする。
+ */
+export function buildGhostCompletionWidget(
+  suffix: string,
+  candidate: WikiLinkGhostCompletionCandidate,
+): HTMLElement {
+  const span = document.createElement("span");
+  span.className = GHOST_CLASS;
+  span.textContent = suffix;
+  span.setAttribute(GHOST_DATA_ATTR, "true");
+  span.setAttribute("data-target-id", candidate.id);
+  // Prevent the caret from entering the widget — critical for IME and
+  // mobile, where the browser may otherwise place the selection inside.
+  // キャレットが widget 内部に入るのを防ぐ。IME / モバイルで重要。
+  span.setAttribute("contenteditable", "false");
+  return span;
+}
+
+/**
+ * Pure-function transaction builder for the Tab / tap confirmation path.
+ * Replaces the typed prefix with the full candidate title wrapped in a
+ * `wikiLink` mark (`exists: true`, `targetId: candidate.id`), and sends a
+ * `close` meta so the plugin collapses to inactive on the same transaction.
+ *
+ * Tab / タップ確定時のトランザクション生成。入力済み接頭辞を candidate の
+ * 完全タイトルへ差し替え、`wikiLink` マーク（`exists: true`、
+ * `targetId: candidate.id`）を付与する。同じトランザクションで `close`
+ * メタを送ってプラグインを非アクティブに倒す。
+ *
+ * Exported for unit testing — the runtime path goes through
+ * `confirmGhostCompletion`.
+ *
+ * 単体テスト目的でエクスポート。実行時は `confirmGhostCompletion` 経由。
+ */
+export function buildConfirmTransaction(
+  state: EditorState,
+  range: { from: number; to: number },
+  candidate: WikiLinkGhostCompletionCandidate,
+): Transaction | null {
+  const wikiLinkMarkType = state.schema.marks.wikiLink;
+  if (!wikiLinkMarkType) return null;
+  const mark = wikiLinkMarkType.create({
+    title: candidate.title,
+    exists: true,
+    referenced: false,
+    targetId: candidate.id,
+  });
+  const tr = state.tr.replaceWith(range.from, range.to, state.schema.text(candidate.title, [mark]));
+  // Place the cursor right after the inserted title so the user can keep
+  // typing. `replaceWith` maps selection forward but we set it explicitly
+  // for clarity (and to defeat any sticky-mark inheritance).
+  // 挿入直後に caret を置く。マークの sticky inheritance を防ぐためにも明示。
+  const cursorAt = range.from + candidate.title.length;
+  tr.setSelection(TextSelection.create(tr.doc, cursorAt));
+  // Strip stored marks so the user's next keystroke is not styled as a wikiLink.
+  // 次の打鍵が wikiLink マークを引き継がないように storedMarks をクリア。
+  tr.setStoredMarks([]);
+  tr.setMeta(wikiLinkGhostCompletionPluginKey, { close: true });
+  return tr;
+}
+
+/**
+ * Runtime confirmation helper shared by the Tab handler and the
+ * mousedown/touchstart delegation. Dispatches the transaction built by
+ * {@link buildConfirmTransaction} on the editor view.
+ *
+ * Tab ハンドラと mousedown/touchstart 経由のタップ確定で共有する確定処理。
+ * {@link buildConfirmTransaction} で組んだトランザクションを dispatch する。
+ */
+function confirmGhostCompletion(view: EditorView, state: WikiLinkGhostCompletionState): boolean {
+  if (!state.active || !state.range || !state.candidate) return false;
+  const tr = buildConfirmTransaction(view.state, state.range, state.candidate);
+  if (!tr) return false;
+  view.dispatch(tr);
+  return true;
+}
+
+/**
+ * ProseMirror plugin that shows an inline "ghost completion" while the user
+ * types a plain word that prefix-matches an existing page title. Pressing
+ * Tab (desktop) or tapping the chip (mobile) confirms by replacing the typed
+ * prefix with the full title wrapped in a `wikiLink` mark.
+ *
+ * ユーザーが通常のテキストをタイプ中、既存ページタイトルの接頭辞に一致した
+ * 単語があれば、その続きをインラインのゴーストテキストとしてカーソル右に
+ * 表示する ProseMirror プラグイン。Tab（デスクトップ）またはチップタップ
+ * （モバイル）で確定し、入力済み接頭辞をフルタイトルに置換、`wikiLink`
+ * マーク（`exists: true`, `targetId: candidate.id`）を付与する。
+ *
+ * 設計は `wikiLinkSuggestionPlugin`（`[[...]]`）と `tagSuggestionPlugin`
+ * （`#name`）と同形の Tiptap `Extension` + ProseMirror `Plugin`。`onStateChange`
+ * で React 側に状態を流せるが、ポップオーバー UI は不要（widget 自体が UI）
+ * のためホスト側に追加コンポーネントは不要。
+ *
+ * 抑止条件:
+ * - 範囲選択中 / 入力中の単語が 2 文字未満 / IME 変換中（compositionstart で
+ *   即時 close）
+ * - コードブロック (`parent.type.spec.code`) / インラインコード
+ *   (`code` mark) / `title` / `caption` などの本文外
+ * - `wikiLinkSuggestionPlugin` / `tagSuggestionPlugin` / `slashSuggestionPlugin`
+ *   のいずれかが active のとき（`[[`・`#`・`/` 入力が優先）
+ * - 既存 `wikiLink` マーク内
+ * - 単語の先頭が `[`, `]`, `#`, `@`, `/`（他フローへ譲る）
+ * - 候補に prefix 一致するページがない、または完全一致で suffix が空
+ *
+ * 親 issue #924 §4 / 子 issue #930。
+ */
+export const WikiLinkGhostCompletionPlugin = Extension.create<WikiLinkGhostCompletionOptions>({
+  name: "wikiLinkGhostCompletion",
+
+  addOptions() {
+    return {
+      getCandidates: () => [],
+      onStateChange: undefined,
+      allowedNodeTypes: undefined,
+    };
+  },
+
+  addProseMirrorPlugins() {
+    const { onStateChange, getCandidates } = this.options;
+    const allowedNodeTypes = this.options.allowedNodeTypes ?? DEFAULT_ALLOWED_NODE_TYPES;
+
+    return [
+      new Plugin<WikiLinkGhostCompletionState>({
+        key: wikiLinkGhostCompletionPluginKey,
+
+        state: {
+          init() {
+            return createInactiveState();
+          },
+
+          apply(tr, prev, _oldState, newState) {
+            // Explicit close meta (Escape, confirm, compositionstart) wins
+            // over everything else.
+            // 明示的な close メタ（Esc / 確定 / IME 開始）は最優先で適用。
+            if (tr.getMeta(wikiLinkGhostCompletionPluginKey)?.close) {
+              return deactivate(prev, onStateChange);
+            }
+
+            // Context-level disqualifiers (selection / sibling plugins / node
+            // type / existing mark). Bundled in `findContextSuppression` so
+            // this branch list does not balloon the apply cyclomatic complexity.
+            // 文脈レベルの抑止理由（選択 / 他プラグイン active / ノード種別 /
+            // 既存マーク）はまとめてヘルパーで判定する。
+            if (findContextSuppression(newState, allowedNodeTypes)) {
+              return deactivate(prev, onStateChange);
+            }
+
+            const { $from } = newState.selection;
+            const typedWord = extractTypedWord($from);
+            if (!typedWord) {
+              return deactivate(prev, onStateChange);
+            }
+
+            const candidate = findBestCandidate(typedWord, getCandidates());
+            if (!candidate) {
+              return deactivate(prev, onStateChange);
+            }
+
+            const suffix = candidate.title.slice(typedWord.length);
+            if (suffix.length === 0) {
+              return deactivate(prev, onStateChange);
+            }
+
+            const range = { from: $from.pos - typedWord.length, to: $from.pos };
+            const widget = Decoration.widget(
+              range.to,
+              () => buildGhostCompletionWidget(suffix, candidate),
+              {
+                side: 1,
+                ignoreSelection: true,
+                // Stable key so ProseMirror reuses the DOM node when the
+                // suffix is unchanged across rapid transactions → no flicker.
+                // suffix 不変なら ProseMirror が DOM を再利用してフリッカ抑止。
+                key: `ghost:${candidate.id}:${suffix}`,
+              },
+            );
+            const decorations = DecorationSet.create(newState.doc, [widget]);
+
+            const next: WikiLinkGhostCompletionState = {
+              active: true,
+              range,
+              query: typedWord,
+              candidate: {
+                id: candidate.id,
+                title: candidate.title,
+                isDeleted: candidate.isDeleted,
+              },
+              suffix,
+              decorations,
+            };
+            onStateChange?.(next);
+            return next;
+          },
+        },
+
+        props: {
+          decorations(state) {
+            return this.getState(state)?.decorations ?? DecorationSet.empty;
+          },
+
+          handleKeyDown(view: EditorView, event: KeyboardEvent) {
+            const pluginState = wikiLinkGhostCompletionPluginKey.getState(view.state);
+            if (!pluginState?.active) return false;
+
+            // Never interfere with IME composition.
+            // IME 変換中は一切干渉しない。
+            if (view.composing) return false;
+
+            if (event.key === "Escape") {
+              view.dispatch(
+                view.state.tr.setMeta(wikiLinkGhostCompletionPluginKey, { close: true }),
+              );
+              return true;
+            }
+
+            if (
+              event.key === "Tab" &&
+              !event.shiftKey &&
+              !event.metaKey &&
+              !event.ctrlKey &&
+              !event.altKey
+            ) {
+              event.preventDefault();
+              return confirmGhostCompletion(view, pluginState);
+            }
+
+            return false;
+          },
+
+          handleDOMEvents: {
+            // Mobile chip tap / desktop mouse confirmation. Use mousedown
+            // (not click) so we beat ProseMirror's own selection handling.
+            // モバイルのチップタップ・デスクトップのマウス確定。`mousedown`
+            // で ProseMirror の selection 処理より先に確定する。
+            mousedown(view, event) {
+              // `event.target` はテキストノードなど `Element` ではないことも
+              // ある。`closest` を安全に呼ぶため `instanceof Element` で絞る。
+              // Guard against non-Element targets (e.g. text nodes) so we can
+              // safely call `closest` without runtime errors.
+              const target = event.target;
+              if (!(target instanceof Element)) return false;
+              if (!target.closest(`[${GHOST_DATA_ATTR}="true"]`)) return false;
+              const pluginState = wikiLinkGhostCompletionPluginKey.getState(view.state);
+              if (!pluginState?.active) return false;
+              event.preventDefault();
+              return confirmGhostCompletion(view, pluginState);
+            },
+
+            touchstart(view, event) {
+              // mousedown と同じ理由で `instanceof Element` ガード。
+              // Same Element guard as mousedown above.
+              const target = event.target;
+              if (!(target instanceof Element)) return false;
+              if (!target.closest(`[${GHOST_DATA_ATTR}="true"]`)) return false;
+              const pluginState = wikiLinkGhostCompletionPluginKey.getState(view.state);
+              if (!pluginState?.active) return false;
+              event.preventDefault();
+              return confirmGhostCompletion(view, pluginState);
+            },
+
+            // Dismiss the moment IME composition starts. The next apply after
+            // `compositionend` re-evaluates against the committed text.
+            // IME 変換開始時にゴーストを消す。`compositionend` 後は通常通り。
+            compositionstart(view) {
+              const pluginState = wikiLinkGhostCompletionPluginKey.getState(view.state);
+              if (!pluginState?.active) return false;
+              view.dispatch(
+                view.state.tr.setMeta(wikiLinkGhostCompletionPluginKey, { close: true }),
+              );
+              return false;
+            },
+          },
+        },
+      }),
+    ];
+  },
+});
diff --git a/src/components/editor/useWikiLinkInputBar.ts b/src/components/editor/useWikiLinkInputBar.ts
new file mode 100644
index 00000000..26cf8903
--- /dev/null
+++ b/src/components/editor/useWikiLinkInputBar.ts
@@ -0,0 +1,281 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { Editor } from "@tiptap/core";
+import { useWikiLinkCandidates } from "@/hooks/useWikiLinkCandidates";
+import { useCheckGhostLinkReferenced, useWikiLinkExistsChecker } from "@/hooks/usePageQueries";
+import type {
+  SuggestionItem,
+  WikiLinkSuggestionHandle,
+  WikiLinkSuggestionPage,
+} from "./extensions/WikiLinkSuggestion";
+
+/**
+ * `useWikiLinkInputBar` のオプション。`WikiLinkInputBar` から関心事
+ * （状態保持・退避選択範囲・確定処理）を抜き出してテスタブルに保つための
+ * 内部 API。
+ *
+ * Options for {@link useWikiLinkInputBar}. The hook isolates the bar's
+ * stateful concerns (saved selection, async confirm, suggestion plumbing)
+ * from rendering so the component itself stays small and the logic is
+ * unit-testable.
+ */
+export interface UseWikiLinkInputBarOptions {
+  editor: Editor | null;
+  pageId?: string;
+  pageNoteId: string | null;
+}
+
+/**
+ * `useWikiLinkInputBar` の戻り値。`WikiLinkInputBar` が描画と DOM 配線に
+ * 必要な値・ハンドラだけを返す（内部 ref は隠す）。
+ *
+ * Return shape of {@link useWikiLinkInputBar}. Limited to what the
+ * rendering component needs — internal refs (saved selection, re-entrancy
+ * guard) stay encapsulated inside the hook.
+ */
+export interface UseWikiLinkInputBarResult {
+  value: string;
+  setValue: (next: string) => void;
+  pages: WikiLinkSuggestionPage[];
+  showSuggestions: boolean;
+  suggestionRef: React.MutableRefObject<WikiLinkSuggestionHandle | null>;
+  handleFocus: () => void;
+  handleBlur: () => void;
+  handleKeyDown: (event: React.KeyboardEvent<HTMLInputElement>) => void;
+  handleSuggestionSelect: (item: SuggestionItem) => void;
+  handleSuggestionClose: () => void;
+}
+
+/**
+ * 退避するエディタ選択範囲。バーをフォーカスする直前の状態を覚えておき、
+ * 確定時にその位置へ Wiki Link を挿入する。
+ *
+ * Saved editor selection used to insert the link back at the cursor the
+ * user left when they jumped into the bar.
+ */
+interface SavedSelection {
+  from: number;
+  to: number;
+}
+
+/**
+ * 入力バーから WikiLink を挿入する共通処理。`existing` 経路は候補側の
+ * `targetId` をそのまま使う。`ghost` 経路は `checkExistence` で完全一致を
+ * もう一度引いて、当たれば既存リンクへ自動フォールバックする
+ * （issue #926 受け入れ条件）。
+ *
+ * Shared insertion path used by both the standalone-Enter and the
+ * suggestion-click flows. The existing branch trusts the resolved
+ * `targetId` from the candidate; the ghost branch re-runs `checkExistence`
+ * so an exact-match still falls back to the existing link
+ * (issue #926 acceptance criterion).
+ */
+async function buildLinkAttrs(
+  trimmed: string,
+  forceExists: boolean | null,
+  forceTargetId: string | null,
+  pageId: string | undefined,
+  checkExistence: ReturnType<typeof useWikiLinkExistsChecker>["checkExistence"],
+  checkReferenced: ReturnType<typeof useCheckGhostLinkReferenced>["checkReferenced"],
+): Promise<{ exists: boolean; referenced: boolean; targetId: string | null }> {
+  if (forceExists === true) {
+    return { exists: true, referenced: false, targetId: forceTargetId };
+  }
+  const { pageTitles, referencedTitles, pageTitleToId } = await checkExistence([trimmed], pageId);
+  const normalized = trimmed.toLowerCase();
+  const exists = pageTitles.has(normalized);
+  const targetId = exists ? (pageTitleToId.get(normalized) ?? null) : null;
+  let referenced = !exists && referencedTitles.has(normalized);
+  if (!exists && !referenced) {
+    // `referencedTitles` で拾えなかった ghost も `ghost_links` をもう一度参照
+    // して、他ページからの参照があれば `referenced=true` を立てる。
+    // Double-check the ghost branch against `ghost_links` to mirror the
+    // in-body suggestion flow in `useSuggestionEffects`.
+    referenced = await checkReferenced(trimmed, pageId);
+  }
+  return { exists, referenced, targetId };
+}
+
+/**
+ * `WikiLinkInputBar` の状態と確定処理を担うフック。レンダリング層から
+ * 状態管理を切り出し、`max-lines-per-function` 制約に収めるための分離。
+ *
+ * State + confirm hook for {@link WikiLinkInputBar}. Splits the stateful
+ * core out of the rendering component so the FC stays small enough to
+ * satisfy the project's `max-lines-per-function` rule and the logic is
+ * unit-testable in isolation.
+ */
+export function useWikiLinkInputBar({
+  editor,
+  pageId,
+  pageNoteId,
+}: UseWikiLinkInputBarOptions): UseWikiLinkInputBarResult {
+  const [value, setValue] = useState("");
+  const [isFocused, setIsFocused] = useState(false);
+  const savedSelectionRef = useRef<SavedSelection | null>(null);
+  const suggestionRef = useRef<WikiLinkSuggestionHandle | null>(null);
+  // 確定処理中フラグ。Promise 中に二重 Enter / クリックが入っても 1 回しか
+  // 挿入が走らないようにする。
+  // Re-entrancy guard so a second Enter or click during the async confirm
+  // does not trigger a duplicate insertion.
+  const isConfirmingRef = useRef(false);
+
+  const { pages } = useWikiLinkCandidates(pageNoteId);
+  // ノートスコープでは `useWikiLinkExistsChecker` が `notePages` 無しに呼ば
+  // れると意図的に空の集合を返し、Enter フォールバックが既存ページを解決
+  // できずゴーストを挿入してしまう（Codex P1, PR #934）。サジェスト用に
+  // 既に取得済みの候補ページを `notePages` としてそのまま流し込み、同じ
+  // データソースで完全一致判定できるようにする。`useWikiLinkStatusSync`
+  // と同じ流儀。個人スコープでは未指定のまま渡し、checker 側の
+  // `repo.getPagesSummary(userId)` 経路を維持する。
+  //
+  // In note scope `useWikiLinkExistsChecker` returns empty sets when
+  // `notePages` is missing, causing the bar's exact-match fallback to
+  // never resolve existing note-scope pages and always insert a ghost
+  // (Codex P1, PR #934). Reuse the suggestion candidates we already
+  // fetched here so the checker has the same data — mirrors
+  // `useWikiLinkStatusSync`. Personal scope stays unchanged: the checker
+  // ignores `notePages` and falls back to `repo.getPagesSummary(userId)`.
+  const { checkExistence } = useWikiLinkExistsChecker({
+    pageNoteId,
+    notePages: pageNoteId !== null ? pages : undefined,
+  });
+  const { checkReferenced } = useCheckGhostLinkReferenced();
+
+  const handleFocus = useCallback(() => {
+    setIsFocused(true);
+    if (editor) {
+      const { from, to } = editor.state.selection;
+      savedSelectionRef.current = { from, to };
+    }
+  }, [editor]);
+
+  const handleBlur = useCallback(() => {
+    setIsFocused(false);
+  }, []);
+
+  const insertLink = useCallback(
+    async (title: string, forceExists: boolean | null, forceTargetId: string | null) => {
+      if (!editor) return;
+      if (isConfirmingRef.current) return;
+      const trimmed = title.trim();
+      if (!trimmed) return;
+
+      isConfirmingRef.current = true;
+      try {
+        const savedFrom = savedSelectionRef.current?.from ?? editor.state.selection.from;
+        const { exists, referenced, targetId } = await buildLinkAttrs(
+          trimmed,
+          forceExists,
+          forceTargetId,
+          pageId,
+          checkExistence,
+          checkReferenced,
+        );
+
+        editor
+          .chain()
+          .focus()
+          .insertContentAt(savedFrom, [
+            {
+              type: "text",
+              marks: [
+                {
+                  type: "wikiLink",
+                  attrs: { title: trimmed, exists, referenced, targetId },
+                },
+              ],
+              text: `[[${trimmed}]]`,
+            },
+          ])
+          .run();
+      } finally {
+        isConfirmingRef.current = false;
+        setValue("");
+        savedSelectionRef.current = null;
+      }
+    },
+    [editor, pageId, checkExistence, checkReferenced],
+  );
+
+  const handleSuggestionSelect = useCallback(
+    (item: SuggestionItem) => {
+      if (item.exists) {
+        void insertLink(item.title, true, item.id);
+      } else {
+        // 「+ 新規作成」エントリ。完全一致の自動フォールバックは
+        // `buildLinkAttrs` 側に任せる。
+        // Synthetic "+ create" row; let `buildLinkAttrs` re-run the
+        // exact-match fallback in case the candidate list is stale.
+        void insertLink(item.title, null, null);
+      }
+    },
+    [insertLink],
+  );
+
+  const handleSuggestionClose = useCallback(() => {
+    setIsFocused(false);
+  }, []);
+
+  const handleKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLInputElement>) => {
+      // Escape は常にバー側で処理する。サジェスト側に渡してしまうと入力値が
+      // 残るため、明示的にクリア + エディタへフォーカスを戻す。
+      // Always handle Escape at the bar level — delegating to the
+      // suggestion would only fire `onClose` and leave the input value
+      // behind, which feels broken.
+      if (event.key === "Escape") {
+        event.preventDefault();
+        setValue("");
+        savedSelectionRef.current = null;
+        editor?.commands.focus();
+        return;
+      }
+
+      // ↑↓ / Enter はサジェスト UI に委譲する。サジェストが消費した場合は
+      // 重複挿入を防ぐためバーの Enter 処理は走らせない。
+      // Delegate ArrowUp / ArrowDown / Enter to the shared suggestion
+      // handle; skip the bar's Enter fallback when the suggestion already
+      // confirmed (avoids a double insertion).
+      const handle = suggestionRef.current;
+      if (handle) {
+        const handled = handle.onKeyDown(event.nativeEvent);
+        if (handled) {
+          event.preventDefault();
+          event.stopPropagation();
+          return;
+        }
+      }
+
+      if (event.key === "Enter") {
+        event.preventDefault();
+        const trimmed = value.trim();
+        if (!trimmed) return;
+        void insertLink(trimmed, null, null);
+      }
+    },
+    [editor, insertLink, value],
+  );
+
+  // editor が外れたタイミング（読み取り専用切替・unmount 前）で残った状態を
+  // 掃除する。保存していた選択範囲は無効なので破棄する。
+  // Clean up the saved selection when the editor unmounts or becomes
+  // unavailable — the position is no longer valid.
+  useEffect(() => {
+    if (!editor) {
+      savedSelectionRef.current = null;
+    }
+  }, [editor]);
+
+  return {
+    value,
+    setValue,
+    pages,
+    showSuggestions: isFocused && value.trim().length > 0,
+    suggestionRef,
+    handleFocus,
+    handleBlur,
+    handleKeyDown,
+    handleSuggestionSelect,
+    handleSuggestionClose,
+  };
+}
diff --git a/src/components/note/PageEditorContent.tsx b/src/components/note/PageEditorContent.tsx
index 242885a6..168db918 100644
--- a/src/components/note/PageEditorContent.tsx
+++ b/src/components/note/PageEditorContent.tsx
@@ -3,6 +3,7 @@ import type { MutableRefObject } from "react";
 import TiptapEditor from "@/components/editor/TiptapEditor";
 import type { ContentError } from "@/components/editor/TiptapEditor/useContentSanitizer";
 import type { CollaborationConfig } from "@/components/editor/TiptapEditor/types";
+import type { PageActionHubHandle } from "@/components/editor/PageActionHub/types";
 import { SourceUrlBadge } from "@/components/editor/SourceUrlBadge";
 import { WikiGeneratorButton } from "@/components/editor/WikiGeneratorButton";
 import { LinkedPagesSection } from "@/components/page/LinkedPagesSection";
@@ -101,6 +102,13 @@ interface PageEditorContentProps {
    * Ref to insert content at the editor's cursor. Forwarded to TiptapEditor.
    */
   insertAtCursorRef?: MutableRefObject<((content: unknown) => boolean) | null>;
+  /**
+   * `PageActionHub` を親 (NotePageView の FAB) から開閉するための ref。
+   * TiptapEditor に透過的に渡す。
+   * Ref the NotePageView FAB uses to open/close the PageActionHub.
+   * Forwarded to TiptapEditor.
+   */
+  pageActionHubRef?: MutableRefObject<PageActionHubHandle | null>;
   /**
    * 編集中ページの noteId。WikiLink 候補・解決のスコープを決定する。
    * `null` は個人ページ、文字列値はそのノートに所属するノートネイティブ
@@ -111,6 +119,17 @@ interface PageEditorContentProps {
    * same note. See issue #713 Phase 4.
    */
   pageNoteId?: string | null;
+  /**
+   * 画面下部の Wiki Link 入力バー右隣に並べるアクション（例: PageActionHub FAB）。
+   * Trailing control rendered beside the floating Wiki Link input bar.
+   */
+  bottomBarTrailingAction?: React.ReactNode;
+  /**
+   * Wiki Compose 画面 (`/compose`) への遷移先 URL。指定すると `WikiGeneratorButton`
+   * が Compose 画面に遷移する経路を取り、本文ありでも表示される (#950 U2)。
+   * Pass-through to the WikiGeneratorButton's `composeHref`.
+   */
+  wikiComposeHref?: string;
 }
 
 /**
@@ -141,7 +160,10 @@ export const PageEditorContent: React.FC<PageEditorContentProps> = ({
   wikiContentForCollab = null,
   onWikiContentApplied,
   insertAtCursorRef,
+  pageActionHubRef,
   pageNoteId = null,
+  bottomBarTrailingAction,
+  wikiComposeHref,
 }) => {
   const isEditorReadOnly = isReadOnly ?? isWikiGenerating;
   const hasContent = useMemo(() => isContentNotEmpty(content), [content]);
@@ -183,13 +205,25 @@ export const PageEditorContent: React.FC<PageEditorContentProps> = ({
               onEnterMoveToContent={!isEditorReadOnly ? focusContent : undefined}
             />
           </div>
-          {wikiStatus && onGenerateWiki && (
+          {/* Wiki 生成ボタンの表示条件:
+              - 旧経路: `wikiStatus` + `onGenerateWiki` 両方ある場合（インライン生成）
+              - 新経路: `wikiComposeHref` がある場合（Compose 画面に遷移、#950）
+              いずれも `WikiGeneratorButton` 自身がタイトル / 本文条件で更に
+              フィルタする。
+
+              Show the Wiki generation button when either:
+              - legacy: both `wikiStatus` + `onGenerateWiki` are supplied
+                (inline generation), or
+              - new: `wikiComposeHref` is supplied (navigate to Compose, #950).
+              `WikiGeneratorButton` itself filters on title/content state. */}
+          {((wikiStatus && onGenerateWiki) || wikiComposeHref) && (
             <div className="shrink-0">
               <WikiGeneratorButton
                 title={title}
                 hasContent={hasContent}
-                onGenerate={onGenerateWiki}
-                status={wikiStatus}
+                onGenerate={onGenerateWiki ?? (() => undefined)}
+                status={wikiStatus ?? "idle"}
+                composeHref={wikiComposeHref}
               />
             </div>
           )}
@@ -217,11 +251,14 @@ export const PageEditorContent: React.FC<PageEditorContentProps> = ({
                 collaborationConfig={collaborationConfig}
                 focusContentRef={contentFocusRef}
                 insertAtCursorRef={insertAtCursorRef}
+                pageActionHubRef={pageActionHubRef}
                 initialContent={initialContent}
                 onInitialContentApplied={onInitialContentApplied}
                 wikiContentForCollab={wikiContentForCollab ?? undefined}
                 onWikiContentApplied={onWikiContentApplied}
                 pageNoteId={pageNoteId}
+                wikiComposeHref={wikiComposeHref}
+                bottomBarTrailingAction={bottomBarTrailingAction}
               />
             </>
           )}
diff --git a/src/components/settings/AISettingsForm.tsx b/src/components/settings/AISettingsForm.tsx
index d9ea38eb..019dc6f3 100644
--- a/src/components/settings/AISettingsForm.tsx
+++ b/src/components/settings/AISettingsForm.tsx
@@ -22,6 +22,7 @@ import { ProviderSelector } from "./ProviderSelector";
 import { SectionSaveStatus } from "./SectionSaveStatus";
 import { ClaudeCodePrerequisites } from "./ClaudeCodePrerequisites";
 import { McpServerSettings } from "./McpServerSettings";
+import { ComposeByokCredentialsSection } from "./ComposeByokCredentialsSection";
 import { getProviderById, type AIInteractionMode } from "@/types/ai";
 import { isTauriDesktop } from "@/lib/platform";
 import { useTranslation } from "react-i18next";
@@ -141,6 +142,11 @@ export const AISettingsForm: React.FC<AISettingsFormProps> = ({ embedded = false
 
         {isClaudeCode && <ClaudeCodePrerequisites />}
         {isClaudeCode && <McpServerSettings />}
+
+        <div className="border-border space-y-3 border-t pt-6">
+          <h3 className="text-sm font-medium">{t("wikiCompose.credentials.title")}</h3>
+          <ComposeByokCredentialsSection />
+        </div>
       </CardContent>
 
       <CardFooter className="flex justify-between">
diff --git a/src/components/settings/ComposeByokCredentialsSection.tsx b/src/components/settings/ComposeByokCredentialsSection.tsx
new file mode 100644
index 00000000..2bdcc6bd
--- /dev/null
+++ b/src/components/settings/ComposeByokCredentialsSection.tsx
@@ -0,0 +1,188 @@
+/**
+ * Settings section to register server-side BYOK API keys (#951).
+ * 設定画面: Wiki Compose BYOK 用 API キー登録。
+ */
+import React, { useCallback, useEffect, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { Eye, EyeOff, Loader2 } from "lucide-react";
+import { Button, Input, Label, Alert, AlertDescription } from "@zedi/ui";
+import {
+  deleteUserAiCredential,
+  fetchUserAiCredentialsStatus,
+  upsertUserAiCredential,
+  type UserAiCredentialProvider,
+} from "@/lib/userAiCredentials";
+
+const PROVIDERS: readonly { id: UserAiCredentialProvider; labelKey: string }[] = [
+  { id: "anthropic", labelKey: "wikiCompose.credentials.anthropic" },
+  { id: "openai", labelKey: "wikiCompose.credentials.openai" },
+  { id: "google", labelKey: "wikiCompose.credentials.google" },
+];
+
+/**
+ * Per-provider API key inputs backed by `/api/user/ai-credentials`.
+ */
+export const ComposeByokCredentialsSection: React.FC = () => {
+  const { t } = useTranslation();
+  const [loading, setLoading] = useState(true);
+  const [storageEnabled, setStorageEnabled] = useState(false);
+  const [configured, setConfigured] = useState<Record<UserAiCredentialProvider, boolean>>({
+    anthropic: false,
+    openai: false,
+    google: false,
+  });
+  const [draftKeys, setDraftKeys] = useState<Record<UserAiCredentialProvider, string>>({
+    anthropic: "",
+    openai: "",
+    google: "",
+  });
+  const [showKey, setShowKey] = useState<Record<UserAiCredentialProvider, boolean>>({
+    anthropic: false,
+    openai: false,
+    google: false,
+  });
+  const [saving, setSaving] = useState<UserAiCredentialProvider | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const reload = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const status = await fetchUserAiCredentialsStatus();
+      setStorageEnabled(status.storageEnabled);
+      const next: Record<UserAiCredentialProvider, boolean> = {
+        anthropic: false,
+        openai: false,
+        google: false,
+      };
+      for (const p of status.providers) {
+        next[p.provider] = p.configured;
+      }
+      setConfigured(next);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    void reload();
+  }, [reload]);
+
+  const handleSave = async (provider: UserAiCredentialProvider) => {
+    setSaving(provider);
+    setError(null);
+    try {
+      await upsertUserAiCredential(provider, draftKeys[provider].trim());
+      setDraftKeys((prev) => ({ ...prev, [provider]: "" }));
+      await reload();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setSaving(null);
+    }
+  };
+
+  const handleRemove = async (provider: UserAiCredentialProvider) => {
+    setSaving(provider);
+    setError(null);
+    try {
+      await deleteUserAiCredential(provider);
+      await reload();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setSaving(null);
+    }
+  };
+
+  if (loading) {
+    return (
+      <div className="flex justify-center py-6">
+        <Loader2 className="text-muted-foreground h-6 w-6 animate-spin" />
+      </div>
+    );
+  }
+
+  if (!storageEnabled) {
+    return (
+      <Alert>
+        <AlertDescription>{t("wikiCompose.credentials.storageDisabled")}</AlertDescription>
+      </Alert>
+    );
+  }
+
+  return (
+    <div className="space-y-6" data-testid="compose-byok-credentials">
+      <p className="text-muted-foreground text-sm">{t("wikiCompose.credentials.description")}</p>
+      {error && (
+        <Alert variant="destructive">
+          <AlertDescription>{error}</AlertDescription>
+        </Alert>
+      )}
+      {PROVIDERS.map(({ id, labelKey }) => (
+        <div key={id} className="space-y-2 rounded-lg border p-4">
+          <div className="flex items-center justify-between gap-2">
+            <Label htmlFor={`byok-${id}`}>{t(labelKey)}</Label>
+            {configured[id] && (
+              <span className="text-muted-foreground text-xs">
+                {t("wikiCompose.credentials.configured")}
+              </span>
+            )}
+          </div>
+          <div className="relative">
+            <Input
+              id={`byok-${id}`}
+              type={showKey[id] ? "text" : "password"}
+              value={draftKeys[id]}
+              onChange={(e) => setDraftKeys((prev) => ({ ...prev, [id]: e.target.value }))}
+              placeholder={t("wikiCompose.credentials.placeholder")}
+              disabled={saving === id}
+              className="pr-10"
+            />
+            <Button
+              type="button"
+              variant="ghost"
+              size="icon"
+              className="absolute top-0 right-0 h-full px-3 hover:bg-transparent"
+              onClick={() => setShowKey((prev) => ({ ...prev, [id]: !prev[id] }))}
+              disabled={saving === id}
+              aria-label={showKey[id] ? t("aiSettings.hideApiKey") : t("aiSettings.showApiKey")}
+            >
+              {showKey[id] ? (
+                <EyeOff className="text-muted-foreground h-4 w-4" />
+              ) : (
+                <Eye className="text-muted-foreground h-4 w-4" />
+              )}
+            </Button>
+          </div>
+          <div className="flex flex-wrap gap-2">
+            <Button
+              type="button"
+              size="sm"
+              onClick={() => void handleSave(id)}
+              disabled={saving === id || !draftKeys[id].trim()}
+            >
+              {saving === id ? <Loader2 className="h-4 w-4 animate-spin" /> : t("common.save")}
+            </Button>
+            {configured[id] && (
+              <Button
+                type="button"
+                size="sm"
+                variant="outline"
+                onClick={() => void handleRemove(id)}
+                disabled={saving === id}
+              >
+                {t("wikiCompose.credentials.remove")}
+              </Button>
+            )}
+          </div>
+        </div>
+      ))}
+      <p className="text-muted-foreground text-xs">
+        {t("wikiCompose.credentials.localStorageNote")}
+      </p>
+    </div>
+  );
+};
diff --git a/src/components/wikiCompose/ActivitySection.tsx b/src/components/wikiCompose/ActivitySection.tsx
new file mode 100644
index 00000000..739efe13
--- /dev/null
+++ b/src/components/wikiCompose/ActivitySection.tsx
@@ -0,0 +1,89 @@
+/**
+ * `ActivitySection` — agent activity timeline (#950).
+ *
+ * Compose 右ペイン下部のアクティビティタイムライン。SSE で来るツール呼び出し /
+ * 調査イテレーション / フェーズ遷移を時系列で表示し、エージェントが何を
+ * しているかを可視化する。Compose 中盤の「無音」を避けるための重要な UI。
+ *
+ * Read-only timeline. Newest entries at the bottom. Auto-scrolls into view
+ * when new rows arrive.
+ */
+import React, { useEffect, useRef } from "react";
+import { ScrollArea } from "@zedi/ui";
+import { cn } from "@zedi/ui";
+import { Check, Circle, AlertCircle, Loader2 } from "lucide-react";
+import type { ComposeActivity } from "@/hooks/useWikiComposeSession";
+
+export interface ActivitySectionProps {
+  activity: ComposeActivity[];
+  isStreaming: boolean;
+}
+
+function Icon({ status }: { status: ComposeActivity["status"] }) {
+  switch (status) {
+    case "started":
+      return <Loader2 className="h-3 w-3 animate-spin text-blue-600 dark:text-blue-400" />;
+    case "completed":
+      return <Check className="h-3 w-3 text-emerald-600 dark:text-emerald-400" />;
+    case "error":
+      return <AlertCircle className="h-3 w-3 text-red-600 dark:text-red-400" />;
+    default:
+      return <Circle className="text-muted-foreground h-3 w-3" />;
+  }
+}
+
+/** Compact activity timeline. */
+export const ActivitySection: React.FC<ActivitySectionProps> = ({ activity, isStreaming }) => {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  // Scroll to the bottom on every new entry so the user sees the latest work.
+  // 新規イベント到着時に末尾までスクロール。
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    el.scrollTop = el.scrollHeight;
+  }, [activity]);
+
+  return (
+    <section data-testid="activity-section" className="border-border border-t pt-3">
+      <header className="mb-2 flex items-center justify-between">
+        <h3 className="text-muted-foreground text-xs font-semibold tracking-wide uppercase">
+          Activity
+        </h3>
+        {isStreaming ? (
+          <span className="text-muted-foreground flex items-center gap-1 text-[10px]">
+            <Loader2 className="h-3 w-3 animate-spin" /> live
+          </span>
+        ) : null}
+      </header>
+      <ScrollArea className="max-h-48">
+        <div ref={containerRef} className="space-y-1 pr-2">
+          {activity.length === 0 ? (
+            <p className="text-muted-foreground text-xs italic">No activity yet.</p>
+          ) : (
+            activity.map((entry) => (
+              <div
+                key={entry.id}
+                data-testid={`activity-row-${entry.id}`}
+                className={cn(
+                  "flex items-start gap-2 text-xs",
+                  entry.status === "error" && "text-red-600 dark:text-red-400",
+                )}
+              >
+                <div className="mt-0.5 shrink-0">
+                  <Icon status={entry.status} />
+                </div>
+                <div className="min-w-0 flex-1">
+                  <div className="truncate">{entry.label}</div>
+                  {entry.detail ? (
+                    <div className="text-muted-foreground truncate text-[11px]">{entry.detail}</div>
+                  ) : null}
+                </div>
+              </div>
+            ))
+          )}
+        </div>
+      </ScrollArea>
+    </section>
+  );
+};
diff --git a/src/components/wikiCompose/BriefQuestionCard.tsx b/src/components/wikiCompose/BriefQuestionCard.tsx
new file mode 100644
index 00000000..f2da3a0b
--- /dev/null
+++ b/src/components/wikiCompose/BriefQuestionCard.tsx
@@ -0,0 +1,102 @@
+/**
+ * `BriefQuestionCard` — one structured Brief question (#950).
+ *
+ * Brief フェーズで Orchestrator が生成した 1 件の質問カード。チップ式選択肢 +
+ * 任意のフリーテキストを統合した入出力 UI。`required` の質問は未回答だと
+ * `Submit` ボタンが無効化される（親側で判定）。
+ *
+ * Renders one question with optional answer chips and a free-text addendum
+ * box. Multi-select is supported; the parent owns the answer state.
+ */
+import React from "react";
+import { cn } from "@zedi/ui";
+import { Badge, Card, CardContent, CardHeader, CardTitle, Input } from "@zedi/ui";
+import type { BriefAnswer, BriefQuestion } from "@/lib/wikiCompose/types";
+
+export interface BriefQuestionCardProps {
+  question: BriefQuestion;
+  answer: BriefAnswer | null;
+  onChange: (next: BriefAnswer) => void;
+}
+
+/** Toggles a single option id in the current selection. */
+function toggleOption(selected: string[], optionId: string): string[] {
+  return selected.includes(optionId)
+    ? selected.filter((id) => id !== optionId)
+    : [...selected, optionId];
+}
+
+/** Render one Brief question card. */
+export const BriefQuestionCard: React.FC<BriefQuestionCardProps> = ({
+  question,
+  answer,
+  onChange,
+}) => {
+  const selected = answer?.selectedOptionIds ?? [];
+  const freeText = answer?.freeText ?? "";
+
+  return (
+    <Card data-testid={`brief-card-${question.id}`}>
+      <CardHeader className="pb-3">
+        <CardTitle className="flex items-start gap-2 text-sm leading-snug font-medium">
+          <span className="flex-1">{question.question}</span>
+          {question.required ? (
+            <Badge variant="outline" className="shrink-0 text-[10px] uppercase">
+              required
+            </Badge>
+          ) : null}
+        </CardTitle>
+        {question.rationale ? (
+          <p className="text-muted-foreground text-xs">{question.rationale}</p>
+        ) : null}
+      </CardHeader>
+      <CardContent className="space-y-3">
+        {question.options.length > 0 ? (
+          <div className="flex flex-wrap gap-2" role="group" aria-label="Answer options">
+            {question.options.map((option) => {
+              const active = selected.includes(option.id);
+              return (
+                <button
+                  type="button"
+                  key={option.id}
+                  data-testid={`brief-option-${option.id}`}
+                  aria-pressed={active}
+                  onClick={() =>
+                    onChange({
+                      questionId: question.id,
+                      selectedOptionIds: toggleOption(selected, option.id),
+                      freeText: freeText || undefined,
+                    })
+                  }
+                  className={cn(
+                    "rounded-full border px-3 py-1.5 text-xs transition",
+                    active
+                      ? "bg-primary text-primary-foreground border-primary"
+                      : "bg-background hover:bg-muted border-border text-foreground",
+                  )}
+                  title={option.hint}
+                >
+                  {option.label}
+                </button>
+              );
+            })}
+          </div>
+        ) : null}
+
+        <Input
+          type="text"
+          placeholder={question.options.length > 0 ? "Add a note (optional)…" : "Type your answer…"}
+          data-testid={`brief-freetext-${question.id}`}
+          value={freeText}
+          onChange={(e) =>
+            onChange({
+              questionId: question.id,
+              selectedOptionIds: selected,
+              freeText: e.target.value || undefined,
+            })
+          }
+        />
+      </CardContent>
+    </Card>
+  );
+};
diff --git a/src/components/wikiCompose/ComposeBackendSelector.tsx b/src/components/wikiCompose/ComposeBackendSelector.tsx
new file mode 100644
index 00000000..814c58d5
--- /dev/null
+++ b/src/components/wikiCompose/ComposeBackendSelector.tsx
@@ -0,0 +1,120 @@
+/**
+ * Execution backend picker for Wiki Compose (#951).
+ * Wiki Compose 用の実行 backend 選択 UI。
+ */
+import React, { useEffect, useMemo, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { Label, RadioGroup, RadioGroupItem } from "@zedi/ui";
+import {
+  COMPOSE_BACKEND_META,
+  type ComposeExecutionBackend,
+  usesZediCu,
+} from "@/lib/wikiCompose/backends";
+import {
+  fetchUserAiCredentialsStatus,
+  type UserAiCredentialProvider,
+} from "@/lib/userAiCredentials";
+
+export interface ComposeBackendSelectorProps {
+  value: ComposeExecutionBackend;
+  onChange: (backend: ComposeExecutionBackend) => void;
+  disabled?: boolean;
+}
+
+/**
+ * Renders backend options; grays out BYOK choices without a stored credential.
+ */
+export const ComposeBackendSelector: React.FC<ComposeBackendSelectorProps> = ({
+  value,
+  onChange,
+  disabled = false,
+}) => {
+  const { t } = useTranslation();
+  const [configuredProviders, setConfiguredProviders] = useState<Set<UserAiCredentialProvider>>(
+    new Set(),
+  );
+  const [storageEnabled, setStorageEnabled] = useState(false);
+
+  useEffect(() => {
+    let cancelled = false;
+    void fetchUserAiCredentialsStatus()
+      .then((status) => {
+        if (cancelled) return;
+        setStorageEnabled(status.storageEnabled);
+        const set = new Set<UserAiCredentialProvider>();
+        for (const p of status.providers) {
+          if (p.configured) set.add(p.provider);
+        }
+        setConfiguredProviders(set);
+      })
+      .catch(() => {
+        if (!cancelled) {
+          setStorageEnabled(false);
+          setConfiguredProviders(new Set());
+        }
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const availability = useMemo(() => {
+    const map = new Map<ComposeExecutionBackend, boolean>();
+    for (const meta of COMPOSE_BACKEND_META) {
+      if (meta.provider === null) {
+        map.set(meta.id, true);
+      } else {
+        map.set(meta.id, storageEnabled && configuredProviders.has(meta.provider));
+      }
+    }
+    return map;
+  }, [configuredProviders, storageEnabled]);
+
+  return (
+    <div className="space-y-2" data-testid="compose-backend-selector">
+      <Label>{t("wikiCompose.backend.label")}</Label>
+      <RadioGroup
+        value={value}
+        onValueChange={(v) => onChange(v as ComposeExecutionBackend)}
+        className="flex flex-col gap-2"
+        disabled={disabled}
+      >
+        {COMPOSE_BACKEND_META.map((meta) => {
+          const available = availability.get(meta.id) ?? false;
+          const itemDisabled = disabled || !available;
+          return (
+            <div
+              key={meta.id}
+              className={`flex items-start gap-2 rounded-md border p-3 ${
+                itemDisabled ? "opacity-50" : ""
+              }`}
+            >
+              <RadioGroupItem
+                value={meta.id}
+                id={`compose-backend-${meta.id}`}
+                disabled={itemDisabled}
+              />
+              <label
+                htmlFor={`compose-backend-${meta.id}`}
+                className={`flex flex-1 cursor-pointer flex-col gap-0.5 ${itemDisabled ? "cursor-not-allowed" : ""}`}
+              >
+                <span className="text-sm font-medium">{t(meta.labelKey)}</span>
+                <span className="text-muted-foreground text-xs">{t(meta.descriptionKey)}</span>
+                {usesZediCu(meta.id) && (
+                  <span className="text-muted-foreground text-xs">
+                    {t("wikiCompose.backend.usesCu")}
+                  </span>
+                )}
+                {!available && meta.provider !== null && (
+                  <span className="text-destructive text-xs">
+                    {t("wikiCompose.backend.credentialRequired")}
+                  </span>
+                )}
+              </label>
+            </div>
+          );
+        })}
+      </RadioGroup>
+    </div>
+  );
+};
diff --git a/src/components/wikiCompose/ComposePanel.tsx b/src/components/wikiCompose/ComposePanel.tsx
new file mode 100644
index 00000000..6d54d522
--- /dev/null
+++ b/src/components/wikiCompose/ComposePanel.tsx
@@ -0,0 +1,125 @@
+/**
+ * `ComposePanel` — right pane of the Wiki Compose split view (#950).
+ *
+ * 分割画面の右ペイン。`PhaseStepper` (top), Dialogue / Research セクション
+ * (middle), ActivitySection (bottom) を 1 つのスクロール可能カラムに積む。
+ * フェーズに応じて DialogueSection と ResearchSection の表示を出し分ける。
+ *
+ * Stacks the stepper + phase-specific dialogue panel + activity log. The
+ * actual interaction logic lives in each section component; this is just a
+ * layout wrapper.
+ */
+import React from "react";
+import { PhaseStepper } from "./PhaseStepper";
+import { DialogueSection } from "./DialogueSection";
+import { ResearchSection } from "./ResearchSection";
+import { ConflictResolutionSection } from "./ConflictResolutionSection";
+import { ActivitySection } from "./ActivitySection";
+import type {
+  BriefAnswer,
+  BriefQuestion,
+  OutlineSection,
+  PageSnapshot,
+  ResearchBatch,
+  ResearchConflictSummary,
+  ResearchSource,
+} from "@/lib/wikiCompose/types";
+import type { ComposeActivity, ComposePhase } from "@/hooks/useWikiComposeSession";
+
+export interface ComposePanelProps {
+  phase: ComposePhase;
+  isStreaming: boolean;
+
+  briefQuestions: BriefQuestion[];
+  pageSnapshot: PageSnapshot | null;
+
+  latestBatch: ResearchBatch | null;
+  pendingSources: ResearchSource[];
+  approvedSources: ResearchSource[];
+  researchConflictSummary: ResearchConflictSummary | null;
+
+  outlineProposal: OutlineSection[];
+
+  activity: ComposeActivity[];
+
+  onSubmitBrief: (input: {
+    answers: BriefAnswer[];
+    appendToExisting?: boolean;
+    researchMaxIterations?: number;
+  }) => Promise<void>;
+  onSubmitResearchApproval: (input: {
+    approvedSourceIds: string[];
+    rejectedSourceIds?: string[];
+    note?: string;
+  }) => Promise<void>;
+  onSubmitOutline: (input: { sections: OutlineSection[] }) => Promise<void>;
+  onSubmitConflictAck: (input?: { note?: string }) => Promise<void>;
+}
+
+/** Right pane container. */
+export const ComposePanel: React.FC<ComposePanelProps> = (props) => {
+  const {
+    phase,
+    isStreaming,
+    briefQuestions,
+    pageSnapshot,
+    latestBatch,
+    pendingSources,
+    approvedSources,
+    researchConflictSummary,
+    outlineProposal,
+    activity,
+    onSubmitBrief,
+    onSubmitResearchApproval,
+    onSubmitOutline,
+    onSubmitConflictAck,
+  } = props;
+
+  return (
+    <aside
+      data-testid="compose-panel"
+      className="bg-card border-border flex h-full flex-col border-l"
+    >
+      <header className="border-border border-b px-4 py-3">
+        <PhaseStepper phase={phase} />
+      </header>
+
+      <div className="flex-1 space-y-4 overflow-auto px-4 py-4">
+        {/* Phase-specific dialogue: Brief / Structure / Draft. */}
+        <DialogueSection
+          phase={phase}
+          briefQuestions={briefQuestions}
+          pageSnapshot={pageSnapshot}
+          outlineProposal={outlineProposal}
+          isStreaming={isStreaming}
+          onSubmitBrief={onSubmitBrief}
+          onSubmitOutline={onSubmitOutline}
+        />
+
+        {phase === "conflict" && researchConflictSummary ? (
+          <ConflictResolutionSection
+            conflicts={researchConflictSummary}
+            isStreaming={isStreaming}
+            onSubmit={onSubmitConflictAck}
+          />
+        ) : null}
+
+        {/* Research review: visible during research interrupt and as a
+            read-only summary in later phases. */}
+        {phase === "research" ||
+        (phase !== "brief" && phase !== "conflict" && approvedSources.length > 0) ? (
+          <ResearchSection
+            batch={latestBatch}
+            pendingSources={pendingSources}
+            approvedSources={approvedSources}
+            isReadOnly={phase !== "research"}
+            isStreaming={isStreaming}
+            onSubmit={onSubmitResearchApproval}
+          />
+        ) : null}
+
+        <ActivitySection activity={activity} isStreaming={isStreaming} />
+      </div>
+    </aside>
+  );
+};
diff --git a/src/components/wikiCompose/ConflictResolutionSection.tsx b/src/components/wikiCompose/ConflictResolutionSection.tsx
new file mode 100644
index 00000000..44cb5463
--- /dev/null
+++ b/src/components/wikiCompose/ConflictResolutionSection.tsx
@@ -0,0 +1,82 @@
+/**
+ * `ConflictResolutionSection` — P5 research conflict acknowledgment (#953).
+ *
+ * 調査承認で採用・却下が混在したときの確認 UI。承認セットで Structure へ進む。
+ *
+ * Shown when the graph interrupts at `conflict_resolution`. The user
+ * acknowledges and resumes with `{ acknowledged: true }`.
+ */
+import React, { useState } from "react";
+import { Button, Card, CardContent, CardHeader, CardTitle } from "@zedi/ui";
+import { AlertTriangle } from "lucide-react";
+import type { ResearchConflictSummary } from "@/lib/wikiCompose/types";
+
+/**
+ * Props for the conflict acknowledgment panel.
+ * 矛盾解消確認パネルの props。
+ */
+export interface ConflictResolutionSectionProps {
+  conflicts: ResearchConflictSummary;
+  isStreaming: boolean;
+  onSubmit: (input?: { note?: string }) => Promise<void>;
+}
+
+/**
+ * Conflict acknowledgment panel between Research and Structure.
+ * Research と Structure の間で表示する矛盾解消確認パネル。
+ */
+export const ConflictResolutionSection: React.FC<ConflictResolutionSectionProps> = ({
+  conflicts,
+  isStreaming,
+  onSubmit,
+}) => {
+  const [submitting, setSubmitting] = useState(false);
+
+  return (
+    <section data-testid="dialogue-conflict" className="space-y-3">
+      <header className="flex items-center gap-1.5 text-sm font-semibold">
+        <AlertTriangle className="h-4 w-4 text-amber-600" aria-hidden />
+        Resolve conflicts
+      </header>
+      <Card>
+        <CardHeader className="pb-2">
+          <CardTitle className="text-sm">Research conflicts</CardTitle>
+        </CardHeader>
+        <CardContent className="space-y-3 text-xs">
+          <p className="text-muted-foreground">{conflicts.rationale}</p>
+          <div>
+            <p className="font-medium">Approved ({conflicts.approved.length})</p>
+            <ul className="text-muted-foreground mt-1 list-inside list-disc">
+              {conflicts.approved.map((s) => (
+                <li key={s.id}>{s.title}</li>
+              ))}
+            </ul>
+          </div>
+          <div>
+            <p className="font-medium">Rejected ({conflicts.rejected.length})</p>
+            <ul className="text-muted-foreground mt-1 list-inside list-disc">
+              {conflicts.rejected.map((s) => (
+                <li key={s.id}>{s.title}</li>
+              ))}
+            </ul>
+          </div>
+          <Button
+            type="button"
+            size="sm"
+            disabled={isStreaming || submitting}
+            onClick={async () => {
+              setSubmitting(true);
+              try {
+                await onSubmit();
+              } finally {
+                setSubmitting(false);
+              }
+            }}
+          >
+            Continue with approved sources
+          </Button>
+        </CardContent>
+      </Card>
+    </section>
+  );
+};
diff --git a/src/components/wikiCompose/DialogueSection.tsx b/src/components/wikiCompose/DialogueSection.tsx
new file mode 100644
index 00000000..663e0e2c
--- /dev/null
+++ b/src/components/wikiCompose/DialogueSection.tsx
@@ -0,0 +1,238 @@
+/**
+ * `DialogueSection` — Brief / Structure interaction panel (#950).
+ *
+ * Compose 画面右ペインの「対話」セクション。フェーズに応じて Brief の質問カード
+ * 群、Structure のアウトラインエディタ、Draft 中のセクション進捗を出し分ける。
+ * Compose は free-form chat ではないため、各フェーズの UI は専用フォーム形式。
+ *
+ * Pure presentational shell that routes between the BriefQuestionCard list,
+ * OutlineEditor, and the section progress view based on `phase`. Submit
+ * handlers come from the parent (`WikiComposePage` → `useWikiComposeSession`).
+ */
+import React, { useMemo, useState } from "react";
+import { Button, Card, CardContent, CardHeader, CardTitle, Slider } from "@zedi/ui";
+import { Sparkles, RefreshCw, ArrowRight } from "lucide-react";
+import type {
+  BriefAnswer,
+  BriefQuestion,
+  OutlineSection,
+  PageSnapshot,
+} from "@/lib/wikiCompose/types";
+import { BriefQuestionCard } from "./BriefQuestionCard";
+import { OutlineEditor } from "./OutlineEditor";
+import type { ComposePhase } from "@/hooks/useWikiComposeSession";
+
+export interface DialogueSectionProps {
+  phase: ComposePhase;
+  briefQuestions: BriefQuestion[];
+  pageSnapshot: PageSnapshot | null;
+  outlineProposal: OutlineSection[];
+  isStreaming: boolean;
+  /** Brief submission. */
+  onSubmitBrief: (input: {
+    answers: BriefAnswer[];
+    appendToExisting?: boolean;
+    researchMaxIterations?: number;
+  }) => Promise<void>;
+  /** Structure submission. */
+  onSubmitOutline: (input: { sections: OutlineSection[] }) => Promise<void>;
+}
+
+/** Whether all required questions have at least one answer. */
+function allRequiredAnswered(
+  questions: BriefQuestion[],
+  answers: Record<string, BriefAnswer>,
+): boolean {
+  return questions
+    .filter((q) => q.required)
+    .every((q) => {
+      const a = answers[q.id];
+      if (!a) return false;
+      const hasOption = (a.selectedOptionIds ?? []).length > 0;
+      const hasText = Boolean(a.freeText && a.freeText.trim().length > 0);
+      return hasOption || hasText;
+    });
+}
+
+/** Container for Brief / Structure / Draft dialogue UIs. */
+export const DialogueSection: React.FC<DialogueSectionProps> = ({
+  phase,
+  briefQuestions,
+  pageSnapshot,
+  outlineProposal,
+  isStreaming,
+  onSubmitBrief,
+  onSubmitOutline,
+}) => {
+  const [answers, setAnswers] = useState<Record<string, BriefAnswer>>({});
+  const [appendToExisting, setAppendToExisting] = useState<boolean>(
+    Boolean(pageSnapshot?.hasContent),
+  );
+  const [maxIterations, setMaxIterations] = useState<number>(3);
+  const [submitting, setSubmitting] = useState(false);
+
+  const canSubmitBrief = useMemo(
+    () => allRequiredAnswered(briefQuestions, answers),
+    [briefQuestions, answers],
+  );
+
+  if (phase === "brief") {
+    return (
+      <section data-testid="dialogue-brief" className="space-y-3">
+        <header className="flex items-center justify-between gap-2">
+          <h2 className="flex items-center gap-1.5 text-sm font-semibold">
+            <Sparkles className="h-4 w-4" aria-hidden /> Brief
+          </h2>
+          <span className="text-muted-foreground text-xs">
+            {briefQuestions.length === 0
+              ? "No questions — proceed to research"
+              : `${briefQuestions.length} question${briefQuestions.length > 1 ? "s" : ""}`}
+          </span>
+        </header>
+
+        {briefQuestions.length === 0 && isStreaming ? (
+          <Card>
+            <CardContent className="text-muted-foreground py-6 text-center text-xs">
+              Preparing Brief questions…
+            </CardContent>
+          </Card>
+        ) : null}
+
+        {briefQuestions.map((q) => (
+          <BriefQuestionCard
+            key={q.id}
+            question={q}
+            answer={answers[q.id] ?? null}
+            onChange={(next) => setAnswers((prev) => ({ ...prev, [q.id]: next }))}
+          />
+        ))}
+
+        {pageSnapshot?.hasContent ? (
+          <Card>
+            <CardHeader className="pb-2">
+              <CardTitle className="text-muted-foreground text-xs tracking-wide uppercase">
+                Page already has content
+              </CardTitle>
+            </CardHeader>
+            <CardContent className="space-y-2">
+              <label className="flex items-center gap-2 text-sm">
+                <input
+                  type="radio"
+                  data-testid="append-radio-true"
+                  checked={appendToExisting}
+                  onChange={() => setAppendToExisting(true)}
+                />
+                Append to existing content
+              </label>
+              <label className="flex items-center gap-2 text-sm">
+                <input
+                  type="radio"
+                  data-testid="append-radio-false"
+                  checked={!appendToExisting}
+                  onChange={() => setAppendToExisting(false)}
+                />
+                Replace existing content
+              </label>
+            </CardContent>
+          </Card>
+        ) : null}
+
+        <Card>
+          <CardHeader className="pb-2">
+            <CardTitle className="text-muted-foreground text-xs tracking-wide uppercase">
+              Research depth
+            </CardTitle>
+          </CardHeader>
+          <CardContent className="space-y-2">
+            <div className="text-muted-foreground flex items-center justify-between text-xs">
+              <span>1 (quick)</span>
+              <span data-testid="research-iterations-value" className="text-foreground font-medium">
+                {maxIterations} iteration{maxIterations > 1 ? "s" : ""}
+              </span>
+              <span>5 (deep)</span>
+            </div>
+            <Slider
+              data-testid="research-iterations-slider"
+              min={1}
+              max={5}
+              step={1}
+              value={[maxIterations]}
+              onValueChange={(v) => setMaxIterations(v[0] ?? 3)}
+            />
+          </CardContent>
+        </Card>
+
+        <div className="flex justify-end">
+          <Button
+            data-testid="submit-brief"
+            disabled={!canSubmitBrief || submitting || isStreaming}
+            onClick={async () => {
+              setSubmitting(true);
+              try {
+                await onSubmitBrief({
+                  answers: Object.values(answers),
+                  appendToExisting,
+                  researchMaxIterations: maxIterations,
+                });
+              } finally {
+                setSubmitting(false);
+              }
+            }}
+          >
+            {submitting ? (
+              <RefreshCw className="mr-1 h-4 w-4 animate-spin" />
+            ) : (
+              <ArrowRight className="mr-1 h-4 w-4" />
+            )}
+            Start research
+          </Button>
+        </div>
+      </section>
+    );
+  }
+
+  if (phase === "structure") {
+    return (
+      <section data-testid="dialogue-structure" className="space-y-3">
+        <header className="flex items-center justify-between gap-2">
+          <h2 className="text-sm font-semibold">Outline</h2>
+          <span className="text-muted-foreground text-xs">
+            {outlineProposal.length} section{outlineProposal.length === 1 ? "" : "s"}
+          </span>
+        </header>
+        <OutlineEditor
+          initialSections={outlineProposal}
+          disabled={submitting || isStreaming}
+          onSubmit={async (sections) => {
+            setSubmitting(true);
+            try {
+              await onSubmitOutline({ sections });
+            } finally {
+              setSubmitting(false);
+            }
+          }}
+        />
+      </section>
+    );
+  }
+
+  if (phase === "draft" || phase === "completed") {
+    return (
+      <section data-testid="dialogue-draft" className="space-y-3">
+        <header>
+          <h2 className="text-sm font-semibold">
+            {phase === "completed" ? "Completed" : "Drafting"}
+          </h2>
+          <p className="text-muted-foreground text-xs">
+            {phase === "completed"
+              ? "Article ready. Return to the page to review and save."
+              : "Sections are being drafted. Watch the editor on the left for live updates."}
+          </p>
+        </header>
+      </section>
+    );
+  }
+
+  // research phase — handled in ResearchSection; nothing to render here.
+  return null;
+};
diff --git a/src/components/wikiCompose/EditorPane.tsx b/src/components/wikiCompose/EditorPane.tsx
new file mode 100644
index 00000000..eff4789e
--- /dev/null
+++ b/src/components/wikiCompose/EditorPane.tsx
@@ -0,0 +1,100 @@
+/**
+ * `EditorPane` — left pane of the Wiki Compose split view (#950).
+ *
+ * 分割画面の左ペイン。タイトル + Tiptap ベースのエディタを表示する想定だが、
+ * Compose 中の draft 進捗を確認できるよう、本実装ではセクション本文を
+ * Markdown プレビューとして直接描画する MVP に絞る。確定後 (`phase === "completed"`)
+ * は完成 Markdown を一括表示し、ユーザーはノートに戻ってから Tiptap で確定する。
+ *
+ * Read-only preview of the streaming/drafted content. Each outline section
+ * gets its own `## heading` block. The currently-streaming section is
+ * highlighted with a pulsing border so the user sees where to look.
+ */
+import React from "react";
+import { cn } from "@zedi/ui";
+import type { DraftedSection, OutlineSection } from "@/lib/wikiCompose/types";
+
+export interface EditorPaneProps {
+  title: string;
+  outline: OutlineSection[];
+  draftedSections: Record<string, DraftedSection>;
+  sectionBuffers: Record<string, string>;
+  streamingSectionId: string | null;
+  /** Markdown preview to render when the run completes. */
+  completedMarkdown: string | null;
+}
+
+/** Render the left preview pane. */
+export const EditorPane: React.FC<EditorPaneProps> = ({
+  title,
+  outline,
+  draftedSections,
+  sectionBuffers,
+  streamingSectionId,
+  completedMarkdown,
+}) => {
+  return (
+    <div
+      data-testid="compose-editor-pane"
+      className="bg-background prose prose-sm dark:prose-invert h-full max-w-none overflow-auto px-6 py-6"
+    >
+      <h1 className="!mb-2">{title || "Untitled page"}</h1>
+
+      {outline.length === 0 && !completedMarkdown ? (
+        <p className="text-muted-foreground text-sm italic">
+          The article will appear here once the agent starts drafting.
+        </p>
+      ) : null}
+
+      {outline.length > 0 ? (
+        <div className="space-y-6">
+          {outline.map((section) => {
+            const drafted = draftedSections[section.id];
+            const buffer = sectionBuffers[section.id] ?? "";
+            const isStreaming = streamingSectionId === section.id;
+            const body = drafted?.body ?? buffer;
+            return (
+              <section
+                key={section.id}
+                data-testid={`editor-section-${section.id}`}
+                className={cn(
+                  "rounded-md transition-colors",
+                  isStreaming &&
+                    "border border-blue-300 px-3 py-2 ring-2 ring-blue-200/40 dark:border-blue-700/60 dark:ring-blue-900/30",
+                )}
+              >
+                {section.depth === 1 ? (
+                  <h2 className="!mt-0">{section.heading}</h2>
+                ) : (
+                  <h3 className="!mt-0">{section.heading}</h3>
+                )}
+                {body.trim().length === 0 ? (
+                  <p className="text-muted-foreground !my-1 text-xs italic">
+                    {isStreaming ? "Streaming…" : section.intent}
+                  </p>
+                ) : (
+                  // Plain-text rendering of the running buffer. Once the
+                  // section finalises we still render as <pre> to preserve
+                  // formatting; a future iteration can mount Tiptap here.
+                  // 進行中はバッファをそのまま <pre> で出す（フォーマット保持）。
+                  <pre className="!bg-transparent !p-0 font-sans text-sm leading-relaxed whitespace-pre-wrap">
+                    {body}
+                  </pre>
+                )}
+              </section>
+            );
+          })}
+        </div>
+      ) : null}
+
+      {completedMarkdown ? (
+        <section data-testid="editor-completed-markdown" className="mt-6 border-t pt-4">
+          <h3 className="text-muted-foreground text-xs tracking-wide uppercase">Final Markdown</h3>
+          <pre className="!bg-muted/40 rounded-md p-3 font-mono text-xs whitespace-pre-wrap">
+            {completedMarkdown}
+          </pre>
+        </section>
+      ) : null}
+    </div>
+  );
+};
diff --git a/src/components/wikiCompose/OutlineEditor.tsx b/src/components/wikiCompose/OutlineEditor.tsx
new file mode 100644
index 00000000..8d80e2a1
--- /dev/null
+++ b/src/components/wikiCompose/OutlineEditor.tsx
@@ -0,0 +1,170 @@
+/**
+ * `OutlineEditor` — editable outline list for the Structure phase (#950).
+ *
+ * Orchestrator が提案したアウトラインをユーザーが編集 (並び替え / リネーム /
+ * depth 変更 / 削除) するための軽量 UI。ドラッグ&ドロップは将来対応とし、
+ * 当面は上下矢印ボタンで順序入れ替えする。
+ *
+ * Minimal accessible outline editor. Each section row has heading + intent
+ * inputs, depth toggle (h2 ↔ h3), move-up / move-down buttons, and a delete
+ * button. The user submits via the dedicated button at the bottom.
+ */
+import React, { useState } from "react";
+import { ArrowDown, ArrowUp, Trash2, Plus, Check } from "lucide-react";
+import { Button, Card, CardContent, Input, Textarea } from "@zedi/ui";
+import { cn } from "@zedi/ui";
+import type { OutlineSection } from "@/lib/wikiCompose/types";
+
+let nextLocalId = 0;
+function makeLocalId(): string {
+  nextLocalId += 1;
+  return `local-${nextLocalId}-${Date.now()}`;
+}
+
+export interface OutlineEditorProps {
+  initialSections: OutlineSection[];
+  disabled?: boolean;
+  onSubmit: (sections: OutlineSection[]) => Promise<void>;
+}
+
+/** Render an editable outline. */
+export const OutlineEditor: React.FC<OutlineEditorProps> = ({
+  initialSections,
+  disabled = false,
+  onSubmit,
+}) => {
+  const [sections, setSections] = useState<OutlineSection[]>(initialSections);
+  const [submitting, setSubmitting] = useState(false);
+
+  React.useEffect(() => {
+    setSections(initialSections);
+  }, [initialSections]);
+
+  const move = (index: number, direction: -1 | 1) => {
+    setSections((prev) => {
+      const next = [...prev];
+      const target = index + direction;
+      if (target < 0 || target >= next.length) return prev;
+      const item = next[index];
+      const other = next[target];
+      if (!item || !other) return prev;
+      next[index] = other;
+      next[target] = item;
+      return next;
+    });
+  };
+
+  const remove = (id: string) => setSections((prev) => prev.filter((s) => s.id !== id));
+
+  const add = () =>
+    setSections((prev) => [
+      ...prev,
+      { id: makeLocalId(), heading: "New section", depth: 1, intent: "" },
+    ]);
+
+  const update = (id: string, patch: Partial<OutlineSection>) =>
+    setSections((prev) => prev.map((s) => (s.id === id ? { ...s, ...patch } : s)));
+
+  const isSubmittable = sections.length > 0 && sections.every((s) => s.heading.trim().length > 0);
+
+  return (
+    <div className="space-y-2">
+      {sections.map((section, i) => (
+        <Card
+          key={section.id}
+          data-testid={`outline-row-${section.id}`}
+          className={cn("transition-colors", section.depth > 1 && "ml-6")}
+        >
+          <CardContent className="space-y-2 pt-4">
+            <div className="flex items-center gap-2">
+              <Input
+                value={section.heading}
+                data-testid={`outline-heading-${section.id}`}
+                onChange={(e) => update(section.id, { heading: e.target.value })}
+                placeholder="Section heading"
+                disabled={disabled}
+              />
+              <Button
+                type="button"
+                size="sm"
+                variant="ghost"
+                title="Toggle depth"
+                onClick={() => update(section.id, { depth: section.depth === 1 ? 2 : 1 })}
+                disabled={disabled}
+              >
+                H{section.depth + 1}
+              </Button>
+              <Button
+                type="button"
+                size="sm"
+                variant="ghost"
+                title="Move up"
+                onClick={() => move(i, -1)}
+                disabled={disabled || i === 0}
+              >
+                <ArrowUp className="h-4 w-4" />
+              </Button>
+              <Button
+                type="button"
+                size="sm"
+                variant="ghost"
+                title="Move down"
+                onClick={() => move(i, +1)}
+                disabled={disabled || i === sections.length - 1}
+              >
+                <ArrowDown className="h-4 w-4" />
+              </Button>
+              <Button
+                type="button"
+                size="sm"
+                variant="ghost"
+                title="Remove section"
+                onClick={() => remove(section.id)}
+                disabled={disabled}
+              >
+                <Trash2 className="h-4 w-4" />
+              </Button>
+            </div>
+            <Textarea
+              value={section.intent}
+              data-testid={`outline-intent-${section.id}`}
+              onChange={(e) => update(section.id, { intent: e.target.value })}
+              placeholder="What should this section cover?"
+              rows={2}
+              disabled={disabled}
+              className="text-xs"
+            />
+          </CardContent>
+        </Card>
+      ))}
+
+      <div className="flex items-center justify-between gap-2">
+        <Button
+          type="button"
+          variant="ghost"
+          size="sm"
+          onClick={add}
+          disabled={disabled}
+          data-testid="outline-add"
+        >
+          <Plus className="mr-1 h-4 w-4" /> Add section
+        </Button>
+        <Button
+          type="button"
+          data-testid="outline-submit"
+          disabled={disabled || submitting || !isSubmittable}
+          onClick={async () => {
+            setSubmitting(true);
+            try {
+              await onSubmit(sections);
+            } finally {
+              setSubmitting(false);
+            }
+          }}
+        >
+          <Check className="mr-1 h-4 w-4" /> Approve outline
+        </Button>
+      </div>
+    </div>
+  );
+};
diff --git a/src/components/wikiCompose/PhaseStepper.test.tsx b/src/components/wikiCompose/PhaseStepper.test.tsx
new file mode 100644
index 00000000..8cffc3bb
--- /dev/null
+++ b/src/components/wikiCompose/PhaseStepper.test.tsx
@@ -0,0 +1,25 @@
+/**
+ * `PhaseStepper` ユニットテスト (#950)。
+ *
+ * `phase` プロップが各値のときに、対応するステップ要素が `aria-current="step"`
+ * になることを確認する。
+ */
+import { describe, it, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { PhaseStepper } from "./PhaseStepper";
+
+describe("PhaseStepper", () => {
+  it("marks the current phase with aria-current=step", () => {
+    render(<PhaseStepper phase="research" />);
+    const current = screen.getByTestId("phase-step-research");
+    expect(current).toHaveAttribute("aria-current", "step");
+
+    expect(screen.getByTestId("phase-step-brief")).not.toHaveAttribute("aria-current");
+    expect(screen.getByTestId("phase-step-completed")).not.toHaveAttribute("aria-current");
+  });
+
+  it("shows the completed phase as the active step", () => {
+    render(<PhaseStepper phase="completed" />);
+    expect(screen.getByTestId("phase-step-completed")).toHaveAttribute("aria-current", "step");
+  });
+});
diff --git a/src/components/wikiCompose/PhaseStepper.tsx b/src/components/wikiCompose/PhaseStepper.tsx
new file mode 100644
index 00000000..a6ae8b7c
--- /dev/null
+++ b/src/components/wikiCompose/PhaseStepper.tsx
@@ -0,0 +1,71 @@
+/**
+ * `PhaseStepper` — top-of-panel progress indicator for Wiki Compose (#950).
+ *
+ * Brief → Research → Structure → Draft → Completed の 5 段階を、現在のフェーズに
+ * 応じて active / completed / upcoming で色分け表示する。Compose 画面の右ペイン
+ * ヘッダーに常時表示し、ユーザーが現在地を見失わないようにする。
+ *
+ * Compact, non-interactive stepper. The user advances phases by submitting at
+ * each interrupt; this component reflects the resulting phase, it does not
+ * trigger transitions.
+ */
+import React from "react";
+import { Check, Circle, CircleDashed } from "lucide-react";
+import { cn } from "@zedi/ui";
+import type { ComposePhase } from "@/hooks/useWikiComposeSession";
+
+const PHASE_ORDER: ComposePhase[] = ["brief", "research", "structure", "draft", "completed"];
+
+const PHASE_LABEL: Record<ComposePhase, string> = {
+  brief: "Brief",
+  research: "Research",
+  structure: "Structure",
+  draft: "Draft",
+  completed: "Done",
+};
+
+export interface PhaseStepperProps {
+  /** Current phase. */
+  phase: ComposePhase;
+}
+
+/** Render the 5-step phase stepper. */
+export const PhaseStepper: React.FC<PhaseStepperProps> = ({ phase }) => {
+  // P5 conflict interrupt sits between Research and Structure on the graph, but
+  // the stepper keeps five labels — highlight Research while resolving conflicts.
+  // P5 の conflict interrupt は Research と Structure の間にあるが、
+  // ステッパーは 5 ラベル維持のため conflict 中は Research をハイライトする。
+  const stepPhase: ComposePhase = phase === "conflict" ? "research" : phase;
+  const currentIndex = Math.max(0, PHASE_ORDER.indexOf(stepPhase));
+  return (
+    <ol className="flex items-center gap-1 text-xs" aria-label="Compose phase progress">
+      {PHASE_ORDER.map((p, i) => {
+        const state = i < currentIndex ? "completed" : i === currentIndex ? "active" : "upcoming";
+        return (
+          <React.Fragment key={p}>
+            <li
+              className={cn(
+                "flex items-center gap-1 rounded-md px-2 py-1",
+                state === "completed" && "text-emerald-600 dark:text-emerald-400",
+                state === "active" && "text-foreground bg-muted font-medium",
+                state === "upcoming" && "text-muted-foreground",
+              )}
+              data-testid={`phase-step-${p}`}
+              aria-current={state === "active" ? "step" : undefined}
+            >
+              {state === "completed" ? (
+                <Check className="h-3 w-3" aria-hidden />
+              ) : state === "active" ? (
+                <Circle className="h-3 w-3 fill-current" aria-hidden />
+              ) : (
+                <CircleDashed className="h-3 w-3" aria-hidden />
+              )}
+              <span>{PHASE_LABEL[p]}</span>
+            </li>
+            {i < PHASE_ORDER.length - 1 ? <li aria-hidden className="bg-border h-px w-3" /> : null}
+          </React.Fragment>
+        );
+      })}
+    </ol>
+  );
+};
diff --git a/src/components/wikiCompose/ResearchSection.tsx b/src/components/wikiCompose/ResearchSection.tsx
new file mode 100644
index 00000000..35cecac9
--- /dev/null
+++ b/src/components/wikiCompose/ResearchSection.tsx
@@ -0,0 +1,234 @@
+/**
+ * `ResearchSection` — research source review panel (#950).
+ *
+ * 調査ループ完了後、`human_review_research` interrupt 中にユーザーに表示する
+ * ソース個別採用 UI。各ソースに対して採用 / 除外を切り替え、最後に
+ * 「Approve selected」で graph を再開する。`approvedSources` が確定済みの場合は
+ * 読み取り専用のサマリ表示にフォールバック。
+ *
+ * Per-source approve/reject UI. Cards show source title + URL/snippet/excerpt
+ * preview; the user toggles each row, then submits the approved + rejected
+ * id sets to `submitResearchApproval`.
+ */
+import React, { useEffect, useState } from "react";
+import { ExternalLink, Check } from "lucide-react";
+import { Badge, Button, Card, CardContent, CardHeader, CardTitle } from "@zedi/ui";
+import { cn } from "@zedi/ui";
+import type { ResearchBatch, ResearchSource } from "@/lib/wikiCompose/types";
+
+type Decision = "approved" | "rejected" | "pending";
+
+export interface ResearchSectionProps {
+  batch: ResearchBatch | null;
+  pendingSources: ResearchSource[];
+  approvedSources: ResearchSource[];
+  isReadOnly: boolean;
+  isStreaming: boolean;
+  onSubmit: (input: {
+    approvedSourceIds: string[];
+    rejectedSourceIds?: string[];
+    note?: string;
+  }) => Promise<void>;
+}
+
+/** Maps source kind to a short label. */
+function kindLabel(kind: ResearchSource["kind"]): string {
+  switch (kind) {
+    case "web":
+      return "Web";
+    case "wiki":
+      return "Wiki";
+    case "fetched":
+      return "Article";
+  }
+}
+
+/** Render the research review panel. */
+export const ResearchSection: React.FC<ResearchSectionProps> = ({
+  batch,
+  pendingSources,
+  approvedSources,
+  isReadOnly,
+  isStreaming,
+  onSubmit,
+}) => {
+  const [decisions, setDecisions] = useState<Record<string, Decision>>({});
+  const [submitting, setSubmitting] = useState(false);
+
+  // Seed decisions to "approved" by default when sources change so the user
+  // can review and reject rather than starting from scratch.
+  // pendingSources の初期 decision は approved を default とする。
+  useEffect(() => {
+    setDecisions((prev) => {
+      const next: Record<string, Decision> = { ...prev };
+      for (const s of pendingSources) {
+        if (next[s.id] === undefined) next[s.id] = "approved";
+      }
+      return next;
+    });
+  }, [pendingSources]);
+
+  const setDecision = (id: string, d: Decision) => setDecisions((prev) => ({ ...prev, [id]: d }));
+
+  const handleSubmit = async () => {
+    const approvedSourceIds: string[] = [];
+    const rejectedSourceIds: string[] = [];
+    for (const s of pendingSources) {
+      const d = decisions[s.id] ?? "approved";
+      if (d === "approved") approvedSourceIds.push(s.id);
+      else if (d === "rejected") rejectedSourceIds.push(s.id);
+    }
+    setSubmitting(true);
+    try {
+      await onSubmit({ approvedSourceIds, rejectedSourceIds });
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  // Read-only view: show approved sources after the user has resumed.
+  // 確定済みソースの表示モード。
+  if (isReadOnly) {
+    if (approvedSources.length === 0) {
+      return (
+        <section data-testid="research-section-readonly" className="text-muted-foreground text-xs">
+          No research sources were approved.
+        </section>
+      );
+    }
+    return (
+      <section data-testid="research-section-readonly" className="space-y-2">
+        <h2 className="flex items-center gap-2 text-sm font-semibold">
+          Research <Badge variant="secondary">{approvedSources.length} approved</Badge>
+        </h2>
+        <ul className="space-y-1.5">
+          {approvedSources.map((s) => (
+            <li
+              key={s.id}
+              className="bg-muted/30 flex items-start gap-2 rounded-md border p-2 text-xs"
+            >
+              <Check className="mt-0.5 h-3 w-3 shrink-0 text-emerald-600 dark:text-emerald-400" />
+              <div className="min-w-0 flex-1">
+                <div className="truncate font-medium">{s.title}</div>
+                {s.url || s.finalUrl ? (
+                  <a
+                    href={s.finalUrl ?? s.url}
+                    target="_blank"
+                    rel="noreferrer"
+                    className="text-muted-foreground hover:text-foreground inline-flex items-center gap-0.5 truncate"
+                  >
+                    <ExternalLink className="h-3 w-3" />
+                    <span className="truncate">{s.finalUrl ?? s.url}</span>
+                  </a>
+                ) : null}
+              </div>
+            </li>
+          ))}
+        </ul>
+      </section>
+    );
+  }
+
+  if (pendingSources.length === 0) {
+    return (
+      <section data-testid="research-section-empty" className="text-muted-foreground text-xs">
+        {isStreaming
+          ? "Research in progress — sources will appear when ready."
+          : "No research sources to review."}
+      </section>
+    );
+  }
+
+  const approvedCount = pendingSources.filter(
+    (s) => (decisions[s.id] ?? "approved") === "approved",
+  ).length;
+
+  return (
+    <section data-testid="research-section-review" className="space-y-3">
+      <header className="flex items-center justify-between">
+        <h2 className="flex items-center gap-2 text-sm font-semibold">
+          Research review
+          {batch ? <Badge variant="outline">iter {batch.iteration + 1}</Badge> : null}
+        </h2>
+        <span className="text-muted-foreground text-xs">
+          {approvedCount} / {pendingSources.length} approved
+        </span>
+      </header>
+
+      <ul className="space-y-2">
+        {pendingSources.map((s) => {
+          const d = decisions[s.id] ?? "approved";
+          return (
+            <Card
+              key={s.id}
+              data-testid={`source-row-${s.id}`}
+              className={cn(
+                "transition-colors",
+                d === "approved" && "border-emerald-300 dark:border-emerald-700/60",
+                d === "rejected" && "opacity-60",
+              )}
+            >
+              <CardHeader className="pb-2">
+                <CardTitle className="flex items-start gap-2 text-sm leading-snug font-medium">
+                  <Badge variant="outline" className="shrink-0 text-[10px] uppercase">
+                    {kindLabel(s.kind)}
+                  </Badge>
+                  <span className="flex-1 break-words">{s.title}</span>
+                </CardTitle>
+              </CardHeader>
+              <CardContent className="space-y-2">
+                {s.url || s.finalUrl ? (
+                  <a
+                    className="text-muted-foreground hover:text-foreground inline-flex items-center gap-0.5 text-xs break-all"
+                    href={s.finalUrl ?? s.url}
+                    target="_blank"
+                    rel="noreferrer"
+                  >
+                    <ExternalLink className="h-3 w-3 shrink-0" />
+                    {s.finalUrl ?? s.url}
+                  </a>
+                ) : null}
+                {s.excerpt || s.snippet ? (
+                  <p className="text-muted-foreground line-clamp-3 text-xs leading-relaxed">
+                    {s.excerpt ?? s.snippet}
+                  </p>
+                ) : null}
+                <div className="flex gap-2">
+                  <Button
+                    type="button"
+                    variant={d === "approved" ? "default" : "outline"}
+                    size="sm"
+                    data-testid={`source-approve-${s.id}`}
+                    onClick={() => setDecision(s.id, "approved")}
+                  >
+                    Approve
+                  </Button>
+                  <Button
+                    type="button"
+                    variant={d === "rejected" ? "destructive" : "outline"}
+                    size="sm"
+                    data-testid={`source-reject-${s.id}`}
+                    onClick={() => setDecision(s.id, "rejected")}
+                  >
+                    Reject
+                  </Button>
+                </div>
+              </CardContent>
+            </Card>
+          );
+        })}
+      </ul>
+
+      <div className="flex justify-end">
+        <Button
+          type="button"
+          data-testid="research-submit"
+          disabled={submitting || isStreaming}
+          onClick={handleSubmit}
+        >
+          <Check className="mr-1 h-4 w-4" /> Continue with selection
+        </Button>
+      </div>
+    </section>
+  );
+};
diff --git a/src/hooks/runAIChatAction.test.ts b/src/hooks/runAIChatAction.test.ts
index 930adae0..f4661c04 100644
--- a/src/hooks/runAIChatAction.test.ts
+++ b/src/hooks/runAIChatAction.test.ts
@@ -1,5 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import { runAIChatAction, type RunAIChatActionDeps } from "./runAIChatAction";
+import { COMPOSE_SEED_STATE_KEY } from "@/lib/wikiCompose/navigation";
 import type { ChatMessage } from "@/types/aiChat";
 
 const t = ((key: string, opts?: Record<string, unknown>) => {
@@ -46,7 +47,7 @@ describe("runAIChatAction — create", () => {
     vi.clearAllMocks();
   });
 
-  it("create-page: creates empty page and navigates with pendingChatPageGeneration state", async () => {
+  it("create-page: creates empty page and navigates to Wiki Compose with chat seed", async () => {
     const createPageMutateAsync = vi.fn().mockResolvedValue({ id: "new-page-1", noteId: "note-1" });
     const navigate = vi.fn();
     const messages: ChatMessage[] = [{ id: "1", role: "user", content: "hello", timestamp: 1 }];
@@ -64,9 +65,9 @@ describe("runAIChatAction — create", () => {
       title: "Wiki Topic",
       content: "",
     });
-    expect(navigate).toHaveBeenCalledWith("/notes/note-1/new-page-1", {
+    expect(navigate).toHaveBeenCalledWith("/notes/note-1/new-page-1/compose", {
       state: {
-        pendingChatPageGeneration: {
+        [COMPOSE_SEED_STATE_KEY]: {
           outline: "- A\n- B",
           conversationText: expect.stringContaining("hello"),
         },
@@ -97,9 +98,9 @@ describe("runAIChatAction — create", () => {
     });
 
     expect(createPageMutateAsync).toHaveBeenCalledTimes(2);
-    expect(navigate).toHaveBeenCalledWith("/notes/note-1/p1", {
+    expect(navigate).toHaveBeenCalledWith("/notes/note-1/p1/compose", {
       state: {
-        pendingChatPageGeneration: {
+        [COMPOSE_SEED_STATE_KEY]: {
           outline: "- o1",
           conversationText: expect.stringContaining("ctx"),
         },
@@ -129,9 +130,9 @@ describe("runAIChatAction — create", () => {
       reason: "multi",
     });
 
-    expect(navigate).toHaveBeenCalledWith("/notes/note-1/p1", {
+    expect(navigate).toHaveBeenCalledWith("/notes/note-1/p1/compose", {
       state: {
-        pendingChatPageGeneration: {
+        [COMPOSE_SEED_STATE_KEY]: {
           outline: "- from-second",
           conversationText: expect.stringContaining("ctx"),
         },
diff --git a/src/hooks/runAIChatAction.ts b/src/hooks/runAIChatAction.ts
index 02b5082d..2b5c0b26 100644
--- a/src/hooks/runAIChatAction.ts
+++ b/src/hooks/runAIChatAction.ts
@@ -10,7 +10,7 @@ import type {
   SuggestWikiLinksAction,
 } from "@/types/aiChat";
 import type { PageContext } from "@/types/aiChat";
-import type { PendingChatPageGenerationState } from "@/types/chatPageGeneration";
+import { navigateToWikiCompose } from "@/lib/wikiCompose/navigation";
 import {
   buildSuggestedWikiLinksMarkdown,
   getCreatePageOutline,
@@ -53,20 +53,19 @@ async function handleCreatePage(
 ): Promise<void> {
   const outline = getCreatePageOutline(action);
   const conversationText = serializeChatMessagesForPageGeneration(deps.messages);
-  const pending: PendingChatPageGenerationState = { outline, conversationText };
   const result = await deps.createPageMutateAsync({
     title: action.title,
     content: "",
   });
   if (result?.id && result.noteId) {
-    // Issue #889 Phase 3: `/pages/:id` 撤去のため `/notes/:noteId/:pageId` に遷移。
-    // `noteId` が無い場合は不正な URL になるので遷移しない（バックエンドの
-    // 想定外応答に対する防御）。
-    // Issue #889 Phase 3: route to `/notes/:noteId/:pageId` (legacy
-    // `/pages/:id` route was retired). Skip navigation when `noteId` is
-    // missing so we never build `/notes/undefined/...`.
-    deps.navigate(`/notes/${result.noteId}/${result.id}`, {
-      state: { pendingChatPageGeneration: pending },
+    // Issue #950: 旧 `pendingChatPageGeneration` インライン生成の代わりに
+    // Wiki Compose 分割画面へ遷移し、チャット文脈を seed する。
+    // Issue #950: open Wiki Compose instead of inline generation on the page.
+    navigateToWikiCompose({
+      navigate: deps.navigate,
+      noteId: result.noteId,
+      pageId: result.id,
+      seed: { outline, conversationText },
     });
   }
 }
@@ -98,17 +97,11 @@ async function handleCreateMultiplePages(
     }
   }
   if (firstCreated?.id && firstCreated.noteId) {
-    const pending: PendingChatPageGenerationState = {
-      outline: firstOutline,
-      conversationText,
-    };
-    // Issue #889 Phase 3: `/pages/:id` 撤去のため `/notes/:noteId/:pageId` に遷移。
-    // `noteId` 欠落時は不正な URL になるため遷移を打ち切る。
-    // Issue #889 Phase 3: route to `/notes/:noteId/:pageId` (legacy
-    // `/pages/:id` route was retired). Skip navigation when `noteId` is
-    // missing so we never build `/notes/undefined/...`.
-    deps.navigate(`/notes/${firstCreated.noteId}/${firstCreated.id}`, {
-      state: { pendingChatPageGeneration: pending },
+    navigateToWikiCompose({
+      navigate: deps.navigate,
+      noteId: firstCreated.noteId,
+      pageId: firstCreated.id,
+      seed: { outline: firstOutline, conversationText },
     });
   }
 }
diff --git a/src/hooks/useEditorWikiLinkShortcuts.test.ts b/src/hooks/useEditorWikiLinkShortcuts.test.ts
new file mode 100644
index 00000000..6db0ff43
--- /dev/null
+++ b/src/hooks/useEditorWikiLinkShortcuts.test.ts
@@ -0,0 +1,346 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import type { Editor } from "@tiptap/core";
+import { useEditorWikiLinkShortcuts } from "./useEditorWikiLinkShortcuts";
+
+/**
+ * テスト用のミニマル Editor モック。`isFocused` / `isEditable` / `state.selection`
+ * を本フックが参照するためだけに最低限の形で公開する。
+ *
+ * Minimal `Editor` mock exposing only the surface `useEditorWikiLinkShortcuts`
+ * reads: `isFocused`, `isEditable`, and `state.selection`.
+ */
+function createMockEditor(
+  options: {
+    isFocused?: boolean;
+    isEditable?: boolean;
+    selection?: { from: number; to: number };
+  } = {},
+): Editor {
+  const { isFocused = true, isEditable = true, selection = { from: 5, to: 5 } } = options;
+  return {
+    isFocused,
+    isEditable,
+    state: { selection: { from: selection.from, to: selection.to } },
+  } as unknown as Editor;
+}
+
+/**
+ * `KeyboardEvent` を dispatch して `defaultPrevented` 結果を返すヘルパー。
+ * `cancelable: true` を必ず付け、`preventDefault` の呼び出しがフラグに反映
+ * されるようにする（jsdom）。
+ *
+ * Dispatch a `KeyboardEvent` and return whether `preventDefault` was called.
+ * Always set `cancelable: true` so jsdom honors `preventDefault`.
+ */
+function dispatchKeyDown(init: KeyboardEventInit & { key: string }): KeyboardEvent {
+  const event = new KeyboardEvent("keydown", {
+    bubbles: true,
+    cancelable: true,
+    ...init,
+  });
+  document.dispatchEvent(event);
+  return event;
+}
+
+describe("useEditorWikiLinkShortcuts - Cmd/Ctrl+K", () => {
+  let focusInputBar: ReturnType<typeof vi.fn>;
+  let convertSelectionToWikiLink: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    focusInputBar = vi.fn();
+    convertSelectionToWikiLink = vi.fn().mockResolvedValue(undefined);
+  });
+
+  it("Cmd+K (mac) を捕捉して focusInputBar を呼び preventDefault する / catches Cmd+K on mac and invokes focusInputBar with preventDefault", () => {
+    const editor = createMockEditor({ isFocused: true });
+    renderHook(() =>
+      useEditorWikiLinkShortcuts({ editor, focusInputBar, convertSelectionToWikiLink }),
+    );
+
+    const event = dispatchKeyDown({ key: "k", metaKey: true });
+
+    expect(focusInputBar).toHaveBeenCalledTimes(1);
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it("Ctrl+K (windows/linux) を捕捉する / catches Ctrl+K cross-platform", () => {
+    const editor = createMockEditor({ isFocused: true });
+    renderHook(() =>
+      useEditorWikiLinkShortcuts({ editor, focusInputBar, convertSelectionToWikiLink }),
+    );
+
+    const event = dispatchKeyDown({ key: "k", ctrlKey: true });
+
+    expect(focusInputBar).toHaveBeenCalledTimes(1);
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it("エディタ非フォーカス時は無視する（グローバル検索に委ねる） / ignores when editor is not focused so the global search shortcut wins", () => {
+    const editor = createMockEditor({ isFocused: false });
+    renderHook(() =>
+      useEditorWikiLinkShortcuts({ editor, focusInputBar, convertSelectionToWikiLink }),
+    );
+
+    const event = dispatchKeyDown({ key: "k", metaKey: true });
+
+    expect(focusInputBar).not.toHaveBeenCalled();
+    expect(event.defaultPrevented).toBe(false);
+  });
+
+  it("Cmd+Shift+K は捕捉しない（modifier 弁別） / does not capture Cmd+Shift+K (modifier discrimination)", () => {
+    const editor = createMockEditor({ isFocused: true });
+    renderHook(() =>
+      useEditorWikiLinkShortcuts({ editor, focusInputBar, convertSelectionToWikiLink }),
+    );
+
+    const event = dispatchKeyDown({ key: "k", metaKey: true, shiftKey: true });
+
+    expect(focusInputBar).not.toHaveBeenCalled();
+    expect(event.defaultPrevented).toBe(false);
+  });
+
+  it("Caps Lock で `event.key` が 'K' になっても捕捉する / matches uppercase 'K' too (Caps Lock without Shift) — Codex P2", () => {
+    const editor = createMockEditor({ isFocused: true });
+    renderHook(() =>
+      useEditorWikiLinkShortcuts({ editor, focusInputBar, convertSelectionToWikiLink }),
+    );
+
+    const event = dispatchKeyDown({ key: "K", metaKey: true });
+
+    expect(focusInputBar).toHaveBeenCalledTimes(1);
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it("Alt 併用は無視する / ignores when Alt is held", () => {
+    const editor = createMockEditor({ isFocused: true });
+    renderHook(() =>
+      useEditorWikiLinkShortcuts({ editor, focusInputBar, convertSelectionToWikiLink }),
+    );
+
+    const event = dispatchKeyDown({ key: "k", metaKey: true, altKey: true });
+
+    expect(focusInputBar).not.toHaveBeenCalled();
+    expect(event.defaultPrevented).toBe(false);
+  });
+});
+
+describe("useEditorWikiLinkShortcuts - Cmd/Ctrl+Shift+L", () => {
+  let focusInputBar: ReturnType<typeof vi.fn>;
+  let convertSelectionToWikiLink: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    focusInputBar = vi.fn();
+    convertSelectionToWikiLink = vi.fn().mockResolvedValue(undefined);
+  });
+
+  it("非空選択時に convertSelectionToWikiLink を呼ぶ / invokes convertSelectionToWikiLink when selection is non-empty", () => {
+    const editor = createMockEditor({ isFocused: true, selection: { from: 3, to: 8 } });
+    renderHook(() =>
+      useEditorWikiLinkShortcuts({ editor, focusInputBar, convertSelectionToWikiLink }),
+    );
+
+    const event = dispatchKeyDown({ key: "L", metaKey: true, shiftKey: true });
+
+    expect(convertSelectionToWikiLink).toHaveBeenCalledTimes(1);
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it("Ctrl+Shift+L もクロスプラットフォームで動く / Ctrl+Shift+L also fires cross-platform", () => {
+    const editor = createMockEditor({ isFocused: true, selection: { from: 3, to: 8 } });
+    renderHook(() =>
+      useEditorWikiLinkShortcuts({ editor, focusInputBar, convertSelectionToWikiLink }),
+    );
+
+    const event = dispatchKeyDown({ key: "L", ctrlKey: true, shiftKey: true });
+
+    expect(convertSelectionToWikiLink).toHaveBeenCalledTimes(1);
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it("key が小文字 'l' でも shift と組み合わさっていれば反応する / matches both 'L' and 'l' when shift is held (some browsers/keymaps)", () => {
+    const editor = createMockEditor({ isFocused: true, selection: { from: 1, to: 4 } });
+    renderHook(() =>
+      useEditorWikiLinkShortcuts({ editor, focusInputBar, convertSelectionToWikiLink }),
+    );
+
+    const event = dispatchKeyDown({ key: "l", metaKey: true, shiftKey: true });
+
+    expect(convertSelectionToWikiLink).toHaveBeenCalledTimes(1);
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it("選択範囲が空のときは no-op で preventDefault も呼ばない / no-op + does NOT preventDefault when selection is empty", () => {
+    const editor = createMockEditor({ isFocused: true, selection: { from: 5, to: 5 } });
+    renderHook(() =>
+      useEditorWikiLinkShortcuts({ editor, focusInputBar, convertSelectionToWikiLink }),
+    );
+
+    const event = dispatchKeyDown({ key: "L", metaKey: true, shiftKey: true });
+
+    expect(convertSelectionToWikiLink).not.toHaveBeenCalled();
+    expect(event.defaultPrevented).toBe(false);
+  });
+
+  it("エディタ非フォーカス時は無視する / ignores when editor is not focused", () => {
+    const editor = createMockEditor({ isFocused: false, selection: { from: 3, to: 8 } });
+    renderHook(() =>
+      useEditorWikiLinkShortcuts({ editor, focusInputBar, convertSelectionToWikiLink }),
+    );
+
+    const event = dispatchKeyDown({ key: "L", metaKey: true, shiftKey: true });
+
+    expect(convertSelectionToWikiLink).not.toHaveBeenCalled();
+    expect(event.defaultPrevented).toBe(false);
+  });
+
+  it("convertSelectionToWikiLink が reject しても unhandled rejection を出さない / swallows rejections from convertSelectionToWikiLink so the document keydown handler does not leak unhandled rejections (CodeRabbit / Gemini review)", async () => {
+    const editor = createMockEditor({ isFocused: true, selection: { from: 3, to: 8 } });
+    const rejection = new Error("boom");
+    const rejecting = vi.fn().mockRejectedValue(rejection);
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      renderHook(() =>
+        useEditorWikiLinkShortcuts({
+          editor,
+          focusInputBar,
+          convertSelectionToWikiLink: rejecting,
+        }),
+      );
+
+      dispatchKeyDown({ key: "L", metaKey: true, shiftKey: true });
+
+      // microtask まで待って catch が走ったことを確認する。
+      // Flush microtasks so the catch handler runs.
+      await Promise.resolve();
+      await Promise.resolve();
+
+      expect(rejecting).toHaveBeenCalledTimes(1);
+      expect(consoleError).toHaveBeenCalled();
+    } finally {
+      consoleError.mockRestore();
+    }
+  });
+
+  it("Shift 無しの Cmd+L は捕捉しない / does not capture Cmd+L without Shift", () => {
+    const editor = createMockEditor({ isFocused: true, selection: { from: 3, to: 8 } });
+    renderHook(() =>
+      useEditorWikiLinkShortcuts({ editor, focusInputBar, convertSelectionToWikiLink }),
+    );
+
+    const event = dispatchKeyDown({ key: "l", metaKey: true });
+
+    expect(convertSelectionToWikiLink).not.toHaveBeenCalled();
+    expect(event.defaultPrevented).toBe(false);
+  });
+});
+
+describe("useEditorWikiLinkShortcuts - 共通ガード / shared guards", () => {
+  let focusInputBar: ReturnType<typeof vi.fn>;
+  let convertSelectionToWikiLink: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    focusInputBar = vi.fn();
+    convertSelectionToWikiLink = vi.fn().mockResolvedValue(undefined);
+  });
+
+  it("editor が null のときは何もしない / no-op when editor is null", () => {
+    renderHook(() =>
+      useEditorWikiLinkShortcuts({
+        editor: null,
+        focusInputBar,
+        convertSelectionToWikiLink,
+      }),
+    );
+
+    const event = dispatchKeyDown({ key: "k", metaKey: true });
+
+    expect(focusInputBar).not.toHaveBeenCalled();
+    expect(event.defaultPrevented).toBe(false);
+  });
+
+  it("editor.isEditable が false なら何もしない / no-op when editor is not editable", () => {
+    const editor = createMockEditor({ isFocused: true, isEditable: false });
+    renderHook(() =>
+      useEditorWikiLinkShortcuts({ editor, focusInputBar, convertSelectionToWikiLink }),
+    );
+
+    const event = dispatchKeyDown({ key: "k", metaKey: true });
+
+    expect(focusInputBar).not.toHaveBeenCalled();
+    expect(event.defaultPrevented).toBe(false);
+  });
+
+  it("isReadOnly が true なら何もしない / no-op when isReadOnly is true", () => {
+    const editor = createMockEditor({ isFocused: true });
+    renderHook(() =>
+      useEditorWikiLinkShortcuts({
+        editor,
+        focusInputBar,
+        convertSelectionToWikiLink,
+        isReadOnly: true,
+      }),
+    );
+
+    const event = dispatchKeyDown({ key: "k", metaKey: true });
+
+    expect(focusInputBar).not.toHaveBeenCalled();
+    expect(event.defaultPrevented).toBe(false);
+  });
+
+  it("IME 変換中 (isComposing) は何もしない / no-op while IME composition is active", () => {
+    const editor = createMockEditor({ isFocused: true, selection: { from: 1, to: 4 } });
+    renderHook(() =>
+      useEditorWikiLinkShortcuts({ editor, focusInputBar, convertSelectionToWikiLink }),
+    );
+
+    const event = dispatchKeyDown({ key: "k", metaKey: true, isComposing: true });
+    const event2 = dispatchKeyDown({ key: "L", metaKey: true, shiftKey: true, isComposing: true });
+
+    expect(focusInputBar).not.toHaveBeenCalled();
+    expect(convertSelectionToWikiLink).not.toHaveBeenCalled();
+    expect(event.defaultPrevented).toBe(false);
+    expect(event2.defaultPrevented).toBe(false);
+  });
+
+  it("unmount でリスナーが解除される / removes the document listener on unmount", () => {
+    const editor = createMockEditor({ isFocused: true });
+    const { unmount } = renderHook(() =>
+      useEditorWikiLinkShortcuts({ editor, focusInputBar, convertSelectionToWikiLink }),
+    );
+
+    unmount();
+
+    const event = dispatchKeyDown({ key: "k", metaKey: true });
+
+    expect(focusInputBar).not.toHaveBeenCalled();
+    expect(event.defaultPrevented).toBe(false);
+  });
+
+  it("後から登録された bubble phase リスナーより先に走り、event 伝播を止める / runs before later-registered bubble-phase listeners and stops propagation so they do not fire (issue #928 collision guard)", () => {
+    const editor = createMockEditor({ isFocused: true });
+    const laterBubbleListener = vi.fn();
+
+    renderHook(() =>
+      useEditorWikiLinkShortcuts({ editor, focusInputBar, convertSelectionToWikiLink }),
+    );
+    // capture phase 登録の後に追加された bubble phase リスナーは、capture が
+    // stopPropagation を呼んだら呼ばれない。これにより `useGlobalSearchShortcut`
+    // のような既存の document リスナーをエディタ側が優先できる。
+    // A bubble-phase listener registered after the hook should not fire when
+    // the hook's capture handler stops propagation — this is what lets the
+    // editor shortcut preempt the global search shortcut.
+    document.addEventListener("keydown", laterBubbleListener);
+
+    try {
+      act(() => {
+        dispatchKeyDown({ key: "k", metaKey: true });
+      });
+
+      expect(focusInputBar).toHaveBeenCalledTimes(1);
+      expect(laterBubbleListener).not.toHaveBeenCalled();
+    } finally {
+      document.removeEventListener("keydown", laterBubbleListener);
+    }
+  });
+});
diff --git a/src/hooks/useEditorWikiLinkShortcuts.ts b/src/hooks/useEditorWikiLinkShortcuts.ts
new file mode 100644
index 00000000..17dac114
--- /dev/null
+++ b/src/hooks/useEditorWikiLinkShortcuts.ts
@@ -0,0 +1,128 @@
+import { useEffect } from "react";
+import type { Editor } from "@tiptap/core";
+
+/**
+ * `useEditorWikiLinkShortcuts` のオプション。
+ *
+ * Options for {@link useEditorWikiLinkShortcuts}.
+ */
+export interface UseEditorWikiLinkShortcutsOptions {
+  /**
+   * 対象 Tiptap エディタ。`null` の間はショートカットを無効化する。
+   * The target Tiptap editor; shortcuts are disabled while it is `null`.
+   */
+  editor: Editor | null;
+  /**
+   * `Cmd/Ctrl+K` 時に Wiki Link 入力バーへフォーカスを移すコールバック。
+   * 入力バーが自身の `onFocus` でエディタの選択位置を退避するため、ここでは
+   * 「フォーカスを移す」だけ実装すれば十分。
+   *
+   * Callback invoked on `Cmd/Ctrl+K` that focuses the Wiki Link input bar.
+   * The bar itself snapshots the editor selection in its own `onFocus`, so
+   * this only needs to move focus.
+   */
+  focusInputBar: () => void;
+  /**
+   * `Cmd/Ctrl+Shift+L` 時に現在の選択範囲を `[[Title]]` の Wiki Link に
+   * 変換する非同期コールバック。実体は通常
+   * `useBubbleMenuWikiLink({editor, pageId}).convertToWikiLink` を渡す。
+   *
+   * Async callback that converts the current editor selection into a
+   * `[[Title]]` wiki link on `Cmd/Ctrl+Shift+L`. Typically wired to
+   * `useBubbleMenuWikiLink({editor, pageId}).convertToWikiLink`.
+   */
+  convertSelectionToWikiLink: () => Promise<void>;
+  /**
+   * true の間は両ショートカットを無効化する。
+   * Disables both shortcuts while true.
+   */
+  isReadOnly?: boolean;
+}
+
+/**
+ * デスクトップ向けのエディタショートカットを登録するフック（issue #928）。
+ *
+ * - `Cmd/Ctrl + K`: エディタフォーカス時に Wiki Link 入力バーへフォーカス。
+ * - `Cmd/Ctrl + Shift + L`: エディタフォーカスかつ非空選択時に選択範囲を
+ *   即 Wiki Link 化（空選択時は no-op）。
+ *
+ * 既存のグローバル検索（`useGlobalSearchShortcut`）および Tiptap `Link` 拡張の
+ * `Mod-k` と衝突するため、リスナーは **capture phase** で登録し、消費時に
+ * `preventDefault()` + `stopPropagation()` を呼ぶ。これによりエディタ
+ * フォーカス時はエディタ側ハンドラが先に処理し、`useGlobalSearchShortcut`
+ * 側は `defaultPrevented` を見て早期 return する契約となる。
+ *
+ * Desktop Wiki Link shortcut hook (issue #928):
+ *
+ * - `Cmd/Ctrl + K` focuses the Wiki Link input bar while the editor is
+ *   focused.
+ * - `Cmd/Ctrl + Shift + L` converts the current editor selection into a
+ *   `[[Title]]` wiki link (no-op on empty selection).
+ *
+ * Listener is attached in the **capture phase** so it preempts the
+ * document-level global search shortcut and the Tiptap `Link` extension's
+ * `Mod-k` keymap. When consumed, the handler calls `preventDefault()` and
+ * `stopPropagation()`; `useGlobalSearchShortcut` cooperates by bailing out
+ * when `defaultPrevented` is already true.
+ */
+export function useEditorWikiLinkShortcuts({
+  editor,
+  focusInputBar,
+  convertSelectionToWikiLink,
+  isReadOnly,
+}: UseEditorWikiLinkShortcutsOptions): void {
+  useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      // IME 変換中はキー入力をフックしない（日本語等）。
+      // Don't intercept while an IME composition is in progress (CJK input).
+      if (event.isComposing) return;
+      // Alt 併用は別ショートカット領域に予約する。
+      // Reserve Alt-modified combinations for other shortcuts.
+      if (event.altKey) return;
+      if (!editor || !editor.isEditable || isReadOnly) return;
+      if (!editor.isFocused) return;
+
+      const mod = event.metaKey || event.ctrlKey;
+      if (!mod) return;
+
+      // Caps Lock 等で `event.key` が大文字になっても拾えるよう `toLowerCase()`
+      // で正規化する（Codex P2: Caps Lock 中の `Cmd+K` が無視されていた問題）。
+      // Normalize case so Caps Lock-uppercased `event.key` still matches
+      // (Codex P2: previously Cmd+K was skipped while Caps Lock was on).
+      const normalizedKey = event.key.toLowerCase();
+
+      // Cmd/Ctrl + K (Shift 無し) → 入力バーへフォーカス。
+      // Cmd/Ctrl + K (no Shift) → focus the Wiki Link input bar.
+      if (!event.shiftKey && normalizedKey === "k") {
+        event.preventDefault();
+        event.stopPropagation();
+        focusInputBar();
+        return;
+      }
+
+      // Cmd/Ctrl + Shift + L → 選択範囲を Wiki Link 化。
+      // Cmd/Ctrl + Shift + L → convert selection to wiki link.
+      if (event.shiftKey && normalizedKey === "l") {
+        const { from, to } = editor.state.selection;
+        // 空選択は no-op、preventDefault も呼ばない（受け入れ条件）。
+        // Empty selection is a no-op; do not even preventDefault (issue #928 AC).
+        if (from === to) return;
+        event.preventDefault();
+        event.stopPropagation();
+        // 非同期処理の rejection はログだけ取る。document の keydown ハンドラ
+        // 経由で unhandled rejection を出さないための防御（CodeRabbit / Gemini）。
+        // Swallow rejections after logging; prevents unhandled promise
+        // rejections from leaking out of the document keydown handler
+        // (CodeRabbit / Gemini review).
+        void convertSelectionToWikiLink().catch((error: unknown) => {
+          console.error("[useEditorWikiLinkShortcuts] convertSelectionToWikiLink failed", error);
+        });
+      }
+    };
+
+    document.addEventListener("keydown", handleKeyDown, true);
+    return () => {
+      document.removeEventListener("keydown", handleKeyDown, true);
+    };
+  }, [editor, focusInputBar, convertSelectionToWikiLink, isReadOnly]);
+}
diff --git a/src/hooks/useGlobalSearchShortcut.test.ts b/src/hooks/useGlobalSearchShortcut.test.ts
new file mode 100644
index 00000000..7b2a4713
--- /dev/null
+++ b/src/hooks/useGlobalSearchShortcut.test.ts
@@ -0,0 +1,91 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { useGlobalSearchShortcut } from "./useGlobalSearchShortcut";
+
+/**
+ * `KeyboardEvent` を dispatch するヘルパー。`cancelable: true` を必ず付け、
+ * `preventDefault` がフラグに反映されるようにする。
+ *
+ * Dispatch helper that always sets `cancelable: true` so `preventDefault`
+ * reflects on the returned event.
+ */
+function dispatchKeyDown(init: KeyboardEventInit & { key: string }): KeyboardEvent {
+  const event = new KeyboardEvent("keydown", {
+    bubbles: true,
+    cancelable: true,
+    ...init,
+  });
+  document.dispatchEvent(event);
+  return event;
+}
+
+describe("useGlobalSearchShortcut", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("Cmd+K で onOpen を呼び preventDefault する / triggers onOpen on Cmd+K with preventDefault", () => {
+    const onOpen = vi.fn();
+    renderHook(() => useGlobalSearchShortcut(onOpen));
+
+    const event = dispatchKeyDown({ key: "k", metaKey: true });
+
+    expect(onOpen).toHaveBeenCalledTimes(1);
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it("Ctrl+K でも動く / also triggers on Ctrl+K", () => {
+    const onOpen = vi.fn();
+    renderHook(() => useGlobalSearchShortcut(onOpen));
+
+    const event = dispatchKeyDown({ key: "k", ctrlKey: true });
+
+    expect(onOpen).toHaveBeenCalledTimes(1);
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it("他のリスナーが capture phase で preventDefault 済みなら onOpen を呼ばない / does not fire onOpen when an earlier capture-phase listener already preventDefault'd (issue #928)", () => {
+    const onOpen = vi.fn();
+    // 先に capture phase のリスナーを登録して preventDefault を発生させる。
+    // これにより、エディタ側ショートカット（capture phase で登録される
+    // useEditorWikiLinkShortcuts）が Cmd+K を消費した場合のグローバル検索の
+    // 抑制契約を担保する。
+    // Register a capture-phase listener that preventDefault's first to model
+    // the editor shortcut. This pins the contract that the global search
+    // bows out when the editor consumed the event (issue #928).
+    const capturePreventer = (e: Event) => {
+      e.preventDefault();
+    };
+    document.addEventListener("keydown", capturePreventer, true);
+
+    try {
+      renderHook(() => useGlobalSearchShortcut(onOpen));
+
+      dispatchKeyDown({ key: "k", metaKey: true });
+
+      expect(onOpen).not.toHaveBeenCalled();
+    } finally {
+      document.removeEventListener("keydown", capturePreventer, true);
+    }
+  });
+
+  it("修飾キー無しの 'k' では発火しない / ignores plain 'k' without modifier", () => {
+    const onOpen = vi.fn();
+    renderHook(() => useGlobalSearchShortcut(onOpen));
+
+    const event = dispatchKeyDown({ key: "k" });
+
+    expect(onOpen).not.toHaveBeenCalled();
+    expect(event.defaultPrevented).toBe(false);
+  });
+
+  it("unmount でリスナーが解除される / removes the listener on unmount", () => {
+    const onOpen = vi.fn();
+    const { unmount } = renderHook(() => useGlobalSearchShortcut(onOpen));
+
+    unmount();
+    dispatchKeyDown({ key: "k", metaKey: true });
+
+    expect(onOpen).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/hooks/useGlobalSearchShortcut.ts b/src/hooks/useGlobalSearchShortcut.ts
index 73a5254d..aaa28102 100644
--- a/src/hooks/useGlobalSearchShortcut.ts
+++ b/src/hooks/useGlobalSearchShortcut.ts
@@ -1,18 +1,35 @@
 import { useEffect } from "react";
 
 /**
- * Hook to handle global keyboard shortcut for opening search
- * Cmd+K on Mac, Ctrl+K on Windows/Linux
+ * グローバル検索を `Cmd/Ctrl + K` で開くショートカット。
+ *
+ * Hook to handle global keyboard shortcut for opening search.
+ * Cmd+K on Mac, Ctrl+K on Windows/Linux.
+ *
+ * 衝突契約 / collision contract:
+ * - エディタ用 `useEditorWikiLinkShortcuts` が capture phase で `Cmd+K` を
+ *   消費する場合、こちらは bubble phase で `event.defaultPrevented` を
+ *   見て早期 return する（issue #928）。これによりエディタフォーカス時は
+ *   入力バーが優先され、それ以外ではグローバル検索が動く。
+ * - When `useEditorWikiLinkShortcuts` (capture phase) consumes `Cmd+K`
+ *   inside a focused editor, this bubble-phase handler bails out via
+ *   `event.defaultPrevented` (issue #928). Result: editor-focused → focus
+ *   the Wiki Link input bar; otherwise → open global search.
+ *
  * @param onOpen - Callback function when shortcut is triggered
  */
 export function useGlobalSearchShortcut(onOpen: () => void) {
   useEffect(() => {
     const handleKeyDown = (e: KeyboardEvent) => {
       // Cmd+K (Mac) or Ctrl+K (Windows/Linux)
-      if ((e.metaKey || e.ctrlKey) && e.key === "k") {
-        e.preventDefault();
-        onOpen();
-      }
+      if (!((e.metaKey || e.ctrlKey) && e.key === "k")) return;
+      // capture phase の他リスナー（エディタショートカット等）が消費済みなら
+      // グローバル検索は呼ばない（issue #928 の衝突回避）。
+      // Skip when an earlier capture-phase listener already consumed the
+      // event (issue #928 collision guard).
+      if (e.defaultPrevented) return;
+      e.preventDefault();
+      onOpen();
     };
 
     document.addEventListener("keydown", handleKeyDown);
diff --git a/src/hooks/useVirtualKeyboardOffset.test.ts b/src/hooks/useVirtualKeyboardOffset.test.ts
new file mode 100644
index 00000000..f1da46ad
--- /dev/null
+++ b/src/hooks/useVirtualKeyboardOffset.test.ts
@@ -0,0 +1,189 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { act, renderHook } from "@testing-library/react";
+import { useVirtualKeyboardOffset } from "./useVirtualKeyboardOffset";
+
+/**
+ * `window.visualViewport` のモック。jsdom には未実装のため、テストの中で
+ * 手動でリスナーを発火させてキーボード表示・非表示の遷移を再現する。
+ *
+ * Mock helper for `window.visualViewport` because jsdom does not implement
+ * the API. Tests use `setMetrics` + `fire` to simulate keyboard show/hide.
+ */
+interface MockVisualViewport {
+  height: number;
+  offsetTop: number;
+  width: number;
+  scale: number;
+  pageLeft: number;
+  pageTop: number;
+  offsetLeft: number;
+  addEventListener: ReturnType<typeof vi.fn>;
+  removeEventListener: ReturnType<typeof vi.fn>;
+  dispatchEvent: ReturnType<typeof vi.fn>;
+}
+
+function installMockVisualViewport(): {
+  vv: MockVisualViewport;
+  listeners: Map<string, Set<EventListener>>;
+  fire: (type: string) => void;
+  setMetrics: (next: { height: number; offsetTop?: number }) => void;
+  restore: () => void;
+} {
+  const listeners = new Map<string, Set<EventListener>>();
+  const vv: MockVisualViewport = {
+    height: 800,
+    offsetTop: 0,
+    width: 400,
+    scale: 1,
+    pageLeft: 0,
+    pageTop: 0,
+    offsetLeft: 0,
+    addEventListener: vi.fn((type: string, cb: EventListener) => {
+      let set = listeners.get(type);
+      if (!set) {
+        set = new Set();
+        listeners.set(type, set);
+      }
+      set.add(cb);
+    }),
+    removeEventListener: vi.fn((type: string, cb: EventListener) => {
+      listeners.get(type)?.delete(cb);
+    }),
+    dispatchEvent: vi.fn(),
+  };
+  const originalDescriptor = Object.getOwnPropertyDescriptor(window, "visualViewport");
+  Object.defineProperty(window, "visualViewport", {
+    configurable: true,
+    value: vv,
+  });
+  const originalInnerHeight = window.innerHeight;
+  Object.defineProperty(window, "innerHeight", {
+    configurable: true,
+    value: 800,
+  });
+  return {
+    vv,
+    listeners,
+    fire: (type: string) => {
+      const set = listeners.get(type);
+      if (!set) return;
+      for (const cb of set) cb(new Event(type));
+    },
+    setMetrics: ({ height, offsetTop = 0 }) => {
+      vv.height = height;
+      vv.offsetTop = offsetTop;
+    },
+    restore: () => {
+      if (originalDescriptor) {
+        Object.defineProperty(window, "visualViewport", originalDescriptor);
+      } else {
+        // jsdom の既定では visualViewport プロパティ自体が無いので削除する。
+        // jsdom has no default `visualViewport`, so drop the property when restoring.
+        delete (window as unknown as { visualViewport?: unknown }).visualViewport;
+      }
+      Object.defineProperty(window, "innerHeight", {
+        configurable: true,
+        value: originalInnerHeight,
+      });
+    },
+  };
+}
+
+describe("useVirtualKeyboardOffset", () => {
+  let env: ReturnType<typeof installMockVisualViewport>;
+
+  beforeEach(() => {
+    env = installMockVisualViewport();
+  });
+
+  afterEach(() => {
+    env.restore();
+  });
+
+  it("active=false ではリスナーを登録せずオフセットは 0 を返す / does not attach listeners and returns 0 when inactive", () => {
+    const { result } = renderHook(() => useVirtualKeyboardOffset(false));
+    expect(result.current).toBe(0);
+    expect(env.vv.addEventListener).not.toHaveBeenCalled();
+  });
+
+  it("active=true で resize / scroll リスナーを登録する / attaches resize + scroll listeners while active", () => {
+    renderHook(() => useVirtualKeyboardOffset(true));
+    expect(env.vv.addEventListener).toHaveBeenCalledWith("resize", expect.any(Function));
+    expect(env.vv.addEventListener).toHaveBeenCalledWith("scroll", expect.any(Function));
+  });
+
+  it("初期マウント時に visualViewport の現在値からオフセットを計算する / computes initial offset from visualViewport on mount", () => {
+    // キーボードが既に表示されている状態（800 − 500 = 300px）で active=true になる場合。
+    // The keyboard is already up when the hook activates (800 − 500 = 300px gap).
+    env.setMetrics({ height: 500 });
+    const { result } = renderHook(() => useVirtualKeyboardOffset(true));
+    expect(result.current).toBe(300);
+  });
+
+  it("resize イベントでキーボード高さが更新される / updates offset when resize fires", () => {
+    const { result } = renderHook(() => useVirtualKeyboardOffset(true));
+    expect(result.current).toBe(0);
+    act(() => {
+      env.setMetrics({ height: 460 });
+      env.fire("resize");
+    });
+    expect(result.current).toBe(340);
+  });
+
+  it("offsetTop を引いて純粋なキーボード高さだけを返す / subtracts offsetTop so the value is purely keyboard height", () => {
+    const { result } = renderHook(() => useVirtualKeyboardOffset(true));
+    act(() => {
+      // 例: iOS でピンチズーム + スクロール状態。height 600, offsetTop 50, layout 800
+      // → キーボードは 800 - 600 - 50 = 150px。
+      // Example: iOS pinch-zoomed and scrolled. The bottom inset is
+      // `innerHeight - vv.height - vv.offsetTop = 150`.
+      env.setMetrics({ height: 600, offsetTop: 50 });
+      env.fire("resize");
+    });
+    expect(result.current).toBe(150);
+  });
+
+  it("計算結果が負になっても 0 にクランプする / clamps negative results to 0 (e.g. layout viewport shrank itself on Android)", () => {
+    const { result } = renderHook(() => useVirtualKeyboardOffset(true));
+    act(() => {
+      // Android Chrome のデフォルトでは window.innerHeight も縮むため、
+      // visualViewport.height のほうが大きく見えることがある。
+      // On Android Chrome with default resize behavior, `window.innerHeight`
+      // can shrink to match or exceed `visualViewport.height`.
+      env.setMetrics({ height: 820 });
+      env.fire("resize");
+    });
+    expect(result.current).toBe(0);
+  });
+
+  it("active=true → false でリスナーを解除しオフセットを 0 に戻す / unregisters listeners and resets to 0 when active flips false", () => {
+    env.setMetrics({ height: 500 });
+    const { result, rerender } = renderHook(
+      ({ active }: { active: boolean }) => useVirtualKeyboardOffset(active),
+      { initialProps: { active: true } },
+    );
+    expect(result.current).toBe(300);
+
+    rerender({ active: false });
+    expect(result.current).toBe(0);
+    expect(env.vv.removeEventListener).toHaveBeenCalledWith("resize", expect.any(Function));
+    expect(env.vv.removeEventListener).toHaveBeenCalledWith("scroll", expect.any(Function));
+  });
+
+  it("unmount でリスナーを解除する / removes listeners on unmount", () => {
+    const { unmount } = renderHook(() => useVirtualKeyboardOffset(true));
+    unmount();
+    expect(env.vv.removeEventListener).toHaveBeenCalledWith("resize", expect.any(Function));
+    expect(env.vv.removeEventListener).toHaveBeenCalledWith("scroll", expect.any(Function));
+  });
+
+  it("visualViewport が未定義の環境では 0 のまま落ちない / stays at 0 without throwing when visualViewport is unavailable", () => {
+    env.restore();
+    Object.defineProperty(window, "visualViewport", {
+      configurable: true,
+      value: undefined,
+    });
+    const { result } = renderHook(() => useVirtualKeyboardOffset(true));
+    expect(result.current).toBe(0);
+  });
+});
diff --git a/src/hooks/useVirtualKeyboardOffset.ts b/src/hooks/useVirtualKeyboardOffset.ts
new file mode 100644
index 00000000..90235009
--- /dev/null
+++ b/src/hooks/useVirtualKeyboardOffset.ts
@@ -0,0 +1,70 @@
+import { useCallback, useSyncExternalStore } from "react";
+
+/**
+ * 仮想キーボードがレイアウトビューポートの下部に作るインセット（px）を返す
+ * フック。`active` が `true` の間だけ `visualViewport` のリスナーを登録し、
+ * `false` または unmount で解除する（issue #927 「focus/blur で update リスナー
+ * 登録解除」）。
+ *
+ * iOS Safari は仮想キーボード表示時に `window.innerHeight` が変わらず
+ * `visualViewport.height` だけが縮むため、その差分（さらに `offsetTop` を
+ * 引いたもの）が「キーボードに覆われた高さ」になる。Android Chrome の既定は
+ * レイアウトビューポート自体がリサイズされ差分が 0 付近になるので、CSS の
+ * `position: fixed; bottom: 0;` がそのまま追従する。本フックはどちらの環境
+ * でも安全に 0 以上の値を返す。
+ *
+ * Returns the bottom inset (px) that the on-screen keyboard takes from the
+ * layout viewport. Listeners are only attached while `active` is `true`,
+ * satisfying #927's "register on focus / unregister on blur" requirement.
+ *
+ * On iOS Safari the layout viewport height (`window.innerHeight`) stays
+ * constant while `visualViewport.height` shrinks, so
+ * `innerHeight − vv.height − vv.offsetTop` is the keyboard-covered area.
+ * Android Chrome's default behaviour resizes the layout viewport itself, so
+ * the difference is ~0 and a plain `bottom: 0` already tracks the keyboard.
+ * The hook clamps to `0` so consumers can use the value unconditionally.
+ *
+ * @param active - リスナーを有効化するかどうか（通常は入力欄の focus 状態）。 / Whether to attach listeners (typically the input focus state).
+ * @returns キーボードによる下部インセット（px、無いときは 0）。 / Bottom inset in px (0 when no keyboard).
+ */
+export function useVirtualKeyboardOffset(active: boolean): number {
+  // `useSyncExternalStore` を使うことで「subscribe / unsubscribe」と
+  // 「現在値の読み出し」が React の規約通り分離でき、effect 内で setState
+  // する必要がなくなる（react-hooks/set-state-in-effect）。
+  // Using `useSyncExternalStore` keeps subscribe / read split per React's
+  // contract and avoids `setState` inside an effect body
+  // (react-hooks/set-state-in-effect).
+  const subscribe = useCallback(
+    (onChange: () => void) => {
+      if (!active || typeof window === "undefined") return noop;
+      const vv = window.visualViewport;
+      if (!vv) return noop;
+      vv.addEventListener("resize", onChange);
+      vv.addEventListener("scroll", onChange);
+      return () => {
+        vv.removeEventListener("resize", onChange);
+        vv.removeEventListener("scroll", onChange);
+      };
+    },
+    [active],
+  );
+
+  const getSnapshot = useCallback(() => {
+    if (!active || typeof window === "undefined") return 0;
+    const vv = window.visualViewport;
+    if (!vv) return 0;
+    return Math.max(0, window.innerHeight - vv.height - vv.offsetTop);
+  }, [active]);
+
+  // SSR は常に 0（キーボードは存在しない）。
+  // SSR snapshot is always 0 — no virtual keyboard outside the browser.
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+
+function noop(): void {
+  // no-op cleanup used while inactive / when visualViewport is unsupported.
+}
+
+function getServerSnapshot(): number {
+  return 0;
+}
diff --git a/src/hooks/useWikiComposeSession.test.ts b/src/hooks/useWikiComposeSession.test.ts
new file mode 100644
index 00000000..dec5b178
--- /dev/null
+++ b/src/hooks/useWikiComposeSession.test.ts
@@ -0,0 +1,387 @@
+/**
+ * `useWikiComposeSession` ユニットテスト (#950)。
+ *
+ * SSE 経由のイベント反映と、resume API 呼び出し時の state machine 進行を
+ * 検証する。実 fetch を叩かないよう `composeService` をモック差し替えする。
+ *
+ * Pins the state-machine reductions: each compose SSE event must produce the
+ * correct slice of state, and submit/* mutators must call the right
+ * `composeService` function with the right payload.
+ */
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { act, renderHook, waitFor } from "@testing-library/react";
+
+const mocks = vi.hoisted(() => ({
+  createSession: vi.fn(),
+  getSession: vi.fn(),
+  runSession: vi.fn(),
+  resumeSession: vi.fn(),
+  cancelSession: vi.fn(),
+}));
+
+vi.mock("@/lib/wikiCompose/composeService", () => ({
+  createSession: mocks.createSession,
+  getSession: mocks.getSession,
+  runSession: mocks.runSession,
+  resumeSession: mocks.resumeSession,
+  cancelSession: mocks.cancelSession,
+}));
+
+import { useWikiComposeSession } from "./useWikiComposeSession";
+import type { ComposeSseEvent } from "@/lib/wikiCompose/types";
+
+const SESSION = {
+  id: "sess-1",
+  pageId: "page-1",
+  userId: "user-1",
+  graphId: "wiki-compose",
+  backend: "zedi_managed",
+  phase: "init",
+  status: "pending" as const,
+  metadata: null,
+  lastError: null,
+  closedAt: null,
+  createdAt: "2026-05-24T00:00:00Z",
+  updatedAt: "2026-05-24T00:00:00Z",
+};
+
+/**
+ * Helper that drives the hook's `onEvent` by configuring `runSession` to
+ * push a sequence of pre-made events.
+ */
+function arrangeRun(events: ComposeSseEvent[]): void {
+  mocks.runSession.mockImplementation(async ({ onEvent }) => {
+    for (const e of events) await onEvent(e);
+  });
+}
+
+describe("useWikiComposeSession", () => {
+  beforeEach(() => {
+    mocks.createSession.mockReset();
+    mocks.getSession.mockReset();
+    mocks.runSession.mockReset();
+    mocks.resumeSession.mockReset();
+    mocks.cancelSession.mockReset();
+    mocks.createSession.mockResolvedValue(SESSION);
+  });
+
+  it("reduces a Brief interrupt into briefQuestions + pageSnapshot", async () => {
+    arrangeRun([
+      { type: "started", sessionId: SESSION.id, graphId: SESSION.graphId },
+      { type: "compose_phase", phase: "brief", status: "entered" },
+      {
+        type: "interrupt",
+        payload: {
+          kind: "human_review_brief",
+          questions: [
+            {
+              id: "q1",
+              question: "Scope?",
+              required: false,
+              options: [{ id: "o1", label: "broad" }],
+            },
+          ],
+          pageSnapshot: { pageId: "page-1", title: "T", body: "", hasContent: false },
+        },
+      },
+      { type: "done", status: "interrupted" },
+    ]);
+
+    const { result } = renderHook(() =>
+      useWikiComposeSession({ pageId: "page-1", sessionId: null }),
+    );
+
+    await waitFor(() => expect(result.current.briefQuestions.length).toBeGreaterThan(0));
+    expect(result.current.phase).toBe("brief");
+    const firstQuestion = result.current.briefQuestions[0];
+    expect(firstQuestion?.question).toBe("Scope?");
+    expect(result.current.pageSnapshot?.title).toBe("T");
+    expect(result.current.status).toBe("interrupted");
+  });
+
+  it("appends tokens to the active streaming section buffer", async () => {
+    arrangeRun([
+      { type: "started", sessionId: SESSION.id, graphId: SESSION.graphId },
+      {
+        type: "compose_section",
+        sectionId: "sec-1",
+        heading: "Overview",
+        status: "started",
+        index: 1,
+        total: 2,
+      },
+      { type: "token", node: "draft_sections", content: "Hello " },
+      { type: "token", node: "draft_sections", content: "world." },
+      {
+        type: "compose_section",
+        sectionId: "sec-1",
+        heading: "Overview",
+        status: "completed",
+        index: 1,
+        total: 2,
+      },
+      { type: "done", status: "completed" },
+    ]);
+
+    const { result } = renderHook(() =>
+      useWikiComposeSession({ pageId: "page-1", sessionId: null }),
+    );
+
+    await waitFor(() => expect(result.current.status).toBe("completed"));
+    expect(result.current.sectionBuffers["sec-1"]).toBe("Hello world.");
+    expect(result.current.streamingSectionId).toBeNull();
+  });
+
+  it("submitOutline hydrates completion from PATCH resume output without POST /run", async () => {
+    arrangeRun([
+      { type: "started", sessionId: SESSION.id, graphId: SESSION.graphId },
+      { type: "done", status: "interrupted" },
+    ]);
+    mocks.resumeSession.mockResolvedValue({
+      status: "completed",
+      output: {
+        completion: {
+          markdown: "## Overview\n\nBody one\n\n## Details\n\nBody two\n",
+          sections: [
+            {
+              sectionId: "sec-1",
+              heading: "Overview",
+              body: "Body one",
+              citedSourceIds: [],
+              completedAt: "2026-05-24T00:00:00Z",
+            },
+            {
+              sectionId: "sec-2",
+              heading: "Details",
+              body: "Body two",
+              citedSourceIds: [],
+              completedAt: "2026-05-24T00:00:01Z",
+            },
+          ],
+          citedSources: [],
+          completedAt: "2026-05-24T00:00:02Z",
+        },
+        approvedOutline: {
+          sections: [
+            { id: "sec-1", heading: "Overview", depth: 1, intent: "intro" },
+            { id: "sec-2", heading: "Details", depth: 1, intent: "deep" },
+          ],
+        },
+      },
+    });
+
+    const { result } = renderHook(() =>
+      useWikiComposeSession({ pageId: "page-1", sessionId: null }),
+    );
+    await waitFor(() => expect(result.current.session).not.toBeNull());
+
+    await act(async () => {
+      await result.current.submitOutline({
+        sections: [
+          { id: "sec-1", heading: "Overview", depth: 1, intent: "intro" },
+          { id: "sec-2", heading: "Details", depth: 1, intent: "deep" },
+        ],
+      });
+    });
+
+    expect(mocks.runSession).toHaveBeenCalledTimes(1);
+    await waitFor(() => expect(result.current.status).toBe("completed"));
+    expect(result.current.completedMarkdown).toContain("Body one");
+    expect(result.current.draftedSections["sec-1"]?.body).toBe("Body one");
+    expect(result.current.phase).toBe("completed");
+  });
+
+  it("submitResearchApproval stops at conflict_resolution without POST /run", async () => {
+    arrangeRun([
+      { type: "started", sessionId: SESSION.id, graphId: SESSION.graphId },
+      { type: "done", status: "interrupted" },
+    ]);
+    mocks.resumeSession.mockResolvedValue({
+      status: "interrupted",
+      output: {
+        __interrupt__: [
+          {
+            value: {
+              kind: "conflict_resolution",
+              conflicts: {
+                approved: [{ id: "src:a", title: "A" }],
+                rejected: [
+                  { id: "src:b", title: "B" },
+                  { id: "src:c", title: "C" },
+                ],
+                rationale: "Confirm approved set.",
+              },
+            },
+          },
+        ],
+      },
+    });
+
+    const { result } = renderHook(() =>
+      useWikiComposeSession({ pageId: "page-1", sessionId: null }),
+    );
+    await waitFor(() => expect(result.current.session).not.toBeNull());
+
+    await act(async () => {
+      await result.current.submitResearchApproval({
+        approvedSourceIds: ["src:a"],
+        rejectedSourceIds: ["src:b", "src:c"],
+      });
+    });
+
+    expect(mocks.runSession).toHaveBeenCalledTimes(1);
+    expect(result.current.researchConflictSummary?.approved).toHaveLength(1);
+    expect(result.current.phase).toBe("conflict");
+  });
+
+  it("submitBrief applies research interrupt from PATCH output without POST /run", async () => {
+    arrangeRun([
+      { type: "started", sessionId: SESSION.id, graphId: SESSION.graphId },
+      { type: "done", status: "interrupted" },
+    ]);
+    mocks.resumeSession.mockResolvedValue({
+      status: "interrupted",
+      output: {
+        __interrupt__: [
+          {
+            value: {
+              kind: "human_review_research",
+              batch: {
+                id: "batch-1",
+                iteration: 0,
+                sources: [],
+                createdAt: "2026-05-24T00:00:00Z",
+              },
+              pendingSources: [
+                {
+                  id: "src-1",
+                  kind: "web",
+                  title: "Example",
+                  url: "https://example.com",
+                },
+              ],
+            },
+          },
+        ],
+      },
+    });
+
+    const { result } = renderHook(() =>
+      useWikiComposeSession({ pageId: "page-1", sessionId: null }),
+    );
+    await waitFor(() => expect(result.current.session).not.toBeNull());
+
+    await act(async () => {
+      await result.current.submitBrief({ answers: [], appendToExisting: false });
+    });
+
+    expect(mocks.runSession).toHaveBeenCalledTimes(1);
+    await waitFor(() => expect(result.current.pendingSources).toHaveLength(1));
+    expect(result.current.pendingSources[0]?.id).toBe("src-1");
+    expect(result.current.phase).toBe("research");
+  });
+
+  it("ignores malformed metadata.composeSeed when building run input", async () => {
+    mocks.createSession.mockResolvedValue({
+      ...SESSION,
+      metadata: { composeSeed: { outline: 1, conversationText: true } },
+    });
+    arrangeRun([{ type: "done", status: "completed" }]);
+
+    const { result } = renderHook(() =>
+      useWikiComposeSession({ pageId: "page-1", sessionId: null }),
+    );
+    await waitFor(() => expect(result.current.session).not.toBeNull());
+
+    expect(mocks.runSession).toHaveBeenCalledWith(
+      expect.objectContaining({
+        body: undefined,
+      }),
+    );
+  });
+
+  it("hydrates interrupted session from GET projection without POST /run", async () => {
+    mocks.createSession.mockReset();
+    mocks.getSession.mockResolvedValue({
+      session: { ...SESSION, status: "interrupted", phase: "brief:await_user" },
+      projection: {
+        phase: "brief",
+        briefQuestions: [
+          {
+            id: "q1",
+            question: "Reloaded?",
+            required: false,
+            options: [],
+          },
+        ],
+        pageSnapshot: { pageId: "page-1", title: "T", body: "", hasContent: false },
+      },
+    });
+
+    const { result } = renderHook(() =>
+      useWikiComposeSession({ pageId: "page-1", sessionId: "sess-1" }),
+    );
+
+    await waitFor(() => expect(result.current.briefQuestions).toHaveLength(1));
+    expect(result.current.briefQuestions[0]?.question).toBe("Reloaded?");
+    expect(mocks.runSession).not.toHaveBeenCalled();
+  });
+
+  it("submitBrief calls resumeSession with the answer payload and re-streams", async () => {
+    // Initial run: halt at Brief.
+    arrangeRun([
+      { type: "started", sessionId: SESSION.id, graphId: SESSION.graphId },
+      { type: "done", status: "interrupted" },
+    ]);
+    mocks.resumeSession.mockResolvedValue({ status: "interrupted", output: null });
+
+    const { result } = renderHook(() =>
+      useWikiComposeSession({ pageId: "page-1", sessionId: null }),
+    );
+    await waitFor(() => expect(result.current.session).not.toBeNull());
+
+    await act(async () => {
+      await result.current.submitBrief({ answers: [], appendToExisting: false });
+    });
+
+    expect(mocks.resumeSession).toHaveBeenCalledWith(
+      expect.objectContaining({
+        pageId: "page-1",
+        sessionId: "sess-1",
+        resume: { answers: [], appendToExisting: false },
+      }),
+    );
+  });
+
+  it("retries a failed session with chatSeed from row metadata when initialInput is absent", async () => {
+    mocks.getSession.mockResolvedValue({
+      session: {
+        ...SESSION,
+        status: "failed",
+        metadata: {
+          composeSeed: {
+            outline: "- topic",
+            conversationText: "User: seed me",
+          },
+        },
+      },
+      projection: {},
+    });
+    arrangeRun([{ type: "done", status: "failed" }]);
+
+    renderHook(() => useWikiComposeSession({ pageId: "page-1", sessionId: "sess-1" }));
+
+    await waitFor(() => expect(mocks.runSession).toHaveBeenCalled());
+    expect(mocks.createSession).not.toHaveBeenCalled();
+    expect(mocks.runSession).toHaveBeenCalledWith(
+      expect.objectContaining({
+        body: {
+          chatSeed: {
+            outline: "- topic",
+            conversationText: "User: seed me",
+          },
+        },
+      }),
+    );
+  });
+});
diff --git a/src/hooks/useWikiComposeSession.ts b/src/hooks/useWikiComposeSession.ts
new file mode 100644
index 00000000..fe8f3169
--- /dev/null
+++ b/src/hooks/useWikiComposeSession.ts
@@ -0,0 +1,751 @@
+/**
+ * `useWikiComposeSession` — React state machine for one Wiki Compose session
+ * (#950).
+ *
+ * Compose 1 セッションのフロント側 state machine。SSE で来るイベントを
+ * pattern match し、Brief 質問 / 調査バッチ / アウトライン / セクション本文
+ * といったフェーズ固有の slice を再アセンブルする。`WikiComposePage` は本
+ * フックの戻り値を読みつつ、`submitBrief` / `submitResearchApproval` /
+ * `submitOutline` を呼ぶことで graph を次フェーズへ進める。
+ *
+ * Owns the wire-level wiring; UI components stay pure. Critically, the hook
+ * does NOT navigate or persist — it only reflects what the SSE stream says.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  cancelSession,
+  createSession,
+  getSession,
+  resumeSession,
+  runSession,
+} from "@/lib/wikiCompose/composeService";
+import type { ComposeExecutionBackend } from "@/lib/wikiCompose/backends";
+import type { ComposeNavigationSeed } from "@/lib/wikiCompose/navigation";
+import type {
+  BriefAnswer,
+  BriefQuestion,
+  ComposeInterruptPayload,
+  ComposeSession,
+  ComposeSessionStatus,
+  ComposeSessionUiProjection,
+  ComposeSseEvent,
+  DraftedSection,
+  OutlineSection,
+  PageSnapshot,
+  ResearchBatch,
+  ResearchConflictSummary,
+  ResearchSource,
+} from "@/lib/wikiCompose/types";
+
+/**
+ * UI phase for Wiki Compose session progression.
+ * Wiki Compose セッション進行を表す UI フェーズ。
+ */
+export type ComposePhase = "brief" | "research" | "conflict" | "structure" | "draft" | "completed";
+
+/** Activity log entry surfaced in the right pane's ActivitySection. */
+export interface ComposeActivity {
+  id: string;
+  /** ISO timestamp. */
+  at: string;
+  /** Human-readable label for the activity row. */
+  label: string;
+  /** Optional secondary line (status, tool name, etc.). */
+  detail?: string;
+  /** Lifecycle hint so the UI can render spinners / checkmarks. */
+  status?: "started" | "completed" | "info" | "error";
+}
+
+/** Aggregate state surfaced to the UI. */
+export interface WikiComposeSessionState {
+  session: ComposeSession | null;
+  status: ComposeSessionStatus | "idle";
+  phase: ComposePhase;
+  /** Brief phase question cards (from interrupt). */
+  briefQuestions: BriefQuestion[];
+  /** Page snapshot (loaded at session start). */
+  pageSnapshot: PageSnapshot | null;
+  /** Latest research batch from the human-review interrupt. */
+  latestBatch: ResearchBatch | null;
+  /** Pending sources at the research interrupt. */
+  pendingSources: ResearchSource[];
+  /** Approved sources after research resume. */
+  approvedSources: ResearchSource[];
+  /** P5 conflict-resolution interrupt payload (#953). */
+  researchConflictSummary: ResearchConflictSummary | null;
+  /** Proposed outline from the structure interrupt. */
+  outlineProposal: OutlineSection[];
+  /** Drafted section bodies — keyed by sectionId. */
+  draftedSections: Record<string, DraftedSection>;
+  /** While streaming a section, this id is set; null between sections. */
+  streamingSectionId: string | null;
+  /** Per-section running token buffer while the section is mid-stream. */
+  sectionBuffers: Record<string, string>;
+  /** Activity timeline (newest last). */
+  activity: ComposeActivity[];
+  /** Final markdown if the session completed. */
+  completedMarkdown: string | null;
+  /** Last error message (set on failure). */
+  error: string | null;
+  /** True while an SSE stream is open. */
+  isStreaming: boolean;
+}
+
+const INITIAL_STATE: WikiComposeSessionState = {
+  session: null,
+  status: "idle",
+  phase: "brief",
+  briefQuestions: [],
+  pageSnapshot: null,
+  latestBatch: null,
+  pendingSources: [],
+  approvedSources: [],
+  researchConflictSummary: null,
+  outlineProposal: [],
+  draftedSections: {},
+  streamingSectionId: null,
+  sectionBuffers: {},
+  activity: [],
+  completedMarkdown: null,
+  error: null,
+  isStreaming: false,
+};
+
+/** Args accepted by the hook. */
+export interface UseWikiComposeSessionArgs {
+  pageId: string;
+  /** Existing session to resume; pass `null` to create a fresh session on start. */
+  sessionId: string | null;
+  /**
+   * 初回 `POST /run` に渡す graph input（例: `chatSeed`）。
+   * Initial graph input for the first `POST /run` (e.g. `{ chatSeed }`).
+   */
+  initialInput?: Record<string, unknown>;
+  /**
+   * チャット由来 seed。セッション行 `metadata` にも保存する。
+   * Chat-origin seed; also persisted on the session row metadata.
+   */
+  composeSeed?: ComposeNavigationSeed;
+  /** Auto-start the first `run` when the session is created. Default `true`. */
+  autoStart?: boolean;
+  /**
+   * 実行 backend（セッション作成時に固定）。省略時は `zedi_managed`。
+   * Execution backend fixed at session create; defaults to `zedi_managed`.
+   */
+  backend?: ComposeExecutionBackend;
+}
+
+/** Hook return shape. */
+export interface UseWikiComposeSessionReturn extends WikiComposeSessionState {
+  /** Start a new session (or resume the existing one) and begin streaming. */
+  start: () => Promise<void>;
+  /** Submit Brief answers and continue streaming. */
+  submitBrief: (input: {
+    answers: BriefAnswer[];
+    appendToExisting?: boolean;
+    researchMaxIterations?: number;
+  }) => Promise<void>;
+  /** Submit research source approval (Approve/Reject) and continue streaming. */
+  submitResearchApproval: (input: {
+    approvedSourceIds: string[];
+    rejectedSourceIds?: string[];
+    note?: string;
+  }) => Promise<void>;
+  /** Submit outline approval and continue streaming. */
+  submitOutline: (input: { sections: OutlineSection[] }) => Promise<void>;
+  /**
+   * Acknowledge research conflicts and continue to Structure (#953).
+   * 調査の矛盾を確認し Structure へ進む（#953）。
+   */
+  submitConflictAck: (input?: { note?: string }) => Promise<void>;
+  /** Cancel the session (DELETE). */
+  cancel: () => Promise<void>;
+}
+
+/** First interrupt kind on a LangGraph checkpoint output, if any. */
+function interruptKindFromOutput(output: unknown): string | undefined {
+  if (!output || typeof output !== "object") return undefined;
+  const interrupts = (output as { __interrupt__?: unknown }).__interrupt__;
+  if (!Array.isArray(interrupts) || interrupts.length === 0) return undefined;
+  const entry = interrupts[0];
+  const value =
+    entry && typeof entry === "object" ? (entry as { value?: unknown }).value : undefined;
+  if (value && typeof value === "object" && "kind" in value) {
+    const kind = (value as { kind?: unknown }).kind;
+    return typeof kind === "string" ? kind : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Returns a unique id for an activity row. Uses crypto.randomUUID when
+ * available (modern browsers); falls back to a coarse fallback for old
+ * environments and SSR.
+ */
+/**
+ * `session.metadata.composeSeed` を型検証して graph input 用 seed にする。
+ * Validate persisted `metadata.composeSeed` before sending `/run` input.
+ */
+function parseComposeSeedFromMetadata(metadata: Record<string, unknown> | null | undefined):
+  | {
+      outline: string;
+      conversationText: string;
+      userSchema?: string;
+      conversationId?: string;
+    }
+  | undefined {
+  if (!metadata || typeof metadata !== "object") return undefined;
+  const raw = metadata.composeSeed;
+  if (!raw || typeof raw !== "object") return undefined;
+  const seed = raw as Record<string, unknown>;
+  if (typeof seed.outline !== "string" || typeof seed.conversationText !== "string") {
+    return undefined;
+  }
+  const out: {
+    outline: string;
+    conversationText: string;
+    userSchema?: string;
+    conversationId?: string;
+  } = {
+    outline: seed.outline,
+    conversationText: seed.conversationText,
+  };
+  if (typeof seed.userSchema === "string" && seed.userSchema.trim()) {
+    out.userSchema = seed.userSchema;
+  }
+  if (typeof seed.conversationId === "string" && seed.conversationId.trim()) {
+    out.conversationId = seed.conversationId;
+  }
+  return out;
+}
+
+function activityId(): string {
+  if (typeof crypto !== "undefined" && "randomUUID" in crypto) return crypto.randomUUID();
+  return `act-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+/**
+ * Map an SSE event into a state update. Returns a partial state to merge.
+ */
+function reduceEvent(
+  prev: WikiComposeSessionState,
+  event: ComposeSseEvent,
+): Partial<WikiComposeSessionState> {
+  switch (event.type) {
+    case "started":
+      return {
+        activity: appendActivity(prev.activity, {
+          label: "Run started",
+          detail: event.graphId,
+          status: "info",
+        }),
+      };
+    case "compose_phase":
+      return {
+        phase: event.phase,
+        activity: appendActivity(prev.activity, {
+          label: `Phase: ${event.phase}`,
+          detail: event.status,
+          status: event.status === "entered" ? "started" : "completed",
+        }),
+      };
+    case "status":
+      // Server-side `status` events use a colon-namespaced phase string
+      // (e.g. "brief:await_user"); we don't surface those as the top-level
+      // phase, only as activity log entries for debug.
+      return {
+        activity: appendActivity(prev.activity, {
+          label: event.phase,
+          detail: event.message,
+          status: "info",
+        }),
+      };
+    case "tool_start":
+      return {
+        activity: appendActivity(prev.activity, {
+          label: `Tool: ${event.tool}`,
+          detail: event.input ? "running" : undefined,
+          status: "started",
+        }),
+      };
+    case "tool_end":
+      return {
+        activity: appendActivity(prev.activity, {
+          label: `Tool: ${event.tool}`,
+          detail: event.error ?? (event.outputLength ? `${event.outputLength} chars` : "ok"),
+          status: event.error ? "error" : "completed",
+        }),
+      };
+    case "research_iteration":
+      return {
+        activity: appendActivity(prev.activity, {
+          label: `Research iteration ${event.iteration + 1}`,
+          detail: `${event.status} · ${event.queryCount} queries`,
+          status: "info",
+        }),
+      };
+    case "research_evaluation":
+      return {
+        activity: appendActivity(prev.activity, {
+          label: `Sufficiency: ${event.score.toFixed(2)}`,
+          detail: event.rationale,
+          status: "info",
+        }),
+      };
+    case "research_batch":
+      return {
+        activity: appendActivity(prev.activity, {
+          label: `Research batch (#${event.iteration})`,
+          detail: `${event.sourceCount} sources · ${event.exitReason}`,
+          status: "completed",
+        }),
+      };
+    case "compose_section":
+      if (event.status === "started") {
+        return {
+          streamingSectionId: event.sectionId,
+          sectionBuffers: { ...prev.sectionBuffers, [event.sectionId]: "" },
+          activity: appendActivity(prev.activity, {
+            label: `Drafting: ${event.heading}`,
+            detail: `${event.index} / ${event.total}`,
+            status: "started",
+          }),
+        };
+      }
+      return {
+        streamingSectionId:
+          prev.streamingSectionId === event.sectionId ? null : prev.streamingSectionId,
+        activity: appendActivity(prev.activity, {
+          label: `Drafted: ${event.heading}`,
+          detail: `${event.index} / ${event.total}`,
+          status: "completed",
+        }),
+      };
+    case "token": {
+      const id = prev.streamingSectionId;
+      if (!id) return {};
+      const prior = prev.sectionBuffers[id] ?? "";
+      return {
+        sectionBuffers: { ...prev.sectionBuffers, [id]: prior + event.content },
+      };
+    }
+    case "interrupt":
+      return reduceInterrupt(prev, event.payload);
+    case "done":
+      return {
+        isStreaming: false,
+        status: event.status,
+        activity: appendActivity(prev.activity, {
+          label: `Run ${event.status}`,
+          status: event.status === "completed" ? "completed" : "info",
+        }),
+      };
+    case "error":
+      return {
+        error: event.message,
+        activity: appendActivity(prev.activity, {
+          label: "Error",
+          detail: event.message,
+          status: "error",
+        }),
+      };
+    case "usage":
+      // Usage doesn't change UI state directly, but log it for debug.
+      return {
+        activity: appendActivity(prev.activity, {
+          label: "Usage",
+          detail: `in=${event.inputTokens} out=${event.outputTokens} cu=${event.costUnits}`,
+          status: "info",
+        }),
+      };
+    default:
+      return {};
+  }
+}
+
+function appendActivity(
+  prev: ComposeActivity[],
+  next: Omit<ComposeActivity, "id" | "at">,
+): ComposeActivity[] {
+  const entry: ComposeActivity = {
+    id: activityId(),
+    at: new Date().toISOString(),
+    ...next,
+  };
+  // Cap the activity log so a long-running session does not grow unbounded.
+  // 直近 200 件のみ保持する（DOM 描画コスト対策）。
+  const merged = [...prev, entry];
+  return merged.length > 200 ? merged.slice(merged.length - 200) : merged;
+}
+
+/**
+ * Extract UI state from a non-streaming `PATCH /resume` response body.
+ *
+ * Resume runs the graph via `invoke`, so tokens and interrupts are returned in
+ * `output` rather than over SSE. The hook must hydrate phase slices from that
+ * payload; relying on a follow-up `POST /run` would pass fresh `input` to an
+ * interrupted checkpoint (invalid for LangGraph) and drop `completion` on the
+ * final outline approve path.
+ */
+/**
+ * Merge `GET /compose-sessions/:id` checkpoint projection into hook state (#950).
+ * `GET` の projection をフック state にマージする（リロード再開用）。
+ */
+function hydrateFromProjection(
+  projection: ComposeSessionUiProjection,
+): Partial<WikiComposeSessionState> {
+  const partial: Partial<WikiComposeSessionState> = {};
+  if (projection.phase) partial.phase = projection.phase;
+  if (projection.briefQuestions?.length) partial.briefQuestions = projection.briefQuestions;
+  if (projection.pageSnapshot) partial.pageSnapshot = projection.pageSnapshot;
+  if (projection.latestBatch !== undefined) partial.latestBatch = projection.latestBatch;
+  if (projection.pendingSources?.length) partial.pendingSources = projection.pendingSources;
+  if (projection.approvedSources?.length) partial.approvedSources = projection.approvedSources;
+  if (projection.researchConflictSummary) {
+    partial.researchConflictSummary = projection.researchConflictSummary;
+  }
+  if (projection.outlineProposal?.length) partial.outlineProposal = projection.outlineProposal;
+  if (projection.completedMarkdown) partial.completedMarkdown = projection.completedMarkdown;
+  if (projection.draftedSections?.length) {
+    const draftedSections: Record<string, DraftedSection> = {};
+    for (const section of projection.draftedSections) {
+      if (section?.sectionId) draftedSections[section.sectionId] = section;
+    }
+    partial.draftedSections = draftedSections;
+  }
+  return partial;
+}
+
+/**
+ * Build hook state context for resume-time interrupt projection.
+ * resume 時の interrupt 投影用に、チェックポイント上の approvedResearch を引き継ぐ。
+ */
+function interruptContextFromCheckpoint(state: Record<string, unknown>): WikiComposeSessionState {
+  const approved = Array.isArray(state.approvedResearch)
+    ? (state.approvedResearch as ResearchSource[])
+    : [];
+  return { ...INITIAL_STATE, approvedSources: approved };
+}
+
+function reduceResumeOutput(
+  output: unknown,
+  status: ComposeSessionStatus,
+): Partial<WikiComposeSessionState> {
+  if (!output || typeof output !== "object") {
+    return status === "completed" ? { phase: "completed" } : {};
+  }
+  const state = output as Record<string, unknown>;
+  const partial: Partial<WikiComposeSessionState> = {};
+
+  const interrupts = state.__interrupt__;
+  if (Array.isArray(interrupts) && interrupts.length > 0) {
+    const entry = interrupts[0];
+    const value =
+      entry && typeof entry === "object" ? (entry as { value?: unknown }).value : undefined;
+    if (value && typeof value === "object" && "kind" in value) {
+      Object.assign(
+        partial,
+        reduceInterrupt(interruptContextFromCheckpoint(state), value as ComposeInterruptPayload),
+      );
+    }
+  }
+
+  const completion = state.completion;
+  if (completion && typeof completion === "object") {
+    const c = completion as {
+      markdown?: string;
+      sections?: DraftedSection[];
+    };
+    if (typeof c.markdown === "string" && c.markdown.length > 0) {
+      partial.completedMarkdown = c.markdown;
+    }
+    if (Array.isArray(c.sections)) {
+      const draftedSections: Record<string, DraftedSection> = {};
+      for (const section of c.sections) {
+        if (!section || typeof section !== "object") continue;
+        const s = section as DraftedSection;
+        if (typeof s.sectionId === "string") draftedSections[s.sectionId] = s;
+      }
+      partial.draftedSections = draftedSections;
+      partial.phase = "completed";
+      const approvedOutline = state.approvedOutline as { sections?: OutlineSection[] } | undefined;
+      if (approvedOutline?.sections?.length) {
+        partial.outlineProposal = approvedOutline.sections;
+      } else if (c.sections.length > 0) {
+        partial.outlineProposal = c.sections.map((s) => ({
+          id: s.sectionId,
+          heading: s.heading,
+          depth: 1,
+          intent: "",
+        }));
+      }
+    }
+  }
+
+  if (status === "completed" && partial.phase !== "completed") {
+    partial.phase = "completed";
+  }
+
+  return partial;
+}
+
+function reduceInterrupt(
+  prev: WikiComposeSessionState,
+  payload: ComposeInterruptPayload | undefined,
+): Partial<WikiComposeSessionState> {
+  if (!payload) return {};
+  switch (payload.kind) {
+    case "human_review_brief":
+      return {
+        briefQuestions: payload.questions,
+        pageSnapshot: payload.pageSnapshot,
+        phase: "brief",
+      };
+    case "human_review_research":
+      return {
+        latestBatch: payload.batch,
+        pendingSources: payload.pendingSources,
+        phase: "research",
+      };
+    case "human_review_outline":
+      return {
+        outlineProposal: payload.outline,
+        approvedSources: payload.approvedSources,
+        researchConflictSummary: null,
+        phase: "structure",
+      };
+    case "conflict_resolution":
+      return {
+        researchConflictSummary: payload.conflicts,
+        phase: "conflict",
+        // Keep approvals from `prev` (SSE) or checkpoint context (resume); do not
+        // overwrite with an empty array when `reduceResumeOutput` seeds context.
+        ...(prev.approvedSources.length > 0 ? { approvedSources: prev.approvedSources } : {}),
+      };
+    default:
+      return {};
+  }
+}
+
+/**
+ * `useWikiComposeSession` — owns SSE wiring and state reduction for one
+ * compose session. The page component reads the returned state and calls the
+ * submit functions to advance phases.
+ */
+export function useWikiComposeSession(
+  args: UseWikiComposeSessionArgs,
+): UseWikiComposeSessionReturn {
+  const {
+    pageId,
+    sessionId: initialSessionId,
+    initialInput,
+    composeSeed,
+    autoStart = true,
+    backend = "zedi_managed",
+  } = args;
+  const [state, setState] = useState<WikiComposeSessionState>(INITIAL_STATE);
+  const sessionRef = useRef<ComposeSession | null>(null);
+  const abortRef = useRef<AbortController | null>(null);
+
+  /** Merge a partial update into state. */
+  const update = useCallback((partial: Partial<WikiComposeSessionState>) => {
+    setState((prev) => ({ ...prev, ...partial }));
+  }, []);
+
+  /** Consume an SSE event by reducing it into state. */
+  const onEvent = useCallback((event: ComposeSseEvent) => {
+    setState((prev) => ({ ...prev, ...reduceEvent(prev, event) }));
+  }, []);
+
+  /** Stream a `runSession` call and update state from events. */
+  const streamRun = useCallback(
+    async (session: ComposeSession, body?: Record<string, unknown>) => {
+      abortRef.current?.abort();
+      const controller = new AbortController();
+      abortRef.current = controller;
+      update({ isStreaming: true, error: null });
+      try {
+        await runSession({
+          pageId,
+          sessionId: session.id,
+          body,
+          onEvent,
+          signal: controller.signal,
+        });
+      } catch (err) {
+        if ((err as { name?: string }).name === "AbortError") {
+          // Caller aborted; do not surface as an error.
+          // ユーザー操作による abort は error として扱わない。
+          return;
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        update({ error: message, isStreaming: false });
+      } finally {
+        update({ isStreaming: false });
+        abortRef.current = null;
+      }
+    },
+    [pageId, onEvent, update],
+  );
+
+  /** Create or resume the session, then begin streaming. */
+  const start = useCallback(async () => {
+    try {
+      const loaded = initialSessionId ? await getSession(pageId, initialSessionId) : null;
+      const session =
+        loaded?.session ??
+        (await createSession({
+          pageId,
+          backend,
+          metadata: composeSeed
+            ? {
+                composeSeed: {
+                  outline: composeSeed.outline,
+                  conversationText: composeSeed.conversationText,
+                  userSchema: composeSeed.userSchema,
+                  conversationId: composeSeed.conversationId,
+                },
+              }
+            : undefined,
+        }));
+      const projectionHydration = loaded?.projection
+        ? hydrateFromProjection(loaded.projection)
+        : {};
+
+      sessionRef.current = session;
+      update({ session, status: session.status, error: null, ...projectionHydration });
+
+      const metadataSeed = parseComposeSeedFromMetadata(session.metadata);
+      const runInput =
+        initialInput ??
+        (metadataSeed
+          ? {
+              chatSeed: metadataSeed,
+            }
+          : undefined);
+
+      // Only fresh / retriable rows may call `POST /run` with graph input.
+      // Interrupted checkpoints require `Command({ resume })`; replaying input
+      // would restart or error, and resume payloads are not stored on the row.
+      if (session.status === "pending" || session.status === "failed") {
+        await streamRun(session, runInput);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      update({ error: message });
+    }
+  }, [pageId, initialSessionId, initialInput, composeSeed, backend, streamRun, update]);
+
+  const submitBrief = useCallback<UseWikiComposeSessionReturn["submitBrief"]>(
+    async (input) => {
+      const session = sessionRef.current;
+      if (!session) throw new Error("Session not initialised");
+      const result = await resumeSession({ pageId, sessionId: session.id, resume: input });
+      const fromResume = reduceResumeOutput(result.output, result.status);
+      update({ status: result.status, ...fromResume });
+    },
+    [pageId, update],
+  );
+
+  const submitResearchApproval = useCallback<UseWikiComposeSessionReturn["submitResearchApproval"]>(
+    async (input) => {
+      const session = sessionRef.current;
+      if (!session) throw new Error("Session not initialised");
+      // Mirror the approved sources into state immediately so the UI can show
+      // the user's choice without waiting for the server's projection.
+      // resume 直後に approvedSources を仮反映してフロントの追随を早める。
+      const approved = state.pendingSources.filter((s) => input.approvedSourceIds.includes(s.id));
+      update({ approvedSources: approved });
+      const result = await resumeSession({ pageId, sessionId: session.id, resume: input });
+      if (interruptKindFromOutput(result.output) === "conflict_resolution") {
+        const fromResume = reduceResumeOutput(result.output, result.status);
+        update({ status: result.status, ...fromResume });
+        return;
+      }
+      const fromResume = reduceResumeOutput(result.output, result.status);
+      update({ status: result.status, ...fromResume });
+    },
+    [pageId, state.pendingSources, update],
+  );
+
+  const submitConflictAck = useCallback<UseWikiComposeSessionReturn["submitConflictAck"]>(
+    async (input) => {
+      const session = sessionRef.current;
+      if (!session) throw new Error("Session not initialised");
+      const result = await resumeSession({
+        pageId,
+        sessionId: session.id,
+        resume: { acknowledged: true as const, ...(input?.note ? { note: input.note } : {}) },
+      });
+      const fromResume = reduceResumeOutput(result.output, result.status);
+      update({
+        status: result.status,
+        researchConflictSummary: null,
+        ...fromResume,
+      });
+    },
+    [pageId, update],
+  );
+
+  const submitOutline = useCallback<UseWikiComposeSessionReturn["submitOutline"]>(
+    async (input) => {
+      const session = sessionRef.current;
+      if (!session) throw new Error("Session not initialised");
+      const result = await resumeSession({ pageId, sessionId: session.id, resume: input });
+      const fromResume = reduceResumeOutput(result.output, result.status);
+      update({ status: result.status, ...fromResume });
+    },
+    [pageId, update],
+  );
+
+  const cancel = useCallback(async () => {
+    abortRef.current?.abort();
+    const session = sessionRef.current;
+    if (!session) return;
+    await cancelSession(pageId, session.id);
+    update({ status: "cancelled" });
+  }, [pageId, update]);
+
+  // Auto-start on mount when requested. The dependency list is intentionally
+  // narrow so we don't double-start on prop changes.
+  // 自動開始は mount 時のみ。引数変更で再起動しないよう依存を意図的に絞る。
+  useEffect(() => {
+    if (!autoStart) return;
+    let cancelled = false;
+    void start().catch((err) => {
+      if (cancelled) return;
+      const message = err instanceof Error ? err.message : String(err);
+      update({ error: message });
+    });
+    return () => {
+      cancelled = true;
+      abortRef.current?.abort();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Derive completion markdown from drafted sections when status flips.
+  // 完了時に Markdown を組み立てるロジックは backend `completed` ノードと別系統
+  // でも UI 側で再構築できるよう、フックでも軽量に持つ。
+  const completedMarkdown = useMemo(() => {
+    if (state.status !== "completed") return state.completedMarkdown;
+    if (state.completedMarkdown) return state.completedMarkdown;
+    const sections = state.outlineProposal
+      .map((s) => state.draftedSections[s.id])
+      .filter((s): s is DraftedSection => Boolean(s));
+    if (sections.length === 0) return null;
+    return sections.map((s) => `## ${s.heading}\n\n${s.body}`).join("\n\n");
+  }, [state.status, state.outlineProposal, state.draftedSections, state.completedMarkdown]);
+
+  return {
+    ...state,
+    completedMarkdown,
+    start,
+    submitBrief,
+    submitResearchApproval,
+    submitConflictAck,
+    submitOutline,
+    submitConflictAck,
+    cancel,
+  };
+}
diff --git a/src/i18n/index.ts b/src/i18n/index.ts
index b1653817..e326bcd8 100644
--- a/src/i18n/index.ts
+++ b/src/i18n/index.ts
@@ -26,6 +26,7 @@ import jaShortcuts from "./locales/ja/shortcuts.json";
 import jaSeedData from "./locales/ja/seedData.json";
 import jaMermaid from "./locales/ja/mermaid.json";
 import jaAiPrompt from "./locales/ja/aiPrompt.json";
+import jaWikiCompose from "./locales/ja/wikiCompose.json";
 import enCommon from "./locales/en/common.json";
 import enSettings from "./locales/en/settings.json";
 import enGeneralSettings from "./locales/en/generalSettings.json";
@@ -48,6 +49,7 @@ import enShortcuts from "./locales/en/shortcuts.json";
 import enSeedData from "./locales/en/seedData.json";
 import enMermaid from "./locales/en/mermaid.json";
 import enAiPrompt from "./locales/en/aiPrompt.json";
+import enWikiCompose from "./locales/en/wikiCompose.json";
 
 const ja = {
   common: jaCommon,
@@ -72,6 +74,7 @@ const ja = {
   seedData: jaSeedData,
   mermaid: jaMermaid,
   aiPrompt: jaAiPrompt,
+  wikiCompose: jaWikiCompose,
 };
 
 const en = {
@@ -97,6 +100,7 @@ const en = {
   seedData: enSeedData,
   mermaid: enMermaid,
   aiPrompt: enAiPrompt,
+  wikiCompose: enWikiCompose,
 };
 
 // localStorage の設定から初期言語を取得
diff --git a/src/i18n/locales/en/common.json b/src/i18n/locales/en/common.json
index 4d66bdb1..1ae174f6 100644
--- a/src/i18n/locales/en/common.json
+++ b/src/i18n/locales/en/common.json
@@ -131,5 +131,9 @@
     "notCreated": "This page does not exist yet.",
     "notCreatedWithRefs": "This page does not exist yet, and is referenced from others.",
     "clickToCreate": "Click to create"
+  },
+  "wikiLinkInputBar": {
+    "placeholder": "Write a note",
+    "ariaLabel": "Create or link a page"
   }
 }
diff --git a/src/i18n/locales/en/editor.json b/src/i18n/locales/en/editor.json
index 632ea2a6..17cd9968 100644
--- a/src/i18n/locales/en/editor.json
+++ b/src/i18n/locales/en/editor.json
@@ -6,6 +6,7 @@
   "collaborationLoading": "Loading editor",
   "pageMenu": {
     "exportMarkdown": "Export Markdown",
+    "exportPdf": "Export as PDF",
     "copyMarkdown": "Copy Markdown",
     "deletePage": "Delete"
   },
@@ -232,13 +233,35 @@
       "aliases": "summarize,summary"
     }
   },
-  "recommendation": {
-    "next": "Next",
+  "pageActionHub": {
+    "title": "Page actions",
+    "openAriaLabel": "Open page actions",
     "back": "Back",
     "close": "Close",
-    "generating": "Generating image",
-    "labelRecommendation": "Recommendations",
-    "labelThumbnails": "Thumbnail candidates"
+    "emptyState": "No actions available",
+    "actions": {
+      "thumbnailSearch": {
+        "label": "Search image",
+        "description": "Search by title and insert as thumbnail",
+        "loading": "Searching images...",
+        "empty": "No candidates found",
+        "next": "Next",
+        "retry": "Retry"
+      },
+      "thumbnailGenerate": {
+        "label": "Generate with AI",
+        "description": "Generate an image with AI and insert as thumbnail",
+        "loading": "Generating image...",
+        "retry": "Regenerate",
+        "missingTitle": "Please enter a title"
+      },
+      "wikiCompose": {
+        "label": "Wiki Compose",
+        "description": "Co-author this page with AI in a guided Brief → research → outline → draft flow.",
+        "start": "Open Wiki Compose",
+        "unavailable": "Wiki Compose is not available for this page."
+      }
+    }
   },
   "webClipper": {
     "title": "Import from URL",
@@ -317,5 +340,10 @@
     "downloaded": "Markdown file downloaded",
     "copied": "Markdown copied to clipboard",
     "copyFailed": "Copy failed"
+  },
+  "pdfExport": {
+    "sourceAttribution": "📎 Source",
+    "downloaded": "PDF downloaded",
+    "failed": "Failed to generate PDF"
   }
 }
diff --git a/src/i18n/locales/en/wikiCompose.json b/src/i18n/locales/en/wikiCompose.json
new file mode 100644
index 00000000..856aade6
--- /dev/null
+++ b/src/i18n/locales/en/wikiCompose.json
@@ -0,0 +1,27 @@
+{
+  "backend": {
+    "label": "Execution backend",
+    "zediManaged": "Zedi managed",
+    "zediManagedDesc": "Uses Zedi API keys; consumes monthly CU.",
+    "userAnthropic": "Your Anthropic key",
+    "userAnthropicDesc": "Runs with your Anthropic API key stored on the server (encrypted).",
+    "userOpenai": "Your OpenAI key",
+    "userOpenaiDesc": "Runs with your OpenAI API key stored on the server (encrypted).",
+    "userGoogle": "Your Google key",
+    "userGoogleDesc": "Runs with your Google API key stored on the server (encrypted).",
+    "usesCu": "Uses Zedi monthly CU.",
+    "credentialRequired": "Register this provider's API key in Settings → AI first."
+  },
+  "credentials": {
+    "title": "Wiki Compose API keys (BYOK)",
+    "description": "Store provider API keys on the server for Wiki Compose. Keys are encrypted at rest and never returned in API responses.",
+    "anthropic": "Anthropic",
+    "openai": "OpenAI",
+    "google": "Google",
+    "placeholder": "Paste API key",
+    "configured": "Configured",
+    "remove": "Remove",
+    "storageDisabled": "Server-side credential storage is not enabled on this environment.",
+    "localStorageNote": "General AI chat may still use browser-local keys; Wiki Compose BYOK uses the credentials above when you pick a user_* backend."
+  }
+}
diff --git a/src/i18n/locales/ja/common.json b/src/i18n/locales/ja/common.json
index b547b12f..3628896b 100644
--- a/src/i18n/locales/ja/common.json
+++ b/src/i18n/locales/ja/common.json
@@ -131,5 +131,9 @@
     "notCreated": "まだ作成されていないページです。",
     "notCreatedWithRefs": "まだ作成されていないページです。他のページからも参照されています。",
     "clickToCreate": "クリックして作成"
+  },
+  "wikiLinkInputBar": {
+    "placeholder": "メモを書く",
+    "ariaLabel": "ページを作成またはリンク"
   }
 }
diff --git a/src/i18n/locales/ja/editor.json b/src/i18n/locales/ja/editor.json
index 92af551b..48d4a562 100644
--- a/src/i18n/locales/ja/editor.json
+++ b/src/i18n/locales/ja/editor.json
@@ -6,6 +6,7 @@
   "collaborationLoading": "エディタを読み込み中",
   "pageMenu": {
     "exportMarkdown": "Markdownでエクスポート",
+    "exportPdf": "PDFで出力",
     "copyMarkdown": "Markdownをコピー",
     "deletePage": "削除"
   },
@@ -232,13 +233,35 @@
       "aliases": "summarize,要約,サマリ"
     }
   },
-  "recommendation": {
-    "next": "次へ",
+  "pageActionHub": {
+    "title": "ページアクション",
+    "openAriaLabel": "ページアクションを開く",
     "back": "戻る",
     "close": "閉じる",
-    "generating": "画像を生成中",
-    "labelRecommendation": "おすすめ",
-    "labelThumbnails": "サムネイル候補"
+    "emptyState": "利用可能なアクションがありません",
+    "actions": {
+      "thumbnailSearch": {
+        "label": "画像を検索",
+        "description": "タイトルから画像を検索してサムネイルとして挿入",
+        "loading": "画像を検索中...",
+        "empty": "候補が見つかりませんでした",
+        "next": "次へ",
+        "retry": "再試行"
+      },
+      "thumbnailGenerate": {
+        "label": "AI で画像生成",
+        "description": "タイトルから AI で画像を生成してサムネイルとして挿入",
+        "loading": "画像を生成中...",
+        "retry": "再生成",
+        "missingTitle": "タイトルを入力してください"
+      },
+      "wikiCompose": {
+        "label": "Wiki Compose",
+        "description": "Brief → 調査 → 構成 → 執筆のガイド付きフローで AI と協働してページを作成します。",
+        "start": "Wiki Compose を開く",
+        "unavailable": "このページでは Wiki Compose を利用できません。"
+      }
+    }
   },
   "webClipper": {
     "title": "URLから取り込み",
@@ -317,5 +340,10 @@
     "downloaded": "Markdownファイルをダウンロードしました",
     "copied": "Markdownをクリップボードにコピーしました",
     "copyFailed": "コピーに失敗しました"
+  },
+  "pdfExport": {
+    "sourceAttribution": "📎 引用元",
+    "downloaded": "PDFをダウンロードしました",
+    "failed": "PDFの生成に失敗しました"
   }
 }
diff --git a/src/i18n/locales/ja/wikiCompose.json b/src/i18n/locales/ja/wikiCompose.json
new file mode 100644
index 00000000..d9ebecb6
--- /dev/null
+++ b/src/i18n/locales/ja/wikiCompose.json
@@ -0,0 +1,27 @@
+{
+  "backend": {
+    "label": "実行バックエンド",
+    "zediManaged": "Zedi 管理",
+    "zediManagedDesc": "Zedi の API キーで実行。月次 CU を消費します。",
+    "userAnthropic": "自分の Anthropic キー",
+    "userAnthropicDesc": "サーバーに保存した Anthropic API キーで実行（暗号化保管）。",
+    "userOpenai": "自分の OpenAI キー",
+    "userOpenaiDesc": "サーバーに保存した OpenAI API キーで実行（暗号化保管）。",
+    "userGoogle": "自分の Google キー",
+    "userGoogleDesc": "サーバーに保存した Google API キーで実行（暗号化保管）。",
+    "usesCu": "Zedi の月次 CU を使用します。",
+    "credentialRequired": "先に 設定 → AI でこのプロバイダの API キーを登録してください。"
+  },
+  "credentials": {
+    "title": "Wiki Compose 用 API キー（BYOK）",
+    "description": "Wiki Compose で使うプロバイダ API キーをサーバーに保存します。キーは暗号化され、API レスポンスでは返しません。",
+    "anthropic": "Anthropic",
+    "openai": "OpenAI",
+    "google": "Google",
+    "placeholder": "API キーを貼り付け",
+    "configured": "登録済み",
+    "remove": "削除",
+    "storageDisabled": "この環境ではサーバー側の credential 保管が有効になっていません。",
+    "localStorageNote": "通常の AI チャットはブラウザ localStorage のキーを使う場合があります。Wiki Compose で user_* バックエンドを選んだときは、上記の登録キーを使います。"
+  }
+}
diff --git a/src/index.css b/src/index.css
index 00a1fd4c..c6407fae 100644
--- a/src/index.css
+++ b/src/index.css
@@ -58,8 +58,14 @@
     --surface-elevated: 220 18% 14%;
     --text-subtle: 220 10% 50%;
     --link-color: 175 50% 60%;
-    --link-referenced: 200 70% 60%;
-    --link-ghost: 35 80% 60%;
+    /* Ghost link family: warm orange, distinguished by lightness/saturation only.
+     * `referenced` is slightly stronger, `ghost` is the faintest. See #932.
+     * Both meet WCAG AA against the 10%-tinted chip background
+     * (referenced ≈ 7:1, ghost ≈ 5.9:1).
+     * ゴーストリンク系: オレンジ系統で薄さの強弱だけで区別する（#932）。
+     * チップ背景込みで AA を満たす。 */
+    --link-referenced: 30 65% 62%;
+    --link-ghost: 30 35% 58%;
 
     /* Callout foreground colors (shared dark/light)
      * コールアウト前景色（ダーク/ライト共通） */
@@ -106,8 +112,14 @@
     --surface-elevated: 0 0% 100%;
     --text-subtle: 220 10% 55%;
     --link-color: 175 60% 40%;
-    --link-referenced: 200 65% 50%;
-    --link-ghost: 35 70% 50%;
+    /* Ghost link family on light background, see #932.
+     * Values verified to meet WCAG AA (≥4.5:1) against the 10%-tinted chip
+     * background (`hsl(var(--link-*) / 0.1)` over `--background`):
+     *   referenced ≈ 5.5:1, ghost ≈ 4.5:1. `referenced` stays slightly
+     *   stronger than `ghost` to preserve the lightness hierarchy.
+     * ライト背景時のゴーストリンク系（#932）。チップ背景込みで AA を満たす。 */
+    --link-referenced: 24 80% 32%;
+    --link-ghost: 28 50% 38%;
 
     --sidebar-background: 45 15% 97%;
     --sidebar-foreground: 220 25% 12%;
@@ -842,11 +854,16 @@
     background: hsl(var(--link-color) / 0.2);
   }
 
-  /* Referenced — exists in other pages but not yet created */
+  /* Referenced — exists in other pages but not yet created.
+   * Distinguished from `ghost` by a slightly stronger orange only; no dashed
+   * underline or icon decorations (#932). `:focus-visible` is intentionally
+   * omitted because the extension renders non-tabbable `<span>` elements; if
+   * keyboard focus is added in the future, restore an outline here.
+   * 参照あり未作成: ゴーストよりわずかに濃いオレンジで区別。装飾なし（#932）。
+   * span は tabbable でないため `:focus-visible` は付けない（将来要対応）。 */
   .wiki-link-referenced {
     color: hsl(var(--link-referenced));
     background: hsl(var(--link-referenced) / 0.1);
-    border-bottom: 1px dashed currentcolor;
     padding: 1px 4px;
     margin: 0 -2px;
     border-radius: 3px;
@@ -857,14 +874,13 @@
 
   .wiki-link-referenced:hover {
     background: hsl(var(--link-referenced) / 0.2);
-    border-bottom-style: solid;
   }
 
-  /* Ghost — new / unreferenced */
+  /* Ghost — new / unreferenced. Faintest orange in the family (#932).
+   * ゴースト: 一番薄いオレンジで表現（#932）。 */
   .wiki-link-ghost {
     color: hsl(var(--link-ghost));
     background: hsl(var(--link-ghost) / 0.1);
-    border-bottom: 1px dashed currentcolor;
     padding: 1px 4px;
     margin: 0 -2px;
     border-radius: 3px;
@@ -875,7 +891,6 @@
 
   .wiki-link-ghost:hover {
     background: hsl(var(--link-ghost) / 0.2);
-    border-bottom-style: solid;
   }
 
   /* Wiki link typing state */
@@ -885,6 +900,32 @@
     border-radius: 2px;
   }
 
+  /* Inline ghost completion preview (issue #930). Rendered as a
+     `Decoration.widget` next to the caret while the typed word prefix-matches
+     an existing page title. Tap (mobile) or press Tab (desktop) to confirm. */
+  /* インライン・ゴースト補完（issue #930）。入力中の単語が既存ページ名の
+     接頭辞に一致した時に `Decoration.widget` でカーソル右に出す薄色のプレビュー。
+     Tab（デスクトップ）またはチップタップ（モバイル）で確定する。 */
+  .wiki-link-ghost-completion {
+    color: hsl(var(--muted-foreground));
+    opacity: 0.55;
+    font-style: italic;
+    /* widget の pointer-events は editor 親から none を継承し得るため明示。
+       Widgets may inherit pointer-events: none from the editor host; opt back
+       in so the chip is tappable on mobile. */
+    pointer-events: auto;
+    cursor: pointer;
+    user-select: none;
+    -webkit-user-select: none;
+    background: transparent;
+    border: none;
+    text-decoration: none;
+  }
+
+  .wiki-link-ghost-completion:hover {
+    opacity: 0.8;
+  }
+
   /* Tag styling — shares the WikiLink color scheme so existing/referenced/ghost
      states are visually consistent across both mark types. See issue #725. */
   /* タグのスタイル。WikiLink と同じ色系列を共有し、existing / referenced /
@@ -899,8 +940,13 @@
     background: hsl(var(--link-color) / 0.2);
   }
 
+  /* Tag referenced/ghost share the WikiLink design (#725, #932): faint orange
+   * only, no dashed underline. Distinguished by lightness only. `:focus-visible`
+   * is intentionally omitted to match `.wiki-link-*` (spans are non-tabbable).
+   * Tag の referenced/ghost も WikiLink と同じ「薄いオレンジのみ」設計（#725, #932）。
+   * span が tabbable でないため `:focus-visible` は付けない。 */
   .tag-referenced {
-    @apply text-link-referenced -mx-0.5 cursor-pointer rounded border-b border-dashed border-current px-0.5 font-medium transition-colors duration-200 hover:border-solid;
+    @apply text-link-referenced -mx-0.5 cursor-pointer rounded px-0.5 font-medium transition-colors duration-200;
 
     background: hsl(var(--link-referenced) / 0.1);
   }
@@ -910,7 +956,7 @@
   }
 
   .tag-ghost {
-    @apply border-ghost-link/50 text-ghost-link hover:border-ghost-link -mx-0.5 cursor-pointer rounded border-b border-dashed px-0.5 font-medium transition-colors duration-200;
+    @apply text-ghost-link -mx-0.5 cursor-pointer rounded px-0.5 font-medium transition-colors duration-200;
 
     background: hsl(var(--link-ghost) / 0.1);
   }
diff --git a/src/lib/markdownExport.test.ts b/src/lib/markdownExport.test.ts
index 4d742a7a..aecbaf63 100644
--- a/src/lib/markdownExport.test.ts
+++ b/src/lib/markdownExport.test.ts
@@ -143,6 +143,38 @@ describe("tiptapToMarkdown", () => {
     expect(md).toContain("---");
   });
 
+  // `mermaid` ノードは ` ```mermaid ` フェンスとして出力し、ペースト時の正規化
+  // (`transformMermaidCodeBlocksInContent`) と round-trip が取れるようにする (Issue #945)。
+  // Mermaid nodes must round-trip back to ` ```mermaid ` fences so paste-side
+  // normalisation (`transformMermaidCodeBlocksInContent`) is reversible.
+  it("converts mermaid node back to a ```mermaid fence", () => {
+    const content = JSON.stringify({
+      type: "doc",
+      content: [
+        {
+          type: "mermaid",
+          attrs: { code: "graph TD\n  A-->B" },
+        },
+      ],
+    });
+    const md = tiptapToMarkdown(content);
+    expect(md).toContain("```mermaid");
+    expect(md).toContain("graph TD");
+    expect(md).toContain("A-->B");
+    // フェンス開始の直後に空行が入らないこと（読みやすさ）
+    // Source code starts on the line immediately after the opening fence.
+    expect(md).toMatch(/```mermaid\ngraph TD/);
+  });
+
+  it("emits an empty mermaid fence when code attribute is missing", () => {
+    const content = JSON.stringify({
+      type: "doc",
+      content: [{ type: "mermaid" }],
+    });
+    const md = tiptapToMarkdown(content);
+    expect(md).toMatch(/```mermaid\n\n```/);
+  });
+
   it("handles bold, italic, strike, code marks", () => {
     const content = JSON.stringify({
       type: "doc",
diff --git a/src/lib/markdownExport.ts b/src/lib/markdownExport.ts
index ce294a67..7a5064fe 100644
--- a/src/lib/markdownExport.ts
+++ b/src/lib/markdownExport.ts
@@ -70,6 +70,17 @@ Object.assign(nodeHandlers, {
     const code = convertChildren(n).trim();
     return `\`\`\`${language}\n${code}\n\`\`\`\n\n`;
   },
+  mermaid: (n) => {
+    // `mermaid` ノードは Markdown 上では ``` ```mermaid ``` ``` フェンスへ戻す。
+    // ハンドラ未登録のままだと `code` 属性が落ちて空エクスポートになるため、
+    // ここで往復対称性を担保する（Issue #945）。
+    // Serialize a `mermaid` node back to a ``` ```mermaid ``` ``` fence so the
+    // Markdown export round-trips with the paste-side normalisation. Without a
+    // handler the `code` attribute would be silently dropped (Issue #945).
+    const code = typeof n.attrs?.code === "string" ? n.attrs.code : "";
+    const trimmed = code.replace(/\n+$/u, "");
+    return `\`\`\`mermaid\n${trimmed}\n\`\`\`\n\n`;
+  },
   horizontalRule: () => "---\n\n",
   hardBreak: () => "\n",
   text: (n) => applyMarks(n.text || "", n.marks || []),
@@ -239,10 +250,13 @@ export function downloadMarkdown(
 }
 
 /**
- * Sanitize filename for safe file system usage
+ * ダウンロードファイル名で使えない文字を `_` に置換し、長さを 100 文字に制限する。
+ * Markdown / PDF 等エクスポート系コード間で共有する純粋関数。
+ *
+ * Replace characters that are invalid in filenames with `_` and clamp the
+ * length to 100 chars. Shared across export utilities (Markdown / PDF).
  */
-function sanitizeFilename(name: string): string {
-  // Remove or replace characters that are invalid in filenames
+export function sanitizeFilename(name: string): string {
   return name
     .replace(/[<>:"/\\|?*]/g, "_")
     .replace(/\s+/g, "_")
diff --git a/src/lib/markdownToTiptap.ts b/src/lib/markdownToTiptap.ts
index 55cfc183..78cd35e6 100644
--- a/src/lib/markdownToTiptap.ts
+++ b/src/lib/markdownToTiptap.ts
@@ -30,6 +30,7 @@
  */
 
 import { parseInlineContent, type TiptapTextNode } from "./markdownToTiptapHelpers";
+import { transformMermaidCodeBlocksInContent } from "@/components/editor/extensions/transformMermaidCodeBlocksInContent";
 
 type TiptapBlockNode = {
   type: string;
@@ -183,5 +184,14 @@ export function convertMarkdownToTiptapContent(
     });
   }
 
-  return JSON.stringify(doc);
+  // `codeBlock` + `language: "mermaid"` を `mermaid` ノードに正規化する。
+  // 現状この変換器は codeBlock を出さないが、将来 fenced code 対応を入れた際の
+  // 取りこぼし防止と、外部経由で同形の JSON が渡るケースの一貫性のために通す。
+  // Normalise any `codeBlock` + `language: "mermaid"` into a dedicated `mermaid`
+  // node. The current converter doesn't emit code blocks, but running the
+  // transform keeps the output consistent if fenced-code support is added
+  // later or if an external caller hands us a doc containing them.
+  const normalised = transformMermaidCodeBlocksInContent(doc);
+
+  return JSON.stringify(normalised);
 }
diff --git a/src/lib/tiptapToHtml.test.ts b/src/lib/tiptapToHtml.test.ts
new file mode 100644
index 00000000..c023b391
--- /dev/null
+++ b/src/lib/tiptapToHtml.test.ts
@@ -0,0 +1,316 @@
+import { describe, it, expect } from "vitest";
+import { tiptapToHtml } from "./tiptapToHtml";
+
+describe("tiptapToHtml", () => {
+  it("converts a paragraph node to a <p> block", () => {
+    const json = JSON.stringify({
+      type: "doc",
+      content: [{ type: "paragraph", content: [{ type: "text", text: "Hello world" }] }],
+    });
+    expect(tiptapToHtml(json)).toBe("<p>Hello world</p>");
+  });
+
+  it("converts body headings (levels 2–5) to matching h2–h5 tags", () => {
+    const json = JSON.stringify({
+      type: "doc",
+      content: [
+        { type: "heading", attrs: { level: 2 }, content: [{ type: "text", text: "H2" }] },
+        { type: "heading", attrs: { level: 3 }, content: [{ type: "text", text: "H3" }] },
+        { type: "heading", attrs: { level: 4 }, content: [{ type: "text", text: "H4" }] },
+        { type: "heading", attrs: { level: 5 }, content: [{ type: "text", text: "H5" }] },
+      ],
+    });
+    const html = tiptapToHtml(json);
+    expect(html).toContain("<h2>H2</h2>");
+    expect(html).toContain("<h3>H3</h3>");
+    expect(html).toContain("<h4>H4</h4>");
+    expect(html).toContain("<h5>H5</h5>");
+  });
+
+  // 旧データに残っている level 1 / 欠損 level は最小の本文見出し `h2` にフォールバックさせる。
+  // Legacy heading nodes with level 1 (or a missing level attribute) fall back to `h2`.
+  it("falls back to <h2> when heading level is missing or below 2", () => {
+    const json = JSON.stringify({
+      type: "doc",
+      content: [
+        { type: "heading", attrs: { level: 1 }, content: [{ type: "text", text: "Legacy" }] },
+        { type: "heading", content: [{ type: "text", text: "NoLevel" }] },
+      ],
+    });
+    const html = tiptapToHtml(json);
+    expect(html).toContain("<h2>Legacy</h2>");
+    expect(html).toContain("<h2>NoLevel</h2>");
+    expect(html).not.toContain("<h1>");
+  });
+
+  it("converts bullet and ordered lists, including nested lists", () => {
+    const json = JSON.stringify({
+      type: "doc",
+      content: [
+        {
+          type: "bulletList",
+          content: [
+            {
+              type: "listItem",
+              content: [
+                { type: "paragraph", content: [{ type: "text", text: "A" }] },
+                {
+                  type: "bulletList",
+                  content: [
+                    {
+                      type: "listItem",
+                      content: [{ type: "paragraph", content: [{ type: "text", text: "A-1" }] }],
+                    },
+                  ],
+                },
+              ],
+            },
+            {
+              type: "listItem",
+              content: [{ type: "paragraph", content: [{ type: "text", text: "B" }] }],
+            },
+          ],
+        },
+        {
+          type: "orderedList",
+          content: [
+            {
+              type: "listItem",
+              content: [{ type: "paragraph", content: [{ type: "text", text: "1st" }] }],
+            },
+          ],
+        },
+      ],
+    });
+    const html = tiptapToHtml(json);
+    expect(html).toContain("<ul>");
+    // ネストした `<ul>` が外側の `<li>` 内側に来ること。
+    // The nested `<ul>` appears inside the outer `<li>`.
+    expect(html).toMatch(/<li><p>A<\/p><ul><li><p>A-1<\/p><\/li><\/ul><\/li>/);
+    expect(html).toContain("<li><p>B</p></li>");
+    expect(html).toContain("<ol>");
+    expect(html).toContain("<li><p>1st</p></li>");
+  });
+
+  it("converts blockquote and horizontalRule", () => {
+    const json = JSON.stringify({
+      type: "doc",
+      content: [
+        {
+          type: "blockquote",
+          content: [{ type: "paragraph", content: [{ type: "text", text: "Quoted" }] }],
+        },
+        { type: "horizontalRule" },
+      ],
+    });
+    const html = tiptapToHtml(json);
+    expect(html).toContain("<blockquote>");
+    expect(html).toContain("Quoted");
+    expect(html).toContain("</blockquote>");
+    expect(html).toContain("<hr");
+  });
+
+  it("renders codeBlock with language class and escapes HTML inside", () => {
+    const json = JSON.stringify({
+      type: "doc",
+      content: [
+        {
+          type: "codeBlock",
+          attrs: { language: "ts" },
+          content: [{ type: "text", text: "<script>alert(1)</script>" }],
+        },
+      ],
+    });
+    const html = tiptapToHtml(json);
+    expect(html).toContain('<pre><code class="language-ts">');
+    expect(html).toContain("&lt;script&gt;alert(1)&lt;/script&gt;");
+    expect(html).not.toContain("<script>alert(1)</script>");
+  });
+
+  // PDF エクスポートは同期的にレンダリングするため、`mermaid` ノードは Mermaid の
+  // 非同期 API を呼ばずに「ソースをコードブロック相当のプレースホルダー」として
+  // 残す。図のソースが PDF 上で失われないことだけ保証する (Issue #945)。
+  // The PDF exporter is synchronous, so `mermaid` nodes are rendered as a
+  // placeholder code block that preserves the diagram source instead of a real
+  // SVG (Issue #945).
+  it("renders mermaid node as a language-mermaid code block placeholder", () => {
+    const json = JSON.stringify({
+      type: "doc",
+      content: [
+        {
+          type: "mermaid",
+          attrs: { code: "graph TD\n  A-->B" },
+        },
+      ],
+    });
+    const html = tiptapToHtml(json);
+    expect(html).toContain('<pre><code class="language-mermaid">');
+    expect(html).toContain("graph TD");
+    expect(html).toContain("A--&gt;B");
+  });
+
+  it("escapes mermaid source when it contains HTML-significant characters", () => {
+    const json = JSON.stringify({
+      type: "doc",
+      content: [
+        {
+          type: "mermaid",
+          attrs: { code: "<script>alert(1)</script>" },
+        },
+      ],
+    });
+    const html = tiptapToHtml(json);
+    expect(html).toContain("&lt;script&gt;alert(1)&lt;/script&gt;");
+    expect(html).not.toContain("<script>alert(1)</script>");
+  });
+
+  it("applies bold, italic, strike, inline-code, and link marks", () => {
+    const json = JSON.stringify({
+      type: "doc",
+      content: [
+        {
+          type: "paragraph",
+          content: [
+            { type: "text", text: "b", marks: [{ type: "bold" }] },
+            { type: "text", text: "i", marks: [{ type: "italic" }] },
+            { type: "text", text: "s", marks: [{ type: "strike" }] },
+            { type: "text", text: "c", marks: [{ type: "code" }] },
+            {
+              type: "text",
+              text: "link",
+              marks: [{ type: "link", attrs: { href: "https://example.com/" } }],
+            },
+          ],
+        },
+      ],
+    });
+    const html = tiptapToHtml(json);
+    expect(html).toContain("<strong>b</strong>");
+    expect(html).toContain("<em>i</em>");
+    expect(html).toContain("<s>s</s>");
+    expect(html).toContain("<code>c</code>");
+    expect(html).toContain('<a href="https://example.com/">link</a>');
+  });
+
+  it("escapes HTML-special characters in text nodes and attributes", () => {
+    const json = JSON.stringify({
+      type: "doc",
+      content: [
+        {
+          type: "paragraph",
+          content: [
+            { type: "text", text: "<>&\"'" },
+            {
+              type: "text",
+              text: "x",
+              marks: [{ type: "link", attrs: { href: 'javascript:alert("x")' } }],
+            },
+          ],
+        },
+      ],
+    });
+    const html = tiptapToHtml(json);
+    expect(html).toContain("&lt;&gt;&amp;&quot;&#39;");
+    // 不正 scheme は完全に除外し、空 href として描画する（XSS 防止）。
+    // Reject non-http(s) schemes outright; emit an empty href to neutralise XSS.
+    expect(html).not.toContain('href="javascript:');
+  });
+
+  it("renders images with src/alt/title attribute escaping", () => {
+    const json = JSON.stringify({
+      type: "doc",
+      content: [
+        {
+          type: "image",
+          attrs: {
+            src: "https://example.com/img.png",
+            alt: 'alt "quote"',
+            title: "t<itle>",
+          },
+        },
+      ],
+    });
+    const html = tiptapToHtml(json);
+    expect(html).toContain('src="https://example.com/img.png"');
+    expect(html).toContain('alt="alt &quot;quote&quot;"');
+    expect(html).toContain('title="t&lt;itle&gt;"');
+  });
+
+  it("renders wikiLink as bracketed text (no anchor target)", () => {
+    const json = JSON.stringify({
+      type: "doc",
+      content: [
+        {
+          type: "paragraph",
+          content: [{ type: "wikiLink", attrs: { title: "Foo" } }],
+        },
+      ],
+    });
+    expect(tiptapToHtml(json)).toContain("[[Foo]]");
+  });
+
+  it("emits empty output for malformed youtubeEmbed and a safe anchor for valid id", () => {
+    const invalid = JSON.stringify({
+      type: "doc",
+      content: [{ type: "paragraph", content: [{ type: "youtubeEmbed", attrs: { videoId: "" } }] }],
+    });
+    expect(tiptapToHtml(invalid)).toBe("<p></p>");
+
+    const valid = JSON.stringify({
+      type: "doc",
+      content: [
+        {
+          type: "paragraph",
+          content: [{ type: "youtubeEmbed", attrs: { videoId: "abcdefghijk" } }],
+        },
+      ],
+    });
+    expect(tiptapToHtml(valid)).toContain(
+      '<a href="https://www.youtube.com/watch?v=abcdefghijk">YouTube</a>',
+    );
+  });
+
+  it("wraps non-JSON plain text in a single <p>", () => {
+    expect(tiptapToHtml("just text")).toBe("<p>just text</p>");
+  });
+
+  // PR #921 codex P1: 読み取り専用パスは Hocuspocus の `extractTextFromYXml`
+  // で抽出したプレーンテキスト（ブロック間に `\n`）を渡してくる。空行で
+  // 区切られた段落を `<p>` ブロックに、単独の `\n` を `<br />` に落とす。
+  //
+  // PR #921 codex P1: the read-only path feeds plain text whose blocks are
+  // separated by `\n` (and sometimes `\n\n`). Blank-line runs delimit `<p>`
+  // paragraphs; single `\n` becomes `<br />` to preserve line structure.
+  it("preserves paragraph and line-break structure for plain-text fallback", () => {
+    const text = "First paragraph\nstill first.\n\nSecond paragraph.\n\n\nThird paragraph.";
+    expect(tiptapToHtml(text)).toBe(
+      "<p>First paragraph<br />still first.</p><p>Second paragraph.</p><p>Third paragraph.</p>",
+    );
+  });
+
+  it("escapes HTML metacharacters in the plain-text fallback", () => {
+    expect(tiptapToHtml("<script>")).toBe("<p>&lt;script&gt;</p>");
+  });
+
+  it("normalises CRLF line endings in the plain-text fallback", () => {
+    expect(tiptapToHtml("a\r\n\r\nb")).toBe("<p>a</p><p>b</p>");
+  });
+
+  it("renders an empty string for empty input", () => {
+    expect(tiptapToHtml("")).toBe("");
+  });
+
+  it("treats whitespace-only input as empty in the plain-text fallback", () => {
+    expect(tiptapToHtml("\n\n\n")).toBe("");
+  });
+
+  // PR #921 gemini-code-assist high: 相対 URL 内のドットを許可する。
+  // PR #921 gemini-code-assist high: dotted relative URLs must be allowed.
+  it("keeps dotted relative image paths through sanitizeUrl", () => {
+    const json = JSON.stringify({
+      type: "doc",
+      content: [{ type: "image", attrs: { src: "image.png", alt: "x" } }],
+    });
+    expect(tiptapToHtml(json)).toContain('src="image.png"');
+  });
+});
diff --git a/src/lib/tiptapToHtml.ts b/src/lib/tiptapToHtml.ts
new file mode 100644
index 00000000..c3e28cd3
--- /dev/null
+++ b/src/lib/tiptapToHtml.ts
@@ -0,0 +1,382 @@
+import { sanitizeFilename } from "./markdownExport";
+
+/**
+ * Tiptap JSON を HTML 文字列へ変換し、html2pdf.js による PDF 書き出しを行う。
+ * `markdownExport.ts` と同じノード dispatch 方式で実装し、エクスポート経路で
+ * 重い React Node View 拡張を読み込まずに済むようにしている。
+ *
+ * Convert Tiptap JSON into HTML and drive html2pdf.js for client-side PDF
+ * export. Mirrors the dispatch pattern in `markdownExport.ts` so the
+ * export path avoids pulling heavy React node-view extensions.
+ */
+
+interface TiptapNode {
+  type: string;
+  attrs?: Record<string, unknown>;
+  content?: TiptapNode[];
+  text?: string;
+  marks?: TiptapMark[];
+}
+
+interface TiptapMark {
+  type: string;
+  attrs?: Record<string, unknown>;
+}
+
+/**
+ * Tiptap JSON 文字列を export 用 HTML 文字列へ変換する。
+ * 入力が JSON でなければプレーンテキストとみなし、`\n` を段落区切りとして
+ * `<p>` ブロックに包んで返す。これにより、読み取り専用パスから渡される
+ * Hocuspocus 抽出の `content_text`（ブロック間に `\n` を挟むプレーンテキスト）
+ * が PDF 上で 1 行に潰れずに描画される（PR #921 codex P1）。
+ *
+ * Convert a Tiptap JSON string to an HTML string suitable for PDF export.
+ * For non-JSON inputs (e.g. the Y.Doc-extracted `content_text` fed from the
+ * read-only path) split on consecutive newlines and emit each chunk as a
+ * `<p>` block so paragraphs survive html2canvas rasterisation. Single `\n`
+ * inside a chunk becomes `<br />` (PR #921 codex P1).
+ */
+export function tiptapToHtml(content: string): string {
+  if (!content) return "";
+
+  try {
+    const doc = JSON.parse(content) as TiptapNode;
+    return convertNode(doc);
+  } catch {
+    return plainTextToHtmlParagraphs(content);
+  }
+}
+
+/**
+ * プレーンテキストを段落 (`<p>`) と改行 (`<br />`) 構造の HTML に変換する。
+ * 連続した空行をブロック区切り、単独の `\n` を行内改行として扱う。
+ *
+ * Convert plain text into a paragraph/`<br>` HTML structure: blank-line runs
+ * delimit blocks, single `\n` becomes `<br />` inside a block.
+ */
+function plainTextToHtmlParagraphs(input: string): string {
+  // 改行コードを LF に統一してから、空行区切りでブロックに分割する。
+  // Normalise line endings then split on one-or-more blank lines.
+  const normalised = input.replace(/\r\n?/g, "\n");
+  const blocks = normalised
+    .split(/\n{2,}/)
+    .map((block) => block.replace(/^\n+|\n+$/g, ""))
+    .filter((block) => block.length > 0);
+  if (blocks.length === 0) return "";
+  return blocks
+    .map(
+      (block) =>
+        `<p>${block
+          .split("\n")
+          .map((line) => escapeHtml(line))
+          .join("<br />")}</p>`,
+    )
+    .join("");
+}
+
+type NodeHandler = (node: TiptapNode) => string;
+
+const nodeHandlers: Record<string, NodeHandler> = {};
+
+function convertNode(node: TiptapNode): string {
+  if (!node) return "";
+  const handler = nodeHandlers[node.type];
+  return handler ? handler(node) : convertChildren(node);
+}
+
+function convertChildren(node: TiptapNode): string {
+  if (!node.content) return "";
+  return node.content.map(convertNode).join("");
+}
+
+Object.assign(nodeHandlers, {
+  doc: (n) => convertChildren(n),
+  paragraph: (n) => `<p>${convertChildren(n)}</p>`,
+  heading: (n) => {
+    // 本文の見出しは body schema 上 h2–h6。`level` が欠落 / 1 以下の旧データは
+    // ページタイトル `h1` と衝突しないよう最小の本文見出し `h2` にフォールバック。
+    // Body headings span h2–h6; legacy `level: 1` / missing falls back to `h2`
+    // so it never collides with the page-title `h1` (PR #921 gemini medium).
+    const rawLevel = n.attrs?.level;
+    const level = typeof rawLevel === "number" && rawLevel >= 2 && rawLevel <= 6 ? rawLevel : 2;
+    return `<h${level}>${convertChildren(n)}</h${level}>`;
+  },
+  bulletList: (n) => `<ul>${convertListChildren(n)}</ul>`,
+  orderedList: (n) => `<ol>${convertListChildren(n)}</ol>`,
+  listItem: (n) => `<li>${convertChildren(n)}</li>`,
+  taskList: (n) => `<ul class="task-list">${convertChildren(n)}</ul>`,
+  taskItem: (n) => {
+    const checked = Boolean(n.attrs?.checked);
+    const box = `<input type="checkbox" disabled${checked ? ' checked="checked"' : ""} />`;
+    return `<li class="task-list-item">${box} ${convertChildren(n)}</li>`;
+  },
+  blockquote: (n) => `<blockquote>${convertChildren(n)}</blockquote>`,
+  codeBlock: (n) => {
+    const language = typeof n.attrs?.language === "string" ? n.attrs.language : "";
+    const codeText = collectPlainText(n);
+    const langAttr = language ? ` class="language-${escapeHtmlAttr(language)}"` : "";
+    return `<pre><code${langAttr}>${escapeHtml(codeText)}</code></pre>`;
+  },
+  mermaid: (n) => {
+    // PDF エクスポートは html2pdf.js / html2canvas で静的レンダリングするため、
+    // 実際の SVG を生成するには Mermaid の非同期 API を呼ぶ必要がある。エクスポート
+    // 経路を同期に保つ目的で、ここでは Mermaid ソースをコードブロック相当の
+    // プレースホルダー (`<pre><code class="language-mermaid">…</code></pre>`) として
+    // 出力する。少なくとも図のソースが PDF 上で失われず、必要に応じて後続パスで
+    // 事前レンダリングへ差し替えやすい形にしておく（Issue #945）。
+    // Render `mermaid` nodes as a `<pre><code class="language-mermaid">` block.
+    // Generating a real SVG would require an async call into Mermaid; this
+    // exporter is synchronous (html2pdf.js consumes the DOM immediately) so we
+    // emit the source verbatim as a placeholder. The diagram source is then
+    // preserved in the PDF and can be upgraded to pre-rendered SVG later
+    // without touching call sites (Issue #945).
+    const code = typeof n.attrs?.code === "string" ? n.attrs.code : "";
+    return `<pre><code class="language-mermaid">${escapeHtml(code)}</code></pre>`;
+  },
+  horizontalRule: () => "<hr />",
+  hardBreak: () => "<br />",
+  text: (n) => applyMarks(escapeHtml(n.text || ""), n.marks || []),
+  wikiLink: (n) => {
+    const title = typeof n.attrs?.title === "string" ? n.attrs.title : "";
+    return `[[${escapeHtml(title)}]]`;
+  },
+  image: (n) => {
+    const src = typeof n.attrs?.src === "string" ? n.attrs.src : "";
+    const alt = typeof n.attrs?.alt === "string" ? n.attrs.alt : "";
+    const title = typeof n.attrs?.title === "string" ? n.attrs.title : "";
+    const safeSrc = sanitizeUrl(src);
+    if (!safeSrc) return "";
+    const attrs = [`src="${escapeHtmlAttr(safeSrc)}"`, `alt="${escapeHtmlAttr(alt)}"`];
+    if (title) attrs.push(`title="${escapeHtmlAttr(title)}"`);
+    return `<img ${attrs.join(" ")} />`;
+  },
+  youtubeEmbed: (n) => {
+    const rawVideoId = n.attrs?.videoId;
+    const videoId = typeof rawVideoId === "string" ? rawVideoId.trim() : "";
+    // 異常な videoId をそのまま href に入れないよう厳格に検証する。
+    // Strictly validate videoId before composing the anchor href.
+    if (!/^[a-zA-Z0-9_-]{11}$/.test(videoId)) return "";
+    return `<a href="https://www.youtube.com/watch?v=${encodeURIComponent(videoId)}">YouTube</a>`;
+  },
+  link: (n) => convertChildren(n),
+  // 表組みのフィデリティは print 時に効くので最低限 HTML <table> に落とす。
+  // Render tables as real HTML tables so print layout stays usable.
+  table: (n) => `<table>${convertChildren(n)}</table>`,
+  tableRow: (n) => `<tr>${convertChildren(n)}</tr>`,
+  tableCell: (n) => `<td>${convertChildren(n)}</td>`,
+  tableHeader: (n) => `<th>${convertChildren(n)}</th>`,
+} satisfies Record<string, NodeHandler>);
+
+function convertListChildren(node: TiptapNode): string {
+  if (!node.content) return "";
+  return node.content.map(convertNode).join("");
+}
+
+/**
+ * codeBlock のテキストノードはマークを無視して raw 文字列を集める。
+ * Collect raw text content of a node tree (used by codeBlock).
+ */
+function collectPlainText(node: TiptapNode): string {
+  if (node.type === "text") return node.text ?? "";
+  if (!node.content) return "";
+  return node.content.map(collectPlainText).join("");
+}
+
+function applyMarks(text: string, marks: TiptapMark[]): string {
+  if (!marks || marks.length === 0) return text;
+  let result = text;
+  for (const mark of marks) {
+    switch (mark.type) {
+      case "bold":
+        result = `<strong>${result}</strong>`;
+        break;
+      case "italic":
+        result = `<em>${result}</em>`;
+        break;
+      case "strike":
+        result = `<s>${result}</s>`;
+        break;
+      case "underline":
+        result = `<u>${result}</u>`;
+        break;
+      case "code":
+        result = `<code>${result}</code>`;
+        break;
+      case "link": {
+        const href = typeof mark.attrs?.href === "string" ? mark.attrs.href : "";
+        const safeHref = sanitizeUrl(href);
+        if (!safeHref) break;
+        result = `<a href="${escapeHtmlAttr(safeHref)}">${result}</a>`;
+        break;
+      }
+      // 他の mark（highlight / color など）は print 時の重要度が低いので無視する。
+      // Other marks (highlight / color etc.) are dropped for export simplicity.
+    }
+  }
+  return result;
+}
+
+const HTML_ESCAPES: Record<string, string> = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;",
+};
+
+/** Escape text nodes for safe HTML body insertion. */
+function escapeHtml(input: string): string {
+  return input.replace(/[&<>"']/g, (c) => HTML_ESCAPES[c] ?? c);
+}
+
+/** Escape attribute values. Same set as body, but kept as a separate fn for clarity. */
+function escapeHtmlAttr(input: string): string {
+  return escapeHtml(input);
+}
+
+/**
+ * 安全な URL スキームだけを許可する。`javascript:` 等をはじいて XSS を防ぐ。
+ * Allow only safe URL schemes; strip `javascript:` and friends to prevent XSS.
+ */
+function sanitizeUrl(input: string): string {
+  const trimmed = input.trim();
+  if (!trimmed) return "";
+  if (/^(https?:|mailto:|tel:|\/|#)/i.test(trimmed)) return trimmed;
+  if (/^data:image\//i.test(trimmed)) return trimmed;
+  // 相対 URL（先頭が `./`・`../`・拡張子付きファイル名・パス断片）を許可する。
+  // 文字クラスに `.` を含めることで `image.png` 等のドット入りパスも通す
+  // （PR #921 gemini-code-assist high）。
+  //
+  // Allow relative URLs: `./`, `../`, or a first segment built from
+  // alphanumeric / `.` / `_` / `-` characters. Including `.` in the class
+  // lets dotted filenames like `image.png` through (PR #921 review).
+  if (/^(\.{0,2}\/|[a-zA-Z0-9_.-]+(\/|$))/.test(trimmed)) return trimmed;
+  return "";
+}
+
+/**
+ * PDF エクスポートのオプション。
+ * Options for {@link downloadPdf}.
+ */
+export interface PdfExportOptions {
+  /** Default title when the page title is empty. */
+  defaultTitle?: string;
+  /** Label for the source-attribution block (e.g. "📎 引用元"). */
+  attributionLabel?: string;
+  /** Page format. Defaults to `"a4"`. */
+  format?: "a4" | "letter";
+}
+
+/**
+ * 引用元ブロックを HTML として組み立てる。`sourceUrl` が空のときは空文字列を返す。
+ * Build the source-attribution block. Returns "" when `sourceUrl` is empty.
+ */
+function buildSourceAttribution(sourceUrl?: string | null, attributionLabel?: string): string {
+  if (!sourceUrl?.trim()) return "";
+  const safeUrl = sanitizeUrl(sourceUrl.trim());
+  if (!safeUrl) return "";
+  const label = (attributionLabel?.trim() || "📎 Source") + ":";
+  return (
+    `<blockquote class="zedi-source">` +
+    `${escapeHtml(label)} <a href="${escapeHtmlAttr(safeUrl)}">${escapeHtml(safeUrl)}</a>` +
+    `</blockquote>`
+  );
+}
+
+/**
+ * オフスクリーン DOM に組み立てたエクスポート用ルート要素を返す。
+ * Compose the offscreen export root used as html2pdf.js source.
+ */
+function buildExportRoot(html: string): HTMLDivElement {
+  const root = document.createElement("div");
+  root.className = "zedi-pdf-root";
+  root.style.cssText = [
+    "position:fixed",
+    "left:-99999px",
+    "top:0",
+    // A4 width at ~96dpi (210mm ≈ 794px). html2canvas captures this width.
+    "width:794px",
+    "padding:0",
+    "background:#fff",
+    "color:#111",
+    "font-family:'Hiragino Kaku Gothic ProN','Hiragino Sans','Yu Gothic','Meiryo','Noto Sans JP',system-ui,-apple-system,sans-serif",
+    "font-size:14px",
+    "line-height:1.7",
+  ].join(";");
+  root.innerHTML = html;
+  return root;
+}
+
+/**
+ * `downloadPdf` の内部で `html2pdf.js` を遅延 import するための疎結合点。
+ * テストで `vi.mock("html2pdf.js")` 経由でモックしやすくしてある。
+ *
+ * Indirection so tests can `vi.mock("html2pdf.js")` and assert calls without
+ * pulling the real library (which depends on canvas / DOM features absent in
+ * jsdom).
+ */
+async function loadHtml2Pdf(): Promise<typeof import("html2pdf.js").default> {
+  const mod = await import("html2pdf.js");
+  return mod.default;
+}
+
+/**
+ * ページ本文を PDF として保存する。`tiptapToHtml` で組み立てた HTML を
+ * オフスクリーン要素に流し込み、`html2pdf.js`（html2canvas + jsPDF）で
+ * 直接ダウンロードを発火する。
+ *
+ * Save the page body as a PDF. Renders `tiptapToHtml` output into an
+ * offscreen element and pipes it through `html2pdf.js` (html2canvas + jsPDF).
+ */
+export async function downloadPdf(
+  title: string,
+  content: string,
+  sourceUrl?: string | null,
+  options?: PdfExportOptions,
+): Promise<void> {
+  const { defaultTitle = "Untitled", attributionLabel, format = "a4" } = options ?? {};
+  const normalizedTitle = title.trim();
+  const bodyHtml = tiptapToHtml(content);
+  const attributionHtml = buildSourceAttribution(sourceUrl, attributionLabel);
+  const titleHtml = normalizedTitle
+    ? `<h1 style="margin:0 0 16px 0;font-size:24px;">${escapeHtml(normalizedTitle)}</h1>`
+    : "";
+
+  // 上下左右の余白は CSS padding に寄せず、jsPDF の `margin` で管理する。
+  // Manage margins via jsPDF options rather than CSS to keep page breaks predictable.
+  const root = buildExportRoot(`${titleHtml}${attributionHtml}${bodyHtml}`);
+  document.body.appendChild(root);
+
+  try {
+    const html2pdf = await loadHtml2Pdf();
+    const filename = sanitizeFilename(normalizedTitle || defaultTitle) + ".pdf";
+    // `pagebreak` は html2pdf.js v0.10+ の実機能だが、同梱の `.d.ts` には未定義。
+    // また `html2pdf()` のオーバーロード解決の都合で戻り値が
+    // `Html2PdfWorker | Promise<void>` のユニオンに見えるため、ここで
+    // `unknown` 経由のキャストで最小限の構造的型に寄せる。
+    //
+    // `pagebreak` is supported at runtime since html2pdf.js v0.10 but is not
+    // in the bundled `.d.ts`. The `html2pdf()` overload resolution also widens
+    // the return type to a union, so we narrow it through `unknown` to a
+    // chainable worker that matches what the library exposes at runtime.
+    const opts = {
+      filename,
+      margin: [12, 12, 16, 12] as [number, number, number, number],
+      image: { type: "jpeg" as const, quality: 0.95 },
+      enableLinks: true,
+      html2canvas: { scale: 2, useCORS: true, backgroundColor: "#ffffff" },
+      jsPDF: { unit: "mm", format, orientation: "portrait" as const },
+      pagebreak: { mode: ["css", "legacy"], avoid: ["pre", "table", "img", "blockquote"] },
+    };
+
+    interface Html2PdfChain {
+      set(options: typeof opts): Html2PdfChain;
+      from(src: HTMLElement): Html2PdfChain;
+      save(): Promise<void>;
+    }
+    const worker = html2pdf() as unknown as Html2PdfChain;
+    await worker.set(opts).from(root).save();
+  } finally {
+    root.remove();
+  }
+}
diff --git a/src/lib/userAiCredentials.ts b/src/lib/userAiCredentials.ts
new file mode 100644
index 00000000..c6af24ae
--- /dev/null
+++ b/src/lib/userAiCredentials.ts
@@ -0,0 +1,58 @@
+/**
+ * Client for `/api/user/ai-credentials` (#951).
+ */
+
+export type UserAiCredentialProvider = "anthropic" | "openai" | "google";
+
+export interface UserAiCredentialAvailability {
+  provider: UserAiCredentialProvider;
+  configured: boolean;
+}
+
+export interface UserAiCredentialsStatus {
+  storageEnabled: boolean;
+  providers: UserAiCredentialAvailability[];
+}
+
+const getApiBaseUrl = () => (import.meta.env.VITE_API_BASE_URL as string) ?? "";
+
+const REST_OPTS: RequestInit = { credentials: "include" };
+
+async function jsonOrThrow<T>(res: Response, hint: string): Promise<T> {
+  if (res.ok) return (await res.json()) as T;
+  const body = await res.json().catch(() => null);
+  const message =
+    (body && typeof body === "object" && "message" in body && typeof body.message === "string"
+      ? body.message
+      : null) ?? `${hint} failed: ${res.status}`;
+  throw new Error(message);
+}
+
+/** Fetch which BYOK providers have server-stored credentials. */
+export async function fetchUserAiCredentialsStatus(): Promise<UserAiCredentialsStatus> {
+  const res = await fetch(`${getApiBaseUrl()}/api/user/ai-credentials`, REST_OPTS);
+  return jsonOrThrow<UserAiCredentialsStatus>(res, "fetchUserAiCredentialsStatus");
+}
+
+/** Store an encrypted credential for a provider. */
+export async function upsertUserAiCredential(
+  provider: UserAiCredentialProvider,
+  apiKey: string,
+): Promise<void> {
+  const res = await fetch(`${getApiBaseUrl()}/api/user/ai-credentials/${provider}`, {
+    ...REST_OPTS,
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ apiKey }),
+  });
+  await jsonOrThrow(res, "upsertUserAiCredential");
+}
+
+/** Remove a stored credential. */
+export async function deleteUserAiCredential(provider: UserAiCredentialProvider): Promise<void> {
+  const res = await fetch(`${getApiBaseUrl()}/api/user/ai-credentials/${provider}`, {
+    ...REST_OPTS,
+    method: "DELETE",
+  });
+  await jsonOrThrow(res, "deleteUserAiCredential");
+}
diff --git a/src/lib/wikiCompose/backends.ts b/src/lib/wikiCompose/backends.ts
new file mode 100644
index 00000000..d5b4f6dd
--- /dev/null
+++ b/src/lib/wikiCompose/backends.ts
@@ -0,0 +1,64 @@
+/**
+ * Wiki Compose execution backends (#951) — mirrors server `ExecutionBackend`.
+ */
+
+/** Zedi-managed or BYOK provider-specific backends. */
+export type ComposeExecutionBackend =
+  | "zedi_managed"
+  | "user_anthropic"
+  | "user_openai"
+  | "user_google";
+
+export const COMPOSE_BACKEND_OPTIONS: readonly ComposeExecutionBackend[] = [
+  "zedi_managed",
+  "user_anthropic",
+  "user_openai",
+  "user_google",
+] as const;
+
+export type ComposeBackendProvider = "anthropic" | "openai" | "google";
+
+/** UI metadata for each backend option. */
+export interface ComposeBackendOptionMeta {
+  id: ComposeExecutionBackend;
+  provider: ComposeBackendProvider | null;
+  labelKey: string;
+  descriptionKey: string;
+}
+
+export const COMPOSE_BACKEND_META: readonly ComposeBackendOptionMeta[] = [
+  {
+    id: "zedi_managed",
+    provider: null,
+    labelKey: "wikiCompose.backend.zediManaged",
+    descriptionKey: "wikiCompose.backend.zediManagedDesc",
+  },
+  {
+    id: "user_anthropic",
+    provider: "anthropic",
+    labelKey: "wikiCompose.backend.userAnthropic",
+    descriptionKey: "wikiCompose.backend.userAnthropicDesc",
+  },
+  {
+    id: "user_openai",
+    provider: "openai",
+    labelKey: "wikiCompose.backend.userOpenai",
+    descriptionKey: "wikiCompose.backend.userOpenaiDesc",
+  },
+  {
+    id: "user_google",
+    provider: "google",
+    labelKey: "wikiCompose.backend.userGoogle",
+    descriptionKey: "wikiCompose.backend.userGoogleDesc",
+  },
+];
+
+export function isUserByokComposeBackend(
+  backend: ComposeExecutionBackend,
+): backend is Exclude<ComposeExecutionBackend, "zedi_managed"> {
+  return backend !== "zedi_managed";
+}
+
+export function usesZediCu(backend: ComposeExecutionBackend): boolean {
+  return backend === "zedi_managed";
+}
diff --git a/src/lib/wikiCompose/composeService.test.ts b/src/lib/wikiCompose/composeService.test.ts
new file mode 100644
index 00000000..1dd9d6b7
--- /dev/null
+++ b/src/lib/wikiCompose/composeService.test.ts
@@ -0,0 +1,133 @@
+/**
+ * `composeService` SSE 経路ユニットテスト (#950)。
+ *
+ * `runSession` の SSE パーサが多行 data:, 複数イベント連結, `event:` 名 (未使用),
+ * 不完全レコードを正しく扱えるかを `ReadableStream` モックで検証する。
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { runSession } from "./composeService";
+import type { ComposeSseEvent } from "./types";
+
+function makeReadable(chunks: string[]): ReadableStream<Uint8Array> {
+  const enc = new TextEncoder();
+  let i = 0;
+  return new ReadableStream({
+    pull(controller) {
+      if (i >= chunks.length) {
+        controller.close();
+        return;
+      }
+      controller.enqueue(enc.encode(chunks[i] as string));
+      i += 1;
+    },
+  });
+}
+
+function makeFetchOk(chunks: string[]): typeof fetch {
+  return vi.fn(async () => {
+    const body = makeReadable(chunks);
+    return new Response(body, {
+      status: 200,
+      headers: { "content-type": "text/event-stream" },
+    });
+  });
+}
+
+describe("composeService.runSession SSE parsing", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", makeFetchOk([]));
+  });
+
+  it("dispatches multiple events from a single stream", async () => {
+    const stream = [
+      `event: started\n`,
+      `data: ${JSON.stringify({ type: "started", sessionId: "s1", graphId: "g1" })}\n\n`,
+      `event: compose_phase\n`,
+      `data: ${JSON.stringify({ type: "compose_phase", phase: "brief", status: "entered" })}\n\n`,
+      `event: done\ndata: ${JSON.stringify({ type: "done", status: "completed" })}\n\n`,
+    ];
+    vi.stubGlobal("fetch", makeFetchOk(stream));
+
+    const events: ComposeSseEvent[] = [];
+    await runSession({
+      pageId: "page-1",
+      sessionId: "sess-1",
+      onEvent: (e) => {
+        events.push(e);
+      },
+    });
+
+    expect(events.map((e) => e.type)).toEqual(["started", "compose_phase", "done"]);
+  });
+
+  it("handles a record split across two fetch chunks", async () => {
+    const json = JSON.stringify({ type: "token", content: "hello" });
+    const stream = [
+      // The split intentionally falls inside the `data:` payload.
+      `event: token\ndata: ${json.slice(0, 5)}`,
+      `${json.slice(5)}\n\n`,
+    ];
+    vi.stubGlobal("fetch", makeFetchOk(stream));
+
+    const events: ComposeSseEvent[] = [];
+    await runSession({
+      pageId: "page-1",
+      sessionId: "sess-1",
+      onEvent: (e) => {
+        events.push(e);
+      },
+    });
+
+    expect(events).toEqual([{ type: "token", content: "hello" }]);
+  });
+
+  it("skips unparseable records without throwing", async () => {
+    const goodEvent = JSON.stringify({ type: "status", phase: "completed" });
+    const stream = [
+      `event: garbled\ndata: {not json}\n\n`,
+      `event: status\ndata: ${goodEvent}\n\n`,
+    ];
+    vi.stubGlobal("fetch", makeFetchOk(stream));
+
+    const events: ComposeSseEvent[] = [];
+    await runSession({
+      pageId: "page-1",
+      sessionId: "sess-1",
+      onEvent: (e) => {
+        events.push(e);
+      },
+    });
+
+    expect(events).toEqual([{ type: "status", phase: "completed" }]);
+  });
+
+  it("aborts when the AbortSignal fires", async () => {
+    // Build a stream that never closes so we can verify the abort path.
+    // 終わらないストリームを作って abort パスを確認する。
+    const controller = new AbortController();
+    const dataLine = `event: token\ndata: ${JSON.stringify({ type: "token", content: "x" })}\n\n`;
+    let pulls = 0;
+    const stream = new ReadableStream<Uint8Array>({
+      pull(c) {
+        pulls += 1;
+        c.enqueue(new TextEncoder().encode(dataLine));
+        if (pulls === 2) controller.abort();
+      },
+    });
+    vi.stubGlobal("fetch", async () => new Response(stream, { status: 200 }));
+
+    const events: ComposeSseEvent[] = [];
+    await expect(
+      runSession({
+        pageId: "page-1",
+        sessionId: "sess-1",
+        onEvent: (e) => {
+          events.push(e);
+        },
+        signal: controller.signal,
+      }),
+    ).rejects.toThrow(/abort/i);
+
+    expect(events.length).toBeGreaterThan(0);
+  });
+});
diff --git a/src/lib/wikiCompose/composeService.ts b/src/lib/wikiCompose/composeService.ts
new file mode 100644
index 00000000..abfc6137
--- /dev/null
+++ b/src/lib/wikiCompose/composeService.ts
@@ -0,0 +1,282 @@
+/**
+ * Wiki Compose REST + SSE client (#950).
+ *
+ * `/api/pages/:pageId/compose-sessions` 系を叩く薄いクライアント。
+ * - `createSession` / `getSession` / `cancelSession` は通常の REST 呼び出し。
+ * - `runSession` / `resumeSession` は SSE ストリームを返し、呼び出し側がイベント
+ *   を pattern match して state を進める。
+ *
+ * Thin REST + SSE client used by `useWikiComposeSession`. The SSE consumer is
+ * built around the wire spec produced by `streamSSE` on the server (each event
+ * is `event: <name>\n` + `data: <JSON>\n\n`).
+ */
+import type {
+  ComposeSession,
+  ComposeSessionUiProjection,
+  ComposeSseEvent,
+  ComposeSessionStatus,
+} from "./types";
+import { WIKI_COMPOSE_GRAPH_ID } from "./types";
+
+const getApiBaseUrl = () => (import.meta.env.VITE_API_BASE_URL as string) ?? "";
+
+/** Common request options that include cross-origin cookies. */
+const REST_OPTS: RequestInit = { credentials: "include" };
+
+/** Error thrown when the server returns a non-2xx response. */
+export class ComposeApiError extends Error {
+  readonly status: number;
+  readonly body: unknown;
+  constructor(status: number, message: string, body: unknown) {
+    super(message);
+    this.name = "ComposeApiError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+async function jsonOrThrow<T>(res: Response, hint: string): Promise<T> {
+  if (res.ok) return (await res.json()) as T;
+  const body = await res.json().catch(() => null);
+  const message =
+    (body && typeof body === "object" && "message" in body && typeof body.message === "string"
+      ? body.message
+      : null) ?? `${hint} failed: ${res.status}`;
+  throw new ComposeApiError(res.status, message, body);
+}
+
+// ── REST ────────────────────────────────────────────────────────────────────
+
+/** Body of `POST /api/pages/:pageId/compose-sessions`. */
+export interface CreateSessionInput {
+  pageId: string;
+  graphId?: string;
+  backend?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/** Create a new compose session row. Defaults to the orchestrator graph. */
+export async function createSession(input: CreateSessionInput): Promise<ComposeSession> {
+  const apiBase = getApiBaseUrl();
+  const res = await fetch(
+    `${apiBase}/api/pages/${encodeURIComponent(input.pageId)}/compose-sessions`,
+    {
+      ...REST_OPTS,
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        graphId: input.graphId ?? WIKI_COMPOSE_GRAPH_ID,
+        backend: input.backend,
+        metadata: input.metadata,
+      }),
+    },
+  );
+  const data = await jsonOrThrow<{ session: ComposeSession }>(res, "createSession");
+  return data.session;
+}
+
+/**
+ * `GET /compose-sessions/:id` の応答（行 + 任意の checkpoint projection）。
+ * Response of `GET /compose-sessions/:id` (session row + optional checkpoint projection).
+ */
+export interface GetComposeSessionResult {
+  session: ComposeSession;
+  projection: ComposeSessionUiProjection | null;
+}
+
+/**
+ * Compose セッション行と、再開用 projection を取得する (#950)。
+ * Fetch a compose session row and optional UI projection for reload.
+ */
+export async function getSession(
+  pageId: string,
+  sessionId: string,
+): Promise<GetComposeSessionResult> {
+  const apiBase = getApiBaseUrl();
+  const res = await fetch(
+    `${apiBase}/api/pages/${encodeURIComponent(pageId)}/compose-sessions/${encodeURIComponent(sessionId)}`,
+    { ...REST_OPTS, method: "GET" },
+  );
+  const data = await jsonOrThrow<{
+    session: ComposeSession;
+    projection?: ComposeSessionUiProjection | null;
+  }>(res, "getSession");
+  return { session: data.session, projection: data.projection ?? null };
+}
+
+/** Cancel a compose session (sets status=cancelled). */
+export async function cancelSession(
+  pageId: string,
+  sessionId: string,
+): Promise<ComposeSessionStatus> {
+  const apiBase = getApiBaseUrl();
+  const res = await fetch(
+    `${apiBase}/api/pages/${encodeURIComponent(pageId)}/compose-sessions/${encodeURIComponent(sessionId)}`,
+    { ...REST_OPTS, method: "DELETE" },
+  );
+  const data = await jsonOrThrow<{ status: ComposeSessionStatus }>(res, "cancelSession");
+  return data.status;
+}
+
+// ── SSE helpers ─────────────────────────────────────────────────────────────
+
+/** Per-event handler (sync or async). */
+export type ComposeEventHandler = (event: ComposeSseEvent) => void | Promise<void>;
+
+/**
+ * Run a compose session. Resolves when the SSE stream terminates (after a
+ * `done` event or when the connection drops). Per-event side effects are
+ * delivered to `onEvent`; the consumer is responsible for accumulating any
+ * state.
+ *
+ * @param input.pageId    Target page id.
+ * @param input.sessionId Compose session id.
+ * @param input.body      `body.input` for the graph (initial input or seed).
+ * @param input.onEvent   Per-event handler.
+ * @param input.signal    Aborts the underlying `fetch` and SSE stream.
+ */
+export async function runSession(input: {
+  pageId: string;
+  sessionId: string;
+  body?: unknown;
+  onEvent: ComposeEventHandler;
+  signal?: AbortSignal;
+}): Promise<void> {
+  const apiBase = getApiBaseUrl();
+  const res = await fetch(
+    `${apiBase}/api/pages/${encodeURIComponent(input.pageId)}/compose-sessions/${encodeURIComponent(input.sessionId)}/run`,
+    {
+      ...REST_OPTS,
+      method: "POST",
+      headers: { "Content-Type": "application/json", Accept: "text/event-stream" },
+      body: JSON.stringify({ input: input.body ?? {} }),
+      signal: input.signal,
+    },
+  );
+  if (!res.ok) {
+    const body = await res.json().catch(() => null);
+    const message =
+      (body && typeof body === "object" && "message" in body && typeof body.message === "string"
+        ? body.message
+        : null) ?? `runSession failed: ${res.status}`;
+    throw new ComposeApiError(res.status, message, body);
+  }
+  await consumeSseStream(res, input.onEvent, input.signal);
+}
+
+/**
+ * Resume a compose session from an interrupt. The `resume` payload shape is
+ * graph-specific:
+ * - `human_review_brief` — `{ answers, appendToExisting?, researchMaxIterations? }`
+ * - `human_review_research` — `{ approvedSourceIds, rejectedSourceIds?, note? }`
+ * - `human_review_outline` — `{ sections }`
+ * - `conflict_resolution` — `{ acknowledged: true, note?: string }`
+ *
+ * The server returns a JSON body `{ status, output }` on resume completion (no
+ * SSE stream). Callers must hydrate UI state from `output` (interrupt payloads
+ * in `__interrupt__` or `completion` on the final outline approve). Do not call
+ * `runSession` while the row is `interrupted` — use `PATCH /resume` only.
+ */
+export async function resumeSession(input: {
+  pageId: string;
+  sessionId: string;
+  resume: unknown;
+  signal?: AbortSignal;
+}): Promise<{ status: ComposeSessionStatus; output: unknown }> {
+  const apiBase = getApiBaseUrl();
+  const res = await fetch(
+    `${apiBase}/api/pages/${encodeURIComponent(input.pageId)}/compose-sessions/${encodeURIComponent(input.sessionId)}/resume`,
+    {
+      ...REST_OPTS,
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ resume: input.resume }),
+      signal: input.signal,
+    },
+  );
+  return jsonOrThrow<{ status: ComposeSessionStatus; output: unknown }>(res, "resumeSession");
+}
+
+/**
+ * Consume an SSE response body, splitting on `\n\n` and dispatching each event.
+ * Tolerant to multi-line `data:` payloads and `:`-comments. Errors out of the
+ * loop on `signal.aborted`.
+ *
+ * SSE 仕様 (https://html.spec.whatwg.org/multipage/server-sent-events.html)
+ * のシンプルなパーサ。`event:` 行を type、`data:` 行を payload として組み立て、
+ * 空行で 1 イベント分を確定する。複数行 `data:` は `\n` 連結。
+ */
+async function consumeSseStream(
+  res: Response,
+  onEvent: ComposeEventHandler,
+  signal?: AbortSignal,
+): Promise<void> {
+  const reader = res.body?.getReader();
+  if (!reader) throw new Error("SSE stream has no body");
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  while (true) {
+    if (signal?.aborted) {
+      await reader.cancel().catch(() => undefined);
+      throw new DOMException("Aborted", "AbortError");
+    }
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+
+    // Split on the SSE record separator (blank line).
+    // `\n\n` または `\r\n\r\n` をレコード区切りとして扱う。
+    let sep: number;
+    while ((sep = findRecordSeparator(buffer)) !== -1) {
+      const rawRecord = buffer.slice(0, sep);
+      const sepLen = buffer.startsWith("\r\n\r\n", sep) ? 4 : 2;
+      buffer = buffer.slice(sep + sepLen);
+      const event = parseSseRecord(rawRecord);
+      if (event) await onEvent(event);
+    }
+  }
+  // Flush any trailing buffered record (in case the server omits the final blank line).
+  buffer += decoder.decode();
+  const tail = buffer.trim();
+  if (tail.length > 0) {
+    const event = parseSseRecord(tail);
+    if (event) await onEvent(event);
+  }
+}
+
+function findRecordSeparator(buf: string): number {
+  const a = buf.indexOf("\n\n");
+  const b = buf.indexOf("\r\n\r\n");
+  if (a === -1) return b;
+  if (b === -1) return a;
+  return Math.min(a, b);
+}
+
+function parseSseRecord(record: string): ComposeSseEvent | null {
+  const dataLines: string[] = [];
+  for (const rawLine of record.split(/\r?\n/)) {
+    const line = rawLine;
+    if (line.length === 0 || line.startsWith(":")) continue;
+    if (line.startsWith("data:")) {
+      dataLines.push(line.slice(5).trim());
+    }
+    // `event:` is informational on the wire (sseMapper already inlines `type`
+    // into the JSON payload), so we don't need to read it.
+  }
+  if (dataLines.length === 0) return null;
+  const payload = dataLines.join("\n");
+  try {
+    const parsed = JSON.parse(payload);
+    if (
+      parsed &&
+      typeof parsed === "object" &&
+      typeof (parsed as { type?: unknown }).type === "string"
+    ) {
+      return parsed as ComposeSseEvent;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
diff --git a/src/lib/wikiCompose/navigation.test.ts b/src/lib/wikiCompose/navigation.test.ts
new file mode 100644
index 00000000..40af07bc
--- /dev/null
+++ b/src/lib/wikiCompose/navigation.test.ts
@@ -0,0 +1,29 @@
+import { describe, it, expect, vi } from "vitest";
+import { COMPOSE_SEED_STATE_KEY, navigateToWikiCompose, wikiComposePath } from "./navigation";
+
+describe("wikiCompose navigation", () => {
+  it("wikiComposePath builds the compose route", () => {
+    expect(wikiComposePath("note-1", "page-1")).toBe("/notes/note-1/page-1/compose");
+  });
+
+  it("navigateToWikiCompose forwards optional seed on location state", () => {
+    const navigate = vi.fn();
+    navigateToWikiCompose({
+      navigate,
+      noteId: "note-1",
+      pageId: "page-1",
+      seed: { outline: "- a", conversationText: "User: hi" },
+    });
+    expect(navigate).toHaveBeenCalledWith("/notes/note-1/page-1/compose", {
+      state: {
+        [COMPOSE_SEED_STATE_KEY]: { outline: "- a", conversationText: "User: hi" },
+      },
+    });
+  });
+
+  it("navigateToWikiCompose omits state when seed is absent", () => {
+    const navigate = vi.fn();
+    navigateToWikiCompose({ navigate, noteId: "n", pageId: "p" });
+    expect(navigate).toHaveBeenCalledWith("/notes/n/p/compose", { state: undefined });
+  });
+});
diff --git a/src/lib/wikiCompose/navigation.ts b/src/lib/wikiCompose/navigation.ts
new file mode 100644
index 00000000..99d1fa0d
--- /dev/null
+++ b/src/lib/wikiCompose/navigation.ts
@@ -0,0 +1,62 @@
+/**
+ * Wiki Compose navigation helpers (#950).
+ *
+ * チャットからのページ作成や Promote to Wiki など、旧
+ * `pendingChatPageGeneration` navigate state の代わりに Compose 画面へ遷移する。
+ *
+ * Replaces the legacy `pendingChatPageGeneration` location state with a direct
+ * route to the split-screen Compose UI. Optional seed data is forwarded so the
+ * orchestrator can bias the Brief phase.
+ */
+import type { NavigateFunction } from "react-router-dom";
+import type { PendingChatPageGenerationState } from "@/types/chatPageGeneration";
+
+/**
+ * `location.state` に載せる Compose seed のキー（チャット → ページ → compose）。
+ * Location state key for Compose seed data (chat → page → compose).
+ */
+export const COMPOSE_SEED_STATE_KEY = "composeSeed" as const;
+
+/**
+ * チャット経由で Compose に入るときの seed。
+ * Seed payload stored on `location.state` when entering Compose from chat.
+ */
+export type ComposeNavigationSeed = PendingChatPageGenerationState;
+
+/**
+ * `navigateToWikiCompose` の引数。
+ * Parameters for {@link navigateToWikiCompose}.
+ */
+export interface NavigateToWikiComposeParams {
+  navigate: NavigateFunction;
+  noteId: string;
+  pageId: string;
+  /**
+   * Brief / 調査に渡す任意のチャット文脈。
+   * Optional chat context to seed the Brief / research phases.
+   */
+  seed?: ComposeNavigationSeed;
+}
+
+/**
+ * ページの Wiki Compose 分割画面へ遷移する。`seed` があるときは location state に載せる。
+ * Navigate to the Wiki Compose split-screen; `seed` is stored on location state when set.
+ */
+export function navigateToWikiCompose({
+  navigate,
+  noteId,
+  pageId,
+  seed,
+}: NavigateToWikiComposeParams): void {
+  navigate(`/notes/${noteId}/${pageId}/compose`, {
+    state: seed ? { [COMPOSE_SEED_STATE_KEY]: seed } : undefined,
+  });
+}
+
+/**
+ * ノートネイティブページ向け Compose URL（ツールバー / PageActionHub 入口）。
+ * Build the Compose URL for a note-native page (toolbar / PageActionHub entry).
+ */
+export function wikiComposePath(noteId: string, pageId: string): string {
+  return `/notes/${noteId}/${pageId}/compose`;
+}
diff --git a/src/lib/wikiCompose/types.ts b/src/lib/wikiCompose/types.ts
new file mode 100644
index 00000000..2d6649e4
--- /dev/null
+++ b/src/lib/wikiCompose/types.ts
@@ -0,0 +1,219 @@
+/**
+ * Wiki Compose wire types — frontend mirror of `server/api/src/agents/...`
+ * (#950).
+ *
+ * Compose session のクライアント側 wire 型。バックエンドの `sseEvents.ts` と
+ * `graphs/wikiCompose/types.ts` を 1:1 にミラーする。サーバー側を変更したら
+ * 本ファイルも追随する（drift 検知テストはまだ自動化していない）。
+ *
+ * Mirrors the backend wire shapes so the React layer can pattern-match
+ * without doing structural type guards everywhere. Keep this file
+ * dependency-free so it's safe to import from anywhere in the app.
+ */
+
+// ── Page snapshot ──────────────────────────────────────────────────────────
+export interface PageSnapshot {
+  pageId: string;
+  title: string;
+  body: string;
+  hasContent: boolean;
+}
+
+// ── Brief phase ────────────────────────────────────────────────────────────
+export interface BriefOption {
+  id: string;
+  label: string;
+  hint?: string;
+}
+
+export interface BriefQuestion {
+  id: string;
+  question: string;
+  rationale?: string;
+  options: BriefOption[];
+  required: boolean;
+}
+
+export interface BriefAnswer {
+  questionId: string;
+  selectedOptionIds: string[];
+  freeText?: string;
+}
+
+export interface BriefResult {
+  answers: BriefAnswer[];
+  summary: string;
+  appendToExisting: boolean;
+}
+
+// ── Research sources (subset of backend `Source`) ──────────────────────────
+export interface ResearchSource {
+  id: string;
+  kind: "web" | "wiki" | "fetched";
+  title: string;
+  url?: string;
+  finalUrl?: string;
+  snippet?: string;
+  excerpt?: string;
+  pageId?: string;
+  noteId?: string;
+}
+
+export interface ResearchBatch {
+  id: string;
+  iteration: number;
+  sources: ResearchSource[];
+  // The full evaluation lives in state; the wire event carries only summary
+  // fields, but the interrupt payload may include it.
+  evaluation?: {
+    score: number;
+    rationale: string;
+    missingAspects: string[];
+  } | null;
+  createdAt: string;
+}
+
+// ── Structure / draft ──────────────────────────────────────────────────────
+export interface OutlineSection {
+  id: string;
+  heading: string;
+  depth: number;
+  intent: string;
+  sourceIds?: string[];
+}
+
+export interface DraftedSection {
+  sectionId: string;
+  heading: string;
+  body: string;
+  citedSourceIds: string[];
+  completedAt: string;
+}
+
+// ── Compose session row (REST shape from POST/GET) ─────────────────────────
+export type ComposeSessionStatus =
+  | "pending"
+  | "running"
+  | "interrupted"
+  | "completed"
+  | "cancelled"
+  | "failed";
+
+export interface ComposeSession {
+  id: string;
+  pageId: string;
+  userId: string;
+  graphId: string;
+  backend: string;
+  phase: string;
+  status: ComposeSessionStatus;
+  metadata?: Record<string, unknown> | null;
+  lastError?: string | null;
+  closedAt?: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * Checkpoint projection returned by `GET /compose-sessions/:id` for reload (#950).
+ * チェックポイントから復元した UI 用スライス。
+ */
+/**
+ * Summary shown at the P5 `conflict_resolution` interrupt (#953).
+ * P5 `conflict_resolution` 割り込みで表示する要約。
+ */
+export interface ResearchConflictSummary {
+  approved: Array<{ id: string; title: string }>;
+  rejected: Array<{ id: string; title: string }>;
+  rationale: string;
+}
+
+export interface ComposeSessionUiProjection {
+  phase?: "brief" | "research" | "conflict" | "structure" | "draft" | "completed";
+  briefQuestions?: BriefQuestion[];
+  pageSnapshot?: PageSnapshot;
+  pendingSources?: ResearchSource[];
+  latestBatch?: ResearchBatch | null;
+  approvedSources?: ResearchSource[];
+  researchConflictSummary?: ResearchConflictSummary;
+  outlineProposal?: OutlineSection[];
+  draftedSections?: DraftedSection[];
+  completedMarkdown?: string | null;
+}
+
+// ── Interrupt payloads (discriminated union) ───────────────────────────────
+export type ComposeInterruptPayload =
+  | {
+      kind: "human_review_brief";
+      questions: BriefQuestion[];
+      pageSnapshot: PageSnapshot;
+    }
+  | {
+      kind: "human_review_research";
+      batch: ResearchBatch | null;
+      pendingSources: ResearchSource[];
+    }
+  | {
+      kind: "human_review_outline";
+      outline: OutlineSection[];
+      approvedSources: ResearchSource[];
+    }
+  | {
+      kind: "conflict_resolution";
+      conflicts: ResearchConflictSummary;
+    };
+
+// ── SSE event union (mirrors backend `SseEvent`) ───────────────────────────
+export type ComposeSseEvent =
+  | { type: "started"; sessionId: string; graphId: string; phase?: string }
+  | { type: "status"; phase: string; message?: string }
+  | { type: "token"; node?: string; content: string }
+  | { type: "tool_start"; tool: string; input?: Record<string, unknown> }
+  | { type: "tool_end"; tool: string; outputLength?: number; error?: string }
+  | {
+      type: "usage";
+      inputTokens: number;
+      outputTokens: number;
+      costUnits: number;
+      usagePercent: number;
+    }
+  | { type: "interrupt"; payload?: ComposeInterruptPayload }
+  | { type: "done"; status: "completed" | "interrupted" | "failed" }
+  | { type: "error"; message: string; retryable?: boolean }
+  | {
+      type: "research_iteration";
+      iteration: number;
+      status: "planned" | "refined";
+      queryCount: number;
+    }
+  | {
+      type: "research_evaluation";
+      iteration: number;
+      score: number;
+      rationale: string;
+      missingAspectsCount: number;
+    }
+  | {
+      type: "research_batch";
+      batchId: string;
+      iteration: number;
+      sourceCount: number;
+      score: number | null;
+      exitReason: "score_threshold" | "max_iterations";
+    }
+  | {
+      type: "compose_phase";
+      phase: "brief" | "research" | "conflict" | "structure" | "draft" | "completed";
+      status: "entered" | "completed";
+    }
+  | {
+      type: "compose_section";
+      sectionId: string;
+      heading: string;
+      status: "started" | "completed";
+      index: number;
+      total: number;
+    };
+
+/** Convenience tag for the orchestrator graph id used by the frontend. */
+export const WIKI_COMPOSE_GRAPH_ID = "wiki-compose";
diff --git a/src/pages/NotePageView.test.tsx b/src/pages/NotePageView.test.tsx
index 1e926882..2cd2218f 100644
--- a/src/pages/NotePageView.test.tsx
+++ b/src/pages/NotePageView.test.tsx
@@ -22,6 +22,7 @@ const {
   mockSetPageContext,
   mockExportMarkdown,
   mockCopyMarkdown,
+  mockExportPdf,
   mockRemoveFromNoteMutate,
   mockUseMarkdownExport,
 } = vi.hoisted(() => ({
@@ -39,6 +40,7 @@ const {
   mockSetPageContext: vi.fn(),
   mockExportMarkdown: vi.fn(),
   mockCopyMarkdown: vi.fn().mockResolvedValue(undefined),
+  mockExportPdf: vi.fn().mockResolvedValue(undefined),
   mockRemoveFromNoteMutate: vi.fn(),
   // `useMarkdownExport(title, body, sourceUrl)` の呼び出し引数を捕捉するための
   // モック。Codex P1 (PR #893) の「export/copy が `page.content` を読んで空に
@@ -143,6 +145,12 @@ vi.mock("@/components/editor/PageEditor/useMarkdownExport", () => ({
   },
 }));
 
+vi.mock("@/components/editor/PageEditor/usePdfExport", () => ({
+  usePdfExport: () => ({
+    handleExportPdf: mockExportPdf,
+  }),
+}));
+
 // 読み取り専用経路の Markdown export ソースは `usePagePublicContent` 経由で
 // 取得した `content_text` に切り替わった (Codex P1, PR #893)。テストは初期値で
 // 「ロード完了 + 本文あり」を返し、必要なテストだけ `mockReturnValue` で上書きする。
@@ -323,6 +331,7 @@ describe("NotePageView", () => {
     mockApi.updatePageMetadata.mockReset();
     mockExportMarkdown.mockReset();
     mockCopyMarkdown.mockReset().mockResolvedValue(undefined);
+    mockExportPdf.mockReset().mockResolvedValue(undefined);
     mockRemoveFromNoteMutate.mockReset();
     mockUseMarkdownExport.mockReset();
     // 既定: read-only 経路の公開コンテンツは「ロード完了 + 本文あり」。
@@ -500,6 +509,7 @@ describe("NotePageView", () => {
 
       expect(screen.getByText("editor.pageHistory.menuButton")).toBeInTheDocument();
       expect(screen.getByText("editor.pageMenu.exportMarkdown")).toBeInTheDocument();
+      expect(screen.getByText("editor.pageMenu.exportPdf")).toBeInTheDocument();
       expect(screen.getByText("editor.pageMenu.copyMarkdown")).toBeInTheDocument();
       expect(screen.getByText("editor.pageMenu.deletePage")).toBeInTheDocument();
       // 旧「個人に取り込み」項目は削除されていることを明示的に検証する。
@@ -507,7 +517,7 @@ describe("NotePageView", () => {
       expect(screen.queryByText("notes.copyToPersonal")).not.toBeInTheDocument();
     });
 
-    it("read-only 時、削除以外の3項目だけを出す / shows history/export/copy but hides delete in read-only mode", () => {
+    it("read-only 時、削除以外の4項目だけを出す / shows history/export-md/export-pdf/copy but hides delete in read-only mode", () => {
       vi.mocked(useNote).mockReturnValue({
         note: { id: "note-1" },
         access: { canView: true, canEdit: false },
@@ -529,6 +539,7 @@ describe("NotePageView", () => {
 
       expect(screen.getByText("editor.pageHistory.menuButton")).toBeInTheDocument();
       expect(screen.getByText("editor.pageMenu.exportMarkdown")).toBeInTheDocument();
+      expect(screen.getByText("editor.pageMenu.exportPdf")).toBeInTheDocument();
       expect(screen.getByText("editor.pageMenu.copyMarkdown")).toBeInTheDocument();
       // read-only では削除は出さない（権限がないため）。
       // Delete is hidden in read-only mode (no permission).
@@ -577,6 +588,7 @@ describe("NotePageView", () => {
 
       expect(screen.queryByText("editor.pageHistory.menuButton")).not.toBeInTheDocument();
       expect(screen.getByText("editor.pageMenu.exportMarkdown")).toBeInTheDocument();
+      expect(screen.getByText("editor.pageMenu.exportPdf")).toBeInTheDocument();
       expect(screen.getByText("editor.pageMenu.copyMarkdown")).toBeInTheDocument();
       expect(screen.queryByText("editor.pageMenu.deletePage")).not.toBeInTheDocument();
     });
@@ -627,6 +639,15 @@ describe("NotePageView", () => {
       expect(mockExportMarkdown).toHaveBeenCalledTimes(1);
     });
 
+    it("`PDFで出力` で `handleExportPdf` を呼ぶ / invokes handleExportPdf on PDF export click", () => {
+      setupEditableRender();
+      renderNotePageView();
+
+      fireEvent.click(screen.getByText("editor.pageMenu.exportPdf"));
+
+      expect(mockExportPdf).toHaveBeenCalledTimes(1);
+    });
+
     it("`Markdownをコピー` で `handleCopyMarkdown` を呼ぶ / invokes handleCopyMarkdown on copy click", () => {
       setupEditableRender();
       renderNotePageView();
@@ -1039,8 +1060,10 @@ describe("NotePageView", () => {
     renderNotePageView();
 
     const exportItem = screen.getByText("editor.pageMenu.exportMarkdown").closest("button");
+    const pdfItem = screen.getByText("editor.pageMenu.exportPdf").closest("button");
     const copyItem = screen.getByText("editor.pageMenu.copyMarkdown").closest("button");
     expect(exportItem).toBeDisabled();
+    expect(pdfItem).toBeDisabled();
     expect(copyItem).toBeDisabled();
   });
 
diff --git a/src/pages/NotePageView.tsx b/src/pages/NotePageView.tsx
index c99bdaca..10b744fb 100644
--- a/src/pages/NotePageView.tsx
+++ b/src/pages/NotePageView.tsx
@@ -1,9 +1,11 @@
 import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useLocation, useNavigate, useParams } from "react-router-dom";
 import { useQueryClient } from "@tanstack/react-query";
-import { Copy, Download, History, Trash2 } from "lucide-react";
+import { Copy, Download, FileText, History, Trash2 } from "lucide-react";
 import { PageLoadingOrDenied } from "@/components/layout/PageLoadingOrDenied";
 import { PageEditorContent } from "@/components/note/PageEditorContent";
+import { PageActionHubFab } from "@/components/editor/PageActionHub/PageActionHubFab";
+import type { PageActionHubHandle } from "@/components/editor/PageActionHub/types";
 import { NotePagePublicView } from "@/components/note/NotePagePublicView";
 import {
   PageEditorHeader,
@@ -35,6 +37,7 @@ import { NoteWorkspaceProvider, useNoteWorkspaceOptional } from "@/contexts/Note
 import { useAIChatContext } from "@/contexts/AIChatContext";
 import { NoteWorkspaceToolbar } from "@/components/note/NoteWorkspaceToolbar";
 import { useMarkdownExport } from "@/components/editor/PageEditor/useMarkdownExport";
+import { usePdfExport } from "@/components/editor/PageEditor/usePdfExport";
 import { usePagePublicContent } from "@/hooks/usePagePublicContent";
 import { PageHistoryModal } from "@/components/editor/pageHistory/PageHistoryModal";
 import { convertMarkdownToTiptapContent } from "@/lib/markdownToTiptap";
@@ -85,11 +88,13 @@ function buildSharedMenuItems({
   t,
   onOpenHistory,
   onExportMarkdown,
+  onExportPdf,
   onCopyMarkdown,
 }: {
   t: (key: string) => string;
   onOpenHistory: () => void;
   onExportMarkdown: () => void;
+  onExportPdf: () => void;
   onCopyMarkdown: () => void;
 }): PageDetailToolbarAction[] {
   return [
@@ -105,6 +110,12 @@ function buildSharedMenuItems({
       icon: Download,
       onClick: onExportMarkdown,
     },
+    {
+      id: "export-pdf",
+      label: t("editor.pageMenu.exportPdf"),
+      icon: FileText,
+      onClick: onExportPdf,
+    },
     {
       id: "copy-markdown",
       label: t("editor.pageMenu.copyMarkdown"),
@@ -186,6 +197,8 @@ function NotePageEditorEditable({
   const noteWorkspace = useNoteWorkspaceOptional();
   const workspaceRoot = noteWorkspace?.workspaceRoot ?? null;
   const editorInsertRef = useRef<((content: unknown) => boolean) | null>(null);
+  const pageActionHubRef = useRef<PageActionHubHandle | null>(null);
+  const { isSignedIn: editorIsSignedIn } = useAuth();
   const queryClient = useQueryClient();
   const { toast } = useToast();
   const { t } = useTranslation();
@@ -199,6 +212,7 @@ function NotePageEditorEditable({
     editorContent,
     page.sourceUrl,
   );
+  const { handleExportPdf } = usePdfExport(title, editorContent, page.sourceUrl);
 
   useEffect(() => {
     setPageContext({
@@ -418,6 +432,7 @@ function NotePageEditorEditable({
         t,
         onOpenHistory: handleOpenHistory,
         onExportMarkdown: handleExportMarkdown,
+        onExportPdf: handleExportPdf,
         onCopyMarkdown: handleCopyMarkdown,
       }),
       {
@@ -434,6 +449,7 @@ function NotePageEditorEditable({
       t,
       handleOpenHistory,
       handleExportMarkdown,
+      handleExportPdf,
       handleCopyMarkdown,
       onRequestDelete,
       isDeletePending,
@@ -482,9 +498,23 @@ function NotePageEditorEditable({
           onTitleChange={isTitleEditable ? handleTitleChange : undefined}
           collaboration={isCollaborationEnabled ? collaboration : undefined}
           insertAtCursorRef={editorInsertRef}
+          pageActionHubRef={pageActionHubRef}
           pageNoteId={page.noteId ?? null}
           initialContent={initialContent}
           onInitialContentApplied={onInitialContentApplied}
+          wikiComposeHref={
+            // Issue #950: surface the Wiki Compose entry point on every
+            // note-native page. `WikiGeneratorButton` itself decides whether to
+            // render based on title presence.
+            page.noteId ? `/notes/${page.noteId}/${page.id}/compose` : undefined
+          }
+          bottomBarTrailingAction={
+            <PageActionHubFab
+              canEdit
+              isSignedIn={editorIsSignedIn}
+              onOpen={() => pageActionHubRef.current?.open()}
+            />
+          }
         />
       </ContentWithAIChat>
       {historyOpen && (
@@ -568,6 +598,11 @@ function NotePageReadOnly({
     exportSource,
     page.sourceUrl,
   );
+  const { handleExportPdf } = usePdfExport(
+    publicContent?.title ?? page.title,
+    exportSource,
+    page.sourceUrl,
+  );
 
   const handleOpenHistory = useCallback(() => {
     setHistoryOpen(true);
@@ -598,6 +633,15 @@ function NotePageReadOnly({
         // exporting an empty Markdown file (Codex P1, PR #893).
         disabled: !isExportSourceReady,
       },
+      {
+        id: "export-pdf",
+        label: t("editor.pageMenu.exportPdf"),
+        icon: FileText,
+        onClick: handleExportPdf,
+        // Markdown と同じ理由で公開コンテンツ未到着時は無効化する。
+        // Same gating as Markdown: block until public-content resolves.
+        disabled: !isExportSourceReady,
+      },
       {
         id: "copy-markdown",
         label: t("editor.pageMenu.copyMarkdown"),
@@ -612,6 +656,7 @@ function NotePageReadOnly({
     canViewHistory,
     handleOpenHistory,
     handleExportMarkdown,
+    handleExportPdf,
     handleCopyMarkdown,
     isExportSourceReady,
   ]);
diff --git a/src/pages/WikiComposePage.tsx b/src/pages/WikiComposePage.tsx
new file mode 100644
index 00000000..bbaa645f
--- /dev/null
+++ b/src/pages/WikiComposePage.tsx
@@ -0,0 +1,271 @@
+/**
+ * `WikiComposePage` — Wiki Compose split-screen UI (#950).
+ *
+ * `/notes/:noteId/:pageId/compose` (および `compose/:sessionId`) のルート要素。
+ * 左ペイン = `EditorPane` (タイトル + 進捗中の本文プレビュー)、右ペイン =
+ * `ComposePanel` (PhaseStepper + Dialogue + Research + Activity)。
+ * モバイルでは縦分割、デスクトップでは横分割で表示する。Compose 完了 / 中断
+ * 時はノートページに戻れる。
+ *
+ * Compose UI shell. The page reads the `useWikiComposeSession` hook for state
+ * and routes user submissions back through the hook's mutator methods.
+ */
+import React, { useEffect, useMemo, useState } from "react";
+import { useLocation, useNavigate, useParams } from "react-router-dom";
+import { ArrowLeft, X } from "lucide-react";
+import {
+  Alert,
+  AlertDescription,
+  AlertTitle,
+  Button,
+  ResizableHandle,
+  ResizablePanel,
+  ResizablePanelGroup,
+  useIsMobile,
+} from "@zedi/ui";
+import { useWikiComposeSession } from "@/hooks/useWikiComposeSession";
+import { COMPOSE_SEED_STATE_KEY, type ComposeNavigationSeed } from "@/lib/wikiCompose/navigation";
+import type { DraftedSection } from "@/lib/wikiCompose/types";
+import { EditorPane } from "@/components/wikiCompose/EditorPane";
+import { ComposePanel } from "@/components/wikiCompose/ComposePanel";
+import { ComposeBackendSelector } from "@/components/wikiCompose/ComposeBackendSelector";
+import type { ComposeExecutionBackend } from "@/lib/wikiCompose/backends";
+
+/** Map drafted section list to a quick lookup. */
+function indexById(items: DraftedSection[]): Record<string, DraftedSection> {
+  const out: Record<string, DraftedSection> = {};
+  for (const it of items) out[it.sectionId] = it;
+  return out;
+}
+
+/** Root page for `/notes/:noteId/:pageId/compose[/:sessionId]`. */
+const WikiComposePage: React.FC = () => {
+  const params = useParams<{ noteId: string; pageId: string; sessionId?: string }>();
+  const navigate = useNavigate();
+  const location = useLocation();
+  const isMobile = useIsMobile();
+
+  const noteId = params.noteId ?? "";
+  const pageId = params.pageId ?? "";
+  const sessionId = params.sessionId ?? null;
+  const [composeBackend, setComposeBackend] = useState<ComposeExecutionBackend>("zedi_managed");
+
+  // チャット seed は mount 時に 1 回だけ保持。`location.state` を消しても hook 側に残す。
+  // Capture chat seed once on mount; survives clearing `location.state` for the hook.
+  const [composeSeed] = useState((): ComposeNavigationSeed | undefined => {
+    const raw = (location.state as Record<string, unknown> | null)?.[COMPOSE_SEED_STATE_KEY];
+    if (!raw || typeof raw !== "object") return undefined;
+    const s = raw as ComposeNavigationSeed;
+    if (typeof s.outline !== "string" || typeof s.conversationText !== "string") return undefined;
+    return s;
+  });
+
+  const initialInput = useMemo(
+    () =>
+      composeSeed
+        ? {
+            chatSeed: {
+              outline: composeSeed.outline,
+              conversationText: composeSeed.conversationText,
+              userSchema: composeSeed.userSchema,
+              conversationId: composeSeed.conversationId,
+            },
+          }
+        : undefined,
+    [composeSeed],
+  );
+
+  const session = useWikiComposeSession({
+    pageId,
+    sessionId,
+    // Fresh compose: user picks backend then clicks Start (#951).
+    autoStart: Boolean(sessionId && pageId),
+    composeSeed,
+    initialInput,
+    backend: composeBackend,
+  });
+
+  const awaitingComposeStart =
+    !sessionId && session.status === "idle" && !session.session && !session.isStreaming;
+  const showBackendSelector = awaitingComposeStart;
+
+  // Clear history seed only after the session row left `pending` (first run claimed).
+  // `pending` のまま state を消すと失敗時リロードで chatSeed が届かなくなる (#950)。
+  useEffect(() => {
+    if (!composeSeed || !location.state) return;
+    if (session.status === "idle" || session.status === "pending") return;
+    navigate(location.pathname + location.search + location.hash, {
+      replace: true,
+      state: null,
+    });
+  }, [
+    composeSeed,
+    location.hash,
+    location.pathname,
+    location.search,
+    location.state,
+    navigate,
+    session.status,
+  ]);
+
+  // Persist the session id in the URL so refresh re-opens the same row.
+  useEffect(() => {
+    const id = session.session?.id;
+    if (!id || sessionId || !noteId || !pageId) return;
+    navigate(`/notes/${noteId}/${pageId}/compose/${id}`, { replace: true });
+  }, [session.session?.id, sessionId, noteId, pageId, navigate]);
+
+  const draftedSectionsById = useMemo(
+    () => indexById(Object.values(session.draftedSections)),
+    [session.draftedSections],
+  );
+
+  // The displayed outline switches sources as the user progresses through
+  // phases: proposal during structure → final approved outline once approved.
+  // (For the editor pane preview, both are acceptable since they share `id`.)
+  const outlineForPreview =
+    session.phase === "completed" || session.phase === "draft"
+      ? session.outlineProposal
+      : session.outlineProposal;
+
+  const handleBack = () => {
+    if (noteId && pageId) {
+      navigate(`/notes/${noteId}/${pageId}`);
+    } else {
+      navigate(-1);
+    }
+  };
+
+  const handleCancel = async () => {
+    await session.cancel().catch(() => undefined);
+    handleBack();
+  };
+
+  if (!pageId) {
+    return (
+      <div className="p-6">
+        <Alert variant="destructive">
+          <AlertTitle>Missing page id</AlertTitle>
+          <AlertDescription>
+            This URL is missing a page id. Use the Compose button on a wiki page to start.
+          </AlertDescription>
+        </Alert>
+      </div>
+    );
+  }
+
+  const header = (
+    <header
+      data-testid="compose-header"
+      className="border-border bg-background/95 flex items-center justify-between gap-2 border-b px-4 py-2 backdrop-blur"
+    >
+      <div className="flex min-w-0 items-center gap-2">
+        <Button
+          type="button"
+          size="sm"
+          variant="ghost"
+          onClick={handleBack}
+          data-testid="compose-back"
+        >
+          <ArrowLeft className="mr-1 h-4 w-4" />
+          Back
+        </Button>
+        <span className="truncate text-sm font-medium">
+          {session.pageSnapshot?.title || "Wiki Compose"}
+        </span>
+        <span className="text-muted-foreground text-[11px] tracking-wide uppercase">
+          {session.phase}
+        </span>
+      </div>
+      <div className="flex items-center gap-2">
+        {session.session ? (
+          <span className="text-muted-foreground hidden text-[11px] sm:inline">
+            session: {session.session.id.slice(0, 8)}…
+          </span>
+        ) : null}
+        <Button
+          type="button"
+          size="sm"
+          variant="outline"
+          onClick={handleCancel}
+          data-testid="compose-cancel"
+          disabled={session.status === "completed" || session.status === "cancelled"}
+        >
+          <X className="mr-1 h-4 w-4" />
+          {session.status === "completed" ? "Close" : "Cancel"}
+        </Button>
+      </div>
+    </header>
+  );
+
+  const left = (
+    <EditorPane
+      title={session.pageSnapshot?.title ?? ""}
+      outline={outlineForPreview}
+      draftedSections={draftedSectionsById}
+      sectionBuffers={session.sectionBuffers}
+      streamingSectionId={session.streamingSectionId}
+      completedMarkdown={session.completedMarkdown}
+    />
+  );
+
+  const right = (
+    <ComposePanel
+      phase={session.phase}
+      isStreaming={session.isStreaming}
+      briefQuestions={session.briefQuestions}
+      pageSnapshot={session.pageSnapshot}
+      latestBatch={session.latestBatch}
+      pendingSources={session.pendingSources}
+      approvedSources={session.approvedSources}
+      researchConflictSummary={session.researchConflictSummary}
+      outlineProposal={session.outlineProposal}
+      activity={session.activity}
+      onSubmitBrief={session.submitBrief}
+      onSubmitResearchApproval={session.submitResearchApproval}
+      onSubmitConflictAck={session.submitConflictAck}
+      onSubmitOutline={session.submitOutline}
+      onSubmitConflictAck={session.submitConflictAck}
+    />
+  );
+
+  return (
+    <div className="flex h-[100dvh] w-full flex-col">
+      {header}
+      {session.error ? (
+        <div className="bg-destructive/10 text-destructive px-4 py-2 text-xs">{session.error}</div>
+      ) : null}
+      {showBackendSelector ? (
+        <div className="border-border space-y-3 border-b px-4 py-3">
+          <ComposeBackendSelector
+            value={composeBackend}
+            onChange={setComposeBackend}
+            disabled={session.isStreaming}
+          />
+          <Button
+            type="button"
+            size="sm"
+            data-testid="compose-start"
+            onClick={() => void session.start()}
+            disabled={session.isStreaming}
+          >
+            Start compose
+          </Button>
+        </div>
+      ) : null}
+      <div className="min-h-0 flex-1">
+        <ResizablePanelGroup direction={isMobile ? "vertical" : "horizontal"} className="h-full">
+          <ResizablePanel defaultSize={55} minSize={30}>
+            {left}
+          </ResizablePanel>
+          <ResizableHandle withHandle />
+          <ResizablePanel defaultSize={45} minSize={25}>
+            {right}
+          </ResizablePanel>
+        </ResizablePanelGroup>
+      </div>
+    </div>
+  );
+};
+
+export default WikiComposePage;
diff --git a/terraform/cloudflare/README.ja.md b/terraform/cloudflare/README.ja.md
new file mode 100644
index 00000000..cd342906
--- /dev/null
+++ b/terraform/cloudflare/README.ja.md
@@ -0,0 +1,79 @@
+> **言語:** [English](README.md) | 日本語
+
+# Cloudflare Terraform（3 スタック構成）
+
+dev と prod の適用タイミングを分離するため、Cloudflare リソースを **shared / dev / prod** の 3 スタックで管理する。
+
+## ディレクトリと役割
+
+| スタック   | ディレクトリ | Terraform Cloud Workspace | 管理リソース                                                              |
+| ---------- | ------------ | ------------------------- | ------------------------------------------------------------------------- |
+| **shared** | `shared/`    | `cloudflare-shared`       | ゾーン参照・api/realtime の DNS（CNAME + Railway 検証 TXT）               |
+| **dev**    | `dev/`       | `cloudflare-dev`          | Pages `zedi-dev`、`dev.zedi-note.app` の DNS                              |
+| **prod**   | `prod/`      | `cloudflare-prod`         | Pages `zedi`・`zedi-admin`、`zedi-note.app`・`admin.zedi-note.app` の DNS |
+
+## 適用タイミング
+
+- **shared**: 変更は少ない想定。PR で plan、**手動で workflow_dispatch の Apply Shared** のみ実行。
+- **dev**: `develop` への push（かつ `terraform/cloudflare/dev/**` の変更）で自動 apply。PR で plan。
+- **prod**: `main` への push（かつ `terraform/cloudflare/prod/**` の変更）で自動 apply。PR で plan。`deploy-prod` の Deploy Admin は apply-cloudflare-prod の後に実行される。
+
+## Cloudflare トークンと Account ID の設定
+
+**3 つの Workspace（shared / dev / prod）すべてで、同じ `cloudflare_api_token` と `cloudflare_account_id` を使ってよい。** 同一 Cloudflare アカウント・同一ゾーンを扱うため、1 セットを共通で設定すれば十分。
+
+| 設定場所             | 用途                                                                                                     |
+| -------------------- | -------------------------------------------------------------------------------------------------------- |
+| **Terraform Cloud**  | 各 Workspace の Variables に Terraform 変数として同じ値を登録（ローカル・手動実行時）                    |
+| **terraform.tfvars** | 各スタックの `terraform.tfvars.example` をコピーして `terraform.tfvars` に同じ値を記入（ローカル実行時） |
+| **GitHub Secrets**   | `CLOUDFLARE_API_TOKEN` と `CLOUDFLARE_ACCOUNT_ID` を Environment に登録（CI 実行時）                     |
+
+Terraform Cloud の Workspace 変数・トークン作成は [HashiCorp Terraform Cloud ドキュメント](https://developer.hashicorp.com/terraform/cloud-docs) を参照（リポジトリ内の長文ガイドは持たない）。
+
+## Railway 検証 TXT トークン（shared 専用）
+
+`shared` スタックは Railway カスタムドメイン用の検証 TXT トークン（`api_railway_verify_txt` / `realtime_railway_verify_txt`）を必須変数として要求する。
+これらは機密値であり、リポジトリには平文で含めない。次のいずれかで渡すこと（**推奨は Terraform Cloud Workspace 変数**）。
+
+| 渡し方                                 | 設定例                                                             |
+| -------------------------------------- | ------------------------------------------------------------------ |
+| Terraform Cloud Workspace 変数（推奨） | `cloudflare-shared` Workspace の Variables に **Sensitive** で登録 |
+| 環境変数 `TF_VAR_*`                    | `export TF_VAR_api_railway_verify_txt="railway-verify=..."`        |
+| `terraform.tfvars`（gitignored）       | `terraform.tfvars.example` をコピーして記入                        |
+
+値は Railway ダッシュボードの該当ドメイン設定画面（`api.zedi-note.app` / `realtime.zedi-note.app`）から取得する。
+**過去にリポジトリへ平文 commit されていたトークンはローテーションすること。**
+
+## ローカルでの実行
+
+各スタックは独立している。Terraform Cloud に **3 つの Workspace** を作成し、上記のとおり変数を設定する（共通のトークン・Account ID でよい）。
+
+```bash
+# 例: shared の plan（変数は Terraform Cloud または terraform.tfvars で設定済みとする）
+cd terraform/cloudflare/shared
+terraform init
+# 未設定なら環境変数で渡す:
+# export TF_VAR_cloudflare_api_token="..."
+# export TF_VAR_cloudflare_account_id="..."
+# shared スタックでは追加で Railway 検証 TXT も必要:
+# export TF_VAR_api_railway_verify_txt="railway-verify=..."
+# export TF_VAR_realtime_railway_verify_txt="railway-verify=..."
+terraform plan
+```
+
+変数は各ディレクトリの `terraform.tfvars.example` をコピーして `terraform.tfvars` に記入するか、Terraform Cloud の各 Workspace 変数で**同じ値**を設定する。
+
+## CI での変数
+
+GitHub Actions では次の Secrets を Environment（development / production）に設定する。
+
+- `TF_API_TOKEN` — Terraform Cloud 認証（backend 用）
+- `CLOUDFLARE_API_TOKEN` — Provider 用（`TF_VAR_cloudflare_api_token` として渡す）
+- `CLOUDFLARE_ACCOUNT_ID` — Provider 用（`TF_VAR_cloudflare_account_id` として渡す）
+
+各 workflow で上記を `TF_VAR_*` に渡しているため、plan/apply はそのまま動作する。
+
+## 参考（外部）
+
+- [Terraform Cloud](https://developer.hashicorp.com/terraform/cloud-docs) — Workspace・変数・実行
+- [Cloudflare Provider](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs) — DNS・ゾーン
diff --git a/terraform/cloudflare/README.md b/terraform/cloudflare/README.md
index 45e89260..554ce367 100644
--- a/terraform/cloudflare/README.md
+++ b/terraform/cloudflare/README.md
@@ -1,77 +1,81 @@
-# Cloudflare Terraform（3 スタック構成）
+> **Language:** English | [日本語](README.ja.md)
 
-dev と prod の適用タイミングを分離するため、Cloudflare リソースを **shared / dev / prod** の 3 スタックで管理する。
+# Cloudflare Terraform (3-stack layout)
 
-## ディレクトリと役割
+Cloudflare resources are split into **shared / dev / prod** stacks so dev and prod apply at different times.
 
-| スタック   | ディレクトリ | Terraform Cloud Workspace | 管理リソース                                                              |
-| ---------- | ------------ | ------------------------- | ------------------------------------------------------------------------- |
-| **shared** | `shared/`    | `cloudflare-shared`       | ゾーン参照・api/realtime の DNS（CNAME + Railway 検証 TXT）               |
-| **dev**    | `dev/`       | `cloudflare-dev`          | Pages `zedi-dev`、`dev.zedi-note.app` の DNS                              |
-| **prod**   | `prod/`      | `cloudflare-prod`         | Pages `zedi`・`zedi-admin`、`zedi-note.app`・`admin.zedi-note.app` の DNS |
+## Directories and roles
 
-## 適用タイミング
+| Stack      | Directory | Terraform Cloud Workspace | Resources managed                                                                |
+| ---------- | --------- | ------------------------- | -------------------------------------------------------------------------------- |
+| **shared** | `shared/` | `cloudflare-shared`       | Zone reference; api/realtime DNS (CNAME + Railway verification TXT)              |
+| **dev**    | `dev/`    | `cloudflare-dev`          | Pages `zedi-dev`; DNS for `dev.zedi-note.app`                                    |
+| **prod**   | `prod/`   | `cloudflare-prod`         | Pages `zedi` and `zedi-admin`; DNS for `zedi-note.app` and `admin.zedi-note.app` |
 
-- **shared**: 変更は少ない想定。PR で plan、**手動で workflow_dispatch の Apply Shared** のみ実行。
-- **dev**: `develop` への push（かつ `terraform/cloudflare/dev/**` の変更）で自動 apply。PR で plan。
-- **prod**: `main` への push（かつ `terraform/cloudflare/prod/**` の変更）で自動 apply。PR で plan。`deploy-prod` の Deploy Admin は apply-cloudflare-prod の後に実行される。
+## Apply timing
 
-## Cloudflare トークンと Account ID の設定
+- **shared**: Infrequent changes. Plan on PR; run **Apply Shared** via manual `workflow_dispatch` only.
+- **dev**: Auto-apply on push to `develop` when `terraform/cloudflare/dev/**` changes. Plan on PR.
+- **prod**: Auto-apply on push to `main` when `terraform/cloudflare/prod/**` changes. Plan on PR. `deploy-prod` Deploy Admin runs after `apply-cloudflare-prod`.
 
-**3 つの Workspace（shared / dev / prod）すべてで、同じ `cloudflare_api_token` と `cloudflare_account_id` を使ってよい。** 同一 Cloudflare アカウント・同一ゾーンを扱うため、1 セットを共通で設定すれば十分。
+## Cloudflare token and Account ID
 
-| 設定場所             | 用途                                                                                                     |
-| -------------------- | -------------------------------------------------------------------------------------------------------- |
-| **Terraform Cloud**  | 各 Workspace の Variables に Terraform 変数として同じ値を登録（ローカル・手動実行時）                    |
-| **terraform.tfvars** | 各スタックの `terraform.tfvars.example` をコピーして `terraform.tfvars` に同じ値を記入（ローカル実行時） |
-| **GitHub Secrets**   | `CLOUDFLARE_API_TOKEN` と `CLOUDFLARE_ACCOUNT_ID` を Environment に登録（CI 実行時）                     |
+**All three workspaces (shared / dev / prod) may use the same `cloudflare_api_token` and `cloudflare_account_id`** — one Cloudflare account and zone.
 
-Terraform Cloud の Workspace 変数・トークン作成は [HashiCorp Terraform Cloud ドキュメント](https://developer.hashicorp.com/terraform/cloud-docs) を参照（リポジトリ内の長文ガイドは持たない）。
+| Location             | Purpose                                                                                 |
+| -------------------- | --------------------------------------------------------------------------------------- |
+| **Terraform Cloud**  | Register the same values as Terraform variables in each workspace (local / manual runs) |
+| **terraform.tfvars** | Copy each stack's `terraform.tfvars.example` to `terraform.tfvars` with the same values |
+| **GitHub Secrets**   | `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` in GitHub Environments (CI runs)     |
 
-## Railway 検証 TXT トークン（shared 専用）
+See [HashiCorp Terraform Cloud docs](https://developer.hashicorp.com/terraform/cloud-docs) for workspace variables and token creation (no long in-repo guide).
 
-`shared` スタックは Railway カスタムドメイン用の検証 TXT トークン（`api_railway_verify_txt` / `realtime_railway_verify_txt`）を必須変数として要求する。
-これらは機密値であり、リポジトリには平文で含めない。次のいずれかで渡すこと（**推奨は Terraform Cloud Workspace 変数**）。
+## Railway verification TXT tokens (shared only)
 
-| 渡し方                                 | 設定例                                                             |
-| -------------------------------------- | ------------------------------------------------------------------ |
-| Terraform Cloud Workspace 変数（推奨） | `cloudflare-shared` Workspace の Variables に **Sensitive** で登録 |
-| 環境変数 `TF_VAR_*`                    | `export TF_VAR_api_railway_verify_txt="railway-verify=..."`        |
-| `terraform.tfvars`（gitignored）       | `terraform.tfvars.example` をコピーして記入                        |
+The `shared` stack requires Railway custom-domain verification TXT tokens (`api_railway_verify_txt` / `realtime_railway_verify_txt`).
 
-値は Railway ダッシュボードの該当ドメイン設定画面（`api.zedi-note.app` / `realtime.zedi-note.app`）から取得する。
-**過去にリポジトリへ平文 commit されていたトークンはローテーションすること。**
+These are secrets — do not commit plaintext. Pass via one of:
 
-## ローカルでの実行
+| Method                                       | Example                                                     |
+| -------------------------------------------- | ----------------------------------------------------------- |
+| Terraform Cloud workspace vars (recommended) | Register as **Sensitive** in `cloudflare-shared` workspace  |
+| `TF_VAR_*` env vars                          | `export TF_VAR_api_railway_verify_txt="railway-verify=..."` |
+| `terraform.tfvars` (gitignored)              | Copy from `terraform.tfvars.example` and fill in            |
 
-各スタックは独立している。Terraform Cloud に **3 つの Workspace** を作成し、上記のとおり変数を設定する（共通のトークン・Account ID でよい）。
+Obtain values from the Railway dashboard for `api.zedi-note.app` / `realtime.zedi-note.app`.
+
+**Rotate any tokens previously committed in plaintext.**
+
+## Local execution
+
+Each stack is independent. Create **three Terraform Cloud workspaces** and set variables (same token and Account ID is fine).
 
 ```bash
-# 例: shared の plan（変数は Terraform Cloud または terraform.tfvars で設定済みとする）
+# Example: shared plan (vars set in Terraform Cloud or terraform.tfvars)
 cd terraform/cloudflare/shared
 terraform init
-# 未設定なら環境変数で渡す:
+# If unset, pass via env:
 # export TF_VAR_cloudflare_api_token="..."
 # export TF_VAR_cloudflare_account_id="..."
-# shared スタックでは追加で Railway 検証 TXT も必要:
+# shared stack also needs Railway verification TXT:
 # export TF_VAR_api_railway_verify_txt="railway-verify=..."
 # export TF_VAR_realtime_railway_verify_txt="railway-verify=..."
 terraform plan
 ```
 
-変数は各ディレクトリの `terraform.tfvars.example` をコピーして `terraform.tfvars` に記入するか、Terraform Cloud の各 Workspace 変数で**同じ値**を設定する。
+Copy each directory's `terraform.tfvars.example` to `terraform.tfvars` or set the **same values** in each Terraform Cloud workspace.
 
-## CI での変数
+## CI variables
 
-GitHub Actions では次の Secrets を Environment（development / production）に設定する。
+GitHub Actions uses these Secrets in Environments (development / production):
 
-- `TF_API_TOKEN` — Terraform Cloud 認証（backend 用）
-- `CLOUDFLARE_API_TOKEN` — Provider 用（`TF_VAR_cloudflare_api_token` として渡す）
-- `CLOUDFLARE_ACCOUNT_ID` — Provider 用（`TF_VAR_cloudflare_account_id` として渡す）
+- `TF_API_TOKEN` — Terraform Cloud auth (backend)
+- `CLOUDFLARE_API_TOKEN` — Provider (`TF_VAR_cloudflare_api_token`)
+- `CLOUDFLARE_ACCOUNT_ID` — Provider (`TF_VAR_cloudflare_account_id`)
 
-各 workflow で上記を `TF_VAR_*` に渡しているため、plan/apply はそのまま動作する。
+Workflows pass these as `TF_VAR_*` so plan/apply works as-is.
 
-## 参考（外部）
+## External references
 
-- [Terraform Cloud](https://developer.hashicorp.com/terraform/cloud-docs) — Workspace・変数・実行
-- [Cloudflare Provider](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs) — DNS・ゾーン
+- [Terraform Cloud](https://developer.hashicorp.com/terraform/cloud-docs) — Workspaces, variables, runs
+- [Cloudflare Provider](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs) — DNS, zones