tony · Oct 29, 2026 · Oct 29, 2026 · Oct 29, 2026 · Oct 29, 2026 · Oct 29, 2026
diff --git a/CHANGES b/CHANGES
@@ -1,41 +1,7 @@
 # Changelog
 
-For instructions on installing the development version of libtmux, refer to
-[development releases](https://libtmux.git-pull.com/quickstart.html#developmental-releases).
-
-[pip](https://pip.pypa.io/en/stable/):
-
-```console
-$ pip install --user --upgrade --pre libtmux
-```
-
-[pipx](https://pypa.github.io/pipx/docs/):
-
-```console
-$ pipx install \
-    --suffix=@next \
-    --pip-args '\--pre' \
-    --force \
-    'libtmux'
-```
-
-Run the suffixed executable as:
-
-```console
-$ libtmux@next [command]
-```
-
-[uv](https://docs.astral.sh/uv/):
-
-```console
-$ uv add libtmux --prerelease allow
-```
-
-[uvx](https://docs.astral.sh/uv/guides/tools/):
-
-```console
-$ uvx --from 'libtmux' --prerelease allow python
-```
+For development installation, see
+[development releases](https://libtmux.git-pull.com/quickstart/#developmental-releases).
 
 ## libtmux 0.63.x (Yet to be released)
 

diff --git a/README.md b/README.md
@@ -30,7 +30,7 @@ libtmux is a typed Python API over [tmux], the terminal multiplexer. Stop shelli
 ## Requirements & support
 
 - tmux: >= 3.2a
-- Python: >= 3.10 (CPython and PyPy)
+- Python: >= 3.10, < 4.0 (CPython and PyPy)
 
 Maintenance-only backports (no new fixes):
 
@@ -39,50 +39,71 @@ Maintenance-only backports (no new fixes):
 
 ## 📦 Installation
 
-Release:
+Install libtmux into the Python environment that will import it:
 
 ```console
-$ pip install libtmux
+$ python -m pip install libtmux
 ```
 
-With pipx:
-
-```console
-$ pipx install libtmux
-```
-
-With uv / uvx:
+With uv in a project:
 
 ```console
 $ uv add libtmux
 ```
 
+For an ad hoc Python REPL:
+
 ```console
-$ uvx --from "libtmux" python
+$ uv run \
+    --with libtmux \
+    python
 ```
 
 From the main branch (bleeding edge):
 
 ```console
-$ pip install 'git+https://github.com/tmux-python/libtmux.git'
+$ python -m pip install 'git+https://github.com/tmux-python/libtmux.git'
 ```
 
-Tip: libtmux is pre-1.0. Pin a range in projects to avoid surprises:
+libtmux is pre-1.0: minor releases may change the API. Pin the minor series
+you have tested; for example, to stay on 0.62.x:
 
 requirements.txt:
 
 ```ini
-libtmux==0.50.*
+libtmux>=0.62,<0.63
 ```
 
 pyproject.toml:
 
 ```toml
-libtmux = "0.50.*"
+[project]
+dependencies = ["libtmux>=0.62,<0.63"]
 ```
 
 ## 🚀 Quickstart
 
+Create a server on a temporary socket. The context managers stop the server
+and remove the temporary directory when the block exits:
+
+```python
+>>> import tempfile
+>>> import libtmux
+>>> with tempfile.TemporaryDirectory() as directory:
+...     with libtmux.Server(socket_path=f"{directory}/tmux.sock") as server:
+...         session = server.new_session(session_name="demo")
+...         window = session.active_window
+...         pane = window.active_pane
+...         pane.send_keys("echo hello")
+...         print(session.session_name)
+demo
+```
+
+The shorter reference examples below use `server`, `session`, `window`,
+`pane`, and imported classes supplied by this repository's doctest setup.
+In your own code, create those objects as above or select them from an
+existing server. `monkeypatch` in the environment example is a pytest fixture.
+
 ### Open a tmux session
 
 First, start a tmux session to connect to:

diff --git a/docs/api/testing/pytest-plugin/fixtures.md b/docs/api/testing/pytest-plugin/fixtures.md
@@ -5,8 +5,9 @@
 ## Quick Start
 
 Add a fixture name as a test parameter — [pytest] creates and injects it
-automatically. You never call fixtures yourself. In doctests, libtmux injects
-the same objects through `doctest_namespace`:
+automatically. You never call fixtures yourself. This repository's
+`conftest.py` also injects objects through `doctest_namespace` for the examples
+below; downstream doctests need their own namespace setup:
 
 ```python
 >>> created_session = server.new_session(session_name="my-session")

diff --git a/docs/api/testing/pytest-plugin/usage.md b/docs/api/testing/pytest-plugin/usage.md
@@ -37,14 +37,15 @@ object lookups in the test grid.
 [pytest-tmux] also works through {ref}`pytest fixtures <pytest:fixtures-api>`,
 so the same fixture concepts apply.
 
-The plugin's fixtures guarantee a fresh, headless {command}`tmux(1)` server, session, window, or pane is
-passed into your test.
+Request `server` or `session` as a test parameter to receive a fresh, headless
+{command}`tmux(1)` server or session. Derive windows and panes from the session;
+the plugin does not register `window` or `pane` fixtures.
 
 (recommended-fixtures)=
 
 ## Recommended fixtures
 
-These fixtures are automatically used when the plugin is enabled and `pytest` is run.
+Requesting `server` or `session` also creates their filesystem dependencies:
 
 - Creating temporary, test directories for:
   - `/home/` ({fixture}`home_path`)
@@ -53,7 +54,8 @@ These fixtures are automatically used when the plugin is enabled and `pytest` is
 
   - `base-index -g 1`
 
-  These are set to ensure panes and windows can be reliably referenced and asserted.
+  To make tmux read this configuration, set the temporary home directory as
+  shown in {ref}`set_home`, or pass `config_file` to a server you create.
 
 (setting_a_tmux_configuration)=
 

diff --git a/docs/glossary.md b/docs/glossary.md
@@ -38,7 +38,7 @@ Session
 
     The session has 1 or more {term}`Window`. The bottom bar in tmux
     show a list of windows. Normally they can be navigated with
-    ``Ctrl-a [0-9]``, ``Ctrl-a n`` and ``Ctrl-a p``.
+    ``Ctrl-b [0-9]``, ``Ctrl-b n`` and ``Ctrl-b p`` with tmux's default prefix.
 
     Sessions can have a ``session_name``.
 

diff --git a/docs/project/compatibility.md b/docs/project/compatibility.md
@@ -3,13 +3,13 @@
 ## Python
 
 - **Minimum**: Python 3.10
-- **Tested**: Python 3.10, 3.11, 3.12, 3.13
+- **CI targets**: see the [CI matrix](https://github.com/tmux-python/libtmux/blob/master/.github/workflows/tests.yml)
 - **Maximum**: Python < 4.0
 
 ## tmux
 
 - **Minimum**: tmux 3.2a
-- **Tested**: latest stable tmux release
+- **CI targets**: the releases and development branch in the matrix above
 - libtmux uses tmux's format system and control mode -- older tmux versions
   may lack required format variables
 
@@ -24,6 +24,7 @@
 
 ## Known Limitations
 
-- tmux must be running and accessible via the default socket or a specified socket
+- Commands targeting existing objects need a running, accessible tmux server.
+  {meth}`~libtmux.Server.new_session` starts a server when needed.
 - Some operations require the tmux server to have at least one session
 - Format string availability depends on tmux version
diff --git a/docs/project/deprecations.md b/docs/project/deprecations.md
@@ -6,7 +6,16 @@ Active deprecations with timeline and migration paths.
 
 <!-- Pull active deprecations from CHANGES when they exist -->
 
-No active deprecations at this time.
+The following {class}`~libtmux.Window` methods emit `DeprecationWarning`:
+
+| Deprecated | Replacement |
+|------------|-------------|
+| {meth}`~libtmux.Window.set_window_option` | {meth}`~libtmux.Window.set_option` |
+| {meth}`~libtmux.Window.show_window_option` | {meth}`~libtmux.Window.show_option` |
+| {meth}`~libtmux.Window.show_window_options` | {meth}`~libtmux.Window.show_options` |
+
+The legacy `g` parameter on option methods also emits `DeprecationWarning`;
+use `global_` instead. No removal release is scheduled here.
 
 See [history](../history.md) for past changes and the
 [migration guide](../migration.md) for upgrading between versions.

diff --git a/docs/project/public-api.md b/docs/project/public-api.md
@@ -2,7 +2,7 @@
 
 ## What Is Public
 
-Every module documented under [API Reference](index.md) is public API.
+Every module documented under [API Reference](../api/index.md) is public API.
 This includes:
 
 ### Core Library

diff --git a/docs/project/releasing.md b/docs/project/releasing.md
@@ -7,51 +7,15 @@ Users should pin to `>=0.x,<0.y`.
 
 ## Release Process
 
-Releases are triggered by git tags and published to [PyPI] via OIDC trusted publishing.
-
-1. Update `CHANGES` with the release notes
-
-2. Bump version in `src/libtmux/__about__.py`
-
-3. Commit:
-
-   ```console
-   $ git commit -m "libtmux <version>"
-   ```
-
-4. Tag:
-
-   ```console
-   $ git tag v<version>
-   ```
-
-5. Push:
-
-   ```console
-   $ git push && git push --tags
-   ```
-
-6. CI builds and publishes to [PyPI] automatically via trusted publishing
+Follow the [contributor release checklist] for version updates, commits, and
+publication to [PyPI]. The owner creates and pushes release tags; tags trigger
+the publishing workflow.
 
 ## Changelog Format
 
-The `CHANGES` file uses this format:
-
-```text
-libtmux <version> (<date>)
---------------------------
-
-### What's new
-
-- Description of feature (#issue)
-
-### Bug fixes
-
-- Description of fix (#issue)
-
-### Breaking changes
-
-- Description of break, migration path (#issue)
-```
+Follow [the changelog policy] for the `CHANGES` structure, unreleased entries,
+and release-time lead paragraphs.
 
+[contributor release checklist]: https://github.com/tmux-python/libtmux/blob/master/.github/CONTRIBUTING.md#releasing
+[the changelog policy]: https://github.com/tmux-python/libtmux/blob/master/.github/WRITING.md#the-changelog
 [PyPI]: https://pypi.org/project/libtmux/