@spree/docs 0.1.248 → 0.1.249

package/dist/developer/agentic/agent-skills.md

@@ -1,7 +1,7 @@
 ---
 title: "Agent Skills"
 sidebarTitle: Agent Skills
-description: "Teach your AI coding agent Spree's conventions — 25 installable skills, a Spree expert subagent, slash commands, and safety hooks."
+description: "Teach your AI coding agent Spree's conventions — 38 installable skills, a Spree expert subagent, slash commands, and safety hooks."
 ---
 
 [spree/agent-skills](https://github.com/spree/agent-skills) is a collection of agent skills for Spree Commerce. Skills are markdown instructions your coding agent loads on demand — they encode Spree's conventions, customization decision trees, API patterns, and upgrade flows, so the agent does things the Spree way instead of improvising from training data.
@@ -10,6 +10,9 @@ The skills work with Claude Code, Codex, Cursor, GitHub Copilot, Cline, Aider, Z
 
 ## Install
 
+> **NOTE:** The skills target Spree 6. For a Spree 5 project, use the [`v0.3.0` release](https://github.com/spree/agent-skills/tree/v0.3.0) of the skills.
+
+
 Run from your project directory:
 
 ```bash
@@ -30,7 +33,7 @@ npx skills update                                        # update installed skil
 
 | | |
 |---|---|
-| **25 skills** | Project conventions, the customization decision tree (subscriber vs decorator vs dependency injection vs generator), the v3 Store + Admin API, the `spree:model` / `spree:api_resource` generators, TypeScript SDKs, upgrades, and domain deep-dives: catalog, checkout, payments, promotions, pricing, shipping, i18n, testing, security, performance, deployment. |
+| **38 skills** | Project conventions, the customization decision tree (workflow hook vs event subscriber vs provider vs dependency swap vs decorator), workflows and hooks, the v3 Store, Admin and Seller APIs, the `spree:model` / `spree:api_resource` generators, TypeScript SDKs, staff permissions, the admin dashboard and plugins, upgrades (including 5.6 → 6.0), and domain deep-dives: catalog, pricing, inventory, checkout, order totals, taxes, payments, promotions, fulfillment, returns, marketplace, B2B, multi-tenant, reporting, i18n, testing, security, performance, deployment. |
 | **`spree-expert` subagent** | A Claude Code agent for multi-step investigations (upgrade audits, checkout-flow debugging, API surface planning). It researches in its own context window and returns a focused report, keeping your main session lean. |
 | **2 slash commands** | `/spree:doctor` diagnoses the local dev stack (containers, env, migrations, job queues) and prescribes fixes. `/spree:audit-upgrade [version]` runs a read-only upgrade-readiness audit against your codebase. |
 | **2 safety hooks** | Block destructive database commands (`db:drop`, `DROP TABLE spree_*`, mass deletes, force-pushes to main) and warn when an edit introduces a hardcoded secret (Stripe live keys, AWS keys, API tokens). Disable with `SPREE_HOOKS_DISABLE=1`. |

package/dist/developer/agentic/llm-docs.md

@@ -40,7 +40,8 @@ node_modules/@spree/docs/dist/
 │   ├── customization/       # decorators, dependencies, events, …
 │   ├── storefront/          # Next.js storefront guides
 │   ├── sdk/                 # TypeScript SDK docs
-│   ├── admin/               # admin customization, form builder, components
+│   ├── dashboard/           # React admin dashboard customization and plugins
+│   ├── providers/           # tax, delivery, payment, search and other providers
 │   └── how-to/              # focused guides
 └── api-reference/
     └── store.yaml           # the full Store API OpenAPI spec

package/dist/developer/cli/admin-api.md

@@ -52,7 +52,7 @@ For remote stores, create a secret key in the admin under **Settings → API Key
 
 ```bash
 spree auth login --profile prod --base-url https://store.example.com
-spree api get /orders --profile prod -q "status_eq=complete"
+spree api get /orders --profile prod -q "status_eq=placed"
 spree auth status
 spree auth logout --profile prod
 ```

package/dist/developer/cli/quickstart.md

@@ -11,7 +11,7 @@ The Spree CLI (`@spree/cli`) does two things from your terminal:
 
 ```bash
 spree dev                                                  # boot the project
-spree api get /orders -q status_eq=complete --limit 10     # query the Admin API
+spree api get /orders -q status_eq=placed --limit 10     # query the Admin API
 spree api post /products -d '{"name":"Classic Tee","prices":[{"currency":"USD","amount":"29.99"}]}'  # create a resource
 spree api endpoints --search refund                        # discover endpoints, offline
 ```
@@ -229,7 +229,7 @@ Run a generator inside the container. Bare generator names are auto-prefixed wit
 ```bash
 spree generate model Brand name:string slug:string:uniq          # runs spree:model
 spree generate api_resource Brand name:string slug:string:uniq   # runs spree:api_resource — model + v3 Store/Admin API
-spree generate subscriber OmsOrderSync order.completed           # runs spree:subscriber — event subscriber + registration
+spree generate subscriber OmsOrderSync order.placed              # runs spree:subscriber — event subscriber + registration
 spree generate migration AddPositionToSpreeBrands position:integer  # Rails built-in, forwarded as-is
 ```
 

package/dist/developer/contributing/creating-an-extension.md

@@ -1,265 +1,411 @@
 ---
 title: Creating a Spree extension
-description: Step-by-step guide to building a Spree extension gem — scaffolding, decorators, migrations, assets, and packaging for distribution on GitHub.
+description: Build a Spree extension gem — models, API endpoints, permissions, workflow hooks and event subscribers — and pair it with a dashboard plugin for the admin UI.
 ---
 
 ## Overview
 
-Spree Extensions are a way to add new functionality to your Spree store. They are a great way to extend the functionality of Spree and add new features. You can share them with Spree community on Github so anyone can use them, contribute back and share your improvements. For officially supported integrations, see the [Integrations directory](/integrations).
+A Spree extension is a Ruby gem containing a Rails engine. It adds features to any Spree application without forking Spree: new models, new API endpoints, new permissions, and custom logic that runs inside Spree's workflows. You can share an extension with the Spree community on GitHub so anyone can use it and contribute improvements. For officially supported integrations, see the [Integrations directory](/integrations).
 
-> **INFO:** This tutorial uses decorators for extending Spree models. For extensions that need to react to events (sync with external services, send notifications, etc.), consider using [Events subscribers](../core-concepts/events.md) instead - they're easier to test and maintain. See [Customization Quickstart](../customization/quickstart.md) for guidance on choosing the right approach.
+An extension is backend code only. Spree 6 has no Rails storefront or Rails admin to add views to:
 
-## Getting Started
+| Part of the feature | Where it lives |
+|---|---|
+| Models, migrations, business logic | The extension gem |
+| API endpoints (Store API and Admin API) | The extension gem |
+| Permissions for staff roles and API keys | The extension gem |
+| Admin screens | A [dashboard plugin](../dashboard/plugins/overview.md) — an npm package that talks to your Admin API endpoints |
+| Storefront pages | Your storefront application, through [`@spree/sdk`](../sdk/quickstart.md) |
 
-Let's build a simple extension. Suppose we want the ability to mark certain products as being on sale. We'd like to be able to set a sale price on a product and show products that are on sale on a separate products page. This is a great example of how an extension can be used to build on the solid Spree foundation.
+> **INFO:** Prefer Spree's extension points over [decorators](../customization/decorators.md): [workflow hooks](../customization/workflows.md) to change what happens inside a flow, [events](../core-concepts/events.md) to react after something happened, and `additional_permitted_attributes` to make your own columns writable. They keep working when Spree changes internally. See the [Customization Quickstart](../customization/quickstart.md) for guidance on choosing the right approach.
 
-Install the Spree Extension CLI by running:
+In this guide we build `spree_reviews`: customers read product reviews through the Store API, and staff manage them through the Admin API.
 
+## Generate the extension
+
+Install the Spree extension generator:
 
 ```bash
 gem install spree_extension
 ```
 
-Run the following command from a directory of your choice outside of our Spree application:
+Run the following command from a directory outside your Spree application:
 
 ```bash
-spree-extension simple_sales
+spree-extension create reviews
 ```
 
-This creates a `spree_simple_sales` directory with several additional files and directories. After generating the extension make sure you change to its directory:
+This creates a `spree_reviews` directory containing the engine, a gemspec, a test setup and continuous integration configuration. Change to its directory:
 
 ```bash
-cd spree_simple_sales
+cd spree_reviews
 ```
 
-## Adding a Sale Price to Variants
-
-The first thing we need to do is create a migration that adds a sale_price column to [variants](../core-concepts/products.md#variants).
-
-We can do this with the following command:
+> **WARNING:** The generated scaffold still declares a dependency on `spree_admin`, the Spree 5 Rails admin, which does not exist in Spree 6. Remove the `spree_admin` lines from both the `.gemspec` and the `Gemfile` before running `bundle install`. The JavaScript, importmap and asset setup in the scaffold is only used by the Spree 5 admin, so you can delete it too.
 
-```bash
-bin/rails g migration add_sale_price_to_spree_variants sale_price:decimal
-```
+## Add a model
 
-Because we are dealing with prices, we need to now edit the generated migration to ensure the correct precision and scale. Edit the file `db/migrate/XXXXXXXXXXX_add_sale_price_to_spree_variants.rb` so that it contains the following:
+Create the migration in `db/migrate/`:
 
-```ruby
-class AddSalePriceToSpreeVariants < ActiveRecord::Migration[7.1]
+```ruby db/migrate/20260901000000_create_spree_reviews.rb
+class CreateSpreeReviews < ActiveRecord::Migration[8.1]
   def change
-    add_column :spree_variants, :sale_price, :decimal, precision: 8, scale: 2
+    create_table :spree_reviews do |t|
+      t.references :store, null: false, index: true, foreign_key: false
+      t.references :product, null: false, index: true, foreign_key: false
+      t.integer :rating, null: false
+      t.text :body
+      t.boolean :approved, null: false, default: false
+
+      t.timestamps
+    end
   end
 end
 ```
 
-## Adding Our Extension to the Spree Application
+Then the model:
 
-Before we continue development of our extension, let's add it to the Spree application.
+```ruby app/models/spree/review.rb
+module Spree
+  class Review < Spree.base_class
+    include Spree::SingleStoreResource
 
-Within the `my_store` application directory, add the following line to the bottom of our `Gemfile`:
+    has_prefix_id :review
+    publishes_lifecycle_events
 
-```ruby
-gem 'spree_simple_sales', path: '../spree_simple_sales'
+    belongs_to :product, class_name: 'Spree::Product'
+
+    validates :rating, presence: true, inclusion: { in: 1..5 }
+
+    scope :approved, -> { where(approved: true) }
+
+    self.whitelisted_ransackable_attributes = %w[rating approved]
+  end
+end
 ```
 
-You may have to adjust the path somewhat depending on where you created the extension. You want this to be the path relative to the location of the `my_store` application.
+A few Spree conventions are at work here:
 
-Once you have added the gem, it's time to bundle:
+- **Reviews belong to a store.** `Spree::SingleStoreResource` fills in the store for new records, and the API only returns the current store's reviews. Commerce data is always per store.
+- **Prefixed IDs.** `has_prefix_id` gives every review an ID like `review_k5nR8xLq` in API responses. Integer database IDs are never exposed.
+- **No foreign key constraints** on business tables, and `class_name` on every association.
+- **Lifecycle events.** `publishes_lifecycle_events` makes the model emit `review.created`, `review.updated` and `review.deleted`, which subscribers and [webhooks](../core-concepts/webhooks.md) can react to.
 
-```bash
-bundle install
+## Expose it through the API
+
+Add serializers for both APIs. The Admin API serializer extends the Store API one with the fields only staff should see:
+
+```ruby app/serializers/spree/api/v3/review_serializer.rb
+module Spree
+  module Api
+    module V3
+      class ReviewSerializer < BaseSerializer
+        typelize rating: :number, body: [:string, nullable: true]
+
+        attributes :rating, :body
+      end
+    end
+  end
+end
 ```
 
-Finally, let's run the `spree_simple_sales` install generator to copy over the migration we just created. Answer **yes** if prompted to run migrations:
+```ruby app/serializers/spree/api/v3/admin/review_serializer.rb
+module Spree
+  module Api
+    module V3
+      module Admin
+        class ReviewSerializer < V3::ReviewSerializer
+          typelize approved: :boolean
+
+          attributes :approved, :created_at, :updated_at
+        end
+      end
+    end
+  end
+end
+```
 
-```bash
-# context: Your Spree store's app root (i.e. Rails.root); not the extension's root path.
-bin/rails g spree_simple_sales:install
+The Store API controller is read-only and returns approved reviews only:
+
+```ruby app/controllers/spree/api/v3/store/reviews_controller.rb
+module Spree
+  module Api
+    module V3
+      module Store
+        class ReviewsController < ResourceController
+          protected
+
+          def model_class
+            Spree::Review
+          end
+
+          def serializer_class
+            Spree::Api::V3::ReviewSerializer
+          end
+
+          def scope
+            super.approved
+          end
+        end
+      end
+    end
+  end
+end
 ```
 
-## Adding a Controller Action to HomeController
+The Admin API controller gives staff full create, read, update and delete access:
 
-Now we need to extend `Spree::HomeController` and add an action that selects "on sale" products.
+```ruby app/controllers/spree/api/v3/admin/reviews_controller.rb
+module Spree
+  module Api
+    module V3
+      module Admin
+        class ReviewsController < ResourceController
+          scoped_resource :reviews
 
- Note for the sake of this example that \`Spree::HomeController\` is only included in spree_storefront so you need to make it a dependency on your extensions \*.gemspec file.
+          protected
 
-Make sure you are in the `spree_simple_sales` root directory and run the following command to create the directory structure for our controller decorator:
+          def model_class
+            Spree::Review
+          end
 
-```bash
-mkdir -p app/controllers/spree_simple_sales
+          def serializer_class
+            Spree::Api::V3::Admin::ReviewSerializer
+          end
+
+          def resource_permitted_attributes
+            [:product_id, :rating, :body, :approved]
+          end
+        end
+      end
+    end
+  end
+end
 ```
 
-Next, create a new file in the directory we just created called `home_controller_decorator.rb` and add the following content to it:
+`scoped_resource :reviews` means only staff roles and secret API keys holding the `read_reviews` or `write_reviews` permission can call these endpoints. The next section registers that permission.
+
+Finally, add the routes. The scaffold's `config/routes.rb` already contains the route hook:
 
-```ruby
-module SpreeSimpleSales
-  module HomeControllerDecorator
-    def sale
-      @products = Spree::Product.joins(:variants_including_master).where.not(sale_price: nil).distinct
+```ruby config/routes.rb
+Spree::Core::Engine.add_routes do
+  namespace :api, defaults: { format: 'json' } do
+    namespace :v3 do
+      namespace :store do
+        resources :reviews, only: [:index, :show]
+      end
+
+      namespace :admin do
+        resources :reviews
+      end
     end
   end
 end
-
-Spree::HomeController.prepend SpreeSimpleSales::HomeControllerDecorator
 ```
 
-This will select just the products that have a variant with a `sale_price` set.
+Pagination, [Ransack](https://github.com/activerecord-hackery/ransack) filtering (`?q[rating_gteq]=4`), sorting and prefixed ID lookup all come from the base `ResourceController`. See [Customizing the API](../customization/api.md) for everything you can override.
 
-We also need to add a route to this action in our `config/routes.rb` file. Let's do this now. Update the routes file to contain the following:
+## Register permissions
 
-```ruby
-Spree::Core::Engine.routes.draw do
-  get "/sale" => "home#sale"
-end
+Register your model as a permission scope, so the `read_reviews` and `write_reviews` permissions appear in the staff role editor and can be granted to secret API keys:
+
+```ruby config/initializers/spree.rb
+Spree.permissions.register_scope(:reviews, group: :catalog, resources: -> {
+  [Spree::Review]
+})
+```
+
+Label the permission for the dashboard in your locale file:
+
+```yaml config/locales/en.yml
+en:
+  spree:
+    permissions_catalog:
+      resources:
+        reviews:
+          label: Reviews
+          description: Product reviews left by customers
 ```
 
-## Viewing On Sale Products
+See [Permissions](../customization/permissions.md) for audiences and read-only scopes.
 
-### Setting the Sale Price for a Variant
+## Extend core models and behavior
 
-Now that our variants have the attribute `sale_price` available to them, let's update the sample data so we have at least one product that is on sale in our application. We will need to do this in the rails console for the time being, as we have no admin interface to set sale prices for variants. So, in order to do this, first open up the rails console:
+Extensions often need to change Spree's own resources as well as add new ones. Reach for these options in order.
 
-```bash
-bin/rails c
+### Make a new column writable
+
+Suppose each product gets a `reviews_enabled` switch. Add the column with a migration, then let the existing product endpoints accept it — no controller changes needed:
+
+```ruby lib/spree_reviews/engine.rb
+config.to_prepare do
+  Spree::Product.additional_permitted_attributes += [:reviews_enabled]
+end
 ```
 
-Now, follow the steps I take in selecting a product and updating its master variant to have a sale price. Note, you may not be editing the exact same product as I am, but this is not important. We just need one "on sale" product to display on the sales page.
+Always append with `+=`, so you don't remove attributes that other extensions added.
+
+### Run code inside a Spree workflow
 
-```ruby
-> product = Spree::Product.first
-=> #<Spree::Product id: 107377505, name: "Spree Bag", description: "Lorem ipsum dolor sit amet, consectetuer adipiscing...", available_on: "2013-02-13 18:30:16", deleted_at: nil, permalink: "spree-bag", meta_description: nil, meta_keywords: nil, tax_category_id: 25484906, shipping_category_id: nil, count_on_hand: 10, created_at: "2013-02-13 18:30:16", updated_at: "2013-02-13 18:30:16", on_demand: false>
+[Workflow hooks](../customization/workflows.md) run your code at a named point inside a core flow — checkout completion, cancellations, refunds, product changes — and can stop the operation. For example, to require a description before a product with reviews enabled goes on sale:
 
-> variant = product.master
-=> #<Spree::Variant id: 833839126, sku: "SPR-00012", weight: nil, height: nil, width: nil, depth: nil, deleted_at: nil, is_master: true, product_id: 107377505, count_on_hand: 10, cost_price: #<BigDecimal:7f8dda5eebf0,'0.21E2',9(36)>, position: nil, lock_version: 0, on_demand: false, cost_currency: nil, sale_price: nil>
+```ruby config/initializers/spree.rb
+Spree.hooks.register('products.activate.validate', 'SpreeReviews::RequireDescription')
+```
 
-> variant.sale_price = 8.00
-=> 8.0
+```ruby app/services/spree_reviews/require_description.rb
+module SpreeReviews
+  class RequireDescription
+    def call(workflow)
+      product = workflow.product
+      return unless product.reviews_enabled
+      return if product.description.present?
 
-> variant.save
-=> true
+      workflow.reject!('Add a description before activating a product with reviews.')
+    end
+  end
+end
 ```
 
-## Decorating Variants
+Hook names are checked when the application boots, so a typo fails at startup rather than silently never running.
 
-Let's fix our extension so that it uses the `sale_price` when it is present.
+### React to events
 
-Next, create the file `app/models/spree_simple_sales/variant_decorator.rb` and add the following content to it:
+To do something *after* an event, without influencing it, write an [event subscriber](../core-concepts/events.md). For example, to ask customers for a review once their order arrives:
 
-```ruby
-module SpreeSimpleSales
-  module VariantDecorator
-    def price_in(currency)
-      return super unless sale_price.present?
-      Spree::Price.new(variant_id: self.id, amount: self.sale_price, currency: currency)
+```ruby app/subscribers/spree_reviews/review_request_subscriber.rb
+module SpreeReviews
+  class ReviewRequestSubscriber < Spree::Subscriber
+    subscribes_to 'order.delivered'
+
+    def handle(event)
+      order = Spree::Order.find_by_prefix_id(event.payload['id'])
+      return unless order
+
+      SpreeReviews::ReviewRequestMailer.request_review(order).deliver_later
     end
   end
 end
+```
+
+Subscribers are not discovered automatically. Register them from the engine:
 
-Spree::Variant.prepend SpreeSimpleSales::VariantDecorator
+```ruby lib/spree_reviews/engine.rb
+config.after_initialize do
+  Spree.subscribers << SpreeReviews::ReviewRequestSubscriber
+end
 ```
 
-If there is a `sale_price` present on the product's master variant, we return that price. Otherwise, we call the original implementation of `price_in` using `return super`.
+### Decorators, as a last resort
 
-## Testing Our Decorator
+When none of the above fits — adding an association to a core model, for example — use a [decorator](../customization/decorators.md):
 
-It's always a good idea to test your code. We should be extra careful to write tests for our Variant decorator since we are modifying core Spree functionality. Let's write a couple of simple unit tests for `variant_decorator.rb`
+```ruby app/models/spree_reviews/product_decorator.rb
+module SpreeReviews
+  module ProductDecorator
+    def self.prepended(base)
+      base.has_many :reviews, class_name: 'Spree::Review', dependent: :destroy
+    end
+  end
+end
 
-### Generating the Test App
+Spree::Product.prepend SpreeReviews::ProductDecorator
+```
 
-An extension is not a full Rails application, so we need something to test our extension against. By running the Spree `test_app` rake task, we can generate a barebones Spree application within our `spec` directory to run our tests against.
+Decorators are not loaded automatically. Load them from your engine:
 
-We can do this with the following command from the root directory of our extension:
+```ruby lib/spree_reviews/engine.rb
+config.to_prepare do
+  Dir.glob(root.join('app/**/*_decorator*.rb')) do |decorator|
+    Rails.configuration.cache_classes ? require(decorator) : load(decorator)
+  end
+end
+```
+
+## Add admin screens
+
+Admin screens are built as a [dashboard plugin](../dashboard/plugins/overview.md): a React package that registers navigation entries, pages and product page widgets, and reads and writes data through your Admin API endpoints. Scaffold one with the Spree CLI:
 
 ```bash
-bundle exec rake test_app
+npx @spree/cli plugin new reviews
 ```
 
-After this command completes, you should be able to run `rspec` and see the following output:
+See [Scaffolding](../dashboard/plugins/scaffolding.md) and [Backend integration](../dashboard/customization/backend.md) to connect it to the endpoints above, and [Distributing](../dashboard/plugins/distributing.md) to ship the gem and the npm package together.
 
-```bash
-No examples found.
+## Add the extension to your application
+
+From your Spree application's backend directory, add the gem to the `Gemfile`. Adjust the path to point at your extension:
 
-Finished in 0.00005 seconds
-0 examples, 0 failures
+```ruby Gemfile
+gem 'spree_reviews', path: '../spree_reviews'
 ```
 
-Great! We're ready to start adding some tests. Let's replicate the extension's directory structure in our spec directory by running the following command
+Install it, then copy the extension's migrations into the application and run them:
 
 ```bash
-mkdir -p spec/models/spree
+bundle install
+bin/rails g spree_reviews:install
 ```
 
-Now, let's create a new file in this directory called `variant_decorator_spec.rb` and add the following tests to it:
+The Store API now serves reviews at `/api/v3/store/reviews`, and the Admin API manages them at `/api/v3/admin/reviews`.
 
-```ruby
-require 'spec_helper'
-
-describe Spree::Variant do
-  describe "#price_in" do
-    it "returns the sale price if it is present" do
-      variant = create(:variant, sale_price: 8.00)
-      expected = Spree::Price.new(variant_id: variant.id, currency: "USD", amount: variant.sale_price)
+## Test the extension
 
-      result = variant.price_in("USD")
+An extension is not a full Rails application, so its tests run against a small generated Spree application. Create it from the extension's root directory:
 
-      expect(result.variant_id).to eq(expected.variant_id)
-      expect(result.amount.to_f).to eq(expected.amount.to_f)
-      expect(result.currency).to eq(expected.currency)
-    end
-
-    it "returns the normal price if it is not on sale" do
-      variant = create(:variant, price: 15.00)
-      expected = Spree::Price.new(variant_id: variant.id, currency: "USD", amount: variant.price)
+```bash
+bundle exec rake test_app
+```
 
-      result = variant.price_in("USD")
+Run this again whenever you add a migration. Tests use RSpec and Factory Bot, with Spree's factories and test helpers coming from [`spree_dev_tools`](https://github.com/spree/spree_dev_tools). Add a factory for your model:
 
-      expect(result.variant_id).to eq(expected.variant_id)
-      expect(result.amount.to_f).to eq(expected.amount.to_f)
-      expect(result.currency).to eq(expected.currency)
-    end
+```ruby lib/spree_reviews/factories.rb
+FactoryBot.define do
+  factory :review, class: Spree::Review do
+    product
+    rating { 5 }
+    approved { true }
   end
 end
 ```
 
-These specs test that the `price_in` method we overrode in our `VariantDecorator` returns the correct price both when the sale price is present and when it is not.
+Then test your endpoints:
 
-## Summary
-
-In this tutorial, you learned how to both install extensions and create your own. A lot of core Spree development concepts were covered and you gained exposure to some of the Spree internals.
+```ruby spec/controllers/spree/api/v3/admin/reviews_controller_spec.rb
+require 'spec_helper'
 
-## Alternative Approaches
+RSpec.describe Spree::Api::V3::Admin::ReviewsController, type: :controller do
+  render_views
+  routes { Spree::Core::Engine.routes }
 
-While this tutorial uses decorators to extend Spree's core behavior, modern Spree provides additional patterns that may be more appropriate depending on your use case:
+  include_context 'API v3 Admin authenticated'
 
-| Use Case | Recommended Approach |
-|----------|---------------------|
-| Structural changes (associations, validations) | Decorators (as shown in this tutorial) |
-| React to model changes | [Events subscribers](../core-concepts/events.md) |
-| External service integration | [Webhooks](../core-concepts/webhooks.md) |
-| Replace core services | [Dependencies injection](../customization/dependencies.md) |
-| Add admin UI elements | [Admin Partials](../dashboard/customization/quickstart.md) |
-| Add admin menu items | [Admin Navigation](../dashboard/customization/navigation.md) |
+  let!(:review) { create(:review, store: store) }
 
-For example, if your extension needs to sync data with an external service when products are updated, use an Events subscriber instead of a decorator callback:
+  before { request.headers.merge!(headers) }
 
-```ruby app/subscribers/my_extension/product_sync_subscriber.rb
-module MyExtension
-  class ProductSyncSubscriber < Spree::Subscriber
-    subscribes_to 'product.updated'
+  it 'lists reviews' do
+    get :index, as: :json
 
-    def handle(event)
-      product = Spree::Product.find_by_prefix_id(event.payload['id'])
-      return unless product
-
-      ExternalService.sync(product)
-    end
+    expect(response).to have_http_status(:ok)
+    expect(json_response['data'].map { |r| r['id'] }).to include(review.prefixed_id)
   end
 end
 ```
 
-## Related Documentation
+Run the suite:
+
+```bash
+bundle exec rspec
+```
+
+Test the logic you wrote — the approved-only scope, your hook handler, your subscriber — rather than behavior that Rails and Spree already guarantee.
+
+## Related documentation
 
+- [Customization Quickstart](../customization/quickstart.md) - Choose the right extension point
+- [Customizing the API](../customization/api.md) - Controllers, serializers and permitted attributes
+- [Services & Workflows](../customization/workflows.md) - The full list of workflow hooks
 - [Events](../core-concepts/events.md) - Subscribe to Spree events
-- [Webhooks](../core-concepts/webhooks.md) - HTTP callbacks for external integrations
-- [Dependencies](../customization/dependencies.md) - Replace core services
-- [Customization Quickstart](../customization/quickstart.md) - Choose the right approach
+- [Permissions](../customization/permissions.md) - Register permission scopes
+- [Dashboard plugins](../dashboard/plugins/overview.md) - Admin UI for your extension