feat: GitHub Pages docs site with MkDocs Material (closes #347)

.github/workflows/docs.yml

@@ -0,0 +1,57 @@
+name: Deploy docs to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'site/**'
+      - 'mkdocs.yml'
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install MkDocs Material
+        run: pip install mkdocs-material mkdocs-minify-plugin
+
+      - name: Copy source docs
+        run: bash scripts/build-docs.sh
+
+      - name: Build docs
+        run: mkdocs build --config-file mkdocs.yml --site-dir _site
+        env:
+          SITE_URL: https://microsoft.github.io/agent-governance-toolkit
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -454,3 +454,4 @@ FodyWeavers.xsd
 *.token
 .env
 .env.*
+_site/

mkdocs.yml

@@ -0,0 +1,142 @@
+site_name: Agent Governance Toolkit
+site_description: Governance, trust, identity, and compliance for AI agents
+site_url: https://microsoft.github.io/agent-governance-toolkit
+repo_url: https://github.com/microsoft/agent-governance-toolkit
+repo_name: microsoft/agent-governance-toolkit
+edit_uri: edit/main/site/docs/
+docs_dir: site/docs
+
+theme:
+  name: material
+  palette:
+    - scheme: default
+      primary: indigo
+      accent: teal
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: indigo
+      accent: teal
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.sections
+    - navigation.expand
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.code.copy
+    - content.tabs.link
+    - toc.follow
+  icon:
+    repo: fontawesome/brands/github
+  font:
+    text: Inter
+    code: JetBrains Mono
+
+plugins:
+  - search
+  - minify:
+      minify_html: true
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - attr_list
+  - md_in_html
+  - tables
+  - toc:
+      permalink: true
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/microsoft/agent-governance-toolkit
+  generator: false
+
+nav:
+  - Home: index.md
+  - Getting Started:
+    - Quick Start: quickstart.md
+    - Architecture: architecture.md
+    - Glossary: glossary.md
+  - Packages:
+    - Overview: packages/index.md
+    - Agent OS: packages/agent-os.md
+    - Agent Mesh: packages/agent-mesh.md
+    - Agent Runtime: packages/agent-runtime.md
+    - Agent SRE: packages/agent-sre.md
+    - Agent Compliance: packages/agent-compliance.md
+    - Agent Marketplace: packages/agent-marketplace.md
+    - Agent Lightning: packages/agent-lightning.md
+    - Agent Hypervisor: packages/agent-hypervisor.md
+    - .NET SDK: packages/agent-governance-dotnet.md
+    - VS Code Extension: packages/agent-os-vscode.md
+  - Tutorials:
+    - Overview: tutorials/index.md
+    - Policy Engine: tutorials/01-policy-engine.md
+    - Trust & Identity: tutorials/02-trust-and-identity.md
+    - Framework Integrations: tutorials/03-framework-integrations.md
+    - Audit & Compliance: tutorials/04-audit-and-compliance.md
+    - Agent Reliability: tutorials/05-agent-reliability.md
+    - Execution Sandboxing: tutorials/06-execution-sandboxing.md
+    - MCP Security Gateway: tutorials/07-mcp-security-gateway.md
+    - OPA / Rego / Cedar Policies: tutorials/08-opa-rego-cedar-policies.md
+    - Prompt Injection Detection: tutorials/09-prompt-injection-detection.md
+    - Plugin Marketplace: tutorials/10-plugin-marketplace.md
+    - Saga Orchestration: tutorials/11-saga-orchestration.md
+    - Liability & Attribution: tutorials/12-liability-and-attribution.md
+    - Observability & Tracing: tutorials/13-observability-and-tracing.md
+    - Kill Switch & Rate Limiting: tutorials/14-kill-switch-and-rate-limiting.md
+    - RL Training Governance: tutorials/15-rl-training-governance.md
+    - Protocol Bridges: tutorials/16-protocol-bridges.md
+    - Advanced Trust: tutorials/17-advanced-trust-and-behavior.md
+    - Compliance Verification: tutorials/18-compliance-verification.md
+    - .NET SDK: tutorials/19-dotnet-sdk.md
+    - TypeScript SDK: tutorials/20-typescript-sdk.md
+    - Rust SDK: tutorials/21-rust-sdk.md
+    - Go SDK: tutorials/22-go-sdk.md
+    - Delegation Chains: tutorials/23-delegation-chains.md
+    - Cost & Token Budgets: tutorials/24-cost-and-token-budgets.md
+    - Security Hardening: tutorials/25-security-hardening.md
+    - SBOM & Signing: tutorials/26-sbom-and-signing.md
+    - MCP Scan CLI: tutorials/27-mcp-scan-cli.md
+  - Deployment:
+    - Overview: deployment/index.md
+    - Azure Container Apps: deployment/azure-container-apps.md
+    - Azure Foundry Agent Service: deployment/azure-foundry-agent-service.md
+    - OpenClaw Sidecar: deployment/openclaw-sidecar.md
+    - Private Endpoints: deployment/private-endpoints.md
+  - Security:
+    - Threat Model: security/threat-model.md
+    - OWASP Compliance: security/owasp-compliance.md
+    - Security Scanning: security/scanning.md
+    - Tenant Isolation: security/tenant-isolation.md
+  - Architecture Decisions:
+    - Overview: adr/index.md
+    - "ADR-0001: Ed25519 for Identity": adr/0001-use-ed25519-for-agent-identity.md
+    - "ADR-0002: Four Execution Rings": adr/0002-use-four-execution-rings-for-runtime-privilege.md
+    - "ADR-0003: IATP Handshake 200ms": adr/0003-keep-iatp-handshake-within-200ms.md
+    - "ADR-0004: Deterministic Policy": adr/0004-keep-policy-evaluation-deterministic.md
+  - Reference:
+    - Benchmarks: reference/benchmarks.md
+    - Comparison: reference/comparison.md
+    - NIST RFI Mapping: reference/nist-rfi-mapping.md
+    - Changelog: reference/changelog.md
+    - Contributing: reference/contributing.md

scripts/build-docs.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# Build script for MkDocs documentation site.
+# Copies existing docs into site/docs/ so content is maintained in one place.
+# Run this before `mkdocs build` or let the GitHub Actions workflow handle it.
+
+set -e
+
+SITE_DOCS="site/docs"
+
+echo "Copying docs to $SITE_DOCS..."
+
+# Create directories
+mkdir -p "$SITE_DOCS"/{packages,tutorials,deployment,security,adr,reference}
+
+# Top-level docs
+cp QUICKSTART.md "$SITE_DOCS/quickstart.md"
+cp docs/ARCHITECTURE.md "$SITE_DOCS/architecture.md"
+cp docs/GLOSSARY.md "$SITE_DOCS/glossary.md"
+
+# Tutorials
+cp docs/tutorials/*.md "$SITE_DOCS/tutorials/"
+
+# Deployment
+cp docs/deployment/*.md "$SITE_DOCS/deployment/"
+
+# Security
+cp docs/THREAT_MODEL.md "$SITE_DOCS/security/threat-model.md"
+cp docs/OWASP-COMPLIANCE.md "$SITE_DOCS/security/owasp-compliance.md"
+cp docs/security-scanning.md "$SITE_DOCS/security/scanning.md"
+cp docs/security/tenant-isolation-checklist.md "$SITE_DOCS/security/tenant-isolation.md"
+
+# ADRs
+cp docs/adr/*.md "$SITE_DOCS/adr/"
+
+# Reference
+cp BENCHMARKS.md "$SITE_DOCS/reference/benchmarks.md"
+cp docs/COMPARISON.md "$SITE_DOCS/reference/comparison.md"
+cp docs/nist-rfi-mapping.md "$SITE_DOCS/reference/nist-rfi-mapping.md"
+cp CHANGELOG.md "$SITE_DOCS/reference/changelog.md"
+cp CONTRIBUTING.md "$SITE_DOCS/reference/contributing.md"
+
+# Package READMEs
+for pkg in agent-os agent-mesh agent-runtime agent-sre agent-compliance agent-marketplace agent-lightning agent-hypervisor agent-governance-dotnet agent-os-vscode; do
+  if [ -f "packages/$pkg/README.md" ]; then
+    cp "packages/$pkg/README.md" "$SITE_DOCS/packages/$pkg.md"
+  fi
+done
+
+echo "Done. $(find $SITE_DOCS -name '*.md' | wc -l | tr -d ' ') pages ready."

site/docs/.gitignore

@@ -0,0 +1,23 @@
+# These files are copied from source by scripts/build-docs.sh at build time.
+# Only index pages and the landing page are committed.
+quickstart.md
+architecture.md
+glossary.md
+tutorials/[0-9]*.md
+tutorials/README.md
+deployment/README.md
+deployment/azure-*.md
+deployment/openclaw-*.md
+deployment/private-*.md
+security/threat-model.md
+security/owasp-compliance.md
+security/scanning.md
+security/tenant-isolation.md
+adr/0*.md
+adr/README.md
+reference/benchmarks.md
+reference/comparison.md
+reference/nist-rfi-mapping.md
+reference/changelog.md
+reference/contributing.md
+packages/agent-*.md

site/docs/adr/index.md

@@ -0,0 +1,10 @@
+# Architecture Decision Records
+
+Key architectural decisions and their rationale.
+
+| ADR | Decision |
+|-----|----------|
+| [ADR-0001](0001-use-ed25519-for-agent-identity.md) | Use Ed25519 for agent identity signatures |
+| [ADR-0002](0002-use-four-execution-rings-for-runtime-privilege.md) | Four execution rings for runtime privilege separation |
+| [ADR-0003](0003-keep-iatp-handshake-within-200ms.md) | Keep IATP handshake under 200ms |
+| [ADR-0004](0004-keep-policy-evaluation-deterministic.md) | Keep policy evaluation deterministic |

site/docs/deployment/index.md

@@ -0,0 +1,10 @@
+# Deployment Guides
+
+Deploy AGT across Azure services and container platforms.
+
+| Guide | Platform |
+|-------|----------|
+| [Azure Container Apps](azure-container-apps.md) | Managed containers on Azure |
+| [Azure Foundry Agent Service](azure-foundry-agent-service.md) | Foundry-native agent hosting |
+| [OpenClaw Sidecar](openclaw-sidecar.md) | Sidecar deployment pattern |
+| [Private Endpoints](private-endpoints.md) | Secure networking with private links |

site/docs/index.md

@@ -0,0 +1,51 @@
+# Agent Governance Toolkit
+
+**Governance, trust, identity, and compliance for AI agents.**
+
+The Agent Governance Toolkit (AGT) provides a comprehensive set of packages for building governed, trustworthy AI agent systems. It covers the full lifecycle: policy enforcement, identity management, runtime sandboxing, reliability engineering, compliance verification, and marketplace governance.
+
+## Quick Links
+
+| | |
+|---|---|
+| :material-rocket-launch: [**Quick Start**](quickstart.md) | Get running in 5 minutes |
+| :material-cube-outline: [**Packages**](packages/index.md) | 11 packages for every governance layer |
+| :material-school: [**Tutorials**](tutorials/index.md) | 27 step-by-step guides |
+| :material-cloud-upload: [**Deployment**](deployment/index.md) | Azure Container Apps, Foundry, OpenClaw |
+| :material-shield-check: [**Security**](security/threat-model.md) | Threat model, OWASP compliance, scanning |
+
+## Packages at a Glance
+
+| Package | Purpose |
+|---------|---------|
+| [Agent OS](packages/agent-os.md) | Core policy engine and agent lifecycle management |
+| [Agent Mesh](packages/agent-mesh.md) | Agent discovery, routing, and trust mesh |
+| [Agent Runtime](packages/agent-runtime.md) | Execution sandboxing with privilege rings |
+| [Agent SRE](packages/agent-sre.md) | Reliability: kill switch, SLO monitoring, chaos testing |
+| [Agent Compliance](packages/agent-compliance.md) | Audit logging, compliance frameworks, evidence collection |
+| [Agent Marketplace](packages/agent-marketplace.md) | Plugin governance and marketplace trust |
+| [Agent Lightning](packages/agent-lightning.md) | High-performance agent orchestration |
+| [Agent Hypervisor](packages/agent-hypervisor.md) | Hardware-level isolation for agent workloads |
+
+## Examples
+
+Governed examples for popular AI agent frameworks:
+
+| Example | Framework | What it demonstrates |
+|---------|-----------|---------------------|
+| [openai-agents-governed](https://github.com/microsoft/agent-governance-toolkit/tree/main/examples/openai-agents-governed) | OpenAI Agents SDK | Policy-gated tool calls with trust tiers |
+| [crewai-governed](https://github.com/microsoft/agent-governance-toolkit/tree/main/examples/crewai-governed) | CrewAI | Multi-agent governance with role-based policies |
+| [smolagents-governed](https://github.com/microsoft/agent-governance-toolkit/tree/main/examples/smolagents-governed) | HuggingFace smolagents | Lightweight agent governance |
+| [protect-mcp-governed](https://github.com/microsoft/agent-governance-toolkit/tree/main/examples/protect-mcp-governed) | protect-mcp | Cedar policies + Ed25519 signed receipts for MCP tool calls |
+| [physical-attestation-governed](https://github.com/microsoft/agent-governance-toolkit/tree/main/examples/physical-attestation-governed) | Physical sensors | Cold chain sensor attestation (temperature, shock, GPS) |
+| [openshell-governed](https://github.com/microsoft/agent-governance-toolkit/tree/main/examples/openshell-governed) | OpenShell | Sandboxed shell execution governance |
+| [mcp-trust-verified-server](https://github.com/microsoft/agent-governance-toolkit/tree/main/examples/mcp-trust-verified-server) | MCP | Trust-verified MCP server implementation |
+| [maf-integration](https://github.com/microsoft/agent-governance-toolkit/tree/main/examples/maf-integration) | MAF | Microsoft Agent Framework integration |
+| [marketplace-governance](https://github.com/microsoft/agent-governance-toolkit/tree/main/examples/marketplace-governance) | Marketplace | Plugin governance and trust scoring |
+| [atr-community-rules](https://github.com/microsoft/agent-governance-toolkit/tree/main/examples/atr-community-rules) | ATR | Community-contributed governance rules |
+
+## Standards
+
+- **OWASP Agentic AI Top 10** — [compliance mapping](security/owasp-compliance.md)
+- **NIST AI RMF** — [RFI response](reference/nist-rfi-mapping.md)
+- **Ed25519 (RFC 8032)** — [ADR-0001](adr/0001-use-ed25519-for-agent-identity.md)

site/docs/packages/index.md

@@ -0,0 +1,43 @@
+# Packages
+
+AGT provides 11 packages covering every layer of agent governance.
+
+```
++------------------+     +------------------+     +------------------+
+|    Agent OS      |     |   Agent Mesh     |     |  Agent Runtime   |
+|  Policy engine   |     |  Discovery &     |     |  Sandboxing &    |
+|  & lifecycle     |     |  trust mesh      |     |  privilege rings  |
++------------------+     +------------------+     +------------------+
+        |                        |                        |
++------------------+     +------------------+     +------------------+
+|   Agent SRE      |     | Agent Compliance |     | Agent Marketplace|
+|  Reliability &   |     |  Audit logging   |     |  Plugin trust    |
+|  monitoring      |     |  & frameworks    |     |  & governance    |
++------------------+     +------------------+     +------------------+
+        |                        |                        |
++------------------+     +------------------+     +------------------+
+| Agent Lightning  |     | Agent Hypervisor |     |   SDK Packages   |
+|  High-perf       |     |  HW isolation    |     |  .NET, TS, Rust  |
+|  orchestration   |     |  for workloads   |     |  Go, VS Code     |
++------------------+     +------------------+     +------------------+
+```
+
+## Core Packages
+
+| Package | Description | Install |
+|---------|------------|---------|
+| [Agent OS](agent-os.md) | Policy engine, agent lifecycle, governance gate | `pip install agent-os` |
+| [Agent Mesh](agent-mesh.md) | Agent discovery, routing, trust mesh | `pip install agent-mesh` |
+| [Agent Runtime](agent-runtime.md) | Execution sandboxing, four privilege rings | `pip install agent-runtime` |
+| [Agent SRE](agent-sre.md) | Kill switch, SLO monitoring, chaos testing | `pip install agent-sre` |
+| [Agent Compliance](agent-compliance.md) | Audit logging, compliance frameworks | `pip install agent-compliance` |
+| [Agent Marketplace](agent-marketplace.md) | Plugin governance, marketplace trust | `pip install agent-marketplace` |
+| [Agent Lightning](agent-lightning.md) | High-performance orchestration | `pip install agent-lightning` |
+| [Agent Hypervisor](agent-hypervisor.md) | Hardware-level workload isolation | `pip install agent-hypervisor` |
+
+## SDK Packages
+
+| Package | Language | Install |
+|---------|---------|---------|
+| [.NET SDK](agent-governance-dotnet.md) | C# / .NET | `dotnet add package AgentGovernance` |
+| [VS Code Extension](agent-os-vscode.md) | VS Code | Install from marketplace |