@spree/docs 0.1.299 → 0.1.301

package/dist/api-reference/store.yaml

@@ -11738,7 +11738,7 @@ components:
           type: array
           items:
             type: string
-          description: Subject class names, e.g. ["Spree::Product"] or ["all"]
+          description: Subject short names, e.g. ["product"] or ["all"]
         has_conditions:
           type: boolean
           description: True if the server-side rule has per-record conditions. The

package/dist/developer/cli/quickstart.md

@@ -94,11 +94,12 @@ spree build --yes            # Skip confirmation prompts (for CI)
 
 Upgrade your project to the latest Spree release in one go. It works for both kinds of project:
 
-1. **Update the server**
-   - On a project that runs the prebuilt image, it pulls the latest Spree image and recreates the containers. Database migrations run as the containers start.
-   - On an [ejected](#spree-eject) project, it updates the Spree gems with `bundle update`, applies pending migrations, and restarts the app so it loads the new gems.
-2. **Run data backfills** — the version-specific steps from the upgrade manifest that convert existing records.
-3. **Update the `@spree/*` packages** — `@spree/cli` in the project root, and the dashboard packages and Admin SDK in `apps/dashboard` and `apps/seller-dashboard`. Each package moves to the newest release its declared range in `package.json` allows, the same way `bundle update` respects your `Gemfile`. To move to a new major version, change the range in `package.json` first.
+1. **Update the server** — on a project that runs the prebuilt image, it pulls the latest Spree image. On an [ejected](#spree-eject) project, it updates the Spree gems with `bundle update`.
+2. **Update the `@spree/*` packages** — `@spree/cli` in the project root, and the dashboard packages and Admin SDK in `apps/dashboard` and `apps/seller-dashboard`. Each package moves to the newest release its declared range in `package.json` allows, the same way `bundle update` respects your `Gemfile`. To move to a new major version, change the range in `package.json` first.
+3. **Migrate the database** — on a prebuilt-image project, it recreates the containers and the migrations run as they start. On an ejected project, it applies pending migrations.
+4. **Run data backfills** — the version-specific steps from the upgrade manifest that convert existing records. An ejected project's app is then restarted so it loads the new gems.
+
+The packages are updated before the database steps, so a failed migration or backfill no longer stops them from moving to the newest release their ranges allow. Fix the cause and run `spree upgrade` again.
 
 ```bash
 spree upgrade                  # Run every step, asking before each one

package/dist/developer/create-spree-app/quickstart.md

@@ -151,7 +151,7 @@ To update to the latest Spree version:
 spree upgrade
 ```
 
-This updates the server (the Docker image, or the Spree gems on an ejected project), runs database migrations and data backfills, and updates the `@spree/*` packages of the project and its dashboard apps. See [`spree upgrade`](../cli/quickstart.md#spree-upgrade) for details.
+This updates the server (the Docker image, or the Spree gems on an ejected project) and the `@spree/*` packages of the project and its dashboard apps, then runs database migrations and data backfills. See [`spree upgrade`](../cli/quickstart.md#spree-upgrade) for details.
 
 To pin a specific version, edit `SPREE_VERSION_TAG` in `.env`:
 

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

@@ -22,7 +22,7 @@ nav.add({
   path: '/analytics',      // prefixed with /$storeId at render time
   icon: BarChartIcon,
   position: 650,
-  subject: 'Spree::Order', // optional permission subject — hides item without read permission
+  subject: 'order', // optional permission subject — hides item without read permission
 })
 ```
 
@@ -70,7 +70,7 @@ nav.addChild('products', {
   key: 'products.brands',
   label: 'Brands',
   path: '/products/brands',
-  subject: 'Spree::Brand',
+  subject: 'brand',
 })
 ```
 
@@ -177,7 +177,7 @@ settingsNav.add({
   path: '/integrations/stripe-tax',  // prefixed with /$storeId/settings
   group: 'integrations',
   position: 100,
-  subject: 'Spree::TaxRate',
+  subject: 'tax_rate',
 })
 ```
 

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

@@ -33,10 +33,10 @@ interface Permissions {
 It mirrors the backend ability at the **class level**:
 
 ```ts
-permissions.can('read', 'Spree::Order')
+permissions.can('read', 'order')
 ```
 
-Subjects are strings (`'Spree::Order'`, `'Spree::Product'`, or your own `'MyApp::Report'`). There is no client-side record-level check — when a rule is conditional on record attributes, `isConditional` returns `true` and the API is the arbiter: render the control and handle a possible 403.
+Subjects are short names: the model's class name without its namespace, underscored (`'order'`, `'product'`, or `'report'` for your own `MyApp::Report`). Use the `Subject` constants from `@spree/dashboard-core` for Spree's own models. There is no client-side record-level check — when a rule is conditional on record attributes, `isConditional` returns `true` and the API is the arbiter: render the control and handle a possible 403.
 
 ## `subject` shortcut
 
@@ -47,7 +47,7 @@ nav.add({
   key: 'reports',
   label: 'Reports',
   path: '/reports',
-  subject: 'Spree::Order',  // hides nav item without read:Spree::Order
+  subject: 'order',  // hides nav item without read:order
 })
 ```
 
@@ -58,7 +58,7 @@ routes: [{
   key: 'reports',
   path: '/reports',
   component: ReportsPage,
-  subject: 'Spree::Order',
+  subject: 'order',
 }],
 ```
 
@@ -76,7 +76,7 @@ nav.add({
   label: 'Reports',
   path: '/reports',
   if: ({ permissions, store }) =>
-    permissions.can('read', 'Spree::Order') &&
+    permissions.can('read', 'order') &&
     !!(store as Store | null)?.setup_tasks?.every((task) => task.done),
 })
 ```
@@ -94,18 +94,18 @@ import { usePermissions } from '@spree/dashboard'
 
 function ReportsPage() {
   const { permissions } = usePermissions()
-  if (!permissions.can('read', 'Spree::Order')) {
+  if (!permissions.can('read', 'order')) {
     return <Forbidden />
   }
   return <ReportsList />
 }
 ```
 
-The same `permissions` object backs the nav registry's `if` predicate, so you can move logic between the two without changing behaviour. For declarative gating, `<Can I="update" a="Spree::Order">…</Can>` (also from `@spree/dashboard-core`) renders children only when the check passes.
+The same `permissions` object backs the nav registry's `if` predicate, so you can move logic between the two without changing behaviour. For declarative gating, `<Can I="update" a="order">…</Can>` (also from `@spree/dashboard-core`) renders children only when the check passes.
 
 ## Custom permissions
 
-If your customization introduces a new model on the backend, register it as a permission catalog scope there (`Spree.permissions.register_scope` in your engine's initializer). Its keys then appear in the role editor and the API-key scope picker, and any role granted them makes `permissions.can('read', 'MyApp::Report')` resolve in the dashboard exactly like a first-party check — the abilities ship with the current-user response (`GET /api/v3/admin/me`) at sign-in, alongside `permission_keys`, the flat key list the role editor grants from.
+If your customization introduces a new model on the backend, register it as a permission catalog scope there (`Spree.permissions.register_scope` in your engine's initializer). Its keys then appear in the role editor and the API-key scope picker, and any role granted them makes `permissions.can('read', 'report')` resolve in the dashboard exactly like a first-party check — the abilities ship with the current-user response (`GET /api/v3/admin/me`) at sign-in, alongside `permission_keys`, the flat key list the role editor grants from.
 
 ## Reference
 

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

@@ -135,7 +135,7 @@ routes: [{
   key: 'reports',
   path: '/reports',
   component: ReportsPage,
-  subject: 'Spree::Order',
+  subject: 'order',
 }],
 ```
 

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

@@ -68,7 +68,7 @@ import { usePermissions } from '@spree/dashboard'
 
 function AdminOnlyMenuItem() {
   const { permissions } = usePermissions()
-  if (!permissions.can('manage', 'Spree::Customer')) return null
+  if (!permissions.can('manage', 'customer')) return null
   return <DropdownMenuItem>…</DropdownMenuItem>
 }
 ```

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

@@ -33,7 +33,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 (!permissions.can('update', 'order')) return null
   if (resource.status !== 'placed') return null
 
   return (
@@ -95,7 +95,7 @@ export function SyncToErpItem({ resource }: Props) {
     successMessage: 'Synced',
   })
 
-  if (!permissions.can('manage', 'Spree::Order')) return null
+  if (!permissions.can('manage', 'order')) return null
 
   return (
     <DropdownMenuItem

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

@@ -42,7 +42,7 @@ interface Props {
 export function LoyaltyStatusCard({ customer }: Props) {
   const { storeId } = useStore()
   const { permissions } = usePermissions()
-  const canRead = permissions.can('read', 'MyApp::LoyaltyRecord')
+  const canRead = permissions.can('read', 'loyalty_record')
   const { data, isLoading } = useQuery({
     queryKey: ['loyalty', storeId, customer.id],
     queryFn: () =>

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

@@ -44,7 +44,7 @@ import { usePermissions, useStore } from '@spree/dashboard'
 function MyWidget({ product }: { product: Product }) {
   const { permissions } = usePermissions()
   const { store } = useStore()
-  if (!permissions.can('read', 'MyApp::LoyaltyRecord')) return null
+  if (!permissions.can('read', 'loyalty_record')) return null
   // ...
 }
 ```

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

@@ -506,7 +506,7 @@ If your storefront or webhook receiver reads any of these fields, compare agains
 | `payment_source_type` | Store API payment setup sessions, `payment_setup_session.*` webhooks | `Spree::CreditCard` | `credit_card` |
 | `type` | Custom fields on products, variants, categories and collections | `Spree::CustomFields::ShortText` | removed — read `field_type` (`short_text`) |
 
-The Admin API follows the same rule everywhere: providers and strategies (`fulfillment_provider: 'manual'`, `preferred_order_routing_strategy: 'rules'`), custom field definition `resource_type` (`product`, `category`), tag `taggable_type`, the owner and originator types on records, and filters such as `q[type_eq]=orders`. An integration written against the Admin API preview sends and expects these short names; the [Admin SDK](../sdk/admin/resources.md) types list them.
+The Admin API follows the same rule everywhere: providers and strategies (`fulfillment_provider: 'manual'`, `preferred_order_routing_strategy: 'rules'`), custom field definition `resource_type` (`product`, `category`), tag `taggable_type`, the owner and originator types on records, the permission subjects `/me` returns (`product`, `category`), and filters such as `q[type_eq]=orders`. An integration written against the Admin API preview sends and expects these short names; the [Admin SDK](../sdk/admin/resources.md) types list them.
 
 ## Every event is declared
 

package/dist/developer/upgrades/quickstart.md

@@ -11,7 +11,7 @@ We strongly advise upgrading Spree incrementally, rather than in one big go.
 
 ## How to upgrade
 
-An upgrade updates the server, migrates the database, runs the version's data backfills, and updates the `@spree/*` packages of your dashboard apps. Always read the guide for the version you're moving to first — it lists the behavior changes to review.
+An upgrade updates the server and the `@spree/*` packages of your dashboard apps, migrates the database, and runs the version's data backfills. Always read the guide for the version you're moving to first — it lists the behavior changes to review.
 
 **Spree CLI:**
 
@@ -19,23 +19,23 @@ An upgrade updates the server, migrates the database, runs the version's data ba
     spree upgrade
     ```
 
-    One command for every project: it pulls the new image, or updates the Spree gems on an [ejected](../cli/quickstart.md#spree-eject) project, then runs migrations, data backfills and the package updates. See [`spree upgrade`](../cli/quickstart.md#spree-upgrade) for its options.
+    One command for every project: it pulls the new image, or updates the Spree gems on an [ejected](../cli/quickstart.md#spree-eject) project, then updates the packages and runs migrations and data backfills. See [`spree upgrade`](../cli/quickstart.md#spree-upgrade) for its options.
 
   **Without CLI:**
 
 Run from the project root:
 
     ```bash
-    cd server
-    bundle update $(bundle list --name-only | grep ^spree)
-    bin/rails spree:install:migrations db:migrate
-    bin/rails spree:upgrade
-    cd ..
+    (cd server && bundle update $(bundle list --name-only | grep ^spree))
 
     # The project root and each dashboard app have their own package.json
     pnpm update "@spree/*"
     (cd apps/dashboard && pnpm update "@spree/*")
     (cd apps/seller-dashboard && pnpm update "@spree/*")
+
+    cd server
+    bin/rails spree:install:migrations db:migrate
+    bin/rails spree:upgrade
     ```
 
     On npm or Yarn, run `npm update` or `yarn upgrade` instead, naming each `@spree/*` package from that `package.json` (they do not accept the `"@spree/*"` pattern).

package/package.json

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