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

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

Restructure libtmux-mcp documentation to the Library Skeleton. topics/
created (architecture, concepts, safety, troubleshooting). project/
section. Get started in one command instant activation above grid cards.
Server Management card added to tools/. Broken ref fixed.
sphinx-design added.

Author: tony

docs/conf.py

@@ -40,10 +40,13 @@
     "sphinx_copybutton",
     "sphinxext.opengraph",
     "sphinxext.rediraffe",
+    "sphinx_design",
     "myst_parser",
     "linkify_issues",
 ]
 
+myst_heading_anchors = 4
+
 myst_enable_extensions = [
     "colon_fence",
     "substitution",

docs/index.md

@@ -8,56 +8,88 @@ MCP server for tmux, powered by [libtmux](https://libtmux.git-pull.com/).
 **Pre-alpha.** APIs may change. [Feedback welcome](https://github.com/tmux-python/libtmux-mcp/issues).
 ```
 
-```{include} ../README.md
-:start-after: "## Quick start"
-:end-before: "## What's included"
+## Get started in one command
+
+```console
+$ claude mcp add libtmux -- uvx libtmux-mcp
 ```
 
-```{toctree}
-:caption: Getting Started
-:maxdepth: 2
-:hidden:
+Then ask your agent:
 
-installation
-quickstart
-clients
-concepts
-configuration
-safety
+```
+> List all tmux sessions and show the panes in the first one.
 ```
 
-```{toctree}
-:caption: Tools
-:maxdepth: 2
-:hidden:
+::::{grid} 1 2 3 3
+:gutter: 2 2 3 3
 
-tools/index
-```
+:::{grid-item-card} Quickstart
+:link: quickstart
+:link-type: doc
+Zero to a working tool invocation in 5 minutes.
+:::
 
-```{toctree}
-:caption: Guides
-:maxdepth: 2
-:hidden:
+:::{grid-item-card} Tools
+:link: tools/index
+:link-type: doc
+30+ tools for sessions, windows, panes, capture, and more.
+:::
+
+:::{grid-item-card} Configuration
+:link: configuration
+:link-type: doc
+Environment variables, safety tiers, socket selection.
+:::
+
+::::
+
+::::{grid} 1 2 3 3
+:gutter: 2 2 3 3
+
+:::{grid-item-card} MCP Clients
+:link: clients
+:link-type: doc
+Copy-pasteable config for Claude Code, Cursor, VS Code, and more.
+:::
 
-guides/troubleshooting
+:::{grid-item-card} Topics
+:link: topics/index
+:link-type: doc
+Architecture, concepts, safety tiers, troubleshooting.
+:::
+
+:::{grid-item-card} Contributing
+:link: project/index
+:link-type: doc
+Development setup, code style, release process.
+:::
+
+::::
+
+## Install
+
+```console
+$ uvx libtmux-mcp
 ```
 
+```console
+$ pip install libtmux-mcp
+```
+
+See [Installation](installation.md) for all methods and options.
+
 ```{toctree}
-:caption: Reference
-:maxdepth: 2
 :hidden:
 
+installation
+quickstart
+clients
+configuration
+tools/index
+topics/index
 reference/api/index
 reference/compatibility
+project/index
 history
-```
-
-```{toctree}
-:caption: Project
-:hidden:
-
-architecture
-development
 glossary
-GitHub <https://github.com/tmux-python/libtmux-mcp>
 ```

docs/project/code-style.md

@@ -0,0 +1,33 @@
+(code-style)=
+
+# Code style
+
+## Linting and formatting
+
+libtmux-mcp uses [ruff](https://docs.astral.sh/ruff/) for linting and formatting:
+
+```console
+$ uv run ruff check .
+```
+
+```console
+$ uv run ruff format .
+```
+
+## Type checking
+
+[mypy](https://mypy-lang.org/) with strict mode:
+
+```console
+$ uv run mypy
+```
+
+## Docstrings
+
+NumPy-style docstrings throughout.
+
+## Imports
+
+- `from __future__ import annotations` at the top of every file.
+- `import typing as t` and access via namespace.
+- Standard-library modules imported by namespace (`import pathlib`, not `from pathlib import Path`).

docs/development.md docs/project/contributing.mddocs/development.md renamed to docs/project/contributing.md

@@ -0,0 +1,36 @@
+(project)=
+
+# Project
+
+Information for contributors and maintainers.
+
+::::{grid} 1 1 2 2
+:gutter: 2 2 3 3
+
+:::{grid-item-card} Contributing
+:link: contributing
+:link-type: doc
+Development setup, running tests, submitting PRs.
+:::
+
+:::{grid-item-card} Code Style
+:link: code-style
+:link-type: doc
+Ruff, mypy, NumPy docstrings, import conventions.
+:::
+
+:::{grid-item-card} Releasing
+:link: releasing
+:link-type: doc
+Release checklist and version policy.
+:::
+
+::::
+
+```{toctree}
+:hidden:
+
+contributing
+code-style
+releasing
+```

docs/project/index.md

@@ -0,0 +1,15 @@
+(releasing)=
+
+# Releasing
+
+## Version scheme
+
+libtmux-mcp follows [PEP 440](https://peps.python.org/pep-0440/) with alpha suffixes during pre-1.0 development (e.g. `0.1.0a0`).
+
+## Release checklist
+
+1. Update `CHANGES`.
+2. Bump version in `src/libtmux_mcp/__about__.py`.
+3. Commit and tag: `git tag v0.X.Y`.
+4. Push with tags: `git push --follow-tags`.
+5. CI publishes to PyPI.

docs/project/releasing.md

@@ -1,10 +1,14 @@
-"about" "concepts"
-"topics/safety" "safety"
-"developing" "development"
+"about" "topics/concepts"
+"developing" "project/contributing"
+"development" "project/contributing"
 "api/index" "reference/api/index"
 "api/server" "reference/api/server"
 "api/tools" "reference/api/tools"
 "api/models" "reference/api/models"
 "api/middleware" "reference/api/middleware"
 "api/resources" "reference/api/resources"
 "api/utils" "reference/api/utils"
+"architecture" "topics/architecture"
+"concepts" "topics/concepts"
+"safety" "topics/safety"
+"guides/troubleshooting" "topics/troubleshooting"

docs/redirects.txt

@@ -2,8 +2,49 @@
 
 # API Reference
 
+::::{grid} 1 1 2 2
+:gutter: 2 2 3 3
+
+:::{grid-item-card} Server
+:link: server
+:link-type: doc
+MCP server entry point and lifecycle.
+:::
+
+:::{grid-item-card} Tools
+:link: tools
+:link-type: doc
+Tool function implementations.
+:::
+
+:::{grid-item-card} Models
+:link: models
+:link-type: doc
+Pydantic models for requests and responses.
+:::
+
+:::{grid-item-card} Middleware
+:link: middleware
+:link-type: doc
+Safety-tier enforcement and request hooks.
+:::
+
+:::{grid-item-card} Resources
+:link: resources
+:link-type: doc
+MCP resource providers.
+:::
+
+:::{grid-item-card} Utils
+:link: utils
+:link-type: doc
+Shared helpers and utilities.
+:::
+
+::::
+
 ```{toctree}
-:maxdepth: 2
+:hidden:
 
 server
 tools

docs/reference/api/index.md

@@ -4,6 +4,53 @@
 
 All tools accept an optional `socket_name` parameter for multi-server support. It defaults to the `LIBTMUX_SOCKET` env var. See {ref}`configuration`.
 
+::::{grid} 1 1 2 2
+:gutter: 2 2 3 3
+
+:::{grid-item-card} Discovery
+Find and inspect tmux objects.
+^^^
+`list_sessions` `list_windows` `list_panes` `get_server_info` `get_pane_info`
+:::
+
+:::{grid-item-card} Capture & Search
+Read and search terminal output.
+^^^
+`capture_pane` `search_panes` `wait_for_text`
+:::
+
+:::{grid-item-card} Session Lifecycle
+Create and manage sessions.
+^^^
+`create_session` `rename_session` `kill_session`
+:::
+
+:::{grid-item-card} Windows & Panes
+Create, split, and organize.
+^^^
+`create_window` `split_window` `rename_window` `select_layout` `resize_window` `resize_pane` `kill_window` `kill_pane`
+:::
+
+:::{grid-item-card} Execution
+Send commands and interact with terminals.
+^^^
+`send_keys` `set_pane_title` `clear_pane`
+:::
+
+:::{grid-item-card} Options & Environment
+Read and set tmux configuration.
+^^^
+`show_option` `set_option` `show_environment` `set_environment`
+:::
+
+:::{grid-item-card} Server Management
+Destructive server operations.
+^^^
+`kill_server`
+:::
+
+::::
+
 ## Discovery
 
 Find and inspect tmux objects.
@@ -66,6 +113,5 @@ Read and set tmux configuration.
 
 ## Tool parameter reference
 
-For full parameter documentation (types, defaults, descriptions), see the {ref}`about <about>` page.
-
-For API-level documentation, see the {ref}`API reference <api>`.
+For full parameter documentation (types, defaults, descriptions), see the
+[API reference](../reference/api/index.md).