docs: humanize wording and remove AI-style em dashes

packages/docs/AGENTS.md

@@ -2,6 +2,25 @@
 
 Documentation website built with Docusaurus v3.
 
+## Writing Style
+
+Documentation prose should read as though a person wrote it, not a language
+model. When writing or editing docs:
+
+- Do not use em dashes (`—`). Rewrite the sentence with a comma, colon,
+  semicolon, parentheses, or a full stop, whichever fits. This is the single
+  most common tell; avoid it everywhere, including frontmatter `description`
+  fields, tables, and code comments.
+- Drop filler and marketing words. Avoid "comprehensive", "a wide variety of",
+  "out of the box", "seamlessly", "powerful", "robust", "unlocks", "leverage",
+  "delve into", "first-class", "it's worth noting", "keep in mind". State the
+  concrete thing instead.
+- Prefer short, direct sentences. Cut words that carry no meaning; don't hedge
+  or pad.
+- Keep British spelling (behaviour, colour, localise) to match the existing
+  docs.
+- An en dash in a numeric range (`v5.0–5.2`) is correct and fine to keep.
+
 ## Build Commands
 
 - `build` - Build templates then build Docusaurus site

packages/docs/docs/advanced/accessibility.mdx

@@ -1,15 +1,15 @@
 ---
 title: Accessibility
-description: The ARIA semantics, keyboard support and screen-reader announcements Dockview ships out of the box.
+description: The ARIA semantics, keyboard support and screen-reader announcements Dockview provides by default.
 sidebar_position: 1
 ---
 
 import { DocRef } from '@site/src/components/ui/reference/docRef';
 
-Dockview ships a baseline of accessibility in core — WAI-ARIA roles and labels,
+Dockview ships a baseline of accessibility in core: WAI-ARIA roles and labels,
 roving-tabindex navigation within the tab strip, screen-reader announcements of
-layout changes, and keyboard-only focus indicators — included out of the box in
-the `dockview` package and the framework packages. No configuration is required
+layout changes, and keyboard-only focus indicators. These come with the
+`dockview` package and the framework packages. No configuration is required
 for the semantics below; the options on this page tune the announcements and the
 opt-in keymap.
 
@@ -28,7 +28,7 @@ technology can describe the layout:
 - Close buttons expose an accessible name that includes the panel title (e.g.
   "Close Orders").
 
-These roles are reactive — activating a tab, floating a group or calling
+These roles are reactive: activating a tab, floating a group or calling
 `setTitle` updates the relevant attributes.
 
 ## Keyboard navigation
@@ -38,8 +38,8 @@ stop, and the arrow keys move between tabs once the strip has focus. `Home` /
 `End` jump to the first / last tab, and `Enter` / `Space` activate the focused
 tab. This within-strip navigation is always on.
 
-Broader keyboard operability — switching tabs, cycling groups with `F6`, jumping
-focus to the tab strip, and keyboard-driven docking — is enabled with the
+Broader keyboard operability (switching tabs, cycling groups with `F6`, jumping
+focus to the tab strip, and keyboard-driven docking) is enabled with the
 `keyboardNavigation` option and is documented in full on the
 [Keyboard](/docs/advanced/keyboard) page, including the rebindable keymap.
 
@@ -59,8 +59,8 @@ focused by keyboard.
 
 ## Screen-reader announcements
 
-Dockview narrates layout changes — panels opening/closing, groups floating,
-docking, popping out, maximising/restoring — through visually-hidden ARIA live
+Dockview narrates layout changes (panels opening/closing, groups floating,
+docking, popping out, maximising/restoring) through visually-hidden ARIA live
 regions (a polite region for routine status and an assertive one for
 cancellations). This is on by default.
 
@@ -126,7 +126,7 @@ const options = {
 
 For full translations, provide a `messages` catalog. Each entry is a function
 that builds the string from the relevant context (e.g. the panel title); supply
-any subset — unset entries keep the English defaults:
+any subset; unset entries keep the English defaults:
 
 ```ts
 const options = {
@@ -154,5 +154,5 @@ const options = {
 
 ## See also
 
-- [Focus navigation](/docs/advanced/focus-navigation) — `DockviewApi` methods for moving focus between panels and groups
-- [Keyboard](/docs/advanced/keyboard) — the opt-in keymap, `F6` group cycling and keyboard-driven docking
+- [Focus navigation](/docs/advanced/focus-navigation): `DockviewApi` methods for moving focus between panels and groups
+- [Keyboard](/docs/advanced/keyboard): the opt-in keymap, `F6` group cycling and keyboard-driven docking

packages/docs/docs/advanced/focus-navigation.mdx

@@ -6,7 +6,7 @@ sidebar_position: 2
 
 `DockviewApi` exposes a small set of framework-agnostic methods for moving
 focus between panels and groups programmatically. They work in every framework
-binding — useful for wiring up your own keyboard shortcut handlers. The rebindable keymap and keyboard docking are a separate,
+binding, useful for wiring up your own keyboard shortcut handlers. The rebindable keymap and keyboard docking are a separate,
 enterprise feature covered in [Keyboard Navigation](/docs/advanced/keyboard).
 
 ## Programmatic focus navigation
@@ -24,7 +24,7 @@ api.activatePrevious({ includePanel: true });
 :::info Renamed in v8
 These methods were previously called `moveToNext` / `moveToPrevious`. The old
 names still work as deprecated aliases but will be removed in a future major
-release — the new names make it clear they advance the active panel/group
+release; the new names make it clear they advance the active panel/group
 (focus) rather than relocating a panel.
 :::
 
@@ -65,5 +65,5 @@ const layout = api.groups.map((group) => ({
 
 ## See also
 
-- [Keyboard](/docs/advanced/keyboard) — the rebindable keymap and keyboard-driven docking built on top of these primitives
-- [Accessibility](/docs/advanced/accessibility) — the ARIA semantics and within-strip keyboard navigation Dockview ships by default
+- [Keyboard](/docs/advanced/keyboard): the rebindable keymap and keyboard-driven docking built on top of these primitives
+- [Accessibility](/docs/advanced/accessibility): the ARIA semantics and within-strip keyboard navigation Dockview ships by default

packages/docs/docs/advanced/keyboard.mdx

@@ -9,7 +9,7 @@ sidebar_custom_props:
 
 import { DocRef } from '@site/src/components/ui/reference/docRef';
 
-Dockview can be driven entirely from the keyboard — switching tabs, moving focus
+Dockview can be driven entirely from the keyboard: switching tabs, moving focus
 between groups, and even docking a panel into a new position, all without a
 mouse. This page covers the built-in keymap and keyboard docking. For the
 accessibility semantics that back it (ARIA roles, screen-reader announcements,
@@ -54,7 +54,7 @@ const options = {
 };
 ```
 
-The keymap is rebindable — pass an object with a `keymap` to override individual
+The keymap is rebindable: pass an object with a `keymap` to override individual
 keys. Unset keys keep their defaults:
 
 ```ts
@@ -71,7 +71,7 @@ const options = {
 Each binding is a `+`-separated string, modifiers first. Recognised modifiers
 are `ctrl`, `shift`, `alt`, and `meta` (alias `cmd`); the final part is the
 [`KeyboardEvent.key`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key)
-to match, case-insensitively — e.g. `'ctrl+]'`, `'shift+f6'`, `'ctrl+tab'`.
+to match, case-insensitively, for example `'ctrl+]'`, `'shift+f6'`, `'ctrl+tab'`.
 
 ## Moving between tabs and groups
 
@@ -85,11 +85,11 @@ to match, case-insensitively — e.g. `'ctrl+]'`, `'shift+f6'`, `'ctrl+tab'`.
 | Move focus to the group in a direction          | `Ctrl+Shift+←/→/↑/↓` | `focusGroup{Left,Right,Up,Down}` |
 
 `F6` / `Shift+F6` cycle the groups in list order. `Ctrl+Shift+Arrows` jump to
-the visually adjacent group instead — the same geometry used by the
+the visually adjacent group instead, the same geometry used by the
 [`adjacentGroupInDirection`](/docs/advanced/focus-navigation) API, so mouse and
 keyboard agree on what "the group to the left" is. Once focus lands on the tab
 strip (via `Ctrl+Shift+\` or `F6`),
-the strip's own arrow-key navigation takes over — see
+the strip's own arrow-key navigation takes over. See
 [Accessibility](/docs/advanced/accessibility#keyboard-navigation).
 
 ## Keyboard docking
@@ -98,9 +98,9 @@ Press `Ctrl+M` to dock the active panel somewhere new without dragging. A live
 drop preview follows the current selection, and each step is announced to screen
 readers:
 
-1. **Pick a target group** — arrow keys cycle through the groups (including the
+1. **Pick a target group**: arrow keys cycle through the groups (including the
    panel's own, so you can split a tab out of its group); `Enter` selects one.
-2. **Pick an edge** — arrow keys choose a split edge (left / right / top /
+2. **Pick an edge**: arrow keys choose a split edge (left / right / top /
    bottom), or the centre to tab into the group; `Enter` commits the move.
 
 `Esc` steps back a phase, or cancels the move entirely from the first phase.

packages/docs/docs/api/dockview/groupApi.mdx

@@ -1,12 +1,12 @@
 ---
 title: Group API
 sidebar_position: 3
-description: Reference for the Dockview Group API — methods and events for controlling individual groups.
+description: Reference for the Dockview Group API: methods and events for controlling individual groups.
 ---
 
 import { DocRef } from '@site/src/components/ui/reference/docRef';
 
-The group API controls a single group of panels — its active panel, location, and header.
+The group API controls a single group of panels: its active panel, location, and header.
 
 :::info
 Use the group API sparingly. As you move panels, groups change and if you don't track this correctly you may encounter unexpected
@@ -17,5 +17,5 @@ behaviours. You should be able to achieve most things directly through the panel
 
 ## See also
 
-- [Add a group](/docs/core/groups/add) — how groups are created and populated.
-- [Add a panel](/docs/core/panels/add) — the panels a group contains.
+- [Add a group](/docs/core/groups/add): how groups are created and populated.
+- [Add a panel](/docs/core/panels/add): the panels a group contains.

packages/docs/docs/api/dockview/options.mdx

@@ -1,7 +1,7 @@
 ---
 title: Options
 sidebar_position: 0
-description: Configuration options for the Dockview component — props and initialization settings.
+description: Configuration options for the Dockview component: props and initialization settings.
 ---
 
 import { DocRef } from '@site/src/components/ui/reference/docRef';
@@ -26,5 +26,5 @@ The options available when creating a Dockview component.
 
 ## See also
 
-- [Dockview overview](/docs/core/overview) — where these options fit in the bigger picture.
-- [Panel rendering](/docs/core/panels/rendering) — the rendering behaviour several options control.
+- [Dockview overview](/docs/core/overview): where these options fit in the bigger picture.
+- [Panel rendering](/docs/core/panels/rendering): the rendering behaviour several options control.

packages/docs/docs/api/dockview/overview.mdx

@@ -1,16 +1,16 @@
 ---
 title: API
 sidebar_position: 1
-description: Full reference for the Dockview API — the primary interface for creating and managing panels and groups.
+description: Full reference for the Dockview API: the primary interface for creating and managing panels and groups.
 ---
 
 import { DocRef } from '@site/src/components/ui/reference/docRef';
 
-The `DockviewApi` is the primary interface for controlling a Dockview instance — adding panels and groups, saving and restoring layouts, and subscribing to events.
+The `DockviewApi` is the primary interface for controlling a Dockview instance: adding panels and groups, saving and restoring layouts, and subscribing to events.
 
 <DocRef declaration="DockviewApi" />
 
 ## See also
 
-- [Dockview overview](/docs/core/overview) — the concepts and setup behind Dockview.
-- [Add a panel](/docs/core/panels/add) — how to populate the layout with content.
+- [Dockview overview](/docs/core/overview): the concepts and setup behind Dockview.
+- [Add a panel](/docs/core/panels/add): how to populate the layout with content.

packages/docs/docs/api/dockview/panelApi.mdx

@@ -1,16 +1,16 @@
 ---
 title: Panel API
 sidebar_position: 2
-description: Reference for the Dockview Panel API — methods and events available within individual panels.
+description: Reference for the Dockview Panel API: methods and events available within individual panels.
 ---
 
 import { DocRef } from '@site/src/components/ui/reference/docRef';
 
-The panel API controls a single Dockview panel — sizing, visibility, focus, and parameter updates.
+The panel API controls a single Dockview panel: sizing, visibility, focus, and parameter updates.
 
 <DocRef declaration="DockviewPanelApi" />
 
 ## See also
 
-- [Add a panel](/docs/core/panels/add) — how panels are created and referenced.
-- [Panel rendering](/docs/core/panels/rendering) — how a panel's content is rendered.
+- [Add a panel](/docs/core/panels/add): how panels are created and referenced.
+- [Panel rendering](/docs/core/panels/rendering): how a panel's content is rendered.

packages/docs/docs/api/gridview/api.mdx

@@ -1,15 +1,15 @@
 ---
 title: API
 sidebar_position: 1
-description: Full reference for the Gridview API — methods and events for controlling the grid layout.
+description: Full reference for the Gridview API: methods and events for controlling the grid layout.
 ---
 
 import { DocRef } from '@site/src/components/ui/reference/docRef';
 
-The `GridviewApi` is the primary interface for controlling a Gridview instance — adding and moving panels, saving and restoring layouts, and subscribing to events.
+The `GridviewApi` is the primary interface for controlling a Gridview instance: adding and moving panels, saving and restoring layouts, and subscribing to events.
 
 <DocRef declaration="GridviewApi" />
 
 ## See also
 
-- [Gridview overview](/docs/other/gridview/overview) — concepts and a live example of the grid.
+- [Gridview overview](/docs/other/gridview/overview): concepts and a live example of the grid.

packages/docs/docs/api/gridview/options.mdx

@@ -1,7 +1,7 @@
 ---
 title: Options
 sidebar_position: 0
-description: Configuration options for the Gridview component — props and initialization settings.
+description: Configuration options for the Gridview component: props and initialization settings.
 ---
 
 import { DocRef } from '@site/src/components/ui/reference/docRef';
@@ -26,4 +26,4 @@ The options available when creating a Gridview component.
 
 ## See also
 
-- [Gridview overview](/docs/other/gridview/overview) — concepts and a live example of the grid.
+- [Gridview overview](/docs/other/gridview/overview): concepts and a live example of the grid.

packages/docs/docs/api/gridview/panelApi.mdx

@@ -1,15 +1,15 @@
 ---
 title: Panel API
 sidebar_position: 2
-description: Reference for the Gridview Panel API — methods and events available within individual grid panels.
+description: Reference for the Gridview Panel API: methods and events available within individual grid panels.
 ---
 
 import { DocRef } from '@site/src/components/ui/reference/docRef';
 
-The panel API controls a single Gridview panel — sizing, visibility, focus, and parameter updates.
+The panel API controls a single Gridview panel: sizing, visibility, focus, and parameter updates.
 
 <DocRef declaration="GridviewPanelApi" />
 
 ## See also
 
-- [Gridview overview](/docs/other/gridview/overview) — concepts and a live example of the grid.
+- [Gridview overview](/docs/other/gridview/overview): concepts and a live example of the grid.

packages/docs/docs/api/paneview/api.mdx

@@ -1,15 +1,15 @@
 ---
 title: API
 sidebar_position: 1
-description: Full reference for the Paneview API — methods and events for controlling the pane layout.
+description: Full reference for the Paneview API: methods and events for controlling the pane layout.
 ---
 
 import { DocRef } from '@site/src/components/ui/reference/docRef';
 
-The `PaneviewApi` is the primary interface for controlling a Paneview instance — adding and moving panes, saving and restoring layouts, and subscribing to events.
+The `PaneviewApi` is the primary interface for controlling a Paneview instance: adding and moving panes, saving and restoring layouts, and subscribing to events.
 
 <DocRef declaration="PaneviewApi" />
 
 ## See also
 
-- [Paneview overview](/docs/other/paneview/overview) — concepts and a live example of the pane view.
+- [Paneview overview](/docs/other/paneview/overview): concepts and a live example of the pane view.

packages/docs/docs/api/paneview/options.mdx

@@ -1,7 +1,7 @@
 ---
 title: Options
 sidebar_position: 0
-description: Configuration options for the Paneview component — props and initialization settings.
+description: Configuration options for the Paneview component: props and initialization settings.
 ---
 
 import { DocRef } from '@site/src/components/ui/reference/docRef';
@@ -26,4 +26,4 @@ The options available when creating a Paneview component.
 
 ## See also
 
-- [Paneview overview](/docs/other/paneview/overview) — concepts and a live example of the pane view.
+- [Paneview overview](/docs/other/paneview/overview): concepts and a live example of the pane view.

packages/docs/docs/api/paneview/panelApi.mdx

@@ -1,15 +1,15 @@
 ---
 title: Panel API
 sidebar_position: 2
-description: Reference for the Paneview Panel API — methods and events available within individual pane panels.
+description: Reference for the Paneview Panel API: methods and events available within individual pane panels.
 ---
 
 import { DocRef } from '@site/src/components/ui/reference/docRef';
 
-The panel API controls a single Paneview pane — sizing, visibility, focus, and parameter updates.
+The panel API controls a single Paneview pane: sizing, visibility, focus, and parameter updates.
 
 <DocRef declaration="PaneviewPanelApi" />
 
 ## See also
 
-- [Paneview overview](/docs/other/paneview/overview) — concepts and a live example of the pane view.
+- [Paneview overview](/docs/other/paneview/overview): concepts and a live example of the pane view.

packages/docs/docs/api/splitview/api.mdx

@@ -1,15 +1,15 @@
 ---
 title: API
 sidebar_position: 1
-description: Full reference for the Splitview API — methods and events for controlling the split layout.
+description: Full reference for the Splitview API: methods and events for controlling the split layout.
 ---
 
 import { DocRef } from '@site/src/components/ui/reference/docRef';
 
-The `SplitviewApi` is the primary interface for controlling a Splitview instance — adding and moving views, saving and restoring layouts, and subscribing to events.
+The `SplitviewApi` is the primary interface for controlling a Splitview instance: adding and moving views, saving and restoring layouts, and subscribing to events.
 
 <DocRef declaration="SplitviewApi" />
 
 ## See also
 
-- [Splitview overview](/docs/other/splitview/overview) — concepts and a live example of the split view.
+- [Splitview overview](/docs/other/splitview/overview): concepts and a live example of the split view.

packages/docs/docs/api/splitview/options.mdx

@@ -1,7 +1,7 @@
 ---
 title: Options
 sidebar_position: 0
-description: Configuration options for the Splitview component — props and initialization settings.
+description: Configuration options for the Splitview component: props and initialization settings.
 ---
 
 import { DocRef } from '@site/src/components/ui/reference/docRef';
@@ -26,4 +26,4 @@ The options available when creating a Splitview component.
 
 ## See also
 
-- [Splitview overview](/docs/other/splitview/overview) — concepts and a live example of the split view.
+- [Splitview overview](/docs/other/splitview/overview): concepts and a live example of the split view.