docs: refine changelog gate documentation formatting and descriptions

AGENTS.md

@@ -229,11 +229,21 @@ Useful optional inputs:
 - `changelog` (default `CHANGELOG.md`)
 - `comment-title` (default `Vociferate Review`)
 - `token` (defaults to workflow token)
+- `enable-changelog-gate` (default `false`) - Enable changelog validation gate
+- `changelog-gate-mode` (default `soft`) - `strict` or `soft` mode for gate
+- `changelog-gate-required-for` (default `code,behavior,security,workflow,tooling`) - Change types requiring entries
+- `changelog-gate-allow-docs-only` (default `true`) - Skip requirement for docs-only PRs
+- `changelog-gate-docs-globs` (default `docs/**,**.md,**.txt,**.rst`) - Docs file patterns
+- `changelog-gate-skip-labels` (default empty) - PR labels that bypass requirement
 
 Primary outputs:
 
-- `comment-id`
+- `comment-id` - Comment ID
-- `comment-url`
+- `comment-url` - Comment URL
+- `gate-passed` - Whether changelog gate validation passed
+- `docs-only` - Whether PR is docs-only
+- `unreleased-additions-count` - Number of Unreleased additions detected
+- `gate-failure-reason` - Reason for gate failure, if applicable
 
 ## Guardrails For Agents
 

CHANGELOG.md

@@ -13,6 +13,14 @@ A `### Breaking` section is used in addition to Keep a Changelog's standard sect
 
 ### Added
 
+- Added changelog gate validation to `decorate-pr` action for enforcing changelog updates on qualifying code changes.
+- Changelog gate modes: `strict` (fails job on violation) and `soft` (warns via PR comment).
+- Docs-only PR exemption with customizable glob patterns for documentation files.
+- PR label-based exemptions for changelog gate (example: `skip-changelog`).
+- Precise diff parsing: validates only added lines within the Unreleased section.
+- Gate decision outputs: `gate-passed`, `docs-only`, `unreleased-additions-count`, `gate-failure-reason` for reuse downstream.
+- Integrated remediation guidance in PR comments showing how to add changelog entries.
+
 ### Changed
 
 ### Removed

README.md

@@ -176,13 +176,14 @@ Enable changelog validation to enforce that code changes include `Unreleased` ch
     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-required-for: "code,behavior,security,workflow,tooling"
     changelog-gate-allow-docs-only: true
-    changelog-gate-docs-globs: 'docs/**,**.md,**.txt,**.rst'
+    changelog-gate-docs-globs: "docs/**,**.md,**.txt,**.rst"
-    changelog-gate-skip-labels: 'skip-changelog'
+    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`)