@spree/docs 0.1.239 → 0.1.241

package/dist/developer/customization/permissions.md

@@ -11,15 +11,17 @@ Every grantable capability is a flat key of the form `read_<resource>` or `write
 
 Keys are per resource, not per action. The money-adjacent areas (`payments`, `refunds`, `gift_cards`, `store_credits`) are separate resources from `orders`, so "view orders but don't refund" needs no special casing.
 
-Roles as code is plain ActiveRecord:
-
-```ruby
-# db/seeds.rb
-Spree::Role.find_or_create_by!(name: 'support')
-  .update!(permissions: %w[read_orders read_customers], description: 'Read-only support')
+Roles are data, so create them where you manage the rest of your store's data: **Settings → Staff → Roles** in the dashboard, or the Admin API when you want it scripted.
+
+```bash
+spree api post roles --data '{
+  "name": "Support",
+  "description": "Read-only support",
+  "permissions": ["read_orders", "read_customers"]
+}'
 ```
 
-A role with `mutable: false` (set from seeds or the console) renders read-only in the dashboard — for roles the application does not want store staff to edit. The `admin` role is always protected.
+A role marked immutable renders read-only in the dashboard, for roles the application does not want store staff editing. The `admin` role is always protected.
 
 ## Registering extension permissions
 
@@ -56,30 +58,13 @@ Naming another audience exposes the scope to a principal outside the store's own
 
 A key never decides *which rows* its holder reaches. That is the controller's job, through scope fetching — a seller holding `write_products` manages their own products because the seller API reads through `current_seller`, not because the key says so.
 
-## Beyond the catalog
+## What the catalog does not cover
 
-The catalog is deliberately flat: it answers "may this role touch this kind of record", and that is the whole grant vocabulary. Two rules that do *not* belong in it:
+The catalog is deliberately flat: it answers "may this role touch this kind of record", and that is the whole grant vocabulary.
 
-- **Record-state rules** ("a completed order cannot be deleted") live on models and workflows, so they bind every caller — including secret API keys, which never consult CanCanCan.
-- **Row-level restrictions** (a support agent limited to one market) are not expressible as keys. Replace the ability class outright:
+**Record-state rules** — "a completed order cannot be deleted" — belong on models and workflows, not on roles. Put them there and they bind every caller, including secret API keys, which never consult the role system at all. A rule enforced only in the permission layer is a rule the API can walk straight past.
 
-```ruby
-# config/initializers/spree.rb
-Spree::Dependencies.ability_class = 'MyApp::Ability'
-```
-
-```ruby
-# app/models/my_app/ability.rb
-class MyApp::Ability < Spree::Ability
-  def initialize(user, options = {})
-    super
-    return unless user.respond_to?(:market_id) && user.market_id
-
-    cannot :manage, Spree::Order
-    can [:read, :admin], Spree::Order, market_id: user.market_id
-  end
-end
-```
+**Row-level restrictions**, such as a support agent limited to one market, are not expressible as permission keys. Scope them where the records are read: a controller reaching through `current_store.orders` rather than `Spree::Order` already restricts by tenant, and the same technique narrows by market or seller. See [extending the API](api.md).
 
 ## How enforcement works
 

package/dist/developer/customization/validations.md

@@ -52,27 +52,6 @@ Both cart keys appear above because adding to a cart and setting a quantity are
 different flows. See [Services & Workflows](workflows.md)
 for the full hook list.
 
-## Adding a rule to a model
-
-For rules about the shape of a record, a decorator is the supported route:
-
-```ruby
-# app/models/spree/product_decorator.rb
-module MyStore
-  module ProductDecorator
-    def self.prepended(base)
-      base.validates :external_id, presence: true, uniqueness: true
-    end
-  end
-end
-
-Spree::Product.prepend(MyStore::ProductDecorator)
-```
-
-Decorators couple you to Spree internals, so prefer a hook when the rule is
-really about an operation. See
-[Decorators](decorators.md).
-
 ## Relaxing a rule Spree ships
 
 Never call `clear_validators!` — it wipes every validation on the model,
@@ -81,7 +60,8 @@ cause. Use one of these instead.
 
 ### Store preferences
 
-Some rules are already switchable, per store, from the dashboard or a console:
+Some rules are switchable per store, with no code at all. Change them in the
+dashboard under **Settings → Store**, or through the Admin API:
 
 | Preference | Effect |
 |---|---|
@@ -90,30 +70,23 @@ Some rules are already switchable, per store, from the dashboard or a console:
 | `address_requires_company` | Requires it — only meaningful with the field shown |
 | `disable_sku_validation` | Turns off SKU uniqueness |
 
-```ruby
-store.update!(preferred_address_requires_company: true)
-```
-
-### Overriding the gating predicate
 
-Most conditional validations in `Spree::Address` are gated on a predicate you
-can override, which is far safer than removing the validation:
-
-```ruby
-module MyStore
-  module AddressDecorator
-    # Business addresses only in this store.
-    def require_company?
-      !quick_checkout
-    end
-  end
-end
+```typescript Admin SDK
+await adminClient.store.update({
+  preferred_address_requires_phone: false,
+})
+```
 
-Spree::Address.prepend(MyStore::AddressDecorator)
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/store' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "preferred_address_requires_phone": false }'
 ```
 
-`require_name?`, `require_street?`, `require_postal_code?`, `require_phone?` and
-`require_company?` all work this way.
+
+> **NOTE:** All four are editable in the dashboard except `address_requires_company`, which
+>   is API-only for now.
 
 ### The address validator registry
 
@@ -121,7 +94,7 @@ Address rules are regional and business-specific, so addresses carry a registry
 of extra validator classes you can add to and remove from:
 
 ```ruby
-# config/initializers/spree.rb — or config.to_prepare for your own classes
+# server/config/initializers/spree.rb — or config.to_prepare for your own classes
 Spree.validators.addresses.register(MyStore::PostBoxValidator)
 
 # Drop a rule Spree ships

package/dist/developer/dashboard/concepts.md

@@ -30,7 +30,9 @@ The dashboard is a **Single Page Application**: one HTML page, all routing clien
 @spree/dashboard      ─ app shell: routes, resource hooks, locales, vite config
 ```
 
-[Overview](overview.md) covers the split in more detail. The short version: **`-ui`** has no providers or hooks (data comes via props); **`-core`** is the extension API and runtime services; **`-dashboard`** is the deployable app shell. Plugins and customizations consume `-core` and `-ui`, never the app shell.
+[Overview](overview.md) covers the split in more detail. The short version: **`-ui`** has no providers or hooks (data comes via props); **`-core`** is the extension API and runtime services; **`-dashboard`** is the deployable app shell.
+
+The split matters when you publish a plugin: it consumes `-core` and `-ui` and never the app shell, which it plugs into rather than ships. In your own dashboard app the distinction is noise, so `@spree/dashboard` re-exports both — one import, and you never have to work out which package a given export lives in.
 
 ## How customization plugs in
 
@@ -53,7 +55,7 @@ The facade `defineDashboardPlugin({ nav, routes, slots, … })` groups all five
 The signed-in admin's identity and abilities are exposed via three providers wrapping the app:
 
 - `<AuthProvider>` — the current admin user; `useAuth()` returns `{ user, signIn, signOut, … }`
-- `<PermissionProvider>` — CanCanCan abilities; `usePermissions()` returns `{ can, cannot }`
+- `<PermissionProvider>` — CanCanCan abilities; `usePermissions()` returns `{ permissions, rules, isLoading }`, and the checks live on `permissions.can(...)`
 - `<StoreProvider>` — current store + timezone + currency; `useStore()` returns `{ storeId, store, … }`
 
 When you write a custom page or hook, pull from these. **Never reach into local state for identity** — it changes on store switch or session refresh, and the providers wire all that for you.

package/dist/developer/dashboard/customization/backend.md

@@ -52,13 +52,16 @@ Resource methods are just `request<T>()` calls with the right path + types pre-b
 The dashboard's data layer is React-Query — every `useFoo` hook is `useQuery({ queryKey, queryFn })` over an SDK call. Follow the same pattern for your own data:
 
 ```ts
-import { adminClient } from '@spree/dashboard'
+import { adminClient, useResourceKey } from '@spree/dashboard'
 import { useQuery } from '@tanstack/react-query'
 import type { AdminBrand } from './types'
 
 export function useBrands(params?: { search?: string }) {
   return useQuery({
-    queryKey: ['brands', params],
+    // `useResourceKey` scopes the key to the current store. A bare
+    // `['brands', params]` key would serve one store's rows to another
+    // after a store switch.
+    queryKey: useResourceKey('brands', params),
     queryFn: () =>
       adminClient.request<{ data: AdminBrand[] }>('GET', '/brands', { params }),
     staleTime: 30_000,

package/dist/developer/dashboard/customization/navigation.md

@@ -26,7 +26,7 @@ nav.add({
 })
 ```
 
-`position` controls ordering — built-ins use 100–600 (Home 100, Orders 200, Products 300, Customers 400, Promotions 500, Reports 600; a conditional Getting Started entry sits at 50), leaving gaps to slot into. The default is 100. Keys must be unique, including against the built-in keys (`getting-started`, `home`, `orders`, `products`, `customers`, `promotions`, `reports`, `settings`) — duplicates throw at boot.
+`position` controls ordering — built-ins run 50–600 (Getting Started 50 when shown, Home 100, Orders 200, Products 300, Inventory 350, Customers 400, Sellers 450, Loyalty 475, Promotions 500, Reports 600), leaving gaps to slot into. The default is 100. Keys must be unique, including against the built-in keys (`getting-started`, `home`, `orders`, `products`, `inventory`, `customers`, `sellers`, `loyalty`, `promotions`, `reports`, `settings`) — duplicates throw at boot.
 
 ### Add via `defineDashboardPlugin`
 

package/dist/developer/dashboard/customization/quickstart.md

@@ -80,7 +80,7 @@ defineDashboardPlugin({
 
 Save. Click "Analytics" — your page renders inside the dashboard chrome, at `/<store id>/analytics`.
 
-> **WARNING:** Every `key` must be unique, including against the built-ins (`getting-started`, `home`, `orders`, `products`, `customers`, `promotions`, `reports`, `settings`). Registering a duplicate key throws at boot with a message naming the conflict.
+> **WARNING:** Every `key` must be unique, including against the built-ins (`getting-started`, `home`, `orders`, `products`, `inventory`, `customers`, `sellers`, `loyalty`, `promotions`, `reports`, `settings`). Registering a duplicate key throws at boot with a message naming the conflict.
 
 ## What just happened
 

package/dist/developer/dashboard/overview.md

@@ -6,7 +6,7 @@ description: Learn about the Spree React Dashboard architecture and how to custo
 
 > **INFO:** The React Dashboard is currently a **Developer Preview** — APIs may still change between releases. It is becoming the default Admin interface.
 
-The React Dashboard is a React single-page application (SPA) that talks to the [Spree Admin API](../../api-reference/admin-api.md). It can be distributed with the Spree API or as a standalone npm package, and it can be extended with plugins. The dashboard is built with modern React libraries and patterns, including:
+The React Dashboard is a React single-page application (SPA) that talks to the [Spree Admin API](../../api-reference/admin-api/introduction.md). It can be distributed with the Spree API or as a standalone npm package, and it can be extended with plugins. The dashboard is built with modern React libraries and patterns, including:
 
 | Layer | Choice |
 |---|---|
@@ -35,7 +35,7 @@ Most customization uses the registries in `@spree/dashboard-core` to add nav ent
 
 **In your own dashboard app, import from `@spree/dashboard`.** It re-exports both packages, so you never have to work out which one an export lives in. A distributed plugin is the exception: it imports `@spree/dashboard-core` and `@spree/dashboard-ui` directly, because it plugs into the shell rather than shipping it.
 
-You can also built your own dashboard using `@spree/dashboard-ui` primitives and `@spree/dashboard-core` registries, if you want to replace the default dashboard entirely. This is rare — most teams just add a few pages or cards to the existing dashboard.
+You can also build your own dashboard using `@spree/dashboard-ui` primitives and `@spree/dashboard-core` registries, if you want to replace the default dashboard entirely. This is rare — most teams just add a few pages or cards to the existing dashboard.
 
 ## Get the dashboard
 

package/dist/developer/dashboard/plugins/distributing.md

@@ -120,7 +120,7 @@ The registries are global singletons, so a key collision is the consumer's probl
 - **Namespace locale keys** — `admin.acme_brands.title` not `admin.brands.title`.
 - **Namespace API paths** — your Rails engine should mount under `/api/v3/admin/acme/...`, not `/api/v3/admin/brands` (which collides with core Brands if it ever ships).
 
-The dashboard logs a warning in dev mode when two registry entries share a key. That's the consumer's signal that two plugins are stepping on each other — and it falls back to "last-registered wins", which is rarely what either plugin wanted.
+Registering a key that already exists throws at boot, with a message naming the conflict. That is deliberate: a silently shadowed entry would leave the consumer with a plugin that half works, where a failure at startup points straight at the two plugins stepping on each other.
 
 ## Distribution channels
 

package/dist/developer/dashboard/public-api.md

@@ -4,7 +4,7 @@ sidebarTitle: Public API
 description: Every importable symbol the dashboard exposes — components, hooks, registries, providers, and the SDK client. Treat this as the surface you can safely depend on.
 ---
 
-The dashboard is structured as three packages, each with a documented public surface. **Anything not listed here is internal** — don't import it via `@spree/dashboard-core/src/internal/...`, because we'll move or rename it without a deprecation cycle.
+The dashboard is structured as three packages. This page lists the symbols we commit to keeping — **treat anything not listed as internal**, liable to move or be renamed without a deprecation cycle, even where the barrel happens to export it today. Never reach past a package entry point into `@spree/dashboard-core/src/...`.
 
 ## `@spree/dashboard-core`
 
@@ -51,7 +51,7 @@ import {
   // Page chrome
   PageHeader,
   PageTabs,
-  TopBar,
+  MobileTopBar,
   AppSidebar,
   SettingsSidebar,
   Slot,
@@ -92,6 +92,7 @@ import {
   useCustomFields,
   useDirectUpload,    // ActiveStorage direct uploads
   useExport,          // CSV export job lifecycle
+  useResourceKey,     // store-scoped query key — use it for every custom query
   useResourceMutation, // useMutation wrapper with 422 handling
   useHostForm,        // the built-in form a slot widget renders inside (throws when absent)
   useOptionalHostForm, // same, but null when the page has no host form

package/dist/developer/dashboard/recipes/attribute-end-to-end.md

@@ -14,7 +14,7 @@ It's the full version of the [custom form field recipe](custom-form-field.md)
 
 ## First: should this be a custom field instead?
 
-**Default to a [custom field definition](custom-form-field.md#path-a-custom-field-definition--no-code).** It needs zero code — declare the field, and the product form renders and saves it. That covers most plugin data and everything merchants define themselves.
+**Default to a [custom field definition](custom-form-field.md#path-a-custom-field-definition-no-code).** It needs zero code — declare the field, and the product form renders and saves it. That covers most plugin data and everything merchants define themselves.
 
 Graduate to a real database column only when the attribute needs **list operations or database guarantees**:
 
@@ -90,7 +90,7 @@ Add a Rails validation while you're here (`validates :lead_time_days, numericali
 ```tsx
 // src/plugins.ts (or a plugin's entry module)
 import { defineDashboardPlugin, i18n } from '@spree/dashboard'
-import { LeadTimeCard } from './fields/lead-time-card'
+import { LeadTimeCard } from './slots/lead-time-card'
 
 i18n.addResourceBundle('en', 'translation', en, true, true)
 
@@ -123,7 +123,7 @@ defineDashboardPlugin({
 The form widget binds to the host form — no `<form>` of its own, no save button:
 
 ```tsx
-// src/fields/lead-time-card.tsx
+// src/slots/lead-time-card.tsx
 import { Card, CardContent, CardHeader, CardTitle, Field, FieldError, FieldLabel, Input, useHostForm } from '@spree/dashboard'
 import { useTranslation } from 'react-i18next'
 

package/dist/developer/dashboard/recipes/custom-form-field.md

@@ -93,7 +93,7 @@ defineDashboardPlugin({
 The `product.form_sidebar` slot renders inside the product form. Bind your input to the host form with `useHostForm()` — no `<form>` of your own, no save button:
 
 ```tsx
-// src/fields/tech-specs-card.tsx
+// src/slots/tech-specs-card.tsx
 import {
   Card,
   CardContent,

package/dist/developer/dashboard/recipes/page-action-button.md

@@ -21,7 +21,7 @@ import { Button, adminClient, usePermissions, useResourceMutation } from '@spree
 import { Send } from 'lucide-react'
 
 interface Props {
-  resource: { id: string; state: string }  // Order
+  resource: { id: string; status: string }  // Order
 }
 
 export function SendInvoiceButton({ resource }: Props) {
@@ -34,7 +34,7 @@ export function SendInvoiceButton({ resource }: Props) {
 
   // Only show to users who can act, and only on completed orders.
   if (!permissions.can('update', 'Spree::Order')) return null
-  if (resource.state !== 'complete') return null
+  if (resource.status !== 'placed') return null
 
   return (
     <Button

package/dist/developer/dashboard/recipes/sidebar-widget.md

@@ -11,7 +11,7 @@ This recipe builds a "Loyalty status" card for the customer detail page: read-on
 ## The component
 
 ```tsx
-// src/widgets/loyalty-status-card.tsx
+// src/slots/loyalty-status-card.tsx
 import { useQuery } from '@tanstack/react-query'
 import {
   adminClient,
@@ -101,7 +101,7 @@ Worth noting:
 ```ts
 // src/plugins.ts (in your dashboard app)
 import { defineDashboardPlugin } from '@spree/dashboard'
-import { LoyaltyStatusCard } from './widgets/loyalty-status-card'
+import { LoyaltyStatusCard } from './slots/loyalty-status-card'
 
 defineDashboardPlugin({
   slots: {

package/dist/developer/dashboard/slots-catalog.md

@@ -89,6 +89,66 @@ The resource detail pages each render a slot below their built-in cards. The con
 | Context | `{ customer }` — the full `Customer` record |
 | Host form | No — the page edits through sheets; widgets save via their own API calls |
 
+### `collection.form_sidebar`
+
+| Where | Collection detail page (`products/collections/$collectionId`), end of the sidebar column |
+|---|---|
+| Use | Collection-scoped cards — merchandising rules, feed settings, external sync state |
+| Context | `{ collection }` — the `Collection` record |
+| Host form | **Yes** — form key `collection` |
+
+### `company.form_main`
+
+| Where | Company detail page, end of the main column |
+|---|---|
+| Use | B2B account cards — credit terms, approval settings, external account references |
+| Context | `{ company, kind, canEdit }` — `kind` is the company's own `kind`, `canEdit` whether the viewer may write |
+| Host form | No — the widget owns its persistence |
+
+### `company.form_sidebar`
+
+| Where | Company detail page, end of the sidebar column |
+|---|---|
+| Use | Narrow company-scoped cards alongside the main form |
+| Context | `{ company, kind, canEdit }` |
+| Host form | No |
+
+## Seller panel slots
+
+Rendered by the marketplace seller panel (`@spree/seller-dashboard`) rather than the admin dashboard, and registered the same way.
+
+### `seller.form_main`
+
+| Where | Seller detail page, end of the main column |
+|---|---|
+| Use | Seller-scoped cards — payout configuration, onboarding state, compliance records |
+| Context | `{ seller, canEdit }` |
+| Host form | No |
+
+### `seller.form_sidebar`
+
+| Where | Seller detail page, end of the sidebar column |
+|---|---|
+| Use | Narrow seller-scoped cards |
+| Context | `{ seller, canEdit }` |
+| Host form | No |
+
+### `seller.team.actions`
+
+| Where | Seller team screen, in the header's action area |
+|---|---|
+| Use | Team-level actions — bulk invite, export, an external directory sync |
+| Context | `{ sellerId }` |
+| Host form | No |
+
+### `seller.team.after`
+
+| Where | Seller team screen, below the member list |
+|---|---|
+| Use | Anything that belongs under the team — audit log, role explainer, seat usage |
+| Context | `{ sellerId }` |
+| Host form | No |
+
 ## Page tabs slot
 
 ### `page.tabs` (default)

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

@@ -6,35 +6,39 @@ description: "Install Spree Commerce locally, run your first store, and deploy i
 
 ## Using `create-spree-app`
 
-  The quickest way to get started. Scaffolds a full Spree project with Next.js Storefront (optional).
+  The quickest way to get started. Scaffolds a full Spree project with React admin dashboard and Next.js Storefront (optional).
 
-  **Requirements:** [Node.js](https://nodejs.org/) 20+ and [Docker](https://docs.docker.com/get-docker/) running.
+  **Requirements:** [Node.js](https://nodejs.org/) 24+ and [Docker](https://docs.docker.com/get-docker/) running.
 
   ```bash
   npx create-spree-app@latest my-store
   ```
 
-  The CLI walks you through an interactive setup:
+  The CLI walks you through an interactive setup where you choose the project name and whether to include the Next.js Storefront. It then builds a Docker stack with Postgres, and Spree API.
 
-  1. Choose **Full-stack** (Backend + Next.js Storefront) or **Backend only**
-  2. Optionally load **sample data** (products, categories, images)
+  Once complete it will open a browser window so you can finalize the store setup (pick name, currency, your email/password).
 
-  Once complete, your store should be running at [http://localhost:3000/admin](http://localhost:3000/admin). The port can be different if `3000` is already used on your system.
+  <video autoPlay muted loop playsInline controls className="block w-auto max-w-full h-auto rounded-xl" src="/videos/store-setup.mp4"></video>
 
-  See the full [create-spree-app documentation](../create-spree-app/quickstart.md) for all CLI flags and options.
+## Project structure and overview
 
-## Accessing Admin Panel
+`create-spree-app` creates a project folder like this:
 
-Navigate to [http://localhost:3000/admin](http://localhost:3000/admin) and log in with the default credentials:
-
-| | |
-|---|---|
-| **Email** | `spree@example.com` |
-| **Password** | `spree123` |
-
-Upon successful authentication, you should see the admin screen:
-
-<img src="/images/spree_admin_dashboard.png" />
+```
+my-store/
+├── server/                 # The Spree API
+├── apps/
+│   ├── dashboard/          # Admin dashboard (Vite/React)
+│   ├── seller-dashboard/   # Seller panel, for marketplaces (Vite/React)
+│   └── storefront/         # Next.js storefront (if selected)
+├── .env                    # Ports, secrets and service URLs
+├── .spree/                 # CLI credentials — gitignored, created on first run
+├── docker-compose.yml      # The local stack
+├── package.json            # Scripts and the pinned @spree/cli
+├── AGENTS.md               # Instructions for coding agents
+├── CLAUDE.md               # Project layout and conventions
+└── README.md               # How to run everything
+```
 
 ## Using the Spree CLI
 
@@ -58,18 +62,15 @@ See the [Spree CLI guide](../cli/quickstart.md) for all commands and the [Admin
 
 ## Next Steps
 
+- [How Spree fits together](../core-concepts/architecture.md) — The catalog, the cart, the order and fulfillment — what each one is for, and the two APIs you build against. Twenty minutes here saves a lot of guessing later, and it ends by pointing you at whichever path suits you.
 
-  - [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.
-
+In a hurry? Jump straight to the [tutorial](../tutorial/introduction.md) to build a feature end to end, the [Next.js Storefront](../storefront/nextjs/quickstart.md) to put a storefront in front of it, or the [API reference](../../api-reference/admin-api/introduction.md) to see what you can do with the Admin API.
 
 > **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!
+Congrats! You've set up your Spree application and it's looking amazing!
 
 Give Spree a [GitHub Star](https://github.com/spree/spree), why don't ya? Thank you for supporting Spree open-source! 
 

package/dist/developer/how-to/custom-promotion.md

@@ -150,7 +150,7 @@ module Spree
         private
 
         def matches_brand?(line_item)
-          brand = line_item.product.get_metafield('details.brand')&.value
+          brand = line_item.product.get_custom_field('details.brand')&.value
           preferred_brand_names.include?(brand)
         end
       end

package/dist/developer/how-to/custom-search-provider.md

@@ -224,9 +224,9 @@ Background jobs (`IndexJob`, `RemoveJob`) fire on `after_commit` when `indexing_
 
 Always use prefixed IDs (`ctg_abc`, `prod_xyz`, `optval_abc`) when indexing. Never use raw database IDs — Spree supports UUID primary keys.
 
-### Metafield search schema
+### Custom Field search schema
 
-Product metafields marked `searchable` / `sortable` on `MetafieldDefinition` are projected through `Spree::SearchProvider::MetafieldSchema` — shared by providers and `ProductPresenter`. Toggle participation with definition flags; run `rake spree:search:reindex` after changes when using Meilisearch.
+Product custom fields marked `searchable` / `sortable` on `CustomFieldDefinition` are projected through `Spree::SearchProvider::CustomFieldSchema` — shared by providers and `ProductPresenter`. Toggle participation with definition flags; run `rake spree:search:reindex` after changes when using Meilisearch.
 
 Document shaping for `cf_*` fields stays on `search_product_presenter` — the only search-related dependency.
 

package/dist/developer/how-to/custom-stock-splitter.md

@@ -170,12 +170,12 @@ end
 
 ### Step 4 (optional): Add a Variant-side Predicate
 
-The example above relies on `variant.refrigerated?`. In a real plugin you'd back that with a [Custom Field](../core-concepts/metafields.md) on `Spree::Variant` — say a boolean metafield with key `refrigerated` — and define the predicate as a thin reader:
+The example above relies on `variant.refrigerated?`. In a real plugin you'd back that with a [Custom Field](../core-concepts/metafields.md) on `Spree::Variant` — say a boolean custom field with key `refrigerated` — and define the predicate as a thin reader:
 
 ```ruby app/models/spree/variant_decorator.rb
 Spree::Variant.class_eval do
   def refrigerated?
-    metafields.find_by(namespace: 'logistics', key: 'refrigerated')&.value == 'true'
+    custom_fields.find_by(namespace: 'logistics', key: 'refrigerated')&.value == 'true'
   end
 end
 ```

package/dist/developer/sdk/admin/extending.md

@@ -66,5 +66,5 @@ The SDK transforms `filter`/`sort` into the Ransack-flavored query string the Ad
 ## See also
 
 - The [Store SDK extending guide](../extending.md) covers the same pattern for storefront endpoints — the API is identical, only the base path (`/api/v3/store`) and auth header differ.
-- The [API](../../tutorial/admin-api.md) and [SDK](../../tutorial/storefront.md) tutorials walk through creating new Spree endpoints end-to-end (Rails controller, serializer, TypeScript types). Everything they show for the Store API applies equivalently for the Admin API.
+- The [API](../../tutorial/model-and-api.md) and [SDK](../../tutorial/storefront.md) tutorials walk through creating new Spree endpoints end-to-end (Rails controller, serializer, TypeScript types). Everything they show for the Store API applies equivalently for the Admin API.
 - For building dashboard UI on top of your custom endpoint, see the [Dashboard](../../dashboard/overview.md) section — start with [Customization Quickstart](../../dashboard/customization/quickstart.md) for in-app changes or [Plugin Overview](../../dashboard/plugins/overview.md) for redistributable packages.

package/dist/developer/sdk/admin/quickstart.md

@@ -66,4 +66,4 @@ const page: PaginatedResponse<Order> = await client.orders.list()
   - [Admin API Reference](../../../api-reference/admin-api/introduction.md) — The underlying REST API the SDK wraps — every endpoint, parameter, and response shape.
 
 
-> **TIP:** Adding your own resources? The [`spree generate api_resource`](../../tutorial/admin-api.md) generator scaffolds Admin API endpoints (model, serializers, controllers, specs) in one command, and the [extending guide](../extending.md) shows how to call custom endpoints from the SDK.
+> **TIP:** Adding your own resources? The [`spree generate api_resource`](../../tutorial/model-and-api.md) generator scaffolds Admin API endpoints (model, serializers, controllers, specs) in one command, and the [extending guide](../extending.md) shows how to call custom endpoints from the SDK.

package/dist/developer/sdk/admin/resources.md

@@ -127,4 +127,4 @@ await client.customFields('Spree::Product', 'prod_xxx').list()
 
 ## Adding your own resources
 
-The resource map grows with your store. The [`spree generate api_resource`](../../tutorial/admin-api.md) generator scaffolds new Admin API endpoints (model, serializers, controllers, routes, specs) in one command — then call them from the SDK with a [custom fetch or raw request](../extending.md), or generate a typed client for them.
+The resource map grows with your store. The [`spree generate api_resource`](../../tutorial/model-and-api.md) generator scaffolds new Admin API endpoints (model, serializers, controllers, routes, specs) in one command — then call them from the SDK with a [custom fetch or raw request](../extending.md), or generate a typed client for them.

package/dist/developer/sdk/configuration.md

@@ -162,7 +162,7 @@ All types are exported as unprefixed names (e.g., `Product`, `Order`). Legacy `S
 - `OptionType` - Option type (e.g., Size, Color)
 - `OptionValue` - Option value (e.g., Small, Red)
 - `DigitalLink` - Digital download link
-- `Metafield` - Custom metafield data
+- `CustomField` - Custom field data
 
 ### Wishlist Types
 - `Wishlist` - Wishlist

package/dist/developer/sdk/extending.md

@@ -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 [API](../tutorial/admin-api.md) and [SDK](../tutorial/storefront.md) tutorials.
+For a complete walkthrough — creating the API endpoints on the backend, defining TypeScript types, filtering, and expanding associations — see the [API](../tutorial/model-and-api.md) and [SDK](../tutorial/storefront.md) tutorials.