docs: move next-release docs out of .pi

9 files changed, 35 insertions, 18 deletions

diff --git a/.pi/prompts/pre-release-audit.md b/.pi/prompts/pre-release-audit.md
index 3b54f6d1..62fe4362 100644
--- a/.pi/prompts/pre-release-audit.md
+++ b/.pi/prompts/pre-release-audit.md
@@ -44,10 +44,10 @@ Process:
      - formatting-only changes
      - comment-only/doc-only changes unless they materially affect users
 
-6. Audit `.pi/docs/CHANGELOG.md` and issue references.
+6. Audit `docs/next/CHANGELOG.md` and issue references.
    - Treat root `CHANGELOG.md` as the latest released changelog.
-   - Treat `.pi/docs/CHANGELOG.md` as the next-release changelog.
-   - Compare meaningful user-facing changes in the commit range against `.pi/docs/CHANGELOG.md`.
+   - Treat `docs/next/CHANGELOG.md` as the next-release changelog.
+   - Compare meaningful user-facing changes in the commit range against `docs/next/CHANGELOG.md`.
    - Flag missing entries for new features, bug fixes, removals, breaking changes, defaults, compatibility changes, user-visible command/config/API behavior, and security-relevant changes.
    - Inspect commit bodies for issue reference lines in the form `refs #<issue-number>`.
    - Flag normal commits that use GitHub closing keywords like `fixes #<issue-number>`, `closes #<issue-number>`, or `resolves #<issue-number>`, because they close issues before release when they land on `master`.
@@ -60,14 +60,14 @@ Process:
 
 7. Audit next-release public docs.
    - Treat root `README.md`, `CONFIGURATION.md`, `INTEGRATIONS.md`, and `SOCKET_API.md` as the latest released public docs.
-   - Treat `.pi/docs/README.md`, `.pi/docs/CONFIGURATION.md`, `.pi/docs/INTEGRATIONS.md`, and `.pi/docs/SOCKET_API.md` as the next-release versions.
-   - Compare meaningful user-facing changes in the range against `.pi/docs/` first.
+   - Treat `docs/next/README.md`, `docs/next/CONFIGURATION.md`, `docs/next/INTEGRATIONS.md`, and `docs/next/SOCKET_API.md` as the next-release versions.
+   - Compare meaningful user-facing changes in the range against `docs/next/` first.
    - Flag missing next-release docs for new or changed features, commands, config keys, protocol behavior, integrations, defaults, and compatibility notes.
-   - Compare `.pi/docs/` against the root docs. Flag each difference as intended to ship in this release, stale, or needing user decision.
+   - Compare `docs/next/` against the root docs. Flag each difference as intended to ship in this release, stale, or needing user decision.
    - Also audit `website/` and example config snippets for release readiness, but keep them aligned with the latest published release unless the user explicitly asks for prerelease docs.
 
 8. Verify finalization state.
-   - Before `just release`, approved `.pi/docs/*` files must be copied to their root counterparts.
+   - Before `just release`, approved `docs/next/*` files must be copied to their root counterparts.
    - Run or recommend:
      ```bash
      just release-docs-check
@@ -77,8 +77,8 @@ Process:
 
 9. Apply changes only when asked.
    - Do not edit files during the audit unless the user explicitly asks you to apply fixes.
-   - When asked to apply audit fixes, update `.pi/docs/CHANGELOG.md` and any relevant `.pi/docs/` files first.
-   - When asked to finalize release docs, copy approved `.pi/docs/` files into the matching root files and run `just release-docs-check`.
+   - When asked to apply audit fixes, update `docs/next/CHANGELOG.md` and any relevant `docs/next/` files first.
+   - When asked to finalize release docs, copy approved `docs/next/` files into the matching root files and run `just release-docs-check`.
 
 Output format:
 
diff --git a/AGENTS.md b/AGENTS.md
index f5258d5f..21a9344e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -51,10 +51,10 @@ Unit tests live next to the code (`#[cfg(test)] mod tests`). If you add behavior
 ## Conventions
 
 - Conventional commits, lowercase, no emojis.
-- Do not edit root `CHANGELOG.md` during normal feature or fix work. For user-facing features, fixes, removals, breaking changes, and meaningful behavior changes, update `.pi/docs/CHANGELOG.md` in the same change when it makes sense.
+- Do not edit root `CHANGELOG.md` during normal feature or fix work. Maintainers prepare `docs/next/CHANGELOG.md` during release review unless explicitly asked to update it earlier.
 - Treat the root public docs as the latest released docs. Do not document unreleased behavior in root `README.md`, `CONFIGURATION.md`, `INTEGRATIONS.md`, `SOCKET_API.md`, or `CHANGELOG.md` during normal feature or fix work.
-- Treat `.pi/docs/README.md`, `.pi/docs/CONFIGURATION.md`, `.pi/docs/INTEGRATIONS.md`, `.pi/docs/SOCKET_API.md`, and `.pi/docs/CHANGELOG.md` as the next-release versions of those public docs. When unreleased work needs public documentation, update the matching file under `.pi/docs/` instead of the root file.
-- Before release, copy the approved `.pi/docs/` versions into the root public docs. `just release` blocks until each root public doc and `CHANGELOG.md` are identical to their `.pi/docs/` counterparts.
+- Treat `docs/next/README.md`, `docs/next/CONFIGURATION.md`, `docs/next/INTEGRATIONS.md`, `docs/next/SOCKET_API.md`, and `docs/next/CHANGELOG.md` as the next-release versions of those public docs. When unreleased work needs public documentation, update the matching file under `docs/next/` instead of the root file.
+- Before release, copy the approved `docs/next/` versions into the root public docs. `just release` blocks until each root public doc and `CHANGELOG.md` are identical to their `docs/next/` counterparts.
 - Keep 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 normal feature or fix commit relates to a GitHub issue, add a commit body line `refs #<issue-number>` after the subject. Use this shape:
@@ -70,7 +70,7 @@ Unit tests live next to the code (`#[cfg(test)] mod tests`). If you add behavior
 
 ## Releases
 
-Before cutting a release, run `/pre-release-audit` to compare commits since the last tag against `.pi/docs/CHANGELOG.md` and `.pi/docs/`, then copy the approved next-release docs and changelog into the root public docs. The release script promotes the root changelog's `## Unreleased` section into the versioned entry and copies the prepared changelog back to `.pi/docs/CHANGELOG.md` so the next cycle starts clean.
+Before cutting a release, run `/pre-release-audit` to compare commits since the last tag against `docs/next/CHANGELOG.md` and `docs/next/`, then copy the approved next-release docs and changelog into the root public docs. The release script promotes the root changelog's `## Unreleased` section into the versioned entry and copies the prepared changelog back to `docs/next/CHANGELOG.md` so the next cycle starts clean.
 
 Default release flow:
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f6be5604..45aeae8b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -46,6 +46,23 @@ If your issue does not make the direction clear, it will likely be closed.
 
 If you plan to implement the change yourself, say that directly in the issue and use the `intends-to-pr` label. That signals intent. It is not approval.
 
+## Documentation for unreleased changes
+
+The root docs describe the latest released version of herdr. Do not update root `README.md`, `CONFIGURATION.md`, `INTEGRATIONS.md`, `SOCKET_API.md`, or `CHANGELOG.md` for normal PRs.
+
+If your PR changes user-facing behavior, update the matching next-release docs under `docs/next/` instead.
+
+Examples:
+
+- config changes: update `docs/next/CONFIGURATION.md`
+- integration changes: update `docs/next/INTEGRATIONS.md`
+- socket/API changes: update `docs/next/SOCKET_API.md`
+- workflow or usage changes: update `docs/next/README.md`
+
+You do not need to edit the changelog for normal PRs. Maintainers prepare `docs/next/CHANGELOG.md` during release review.
+
+If you are unsure whether docs are needed, mention it in the PR.
+
 ## Before submitting a PR
 
 Install the repo hook once in your clone.
diff --git a/.pi/docs/CHANGELOG.md b/docs/next/CHANGELOG.md
index 72209d15..72209d15 100644
--- a/.pi/docs/CHANGELOG.md
+++ b/docs/next/CHANGELOG.md
diff --git a/.pi/docs/CONFIGURATION.md b/docs/next/CONFIGURATION.md
index ee524942..ee524942 100644
--- a/.pi/docs/CONFIGURATION.md
+++ b/docs/next/CONFIGURATION.md
diff --git a/.pi/docs/INTEGRATIONS.md b/docs/next/INTEGRATIONS.md
index ff46d0c5..ff46d0c5 100644
--- a/.pi/docs/INTEGRATIONS.md
+++ b/docs/next/INTEGRATIONS.md
diff --git a/.pi/docs/README.md b/docs/next/README.md
index 1b5ed7fa..1b5ed7fa 100644
--- a/.pi/docs/README.md
+++ b/docs/next/README.md
diff --git a/.pi/docs/SOCKET_API.md b/docs/next/SOCKET_API.md
index 783d6e97..783d6e97 100644
--- a/.pi/docs/SOCKET_API.md
+++ b/docs/next/SOCKET_API.md
diff --git a/justfile b/justfile
index 30fabe1b..794c398b 100644
--- a/justfile
+++ b/justfile
@@ -32,11 +32,11 @@ build:
 build-libghostty-vt:
     scripts/build_vendored_libghostty_vt.sh
 
-# Check that public docs and changelog have been finalized from .pi/docs before release
+# Check that public docs and changelog have been finalized from docs/next before release
 release-docs-check:
     @for file in README.md CONFIGURATION.md INTEGRATIONS.md SOCKET_API.md CHANGELOG.md; do \
-        if ! diff -u "$file" ".pi/docs/$file"; then \
-            echo "error: $file differs from .pi/docs/$file; finalize release docs before releasing"; \
+        if ! diff -u "$file" "docs/next/$file"; then \
+            echo "error: $file differs from docs/next/$file; finalize release docs before releasing"; \
             exit 1; \
         fi; \
     done
@@ -53,11 +53,11 @@ release version:
     fi
     just release-docs-check
     python3 scripts/changelog.py prepare --version {{version}}
-    cp CHANGELOG.md .pi/docs/CHANGELOG.md
+    cp CHANGELOG.md docs/next/CHANGELOG.md
     sed -i.bak 's/^version = ".*"/version = "{{version}}"/' Cargo.toml && rm -f Cargo.toml.bak
     cargo update -p herdr --offline
     just check
-    git add CHANGELOG.md .pi/docs/CHANGELOG.md Cargo.toml Cargo.lock
+    git add CHANGELOG.md docs/next/CHANGELOG.md Cargo.toml Cargo.lock
     git diff --cached --quiet || git commit -m "release: v{{version}}"
     git tag -a v{{version}} -m "v{{version}}"
     git push --follow-tags