diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..b1b355f
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,21 @@
+# Exclude dev files from `git archive` (release.sh build)
+/tests/                  export-ignore
+/docs/                   export-ignore
+/phpunit.xml.dist        export-ignore
+/patchwork.json          export-ignore
+/composer.json           export-ignore
+/composer.lock           export-ignore
+/.phpunit.result.cache   export-ignore
+/.beads/                 export-ignore
+/.claude/                export-ignore
+/.gitea/                 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 —
+# required at runtime on target WP site.