docs: starlight site

AGENTS.md

@@ -52,6 +52,8 @@ Every compiled pipeline runs as three sequential jobs:
 │   │   ├── common.rs     # Shared helpers across targets
 │   │   ├── standalone.rs # Standalone pipeline compiler
 │   │   ├── onees.rs      # 1ES Pipeline Template compiler
+│   │   ├── job.rs        # Job-level ADO template compiler (target: job)
+│   │   ├── stage.rs      # Stage-level ADO template compiler (target: stage)
 │   │   ├── gitattributes.rs # .gitattributes management for compiled pipelines
 │   │   ├── filter_ir.rs  # Filter expression IR: Fact/Predicate types, lowering, validation, codegen
 │   │   ├── pr_filters.rs # PR trigger filter generation (native ADO + gate steps)
@@ -122,6 +124,8 @@ Every compiled pipeline runs as three sequential jobs:
 │   ├── data/
 │   │   ├── base.yml          # Base pipeline template for standalone
 │   │   ├── 1es-base.yml      # Base pipeline template for 1ES target
+│   │   ├── job-base.yml      # Job-level ADO template for target: job
+│   │   ├── stage-base.yml    # Stage-level ADO template for target: stage
 │   │   ├── ecosystem_domains.json # Network allowlists per ecosystem
 │   │   ├── init-agent.md     # Dispatcher agent template for `init` command
 │   │   └── threat-analysis.md # Threat detection analysis prompt template

docs-site/.github/workflows/deploy-docs.yml

@@ -0,0 +1,50 @@
+name: Deploy Docs to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths: ['docs-site/**']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: docs-site/package-lock.json
+
+      - name: Install dependencies
+        working-directory: docs-site
+        run: npm ci
+
+      - name: Build site
+        working-directory: docs-site
+        run: npm run build
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs-site/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

docs-site/.gitignore

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

docs-site/astro.config.mjs

@@ -0,0 +1,78 @@
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import sitemap from '@astrojs/sitemap';
+import starlightLlmsTxt from 'starlight-llms-txt';
+import starlightLinksValidator from 'starlight-links-validator';
+import mermaid from 'astro-mermaid';
+
+export default defineConfig({
+  site: 'https://githubnext.github.io',
+  base: '/ado-aw/',
+  trailingSlash: 'always',
+  integrations: [
+    mermaid({ autoTheme: true }),
+    starlight({
+      title: 'ado-aw',
+      description: 'Compile natural-language markdown into Azure DevOps agentic pipelines',
+      plugins: [
+        starlightLlmsTxt(),
+        starlightLinksValidator(),
+      ],
+      customCss: ['./src/styles/custom.css'],
+      components: {
+        Head: './src/components/CustomHead.astro',
+      },
+      tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 4 },
+      social: [
+        { icon: 'github', label: 'GitHub', href: 'https://github.com/githubnext/ado-aw' },
+      ],
+      sidebar: [
+        {
+          label: 'Introduction',
+          autogenerate: { directory: 'introduction' },
+        },
+        {
+          label: 'Setup',
+          items: [
+            { label: 'Quick Start', slug: 'setup/quick-start' },
+            { label: 'CLI Commands', slug: 'setup/cli' },
+            { label: 'Local Development', slug: 'setup/local-development' },
+          ],
+        },
+        {
+          label: 'Guides',
+          items: [
+            { label: 'Creating Agents', slug: 'guides/creating-agents' },
+            { label: 'Network Configuration', slug: 'guides/network-config' },
+            { label: 'Schedule Syntax', slug: 'guides/schedule-syntax' },
+            { label: 'Using MCP', slug: 'guides/using-mcp' },
+            { label: 'Extending the Compiler', slug: 'guides/extending' },
+          ],
+        },
+        {
+          label: 'Reference',
+          items: [
+            { label: 'Front Matter', slug: 'reference/front-matter' },
+            { label: 'Engine', slug: 'reference/engine' },
+            { label: 'Parameters', slug: 'reference/parameters' },
+            { label: 'Tools', slug: 'reference/tools' },
+            { label: 'Runtimes', slug: 'reference/runtimes' },
+            { label: 'Safe Outputs', slug: 'reference/safe-outputs' },
+            { label: 'Targets', slug: 'reference/targets' },
+            { label: 'Network', slug: 'reference/network' },
+            { label: 'MCP', slug: 'reference/mcp' },
+            { label: 'MCP Gateway', slug: 'reference/mcpg' },
+            { label: 'Template Markers', slug: 'reference/template-markers' },
+            { label: 'Filter IR', slug: 'reference/filter-ir' },
+            { label: 'Codemods', slug: 'reference/codemods' },
+          ],
+        },
+        {
+          label: 'Troubleshooting',
+          autogenerate: { directory: 'troubleshooting' },
+        },
+      ],
+    }),
+    sitemap(),
+  ],
+});