@spree/docs 0.1.80 → 0.1.82

package/dist/developer/core-concepts/customers.md

@@ -84,7 +84,7 @@ const { token, user } = await client.auth.login({
 
 ```bash cURL
 curl -X POST 'https://api.mystore.com/api/v3/store/auth/login' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'Content-Type: application/json' \
   -d '{
     "email": "john@example.com",

package/dist/developer/core-concepts/events.md

@@ -65,7 +65,7 @@ module MyApp
 
     def handle(event)
       order_id = event.payload['id']
-      order = Spree::Order.find_by(id: order_id)
+      order = Spree::Order.find_by_prefix_id(order_id)
       return unless order
 
       # Your custom logic here
@@ -75,6 +75,14 @@ module MyApp
 end
 ```
 
+Then register it in an initializer — subscribers are not auto-discovered (see [Registering Subscribers](#registering-subscribers)):
+
+```ruby config/initializers/event_subscribers.rb
+Rails.application.config.after_initialize do
+  Spree.subscribers << MyApp::OrderCompletedSubscriber
+end
+```
+
 ### Subscriber DSL
 
 The `Spree::Subscriber` class provides a clean DSL for declaring subscriptions:
@@ -164,7 +172,7 @@ The payload contains serialized attributes, not the actual record. To get the re
 ```ruby
 def handle(event)
   record_id = event.payload['id']
-  record = Spree::Order.find_by(id: record_id)
+  record = Spree::Order.find_by_prefix_id(record_id)
   return unless record
 
   # Work with the record
@@ -395,9 +403,7 @@ Models without a matching serializer will use a minimal fallback payload contain
 
 ## Registering Subscribers
 
-Subscribers in `app/subscribers/` are automatically registered during application initialization.
-
-For subscribers in other locations, add them to the `Spree.subscribers` array in an initializer:
+Subscribers are not auto-discovered — every subscriber must be registered explicitly, regardless of where the class lives. Add it to the `Spree.subscribers` array in an initializer:
 
 ```ruby config/initializers/event_subscribers.rb
 Rails.application.config.after_initialize do
@@ -521,7 +527,7 @@ module MyApp
     private
 
     def find_stock_item(event)
-      Spree::StockItem.find_by(id: event.payload['id'])
+      Spree::StockItem.find_by_prefix_id(event.payload['id'])
     end
 
     def stock_dropped_below_threshold?(event, stock_item)

package/dist/developer/core-concepts/markets.md

@@ -96,7 +96,7 @@ const { data: markets } = await client.markets.list()
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/markets' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -112,7 +112,7 @@ const market = await client.markets.resolve('DE')
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/markets/resolve?country=DE' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -141,11 +141,11 @@ const usa = await client.markets.countries.get('mkt_k5nR8xLq', 'US', {
 ```bash cURL
 # List countries in a market
 curl 'https://api.mystore.com/api/v3/store/markets/mkt_k5nR8xLq/countries' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # Get a country with its states
-curl 'https://api.mystore.com/api/v3/store/markets/mkt_k5nR8xLq/countries/US?include=states' \
-  -H 'Authorization: Bearer pk_xxx'
+curl 'https://api.mystore.com/api/v3/store/markets/mkt_k5nR8xLq/countries/US?expand=states' \
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -164,11 +164,11 @@ const germany = await client.countries.get('DE', { include: 'market' })
 ```bash cURL
 # All countries across all markets
 curl 'https://api.mystore.com/api/v3/store/countries' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # Get a country with its market
-curl 'https://api.mystore.com/api/v3/store/countries/DE?include=market' \
-  -H 'Authorization: Bearer pk_xxx'
+curl 'https://api.mystore.com/api/v3/store/countries/DE?expand=market' \
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -189,10 +189,10 @@ const { data: locales } = await client.locales.list()
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/currencies' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 curl 'https://api.mystore.com/api/v3/store/locales' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 

package/dist/developer/core-concepts/media.md

@@ -114,7 +114,7 @@ products.forEach(product => {
 ```bash cURL
 # thumbnail_url is always in the response — no ?expand needed
 curl 'https://api.mystore.com/api/v3/store/products?limit=12' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -143,7 +143,7 @@ product.variants?.forEach(variant => {
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,variants' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 

package/dist/developer/core-concepts/orders.md

@@ -109,30 +109,30 @@ await client.carts.items.delete(cart.id, 'li_xxx')
 ```bash cURL
 # Create a cart
 curl -X POST 'https://api.mystore.com/api/v3/store/carts' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # Get existing cart
 curl 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: abc123'
 
 # Add an item
 curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/items' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: abc123' \
   -H 'Content-Type: application/json' \
   -d '{ "variant_id": "var_xxx", "quantity": 2 }'
 
 # Update quantity
 curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/items/li_xxx' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: abc123' \
   -H 'Content-Type: application/json' \
   -d '{ "quantity": 3 }'
 
 # Remove an item
 curl -X DELETE 'https://api.mystore.com/api/v3/store/carts/cart_xxx/items/li_xxx' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: abc123'
 ```
 
@@ -206,7 +206,7 @@ await client.carts.complete(cartId)
 ```bash cURL
 # Set addresses
 curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: abc123' \
   -H 'Content-Type: application/json' \
   -d '{
@@ -221,14 +221,14 @@ curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
 
 # Select a delivery rate
 curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/fulfillments/ful_xxx' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: abc123' \
   -H 'Content-Type: application/json' \
   -d '{ "selected_delivery_rate_id": "rate_xxx" }'
 
 # Complete the order
 curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/complete' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: abc123'
 ```
 
@@ -249,14 +249,14 @@ await client.carts.discountCodes.remove(cartId, 'SAVE20')
 ```bash cURL
 # Apply a discount code
 curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/discount_codes' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: abc123' \
   -H 'Content-Type: application/json' \
   -d '{ "code": "SAVE20" }'
 
 # Remove a discount code
 curl -X DELETE 'https://api.mystore.com/api/v3/store/carts/cart_xxx/discount_codes/SAVE20' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: abc123'
 ```
 

package/dist/developer/core-concepts/pricing.md

@@ -45,11 +45,11 @@ detailed.variants?.forEach(variant => {
 ```bash cURL
 # Product price is always in the response
 curl 'https://api.mystore.com/api/v3/store/products/spree-tote' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # With variants
 curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=variants' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 

package/dist/developer/core-concepts/products.md

@@ -107,15 +107,15 @@ const sorted = await client.products.list({
 ```bash cURL
 # List products
 curl 'https://api.mystore.com/api/v3/store/products?limit=12&page=1' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # Filter by price and stock
 curl 'https://api.mystore.com/api/v3/store/products?q[price_gte]=10&q[price_lte]=50&q[in_stock]=true' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # Search
 curl 'https://api.mystore.com/api/v3/store/products?q[search]=tote+bag' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -139,7 +139,7 @@ const detailed = await client.products.get('spree-tote', {
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=variants,media,option_types,categories' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -164,11 +164,11 @@ const categoryFilters = await client.products.filters({
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products/filters' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # Scoped to a category
 curl 'https://api.mystore.com/api/v3/store/products/filters?category_id=ctg_xxx' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -228,7 +228,7 @@ product.option_types?.forEach(optionType => {
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products/spree-tee?expand=option_types' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -257,7 +257,7 @@ products.forEach(product => {
 ```bash cURL
 # thumbnail_url is always in the response — no ?expand needed
 curl 'https://api.mystore.com/api/v3/store/products?limit=12' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -286,7 +286,7 @@ product.variants?.forEach(variant => {
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,variants' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -338,15 +338,15 @@ const { data: products } = await client.categories.products.list('clothing/shirt
 ```bash cURL
 # List categories
 curl 'https://api.mystore.com/api/v3/store/categories' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # Get a category by permalink
 curl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # List products in a category
 curl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts/products?limit=12' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 

package/dist/developer/core-concepts/promotions.md

@@ -292,7 +292,7 @@ await client.carts.discountCodes.remove('cart_abc123', 'SUMMER20', {
 ```bash cURL
 # Apply a coupon code
 curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_abc123/coupon_codes' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: <token>' \
   -H 'Content-Type: application/json' \
   -d '{ "code": "SUMMER20" }'

package/dist/developer/core-concepts/search-filtering.md

@@ -29,7 +29,7 @@ const { data: products } = await client.products.list({
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products?q[search]=tote+bag&limit=12' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -47,7 +47,7 @@ const { data: products } = await client.products.list({
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products?q[price_gte]=20&q[price_lte]=100' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -62,7 +62,7 @@ const { data: products } = await client.products.list({
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products?q[in_stock]=true' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -89,15 +89,15 @@ const { data: products } = await client.products.list({
 ```bash cURL
 # Products in a category
 curl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts/products?limit=12' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # Filter by category ID (includes descendants)
 curl 'https://api.mystore.com/api/v3/store/products?q[in_category]=ctg_xxx' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # Multiple categories (OR logic)
 curl 'https://api.mystore.com/api/v3/store/products?q[in_categories][]=ctg_shirts&q[in_categories][]=ctg_pants' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -112,7 +112,7 @@ const { data: products } = await client.products.list({
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products?q[tags_cont]=sale' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -131,7 +131,7 @@ const sorted = await client.products.list({
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products?sort=price_low_to_high' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -157,11 +157,11 @@ const categoryFilters = await client.products.filters({
 ```bash cURL
 # All filters
 curl 'https://api.mystore.com/api/v3/store/products/filters' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # Scoped to a category
 curl 'https://api.mystore.com/api/v3/store/products/filters?category_id=ctg_xxx' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -221,7 +221,7 @@ const { data: products, meta } = await client.products.list({
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products?page=1&limit=24' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 

package/dist/developer/core-concepts/shipments.md

@@ -111,12 +111,12 @@ await client.carts.fulfillments.update(cartId, fulfillment.id, {
 ```bash cURL
 # Get fulfillments
 curl 'https://api.mystore.com/api/v3/store/carts/cart_xxx?expand=fulfillments' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: abc123'
 
 # Select a delivery rate
 curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/fulfillments/ful_xxx' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: abc123' \
   -H 'Content-Type: application/json' \
   -d '{ "selected_delivery_rate_id": "rate_xxx" }'

package/dist/developer/core-concepts/slugs.md

@@ -22,11 +22,11 @@ const category = await client.categories.get('clothing/shirts')
 ```bash cURL
 # By slug
 curl 'https://api.mystore.com/api/v3/store/products/spree-tote' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # By ID
 curl 'https://api.mystore.com/api/v3/store/products/prod_86Rf07xd4z' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -89,11 +89,11 @@ const product = await client.products.get('chaussures-rouges', {
 ```bash cURL
 # English
 curl 'https://api.mystore.com/api/v3/store/products/red-shoes' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # French
 curl 'https://api.mystore.com/api/v3/store/products/chaussures-rouges' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Locale: fr'
 ```
 

package/dist/developer/core-concepts/stores.md

@@ -42,7 +42,7 @@ const store = await client.store.get()
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/store' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 

package/dist/developer/core-concepts/translations.md

@@ -85,7 +85,7 @@ const { data: categories } = await client.categories.list({}, {
 ```bash cURL
 # Fetch product in French
 curl 'https://api.mystore.com/api/v3/store/products/spree-tote' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Locale: fr'
 ```
 

package/dist/developer/core-concepts/users.md

@@ -96,7 +96,7 @@ const { token, user } = await client.auth.login({
 
 ```bash cURL
 curl -X POST 'https://api.mystore.com/api/v3/store/auth/login' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'Content-Type: application/json' \
   -d '{
     "email": "john@example.com",

package/dist/developer/create-spree-app/quickstart.md

@@ -21,7 +21,7 @@ Once complete, your store is running at [http://localhost:3000](http://localhost
 ## Prerequisites
 
 - [Node.js](https://nodejs.org/) 20 or later
-- [Docker](https://docs.docker.com/get-docker/) (for running the Spree backend, PostgreSQL, and Redis)
+- [Docker](https://docs.docker.com/get-docker/) (for running the Spree backend, PostgreSQL, Redis, and Meilisearch)
 
 ## CLI Flags
 
@@ -49,9 +49,9 @@ npx create-spree-app@latest my-store --no-storefront --no-sample-data --no-start
 
 ```text
 my-store/
-├── docker-compose.yml        # Spree backend (prebuilt image) + Postgres + Redis
+├── docker-compose.yml        # Spree backend (prebuilt image) + Postgres + Redis + Meilisearch
 ├── docker-compose.dev.yml    # Alternative: build from local backend/
-├── .env                      # SECRET_KEY_BASE, SPREE_PORT
+├── .env                      # SECRET_KEY_BASE, SPREE_PORT, SPREE_VERSION_TAG
 ├── .gitignore
 ├── package.json              # Convenience scripts
 ├── README.md
@@ -69,10 +69,11 @@ my-store/
 
 ### What's in docker-compose.yml
 
-- **Spree** — runs the `ghcr.io/spree/spree:latest` image on the configured port (default `3000`)
+- **Spree** — `web` (Rails) + `worker` (Sidekiq) running the `ghcr.io/spree/spree:latest` image on the configured port (default `3000`)
 - **PostgreSQL 18** — database with persistent volume
 - **Redis 7** — caching, background jobs, and Action Cable
-- Health checks on all services
+- **Meilisearch** — search engine
+- Health checks on postgres, redis, meilisearch, and web
 
 ## Customizing the Backend
 
@@ -88,7 +89,7 @@ This replaces `docker-compose.yml` with a version that builds from `backend/`, r
 - **Override models** with decorators in `backend/app/models/`
 - **Add controllers** in `backend/app/controllers/`
 - **Configure Spree** in `backend/config/initializers/spree.rb`
-- **Add migrations** with `cd backend && bin/rails generate migration`
+- **Add migrations** with `spree generate migration AddFooToSpreeBars foo:string` (runs inside the container)
 
 See the [Customization Guide](../customization.md) for more details.
 
@@ -98,7 +99,7 @@ The project includes [@spree/cli](../cli/quickstart.md) for managing your Spree
 
 | Command | Description |
 |---------|-------------|
-| `spree dev` | Start backend services and stream logs |
+| `spree dev` | Run the backend in the foreground — streams logs, Ctrl+C stops it |
 | `spree stop` | Stop backend services |
 | `spree update` | Pull latest Spree image and restart (runs migrations automatically) |
 | `spree eject` | Switch from prebuilt image to building from `backend/` |

package/dist/developer/customization/checkout.md

@@ -108,7 +108,7 @@ module MyApp
     subscribes_to 'order.completed'
 
     def handle(event)
-      order = Spree::Order.find_by(id: event.payload['id'])
+      order = Spree::Order.find_by_prefix_id(event.payload['id'])
       return unless order
 
       # Sync to fulfillment system, notify warehouse, etc.

package/dist/developer/customization/decorators.md

@@ -113,19 +113,21 @@ bin/rails g spree:controller_decorator Spree::Admin::ProductsController
 This creates `app/controllers/spree/admin/products_controller_decorator.rb`:
 
 ```ruby
-module Spree
-  module Admin
-    module ProductsControllerDecorator
-      def self.prepended(base)
-        # Class-level configurations go here
-      end
+module Spree::Admin
+  module ProductsControllerDecorator
+    def self.prepended(base)
+      # base.before_action :my_filter
     end
 
-    ProductsController.prepend(ProductsControllerDecorator)
+    # add custom methods here
   end
 end
+
+Spree::Admin::ProductsController.prepend Spree::Admin::ProductsControllerDecorator
 ```
 
+The generator accepts any namespace depth. `Spree::ProductsController` produces a top-level `module Spree` wrapper; `Spree::Api::V3::Store::ProductsController` produces a `module Spree::Api::V3::Store` wrapper. The final `.prepend` line is always fully qualified.
+
 ## Decorating Models
 
 ### Changing Behavior of Existing Methods
@@ -487,7 +489,7 @@ module MyApp
     subscribes_to 'product.updated'
 
     def handle(event)
-      product = Spree::Product.find_by(id: event.payload['id'])
+      product = Spree::Product.find_by_prefix_id(event.payload['id'])
       return unless product
 
       # The payload includes changes, check if name changed

package/dist/developer/customization/quickstart.md

@@ -62,7 +62,7 @@ Spree is a flexible platform allowing you to customize every part of it to suit
         subscribes_to 'order.completed'
 
         def handle(event)
-          order = Spree::Order.find_by(id: event.payload['id'])
+          order = Spree::Order.find_by_prefix_id(event.payload['id'])
           return unless order
 
           # Sync to external service, send notification, etc.

package/dist/developer/deployment/environment_variables.md

@@ -19,7 +19,7 @@ These variables are required to run Spree in production.
 
 > **TIP:** This configuration is used for system emails (e.g. staff invitations, report ready, export complete). Customer facing emails are handled by the [storefront via webhooks](../storefront/nextjs/customization.md#transactional-emails).
 
-Spree works with any SMTP provider (Resend, Postmark, Mailgun, SendGrid, Amazon SES, etc.). Set `SMTP_HOST` to enable email delivery — when not set, emails are logged to stdout.
+Spree works with any SMTP provider (Resend, Postmark, Mailgun, SendGrid, Amazon SES, etc.). Set `SMTP_HOST` to enable email delivery — when not set, no delivery method is configured and production email delivery fails (development opens emails in the browser via `letter_opener`).
 
 | Variable | Default | Description |
 | --- | --- | --- |

package/dist/developer/how-to/custom-order-routing.md

@@ -88,7 +88,12 @@ Spree::OrderRouting::Rules::ClosestLocation.create!(
 )
 ```
 
-Spree's autoloader picks up models under `app/models/` automatically — no separate registration step.
+Register the rule kind so it's available to add and passes the `type` validation. Spree's autoloader picks up the model under `app/models/`; the registry is the curated allowlist (it also drives admin pickers):
+
+```ruby
+# config/initializers/spree.rb
+Spree.order_routing.rules << 'AcmeFresh::OrderRouting::RefrigeratedRule'.constantize
+```
 
 To activate the rule across multiple channels, create one row per channel. That keeps each channel's rule list explicit and lets you tune per-channel preferences independently.
 
@@ -223,7 +228,17 @@ Notes:
 
 ### Step 2: Register the Strategy
 
-Strategies are selected by class name string — set on `Spree::Store` (default) or `Spree::Channel` (override).
+First register the class so it's selectable (this is the allowlist the model validation checks against, and the source for admin strategy pickers):
+
+```ruby
+# config/initializers/spree.rb
+Spree.order_routing.strategies << 'Acme::Oms::Strategy'.constantize
+
+# Optionally drop the legacy escape hatch:
+# Spree.order_routing.strategies.delete(Spree::OrderRouting::Strategy::Legacy)
+```
+
+Then select it by class name string — set on `Spree::Store` (default) or `Spree::Channel` (override). Setting an unregistered class fails validation.
 
 Activate on the whole store:
 
@@ -242,7 +257,7 @@ store.channels.find_by(code: 'pos').update!(
 )
 ```
 
-Resolution order: `channel.preferred_order_routing_strategy` → `store.preferred_order_routing_strategy` → the default `Strategy::Rules`. Only a value that points to a real `Strategy::Base` subclass is used; anything unset or invalid is skipped, so a misconfigured strategy falls back to the default instead of breaking checkout.
+Resolution order: `channel.preferred_order_routing_strategy` → `store.preferred_order_routing_strategy` → the default `Strategy::Rules`. Only a value pointing to a **registered** `Strategy::Base` subclass is used; anything unset, unregistered, or invalid is skipped, so a misconfiguration (or a strategy you've since unregistered) falls back to the default instead of breaking checkout.
 
 ### Step 3: Test the Strategy