docs: document verify_manual_action.yml and require doc updates for features

- README: rewrite the "Automated Verification in CI" section to list both
  verify workflows (dependabot + manual) and describe their triggers,
  permissions, and pass/fail semantics.
- AGENTS.md: add a "Documentation" section requiring user-visible changes
  (workflows, scripts, CLI flags) to ship with reference-doc updates in
  the same PR.

Generated-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: potiuk

AGENTS.md

@@ -55,6 +55,15 @@ When creating a PR via `gh pr create --web`, GitHub will present a template choo
 template that matches the type of change. When opening a PR URL directly, you can append
 `&template=action_approval.md` or `&template=code_change.md` to pre-fill the appropriate template.
 
+## Documentation
+
+When you add, change, or remove a user-visible feature, workflow, script, or flag, update the
+corresponding reference documentation in the same PR. At minimum this means the relevant section of
+`README.md`; check other `*.md` files in the area you touched for stale references as well. A PR
+that introduces a new workflow in `.github/workflows/`, a new utility under `utils/`, or a new CLI
+flag is not complete until the docs describe it — reviewers should not have to ask "is this
+documented?".
+
 ## License headers
 
 All files must include the Apache License 2.0 header where the file format supports it. Use the

README.md

@@ -246,7 +246,12 @@ The `--no-gh` mode supports all the same features as the default `gh`-based mode
 
 #### Automated Verification in CI
 
-Dependabot PRs that modify `.github/actions/for-dependabot-triggered-reviews/action.yml` are automatically verified by the `verify_dependabot_action.yml` workflow. It extracts the action reference from the PR, rebuilds the compiled JavaScript in Docker, and compares it against the published version. The workflow reports success or failure but does **not** auto-approve or merge — a human reviewer must still approve.
+Two workflows in `.github/workflows/` run `verify-action-build` on PRs that touch the allow list, so the verification status is visible on every PR as a required-candidate status check:
+
+- **`verify_dependabot_action.yml`** — triggers on Dependabot PRs that modify `.github/actions/for-dependabot-triggered-reviews/action.yml`. Extracts the action reference from the PR, rebuilds the compiled JavaScript in Docker, and compares it against the published version.
+- **`verify_manual_action.yml`** — triggers on human-authored PRs that modify `actions.yml` or `approved_patterns.yml` (i.e. manual allow-list additions / version bumps). Dependabot-authored PRs are skipped, since they are already covered by the workflow above.
+
+Both workflows use a regular `pull_request` trigger with read-only permissions and no PR comments — pass/fail is surfaced through the status check. Neither workflow auto-approves or merges; a human reviewer must still approve.
 
 The script exits with code **1** (failure) when something is unexpectedly broken — for example, the action cannot be compiled, the rebuilt JavaScript is invalid, or required tools are missing. In all other cases it exits with code **0** and produces reviewable diffs: a large diff does not by itself cause an error (e.g. major version bumps will naturally have big diffs). It is always up to a human reviewer to inspect the output, assess the changes, and decide whether the update is safe to approve.