📚 Create APM documentation site with Astro + Starlight

[danielmeppiel]

Summary

Build a dedicated documentation site for APM using Astro + Starlight (same stack as GitHub Agentic Workflows), deployed via GitHub Pages. The site should migrate our existing 17 docs files, fill narrative gaps identified in our evangelization analysis, and establish APM as the authoritative resource for agent primitive packaging.

Motivation

APM has reached an inflection point — GitHub Next has natively integrated APM into gh-aw, and external contributors are joining. Our current docs live as raw markdown in docs/ and aren't discoverable, searchable, or linkable. A proper docs site is table stakes for:

1. Developer trust — OSS projects without docs sites signal "not production-ready"
2. Evangelization — We need a URL to point people to, not a GitHub folder
3. SEO & discoverability — Starlight generates proper HTML with metadata
4. Narrative — Our docs cover the "how" but miss the "why" (see Narrative Gaps below)

Narrative Gaps to Address

Our existing docs are technically solid but miss two critical evangelization narratives:

The Inner Loop Story (Developer → Developer)

"I keep copy-pasting the same AGENTS.md tweaks across repos. How do I share them?"

Missing content:

• "Why APM?" landing page — the 30-second pitch with before/after comparison
• "From Copy-Paste to Packages" tutorial — takes a real instruction file, packages it, installs it in another repo
• Compilation deep-dive — demo showing how apm compile deduplicates and optimizes across 5+ packages into clean AGENTS.md

The Outer Loop Story (Platform Engineer → CI Pipeline)

"Our CI agent sees developer instructions and hallucinates. How do I isolate agent context?"

Missing content:

• "APM in CI/CD" guide — using apm-action, the isolated: true mode, and why it matters
• "APM + GitHub Agentic Workflows" integration guide — how gh-aw uses APM natively, the 3-tier model
• "Instruction Pollution" explainer — the problem, why it matters, how isolated mode solves it

Scope

Phase 1: Foundation (this issue)

Site Scaffolding

• Initialize docs/ as Astro + Starlight project
• Configure astro.config.mjs with sidebar, site metadata, and base path
• Add GitHub Actions workflow for deployment to GitHub Pages
• Add favicon and APM logo/branding

Starlight Plugins (match gh-aw where useful)

• starlight-links-validator — catch broken links at build time
• starlight-llms-txt — generate LLM-readable docs (dogfooding our own narrative)
• astro-mermaid — diagram support for architecture visuals
• Skip starlight-blog for now (add when we have content to blog about)

Content Migration (existing 17 docs)

Migrate and reorganize into Starlight sidebar structure:

Introduction
├── Overview (new — the "Why APM?" pitch)
├── How It Works (from concepts.md)
└── Key Concepts (from primitives.md)

Getting Started
├── Installation (from getting-started.md)
├── Your First Package (new — quick tutorial)
└── Golden Demo (extract from README.md)

Guides
├── From Copy-Paste to Packages (new — inner loop narrative)
├── Compilation & Optimization (from compilation.md)
├── Skills & Prompts (from skills.md, prompts.md)
├── Plugins (from plugins.md)
├── Dependencies & Lockfile (from dependencies.md)
└── APM in CI/CD (new — outer loop narrative)

Integrations
├── GitHub Agentic Workflows (new — gh-aw integration story)
├── AI Runtime Compatibility (from runtime-integration.md)
└── IDE & Tool Integration (from integrations.md)

Reference
├── CLI Commands (from cli-reference.md)
├── Manifest Schema (from manifest-schema.md)
├── Primitive Types (from enhanced-primitive-discovery.md)
└── Examples (from examples.md)

Contributing
├── Development Guide (from CONTRIBUTING.md)
└── Changelog (from CHANGELOG.md)

New Content (minimum viable)

• "Why APM?" overview page — 30-second pitch, before/after, one-liner positioning
• "Your First Package" tutorial — create, publish, install in 5 minutes
• "APM in CI/CD" guide — apm-action, isolated mode, instruction pollution problem
• "APM + GitHub Agentic Workflows" integration page — how gh-aw uses APM, the vision

Phase 2: Polish (follow-up issues)

• Diagrams and architecture visuals (mermaid)
• Blog section with launch post
• Search integration
• FAQ / Troubleshooting section
• API/programmatic usage reference
• Video/GIF demos embedded in key pages

Technical Specification

Stack

Component	Choice	Rationale
Framework	Astro 5.x	Same as gh-aw, modern SSG
Theme	Starlight	Purpose-built for docs, accessible, fast
Deployment	GitHub Pages via Actions	Free, integrated, same as gh-aw
Node version	22+ LTS	Match gh-aw

Project Structure

docs/
├── astro.config.mjs
├── package.json
├── tsconfig.json
├── public/
│   ├── favicon.svg
│   └── og-image.png
└── src/
    ├── assets/
    │   └── logo.svg
    └── content/
        └── docs/
            ├── index.mdx
            ├── introduction/
            ├── getting-started/
            ├── guides/
            ├── integrations/
            ├── reference/
            └── contributing/

GitHub Actions Workflow

name: Deploy Docs
on:
  push:
    branches: [main]
    paths: ['docs/**']
  pull_request:
    paths: ['docs/**']

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
        working-directory: docs
      - run: npm run build
        working-directory: docs
      - uses: actions/upload-pages-artifact@v3
        with:
          path: docs/dist

  deploy:
    needs: build
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
    steps:
      - uses: actions/deploy-pages@v4

Definition of Done

• npm run build succeeds with zero link validation errors
• Site deploys to GitHub Pages on push to main
• All 17 existing docs migrated and accessible
• 4 new narrative pages written (Why APM, First Package, CI/CD, gh-aw Integration)
• Sidebar navigation matches the structure above
• llms.txt generated for LLM-readable docs
• Mobile-responsive and accessible (Starlight defaults)
• PR links validated — no broken internal links

References

• gh-aw docs site — reference implementation
• Starlight docs — framework documentation
• Existing APM docs — content to migrate
• APM + gh-aw integration proposal — integration narrative source