Add VitePress website with developer landing page and GitHub Pages deploy

.github/workflows/check.yml

@@ -236,6 +236,19 @@ jobs:
       - name: Typecheck, test and build Web and clients
         run: make check-web-unit
 
+  website:
+    needs: plan
+    if: needs.plan.result == 'success' && contains(fromJSON(needs.plan.outputs.jobs || '[]'), 'website')
+    runs-on: ${{ vars.OAC_USE_GITHUB_RUNNERS == 'true' && 'ubuntu-22.04' || 'blacksmith-2vcpu-ubuntu-2204' }}
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ inputs.ref || github.sha }}
+      - uses: ./.github/actions/node
+      - name: Build and test the website
+        run: make check-website
+
   web-acceptance:
     needs: [plan, web]
     if: needs.web.result == 'success' && needs.plan.result == 'success' && contains(fromJSON(needs.plan.outputs.jobs || '[]'), 'web-acceptance')
@@ -294,7 +307,7 @@ jobs:
   # Always report the required check, even when planning or a dependency fails.
   check:
     if: always()
-    needs: [plan, hygiene, distribution, backend, harness, example, web, web-acceptance, api, native, lint]
+    needs: [plan, hygiene, distribution, backend, harness, example, web, web-acceptance, website, api, native, lint]
     runs-on: ${{ vars.OAC_USE_GITHUB_RUNNERS == 'true' && 'ubuntu-22.04' || 'blacksmith-2vcpu-ubuntu-2204' }}
     timeout-minutes: 5
     steps:

.github/workflows/website.yml

@@ -0,0 +1,83 @@
+# Publishes the website (landing page and documentation) to GitHub Pages from
+# main, and builds it for documentation-only pull requests. The website reads the
+# existing docs/, contracts/ and docs.json in place; see website/README.md.
+name: website
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - website/**
+      - docs/**
+      - contracts/**
+      - docs.json
+      - package.json
+      - pnpm-lock.yaml
+      - pnpm-workspace.yaml
+      - .github/actions/node/**
+      - .github/workflows/website.yml
+  # Changes under website/ are checked by core-check; documentation-only
+  # changes build the site here so broken links surface before merge.
+  pull_request:
+    paths:
+      - docs/**
+      - contracts/**
+      - docs.json
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: website-${{ github.ref }}
+  # Never cancel a run that may be deploying main.
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build:
+    runs-on: ${{ vars.OAC_USE_GITHUB_RUNNERS == 'true' && 'ubuntu-24.04' || 'blacksmith-2vcpu-ubuntu-2404' }}
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      # configure-pages reads the site's base path.
+      pages: read
+    env:
+      PUBLISH: ${{ github.event_name != 'pull_request' && github.ref == 'refs/heads/main' }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # Full history gives each page its last-updated date.
+          fetch-depth: 0
+      - uses: ./.github/actions/node
+      - name: Read the Pages base path
+        id: pages
+        if: env.PUBLISH == 'true'
+        uses: actions/configure-pages@v6
+      - name: Build and test
+        run: make check-website
+        env:
+          WEBSITE_BASE: ${{ steps.pages.outputs.base_path }}
+      - name: Upload the site
+        if: env.PUBLISH == 'true'
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: website/.vitepress/dist
+
+  deploy:
+    needs: build
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    runs-on: ${{ vars.OAC_USE_GITHUB_RUNNERS == 'true' && 'ubuntu-24.04' || 'blacksmith-2vcpu-ubuntu-2404' }}
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    concurrency:
+      group: website-pages
+      cancel-in-progress: false
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

CONTRIBUTING.md

@@ -31,6 +31,7 @@ This guide owns how to work in the repository: documentation ownership, the repo
 | Runtime telemetry responses | [Runtime telemetry API](contracts/agents-api/runtime-observability-api.md) |
 | Runtime observation, sampling, retention and export | [Runtime observability](contracts/agents-api/runtime-observability.md) |
 | Distribution builds, Runtime image builds, CI and publication | [Maintainer guide](docs/maintainers.md) |
+| Website: landing page, documentation site build and GitHub Pages publication | [Website guide](website/README.md) |
 | Self-hosted Runtime installation, recovery and local operation | [Self-hosted execution](docs/getting-started/self-hosted.md) |
 | Installer lifecycle, locking, generated state, managed HTTPS and downloads | [Installer design rules](deploy/install/README.md) |
 | Operator installation and alternatives | [Installation](docs/getting-started/install.md), [installation options](docs/getting-started/install-options.md) |

Makefile

@@ -100,7 +100,7 @@ check-claude-sdk: node-deps
 	pnpm --filter @oac/claude-sdk-adapter test
 	$(MAKE) build-claude-sdk-runtime
 
-.PHONY: check-web-unit check-web-acceptance
+.PHONY: check-web-unit check-web-acceptance check-website
 check-web: override OAC_WEB_TEST_SHARD :=
 check-web: check-web-unit check-web-acceptance
 
@@ -109,6 +109,11 @@ check-web-unit: node-deps
 	pnpm test:web
 	pnpm --filter @oac/web build
 
+# The website build also checks every published documentation link.
+check-website: node-deps
+	pnpm --filter @oac/website build
+	pnpm --filter @oac/website test
+
 # CI shards run in separate jobs, each with its own fixture and Web server.
 # An unset shard keeps the complete local make check gate.
 check-web-acceptance: node-deps