chore: complete M1.1 runtime QA and release packaging

shop/docs/ADR/002-rest-over-admin-ajax.md

@@ -0,0 +1,17 @@
+# ADR 002 – REST API as Primary for AJAX
+
+**Status**: Accepted
+
+## Context
+
+Search/filter/wishlist/compare/Q&A need async endpoints. `admin-ajax.php` is uncacheable and fires `admin_init`. REST is cache-friendly and has `permission_callback`.
+
+## Decision
+
+- REST (`xshop/v1/*`) for search, filter, wishlist, compare, Q&A.
+- Keep `admin-ajax` only where WC core expects it (cart fragments/mini-cart) or as fallback.
+
+## Consequences
+
+- Requires nonce via `X-WP-Nonce` + localized `wpApiSettings` or custom `xshopData.nonce`.
+- Better compatibility with caching plugins; clearer permission model.