docs(redesign): restructure documentation to Library Skeleton pattern

README.md

@@ -230,12 +230,12 @@ Session($... ...)
 
 | libtmux object | tmux concept                | Notes                          |
 |----------------|-----------------------------|--------------------------------|
-| [`Server`](https://libtmux.git-pull.com/api/servers.html) | tmux server / socket | Entry point; owns sessions |
-| [`Session`](https://libtmux.git-pull.com/api/sessions.html) | tmux session (`$0`, `$1`,...) | Owns windows |
-| [`Window`](https://libtmux.git-pull.com/api/windows.html) | tmux window (`@1`, `@2`,...) | Owns panes |
-| [`Pane`](https://libtmux.git-pull.com/api/panes.html) | tmux pane (`%1`, `%2`,...) | Where commands run |
+| [`Server`](https://libtmux.git-pull.com/api/libtmux.server.html) | tmux server / socket | Entry point; owns sessions |
+| [`Session`](https://libtmux.git-pull.com/api/libtmux.session.html) | tmux session (`$0`, `$1`,...) | Owns windows |
+| [`Window`](https://libtmux.git-pull.com/api/libtmux.window.html) | tmux window (`@1`, `@2`,...) | Owns panes |
+| [`Pane`](https://libtmux.git-pull.com/api/libtmux.pane.html) | tmux pane (`%1`, `%2`,...) | Where commands run |
 
-Also available: [`Options`](https://libtmux.git-pull.com/api/options.html) and [`Hooks`](https://libtmux.git-pull.com/api/hooks.html) abstractions for tmux configuration.
+Also available: [`Options`](https://libtmux.git-pull.com/api/libtmux.options.html) and [`Hooks`](https://libtmux.git-pull.com/api/libtmux.hooks.html) abstractions for tmux configuration.
 
 Collections are live and queryable:
 

docs/api/compatibility.md

@@ -0,0 +1,29 @@
+# Compatibility
+
+## Python
+
+- **Minimum**: Python 3.10
+- **Tested**: Python 3.10, 3.11, 3.12, 3.13
+- **Maximum**: Python < 4.0
+
+## tmux
+
+- **Minimum**: tmux 3.2a
+- **Tested**: latest stable tmux release
+- libtmux uses tmux's format system and control mode -- older tmux versions
+  may lack required format variables
+
+## Platforms
+
+| Platform | Status |
+|----------|--------|
+| Linux | Fully supported |
+| macOS | Fully supported |
+| WSL / WSL2 | Supported (tmux runs inside WSL) |
+| Windows (native) | Not supported (tmux does not run natively on Windows) |
+
+## Known Limitations
+
+- tmux must be running and accessible via the default socket or a specified socket
+- Some operations require the tmux server to have at least one session
+- Format string availability depends on tmux version

docs/api/deprecations.md

@@ -0,0 +1,16 @@
+# Deprecations
+
+Active deprecations with timeline and migration paths.
+
+## Active Deprecations
+
+<!-- Pull active deprecations from CHANGES when they exist -->
+
+No active deprecations at this time.
+
+See [history](../history.md) for past changes and the
+[migration guide](../migration.md) for upgrading between versions.
+
+## Deprecation Policy
+
+See [Public API -- Deprecation Process](public-api.md#deprecation-process).

docs/api/index.md

@@ -4,16 +4,103 @@
 
 # API Reference
 
+libtmux's public API mirrors tmux's object hierarchy:
+
+```
+Server -> Session -> Window -> Pane
+```
+
+## Core Objects
+
+::::{grid} 2
+:gutter: 3
+
+:::{grid-item-card} Server
+:link: libtmux.server
+:link-type: doc
+Entry point. Manages sessions and executes raw tmux commands.
+:::
+
+:::{grid-item-card} Session
+:link: libtmux.session
+:link-type: doc
+Manages windows within a tmux session.
+:::
+
+:::{grid-item-card} Window
+:link: libtmux.window
+:link-type: doc
+Manages panes, layouts, and window operations.
+:::
+
+:::{grid-item-card} Pane
+:link: libtmux.pane
+:link-type: doc
+Terminal instance. Send keys and capture output.
+:::
+
+::::
+
+## Supporting Modules
+
+::::{grid} 3
+:gutter: 3
+
+:::{grid-item-card} Common
+:link: libtmux.common
+:link-type: doc
+Base classes and command execution.
+:::
+
+:::{grid-item-card} Neo
+:link: libtmux.neo
+:link-type: doc
+Dataclass-based query interface.
+:::
+
+:::{grid-item-card} Options
+:link: libtmux.options
+:link-type: doc
+tmux option get/set.
+:::
+
+:::{grid-item-card} Hooks
+:link: libtmux.hooks
+:link-type: doc
+tmux hook management.
+:::
+
+:::{grid-item-card} Constants
+:link: libtmux.constants
+:link-type: doc
+Format strings and constants.
+:::
+
+:::{grid-item-card} Exceptions
+:link: libtmux.exc
+:link-type: doc
+Exception hierarchy.
+:::
+
+::::
+
+## Test Utilities
+
+If you're testing code that uses libtmux, see the test helpers and pytest plugin:
+
+```{toctree}
+:maxdepth: 1
+
+test-helpers/index
+pytest-plugin/index
+```
+
+## API Contract
+
 ```{toctree}
+:maxdepth: 1
 
-properties
-servers
-sessions
-windows
-panes
-options
-hooks
-constants
-common
-exceptions
+public-api
+compatibility
+deprecations
 ```

docs/api/public-api.md

@@ -0,0 +1,57 @@
+# Public API
+
+## What Is Public
+
+Every module documented under [API Reference](index.md) is public API.
+This includes:
+
+### Core Library
+
+| Module | Import Path |
+|--------|-------------|
+| Server | `from libtmux.server import Server` |
+| Session | `from libtmux.session import Session` |
+| Window | `from libtmux.window import Window` |
+| Pane | `from libtmux.pane import Pane` |
+| Common | `from libtmux.common import ...` |
+| Neo | `from libtmux.neo import ...` |
+| Options | `from libtmux.options import ...` |
+| Hooks | `from libtmux.hooks import ...` |
+| Constants | `from libtmux.constants import ...` |
+| Exceptions | `from libtmux.exc import ...` |
+
+### Test Utilities
+
+| Module | Import Path |
+|--------|-------------|
+| Test helpers | `from libtmux.test import ...` |
+| Pytest plugin | `libtmux.pytest_plugin` (auto-loaded) |
+
+## What Is Internal
+
+Modules under `libtmux._internal` and `libtmux._vendor` are **not public**.
+They may change or be removed without notice between any release.
+
+Do not import from:
+- `libtmux._internal.*`
+- `libtmux._vendor.*`
+
+## Pre-1.0 Stability Policy
+
+libtmux is pre-1.0. This means:
+
+- **Minor versions** (0.x -> 0.y) may include breaking API changes
+- **Patch versions** (0.x.y -> 0.x.z) are bug fixes only
+- **Pin your dependency**: use `libtmux>=0.55,<0.56` or `libtmux~=0.55.0`
+
+Breaking changes are documented in the [changelog](../history.md) and
+the [deprecations](deprecations.md) page before removal.
+
+## Deprecation Process
+
+Before removing or changing public API:
+
+1. A deprecation warning is added for at least one minor release
+2. The change is documented in [deprecations](deprecations.md)
+3. Migration guidance is provided
+4. The old API is removed in a subsequent minor release

docs/conf.py

@@ -42,6 +42,7 @@
     "sphinxext.rediraffe",
     "myst_parser",
     "linkify_issues",
+    "sphinx_design",
 ]
 
 myst_enable_extensions = [
@@ -52,6 +53,8 @@
     "linkify",
 ]
 
+myst_heading_anchors = 4
+
 templates_path = ["_templates"]
 
 source_suffix = {".rst": "restructuredtext", ".md": "markdown"}