diff --git a/README.md b/README.md
index 6a00ea5..492098c 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,11 @@
 # DiffVisualizer — visual diffs in Agent Zero chat
 
+<!-- BADGES:START (generated by the devkit — `make badges`) -->
+
+[![plugin-e2e](https://github.com/agent-zero-plugins/agent-zero-plugin-diff-visualizer/actions/workflows/plugin-e2e.yml/badge.svg?branch=main)](https://github.com/agent-zero-plugins/agent-zero-plugin-diff-visualizer/actions/workflows/plugin-e2e.yml) [![BDD scenarios](https://img.shields.io/badge/tests-BDD%20e2e-brightgreen)](https://github.com/agent-zero-plugins/agent-zero-plugin-diff-visualizer/tree/main/tests/e2e/features) [![Release](https://img.shields.io/github/v/tag/agent-zero-plugins/agent-zero-plugin-diff-visualizer?label=release&sort=semver)](https://github.com/agent-zero-plugins/agent-zero-plugin-diff-visualizer/tags) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/agent-zero-plugins/agent-zero-plugin-diff-visualizer/blob/main/LICENSE) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/agent-zero-plugins/agent-zero-plugin-diff-visualizer/blob/main/CONTRIBUTING.md)
+
+<!-- BADGES:END -->
+
 Renders unified-diff fenced code blocks as **side-by-side visual diffs** directly in the
 Agent Zero chat UI — with a fullscreen maximize view, a copy-raw-source button, and
 theme-aware styling. It also ships an agent **skill** that teaches the agent to emit
@@ -110,4 +116,4 @@ trace to those IDs.
 
 ## License
 
-Apache-2.0 — see [LICENSE](LICENSE).
+Apache-2.0 — see [LICENSE](LICENSE).
\ No newline at end of file
diff --git a/docs/BEHAVIOUR.md b/docs/BEHAVIOUR.md
new file mode 100644
index 0000000..2217f0d
--- /dev/null
+++ b/docs/BEHAVIOUR.md
@@ -0,0 +1,63 @@
+# DiffVisualizer — behaviour
+
+<!-- GENERATED by the devkit (`make docs`) from this plugin's own e2e run.
+     Do not edit by hand: every screenshot below is the asserted end state of a
+     passing BDD scenario, so it cannot show behaviour the plugin no longer has.
+     Captions are the scenario titles verbatim — reword them in tests/e2e/features/. -->
+
+Each section is one scenario from `tests/e2e/features/`, with the screenshot the
+test captured at its final assertion. 10 of 10 scenarios have one.
+
+## Rendering diffs
+
+### A diff block in the chat is rendered as a visual diff
+<sub>BEH-1, BEH-3</sub>
+
+![A diff block in the chat is rendered as a visual diff](screenshots/a-diff-block-in-the-chat-is-rendered-as-a-visual-diff.png)
+
+### The rendered diff offers maximize and copy
+<sub>BEH-2</sub>
+
+![The rendered diff offers maximize and copy](screenshots/the-rendered-diff-offers-maximize-and-copy.png)
+
+## Diff overlay, copy, and edge-case handling
+
+### Maximizing a rendered diff opens a single fullscreen overlay
+<sub>BEH-4</sub>
+
+![Maximizing a rendered diff opens a single fullscreen overlay](screenshots/maximizing-a-rendered-diff-opens-a-single-fullscreen-overlay.png)
+
+### The overlay closes via its close button and the inline diff survives
+<sub>BEH-5</sub>
+
+![The overlay closes via its close button and the inline diff survives](screenshots/the-overlay-closes-via-its-close-button-and-the-inline-diff-survives.png)
+
+### The overlay closes via a backdrop click
+<sub>BEH-5</sub>
+
+![The overlay closes via a backdrop click](screenshots/the-overlay-closes-via-a-backdrop-click.png)
+
+### The overlay closes via the Escape key
+<sub>BEH-5</sub>
+
+![The overlay closes via the Escape key](screenshots/the-overlay-closes-via-the-escape-key.png)
+
+### Copying a rendered diff puts the raw diff text on the clipboard
+<sub>BEH-6</sub>
+
+![Copying a rendered diff puts the raw diff text on the clipboard](screenshots/copying-a-rendered-diff-puts-the-raw-diff-text-on-the-clipboard.png)
+
+### A multi-file diff renders both files inside one visual diff
+<sub>BEH-1</sub>
+
+![A multi-file diff renders both files inside one visual diff](screenshots/a-multi-file-diff-renders-both-files-inside-one-visual-diff.png)
+
+### Malformed diff text falls back to the readable plain code block
+<sub>BEH-3</sub>
+
+![Malformed diff text falls back to the readable plain code block](screenshots/malformed-diff-text-falls-back-to-the-readable-plain-code-block.png)
+
+### A non-diff code fence is left untouched
+<sub>BEH-1</sub>
+
+![A non-diff code fence is left untouched](screenshots/a-non-diff-code-fence-is-left-untouched.png)
diff --git a/docs/screenshots/a-diff-block-in-the-chat-is-rendered-as-a-visual-diff.png b/docs/screenshots/a-diff-block-in-the-chat-is-rendered-as-a-visual-diff.png
new file mode 100644
index 0000000..ef283a7
Binary files /dev/null and b/docs/screenshots/a-diff-block-in-the-chat-is-rendered-as-a-visual-diff.png differ
diff --git a/docs/screenshots/a-multi-file-diff-renders-both-files-inside-one-visual-diff.png b/docs/screenshots/a-multi-file-diff-renders-both-files-inside-one-visual-diff.png
new file mode 100644
index 0000000..605523c
Binary files /dev/null and b/docs/screenshots/a-multi-file-diff-renders-both-files-inside-one-visual-diff.png differ
diff --git a/docs/screenshots/a-non-diff-code-fence-is-left-untouched.png b/docs/screenshots/a-non-diff-code-fence-is-left-untouched.png
new file mode 100644
index 0000000..f8546c1
Binary files /dev/null and b/docs/screenshots/a-non-diff-code-fence-is-left-untouched.png differ
diff --git a/docs/screenshots/copying-a-rendered-diff-puts-the-raw-diff-text-on-the-clipboard.png b/docs/screenshots/copying-a-rendered-diff-puts-the-raw-diff-text-on-the-clipboard.png
new file mode 100644
index 0000000..75f8690
Binary files /dev/null and b/docs/screenshots/copying-a-rendered-diff-puts-the-raw-diff-text-on-the-clipboard.png differ
diff --git a/docs/screenshots/malformed-diff-text-falls-back-to-the-readable-plain-code-block.png b/docs/screenshots/malformed-diff-text-falls-back-to-the-readable-plain-code-block.png
new file mode 100644
index 0000000..be89b18
Binary files /dev/null and b/docs/screenshots/malformed-diff-text-falls-back-to-the-readable-plain-code-block.png differ
diff --git a/docs/screenshots/maximizing-a-rendered-diff-opens-a-single-fullscreen-overlay.png b/docs/screenshots/maximizing-a-rendered-diff-opens-a-single-fullscreen-overlay.png
new file mode 100644
index 0000000..7465f7a
Binary files /dev/null and b/docs/screenshots/maximizing-a-rendered-diff-opens-a-single-fullscreen-overlay.png differ
diff --git a/docs/screenshots/the-overlay-closes-via-a-backdrop-click.png b/docs/screenshots/the-overlay-closes-via-a-backdrop-click.png
new file mode 100644
index 0000000..a3cc7b2
Binary files /dev/null and b/docs/screenshots/the-overlay-closes-via-a-backdrop-click.png differ
diff --git a/docs/screenshots/the-overlay-closes-via-its-close-button-and-the-inline-diff-survives.png b/docs/screenshots/the-overlay-closes-via-its-close-button-and-the-inline-diff-survives.png
new file mode 100644
index 0000000..b770ad1
Binary files /dev/null and b/docs/screenshots/the-overlay-closes-via-its-close-button-and-the-inline-diff-survives.png differ
diff --git a/docs/screenshots/the-overlay-closes-via-the-escape-key.png b/docs/screenshots/the-overlay-closes-via-the-escape-key.png
new file mode 100644
index 0000000..8e07426
Binary files /dev/null and b/docs/screenshots/the-overlay-closes-via-the-escape-key.png differ
diff --git a/docs/screenshots/the-rendered-diff-offers-maximize-and-copy.png b/docs/screenshots/the-rendered-diff-offers-maximize-and-copy.png
new file mode 100644
index 0000000..ca0341f
Binary files /dev/null and b/docs/screenshots/the-rendered-diff-offers-maximize-and-copy.png differ