feat: add decorate-pr composite action for pull request review decoration

README.md

@@ -16,7 +16,7 @@ revision.
 
 ## Use In Other Repositories
 
-Vociferate ships three composite actions covering release preparation, release publication, and coverage badge publishing.
+Vociferate ships composite actions covering release preparation, release publication, coverage badge publishing, and pull request decoration.
 Release tags now exist; pin all action and reusable-workflow references to the same released tag (for example, `@v1.0.1`) instead of `@main`.
 
 For agentic coding partners, see [`AGENTS.md`](AGENTS.md) for a direct integration playbook, selection matrix, and copy-paste workflow patterns.
@@ -131,6 +131,30 @@ Run your coverage tests first, then call the action to generate `coverage.html`,
     echo "Badge: ${{ steps.coverage.outputs.badge-url }}"
 ```
 
+### `decorate-pr` - annotate pull requests with coverage and changes
+
+Decorate pull requests with coverage badges, coverage percentages, and unreleased changelog entries. The action creates a new comment or updates an existing one on each run.
+
+```yaml
+- name: Run tests with coverage
+  run: go test -covermode=atomic -coverprofile=coverage.out ./...
+
+- id: coverage
+  uses: git.hrafn.xyz/aether/vociferate/coverage-badge@v1.0.0
+  with:
+    artefact-bucket-name: ${{ vars.ARTEFACT_BUCKET_NAME }}
+    artefact-bucket-endpoint: ${{ vars.ARTEFACT_BUCKET_ENDPONT }}
+
+- name: Decorate pull request
+  if: github.event_name == 'pull_request'
+  uses: git.hrafn.xyz/aether/vociferate/decorate-pr@v1.0.0
+  with:
+    coverage-percentage: ${{ steps.coverage.outputs.total }}
+    badge-url: ${{ steps.coverage.outputs.badge-url }}
+```
+
+The action automatically finds existing vociferate comments by their marker and updates them instead of creating duplicates. This keeps PR timelines clean while keeping review information current.
+
 ## Why The Name
 
 > **vociferate** _(verb)_: to cry out loudly or forcefully.