docs: enhance decorate-pr documentation with changelog gate examples

README.md

@@ -143,6 +143,8 @@ Decorate pull requests with coverage badges, coverage percentages, and unrelease
 `decorate-pr` also runs a preflight comment API check so workflows fail early
 with a clear message when token permissions are insufficient.
 
+#### Basic Usage
+
 ```yaml
 - name: Run tests with coverage
   run: go test -covermode=atomic -coverprofile=coverage.out ./...
@@ -161,6 +163,55 @@ with a clear message when token permissions are insufficient.
     badge-url: ${{ steps.coverage.outputs.badge-url }}
 ```
 
+#### Changelog Gate (Strict Mode)
+
+Enable changelog validation to enforce that code changes include `Unreleased` changelog entries. The gate fails the workflow in strict mode, or warns in soft mode:
+
+```yaml
+- name: Decorate pull request with changelog gate
+  if: github.event_name == 'pull_request'
+  uses: git.hrafn.xyz/aether/vociferate/decorate-pr@v1.0.2
+  with:
+    coverage-percentage: ${{ steps.coverage.outputs.total }}
+    badge-url: ${{ steps.coverage.outputs.badge-url }}
+    enable-changelog-gate: true
+    changelog-gate-mode: strict
+    changelog-gate-required-for: 'code,behavior,security,workflow,tooling'
+    changelog-gate-allow-docs-only: true
+    changelog-gate-docs-globs: 'docs/**,**.md,**.txt,**.rst'
+    changelog-gate-skip-labels: 'skip-changelog'
+```
+
+The gate automatically:
+- Parses diffs to detect docs-only PRs (skips requirement for doc-only changes)
+- Counts `Unreleased` additions using section-aware parsing (ignores edits outside the section)
+- Checks PR labels for skip exemptions (for example, `skip-changelog`)
+- Outputs decision status and remediation guidance in the PR comment
+- Handles both strict (fail) and soft (warn) modes
+
+Decision outputs enable downstream workflow logic:
+
+```yaml
+- name: Decorate PR and check gate
+  id: decorate
+  if: github.event_name == 'pull_request'
+  uses: git.hrafn.xyz/aether/vociferate/decorate-pr@v1.0.2
+  with:
+    coverage-percentage: ${{ steps.coverage.outputs.total }}
+    badge-url: ${{ steps.coverage.outputs.badge-url }}
+    enable-changelog-gate: true
+    changelog-gate-mode: soft
+
+- name: Gate decision
+  run: |
+    echo "Gate passed: ${{ steps.decorate.outputs.gate-passed }}"
+    echo "Is docs-only PR: ${{ steps.decorate.outputs.docs-only }}"
+    echo "Unreleased additions: ${{ steps.decorate.outputs.unreleased-additions-count }}"
+    if [[ "${{ steps.decorate.outputs.gate-passed }}" == "false" ]]; then
+      echo "Gate failure reason: ${{ steps.decorate.outputs.gate-failure-reason }}"
+    fi
+```
+
 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