feat: GitHub Pages docs site with static HTML generation from markdown #51

What

Create a GitHub Actions workflow that generates a beautiful static HTML documentation site from the markdown files in /docs\ and all subfolders. The workflow runs on push to \preview\ and deploys to GitHub Pages.

Why

Squad's docs are excellent markdown — but they deserve a proper web presence. Users should be able to browse docs at a clean URL with a polished reading experience, not just raw markdown on GitHub.

Requirements

Workflow

• Triggers on push to \preview\ branch
• Reads all .md\ files in \docs/\ and subfolders
• Generates static HTML files preserving the directory structure
• Deploys to GitHub Pages (using \�ctions/deploy-pages\ or equivalent)
• Fast — should complete in under 2 minutes for ~50 markdown files

Design & UX

• Dark and light mode support with system preference detection and manual toggle
• Clean, modern typography — optimized for reading long-form documentation
• Responsive — works beautifully on mobile, tablet, and desktop
• Navigation sidebar with collapsible sections matching the \docs/\ folder structure
• Syntax highlighting for code blocks (Squad has lots of YAML, JSON, bash, and JS examples)
• Search functionality (client-side is fine)
• People should love looking at the Squad docs — this is the product's public face

Content Structure

• \docs/README.md\ → site index/landing page
• \docs/guide.md\ → getting started guide
• \docs/features/\ → feature docs (sidebar section)
• \docs/scenarios/\ → scenario guides (sidebar section)
• \docs/blog/\ → blog posts (once moved from team-docs, see chore: move blogs from team-docs/blog to docs/blog, enforce naming convention #49)
• \docs/tour-*.md\ → interactive tours (sidebar section)
• \docs/tips-and-tricks.md, \docs/sample-prompts.md\ → reference section

Tech Constraints

• Prefer lightweight tooling — avoid heavy SSG frameworks if possible
• If using a generator, prefer one that can be installed via npm/npx in the workflow
• Template should be self-contained (no external CDN dependencies that could break)
• Generated HTML should work as a static site (no server required)

Acceptance Criteria

• Workflow file at .github/workflows/squad-docs.yml\ (and template copy)
• All \docs/**/*.md\ files converted to HTML with proper linking
• Dark/light mode toggle with system preference detection
• Responsive sidebar navigation
• Code syntax highlighting
• Mobile-friendly layout
• GitHub Pages deployment working from \preview\ branch
• Build completes in <2 minutes
• The docs look great — clean, modern, lovable