Add mkdocs-material documentation site

- mkdocs.yml with material theme and mkdocstrings
- Home, Quickstart
- Concepts: TCS, Capability-State Attestation, Breakpoints
- Guides: CI integration, Policy authoring, Auditor handbook
- Paper and SPEC pointer pages
- docs.yml workflow already deploys to GitHub Pages on push to main

Built with --strict, 3.4s, no warnings.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: linus131313

.gitignore

@@ -56,3 +56,4 @@ site/
 *.key
 .env
 .env.local
+site/

docs/concepts/attestation.md

@@ -0,0 +1,34 @@
+# Capability-State Attestation
+
+An **attestation** is a reproducible, signable snapshot of a host's
+runtime capability graph: what tools are bound, with what reach and
+action-level privilege, through what trust path, together with a TCS
+score, at a single point in time.
+
+The full specification lives in [`SPEC.md`](../spec.md). The pydantic
+model and the JSON Schema shipped in the wheel are the authoritative
+artefacts; the spec document tracks them.
+
+## Lifecycle
+
+1. **Collect** — parse the MCP config file (Claude Desktop, Claude
+   Code, Cursor). The source path and SHA-256 are recorded.
+2. **Classify** — each server's identity, reach, action, and
+   third-party flag are derived from a deterministic classifier with a
+   published catalogue and optional overrides.
+3. **Score** — TCS is computed with the paper's default weights; the
+   exact weights used are recorded in the attestation.
+4. **Sign** — sigstore keyless produces a Rekor-logged signature bound
+   to a GitHub OIDC identity or an email OAuth identity.
+5. **Verify** — any party can re-parse the JSON, recompute TCS, and
+   check the signature against the transparency log.
+
+## Fields
+
+See the [SPEC](../spec.md) for the full field list. The high-level
+shape is:
+
+- `host`, `config_source`
+- `tools[]` with per-tool `server`, `reach`, `action`, `resolved`
+- `tcs.value`, `tcs.weights`, `tcs.third_party_count`
+- `policy_refs[]`, `signature`

docs/concepts/breakpoints.md

@@ -0,0 +1,34 @@
+# Control Breakpoints B1–B6
+
+The six control families from Table 6 of the paper, each operationalised
+as a Python function that returns a structured `CheckResult`.
+
+| Check | Control family | Behaviour |
+|-------|----------------|-----------|
+| B1 | Change management | Diffs two attestations, flags added/removed/reclassified tools. |
+| B2 | Third-party risk | Enumerates third-party servers against an allow-list. |
+| B3 | Data loss prevention | Flags local-to-network tool compositions. |
+| B4 | Privileged access | TCS threshold + execute-capable tool enumeration. |
+| B5 | Audit and monitoring | Emits OCSF / CEF for SIEM ingestion; requires signed attestation. |
+| B6 | AI-specific capability state | Detects graph changes under a stable host version. |
+
+## Framework mapping
+
+Every check is mapped to specific clauses in the three major AI
+governance frameworks:
+
+```bash
+mcp-gov mappings list
+mcp-gov mappings show iso42001
+mcp-gov mappings show nist-ai-600-1
+mcp-gov mappings show eu-ai-act
+```
+
+## Severity
+
+Each check returns one of:
+
+- `pass` — control satisfied.
+- `info` — observation; not a policy violation.
+- `warn` — attention required; not a blocker.
+- `block` — policy violation; CI/pre-commit will fail.

docs/concepts/tcs.md

@@ -0,0 +1,40 @@
+# Tool Graph Capability Score (TCS)
+
+## Formula
+
+Given a tool graph `G` (the set of tools bound to a host), TCS is:
+
+$$
+\mathrm{TCS}(G) = \left[ \sum_{t \in G} \mathrm{reach}(t) \cdot \mathrm{action}(t) \right] \cdot \left( 1 + t_{\mathrm{coef}} \cdot T(G) \right)
+$$
+
+where
+
+- `reach(t)` is `local=1` or `network=2`,
+- `action(t)` is `read=1`, `write=2`, or `execute=3`,
+- `T(G)` is the count of third-party (non-first-party-to-the-host) servers,
+- `t_coef` defaults to `0.25`.
+
+## What TCS is, and is not
+
+TCS is a **comparability** metric, not a safety metric. Its value is
+that it is reproducible and ordinally stable: under all 48 reasonable
+reweightings tested in the paper (`w_write ∈ {1.5, 2, 2.5, 3}`,
+`w_execute ∈ {2, 3, 4, 5}`, `t_coef ∈ {0.1, 0.25, 0.5}`), the
+comparisons that matter hold — `C4 > R4` in 48/48, `C3 > R3` in 48/48,
+`C2 > R3` in 39/48. The exact ranking is preserved in 20 of the 48.
+
+You can reproduce this analysis locally:
+
+```bash
+mcp-gov tcs sensitivity
+```
+
+## Table 3 reproduction
+
+```bash
+mcp-gov tcs reference
+```
+
+The values printed match the paper to the decimal: C1=1.0, C2=9.0,
+C3=13.5, C4=49.5, C5=29.75, R1=2.0, R2=5.0, R3=7.0, R4=15.0.

docs/guides/auditor-handbook.md

@@ -0,0 +1,59 @@
+# Auditor handbook
+
+This page is written for the auditor who has never seen an MCP
+attestation before. It tells you: what a conformant attestation looks
+like, how to read it, and which clauses of ISO 42001 / NIST AI 600-1 /
+EU AI Act each field addresses.
+
+## What you should receive
+
+The deployer should hand you, for each covered host:
+
+1. A **Capability-State Attestation** JSON file, signed via sigstore
+   keyless. Schema: `attestation-v0.schema.json`. Spec: `SPEC.md`.
+2. The **policy** YAML that was active when the attestation was
+   produced. It specifies thresholds and allow-lists.
+3. The **policy report** (JSON) produced by `mcp-gov check`. Lists one
+   result per breakpoint with severity `pass | info | warn | block`.
+4. The **framework mapping** for your target framework (ISO 42001,
+   NIST AI 600-1, or EU AI Act). The deployer can emit it with
+   `mcp-gov mappings show iso42001`.
+
+## How to verify the attestation
+
+```bash
+mcp-gov verify attestation.json \
+  --expected-identity user@example.com \
+  --expected-issuer https://accounts.google.com
+```
+
+The tool:
+
+- validates the JSON against the schema,
+- recomputes the TCS from the `tools` array,
+- verifies the sigstore bundle against the transparency log and the
+  expected identity/issuer.
+
+Any mismatch causes a non-zero exit code.
+
+## Clause mapping
+
+Each breakpoint is mapped to specific clauses. See the
+`mcp_governance_kit.mappings` bundle for the authoritative source.
+
+- **ISO/IEC 42001:2023 Annex A** — B1 → A.6.2.5 and A.6.2.6; B2 → A.10.2
+  and A.10.3; B4 → A.4.5 and A.9.3; B5 → A.6.2.6 and A.9.4; B6 → A.6.2.4
+  and A.6.2.8.
+- **NIST AI 600-1** — B1 → GOVERN-1.4-004 and MANAGE-2.4-002; B2 →
+  GOVERN-6.1-001 and MAP-4.1-003; B4 → MANAGE-1.2-004 and MANAGE-2.2-001;
+  B5 → MEASURE-2.8-001 and MANAGE-2.3-002; B6 → MAP-3.1-002 and
+  MANAGE-4.2-001.
+- **EU AI Act** — B1 → Art. 55(1)(b); B2 → Art. 25 and 53(1)(b); B4 →
+  Art. 14 and 15(4); B5 → Art. 12 and 55(1)(c); B6 → Art. 51 and 55(1)(a).
+
+## What the paper says you will not find
+
+The paper argues that **no published framework text** currently
+operationalises a runtime capability-state primitive. The attestation
+is that primitive. Treat clause mappings above as the adjacent text you
+can cite; treat the attestation itself as the evidence artefact.

docs/guides/ci-integration.md

@@ -0,0 +1,50 @@
+# CI integration
+
+The kit ships a composite GitHub Action at the root of the repository.
+
+## Minimal workflow
+
+`.github/workflows/mcp-governance.yml`:
+
+```yaml
+name: MCP Governance
+on:
+  pull_request:
+    paths: [".mcp.json", "policies/*.yaml"]
+
+permissions:
+  id-token: write       # required for sigstore keyless
+  contents: read
+
+jobs:
+  attest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: linus131313/mcp-governance-kit@v0
+        with:
+          config-path: .mcp.json
+          policy-path: policies/default.yaml
+          fail-on-warn: "false"
+```
+
+## What the action does
+
+1. Installs `mcp-governance-kit[sign]`.
+2. Runs `mcp-gov attest` with `--sign` (sigstore keyless via GitHub OIDC).
+3. Uploads the TCS and attestation path as step outputs.
+4. Runs `mcp-gov check` against the supplied policy.
+5. Writes the JSON report to the GitHub Actions job summary.
+6. Fails the job on `BLOCK`; also fails on `WARN` when `fail-on-warn` is true.
+
+## Attestation as a release artefact
+
+To publish the signed attestation as part of a release, add a follow-up
+step:
+
+```yaml
+      - uses: softprops/action-gh-release@v2
+        if: startsWith(github.ref, 'refs/tags/')
+        with:
+          files: ${{ steps.run.outputs.attestation-path }}
+```

docs/guides/policy-authoring.md

@@ -0,0 +1,41 @@
+# Policy authoring
+
+A policy is a YAML document that parameterises the six breakpoint checks.
+The schema is defined in `mcp_governance_kit.policy.Policy` and validates
+on load.
+
+## Minimal example
+
+```yaml
+version: 1
+name: my-team
+max_tcs: 20
+max_third_party: 5
+third_party_allowlist:
+  - "@modelcontextprotocol/server-github"
+  - "@modelcontextprotocol/server-filesystem"
+```
+
+## Full reference
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `version` | int | Schema version; default 1. |
+| `name` | string | Human name; shown in the policy report. |
+| `max_tcs` | float? | If TCS exceeds, B4 blocks. |
+| `warn_tcs` | float? | If TCS exceeds, B4 warns. |
+| `max_third_party` | int? | If exceeded, B2 blocks. |
+| `third_party_allowlist` | string[] | Identities not on the list trigger B2 warn. |
+| `require_approval_for_execute` | bool | B4 blocks when network+execute tools are bound without approval. |
+| `execute_approved` | bool | Set to lift the B4 block when approval has been obtained. |
+| `require_approval_for_changes` | bool | B1 blocks on any change without an approval flag. |
+| `changes_approved` | bool | Set to lift the B1 block. |
+| `allow_exfil_paths` | bool | If true, B3 downgrades warn to info. |
+
+## Three built-in policies
+
+| Policy | Intended role | Highlights |
+|--------|---------------|------------|
+| `default.yaml` | Starting point for most teams | TCS ≤ 30, warn at 15. |
+| `developer.yaml` | Full-stack engineering | TCS ≤ 20, allow-list covers git/shell/docker. |
+| `restricted.yaml` | Analyst / data-science | TCS ≤ 10, execute requires approval. |

docs/index.md

@@ -0,0 +1,36 @@
+# mcp-governance-kit
+
+Runtime capability-state attestation for Model Context Protocol agents.
+
+Companion implementation to [*The MCP Governance Gap*](paper.md)
+(Teklenburg, 2026). The paper identifies a missing governance primitive:
+
+> a reproducible, signable snapshot of what tools an agent can reach,
+> with what action-level privilege, through what trust path, that an
+> auditor can test against.
+
+This kit implements that primitive. It ships:
+
+- a Tool Graph Capability Score (TCS) scorer that reproduces Table 3 of
+  the paper exactly;
+- a JSON-Schema'd, versioned attestation format signable with sigstore;
+- six control-breakpoint checks (B1–B6) mapped to ISO 42001, NIST AI
+  600-1, and the EU AI Act;
+- three adoption paths — GitHub Action, pre-commit hook, Claude Code
+  PreToolUse hook.
+
+## Install
+
+```bash
+pip install mcp-governance-kit             # core
+pip install 'mcp-governance-kit[sign]'     # + sigstore signing
+```
+
+## One-minute demo
+
+```bash
+mcp-gov attest .mcp.json --host-id $HOSTNAME --out att.json --sign
+mcp-gov check att.json --policy policies/default.yaml
+```
+
+See [Quickstart](quickstart.md) for a full walk-through.

docs/paper.md

@@ -0,0 +1,43 @@
+# The paper
+
+The full companion paper is archived in the repository at
+[`paper/governance-speed-gap.pdf`](https://github.com/linus131313/mcp-governance-kit/blob/main/paper/governance-speed-gap.pdf).
+
+## Abstract
+
+A typical developer agent configured with the Model Context Protocol
+(MCP) scores 13.5 on the Tool Graph Capability Score introduced in the
+paper, 1.9× the score of a traditional database-administration-plus-shell
+tool; a full-stack developer configuration scores 49.5, 3.3× that of a
+domain-administrator workstation and 7.1× the database-administration
+tool. These comparisons hold under all 48 reweightings tested in a
+sensitivity analysis. The capability expansion happens outside any
+change-management process: MCP allows language-model hosts to bind
+external tools at runtime, a property no AI-specific governance
+framework in applicable form yet addresses.
+
+The paper quantifies the gap between the adoption curve of agentic tool
+binding and the response cadence of the three governance regimes CISOs
+rely on, identifies six control breakpoints where application-centric
+controls fail under an MCP-native architecture, and concludes that
+closing the gap requires a new primitive — runtime capability-state
+attestation — that no published revision yet defines.
+
+**This repository implements that primitive.**
+
+## Citation
+
+See [`paper/CITATION.cff`](https://github.com/linus131313/mcp-governance-kit/blob/main/paper/CITATION.cff)
+for a machine-readable citation. BibTeX equivalent:
+
+```bibtex
+@article{teklenburg2026mcp,
+  title  = {The {MCP} Governance Gap: Empirical Evidence on Dynamic
+            Tool Binding in Enterprise {AI}},
+  author = {Teklenburg, Linus},
+  year   = {2026},
+  month  = {4},
+  note   = {Independent Researcher},
+  url    = {https://github.com/linus131313/mcp-governance-kit/blob/main/paper/governance-speed-gap.pdf}
+}
+```