Astro docs monorepo + API autodoc pipeline

.gitignore

@@ -81,3 +81,7 @@ monkeytype.sqlite3
 **/CLAUDE.local.md
 **/CLAUDE.*.md
 **/.claude/settings.local.json
+
+# Allow Astro app helpers (lib/ is ignored globally)
+!astro/apps/docs/src/lib/
+!astro/apps/docs/src/lib/**

astro/.gitignore

@@ -0,0 +1,100 @@
+###
+### Sphinx
+###
+
+# macOS
+.DS_Store
+
+.env
+*.pyc
+*.tar.gz
+*.egg-info
+
+_build
+
+# ignore virtualenvs
+/*env*/
+
+# npm
+node_modules/
+
+# editors
+.vim/
+.vscode/
+
+# cache
+.mypy_cache/
+
+**/.claude/settings.local.json
+
+###
+### Node.js
+###
+
+# Dependencies
+node_modules/
+.pnpm-store/
+
+# Build outputs
+dist/
+.vite-react-ssg-temp/
+.vite/
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# TypeScript
+*.tsbuildinfo
+
+# Generated files
+routeTree.gen.ts
+.tanstack/
+
+# Astro
+.astro/
+
+# Testing
+coverage/
+.nyc_output/
+
+# Temporary files
+.tmp/
+temp/
+
+# MyST build files
+_build/
+.myst/
+
+# Build analytics
+build-analytics.json
+
+# Playwright
+playwright-report/
+.playwright-mcp/

astro/AGENTS.md

@@ -0,0 +1,73 @@
+# AGENTS.md
+
+## Project Context
+
+Astro-based documentation monorepo for libtmux. It replaces the existing Sphinx site with a static-first Astro site that renders API docs by scanning Python source with a TypeScript toolchain and a small Python AST helper.
+
+## Tech Stack
+
+- **Framework**: Astro v5 (islands) + optional React for hydration
+- **Styling**: Tailwind CSS v4
+- **Language**: TypeScript (strict)
+- **Testing**: Vitest
+- **Quality**: Biome (lint/format)
+- **Package Manager**: pnpm 10.x workspaces
+- **Python tooling**: uv/uvx + Python AST for API scanning
+
+## Architecture Map
+
+```
+packages/
+├── schema/                # Zod contracts (schema firewall)
+├── py-bridge/             # uv/uvx subprocess boundary
+├── py-parse/              # Static AST parsing
+├── py-introspect/         # Runtime introspection
+├── api-model/             # High-level API model + snapshots
+├── core/                  # Orchestration + caching
+├── intersphinx/           # Intersphinx inventory parser
+├── astro-autodoc/         # Astro components + helpers for API rendering
+└── astro-intersphinx/     # Astro helpers for intersphinx resolution
+
+apps/
+└── docs/                  # Astro docs site for libtmux
+
+python/
+└── pyautodoc_sidecar/     # Python sidecar invoked via uv run
+```
+
+## Workflow Commands
+
+```bash
+pnpm install
+```
+
+```bash
+pnpm start
+```
+
+```bash
+pnpm type-check
+```
+
+```bash
+pnpm biome-all
+```
+
+```bash
+pnpm test
+```
+
+```bash
+pnpm update:all
+```
+
+```bash
+pnpm ncu
+```
+
+## Hard Constraints
+
+1. **Monorepo layering**: core packages must not depend on astro packages.
+2. **Autodoc data**: use Zod schemas for validated data flow between packages.
+3. **Python scanning**: default to `uv run` with a sidecar project; allow an override for local Python executables and optional `uvx` tool mode.
+4. **Astro hydration**: any React components must include an explicit client directive.

astro/README.md

@@ -0,0 +1,64 @@
+# libtmux docs (Astro)
+
+Astro-based documentation monorepo for libtmux. It replaces the Sphinx site with a static-first site and a TypeScript-driven API doc pipeline that scans Python source via a Python sidecar.
+
+## Packages
+
+- `packages/schema`: Zod schema firewall
+- `packages/py-bridge`: Python subprocess bridge (uv run / uvx)
+- `packages/py-parse`: Python AST parser
+- `packages/py-introspect`: Runtime introspection wrapper
+- `packages/api-model`: High-level API model built from scan results
+- `packages/core`: Orchestration + caching
+- `packages/intersphinx`: Sphinx intersphinx inventory parser
+- `packages/astro-autodoc`: Astro components for API docs
+- `packages/astro-intersphinx`: Astro helpers for intersphinx links
+- `apps/docs`: The docs website
+
+## Setup
+
+Install dependencies:
+
+```bash
+pnpm install
+```
+
+## Development
+
+Start the docs site:
+
+```bash
+pnpm start
+```
+
+## Quality checks
+
+Run the type checker:
+
+```bash
+pnpm type-check
+```
+
+Run the linter:
+
+```bash
+pnpm biome-all
+```
+
+Run tests:
+
+```bash
+pnpm test
+```
+
+## Updating dependencies
+
+Update all dependencies with npm-check-updates:
+
+```bash
+pnpm update:all
+```
+
+## Python scanning
+
+The sidecar defaults to `uv run python` and can be overridden with `LIBTMUX_PYTHON_COMMAND`.

astro/apps/docs/astro.config.ts

@@ -0,0 +1,15 @@
+import mdx from '@astrojs/mdx'
+import react from '@astrojs/react'
+import tailwind from '@tailwindcss/vite'
+import { defineConfig } from 'astro/config'
+
+export default defineConfig({
+  site: 'https://libtmux.git-pull.com',
+  integrations: [react(), mdx()],
+  server: {
+    port: 4350,
+  },
+  vite: {
+    plugins: [tailwind()],
+  },
+})

astro/apps/docs/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@libtmux/docs-site",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Astro docs site for libtmux",
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro",
+    "lint": "biome lint .",
+    "format": "pnpm biome check . --write; biome format . --write",
+    "type-check": "astro check && tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "ncu": "ncu",
+    "update": "pnpm update",
+    "clean": "rm -rf dist/ node_modules/.cache/",
+    "biome": "biome check . --write && biome format . --write"
+  },
+  "dependencies": {
+    "@astrojs/mdx": "^4.3.13",
+    "@astrojs/react": "^4.4.2",
+    "@fontsource/fraunces": "^5.2.9",
+    "@fontsource/ibm-plex-mono": "^5.2.7",
+    "@fontsource/space-grotesk": "^5.2.10",
+    "@libtmux/api-model": "workspace:*",
+    "@libtmux/astro-autodoc": "workspace:*",
+    "@libtmux/astro-intersphinx": "workspace:*",
+    "@libtmux/intersphinx": "workspace:*",
+    "@libtmux/py-parse": "workspace:*",
+    "@tailwindcss/typography": "^0.5.19",
+    "@tailwindcss/vite": "^4.1.18",
+    "astro": "^5.16.6",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "tailwindcss": "^4.1.18"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.11",
+    "@astrojs/check": "^0.9.6",
+    "@types/node": "^25.0.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  }
+}

astro/apps/docs/src/components/SiteFooter.astro

@@ -0,0 +1,14 @@
+<footer class="border-t border-ink/10 bg-paper/70">
+  <div class="mx-auto flex w-full max-w-6xl flex-col gap-6 px-6 py-10 text-sm text-ink/70 md:flex-row md:items-center md:justify-between">
+    <div>
+      <div class="font-serif text-lg text-ink">libtmux</div>
+      <div>Typed Python ORM for tmux automation.</div>
+    </div>
+    <div class="flex flex-wrap gap-4">
+      <a href="https://libtmux.git-pull.com/">Sphinx docs</a>
+      <a href="https://github.com/tmux-python/libtmux">GitHub</a>
+      <a href="https://github.com/tmux-python/tmuxp">tmuxp</a>
+      <a href="https://man.openbsd.org/OpenBSD-current/man1/tmux.1">tmux man page</a>
+    </div>
+  </div>
+</footer>

astro/apps/docs/src/components/SiteNav.astro

@@ -0,0 +1,42 @@
+---
+const navLinks = [
+  { label: 'Overview', href: '/' },
+  { label: 'Guides', href: '/guides' },
+  { label: 'API', href: '/api' },
+  { label: 'Architecture', href: '/architecture' },
+]
+---
+
+<header class="sticky top-0 z-20 border-b border-ink/10 bg-paper/80 backdrop-blur">
+  <div class="mx-auto flex w-full max-w-6xl items-center justify-between px-6 py-4">
+    <a href="/" class="flex items-center gap-3 font-serif text-xl">
+      <span class="tag">libtmux</span>
+      <span>Docs</span>
+    </a>
+    <nav class="hidden items-center gap-6 text-sm font-medium md:flex">
+      {navLinks.map((link) => (
+        <a class="nav-link" href={link.href}>
+          {link.label}
+        </a>
+      ))}
+    </nav>
+    <div class="hidden items-center gap-3 md:flex">
+      <a class="text-sm" href="https://github.com/tmux-python/libtmux">
+        GitHub
+      </a>
+      <a
+        class="rounded-full bg-accent px-4 py-2 text-sm font-semibold text-paper shadow-glow"
+        href="https://tmuxp.git-pull.com/"
+      >
+        tmuxp
+      </a>
+    </div>
+  </div>
+  <div class="mx-auto flex w-full max-w-6xl flex-wrap gap-3 px-6 pb-4 text-xs font-semibold uppercase tracking-wide text-ink/70 md:hidden">
+    {navLinks.map((link) => (
+      <a class="nav-link" href={link.href}>
+        {link.label}
+      </a>
+    ))}
+  </div>
+</header>

astro/apps/docs/src/env.d.ts

@@ -0,0 +1,4 @@
+declare module '*.astro' {
+  const Component: (props: Record<string, unknown>) => unknown
+  export default Component
+}