Squad/docs astro rewrite

.github/workflows/squad-docs.yml

@@ -26,12 +26,16 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: '22'
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
 
-      - name: Install build dependencies
-        run: npm install --no-save markdown-it markdown-it-anchor
+      - name: Install docs dependencies
+        working-directory: docs
+        run: npm ci
 
       - name: Build docs site
-        run: node docs/build.js
+        working-directory: docs
+        run: npm run build
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3

.squad-templates/workflows/squad-docs.yml

@@ -26,17 +26,21 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: '22'
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
 
-      - name: Install build dependencies
-        run: npm install --no-save markdown-it markdown-it-anchor
+      - name: Install docs dependencies
+        working-directory: docs
+        run: npm ci
 
       - name: Build docs site
-        run: node docs/build.js --out _site --base /squad
+        working-directory: docs
+        run: npm run build
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: _site
+          path: docs/dist
 
   deploy:
     needs: build

docs/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+.astro/

docs/README.md

@@ -1,74 +1,105 @@
-# Squad Documentation
-
-Public-facing documentation for Squad. GitHub Pages ready.
-
-## Guides
-
-- [Product Guide](guide.md) — Complete reference for all Squad features
-- [Sample Prompts](sample-prompts.md) — Ready-to-use prompts showing what Squad can do
-
-## Feature Reference
-
-### Core
-- [Team Setup](features/team-setup.md) — Init mode, first session, team creation
-- [Work Routing](features/routing.md) — How work gets assigned to agents
-- [Parallel Execution](features/parallel-execution.md) — Background vs sync, fan-out
-- [Response Modes](features/response-modes.md) — Tiered response speed/depth
-- [Memory System](features/memory.md) — How agents learn and remember
-- [Directives](features/directives.md) — Capturing team rules and preferences
-- [Reviewer Protocol](features/reviewer-protocol.md) — Rejection lockout and revision routing
-
-### Workflow
-- [GitHub Issues Mode](features/github-issues.md) — GitHub issue-driven development
-- [GitLab Issues Mode](features/gitlab-issues.md) — 🧪 *Experimental* — GitLab issue-driven development
-- [PRD Mode](features/prd-mode.md) — Product requirements decomposition
-- [Labels & Triage](features/labels.md) — go:/release:/type:/priority: taxonomy
-- [Ralph — Work Monitor](features/ralph.md) — Autonomous backlog processing
-- [Project Boards](features/project-boards.md) — GitHub Projects V2 integration
-
-### Team
-- [Human Team Members](features/human-team-members.md) — Mixed AI/human teams
-- [@copilot Coding Agent](features/copilot-coding-agent.md) — Autonomous issue agent
-- [Skills System](features/skills.md) — Earned knowledge with confidence lifecycle
-- [Ceremonies](features/ceremonies.md) — Team meetings and rituals
-- [Notifications](features/notifications.md) — Ping via Teams/MCP
-
-### Infrastructure
-- [Per-Agent Model Selection](features/model-selection.md) — Cost-first model routing
-- [Git Worktrees](features/worktrees.md) — Multi-branch team state
-- [Export & Import](features/export-import.md) — Portable team snapshots
-
-## Walkthroughs
-
-- [First Session](tour-first-session.md) — Your first time using Squad
-- [GitHub Issues](tour-github-issues.md) — GitHub issue-driven development walkthrough
-- [GitLab Issues](tour-gitlab-issues.md) — 🧪 *Experimental* — GitLab issue-driven development walkthrough 
-
-## Scenarios
-
-### Getting Started
-- [Starting a New Project](scenarios/new-project.md) — Greenfield setup
-- [Adding to an Existing Repo](scenarios/existing-repo.md) — Drop Squad into existing code
-- [Mid-Project Onboarding](scenarios/mid-project.md) — Adding Squad halfway through
-- [Upgrading Squad](scenarios/upgrading.md) — Update to the latest version
-
-### Team Management
-- [Solo Developer](scenarios/solo-dev.md) — Is Squad overkill for one person?
-- [Mixed Human + AI Team](scenarios/team-of-humans.md) — Humans and agents working together
-- [Keeping Your Squad](scenarios/keep-my-squad.md) — Persistence across projects
-- [Combining Old Squads](scenarios/multiple-squads.md) — Cherry-picking from multiple teams
-
-### Project Types
-- [Large Codebases](scenarios/large-codebase.md) — Will Squad choke on a big repo?
-- [Monorepos](scenarios/monorepo.md) — Multiple services, one squad
-- [Open Source Projects](scenarios/open-source.md) — Triage, contributors, community
-
-### Operations
-- [Client Compatibility Matrix](scenarios/client-compatibility.md) — What works on CLI, VS Code, JetBrains, GitHub.com
-- [Issue-Driven Development](scenarios/issue-driven-dev.md) — End-to-end issue workflow
-- [CI/CD Integration](scenarios/ci-cd-integration.md) — Squad + GitHub Actions
-- [Moving a Team](scenarios/team-portability.md) — Export and import between repos
-- [Team State Storage](scenarios/team-state-storage.md) — Gitignore, submodules, branches, and more
-- [Model Selection Strategies](scenarios/switching-models.md) — Budget vs quality tradeoffs
-- [Privacy & Security](scenarios/private-repos.md) — What stays private
-- [Disaster Recovery](scenarios/disaster-recovery.md) — When things go wrong
+# Squad Docs
+
+The documentation site for Squad, built with [Astro](https://astro.build/), [Tailwind CSS](https://tailwindcss.com/), and [Pagefind](https://pagefind.app/) for search.
+
+## Prerequisites
+
+- Node.js 22+
+- Run `npm install` from the `docs/` directory
+
+## Commands
+
+All commands are run from the `docs/` directory, or from the repo root using the `docs:` prefix.
+
+| From `docs/` | From repo root | Description |
+|---|---|---|
+| `npm run dev` | `npm run docs:dev` | Start dev server with hot reload |
+| `npm run build` | `npm run docs:build` | Production build (Astro + Pagefind) |
+| `npm run preview` | `npm run docs:preview` | Preview the production build |
+
+## Development
+
+```bash
+npm run dev
+```
+
+Starts a local dev server at `http://localhost:4321/squad/` with hot module reloading. Changes to markdown content, layouts, and components are reflected immediately.
+
+> **Note:** Search does not work in dev mode. Pagefind indexes are only generated during `build`, so the search modal will not return results. Use `build` + `preview` to test search.
+
+## Build
+
+```bash
+npm run build
+```
+
+Runs two steps:
+
+1. **`astro build`** — Compiles all pages to static HTML in `dist/`
+2. **`npx pagefind --site dist`** — Indexes the HTML output to generate the search index at `dist/pagefind/`
+
+The output in `dist/` is what gets deployed to GitHub Pages.
+
+## Preview
+
+```bash
+npm run preview
+```
+
+Serves the `dist/` directory locally so you can verify the production build, including working search.
+
+## Search
+
+Search is powered by [Pagefind](https://pagefind.app/), a static search library that indexes the built HTML.
+
+- **Dev mode:** Search UI appears but returns no results (no index exists).
+- **Build + Preview:** Search works fully. The build step generates the Pagefind index, and preview serves it.
+- **Only pages with `data-pagefind-body`** are indexed. This attribute is set on the `<article>` element in `DocsLayout.astro` and the blog post template.
+
+## Project Structure
+
+```
+docs/
+├── astro.config.mjs        # Astro configuration (site, base path, plugins)
+├── package.json             # Docs-specific dependencies
+├── src/
+│   ├── components/          # Astro components (Header, Sidebar, Search, etc.)
+│   ├── content/
+│   │   ├── blog/            # Blog posts (markdown)
+│   │   └── docs/            # Documentation articles (markdown)
+│   │       ├── concepts/
+│   │       ├── cookbook/
+│   │       ├── features/
+│   │       ├── get-started/
+│   │       ├── guide/
+│   │       ├── reference/
+│   │       └── scenarios/
+│   ├── layouts/             # Page layouts (BaseLayout, DocsLayout)
+│   ├── navigation.ts        # Sidebar navigation structure
+│   ├── pages/               # Astro page routes
+│   ├── plugins/             # Remark plugins (link rewriting)
+│   └── styles/              # Global CSS (Tailwind)
+├── public/                  # Static assets (images)
+└── dist/                    # Build output (gitignored)
+```
+
+## Adding a Doc Page
+
+1. Create a markdown file under `src/content/docs/{section}/your-page.md`
+2. Add a sidebar entry in `src/navigation.ts` under the appropriate `NAV_SECTIONS` section
+3. Run the docs build test to verify: `npx vitest run test/docs-build.test.ts` (from repo root)
+
+## Adding a Blog Post
+
+Create a markdown file under `src/content/blog/` with frontmatter:
+
+```markdown
+---
+title: "Your Post Title"
+date: 2026-03-08
+---
+
+Post content here.
+```
+
+Blog posts are automatically discovered and listed on the blog index page.

docs/specs/platform-adapter-prd.md → docs/_internal/specs/platform-adapter-prd.md

@@ -1,61 +1,61 @@
-# Platform Adapter — Design Spec
-
-## Overview
-
-The Platform Adapter abstraction allows Squad to work with multiple source code hosting platforms (GitHub, Azure DevOps) through a unified interface. This enables Ralph and the coordinator to use the same triage/assignment logic regardless of the underlying platform.
-
-## Design Decisions
-
-### 1. Interface-based abstraction
-
-We use a TypeScript interface (`PlatformAdapter`) rather than an abstract class. This keeps the contract pure and allows each adapter to manage its own dependencies independently.
-
-### 2. CLI-based implementations
-
-Both adapters wrap CLI tools (`gh` for GitHub, `az` for ADO) rather than using REST APIs directly. This:
-- Leverages existing authentication (users are already logged into `gh`/`az`)
-- Avoids managing OAuth tokens, PATs, or refresh flows
-- Matches how Squad already interacts with GitHub
-
-### 3. Auto-detection from git remote
-
-Platform detection reads the `origin` remote URL. This is zero-config — users don't need to specify which platform they're on.
-
-### 4. Graceful failure
-
-If the required CLI is not installed, the adapter throws a descriptive error with installation instructions rather than a cryptic exec failure.
-
-## Mapping Table
-
-| Concept | GitHub | Azure DevOps |
-|---|---|---|
-| Work item | Issue | Work Item |
-| Work item query | `gh issue list --label X` | WIQL via `az boards query` |
-| Work item tags | Labels | Tags (`;`-separated) |
-| Pull request list | `gh pr list` | `az repos pr list` |
-| Pull request create | `gh pr create` | `az repos pr create` |
-| Pull request merge | `gh pr merge` | `az repos pr update --status completed` |
-| Branch create | `git checkout -b` | `git checkout -b` |
-| Review status | `reviewDecision` field | `vote` field on reviewers |
-| Authentication | `gh auth login` | `az login` |
-
-## Module Structure
-
-```
-packages/squad-sdk/src/platform/
-├── types.ts          # PlatformType, WorkItem, PullRequest, PlatformAdapter
-├── detect.ts         # detectPlatform, parseGitHubRemote, parseAzureDevOpsRemote
-├── github.ts         # GitHubAdapter
-├── azure-devops.ts   # AzureDevOpsAdapter
-├── ralph-commands.ts # getRalphScanCommands
-└── index.ts          # Factory + barrel exports
-```
-
-## Future Work
-
-- **GitLab adapter** — Same interface, wrapping `glab` CLI
-- **Bitbucket adapter** — Same interface, wrapping Bitbucket APIs
-- **REST API fallback** — Direct API calls when CLI tools aren't available
-- **Token-based auth** — Support PAT/token auth for CI environments
-- **Pipelines abstraction** — Normalize GitHub Actions and Azure Pipelines
-- **Board view** — Normalize GitHub Projects and ADO Boards
+# Platform Adapter — Design Spec
+
+## Overview
+
+The Platform Adapter abstraction allows Squad to work with multiple source code hosting platforms (GitHub, Azure DevOps) through a unified interface. This enables Ralph and the coordinator to use the same triage/assignment logic regardless of the underlying platform.
+
+## Design Decisions
+
+### 1. Interface-based abstraction
+
+We use a TypeScript interface (`PlatformAdapter`) rather than an abstract class. This keeps the contract pure and allows each adapter to manage its own dependencies independently.
+
+### 2. CLI-based implementations
+
+Both adapters wrap CLI tools (`gh` for GitHub, `az` for ADO) rather than using REST APIs directly. This:
+- Leverages existing authentication (users are already logged into `gh`/`az`)
+- Avoids managing OAuth tokens, PATs, or refresh flows
+- Matches how Squad already interacts with GitHub
+
+### 3. Auto-detection from git remote
+
+Platform detection reads the `origin` remote URL. This is zero-config — users don't need to specify which platform they're on.
+
+### 4. Graceful failure
+
+If the required CLI is not installed, the adapter throws a descriptive error with installation instructions rather than a cryptic exec failure.
+
+## Mapping Table
+
+| Concept | GitHub | Azure DevOps |
+|---|---|---|
+| Work item | Issue | Work Item |
+| Work item query | `gh issue list --label X` | WIQL via `az boards query` |
+| Work item tags | Labels | Tags (`;`-separated) |
+| Pull request list | `gh pr list` | `az repos pr list` |
+| Pull request create | `gh pr create` | `az repos pr create` |
+| Pull request merge | `gh pr merge` | `az repos pr update --status completed` |
+| Branch create | `git checkout -b` | `git checkout -b` |
+| Review status | `reviewDecision` field | `vote` field on reviewers |
+| Authentication | `gh auth login` | `az login` |
+
+## Module Structure
+
+```
+packages/squad-sdk/src/platform/
+├── types.ts          # PlatformType, WorkItem, PullRequest, PlatformAdapter
+├── detect.ts         # detectPlatform, parseGitHubRemote, parseAzureDevOpsRemote
+├── github.ts         # GitHubAdapter
+├── azure-devops.ts   # AzureDevOpsAdapter
+├── ralph-commands.ts # getRalphScanCommands
+└── index.ts          # Factory + barrel exports
+```
+
+## Future Work
+
+- **GitLab adapter** — Same interface, wrapping `glab` CLI
+- **Bitbucket adapter** — Same interface, wrapping Bitbucket APIs
+- **REST API fallback** — Direct API calls when CLI tools aren't available
+- **Token-based auth** — Support PAT/token auth for CI environments
+- **Pipelines abstraction** — Normalize GitHub Actions and Azure Pipelines
+- **Board view** — Normalize GitHub Projects and ADO Boards