From ddffb6e1d79efb517a92034ed18b75c388a36e55 Mon Sep 17 00:00:00 2001
From: Ogulcan Celik <ogulcancelik@gmail.com>
Date: Tue, 11 Aug 2026 03:53:55 +0300
Subject: chore: refresh english documentation

---
 docs/next/README.md                                | 10 ++--
 .../website/src/content/docs/agent-automation.mdx  |  4 +-
 docs/next/website/src/content/docs/agent-skill.mdx |  4 +-
 docs/next/website/src/content/docs/agents.mdx      |  8 ++--
 .../website/src/content/docs/cli-reference.mdx     | 16 +++----
 docs/next/website/src/content/docs/concepts.mdx    |  2 +-
 .../website/src/content/docs/config-reference.mdx  |  2 +-
 .../website/src/content/docs/configuration.mdx     | 18 +++----
 docs/next/website/src/content/docs/how-to-work.mdx |  4 +-
 docs/next/website/src/content/docs/index.mdx       |  4 +-
 docs/next/website/src/content/docs/install.mdx     | 10 ++--
 .../next/website/src/content/docs/integrations.mdx | 14 +++---
 docs/next/website/src/content/docs/keyboard.mdx    |  6 +--
 docs/next/website/src/content/docs/marketplace.mdx | 14 +++---
 .../src/content/docs/persistence-remote.mdx        |  8 ++--
 docs/next/website/src/content/docs/plugins.mdx     | 55 +++++++++++-----------
 docs/next/website/src/content/docs/quick-start.mdx | 10 ++--
 .../website/src/content/docs/session-state.mdx     | 14 +++---
 docs/next/website/src/content/docs/socket-api.mdx  | 27 ++++++-----
 .../website/src/content/docs/troubleshooting.mdx   |  6 +--
 .../next/website/src/content/docs/windows-beta.mdx | 16 +++----
 21 files changed, 125 insertions(+), 127 deletions(-)

(limited to 'docs')

diff --git a/docs/next/README.md b/docs/next/README.md
index d1fc93a1..31a8a7d2 100644
--- a/docs/next/README.md
+++ b/docs/next/README.md
@@ -28,10 +28,10 @@ https://github.com/user-attachments/assets/043ec09f-4bdd-41d5-aee0-8fda6b83e267
 
 **the runtime your coding agents live on.**
 
-- **always running** — herdr is a background server; the terminals live inside it. close the lid, drop the network, restart the machine — agents keep working and sessions come back. reattach from any terminal, or over ssh.
+- **always running** — herdr is a background server; the terminals live inside it. close the lid, drop the network, or restart the machine; agents keep working and sessions come back. reattach from any terminal, or over ssh.
 - **never hunt for the stuck one** — every pane is marked working, blocked, or idle. when an agent stops and needs an answer, herdr says so.
-- **agent-native** — the cli and socket api are the same surface agents drive: spawn panes, prompt each other, wait until another agent is genuinely blocked. [agent skill →](https://herdr.dev/docs/agent-skill/)
-- **runs what you already run** — claude code, codex, cursor, opencode, grok and the rest. herdr doesn't wrap or replace them, it just owns their terminals.
+- **agent-native** — agents drive herdr through the cli and socket api: they can spawn panes, prompt each other, and wait until another agent is genuinely blocked. [agent skill →](https://herdr.dev/docs/agent-skill/)
+- **runs what you already run** — claude code, codex, cursor, opencode, grok and the rest. herdr doesn't wrap or replace them; it owns their terminals.
 - **keyboard and mouse, both first-class** — tmux-style prefix keys *and* click, drag, split. pick per moment, not per tool.
 - **plugins** — extend panes and workflows. [browse the marketplace →](https://herdr.dev/plugins/)
 - **one rust binary, no electron** — runs in whatever terminal you already use.
@@ -60,9 +60,7 @@ everything lives at [herdr.dev/docs](https://herdr.dev/docs/): [quick start](htt
 
 ## thanks
 
-<a href="https://terminaltrove.com/"><img src="assets/sponsors/terminal-trove.png" alt="Terminal Trove" width="200" /></a>
-
-[Terminal Trove](https://terminaltrove.com/) and every backer listed in [SPONSORS.md](./SPONSORS.md) — thank you 🐑
+every past sponsor and backer is listed in [SPONSORS.md](./SPONSORS.md) — thank you 🐑
 
 enterprise / partnership: hey@herdr.dev
 
diff --git a/docs/next/website/src/content/docs/agent-automation.mdx b/docs/next/website/src/content/docs/agent-automation.mdx
index 807bebd8..33bb14a5 100644
--- a/docs/next/website/src/content/docs/agent-automation.mdx
+++ b/docs/next/website/src/content/docs/agent-automation.mdx
@@ -3,7 +3,7 @@ title: Agent automation
 description: Use Herdr's layout, pane, and agent primitives to coordinate coding agents from scripts or other agents.
 ---
 
-Herdr can act as an automation layer for coding agents. A script can control them, or one agent can create work for other agents, inspect their state, and collect their results. The important part is choosing the primitive that matches the job.
+Use Herdr as an automation layer for coding agents. A script can control them, or one agent can create work for other agents, inspect their state, and collect their results. Choose the primitive that matches the job.
 
 ## Three primitives
 
@@ -73,7 +73,7 @@ herdr agent rename w1:p2 reviewer
 
 Pane input addresses the terminal regardless of its current occupant. Agent input resolves the live agent and rejects the operation if that agent no longer controls the pane.
 
-`agent prompt --wait` submits immediately. When the agent starts from a non-working state, Herdr first requires an observed lifecycle change within five seconds. If the state sequence does not advance, it returns `agent_prompt_stalled` instead of waiting indefinitely; a caller `--timeout` of five seconds or less returns the normal `timeout` error. After activity is observed, it waits for the requested settled status. It does not track individual turns. If the agent is already working, completion of that active turn may satisfy the wait. Standalone `agent wait` observes the current agent and returns immediately if its status already matches. Both commands default to `idle`, `done`, or `blocked`. Repeat `--until` to accept several exact states, for example `--until idle --until done`; use `--until unknown` explicitly when needed. On `agent prompt`, `--until` requires `--wait`.
+`agent prompt --wait` submits immediately. If the agent starts from a non-working state, Herdr must observe a lifecycle change within five seconds. Otherwise, it returns `agent_prompt_stalled` instead of waiting indefinitely; a caller `--timeout` of five seconds or less returns the normal `timeout` error. After Herdr observes activity, it waits for the requested settled status. It does not track individual turns. If the agent is already working, completion of that active turn may satisfy the wait. Standalone `agent wait` observes the current agent and returns immediately if its status already matches. Both commands default to `idle`, `done`, or `blocked`. Repeat `--until` to accept several exact states, for example `--until idle --until done`; use `--until unknown` explicitly when needed. On `agent prompt`, `--until` requires `--wait`.
 
 `idle` means the agent is ready for input and its tab has been seen in the focused Herdr UI. `done` is the same underlying idle state after background work finishes, until that tab is focused or `pane focus` / `agent focus` targets it. Reading through the CLI does not mark it seen. `blocked` means Herdr recognized an approval or question UI. `unknown` means an agent is present but Herdr cannot classify its lifecycle confidently; it does not prove successful completion. Use exact `--until` states when that distinction matters.
 
diff --git a/docs/next/website/src/content/docs/agent-skill.mdx b/docs/next/website/src/content/docs/agent-skill.mdx
index d9c0f162..d73832ac 100644
--- a/docs/next/website/src/content/docs/agent-skill.mdx
+++ b/docs/next/website/src/content/docs/agent-skill.mdx
@@ -21,7 +21,7 @@ With the skill installed, an agent can:
 - wait for servers, tests, or another agent to finish
 - start helper agents in sibling panes
 
-The skill is not a separate app or service. It is a markdown instruction file for agents. If Herdr is already installed, run `herdr --skill` to print the release-matched copy bundled with that binary.
+The skill is a Markdown instruction file for agents. If Herdr is already installed, run `herdr --skill` to print the release-matched copy bundled with that binary.
 
 ## Install it
 
@@ -50,7 +50,7 @@ herdr
 claude
 ```
 
-Or use any other coding agent in a Herdr pane. The important part is that the agent process runs inside Herdr, so `HERDR_ENV=1` is available.
+Or use any other coding agent in a Herdr pane so `HERDR_ENV=1` is available to the agent process.
 
 ## Safety rule
 
diff --git a/docs/next/website/src/content/docs/agents.mdx b/docs/next/website/src/content/docs/agents.mdx
index 2833f4bb..58939ed4 100644
--- a/docs/next/website/src/content/docs/agents.mdx
+++ b/docs/next/website/src/content/docs/agents.mdx
@@ -9,7 +9,7 @@ To coordinate agents from scripts or from another agent, see [Agent automation](
 
 ## Supported agents
 
-Automatic detection works out of the box for common coding agents. The important difference is not whether Herdr can see an agent. It is which signal is allowed to author `idle`, `working`, and `blocked`.
+Automatic detection works out of the box for common coding agents. The table shows which signal determines `idle`, `working`, and `blocked` for each one.
 
 | Agent | State authority | Integration role |
 | --- | --- | --- |
@@ -49,7 +49,7 @@ Integrations marked `session` in the table above are intentionally not lifecycle
 
 ## VMs and sandbox wrappers
 
-On Linux and macOS, a host-visible wrapper can hide the real agent process from Herdr. Set `HERDR_AGENT=<agent>` on the wrapper command to tell Herdr which existing agent screen manifest to use. For example, run `HERDR_AGENT=claude fence -- claude` on Linux or `HERDR_AGENT=claude nono run --profile claude-code -- claude` on macOS. The hint is scoped to that foreground process; setting it only inside a VM or container is not visible to Herdr, and you should avoid exporting it globally unless every inherited foreground process should be treated as that agent.
+On Linux and macOS, a host-visible wrapper can hide the real agent process from Herdr. Set `HERDR_AGENT=<agent>` on the wrapper command to tell Herdr which existing agent screen manifest to use. For example, run `HERDR_AGENT=claude fence -- claude` on Linux or `HERDR_AGENT=claude nono run --profile claude-code -- claude` on macOS. The hint applies only to that foreground process. Herdr cannot see it if you set it only inside a VM or container. Avoid exporting it globally unless every inherited foreground process should be treated as that agent.
 
 Some restricted Linux runtimes do not expose a terminal foreground process group. Start the Herdr server with `HERDR_PROCESS_DETECTION=child-groups` to opt into direct child-process-group inference when native detection is unavailable. Native detection remains preferred, and the default `native` mode never performs this inference. The opt-in mode is best effort: a newer background job can be mistaken for the foreground job. The variable is read by the server and requires a restart; set it in the remote server environment rather than on an attaching client.
 
@@ -57,7 +57,7 @@ Some restricted Linux runtimes do not expose a terminal foreground process group
 
 Blocked detection is deliberately strict for screen-manifest agents. Herdr only marks `blocked` when the live bottom-buffer snapshot matches known visible approval, question, or permission UI. If no manifest rule matches for a known agent, Herdr falls back to `idle` and labels that fallback as `default_known_agent_idle_fallback` in explain output.
 
-This means unusual new agent prompts may initially show as `idle` instead of `blocked` until Herdr learns that screen shape. Those interactions should not make Herdr send input or take destructive action; they only affect the visible status and waits.
+This means unusual new agent prompts may initially show as `idle` instead of `blocked` until Herdr learns that screen shape. The misclassification affects only the visible status and waits. It should not make Herdr send input or take destructive action.
 
 ## Detection manifests
 
@@ -96,7 +96,7 @@ This is the main Herdr workflow: start several agents, let them work in parallel
 
 ## Direct integrations
 
-Install the integration for each agent you use; it gives Herdr hook or plugin reports instead of screen detection alone:
+Install the integration for each agent you use to give Herdr hook or plugin reports instead of screen detection alone:
 
 ```bash
 herdr integration install claude
diff --git a/docs/next/website/src/content/docs/cli-reference.mdx b/docs/next/website/src/content/docs/cli-reference.mdx
index d9317c6e..1a362ca9 100644
--- a/docs/next/website/src/content/docs/cli-reference.mdx
+++ b/docs/next/website/src/content/docs/cli-reference.mdx
@@ -5,7 +5,7 @@ description: Herdr commands for sessions, workspaces, tabs, panes, notifications
 
 Herdr’s CLI talks to the running server over the same local socket API used by integrations and agents.
 
-Most commands print JSON responses. Use them from scripts when you want deterministic automation.
+Most commands print JSON responses for deterministic automation in scripts.
 
 ## Launch and status
 
@@ -130,7 +130,7 @@ Create a workspace without stealing focus:
 herdr workspace create --cwd ~/project --label api --no-focus
 ```
 
-A workspace is the top-level project or work context. Creating one also creates its first tab and root pane. The JSON response exposes their IDs as `.result.workspace.workspace_id`, `.result.tab.tab_id`, and `.result.root_pane.pane_id`.
+A workspace is a top-level project or work context. Creating one also creates its first tab and root pane. The JSON response exposes their IDs as `.result.workspace.workspace_id`, `.result.tab.tab_id`, and `.result.root_pane.pane_id`.
 
 ## Worktrees
 
@@ -143,7 +143,7 @@ herdr worktree remove --workspace ID [--force]
 
 Worktrees are normal Herdr workspaces with Git checkout provenance. `worktree create` creates a Git worktree checkout, opens it as a workspace, and groups it with the parent repo workspace. If `--branch` names an existing local branch, Herdr checks it out; otherwise it creates the branch from `--base` or `HEAD`. Without `--path`, Herdr creates the checkout under `<worktrees.directory>/<repo>/<branch-slug>`.
 
-`workspace close` closes Herdr state only. `worktree remove` is the explicit checkout deletion path; it runs `git worktree remove`, never deletes the branch, and requires `--force` when Git refuses a dirty checkout.
+`workspace close` closes only Herdr state. To delete the checkout, run `worktree remove`. It runs `git worktree remove`, never deletes the branch, and requires `--force` when Git refuses a dirty checkout.
 
 ## Tabs
 
@@ -156,7 +156,7 @@ herdr tab rename <tab_id> <label>
 herdr tab close <tab_id>
 ```
 
-A tab is another terminal layout inside a workspace. Without `--workspace`, `tab create` uses the active workspace and fails if none exists. Its JSON response exposes `.result.tab.tab_id` and `.result.root_pane.pane_id`. Closing a workspace's last tab also closes the workspace, matching the TUI close-tab action; when `confirm_close` is enabled and that would also close a whole worktree group, `tab close` returns a `confirmation_required` error instead.
+A tab is another terminal layout inside a workspace. Without `--workspace`, `tab create` uses the active workspace and fails if none exists. Its JSON response exposes `.result.tab.tab_id` and `.result.root_pane.pane_id`. Closing a workspace's last tab also closes the workspace, matching the TUI close-tab action. If `confirm_close` is enabled and closing the tab would also close a whole worktree group, `tab close` returns a `confirmation_required` error instead.
 
 Workspace and tab creation, and pane splitting, leave focus unchanged by default. `--focus` selects the new layout; `--no-focus` states the default explicitly. Without `--cwd`, new terminals follow the configured `terminal.new_cwd` policy, which follows the source pane or workspace by default. Each `--env KEY=VALUE` adds or replaces that variable in the new root shell.
 
@@ -255,7 +255,7 @@ herdr pane release-agent <pane_id> \
 
 `pane get`, `pane list`, `agent get`, and `agent list` include a read-only `agent_session` object when an official integration has reported a native session reference. If no native session reference is stored, the field is omitted.
 
-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.
+Those commands include `foreground_cwd` when Herdr can resolve the cwd of the foreground process controlling the pane. The `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.
 
@@ -418,7 +418,7 @@ herdr plugin link <path> [--disabled]
 herdr plugin unlink <plugin_id>
 ```
 
-`plugin link` accepts a plugin directory containing `herdr-plugin.toml` or a direct manifest path. It is still the right command while authoring or testing a plugin from a local checkout. `plugin unlink` unregisters the plugin and leaves files alone. `plugin uninstall` unregisters a plugin and also removes Herdr-managed GitHub checkout files. For GitHub installs, uninstall accepts either the plugin id or the same `owner/repo[/subdir...]` shorthand used by install. Actions, event hooks, panes, and link handlers are declared in the manifest; runtime action registration is not part of v1.
+`plugin link` accepts a plugin directory containing `herdr-plugin.toml` or a direct manifest path. Use it while authoring or testing a plugin from a local checkout. `plugin unlink` unregisters the plugin and leaves files alone. `plugin uninstall` unregisters a plugin and also removes Herdr-managed GitHub checkout files. For GitHub installs, uninstall accepts either the plugin id or the same `owner/repo[/subdir...]` shorthand used by install. Actions, event hooks, panes, and link handlers are declared in the manifest; runtime action registration is not part of v1.
 
 Config directory:
 
@@ -426,7 +426,7 @@ Config directory:
 herdr plugin config-dir <plugin_id>
 ```
 
-`plugin config-dir` prints the plugin's config directory, creating it (and seeding it from legacy plugin config locations when present) if needed. Use it in setup docs and shell scripts to point users at a stable path for `.env` files and other user-editable config, separate from the managed plugin checkout.
+`plugin config-dir` prints the plugin's config directory. It creates the directory if needed and seeds it from legacy plugin config locations when present. Use it in setup docs and shell scripts to point users at a stable path for `.env` files and other user-editable config, separate from the managed plugin checkout.
 
 Actions:
 
@@ -464,7 +464,7 @@ layout. `--width` and `--height` set the outer popup dimensions in terminal
 cells or percentages such as `80%`; omitted dimensions default to half the
 terminal size, and values smaller than the popup minimum are clamped. A popup
 is not a Herdr pane, does not export `HERDR_PANE_ID`, and does not participate
-in pane or agent APIs. Native non-terminal plugin panes are a later surface.
+in pane or agent APIs. Native non-terminal plugin panes are outside plugin v1.
 
 `--env KEY=VALUE` can be repeated on process-launching commands. It applies to the newly launched process only. Herdr-managed variables such as `HERDR_SOCKET_PATH`, `HERDR_BIN_PATH`, `HERDR_ENV`, `HERDR_WORKSPACE_ID`, `HERDR_TAB_ID`, `HERDR_PANE_ID`, `HERDR_PLUGIN_ID`, `HERDR_PLUGIN_ROOT`, `HERDR_PLUGIN_CONFIG_DIR`, `HERDR_PLUGIN_STATE_DIR`, `HERDR_PLUGIN_ENTRYPOINT_ID`, and `HERDR_PLUGIN_CONTEXT_JSON` stay authoritative when they conflict with caller-provided env.
 
diff --git a/docs/next/website/src/content/docs/concepts.mdx b/docs/next/website/src/content/docs/concepts.mdx
index 2ac32cc9..733da1bb 100644
--- a/docs/next/website/src/content/docs/concepts.mdx
+++ b/docs/next/website/src/content/docs/concepts.mdx
@@ -82,4 +82,4 @@ Herdr has terminal mode, prefix mode, and navigate mode.
 
 Terminal mode sends keys to the focused pane. Prefix mode waits for one Herdr action after the prefix key. Navigate mode is the persistent workspace navigation surface.
 
-Press the prefix key, default `ctrl+b`, then an action key such as `c` for a new tab or `w` for workspace navigation. New to the prefix idea? See [Keyboard](/docs/keyboard/).
+Press the prefix key, default `ctrl+b`, then an action key such as `c` for a new tab or `w` for workspace navigation. See [Keyboard](/docs/keyboard/) if the prefix idea is new to you.
diff --git a/docs/next/website/src/content/docs/config-reference.mdx b/docs/next/website/src/content/docs/config-reference.mdx
index 499ee390..8ea9ec79 100644
--- a/docs/next/website/src/content/docs/config-reference.mdx
+++ b/docs/next/website/src/content/docs/config-reference.mdx
@@ -5,7 +5,7 @@ description: Every canonical config.toml key, with types, defaults, and allowed
 
 import ConfigReference from '../../components/ConfigReference.astro';
 
-Every canonical key Herdr reads from `config.toml`, flat and filterable. For guided setup
+Browse every canonical key Herdr reads from `config.toml` in a flat, filterable list. For setup guidance
 and the reasoning behind these options, see [Configuration](/docs/configuration/).
 
 Print the full commented default config at any time:
diff --git a/docs/next/website/src/content/docs/configuration.mdx b/docs/next/website/src/content/docs/configuration.mdx
index 90614c53..5f516c4e 100644
--- a/docs/next/website/src/content/docs/configuration.mdx
+++ b/docs/next/website/src/content/docs/configuration.mdx
@@ -5,7 +5,7 @@ description: Configure Herdr keybindings, themes, sidebar behavior, notification
 
 Herdr works without a config file. Add one when you want custom keys, themes, sidebar layouts, notifications, or advanced behavior.
 
-Looking for any setting or keybinding? Search the [Config reference](/docs/config-reference/) for every key, type, default, and allowed value. This page focuses on setup, common recipes, and configuration structures that need more explanation than a reference row.
+The [Config reference](/docs/config-reference/) lists every setting and keybinding, with types, defaults, and allowed values. This page covers setup, common recipes, and configuration structures that need more explanation than a reference row.
 
 ## Config file
 
@@ -32,7 +32,7 @@ herdr --default-config > ~/.config/herdr/config.toml
 
 If a config value is invalid, Herdr falls back to a safe default and shows a startup warning.
 
-Herdr shows first-run setup when `onboarding` is missing or true. Continuing from onboarding writes `onboarding = false` and opens settings on the integrations tab. Set it when you want to skip that flow after setup.
+Herdr shows first-run setup when `onboarding` is missing or true. Continuing from onboarding writes `onboarding = false` and opens settings on the integrations tab. Set `onboarding = false` to skip that flow after setup.
 
 ```toml
 onboarding = false
@@ -68,7 +68,7 @@ Set how Herdr starts newly created interactive pane shells:
 shell_mode = "auto"
 ```
 
-`shell_mode = "auto"` starts login shells on macOS so login-only PATH setup such as `/usr/libexec/path_helper` and Homebrew shell initialization runs in new panes. On other platforms, it keeps the existing non-login shell behavior. Use `"login"` to force login-shell startup, or `"non_login"` to opt out. Command panes, detached custom command keybindings, and explicit argv launches keep their existing command execution paths.
+`shell_mode = "auto"` starts login shells on macOS so login-only PATH setup such as `/usr/libexec/path_helper` and Homebrew shell initialization runs in new panes. On other platforms, it keeps the existing non-login shell behavior. Use `"login"` to force login-shell startup or `"non_login"` to force non-login startup. Command panes, detached custom command keybindings, and explicit argv launches keep their existing command execution paths.
 
 Set the working directory policy for new panes, tabs, and workspaces:
 
@@ -90,11 +90,11 @@ directory = "~/.herdr/worktrees"
 
 Herdr creates checkouts under `<directory>/<repo>/<branch-slug>`. For sibling-style checkouts, set this to a directory such as `~/Projects/herdr-worktrees`. Relative values are resolved to an absolute path when the app applies the config.
 
-Worktree actions are available from Git workspace rows. `New worktree` creates a checkout, checks out an existing local branch when the entered branch already exists, otherwise creates the branch, opens it as a new Herdr workspace, and groups it under the source workspace. `Open worktree...` lists existing Git worktree checkouts for that repo; choosing an already-open checkout focuses it, and choosing a closed checkout opens it in the same group.
+Worktree actions are available from Git workspace rows. `New worktree` creates a checkout. It checks out an existing local branch when the entered branch exists; otherwise, it creates the branch. It then opens the checkout as a new Herdr workspace and groups it under the source workspace. `Open worktree...` lists existing Git worktree checkouts for that repo. Choosing an already-open checkout focuses it, while choosing a closed checkout opens it in the same group.
 
 Grouped worktrees still behave like normal Herdr workspaces: they can be focused, renamed, closed, and contain their own tabs and panes. The parent row is the original workspace. Closing the parent row closes the whole Herdr group, but it does not delete checkout folders or branches.
 
-Deleting a worktree checkout is explicit. Use `Delete worktree checkout...` on a grouped child workspace to run `git worktree remove`. Herdr first asks Git to remove safely. If Git refuses because the checkout has modified or untracked files, Herdr asks again before running the forced remove. Branches are not deleted.
+To delete a worktree checkout, use `Delete worktree checkout...` on a grouped child workspace. Herdr runs `git worktree remove`, first asking Git to remove safely. If Git refuses because the checkout has modified or untracked files, Herdr asks again before running the forced remove. Branches are not deleted.
 
 ## Remote attach
 
@@ -217,7 +217,7 @@ command = "example.layout.apply"
 description = "apply layout"
 ```
 
-An optional `description` can be provided. When specified, this description is displayed in the keybind help panel (opened with `prefix+?`) in place of the default `'custom command'` label.
+`description` is optional. When set, it appears in the keybind help panel (opened with `prefix+?`) instead of the default `'custom command'` label.
 
 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.
 
@@ -407,7 +407,7 @@ herdr pane report-metadata <pane_id> \
   --token summary="reviewing authentication"
 ```
 
-Use `herdr workspace report-metadata` in the same way for custom Space tokens. Unreported custom tokens simply disappear.
+Use `herdr workspace report-metadata` in the same way for custom Space tokens. Unreported custom tokens disappear.
 
 Metadata reporters provide values only; styling stays in the local sidebar configuration. See [CLI reference: report metadata](/docs/cli-reference/#panes) for limits, clearing, sequencing, and expiry.
 
@@ -426,13 +426,13 @@ delay_seconds = 1
 position = "bottom-right"
 ```
 
-Choose `herdr` for an in-app toast, `terminal` for an outer-terminal notification that works well over SSH, `system` for the local OS notification service, or `off` to disable popups. Herdr suppresses popups for the active tab. Search `ui.toast` in the [Config reference](/docs/config-reference/) for positions, delay behavior, and clipboard feedback settings.
+Choose `herdr` for an in-app toast, `terminal` for an outer-terminal notification that also works over SSH, `system` for the local OS notification service, or `off` to disable popups. Herdr suppresses popups for the active tab. Search `ui.toast` in the [Config reference](/docs/config-reference/) for positions, delay behavior, and clipboard feedback settings.
 
 On macOS, `system` tries `terminal-notifier` first and falls back to `/usr/bin/osascript` when it is unavailable or fails. The fallback appears as Script Editor in Notification Center and cannot activate the hosting terminal. Install `terminal-notifier` with `brew install terminal-notifier`. For a supported, detected terminal, it can activate the terminal app when you click the notification. Alternatively, choose `terminal` to let a supported outer terminal own the notification.
 
 ## Sound
 
-Sound notifications play through the local Herdr client. Custom sounds must be mp3 files; relative paths are resolved from the config file's directory.
+Sound notifications play through the local Herdr client. Custom sounds must be mp3 files; Herdr resolves relative paths from the config file's directory.
 
 ```toml
 [ui.sound]
diff --git a/docs/next/website/src/content/docs/how-to-work.mdx b/docs/next/website/src/content/docs/how-to-work.mdx
index 812aae9f..8d3ad081 100644
--- a/docs/next/website/src/content/docs/how-to-work.mdx
+++ b/docs/next/website/src/content/docs/how-to-work.mdx
@@ -42,11 +42,11 @@ herdr
 
 This works like a terminal multiplexer. Your shell is remote. The Herdr server is remote. The agents and panes run on the remote machine. Detach with `ctrl+b q`, disconnect, then SSH back and run `herdr` again.
 
-Use this path when you already live inside an SSH shell, when you are on a phone or tablet SSH client, or when you want the simplest possible setup.
+Use this path when you already live inside an SSH shell, when you are on a phone or tablet SSH client, or when you want the simplest setup.
 
 ## Work from your phone
 
-You do not need a Herdr mobile app or a web dashboard. Install any SSH client on your phone, connect to the machine where your agents run, and start Herdr there:
+Herdr works on your phone without a mobile app or web dashboard. Install any SSH client, connect to the machine where your agents run, and start Herdr there:
 
 ```bash
 ssh you@server
diff --git a/docs/next/website/src/content/docs/index.mdx b/docs/next/website/src/content/docs/index.mdx
index 1502462d..429018f7 100644
--- a/docs/next/website/src/content/docs/index.mdx
+++ b/docs/next/website/src/content/docs/index.mdx
@@ -33,13 +33,13 @@ import { Card, CardGrid } from '@astrojs/starlight/components';
 
 ## Or let your agent introduce you
 
-Already running an AI coding agent? Let it do the onboarding. Paste this prompt:
+If you already run an AI coding agent, let it handle the onboarding. Paste this prompt:
 
 ```text
 Help me understand and set up Herdr. Read https://herdr.dev/agent-guide.md first, then walk me through it step by step.
 ```
 
-The guide teaches your agent Herdr's concepts, setup, configuration, and common fixes, so its answers stay accurate instead of improvised.
+The guide covers Herdr's concepts, setup, configuration, and common fixes, so your agent can answer from the docs instead of improvising.
 
 ## Core guides
 
diff --git a/docs/next/website/src/content/docs/install.mdx b/docs/next/website/src/content/docs/install.mdx
index 54e5a694..e5a786c3 100644
--- a/docs/next/website/src/content/docs/install.mdx
+++ b/docs/next/website/src/content/docs/install.mdx
@@ -19,7 +19,7 @@ On Windows preview beta, install the preview channel:
 powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"
 ```
 
-The installer downloads the right release binary for your platform and places it on your PATH. Herdr defaults to preview on Windows without changing your config. The installer uses versioned install folders and updates a `current` junction, so updates do not need to overwrite a running `herdr.exe`.
+The installer downloads the release binary for your platform and installs it in a directory on your PATH. Herdr defaults to preview on Windows without changing your config. The installer uses versioned install folders and updates a `current` junction, so updates do not need to overwrite a running `herdr.exe`.
 
 ## Install with Homebrew
 
@@ -57,7 +57,7 @@ The flake also exposes a development shell:
 nix develop github:herdrdev/herdr
 ```
 
-Update through the same Nix workflow you used to install Herdr. For a profile install, list your profile entries and upgrade the Herdr entry:
+Use the same Nix workflow to update Herdr. For a profile install, list your profile entries and upgrade the Herdr entry:
 
 ```bash
 nix profile list
@@ -118,7 +118,7 @@ Herdr checks for new releases and notifies you in the app. You can update manual
 herdr update
 ```
 
-`herdr update` is for installs managed by Herdr's own installer. Homebrew, mise, and Nix installs are updated through those package managers instead.
+Use `herdr update` only for installs managed by Herdr's own installer. Update Homebrew, mise, and Nix installs through those package managers instead.
 
 On Linux and macOS, Herdr uses the stable update channel by default. To opt into preview builds from `master`, set the channel:
 
@@ -132,13 +132,13 @@ Switch Linux and macOS direct installs back to stable the same way:
 herdr channel set stable
 ```
 
-For direct installs, changing channels also checks that channel and installs its latest binary. If that update fails, run `herdr update` to retry from the configured channel.
+For direct installs, changing channels checks the selected channel and installs its latest binary. If that update fails, run `herdr update` to retry from the configured channel.
 
 Preview builds are manually published GitHub prereleases from the current development branch. They are useful when you want fixes before the next stable release, but they can regress. Homebrew, mise, and Nix installs do not use the preview channel.
 
 Windows beta builds are preview-only for now. `herdr channel set stable` is rejected on Windows until stable Windows releases are available.
 
-By default, `herdr update` installs the new binary and leaves compatible running sessions alone. If an update changes Herdr's client/server protocol, Herdr asks whether to stop the old server after installing. Stop the old server to use the new version. Stopping exits pane processes. For the default session, run `herdr server stop`, then run `herdr` again. For a named session, run `herdr session stop <name>`, then run `herdr session attach <name>` again.
+By default, `herdr update` installs the new binary and leaves compatible running sessions alone. If an update changes Herdr's client/server protocol, Herdr asks whether to stop the old server after installing. Stop the old server to use the new version. Stopping the server exits its pane processes. For the default session, run `herdr server stop`, then run `herdr` again. For a named session, run `herdr session stop <name>`, then run `herdr session attach <name>` again.
 
 To opt into experimental live server handoff for supported running sessions, run:
 
diff --git a/docs/next/website/src/content/docs/integrations.mdx b/docs/next/website/src/content/docs/integrations.mdx
index 2cdc0d62..67ea8c3e 100644
--- a/docs/next/website/src/content/docs/integrations.mdx
+++ b/docs/next/website/src/content/docs/integrations.mdx
@@ -3,9 +3,7 @@ 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, Cursor Agent CLI, MastraCode, Antigravity CLI, and Grok CLI.
 ---
 
-Herdr detects supported agents automatically. Official integrations can add native session identity for restore, lifecycle state reports, or both.
-
-Use integrations when you want native agent session restore, direct lifecycle reports, or both. See [Agents](/docs/agents/) for the full status authority model.
+Herdr detects supported agents automatically. Install official integrations when you want native agent session restore, direct lifecycle reports, or both. See [Agents](/docs/agents/) for the full status authority model.
 
 ## Install integrations
 
@@ -53,14 +51,14 @@ herdr integration uninstall grok
 
 ## How Herdr uses integrations
 
-Herdr uses integrations in two different ways:
+Herdr uses integrations in two ways:
 
 | Integration type | Agents | Effect |
 | --- | --- | --- |
 | Lifecycle authority | Pi, OMP, Kimi Code CLI, OpenCode, Kilo Code CLI, 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, Hermes Agent, Antigravity CLI, Grok CLI | The integration reports native session references for restore. State still comes from Herdr's screen manifest detection. |
 
-Custom integrations can also report state when they define state that is not visible in the native terminal UI. They do not need to be built into Herdr or use a recognized agent executable.
+Custom integrations can also report state that is not visible in the native terminal UI. They do not need to be built into Herdr or use a recognized agent executable.
 
 ## Integrate your own agent
 
@@ -81,9 +79,9 @@ Report `idle` when the agent is ready for input and `blocked` when it needs a us
   --agent my-agent
 ```
 
-Only report when `HERDR_ENV=1` and the required variables are present so the integration remains a no-op outside Herdr. Keep `--source` stable and unique to the integration. If reports can arrive out of order, include a strictly increasing `--seq`; Herdr ignores stale sequence numbers from the same source.
+Report only when `HERDR_ENV=1` and the required variables are present. This keeps the integration a no-op outside Herdr. Keep `--source` stable and unique to the integration. If reports can arrive out of order, include a strictly increasing `--seq`; Herdr ignores stale sequence numbers from the same source.
 
-You can include `--agent-session-id` or `--agent-session-path` with `report-agent`, or use `pane report-agent-session` when session identity changes independently of state. Herdr exposes that reference through its pane and agent APIs. Automatic session restore additionally requires Herdr to know how to launch that agent and resume the referenced session.
+You can include `--agent-session-id` or `--agent-session-path` with `report-agent`, or use `pane report-agent-session` when session identity changes independently of state. Herdr exposes that reference through its pane and agent APIs. Automatic session restore also requires Herdr to know how to launch that agent and resume the referenced session.
 
 Use `HERDR_BIN_PATH` and the CLI wrappers for portable integrations. Code that needs direct IPC can send the equivalent `pane.report_agent`, `pane.report_agent_session`, and `pane.release_agent` requests described in the [Socket API](/docs/socket-api/#agent-state-reporting).
 
@@ -297,7 +295,7 @@ herdr integration install antigravity-cli
 
 Herdr uses `~/.gemini/config/` by default, or `ANTIGRAVITY_CLI_CONFIG_DIR` when set. This is the directory Antigravity CLI reads global customizations from, and it must already exist. Install writes `hooks/herdr-agent-state.sh` (or `herdr-agent-state.ps1` on Windows) and adds a Herdr-owned `herdr` block to `hooks.json`. Antigravity CLI keys `hooks.json` by hook name, so install rewrites only that block and leaves other named hooks untouched. Uninstall removes the `herdr` block and deletes the hook script.
 
-This integration is session-only. It reports the conversation the pane is running and does not report agent state, so Herdr keeps deriving working, idle, and blocked from what Antigravity CLI draws on screen.
+This session-only integration reports the pane's current conversation, but not agent state. Herdr keeps deriving working, idle, and blocked from what Antigravity CLI draws on screen.
 
 The hook runs on `PreInvocation`, so Herdr learns the conversation once the first prompt is sent. From then on Herdr can resume the pane with `agy --conversation <id>` after a Herdr server restart.
 
diff --git a/docs/next/website/src/content/docs/keyboard.mdx b/docs/next/website/src/content/docs/keyboard.mdx
index d159b2c8..84f78013 100644
--- a/docs/next/website/src/content/docs/keyboard.mdx
+++ b/docs/next/website/src/content/docs/keyboard.mdx
@@ -7,13 +7,13 @@ description: What the prefix is, which bindings to learn first, and how to go pr
 You already know this model. Jump to the [keybinding reference](/docs/configuration/#keybindings) for the full default keymap and config syntax.
 :::
 
-Herdr is mouse-native. You can click panes, tabs, workspaces, and agents, drag split borders, and use right-click menus without learning a single keybinding. Keyboard control is an optional layer, not a requirement.
+Herdr is mouse-native. You can click panes, tabs, workspaces, and agents, drag split borders, and use right-click menus without learning a single keybinding. Keyboard control is optional.
 
 ## What the prefix is
 
 A terminal multiplexer sits between your terminal and the programs running inside it. Those programs already use most key combinations: `ctrl+c` interrupts, `ctrl+r` searches history, editors claim nearly everything else. If Herdr grabbed common keys directly, it would break the programs inside it.
 
-The prefix solves this. Press the prefix key, default `ctrl+b`, and the next keypress goes to Herdr instead of your terminal. `prefix+c` means: press `ctrl+b`, release, then press `c`. One reserved key instead of dozens.
+The prefix solves this. Press the prefix key, default `ctrl+b`, and the next keypress goes to Herdr instead of your terminal. `prefix+c` means: press `ctrl+b`, release, then press `c`. Herdr reserves one key instead of dozens.
 
 Press `prefix+?` at any time to see every active binding. Press `/` in the keybind help to filter actions and shortcuts; use Backspace to edit the filter or `ctrl+u` to clear it.
 
@@ -81,7 +81,7 @@ You can bind Herdr actions to direct chords that need no prefix at all. The hard
 
 Any chord works as a binding: `ctrl+j`, `alt+k`, whatever fits your hands. But a chord has to survive three layers before Herdr sees it: your operating system, your outer terminal (Ghostty, iTerm2, and others ship their own defaults), and the programs running inside the pane. `ctrl+j` reaches Herdr fine, but shells and editors treat it as enter. `alt+k` is free on Linux, but macOS composes it into a special character in most terminals. If you pick chords from these families, double-check them against your own terminal and OS shortcuts.
 
-We mapped the default keybindings of Ghostty, iTerm2, Terminal.app, kitty, WezTerm, Alacritty, Warp, Windows Terminal, GNOME Terminal, and Konsole, plus the global shortcuts of GNOME and KDE. One modifier family is almost untouched everywhere: `ctrl+alt`. Terminals leave it free, it is not affected by the macOS option-key composing behavior that blocks plain `alt` chords, and it transmits even in terminals without a modern keyboard protocol. It is the safe default recommendation; the choice stays yours.
+We mapped the default keybindings of Ghostty, iTerm2, Terminal.app, kitty, WezTerm, Alacritty, Warp, Windows Terminal, GNOME Terminal, and Konsole, plus the global shortcuts of GNOME and KDE. One modifier family is almost untouched everywhere: `ctrl+alt`. Terminals leave it free, it is not affected by the macOS option-key composing behavior that blocks plain `alt` chords, and it transmits even in terminals without a modern keyboard protocol. It is a safe default, but the choice is yours.
 
 This setup keeps the prefix bindings working and adds direct chords on top:
 
diff --git a/docs/next/website/src/content/docs/marketplace.mdx b/docs/next/website/src/content/docs/marketplace.mdx
index 88bbaf98..4c12bdbe 100644
--- a/docs/next/website/src/content/docs/marketplace.mdx
+++ b/docs/next/website/src/content/docs/marketplace.mdx
@@ -3,9 +3,9 @@ title: Marketplace
 description: Discover community Herdr plugins on GitHub, and get your own plugin listed.
 ---
 
-The Herdr plugin marketplace is a discoverable index of community plugins.
-Browse it at [herdr.dev/plugins](/plugins/). It is an automatic index of public
-GitHub repositories, not a reviewed catalog.
+The Herdr plugin marketplace indexes community plugins. Browse it at
+[herdr.dev/plugins](/plugins/). The index covers public GitHub repositories; it
+is not a reviewed catalog.
 
 ## Browse plugins
 
@@ -23,15 +23,15 @@ anything.
 
 ## Install a plugin
 
-The marketplace adds discovery on top of installation; it does not replace it.
-Install any plugin straight from GitHub:
+The marketplace helps you discover plugins. Install any plugin straight from
+GitHub:
 
 ```bash
 herdr plugin install owner/repo[/subdir...]
 ```
 
-Publish a normal public GitHub repository with a `herdr-plugin.toml` manifest at
-its root, or in a subdirectory, and that command works. See
+The command works with a public GitHub repository that has a
+`herdr-plugin.toml` manifest at its root or in a subdirectory. See
 [Plugins](/docs/plugins/) for the manifest and authoring reference.
 
 ## Get your plugin listed
diff --git a/docs/next/website/src/content/docs/persistence-remote.mdx b/docs/next/website/src/content/docs/persistence-remote.mdx
index befbfb25..1847a0a5 100644
--- a/docs/next/website/src/content/docs/persistence-remote.mdx
+++ b/docs/next/website/src/content/docs/persistence-remote.mdx
@@ -37,14 +37,14 @@ herdr session delete side-project --json
 
 ## Remote attach over SSH
 
-There are two remote modes; [How to work with Herdr](/docs/how-to-work/) compares them. SSH to the server and run `herdr` there for the tmux-style path. Or attach through SSH from your local machine:
+Herdr supports two remote modes. [How to work with Herdr](/docs/how-to-work/) compares them. SSH to the server and run `herdr` there for the tmux-style path, or attach through SSH from your local machine:
 
 ```bash
 herdr --remote workbox
 herdr --remote ssh://you@server:2222
 ```
 
-In this mode your local Herdr is a thin client. It connects over SSH, starts or attaches to the remote Herdr server, and streams the UI back to your local terminal. Because the client runs locally, Herdr can bridge local desktop features such as image clipboard paste into the remote session by copying the image to a remote temp file and pasting that path.
+In this mode, your local Herdr is a thin client. It connects over SSH, starts or attaches to the remote Herdr server, and streams the UI back to your local terminal. Because the client runs locally, Herdr can bridge local desktop features such as image clipboard paste into the remote session by copying the image to a remote temp file and pasting that path.
 
 By default, `herdr --remote` uses your local Herdr keybindings for that attach. This keeps local muscle memory even when the remote server has different config. The local keybindings are a snapshot from attach time; detach and reattach after editing local keybindings. Use `--remote-keybindings server` when you want the remote server config instead. Local custom command keybindings are not sent, because those commands would run on the remote host.
 
@@ -82,7 +82,7 @@ By default, remote attach uses the normal restart/stop flow if it needs to repla
 herdr --remote workbox --handoff
 ```
 
-If you SSH into the server first and run `herdr` there, Herdr runs entirely on the server. That mode is useful and simple, but it cannot access your local desktop clipboard beyond normal terminal text paste.
+If you SSH into the server first and run `herdr` there, Herdr runs entirely on the server and cannot access your local desktop clipboard beyond normal terminal text paste.
 
 When your local and remote platforms match, Herdr can copy the current local binary for direct installs. For Homebrew, mise, and Nix installs, or when the platforms differ, it downloads the matching release asset for the current client version from `https://herdr.dev/latest.json`.
 
@@ -160,4 +160,4 @@ Use `--no-session` to run Herdr without the background server/client split:
 herdr --no-session
 ```
 
-This is mainly an escape hatch for debugging or compatibility. The default persistent session mode is the normal path.
+Use `--no-session` mainly for debugging or compatibility. Persistent session mode remains the default.
diff --git a/docs/next/website/src/content/docs/plugins.mdx b/docs/next/website/src/content/docs/plugins.mdx
index 418d5af6..4085e242 100644
--- a/docs/next/website/src/content/docs/plugins.mdx
+++ b/docs/next/website/src/content/docs/plugins.mdx
@@ -15,19 +15,18 @@ workspaces, panes, agents, and a stable CLI/socket API. Plugins turn that
 existing extension surface into reusable workflows that people can build,
 install, and share without adding every workflow to Herdr itself.
 
-A plugin is not an SDK integration. It is a directory with a
-`herdr-plugin.toml` manifest and commands Herdr can launch. Herdr validates the
-manifest, injects runtime context, starts the declared commands, and records
-logs. The commands call back into Herdr through the CLI or socket when they need
-to do more work.
+A plugin is a directory with a `herdr-plugin.toml` manifest and commands Herdr
+can launch. Herdr validates the manifest, injects runtime context, starts the
+declared commands, and records logs. The commands call back into Herdr through
+the CLI or socket when they need to do more work.
 
 There is no separate plugin SDK or restricted command set. The entire Herdr CLI
-is the plugin API: every command in the [CLI reference](/docs/cli-reference/) is
-available to a plugin, and anything you can run as `herdr ...` yourself a plugin
-can run too. Most plugins should call Herdr through `HERDR_BIN_PATH`, which
-points at the running Herdr binary. That keeps plugins portable across Unix
-sockets and Windows named pipes. Use the [socket API](/docs/socket-api/) when
-you want to send raw JSON requests yourself.
+is the plugin API. Every command in the
+[CLI reference](/docs/cli-reference/) is available to a plugin, and a plugin can
+run anything you can run yourself as `herdr ...`. Most plugins should call Herdr
+through `HERDR_BIN_PATH`, which points at the running Herdr binary. That keeps
+plugins portable across Unix sockets and Windows named pipes. Use the
+[socket API](/docs/socket-api/) when you want to send raw JSON requests yourself.
 
 Runtime action registration and native non-terminal plugin UI are not part of
 plugin v1. Actions, event hooks, panes, and link handlers are all declared in
@@ -35,22 +34,22 @@ the manifest.
 
 ## Trust and security
 
-A plugin is ordinary code that runs on your machine. When you install or link
-one, its build and runtime commands run as your user, with your environment, and
-can call the full Herdr CLI — the same as any extension you add to an editor,
-shell, or coding agent. That openness is the point, and a little judgment keeps
-it safe.
+A plugin is ordinary code that runs on your machine. Its build and runtime
+commands run as your user, inherit your environment, and can call the full Herdr
+CLI. Treat a plugin like any extension you add to an editor, shell, or coding
+agent.
 
-Install plugins from authors and repositories you trust, and skim what a new one
-does first: the `herdr-plugin.toml` manifest and the scripts or binaries it runs.
-`herdr plugin install` shows a preview of the source and the commands it will run
-in interactive terminals, so you can review before confirming. Use `--yes` for
+Install or link plugins only from authors and repositories you trust. Before
+installing or linking one, skim the `herdr-plugin.toml` manifest and the scripts
+or binaries it runs. `herdr plugin install` shows a preview of the source and
+the commands it will run in interactive terminals, so you can review before
+confirming. Use `--yes` for
 sources you already trust, and pin `--ref` when you want a specific revision.
 
 Herdr validates the manifest and keeps each plugin's config and state in its own
-directory, but it does not review or sandbox what a plugin does. Third-party
-plugins come from their authors, not from Herdr, so they are yours to vet and run
-at your own discretion.
+directory, but it does not review or sandbox plugin code. Third-party plugins
+come from their authors, not Herdr; you are responsible for deciding whether to
+run them.
 
 ## Manifest
 
@@ -213,8 +212,8 @@ reinstall from GitHub to refresh a managed plugin.
 
 The example cookbook repo is `ogulcancelik/herdr-plugin-examples`. It contains
 separate example plugins in subdirectories, including `agent-telegram-notify`,
-`github-link-preview`, and `dev-layout-bootstrap`. These are examples to copy,
-not maintained official plugins.
+`github-link-preview`, and `dev-layout-bootstrap`. Use them as examples to copy;
+Herdr does not maintain them as official plugins.
 
 ## Build commands
 
@@ -240,9 +239,9 @@ is linked or enabled. Herdr starts them asynchronously and records their
 completion in the normal plugin command log. A startup failure does not stop the
 server.
 
-Startup hooks are one-shot initialization commands, not supervised daemons. A
-hook should restore plugin-owned state, call any required Herdr APIs, and exit.
-For example, a plugin can save a declarative Agent view under
+Startup hooks are one-shot initialization commands rather than supervised
+daemons. A hook should restore plugin-owned state, call any required Herdr APIs,
+and exit. For example, a plugin can save a declarative Agent view under
 `HERDR_PLUGIN_STATE_DIR`, then read and reapply that view from its startup hook.
 
 Startup hooks receive the normal runtime plugin environment and
diff --git a/docs/next/website/src/content/docs/quick-start.mdx b/docs/next/website/src/content/docs/quick-start.mdx
index 86d8bc8e..5ac2d56d 100644
--- a/docs/next/website/src/content/docs/quick-start.mdx
+++ b/docs/next/website/src/content/docs/quick-start.mdx
@@ -13,11 +13,11 @@ Herdr launches or attaches to your default background session. You do not manage
 
 ## Create a workspace
 
-When a session has no workspaces, Herdr opens one automatically. A workspace is a project-level container for tabs, panes, and agents. Give each active project its own workspace; this keeps agent state readable in the sidebar.
+When a session has no workspaces, Herdr opens one automatically. A workspace is a project-level container for tabs, panes, and agents. Give each active project its own workspace to keep agent state readable in the sidebar.
 
 ## Use the mouse
 
-Herdr is mouse-native, so start by clicking. Click panes, tabs, workspaces, and agents to focus them. Drag split borders to resize. Right-click for context menus, including splitting panes and creating tabs. Drag-select text to copy it to your clipboard; double-click a token to copy it directly. Copying does not require Ctrl+C.
+Herdr is mouse-native, so start by clicking panes, tabs, workspaces, and agents to focus them. Drag split borders to resize. Right-click for context menus, including splitting panes and creating tabs. Drag-select text to copy it to your clipboard; double-click a token to copy it directly. Copying does not require Ctrl+C.
 
 Ctrl-click opens pane links when your terminal sends the modified click to Herdr. This works for OSC 8 hyperlinks and visible `http://` or `https://` URLs. On macOS, use Ctrl-click for Herdr-handled pane links while mouse capture is enabled; Cmd-click is only available through the terminal-native bypass path, such as Shift-Cmd-click or `ui.mouse_capture = false`.
 
@@ -31,7 +31,7 @@ Start your coding agent in a pane:
 claude
 ```
 
-Or `codex`, `pi`, `opencode`, or any other [supported agent](/docs/agents/). Herdr detects it automatically. The sidebar shows whether each agent is `working`, `blocked`, `done`, or `idle` — across every workspace, so you always know which project needs you.
+Or `codex`, `pi`, `opencode`, or any other [supported agent](/docs/agents/). Herdr detects it automatically. Across every workspace, the sidebar shows whether each agent is `working`, `blocked`, `done`, or `idle`, so you always know which project needs you.
 
 ## Keyboard control
 
@@ -49,13 +49,13 @@ Common actions:
 | New workspace | `prefix+shift+n` |
 | Detach client | `prefix+q` |
 
-New to the prefix idea? [Keyboard](/docs/keyboard/) explains what it is, why multiplexers use one, and how to go prefix-free. Press `prefix+?` inside Herdr to see every active binding, and `prefix+[` to copy from the keyboard in copy mode.
+If the prefix idea is new to you, [Keyboard](/docs/keyboard/) explains what it is, why multiplexers use one, and how to go prefix-free. Press `prefix+?` inside Herdr to see every active binding, and `prefix+[` to copy from the keyboard in copy mode.
 
 ## Detach and come back
 
 Press `prefix+q` or simply close your terminal window. The Herdr server and every agent keep running. Run `herdr` again to reattach to the same session.
 
-To actually end the session and stop its panes:
+To end the session and stop its panes:
 
 ```bash
 herdr server stop
diff --git a/docs/next/website/src/content/docs/session-state.mdx b/docs/next/website/src/content/docs/session-state.mdx
index 468557b4..548cf120 100644
--- a/docs/next/website/src/content/docs/session-state.mdx
+++ b/docs/next/website/src/content/docs/session-state.mdx
@@ -3,7 +3,7 @@ title: Session state and restore
 description: Understand what Herdr keeps live, restores after restart, replays from history, resumes through agent integrations, and hands off during updates.
 ---
 
-Herdr has several state paths. They solve different problems.
+Herdr uses several state paths for different situations.
 
 ## What survives
 
@@ -14,8 +14,6 @@ Herdr has several state paths. They solve different problems.
 | Update without `--handoff` | Compatible servers keep running; restart-required servers may need stop/restart | Yes after restart | Only with pane screen history | Only with native agent session restore |
 | Update with `--handoff` | Best effort for supported running servers | Yes | Yes, from the live terminal if handoff succeeds | Yes, because the process keeps running if handoff succeeds |
 
-The sections below explain each path.
-
 ## Live persistence
 
 Normal detach keeps the Herdr server running. Panes, shells, agents, servers, tests, and command processes keep running inside that server.
@@ -36,9 +34,9 @@ Snapshot restore does not preserve running shells, servers, tests, or arbitrary
 
 ## Pane screen history replay
 
-Pane screen history restores recent terminal contents after a full server restart. It restores what Herdr can show, not the old process.
+Pane screen history restores recent terminal contents after a full server restart without restoring the old process.
 
-This is off by default because pane output can include secrets, tokens, prompts, and command output. Enable it in the config file:
+Pane screen history is off by default because pane output can include secrets, tokens, prompts, and command output. Enable it in the config file:
 
 ```toml
 [experimental]
@@ -51,7 +49,7 @@ When enabled, Herdr stores saved pane history in `session-history.json` next to
 
 Some agents can resume their own conversation sessions. Herdr can use official integration-reported session references to restart supported agent panes after a Herdr server restart.
 
-This is enabled by default. Disable it with:
+Native agent session restore is enabled by default. Disable it with:
 
 ```toml
 [session]
@@ -93,9 +91,9 @@ If native agent session restore applies to a pane, Herdr resumes the agent sessi
 
 Live handoff is for update and remote attach flows that need to replace a running Herdr server. It asks the old server to transfer live panes to the new server, so pane processes can keep running across the server replacement.
 
-This is different from snapshot restore, pane history replay, and native agent session restore. Handoff tries to keep the current processes alive. The others reconstruct state after the old server has already stopped.
+Unlike snapshot restore, pane history replay, and native agent session restore, handoff tries to keep the current processes alive rather than reconstructing state after the old server stops.
 
-Handoff protects long-lived server-owned session state: pane PTYs and processes, agent identity and durable metadata, and plugin/session state needed by the replacement server. It does not preserve transient coordination across the replacement boundary. In-flight CLI or API requests, waits, subscription streams, client sockets, and pane-to-pane messages may be interrupted; clients should reconnect and retry them.
+A successful handoff preserves long-lived server-owned session state: pane PTYs and processes, agent identity and durable metadata, and plugin/session state needed by the replacement server. It does not preserve transient coordination across the replacement boundary. In-flight CLI or API requests, waits, subscription streams, client sockets, and pane-to-pane messages may be interrupted; clients should reconnect and retry them.
 
 Live handoff is experimental and opt-in:
 
diff --git a/docs/next/website/src/content/docs/socket-api.mdx b/docs/next/website/src/content/docs/socket-api.mdx
index 430cf4bf..6431dcb9 100644
--- a/docs/next/website/src/content/docs/socket-api.mdx
+++ b/docs/next/website/src/content/docs/socket-api.mdx
@@ -480,10 +480,10 @@ A source mismatch leaves the active view unchanged. Set and clear responses use
 
 ## Plugin APIs
 
-The plugin API is an early host surface for executable workflow tools. A plugin
-is a package with a `herdr-plugin.toml` manifest. The manifest declares
-startup hooks, shareable actions, event hooks, terminal pane entrypoints, and
-link handlers. Startup hooks run once after restore when the API is ready.
+The plugin API is an early interface for executable workflow tools. A plugin is
+a package with a `herdr-plugin.toml` manifest. The manifest declares startup
+hooks, shareable actions, event hooks, terminal pane entrypoints, and link
+handlers. Startup hooks run once after restore when the API is ready.
 Actions and panes are manifest-only; runtime action registration and runtime
 argv pane creation are not part of v1.
 
@@ -492,11 +492,14 @@ Installed and linked plugins persist across restarts. Herdr writes a
 `plugin.unlink`, `plugin.enable`, and `plugin.disable`. The
 `herdr plugin install` and `herdr plugin link` CLIs also write the same registry
 when Herdr is not running, then startup loads it automatically. On startup,
-Herdr re-reads each
-manifest from its original path; if the file is missing or unparseable the entry
-is kept with a `warnings` field so `plugin.list` surfaces it.
+Herdr re-reads each manifest from its original path; if the file is missing or
+unparseable, the entry is kept with a `warnings` field so `plugin.list` surfaces
+it.
 
-Event hook `on` values are validated against the known Herdr event names at link time. An unrecognised name is not an error — the link still succeeds — but the returned plugin info includes a warning (e.g. `"unknown event 'worktree.craeted'"`). Check the `warnings` field in the `plugin.link` and `plugin.list` responses.
+Herdr validates event hook `on` values against known event names at link time.
+An unrecognised name does not block the link, but the returned plugin info
+includes a warning (e.g. `"unknown event 'worktree.craeted'"`). Check the
+`warnings` field in the `plugin.link` and `plugin.list` responses.
 
 Link a local plugin manifest:
 
@@ -552,7 +555,7 @@ field is missing, invalid, or newer than the running Herdr binary.
 
 Declare `platforms` at the top level with the OS identifiers (`linux`, `macos`,
 `windows`) your plugin supports. Omitting `platforms` is allowed for local
-development — `plugin.link` succeeds but the response includes a warning.
+development. `plugin.link` succeeds, but the response includes a warning.
 Individual build commands, actions, event hooks, panes, and link handlers can
 declare their own `platforms` to override the plugin-level list; if omitted they
 inherit from the plugin. Invoking an action or opening a pane whose effective
@@ -695,7 +698,8 @@ Integrations report agent state with `pane.report_agent`.
 }
 ```
 
-`state` is semantic. It affects waits, notifications, and rollups. Report display-only values separately through metadata.
+`state` carries semantic agent state and affects waits, notifications, and
+rollups. Report display-only values separately through metadata.
 
 Session-only official integrations report native session references with `pane.report_agent_session`. State-reporting integrations can still include native session references in `pane.report_agent`. State-independent session reports do not affect waits, notifications, or rollups.
 
@@ -917,6 +921,7 @@ Errors look like this:
 
 ## Protocol stability
 
-Herdr has a protocol version for client/server compatibility. Protocol changes are reviewed with release compatibility in mind.
+Herdr has a protocol version for client/server compatibility. Protocol changes
+are reviewed for release compatibility.
 
 Check the server protocol with `ping` or `herdr status` before depending on new behavior. Handle unknown fields gracefully.
diff --git a/docs/next/website/src/content/docs/troubleshooting.mdx b/docs/next/website/src/content/docs/troubleshooting.mdx
index ee094ae5..e908057e 100644
--- a/docs/next/website/src/content/docs/troubleshooting.mdx
+++ b/docs/next/website/src/content/docs/troubleshooting.mdx
@@ -27,9 +27,9 @@ Native mode restores the IME anchor but may reintroduce occasional cursor moveme
 
 ## Enter, Tab, or Backspace fires twice
 
-Older terminal versions can emit the release of Enter, Tab, and Backspace as the same bytes as the press when an application enables Kitty keyboard event reporting. Herdr cannot distinguish those duplicate bytes after the terminal sends them.
+Older versions of some terminals can emit the release of Enter, Tab, and Backspace as the same bytes as the press when an application enables Kitty keyboard event reporting. Herdr cannot distinguish those duplicate bytes after the terminal sends them.
 
-Update the outer terminal to a version containing its upstream fix:
+Update the outer terminal to a version that contains its upstream fix:
 
 | Terminal | Minimum fixed version |
 | --- | --- |
@@ -72,7 +72,7 @@ Stopping a server exits its pane processes. Named sessions use `herdr session st
 
 ## The `herdr` command is not found
 
-Restart the terminal so it reloads its environment, then confirm the Herdr install directory is on `PATH`. Package-manager installs must be updated and exposed through that package manager. See [Install Herdr](/docs/install/#verify).
+Restart the terminal so it reloads its environment, then confirm the Herdr install directory is on `PATH`. For package-manager installs, use that package manager to update Herdr and expose it on `PATH`. See [Install Herdr](/docs/install/#verify).
 
 ## A direct keybinding does nothing
 
diff --git a/docs/next/website/src/content/docs/windows-beta.mdx b/docs/next/website/src/content/docs/windows-beta.mdx
index b21d1efb..54c9441f 100644
--- a/docs/next/website/src/content/docs/windows-beta.mdx
+++ b/docs/next/website/src/content/docs/windows-beta.mdx
@@ -3,11 +3,11 @@ title: Windows beta
 description: Native Windows support status, supported workflows, and known limitations.
 ---
 
-Native Windows support is experimental beta.
+Native Windows support is an experimental beta.
 
-Herdr on Windows uses ConPTY and Windows process/runtime behavior instead of the Unix PTY model Herdr was originally built around. Some Herdr features map cleanly to Windows, and some do not. This preview is not a commitment that every Linux/macOS feature will become fully supported on Windows.
+Herdr on Windows uses ConPTY and Windows process/runtime behavior instead of the Unix PTY model Herdr was built around, so feature support varies. This preview is not a commitment that every Linux/macOS feature will become fully supported on Windows.
 
-The goal of the beta is to learn from real use: install success, pane reliability, agent workflows, bug volume, missing features, and whether Windows users are getting enough value from Herdr. Based on that feedback, Windows support may graduate to stable, stay preview-only while it matures, or be reduced if the maintenance cost is not justified.
+The beta gathers feedback from real use: install success, pane reliability, agent workflows, bug volume, missing features, and whether Windows users get enough value from Herdr. Based on that feedback, Windows support may graduate to stable, stay preview-only while it matures, or be reduced if the maintenance cost is not justified.
 
 Install native Windows beta builds with PowerShell:
 
@@ -41,7 +41,7 @@ For internal beta testing, `HERDR_MANIFEST_URL` can point the installer at a cus
 
 Windows agent process detection scans descendants of the pane shell and recognizes direct agents plus common command wrappers. It is useful for Codex, Claude, and similar agents, but it is not the same as Unix foreground process-group detection.
 
-Plugins support `windows` as a manifest platform in preview. GitHub install, local link, build commands, actions, events, and plugin panes are best effort on Windows. Commands are argv commands and must be Windows-compatible; Node package shims such as `npm`, `bun`, and `node` are expected to work when they are on `PATH`, while Unix-only examples using `sh` or Bash need Windows-specific alternatives. Platform filters skip unsupported build commands and return `platform_unsupported` for unsupported actions or panes.
+Plugins support `windows` as a manifest platform in preview. GitHub install, local link, build commands, actions, events, and plugin panes are best-effort on Windows. Commands are argv commands and must be Windows-compatible; Node package shims such as `npm`, `bun`, and `node` are expected to work when they are on `PATH`, while Unix-only examples using `sh` or Bash need Windows-specific alternatives. Platform filters skip unsupported build commands and return `platform_unsupported` for unsupported actions or panes.
 
 ## Partial support
 
@@ -54,7 +54,7 @@ Plugins support `windows` as a manifest platform in preview. GitHub install, loc
 | Kitty graphics rendering | unverified |
 | Host cursor rendering | partial |
 
-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.
+Herdr can launch panes in the right directory and create the initial workspace from the directory where you started Herdr. After startup, the process field Herdr can inspect does not reliably track later logical `cd` changes in PowerShell. Use Herdr integrations or prompt shell integration for live cwd reporting.
 
 During `herdr --remote`, the configured remote image paste key reads a Windows clipboard image and transfers it to the remote host. Dropping one local image file into Windows Terminal also transfers that file and pastes its remote path. Clipboard image paste into a local native Windows pane remains unverified.
 
@@ -64,18 +64,18 @@ Kitty graphics remains experimental and is not claimed as Windows-supported yet.
 
 ### Cursor rendering
 
-Herdr relies on ConPTY for native Windows panes. The current Windows terminal cursor path can expose intermediate cursor positions while a multiplexer repaints the screen. A native cursor may flicker, jump, or briefly remain at an old position during active output. This behavior also reproduces in other native Windows terminal multiplexers and with direct VT cursor-position stress tests, so Herdr cannot eliminate it while preserving native cursor behavior.
+Herdr relies on ConPTY for native Windows panes. The Windows terminal cursor path can expose intermediate positions while a multiplexer repaints the screen. A native cursor may flicker, jump, or briefly remain at an old position during active output. This behavior also reproduces in other native Windows terminal multiplexers and with direct VT cursor-position stress tests, so Herdr cannot eliminate it while preserving native cursor behavior.
 
 To prioritize visual stability, the default `host_cursor = "auto"` draws Herdr's cursor as terminal cell content on native Windows and WSL. Other Linux and macOS clients continue to use the native terminal cursor. The drawn Windows cursor is steady and non-blinking, but it does not provide the outer terminal's native blink, shape, or cursor color.
 
-A drawn cursor is not the cursor that Windows uses to position IME composition and candidate UI. Korean, Japanese, or Chinese IME UI may therefore appear at the wrong location. If this affects you, opt back into the outer terminal cursor:
+Windows does not use a drawn cursor to position IME composition and candidate UI. Korean, Japanese, or Chinese IME UI may therefore appear at the wrong location. If this affects you, opt back into the outer terminal cursor:
 
 ```toml
 [ui]
 host_cursor = "native"
 ```
 
-Native mode restores the IME anchor, but it can reintroduce occasional cursor flicker, jumps, or stale cursor positions during active output. This is currently a compatibility trade-off in the Windows beta.
+Native mode restores the IME anchor, but it can reintroduce occasional cursor flicker, jumps, or stale cursor positions during active output.
 
 ### Keyboard and mouse
 
-- 
cgit v1.2.3