Docs(feat[astro]): Scaffold Astro docs monorepo

why: Establish the Astro-based docs pipeline and site structure alongside the existing Sphinx docs.
what:
- Add pnpm workspace with Biome/TS configs and AGENTS guidance
- Introduce core API scan/model/intersphinx packages with tests
- Add Astro autodoc/intersphinx packages and a starter docs site

Author: tony

astro/AGENTS.md

@@ -0,0 +1,67 @@
+# 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/
+├── core/
+│   ├── py-ast/            # Python AST scanner + Zod schemas
+│   ├── api-model/         # High-level API model + snapshots
+│   └── intersphinx/       # Intersphinx inventory parser
+├── astro/
+│   ├── autodoc/           # Astro components + helpers for API rendering
+│   └── intersphinx/       # Astro helpers for intersphinx resolution
+└── site/
+    └── docs/              # Astro docs site for libtmux
+```
+
+## 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 uvx when available; allow an override for local Python executables.
+4. **Astro hydration**: any React components must include an explicit client directive.

astro/README.md

@@ -0,0 +1,60 @@
+# 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 uv/uvx.
+
+## Packages
+
+- `packages/core/py-ast`: Python AST scanner with Zod schemas
+- `packages/core/api-model`: High-level API model built from scan results
+- `packages/core/intersphinx`: Sphinx intersphinx inventory parser
+- `packages/astro/autodoc`: Astro components for API docs
+- `packages/astro/intersphinx`: Astro helpers for intersphinx links
+- `packages/site/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 AST scanner defaults to `uvx python` and can be overridden with `LIBTMUX_PYTHON_COMMAND`.

astro/biome.jsonc

@@ -0,0 +1,87 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.3.11/schema.json",
+  "css": {
+    "parser": {
+      "tailwindDirectives": true
+    }
+  },
+  "files": {
+    "includes": [
+      "**",
+      "!**/.venv",
+      "!**/.astro",
+      "!**/node_modules",
+      "!**/dist",
+      "!**/coverage",
+      "!**/.vitest",
+      "!**/notes",
+      "!**/playwright-report",
+      "!**/pnpm-lock.yaml",
+      "!**/.pnpm-store",
+      "!**/build-analytics.json",
+      "!**/CHANGELOG.md"
+    ]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 120
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "complexity": {
+        "noExcessiveCognitiveComplexity": "off"
+      },
+      "suspicious": {
+        "noExplicitAny": "off",
+        "noArrayIndexKey": "off"
+      },
+      "style": {
+        "noNonNullAssertion": "off",
+        "noParameterAssign": "error",
+        "useAsConstAssertion": "error",
+        "useDefaultParameterLast": "error",
+        "useEnumInitializers": "error",
+        "useSelfClosingElements": "error",
+        "useSingleVarDeclarator": "error",
+        "noUnusedTemplateLiteral": "error",
+        "useNumberNamespace": "error",
+        "noInferrableTypes": "error",
+        "noUselessElse": "error"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "trailingCommas": "all",
+      "semicolons": "asNeeded"
+    }
+  },
+  "overrides": [
+    {
+      "includes": ["**/*.astro"],
+      "linter": {
+        "rules": {
+          "correctness": {
+            "noUnusedImports": "off",
+            "noUnusedVariables": "off"
+          }
+        }
+      }
+    },
+    {
+      "includes": ["**/*.css"],
+      "linter": {
+        "rules": {
+          "suspicious": {
+            "noUnknownAtRules": "off"
+          }
+        }
+      }
+    }
+  ]
+}

astro/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@libtmux/docs-monorepo",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "pnpm --filter @libtmux/docs-site start",
+    "build": "pnpm --filter @libtmux/docs-site build",
+    "preview": "pnpm --filter @libtmux/docs-site preview",
+    "clean": "pnpm run --recursive clean",
+    "distclean": "pnpm run --recursive distclean",
+    "format": "pnpm run --recursive format",
+    "format:check": "biome format .",
+    "lint": "biome lint .",
+    "ncu": "pnpm run --recursive ncu",
+    "ncu-local": "ncu",
+    "biome-all": "pnpm run --recursive biome",
+    "biome-full": "biome lint . --apply --max-diagnostics=100 && biome check . --apply && biome format . --write",
+    "test": "pnpm run --recursive test",
+    "update": "pnpm run --recursive update",
+    "update:all": "ncu -u; pnpm --recursive run 'ncu' -u",
+    "deduplicate": "pnpm dedupe",
+    "type-check": "pnpm run --recursive type-check",
+    "type-check:watch": "pnpm run --recursive type-check:watch"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "packageManager": "pnpm@10.27.0",
+  "devDependencies": {
+    "@biomejs/biome": "2.3.11",
+    "npm-check-updates": "^19.2.1",
+    "typescript": "^5.9.3"
+  }
+}

astro/packages/astro/autodoc/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@libtmux/astro-autodoc",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Astro components for libtmux API docs",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": ["src"],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome lint .",
+    "format": "pnpm biome check . --write; biome format . --write",
+    "type-check": "tsc --noEmit",
+    "type-check:watch": "tsc --noEmit --watch",
+    "update": "pnpm update",
+    "ncu": "ncu",
+    "clean": "rm -rf dist/ node_modules/.cache/",
+    "biome": "biome check . --apply && biome format . --write"
+  },
+  "dependencies": {
+    "@libtmux/api-model": "workspace:*",
+    "@libtmux/py-ast": "workspace:*"
+  },
+  "peerDependencies": {
+    "astro": "^5.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.11",
+    "@types/node": "^25.0.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  }
+}

astro/packages/astro/autodoc/src/components/AutodocClass.astro

@@ -0,0 +1,48 @@
+---
+import '../styles.css'
+import AutodocFunction from './AutodocFunction.astro'
+import AutodocVariable from './AutodocVariable.astro'
+import Docstring from './Docstring.astro'
+import { slugify } from '../utils'
+
+const { klass } = Astro.props
+const anchor = slugify(klass.qualname)
+const bases = klass.bases.length > 0 ? `(${klass.bases.join(', ')})` : ''
+---
+
+<section id={anchor} class="autodoc-card autodoc">
+  <header>
+    <div class="autodoc-title">class {klass.name}{bases}</div>
+    {klass.decorators.length > 0 ? (
+      <div>
+        {klass.decorators.map((decorator) => (
+          <span class="autodoc-pill">@{decorator}</span>
+        ))}
+      </div>
+    ) : null}
+  </header>
+
+  <Docstring value={klass.docstring} />
+
+  {klass.attributes.length > 0 ? (
+    <div class="autodoc-divider">
+      <h4>Attributes</h4>
+      <div class="autodoc-grid">
+        {klass.attributes.map((attribute) => (
+          <AutodocVariable variable={attribute} />
+        ))}
+      </div>
+    </div>
+  ) : null}
+
+  {klass.methods.length > 0 ? (
+    <div class="autodoc-divider">
+      <h4>Methods</h4>
+      <div class="autodoc-grid">
+        {klass.methods.map((method) => (
+          <AutodocFunction fn={method} label={`${klass.name}.${method.name}`} />
+        ))}
+      </div>
+    </div>
+  ) : null}
+</section>

astro/packages/astro/autodoc/src/components/AutodocFunction.astro

@@ -0,0 +1,16 @@
+---
+import '../styles.css'
+import Docstring from './Docstring.astro'
+import { formatSignature, slugify } from '../utils'
+
+const { fn, label } = Astro.props
+const anchor = slugify(fn.qualname)
+const title = label ?? fn.name
+const signature = formatSignature(fn.signature, fn.returns)
+---
+
+<section id={anchor} class="autodoc-card autodoc">
+  <div class="autodoc-title">{title}</div>
+  <div class="autodoc-signature">{signature}</div>
+  <Docstring value={fn.docstring} />
+</section>