ci: run doc-bot automatically on every pull request push

.gitattributes

@@ -16,7 +16,7 @@
 .gitattributes text
 .gitignore text
 
-.github/workflows/*.lock.yml linguist-generated=true merge=ours
+.github/workflows/*.lock.yml linguist-generated=true
 
 vaadin-dev text eol=lf
 *.ps1 text eol=lf

.github/aw/actions-lock.json

@@ -10,15 +10,10 @@
       "version": "v9",
       "sha": "373c709c69115d41ff229c7e5df9f8788daa9553"
     },
-    "github/gh-aw-actions/setup-cli@v0.80.4": {
-      "repo": "github/gh-aw-actions/setup-cli",
-      "version": "v0.80.4",
-      "sha": "00c24a5774577e7282046aa2225105571a8f4195"
-    },
-    "github/gh-aw-actions/setup@v0.80.4": {
+    "github/gh-aw-actions/setup@v0.86.2": {
       "repo": "github/gh-aw-actions/setup",
-      "version": "v0.80.4",
-      "sha": "00c24a5774577e7282046aa2225105571a8f4195"
+      "version": "v0.86.2",
+      "sha": "6aab9e5b5c91c615506061f09bedd81a23babe3c"
     }
   }
 }

.github/workflows/README.md

@@ -15,13 +15,56 @@ files directly — edit the source `.md` file and regenerate.
 
 | Source (edit this) | Generated (do not edit) | Purpose |
 |---|---|---|
-| `doc-bot.md` | `doc-bot.lock.yml` | Documentation bot that analyzes PRs and proposes documentation updates in `vaadin/docs`. |
+| `doc-bot.md` | `doc-bot.lock.yml` | Documentation bot that analyzes a pull request merged into `main` and opens a draft documentation pull request for it in `vaadin/docs`. |
 | `diagram-bot.md` | `diagram-bot.lock.yml` | Diagram bot that posts a Mermaid diagram on pull requests whose change is about structure, flow, or ordering. |
 | _(none — generated automatically)_ | `agentics-maintenance.yml` | Scheduled maintenance job that closes expired discussions, issues, and pull requests created by agentic workflows. Regenerated whenever any agentic workflow uses the `expires` field on a safe-output. |
 
 Pinned action versions and SHAs used by the generated workflows are
 tracked in [`../aw/actions-lock.json`](../aw/actions-lock.json).
 
+### Documentation Bot
+
+`doc-bot.md` runs once per pull request, when it is merged into `main`.
+Running after the merge rather than on every push means the change has
+already been reviewed and approved, so the documentation is written
+against its final shape instead of an in-progress feature — and one run
+replaces the burst of runs a long-lived pull request used to trigger.
+
+It reads the whole pull request and decides whether the change is
+something a reader of [vaadin/docs](https://github.com/vaadin/docs) would
+need to know about. When it is, the bot opens a draft documentation pull
+request there.
+
+Four filters keep the bot off pull requests that cannot need
+documentation, cheapest first:
+
+1. **Base branch.** Only merges into `main` count. Development lands
+   there and is cherry-picked into the maintenance branches, so `main`
+   sees every change once, and a backport does not open a second
+   documentation pull request for a change already documented.
+2. **Paths.** A pull request that touches only tests, build files,
+   `.github/`, or Markdown never starts a runner.
+3. **Conventional-commit type.** Titles starting with `test:`, `ci:`,
+   `refactor:`, `chore:`, or `build:` (with or without a scope) are
+   skipped. `fix:`, `feat:`, `docs:`, and `perf:` are not.
+4. **The agent itself.** It classifies the diff and stops when everything
+   in it is internal, test-only, or build-only, recording the reason in
+   the run log without commenting on the pull request.
+
+The bot leaves one standing comment on the source pull request linking to
+the documentation pull request; a later run replaces it rather than adding
+another. It says nothing at all when there is nothing to document.
+
+There is no manual trigger. A pull request the type filter passed over
+gets no documentation pull request, and the way to correct that is to
+document the change by hand in `vaadin/docs`. To make the bot look at a
+pull request again, re-run the workflow from the Actions UI; Phase 0 then
+finds the documentation pull request an earlier run opened and commits
+onto its branch instead of opening a second one.
+
+An abandoned documentation pull request closes itself: `expires: 30` marks
+it, and the scheduled `agentics-maintenance` workflow does the closing.
+
 ### Diagram Bot
 
 `diagram-bot.md` runs once per pull request, on `opened` and on