diff --git a/.gitattributes b/.gitattributes
index 033ffdd..54cae2f 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -1,7 +1,19 @@
-/tests export-ignore
-/docs export-ignore
-/phpunit.xml export-ignore
-/composer.json export-ignore
-/composer.lock export-ignore
-/.gitignore export-ignore
-/.gitattributes export-ignore
+# Exclude dev files from `git archive` (used by release.sh to build release zip)
+/tests/                  export-ignore
+/docs/                   export-ignore
+/phpunit.xml             export-ignore
+/composer.json           export-ignore
+/composer.lock           export-ignore
+/.phpunit.result.cache   export-ignore
+/.beads/                 export-ignore
+/.claude/                export-ignore
+/CLAUDE.md               export-ignore
+/AGENTS.md               export-ignore
+/release.sh              export-ignore
+/dist/                   export-ignore
+/.gitignore              export-ignore
+/.gitattributes          export-ignore
+/.DS_Store               export-ignore
+
+# NOTE: includes/lib/plugin-update-checker/ MUST NOT be excluded —
+# it is required at runtime on the target WP site.