docs: finalize release docs

19 files changed, 279 insertions, 31 deletions

diff --git a/website/src/content/docs/agents.mdx b/website/src/content/docs/agents.mdx
index 5e50dfdd..f752a297 100644
--- a/website/src/content/docs/agents.mdx
+++ b/website/src/content/docs/agents.mdx
@@ -21,6 +21,7 @@ Automatic detection works out of the box for common coding agents. The important
 | Droid | screen manifest | session |
 | OpenCode | lifecycle plugin when installed; otherwise screen manifest | state and session |
 | Kilo Code CLI | lifecycle plugin when installed; otherwise screen manifest | state and session |
+| MastraCode | lifecycle hooks when installed | state and session |
 | Claude Code | screen manifest | session |
 | Codex | screen manifest | session |
 | Cursor Agent CLI | screen manifest | session |
diff --git a/website/src/content/docs/cli-reference.mdx b/website/src/content/docs/cli-reference.mdx
index d841e564..81fe4dce 100644
--- a/website/src/content/docs/cli-reference.mdx
+++ b/website/src/content/docs/cli-reference.mdx
@@ -19,6 +19,7 @@ herdr --no-session            # single-process escape hatch
 herdr --default-config        # print default config
 herdr update                  # download and install from the configured channel
 herdr update --handoff        # opt into live handoff for supported running servers
+herdr completion zsh          # generate a zsh completion script
 herdr channel show            # print stable or preview
 herdr channel set preview     # opt into preview builds
 herdr channel set stable      # return Linux/macOS direct installs to stable
@@ -33,6 +34,52 @@ herdr status server
 herdr status client
 ```
 
+API schema commands:
+
+```bash
+herdr api schema
+herdr api schema --json
+herdr api schema --output herdr-api.schema.json
+```
+
+`herdr api schema` prints a short summary of the socket protocol schema bundled
+with the installed binary. Use `--json` for the full JSON Schema document, or
+`--output PATH` to write that document to a file.
+
+## Shell completions
+
+```bash
+herdr completion zsh
+herdr completions zsh
+herdr completion bash
+herdr completion fish
+herdr completion powershell
+herdr completion elvish
+```
+
+`completion` prints the script to stdout. `completions` is an alias. For a
+temporary zsh session, load the script directly:
+
+```bash
+source <(herdr completion zsh)
+```
+
+For a persistent zsh setup, write the generated `_herdr` function somewhere on
+your `fpath` before `compinit` runs:
+
+```bash
+mkdir -p ~/.zfunc
+herdr completion zsh > ~/.zfunc/_herdr
+```
+
+Then make sure your `.zshrc` contains:
+
+```zsh
+fpath=(~/.zfunc $fpath)
+autoload -Uz compinit
+compinit
+```
+
 ## Server
 
 ```bash
@@ -129,6 +176,11 @@ herdr pane move <pane_id> --new-workspace [--label TEXT] [--tab-label TEXT] [--f
 herdr pane close <pane_id>
 ```
 
+For pane commands that accept `--current`, Herdr uses the calling pane's
+`HERDR_PANE_ID` when the command runs inside a Herdr pane. For `pane split`,
+an explicit pane id or `--pane ID` splits that pane, `--current` splits the
+calling pane, and an omitted target keeps using the UI-focused pane.
+
 Read output:
 
 ```bash
@@ -172,6 +224,8 @@ herdr pane report-agent <pane_id> \
 
 Those commands include `foreground_cwd` when Herdr can resolve the cwd of the foreground process controlling the pane. The existing `cwd` field remains the pane/workspace cwd used for labels and follow-cwd behavior.
 
+`pane get` and `pane list` include `scroll` when terminal scroll metrics are available. `scroll.offset_from_bottom == 0` means the pane is at the bottom of its scrollback.
+
 Report display-only pane metadata without taking over semantic state:
 
 ```bash
@@ -222,11 +276,24 @@ Use `pane send-text`, `pane send-keys`, `pane run`, and `terminal attach` for or
 
 ```bash
 herdr terminal attach <terminal_id> [--takeover]
+herdr terminal session control <target> [--takeover] [--cols N] [--rows N]
+herdr terminal session observe <target> [--cols N] [--rows N]
 herdr terminal title set <title>
 herdr terminal title clear
 ```
 
 Detach from direct attach with `ctrl+b q`. Send literal `ctrl+b` with `ctrl+b ctrl+b`.
+`terminal session control` opens a writable live terminal stream for a pane,
+terminal, or agent target. It prints the same newline-delimited
+`terminal.frame` and `terminal.closed` records as observe mode. It reads
+newline-delimited JSON commands on stdin: `terminal.input`, `terminal.resize`,
+`terminal.scroll`, and `terminal.release`. One controller can own a terminal at
+a time; use `--takeover` to replace it.
+`terminal session observe` opens a read-only live terminal stream for a pane,
+terminal, or agent target. It prints newline-delimited JSON `terminal.frame`
+records with base64-encoded ANSI bytes, then a `terminal.closed` record when
+the server closes the stream. Multiple observers can watch the same terminal
+without taking input, resize, scroll, or takeover authority.
 `terminal title clear` restores Herdr's default outer terminal window title.
 
 ## Waits
@@ -261,6 +328,7 @@ herdr integration install kilo
 herdr integration install hermes
 herdr integration install qodercli
 herdr integration install cursor
+herdr integration install mastracode
 herdr integration uninstall pi
 herdr integration uninstall omp
 herdr integration uninstall claude
@@ -274,6 +342,7 @@ herdr integration uninstall kilo
 herdr integration uninstall hermes
 herdr integration uninstall qodercli
 herdr integration uninstall cursor
+herdr integration uninstall mastracode
 herdr integration status [--outdated-only]
 ```
 
diff --git a/website/src/content/docs/configuration.mdx b/website/src/content/docs/configuration.mdx
index 20eadb96..5ce4c037 100644
--- a/website/src/content/docs/configuration.mdx
+++ b/website/src/content/docs/configuration.mdx
@@ -71,7 +71,7 @@ Set the executable Herdr uses for newly created interactive panes:
 default_shell = "nu"
 ```
 
-When unset or empty, Herdr uses `$SHELL`, then `/bin/sh`. This is an executable name or path, not a shell command line. Existing panes keep their current shell until they are recreated. Command panes still run through `/bin/sh -c`; detached custom command keybindings use Herdr's existing `/bin/sh -lc` path.
+When unset or empty, Herdr uses `$SHELL`, then `/bin/sh` on Unix and PowerShell on Windows. This is an executable name or path, not a shell command line. Existing panes keep their current shell until they are recreated. Custom command keybinding strings run through `/bin/sh -c` for pane commands and `/bin/sh -lc` for detached commands on Unix; on Windows they run through `cmd.exe /d /c`.
 
 Set how Herdr starts newly created interactive pane shells:
 
@@ -110,14 +110,14 @@ Deleting a worktree checkout is explicit. Use `Delete worktree checkout...` on a
 
 ## Remote attach
 
-Remote attach manages its SSH bridge with a temporary keepalive fallback by default.
+Remote attach manages its SSH connection with a temporary keepalive and connection-reuse fallback by default.
 
 ```toml
 [remote]
 manage_ssh_config = true
 ```
 
-When enabled, `herdr --remote` writes a private temporary SSH config that includes your `~/.ssh/config` and `/etc/ssh/ssh_config` first, then adds fallback `ServerAliveInterval` and `ServerAliveCountMax` values. Your own SSH keepalive settings win. Set `manage_ssh_config = false` to run the bridge through plain `ssh` without Herdr's generated config.
+When enabled, `herdr --remote` writes a private temporary SSH config that includes your `~/.ssh/config` and `/etc/ssh/ssh_config` first, then adds fallback `ServerAliveInterval` and `ServerAliveCountMax` values. Your own keepalive settings win. Herdr also uses a private per-attach OpenSSH control socket to reuse the first authenticated connection. Set `manage_ssh_config = false` to run remote attach through plain `ssh` without Herdr's generated config or control socket.
 
 ## Keybindings
 
@@ -198,7 +198,7 @@ next_tab = ["prefix+n", "ctrl+alt+]"]
 
 `last_pane` switches back to the last focused pane across workspaces and tabs. It is unset by default because the tmux-style pane binding `prefix+l` is already used for pane-right focus.
 
-`remote_image_paste` is only active in `herdr --remote`. It is the local-client shortcut that sends a local clipboard image to the remote pane. Set it to an empty string to disable the raw-key shortcut; terminal paste-image signals still work when the outer terminal sends them.
+`remote_image_paste` is only active in `herdr --remote`. It is the local-client shortcut that sends a local clipboard image to the remote pane. Set it to an empty string to disable the raw-key shortcut; remote terminal paste-image signals still work when the outer terminal sends them.
 
 Key strings accept plain keys, modifier combinations such as `ctrl+a`, `shift+n`, `alt+1`, `cmd+k`, and special keys such as `enter`, `tab`, `esc`, `left`, `right`, `up`, and `down`. Named punctuation such as `minus`, `comma`, `ampersand`, `plus`, and `backtick` is also accepted. Plain direct printable keys such as `n` are unsafe because they intercept typing; use `prefix+n` unless you intentionally want a direct binding. The `navigate_workspace_*` and `navigate_pane_*` fields are navigate-mode-only and may use plain keys such as `j` or `k`; they must not use `prefix+`, `esc`, `enter`, `tab`, `shift+tab`, `left`, `right`, or unmodified `1` through `9`. Left and right arrows are permanent aliases for pane-left and pane-right navigation. These navigate-mode shortcuts are independent from general action bindings such as `focus_pane_down = "prefix+j"`; when both use the same key, the navigate-mode shortcut wins while navigate mode is open. Alt, Cmd/Super, and punctuation with modifiers depend on your terminal and tmux settings.
 
@@ -248,6 +248,8 @@ An optional `description` can be provided. When specified, this description is d
 
 Custom commands receive `HERDR_SOCKET_PATH`, `HERDR_BIN_PATH`, `HERDR_ACTIVE_WORKSPACE_ID`, `HERDR_ACTIVE_TAB_ID`, `HERDR_ACTIVE_PANE_ID`, and `HERDR_ACTIVE_PANE_CWD` when those values are available. Shell commands run from the focused pane's working directory when Herdr can detect it.
 
+On Windows, custom command strings use `cmd.exe /d /c`, so environment variables use `%HERDR_BIN_PATH%` syntax. To run PowerShell syntax, invoke it explicitly, for example `powershell.exe -NoProfile -Command "..."`.
+
 ## Theme
 
 Choose a built-in theme:
@@ -300,8 +302,10 @@ Common options:
 sidebar_width = 32
 sidebar_min_width = 18
 sidebar_max_width = 36
+sidebar_collapsed_mode = "compact"
 mobile_width_threshold = 64
 mouse_capture = true
+host_cursor = "auto"
 right_click_passthrough_modifier = ""
 redraw_on_focus_gained = true
 mouse_scroll_lines = 3
@@ -310,12 +314,15 @@ prompt_new_tab_name = true
 pane_borders = true
 pane_gaps = true
 show_agent_labels_on_pane_borders = false
+hide_tab_bar_when_single_tab = false
 agent_panel_sort = "spaces"
 accent = "cyan"
 ```
 
 `sidebar_min_width` and `sidebar_max_width` control the expanded sidebar's resize bounds in columns. The defaults are 18 and 36.
 
+`sidebar_collapsed_mode` controls what remains visible after toggling the sidebar closed. The default, `compact`, keeps the narrow status rail. Set it to `hidden` to make the collapsed sidebar zero-width; reopen it with `keys.toggle_sidebar`.
+
 `mobile_width_threshold` controls the terminal width at or below which Herdr uses the mobile single-column layout. The default is 64 columns; increase it for foldables, tablets, or wide phone terminals.
 
 The agent panel shows all agents across all spaces. `agent_panel_sort` can be `spaces` or `priority`; `workspaces` is accepted as an alias for `spaces`. `spaces` is the default and keeps agents grouped by space order. `priority` sorts by attention priority: blocked, done, working, idle, then unknown. Within the same status, agents that most recently changed state appear first.
@@ -324,6 +331,8 @@ The agent panel shows all agents across all spaces. `agent_panel_sort` can be `s
 
 Set `mouse_capture = false` if you want your terminal to handle normal clicks, such as command-clicking URLs. With mouse capture enabled, Ctrl-click opens pane links when your terminal sends that modified click to Herdr. This includes macOS; Cmd-click is not reported separately from plain click while Herdr captures mouse input. Use Shift-Ctrl-click on Linux or Shift-Cmd-click on macOS for the terminal-native bypass path.
 
+`host_cursor` controls whether Herdr uses the outer terminal's native cursor or draws its own cursor as terminal cell content. The default, `auto`, draws Herdr's cursor on Windows to avoid ConPTY cursor flicker during active redraws, and uses the native cursor elsewhere. Set it to `native` to always use the outer terminal cursor, or `drawn` to always use Herdr's drawn cursor.
+
 Set `right_click_passthrough_modifier = "ctrl"` if you want Ctrl-right-click, hold, and drag gestures inside mouse-reporting pane apps to reach the app instead of opening Herdr's pane menu. The default is empty, which disables this passthrough. Supported modifiers are `ctrl`, `alt`, `cmd`, `super`, `meta`, and `hyper`; `shift` is rejected because many terminals reserve Shift+mouse for their own mouse bypass.
 
 Set `redraw_on_focus_gained = false` to avoid the visible full-screen refresh when switching back to Herdr. The default is `true` because a full redraw recovers from rare stale or dirty host terminal surfaces.
@@ -334,6 +343,8 @@ Set `pane_borders = false` to remove split pane borders. Set `pane_gaps = false`
 
 Set `show_agent_labels_on_pane_borders = true` if you want detected agent labels in split pane borders when no manual pane label is set.
 
+Set `hide_tab_bar_when_single_tab = true` to hide the tab row when the active workspace has exactly one tab. New tabs can still be created with the configured keybinding. When a second tab appears, Herdr restores the tab row and resizes panes to make room for it.
+
 ## Notifications
 
 Herdr can show popup notifications when agents finish or need input.
@@ -458,7 +469,7 @@ Herdr can restart supported agent panes in their native conversation sessions af
 resume_agents_on_restore = true
 ```
 
-This is enabled by default. Herdr only resumes panes that reported a native session reference through an official Herdr integration. Supported resume targets are Claude Code, Codex, Cursor Agent CLI, GitHub Copilot CLI, Droid, Kimi Code CLI, Qoder CLI, Pi, Hermes Agent, OpenCode, and Kilo Code CLI. Unsupported, missing, invalid, duplicated, or stale session references restore as a normal shell in the saved pane directory.
+This is enabled by default. Herdr only resumes panes that reported a native session reference through an official Herdr integration. Supported resume targets are Claude Code, Codex, Cursor Agent CLI, GitHub Copilot CLI, Droid, Kimi Code CLI, Qoder CLI, Pi, Hermes Agent, OpenCode, Kilo Code CLI, and MastraCode. Unsupported, missing, invalid, duplicated, or stale session references restore as a normal shell in the saved pane directory.
 
 Session references are stored in the local Herdr session snapshot. They are not shown in normal pane, agent, status, or event output.
 
@@ -491,14 +502,14 @@ The trade-off when enabled: an extra hardware cursor is visible in the outer ter
 
 On macOS, prefix-mode commands can be hard to use while a non-ASCII input source is active because prefix commands are still interpreted through the host input source.
 
-Set `switch_ascii_input_source_in_prefix = true` to switch the host input source to the system ASCII-capable input source while prefix mode is active:
+Set `switch_ascii_input_source_in_prefix = true` to switch the host input source to the system ASCII-capable input source while prefix commands and prefix-launched navigation are active:
 
 ```toml
 [experimental]
 switch_ascii_input_source_in_prefix = false
 ```
 
-When enabled, Herdr switches input sources only after prefix mode is entered, then restores the previous input source when prefix mode exits. The setting is macOS-only and is a no-op on other platforms or when the system input-source switch fails.
+When enabled, Herdr switches input sources after prefix mode is entered, keeps the ASCII source across prefix-launched modes such as navigation, menus, resize, and copy mode, and restores the previous input source when returning to the terminal or entering a text field such as a rename dialog. The setting is macOS-only and is a no-op on other platforms or when the system input-source switch fails.
 
 You can also toggle it from Settings > Experiments > switch to ascii input source in prefix (macOS).
 
diff --git a/website/src/content/docs/integrations.mdx b/website/src/content/docs/integrations.mdx
index 605a55d1..5f37afbc 100644
--- a/website/src/content/docs/integrations.mdx
+++ b/website/src/content/docs/integrations.mdx
@@ -1,6 +1,6 @@
 ---
 title: Integrations
-description: Install Herdr integrations for Pi, OMP, Claude Code, Codex, GitHub Copilot CLI, Devin CLI, Droid, Kimi Code CLI, OpenCode, Kilo Code CLI, Hermes Agent, Qoder CLI, and Cursor Agent CLI.
+description: Install Herdr integrations for Pi, OMP, Claude Code, Codex, GitHub Copilot CLI, Devin CLI, Droid, Kimi Code CLI, OpenCode, Kilo Code CLI, Hermes Agent, Qoder CLI, Cursor Agent CLI, and MastraCode.
 ---
 
 Herdr detects supported agents automatically. Official integrations can add native session identity for restore, lifecycle state reports, or both.
@@ -25,6 +25,7 @@ herdr integration install kilo
 herdr integration install hermes
 herdr integration install qodercli
 herdr integration install cursor
+herdr integration install mastracode
 ```
 
 ## Uninstall integrations
@@ -43,6 +44,7 @@ herdr integration uninstall kilo
 herdr integration uninstall hermes
 herdr integration uninstall qodercli
 herdr integration uninstall cursor
+herdr integration uninstall mastracode
 ```
 
 ## How Herdr uses integrations
@@ -51,14 +53,14 @@ Herdr uses integrations in two different ways:
 
 | Integration type | Agents | Effect |
 | --- | --- | --- |
-| Lifecycle authority | Pi, OMP, Kimi Code CLI, OpenCode, Kilo Code CLI, Hermes Agent | When installed and actively reporting for the pane, hook or plugin events author `idle`, `working`, and `blocked`. Herdr does not also use screen manifest fallback for that same lifecycle authority. |
+| Lifecycle authority | Pi, OMP, Kimi Code CLI, OpenCode, Kilo Code CLI, Hermes Agent, MastraCode | When installed and actively reporting for the pane, hook or plugin events author `idle`, `working`, and `blocked`. Herdr does not also use screen manifest fallback for that same lifecycle authority. |
 | Session identity | Claude Code, Codex, GitHub Copilot CLI, Devin CLI, Droid, Qoder CLI, Cursor Agent CLI | The integration reports native session references for restore. State still comes from Herdr's screen manifest detection. |
 
 Custom socket integrations can also report state when they define state that is not visible in the native terminal UI.
 
-Some integrations report native agent session references. Herdr uses official session references to resume Claude Code, Codex, Devin CLI, Droid, Kimi Code CLI, Qoder CLI, Cursor Agent CLI, GitHub Copilot CLI, Pi, OMP, Hermes Agent, OpenCode, and Kilo Code CLI panes after a Herdr server restart unless `[session] resume_agents_on_restore = false` disables it.
+Some integrations report native agent session references. Herdr uses official session references to resume Claude Code, Codex, Devin CLI, Droid, Kimi Code CLI, Qoder CLI, Cursor Agent CLI, GitHub Copilot CLI, Pi, OMP, Hermes Agent, OpenCode, Kilo Code CLI, and MastraCode panes after a Herdr server restart unless `[session] resume_agents_on_restore = false` disables it.
 
-Native session restore requires current Herdr integrations: Pi integration version `2`, OMP version `3`, Claude Code version `6`, Codex version `5`, GitHub Copilot CLI version `2`, Devin CLI version `2`, Droid version `2`, Kimi Code CLI version `3`, Qoder CLI version `2`, Cursor Agent CLI version `1`, OpenCode version `5`, Kilo Code CLI version `1`, or Hermes Agent version `2`. Check installed versions with `herdr integration status`.
+Native session restore requires current Herdr integrations: Pi integration version `2`, OMP version `3`, Claude Code version `6`, Codex version `5`, GitHub Copilot CLI version `2`, Devin CLI version `2`, Droid version `2`, Kimi Code CLI version `3`, Qoder CLI version `2`, Cursor Agent CLI version `1`, OpenCode version `5`, Kilo Code CLI version `1`, Hermes Agent version `2`, or MastraCode version `1`. Check installed versions with `herdr integration status`.
 
 ## Pi
 
@@ -240,6 +242,20 @@ Herdr uses `~/.cursor` by default, or `CURSOR_CONFIG_DIR` when set. The Cursor c
 
 After Cursor emits a session start event, Herdr can use the reported session id to resume the pane with `cursor-agent --resume <id>`. The `cursor-agent` command must be on `PATH` when Herdr restores the pane; Herdr does not launch the generic `agent` command.
 
+## MastraCode
+
+Install the MastraCode hook:
+
+```bash
+herdr integration install mastracode
+```
+
+The hook reports MastraCode lifecycle state and thread identity to Herdr for authoritative `idle`, `working`, and `blocked` status and native restore. MastraCode has no screen manifest fallback; state comes from the hook while MastraCode runs inside a Herdr pane.
+
+Herdr uses `~/.mastracode`. Install writes `hooks/herdr-agent-state.sh` and adds Herdr command entries to `hooks.json`, creating the directory when missing. Uninstall removes the matching hook entries and deletes the hook script.
+
+Herdr resumes stored MastraCode threads with `mastracode --thread <id>`.
+
 ## Custom status labels
 
 Integrations can report a short visual label without changing the semantic state.
diff --git a/website/src/content/docs/ja/agents.mdx b/website/src/content/docs/ja/agents.mdx
index 60a6451c..4982aa04 100644
--- a/website/src/content/docs/ja/agents.mdx
+++ b/website/src/content/docs/ja/agents.mdx
@@ -21,6 +21,7 @@ Herdr は複数のコーディングエージェントを同時に動かすた�
 | Droid | スクリーンマニフェスト | セッション |
 | OpenCode | インストール時はライフサイクルプラグイン。それ以外はスクリーンマニフェスト | 状態とセッション |
 | Kilo Code CLI | インストール時はライフサイクルプラグイン。それ以外はスクリーンマニフェスト | 状態とセッション |
+| MastraCode | インストール時はライフサイクルフック | 状態とセッション |
 | Claude Code | スクリーンマニフェスト | セッション |
 | Codex | スクリーンマニフェスト | セッション |
 | Cursor Agent CLI | スクリーンマニフェスト | セッション |
diff --git a/website/src/content/docs/ja/cli-reference.mdx b/website/src/content/docs/ja/cli-reference.mdx
index 53559ea0..f3a8d015 100644
--- a/website/src/content/docs/ja/cli-reference.mdx
+++ b/website/src/content/docs/ja/cli-reference.mdx
@@ -254,6 +254,7 @@ herdr integration install kimi
 herdr integration install opencode
 herdr integration install kilo
 herdr integration install hermes
+herdr integration install mastracode
 herdr integration install qodercli
 herdr integration install cursor
 herdr integration uninstall pi
@@ -267,6 +268,7 @@ herdr integration uninstall kimi
 herdr integration uninstall opencode
 herdr integration uninstall kilo
 herdr integration uninstall hermes
+herdr integration uninstall mastracode
 herdr integration uninstall qodercli
 herdr integration uninstall cursor
 herdr integration status [--outdated-only]
diff --git a/website/src/content/docs/ja/configuration.mdx b/website/src/content/docs/ja/configuration.mdx
index 39d3c825..44b327b2 100644
--- a/website/src/content/docs/ja/configuration.mdx
+++ b/website/src/content/docs/ja/configuration.mdx
@@ -457,7 +457,7 @@ Herdr は、Herdr サーバーの再起動後に、対応エージェントの�
 resume_agents_on_restore = true
 ```
 
-これはデフォルトで有効です。Herdr が resume するのは、公式 Herdr インテグレーションを通じてネイティブセッション参照を報告したペインだけです。対応する resume ターゲットは Claude Code、Codex、Cursor Agent CLI、GitHub Copilot CLI、Droid、Kimi Code CLI、Qoder CLI、Pi、Hermes Agent、OpenCode、Kilo Code CLI です。未対応、欠落、無効、重複、または古くなったセッション参照は、保存されたペインディレクトリで通常のシェルとして復元されます。
+これはデフォルトで有効です。Herdr が resume するのは、公式 Herdr インテグレーションを通じてネイティブセッション参照を報告したペインだけです。対応する resume ターゲットは Claude Code、Codex、Cursor Agent CLI、GitHub Copilot CLI、Droid、Kimi Code CLI、Qoder CLI、Pi、Hermes Agent、OpenCode、Kilo Code CLI、MastraCode です。未対応、欠落、無効、重複、または古くなったセッション参照は、保存されたペインディレクトリで通常のシェルとして復元されます。
 
 セッション参照はローカルの Herdr セッションスナップショットに保存されます。通常のペイン、エージェント、ステータス、イベント出力には表示されません。
 
diff --git a/website/src/content/docs/ja/integrations.mdx b/website/src/content/docs/ja/integrations.mdx
index 0930db49..dd1b4449 100644
--- a/website/src/content/docs/ja/integrations.mdx
+++ b/website/src/content/docs/ja/integrations.mdx
@@ -1,11 +1,11 @@
 ---
 title: インテグレーション
-description: Pi、OMP、Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Kimi Code CLI、OpenCode、Kilo Code CLI、Hermes Agent、Qoder CLI、Cursor Agent CLI 向けの Herdr インテグレーションをインストールします。
+description: Pi、OMP、Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Kimi Code CLI、OpenCode、Kilo Code CLI、Hermes Agent、Qoder CLI、Cursor Agent CLI、MastraCode 向けの Herdr インテグレーションをインストールします。
 ---
 
 Herdr は対応エージェントを自動的に検出します。公式インテグレーションは、復元のためのネイティブセッション識別、ライフサイクル状態の報告、またはその両方を追加できます。
 
-Claude Code/Codex/Copilot/Devin 系のフックによるエージェントネイティブのセッション復元、Pi/OMP/Kimi/OpenCode/Kilo/Hermes 系のフックまたはプラグインによる直接のライフサイクル報告、あるいはその両方が欲しいときにインテグレーションを使ってください。状態権威モデルの全体像は[エージェント](/ja/docs/agents/)を参照してください。
+Claude Code/Codex/Copilot/Devin 系のフックによるエージェントネイティブのセッション復元、Pi/OMP/Kimi/OpenCode/Kilo/Hermes/MastraCode 系のフックまたはプラグインによる直接のライフサイクル報告、あるいはその両方が欲しいときにインテグレーションを使ってください。状態権威モデルの全体像は[エージェント](/ja/docs/agents/)を参照してください。
 
 ## インテグレーションをインストールする
 
@@ -23,6 +23,7 @@ herdr integration install kimi
 herdr integration install opencode
 herdr integration install kilo
 herdr integration install hermes
+herdr integration install mastracode
 herdr integration install qodercli
 herdr integration install cursor
 ```
@@ -41,6 +42,7 @@ herdr integration uninstall kimi
 herdr integration uninstall opencode
 herdr integration uninstall kilo
 herdr integration uninstall hermes
+herdr integration uninstall mastracode
 herdr integration uninstall qodercli
 herdr integration uninstall cursor
 ```
@@ -51,14 +53,14 @@ Herdr はインテグレーションを 2 つの異なる方法で使います:
 
 | インテグレーションの種類 | エージェント | 効果 |
 | --- | --- | --- |
-| ライフサイクル権威 | Pi、OMP、Kimi Code CLI、OpenCode、Kilo Code CLI、Hermes Agent | インストールされ、そのペインについて能動的に報告している間は、フックまたはプラグインのイベントが `idle`、`working`、`blocked` を決定します。同じライフサイクル権威に対して、Herdr はスクリーンマニフェストのフォールバックを併用しません。 |
+| ライフサイクル権威 | Pi、OMP、Kimi Code CLI、OpenCode、Kilo Code CLI、Hermes Agent、MastraCode | インストールされ、そのペインについて能動的に報告している間は、フックまたはプラグインのイベントが `idle`、`working`、`blocked` を決定します。同じライフサイクル権威に対して、Herdr はスクリーンマニフェストのフォールバックを併用しません。 |
 | セッション識別 | Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Qoder CLI、Cursor Agent CLI | インテグレーションは復元用のネイティブセッション参照を報告します。状態は引き続き Herdr のスクリーンマニフェスト検出から得られます。 |
 
 カスタムソケットインテグレーションも、ネイティブのターミナル UI では見えない状態を定義する場合に状態を報告できます。
 
-一部のインテグレーションは、エージェントのネイティブセッション参照を報告します。Herdr は公式のセッション参照を使って、`[session] resume_agents_on_restore = false` で無効化されていない限り、Herdr サーバーの再起動後に Claude Code、Codex、Devin CLI、Droid、Kimi Code CLI、Qoder CLI、Cursor Agent CLI、GitHub Copilot CLI、Pi、OMP、Hermes Agent、OpenCode、Kilo Code CLI のペインを resume します。
+一部のインテグレーションは、エージェントのネイティブセッション参照を報告します。Herdr は公式のセッション参照を使って、`[session] resume_agents_on_restore = false` で無効化されていない限り、Herdr サーバーの再起動後に Claude Code、Codex、Devin CLI、Droid、Kimi Code CLI、Qoder CLI、Cursor Agent CLI、GitHub Copilot CLI、Pi、OMP、Hermes Agent、OpenCode、Kilo Code CLI、MastraCode のペインを resume します。
 
-エージェントネイティブのセッション復元には最新の Herdr インテグレーションが必要です: Pi インテグレーションはバージョン `2`、OMP は `3`、Claude Code は `6`、Codex は `5`、GitHub Copilot CLI は `2`、Devin CLI は `2`、Droid は `2`、Kimi Code CLI は `3`、Qoder CLI は `2`、Cursor Agent CLI は `1`、OpenCode は `5`、Kilo Code CLI は `1`、Hermes Agent は `2` です。インストール済みバージョンは `herdr integration status` で確認してください。
+エージェントネイティブのセッション復元には最新の Herdr インテグレーションが必要です: Pi インテグレーションはバージョン `2`、OMP は `3`、Claude Code は `6`、Codex は `5`、GitHub Copilot CLI は `2`、Devin CLI は `2`、Droid は `2`、Kimi Code CLI は `3`、Qoder CLI は `2`、Cursor Agent CLI は `1`、OpenCode は `5`、Kilo Code CLI は `1`、Hermes Agent は `2`、MastraCode は `1` です。インストール済みバージョンは `herdr integration status` で確認してください。
 
 ## Pi
 
@@ -240,6 +242,20 @@ Herdr はデフォルトで `~/.cursor` を使い、`CURSOR_CONFIG_DIR` が設�
 
 Cursor がセッション開始イベントを発行した後、Herdr は報告されたセッション id を使って `cursor-agent --resume <id>` でペインを resume できます。Herdr がペインを復元するとき、`cursor-agent` コマンドが `PATH` にある必要があります。Herdr は汎用の `agent` コマンドを起動しません。
 
+## MastraCode
+
+MastraCode フックをインストールします:
+
+```bash
+herdr integration install mastracode
+```
+
+このフックは、MastraCode のライフサイクル状態とスレッド識別を Herdr に報告し、権威ある `idle`、`working`、`blocked` 状態とネイティブ復元を提供します。MastraCode にはスクリーンマニフェストのフォールバックはありません。MastraCode が Herdr ペイン内で動いている間、状態はフックから得られます。
+
+Herdr は `~/.mastracode` を使います。インストールは `hooks/herdr-agent-state.sh` を書き込み、`hooks.json` に Herdr のコマンドエントリを追加します。ディレクトリがなければ作成します。アンインストールは一致するフックエントリを削除し、フックスクリプトを削除します。
+
+Herdr は保存された MastraCode スレッドを `mastracode --thread <id>` で resume します。
+
 ## カスタムステータスラベル
 
 インテグレーションは、意味的な状態を変えずに短い表示用ラベルを報告できます。
diff --git a/website/src/content/docs/ja/session-state.mdx b/website/src/content/docs/ja/session-state.mdx
index 95bc0d28..6b349159 100644
--- a/website/src/content/docs/ja/session-state.mdx
+++ b/website/src/content/docs/ja/session-state.mdx
@@ -79,6 +79,7 @@ Herdr が resume するのは、現行の公式 Herdr インテグレーショ�
 | OpenCode | `5` | `opencode --session <id>` |
 | Kilo Code CLI | `1` | `kilo --session <id>` |
 | Hermes Agent | `2` | `hermes --resume <id>` |
+| MastraCode | `1` | `mastracode --thread <id>` |
 
 インストール済みインテグレーションのバージョンは `herdr integration status` で確認できます。古いインテグレーションは `herdr integration install <agent>` で再インストールしてください。
 
diff --git a/website/src/content/docs/keyboard.mdx b/website/src/content/docs/keyboard.mdx
index 07f11362..d102802f 100644
--- a/website/src/content/docs/keyboard.mdx
+++ b/website/src/content/docs/keyboard.mdx
@@ -64,7 +64,7 @@ The full keymap and the binding syntax live in the [keybinding reference](/docs/
 
 ## Copy mode
 
-Press `prefix+[` to enter copy mode for the focused pane. Use `h/j/k/l`, `w/b/e`, and `{`/`}` to move, `v` or Space to start a selection, `y` or Enter to copy it, and `q` or Esc to leave without copying. Mouse drag-select copies without entering copy mode at all.
+Press `prefix+[` to enter copy mode for the focused pane. Use `h/j/k/l`, `w/b/e`, `{`/`}`, `PageUp`/`PageDown`, `ctrl+b`/`ctrl+f`, and `ctrl+u`/`ctrl+d` to move, `v` or Space to start a selection, `y` or Enter to copy it, and `q` or Esc to leave without copying. The configured prefix keeps its normal meaning in copy mode; with the default prefix, `ctrl+b` enters prefix mode instead of paging up, so use a different prefix if you want `ctrl+b` for copy-mode page-up. Mouse drag-select copies without entering copy mode at all.
 
 ## Change anything
 
diff --git a/website/src/content/docs/persistence-remote.mdx b/website/src/content/docs/persistence-remote.mdx
index 80cf19d3..a365ac88 100644
--- a/website/src/content/docs/persistence-remote.mdx
+++ b/website/src/content/docs/persistence-remote.mdx
@@ -63,11 +63,20 @@ Then attach with:
 herdr --remote workbox
 ```
 
-Remote attach supports Linux and macOS hosts on x86_64 and aarch64. Herdr checks the remote platform, prefers a matching `herdr` already on the remote `PATH`, then checks `~/.local/bin/herdr`. If no matching binary exists, interactive runs prompt to install one to `~/.local/bin/herdr`; non-interactive runs fail instead of modifying the host. If `~/.local/bin` is not on the remote `PATH`, Herdr warns after install.
+Remote attach supports Linux and macOS hosts on x86_64 and aarch64. Herdr checks the remote platform, prefers a matching `herdr` already on the remote `PATH`, then checks common direct, Homebrew, mise, and Nix profile install paths. If no matching binary exists, interactive runs prompt to install one to `~/.local/bin/herdr`; non-interactive runs fail instead of modifying the host. If `~/.local/bin` is not on the remote `PATH`, Herdr warns after install.
 
 Native Windows `herdr --remote` is not part of the Windows beta. From Windows, SSH into the server and run `herdr` there.
 
-By default, `herdr --remote` runs the bridge through a temporary SSH config that includes your SSH config first, then adds fallback keepalive settings. Existing user keepalive settings win. Set `[remote].manage_ssh_config = false` to use plain `ssh` without Herdr's generated bridge config.
+By default, `herdr --remote` runs remote setup and the bridge through a temporary SSH config that includes your SSH config first, then adds fallback keepalive settings and a private per-attach control socket for connection reuse. Existing user keepalive settings win. Set `[remote].manage_ssh_config = false` to use plain `ssh` without Herdr's generated config or control socket.
+
+Remote attach uses your normal OpenSSH authentication. If the target uses a passphrase-protected key in a non-interactive shell, script, CI job, or mobile terminal that cannot show the passphrase prompt, load the key into ssh-agent first:
+
+```bash
+ssh-add
+herdr --remote workbox
+```
+
+For any remote authentication failure, verify plain SSH access first with `ssh workbox`, then run `herdr --remote workbox` again.
 
 By default, remote attach uses the normal restart/stop flow if it needs to replace or restart a running remote server. To opt into experimental live handoff for a supported running remote server, pass `--handoff`:
 
@@ -121,6 +130,30 @@ Only one writable direct attach client owns input and resize for a terminal. Use
 herdr terminal attach term_abc123 --takeover
 ```
 
+For third-party bridges that only need rendered terminal bytes, use a read-only
+terminal session observer:
+
+```bash
+herdr terminal session observe w1:p1 --cols 120 --rows 40
+```
+
+It prints newline-delimited JSON `terminal.frame` records with base64 ANSI
+bytes, then a `terminal.closed` record when the server closes the stream.
+Multiple observers can watch the same terminal without taking input, resize,
+scroll, or takeover ownership.
+
+For an interactive bridge, use a writable terminal session controller:
+
+```bash
+herdr terminal session control w1:p1 --takeover --cols 120 --rows 40
+```
+
+Control mode prints the same newline-delimited frame records and reads
+newline-delimited JSON commands on stdin. `terminal.input` sends text or
+base64 bytes, `terminal.resize` changes the controller viewport,
+`terminal.scroll` scrolls the attached viewport, and `terminal.release` closes
+the controller. Only one controller owns input and resize at a time.
+
 ## Single-process escape hatch
 
 Use `--no-session` to run Herdr without the background server/client split:
diff --git a/website/src/content/docs/session-state.mdx b/website/src/content/docs/session-state.mdx
index 0c7f68ac..a2ac187e 100644
--- a/website/src/content/docs/session-state.mdx
+++ b/website/src/content/docs/session-state.mdx
@@ -79,6 +79,7 @@ Native session restore requires these Herdr integration versions or newer:
 | OpenCode | `5` | `opencode --session <id>` |
 | Kilo Code CLI | `1` | `kilo --session <id>` |
 | Hermes Agent | `2` | `hermes --resume <id>` |
+| MastraCode | `1` | `mastracode --thread <id>` |
 
 Run `herdr integration status` to check installed integration versions. Reinstall outdated integrations with `herdr integration install <agent>`.
 
diff --git a/website/src/content/docs/socket-api.mdx b/website/src/content/docs/socket-api.mdx
index 0db2e3c6..600238b9 100644
--- a/website/src/content/docs/socket-api.mdx
+++ b/website/src/content/docs/socket-api.mdx
@@ -17,6 +17,22 @@ Most automation should start with the CLI wrappers. Use the raw socket API only
 
 The layers share the same control surface.
 
+## Schema
+
+The installed CLI can print the socket protocol schema bundled with that Herdr
+binary:
+
+```bash
+herdr api schema
+herdr api schema --json
+herdr api schema --output herdr-api.schema.json
+```
+
+Plain `herdr api schema` prints a short summary. `--json` prints the full JSON
+Schema document for tools, and `--output PATH` writes that document to a file.
+The schema covers raw requests, success responses, error responses, emitted
+events, and subscription events.
+
 ## What you can control
 
 The socket API can:
@@ -83,11 +99,12 @@ Raw socket method names use dot notation:
 | Server | `ping`, `server.stop`, `server.reload_config`, `server.agent_manifests`, `server.reload_agent_manifests` |
 | Notification | `notification.show` |
 | Client | `client.window_title.set`, `client.window_title.clear` |
-| Workspace | `workspace.create`, `workspace.list`, `workspace.get`, `workspace.focus`, `workspace.rename`, `workspace.close` |
+| Session | `session.snapshot` |
+| Workspace | `workspace.create`, `workspace.list`, `workspace.get`, `workspace.focus`, `workspace.rename`, `workspace.move`, `workspace.close` |
 | Worktree | `worktree.list`, `worktree.create`, `worktree.open`, `worktree.remove` |
-| Tab | `tab.create`, `tab.list`, `tab.get`, `tab.focus`, `tab.rename`, `tab.close` |
+| Tab | `tab.create`, `tab.list`, `tab.get`, `tab.focus`, `tab.rename`, `tab.move`, `tab.close` |
 | Pane | `pane.split`, `pane.swap`, `pane.move`, `pane.zoom`, `pane.layout`, `pane.process_info`, `pane.neighbor`, `pane.edges`, `pane.focus_direction`, `pane.resize`, `pane.list`, `pane.current`, `pane.get`, `pane.rename`, `pane.send_text`, `pane.send_keys`, `pane.send_input`, `pane.read`, `pane.report_agent`, `pane.report_agent_session`, `pane.report_metadata`, `pane.clear_agent_authority`, `pane.release_agent`, `pane.close`, `pane.wait_for_output` |
-| Layout | `layout.export`, `layout.apply` |
+| Layout | `layout.export`, `layout.apply`, `layout.set_split_ratio` |
 | Agent | `agent.list`, `agent.get`, `agent.read`, `agent.explain`, `agent.send`, `agent.rename`, `agent.focus`, `agent.start` |
 | Events | `events.subscribe`, `events.wait` |
 | Integrations | `integration.install`, `integration.uninstall` |
@@ -95,6 +112,18 @@ Raw socket method names use dot notation:
 
 Some CLI commands are conveniences around these methods. For example, `herdr agent wait` resolves an agent target and then subscribes to pane agent state events.
 
+`session.snapshot` returns a one-time bootstrap snapshot for clients that keep
+their own local runtime cache. The response includes version/protocol metadata,
+focused workspace/tab/pane ids, workspace records, tab records, pane records,
+tab layout snapshots, and agent records. It is not a subscription; after reading
+it, subscribe to resource events and update the local cache from those events.
+Call `session.snapshot` again after reconnecting or when the local cache may be
+stale. Attached worktree provenance is included on workspace records. Full repo
+worktree discovery remains `worktree.list`.
+
+From the CLI, `herdr api snapshot` prints the live `session.snapshot` response
+as JSON for clients and agents that want a simple bootstrap command.
+
 Pane control methods use public pane ids such as `w1:p1`. Methods whose
 schema makes `pane_id` optional use the server's active focused pane when it is
 omitted. `pane.move` always requires the source `pane_id`.
@@ -121,6 +150,18 @@ like `ctrl+h`, `control+j`, `alt+x`, and `shift+tab`, function keys like
 Herdr returns that pane. When it is omitted, Herdr returns the active focused
 pane.
 
+`PaneInfo` includes `scroll` when terminal scroll metrics are available:
+
+```json
+{
+  "offset_from_bottom": 12,
+  "max_offset_from_bottom": 240,
+  "viewport_rows": 30
+}
+```
+
+Clients can treat `offset_from_bottom == 0` as at-bottom state.
+
 `pane.layout` returns the tab layout snapshot with `workspace_id`, `tab_id`,
 `zoomed`, outer `area`, `focused_pane_id`, pane rects, and split rects/ratios.
 `pane.neighbor` and `pane.edges` include that same layout snapshot so clients
@@ -177,6 +218,13 @@ not preserve live PTYs, scrollback, or running processes.
 }
 ```
 
+`layout.set_split_ratio` updates an existing split in a tab layout. The response
+is `type: "layout_split_ratio_set"` with the updated portable `layout`.
+
+```json
+{"id":"req_ratio","method":"layout.set_split_ratio","params":{"tab_id":"w1:t1","path":[],"ratio":0.6}}
+```
+
 Process-launching methods accept an `env` object. Herdr applies those key/value
 pairs to the newly launched process only. Herdr also injects `HERDR_SOCKET_PATH`,
 `HERDR_ENV=1`, `HERDR_WORKSPACE_ID`, `HERDR_TAB_ID`, and `HERDR_PANE_ID` into
@@ -587,10 +635,21 @@ Subscribe to events when you need a long-lived stream:
 
 The first response acknowledges the subscription. Later lines are pushed events.
 
-Workspace event subscriptions include `workspace.created`, `workspace.updated`, `workspace.renamed`, `workspace.closed`, and `workspace.focused`. Workspace events describe Herdr UI/runtime lifecycle. `workspace.created` includes optional `workspace.worktree` provenance when the workspace belongs to a worktree group. `workspace.closed` includes a final `workspace` snapshot when Herdr can still identify it before removal.
+Workspace event subscriptions include `workspace.created`, `workspace.updated`, `workspace.renamed`, `workspace.moved`, `workspace.closed`, and `workspace.focused`. Workspace events describe Herdr UI/runtime lifecycle. `workspace.created` includes optional `workspace.worktree` provenance when the workspace belongs to a worktree group. `workspace.moved` includes the moved `workspace_id`, requested `insert_index`, and updated ordered `workspaces` list. `workspace.closed` includes a final `workspace` snapshot when Herdr can still identify it before removal.
+Tab event subscriptions include `tab.created`, `tab.closed`, `tab.focused`,
+`tab.renamed`, and `tab.moved`. `tab.moved` includes the moved `tab_id`,
+`workspace_id`, requested `insert_index`, and updated ordered `tabs` list for
+that workspace.
 Pane event subscriptions include `pane.created`, `pane.closed`, `pane.focused`,
 `pane.moved`, `pane.exited`, `pane.agent_detected`,
-`pane.output_matched`, and `pane.agent_status_changed`.
+`pane.output_matched`, `pane.agent_status_changed`, and `pane.scroll_changed`.
+`pane.scroll_changed` is scoped to one `pane_id` and emits `pane_id`,
+`workspace_id`, and the current `scroll` metrics whenever Herdr observes a
+changed scroll snapshot.
+Layout event subscriptions include `layout.updated`. The event carries the
+updated `PaneLayoutSnapshot` for one tab. Clients that bootstrap with
+`session.snapshot` should replace the cached layout with the same
+`workspace_id` and `tab_id`.
 
 Worktree event subscriptions include `worktree.created`, `worktree.opened`, and `worktree.removed`. Worktree events describe Git checkout lifecycle. `worktree.created` includes the opened `workspace` and created `worktree`. `worktree.opened` includes the target `workspace`, opened `worktree`, and `already_open`. `worktree.removed` includes the `workspace_id`, removed `worktree`, and `forced`.
 
diff --git a/website/src/content/docs/windows-beta.mdx b/website/src/content/docs/windows-beta.mdx
index 539abf8d..dbfe6964 100644
--- a/website/src/content/docs/windows-beta.mdx
+++ b/website/src/content/docs/windows-beta.mdx
@@ -50,6 +50,7 @@ Plugins support `windows` as a manifest platform in preview. GitHub install, loc
 | Clipboard image paste to agents | unverified |
 | CJK hidden-cursor reveal | beta |
 | Kitty graphics rendering | unverified |
+| Host cursor rendering | beta |
 
 Herdr can launch panes in the right directory and can create the initial workspace from the directory where you started Herdr. PowerShell directory changes after startup are different: the process field Herdr can inspect does not reliably track later logical `cd` changes. Use Herdr integrations or prompt shell integration for live cwd reporting.
 
@@ -57,6 +58,23 @@ Windows Terminal may support image paste paths for specific agents, but Herdr's
 
 Kitty graphics remains experimental and is not claimed as Windows-supported yet. Leave `experimental.kitty_graphics = false` unless you are specifically testing image rendering in Windows Terminal.
 
+## Known caveats
+
+### Cursor rendering
+
+Windows terminals run Herdr through ConPTY, and native terminal cursors can flicker, jump, or briefly show stale positions during active full-screen redraws. Herdr's default `host_cursor = "auto"` draws Herdr's cursor as terminal cell content on Windows, while Linux and macOS keep using the native terminal cursor. The Windows trade-off is a steady non-blinking cursor inside Herdr instead of the outer terminal's native blink, shape, and cursor color.
+
+To opt back into the outer terminal cursor on Windows, set:
+
+```toml
+[ui]
+host_cursor = "native"
+```
+
+### Keyboard and mouse
+
+Windows terminals do not all report modified keys in the same shape. Herdr preserves mouse reporting and `ctrl+j` in Windows Terminal and Alacritty on Windows, but `shift+enter` only works when the outer terminal reports it as a distinct modified Enter key. If Windows or the terminal reports it as plain Enter, Herdr forwards plain Enter.
+
 ## Copy and paste
 
 Herdr's pane text copy works on Windows beta. Drag-select text inside a pane to copy through Herdr.
diff --git a/website/src/content/docs/zh-cn/agents.mdx b/website/src/content/docs/zh-cn/agents.mdx
index f8db7a41..24459ffb 100644
--- a/website/src/content/docs/zh-cn/agents.mdx
+++ b/website/src/content/docs/zh-cn/agents.mdx
@@ -21,6 +21,7 @@ Herdr 为同时运行多个编程智能体而生。每个智能体都待在一�
 | Droid | 屏幕清单 | 会话 |
 | OpenCode | 安装后为生命周期插件;否则为屏幕清单 | 状态与会话 |
 | Kilo Code CLI | 安装后为生命周期插件;否则为屏幕清单 | 状态与会话 |
+| MastraCode | 安装后为生命周期钩子 | 状态与会话 |
 | Claude Code | 屏幕清单 | 会话 |
 | Codex | 屏幕清单 | 会话 |
 | Cursor Agent CLI | 屏幕清单 | 会话 |
diff --git a/website/src/content/docs/zh-cn/cli-reference.mdx b/website/src/content/docs/zh-cn/cli-reference.mdx
index 0c23adec..91a7b205 100644
--- a/website/src/content/docs/zh-cn/cli-reference.mdx
+++ b/website/src/content/docs/zh-cn/cli-reference.mdx
@@ -254,6 +254,7 @@ herdr integration install kimi
 herdr integration install opencode
 herdr integration install kilo
 herdr integration install hermes
+herdr integration install mastracode
 herdr integration install qodercli
 herdr integration install cursor
 herdr integration uninstall pi
@@ -267,6 +268,7 @@ herdr integration uninstall kimi
 herdr integration uninstall opencode
 herdr integration uninstall kilo
 herdr integration uninstall hermes
+herdr integration uninstall mastracode
 herdr integration uninstall qodercli
 herdr integration uninstall cursor
 herdr integration status [--outdated-only]
diff --git a/website/src/content/docs/zh-cn/configuration.mdx b/website/src/content/docs/zh-cn/configuration.mdx
index e6bccd81..56f10a19 100644
--- a/website/src/content/docs/zh-cn/configuration.mdx
+++ b/website/src/content/docs/zh-cn/configuration.mdx
@@ -457,7 +457,7 @@ Herdr 可以在服务器重启后,让受支持的智能体窗格在其原生对�
 resume_agents_on_restore = true
 ```
 
-这默认开启。Herdr 只恢复通过官方 Herdr 集成上报了原生会话引用的窗格。受支持的恢复目标是 Claude Code、Codex、Cursor Agent CLI、GitHub Copilot CLI、Droid、Kimi Code CLI、Qoder CLI、Pi、Hermes Agent、OpenCode 和 Kilo Code CLI。不受支持、缺失、无效、重复或过期的会话引用,会在保存的窗格目录中作为普通 shell 恢复。
+这默认开启。Herdr 只恢复通过官方 Herdr 集成上报了原生会话引用的窗格。受支持的恢复目标是 Claude Code、Codex、Cursor Agent CLI、GitHub Copilot CLI、Droid、Kimi Code CLI、Qoder CLI、Pi、Hermes Agent、OpenCode、Kilo Code CLI 和 MastraCode。不受支持、缺失、无效、重复或过期的会话引用,会在保存的窗格目录中作为普通 shell 恢复。
 
 会话引用存储在本地 Herdr 会话快照中。它们不会出现在普通的窗格、智能体、状态或事件输出中。
 
diff --git a/website/src/content/docs/zh-cn/integrations.mdx b/website/src/content/docs/zh-cn/integrations.mdx
index 5ad8fa92..1f7d0787 100644
--- a/website/src/content/docs/zh-cn/integrations.mdx
+++ b/website/src/content/docs/zh-cn/integrations.mdx
@@ -1,11 +1,11 @@
 ---
 title: 集成
-description: 为 Pi、OMP、Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Kimi Code CLI、OpenCode、Kilo Code CLI、Hermes Agent、Qoder CLI 和 Cursor Agent CLI 安装 Herdr 集成。
+description: 为 Pi、OMP、Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Kimi Code CLI、OpenCode、Kilo Code CLI、Hermes Agent、Qoder CLI、Cursor Agent CLI 和 MastraCode 安装 Herdr 集成。
 ---
 
 Herdr 自动检测受支持的智能体。官方集成可以额外提供用于恢复的原生会话身份、生命周期状态上报,或两者兼有。
 
-当你想要 Claude Code/Codex/Copilot/Devin 式钩子的智能体原生会话恢复、Pi/OMP/Kimi/OpenCode/Kilo/Hermes 式钩子或插件的直接生命周期上报,或两者都要时,使用集成。完整的状态权威模型见[智能体](/zh-cn/docs/agents/)。
+当你想要 Claude Code/Codex/Copilot/Devin 式钩子的智能体原生会话恢复、Pi/OMP/Kimi/OpenCode/Kilo/Hermes/MastraCode 式钩子或插件的直接生命周期上报,或两者都要时,使用集成。完整的状态权威模型见[智能体](/zh-cn/docs/agents/)。
 
 ## 安装集成
 
@@ -23,6 +23,7 @@ herdr integration install kimi
 herdr integration install opencode
 herdr integration install kilo
 herdr integration install hermes
+herdr integration install mastracode
 herdr integration install qodercli
 herdr integration install cursor
 ```
@@ -41,6 +42,7 @@ herdr integration uninstall kimi
 herdr integration uninstall opencode
 herdr integration uninstall kilo
 herdr integration uninstall hermes
+herdr integration uninstall mastracode
 herdr integration uninstall qodercli
 herdr integration uninstall cursor
 ```
@@ -51,14 +53,14 @@ Herdr 以两种不同方式使用集成:
 
 | 集成类型 | 智能体 | 效果 |
 | --- | --- | --- |
-| 生命周期权威 | Pi、OMP、Kimi Code CLI、OpenCode、Kilo Code CLI、Hermes Agent | 已安装且在为该窗格主动上报时,由钩子或插件事件决定 `idle`、`working` 和 `blocked`。对同一个生命周期权威,Herdr 不再使用屏幕清单兜底。 |
+| 生命周期权威 | Pi、OMP、Kimi Code CLI、OpenCode、Kilo Code CLI、Hermes Agent、MastraCode | 已安装且在为该窗格主动上报时,由钩子或插件事件决定 `idle`、`working` 和 `blocked`。对同一个生命周期权威,Herdr 不再使用屏幕清单兜底。 |
 | 会话身份 | Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Qoder CLI、Cursor Agent CLI | 集成上报用于恢复的原生会话引用。状态仍来自 Herdr 的屏幕清单检测。 |
 
 自定义 socket 集成在定义了原生终端 UI 中不可见的状态时,也可以上报状态。
 
-一些集成会上报智能体的原生会话引用。除非被 `[session] resume_agents_on_restore = false` 禁用,Herdr 会在服务器重启后使用官方会话引用恢复 Claude Code、Codex、Devin CLI、Droid、Kimi Code CLI、Qoder CLI、Cursor Agent CLI、GitHub Copilot CLI、Pi、OMP、Hermes Agent、OpenCode 和 Kilo Code CLI 的窗格。
+一些集成会上报智能体的原生会话引用。除非被 `[session] resume_agents_on_restore = false` 禁用,Herdr 会在服务器重启后使用官方会话引用恢复 Claude Code、Codex、Devin CLI、Droid、Kimi Code CLI、Qoder CLI、Cursor Agent CLI、GitHub Copilot CLI、Pi、OMP、Hermes Agent、OpenCode、Kilo Code CLI 和 MastraCode 的窗格。
 
-原生会话恢复需要最新的 Herdr 集成: Pi 集成版本 `2`、OMP 版本 `3`、Claude Code 版本 `6`、Codex 版本 `5`、GitHub Copilot CLI 版本 `2`、Devin CLI 版本 `2`、Droid 版本 `2`、Kimi Code CLI 版本 `3`、Qoder CLI 版本 `2`、Cursor Agent CLI 版本 `1`、OpenCode 版本 `5`、Kilo Code CLI 版本 `1`、Hermes Agent 版本 `2`。用 `herdr integration status` 查看已安装版本。
+原生会话恢复需要最新的 Herdr 集成: Pi 集成版本 `2`、OMP 版本 `3`、Claude Code 版本 `6`、Codex 版本 `5`、GitHub Copilot CLI 版本 `2`、Devin CLI 版本 `2`、Droid 版本 `2`、Kimi Code CLI 版本 `3`、Qoder CLI 版本 `2`、Cursor Agent CLI 版本 `1`、OpenCode 版本 `5`、Kilo Code CLI 版本 `1`、Hermes Agent 版本 `2`、MastraCode 版本 `1`。用 `herdr integration status` 查看已安装版本。
 
 ## Pi
 
@@ -240,6 +242,20 @@ Herdr 默认使用 `~/.cursor`,设置了 `CURSOR_CONFIG_DIR` 时使用后者。C
 
 在 Cursor 发出会话启动事件后,Herdr 可以用上报的会话 id 通过 `cursor-agent --resume <id>` 恢复该窗格。Herdr 恢复窗格时,`cursor-agent` 命令必须在 `PATH` 上;Herdr 不会启动通用的 `agent` 命令。
 
+## MastraCode
+
+安装 MastraCode 钩子:
+
+```bash
+herdr integration install mastracode
+```
+
+该钩子向 Herdr 上报 MastraCode 生命周期状态和线程身份,用于权威的 `idle`、`working`、`blocked` 状态和原生恢复。MastraCode 没有屏幕清单兜底;当 MastraCode 在 Herdr 窗格内运行时,状态来自该钩子。
+
+Herdr 使用 `~/.mastracode`。安装会写入 `hooks/herdr-agent-state.sh`,并把 Herdr 命令条目添加到 `hooks.json`;目录不存在时会创建。卸载会删除匹配的钩子条目和钩子脚本。
+
+Herdr 用 `mastracode --thread <id>` 恢复保存的 MastraCode 线程。
+
 ## 自定义状态标签
 
 集成可以上报一个简短的视觉标签,而不改变语义状态。
diff --git a/website/src/content/docs/zh-cn/session-state.mdx b/website/src/content/docs/zh-cn/session-state.mdx
index 2b41d038..c87016ec 100644
--- a/website/src/content/docs/zh-cn/session-state.mdx
+++ b/website/src/content/docs/zh-cn/session-state.mdx
@@ -79,6 +79,7 @@ Herdr 只会恢复那些通过当前官方 Herdr 集成上报了原生会话引�
 | OpenCode | `5` | `opencode --session <id>` |
 | Kilo Code CLI | `1` | `kilo --session <id>` |
 | Hermes Agent | `2` | `hermes --resume <id>` |
+| MastraCode | `1` | `mastracode --thread <id>` |
 
 运行 `herdr integration status` 查看已安装的集成版本。用 `herdr integration install <agent>` 重新安装过期的集成。