@spree/docs 0.1.240 → 0.1.241

package/dist/developer/customization/decorators.md

@@ -8,10 +8,9 @@ description: Use Spree decorators to add or modify behavior on core models, cont
 >   - **[Events & Subscribers](../core-concepts/events.md)** - For reacting to model changes (after save, create, update, delete)
 >   - **[Webhooks](../core-concepts/webhooks.md)** - For notifying external services when events occur
 >   - **[Dependencies](dependencies.md)** - For swapping out services, serializers, and abilities
->   - **[Admin Navigation](../dashboard/customization/navigation.md)** - For adding menu items without controller decorators
->   - **[Admin Partials](../dashboard/customization/quickstart.md)** - For extending admin UI without view decorators
->   - **[Admin Tables](../dashboard/customization/tables.md)** - For customizing admin list views
->   - **[Ransack Configuration](../core-concepts/search-filtering.md#extending-ransackable-configuration)** - For adding searchable/sortable fields without model decorators
+>   - **[Dashboard Navigation](../dashboard/customization/navigation.md)** - For adding menu items
+>   - **[Dashboard Slots](../dashboard/customization/slots.md)** - For adding your own UI to an existing dashboard screen
+>   - **[Dashboard Tables](../dashboard/customization/tables.md)** - For customizing list views
 
 ## When to Use Decorators vs Modern Alternatives
 
@@ -23,20 +22,28 @@ Before reaching for a decorator, check if your use case is better served by a mo
 | Notify external service on changes | Model decorator with callbacks | [Webhooks](../core-concepts/webhooks.md) |
 | Custom add-to-cart logic | Service decorator | [Dependencies injection](dependencies.md) |
 | Custom API responses | Serializer decorator | [Dependencies injection](dependencies.md) |
-| Add admin menu item | Controller decorator | [Admin Navigation API](../dashboard/customization/navigation.md) |
-| Add section to admin form | View decorator/override | [Admin Partials injection](../dashboard/customization/quickstart.md) |
-| Add searchable/filterable field | Model decorator with `ransackable_attributes` | [Ransack configuration](../core-concepts/search-filtering.md#extending-ransackable-configuration) |
+| Add a dashboard menu item | Controller decorator | [Navigation registry](../dashboard/customization/navigation.md) |
+| Add a section to a dashboard form | View decorator/override | [Slots](../dashboard/customization/slots.md) |
+| Narrow what an endpoint returns | Overriding an action | Controller decorator overriding `scope` |
+| Accept a new attribute on write | Controller decorator | `Model.additional_permitted_attributes +=` |
 | Add association to core model | - | Decorator (still appropriate) |
 | Add validation to core model | - | Decorator (still appropriate) |
 | Add new method to core model | - | Decorator (still appropriate) |
+| Make a new column [filterable](../core-concepts/search-filtering.md) | - | Decorator (still appropriate) |
 
 > **INFO:** Decorators are still appropriate for **structural changes** like adding associations, validations, scopes, and new methods to models. Use modern alternatives for **behavioral changes** like callbacks, hooks, and side effects.
 
 ## Overview
 
-All of Spree's models, controllers, helpers, etc can easily be extended or overridden to meet your exact requirements using standard Ruby idioms.
+Spree's models, API controllers and helpers can be extended or overridden to meet your requirements using standard Ruby idioms.
 
-Standard practice for including such changes in your application or extension is to create a file within the relevant **app/models/spree** or **app/controllers/spree** directory with the original class name with **_decorator** appended.
+The convention is a file under `server/app/models/spree` or `server/app/controllers/spree`, named after the original class with `_decorator` appended. The generators below place it for you.
+
+> **NOTE:** There is nothing else to decorate. The dashboard is a React application that
+>   talks to the Admin API, and the storefront is your own — so the only
+>   controllers Spree ships are the API ones, and the only views are the emails.
+>   Customize the dashboard through
+>   [its own extension points](../dashboard/customization/quickstart.md).
 
 ## Why Use Decorators?
 
@@ -88,7 +95,7 @@ Spree provides generators to create decorator files with the correct structure:
 
 
 ```bash Spree CLI (Docker)
-spree generate spree:model_decorator Spree::Product
+spree generate model_decorator Spree::Product
 ```
 
 ```bash Without Spree CLI
@@ -96,7 +103,7 @@ bin/rails g spree:model_decorator Spree::Product
 ```
 
 
-This creates `app/models/spree/product_decorator.rb`:
+This creates `server/app/models/spree/product_decorator.rb`:
 
 ```ruby
 module Spree
@@ -114,18 +121,18 @@ end
 
 
 ```bash Spree CLI (Docker)
-spree generate spree:controller_decorator Spree::Admin::ProductsController
+spree generate controller_decorator Spree::Api::V3::Admin::ProductsController
 ```
 
 ```bash Without Spree CLI
-bin/rails g spree:controller_decorator Spree::Admin::ProductsController
+bin/rails g spree:controller_decorator Spree::Api::V3::Admin::ProductsController
 ```
 
 
-This creates `app/controllers/spree/admin/products_controller_decorator.rb`:
+This creates `server/app/controllers/spree/api/v3/admin/products_controller_decorator.rb`:
 
 ```ruby
-module Spree::Admin
+module Spree::Api::V3::Admin
   module ProductsControllerDecorator
     def self.prepended(base)
       # base.before_action :my_filter
@@ -135,7 +142,7 @@ module Spree::Admin
   end
 end
 
-Spree::Admin::ProductsController.prepend Spree::Admin::ProductsControllerDecorator
+Spree::Api::V3::Admin::ProductsController.prepend Spree::Api::V3::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.
@@ -146,7 +153,7 @@ The generator accepts any namespace depth. `Spree::ProductsController` produces
 
 The most common use case is changing the behavior of existing methods. When overriding a method, you can call `super` to invoke the original implementation:
 
-```ruby app/models/spree/product_decorator.rb
+```ruby server/app/models/spree/product_decorator.rb
 module Spree
   module ProductDecorator
     def available?
@@ -168,7 +175,7 @@ end
 
 Add new instance methods directly in the decorator module:
 
-```ruby app/models/spree/product_decorator.rb
+```ruby server/app/models/spree/product_decorator.rb
 module Spree
   module ProductDecorator
     def featured?
@@ -189,7 +196,7 @@ end
 
 Use the `self.prepended(base)` callback to add associations:
 
-```ruby app/models/spree/product_decorator.rb
+```ruby server/app/models/spree/product_decorator.rb
 module Spree
   module ProductDecorator
     def self.prepended(base)
@@ -204,7 +211,7 @@ end
 
 ### Adding Validations
 
-```ruby app/models/spree/product_decorator.rb
+```ruby server/app/models/spree/product_decorator.rb
 module Spree
   module ProductDecorator
     def self.prepended(base)
@@ -219,7 +226,7 @@ end
 
 ### Adding Scopes
 
-```ruby app/models/spree/product_decorator.rb
+```ruby server/app/models/spree/product_decorator.rb
 module Spree
   module ProductDecorator
     def self.prepended(base)
@@ -237,7 +244,7 @@ end
 
 Use `extend` within the `prepended` callback to add class methods:
 
-```ruby app/models/spree/product_decorator.rb
+```ruby server/app/models/spree/product_decorator.rb
 module Spree
   module ProductDecorator
     def self.prepended(base)
@@ -263,131 +270,103 @@ Spree::Product.search_by_name('shirt')
 
 ## Decorating Controllers
 
-> **WARNING:** **Consider creating a new controller instead of decorating.** Creating your own controller that inherits from Spree's base controllers is more maintainable and less likely to break during upgrades. Use controller decorators only when you must modify existing Spree actions.
+The only controllers Spree ships are the API ones, under
+`Spree::Api::V3::Store` and `Spree::Api::V3::Admin`. There is no server-rendered
+storefront or admin to decorate — the dashboard is a React app that talks to the
+Admin API, and the storefront is yours.
 
-### Recommended: Create a New Controller
+> **WARNING:** **Reach for a decorator last.** A `ResourceController` subclass exposes named
+>   hooks — `scope`, `permitted_params`, `serializer_class`, `collection_includes`
+>   — and overriding one of those in a decorator is safe. Overriding an *action*
+>   couples your code to Spree's internals and is what breaks on upgrade.
 
-Instead of decorating `Spree::ProductsController` to add a new action, create your own controller:
+### Narrowing what an endpoint returns
 
-```ruby app/controllers/spree/product_quick_views_controller.rb
-module Spree
-  class ProductQuickViewsController < StoreController
-    def show
-      @product = current_store.products.friendly.find(params[:product_id])
-      render partial: 'spree/products/quick_view', locals: { product: @product }
-    end
-  end
-end
-```
+The most common reason to decorate: restrict a listing beyond what the store
+scope already does.
 
-```ruby config/routes.rb
-Spree::Core::Engine.add_routes do
-  get 'products/:product_id/quick_view', to: 'product_quick_views#show', as: :product_quick_view
-end
+```bash
+spree generate controller_decorator Spree::Api::V3::Admin::ProductsController
 ```
 
-This approach:
-- Won't break when Spree updates `ProductsController`
-- Is easier to test in isolation
-- Makes your customizations clearly visible in your codebase
-
-### Adding a New Action via Decorator
-
-If you must add an action to an existing controller:
-
-```ruby app/controllers/spree/products_controller_decorator.rb
-module Spree
+```ruby server/app/controllers/spree/api/v3/admin/products_controller_decorator.rb
+module Spree::Api::V3::Admin
   module ProductsControllerDecorator
-    def self.prepended(base)
-      base.before_action :load_product, only: [:quick_view]
-    end
-
-    def quick_view
-      respond_to do |format|
-        format.html { render partial: 'quick_view', locals: { product: @product } }
-        format.json { render json: @product }
-      end
-    end
+    protected
 
-    private
+    # `super` is already scoped to the current store. Chain onto it — never
+    # replace it, or the endpoint stops being scoped and starts returning
+    # another store's records. `current_user` is nil for a secret-key
+    # request, hence `&.` — a caller that is not a staff member gets the
+    # narrowed scope.
+    def scope
+      return super if current_user&.spree_admin?
 
-    def load_product
-      @product = current_store.products.friendly.find(params[:id])
+      super.where(discontinue_on: nil)
     end
   end
-
-  ProductsController.prepend(ProductsControllerDecorator)
 end
-```
-
-Don't forget to add the route:
 
-```ruby config/routes.rb
-Spree::Core::Engine.add_routes do
-  get 'products/:id/quick_view', to: 'products#quick_view', as: :product_quick_view
-end
+Spree::Api::V3::Admin::ProductsController.prepend(
+  Spree::Api::V3::Admin::ProductsControllerDecorator
+)
 ```
 
-### Modifying Existing Actions
+`current_user` is the signed-in staff member, and `spree_admin?` asks whether
+they hold the admin role for the current store.
 
-> **WARNING:** **High risk of breaking during upgrades.** When you override an existing Spree action, your code depends on Spree's internal implementation details. If Spree changes the action's behavior, instance variables, or method signatures in a future version, your decorator may silently break or cause unexpected bugs. Use [Events](../core-concepts/events.md) for post-action side effects instead.
+> **WARNING:** `current_user` is only set when the request carries a staff token. A request
+>   authenticated with a [secret API key](../../api-reference/admin-api/authentication.md)
+>   has no user, so `current_user` is `nil` — guard for it, or a server-to-server
+>   integration hits `NoMethodError` on every call.
 
-```ruby app/controllers/spree/admin/products_controller_decorator.rb
-module Spree
-  module Admin
-    module ProductsControllerDecorator
-      def create
-        # Add custom logic before
-        log_product_creation_attempt
-
-        # Call original method
-        super
+### Accepting an extra attribute
 
-        # Add custom logic after
-        notify_team_of_new_product if @product.persisted?
-      end
+If your decorator added a column to a core model, the controller has to permit
+it — but you rarely need a decorator for that. Extensions append to the model's
+own list from an initializer:
 
-      private
+```ruby server/config/initializers/spree.rb
+Spree::Product.additional_permitted_attributes += [:brand_id]
+```
 
-      def log_product_creation_attempt
-        Rails.logger.info "Product creation attempted by #{current_spree_user.email}"
-      end
+Always `+=`, never `=`, or you drop what another extension added.
 
-      def notify_team_of_new_product
-        ProductNotificationJob.perform_later(@product)
-      end
-    end
+### A new endpoint is a new controller
 
-    ProductsController.prepend(ProductsControllerDecorator)
-  end
-end
-```
+To add an action, write your own controller rather than decorating one of
+Spree's. It inherits the same pagination, filtering and authorization:
 
-> **INFO:** **Better alternative:** For post-action side effects like notifications, use [Events subscribers](../core-concepts/events.md) instead. Subscribe to `product.created` to be notified when products are created, without coupling to controller internals.
+```ruby server/app/controllers/spree/api/v3/admin/product_audits_controller.rb
+module Spree::Api::V3::Admin
+  class ProductAuditsController < ResourceController
+    # Names the API-key scope this endpoint needs: `read_products` for
+    # index/show, `write_products` for everything else. Every Admin API
+    # controller must declare one.
+    scoped_resource :products
 
-### Adding Before Actions
+    protected
 
-```ruby app/controllers/spree/checkout_controller_decorator.rb
-module Spree
-  module CheckoutControllerDecorator
-    def self.prepended(base)
-      base.before_action :check_minimum_order, only: [:update]
+    def model_class
+      Spree::ProductAudit
     end
 
-    private
-
-    def check_minimum_order
-      if @order.total < 25.0 && params[:state] == 'payment'
-        flash[:error] = 'Minimum order amount is $25'
-        redirect_to checkout_state_path(@order.state)
-      end
+    def serializer_class
+      MyApp::ProductAuditSerializer
     end
   end
-
-  CheckoutController.prepend(CheckoutControllerDecorator)
 end
 ```
 
+Add the route to your application's `config/routes.rb`, inside the engine's
+route hook. See [extending the API](api.md).
+
+> **INFO:** **For side effects, use events rather than a decorator.** Subscribing to
+>   `product.created` runs your code for every caller — the dashboard, a secret
+>   API key, an import, the console. A controller override only fires for
+>   requests that happen to pass through that controller. See
+>   [Events](../core-concepts/events.md).
+
 ## Best Practices
 
 
@@ -405,7 +384,7 @@ end
 If you have many customizations for a single class, consider splitting them into focused decorators:
 
 ```
-app/models/spree/
+server/app/models/spree/
 ├── product_decorator.rb           # Main decorator (loads others)
 ├── product/
 │   ├── brand_decorator.rb         # Brand association
@@ -413,13 +392,22 @@ app/models/spree/
 │   └── seo_decorator.rb           # SEO-related methods
 ```
 
-```ruby app/models/spree/product_decorator.rb
-# Load focused decorators
-require_dependency 'spree/product/brand_decorator'
-require_dependency 'spree/product/inventory_decorator'
-require_dependency 'spree/product/seo_decorator'
+```ruby server/app/models/spree/product_decorator.rb
+module Spree
+  module ProductDecorator
+    include Product::BrandDecorator
+    include Product::InventoryDecorator
+    include Product::SeoDecorator
+  end
+
+  Product.prepend(ProductDecorator)
+end
 ```
 
+Each focused module is a plain module — only the top-level decorator calls
+`prepend`. Autoloading resolves them from their paths, so nothing needs
+requiring by hand.
+
 ## Common Pitfalls
 
 ### Forgetting to Call Super
@@ -475,7 +463,7 @@ If you have existing decorators that use callbacks for side effects, consider mi
 
 **Before (Decorator with callback):**
 
-```ruby app/models/spree/product_decorator.rb
+```ruby server/app/models/spree/product_decorator.rb
 module Spree
   module ProductDecorator
     def self.prepended(base)
@@ -495,7 +483,7 @@ end
 
 **After (Events subscriber):**
 
-```ruby app/subscribers/product_sync_subscriber.rb
+```ruby server/app/subscribers/product_sync_subscriber.rb
 class ProductSyncSubscriber < Spree::Subscriber
   subscribes_to 'product.updated'
 
@@ -503,14 +491,16 @@ class ProductSyncSubscriber < Spree::Subscriber
     product = Spree::Product.find_by_prefix_id(event.payload['id'])
     return unless product
 
-    # The payload includes changes, check if name changed
-    if event.payload['previous_changes']&.key?('name')
-      ExternalSyncJob.perform_later(product)
-    end
+    ExternalSyncJob.perform_later(product)
   end
 end
 ```
 
+The payload is the record as the API serializes it, so it carries the new
+values rather than a list of what changed. When a subscriber only cares about
+one attribute, compare against what you last synced rather than looking for a
+changeset in the event.
+
 ### Benefits of Migration
 
 
@@ -528,7 +518,7 @@ end
 - [Events](../core-concepts/events.md) - Learn about Spree's event system
 - [Webhooks](../core-concepts/webhooks.md) - HTTP callbacks for external integrations
 - [Dependencies](dependencies.md) - Swap core services with your own
-- [Admin Navigation](../dashboard/customization/navigation.md) - Extend admin menu without decorators
-- [Admin Partials](../dashboard/customization/quickstart.md) - Extend admin UI without view decorators
-- [Extending Core Models Tutorial](../tutorial/model.md) - Step-by-step guide to connecting custom models with Spree core
+- [Extending the API](api.md) - Add your own endpoints
+- [Dashboard customization](../dashboard/customization/quickstart.md) - Extend the dashboard from its own React app
+- [Extending Core Models Tutorial](../tutorial/model-and-api.md) - Step-by-step guide to connecting custom models with Spree core
 - [Customization Overview](quickstart.md) - General customization patterns

package/dist/developer/customization/metadata.md

@@ -6,11 +6,11 @@ title: Metadata
 
 Metadata provides simple, unstructured key-value storage on Spree resources — similar to [Stripe's metadata](https://docs.stripe.com/api/metadata). It's ideal for storing integration IDs, tracking data, or any arbitrary information that doesn't need validation or admin UI.
 
-Metadata is a **permanent, first-class system** in Spree. It is designed to coexist alongside [Metafields](../core-concepts/metafields.md) (structured, typed, admin-managed). The two systems serve different purposes and are not interchangeable — think of it as **metadata for machines, metafields for humans**.
+Metadata is a **permanent, first-class system** in Spree. It is designed to coexist alongside [Custom Fields](../core-concepts/metafields.md) (structured, typed, admin-managed). The two systems serve different purposes and are not interchangeable — think of it as **metadata for machines, custom fields for humans**.
 
 Metadata is **write-only** in the Store API — you can set it when creating or updating resources, but it is never returned in Store API responses. It is visible in Admin API responses for administrative use.
 
-> **INFO:** For structured, type-safe custom attributes with admin UI support, use [Metafields](../core-concepts/metafields.md) instead.
+> **INFO:** For structured, type-safe custom attributes with admin UI support, use [Custom Fields](../core-concepts/metafields.md) instead.
 
 ## Store API
 
@@ -186,14 +186,14 @@ Metadata updates use **merge semantics** — existing keys are preserved, new ke
 { "source": "mobile_app", "campaign": "winter", "new_key": "value" }
 ```
 
-## Metadata vs Metafields
+## Metadata vs Custom Fields
 
 Spree has two permanent, complementary systems for custom data. They are not interchangeable and neither is going away.
 
-| | Metadata | [Metafields](../core-concepts/metafields.md) |
+| | Metadata | [Custom Fields](../core-concepts/metafields.md) |
 |---|---|---|
 | **Purpose** | Developer escape hatch — integration data, sync state, ad-hoc flags | Merchant-defined structured attributes with admin UI |
-| **Schema** | Schemaless JSON — no definition required | Defined via MetafieldDefinitions (typed, validated) |
+| **Schema** | Schemaless JSON — no definition required | Defined via CustomFieldDefinitions (typed, validated) |
 | **Validation** | None — accepts any JSON-serializable data | Type-specific (text, number, boolean, rich text, JSON) |
 | **Visibility** | Write-only in Store API, readable in Admin API | Configurable (front-end, back-end, both) |
 | **Admin UI** | JSON preview only | Dedicated management forms |
@@ -208,7 +208,7 @@ Spree has two permanent, complementary systems for custom data. They are not int
 - Any write-and-forget data that only needs to be read by backend systems
 - Syncing state with external integrations (webhooks, ETL pipelines)
 
-### When to use metafields
+### When to use custom fields
 
 - Custom product specifications shown to customers (material, dimensions, certifications)
 - Admin-managed fields with validation and type safety
@@ -231,7 +231,7 @@ The Store API currently supports writing metadata on:
 
 The `public_metadata` column was never exposed in Store API responses and in practice served the same purpose as `private_metadata`. Calling `public_metadata=` emits a deprecation warning.
 
-Always use the single `metadata` accessor for all schemaless key-value storage. If you need data visible to customers on the storefront, use [Metafields](../core-concepts/metafields.md) instead.
+Always use the single `metadata` accessor for all schemaless key-value storage. If you need data visible to customers on the storefront, use [Custom Fields](../core-concepts/metafields.md) instead.
 
 ```ruby
 # Deprecated — use `metadata` instead
@@ -240,6 +240,6 @@ order.public_metadata = { 'gift_message' => 'Happy Birthday!' }
 # Use metadata for internal storage
 order.metadata = { 'gift_message' => 'Happy Birthday!' }
 
-# Use metafields for customer-visible structured data
-order.set_metafield('custom.gift_message', 'Happy Birthday!')
+# Use custom fields for customer-visible structured data
+order.set_custom_field('custom.gift_message', 'Happy Birthday!')
 ```

package/dist/developer/customization/model-preferences.md

@@ -6,8 +6,8 @@ description: Add typed configuration options to Spree models using model prefere
 Model preferences allow you to easily extend Spree models with configuration options. Thanks to this you can store useful information on Spree models, eg.
 
 ```ruby
-user.preferred_language = "English"
-user.save
+store.preferred_timezone = 'Europe/Warsaw'
+store.save
 ```
 
 ## Defining Model Preferences
@@ -16,41 +16,26 @@ To define a model preference, you need to add them to your model class.
 
 Make sure to generate a migration to add the `preferences` column to the table. This column will store the preferences in a serialized format.
 
-
-```bash Spree CLI (Docker)
-spree generate migration AddPreferencesToSpreeUsers preferences:text
-```
-
-```bash Without Spree CLI
-bin/rails g migration AddPreferencesToSpreeUsers preferences:text
+```bash
+spree generate migration AddPreferencesToSpreeBrands preferences:text
 ```
 
-
 Run the migration.
 
-
-```bash Spree CLI (Docker)
+```bash
 spree migrate
 ```
 
-```bash Without Spree CLI
-bin/rails db:migrate
-```
-
-
-```ruby
-class Spree::User < ApplicationRecord
-  # ... you existing code ...
-
-  # include the preferable module
-  include Spree::Preferences::Preferable
-  # define the preferences
-  preference :language, :string, default: "English"
-  preference :sms_marketing, :boolean, default: false
+```ruby server/app/models/spree/brand.rb
+module Spree
+  class Brand < Spree.base_class
+    preference :featured, :boolean, default: false
+    preference :display_name, :string
+  end
 end
 ```
 
-This will add a `language` preference to the `User` model. The preference will be stored in the newly created `preferences` column of the `spree_users` table. You can add more preferences to the model in the same way.
+Any model inheriting from `Spree.base_class` can declare preferences — the reader and writer methods come with it, so there is nothing to include. The values live in that model's `preferences` column.
 
 ## Accessing Model Preferences
 
@@ -63,59 +48,38 @@ There are several shortcut methods that are generated. They are shown below.
 Query methods:
 
 ```ruby
-user.prefers_sms_marketing? # => false
+brand.prefers_featured? # => false
 ```
 
 Reader methods:
 
 ```ruby
-user.preferred_sms_marketing      # => false
-user.preferred_language   # => "English"
+brand.preferred_featured      # => false
+brand.preferred_display_name   # => "English"
 ```
 
 Writer methods:
 
 ```ruby
-user.prefers_sms_marketing = false         # => false
-user.preferred_language = "English"    # => "English"
+brand.prefers_featured = false         # => false
+brand.preferred_display_name = "English"    # => "English"
 ```
 
-> **NOTE:** Remember to run `user.save` after setting the preference value to save the changes to the database.
+> **NOTE:** Remember to run `brand.save` after setting the preference value to save the changes to the database.
 
 Check if a preference is available:
 
 ```ruby
-user.has_preference? :sms_marketing
+brand.has_preference? :featured
 ```
 
 ### Generic Methods
 
-Each shortcut method is essentially a wrapper for the various generic methods shown below:
-
-Query method:
+When the preference name is only known at runtime, read and write it generically:
 
 ```ruby
-user.prefers?(:sms_marketing)       # => false
-user.prefers?(:language)  # => false
-```
-
-Reader methods:
-
-```ruby
-user.preferred(:sms_marketing)      # => false
-user.preferred(:language)   # => "English"
-```
-
-```ruby
-user.get_preference :sms_marketing
-user.get_preference :language
-```
-
-Writer method:
-
-```ruby
-user.set_preference(:sms_marketing, false)     # => false
-user.set_preference(:language, "English")  # => "English"
+brand.get_preference(:featured)             # => false
+brand.set_preference(:display_name, 'Wilson')
 ```
 
 ### Accessing All Preferences
@@ -123,21 +87,23 @@ user.set_preference(:language, "English")  # => "English"
 You can get a hash of all stored preferences by accessing the `preferences` helper:
 
 ```ruby
-user.preferences # => {"language"=>"English", "sms_marketing"=>false}
+brand.preferences # => { 'featured' => false, 'display_name' => 'Wilson' }
 ```
 
 This hash will contain the value for every preference that has been defined for the model instance, whether the value is the default or one that has been previously stored.
 
 ## Models with preferences
 
-The following Spree models already have preferences defined:
+Around fifty models use preferences, and the pattern is always the same: a family of subclasses that share a table but need different settings.
+
+| Family | What the preferences hold |
+|---|---|
+| `Spree::Calculator` | The numbers behind a delivery charge or a discount — flat rate, percentage, tiers |
+| `Spree::PaymentMethod` | Gateway credentials and per-provider options |
+| `Spree::Promotion::Rules` and `Spree::Promotion::Actions` | What a promotion matches on, and what it does |
+| `Spree::Integration` | Per-service configuration and API keys |
+| `Spree::PriceRules` and `Spree::DeliveryMethodRules` | When a price list or a delivery method applies |
+| `Spree::Store`, `Spree::Channel` and `Spree::Market` | Merchant settings — timezone, units, currency behaviour |
 
-* `Spree::Calculator`
-* `Spree::Gateway`
-* `Spree::PageBlock`
-* `Spree::PageSection`
-* `Spree::Page`
-* `Spree::PaymentMethod`
-* `Spree::PromotionRule`
-* `Spree::Store`
+This is why preferences exist rather than columns: `Spree::Calculator::FlatRate` and `Spree::Calculator::TieredPercent` are rows in one table with entirely different settings, and neither wants a column the other leaves null.
 * `Spree::Theme`