CRAFT v0.2.0: unified MkDocs docs site

Ships the Tier-3 presentation layer the platform proposal calls
for: a unified MkDocs Material docs site, auto-deployed to
GitHub Pages on push to main.

What lands in v0.2.0:

- 19 docs pages under docs/: quick-start (3) + architecture (4)
  + skills (3) + operations (4) + extending (2) + reference (2).
  Skills + auto-include content (contract, dependencies,
  release runbook, retrospective, platform proposal, release
  notes, workflows README) pull from canonical source docs via
  the include-markdown plugin so per-skill maintenance flows
  through without duplication.
- mkdocs.yml: Material theme, light/dark toggle, navigation
  tabs + sections, search, mermaid custom-fence, include-markdown
  + pymdownx.snippets plugins.
- .github/workflows/docs.yml: mkdocs gh-deploy on push to main
  (paths-filtered) + manual dispatch; submodules: recursive so
  per-skill READMEs are present at build time.
- .gitignore: adds site/ + .mkdocs-venv/.
- RELEASE_NOTES.md: v0.2.0 entry; also updates one inline link
  to use a github.com URL so the link works both in the source
  doc and in the included docs page.

Local mkdocs build verified clean: 46 warnings (all from
per-skill READMEs containing intra-repo links that exist on
GitHub but aren't part of the docs/ tree — inherent to
including external content); 0 errors; site renders correctly.
9/9 platform CLI tests still pass.

Post-merge action: enable GitHub Pages on the gh-pages branch
at https://github.com/kbaseincubator/craft/settings/pages.
After that, the docs workflow auto-deploys.

Author: aparkin

.github/workflows/docs.yml

@@ -0,0 +1,72 @@
+# Build + deploy the CRAFT MkDocs site to GitHub Pages.
+#
+# Triggered on push to main + manual dispatch. Per-skill READMEs
+# are pulled from the git submodules via include-markdown, so the
+# checkout step needs `submodules: recursive`.
+#
+# Deploys via the gh-pages branch (mkdocs gh-deploy default). The
+# repo's Pages settings need to point at the gh-pages branch on
+# first deploy; see operations/github-actions.md.
+
+name: Deploy docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "CRAFT-CONTRACT.md"
+      - "CRAFT-DEPENDENCIES.md"
+      - "CROSS-SKILL-RELEASE.md"
+      - "PLATFORM-PROPOSAL.md"
+      - "AUGMENTATION-STREAM-RETROSPECTIVE.md"
+      - "RELEASE_NOTES.md"
+      - "README.md"
+      - ".github/workflows/docs.yml"
+      - ".github/workflows/README.md"
+  workflow_dispatch:
+
+permissions:
+  contents: write   # gh-deploy needs to push to gh-pages branch
+
+concurrency:
+  group: docs-deploy
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout (with submodules)
+        uses: actions/checkout@v5
+        with:
+          submodules: recursive
+          fetch-depth: 0   # gh-deploy benefits from full history
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install MkDocs + plugins
+        run: |
+          python -m pip install --upgrade pip
+          pip install \
+            mkdocs-material>=9.5.0 \
+            mkdocs-include-markdown-plugin>=6.0.0 \
+            pymdown-extensions>=10.7.0
+
+      - name: Build site (validation)
+        # Don't use --strict: per-skill READMEs (pulled via
+        # include-markdown from the submodules) contain
+        # intra-repo links that resolve fine on GitHub but
+        # aren't present in the docs/ tree. They render as
+        # broken-link warnings; the site is otherwise clean.
+        run: mkdocs build
+
+      - name: Deploy to gh-pages
+        run: mkdocs gh-deploy --force --clean

.gitignore

@@ -5,5 +5,8 @@ __pycache__/
 .ruff_cache/
 .DS_Store
 .venv/
+.mkdocs-venv/
 dist/
 build/
+# MkDocs build output
+site/

RELEASE_NOTES.md

@@ -1,5 +1,90 @@
 # CRAFT — Release Notes
 
+## v0.2.0 (2026-06-03) — Unified MkDocs documentation site
+
+Ships the Tier-3 presentation layer the platform proposal calls
+for: a unified MkDocs Material docs site, auto-deployed to
+GitHub Pages via `mkdocs gh-deploy` on push to main.
+
+### What changed in v0.2.0
+
+`docs/` (new):
+
+- `index.md` — platform landing with the Tier-0 workflow
+  mermaid diagram.
+- `quick-start/` — install → first-run → verify walkthrough.
+- `architecture/` — platform-structure + cross-skill contract
+  (auto-pulled from `CRAFT-CONTRACT.md`) + skill relationships
+  diagram + augmentation-stream retrospective (auto-pulled
+  from `AUGMENTATION-STREAM-RETROSPECTIVE.md`).
+- `skills/` — per-skill operator pages with the skill README
+  auto-pulled from each submodule via the `include-markdown`
+  plugin.
+- `operations/` — coordinated release runbook (auto-pulled from
+  `CROSS-SKILL-RELEASE.md`) + upstream dependencies (auto-pulled
+  from `CRAFT-DEPENDENCIES.md`) + GitHub Actions setup
+  (auto-pulled from `.github/workflows/README.md`) +
+  troubleshooting decision tree.
+- `extending/` — `adding-a-skill.md` (the formal join process)
+  + `external-contributors.md` (scope + conventions).
+- `reference/` — release notes (this file, auto-pulled) +
+  platform proposal (auto-pulled from `PLATFORM-PROPOSAL.md`).
+
+`mkdocs.yml`:
+
+- MkDocs Material theme; light/dark toggle (indigo palette);
+  navigation tabs + sections; search; content.code.copy +
+  content.action.edit.
+- `pymdownx.superfences` + `mermaid` custom-fence — diagrams
+  ship as text.
+- `pymdownx.snippets` + `include-markdown` plugin — auto-pull
+  per-skill READMEs from submodules; auto-pull platform-level
+  docs from repo root.
+- Flat nav (Home / Quick Start / Architecture / Skills /
+  Operations / Extending / Reference); 19 markdown pages total.
+
+`.github/workflows/docs.yml` (new):
+
+- Triggered on push to main (paths-filtered to docs/ + root
+  doc files) + manual dispatch.
+- Checks out with `submodules: recursive` so include-markdown
+  can read per-skill READMEs.
+- Installs `mkdocs-material`, `mkdocs-include-markdown-plugin`,
+  `pymdown-extensions`.
+- Runs `mkdocs build` then `mkdocs gh-deploy --force --clean`.
+- 10-minute timeout; concurrency-grouped so docs deploys
+  don't pile up.
+
+`.gitignore`:
+
+- Added `site/` (MkDocs build output) + `.mkdocs-venv/` (local
+  preview venv).
+
+### Local build verification
+
+Build verified clean locally (46 warnings, all from per-skill
+READMEs containing intra-repo links that exist on GitHub but
+aren't in the docs/ tree; 0 errors; site renders correctly).
+
+### One-time GitHub Pages setup needed
+
+First docs deploy needs the GitHub Pages source set to the
+`gh-pages` branch:
+
+1. https://github.com/kbaseincubator/craft/settings/pages
+2. "Build and deployment" → Source → "Deploy from a branch"
+3. Branch: `gh-pages` / `(root)`
+4. Save.
+
+After that the docs workflow handles deploys automatically on
+push to main.
+
+### Site URL
+
+After Pages activates: https://kbaseincubator.github.io/craft/
+
+---
+
 ## v0.1.4 (2026-06-03) — Smoke narrowed to adversarial-only + fixture cleanup
 
 First end-to-end cross-skill smoke run (26904057672) succeeded
@@ -263,5 +348,5 @@ documentation surface. No new skill features.
 [beril-atlas-skill](https://github.com/ArkinLaboratory/beril-atlas-skill)
 is metrology (observability) — distinct from CRAFT's
 research-artifact-production focus. Stays as its own skill with
-its own release cycle. See [PLATFORM-PROPOSAL.md §3](PLATFORM-PROPOSAL.md)
+its own release cycle. See [PLATFORM-PROPOSAL.md §3](https://github.com/kbaseincubator/craft/blob/main/PLATFORM-PROPOSAL.md)
 for the rationale.

docs/architecture/contract.md

@@ -0,0 +1,58 @@
+# Cross-skill contract
+
+The CRAFT contract is the **interface pin** that lets the three
+skills release independently without breaking each other. It
+codifies the schemas they share, the operational invariants
+they all uphold, and the process for evolving them.
+
+The full contract lives at `CRAFT-CONTRACT.md` in the platform
+repo root and is included below verbatim. The platform
+maintainer is the source of truth for contract evolution; this
+page is auto-rendered from that file.
+
+## Why the contract exists
+
+The three skills work independently — each has its own CLI,
+its own install, its own release cycle. But they also
+**explicitly compose**:
+
+- `beril-adversarial-skill` produces structured review findings
+  (the `adversarial-review-{paper,presentation}.v3` schemas).
+- `beril-paper-writer-skill` consumes those findings in its
+  review-rewrite loop.
+- `beril-presentation-maker-skill` consumes those findings in
+  its review-rewrite loop AND consumes paper-writer's
+  `citation_pool.json` via the reuse-from-paper path.
+
+The contract pins:
+
+1. **Schema versioning.** Producer schemas have stability
+   guarantees through the current CRAFT major version. Breaking
+   changes require a dual-version support window.
+2. **The 4-zone draft layout** (`deliverable/`, `narrative/`,
+   `working/`, `audit/`) — what every skill produces under
+   `<BERIL_ROOT>/projects/<project_id>/{papers,talks}/draft_N/`.
+3. **The `claude -p` subagent invocation pattern** + stream-json
+   output parsing — the load-bearing primitive.
+4. **The `install-skill` discoverability convention** — every
+   skill stays independently installable; `craft install-platform`
+   is a coordinator, not a replacement.
+5. **The environment-variable contract** (`CBORG_API_KEY`,
+   `GOOGLE_AI_STUDIO_API_KEY`, `BERIL_ROOT`).
+6. **The auto-memory convention** for cross-skill discoveries.
+7. **The tiered review cascade pattern** for skills with quality
+   gates.
+
+For the rationale see the [platform proposal](../reference/platform-proposal.md);
+for the join/depart process for future skills see [Adding a
+skill](../extending/adding-a-skill.md).
+
+---
+
+## The contract — full text
+
+{%
+  include-markdown "../../CRAFT-CONTRACT.md"
+  start="## 1. What this contract is"
+  rewrite-relative-urls=false
+%}