@spree/docs 0.1.248 → 0.1.249

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

@@ -98,10 +98,10 @@ await adminClient.sellers.suspend('sel_xxx', { reason: 'Unresolved delivery comp
 curl -X POST 'https://api.mystore.com/api/v3/admin/sellers/sel_xxx/invite' \
   -H 'X-Spree-API-Key: sk_xxx'
 
-curl -X POST 'https://api.mystore.com/api/v3/admin/sellers/sel_xxx/approve' \
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/sellers/sel_xxx/approve' \
   -H 'X-Spree-API-Key: sk_xxx'
 
-curl -X POST 'https://api.mystore.com/api/v3/admin/sellers/sel_xxx/suspend' \
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/sellers/sel_xxx/suspend' \
   -H 'X-Spree-API-Key: sk_xxx' \
   -H 'Content-Type: application/json' \
   -d '{ "reason": "Unresolved delivery complaints" }'
@@ -204,7 +204,7 @@ curl -X POST 'https://marketplace.example.com/api/v3/seller/products' \
   -H 'Content-Type: application/json' \
   -d '{ "name": "Handmade Vase" }'
 
-curl -X POST 'https://marketplace.example.com/api/v3/seller/products/prod_xxx/submit' \
+curl -X PATCH 'https://marketplace.example.com/api/v3/seller/products/prod_xxx/submit' \
   -H 'Authorization: Bearer $SELLER_JWT' \
   -H 'X-Spree-Seller-Id: sel_xxx'
 ```

package/dist/developer/core-concepts/staff-roles.md

@@ -211,9 +211,11 @@ The invitation system publishes [events](events.md) you can subscribe to:
 
 ## Permissions
 
-Spree uses [CanCanCan](https://github.com/CanCanCommunity/cancancan) for authorization. Permissions apply to both customers (Store API access) and admins (Admin Panel access).
+A role holds flat permission keys from one catalog (`read_orders`, `write_products`, …) — the same vocabulary as secret API key scopes. Every Admin API request checks the staff member's keys on the current store against the endpoint's `read_<resource>` / `write_<resource>` key and returns `403` with `details.required_permission` when it is missing. Staff endpoints (`/admin_users`, `/invitations`, `/roles`) need `read_staff` / `write_staff`.
 
-See the [Customize Permissions guide](../customization/permissions.md) for details on creating custom roles and permission sets.
+Permissions apply to staff only. Customers never hold roles: the Store API authorizes them by ownership-scoped queries plus `Spree::Storefront::AccessPolicy`.
+
+See the [Customize Permissions guide](../customization/permissions.md) for details on creating custom roles and registering your own permission keys.
 
 ## Related Documentation
 

package/dist/developer/core-concepts/store-credits-gift-cards.md

@@ -18,7 +18,7 @@ Spree provides two stored value mechanisms that customers can use at checkout:
 | Has code | No | Yes |
 | Created by | Admin | Admin |
 | Assignment | Directly to customer | Applied to order via code |
-| Expiration | Configurable by type | Configurable per card |
+| Expiration | Never expire | Optional, per card |
 
 ## Store Credits
 

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

@@ -5,7 +5,7 @@ description: Understand Spree Stores — the top-level tenant boundary that scop
 
 ## Overview
 
-The Store is the top-level tenant in Spree. Every resource — products, orders, channels, markets, taxonomies — belongs to exactly one store. A store owns its [channels](channels.md) (online, POS, wholesale, …), its [markets](markets.md) (region/currency/locale), and its [product catalog](products.md).
+The Store is the top-level tenant in Spree. Every resource — products, orders, channels, markets, categories — belongs to exactly one store. A store owns its [channels](channels.md) (online, POS, wholesale, …), its [markets](markets.md) (region/currency/locale), and its [product catalog](products.md).
 
 ```mermaid
 erDiagram
@@ -85,7 +85,7 @@ The store sets the fallback for **storefront access gating** — whether anonymo
 
 ## Store Resources
 
-Each store owns its own resources. Products, orders, channels, markets, and taxonomies in one store are independent from another.
+Each store owns its own resources. Products, orders, channels, markets, and categories in one store are independent from another.
 
 | Resource | Relationship |
 |----------|-------------|

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

@@ -85,26 +85,30 @@ If a field has no translation for the requested locale, you get the default-lang
 
 Merchants translate in the dashboard, switching locale on the record they're editing. For bulk work — handing a catalogue to a translation agency — export to CSV, translate, and import it back.
 
-Translations can also be written through the Admin API, which is what you'd use to sync from an external translation service:
+Translations can also be written through the Admin API, which is what you'd use to sync from an external translation service. Writes go through one batch endpoint — every entry succeeds or none do — so a product and its option values can be translated in a single request:
 
 
 ```typescript Admin SDK
-await adminClient.products.update('prod_xxx', {
-  translations: {
-    fr: { name: 'Sac Spree', description: 'Un sac fourre-tout élégant…' },
-    de: { name: 'Spree Tasche' },
+await adminClient.translations.batch([
+  {
+    resource_type: 'product',
+    resource_id: 'prod_xxx',
+    values: {
+      fr: { name: 'Sac Spree', description: 'Un sac fourre-tout élégant…' },
+      de: { name: 'Spree Tasche' },
+    },
   },
-})
+])
 
 // Which resources and fields accept translations
 const { data: resources } = await adminClient.translatableResources.list()
 ```
 
 ```bash cURL
-curl -X PATCH 'https://api.mystore.com/api/v3/admin/products/prod_xxx' \
+curl -X POST 'https://api.mystore.com/api/v3/admin/translations/batch' \
   -H 'X-Spree-API-Key: sk_xxx' \
   -H 'Content-Type: application/json' \
-  -d '{ "translations": { "de": { "name": "Baumwolltasche" } } }'
+  -d '{ "translations": [ { "resource_type": "product", "resource_id": "prod_xxx", "values": { "de": { "name": "Baumwolltasche" } } } ] }'
 ```
 
 

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

@@ -12,7 +12,7 @@ Webhooks are built on top of Spree's [event system](events.md), providing:
 - **Multi-store support** - Each store has its own webhook endpoints
 - **Event filtering** - Subscribe to specific events or patterns with wildcards
 - **Secure delivery** - HMAC-SHA256 signatures for payload verification
-- **Automatic retries** - Failed deliveries retry with exponential backoff
+- **Failure handling** - Failed deliveries are recorded and can be re-sent, and an endpoint that keeps failing is disabled
 - **Full audit trail** - Track every delivery attempt with response codes and timing
 
 ## How Webhooks Work
@@ -34,10 +34,9 @@ flowchart LR
 
     subgraph External Service
         H --> I{Response}
-        I -->|2xx| J[Success]
-        I -->|Error| K[Retry with Backoff]
-        K -->|Max Retries| L[Mark Failed]
-        K -->|Retry| H
+        I -->|2xx| J[Mark Successful]
+        I -->|Error| K[Mark Failed]
+        K -->|15 failures in a row| L[Disable Endpoint]
     end
 ```
 
@@ -51,7 +50,7 @@ flowchart LR
 
 ### Via Admin Panel
 
-Navigate to **Settings → Developers → Webhooks** in the admin panel to create and manage webhook endpoints.
+Navigate to **Settings → Developer → Webhooks** in the admin panel to create and manage webhook endpoints.
 
 ### Via the Admin API
 
@@ -139,7 +138,7 @@ The `subscriptions` array accepts exact event names and wildcard patterns:
 | `['order.placed', 'order.canceled']` | Only those two events |
 | `['order.*']` | All order events |
 | `['*.created']` | All creation events |
-| `['order.*', 'payment.*', 'shipment.shipped']` | Multiple patterns |
+| `['order.*', 'payment.*', 'fulfillment.fulfilled']` | Multiple patterns |
 | `[]` or `['*']` | All events |
 
 ## Webhook Payload
@@ -154,7 +153,7 @@ Each webhook delivery sends a JSON payload with the following structure. The `da
   "data": {
     "id": "or_m3Rp9wXz",
     "number": "R123456789",
-    "fulfillment_status": "shipped",
+    "fulfillment_status": "unfulfilled",
     "payment_status": "paid",
     "total": "99.99",
     "display_total": "$99.99",
@@ -165,7 +164,7 @@ Each webhook delivery sends a JSON payload with the following structure. The `da
     "payments": [ ... ]
   },
   "metadata": {
-    "spree_version": "5.1.0"
+    "spree_version": "6.0.0"
   }
 }
 ```
@@ -243,7 +242,7 @@ class WebhooksController < ApplicationController
 
     case event['name']
     when 'order.placed'
-      handle_order_completed(event['data'])
+      handle_order_placed(event['data'])
     when 'product.updated'
       handle_product_updated(event['data'])
     end
@@ -266,11 +265,13 @@ class WebhooksController < ApplicationController
 end
 ```
 
-## Delivery Status & Retries
+## Delivery Status
 
-### Automatic Retries
+### Failed Deliveries
 
-Failed webhook deliveries automatically retry up to 5 times with exponential backoff. This handles temporary network issues and endpoint downtime.
+Spree sends each delivery once. Any response other than 2xx — including a timeout or a connection error — marks the delivery as failed, and Spree does not send it again on its own. To send a failed delivery again, re-send it from the delivery log (see below).
+
+If an endpoint fails 15 deliveries in a row, Spree disables it and emails the store staff. Fix the endpoint, then turn it back on by marking it active again.
 
 ### Checking Delivery Status
 
@@ -321,7 +322,7 @@ SSL certificates are verified in production, and not in development — so you c
 
 ## Available Events
 
-Webhooks can subscribe to any event in Spree's event system. See [Events](events.md#available-events) for a complete list.
+Webhooks can subscribe to any event in Spree's event system. See [Webhook Events & Payloads](../../api-reference/webhooks-events.md) for the complete list.
 
 Common webhook events include:
 
@@ -330,12 +331,12 @@ Common webhook events include:
 | `order.placed` | A customer completed checkout |
 | `order.paid` | The order is fully paid |
 | `order.canceled` | The order was canceled |
-| `order.shipped` | Everything on the order has shipped |
-| `fulfillment.shipped` | One parcel went out |
+| `order.fulfilled` | Everything on the order has shipped |
+| `fulfillment.fulfilled` | One parcel went out |
 | `payment.completed` | A payment succeeded |
 | `product.created` / `product.updated` | Catalog changes |
 | `product.out_of_stock` / `product.back_in_stock` | Availability flipped |
-| `customer.created` | A new customer registered |
+| `user.created` | A new customer registered |
 | `return.received` | A return arrived |
 
 ## Testing Webhooks
@@ -386,7 +387,7 @@ curl -X POST 'https://api.mystore.com/api/v3/admin/webhook_endpoints' \
 
   - **Verify signatures** — Always verify the `X-Spree-Webhook-Signature` header to ensure the webhook is authentic.
 
-  - **Handle duplicates** — Use the event `id` to detect and handle duplicate deliveries. Webhooks may be retried.
+  - **Handle duplicates** — Use the event `id` to detect and handle duplicate deliveries. A delivery that is re-sent carries the same event `id`.
 
   - **Subscribe selectively** — Only subscribe to events you need. Use specific patterns rather than `*` when possible.
 

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

@@ -123,14 +123,9 @@ The project includes [@spree/cli](../cli/quickstart.md) for managing your Spree
 
 ### Admin Dashboard
 
-Open [http://localhost:3000/admin](http://localhost:3000/admin) and log in with:
+The dashboard runs as its own dev server: `spree dev` starts it alongside the API at [http://localhost:5173](http://localhost:5173), live-reloading from `apps/dashboard/`. See the [dashboard docs](../dashboard/overview.md).
 
-| | |
-|---|---|
-| **Email** | `spree@example.com` |
-| **Password** | `spree123` |
-
-The dashboard runs as its own dev server: `spree dev` starts it alongside the API at [http://localhost:5173](http://localhost:5173), with the same credentials, live-reloading from `apps/dashboard/`. See the [dashboard docs](../dashboard/overview.md).
+No default admin account is created. On the first run, `spree dev` opens a one-time setup link where you create the admin account. If you missed it, print it again with `spree rails spree:setup:token`.
 
 ### Store API
 

package/dist/developer/customization/api.md

@@ -141,7 +141,7 @@ The base `ResourceController` provides:
 | Pagination | [Pagy](https://github.com/ddnexus/pagy) — `?page=2&limit=25` |
 | Filtering | [Ransack](https://github.com/activerecord-hackery/ransack) — `?q[name_cont]=nike` |
 | Sorting | JSON:API style — `?sort=-name` |
-| Authorization | [CanCanCan](https://github.com/CanCanCommunity/cancancan) |
+| Authorization | Ownership scoping — `scope` decides what the caller can see (Admin API controllers add the `scoped_resource` permission gate) |
 | Prefixed IDs | Stripe-style — `brand_k5nR8xLq` |
 
 Override these methods to customize:

package/dist/developer/customization/checkout.md

@@ -34,7 +34,7 @@ Spree::Checkout::Registry.add_requirement(
   step: :address,
   field: :vat_number,
   message: 'VAT number is required for business orders',
-  satisfied: ->(cart) { cart.custom_fields['vat_number'].present? }
+  satisfied: ->(cart) { cart.metadata['vat_number'].present? }
 )
 ```
 
@@ -58,7 +58,7 @@ A step bundles its own requirements and says when it is satisfied:
 Spree::Checkout::Registry.register_step(
   name: :loyalty,
   before: :payment,
-  satisfied: ->(cart) { cart.custom_fields['loyalty_number'].present? },
+  satisfied: ->(cart) { cart.metadata['loyalty_number'].present? },
   requirements: ->(cart) {
     [{ step: 'loyalty', field: 'loyalty_number',
        message: 'Loyalty number is required' }]

package/dist/developer/customization/dependencies.md

@@ -6,8 +6,8 @@ section: customization
 ## Overview
 
 With Dependencies, you can replace parts of Spree core with your custom code:
-[Services and Workflows](workflows.md), CanCanCan
-Abilities (used for [Permissions](permissions.md)), and API Serializers (used for
+[Services and Workflows](workflows.md), the staff ability class
+and the storefront access policy (used for [Permissions](permissions.md)), and API Serializers (used for
 generating JSON API responses).
 
 > **TIP:** Replacing a whole class means keeping your copy in sync with every Spree
@@ -18,19 +18,19 @@ generating JSON API responses).
 
 ## Application (global) customization
 
-This will change every aspect of the application (both APIs, Admin Panel, and Storefront).
+This will change every aspect of the application (the Store API, the Admin API, and everything built on them).
 
 In your `config/initializers/spree.rb` file, you can set the following:
 
 ```ruby
-Spree.cart_update_service = MyStore::CartUpdate
+Spree.carts_update_service = MyStore::CartUpdate
 ```
 
 or using the block syntax:
 
 ```ruby
 Spree.dependencies do |dependencies|
-  dependencies.cart_update_service = MyStore::CartUpdate
+  dependencies.carts_update_service = MyStore::CartUpdate
 end
 ```
 
@@ -86,6 +86,18 @@ Spree.cart_add_item_workflow = MyStore::AddItem
 > reasons people replace this class, and they don't need maintaining across
 > upgrades.
 
+> **WARNING:** A subclass runs its hooks under its **own** key, derived from its class name —
+> `MyStore::AddItem` fires `my_store.add_item.*`, not `carts.add_item.*`. Hooks
+> registered on the original key (by you or by an installed extension) stop
+> firing once you swap the class in. To keep them, declare the original key in
+> the subclass:
+> 
+> ```ruby
+class AddItem < Spree::Carts::AddItem
+  workflow_key 'carts.add_item'
+end
+```
+
 ## Using dependencies in your code
 
 When you need to use a dependency in your code, you can access it directly via the `Spree` module:
@@ -95,60 +107,53 @@ When you need to use a dependency in your code, you can access it directly via t
 Spree.cart_add_item_workflow.call(cart: cart, variant: variant, quantity: 1)
 
 # For API dependencies, use the Spree.api accessor
-Spree.api.storefront_cart_serializer.new(order).serializable_hash
+Spree.api.cart_serializer.new(cart).serializable_hash
 ```
 
 ## Controller level customization
 
-If you need to replace [serializers](https://github.com/jsonapi-serializer/jsonapi-serializer) or Services in a specific API endpoint you can create a [code decorator](decorators.md):
+If you need to replace a serializer in a specific API endpoint only, you can create a [code decorator](decorators.md):
 
 ```bash
-mkdir -p app/controllers/spree && touch app/controllers/spree/cart_controller_decorator.rb
+mkdir -p app/controllers/spree/api/v3/store && touch app/controllers/spree/api/v3/store/carts_controller_decorator.rb
 ```
 
 and add the following code to it:
 
 ```ruby
 module Spree
-  module CartControllerDecorator
-    def resource_serializer
-      MyNewAwesomeCartSerializer
-    end
-
-    def add_item_service
-      MyNewAwesomeAddItemToCart
+  module Api
+    module V3
+      module Store
+        module CartsControllerDecorator
+          def serializer_class
+            MyNewAwesomeCartSerializer
+          end
+        end
+
+        CartsController.prepend(CartsControllerDecorator)
+      end
     end
   end
-
-  CartController.prepend(CartControllerDecorator)
 end
 ```
 
-This will change the serializer in this API endpoint to `MyNewAwesomeCartSerializer` and also it will swap the default `add_item_service` to `MyNewAwesomeAddItemToCart`.
+This will change the serializer in this API endpoint to `MyNewAwesomeCartSerializer`. Services and workflows are resolved through the global dependencies (e.g. `Spree.cart_add_item_workflow`), so swap those at the application level.
 
-Different API endpoints can have different dependency injection points. You can review their [source code](https://github.com/spree/spree/tree/main/api/app/controllers/spree/api/v3) to see what you can replace.
+Different API endpoints can have different dependency injection points. You can review their [source code](https://github.com/spree/spree/tree/main/spree/api/app/controllers/spree/api/v3) to see what you can replace.
 
 ## API level customization
 
-Storefront API and Platform API have separate Dependencies injection points so you can easily customize one without touching the other.
+API serializers have their own injection points under `Spree.api` — Store API serializers (`cart_serializer`, `product_serializer`, …) and Admin API serializers (`admin_order_serializer`, …) — so you can customize one surface without touching the other.
 
 In your Spree initializer (`config/initializers/spree.rb`) please add:
 
 ```ruby
-Spree.api.storefront_cart_serializer = MyNewAwesomeCartSerializer
-Spree.api.storefront_cart_add_item_service = MyNewAwesomeAddItemToCart
+Spree.api.cart_serializer = MyNewAwesomeCartSerializer
+Spree.api.admin_order_serializer = MyNewAwesomeAdminOrderSerializer
 ```
 
-This will swap the default Cart serializer and Add Item to Cart service for your custom ones within all Storefront API endpoints that use those classes.
-
-You can mix and match both global and API-level customizations:
-
-```ruby
-Spree.cart_add_item_workflow = MyNewAwesomeAddItemToCart
-Spree.api.storefront_cart_add_item_service = AnotherAddItemToCart
-```
-
-The second line will have precedence over the first one, and the Storefront API will use `AnotherAddItemToCart` and the rest of the application will use `MyNewAwesomeAddItemToCart`.
+This will swap the default serializers for your custom ones within all API endpoints that use them.
 
 ## Debugging dependencies
 
@@ -170,8 +175,8 @@ cart_recalculate_workflow       Spree::Carts::Recalculate [OVERRIDDEN]
 ...
 
 [API]
-storefront_cart_serializer      Spree::V2::Storefront::CartSerializer
-storefront_cart_add_item_service  MyApp::CartAddItem [OVERRIDDEN]
+cart_serializer                 Spree::Api::V3::CartSerializer
+product_serializer              MyApp::ProductSerializer [OVERRIDDEN]
 ...
 ```
 
@@ -194,7 +199,7 @@ This shows only the dependencies that have been customized, along with their ori
 cart_recalculate_workflow  Spree::Carts::Recalculate -> MyApp::CartRecalculate (config/initializers/spree.rb:15)
 
 [API OVERRIDES]
-storefront_cart_add_item_service  Spree::Carts::AddItem -> MyApp::CartAddItem (config/initializers/spree.rb:20)
+product_serializer  Spree::Api::V3::ProductSerializer -> MyApp::ProductSerializer (config/initializers/spree.rb:20)
 ```
 
 ### Validate all dependencies
@@ -243,11 +248,16 @@ Seams backed by a [workflow](workflows.md) use a
 | `cart_add_item_service` | `cart_add_item_workflow` |
 | `cart_recalculate_service` | `cart_recalculate_workflow` |
 | `carts_complete_service` | `carts_complete_workflow` |
+| `carts_upsert_items_service` | `cart_upsert_items_workflow` |
 | `cart_merge_strategy` | `cart_merge_workflow` |
 | `order_cancel_service` | `order_cancel_workflow` |
 | `order_complete_service` | `order_complete_workflow` |
 | `fulfillment_create_service` | `fulfillment_create_workflow` |
 | `payments_handle_webhook_service` | `payments_handle_webhook_workflow` |
+| `shipment_update_service`, `fulfillment_update_service` | `fulfillment_update_workflow` |
+| `gift_card_apply_service` | `gift_card_apply_workflow` |
+| `gift_card_remove_service` | `gift_card_remove_workflow` |
+| `gift_card_redeem_service` | `gift_card_redeem_workflow` |
 
 > **WARNING:** The legacy names stay readable, but **assigning to one no longer has any
 > effect** — the override is recorded and a deprecation warning names the seam to
@@ -258,6 +268,12 @@ Seams backed by a [workflow](workflows.md) use a
 > If you override any of these, move to the `*_workflow` name and make sure your
 > class subclasses the workflow.
 
+Two seams are plain renames with an unchanged contract, so an override set
+under the old name is still applied (with a deprecation warning):
+`checkout_add_store_credit_service` → `store_credit_apply_service` and
+`checkout_remove_store_credit_service` → `store_credit_remove_service`. All
+legacy names are removed in Spree 6.1.
+
 ## Backwards compatibility
 
 The legacy string-based syntax is still supported for backwards compatibility:
@@ -280,5 +296,5 @@ Default values can be easily checked by:
 
 1. Using the rake task: `bin/rake spree:dependencies:list`
 2. Looking at the source code:
-   * [Application (global) dependencies](https://github.com/spree/spree/blob/main/core/lib/spree/core/dependencies.rb)
-   * [API level dependencies](https://github.com/spree/spree/blob/main/api/lib/spree/api/dependencies.rb)
+   * [Application (global) dependencies](https://github.com/spree/spree/blob/main/spree/core/lib/spree/core/dependencies.rb)
+   * [API level dependencies](https://github.com/spree/spree/blob/main/spree/api/lib/spree/api/dependencies.rb)

package/dist/developer/customization/permissions.md

@@ -11,7 +11,7 @@ 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 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.
+Roles are data, so create them where you manage the rest of your store's data: **Settings → Roles** in the dashboard, or the Admin API when you want it scripted.
 
 ```bash
 spree api post roles --data '{
@@ -68,6 +68,6 @@ The catalog is deliberately flat: it answers "may this role touch this kind of r
 
 ## How enforcement works
 
-Every Admin API controller declares its resource (`scoped_resource :orders`). Each request checks the principal's keys — a staff member's role permissions on the current store, or a secret key's scopes — against `read_<resource>` or `write_<resource>` for the action. A missing key produces a 403 naming it in `details.required_permission`. Behind that gate, keys compile to CanCanCan rules for record-level concerns, and `GET /api/v3/admin/me` returns both the rule dump the dashboard mirrors and `permission_keys`, the flat key list.
+Every Admin API controller declares its resource (`scoped_resource :orders`). Each request checks the principal's keys — a staff member's role permissions on the current store, or a secret key's scopes — against `read_<resource>` or `write_<resource>` for the action. A missing key produces a 403 naming it — `details.required_permission` for staff, `details.required_scope` for a secret key. Behind that gate, keys compile to CanCanCan rules for record-level concerns, and `GET /api/v3/admin/me` returns both the rule dump the dashboard mirrors and `permission_keys`, the flat key list.
 
 Storefront customers are not part of this system — customer authorization is ownership, enforced by the Store API's scoped lookups, with nothing to configure. The one swappable piece is `Spree::Storefront::AccessPolicy` (via `Spree::Dependencies.storefront_access_policy_class`): a generic `readable?` / `writable?` / `scope` protocol that defaults to "the caller owns the record", with carts and orders adding guest-token access. Replace it only when access must widen beyond the owner, such as company accounts sharing purchases or wishlists.

package/dist/developer/dashboard/concepts.md

@@ -55,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 `{ permissions, rules, isLoading }`, and the checks live on `permissions.can(...)`
+- `<PermissionProvider>` — the admin's permissions on the current store; `usePermissions()` returns `{ permissions, rules, permissionKeys, isLoading, refresh }`, 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/navigation.md

@@ -22,7 +22,7 @@ nav.add({
   path: '/analytics',      // prefixed with /$storeId at render time
   icon: BarChartIcon,
   position: 650,
-  subject: 'Spree::Order', // optional CanCanCan subject — hides item without read permission
+  subject: 'Spree::Order', // optional permission subject — hides item without read permission
 })
 ```
 
@@ -49,6 +49,7 @@ defineDashboardPlugin({
 nav.add({
   key: 'analytics',
   label: 'Analytics',
+  path: '/analytics',       // required, even on a parent
   icon: BarChartIcon,
   position: 650,
   children: [
@@ -196,7 +197,7 @@ settingsNav.add({
 
 ## Permission gating
 
-`subject` on a nav entry checks `permissions.can('read', subject)` — when it fails, the sidebar item is hidden. **This is UX, not authorization.** The backend still enforces CanCanCan via `authorize!` on every API call. Hiding the link is a hint, not a security boundary.
+`subject` on a nav entry checks `permissions.can('read', subject)` — when it fails, the sidebar item is hidden. **This is UX, not authorization.** The backend still enforces permissions on every API call. Hiding the link is a hint, not a security boundary.
 
 ## Order of operations
 

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

@@ -1,12 +1,12 @@
 ---
 title: Permissions
 sidebarTitle: Permissions
-description: How to hide UI behind CanCanCan permissions in your customisations — and why hiding is never the same as authorising.
+description: How to hide UI behind the current admin's permissions in your customisations — and why hiding is never the same as authorising.
 ---
 
 > **NOTE:** Examples here import from `@spree/dashboard`, which re-exports the framework and the design system for host applications. A **distributed plugin** imports `@spree/dashboard-core` and `@spree/dashboard-ui` directly instead — it extends the shell rather than shipping it. See [plugin overview](../plugins/overview.md).
 
-The dashboard exposes the current admin's CanCanCan abilities to every component via the `usePermissions()` hook. The registry surfaces — nav entries, settings entries, custom routes — also accept a `subject` shortcut, and nav entries take a generic `if` predicate that reads from `permissions`.
+The dashboard exposes the current admin's permissions to every component via the `usePermissions()` hook: the catalog keys their role holds on the current store (`read_orders`, `write_products`, …) and the class-level ability rules the server compiles from those keys. The registry surfaces — nav entries, settings entries, custom routes — also accept a `subject` shortcut, and nav entries take a generic `if` predicate that reads from `permissions`.
 
 ## Two layers
 
@@ -15,9 +15,9 @@ UI gating is for **UX**. Backend authorization is for **security**. They are not
 | Layer | Where | What it does |
 |---|---|---|
 | UI gating | Dashboard registries (`subject`, `if`) | Hides menu items, columns, buttons — keeps the interface tidy |
-| Authorization | Rails API controllers (CanCanCan, scopes) | Refuses the request when the user doesn't have permission |
+| Authorization | Rails API controllers (per-controller `read_*`/`write_*` key gate, record-level checks) | Refuses the request when the user doesn't have permission |
 
-**Always rely on the backend for security.** Hiding a button is a hint to the user, not a wall. A user with browser dev tools (or the API token) can always hit the endpoint directly — your `authorize!` call is what stops them.
+**Always rely on the backend for security.** Hiding a button is a hint to the user, not a wall. A user with browser dev tools (or the API token) can always hit the endpoint directly — the API's permission check is what stops them.
 
 ## The `permissions` object
 
@@ -87,7 +87,7 @@ Use it for combined checks (permission + store state), feature flags, multi-acti
 
 ## Inside components
 
-Use the `usePermissions()` hook — it returns `{ permissions, rules, isLoading }`:
+Use the `usePermissions()` hook — it returns `{ permissions, rules, permissionKeys, isLoading, refresh }`. `permissionKeys` is the flat key list (the same vocabulary as the role editor and API-key scopes), for when `permissionKeys.includes('read_orders')` reads better than a subject check:
 
 ```tsx
 import { usePermissions } from '@spree/dashboard'
@@ -110,4 +110,4 @@ If your customization introduces a new model on the backend, register it as a pe
 ## Reference
 
 - [`Permissions` interface](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/providers/permission-provider.tsx)
-- [CanCanCan docs](https://github.com/CanCanCommunity/cancancan) — the Ruby ability definition language
+- [Customize Permissions](../../customization/permissions.md) — the backend permission catalog and `register_scope`

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

@@ -15,9 +15,9 @@ Your plugin imports React, the dashboard, Tailwind, i18next, etc., but **you don
   "peerDependencies": {
     "react": "^19",
     "react-dom": "^19",
-    "@spree/dashboard-core": "^0.10.0",
-    "@spree/dashboard-ui": "^0.10.0",
-    "@spree/admin-sdk": "^0.6.0",
+    "@spree/dashboard-core": "^1.0.0-beta.3",
+    "@spree/dashboard-ui": "^1.0.0-beta.3",
+    "@spree/admin-sdk": "^1.0.0-beta.2",
     "i18next": "^26",
     "react-i18next": "^17",
     "@tanstack/react-query": "^5",
@@ -27,7 +27,7 @@ Your plugin imports React, the dashboard, Tailwind, i18next, etc., but **you don
 }
 ```
 
-Use ranges, not exact versions — pin too tightly and consumers can't upgrade the dashboard without you cutting a release. One Developer Preview caveat: for `0.x` versions, `^` only allows patch-level drift (`^0.10.0` matches `0.10.x`, not `0.11.0`), so expect to bump your `@spree/dashboard-*` peers alongside dashboard releases until 1.0. `spree plugin new` scaffolds these ranges for you, matched to the current release.
+Use ranges, not exact versions — pin too tightly and consumers can't upgrade the dashboard without you cutting a release. One pre-release caveat: a range like `^1.0.0-beta.3` accepts later `1.0.0` betas and every stable `1.x` release, but not betas of other versions — so keep your `@spree/dashboard-*` peers in step with the dashboard until 1.0 ships. Check the ranges `spree plugin new` scaffolds against the versions your host app installs.
 
 `dependencies` is for things your plugin *uses* that the host *doesn't* — small utilities (e.g., `clsx`, `date-fns` if you need a specific version, your own helper packages). When in doubt, peer-dep it. The trade-off is "user has to install one more thing" vs. "user has two copies of React" — always pay the first cost.
 

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

@@ -15,7 +15,7 @@ your-plugin/
 ├── .gitignore
 └── packages/
     └── dashboard/
-        ├── package.json    # @your-scope/dashboard-your-plugin
+        ├── package.json    # @your-scope/your-plugin-dashboard
         ├── tsconfig.json
         ├── biome.json
         └── src/

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

@@ -84,7 +84,7 @@ import {
 ```ts
 import {
   useAuth,            // current admin user
-  usePermissions,     // CanCanCan abilities
+  usePermissions,     // current admin's permissions
   useStore,           // current store
   useCommandPalette,  // ⌘K palette open/close state
   useGlobalSearch,    // global search query state