@spree/docs 0.1.85 → 0.1.87

package/dist/developer/getting-started/quickstart.md

@@ -1,7 +1,7 @@
 ---
 title: "Installing Spree"
 sidebarTitle: Installation
-description: "Follow the instructions below to learn how to build and deploy your Spree application."
+description: "Install Spree Commerce locally with Docker or Ruby on Rails, run your first store, and deploy it to production with the official starter template."
 ---
 
 ## Installation options
@@ -73,6 +73,17 @@ Upon successful authentication, you should see the admin screen:
 
 <img src="/images/spree_admin_dashboard.png" />
 
+## Next Steps
+
+
+  - [Build with AI Agents](../agentic/overview.md) — Install the Spree agent skills and connect the docs MCP server — Claude Code, Cursor, Copilot, and 60+ other tools learn Spree's conventions and build features with you.
+  - [Customization Tutorial](../tutorial/introduction.md) — Build a complete custom feature — model, admin UI, API, and TypeScript SDK — step by step.
+  - [Core Concepts](../core-concepts/architecture.md) — Understand how Spree models commerce — stores, products, orders, payments.
+  - [Next.js Storefront](../storefront/nextjs/quickstart.md) — Customize and extend the headless storefront.
+
+
+> **TIP:** Using an AI coding agent? Run `npx skills add spree/agent-skills` in your new project — it teaches your agent the customization patterns before you write a line of code. See [Agentic Development](../agentic/overview.md).
+
 ---
 
 Congrats! You've set up your Spree Commerce and it's looking amazing!

package/dist/developer/sdk/extending.md

@@ -1,7 +1,7 @@
 ---
 title: Custom Endpoints
 sidebarTitle: Custom Endpoints
-description: Call custom Store API endpoints using the SDK's built-in request method
+description: Call your own custom Store API endpoints from the Spree TypeScript SDK using the built-in request method, with typed responses and shared auth handling.
 ---
 
 The client exposes a `request` method — the same function that powers all built-in resources. Use it to call any Store API endpoint, including ones you've added yourself.
@@ -30,4 +30,4 @@ const nike = await client.request<Brand>('GET', '/brands/nike')
 
 `client.request` uses the same auth headers, retry logic, and locale/currency defaults as `client.products.list()` or any other built-in resource.
 
-For a complete walkthrough — creating the API endpoints on the backend, defining TypeScript types, filtering, and expanding associations — see the [Store API](../tutorial/store-api.md) and [SDK](../tutorial/sdk.md) tutorials.
+For a complete walkthrough — creating the API endpoints on the backend, defining TypeScript types, filtering, and expanding associations — see the [API](../tutorial/api.md) and [SDK](../tutorial/sdk.md) tutorials.

package/dist/developer/sdk/quickstart.md

@@ -1,6 +1,6 @@
 ---
 title: Quickstart
-description: Install and start using the Spree SDK in your project
+description: Install the Spree TypeScript SDK, configure your Store API client, and make your first calls to products, carts, checkout, and customer endpoints.
 ---
 
 ## Installation
@@ -82,3 +82,7 @@ await client.customer.addresses.list({}, options);
 await client.categories.products.list(categoryId, params, options);
 await client.wishlists.items.create(wishlistId, params, options);
 ```
+
+## Pair with AI agents
+
+Building your storefront with an AI coding agent? The [Spree agent skills](../agentic/agent-skills.md) include dedicated SDK and storefront skills (typed clients, Ransack filtering, error handling, custom endpoints), and the [docs MCP server](../agentic/mcp.md) gives your agent the full SDK reference on demand. See [Agentic Development](../agentic/overview.md).

package/dist/developer/tutorial/admin.md

@@ -1,26 +1,30 @@
 ---
 title: Admin Dashboard
-description: Learn how to create Admin Dashboard UI to manage Brands
+description: Scaffold the Spree admin UI for the Brands resource and add a rich text description editor, an Active Storage logo upload, and a custom table column.
 ---
 
-Now that we've created a complete "Brand" model, let's create an Admin Dashboard interface so our admins can manage the brands.
+Now that we've created the `Brand` model, let's create an Admin Dashboard interface so admins can manage brands — including editing the rich text description and uploading the logo.
 
-## Step 1: Create the boilerplate Admin Dashboard UI
+## Step 1: Scaffold the Admin UI
 
-Admin Scaffold generator is a tool that helps us create a complete Admin Dashboard UI for our new resource.
+The Admin Scaffold generator creates a complete admin section for a resource:
 
-Run the following command in our Spree application root directory:
 
-```bash
+```bash Spree CLI (Docker)
+spree generate spree:admin:scaffold Spree::Brand
+```
+
+```bash Without Spree CLI
 bin/rails g spree:admin:scaffold Spree::Brand
 ```
 
+
 This will create the following files:
 
 | File Type | Path | Description |
 |-----------|------|-------------|
 | Controller | `app/controllers/spree/admin/brands_controller.rb` | Handles the logic for the brands resource. |
-| View | `app/views/spree/admin/brands/index.html.erb` | Displays the list of brands using the new tables system. |
+| View | `app/views/spree/admin/brands/index.html.erb` | Displays the list of brands using the tables system. |
 | View | `app/views/spree/admin/brands/new.html.erb` | Displays the new brand form. |
 | View | `app/views/spree/admin/brands/edit.html.erb` | Displays the edit brand form. |
 | Partial | `app/views/spree/admin/brands/_form.html.erb` | The form partial used in new and edit views. |
@@ -37,7 +41,54 @@ end
 
 You will now be able to access the brands resource at `http://localhost:3000/admin/brands` in your browser. To reference this route in your code, you can use the `spree.admin_brands_path` helper.
 
-## Step 2: Customize the Table Columns
+## Step 2: Add the Description Editor and Logo Upload
+
+The generated form only knows about the `name` column. Let's add the rich text editor for `description` and the upload field for `logo` using Spree's [admin form builder](../admin/form-builder.md):
+
+```erb app/views/spree/admin/brands/_form.html.erb {4,9-16}
+<div class="card mb-6">
+  <div class="card-body">
+    <%= f.spree_text_field :name, required: true, autofocus: true %>
+    <%= f.spree_rich_text_area :description %>
+  </div>
+</div>
+
+<div class="card mb-6">
+  <div class="card-header">
+    <h5 class="card-title"><%= Spree.t(:logo) %></h5>
+  </div>
+  <div class="card-body">
+    <%= f.spree_file_field :logo, width: 300, height: 300 %>
+  </div>
+</div>
+```
+
+- **`spree_rich_text_area`** renders a WYSIWYG editor (Trix) for the Action Text description.
+- **`spree_file_field`** handles drag-and-drop upload, image preview, and direct upload to storage. Add `crop: true` to enable image cropping with a recommended-size indicator.
+
+Then permit the two new attributes in the controller:
+
+```ruby app/controllers/spree/admin/brands_controller.rb {7-11}
+module Spree
+  module Admin
+    class BrandsController < ResourceController
+      private
+
+      def permitted_resource_params
+        params.require(:brand).permit(
+          :name,
+          :description,
+          :logo
+        )
+      end
+    end
+  end
+end
+```
+
+Open `http://localhost:3000/admin/brands/new`, create a brand with a formatted description and a logo — everything saves through the standard form.
+
+## Step 3: Customize the Table Columns
 
 The scaffold generator creates a table initializer at `config/initializers/spree_admin_brands_table.rb` with default columns:
 
@@ -71,21 +122,36 @@ Rails.application.config.after_initialize do
 end
 ```
 
-You can customize this file to add more columns based on your model's attributes. For example, to add a description column:
+### Show the logo next to the name
 
-```ruby
-Spree.admin.tables.brands.add :description,
-  label: :description,
-  type: :string,
-  sortable: false,
+To render the logo thumbnail in the name column — the same pattern the Products table uses — switch the column to a custom partial:
+
+```ruby config/initializers/spree_admin_brands_table.rb
+Spree.admin.tables.brands.add :name,
+  label: :name,
+  type: :custom,
+  partial: 'spree/admin/tables/columns/brand_name',
+  sortable: true,
   filterable: true,
   default: true,
-  position: 15
+  position: 10
+```
+
+And create the partial:
+
+```erb app/views/spree/admin/tables/columns/_brand_name.html.erb
+<%# locals: (record:, column:, value:) %>
+<%= link_to spree.edit_admin_brand_path(record), class: 'flex items-center gap-3 no-underline', data: { turbo_frame: '_top' } do %>
+  <% if record.logo.attached? %>
+    <%= spree_image_tag record.logo, width: 48, height: 48, class: 'rounded' %>
+  <% end %>
+  <span class="text-gray-900 font-medium"><%= record.name %></span>
+<% end %>
 ```
 
 > **INFO:** For complete table customization options including column types, filtering, sorting, and bulk actions, see the [Admin Tables](../admin/tables.md) guide.
 
-## Step 3: Customize Navigation
+## Step 4: Customize Navigation
 
 The scaffold generator also creates a navigation initializer at `config/initializers/spree_admin_brands_navigation.rb`:
 
@@ -131,4 +197,8 @@ end
 
 After restarting your server, you'll see the new "Brands" navigation link in the admin sidebar!
 
-> **INFO:** For complete navigation API documentation including all available options, submenu creation, badges, and more, see the [Admin Navigation](../admin/navigation.md) guide.
+> **INFO:** For complete navigation API documentation including all available options, submenu creation, badges, and more, see the [Admin Navigation](../admin/navigation.md) guide. The form helpers used in Step 2 are documented in [Form Builder](../admin/form-builder.md) and [Components](../admin/components.md).
+
+## Next Step
+
+Brands are manageable in the admin. Now let's connect them to Products: [Extending Core Models](extending-models.md).

package/dist/developer/tutorial/{store-api.md → api.md}

@@ -1,9 +1,9 @@
 ---
-title: Store API
-description: Expose your Brand model through the Store API with serializers, controllers, and routes
+title: API
+description: Expose your custom Brand model through the Spree Store and Admin REST APIs with serializers, controllers, routes, and the spree:api_resource generator.
 ---
 
-In this tutorial, we'll create Store API endpoints for our Brand model so that storefronts can list and display brands. We'll also extend the existing Product serializer to include brand data.
+In this tutorial, we'll expose our Brand model through Spree's v3 API — the customer-facing **Store API** that storefronts read from, and the back-office **Admin API** with full CRUD for apps and integrations. We'll also extend the existing Product serializer to include brand data.
 
 > **INFO:** This guide assumes you've completed the [Model](model.md), [Admin](admin.md), and [Extending Core Models](extending-models.md) tutorials.
 
@@ -11,11 +11,43 @@ In this tutorial, we'll create Store API endpoints for our Brand model so that s
 
 By the end of this tutorial, you'll have:
 
-- `GET /api/v3/store/brands` — list all brands
-- `GET /api/v3/store/brands/:id` — get a single brand by prefixed ID or slug
+- `GET /api/v3/store/brands` and `GET /api/v3/store/brands/:id` — customer-facing, read-only, lookup by prefixed ID or slug
+- Full CRUD on `/api/v3/admin/brands` — for back-office apps and integrations
 - Brand data included in Product responses via `?expand=brand`
 - Understanding of how to add new API endpoints and extend existing serializers
 
+## The Fast Path: One Generator Command
+
+Everything this page builds by hand can be generated in one command with `spree:api_resource`:
+
+
+```bash Spree CLI (Docker)
+spree generate api_resource Brand
+```
+
+```bash Without Spree CLI
+bin/rails g spree:api_resource Brand
+```
+
+
+Because the Brand model already exists, the generator leaves it (and its migration) untouched and produces only the API surface — no conflict prompts, no overwrites. Your model is "owned once": after creation, domain code belongs to you, and the generator only ever adds API files around it. You'll see this in the output:
+
+```text
+      skip  model app/models/spree/brand.rb (owned-once; already exists)
+      skip  migration (model already exists; add a new migration for schema changes)
+    create  app/controllers/spree/api/v3/store/brands_controller.rb
+    create  app/controllers/spree/api/v3/admin/brands_controller.rb
+    create  app/serializers/spree/api/v3/brand_serializer.rb
+    create  app/serializers/spree/api/v3/admin/brand_serializer.rb
+    create  spec/factories/spree/brand_factory.rb
+```
+
+For a brand-new resource you'd pass the attributes too (`spree generate api_resource Brand name:string:uniq`) and get the model and migration in the same run.
+
+If you just want a working API, run the generator and skip ahead to [Step 5: Test the Endpoints](#step-5-test-the-endpoints). The rest of this page builds the Store side by hand so you understand what the generator produces and how to customize it — the [Admin API section](#the-admin-api) then shows how little the back-office surface adds on top.
+
+> **TIP:** Using an AI agent? The [Spree agent skills](../agentic/agent-skills.md) include a dedicated resource-generator skill — your agent knows the field syntax, the flags, and the generated-file contract.
+
 ## How the Store API Works
 
 Every Store API endpoint follows the same pattern:
@@ -29,22 +61,28 @@ Every Store API endpoint follows the same pattern:
 
 Store API requires two things from models:
 
-1. **Prefixed IDs** — Stripe-style IDs like `brand_k5nR8xLq` instead of raw database IDs
+1. **Prefixed IDs** — Stripe-style IDs like `brand_k5nR8xLq` instead of raw database IDs. The `spree:model` generator already added `has_prefix_id :brand` in the [Model step](model.md), so this is done.
 2. **Slugs** — human-readable URL identifiers like `nike` for `GET /brands/nike`
 
-First, add a `slug` column if you haven't already:
+Add a `slug` column:
 
-```bash
+
+```bash Spree CLI (Docker)
+spree generate migration AddSlugToSpreeBrands slug:string:uniq
+spree migrate
+```
+
+```bash Without Spree CLI
 bin/rails g migration AddSlugToSpreeBrands slug:string:uniq
 bin/rails db:migrate
 ```
 
-Then update the Brand model with `PrefixedId` and `FriendlyId`:
 
-```ruby app/models/spree/brand.rb {3-7}
+Then add `FriendlyId` to the Brand model:
+
+```ruby app/models/spree/brand.rb {3,6}
 module Spree
-  class Brand < Spree::Base
-    include Spree::PrefixedId
+  class Brand < Spree.base_class
     extend FriendlyId
 
     has_prefix_id :brand
@@ -52,10 +90,14 @@ module Spree
 
     has_many :products, class_name: 'Spree::Product', dependent: :nullify
 
-    has_one_attached :logo
     has_rich_text :description
+    has_one_attached :logo
 
     validates :name, presence: true
+
+    self.whitelisted_ransackable_attributes = %w[name]
+    self.whitelisted_ransackable_associations = %w[]
+    self.whitelisted_ransackable_scopes = %w[]
   end
 end
 ```
@@ -64,7 +106,7 @@ Now:
 - `Spree::Brand.first.prefixed_id` returns `brand_k5nR8xLq`
 - `Spree::Brand.find_by_prefix_id!('brand_k5nR8xLq')` finds by prefixed ID
 - `Spree::Brand.friendly.find('nike')` finds by slug
-- Slugs are auto-generated from the `name` via `slug_candidates` (inherited from `Spree::Base`)
+- Slugs are auto-generated from the `name` via `slug_candidates` (inherited from the Spree base class)
 
 ## Step 2: Create the Serializer
 
@@ -261,6 +303,67 @@ List response:
 }
 ```
 
+## The Admin API
+
+The Admin API is the other half of v3 — same protocol, same serializer/controller patterns, but authenticated with secret keys (`sk_*`) or admin JWTs, and **full CRUD by default**. The `spree:api_resource` generator produces both pieces; here's what they look like:
+
+```ruby app/serializers/spree/api/v3/admin/brand_serializer.rb
+module Spree
+  module Api
+    module V3
+      module Admin
+        class BrandSerializer < V3::BrandSerializer
+          attributes :created_at, :updated_at
+        end
+      end
+    end
+  end
+end
+```
+
+```ruby app/controllers/spree/api/v3/admin/brands_controller.rb
+module Spree
+  module Api
+    module V3
+      module Admin
+        class BrandsController < ResourceController
+          protected
+
+          def model_class
+            Spree::Brand
+          end
+
+          def serializer_class
+            Spree::Api::V3::Admin::BrandSerializer
+          end
+
+          def permitted_params
+            params.permit(:name)
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+Two conventions to notice:
+
+- **The Admin serializer extends the Store serializer** — public fields stay in sync automatically, and the Admin side adds back-office data (timestamps here; cost prices, internal notes, and audit fields on richer resources). Customers never see those fields because storefronts use the Store serializer.
+- **`Admin::ResourceController` ships full CRUD** — `index`, `show`, `create`, `update`, and `destroy` are inherited; `permitted_params` lists the writable attributes with flat params (no nested `brand: {...}` wrapping).
+
+With the routes registered (`resources :brands` under the `admin` namespace — the generator injects this), back-office clients get:
+
+```bash
+# Create a brand with a secret API key
+curl -X POST -H "X-Spree-API-Key: sk_YOUR_KEY" \
+     -H "Content-Type: application/json" \
+     -d '{"name": "Adidas"}' \
+     http://localhost:3000/api/v3/admin/brands
+```
+
+> **INFO:** Secret keys carry scopes (`read_brands`, `write_brands` style) and JWT admin users go through CanCanCan abilities — see [API authentication](../customization/api.md) for the full model.
+
 ## Step 6: Add Brand to Product Responses
 
 Now let's extend the Product serializer so that brand data is included when a storefront requests `?expand=brand`.
@@ -494,6 +597,7 @@ Spree.ransack.add_association(Spree::Product, :brand)
 ## Related Documentation
 
 - [Extending Core Models](extending-models.md) - Adding the Brand association to Product
+- [Events & Webhooks](events.md) - Lifecycle events for Brand and external-system integration (next step)
 - [Using Brands with the SDK](sdk.md) - Consuming brand endpoints from TypeScript
 - [Decorators](../customization/decorators.md) - Full decorator reference
 - [Dependencies](../customization/dependencies.md) - Swapping services and serializers

package/dist/developer/tutorial/events.md

@@ -0,0 +1,166 @@
+---
+title: Events & Webhooks
+description: React to Spree store activity and connect to external systems like an OMS, warehouse, or ERP using event subscribers, the subscriber generator, and webhooks.
+---
+
+> **INFO:** This guide assumes you've completed the [Model](model.md) and [API](api.md) tutorials — we'll reuse the Brand serializer created there.
+
+Almost every real store talks to other systems: an order management system (OMS), a warehouse (WMS), an ERP, a CRM, a marketing platform. In Spree, the integration surface is the **events system** — models publish events as things happen, and you react to them without touching core code.
+
+There are two ways to consume events, and they serve different audiences:
+
+| Mechanism | Code lives | Best for |
+|---|---|---|
+| **Subscriber** | In your Spree app | Calling external APIs with your own client code, internal side effects, anything needing app context |
+| **Webhook** | In the external system | Letting a third party receive HTTP callbacks — no Ruby in your app, endpoints managed from the admin |
+
+We'll do both: push completed orders to an OMS with a subscriber, give the Brand model its own lifecycle events, and set up an outbound webhook.
+
+## Step 1: Subscribe to a Core Event
+
+When an order completes, send it to the OMS. Generate a subscriber:
+
+
+```bash Spree CLI (Docker)
+spree generate subscriber OmsOrderSync order.completed
+```
+
+```bash Without Spree CLI
+bin/rails g spree:subscriber OmsOrderSync order.completed
+```
+
+
+This creates the subscriber, a spec stub, and — crucially — **registers it** in `config/initializers/spree.rb` (injected into the existing `after_initialize` block every Spree app ships with). Subscribers are not auto-discovered; a subscriber that never gets appended to `Spree.subscribers` is a silent no-op, which is why the generator owns that step (re-runs are idempotent, and each new subscriber appends to the same initializer).
+
+Fill in the handler:
+
+```ruby app/subscribers/oms_order_sync_subscriber.rb
+class OmsOrderSyncSubscriber < Spree::Subscriber
+  subscribes_to 'order.completed'
+
+  def handle(event)
+    order = Spree::Order.find_by_prefix_id(event.payload['id'])
+    return unless order
+
+    OmsClient.create_order(
+      number: order.number,
+      email: order.email,
+      line_items: order.line_items.map { |li| { sku: li.sku, quantity: li.quantity } }
+    )
+  end
+end
+```
+
+Two things worth understanding:
+
+- **Payloads carry prefixed IDs**, not raw database IDs — always look records up with `find_by_prefix_id`. The payload itself is the resource serialized with its v3 API serializer, so `event.payload['number']`, `['email']`, etc. are available directly when you don't need the full record.
+- **Subscribers run async by default** — each `handle` call is an ActiveJob on the events queue, so a slow OMS API never blocks checkout. Pass `subscribes_to 'order.completed', async: false` only when you genuinely need synchronous execution.
+
+Restart the server, complete a test order, and watch the job fire (`spree logs worker` — or your job backend's UI).
+
+## Step 2: Give Brand Its Own Lifecycle Events
+
+Core models like Payment and Shipment publish `*.created` / `*.updated` / `*.deleted` events automatically. Your models can too — add one line to the Brand model:
+
+```ruby app/models/spree/brand.rb {3}
+module Spree
+  class Brand < Spree.base_class
+    publishes_lifecycle_events
+
+    # ... existing code ...
+  end
+end
+```
+
+Now `brand.created`, `brand.updated`, and `brand.deleted` fire after the matching transactions commit — and because you created `Spree::Api::V3::BrandSerializer` in the [API step](api.md), the payloads automatically use it (the events system resolves the serializer by naming convention). Anyone — subscriber or webhook — can react to brand changes with the same JSON shape your API serves.
+
+
+```bash Spree CLI (Docker)
+spree generate subscriber BrandSync brand.created brand.updated
+```
+
+```bash Without Spree CLI
+bin/rails g spree:subscriber BrandSync brand.created brand.updated
+```
+
+
+```ruby app/subscribers/brand_sync_subscriber.rb
+class BrandSyncSubscriber < Spree::Subscriber
+  subscribes_to 'brand.created', 'brand.updated'
+
+  def handle(event)
+    SearchIndexer.upsert_brand(event.payload)
+  end
+end
+```
+
+## Step 3: Publish a Custom Event
+
+Lifecycle events cover persistence; custom events express *domain* moments. Say featuring a brand should notify the marketing platform:
+
+```ruby
+brand.publish_event('brand.featured')
+```
+
+The payload defaults to the serializer output; pass your own hash as the second argument when the event needs different data. Subscribers consume it like any other event name.
+
+## Step 4: Outbound Webhooks — No Code Required
+
+When the consumer is an external system you don't deploy code into, use webhooks. In the admin, go to **Settings → Webhooks**, add an endpoint with the destination URL, and pick the events to deliver — `order.completed`, `brand.created`, anything publishing in your store. The endpoint's **signing secret is shown once on creation** — store it in the receiving system.
+
+Each delivery is an HTTP POST with this envelope:
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "name": "order.completed",
+  "created_at": "2026-06-11T12:00:00Z",
+  "data": { "id": "or_m3Rp9wXz", "number": "R123456789", "...": "..." },
+  "metadata": {}
+}
+```
+
+And three headers the receiver should use:
+
+| Header | Contents |
+|---|---|
+| `X-Spree-Webhook-Event` | The event name |
+| `X-Spree-Webhook-Timestamp` | Unix timestamp of the delivery |
+| `X-Spree-Webhook-Signature` | `HMAC-SHA256(secret, "{timestamp}.{body}")` |
+
+Verify the signature before trusting a payload:
+
+```ruby
+def verified?(request, secret)
+  timestamp = request.headers['X-Spree-Webhook-Timestamp']
+  expected  = OpenSSL::HMAC.hexdigest('SHA256', secret, "#{timestamp}.#{request.raw_post}")
+  ActiveSupport::SecurityUtils.secure_compare(expected, request.headers['X-Spree-Webhook-Signature'])
+end
+```
+
+Delivery semantics to design around: failed deliveries (timeouts, connection errors, non-2xx responses) are **recorded, not retried automatically** — redeliver from the endpoint's delivery history in the admin, or via `POST /api/v3/admin/webhook_endpoints/:webhook_endpoint_id/deliveries/:id/redeliver`. After **15 consecutive failures** the endpoint auto-disables and store staff get an email; a successful delivery resets the counter.
+
+## Testing a Subscriber
+
+Subscribers are plain Ruby — test `handle` directly with a constructed event:
+
+```ruby spec/subscribers/oms_order_sync_subscriber_spec.rb
+require 'rails_helper'
+
+RSpec.describe OmsOrderSyncSubscriber do
+  it 'pushes completed orders to the OMS' do
+    order = create(:completed_order_with_totals)
+    event = Spree::Event.new(name: 'order.completed', payload: { 'id' => order.prefixed_id })
+
+    expect(OmsClient).to receive(:create_order).with(hash_including(number: order.number))
+
+    described_class.new.handle(event)
+  end
+end
+```
+
+## Related Documentation
+
+- [Events](../core-concepts/events.md) — the full event catalog, subscriber DSL, and delivery guarantees
+- [Webhooks](../core-concepts/webhooks.md) — endpoint management, security, and the per-event payload schemas
+- [Extending Core Models](extending-models.md) — when a decorator is the right tool instead

package/dist/developer/tutorial/extending-models.md

@@ -5,7 +5,7 @@ description: Tutorial — extend Spree's core models with a custom Brand resourc
 
 In this tutorial, we'll connect our custom Brand model with Spree's core Product model. This is a common pattern when building features that need to integrate with existing Spree functionality.
 
-> **INFO:** This guide assumes you've completed the [Model](model.md), [Admin](admin.md), and [File Uploads](file-uploads.md) tutorials.
+> **INFO:** This guide assumes you've completed the [Model](model.md) and [Admin](admin.md) tutorials.
 
 ## What We're Building
 
@@ -77,10 +77,16 @@ The key line is `Product.prepend(ProductDecorator)` - this inserts your module a
 
 First, add a `brand_id` column to the products table:
 
-```bash
+
+```bash Spree CLI (Docker)
+spree generate migration AddBrandIdToSpreeProducts brand_id:integer:index
+```
+
+```bash Without Spree CLI
 bin/rails g migration AddBrandIdToSpreeProducts brand_id:integer:index
 ```
 
+
 Edit the migration to add an index (but no foreign key constraint, keeping it optional):
 
 ```ruby db/migrate/XXXXXXXXXXXXXX_add_brand_id_to_spree_products.rb
@@ -94,20 +100,32 @@ end
 
 Run the migration:
 
-```bash
+
+```bash Spree CLI (Docker)
+spree migrate
+```
+
+```bash Without Spree CLI
 bin/rails db:migrate
 ```
 
+
 > **INFO:** We intentionally don't add a foreign key constraint. This keeps the association optional and avoids issues if brands are deleted. Spree follows this pattern for flexibility.
 
 ## Step 2: Generate the Product Decorator
 
 Spree provides a generator to create decorator files with the correct structure:
 
-```bash
+
+```bash Spree CLI (Docker)
+spree generate model_decorator Spree::Product
+```
+
+```bash Without Spree CLI
 bin/rails g spree:model_decorator Spree::Product
 ```
 
+
 This creates `app/models/spree/product_decorator.rb`:
 
 ```ruby app/models/spree/product_decorator.rb
@@ -281,22 +299,7 @@ def normalize_name
 end
 ```
 
-**Events approach** (recommended for side effects):
-
-```ruby app/subscribers/my_app/product_sync_subscriber.rb
-module MyApp
-  class ProductSyncSubscriber < Spree::Subscriber
-    subscribes_to 'product.updated'
-
-    def handle(event)
-      product = Spree::Product.find_by_prefix_id(event.payload['id'])
-      return unless product
-
-      ExternalSyncService.sync(product)
-    end
-  end
-end
-```
+**Events approach** (recommended for side effects): subscribe to `product.updated` and react in a `Spree::Subscriber` — no decorator, no callback coupling. The [Events & Webhooks tutorial](events.md) builds this out fully, including external-system sync (OMS, warehouse) and outbound webhooks.
 
 #### Adding Class Methods
 
@@ -373,13 +376,14 @@ Spree::PermittedAttributes.product_attributes << :brand_id
 
 Now that Brands are connected to Products, let's expose them through the Store API:
 
-- [6. Store API](store-api.md) — Create API endpoints for brands and extend the Product API response
+- [6. API](api.md) — Create API endpoints for brands and extend the Product API response
 
 ## Related Documentation
 
 - [Model Tutorial](model.md) - Creating the Brand model
 - [Admin Tutorial](admin.md) - Building the admin interface
-- [Store API Tutorial](store-api.md) - Exposing brands through the API
+- [API Tutorial](api.md) - Exposing brands through the API
+- [Events & Webhooks tutorial](events.md) - Subscribers, custom events, and webhooks in the Brand storyline
 - [Events](../core-concepts/events.md) - Subscribe to model changes without decorators
 - [Webhooks](../core-concepts/webhooks.md) - HTTP callbacks for external integrations
 - [Decorators](../customization/decorators.md) - Full decorator reference