Merge pull request #652 from tmux-python/2026-spring-doc-redesign

docs(redesign) — Library Skeleton pattern (#652)

Restructure libtmux documentation to the Library Documentation Skeleton.
api/ is the primary reference surface. Standalone composed homepage.
Grid cards on all section indexes. Trust stack (public-api, compatibility,
deprecations). Internals separated. 22 redirects. sphinx-design added.

Author: tony

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/about.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/compatibility.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/deprecations.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
 ```