@spree/docs 0.1.236 → 0.1.238

package/dist/developer/tutorial/introduction.md

@@ -1,24 +1,53 @@
 ---
 title: "Tutorial: Build a Custom Feature"
-description: Build Product FAQs end to end — a custom model, an Admin API endpoint, a dashboard plugin, a Store API endpoint, and storefront rendering through the TypeScript SDK.
+description: Build a complete Brands feature in Spree — model and API from one generator, a dashboard plugin, storefront rendering, events, and tests.
 ---
 
-This tutorial builds one complete feature — **Product FAQs**, questions and answers attached to products — through every layer of a Spree 6 application. By the end you will have a custom model, back-office management in the dashboard, and customer-facing display on the storefront.
+This tutorial builds one complete feature — **Brands**, a manufacturer or label attached to products — through every layer of a Spree application. By the end you will have a custom model with its own Store and Admin API, brand management in the dashboard, brands rendered on the storefront, other systems reacting to brand changes, and tests covering all of it.
 
-## The two tracks
+It is written for **both backend and frontend developers**. The backend code you write is minimal and mostly generated — Spree's generators produce convention-correct models, controllers and serializers, and the TypeScript SDK gives you typed access from your storefront. Most of what you write by hand is TypeScript.
 
-The tutorial is organized so you only build what your feature needs:
+## What you'll build
 
-| Track | Chapters | Build this when |
-|---|---|---|
-| Foundation | [Model](model.md) | Always |
-| **A — manage it in the dashboard** | [Admin API](admin-api.md) → [Dashboard plugin](dashboard-plugin.md) | The feature is operated by staff — internal tooling, back-office data |
-| **B — expose it on the storefront** | [Store API](store-api.md) → [Storefront](storefront.md) | Customers see the feature |
-| Finishing | [Events](events.md) → [Testing](testing.md) | Always |
+- A `Spree::Brand` model with a Store API and an Admin API — one generator command
+- A brands screen in the dashboard: a list page, navigation and a card on the product page
+- Brands on the storefront, fetched through `@spree/sdk` with generated types
+- Lifecycle events other systems subscribe to, in the app or over webhooks
+- Specs for the model and both APIs, plus an end-to-end pass
 
-An internal tool is Track A alone. A storefront feature over existing data is Track B alone. Product FAQs need both: staff write the answers, customers read them.
+## The five steps
+
+
+  - [1. Models & API](model-and-api.md) — Generate the model, migration, Store and Admin controllers, serializers and routes in one command
+  - [2. Dashboard](dashboard.md) — Scaffold the back-office UI with the CLI — a table, a form, navigation and a product slot
+  - [3. Storefront](storefront.md) — Regenerate SDK types and render brands on the product page in the Next.js storefront
+  - [4. Events](events.md) — Publish lifecycle events and consume them with subscribers and outbound webhooks
+  - [5. Testing](testing.md) — Model and request specs, dashboard plugin tests, and one end-to-end check
+
+
+The order is deliberate. Step 1 gives every later step something real to talk to: the dashboard plugin calls the Admin API, the storefront calls the Store API, and the events in step 4 reuse the serializer the same generator produced.
 
 ## Before you start
 
-- A running Spree application — see the [quickstart](../getting-started/quickstart.md)
-- The AI tooling set up — the [agent skills and MCP server](../agentic/overview.md) make every step of this tutorial faster
+You need a running Spree application. The fastest path is [create-spree-app](../create-spree-app/quickstart.md), a Docker-based project with the [Spree CLI](../cli/quickstart.md) and nothing to install locally:
+
+```bash
+npx create-spree-app@latest my-store
+```
+
+**Every command in this tutorial runs from the root of that project**, through the `spree` CLI. Nothing needs installing on your machine — the CLI routes each command into the right container.
+
+The project it creates has this shape, and the paths in every chapter are relative to its root:
+
+```
+my-store/
+├── server/          # the Server app — models, API, specs
+├── apps/
+│   ├── dashboard/   # the admin SPA (React)
+│   └── storefront/  # the Next.js storefront
+└── docker-compose.yml
+```
+
+> **NOTE:** **create-spree-app projects:** run `spree eject` once before starting. Fresh projects use a prebuilt Docker image; ejecting switches to the development setup that mounts your app into the container, so the files the generators create land in your project and reload as you edit them.
+
+> **TIP:** Using an AI coding agent? Install the [Spree agent skills](../agentic/agent-skills.md) (`npx skills add spree/agent-skills`) and connect the [docs MCP server](../agentic/mcp.md) before starting. Your agent will know the conventions this tutorial teaches and can follow along with you. See [AI-assisted development](../agentic/overview.md).

package/dist/developer/tutorial/model-and-api.md

@@ -0,0 +1,187 @@
+---
+title: Models & API
+sidebarTitle: Models & API
+description: Generate the Brand model, migration, Store and Admin API controllers, serializers and routes with a single spree:api_resource command.
+---
+
+Every feature starts with a model and the API that exposes it. They arrive together: `spree:api_resource` generates the model, its migration, a customer-facing Store API, a back-office Admin API, serializers, routes, a factory and controller specs in one command.
+
+This matters for the rest of the tutorial. The dashboard plugin in step 2 talks to the Admin API, the storefront in step 3 talks to the Store API, and the events in step 4 reuse the serializer generated here. Getting this step right makes the other four mostly configuration.
+
+## Step 1: Generate the resource
+
+A brand has a name, a slug for friendly URLs, and an active flag:
+
+```bash
+spree generate api_resource Brand name:string:index slug:string:uniq active:boolean
+```
+
+The generator reports what it created:
+
+```text
+    create  app/models/spree/brand.rb
+    create  db/migrate/XXXXXXXXXXXXXX_create_spree_brands.rb
+    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
+    create  spec/controllers/spree/api/v3/store/brands_controller_spec.rb
+    create  spec/controllers/spree/api/v3/admin/brands_controller_spec.rb
+
+✓ Generated Spree::Brand API resource
+
+  Prefixed ID:  brand_xxxxxxxxxx
+  Store API:    /api/v3/store/brands  (read-only)
+  Admin API:    /api/v3/admin/brands  (full CRUD)
+```
+
+Apply the migration:
+
+```bash
+spree migrate
+```
+
+> **INFO:** Every command in this tutorial runs from the root of your [create-spree-app](../create-spree-app/quickstart.md) project. `spree` routes each one into the right container, so generators write into `server/` and nothing needs installing on your machine.
+
+### The field syntax
+
+Attributes follow the familiar `name:type:index` form, with the Spree conventions applied for you:
+
+| You write | You get |
+|---|---|
+| `name:string:index` | A non-null string column with an index |
+| `slug:string:uniq` | A string column with a unique index |
+| `active:boolean` | A boolean column with a default |
+| `user:belongs_to` | A reference with the class name resolved |
+
+Useful flags: `--paranoid` for soft delete, `--custom-fields` for [custom fields](../core-concepts/metafields.md) support, `--writable` to give the Store API create, update and destroy as well, and `--no-store` or `--no-admin` to generate only one side. Run the generator with `--help` for the full list.
+
+## Step 2: What you got
+
+You do not need to read the generated code to use it. The command produced a complete, convention-correct API, and the contract it gives you is this:
+
+| Surface | Endpoint | Who calls it | Default access |
+|---|---|---|---|
+| Store API | `/api/v3/store/brands` | Storefronts, mobile apps | Read-only |
+| Admin API | `/api/v3/admin/brands` | Dashboard, integrations, scripts | Full CRUD |
+
+Three conventions are worth knowing, because every later step depends on them:
+
+- **Public IDs, never database IDs.** Records are addressed as `brand_k5nR8xLq`. The API accepts and returns that form everywhere.
+- **Two serializers, one inheriting the other.** The Store serializer carries public fields only; the Admin serializer extends it and adds `created_at` and `updated_at`. Add a public field once and both surfaces get it. This is why customers never see back-office data by accident.
+- **Filtering is allowlisted.** `name`, `slug` and `active` are queryable because the generator listed them. Anything not on that list is rejected, so a caller cannot filter by a column you did not intend to expose.
+
+The Store API is read-only by default — a shopper cannot create a brand. Pass `--writable` if a resource genuinely needs customer writes, as carts and addresses do.
+
+**Brands belong to a store.** Every resource you generate is scoped to one, because commerce data — catalog, configuration, orders — is always per-store. A new record picks up its store automatically, and a field marked unique is unique *within* a store, so two stores can each have a brand called `wilson`. Only genuinely global reference data, like countries, opts out with `--no-store-scoped`.
+
+> **WARNING:** One decision is still yours: **authorization**. Give the resource a permission rule before exposing it, and read lookups through the store (`current_store.brands`) rather than the whole table. Scoping by association is the cheapest defence against one store reading another's records — filtering by role is not a substitute.
+
+## Step 3: Try it
+
+Create a brand through the Admin API. You need a secret key from **Settings → API keys** in the dashboard:
+
+```bash
+curl -X POST "http://localhost:3000/api/v3/admin/brands" \
+  -H "X-Spree-API-Key: sk_YOUR_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{ "name": "Wilson", "slug": "wilson", "active": true }'
+```
+
+```json
+{
+  "id": "brand_k5nR8xLq",
+  "name": "Wilson",
+  "slug": "wilson",
+  "active": true,
+  "created_at": "2026-01-15T10:30:00Z",
+  "updated_at": "2026-01-15T10:30:00Z"
+}
+```
+
+Note the flat request body. API v3 takes no `{ "brand": { ... } }` wrapper around the attributes, and the response identifies the record as `brand_k5nR8xLq` rather than by a database ID.
+
+Now read it back from the Store API, using a publishable key from the same settings page:
+
+```bash
+curl -H "X-Spree-API-Key: pk_YOUR_KEY" \
+  "http://localhost:3000/api/v3/store/brands"
+```
+
+```json
+{
+  "data": [
+    { "id": "brand_k5nR8xLq", "name": "Wilson", "slug": "wilson", "active": true }
+  ],
+  "meta": { "count": 1, "page": 1, "pages": 1 }
+}
+```
+
+The same record, minus the timestamps. That difference is the serializer split doing its job: customers get public fields, staff get the operational ones.
+
+Filtering works through the allowlist:
+
+```bash
+curl -H "X-Spree-API-Key: pk_YOUR_KEY" \
+  "http://localhost:3000/api/v3/store/brands?q[name_cont]=wil"
+```
+
+> **TIP:** Prefer TypeScript? The same call through the SDK is `client.request('GET', '/brands')` — step 3 covers the typed client in full.
+
+## Connect brands to products
+
+A brand on its own is a list. Adding a `brand_id` to products is what makes it useful in steps 2 and 3:
+
+```bash
+spree generate migration AddBrandToSpreeProducts brand:belongs_to
+spree migrate
+```
+
+Then connect the two models. Extending a core model like `Spree::Product` is the one place this step needs backend code — a [decorator](../customization/decorators.md) adds behavior to a core class without forking it. The generator writes the file:
+
+```bash
+spree generate model_decorator Product
+```
+
+Add one line inside the generated `prepended` block:
+
+```ruby server/app/models/spree/product_decorator.rb
+base.belongs_to :brand, class_name: 'Spree::Brand', optional: true
+```
+
+And the matching line in `app/models/spree/brand.rb`, which is your own file:
+
+```ruby
+has_many :products, class_name: 'Spree::Product', dependent: :nullify
+```
+
+`optional: true` lets a product exist without a brand. `dependent: :nullify` means deleting a brand clears the reference rather than deleting the products that carried it — almost always what you want for a label attached to a catalog.
+
+Two more lines make the association usable from the API. The product serializer has to expose it, or the storefront cannot read a product's brand:
+
+```ruby server/app/serializers/spree/api/v3/product_serializer_decorator.rb
+attribute(:brand_id) { |product| product.brand&.prefixed_id }
+has_one :brand, serializer: Spree::Api::V3::BrandSerializer
+```
+
+The model has to allow filtering by it, or `?q[brand_id_eq]=…` is rejected:
+
+```ruby server/app/models/spree/product_decorator.rb
+base.whitelisted_ransackable_attributes |= %w[brand_id]
+base.whitelisted_ransackable_associations |= %w[brand]
+```
+
+The allowlist is deliberate: every entry is a query any caller can run, so add only what the storefront needs.
+
+Finally, the Admin API has to accept `brand_id` on write, or the picker you build in step 2 will appear to work and save nothing. Extensions append to the model's list rather than replacing it:
+
+```ruby server/config/initializers/spree.rb
+Spree::Product.additional_permitted_attributes += [:brand_id]
+```
+
+Always `+=`, never `=` — assigning would drop whatever another extension added.
+
+## Next step
+
+The data and both APIs are live. Now give staff a way to manage brands: [Dashboard](dashboard.md).

package/dist/developer/tutorial/storefront.md

@@ -1,12 +1,129 @@
 ---
 title: Storefront
-description: Render FAQs on the product page — regenerate the SDK types, extend the TypeScript client, and build the component in the Next.js storefront.
+description: Render brands on the Next.js storefront in apps/storefront — call the Store API through @spree/sdk and build the product and brand pages.
 ---
 
-The Store API endpoint becomes typed TypeScript and a component on the product page. This chapter closes the loop from Rails model to customer screen.
+The Store API endpoint from step 1 becomes typed TypeScript and a component on the product page. This step closes the loop from the Server app to the customer’s screen.
 
-## What this chapter covers
+## Step 1: Describe the resource to TypeScript
 
-- The type generation pipeline: serializer to TypeScript types to runtime schemas
-- Extending the SDK client with the new resource
-- Fetching and rendering FAQs on the product detail page in the Next.js storefront
+The storefront lives at `apps/storefront/` and talks to the Store API through `@spree/sdk`. Built-in resources like products and carts already ship typed. A resource you added is new to the SDK, so declare its shape once and reuse it:
+
+```typescript apps/storefront/src/types/brand.ts
+export interface Brand {
+  id: string
+  name: string
+  slug: string | null
+  active: boolean
+}
+```
+
+These are exactly the fields your Store serializer returns — the public ones, without the timestamps the Admin API adds. Keep this file in step with the serializer: it is the contract between the two halves of your project.
+
+> **NOTE:** Spree generates the built-in SDK types from its own serializers, which is why `client.products` is typed without you doing anything. That pipeline runs inside the Spree repository, not your app, so a resource you add gets a hand-written interface like the one above.
+
+## Step 2: Call the endpoint
+
+`createClient` gives you a typed Store API client. Built-in resources have methods; custom ones go through `request`, which carries the same authentication, retries and locale defaults:
+
+```typescript apps/storefront/src/lib/spree.ts
+import { createClient } from '@spree/sdk'
+
+export const client = createClient({
+  baseUrl: process.env.NEXT_PUBLIC_SPREE_API_URL!,
+  publishableKey: process.env.NEXT_PUBLIC_SPREE_PUBLISHABLE_KEY!,
+})
+```
+
+Fetching brands then goes through `request`, with paths relative to `/api/v3/store`:
+
+```typescript
+import type { PaginatedResponse } from '@spree/sdk'
+import { client } from '@/lib/spree'
+import type { Brand } from '@/types/brand'
+
+const brands = await client.request<PaginatedResponse<Brand>>('GET', '/brands')
+const wilson = await client.request<Brand>('GET', '/brands/brand_k5nR8xLq')
+```
+
+Only the fields the Store serializer declared come back. Timestamps and anything admin-only are absent by design — that is the serializer split from step 1 doing its job.
+
+> **NOTE:** A generated resource is addressed by its prefixed ID. Looking one up by slug needs a `find_resource` override on the controller — the products endpoint does exactly that, so `/products/{slug}` works. Until you add one for brands, route by ID and treat `slug` as display data.
+
+## Step 3: Expand brand on products
+
+Because `Spree::Product` now belongs to a brand, product responses can carry it. Ask for it with `expand`:
+
+```typescript
+// Without expand — the id only
+const product = await client.products.get('prod_86Rf07xd4z')
+
+// With expand — the nested brand object
+const withBrand = await client.products.get('prod_86Rf07xd4z', {
+  expand: ['brand'],
+})
+```
+
+Expanding avoids a second round trip per product, which matters on a product listing page.
+
+> **INFO:** For `expand: ['brand']` to work, the Product serializer must declare the association and the model must allowlist it for filtering. Add `brand` to the product's `whitelisted_ransackable_associations` if you also want `?q[brand_name_cont]=wilson`. Every allowlist entry is a query any caller can run, so add only what the storefront needs.
+
+## Step 4: Render it on the product page
+
+In the Next.js storefront, fetch the product with its brand and render the name:
+
+```tsx apps/storefront/src/app/products/[slug]/page.tsx
+import { client } from '@/lib/spree'
+
+export default async function ProductPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params
+  const product = await client.products.get(slug, { expand: ['brand'] })
+
+  return (
+    <article>
+      {product.brand && (
+        <a href={`/brands/${product.brand.id}`} className="text-sm text-neutral-500">
+          {product.brand.name}
+        </a>
+      )}
+      <h1>{product.name}</h1>
+      <p>{product.price.display}</p>
+    </article>
+  )
+}
+```
+
+And a brand page listing everything that brand makes:
+
+```tsx apps/storefront/src/app/brands/[id]/page.tsx
+import { client } from '@/lib/spree'
+import type { Brand } from '@/types/brand'
+
+export default async function BrandPage({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const brand = await client.request<Brand>('GET', `/brands/${id}`)
+  const products = await client.products.list({ brand_id_eq: brand.id })
+
+  return (
+    <section>
+      <h1>{brand.name}</h1>
+      <p>{products.meta.count} products</p>
+      <ul>
+        {products.data.map((product) => (
+          <li key={product.id}>
+            <a href={`/products/${product.slug}`}>{product.name}</a>
+          </li>
+        ))}
+      </ul>
+    </section>
+  )
+}
+```
+
+`brand_id_eq` is a Ransack predicate, available because `brand_id` is on the product's ransackable allowlist. See [search and filtering](../core-concepts/search-filtering.md) for the full predicate list.
+
+> **NOTE:** The storefront runs on its own dev server. From the project root, `spree dev` starts the API and dashboard; start the storefront alongside them with `cd apps/storefront && pnpm dev`. It reads the API URL and publishable key from `apps/storefront/.env.local`.
+
+## Next step
+
+Customers can see brands. Now let other systems react when they change: [Events](events.md).

package/dist/developer/tutorial/testing.md

@@ -1,13 +1,169 @@
 ---
 title: Testing
-description: Test the feature at every layer — model and request specs with RSpec, dashboard plugin tests with Vitest, and an end-to-end check with Playwright.
+description: Test the Brands feature at every layer — model and API specs with RSpec, dashboard tests with Vitest, and one end-to-end Playwright pass.
 ---
 
-Each layer of the feature gets the test that suits it: fast Ruby specs for the model and both API endpoints, component tests for the plugin, and one end-to-end pass proving the whole path works.
+Each layer gets the test that suits it: fast backend specs for the model and both APIs, component tests for the dashboard, and one end-to-end pass proving the whole path works.
 
-## What this chapter covers
+Your project arrives with testing already configured — RSpec, FactoryBot, and Spree's own test helpers, including every factory core ships. You can write a spec against `create(:product)` without setting anything up.
 
-- Model and factory setup
-- Request specs for the Admin and Store API endpoints
-- Dashboard plugin tests with Vitest
-- An end-to-end Playwright spec: create an FAQ in the dashboard, see it on the storefront
+## Step 1: Run what the generator wrote
+
+The generator in step 1 already wrote a factory and a controller spec per API side, so this step is mostly filling in rather than starting over:
+
+```text
+server/spec/factories/spree/brand_factory.rb
+server/spec/controllers/spree/api/v3/store/brands_controller_spec.rb
+server/spec/controllers/spree/api/v3/admin/brands_controller_spec.rb
+```
+
+Run them:
+
+```bash
+spree rspec spec/controllers/spree/api/v3/
+```
+
+The generated factory is the starting point for every other spec — always build records through factories rather than creating them directly, so a change to the model does not mean editing fifty specs.
+
+## Step 2: Model specs
+
+Test what you wrote, not what the framework already guarantees. A presence validation on a required column needs no spec; the association behavior you chose does:
+
+```ruby server/spec/models/spree/brand_spec.rb
+RSpec.describe Spree::Brand, type: :model do
+  it 'nullifies the reference instead of deleting products' do
+    brand = create(:brand)
+    product = create(:product, brand: brand)
+
+    brand.destroy
+
+    expect(product.reload.brand_id).to be_nil
+    expect(product).to be_persisted
+  end
+end
+```
+
+Prefer `build` over `create` when a record does not need to hit the database — it is markedly faster across a suite.
+
+## Step 3: Controller specs
+
+Controller specs are where edge cases belong: authorization, scoping, filtering, error shapes. Always `render_views`, so a broken serializer fails the spec rather than passing silently:
+
+```ruby server/spec/controllers/spree/api/v3/store/brands_controller_spec.rb
+RSpec.describe Spree::Api::V3::Store::BrandsController, type: :controller do
+  render_views
+
+  it 'exposes public fields only' do
+    create(:brand, name: 'Wilson')
+
+    get :index, params: { format: :json }
+
+    record = json_response['data'].first
+    expect(record['id']).to start_with('brand_')
+    expect(record).not_to have_key('created_at')
+  end
+
+  it 'filters by name' do
+    create(:brand, name: 'Wilson')
+    create(:brand, name: 'Penn')
+
+    get :index, params: { q: { name_cont: 'wil' }, format: :json }
+
+    expect(json_response['data'].map { |b| b['name'] }).to eq(['Wilson'])
+  end
+end
+```
+
+That second example is worth keeping: it proves the Ransack allowlist from step 1 actually permits `name_cont`. Remove `name` from `whitelisted_ransackable_attributes` and this spec fails, which is exactly what you want.
+
+> **NOTE:** Specs run against a store the suite sets up for you, available as `@default_store`. Use it rather than creating another store marked as the default — two of them in one run produce failures that surface far from their cause.
+
+## Step 4: Dashboard tests
+
+The dashboard is a TypeScript app, so its code tests with Vitest:
+
+```bash
+cd apps/dashboard && pnpm test
+```
+
+Test the client wrappers and any logic in your pages. Mock the HTTP layer rather than the client module, so the test exercises the real request path:
+
+```ts apps/dashboard/src/brands/client.test.ts
+import { http, HttpResponse } from 'msw'
+import { setupServer } from 'msw/node'
+import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest'
+import { BrandsClient } from './client'
+
+const server = setupServer(
+  http.get('*/api/v3/admin/brands', () =>
+    HttpResponse.json({ data: [{ id: 'brand_k5nR8xLq', name: 'Wilson' }] }),
+  ),
+)
+
+beforeAll(() => server.listen())
+afterEach(() => server.resetHandlers())
+afterAll(() => server.close())
+
+describe('BrandsClient', () => {
+  it('lists brands from the admin endpoint', async () => {
+    const result = await BrandsClient.list({ per_page: 10 })
+
+    expect(result.data).toHaveLength(1)
+    expect(result.data[0].name).toBe('Wilson')
+  })
+})
+```
+
+Mocking the HTTP layer rather than the client module means the test exercises the real request path — the URL, the params and the response shape — so a wrong endpoint fails here instead of in the browser.
+
+## Step 5: One end-to-end pass
+
+Everything above tests a layer in isolation. One Playwright spec proves the layers are actually connected — a brand created through the Admin API reaches the dashboard screen you built:
+
+```ts apps/dashboard/e2e/brands.spec.ts
+import { expect, test } from '@playwright/test'
+import { createBrand } from './helpers/api'
+import { login } from './helpers/login'
+
+test('a brand appears on the brands screen', async ({ page }) => {
+  const name = `Wilson ${Date.now()}`
+  await createBrand({ name, slug: `wilson-${Date.now()}` })
+
+  await login(page)
+  await page.getByRole('link', { name: /brands/i }).click()
+
+  await expect(page.getByRole('cell', { name })).toBeVisible()
+})
+```
+
+Navigating from the sidebar rather than calling `page.goto('/brands')` keeps the spec honest about the real path, which is store-scoped (`/:storeId/brands`) and would otherwise have to be hardcoded.
+
+Once you add a create form, replace the API call with the form itself — filling it and asserting the new row is the stronger test, because it covers the write path too.
+
+Two conventions matter here:
+
+- **Drive the UI, assert on the UI.** Fill labels, click buttons, check visible text. Avoid waiting on API responses — `expect(...).toBeVisible()` polls until the condition holds, which covers nearly every case and keeps the test from breaking when the API shape changes.
+- **Suffix names with `Date.now()`.** Specs share a database, and a fixed name collides with whatever an earlier run left behind.
+
+## What to run before you push
+
+Run the specs for what you changed rather than the whole suite:
+
+```bash
+spree rspec spec/models/spree/brand_spec.rb
+spree rspec spec/controllers/spree/api/v3/
+```
+
+Pass a file, a directory, or a single example with a line number (`spec/models/spree/brand_spec.rb:12`). Keep the full run for continuous integration, where waiting costs you nothing.
+
+## You're done
+
+You have built one feature through every layer of Spree:
+
+- A model with a Store API and an Admin API, generated in one command
+- A dashboard plugin giving staff a place to manage it
+- Storefront pages rendering it through typed SDK calls
+- Lifecycle events other systems react to
+- Tests at each layer, plus one pass across all of them
+
+From here: [customization reference](../customization/quickstart.md) for extending core models and workflows, [dashboard customization](../dashboard/customization/quickstart.md) for deeper plugin work, and [core concepts](../core-concepts/architecture.md) for how the rest of the platform fits together.

package/dist/developer/upgrades/5.6-to-6.0.md

@@ -138,6 +138,22 @@ bundle exec rake spree:stock:recount_levels
 
 `spree_stock_levels` gains `reserved_count` (units held by checkouts in progress) and `incoming_count` (units on their way on a purchase order placed with a supplier or a transfer in transit). Both are kept by the workflows that change them and start at zero on an existing install; this recomputes them from active reservations and open documents and prints every level it corrected. Until it runs, the dashboard's Inventory page shows zero reserved and incoming for stock that predates the upgrade. Safe to re-run at any time.
 
+### Name who performed past actions
+
+```bash
+bundle exec rake spree:upgrade:backfill_actor_types
+```
+
+Orders, refunds, returns, exchanges, claims and stock receipts remember who
+cancelled, approved, created or received them. In 6.0 that can be a member of
+staff **or an API key**, so each id column — `canceler_id`, `approver_id`,
+`created_by_id`, `refunder_id`, `received_by_id` — gained a type column beside
+it (`canceler_type`, and so on) naming which kind of actor the id points at.
+
+Rows written before the upgrade carry an id and an empty type; this task fills
+the type in. Until it runs they still read as the staff member they always
+were, with a deprecation warning. Safe to re-run at any time.
+
 ## The Cart/Order split
 
 The single biggest change. What used to be one `Spree::Order` living through checkout and beyond is now two models:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.236",
+  "version": "0.1.238",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",

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

@@ -1,13 +0,0 @@
----
-title: Admin API
-description: Add a ProductFaq endpoint to the Admin API — resource controller conventions, an admin serializer, and a permission catalog entry.
----
-
-Staff manage FAQs through the Admin API — the same API the dashboard, integrations and scripts use. This chapter adds the endpoint following the conventions every Spree resource follows, which is what makes the dashboard plugin in the next chapter nearly free.
-
-## What this chapter covers
-
-- The resource controller: full CRUD from one small controller declaring its model, serializer and permitted attributes
-- The admin serializer and prefixed IDs
-- Registering the resource in the permission catalog so roles and API key scopes cover it
-- Exercising the endpoint with the Admin CLI

package/dist/developer/tutorial/dashboard-plugin.md

@@ -1,14 +0,0 @@
----
-title: Dashboard Plugin
-description: Scaffold a dashboard plugin for ProductFaqs — a table, a form, and navigation, generated by the CLI and wired to the Admin API endpoint.
----
-
-With the Admin API in place, the back-office UI is a dashboard plugin: a table listing FAQs, a form to create and edit them, and a navigation entry — scaffolded by the CLI and customized from there.
-
-## What this chapter covers
-
-- Scaffolding the plugin with the CLI
-- The resource table: columns, search and pagination against the Admin API
-- The form: fields, validation errors mapped from API responses
-- Registering navigation and permissions-aware visibility
-- Running it against your development store

package/dist/developer/tutorial/model.md

@@ -1,13 +0,0 @@
----
-title: Model
-description: Generate the ProductFaq model — migration, associations, validations and store scoping — the foundation both tracks build on.
----
-
-Every feature starts with a model. This chapter generates `ProductFaq` — question, answer, position, attached to a product and scoped to the store.
-
-## What this chapter covers
-
-- Generating the model and migration from the command line
-- Store scoping — why every store-owned record belongs to a store, and what that buys you
-- The association to products, validations, and ordering
-- Running the migration and creating a record in the console