Rewrite documentation and complete shortcut and feature lists

2026-10-02 10:13:53 +01:00
1 parent bbb1eac189
commit 17243464f6
@@ -2,7 +2,7 @@
  <img src="docs/images/ferese-lockup.svg" width="300" alt="Ferese">
 </p>
-<p align="center"><strong>A complete Wayland desktop built around personalization</strong></p>
+<p align="center"><strong>A configurable Wayland desktop</strong></p>
 <p align="center">
  <a href="docs/installation.md">Install</a> ·
@@ -11,7 +11,7 @@
  <a href="docs/README.md">Documentation</a>
 </p>
-Ferese is a window manager and desktop shell built together and configured in one place, for people who want their desktop to be their own.
+Ferese combines a window manager and desktop shell with one configuration.
 ![Ferese Blue desktop with Settings and Control Center](docs/images/screenshots/ferese-main-hero.png)
@@ -19,14 +19,16 @@ Ferese is a window manager and desktop shell built together and configured in on
 ## Features
- Scrolling columns, tree tiling and floating windows, with an overview of all your workspaces
+- Scrolling columns with window grouping, tree tiling and floating windows that remember their size and placement
- Keyboard shortcuts and touchpad gestures you can remap
+- Workspace overview and recent-window switching
- Multiple monitors with fractional scaling
+- Remappable keyboard shortcuts and touchpad gestures
- Themes, wallpapers, blur and corners that update live, with Light/Dark/Auto modes and custom KDL themes
+- Multiple monitors with fractional scaling and automatic refresh-rate switching on low battery
 - Themes, wallpapers and blur that update live, with Light/Dark/Auto modes and custom KDL themes
 - Squircle window corners with matching borders and shadows
 - Desktop widgets, including a clock and sticky notes
- Screenshots with annotation, plus screen sharing and built-in recording
+- Screenshots with annotation, screen sharing and built-in recording
- A built-in lock screen
+- A built-in lock screen and authentication dialogs
- Integrated Settings and Control Center for configuring your desktop
+- Settings and Control Center with Wi-Fi, Bluetooth and audio controls
 ## Install
@@ -45,9 +47,8 @@ guide](docs/installation.md) also walks you through previews, updates and recove
 ## Configure
-Make it yours through **Control Center → Settings** or `~/.config/ferese/config.kdl`,
+Configure Ferese through **Control Center → Settings** or `~/.config/ferese/config.kdl`.
-with changes applying as you make them and the last working configuration staying in
+Changes apply live. Invalid edits leave the last working configuration in place.
 place if an edit is invalid.
 The [configuration reference](docs/configuration.md) and [example
 config](packaging/config.kdl) cover everything from appearance and window layouts to
@@ -78,16 +79,14 @@ Shortcuts** whenever you want to change a shortcut or gesture.
 | Three-finger swipe up / down | Next / previous workspace |
 | Three-finger swipe left / right | Focus the window to the right / left |
-Explore [all shortcuts and mouse actions](docs/shortcuts.md) for more ways to arrange
+See [all shortcuts and mouse actions](docs/shortcuts.md) for window and workspace controls.
 your windows and move between workspaces.
 ## Documentation
-The [documentation index](docs/README.md) brings the desktop guides together, while
+The [documentation index](docs/README.md) lists the desktop guides.
-[development instructions](docs/development.md) cover building, testing and
+[Development instructions](docs/development.md) cover building, testing and contributing.
 contributing.
-Ferese is written in Rust using Smithay, with development happening [on
+Ferese is written in Rust using Smithay. Development happens [on
 GitHub](https://github.com/ferese-wm/ferese). If something goes wrong, [open an
 issue](https://github.com/ferese-wm/ferese/issues) with the steps to reproduce it and
 any relevant logs.
@@ -1,7 +1,7 @@
 # Ferese theme
-The shared native UI theme for the shell, settings, lock screen, authentication
+This crate supplies the shared native UI theme used by the shell, settings, lock
-prompt and screen-sharing/recording chooser.
+screen, authentication prompt and screen-sharing/recording chooser.
 - `Palette` resolves KDL colors and corners and builds the native toolkit theme.
 - `PRESETS` defines twelve variants in six families.
@@ -17,8 +17,8 @@ prompt and screen-sharing/recording chooser.
  Keep the attachment alive with its window and make the client background
  transparent after attachment succeeds. Other compositors retain the client fill.
-Applications supply layout, data, actions, and animation progress. Extend shared
+Each application supplies its layout, data, actions and animation progress.
-components when a style is needed across apps.
+Add styles used by several apps to the shared components.
 ```rust
 let palette = ferese_theme::Palette::from_document(Some(&document));
@@ -28,5 +28,5 @@ let font = ferese_theme::font(Some("Inter"));
 let label = ferese_theme::text("Appearance", font);
 ```
-The compositor owns backdrop blur and material rendering. This crate does not
+Backdrop blur and material rendering happen in the compositor. This crate does
-provide a client-side imitation of those effects.
+not reproduce those effects on the client.
@@ -2,23 +2,21 @@
 ## Get started
- [Installation](installation.md): dependencies, login, previews, updates, and recovery.
+- [Installation](installation.md): install dependencies, log in, preview changes, update and recover a session.
- [Configuration](configuration.md): KDL syntax, layouts, input, shortcuts, and displays.
+- [Configuration](configuration.md): configure layouts, input, shortcuts and displays in KDL.
- [Why Ferese](why-ferese.md): layouts and the shared desktop theme.
+- [Why Ferese](why-ferese.md): window layouts and a shared theme for the desktop.
-
+- [Screenshots](screenshots.md): see the themes, overview and shell controls.
 - [Screenshots](screenshots.md): desktop themes, overview and shell controls.
 ## Use the desktop
- [Shortcuts and gestures](shortcuts.md): keyboard navigation, Super-drag, resize, and window grouping.
+- [Shortcuts and gestures](shortcuts.md): keyboard navigation, moving and resizing with Super-drag, and window grouping.
-
+- [Lock screen](locking.md): change its appearance, set up automatic locking and configure display sleep.
- [Lock screen](locking.md): appearance, automatic locking, and display sleep.
+- [Screen sharing and recording](screen-sharing.md): choose a source and stop sharing.
- [Screen sharing and recording](screen-sharing.md): choosing sources and stopping a session.
+- [Desktop portals](portals.md): services available to applications.
 - [Desktop portals](portals.md): application integration and supported services.
 ## Develop Ferese
- [Development](development.md): builds, tests, and portal checks.
+- [Development](development.md): build Ferese, run tests and check portal contracts.
 - [Nested resize checks](nested-resize-testing.md).
 - [Client soak testing](native-soak-testing.md).
 - [Performance measurements](performance-baseline.md).
@@ -39,21 +39,22 @@ output-profile "docked" {
 }
 ```
-Repeated `binding`, `window-rule`, `output-profile`, `output`, `note` and
+Use repeated `binding`, `window-rule`, `output-profile`, `output`, `note` and
-`autostart` nodes describe lists of settings. Bindings accept positional
+`autostart` nodes for lists of settings. Bindings accept keys, an action and its
-keys/action/argument; profiles, outputs and notes accept a positional name,
+argument positionally. Profiles, outputs and notes accept a positional name,
-match or ID. Other fields can be properties or child nodes. Autostart accepts
+match or ID; other fields can be properties or child nodes. Autostart commands
-its command as positional arguments. Duplicate fields are rejected.
+use positional arguments. Duplicate fields are rejected.
 The dotted paths in the reference tables below describe nested sections.
 Settings preserves comments and custom fields when editing, while normalizing
-indentation. Configuration uses KDL.
+indentation.
 ## Saving and validation
-Settings saves automatically: text on Enter/focus loss, sliders when released.
+Settings saves text when you press Enter or leave the field, and sliders when
-Undo restores the previous save; Reload picks up external edits without merging
+you release them. Undo restores the previous save. Reload reads external edits
-unfinished drafts. Wallpaper browsing needs `zenity`; a path can also be entered.
+without merging unfinished drafts. Wallpaper browsing needs `zenity`, but you
 can also enter a path directly.
 Settings keeps `config.kdl.settings-backup` before saving.
 File edits reload automatically, including atomic editor saves. Invalid changes
@@ -414,11 +415,12 @@ window rules can override that behavior.
 | `width`, `height` | numbers > 0 | Application-chosen floating size |
 | `fullscreen` | boolean | Leave fullscreen state unchanged |
-At least one matcher is required; supplied matchers must all match. Rules apply
+Every rule needs at least one matcher, and supplied matchers must all match.
-in order, with later fields overriding earlier ones. Dimensions imply floating
+Rules apply in order; later fields override earlier ones. Dimensions imply
-when `floating` is omitted. Floating apps without dimensions choose their own
+floating when `floating` is omitted. Floating apps without dimensions choose
-size. Placement first centers transients on the visible part of their parent,
+their own size. Ferese first tries to center transient windows on the visible
-then tries remembered geometry, then the position with least summed overlap.
+part of their parent, then tries saved geometry, then the position with the least
 summed overlap.
 Equal-overlap candidates favor the focused window's center. If the size cannot
 fit, a per-output cascade advances by 32 logical pixels and wraps to the work-area
 origin. Placement respects layer-shell exclusive zones and client minimum sizes;
@@ -426,10 +428,11 @@ an oversized window keeps its size with its top-left corner reachable.
 Successful move/resize completion saves ordinary floating geometry by app ID in
 `$XDG_STATE_HOME/ferese/floating.json` (normally `~/.local/state/ferese/floating.json`).
-The output name and work-area fractions preserve placement across resolution
+Geometry is stored with the output name and as fractions of its work area, so
-changes. Missing outputs and restores with less than 25% visibility are skipped.
+placement survives resolution changes. Restores are skipped if the output is
-Saves run on a worker and pending updates coalesce to the latest snapshot;
+missing or less than 25% of the window would be visible. A worker saves the
-drag completion updates memory immediately without waiting for storage.
+latest snapshot, combining pending updates. Completing a drag updates memory
 immediately without waiting for storage.
 Transient dialogs and cancelled drags do not update this memory. Floating → tiled
 → floating also restores the window's last floating geometry. Nested previews
 keep drag memory in process and do not write the user's saved placements.
@@ -27,9 +27,9 @@ cargo test --locked -p xdg-desktop-portal-ferese
 python3 scripts/tests/test_portal_contracts.py
 ```
-The contract test uses a private bus. It checks signatures, appearance changes,
+The contract test runs on a private bus and checks signatures, appearance changes,
-invalid-config retention, and caller authorization. It does not prove complete
+caller authorization and retention of the last working config after invalid edits.
-compatibility with every app or open consent dialogs.
+It does not open consent dialogs or prove complete compatibility with every app.
 With release binaries built, run isolated integration checks:
@@ -41,9 +41,9 @@ FERESE_TEST_RESTORE=1 python3 scripts/tests/test_restore_isolated.py
 FERESE_TEST_WINDOW_STREAM=1 python3 scripts/tests/test_window_stream_isolated.py
 ```
-These cover shortcut cleanup, window capture, inhibitors, restored permissions,
+These checks use disposable nested sessions or private buses to test shortcut
-and live window streams. Check each script's dependencies before running it.
+cleanup, window capture, inhibitors, restored permissions and live window streams.
-They use disposable nested sessions or private buses.
+Check each script's dependencies before running it.
 For monitor streaming and lock revocation, install Python GI/GStreamer with
 `pipewiresrc`, `dbus-daemon`, `xdg-desktop-portal`, and `bwrap`, then run:
@@ -77,17 +77,17 @@ access tokens, or private window content.
 ## Resume recovery
-The direct backend retains known GPU identities while their DRM resources are
+The direct backend keeps track of known GPUs when their DRM resources are
-unavailable. Hotplug, configuration and lid changes reconcile through one path;
+unavailable. It handles hotplug, configuration and lid changes through the same
-inactive sessions defer that work. Activation reads the lid asynchronously, then
+recovery path, deferring the work while the session is inactive. On activation,
-re-enumerates devices and connectors before allowing presentation. A logind
+it reads the lid state asynchronously and re-enumerates devices and connectors
-system-wake signal follows the same path, including when seat ownership did not
+before allowing presentation. A logind system-wake signal triggers the same work,
-change. Newer libinput observations supersede in-flight lid reads. A failed read
+even if seat ownership has not changed. New libinput observations take precedence
-preserves the last observation; a three-second deadline prevents a stalled bus
+over pending lid reads. If a read fails, Ferese keeps the last observation. Reads
-from blocking recovery indefinitely.
+have a three-second deadline so a stalled bus cannot block recovery indefinitely.
-Device failures retire their output globals and retry with exponential backoff
+When a device fails, Ferese removes its output globals and retries with exponential
-capped at 32 seconds. Working devices remain usable. Known hardware can return
+backoff capped at 32 seconds. Working devices remain usable. Known hardware can return
 under a different `cardN` path. This does not expand support to previously
 unmanaged secondary GPUs. Connected-output reports mark a mode active only when
 output creation succeeded. Lock ownership is retained throughout recovery.
@@ -1,13 +1,13 @@
 # Installation
-Ferese runs on Linux as its own Wayland session, alongside your existing desktop, and
+Ferese runs on Linux as its own Wayland session alongside your existing desktop.
-you can launch it from a login manager, a command-based greeter or a local TTY.
+Launch it from a login manager, a command-based greeter or a local TTY.
 ## Requirements
 For a full session, you’ll need a Wayland-capable graphics driver and a local user
-session with seat access through logind or seatd, while a nested preview runs inside the
+session with seat access through logind or seatd. A nested preview runs inside your
-Wayland desktop you already use.
+existing Wayland desktop.
 To build Ferese, install **Rust 1.95 or newer**, a C/C++ toolchain, CMake, pkg-config
 and the libraries below. The installer builds the Ferese components once those system
@@ -49,10 +49,10 @@ sudo apt install build-essential git curl cmake pkg-config libwayland-dev \
  gstreamer1.0-plugins-good
 ```
-Fedora is the tested installation path, and package names or versions may differ on
+Installation has been tested on Fedora. Package names or versions may differ on
-other distributions, where the [Smithay
+other distributions; check the [Smithay
-dependencies](https://github.com/Smithay/smithay#system-dependencies) can help you find
+dependencies](https://github.com/Smithay/smithay#system-dependencies) for equivalent
-equivalent libraries.
+libraries.
 ### Rust toolchain
@@ -82,17 +82,17 @@ cd ferese
 ./scripts/install.sh
 ```
-The script builds locked release binaries as your normal user and then asks for
+The script builds locked release binaries as your normal user, then asks for
-administrator access through `sudo` or `pkexec` to install them, so leave the build
+administrator access through `sudo` or `pkexec` to install them. Leave the build
 itself unprivileged. The first build needs network access to fetch Rust dependencies.
-Installation brings together the session launcher, desktop tools, portal backend, login
+The installer adds the session launcher, desktop tools, portal backend, login
 entry, icons, default wallpaper and example config. Releases live under
 `/usr/local/lib/ferese/releases/` and commands under `/usr/local/bin/`, with `current`
 and `previous` links for switching between releases during updates and rollback.
-Your configuration, other desktop sessions and existing PAM policy stay in place, while
+The installer preserves your configuration, other desktop sessions and existing PAM
-Ferese starts its authentication agent and portal services together with the session.
+policy. Ferese starts its authentication agent and portal services with the session.
 The authentication agent registers for the login session, so requests from desktop
 apps use the Ferese dialog. Remove other polkit agents from your Ferese autostart
 configuration to avoid competing session registrations.
@@ -110,8 +110,8 @@ if [ ! -e "${XDG_CONFIG_HOME:-$HOME/.config}/ferese/config.kdl" ]; then
 fi
 ```
-After login, open **Control Center → Settings** or run `ferese-settings` to shape your
+After login, open **Control Center → Settings** or run `ferese-settings` to configure
-desktop, using [Configuration](configuration.md) for themes, displays, shortcuts and
+your desktop. See [Configuration](configuration.md) for themes, displays, shortcuts and
 startup apps. The default terminal is `foot`, which you can replace with your preferred
 terminal command in Settings.
@@ -144,8 +144,8 @@ If your greeter asks for a session command instead of reading desktop files, use
 /usr/local/bin/ferese-session
 ```
-For greetd, set this as the session command after authentication using the [greetd
+For greetd, set this as the session command after authentication; see the [greetd
-documentation](https://sr.ht/~kennylevinsen/greetd/), and the launcher will start the
+documentation](https://sr.ht/~kennylevinsen/greetd/). The launcher starts the
 compositor, shell and session services together.
 ### From a TTY
@@ -176,7 +176,7 @@ Install these through your distribution when you want the corresponding features
 | Audio controls | PipeWire, WirePlumber, and `wpctl` |
 | Bluetooth controls | BlueZ, `bluetoothctl`, and its running service |
-Package names and availability vary by distribution, so use Satty’s [upstream
+Package names and availability vary by distribution. Use Satty’s [upstream
 instructions](https://github.com/Satty-org/Satty#install) if it isn’t in your
 repositories. Ferese leaves service setup to you and preserves your existing service
 configuration during installation.
@@ -184,8 +184,8 @@ configuration during installation.
 Use **Print Screen** to capture the active monitor, **Super+Shift+S** to select an area,
 or `ferese-screenshot --all` to capture all monitors in one image.
-The native locker follows your shell theme and can be personalized in **Settings → Lock
+The native locker follows your shell theme. Customize it in **Settings → Lock
-Screen**, with `ferese-lock --preview` opening an ordinary preview window. Before
+Screen**, and run `ferese-lock --preview` to open an ordinary preview window. Before
 enabling automatic locking, test real unlocking and read [Native locker](locking.md) for
 authentication, idle locking and limits.
@@ -230,11 +230,11 @@ git pull --ff-only
 ./scripts/install.sh
 ```
-Log out and back in to start using the new release, as a running session keeps its
+Log out and back in to use the new release. A running session keeps its existing
-existing processes and release paths until it restarts.
+processes and release paths until it restarts.
 Each release records the portal configuration it ships so later upgrades can identify
-it, and installation stops if it encounters modified or untracked administrator files.
+it. Installation stops if it encounters modified or untracked administrator files.
 To replace Ferese portal configuration from an earlier development install, build first
 and run `./scripts/install.sh --skip-build --replace-portal-config`, which backs up the
 existing files in the new release’s `portal-config.previous/` directory.
@@ -268,8 +268,8 @@ process:
 pgrep -a -u "$USER" -x ferese
 ```
-Replace `PID` with the affected session’s process ID and use `kill PID` to end it,
+Replace `PID` with the affected session’s process ID and use `kill PID` to end it.
-bearing in mind that its applications will close and unsaved work may be lost. You can
+Its applications will close and unsaved work may be lost. You can
 then choose another desktop at the next login.
 ### Roll back a release
@@ -312,8 +312,8 @@ configuration; reinstalling Ferese restores the desktop session entry.
 ## Screen sharing and recording
-Ferese’s native ScreenCast portal is included in the installation, which backs up the
+The installer includes Ferese’s native ScreenCast portal and backs up the old user
-old user service override pointing to `~/.local/libexec/ferese` so new sessions use the
+service override pointing to `~/.local/libexec/ferese`, so new sessions use the
-installed release. Custom overrides are preserved and reported before building, and
+installed release. Custom overrides are preserved and reported before building.
-[Screen sharing](screen-sharing.md) covers consent, PipeWire setup, supported sources
+See [Screen sharing](screen-sharing.md) for consent, PipeWire setup, supported sources
 and recording limits.
@@ -15,9 +15,9 @@ ferese-lock --foreground   # stay attached until unlock
 Do not enter your real password in a preview. The account picture comes from
 AccountsService or `~/.face`; a silhouette is used when neither is available.
-Escape clears the password. Caps Lock is shown beside authentication status.
+Press Escape to clear the password. The authentication status also shows whether
-Failed attempts show an error and delay retries. Authentication uses the system's
+Caps Lock is on. A failed attempt displays an error and delays the next retry.
-PAM policy; both password and account validation must succeed.
+Authentication uses the system's PAM policy; both password and account validation must succeed.
 ## Automatic locking
@@ -46,23 +46,23 @@ lock-screen {
 }
 ```
-These delays start after locking, independently of the automatic-lock timer.
+Both delays start when the session locks, separately from the automatic-lock timer.
 Display sleep does not suspend the computer. A nested preview shows black
 instead of powering off the host display.
 ## Recovery and limits
-The lock covers all displays, including newly connected ones. If the lock UI
+The lock covers all displays, including displays connected after locking. If the
-crashes, the compositor keeps the session protected and permits a replacement
+lock UI crashes, the compositor keeps the session protected and allows a replacement
-locker to take over. A running locker cannot be replaced. Launch `ferese-lock`
+locker to take over. A running locker cannot be replaced. To recover, launch
-with the affected session's Wayland environment to recover; ending the session
+`ferese-lock` with the affected session's Wayland environment. You can also end the
-from another TTY remains an option (see [Recovery](installation.md#logout-and-recovery)).
+session from another TTY; see [Recovery](installation.md#logout-and-recovery).
-Readiness is reported only after protocol confirmation: every connected output
+The locker reports readiness only after protocol confirmation. At that point,
-has presented protected content, or there are no outputs. The pinned Iced runtime
+every connected output has presented protected content, or there are no outputs.
-also emits a synthetic `Locked` event when making the request. The locker retains
+The pinned Iced runtime also emits a synthetic `Locked` event when it sends the
-its two-event guard until upstream distinguishes request initiation from protocol
+request. The locker keeps a two-event guard until upstream separates that event
-confirmation; dependency upgrades must re-audit this workaround.
+from protocol confirmation. Dependency upgrades must re-audit this workaround.
 Password messages use zeroizing storage. Avatar files are limited to 8 MiB,
 4096 pixels per dimension, and a 32 MiB decoding budget. The clock updates at
@@ -1,13 +1,12 @@
 # Native-client soak testing
-The soak runner repeatedly creates and destroys native Wayland clients while
+The soak runner repeatedly opens and closes native Wayland clients, testing focus,
-exercising focus, resize, column width, fullscreen, floating, and workspace
+resize, column width, fullscreen, floating windows and workspace changes. Every
-paths. Every tenth iteration also terminates a client abruptly. If a local
+tenth iteration terminates a client abruptly. When a local malformed-client probe
-malformed-client probe is available, it opens three isolated connections that
+is available, it sends malformed Wayland messages through three isolated connections.
-send malformed Wayland messages. The runner requires
+The runner requires Ferese to disconnect each malformed client, then checks that
-Ferese to disconnect each malformed client and then checks that the compositor
+the compositor and authenticated IPC socket still respond. It also records
-and authenticated IPC socket remain responsive. It also records compositor RSS
+compositor RSS growth.
 growth.
 Build `ferese` and `feresectl` and start a disposable
 [nested session](installation.md#preview-and-logs). Select its Wayland socket and
@@ -29,10 +28,10 @@ FERESE_SOAK_SECONDS=300 \
 ./scripts/soak-native.sh
 ```
-Development probes are local-only, not distributed in the Cargo workspace.
+Development probes are local tools and are not distributed in the Cargo workspace.
-Supply an existing executable with `FERESE_MALFORMED_CLIENT` to enable protocol
+Set `FERESE_MALFORMED_CLIENT` to an existing executable to enable protocol checks.
-checks. An explicitly configured missing probe is an error; without a probe,
+If you explicitly configure a probe that does not exist, the runner reports an
-the runner reports that protocol checks are skipped.
+error. Without a probe, it reports that protocol checks are skipped.
 The local probe can also be run independently against a disposable Ferese session:
@@ -9,18 +9,18 @@ WAYLAND_DEBUG=1 FERESE_TRACE_PERFORMANCE=1 \
  target/release/ferese-shell 2>/tmp/ferese-resize.log
 ```
-Use a wallpaper, drag each edge of the host window, and repeatedly maximize and
+Set a wallpaper, then drag each edge of the host window and repeatedly maximize
-restore it. Check that the wallpaper and bar follow without long stalls, including
+and restore it. The wallpaper and bar should resize without long stalls. Check
-at fractional scaling.
+this at fractional scaling too.
 ## Compare renderers
 Repeat with `ICED_BACKEND=wgpu` and `ICED_BACKEND=tiny-skia`. The shell enables
 wgpu; software fallback can be slower when resampling wallpaper.
-Trace the whole sequence: host resize, layer configure, client acknowledgement,
+Follow the trace from host resize through layer configure, client acknowledgement,
-new buffer commit, then compositor rendering. A quick acknowledgement does not
+new buffer commit and compositor rendering. A quick acknowledgement does not mean
-mean the client has finished drawing. `FERESE_TRACE_PERFORMANCE` measures compositor
+the client has finished drawing. `FERESE_TRACE_PERFORMANCE` measures compositor
 work, not shell rasterization.
 ## Historical check
@@ -28,8 +28,8 @@ work, not shell rasterization.
 A KDE Wayland check at 175% scale used debug binaries and protocol tracing.
 Median configure acknowledgement was 1.35 ms with tiny-skia and 2.27 ms with
 wgpu. Wallpaper buffer intervals were 5919 ms with tiny-skia (only two buffers)
-and 9.85 ms median with wgpu. Capture durations differed, so these are diagnostic
+and 9.85 ms median with wgpu. The captures had different durations, so these
-observations rather than throughput benchmarks. GPU intervals also had stalls
+observations do not establish comparative throughput. GPU intervals also had stalls
 up to about 200 ms.
 Repeat on the current build. A nested result does not establish direct-session
@@ -13,13 +13,13 @@ FERESE_TRACE_PERFORMANCE=1 target/release/ferese --backend nested \
  --grant-effects --grant-shell-control -- target/release/ferese-shell
 ```
-Compare idle, several windows, overview, Settings navigation, translucent
+Measure idle, several windows, overview, Settings navigation, translucent popovers
-popovers, and screen capture separately. Allow startup to settle and repeat each
+and screen capture separately. Wait for startup to settle, then repeat each sample.
-sample. Record process CPU, child-process CPU, RSS, render attempts, and damaged
+Record process CPU, child-process CPU, RSS, render attempts and damaged frames.
-frames. Keep build work and unrelated activity outside the sampling interval.
+Do not build or run unrelated workloads during the sample.
-CPU percentages below use one core as 100%. Short samples are observations,
+CPU percentages below use one core as 100%. These short samples describe observed
-not guarantees or hardware-session benchmarks.
+behavior; they are not guarantees or hardware-session benchmarks.
 ## Direct frame timing
@@ -33,11 +33,11 @@ For a direct session, enable `FERESE_TRACE_PERFORMANCE=1` and
 `RUST_LOG=ferese::render=debug` before starting Ferese. The timing records include
 the planned render start, actual render start, timer lateness, presentation
 target, DRM presentation timestamp, and request-to-presentation duration.
-Missed deadlines compare submitted frames with their targets; idle gaps do not
+Missed deadlines are counted against submitted frames' presentation targets;
-count. Request-to-presentation starts at the compositor's redraw request, so it
+idle gaps do not count. Request-to-presentation timing starts at the compositor's
-does not include device input latency, client rendering before the request, or
+redraw request. It does not include device input latency, client rendering before
-the display's pixel response. Render cost measures CPU preparation and queueing;
+the request or the display's pixel response. Render cost measures CPU preparation
-asynchronous GPU work is covered conservatively by feedback-driven margins.
+and queueing. Feedback-driven margins allow conservatively for asynchronous GPU work.
 Check sustained animation, idle wakeup, callback-only clients, and mixed-refresh
 outputs separately. Nested sessions do not exercise the DRM scheduler.
@@ -52,23 +52,22 @@ while a render timer was scheduled or a frame was in flight. Compare these with
 coalesce and are not themselves rendered frames.
 `animation fallback scheduling` reports watchdog arms, cancellations, wakeups,
-recovery requests and observations of animations with an intact normal frame
+recovery requests and animations whose normal frame chain is intact. Ferese emits
-chain. Summaries are emitted during redraw activity every five seconds and on
+summaries every five seconds during redraw activity and on normal exit, resetting
-normal exit. The fallback counters reset with each summary. An orphaned animation
+the fallback counters each time. When an animation loses its output's frame chain,
-gets a watchdog deadline two refresh intervals after its own output loses its
+the watchdog deadline is two refresh intervals later. Recovery keeps a requested
-frame chain. Recovery also retains a requested final frame if another output
+final frame even if another output settles the animation while scheduling is
-settles that animation while scheduling is unavailable. Idle, powered-off and
+unavailable. Idle, powered-off and disconnected outputs do not set that deadline.
-disconnected outputs do not set that deadline.
+The watchdog is suppressed when a render is already scheduled or a page flip is
-An already scheduled render or pending page flip suppresses the watchdog; this
+pending. It does not replace DRM error recovery or diagnose a permanently lost flip.
 policy does not replace DRM error recovery or diagnose a permanently lost flip.
 The regression replays use a 60 Hz animation beside an idle 240 Hz output.
 The old fallback rule produces 60 unnecessary wakes in one simulated second;
 the new rule produces zero while the normal chain remains intact. Three cursor
 moves within one output require three output requests rather than the old six.
-These are deterministic scheduling counts, not live DRM CPU, latency or battery
+These counts come from deterministic scheduling replays. They do not measure live
-measurements. Verify those separately with the same hardware workload before
+DRM CPU use, latency or battery consumption. Measure those separately with the same
-making claims about power savings.
+hardware workload before claiming power savings.
 ## Settled overview damage
@@ -79,8 +78,8 @@ Intel Core Ultra 7 258V and Mesa 26.2.3. Ten-second process samples measured
 removing forced full damage from unchanged rounded thumbnails.
 A settled five-second interval changed from 300 damaged frames to zero.
-The nested backend still makes about 300 no-damage render attempts per interval;
+The nested backend still makes about 300 no-damage render attempts per interval.
-this change avoids unchanged submissions rather than changing nested scheduling.
+The change skips unchanged submissions; it does not alter nested scheduling.
 These short samples exclude host compositor CPU and do not measure battery
 discharge or direct DRM performance.
@@ -115,8 +114,8 @@ cached reading; the existing `wpctl` reader preserves volume and device semantic
 Disconnected subscriptions retain bounded polling, and missing sinks retry.
 Brightness and other status polling remain unchanged.
-These are short nested observations, exclude the host compositor, and do not
+These short nested samples exclude the host compositor and do not measure battery
-measure battery discharge. Raw measurements and profiles were saved locally in
+discharge. Raw measurements and profiles were saved locally in
 `/tmp/ferese-shell-profile-20261002`.
 The subscription regression starts its own PipeWire server, changes default
@@ -1,8 +1,8 @@
 # Desktop portals
-Desktop portals let applications request screen sharing, screenshots, wallpaper
+Applications use desktop portals to request screen sharing, screenshots, wallpaper
-changes, and other desktop services. Ferese provides themed consent dialogs;
+changes and other desktop services. Ferese supplies themed consent dialogs, while
-GTK supplies file, print, and other standard dialogs.
+GTK handles file, print and other standard dialogs.
 Install `xdg-desktop-portal`, `xdg-desktop-portal-gtk`, and Ferese's backend through
 [Installation](installation.md). The session launcher starts the services with
@@ -29,23 +29,24 @@ This does not affect ordinary application clipboard use.
 ## Consent and capture
-Screenshot and screen-sharing requests ask for approval. Screen sharing can
+Screenshot and screen-sharing requests need approval. Display-sharing permissions
-remember display permissions when the application requests it and the user opts
+can be remembered when the application requests it and the user opts in. Window
-in. Window sharing always asks again. See [Screen sharing](screen-sharing.md).
+sharing always asks again. See [Screen sharing](screen-sharing.md).
 Window captures contain the selected app and its subsurfaces; separate popups,
 other apps, shell layers, and compositor decorations are excluded.
-InputCapture starts at an approved display-edge barrier. **Ctrl+Alt+Escape**
+InputCapture starts at an approved barrier at the edge of a display. Press
-returns local control. Locking, disconnecting the receiver, or changing displays
+**Ctrl+Alt+Escape** to regain local control. Capture stops when you lock the session,
-or the keyboard layout stops capture. Touch and remembered InputCapture grants
+disconnect the receiver, change displays or change the keyboard layout. Touch and
-are not supported. InputCapture forwards local input; it does not inject remote input.
+remembered InputCapture grants are not supported. InputCapture forwards local
 input; it does not inject remote input.
 Wallpaper approval copies the image into Ferese's data directory and updates the
 config. Set `theme.background.lock-path` for a separate lock-screen image; otherwise
 it follows the desktop wallpaper.
 Global shortcuts cannot replace Ferese bindings or reserved escape/console keys.
-They stop when the app session closes and never activate on the lock screen.
+They stop when the app session closes. They never activate on the lock screen.
 Power confirmations show app inhibitors before proceeding. Ferese has no
 user-switch operation.
@@ -10,9 +10,9 @@ portal and PipeWire dependencies.
 2. Select a monitor and click **Share**.
 3. Click the stop square to finish.
-Videos are saved as VP8 WebM files in your XDG Videos folder under `Ferese`.
+The recorder saves VP8 WebM files under `Ferese` in your XDG Videos folder, then
-A notification shows the saved path. Audio and region recording are not supported
+shows the path in a notification. The built-in recorder does not support audio or
-by the built-in recorder; other recording apps can handle audio separately.
+region recording; other recording apps can handle audio separately.
 If recording fails, a notification reports the error and any unfinished
 `.webm.part` file.
@@ -23,18 +23,19 @@ choose a display or window and click **Share**. Nothing is selected initially.
 Apps requesting multiple sources can select up to eight.
 A shared display includes everything visible on it, including notifications.
-A shared window includes only that app's content and subsurfaces, even when
+Window sharing captures only the selected app's content and subsurfaces, even if
-covered or on another workspace. Separate popups and compositor decorations are
+the window is covered or on another workspace. It excludes separate popups and
-excluded. Resizing a shared window updates its video size; closing it ends sharing.
+compositor decorations. The video size follows window resizes; closing the window
 ends sharing.
 The picker follows your shell colors, font, corners, opacity, and blur.
 ## Stop sharing
-Click **Stop sharing** in the sharing window, or close that window. The built-in
+Click **Stop sharing** or close the sharing window. For the built-in recorder,
-recorder uses the top-bar stop button instead. Sharing also ends when the app
+use the stop button in the top bar. Sharing also ends when the app closes or
-closes or Ferese locks. Disconnecting a shared monitor or changing its capture
+Ferese locks. If you disconnect a shared monitor or change its capture size,
-size ends its stream; start sharing again afterward.
+its stream ends and you need to start sharing again.
 ## Remember permissions
@@ -55,9 +56,9 @@ see the [package lists](installation.md#requirements).
 The installer supplies Ferese's portal backend and selects it for screen sharing.
 Log into a new Ferese session after installation.
-Streams run at up to 30 fps and support hidden or embedded cursors. Capture copies
+Streams run at up to 30 fps with hidden or embedded cursors. Frames are copied
-frames through CPU-accessible buffers, so large or multiple streams can use
+through CPU-accessible buffers. Large streams or several simultaneous streams
-substantial CPU and memory bandwidth.
+can therefore use substantial CPU and memory bandwidth.
 ## Troubleshooting
@@ -1,6 +1,6 @@
 # Screenshots
-Captured on September 30, 2026. Select an image to view it at full size.
+These screenshots were taken on September 30, 2026. Click an image to open it at full size.
 ## Ferese Blue
@@ -22,7 +22,7 @@ Windows and workspaces over a custom wallpaper.
 ## Power controls
-Power profiles and restart, power off and suspend actions.
+Power controls for selecting a profile, restarting, powering off and suspending.
 [![Power profiles and restart, power off and suspend actions.](images/screenshots/power-controls.png)](images/screenshots/power-controls.png)
@@ -34,7 +34,7 @@ Application previews and workspace selection.
 ## Shortcut guide
-The login guide shows the configured keyboard shortcuts.
+The shortcut guide displayed at login, using the configured keyboard shortcuts.
 [![The login guide shows the configured keyboard shortcuts.](images/screenshots/shortcut-guide.png)](images/screenshots/shortcut-guide.png)
@@ -3,6 +3,8 @@
 `Super` is usually the Windows key. These are the built-in defaults. Open
 **Settings → Shortcuts** to change bindings and gestures or disable the login
 guide. Your saved bindings can override these defaults.
 The [example config](../packaging/config.kdl) adds the app, media and arrow-key
 shortcuts listed below.
 ## Move and resize with the mouse
@@ -25,6 +27,9 @@ to nearby edges; continuing to drag beyond 20 logical pixels releases the snap.
 | Shortcut | Action |
 | --- | --- |
 | Super + H / J / K / L | Focus in that direction |
 | Super + Backspace | Return to the last focused window, including on another workspace or monitor |
 | Alt + Tab | Preview recent windows in focus order |
 | Alt + Shift + Tab | Preview recent windows in reverse focus order |
 | Super + Shift + H / J / K / L | Move the focused window in that direction |
 | Super + Ctrl + H / J / K / L | Resize in that direction |
 | Super + Q | Close the focused window |
@@ -34,6 +39,10 @@ to nearby edges; continuing to drag beyond 20 logical pixels releases the snap.
 Maximize fills the available workspace. Fullscreen also hides the bar and window
 decorations.
 Keep Alt held to cycle through recent windows. Release Alt to select the previewed
 window, or press Escape to cancel. Repeating Super + Backspace toggles between the
 two most recently focused windows.
 ## Columns and layouts
 | Shortcut | Action |
@@ -61,8 +70,8 @@ overview.
 | Super + Shift + 1–9 | Move the window to that workspace |
 | Super + Escape | Toggle between the last two visited workspaces on this monitor |
-Workspaces are created as needed. Selecting one visible on another monitor focuses
+Workspaces are created as needed and numbered separately on each monitor.
-that monitor.
+Workspace shortcuts select a workspace on the focused monitor.
 To make pressing the current workspace's shortcut toggle back too, enable
 **Settings → Windows → Toggle back with the same workspace shortcut**. It is off
@@ -99,6 +108,39 @@ Gestures can use the same actions
 as keyboard bindings, including overview or moving a window. Four- and five-finger
 bindings are supported too.
 ## Reserved and context controls
 These controls are handled by the compositor rather than configurable bindings.
 | Control | Action |
 | --- | --- |
 | Enter in overview | Activate the selected window |
 | Escape in overview | Close overview |
 | Escape during Alt + Tab | Cancel the preview without changing focus |
 | Release Alt during Alt + Tab | Focus the previewed window |
 | Ctrl + Alt + Escape | Release an active shortcut inhibitor or input-capture session |
 | Ctrl + Alt + F1–F12 | Switch virtual terminals in a direct session |
 Virtual-terminal switching is unavailable in nested previews.
 ## Example-config shortcuts
 The [example config](../packaging/config.kdl) adds these to the built-in defaults.
 App and hardware controls require their configured programs to be installed.
 | Shortcut | Action |
 | --- | --- |
 | Super + B | Open Firefox |
 | Super + Z | Open Zed |
 | Super + Alt + L | Lock with `ferese-lock` |
 | Super + Left / Down / Up / Right | Focus in that direction |
 | Super + Ctrl + Left / Down / Up / Right | Move the focused window in that direction |
 | Super + Alt + Left / Down / Up / Right | Resize in that direction |
 | Brightness up / down | Adjust brightness with `brightnessctl` |
 | Volume up / down | Adjust volume with `wpctl` |
 | Audio mute | Toggle output mute with `wpctl` |
 | Microphone mute | Toggle microphone mute with `wpctl` |
 ## Add a shortcut
 For example, bind a lock command and use a swipe to open overview:
@@ -1,17 +1,16 @@
 # Why Ferese
-Most Wayland desktops are assembled from separate programs such as a compositor, a bar, a notification daemon, a launcher, a lock screen with each having its own config and its own idea of how things should look. Ferese is built as one desktop. Window management and the shell share a single configuration, so personalizing it means changing one thing, not five.
+Most Wayland desktops are assembled from separate programs: a compositor, a bar, a notification daemon, a launcher and a lock screen, each with its own config and appearance settings. Ferese's window manager and shell share a single configuration.
-## Choose how windows fit
+## Window layouts
 Keep windows at useful widths and move through them horizontally with scrolling columns,
 divide the screen into nested splits with tree tiling, or let individual windows float
-alongside either layout. When you want to see how everything fits together, overview
+alongside either layout. Overview shows your windows and workspaces together.
 brings your windows and workspaces into view.
 ![Ferese Overview showing windows and workspaces](images/screenshots/ferese-blue-overview.png)
-## Change the desktop together
+## Appearance
 Choose a theme in Settings and build on it with your own wallpaper, colors, font,
 corners and motion, with changes applying across the desktop as you make them. Window
@@ -29,6 +28,6 @@ theme {
 }
 ```
-Explore [Configuration](configuration.md) for everything you can change, or follow
+See [Configuration](configuration.md) for available settings, or follow
 [Installation](installation.md) to try Ferese inside your current desktop with a nested
 preview.
@@ -1,8 +1,7 @@
 # Ferese website and handbook
-The website introduces Ferese as one desktop you can make your own, with a handbook
+The website's handbook is built from the project's Markdown guides, so the website
-built from the project’s Markdown guides so the website and repository share the same
+and repository share the same documentation.
 documentation.
 ## Local preview
@@ -14,8 +13,7 @@ python3 -m http.server 8080 --bind 127.0.0.1 --directory build/site
 ```
 Open http://localhost:8080 for the homepage or http://localhost:8080/docs/ for the
-handbook, then rebuild and refresh the browser whenever you change the site sources or
+handbook. Rebuild and refresh the browser after changing the site sources or guides.
 guides.
 - `site/index.html` and `site/styles.css`: homepage and shared visual design.
 - `site/content/index.md`: handbook introduction.
@@ -28,8 +26,8 @@ guides.
 ## GitHub Pages
 Choose **Settings → Pages → Source → GitHub Actions** to publish through the Pages
-workflow, which runs when site or documentation changes reach `main` and can also be
+workflow. It runs when site or documentation changes reach `main`; you can also
-started manually. The expected address is https://ferese-wm.github.io/ferese/.
+start it manually. The expected address is https://ferese-wm.github.io/ferese/.
 The site uses relative links, including for handbook search, so it also works under the
 `/ferese/` project path. Each build copies screenshots from `docs/images` into
@@ -1,11 +1,10 @@
 # Ferese handbook
-Ferese is a window manager and desktop shell built together and configured in one place,
+Ferese combines a window manager and desktop shell with one configuration.
-for people who want their desktop to be their own. This handbook helps you get settled,
+This handbook covers installation, settings and desktop controls.
 shape the desktop around the way you work and understand what you can change.
 [Browse screenshots](screenshots.md) to see the themes, layouts and desktop controls in
-use
+use.
 ## Get started
@@ -44,9 +43,8 @@ group windows, resize them and move between workspaces.
 - [Screen sharing and recording](screen-sharing.md): share an app or display, or save a video.
 - [Desktop portals](portals.md): integration with applications.
-Personalize the desktop in Settings or edit `~/.config/ferese/config.kdl` directly, with
+Configure the desktop in Settings or edit `~/.config/ferese/config.kdl` directly.
-changes applying live and the last working configuration staying in place if an edit is
+Changes apply live. Invalid edits leave the last working configuration in place.
 invalid.
 ## Troubleshooting
@@ -54,6 +52,6 @@ If you need to end a session, `feresectl request-logout` asks for confirmation a
 `feresectl exit` exits immediately, so save your work first. The [logs and recovery
 guide](installation.md#logout-and-recovery) helps when something stops responding.
-You can [report a problem](https://github.com/ferese-wm/ferese/issues) with the steps to
+To [report a problem](https://github.com/ferese-wm/ferese/issues), include the steps to
 reproduce it, relevant logs and whether you were using a nested preview or a direct
-session, or start with [Development](development.md) if you’d like to contribute.
+session. See [Development](development.md) to contribute.
@@ -5,9 +5,9 @@
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <meta name="theme-color" content="#10151c" />
-  <meta name="description" content="Ferese is a Wayland desktop built around personalization." />
+  <meta name="description" content="Ferese is a configurable Wayland desktop." />
  <meta property="og:title" content="Ferese — Wayland desktop" />
-  <meta property="og:description" content="A Wayland desktop built around personalization." />
+  <meta property="og:description" content="A configurable Wayland desktop." />
  <meta property="og:type" content="website" />
  <meta property="og:image" content="https://ferese-wm.github.io/ferese/assets/screenshots/ferese-main-hero.png" />
  <meta name="twitter:card" content="summary_large_image" />
@@ -36,12 +36,11 @@
  <main id="main" class="simple-home">
    <section class="product-intro page-width">
      <h1 class="product-tagline">
-        A Wayland desktop built around personalization.
+        A configurable Wayland desktop.
      </h1>
      <p class="product-description">
-        Ferese is a window manager and desktop shell
+        Ferese combines a window manager and desktop shell
-        built together and configured in one place,
+        with one configuration.
        for people who want their desktop to be their own.
      </p>
      <div class="product-links">
        <a class="button" href="docs/installation.html">Install Ferese</a>
@@ -64,7 +63,7 @@
    </figure>
    <section class="product-features page-width" aria-label="Features">
      <article>
-        <h2>Flexible layouts</h2>
+        <h2>Window layouts</h2>
        <p>
          Scrolling columns, tree tiling, floating windows, and a workspace
          overview. Use keyboard shortcuts or gestures to move around.
@@ -72,15 +71,14 @@
        <a href="docs/configuration.html#layout">Configure layouts →</a>
      </article>
      <article>
-        <h2>A native desktop</h2>
+        <h2>Desktop tools</h2>
        <p>
-          A menu bar, Control Center, Settings, notifications, and desktop
+          A menu bar, Control Center, Settings, notifications, and desktop widgets.
          widgets, designed to work together.
        </p>
        <a href="docs/why-ferese.html">Explore Ferese →</a>
      </article>
      <article>
-        <h2>Make it yours</h2>
+        <h2>Appearance</h2>
        <p>
          Choose your theme, wallpaper, colors, and motion. Change settings
          through the app or a KDL config, with live reload.