docs: add prerelease docs guardrails

2 files changed, 12 insertions, 2 deletions

diff --git a/.pi/prompts/draft-changelog.md b/.pi/prompts/draft-changelog.md
index 59844e96..1b0bce51 100644
--- a/.pi/prompts/draft-changelog.md
+++ b/.pi/prompts/draft-changelog.md
@@ -44,7 +44,15 @@ Process:
      - formatting-only changes
      - comment-only/doc-only changes unless they materially affect users
 
-6. Draft the changelog entry.
+6. Audit public docs for release readiness.
+   - Treat `HEAD` as the release candidate that will be released after the changelog is drafted.
+   - Compare meaningful user-facing changes in the range against public docs, especially `README.md`, `CONFIGURATION.md`, `INTEGRATIONS.md`, `SOCKET_API.md`, `website/`, and example config snippets.
+   - Flag missing docs for new or changed features, commands, config keys, protocol behavior, integrations, defaults, and compatibility notes that should be documented for this release.
+   - Flag stale docs that now describe behavior incorrectly.
+   - Flag docs that mention work not included in the release range, deferred experiments, or incomplete features that should not ship in public docs yet.
+   - Do not edit docs unless the user explicitly asks; report the docs audit alongside the changelog draft.
+
+7. Draft the changelog entry.
    - Group items under these sections when applicable:
      - `### Added`
      - `### Changed`
@@ -58,7 +66,7 @@ Process:
    - If there are both PRs and direct commits, include both, but exclude direct commits already covered by PRs.
    - For merged PR items, append the PR reference and contributor thanks inline when appropriate, in the form `(#123, thanks @author)`. Do this for merged PRs, not for direct commits.
 
-7. Respect repo reality.
+8. Respect repo reality.
    - If `CHANGELOG.md` exists, read it before proposing edits and follow its existing style.
    - If no changelog file exists, say so explicitly and produce a draft entry only.
    - Do not edit files yet unless the user explicitly asks you to apply the draft.
@@ -69,6 +77,7 @@ Output format:
 - `PRs included:`
 - `Direct commits included:`
 - `Excluded as housekeeping:`
+- `Public docs release-readiness audit:`
 - `Proposed changelog entry:`
 
 If the range has no meaningful user-facing changes, say that plainly instead of forcing entries.
diff --git a/AGENTS.md b/AGENTS.md
index 769da1d0..4c7499ab 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -52,6 +52,7 @@ Unit tests live next to the code (`#[cfg(test)] mod tests`). If you add behavior
 
 - Conventional commits, lowercase, no emojis.
 - Do not edit `CHANGELOG.md` during normal feature or fix work. Changelog entries are drafted and applied immediately before release.
+- Do not advertise unreleased features in public docs before the release is cut. Keep README, `CONFIGURATION.md`, `INTEGRATIONS.md`, `SOCKET_API.md`, website copy, and config examples aligned with the latest published release unless the user explicitly asks for prerelease docs.
 - Put local PRDs, planning notes, and exploratory specs under `.prd/`; that directory is ignored and locally controlled.
 - When a commit fully fixes a GitHub issue, include `fixes #<issue-number>` in the commit body so GitHub closes it on merge.
 - Rust: no `unwrap()` in production code. `tracing` for logging. `#[allow]` only with a comment explaining why.