scaffold mkdocs-material docs site

[cchinchilla-dev]

Description

the planning notes requires a docs site at 0.2.0 release. Today the repo has README.md, CLAUDE.md, CONTRIBUTING.md — no navigable site. Reviewers, the framework readers, and early adopters need a browsable reference.

Six sections required by 0.2.0; more added by later phases:

1. Getting Started — install + quickstart.
2. Contract Reference — YAML fields, static analyzer output.
3. Backends — Direct vs AgentLoom, portability invariant.
4. Evaluators — Layer 1 objective + Layer 2 single judge.
5. Recording and Replay — determinism guarantees.
6. API Reference — auto-generated from docstrings.

Proposal

1. mkdocs-material setup:

# mkdocs.yml
site_name: AgentAnvil
site_description: Contract-based testing framework for LLM agents
site_url: https://agentanvil.dev
repo_url: https://github.com/cchinchilla-dev/agentanvil

theme:
  name: material
  palette:
    - scheme: default
      primary: indigo
  features:
    - navigation.tabs
    - navigation.sections
    - content.code.annotate

nav:
  - Home: index.md
  - Getting Started:
      - Install: getting-started/install.md
      - Quickstart (LangChain): getting-started/quickstart.md
  - Concepts:
      - Contracts: concepts/contracts.md
      - Evaluators: concepts/evaluators.md
      - Backends: concepts/backends.md
      - Record / Replay: concepts/record-replay.md
  - Reference:
      - Contract YAML: reference/contract-yaml.md
      - CLI: reference/cli.md
      - API: reference/api/  # mkdocstrings auto-generated

plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          options:
            show_source: false
            docstring_style: google

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.superfences
  - admonition
  - pymdownx.details

2. Index page:

One-paragraph pitch, link to quickstart, link to acknowledgement, link to Zenodo DOI (pending 0.5.0).

3. Deploy to GitHub Pages:

# .github/workflows/docs.yml (new)
name: docs
on:
  push:
    branches: [main]
  workflow_dispatch:
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -e ".[docs]"
      - run: mkdocs gh-deploy --force

agentanvil[docs] extra installs mkdocs-material, mkdocstrings[python], mkdocs-section-index.

4. Preview in PRs:

PR comments include a link to a preview site built by the docs-preview action (optional; landable later).

Scope

• mkdocs.yml — new.
• docs/index.md — new.
• docs/getting-started/install.md — new.
• docs/getting-started/quickstart.md — new (links to examples/quickstart-langchain/README.md).
• docs/concepts/contracts.md — new.
• docs/concepts/evaluators.md — new.
• docs/concepts/backends.md — new.
• docs/concepts/record-replay.md — new.
• docs/reference/contract-yaml.md — new.
• docs/reference/cli.md — new.
• docs/reference/api/index.md — mkdocstrings target.
• pyproject.toml — add docs extra.
• .github/workflows/docs.yml — new.

Regression tests

• docs workflow builds without warnings.
• test_every_public_api_has_docstring — pytest test walking agentanvil.__all__, asserting non-empty docstrings.

Notes

• Full reviewer guide, the framework references, case-study appendix land in 0.5.0 #106 and #107.
• Multi-agent, A2A, corpus, stats docs sections are added by 0.3.0 (not this issue).
• Depends on: add evaluator Layer 2 (single LLM-as-judge) with structured output #11, add first Tier A single-agent case study under examples/case-studies/ #17, ship 0.2.0: single-agent MVP with LangChain quickstart under 10 minutes #18, #019 (content for reference pages).
• Blocks: nothing critical — but the framework's introduction references the docs URL.