diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 319c1d0..263bc0e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -55,3 +55,27 @@ jobs:
         with:
           name: selftest-results-py${{ matrix.python-version }}
           path: selftest-results.xml
+
+  verify-demo:
+    name: Verify showboat demo
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync
+      - name: Check for demo
+        id: check
+        run: |
+          if [ -f demo.md ]; then
+            echo "found=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "found=false" >> "$GITHUB_OUTPUT"
+            echo "No demo.md found — skipping verification"
+          fi
+      - name: Verify demo
+        if: steps.check.outputs.found == 'true'
+        run: uvx showboat verify demo.md
diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml
index 28b0b43..0a3cb9e 100644
--- a/.github/workflows/copilot-setup-steps.yml
+++ b/.github/workflows/copilot-setup-steps.yml
@@ -24,3 +24,5 @@ jobs:
         uses: github/gh-aw/actions/setup-cli@v0.48.1
         with:
           version: v0.48.1
+      - name: Install showboat
+        run: pip install showboat
diff --git a/.gitignore b/.gitignore
index 3b34190..b04ccef 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,7 @@
 # VIP-specific
 vip.toml
 report/results.json
+demo.md
 report/_output/
 report/_freeze/
 report/.quarto/
diff --git a/AGENTS.md b/AGENTS.md
index 3d0a87c..4e40875 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -191,6 +191,51 @@ silently swallowed inside conditionals.
   PR preview to gh-pages via `rossjrw/pr-preview-action@v1`. Uses uv
   and Quarto caches.
 
+## Showboat demos
+
+After completing work on a branch, create a showboat demo that proves
+your changes work. The demo file is committed to the branch and its
+contents are pasted into the PR body under a `## Demo` heading.
+
+### Getting started
+
+Run `uvx showboat --help` at the start of a session to learn the tool.
+
+### Creating a demo
+
+```bash
+uvx showboat init demo.md "Feature: <title>"
+uvx showboat note demo.md "Explanation of what was done..."
+uvx showboat exec demo.md bash "uv run pytest selftests/ -v"
+uvx showboat exec demo.md bash "just check"
+```
+
+Use `uvx showboat image demo.md <path>` if screenshots are relevant.
+
+### What to demonstrate
+
+- **New tests:** run the new tests and show them passing
+- **New features:** exercise the feature with concrete examples
+- **Bug fixes:** show the fix in action (before/after if feasible)
+- **Refactors:** show that existing tests still pass
+- **Always** include `just check` (lint/format) output
+
+### Before committing
+
+```bash
+uvx showboat verify demo.md
+```
+
+Verification re-runs all `exec` blocks and confirms output matches.
+If it fails, fix the demo before committing.
+
+### PR workflow
+
+1. Commit `demo.md` to the branch root
+2. Paste the contents of `demo.md` into the PR body under `## Demo`
+
+CI will run `showboat verify demo.md` on PRs that include the file.
+
 ## Common mistakes to avoid
 
 - Forgetting to include `examples/` in ruff check paths.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 0000000..47dc3e3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/justfile b/justfile
index 5f224ba..d39cfe4 100644
--- a/justfile
+++ b/justfile
@@ -48,6 +48,14 @@ report *ARGS:
     uv run pytest tests/ --vip-report=report/results.json {{ ARGS }}
     cd report && uv run quarto render
 
+# Create a new showboat demo document
+demo-init TITLE:
+    uvx showboat init demo.md "{{ TITLE }}"
+
+# Verify an existing demo document
+demo-verify:
+    uvx showboat verify demo.md
+
 # Generate a Quarto report from selftests (for CI / demo purposes)
 report-selftest:
     uv run pytest selftests/ --vip-report=report/results.json