Preview gp-sphinx#36 curated default-value rendering

.github/workflows/docs.yml

@@ -4,6 +4,8 @@ on:
   push:
     branches:
       - main
+      # [DO NOT MERGE] preview branch for gp-sphinx PR #36 — revert before merge.
+      - improved-defaults-reprs
 
 permissions:
   contents: read
@@ -48,6 +50,21 @@ jobs:
         if: env.PUBLISH == 'true'
         run: uv python install ${{ matrix.python-version }}
 
+      # [DO NOT MERGE] pnpm + Node bootstrap for sphinx-vite-builder source build
+      # of gp-furo-theme — required while gp-sphinx-family deps resolve from the
+      # improved-defaults-reprs branch (see [tool.uv.sources]). Revert with the
+      # uv.sources block when gp-sphinx>=0.0.1a18 lands.
+      - name: Install pnpm
+        if: env.PUBLISH == 'true'
+        uses: pnpm/action-setup@v6
+        with:
+          version: 10
+      - name: Set up Node
+        if: env.PUBLISH == 'true'
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+
       - name: Install dependencies [w/ docs]
         if: env.PUBLISH == 'true'
         run: uv sync --all-extras --dev

.github/workflows/tests.yml

@@ -31,6 +31,19 @@ jobs:
           print("libtmux-mcp version:", __version__)
           '
 
+      # [DO NOT MERGE] pnpm + Node bootstrap for sphinx-vite-builder source build
+      # of gp-furo-theme — required while gp-sphinx-family deps resolve from the
+      # improved-defaults-reprs branch (see [tool.uv.sources]). Revert with the
+      # uv.sources block when gp-sphinx>=0.0.1a18 lands.
+      - name: Install pnpm
+        uses: pnpm/action-setup@v6
+        with:
+          version: 10
+      - name: Set up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+
       - name: Install dependencies
         run: uv sync --all-extras --dev
 
@@ -109,6 +122,19 @@ jobs:
       - name: Set up Python ${{ matrix.python-version }}
         run: uv python install ${{ matrix.python-version }}
 
+      # [DO NOT MERGE] pnpm + Node bootstrap for sphinx-vite-builder source build
+      # of gp-furo-theme — required while gp-sphinx-family deps resolve from the
+      # improved-defaults-reprs branch (see [tool.uv.sources]). Revert with the
+      # uv.sources block when gp-sphinx>=0.0.1a18 lands.
+      - name: Install pnpm
+        uses: pnpm/action-setup@v6
+        with:
+          version: 10
+      - name: Set up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+
       - name: Install dependencies
         run: uv sync --all-extras --dev
 

AGENTS.md

@@ -409,13 +409,15 @@ $ claude mcp add --scope user tmux -- uv --directory ~/work/python/libtmux-mcp r
 
 These rules apply when authoring entries in `CHANGES`, which is included into `docs/history.md` and rendered as the Sphinx changelog page. Modeled on Django's release-notes shape — deliverables get titles and prose, not bullets.
 
-**Open with a multi-sentence lead paragraph.** Plain prose, no italic. Two to four sentences telling the reader what shipped and who cares — user-visible takeaways, not internal mechanism. Cross-reference detail docs with `{ref}` to keep the lead compact.
+**Release entry boilerplate.** Every release header is `## libtmux-mcp X.Y.Z (YYYY-MM-DD)`. The file opens with a `## libtmux-mcp 0.1.x (unreleased)` placeholder block fenced by `<!-- KEEP THIS PLACEHOLDER ... -->` and `<!-- END PLACEHOLDER ... -->` HTML comments — new release entries land immediately below the END marker, never above it.
+
+**Open with a multi-sentence lead paragraph.** Plain prose, no italic. Open with the version as sentence subject (*"libtmux-mcp X.Y.Z ships …"*) so the lead is self-contained when excerpted. Two to four sentences telling the reader what shipped and who cares — user-visible takeaways, not internal mechanism. Cross-reference detail docs with `{ref}` to keep the lead compact.
 
 **Each deliverable is a section, not a bullet.** Inside `### What's new`, every distinct deliverable gets a `**Bold subheading**` naming it in user vocabulary, followed by 1-3 prose paragraphs explaining what shipped. Don't wrap a paragraph in `- ` — bullets are for enumerable lists, not paragraph containers. Cross-link detail docs (`See {ref}\`foo\` for details.`) so prose stays focused.
 
 **The deliverable test.** Before writing an entry, ask: "What's the deliverable, in user vocabulary?" If you can't answer in one sentence, the entry isn't ready. Mechanism (LIFO ordering, helper internals, byte counters, schema-validation locations) belongs in PR descriptions and code comments, not the changelog.
 
-**Fixed subheadings**, in this order when present: `### Breaking changes`, `### Dependencies`, `### What's new`, `### Fixes`, `### Documentation`, `### Development`. Dev tooling (helper scripts, internal automation) lives under `### Development`. For breaking changes, show the migration path with concrete inline code (commands, before/after).
+**Fixed subheadings**, in this order when present: `### Breaking changes`, `### Dependencies`, `### What's new`, `### Fixes`, `### Documentation`, `### Development`. Dev tooling (helper scripts, internal automation) lives under `### Development`. For breaking changes, show the migration path with concrete inline code (e.g. a `# Before` / `# After` fenced code block). Dependency floor bumps use the form ``Minimum `pkg>=X.Y.Z` (was `>=X.Y.W`)``.
 
 **PR refs `(#NN)`** sit at the end of each deliverable's prose paragraph, not on every sentence.
 
@@ -428,7 +430,7 @@ These rules apply when authoring entries in `CHANGES`, which is included into `d
 - Walls of text dressed up as bullets.
 - Buried breaking changes — they get their own subheading at the top of the entry.
 
-**Always link autodoc'd APIs.** Any class, function, exception, attribute, or tool slug that has its own rendered page must be cited via the appropriate role (`{class}`, `{func}`, `{exc}`, `{attr}`, `{tooliconl}`) — never with plain backticks. Doc pages without explicit ref labels use `{doc}` (e.g. `{doc}\`/tools/buffer/index\``). Plain backticks are correct for code syntax (`{user,project}`, `True`), env vars (`LIBTMUX_SOCKET`), pydantic field names on returned models (`pane_at_*`), parameter names, and file paths that aren't doc pages — anything without an autodoc destination.
+**Always link autodoc'd APIs.** Any class, function, exception, attribute, or tool slug that has its own rendered page must be cited via the appropriate role (`{class}`, `{func}`, `{exc}`, `{attr}`, `{tooliconl}`) — never with plain backticks. Tool slugs use the dash form matching the doc page filename (`{tooliconl}\`snapshot-pane\``, not the Python symbol `snapshot_pane`). Doc pages without explicit ref labels use `{doc}` (e.g. `{doc}\`/tools/buffer/index\``). Plain backticks are correct for code syntax (`{user,project}`, `True`), env vars (`LIBTMUX_SOCKET`), pydantic field names on returned models (`pane_at_*`), parameter names, and file paths that aren't doc pages — anything without an autodoc destination.
 
 **MyST roles.** Tool references use `{tooliconl}` (inline-friendly badge), class references use `{class}`, exceptions use `{exc}`, functions use `{func}`, attributes use `{attr}`, internal anchors use `{ref}`, doc-path links use `{doc}`. See **Sphinx Cross-Reference Roles for MCP Tools** above for the full table.
 

pyproject.toml

@@ -111,6 +111,16 @@ lint = [
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[tool.uv.sources]
+# TEMPORARY: pull gp-sphinx-family deps from the improved-defaults-reprs
+# branch on git-pull/gp-sphinx so this PR previews the curated-default
+# rendering work before a release bump propagates the changes via PyPI.
+# Revert this block when gp-sphinx>=0.0.1a18 lands.
+gp-sphinx = { git = "https://github.com/git-pull/gp-sphinx.git", branch = "improved-defaults-reprs", subdirectory = "packages/gp-sphinx" }
+sphinx-autodoc-typehints-gp = { git = "https://github.com/git-pull/gp-sphinx.git", branch = "improved-defaults-reprs", subdirectory = "packages/sphinx-autodoc-typehints-gp" }
+sphinx-autodoc-api-style = { git = "https://github.com/git-pull/gp-sphinx.git", branch = "improved-defaults-reprs", subdirectory = "packages/sphinx-autodoc-api-style" }
+sphinx-autodoc-fastmcp = { git = "https://github.com/git-pull/gp-sphinx.git", branch = "improved-defaults-reprs", subdirectory = "packages/sphinx-autodoc-fastmcp" }
+
 [tool.uv.exclude-newer-package]
 # git-pull packages release in lockstep with their workspaces, so a
 # fresh release blocking on the 3-day cooldown blocks every