@spree/docs 0.1.121 → 0.1.123

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

@@ -0,0 +1,189 @@
+---
+title: Add a page action button
+sidebarTitle: Page action button
+description: Add a primary action (e.g., "Send invoice", "Sync to ERP") to a built-in detail page's header — both as a top-right button and as a dropdown item.
+---
+
+Built-in detail pages render `<PageHeader>` at the top with primary action buttons on the right and a more-actions (`⋯`) dropdown next to them. Both are slot-based — you can inject your own buttons or menu items without touching the host page.
+
+Two slots cover the surface:
+
+- `page.actions` — the right-aligned action zone (buttons, badges)
+- `page.actions_dropdown` — the dropdown menu
+
+This recipe shows both — and how to gate them by permission + resource state. (Strings are hardcoded for brevity; real buttons should go through i18n — see [Translations](../customization/translations.md).)
+
+## A button in the actions row
+
+```tsx
+// src/actions/send-invoice-button.tsx
+import { adminClient, usePermissions, useResourceMutation } from '@spree/dashboard-core'
+import { Button } from '@spree/dashboard-ui'
+import { Send } from 'lucide-react'
+
+interface Props {
+  resource: { id: string; state: string }  // Order
+}
+
+export function SendInvoiceButton({ resource }: Props) {
+  const { permissions } = usePermissions()
+  const mutation = useResourceMutation({
+    mutationFn: () =>
+      adminClient.request('POST', `/orders/${resource.id}/send_invoice`),
+    successMessage: 'Invoice sent',
+  })
+
+  // 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
+
+  return (
+    <Button
+      variant="outline"
+      size="sm"
+      onClick={() => mutation.mutate()}
+      disabled={mutation.isPending}
+    >
+      <Send className="size-4" />
+      Send invoice
+    </Button>
+  )
+}
+```
+
+Register it:
+
+```ts
+// src/plugins.ts (in your dashboard app)
+import { defineDashboardPlugin } from '@spree/dashboard-core'
+import { SendInvoiceButton } from './actions/send-invoice-button'
+
+defineDashboardPlugin({
+  slots: {
+    'page.actions': [{
+      id: 'send-invoice',
+      component: SendInvoiceButton as never,
+      position: 50,
+    }],
+  },
+})
+```
+
+Two layers of gating, both inside the component:
+
+1. **Permission check** — `usePermissions()`; render `null` when the user can't act.
+2. **Resource-state check** — the user *can* send invoices, but this specific order isn't ready yet.
+
+(The slot entry's `if` predicate receives only the slot's own context — `{ resource }` here — so use it for resource-state conditions, and keep permission checks in the component. See [Slots](../customization/slots.md).)
+
+## A dropdown menu item
+
+For secondary actions, use `page.actions_dropdown` and render `<DropdownMenuItem>`:
+
+```tsx
+// src/actions/sync-to-erp-item.tsx
+import { adminClient, usePermissions, useResourceMutation } from '@spree/dashboard-core'
+import { DropdownMenuItem } from '@spree/dashboard-ui'
+import { RefreshCw } from 'lucide-react'
+
+interface Props {
+  resource: { id: string }
+}
+
+export function SyncToErpItem({ resource }: Props) {
+  const { permissions } = usePermissions()
+  const mutation = useResourceMutation({
+    mutationFn: () => adminClient.request('POST', `/orders/${resource.id}/sync_to_erp`),
+    successMessage: 'Synced',
+  })
+
+  if (!permissions.can('manage', 'Spree::Order')) return null
+
+  return (
+    <DropdownMenuItem
+      onSelect={(event) => {
+        event.preventDefault()
+        mutation.mutate()
+      }}
+      disabled={mutation.isPending}
+    >
+      <RefreshCw className="size-4" />
+      Sync to ERP
+    </DropdownMenuItem>
+  )
+}
+```
+
+```ts
+defineDashboardPlugin({
+  slots: {
+    'page.actions_dropdown': [{
+      id: 'sync-to-erp',
+      component: SyncToErpItem as never,
+      position: 50,
+    }],
+  },
+})
+```
+
+The `event.preventDefault()` keeps the dropdown open if the mutation fails — without it, the menu closes on click and the toast appears with no context.
+
+## Confirm before acting
+
+For destructive or expensive actions, wrap the click in a `<Dialog>`:
+
+```tsx
+import { useState } from 'react'
+import {
+  Dialog, DialogContent, DialogHeader, DialogTitle, DialogFooter,
+  DropdownMenuItem, Button,
+} from '@spree/dashboard-ui'
+
+export function ResetCartItem({ resource }: { resource: { id: string } }) {
+  const [open, setOpen] = useState(false)
+  const mutation = useResourceMutation({
+    mutationFn: () => adminClient.request('POST', `/orders/${resource.id}/reset_cart`),
+    successMessage: 'Cart reset',
+    onSuccess: () => setOpen(false),
+  })
+
+  return (
+    <>
+      <DropdownMenuItem
+        onSelect={(event) => {
+          event.preventDefault()
+          setOpen(true)
+        }}
+      >
+        Reset cart
+      </DropdownMenuItem>
+      <Dialog open={open} onOpenChange={setOpen}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Reset this cart?</DialogTitle>
+          </DialogHeader>
+          <p>All line items will be cleared. This cannot be undone.</p>
+          <DialogFooter>
+            <Button variant="ghost" onClick={() => setOpen(false)}>Cancel</Button>
+            <Button variant="destructive" onClick={() => mutation.mutate()}>
+              Reset
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </>
+  )
+}
+```
+
+## Context
+
+The `resource` prop is whatever the host page passed to `<PageHeader resource={…} />`. On the order detail page it's an `Order`; on a product page it's a `Product`. The slot doesn't statically know which — see [Slots](../customization/slots.md) for the typing escape hatches.
+
+For the current store, user, or permissions, call the hooks inside your component — `useStore()`, `useAuth()`, `usePermissions()` from `@spree/dashboard-core`.
+
+## Reference
+
+- [`page.actions` / `page.actions_dropdown`](../slots-catalog.md#page-header-slots) in the slots catalog
+- [`useResourceMutation`](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/hooks/use-resource-mutation.ts) — 422-aware mutation hook
+- [Slots](../customization/slots.md) — registry primer

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

@@ -0,0 +1,147 @@
+---
+title: Add a sidebar widget
+sidebarTitle: Sidebar widget
+description: Add an info card to a built-in detail page's sidebar — pulling its own data, gated by permissions, with loading and empty states.
+---
+
+The product, order, and customer detail pages each render a `<Slot>` in their right-hand sidebar — typically named `<resource>.form_sidebar`. Widgets rendered into these slots see the current record and can fetch their own data without disturbing the host page.
+
+This recipe builds a "Loyalty status" card for the customer detail page: read-only, fetches the customer's points + tier, shows a spinner while loading, an empty state when there's no data, and hides itself for staff without the right permission.
+
+## The component
+
+```tsx
+// src/widgets/loyalty-status-card.tsx
+import { useQuery } from '@tanstack/react-query'
+import { adminClient, usePermissions, useStore } from '@spree/dashboard-core'
+import {
+  Badge,
+  Card, CardContent, CardHeader, CardTitle,
+  Empty, EmptyDescription,
+  Skeleton,
+} from '@spree/dashboard-ui'
+import { Trophy } from 'lucide-react'
+
+interface LoyaltyRecord {
+  customer_id: string
+  points: number
+  tier: 'bronze' | 'silver' | 'gold'
+}
+
+interface Props {
+  // The customer detail page's slot context — see the slots catalog.
+  customer: { id: string }
+}
+
+export function LoyaltyStatusCard({ customer }: Props) {
+  const { storeId } = useStore()
+  const { permissions } = usePermissions()
+  const canRead = permissions.can('read', 'MyApp::LoyaltyRecord')
+  const { data, isLoading } = useQuery({
+    queryKey: ['loyalty', storeId, customer.id],
+    queryFn: () =>
+      adminClient.request<{ data: LoyaltyRecord | null }>(
+        'GET',
+        `/customers/${customer.id}/loyalty`,
+      ),
+    staleTime: 30_000,
+    enabled: canRead,
+  })
+
+  // Hide entirely for staff without the permission — same behavior as
+  // core's permission-gated cards.
+  if (!canRead) return null
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle className="flex items-center gap-2">
+          <Trophy className="size-4" />
+          Loyalty status
+        </CardTitle>
+      </CardHeader>
+      <CardContent>
+        {isLoading ? (
+          <Skeleton className="h-8 w-32" />
+        ) : !data?.data ? (
+          <Empty>
+            <EmptyDescription>No loyalty record</EmptyDescription>
+          </Empty>
+        ) : (
+          <div className="space-y-2">
+            <Badge variant={tierVariant(data.data.tier)}>{data.data.tier}</Badge>
+            <p className="text-sm text-muted-foreground">{data.data.points} points</p>
+          </div>
+        )}
+      </CardContent>
+    </Card>
+  )
+}
+
+function tierVariant(tier: LoyaltyRecord['tier']) {
+  return tier === 'gold' ? 'default' : 'secondary'
+}
+```
+
+Worth noting:
+
+- **`storeId` in the query key.** The dashboard is multi-store; without this, switching stores leaves stale data on screen.
+- **`staleTime: 30_000`** keeps the data fresh enough for a sidebar widget without re-fetching on every focus event.
+- **Three states.** Loading (`<Skeleton>`), empty (`<Empty>`), and loaded. Skipping the empty state ships a card that says "0 points" when really the customer has never been enrolled — different meaning, different UX.
+- **Strings are hardcoded for brevity.** Real widgets should go through i18n — see [Translations](../customization/translations.md).
+
+## Register the widget
+
+```ts
+// src/plugins.ts (in your dashboard app)
+import { defineDashboardPlugin } from '@spree/dashboard-core'
+import { LoyaltyStatusCard } from './widgets/loyalty-status-card'
+
+defineDashboardPlugin({
+  slots: {
+    'customer.form_sidebar': [{
+      id: 'loyalty-status',
+      component: LoyaltyStatusCard as never,
+      position: 50,
+    }],
+  },
+})
+```
+
+The permission gate lives *inside* the component (`usePermissions`) rather than in an `if` predicate on the entry — the predicate only receives the slot context today, not ambient permissions (see the [slots catalog](../slots-catalog.md#ambient-context)).
+
+`position: 50` puts the card near the top of the sidebar (built-in cards typically use 100/200/300). Pick a number based on whether your widget is more or less important than the others — for a "status" card, near the top is right.
+
+## When to fetch in the widget vs. read from the host
+
+The pattern above fetches its own data. The alternative is to read it from the resource the host passes:
+
+```tsx
+function MyCard({ customer }: { customer: Customer }) {
+  return <div>{customer.loyalty_points}</div>  // host already loaded it
+}
+```
+
+Choose based on **whether the data is hot path for the rest of the page**:
+
+| Data | Approach |
+|---|---|
+| Already on the host's serializer (e.g., `customer.tags`) | Read from the slot context — no extra HTTP |
+| Conditional, expensive, or owned by your plugin | Fetch in the widget |
+| Sometimes-needed (e.g., gated by feature flag) | Fetch in the widget |
+
+A widget that always fetches is wasteful when the host already has the data. A widget that reads from the host but the host doesn't serialize is broken. Match the pattern to the source of truth.
+
+## Loading states for the host page
+
+The built-in detail pages render their sidebar only after the record has loaded, so the context record is always set when your widget mounts. If you register into a slot where that's not guaranteed (check the slots catalog entry), guard defensively:
+
+```tsx
+if (!customer) return null  // or a <Skeleton> to reserve layout space
+```
+
+## Reference
+
+- [Slots catalog → form sidebars](../slots-catalog.md) — every page-level sidebar slot
+- [`useQuery`](https://tanstack.com/query/v5/docs/framework/react/reference/useQuery) — query key conventions
+- [`@spree/dashboard` README](https://github.com/spree/spree/blob/main/packages/dashboard/README.md) — the multi-store model and why `storeId` belongs in the key

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

@@ -0,0 +1,173 @@
+---
+title: Slots catalog
+sidebarTitle: Slots catalog
+description: Every named slot the dashboard renders today. Each entry lists the host page, the slot name, and the context the slot's components receive.
+---
+
+This is the canonical list of slots the dashboard currently exposes. The source of truth is the `<Slot name="…">` call sites in the dashboard source (linked under Reference below); each entry here records the host page, the slot name, and the context your component receives.
+
+If you need a new injection point in a built-in page, open a PR adding `<Slot name="..." context={...} />` and a documentation entry here — that's the contract for new slots.
+
+## Ambient context
+
+Ambient context (`permissions`, `store`, `user` merged into every slot's props) is planned but **not wired up yet** — today slot components receive only the slot-specific context listed below. Until it lands, read those values with the hooks instead:
+
+```tsx
+import { usePermissions, useStore } from '@spree/dashboard-core'
+
+function MyWidget({ product }: { product: Product }) {
+  const { permissions } = usePermissions()
+  const { store } = useStore()
+  if (!permissions.can('read', 'MyApp::LoyaltyRecord')) return null
+  // ...
+}
+```
+
+The same applies to an entry's `if` predicate: it receives the slot context, but not `permissions` — gate inside the component for now.
+
+## Page header slots
+
+Rendered by `<PageHeader>` (`@spree/dashboard-core/components/page-header.tsx`) at the top of every detail and list page that uses the shared chrome.
+
+### `page.actions`
+
+| Where | Top-right of `<PageHeader>`, left of any explicit `actions` prop |
+|---|---|
+| Use | Add primary action buttons (e.g., a "Refund" button on the order detail page) |
+| Context | `{ resource, ...slotContext }` — `resource` is the current page's primary record, when the host passed one to `<PageHeader resource={...} />`. May be `undefined` on list pages. |
+
+### `page.actions_dropdown`
+
+| Where | Inside the more-actions (`⋯`) dropdown menu, above the auto-rendered Copy ID / Delete items |
+|---|---|
+| Use | Add menu items (`<DropdownMenuItem>`) for secondary actions |
+| Context | `{ resource, ...slotContext }` — same as `page.actions` |
+
+## Detail-page form slots
+
+The resource detail pages each render a slot below their built-in cards. The context key matches the resource name.
+
+**Host form:** on pages marked *host form: yes*, the slot renders inside the page's own `<form>` and the form context is exposed — widgets can bind inputs via [`useHostForm()`](recipes/custom-form-field.md) that hydrate, dirty-track, and save with the page's Save button. On pages without one, widgets own their persistence (use `useOptionalHostForm()` to adapt).
+
+### `product.form_sidebar`
+
+| Where | Product detail page (`products/$productId`), end of the sidebar column |
+|---|---|
+| Use | Add a card scoped to the product being edited (e.g., a "Brand" picker, wishlist stats, sync status from an external system) |
+| Context | `{ product }` — the full `Product` record from the Admin API |
+| Host form | **Yes** — form key `product` |
+
+### `category.form_sidebar`
+
+| Where | Category detail page (`products/categories/$categoryId`), end of the sidebar column |
+|---|---|
+| Use | Category-scoped cards — merchandising rules, feed settings, external sync state |
+| Context | `{ category }` — the `Category` record (may be briefly `undefined` while refetching) |
+| Host form | **Yes** — form key `category` |
+
+### `store.form_main`
+
+| Where | Store settings page (`settings/store`), end of the main column |
+|---|---|
+| Use | Store-level settings a plugin owns — integration toggles, account linking |
+| Context | `{ store }` — the full `Store` record |
+| Host form | **Yes** — form key `store` |
+
+### `order.form_sidebar`
+
+| Where | Order detail page (`orders/$orderId`), end of the sidebar column |
+|---|---|
+| Use | Fraud-check status, shipping-integration state, loyalty points earned |
+| Context | `{ order }` — the full `Order` record |
+| Host form | No — widgets save via their own API calls |
+
+### `customer.form_sidebar`
+
+| Where | Customer detail page (`customers/$customerId`), end of the sidebar column |
+|---|---|
+| Use | Loyalty status, support-ticket summary, external CRM links |
+| Context | `{ customer }` — the full `Customer` record |
+| Host form | No — the page edits through sheets; widgets save via their own API calls |
+
+## Page tabs slot
+
+### `page.tabs` (default)
+
+Rendered by `<PageTabs>` at the right edge of any tabbed sub-nav.
+
+| Where | After the built-in tab strip |
+|---|---|
+| Use | Append your own tab(s) to a sub-route — typically for plugin-owned views inside an existing resource (e.g., "Returns" tab on the order detail) |
+| Context | `{ tabs, ...slotContext }` — `tabs` is the array of built-in tabs (so you can inspect or filter by them) |
+
+Some pages override `slotName` to scope tabs to a single resource (e.g., `slotName="order.tabs"`). The catalog will grow these as we wire them up; today only the default `page.tabs` name is in production use.
+
+## Payment method editor slots (dynamic)
+
+Used by `<PaymentMethodForm>` to let payment-provider plugins replace pieces of the editor sheet. The slot names are computed per provider type (`stripe`, `bogus`, …), so registering against the right name is what hooks your editor in.
+
+### `payment_method.guide.<providerType>`
+
+| Where | Above the preferences form |
+|---|---|
+| Use | Banner explaining what the integration does, what credentials to use, links to provider docs |
+| Context | `PaymentMethodEditorContext` (see below) |
+
+### `payment_method.form.<providerType>`
+
+| Where | In place of the auto-generated preferences form |
+|---|---|
+| Use | Render a custom React form when the provider's preferences are too complex for the generated UI (multi-step OAuth, environment switchers, …) |
+| Context | `PaymentMethodEditorContext` |
+
+### `payment_method.actions.<providerType>`
+
+| Where | Sheet footer, before Save/Cancel |
+|---|---|
+| Use | Provider-specific action buttons — "Test connection", "Rotate keys", "Open dashboard in provider" |
+| Context | `PaymentMethodEditorContext` |
+
+### `PaymentMethodEditorContext`
+
+```ts
+interface PaymentMethodEditorContext {
+  mode: 'create' | 'edit'
+  type: string                                    // STI shorthand (`stripe`, `bogus`, …)
+  paymentMethod: PaymentMethod | null             // null in create mode
+  preferenceSchema: PreferenceField[]
+  preferences: Record<string, unknown>
+  onPreferencesChange: (next: Record<string, unknown>) => void
+  form: UseFormReturn<PaymentMethodFormValues>    // RHF instance for top-level fields
+}
+```
+
+Helpers for building the slot name:
+
+```ts
+import {
+  paymentMethodGuideSlot,
+  paymentMethodFormSlot,
+  paymentMethodActionsSlot,
+} from '@spree/dashboard/components/spree/payment-method-editors/types'
+
+paymentMethodFormSlot('stripe')  // → "payment_method.form.stripe"
+```
+
+Use these instead of constructing the string yourself, so a rename in one place doesn't silently break your registration.
+
+## Adding a new slot
+
+If a built-in page should expose a new injection point:
+
+1. Pick a name (`<resource>.<area>`, e.g., `order.timeline`)
+2. Add `<Slot name="..." context={{ resource: order, /* ... */ }} />` at the call site
+3. Document the slot here — host, intent, context shape
+4. Open the PR
+
+The slot is not "live" until the docs land — without an entry here, no plugin author knows it exists.
+
+## Reference
+
+- [`<Slot>` source](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/components/slot.tsx)
+- [`slot-registry`](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/lib/slot-registry.ts) — `registerSlot`, `removeSlot`, `updateSlot`, `useSlotEntries`
+- [Slots customization page](customization/slots.md) — how to register against a slot

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

@@ -0,0 +1,70 @@
+---
+title: Custom Admin Endpoints
+sidebarTitle: Custom Endpoints
+description: Call custom Admin API endpoints using the SDK's built-in request method
+---
+
+The Admin SDK client exposes a `request` method — the same function that powers `client.products.list()`, `client.orders.get()`, and every other built-in resource. Use it to call any Admin API endpoint, including ones added by an extension gem that doesn't ship its own client.
+
+```typescript
+import { createAdminClient } from '@spree/admin-sdk'
+import type { PaginatedResponse } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+  baseUrl: 'https://api.mystore.com',
+  token: 'sk_YOUR_SECRET_KEY', // or a JWT from /auth/login
+})
+
+interface Brand {
+  id: string
+  name: string
+  slug: string | null
+  description: string | null
+  logo_url: string | null
+}
+
+// Paths are relative to /api/v3/admin
+const brands = await client.request<PaginatedResponse<Brand>>('GET', '/brands')
+const brand = await client.request<Brand>('GET', '/brands/brand_2X9aQf7kEw')
+```
+
+`client.request` uses the same auth headers (secret API key *or* JWT, whichever was configured at client creation), retry logic, and base URL as every other resource on the client. The 401 → refresh → retry handshake that's wired up for the dashboard's user session applies to your custom endpoint too.
+
+## Mutations
+
+POST/PATCH/DELETE work the same way — pass `{ body }` for the request payload:
+
+```typescript
+const created = await client.request<Brand>('POST', '/brands', {
+  body: { name: 'Acme', slug: 'acme', description: 'Quality goods since 1953' },
+})
+
+const updated = await client.request<Brand>('PATCH', `/brands/${created.id}`, {
+  body: { description: 'New tagline' },
+})
+
+await client.request<void>('DELETE', `/brands/${created.id}`)
+```
+
+## Ransack filters and pagination
+
+Standard list params work — pass them as the third argument's `params`:
+
+```typescript
+const result = await client.request<PaginatedResponse<Brand>>('GET', '/brands', {
+  params: {
+    page: 2,
+    limit: 25,
+    filter: { name_cont: 'nike' },
+    sort: '-created_at',
+  },
+})
+```
+
+The SDK transforms `filter`/`sort` into the Ransack-flavored query string the Admin API expects (`q[name_cont]=nike&q[s]=created_at%20desc`) automatically — same behavior as `client.products.list({ filter: ... })`.
+
+## 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/api.md) and [SDK](../../tutorial/sdk.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

@@ -47,12 +47,12 @@ const product = await client.products.create({
 })
 ```
 
-Every method is fully typed — responses use `Admin`-prefixed types generated from the API serializers:
+Every method is fully typed — responses use types generated from the API serializers:
 
 ```typescript
-import type { AdminOrder, PaginatedResponse } from '@spree/admin-sdk'
+import type { Order, PaginatedResponse } from '@spree/admin-sdk'
 
-const page: PaginatedResponse<AdminOrder> = await client.orders.list()
+const page: PaginatedResponse<Order> = await client.orders.list()
 ```
 
 > **NOTE:** Secret keys grant back-office access — never ship them in browser code. For browser-based admin apps, use [JWT cookie authentication](authentication.md#jwt--cookie-authentication-browser-apps) instead.

package/dist/developer/tutorial/admin.md

@@ -3,6 +3,8 @@ title: Admin Dashboard
 description: Scaffold the Spree admin UI for the Brands resource and add a rich text description editor, an Active Storage logo upload, and a custom table column.
 ---
 
+> **NOTE:** This is a backend customization. You need to perform it in the `backend` directory if you used `create-spree-app` to set up your Spree application.
+
 Now that we've created the `Brand` model, let's create an Admin Dashboard interface so admins can manage brands — including editing the rich text description and uploading the logo.
 
 ## Step 1: Scaffold the Admin UI

package/dist/developer/tutorial/api.md

@@ -4,6 +4,8 @@ sidebarTitle: API
 description: Expose your custom Brand model through the Spree Store and Admin REST APIs with serializers, controllers, routes, and the spree:api_resource generator.
 ---
 
+> **NOTE:** This is a backend customization. You need to perform it in the `backend` directory if you used `create-spree-app` to set up your Spree application.
+
 In this tutorial, we'll expose our Brand model through Spree's v3 API — the customer-facing **Store API** that storefronts read from, and the back-office **Admin API** with full CRUD for apps and integrations. We'll also extend the existing Product serializer to include brand data.
 
 > **INFO:** This guide assumes you've completed the [Model](model.md), [Admin](admin.md), and [Extending Core Models](extending-models.md) tutorials.

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

@@ -3,6 +3,8 @@ title: Extending Core Models
 description: Tutorial — extend Spree's core models with a custom Brand resource, generate a migration, and associate it with Products via a decorator.
 ---
 
+> **NOTE:** This is a backend customization. You need to perform it in the `backend` directory if you used `create-spree-app` to set up your Spree application.
+
 In this tutorial, we'll connect our custom Brand model with Spree's core Product model. This is a common pattern when building features that need to integrate with existing Spree functionality.
 
 > **INFO:** This guide assumes you've completed the [Model](model.md) and [Admin](admin.md) tutorials.

package/dist/developer/tutorial/model.md

@@ -3,6 +3,8 @@ title: Model
 description: Create a custom Brand model in Spree with database columns, a rich text description, and an Active Storage logo upload using a single generator command.
 ---
 
+> **NOTE:** This is a backend customization. You need to perform it in the `backend` directory if you used `create-spree-app` to set up your Spree application.
+
 In this step we'll create the `Spree::Brand` model with everything it needs: a `name` column, a rich text `description`, and an uploadable `logo`.
 
 ## Step 1: Generate the Model

package/package.json

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