@spree/docs 0.1.237 → 0.1.238

package/dist/api-reference/webhooks-events.md

@@ -764,7 +764,7 @@ Events: `newsletter_subscriber.created`, `newsletter_subscriber.updated`, `newsl
 Events: `digital_asset.created`, `digital_asset.updated`, `digital_asset.deleted`
 
 The legacy `digital.created` / `digital.updated` / `digital.deleted` names are
-still emitted alongside these for one release and are removed in Spree 6.1 —
+still emitted alongside these, but will stop being sent in a future release —
 subscribe to the `digital_asset.*` names.
 
 ```json

package/dist/developer/contributing/developing-spree.md

@@ -191,7 +191,7 @@ Install chromedriver on macOS:
 brew install chromedriver
 ```
 
-The 6.0 React dashboard (`packages/dashboard`) has its own end-to-end test suite running on Playwright against a real Rails backend — see [Dashboard E2E tests](#dashboard-e2e-tests) under TypeScript Development.
+The React dashboard (`packages/dashboard`) has its own end-to-end test suite running on Playwright against a real Rails backend — see [Dashboard E2E tests](#dashboard-e2e-tests) under TypeScript Development.
 
 ### Performance in development mode
 
@@ -216,7 +216,7 @@ The backend setup is the same as for Ruby work — see [Setup](#setup) above. Wi
 | `@spree/cli` | `packages/cli` | yes | CLI for managing Spree Commerce projects |
 | `create-spree-app` | `packages/create-spree-app` | yes | Project scaffolding (`npm create spree-app`) |
 | `@spree/docs` | `packages/docs` | yes | Developer documentation for AI agents and local reference |
-| `@spree/dashboard` | `packages/dashboard` | no | React SPA admin dashboard (Spree 6.0, replaces the legacy Rails admin) |
+| `@spree/dashboard` | `packages/dashboard` | no | React SPA admin dashboard (replaces the legacy Rails admin) |
 | `@spree/dashboard-core` | `packages/dashboard-core` | no | Framework: registries, providers, generic infra hooks for the dashboard |
 | `@spree/dashboard-ui` | `packages/dashboard-ui` | no | Design system used by the dashboard |
 | `@spree/sdk-core` | `packages/sdk-core` | no | Shared HTTP/retry/error layer used by both SDKs |

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

@@ -9,7 +9,7 @@ Sooner or later you need to store something Spree doesn't have a field for. A fa
 
 Custom fields are how you do that without changing the database. You declare a field once — its name, its type, who can see it — and from then on it can be set on any record of that kind, edited in the dashboard, returned by the API, and searched or filtered like any built-in field.
 
-> **NOTE:** Custom fields were called **metafields** before Spree 6.0. The API and SDK have always called them custom fields; now the rest of Spree does too.
+> **NOTE:** Custom fields are also known as **metafields** in the dashboard. The API and SDK call them custom fields throughout.
 
 ## Definitions and values
 

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

@@ -76,9 +76,7 @@ erDiagram
 
 ### Why a Credit Exists
 
-Store credits carry no category and no type — both were retired in Spree 6.0
-because neither answered a question anything asked. Two fields cover it
-instead:
+Store credits carry no category and no type. Two fields cover it instead:
 
 | Field | What it tells you |
 |-------|-------------------|
@@ -88,8 +86,8 @@ instead:
 Store credits do not expire; only gift cards carry an expiry, on their own
 record. Which credit is spent first is decided by `Spree::StoreCredit.oldest_first`.
 
-> **NOTE:** `Spree::StoreCreditCategory` and `Spree::StoreCreditType` survive as deprecated
-> shells for one release and are removed in 6.1. Nothing writes them.
+> **NOTE:** `Spree::StoreCreditCategory` and `Spree::StoreCreditType` still exist as
+> deprecated shells for compatibility. Nothing writes them.
 
 ### Store Credit Events
 

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

@@ -102,7 +102,7 @@ Each store owns its own resources. Products, orders, channels, markets, and taxo
 
 If you need one Spree backend to serve **multiple distinct merchant brands** — different domains, different catalogs — there are two patterns:
 
-- **Multiple channels under one store** (recommended for most cases) — model each storefront as a Sales Channel. Products are scoped per-channel via publications, orders carry the channel that originated them, and routing/pricing can differ per channel. This is the supported pattern in core Spree 5.5+.
+- **Multiple channels under one store** (recommended for most cases) — model each storefront as a Sales Channel. Products are scoped per-channel via publications, orders carry the channel that originated them, and routing/pricing can differ per channel. This is the supported pattern in core Spree.
 - **Multiple isolated stores (tenants) in one app** — full data isolation, only recommended if you're building a SaaS platform or a multi-tenant application. Each store can have different staff members, payment methods, shipping methods, and branding. This is supported by the [Spree Multi Tenant](../multi-tenant/quickstart.md) extension, which is a separate gem from core Spree.
 
 ## Related Documentation

package/dist/developer/customization/configuration.md

@@ -1,6 +1,6 @@
 ---
 title: Configuration
-description: Every global Spree setting that is actually read by Spree 6 — grouped by area, with defaults and what each one changes.
+description: Every global Spree setting that is actually read by Spree — grouped by area, with defaults and what each one changes.
 ---
 
 Global settings live in `config/initializers/spree.rb` and apply to the whole application. Anything that varies per store — currency, markets, delivery zones, languages — is data you change in the dashboard instead.
@@ -23,7 +23,7 @@ Settings that describe the deployment rather than commerce behavior can be set w
 | `dashboard_url` | `SPREE_DASHBOARD_URL` | Origin where the admin dashboard is hosted (e.g. `https://admin.my-shop.com`). Used for every link that sends someone into the dashboard: invitation emails, SSO redirects, and the first-run setup link printed by `db:seed`. |
 | `seller_panel_url` | `SPREE_SELLER_PANEL_URL` | Origin where the marketplace seller panel is hosted, when you serve it somewhere other than this app's own `/sellers` mount. Used for links sent to sellers, today the invitation email. Leave it unset to use `/sellers`; with no panel deployed at all, those links open the dashboard. |
 
-This page lists only settings Spree 6 actually reads. Settings that exist for backwards compatibility are listed under [Deprecated settings](#deprecated-settings) rather than mixed in with the rest.
+This page lists only settings Spree actually reads. Settings that exist for backwards compatibility are listed under [Deprecated settings](#deprecated-settings) rather than mixed in with the rest.
 
 ## Settings that belong to a store
 
@@ -31,7 +31,7 @@ Settings that shape how a shop sells — when customers are charged, whether sto
 
 `capture_method`, `track_inventory_levels`, `stock_reservations_enabled`, `stock_reservation_ttl_minutes`, `track_price_history`, `show_products_without_price`, `disable_sku_validation`, `address_requires_phone`, `company_field_enabled`, `tax_using_ship_address`, plus `guest_checkout` and `storefront_access` — those last two are owned by the channel, and the store's value is what a channel falls back to.
 
-They were global before Spree 6. The global versions still exist for one release but are no longer read, so setting one in the initializer changes nothing — run `bin/rake spree:store_settings:backfill_from_config` during the upgrade to copy your values onto every store.
+The global versions of these settings still exist but are no longer read, so setting one in the initializer changes nothing. If you're upgrading from an installation that used them, run `bin/rake spree:store_settings:backfill_from_config` to copy your values onto every store.
 
 ```ruby
 store = Spree::Current.store
@@ -59,7 +59,7 @@ payment_method.update!(capture_method: nil)   # back to inheriting
 payment_method.resolved_capture_method        # => "checkout"
 ```
 
-Before Spree 6 this was two separate booleans, `auto_capture` and `auto_capture_on_dispatch`, which could contradict each other. Two upgrade tasks carry existing installs over: `spree:store_settings:backfill_from_config` maps the old globals onto each store's `capture_method`, and `spree:migrate_capture_methods` converts the per-payment-method `auto_capture` column. A method left without a value inherits its store.
+If you're upgrading from an installation that used the older `auto_capture` and `auto_capture_on_dispatch` booleans, two tasks carry it over: `spree:store_settings:backfill_from_config` maps the old globals onto each store's `capture_method`, and `spree:migrate_capture_methods` converts the per-payment-method `auto_capture` column. A method left without a value inherits its store.
 
 ## Checkout and payments
 
@@ -180,7 +180,7 @@ Assigning at runtime affects only the current process and is lost on restart. Se
 
 ## Deprecated settings
 
-These still exist so upgrades don't break, but Spree 6 either ignores them or reads them only from subsystems it has replaced. Don't use them in new code.
+These still exist so upgrades don't break, but Spree either ignores them or reads them only from subsystems it has replaced. Don't use them in new code.
 
 | Setting | Use instead |
 |---|---|
@@ -203,11 +203,11 @@ These still exist so upgrades don't break, but Spree 6 either ignores them or re
 | `tax_using_ship_address` | The `tax_using_ship_address` setting on the store |
 | `disable_store_presence_validation` | Every store-owned record now requires a store |
 
-> **WARNING:** These settings have no effect at all in Spree 6, and are scheduled for removal: `allow_checkout_on_gateway_error` (completion checks whether payments cover the total, so a failed gateway call never completes an order), `products_per_page`, `alternative_shipping_phone`, `show_variant_full_price`, `reserve_stock_on`, `storefront_products_path`, `storefront_taxons_path`, `storefront_pages_path`. Setting them changes nothing.
+> **WARNING:** These settings have no effect at all, and are scheduled for removal: `allow_checkout_on_gateway_error` (completion checks whether payments cover the total, so a failed gateway call never completes an order), `products_per_page`, `alternative_shipping_phone`, `show_variant_full_price`, `reserve_stock_on`, `storefront_products_path`, `storefront_taxons_path`, `storefront_pages_path`. Setting them changes nothing.
 
-## Settings removed in Spree 6
+## Settings that have been removed
 
-These were deprecated in Spree 5 and are gone. Assigning one in your initializer now raises `NoMethodError`, so delete the line.
+These settings are gone. Assigning one in your initializer now raises `NoMethodError`, so delete the line.
 
 | Setting | What to do instead |
 |---|---|

package/dist/developer/customization/dependencies.md

@@ -233,10 +233,10 @@ Spree::Dependencies.validate!
 # => true (or raises Spree::DependencyError)
 ```
 
-## Renamed seams in Spree 6.0
+## Seams backed by a workflow
 
-Seams backed by a [workflow](workflows.md) were renamed
-from `*_service` to `*_workflow` in 6.0:
+Seams backed by a [workflow](workflows.md) use a
+`*_workflow` name, not `*_service`:
 
 | Legacy name | Current name |
 |---|---|
@@ -249,14 +249,14 @@ from `*_service` to `*_workflow` in 6.0:
 | `fulfillment_create_service` | `fulfillment_create_workflow` |
 | `payments_handle_webhook_service` | `payments_handle_webhook_workflow` |
 
-> **WARNING:** The legacy names stay readable for one release, but **assigning to one no longer
-> has any effect** — the override is recorded and a deprecation warning names the
-> seam to port to. A class written against the old service contract isn't
-> interchangeable with the workflow the new call sites use, so applying it
-> silently would break checkout in ways that are hard to trace.
+> **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
+> port to. A class written against the old service contract isn't interchangeable
+> with the workflow the new call sites use, so applying it silently would break
+> checkout in ways that are hard to trace.
 > 
 > If you override any of these, move to the `*_workflow` name and make sure your
-> class subclasses the workflow. The legacy names are removed in Spree 6.1.
+> class subclasses the workflow.
 
 ## Backwards compatibility
 

package/dist/developer/customization/metadata.md

@@ -227,14 +227,14 @@ The Store API currently supports writing metadata on:
 
 ## Deprecation: public_metadata
 
-> **WARNING:** `public_metadata` is deprecated and will be removed in Spree 6.0. Use `metadata` instead.
+> **WARNING:** `public_metadata` is deprecated. Use `metadata` instead.
 
-The `public_metadata` column was never exposed in Store API responses and in practice served the same purpose as `private_metadata`. It will be removed in Spree 6.0 and calling `public_metadata=` will emit a deprecation warning.
+The `public_metadata` column was never exposed in Store API responses and in practice served the same purpose as `private_metadata`. Calling `public_metadata=` emits a deprecation warning.
 
 Always use the single `metadata` accessor for all schemaless key-value storage. If you need data visible to customers on the storefront, use [Metafields](../core-concepts/metafields.md) instead.
 
 ```ruby
-# Deprecated — will be removed in 6.0
+# Deprecated — use `metadata` instead
 order.public_metadata = { 'gift_message' => 'Happy Birthday!' }
 
 # Use metadata for internal storage

package/dist/developer/customization/quickstart.md

@@ -1,7 +1,7 @@
 ---
 title: Quickstart
 og:title: Spree Customization Quickstart
-description: Recommended ways to customize the Spree 6 backend — configuration, workflow hooks, events, checkout steps, providers, dependencies, and decorators as a last resort.
+description: Recommended ways to customize the Spree backend — configuration, workflow hooks, events, checkout steps, providers, dependencies, and decorators as a last resort.
 ---
 
 Spree is designed to be customized without forking it. This guide presents the options **in order of recommendation** — start at the top and only move down when a simpler option doesn't fit.
@@ -25,7 +25,7 @@ Spree is designed to be customized without forking it. This guide presents the o
 | Replace a whole workflow or service | [Dependencies](#dependencies) |
 | Add associations/validations to models | [Decorators](#decorators) (last resort) |
 
-> **INFO:** **Customizing the admin?** This page covers the backend — models, API and business logic. The Spree 6 admin is a separate React application with its own extension points. See [Dashboard Customization](../dashboard/customization/quickstart.md).
+> **INFO:** **Customizing the admin?** This page covers the backend — models, API and business logic. The admin is a separate React application with its own extension points. See [Dashboard Customization](../dashboard/customization/quickstart.md).
 
 **Best for:** currency, markets, delivery zones, languages, and other business settings.
 
@@ -50,7 +50,7 @@ Spree is designed to be customized without forking it. This guide presents the o
 
 **Best for:** running your own logic *inside* a core flow — checkout completion, order cancellation, refunds, fulfillment creation.
 
-    > **INFO:** Hooks are the **headline extension point in Spree 6**. Before them, customizing a flow meant replacing the entire class and keeping your copy in sync with core forever.
+    > **INFO:** Hooks are the **headline extension point in Spree**, so you don't have to replace an entire class and keep your copy in sync with core forever.
 
     Register a handler against a hook key — `<workflow key>.<hook name>`:
 
@@ -111,7 +111,7 @@ Spree is designed to be customized without forking it. This guide presents the o
 
 **Best for:** adding, removing or reordering checkout steps.
 
-    Spree 6 has no checkout state machine. A cart reports what it still needs, and you can add to that list:
+    Spree has no checkout state machine. A cart reports what it still needs, and you can add to that list:
 
     ```ruby config/initializers/spree.rb
     Spree::Checkout::Registry.register_step(
@@ -146,7 +146,7 @@ Spree is designed to be customized without forking it. This guide presents the o
 
 **Best for:** swapping a whole area of behavior for your own implementation.
 
-    Spree 6 exposes pluggable providers for the domains that vary most between businesses:
+    Spree exposes pluggable providers for the domains that vary most between businesses:
 
     | Provider | Controls |
     |---|---|
@@ -182,7 +182,7 @@ Spree is designed to be customized without forking it. This guide presents the o
 
 **Best for:** using your own user model or identity provider.
 
-    Spree 6 owns its authentication stack rather than depending on Devise, and separates the customer identity from the staff identity. Point Spree at your own classes with `Spree.customer_class` and `Spree.admin_user_class`.
+    Spree owns its authentication stack rather than depending on Devise, and separates the customer identity from the staff identity. Point Spree at your own classes with `Spree.customer_class` and `Spree.admin_user_class`.
 
     See [Authentication](../providers/sso.md).
 
@@ -208,7 +208,7 @@ Spree is designed to be customized without forking it. This guide presents the o
     Spree::Dependencies.cart_add_item_workflow = 'MyApp::Carts::AddItem'
     ```
 
-    > **WARNING:** Seam names end in `_workflow` in Spree 6. The old `*_service` names still resolve for one release with a warning, but **writes to them are ignored** — a class written against the old service contract isn't interchangeable with a workflow. Update the key when you upgrade.
+    > **WARNING:** Seam names end in `_workflow`. The old `*_service` names still resolve with a warning, but **writes to them are ignored** — a class written against the old service contract isn't interchangeable with a workflow. Update the key if your code still uses the old name.
 
     Prefer a hook when you only need to add behavior. Replace the class only when you need to change what the flow fundamentally does.
 

package/dist/developer/customization/validations.md

@@ -162,7 +162,7 @@ Spree::Checkout::Registry.add_requirement(
 )
 ```
 
-See the [Spree 6 quickstart](quickstart.md) for the full registry API.
+See the [customization quickstart](quickstart.md) for the full registry API.
 
 ## Custom field values
 

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

@@ -4,6 +4,8 @@ sidebarTitle: Backend integration
 description: Talk to your own (or Spree's) Admin API from the dashboard — typed SDK calls, custom endpoints, prefixed IDs, error handling, and React-Query hooks.
 ---
 
+> **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 never reaches into Rails models or fetches HTML. All data flows through `@spree/admin-sdk` — a typed Admin API client. This page covers the patterns: calling existing endpoints, adding new ones, handling errors, and wrapping it all in React-Query hooks for caching.
 
 ## The `adminClient`
@@ -11,7 +13,7 @@ The dashboard never reaches into Rails models or fetches HTML. All data flows th
 The SPA boots a single `adminClient` instance and exposes it from `@spree/dashboard-core`. Resource methods follow `client.<resource>.<verb>()`:
 
 ```ts
-import { adminClient } from '@spree/dashboard-core'
+import { adminClient } from '@spree/dashboard'
 
 await adminClient.products.list({ filter: { name_cont: 'shirt' } })
 await adminClient.products.get('prod_86Rf07xd4z', { expand: ['variants'] })
@@ -50,7 +52,7 @@ 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-core'
+import { adminClient } from '@spree/dashboard'
 import { useQuery } from '@tanstack/react-query'
 import type { AdminBrand } from './types'
 
@@ -67,7 +69,8 @@ export function useBrands(params?: { search?: string }) {
 For mutations, prefer the existing `useResourceMutation` helper — it wires up the SDK's error shape, the 422 silencer, and the toast for non-validation errors:
 
 ```ts
-import { useResourceMutation } from '@spree/dashboard-core'
+import type { AdminBrand } from '@spree/admin-sdk'
+import { adminClient, useResourceMutation } from '@spree/dashboard'
 
 export function useUpdateBrand(id: string) {
   return useResourceMutation({
@@ -100,7 +103,7 @@ try {
 In a React Hook Form submit handler, prefer the higher-level helper:
 
 ```tsx
-import { mapSpreeErrorsToForm } from '@spree/dashboard-core'
+import { mapSpreeErrorsToForm } from '@spree/dashboard'
 
 async function handleSubmit(values: FormValues) {
   try {

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

@@ -4,6 +4,8 @@ sidebarTitle: Navigation
 description: Add, modify, and remove items from the dashboard's main sidebar and settings sub-nav.
 ---
 
+> **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 has two navigation registries: **main sidebar** (`nav`) and **settings sub-shell** (`settingsNav`). Both are module singletons exposed from `@spree/dashboard-core` and consumed by `<AppSidebar>` and `<SettingsSidebar>` via `useSyncExternalStore`, so late registration re-renders the sidebars automatically.
 
 ## Main sidebar (`nav`)
@@ -11,7 +13,7 @@ The dashboard has two navigation registries: **main sidebar** (`nav`) and **sett
 ### Add an entry
 
 ```ts
-import { nav } from '@spree/dashboard-core'
+import { nav } from '@spree/dashboard'
 import { BarChartIcon } from 'lucide-react'
 
 nav.add({
@@ -31,7 +33,7 @@ nav.add({
 The facade groups multiple registry calls:
 
 ```ts
-import { defineDashboardPlugin } from '@spree/dashboard-core'
+import { defineDashboardPlugin } from '@spree/dashboard'
 
 defineDashboardPlugin({
   nav: [
@@ -156,7 +158,7 @@ The settings page has its own sub-shell sidebar with grouped entries (Store, Loc
 ### Register a group
 
 ```ts
-import { settingsNav } from '@spree/dashboard-core'
+import { settingsNav } from '@spree/dashboard'
 
 settingsNav.addGroup({
   key: 'integrations',

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

@@ -4,6 +4,8 @@ sidebarTitle: Permissions
 description: How to hide UI behind CanCanCan 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`.
 
 ## Two layers
@@ -88,7 +90,7 @@ Use it for combined checks (permission + store state), feature flags, multi-acti
 Use the `usePermissions()` hook — it returns `{ permissions, rules, isLoading }`:
 
 ```tsx
-import { usePermissions } from '@spree/dashboard-core'
+import { usePermissions } from '@spree/dashboard'
 
 function ReportsPage() {
   const { permissions } = usePermissions()

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

@@ -18,7 +18,7 @@ Add an "Analytics" item to the dashboard sidebar.
 **Step 1.** Open `src/plugins.ts` — the starter ships this file already wired up — and register a nav entry:
 
 ```tsx
-import { defineDashboardPlugin } from '@spree/dashboard-core'
+import { defineDashboardPlugin } from '@spree/dashboard'
 import { BarChartIcon } from 'lucide-react'
 
 defineDashboardPlugin({
@@ -43,8 +43,7 @@ Clicking it lands on a "Page not found" screen — we registered the nav entry b
 **Step 3.** Create the page component at `src/pages/analytics.tsx`:
 
 ```tsx
-import { PageHeader } from '@spree/dashboard-core'
-import { ResourceLayout } from '@spree/dashboard-ui'
+import { PageHeader, ResourceLayout } from '@spree/dashboard'
 
 export function AnalyticsPage() {
   return (
@@ -59,7 +58,7 @@ export function AnalyticsPage() {
 **Step 4.** Register the route in `src/plugins.ts`:
 
 ```tsx
-import { defineDashboardPlugin } from '@spree/dashboard-core'
+import { defineDashboardPlugin } from '@spree/dashboard'
 import { BarChartIcon } from 'lucide-react'
 import { AnalyticsPage } from './pages/analytics'
 

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

@@ -4,6 +4,8 @@ sidebarTitle: Routes
 description: Mount custom pages under your dashboard's `/$storeId/...` path. Supports path params, permission gating, and works alongside the dashboard's built-in routes.
 ---
 
+> **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's first-party routes (`customers/`, `orders/`, `products/`, …) are file-based via TanStack Router and live in `@spree/dashboard/src/routes/`. Custom pages have two mechanisms:
 
 1. **File routes** (packaged plugins — preferred): the plugin ships ordinary TanStack route files, and the host build compiles them into its typed route tree. Typed `<Link>`s with no casts, route-level code splitting, `validateSearch`, loaders — full router citizenship.
@@ -28,7 +30,7 @@ src/
 
 ```tsx
 // src/routes/brands.index.tsx
-import { resourceSearchSchema } from '@spree/dashboard-core'
+import { resourceSearchSchema } from '@spree/dashboard'
 import { createFileRoute } from '@tanstack/react-router'
 import { BrandsListPage } from '../pages/brands-list'
 
@@ -70,7 +72,7 @@ Rename one of the routes, or drop the plugin that shouldn't own it. (Duplicate p
 Register from your host app's `plugins.ts` (or a plugin that genuinely needs runtime registration):
 
 ```tsx
-import { defineDashboardPlugin } from '@spree/dashboard-core'
+import { defineDashboardPlugin } from '@spree/dashboard'
 import { ReportsPage } from './pages/reports'
 
 defineDashboardPlugin({
@@ -119,7 +121,7 @@ function ReportDetailPage({ params, storeId, searchParams }: PluginRouteProps) {
 `searchParams` is typed as `Record<string, unknown>` because the dispatcher can't statically know your page's shape. If you're handing it to `<ResourceTable>`, cast to `ResourceSearch`:
 
 ```tsx
-import type { ResourceSearch } from '@spree/dashboard-core'
+import type { ResourceSearch } from '@spree/dashboard'
 
 <ResourceTable searchParams={searchParams as ResourceSearch} ... />
 ```
@@ -143,11 +145,10 @@ Always pair this with a matching `subject` on the **nav entry** so users without
 
 ## Layout
 
-Custom routes inherit the dashboard's `_authenticated` + `$storeId` layout (auth guard, sidebar, top bar, etc.) — your component renders inside the `<Outlet />`. Use `<ResourceLayout>` from `@spree/dashboard-ui` to get the same header/main/sidebar grid as core pages:
+Custom routes inherit the dashboard's `_authenticated` + `$storeId` layout (auth guard, sidebar, top bar, etc.) — your component renders inside the `<Outlet />`. Use `<ResourceLayout>` to get the same header/main/sidebar grid as core pages:
 
 ```tsx
-import { PageHeader } from '@spree/dashboard-core'
-import { ResourceLayout } from '@spree/dashboard-ui'
+import { PageHeader, ResourceLayout } from '@spree/dashboard'
 
 function ReportsPage() {
   return (

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

@@ -4,6 +4,8 @@ sidebarTitle: Slots
 description: Inject your own widgets into existing dashboard pages without forking them. Slots are named injection points the dashboard exposes on built-in pages.
 ---
 
+> **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).
+
 A slot is a named injection point in a built-in page. Components registered against a slot render inside it, sorted by `position`, gated by an optional `if` predicate. The host page knows nothing about your widget — it just renders `<Slot name="..." context={...} />` and the slot registry handles the rest.
 
 ## Quick example
@@ -11,8 +13,7 @@ A slot is a named injection point in a built-in page. Components registered agai
 Render a card with the current user's email in every page's actions dropdown:
 
 ```tsx
-import { defineDashboardPlugin } from '@spree/dashboard-core'
-import { DropdownMenuItem } from '@spree/dashboard-ui'
+import { DropdownMenuItem, defineDashboardPlugin } from '@spree/dashboard'
 
 function UserBadge({ user }: { user?: { email: string } }) {
   if (!user) return null
@@ -45,7 +46,7 @@ For anything beyond the slot's own context — permissions, the current store, t
 If you'd rather have full type safety, call `registerSlot` directly with the explicit type parameter:
 
 ```tsx
-import { registerSlot } from '@spree/dashboard-core'
+import { registerSlot } from '@spree/dashboard'
 
 interface ProductSlotContext {
   product: { id: string; brand_id?: string | null }
@@ -63,7 +64,7 @@ registerSlot<ProductSlotContext>('product.form_sidebar', {
 Gate inside the component with `usePermissions()` — return `null` when the user lacks access:
 
 ```tsx
-import { usePermissions } from '@spree/dashboard-core'
+import { usePermissions } from '@spree/dashboard'
 
 function AdminOnlyMenuItem() {
   const { permissions } = usePermissions()
@@ -79,7 +80,7 @@ The entry-level `if` predicate also exists, but it only receives the slot's own
 Slots on form pages (product, category, store settings — see the [slots catalog](../slots-catalog.md#detail-page-form-slots) for which) render **inside the page's `<form>`** and expose its react-hook-form instance. A widget can register inputs against it with `useHostForm()` — they hydrate from the API, flip the Save button on change, and persist in the page's own save, with no save logic in the widget:
 
 ```tsx
-import { useHostForm } from '@spree/dashboard-core'
+import { useHostForm } from '@spree/dashboard'
 
 function TechSpecsCard() {
   const form = useHostForm<{ tech_specs: string }>()
@@ -96,7 +97,7 @@ Pair it with a `formFields` registration so the field hydrates and ships in the
 ## Removing or updating an entry
 
 ```ts
-import { removeSlot, updateSlot } from '@spree/dashboard-core'
+import { removeSlot, updateSlot } from '@spree/dashboard'
 
 removeSlot('product.form_sidebar', 'brand-card')
 updateSlot('product.form_sidebar', 'brand-card', { position: 999 })

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

@@ -4,6 +4,8 @@ sidebarTitle: Tables
 description: Add, change, or remove columns on built-in list tables (products, orders, customers, …), or define a table for your own resource.
 ---
 
+> **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).
+
 Every list page in the dashboard renders through `<ResourceTable>`, which reads its column definitions from a **table registry** keyed by table name (`products`, `orders`, `customers`, …). That gives you two levers:
 
 1. **Extend a built-in table** — add, patch, or remove columns (including their filters) without forking the page.
@@ -14,7 +16,7 @@ Every list page in the dashboard renders through `<ResourceTable>`, which reads
 Imperatively, from `src/plugins.ts` (or a plugin entry):
 
 ```tsx
-import { tables } from '@spree/dashboard-core'
+import { tables } from '@spree/dashboard'
 
 tables.products.addColumn({
   key: 'brand',
@@ -117,7 +119,7 @@ Filtering and sorting are executed by the Admin API (Ransack), not in the browse
 For your own list page, declare the table once — typically right next to your `defineDashboardPlugin` call:
 
 ```tsx
-import { defineTable } from '@spree/dashboard-core'
+import { defineTable } from '@spree/dashboard'
 
 defineTable<Brand>('brands', {
   title: 'Brands',

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

@@ -4,12 +4,14 @@ sidebarTitle: Translations
 description: Add your own i18n strings to the dashboard so labels, validation messages, and notifications respect the admin's chosen locale.
 ---
 
+> **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 uses [i18next](https://www.i18next.com/) with the `react-i18next` bindings. All strings live in i18next's default `translation` namespace, with every key under a top-level `admin.` prefix (`admin.nav.orders`, `admin.fields.<resource>.<attribute>.label`, …). You register your strings into the same namespace with the same prefix so they look and feel native.
 
 ## Add translations
 
 ```ts
-import { i18n } from '@spree/dashboard-core'
+import { i18n } from '@spree/dashboard'
 
 i18n.addResourceBundle('en', 'translation', {
   admin: {
@@ -126,7 +128,7 @@ Register translations **before** any code that calls `i18n.t()` at module-load t
 
 ```tsx
 // src/plugins.ts (same pattern in a plugin package's entry module)
-import { defineDashboardPlugin, i18n } from '@spree/dashboard-core'
+import { defineDashboardPlugin, i18n } from '@spree/dashboard'
 
 i18n.addResourceBundle('en', 'translation', en, true, true)  // ① translations first
 

package/dist/developer/dashboard/overview.md

@@ -4,8 +4,7 @@ sidebarTitle: Overview
 description: Learn about the Spree React Dashboard architecture and how to customize it and extend it
 ---
 
-> **INFO:** The React Dashboard is currently a **Developer Preview** — APIs may still change between releases. 
-> In Spree 6 it will become the default Admin interface replacing the Spree 5 admin.
+> **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:
 
@@ -32,7 +31,9 @@ Dashboard consinsts of 3 NPM packages, each with a different purpose. You can im
 | `@spree/dashboard-core` | Framework: registries (nav, route, slot, table, settings-nav), providers (auth, permission, store), admin SDK client, infra hooks, the `defineDashboardPlugin` API | Extending the admin — every customization API lives here |
 | `@spree/dashboard` | The deployable SPA: routes, resource hooks, schemas, locale strings, app shell | Replacing or restyling specific routes (rare) |
 
-Most customization happens via `@spree/dashboard-core`. You import its registries from your own host-app code (or from a separate plugin package) to add nav entries, routes, slot widgets, table columns, and translations.
+Most customization uses the registries in `@spree/dashboard-core` to add nav entries, routes, slot widgets, table columns and translations.
+
+**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.
 
@@ -55,7 +56,7 @@ You're building a Spree store and want a "Featured products" page or a custom ca
 
 ```tsx
 // src/plugins.ts — already imported by the app; just add your registrations
-import { defineDashboardPlugin } from '@spree/dashboard-core'
+import { defineDashboardPlugin } from '@spree/dashboard'
 import { MyAnalyticsPage } from './pages/analytics'
 
 defineDashboardPlugin({

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

@@ -195,7 +195,15 @@ import { cn } from '@spree/dashboard-ui'  // clsx + tailwind-merge
 
 ## `@spree/dashboard`
 
-The app shell. **Plugins don't import from here** — a plugin extends the dashboard through `@spree/dashboard-core` and never renders the shell. The host (the `dashboard-starter` project, or a create-spree-app project) is what imports it, to mount the admin:
+The app shell, and the single import a host application needs. It re-exports everything from `@spree/dashboard-core` and `@spree/dashboard-ui`, so code in your own dashboard app never has to work out which package an export lives in:
+
+```ts
+import { defineDashboardPlugin, useStore, adminClient, Button, ResourceTable } from '@spree/dashboard'
+```
+
+**Plugins don't import from here** — a plugin extends the dashboard through `@spree/dashboard-core` and never renders the shell, so importing the shell would pull the whole app into a package meant to plug into it.
+
+The host (the `dashboard-starter` project, or a create-spree-app project) is also what mounts the admin:
 
 ```ts
 import { createDashboardRouter, Dashboard } from '@spree/dashboard'
@@ -211,7 +219,13 @@ import { spreeDashboardPlugin } from '@spree/dashboard/vite'  // Vite plugin: Ta
 import '@spree/dashboard/styles.css'                          // the app's CSS entry
 ```
 
-Importing from `@spree/dashboard` pins your code to the deployable app's version. Plugins and custom UI should prefer `@spree/dashboard-core` + `@spree/dashboard-ui`.
+A few names exist in both re-exported packages — the design system ships a presentational component and the framework wraps it with data (`ResourceCombobox`, `StatusCard`, `Slot`, `DateRange`, `ResourceMultiAutocomplete`). The facade gives you the framework's version, which is the one an application wants. Reach past it when you want the presentational half:
+
+```ts
+import { ResourceCombobox } from '@spree/dashboard-ui'  // takes its options as props
+```
+
+Importing from `@spree/dashboard` pins your code to the deployable app's version, which is what a host app wants and what a distributed plugin must avoid.
 
 ## What about `@spree/admin-sdk`?