docs: documentation site (MkDocs Material) — no-drift, AI-native (#12)

* docs: add MkDocs Material site with no-drift API ref + llms.txt

Build the public documentation site so the advertised Documentation URL
(https://block.github.io/model-ledger) stops 404ing. Docs-only; no SDK changes.

- mkdocs.yml — Material theme, mkdocstrings/Griffe API reference (generated
  from src/, cannot drift), mermaid, multi-surface content tabs
- docs/ — landing (four surfaces + self-building-graph demo), 60s quickstart,
  concepts (DataNode / Snapshot / Composite), guides (agents/MCP, backends,
  connectors), recipe cookbook, auto API reference
- docs/stylesheets/extra.css — "technical-archive" theme: serif display,
  warm paper, oxblood accent, hairline rules
- docs_hooks/llms_txt.py — build-time llms.txt + llms-full.txt + per-page .md
  for AI agents, zero extra dependencies
- .github/workflows/docs.yml — build --strict on every PR, gh-deploy to
  GitHub Pages on push to main
- pyproject.toml — add [docs] optional-dependencies extra
- .pre-commit-config.yaml — exclude mkdocs.yml from check-yaml (custom tags)
- .gitignore — ignore /site/ build output

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

* docs: make it sing — animated hero, OG card, favicon, on-brand 404

Craft pass over the docs landing + shareability:

- Landing moment: the hero is now two columns; a dependency graph assembles
  itself on the right — nodes pop in (declared), then edges draw in
  (connect() links them), visualizing the core thesis. Pure inline SVG + CSS,
  no JS; respects prefers-reduced-motion.
- Open Graph card: scripts/make_og_card.py renders a 1200x630
  "technical-archive" social card (docs/assets/og-image.png); overrides/main.html
  injects per-page og:/twitter: meta so shared links preview beautifully.
- Favicon + logo: docs/assets/favicon.svg — a minimal oxblood graph glyph,
  scalable, light/dark safe.
- 404: overrides/404.html — "This node isn't in the graph." with routes home,
  to the quickstart, and the reference.

Docs-only; strict build green.

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

* docs: execute examples in CI + griffe API check — close the drift hole

The API reference is generated from source and `mkdocs build --strict` catches
broken references/links. The remaining risk was hand-written prose: a tutorial
snippet calling an API that has since changed. Now the snippets run in CI.

- tests/test_docs_examples.py — extracts the runnable ```python blocks from each
  docs page (including tab-indented ones), skips blocks needing external
  resources (Snowflake/boto3/live connectors/GitHub), and execs each page's
  blocks in one namespace. A renamed param or removed method fails the PR.
- Fixes two real bugs the test caught in the snippets:
  * Ledger.record() is record(model, *, event, payload, actor) — event/payload/
    actor are keyword-only and required (had conflated it with the MCP tool).
  * inventory_at() needs a timezone-aware datetime; naive dates raised TypeError.
    point-in-time recipe rewritten to a self-contained, honest demonstration.
- .github/workflows/docs.yml — run the example tests (blocking) before build +
  deploy; add an advisory `griffe check` step flagging breaking public-API
  changes vs. the base branch.
- pyproject.toml — add griffecli to the [docs] extra for `griffe check`.

Verified: deliberately breaking a snippet turns the test red; reverting is green.

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

---------

Co-authored-by: Vignesh Narayanaswamy <Vigneshn@squareup.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

.github/workflows/docs.yml

@@ -0,0 +1,67 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "docs_hooks/**"
+      - "mkdocs.yml"
+      - "src/**"
+      - "tests/test_docs_examples.py"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    paths:
+      - "docs/**"
+      - "docs_hooks/**"
+      - "mkdocs.yml"
+      - "src/**"
+      - "tests/test_docs_examples.py"
+
+# Allow one concurrent deployment; cancel superseded runs.
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write   # mkdocs gh-deploy pushes the built site to the gh-pages branch
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      # NOTE: tags are pinned to digests by Renovate (see renovate.json) on its next run.
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # gh-deploy needs full history to update gh-pages
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install
+        run: pip install -e ".[docs,dev]"
+
+      # The docs cannot drift from the SDK: every runnable code example in the
+      # docs is executed against the installed package. A renamed param or
+      # removed method breaks a snippet here and fails the PR.
+      - name: Test docs examples
+        run: pytest tests/test_docs_examples.py -q
+
+      # Always validate: a broken link, a missing nav entry, or a bad
+      # mkdocstrings reference fails the build (and therefore the PR).
+      - name: Build (strict)
+        run: mkdocs build --strict
+
+      # Advisory radar: flag breaking public-API changes vs. the base branch so
+      # they're noticed and changelog'd. Non-blocking during alpha.
+      - name: Check public API (griffe)
+        continue-on-error: true
+        run: |
+          git fetch origin main --depth=1 || true
+          python -m griffe check model_ledger -s src -a origin/main
+
+      # Deploy only from main, only on push (not PRs).
+      - name: Deploy to GitHub Pages
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: mkdocs gh-deploy --force --no-history

.gitignore

@@ -26,6 +26,10 @@ uv.lock
 # Internal design docs (contain org-specific context)
 docs/superpowers/
 
+# MkDocs build output (the docs site is built + deployed in CI)
+/site/
+.cache/
+
 # Detailed internal blocklist (committed config is .gitleaks.toml)
 .gitleaks-internal.toml
 

.pre-commit-config.yaml

@@ -5,6 +5,9 @@ repos:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-yaml
+        # mkdocs.yml uses MkDocs' custom !!python/ YAML tags that the safe
+        # loader can't parse; `mkdocs build --strict` validates it in CI instead.
+        exclude: ^mkdocs\.yml$
       - id: check-json
       - id: check-toml
       - id: check-added-large-files

docs/assets/favicon.svg

@@ -0,0 +1,81 @@
+---
+title: Composites
+description: Governed groups whose members are themselves models — a business-level entity that rolls up its technical components, each governed in its own right.
+---
+
+# Composites
+
+A regulator doesn't approve "a SQL job." They approve a **Credit Decision System**.
+But that system is really a scorecard, some policy rules, and an ETL pipeline — each
+of which deserves its own governance.
+
+A **composite** is the business-level entity that aggregates technical components.
+Critically, a member *is itself a model* — so it has its own owner, history, and
+validation. Composites are the layer no plain registry or catalog models.
+
+## Register a group and its members
+
+`register_group()` creates the composite and links each member with the
+`member_of` relationship:
+
+```python
+from model_ledger import Ledger
+ledger = Ledger.from_sqlite("./inventory.db")
+
+group = ledger.register_group(
+    name="Credit Scorecard",
+    owner="risk-team",
+    model_type="ml_model",
+    tier="high",
+    purpose="Credit risk scoring pipeline",
+    members=["feature_pipeline", "scoring_model", "alert_queue"],
+    actor="system",
+)
+```
+
+```mermaid
+graph TD
+    G["Credit Scorecard<br/><small>composite · tier: high</small>"]
+    G --- M1["feature_pipeline"]
+    G --- M2["scoring_model"]
+    G --- M3["alert_queue"]
+    classDef ink fill:#1c1a17,color:#f7f3ec,stroke:#000;
+    classDef ox fill:#efe8da,stroke:#7a1a1a,color:#1c1a17;
+    class G ink; class M1,M2,M3 ox;
+```
+
+## Membership is an event, too
+
+Add and remove members over time — each change is recorded as a snapshot, so you can
+ask *who belonged to this system on any past date*:
+
+```python
+ledger.add_member("Credit Scorecard", "challenger_model", role="challenger", actor="risk-team")
+ledger.remove_member("Credit Scorecard", "scoring_model", actor="risk-team")
+
+ledger.members("Credit Scorecard")   # current members (replayed from the event log)
+ledger.groups("scoring_model")       # which composites a model belongs to
+
+from datetime import datetime
+ledger.membership_at("Credit Scorecard", datetime(2025, 12, 31))  # membership as of a date
+```
+
+## Roll-up view
+
+`composite_summary()` aggregates a composite and its members into a single governance
+view — tiers, statuses, open observations, and validation state across the whole
+system:
+
+```python
+summary = ledger.composite_summary("Credit Scorecard")
+```
+
+This is what makes composites the **primary inventory entry** for governance: an
+examiner reads ~one entry per business system, and every technical component beneath it
+remains individually traceable.
+
+!!! note "Observations & validations"
+    Composites also carry governance events — `record_observation()`,
+    `resolve_observation()`, and `record_validation()` — so findings and validation
+    outcomes live in the same immutable log as everything else. See the
+    [API reference](../reference/index.md).

docs/assets/og-image.png

@@ -0,0 +1,88 @@
+---
+title: DataNode & the graph
+description: Everything is a DataNode with typed ports. Declare inputs and outputs; the dependency graph builds itself.
+---
+
+# DataNode & the graph
+
+The core insight: **a model, a rule, an ETL job, and an alert queue are the same
+shape.** Each consumes some things and produces others. So they're all one type —
+`DataNode` — and the dependency graph falls out of matching what they produce to
+what others consume.
+
+## A node is what it reads and writes
+
+```python
+from model_ledger import DataNode
+
+DataNode(
+    name="fraud_scorer",
+    platform="ml",
+    inputs=["customer_features"],   # what it consumes
+    outputs=["risk_scores"],        # what it produces
+    metadata={"framework": "xgboost", "owner": "risk-team"},
+)
+```
+
+`inputs` and `outputs` are **ports** — the names of the data flowing in and out. A
+plain string becomes a [`DataPort`](#dataport-precision) automatically.
+
+## The graph builds itself
+
+You never draw edges. You call `connect()`, and every place an output port name
+matches an input port name becomes a dependency:
+
+```python
+from model_ledger import Ledger, DataNode
+
+ledger = Ledger()
+ledger.add([
+    DataNode("segmentation", platform="etl", outputs=["customer_segments"]),
+    DataNode("fraud_scorer", platform="ml",  inputs=["customer_segments"], outputs=["risk_scores"]),
+    DataNode("fraud_alerts", platform="alerting", inputs=["risk_scores"]),
+])
+ledger.connect()
+
+ledger.trace("fraud_alerts")     # ['segmentation', 'fraud_scorer', 'fraud_alerts']
+ledger.upstream("fraud_alerts")  # everything that feeds it
+ledger.downstream("segmentation")# everything that depends on it
+```
+
+```mermaid
+graph LR
+    A["segmentation"] -->|customer_segments| B["fraud_scorer"] -->|risk_scores| C["fraud_alerts"]
+    classDef n fill:#efe8da,stroke:#7a1a1a,color:#1c1a17;
+    class A,B,C n;
+```
+
+This is why discovery scales: a connector just emits `DataNode`s with their ports,
+and the cross-platform graph assembles itself — an ETL job in your warehouse links to
+a model in MLflow links to a queue in your alerting system, with no shared ID scheme.
+
+## DataPort precision
+
+When two models legitimately write a table with the same name, a bare port name would
+collide. `DataPort` carries optional schema to disambiguate — edges only form when the
+schema matches too:
+
+```python
+from model_ledger import DataNode, DataPort
+
+DataNode("check_rules", outputs=[DataPort("alerts", model_name="checks")])
+DataNode("card_rules",  outputs=[DataPort("alerts", model_name="cards")])
+DataNode("check_queue", inputs=[DataPort("alerts", model_name="checks")])
+# check_queue connects to check_rules only — model_name must match.
+```
+
+Port matching is case-insensitive, and schema values support `%` wildcards.
+
+## From node to governed model
+
+A `DataNode` gives you structure. To give a node an **identity and history** —
+owner, risk tier, purpose, and an audit trail — you
+[`register()`](../reference/index.md) it as a [`ModelRef`](snapshot.md) and
+[`record()`](snapshot.md) events against it. Discovery and registration are two views
+of the same inventory: the graph (what connects to what) and the ledger (what each
+thing *is* and how it changed).
+
+[Next: Snapshots & the event log :octicons-arrow-right-24:](snapshot.md)

docs/concepts/composite.md

@@ -0,0 +1,63 @@
+---
+title: Concepts
+description: The whole model in three ideas — the DataNode graph, the Snapshot event log, and Composites.
+---
+
+# Concepts
+
+model-ledger is small on purpose. Three ideas carry the whole system.
+
+<div class="grid cards" markdown>
+
+-   :material-graph-outline:{ .lg } &nbsp;__[DataNode & the graph](datanode.md)__
+
+    ---
+
+    Everything is a `DataNode` with typed input/output ports. Declare what a node
+    reads and writes; the dependency graph builds itself from port matching.
+
+-   :material-history:{ .lg } &nbsp;__[Snapshot & the event log](snapshot.md)__
+
+    ---
+
+    A model is an identity (`ModelRef`). Everything that happens to it is an
+    immutable, content-addressed `Snapshot`. The inventory is an append-only log.
+
+-   :material-layers-outline:{ .lg } &nbsp;__[Composites](composite.md)__
+
+    ---
+
+    Governed groups whose members are themselves models. A "credit decision system"
+    that rolls up its scorecard, policy rules, and ETL — each governed in its own right.
+
+</div>
+
+## How they fit together
+
+```mermaid
+graph TB
+    subgraph identity ["Identity"]
+        REF["ModelRef<br/><small>name · owner · type · tier · purpose</small>"]
+    end
+    subgraph history ["History (append-only)"]
+        S1["Snapshot<br/><small>registered</small>"] --> S2["Snapshot<br/><small>retrained</small>"] --> S3["Snapshot<br/><small>validated</small>"]
+    end
+    subgraph graph ["Graph"]
+        N1["DataNode"] -->|port match| N2["DataNode"]
+    end
+    REF --- S1
+    REF -.is a node in.- N1
+    classDef ink fill:#1c1a17,color:#f7f3ec,stroke:#000;
+    classDef ox fill:#7a1a1a,color:#fff,stroke:#5a1010;
+    class REF ink; class S1,S2,S3 ox;
+```
+
+- **Identity** is the minimum a regulator needs: who owns it, what kind of model,
+  how risky, what it's for.
+- **History** is every change, immutable and ordered. You can ask the inventory what
+  it looked like on any past date.
+- **Graph** is how models relate. Declare ports; dependencies follow.
+
+A fourth idea — **compliance profiles** (SR 11-7, EU AI Act, NIST AI RMF) — reads this
+data to check completeness. It's a pluggable layer, not part of the core model; see the
+[API reference](../reference/index.md).