docs: behaviour docs + screenshots from the e2e run

README.md

@@ -1,5 +1,11 @@
 # Chat Comments — Agent Zero plugin
 
+<!-- BADGES:START (generated by the devkit — `make badges`) -->
+
+[![plugin-e2e](https://github.com/agent-zero-plugins/agent-zero-plugin-chat-comments/actions/workflows/plugin-e2e.yml/badge.svg?branch=main)](https://github.com/agent-zero-plugins/agent-zero-plugin-chat-comments/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-chat-comments/tree/main/tests/e2e/features) [![Release](https://img.shields.io/github/v/tag/agent-zero-plugins/agent-zero-plugin-chat-comments?label=release&sort=semver)](https://github.com/agent-zero-plugins/agent-zero-plugin-chat-comments/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-chat-comments/blob/main/LICENSE) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/agent-zero-plugins/agent-zero-plugin-chat-comments/blob/main/CONTRIBUTING.md)
+
+<!-- BADGES:END -->
+
 > Select text in any chat message and attach a **Google-Docs-style comment** to it.
 > Comments are highlighted inline, listed in a manager modal, **persisted per chat**,
 > and can be sent to the prompt box as a single review request for the agent to address.
@@ -157,4 +163,4 @@ telemetry. See [SECURITY.md](SECURITY.md).
 
 ## License
 
-[Apache-2.0](LICENSE).
+[Apache-2.0](LICENSE).

docs/BEHAVIOUR.md

@@ -0,0 +1,71 @@
+# Chat Comments — 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. 11 of 12 scenarios have one.
+
+## Commenting on a chat
+
+### The comments control is present
+<sub>BEH-1, UI-1</sub>
+
+![The comments control is present](screenshots/the-comments-control-is-present.png)
+
+### A comment added to a chat is remembered
+<sub>BEH-2, BEH-11, BEH-12</sub>
+
+![A comment added to a chat is remembered](screenshots/a-comment-added-to-a-chat-is-remembered.png)
+
+### A comment can be attached to selected message text
+<sub>BEH-5, BEH-7, BEH-8</sub>
+
+![A comment can be attached to selected message text](screenshots/a-comment-can-be-attached-to-selected-message-text.png)
+
+### A comment carries its attribution and creation time
+<sub>BEH-8, BEH-11</sub>
+
+![A comment carries its attribution and creation time](screenshots/a-comment-carries-its-attribution-and-creation-time.png)
+
+### A comment can be edited
+<sub>BEH-10</sub>
+
+![A comment can be edited](screenshots/a-comment-can-be-edited.png)
+
+### A comment can be deleted
+<sub>BEH-10</sub>
+
+![A comment can be deleted](screenshots/a-comment-can-be-deleted.png)
+
+### Comments stay with their chat when I switch away and back
+<sub>BEH-3</sub>
+
+![Comments stay with their chat when I switch away and back](screenshots/comments-stay-with-their-chat-when-i-switch-away-and-back.png)
+
+### One message can carry several comments
+<sub>BEH-8, BEH-9</sub>
+
+![One message can carry several comments](screenshots/one-message-can-carry-several-comments.png)
+
+### Both my messages and agent replies can be commented
+<sub>BEH-5, BEH-8</sub>
+
+![Both my messages and agent replies can be commented](screenshots/both-my-messages-and-agent-replies-can-be-commented.png)
+
+### An empty comment is not accepted
+<sub>BEH-8, BEH-12, EC-6</sub>
+
+![An empty comment is not accepted](screenshots/an-empty-comment-is-not-accepted.png)
+
+### The comments service rejects malformed requests
+<sub>BEH-11, EC-4</sub>
+
+![The comments service rejects malformed requests](screenshots/the-comments-service-rejects-malformed-requests.png)
+
+### Comments can be sent to the prompt box
+<sub>BEH-13, BEH-14</sub>
+
+_No screenshot captured for this scenario in the last run._