Add richer documentation, supported by Docusaurus

Start by inventorying the existing docs/.md files, README.md, .github/agents/.agent.md, and .github/skills/*/SKILL.md files, then review the proposed docs-site/ structure and Docusaurus configuration needs. Done means the documentation site builds and deploys through .github/workflows/docs-deploy.yml, existing content is migrated, reference pages stay synchronized, search works, and the landing page and initial blog post are present.

Motivation

Git-Ape's documentation currently lives in docs/ as standalone Markdown files (EXAMPLES.md, ONBOARDING.md, DEPLOYMENT_STATE.md, etc.) and a basic README.md. There is no structured documentation site, no searchable wiki, and no versioned docs. As the project grows with manifesto alignment work (#39), the documentation surface area will expand significantly (ADRs, blueprints, org-level patterns, OPA policies, SRE runbooks, etc.).

A Docusaurus site on GitHub Pages provides:

• Searchable, navigable documentation
• Versioned docs tied to releases
• API/skill reference pages auto-generated from SKILL.md files
• Blog section for release notes and updates
• Dark mode, responsive design, and a professional landing page

Proposed Work

1. Docusaurus Setup

• Initialize Docusaurus project in docs-site/ (or website/)
• Configure for GitHub Pages deployment (Azure.github.io/git-ape-private or custom domain)
• GitHub Actions workflow for automatic build and deploy on push to main

2. Documentation Structure

docs-site/
├── docs/
│   ├── getting-started/
│   │   ├── introduction.md        ← What is Git-Ape
│   │   ├── quickstart.md          ← 5-minute first deployment
│   │   ├── installation.md        ← CLI plugin + VS Code extension
│   │   └── prerequisites.md       ← Required tools and auth
│   │
│   ├── guides/
│   │   ├── deployment-workflow.md ← Full 4-stage pipeline walkthrough
│   │   ├── onboarding.md         ← OIDC, RBAC, GitHub environments
│   │   ├── drift-detection.md    ← Manual and scheduled drift
│   │   ├── headless-mode.md      ← Coding Agent / GitHub Actions
│   │   ├── cost-management.md    ← Cost estimation and budget gates
│   │   ├── security-gates.md     ← Security analysis and gate enforcement
│   │   └── blueprints.md         ← Golden-path reference architectures
│   │
│   ├── reference/
│   │   ├── agents/               ← Auto-generated from .agent.md files
│   │   │   ├── git-ape.md
│   │   │   ├── requirements-gatherer.md
│   │   │   ├── template-generator.md
│   │   │   └── ...
│   │   ├── skills/               ← Auto-generated from SKILL.md files
│   │   │   ├── arm-checkov.md
│   │   │   ├── azure-naming-research.md
│   │   │   └── ...
│   │   ├── workflows/            ← CI/CD workflow reference
│   │   ├── deployment-state.md   ← Artifact format and state machine
│   │   └── configuration.md     ← All configuration options
│   │
│   ├── architecture/
│   │   ├── overview.md           ← System architecture and design
│   │   ├── manifesto.md          ← Manifesto alignment and vision
│   │   ├── adrs/                 ← Architecture Decision Records (relates to #42)
│   │   └── security-model.md    ← Security analysis integrity rules
│   │
│   └── contributing/
│       ├── development.md        ← Dev setup, testing, PR process
│       ├── adding-skills.md      ← How to create new skills
│       ├── adding-agents.md      ← How to create new agents
│       └── adding-blueprints.md  ← How to create golden-path blueprints
│
├── blog/
│   └── 2026-04-15-manifesto-alignment.md  ← Release notes / updates
│
├── src/
│   └── pages/
│       └── index.tsx             ← Landing page with hero, features, CTA
│
├── static/
│   └── img/                      ← Logo, diagrams, screenshots
│
├── docusaurus.config.ts
├── sidebars.ts
└── package.json

3. Auto-Generation Pipeline

• Script to sync agent descriptions from .github/agents/*.agent.md → docs/reference/agents/
• Script to sync skill descriptions from .github/skills/*/SKILL.md → docs/reference/skills/
• Run on CI to keep docs in sync with source-of-truth files

4. GitHub Pages Deployment

• GitHub Actions workflow: docs-deploy.yml
  • Trigger: push to main with changes in docs-site/, .github/agents/, or .github/skills/
  • Build Docusaurus, deploy to gh-pages branch
  • Optional: custom domain (e.g., git-ape.dev or gitape.azure.dev)

5. Landing Page

• Hero section with Git-Ape logo and tagline
• Feature cards: Security Gates, Cost Estimation, Drift Detection, IaC Scanning, Architecture Review
• Quick start CTA
• Link to manifesto blog post

6. Search

• Enable Docusaurus local search plugin (or Algolia DocSearch for larger scale?)
• Index all docs, guides, and reference pages

Migration Plan

1. Move existing docs/*.md content into the Docusaurus structure
2. Keep docs/ in repo for backward compatibility (symlink or redirect)
3. Update README.md to link to the docs site instead of inline docs
4. Update onboarding to reference the docs site

Files to Create/Modify

• docs-site/ — New Docusaurus project
• .github/workflows/docs-deploy.yml — GitHub Pages deployment workflow
• .github/scripts/sync-docs.sh — Agent/skill docs sync script
• README.md — Update to link to docs site

Acceptance Criteria

• Docusaurus site builds and deploys to GitHub Pages
• All existing documentation migrated to structured docs
• Agent and skill reference pages auto-generated from source files
• Search works across all documentation
• Landing page with project overview and quick start
• GitHub Actions workflow auto-deploys on push to main
• Docs stay in sync with agent/skill source files
• Blog section with initial post

References

• Tracking epic: #39
• Related: #42 (ADRs — architecture docs section), #44 (living docs), #46 (org-level patterns docs)
• Docusaurus: https://docusaurus.io/
• GitHub Pages: https://pages.github.com/