diff --git a/.gitattributes b/.gitattributes
index fcb21d3..d4ca542 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -7,5 +7,12 @@
 *.php diff=php
 
 /.github export-ignore
-CHANGELOG.md export-ignore
 .styleci.yml export-ignore
+
+# Internal-only — never published to the PUBLIC repo. promote.sh copies a release tree with
+# `git archive`, which honours export-ignore, so these are dropped automatically. CHANGELOG.md is
+# deliberately NOT export-ignored: the public Versions page fetches it from the public repo.
+/CLAUDE.md export-ignore
+/rules.md export-ignore
+/handoff.md export-ignore
+/docs export-ignore
diff --git a/scripts/promote.test.sh b/scripts/promote.test.sh
index 4632a5d..b8da7fb 100755
--- a/scripts/promote.test.sh
+++ b/scripts/promote.test.sh
@@ -1,17 +1,23 @@
 #!/usr/bin/env bash
-# Test: promote.sh extracts a tag's tree into the public repo working dir (excluding .git + .github),
+# Test: promote.sh extracts a tag's tree into the public repo working dir (excluding .git + .github,
+# and anything marked `export-ignore` in .gitattributes — internal docs), keeps CHANGELOG.md public,
 # commits "Release <tag>" and creates the tag. The public repo's own .git is preserved.
 set -euo pipefail
 here="$(cd "$(dirname "$0")" && pwd)"
 work="$(mktemp -d)"; trap 'rm -rf "$work"' EXIT
 export GIT_AUTHOR_NAME=t GIT_AUTHOR_EMAIL=t@t GIT_COMMITTER_NAME=t GIT_COMMITTER_EMAIL=t@t
 
-# source repo with a tag, a .github dir and an .env.example
+# source repo with a tag, a .github dir, an .env.example, a public CHANGELOG.md, and internal files
+# that .gitattributes marks export-ignore (must NOT reach the public repo).
 git init -q "$work/src"
-mkdir -p "$work/src/.github/workflows"
+mkdir -p "$work/src/.github/workflows" "$work/src/docs/superpowers"
 printf 'app\n' > "$work/src/app.txt"
 printf 'CLUSEV_REPOSITORY=\n' > "$work/src/.env.example"
 printf 'name: ci\n' > "$work/src/.github/workflows/ci.yml"
+printf '# Changelog\n' > "$work/src/CHANGELOG.md"
+printf '/CLAUDE.md export-ignore\n/docs export-ignore\n' > "$work/src/.gitattributes"
+printf 'internal\n' > "$work/src/CLAUDE.md"
+printf 'internal spec\n' > "$work/src/docs/superpowers/spec.md"
 git -C "$work/src" add -A && git -C "$work/src" commit -qm init && git -C "$work/src" tag v1.0.0
 
 # empty public repo (its own history)
@@ -21,7 +27,10 @@ bash "$here/promote.sh" "$work/src" v1.0.0 "$work/pub" "Release v1.0.0"
 
 test -f "$work/pub/app.txt"        || { echo "FAIL: tree not copied"; exit 1; }
 test -f "$work/pub/.env.example"   || { echo "FAIL: .env.example missing"; exit 1; }
+test -f "$work/pub/CHANGELOG.md"   || { echo "FAIL: CHANGELOG.md must stay public (Versions page fetches it)"; exit 1; }
 test ! -d "$work/pub/.github"      || { echo "FAIL: .github leaked to public"; exit 1; }
+test ! -f "$work/pub/CLAUDE.md"    || { echo "FAIL: internal CLAUDE.md leaked to public"; exit 1; }
+test ! -d "$work/pub/docs"         || { echo "FAIL: internal docs/ leaked to public"; exit 1; }
 test -d "$work/pub/.git"           || { echo "FAIL: public .git clobbered"; exit 1; }
 git -C "$work/pub" rev-parse v1.0.0 >/dev/null 2>&1 || { echo "FAIL: tag missing"; exit 1; }
 git -C "$work/pub" log -1 --pretty=%s | grep -qx 'Release v1.0.0' || { echo "FAIL: commit message"; exit 1; }