@spree/docs 0.1.85 → 0.1.86

package/dist/api-reference/admin-api/introduction.md

@@ -7,8 +7,6 @@ description: "Overview of the Spree Admin REST API for managing products, orders
 import { Since } from '/snippets/since.mdx';
 
 
-> **WARNING:** **Developer Preview.** The Admin API is in active development and may change between major versions.
-
 The Admin API is a REST API for managing Spree stores programmatically — products, orders, customers, fulfillments, payments, and more. It is intended for backend integrations, custom admin tooling, and automation.
 
 All routes are prefixed with `/api/v3/admin`. During development the API is available under `http://localhost:3000/api/v3/admin`. For production, replace `http://localhost:3000` with your Spree application URL.
@@ -55,16 +53,6 @@ const { data: orders } = await client.orders.list({
 })
 ```
 
-## What's covered
-
-The Admin API today (in Spree 5.5) covers:
-
-- **Catalog** — products, variants, prices
-- **Orders** — list, create, update, items, complete, cancel, approve, resume; nested fulfillments, payments, refunds, gift cards, store credits
-- **Customers** — full CRUD, addresses, store credits, credit cards
-
-See the **Endpoints** section in the sidebar for the complete reference, generated from the OpenAPI spec.
-
 Before integrating, read:
 
 - [Authentication](authentication.md) — secret API keys, scopes, and JWT tokens

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

@@ -0,0 +1,64 @@
+---
+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."
+---
+
+[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.
+
+The skills work with Claude Code, Codex, Cursor, GitHub Copilot, Cline, Aider, Zed, Windsurf, OpenCode, and 60+ other agentic tools.
+
+## Install
+
+Run from your project directory:
+
+```bash
+npx skills add spree/agent-skills
+```
+
+The [skills CLI](https://github.com/vercel-labs/skills) auto-detects which agent tools you have configured and copies the skill files into each tool's native location.
+
+Useful variants:
+
+```bash
+npx skills add spree/agent-skills --list                 # see what's available without installing
+npx skills add spree/agent-skills --skill spree-api-v3   # install a subset
+npx skills update                                        # update installed skills later
+```
+
+## What's inside
+
+| | |
+|---|---|
+| **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. |
+| **`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`. |
+
+Skills activate automatically based on what you're working on — asking your agent to "add a Brand model with an API" pulls in the resource-generator skill; "why is this promotion not applying" pulls in the promotions skill. There's nothing to invoke manually.
+
+## Claude Code plugin (adds commands + hooks)
+
+The `npx skills add` path installs the skills and the subagent. The slash commands and safety hooks need the Claude Code plugin install — run inside a Claude Code session:
+
+```text
+/plugin marketplace add spree/agent-skills
+/plugin install spree@spree
+```
+
+The plugin delivers everything the skills CLI does **plus** `/spree:doctor`, `/spree:audit-upgrade`, and the two safety hooks. Use one install path or the other — installing both makes the skills collide.
+
+## Works in any Spree project
+
+The skills detect your project flavor before running commands:
+
+- **create-spree-app projects** (Docker, Rails app in `backend/`) — commands route through the [Spree CLI](../cli/quickstart.md) (`spree migrate`, `spree console`, …).
+- **Classic Rails apps** (Spree gems in a plain Rails app, no Docker — typical for apps created before Spree 5.4) — the skills fall back to native commands (`bin/rails`, `bundle exec rake`) from the app root.
+
+## Updating
+
+```bash
+npx skills update          # skills CLI installs
+```
+
+Plugin installs update through Claude Code's plugin system (`/plugin` → check for updates). New Spree releases ship matching skill updates — update the skills when you upgrade Spree so the guidance matches your installed version.

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

@@ -0,0 +1,55 @@
+---
+title: "LLM-Ready Documentation"
+sidebarTitle: LLM-Ready Docs
+description: "Every page of the Spree docs is consumable by LLMs — llms.txt indexes, per-page Markdown, and a local npm package for offline agent reads."
+---
+
+Beyond the [MCP server](mcp.md), the Spree documentation is published in formats designed for direct LLM consumption. Use these when you want to feed docs into a prompt, point a custom agent at an index, or give agents fast local file access.
+
+## llms.txt
+
+Following the [llms.txt convention](https://llmstxt.org), two indexes are published:
+
+| URL | Contents |
+|---|---|
+| [`spreecommerce.org/docs/llms.txt`](https://spreecommerce.org/docs/llms.txt) | An index of every documentation page with links — lets an agent discover and fetch exactly the pages it needs |
+| [`spreecommerce.org/docs/llms-full.txt`](https://spreecommerce.org/docs/llms-full.txt) | The entire documentation in one file — for tools that ingest a single context dump |
+
+## Per-page Markdown
+
+Append `.md` to any docs URL to get the raw Markdown for that page — ideal for fetching a single authoritative page into context:
+
+```text
+https://spreecommerce.org/docs/developer/cli/quickstart.md
+https://spreecommerce.org/docs/developer/core-concepts/orders.md
+```
+
+## The `@spree/docs` npm package
+
+The full developer documentation also ships as an npm package, so agents working in your repository can `Read` doc files locally — no network round-trips, works offline, and version-pinned to what you installed:
+
+```bash
+npm install --save-dev @spree/docs
+```
+
+```text
+node_modules/@spree/docs/dist/
+├── developer/
+│   ├── getting-started/     # setup and quickstarts
+│   ├── core-concepts/       # products, orders, payments, inventory, …
+│   ├── customization/       # decorators, dependencies, events, …
+│   ├── storefront/          # Next.js storefront guides
+│   ├── sdk/                 # TypeScript SDK docs
+│   ├── admin/               # admin customization, form builder, components
+│   └── how-to/              # focused guides
+└── api-reference/
+    └── store.yaml           # the full Store API OpenAPI spec
+```
+
+Projects scaffolded with [create-spree-app](../create-spree-app/quickstart.md) install it automatically.
+
+> **NOTE:** The package tracks the docs published at install time and is versioned independently of your Spree gems — run your package manager's update to refresh it, and prefer the [MCP server](mcp.md) when you need the absolute latest.
+
+## Generated agent instructions
+
+`create-spree-app` scaffolds every project with a `CLAUDE.md` that tells coding agents where the local docs live, which CLI commands to use (`spree dev`, `spree migrate`, `spree console`), and the customization patterns to follow — so an agent dropped into a fresh project is productive without any prompting. The scaffold's next-steps also suggest installing the [agent skills](agent-skills.md) for the full experience.

package/dist/developer/agentic/mcp.md

@@ -0,0 +1,75 @@
+---
+title: "Docs MCP Server"
+sidebarTitle: MCP
+description: "Connect your AI agent to the Spree documentation MCP server to search and read the latest docs while building."
+---
+
+Spree hosts a [Model Context Protocol](https://modelcontextprotocol.io) server on top of this documentation. Once connected, your agent can search the docs and read full pages on demand — answering questions from the latest published documentation instead of stale training data.
+
+```text
+https://spreecommerce.org/docs/mcp
+```
+
+The server exposes two tools: full-text **search** across the documentation, and **reading** doc pages as Markdown.
+
+## Setup
+
+**Claude Code:**
+
+```bash
+    claude mcp add --transport http spree-docs https://spreecommerce.org/docs/mcp
+    ```
+
+    Scope it to the project (`--scope project`) to share the connection with your team via `.mcp.json`, or keep the default local scope for just yourself.
+
+  **Claude.ai / Claude Desktop:**
+
+Go to [Settings → Connectors](https://claude.ai/settings/connectors), click **Add custom connector**, and paste the URL:
+
+    ```text
+    https://spreecommerce.org/docs/mcp
+    ```
+
+  **Cursor:**
+
+Add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` globally):
+
+    ```json
+    {
+      "mcpServers": {
+        "spree-docs": {
+          "url": "https://spreecommerce.org/docs/mcp"
+        }
+      }
+    }
+    ```
+
+  **VS Code (Copilot):**
+
+Add to `.vscode/mcp.json` in your project:
+
+    ```json
+    {
+      "servers": {
+        "spree-docs": {
+          "type": "http",
+          "url": "https://spreecommerce.org/docs/mcp"
+        }
+      }
+    }
+    ```
+
+  **Other tools:**
+
+Any MCP client that supports remote servers over streamable HTTP can connect — point it at `https://spreecommerce.org/docs/mcp`. No authentication is required.
+
+
+## When to use MCP vs the other doc channels
+
+| Channel | Best for |
+|---|---|
+| **MCP server** (this page) | The latest published docs; agents working outside a scaffolded project; questions the installed skills don't cover |
+| **[`@spree/docs` npm package](llm-docs.md)** | Fast local reads inside a project — no network round-trip, works offline, pinned to what you installed |
+| **[Agent skills](agent-skills.md)** | Conventions and how-to knowledge the agent should apply without searching at all |
+
+> **NOTE:** In create-spree-app projects the generated `CLAUDE.md` already points agents at the local `@spree/docs` package first — MCP complements it for anything newer than your installed docs version.

package/dist/developer/agentic/overview.md

@@ -0,0 +1,31 @@
+---
+title: "Agentic Development"
+sidebarTitle: Overview
+description: "Build, customize, and upgrade Spree with AI coding agents — agent skills, a docs MCP server, and LLM-ready documentation."
+---
+
+Spree ships first-class tooling for AI-assisted development. Whether you use Claude Code, Cursor, Codex, Copilot, or any other coding agent, your agent can learn Spree's conventions, read the right docs at the right time, and run the project safely.
+
+## Why Spree works well with AI agents
+
+- **Strong conventions** — everything is namespaced under `Spree::`, models follow predictable patterns (prefixed IDs, `Spree.base_class`, service objects, events), and the v3 REST API uses flat request/response shapes. Conventions are what agents are best at following.
+- **Docs designed for machine consumption** — the full documentation is available as [llms.txt, per-page Markdown, and a local npm package](llm-docs.md), so agents read authoritative content instead of guessing from training data.
+- **A guided project workflow** — [create-spree-app](../create-spree-app/quickstart.md) scaffolds projects with a generated `CLAUDE.md`, local docs, and the [Spree CLI](../cli/quickstart.md), so an agent can boot, migrate, generate code, and run tests without bespoke setup.
+
+## The toolbox
+
+
+  - [Agent Skills](agent-skills.md) — 25 skills teaching agents Spree's conventions, customization patterns, and upgrade flows — installable into 60+ agent tools, plus a Claude Code plugin with slash commands and safety hooks.
+  - [Docs MCP Server](mcp.md) — Connect your agent to the Spree documentation MCP server to search and read the latest docs while building.
+  - [LLM-Ready Docs](llm-docs.md) — llms.txt, per-page Markdown, and the `@spree/docs` npm package for fast local reads.
+  - [Spree CLI](../cli/quickstart.md) — A predictable command surface (`spree dev`, `spree generate`, `spree migrate`, `spree upgrade`) that agents can drive end-to-end.
+
+
+## A typical agentic workflow
+
+1. **Scaffold** a project with `npx create-spree-app@latest my-store` — it generates a `CLAUDE.md`, installs `@spree/docs` for local reference, and wires up the CLI.
+2. **Install the agent skills** with `npx skills add spree/agent-skills` so your agent knows the decision tree for customizations (subscriber vs decorator vs dependency injection vs generator) before it writes a line of code.
+3. **Connect the docs MCP server** so questions the skills don't cover get answered from the live documentation.
+4. **Let the agent work** — generate an API resource (`spree generate api_resource Brand name:string`), customize checkout, integrate a payment provider, or run an upgrade with `spree upgrade`.
+
+> **TIP:** Skills, local docs, and MCP are complementary: skills encode *how to do things the Spree way*, local docs give *fast authoritative lookups*, and MCP covers *the latest published documentation*. Most teams use all three.

package/dist/developer/cli/quickstart.md

@@ -185,6 +185,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 migration AddPositionToSpreeBrands position:integer  # Rails built-in, forwarded as-is
 ```
 
@@ -283,3 +284,7 @@ spree task load_sample_data
 spree task spree:price_history:seed
 spree task spree:price_history:prune
 ```
+
+## Pair with AI agents
+
+The CLI's predictable command surface is what AI coding agents drive when working on Spree projects. The [Spree agent skills](../agentic/agent-skills.md) teach agents these commands and conventions, and the Claude Code plugin adds `/spree:doctor` (stack diagnosis) and `/spree:audit-upgrade` (upgrade-readiness audit) on top. See [Agentic Development](../agentic/overview.md).

package/dist/developer/contributing/developing-spree.md

@@ -432,16 +432,14 @@ Issues that are open for 14 days without actionable information or activity will
 
 Spree comes with an [AGENTS.md](https://github.com/spree/spree/blob/main/AGENTS.md) file that instructs coding agents like Claude Code or Codex to help you with your development.
 
-We also have an MCP server built on top of our Documentation website to help you with your development.
+We also ship [agent skills](../agentic/agent-skills.md) (`npx skills add spree/agent-skills`), a [docs MCP server](../agentic/mcp.md), and [LLM-ready documentation](../agentic/llm-docs.md) — see the [Agentic Development docs](../agentic/overview.md) for setup across Claude Code, Cursor, Copilot, and other tools.
 
-Add this URL to your AI tools:
+The MCP server URL for quick setup:
 
 ```
 https://spreecommerce.org/docs/mcp
 ```
 
-In Claude Code you need to go to [Connectors](https://claude.ai/settings/connectors) settings and add the URL.
-
 ## That's a wrap!
 
 Thank you for participating in Open Source and improving Spree - you're awesome!

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

@@ -56,30 +56,40 @@ flowchart TB
 
 ## Creating a Subscriber
 
-Create a subscriber class in `app/subscribers/` that inherits from `Spree::Subscriber`:
+The fastest path is the generator — it creates the class, a spec stub, and registers the subscriber in `config/initializers/spree.rb` (the step that's easy to forget):
 
-```ruby app/subscribers/my_app/order_completed_subscriber.rb
-module MyApp
-  class OrderCompletedSubscriber < Spree::Subscriber
-    subscribes_to 'order.completed'
 
-    def handle(event)
-      order_id = event.payload['id']
-      order = Spree::Order.find_by_prefix_id(order_id)
-      return unless order
+```bash Spree CLI (Docker)
+spree generate subscriber OrderCompleted order.completed
+```
 
-      # Your custom logic here
-      ExternalService.notify_order_placed(order)
-    end
+```bash Without Spree CLI
+bin/rails g spree:subscriber OrderCompleted order.completed
+```
+
+
+Or create the class by hand in `app/subscribers/`, inheriting from `Spree::Subscriber`:
+
+```ruby app/subscribers/order_completed_subscriber.rb
+class OrderCompletedSubscriber < Spree::Subscriber
+  subscribes_to 'order.completed'
+
+  def handle(event)
+    order_id = event.payload['id']
+    order = Spree::Order.find_by_prefix_id(order_id)
+    return unless order
+
+    # Your custom logic here
+    ExternalService.notify_order_placed(order)
   end
 end
 ```
 
 Then register it in an initializer — subscribers are not auto-discovered (see [Registering Subscribers](#registering-subscribers)):
 
-```ruby config/initializers/event_subscribers.rb
+```ruby config/initializers/spree.rb
 Rails.application.config.after_initialize do
-  Spree.subscribers << MyApp::OrderCompletedSubscriber
+  Spree.subscribers << OrderCompletedSubscriber
 end
 ```
 
@@ -108,37 +118,35 @@ end
 
 When subscribing to multiple events, use the `on` DSL to route events to specific methods:
 
-```ruby app/subscribers/my_app/order_audit_subscriber.rb
-module MyApp
-  class OrderAuditSubscriber < Spree::Subscriber
-    subscribes_to 'order.completed', 'order.canceled', 'order.resumed'
+```ruby app/subscribers/order_audit_subscriber.rb
+class OrderAuditSubscriber < Spree::Subscriber
+  subscribes_to 'order.completed', 'order.canceled', 'order.resumed'
 
-    on 'order.completed', :log_order_completed
-    on 'order.canceled', :log_order_canceled
-    on 'order.resumed', :log_order_resumed
+  on 'order.completed', :log_order_completed
+  on 'order.canceled', :log_order_canceled
+  on 'order.resumed', :log_order_resumed
 
-    private
+  private
 
-    def log_order_completed(event)
-      create_audit_log(event, 'completed')
-    end
+  def log_order_completed(event)
+    create_audit_log(event, 'completed')
+  end
 
-    def log_order_canceled(event)
-      create_audit_log(event, 'canceled')
-    end
+  def log_order_canceled(event)
+    create_audit_log(event, 'canceled')
+  end
 
-    def log_order_resumed(event)
-      create_audit_log(event, 'resumed')
-    end
+  def log_order_resumed(event)
+    create_audit_log(event, 'resumed')
+  end
 
-    def create_audit_log(event, action)
-      AuditLog.create!(
-        resource_type: 'Spree::Order',
-        resource_id: event.payload['id'],
-        action: action,
-        occurred_at: event.created_at
-      )
-    end
+  def create_audit_log(event, action)
+    AuditLog.create!(
+      resource_type: 'Spree::Order',
+      resource_id: event.payload['id'],
+      action: action,
+      occurred_at: event.created_at
+    )
   end
 end
 ```
@@ -363,8 +371,8 @@ Spree.api.order_serializer = 'MyApp::OrderSerializer'
 
 If you add a custom model that publishes events, create a V3 serializer:
 
-```ruby app/models/my_app/subscription.rb
-module MyApp
+```ruby app/models/spree/subscription.rb
+module Spree
   class Subscription < Spree.base_class
     publishes_lifecycle_events
 
@@ -403,17 +411,17 @@ Models without a matching serializer will use a minimal fallback payload contain
 
 ## Registering Subscribers
 
-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:
+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 `config/initializers/spree.rb` (or any initializer):
 
-```ruby config/initializers/event_subscribers.rb
+```ruby config/initializers/spree.rb
 Rails.application.config.after_initialize do
-  Spree.subscribers << MyApp::CustomSubscriber
+  Spree.subscribers << CustomSubscriber
 end
 ```
 
 To remove a built-in subscriber:
 
-```ruby config/initializers/event_subscribers.rb
+```ruby config/initializers/spree.rb
 Rails.application.config.after_initialize do
   Spree.subscribers.delete(Spree::ExportSubscriber)
 end
@@ -457,10 +465,10 @@ This is useful for:
 
 ### Testing Event Handling
 
-```ruby spec/subscribers/my_app/order_completed_subscriber_spec.rb
+```ruby spec/subscribers/order_completed_subscriber_spec.rb
 require 'spec_helper'
 
-RSpec.describe MyApp::OrderCompletedSubscriber do
+RSpec.describe OrderCompletedSubscriber do
   let(:order) { create(:completed_order_with_totals) }
   let(:event) do
     Spree::Event.new(
@@ -509,41 +517,39 @@ end
 
 Here's a complete example of a subscriber that sends alerts when inventory is low:
 
-```ruby app/subscribers/my_app/inventory_alert_subscriber.rb
-module MyApp
-  class InventoryAlertSubscriber < Spree::Subscriber
-    subscribes_to 'stock_item.updated'
+```ruby app/subscribers/inventory_alert_subscriber.rb
+class InventoryAlertSubscriber < Spree::Subscriber
+  subscribes_to 'stock_item.updated'
 
-    LOW_STOCK_THRESHOLD = 10
+  LOW_STOCK_THRESHOLD = 10
 
-    def handle(event)
-      stock_item = find_stock_item(event)
-      return unless stock_item
-      return unless stock_dropped_below_threshold?(event, stock_item)
+  def handle(event)
+    stock_item = find_stock_item(event)
+    return unless stock_item
+    return unless stock_dropped_below_threshold?(event, stock_item)
 
-      send_low_stock_alert(stock_item)
-    end
+    send_low_stock_alert(stock_item)
+  end
 
-    private
+  private
 
-    def find_stock_item(event)
-      Spree::StockItem.find_by_prefix_id(event.payload['id'])
-    end
+  def find_stock_item(event)
+    Spree::StockItem.find_by_prefix_id(event.payload['id'])
+  end
 
-    def stock_dropped_below_threshold?(event, stock_item)
-      previous_count = event.payload['count_on_hand_before_last_save']
-      current_count = stock_item.count_on_hand
+  def stock_dropped_below_threshold?(event, stock_item)
+    previous_count = event.payload['count_on_hand_before_last_save']
+    current_count = stock_item.count_on_hand
 
-      previous_count >= LOW_STOCK_THRESHOLD && current_count < LOW_STOCK_THRESHOLD
-    end
+    previous_count >= LOW_STOCK_THRESHOLD && current_count < LOW_STOCK_THRESHOLD
+  end
 
-    def send_low_stock_alert(stock_item)
-      InventoryMailer.low_stock_alert(
-        variant: stock_item.variant,
-        stock_location: stock_item.stock_location,
-        count_on_hand: stock_item.count_on_hand
-      ).deliver_later
-    end
+  def send_low_stock_alert(stock_item)
+    InventoryMailer.low_stock_alert(
+      variant: stock_item.variant,
+      stock_location: stock_item.stock_location,
+      count_on_hand: stock_item.count_on_hand
+    ).deliver_later
   end
 end
 ```

package/dist/developer/customization/api.md

@@ -6,7 +6,7 @@ description: >-
 
 Before you start customizing Spree API endpoints, make sure you reviewed all existing API endpoints in the [Spree API docs](/api-reference).
 
-For a step-by-step walkthrough of adding a complete new resource (model, serializer, controller, routes), see the [Store API tutorial](../tutorial/store-api.md).
+For a step-by-step walkthrough of adding a complete new resource (model, serializer, controller, routes), see the [API tutorial](../tutorial/api.md).
 
 ## Customizing JSON Responses
 
@@ -36,7 +36,7 @@ Restart the server and the Product API will include your new attribute.
 
 ### Adding an Association
 
-Let's say you've created a `Spree::Brand` model that belongs to `Product` (see the [tutorial](../tutorial/store-api.md) for the full example).
+Let's say you've created a `Spree::Brand` model that belongs to `Product` (see the [tutorial](../tutorial/api.md) for the full example).
 
 Create a serializer for the new model:
 

package/dist/developer/customization/checkout.md

@@ -102,19 +102,17 @@ There are two approaches for adding logic around checkout state transitions:
 
 For actions that should happen **after** a checkout step completes (syncing with external services, sending notifications, logging, etc.), use [Events subscribers](../core-concepts/events.md). This is the recommended approach because it keeps your code decoupled from Spree internals.
 
-```ruby app/subscribers/my_app/order_completed_subscriber.rb
-module MyApp
-  class OrderCompletedSubscriber < Spree::Subscriber
-    subscribes_to 'order.completed'
-
-    def handle(event)
-      order = Spree::Order.find_by_prefix_id(event.payload['id'])
-      return unless order
-
-      # Sync to fulfillment system, notify warehouse, etc.
-      FulfillmentService.notify(order)
-      AnalyticsService.track_purchase(order)
-    end
+```ruby app/subscribers/order_completed_subscriber.rb
+class OrderCompletedSubscriber < Spree::Subscriber
+  subscribes_to 'order.completed'
+
+  def handle(event)
+    order = Spree::Order.find_by_prefix_id(event.payload['id'])
+    return unless order
+
+    # Sync to fulfillment system, notify warehouse, etc.
+    FulfillmentService.notify(order)
+    AnalyticsService.track_purchase(order)
   end
 end
 ```

package/dist/developer/customization/decorators.md

@@ -483,19 +483,17 @@ end
 
 **After (Events subscriber):**
 
-```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
-
-      # The payload includes changes, check if name changed
-      if event.payload['previous_changes']&.key?('name')
-        ExternalSyncJob.perform_later(product)
-      end
+```ruby app/subscribers/product_sync_subscriber.rb
+class ProductSyncSubscriber < Spree::Subscriber
+  subscribes_to 'product.updated'
+
+  def handle(event)
+    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
   end
 end

package/dist/developer/customization/quickstart.md

@@ -56,18 +56,16 @@ Spree is a flexible platform allowing you to customize every part of it to suit
 
     Spree's event system lets you subscribe to events like `order.completed`, `product.updated`, `payment.paid`, etc.:
 
-    ```ruby app/subscribers/my_app/order_completed_subscriber.rb
-    module MyApp
-      class OrderCompletedSubscriber < Spree::Subscriber
-        subscribes_to 'order.completed'
+    ```ruby app/subscribers/order_completed_subscriber.rb
+    class OrderCompletedSubscriber < Spree::Subscriber
+      subscribes_to 'order.completed'
 
-        def handle(event)
-          order = Spree::Order.find_by_prefix_id(event.payload['id'])
-          return unless order
+      def handle(event)
+        order = Spree::Order.find_by_prefix_id(event.payload['id'])
+        return unless order
 
-          # Sync to external service, send notification, etc.
-          ExternalService.notify_order_placed(order)
-        end
+        # Sync to external service, send notification, etc.
+        ExternalService.notify_order_placed(order)
       end
     end
     ```

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

@@ -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!