@spree/docs 0.1.81 → 0.1.83

package/dist/api-reference/store-api/errors.md

@@ -1,6 +1,6 @@
 ---
 title: Errors
-description: Error response format, error codes, and handling strategies
+description: Reference for Spree Store API error responses — JSON format, machine-readable codes, HTTP status codes, validation details, and retry strategies.
 ---
 
 The Store API uses a consistent, Stripe-style error format across all endpoints. Every error response includes a machine-readable `code` and a human-readable `message`.
@@ -145,7 +145,7 @@ Validation errors include an additional `details` field with per-field error mes
 
 ```bash
 curl https://api.mystore.com/api/v3/store/products/prod_nonexistent \
-  -H "Authorization: Bearer pk_xxx"
+  -H "X-Spree-API-Key: pk_xxx"
 ```
 
 ```json 404
@@ -185,7 +185,7 @@ curl -X POST https://api.mystore.com/api/v3/store/account/addresses \
 
 ```bash
 curl -X POST https://api.mystore.com/api/v3/store/carts/cart_xxx/items \
-  -H "Authorization: Bearer pk_xxx" \
+  -H "X-Spree-API-Key: pk_xxx" \
   -H "X-Spree-Token: abc123" \
   -H "Content-Type: application/json" \
   -d '{"variant_id": "var_xxx", "quantity": 999}'
@@ -204,7 +204,7 @@ curl -X POST https://api.mystore.com/api/v3/store/carts/cart_xxx/items \
 
 ```bash
 curl -X POST https://api.mystore.com/api/v3/store/carts/cart_xxx/complete \
-  -H "Authorization: Bearer pk_xxx"
+  -H "X-Spree-API-Key: pk_xxx"
 ```
 
 ```json 422

package/dist/api-reference/store-api/idempotency.md

@@ -1,7 +1,7 @@
 ---
 title: "Idempotency"
 sidebarTitle: "Idempotency"
-description: "Prevent duplicate operations with idempotency keys"
+description: "Use Idempotency-Key headers on Spree Store API mutations to safely retry carts, checkouts, and payments without creating duplicate side effects."
 ---
 
 The Store API supports idempotency keys on mutating endpoints. This lets you safely retry requests without risking duplicate side effects — for example, adding an item to cart twice or creating duplicate payments due to network timeouts.
@@ -16,7 +16,7 @@ Include an `Idempotency-Key` header with a unique value (e.g., a UUID) on any su
 
 ```bash
 curl -X POST https://api.mystore.com/api/v3/store/carts/cart_xxx/items \
-  -H "Authorization: Bearer pk_xxx" \
+  -H "X-Spree-API-Key: pk_xxx" \
   -H "X-Spree-Token: abc123" \
   -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
   -H "Content-Type: application/json" \

package/dist/developer/cli/quickstart.md

@@ -1,7 +1,7 @@
 ---
 title: Spree CLI
 sidebarTitle: Overview
-description: Manage your Spree Commerce project from the command line.
+description: Install and use the @spree/cli to scaffold, run, build, migrate, and upgrade Docker-based Spree Commerce projects from the command line.
 ---
 
 The Spree CLI (`@spree/cli`) manages Docker-based Spree projects created with [create-spree-app](../create-spree-app/quickstart.md).
@@ -40,7 +40,7 @@ spree init --no-open           # Skip opening browser
 
 ### `spree dev`
 
-Start services and stream logs.
+Run the app in the foreground — streams web + worker logs; `Ctrl+C` stops them. The databases keep running for a fast next boot (`spree stop` shuts everything down).
 
 ```bash
 spree dev
@@ -54,6 +54,16 @@ Stop all services.
 spree stop
 ```
 
+### `spree restart`
+
+Restart `web` and `worker` in place — same image, same volumes, fresh Rails process. Good for `config/initializers/*.rb` changes or anything Zeitwerk doesn't auto-reload.
+
+```bash
+spree restart
+```
+
+Not appropriate for Gemfile changes (use `spree bundle install`, then Ctrl+C and re-run `spree dev`), Dockerfile / `.ruby-version` changes (use `spree build`), or compose file changes (Ctrl+C and re-run `spree dev`).
+
 ### `spree update`
 
 Pull the latest Spree Docker image and recreate containers. Migrations run automatically on startup.
@@ -62,6 +72,34 @@ Pull the latest Spree Docker image and recreate containers. Migrations run autom
 spree update
 ```
 
+### `spree build`
+
+Rebuild the dev image after Dockerfile or `.ruby-version` changes. Only relevant after `spree eject`.
+
+```bash
+spree build
+spree build --reset-bundle   # Also drop the bundle_cache volume so gems re-seed
+spree build --yes            # Skip confirmation prompts (for CI)
+```
+
+`spree bundle add` does NOT require a rebuild — gems land in the `bundle_cache` volume which survives image rebuilds.
+
+`--reset-bundle` only drops `bundle_cache`. Postgres, Redis, Meilisearch, and storage volumes are preserved.
+
+### `spree upgrade`
+
+Walk a Spree version upgrade end-to-end inside the dev stack. Runs `bundle update`, applies pending migrations, then walks the version-specific data backfills from the upgrade manifest.
+
+```bash
+spree upgrade                  # Detect target, run the full sequence interactively
+spree upgrade --plan           # Print the plan without executing (DRY_RUN=1)
+spree upgrade --to 5.5         # Cap the walk at a specific target version
+spree upgrade --step <id>      # Re-run a single step idempotently (skips bundle + migrate)
+spree upgrade --yes            # Skip the per-step prompts
+```
+
+Production upgrades only need the third stage — `bundle install` and `db:migrate` happen in your deploy pipeline. The CLI runs all three for local development. See [Upgrades](../upgrades.md) for the manual production path.
+
 ### `spree eject`
 
 Switch from the prebuilt Docker image to building from your local `backend/` directory. This lets you customize the Rails app — add gems, override models, add migrations, etc.
@@ -135,3 +173,113 @@ spree api-key create --name "Storefront" --type publishable  # Store API key
 spree api-key create --name "Admin" --type secret            # Admin API key
 spree api-key revoke <id>                              # Revoke a key
 ```
+
+## Dev workflow commands
+
+These mirror the Rails commands you'd run if you were running the app directly on your host — but each is routed through `docker compose exec` against the running stack.
+
+### `spree generate`
+
+Run a generator inside the container. Bare generator names are auto-prefixed with `spree:` — `model` runs `spree:model`, `api_resource` runs `spree:api_resource` — so you get the Spree conventions (`Spree::` namespace, `spree_`-prefixed table, prefixed IDs, `null: false`, no FK constraints) by default. Rails built-ins (`migration`, `scaffold`, `mailer`, `job`, …) and any name containing `:` are forwarded as-is.
+
+```bash
+spree generate model Brand name:string slug:string:uniq          # runs spree:model
+spree generate api_resource Brand name:string slug:string:uniq   # runs spree:api_resource — model + v3 Store/Admin API
+spree generate migration AddPositionToSpreeBrands position:integer  # Rails built-in, forwarded as-is
+```
+
+`spree:api_resource` scaffolds the full v3 surface: model, migration, Store + Admin controllers and serializers, factory, controller specs, and routes.
+
+### `spree migrate`
+
+Install pending Spree migrations from gems, then run `db:migrate` — the canonical post-update sequence.
+
+```bash
+spree migrate
+spree migrate:status            # show the migration log (`db:migrate:status`)
+spree migrate:rollback STEP=2   # roll back (`db:rollback`)
+```
+
+### `spree db:reset`
+
+Drop, recreate, migrate, and seed the database. **Destructive** — wipes everything. Asks for confirmation.
+
+```bash
+spree db:reset
+spree db:reset --yes   # Skip confirmation (for CI)
+```
+
+### `spree db:console`
+
+Open a `psql` session against the dev Postgres database (runs inside the `postgres` container).
+
+```bash
+spree db:console
+```
+
+### `spree routes`
+
+Show Rails routes. All flags pass through to `bin/rails routes`.
+
+```bash
+spree routes
+spree routes -g products                                 # Filter by pattern
+spree routes -c Spree::Api::V3::Store::ProductsController   # Filter by controller
+spree routes --expanded
+```
+
+## Running things inside the container
+
+These are passthrough commands — anything after the subcommand reaches the inner Rails/Bundle/Rake invocation as-is. Useful for ad-hoc commands that don't have a dedicated wrapper.
+
+### `spree exec`
+
+Run an arbitrary command inside the `web` container.
+
+```bash
+spree exec ls -la
+spree exec env
+spree exec ruby -v
+```
+
+### `spree rails`
+
+Run a `bin/rails` command.
+
+```bash
+spree rails c                                  # Console (alias of `spree console`)
+spree rails routes -g products                 # Alias of `spree routes -g products`
+spree rails runner "puts Spree::Product.count"
+spree rails new_subcommand arg1 arg2
+```
+
+### `spree bundle`
+
+Run a `bundle` command. Gems land in the `bundle_cache` volume (no image rebuild needed).
+
+```bash
+spree bundle install
+spree bundle add stripe
+spree bundle update spree_core
+spree bundle outdated
+```
+
+### `spree rake`
+
+Run a Rake task.
+
+```bash
+spree rake -T                          # List tasks
+spree rake spree:upgrade               # Run the version-specific data backfills
+spree rake spree:upgrade DRY_RUN=1     # Same, plan only
+```
+
+### `spree task`
+
+Shortcut for `bin/rails <task>` (Spree-style rake tasks registered as Rails tasks).
+
+```bash
+spree task load_sample_data
+spree task spree:price_history:seed
+spree task spree:price_history:prune
+```

package/dist/developer/contributing/creating-an-extension.md

@@ -1,6 +1,6 @@
 ---
 title: Creating an Extension
-description: Learn how to create a Spree extension.
+description: Step-by-step guide to building a Spree extension gem — scaffolding, decorators, migrations, assets, and packaging for distribution.
 ---
 
 ## Overview
@@ -248,7 +248,7 @@ module MyExtension
     subscribes_to 'product.updated'
 
     def handle(event)
-      product = Spree::Product.find_by(id: event.payload['id'])
+      product = Spree::Product.find_by_prefix_id(event.payload['id'])
       return unless product
 
       ExternalService.sync(product)

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

@@ -1,10 +1,10 @@
 ---
 title: Developing Spree
-description: >-
-  This guide covers all the necessary steps to contributing to Spree source
-  code. We're happy you're here!
+description: Set up a Spree development environment with Docker, run the test suite, and submit pull requests to contribute to the Spree Commerce source code.
 ---
 
+Please read our [Code of Conduct](https://github.com/spree/spree/blob/main/CODE_OF_CONDUCT.md) before contributing.
+
 ## Cloning the repository
 
 Spree is a big monorepo. For a faster clone, use a **partial clone** which downloads file contents on demand while keeping full commit history for `git log` and `git blame`:
@@ -24,66 +24,98 @@ You need **Node.js 20+** to run the workspace scripts (including `pnpm server:se
 Spree is a monorepo with three main areas:
 
 - **`spree/`** — Ruby gems (core, api, admin, emails) distributed as separate packages via RubyGems
-- **`packages/`** — TypeScript packages (SDKs, CLI, project scaffolding, docs)
-- **`server/`** — A Rails application cloned from [spree-starter](https://github.com/spree/spree-starter) that mounts the Spree gems (not checked in — run `pnpm server:setup` to create it)
+- **`packages/`** — TypeScript packages (SDKs, CLI, project scaffolding, docs, React dashboard)
+- **`server/`** — A Rails application cloned from [spree-starter](https://github.com/spree/spree-starter) that mounts the local Spree gems (not checked in — `pnpm server:setup` creates it)
 
-## Backend Development (Ruby)
+## Setup
 
-### Engines overview
+A single command bootstraps the whole monorepo for both backend and frontend work. You need **Docker** running locally (Docker Desktop, OrbStack, or any compatible runtime) — no Ruby, Postgres, or Redis on your host.
 
-The Spree [Rails engines](https://guides.rubyonrails.org/engines.html) live inside `spree/` and are distributed as separate gems (Ruby packages installed via Bundler):
+```bash
+pnpm install        # workspace dependencies
+pnpm server:setup   # ~5–10 min on first run; idempotent
+```
 
-| Engine | Gem | Description |
-|---|---|---|
-| `core` | `spree_core` | Models, services, business logic |
-| `api` | `spree_api` | REST APIs |
-| `admin` | `spree_admin` | Admin dashboard |
-| `emails` | `spree_emails` | Transactional emails |
+`pnpm server:setup` clones [spree-starter](https://github.com/spree/spree-starter) into `./server/`, wires it to load Spree gems from the monorepo via a Docker compose overlay, builds the dev image, starts the stack (Postgres + Redis + Meilisearch + Rails `web` + Sidekiq `worker`), and prepares the database. The full sequence lives in `scripts/server-setup.sh`.
 
-### Spree namespace
+When it's done, the backend is up at [http://localhost:3000](http://localhost:3000) and the admin is at [http://localhost:3000/admin](http://localhost:3000/admin). Sign in with the seed admin: **`spree@example.com`** / **`spree123`** (override at seed time with `ADMIN_EMAIL` / `ADMIN_PASSWORD` env vars — see `spree/core/app/services/spree/seeds/admin_user.rb`).
 
-All Spree models, controllers and other Ruby classes are namespaced by the `Spree` keyword, eg. `Spree::Product`. This means that those files are also located in `spree` sub-directories eg. [app/models/spree/product.rb](https://github.com/spree/spree/blob/main/spree/core/app/models/spree/product.rb).
+Optionally load sample products, taxonomies, and option types:
 
-### Setup
+```bash
+pnpm server:load_sample_data
+```
 
-The server app is not checked into the monorepo. It's cloned from [spree-starter](https://github.com/spree/spree-starter) on first setup, with `SPREE_PATH=..` automatically configured so it uses your local Spree gems.
+## Running a backend day-to-day
 
-**Step 1: Clone the server app**
+After the one-time setup, use these to bring the stack up and down:
 
 ```bash
-pnpm server:setup
+pnpm server:dev     # run the stack in the foreground — streams web + worker logs, Ctrl+C stops them
+pnpm server:stop    # full teardown (also stops postgres / redis / meilisearch)
+pnpm server:restart # restart web + worker in place
+pnpm server:logs    # follow web container logs (when the stack runs detached)
+pnpm server:console # open a Rails console inside the container
+pnpm server:seed    # re-run database seeds
+pnpm server:build   # rebuild the dev image (only after Dockerfile / .ruby-version changes)
 ```
 
-This clones [spree-starter](https://github.com/spree/spree-starter) into `server/` and sets `SPREE_PATH=..` in `server/.env` so it uses your local Spree gems.
+`server:dev` behaves like any TS dev server (`vite dev`, the dashboard's `pnpm dev`): it runs in the foreground and Ctrl+C stops the app containers. Postgres, Redis, and Meilisearch keep running for a fast next boot — `pnpm server:stop` shuts everything down.
 
-**Step 2: Configure and run**
+Run any CLI command against the running backend from `server/`:
 
 ```bash
 cd server
-# Edit .env if needed (e.g. DATABASE_USERNAME, DATABASE_HOST, DATABASE_PORT)
-bin/setup        # installs Ruby (via mise), Postgres/Redis/Meilisearch (via brew), gems, prepares database
-bin/dev          # starts Rails + Sidekiq + CSS watchers via overmind
+pnpm exec spree migrate
+pnpm exec spree generate model Brand name:string
+pnpm exec spree upgrade --plan
 ```
 
-`bin/setup` installs system services natively (PostgreSQL, Redis, Meilisearch) via `brew bundle` on macOS or `apt-get` on Linux. If you'd rather run those services in Docker, start them from the repo root before running `bin/setup`:
+See the [`@spree/cli` README](https://github.com/spree/spree/blob/main/packages/cli/README.md) for the full command surface.
 
-```bash
-docker compose up -d postgres redis meilisearch
-```
+Which command after which change:
 
-Use `bin/setup --reset` to drop and recreate the database.
+| What changed | What to run |
+|---|---|
+| Ruby code in `spree/*` gems | Nothing — gems are bind-mounted; code reloads on the next request |
+| A new migration in a gem | `cd server && pnpm exec spree migrate` |
+| Gem dependencies (gemspec / Gemfile) | `cd server && pnpm exec spree bundle install` (persists in the `bundle_cache` volume) |
+| Compose files / `server/.env` | `pnpm server:dev` (force-recreates the containers) |
+| `server/Dockerfile` / `.ruby-version` | `pnpm server:build`, then `pnpm server:dev` |
+| Broken beyond repair | `pnpm server:setup` (full reset — wipes the database and volumes) |
 
-The app runs at [http://localhost:3000](http://localhost:3000). Admin Panel is at [http://localhost:3000/admin](http://localhost:3000/admin).
+Re-run `pnpm server:setup` **only** to fully reset — it does `docker compose down -v` + `rm -rf ./server`, wiping all DB data.
 
-**Step 3 (optional): Load sample data**
+## Native Ruby (advanced)
 
-To populate your store with sample products, customers, orders, and configuration:
+If you prefer the fastest possible inner loop and don't mind installing Ruby, Postgres, Redis, and Meilisearch on your host directly, you can skip Docker:
 
 ```bash
-pnpm server:load_sample_data    # from repo root
-# or, from server/: bin/rails spree:load_sample_data
+pnpm server:create   # clones spree-starter, writes server/.env with SPREE_PATH=..
+cd server
+bin/setup            # installs Ruby (via mise), Postgres/Redis/Meilisearch (via brew bundle on macOS), gems, prepares the database
+bin/dev              # starts Rails + Sidekiq + CSS watchers via Foreman
 ```
 
+This path is faster per request but means more on your host. It also runs against your installed system services, not a sandboxed Docker stack.
+
+## Backend Development (Ruby)
+
+### Engines overview
+
+The Spree [Rails engines](https://guides.rubyonrails.org/engines.html) live inside `spree/` and are distributed as separate gems (Ruby packages installed via Bundler):
+
+| Engine | Gem | Description |
+|---|---|---|
+| `core` | `spree_core` | Models, services, business logic |
+| `api` | `spree_api` | REST APIs |
+| `admin` | `spree_admin` | Admin dashboard |
+| `emails` | `spree_emails` | Transactional emails |
+
+### Spree namespace
+
+All Spree models, controllers and other Ruby classes are namespaced by the `Spree` keyword, eg. `Spree::Product`. This means that those files are also located in `spree` sub-directories eg. [app/models/spree/product.rb](https://github.com/spree/spree/blob/main/spree/core/app/models/spree/product.rb).
+
 ### Running engine tests
 
 Each engine has its own test suite. First install the shared dependencies at the `spree/` level, then navigate into the specific engine to set up and run its tests:
@@ -148,9 +180,9 @@ bundle exec parallel_rspec -n 4 spec
 
 After schema changes, re-run `bundle exec rake parallel_setup` to update the worker databases.
 
-### Integration tests (Admin Panel)
+### Integration tests (legacy Rails admin)
 
-The Admin Panel uses feature specs that run in a real browser via chromedriver. You only need this if you're working on admin UI changes.
+The legacy Rails admin (`spree/admin`) ships feature specs that run in a real browser via chromedriver. You only need this if you're touching the legacy admin UI.
 
 Install chromedriver on macOS:
 
@@ -158,47 +190,35 @@ Install chromedriver on macOS:
 brew install chromedriver
 ```
 
-### Performance in development mode
+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.
 
-You may notice that your Spree store runs slower in development environment. This is caused by disabled caching and automatic reloading of code after each change.
+### Performance in development mode
 
-Caching is disabled by default. To turn on caching please run:
+Spree runs slower in development because caching is disabled and code reloads on each request. To turn on caching:
 
 ```bash
-cd server && bin/rails dev:cache
+cd server && pnpm exec spree rails dev:cache
 ```
 
-You will need to restart rails server after this change.
+Restart the Rails server after running this (Ctrl+C the running `pnpm server:dev` and start it again).
 
 ## TypeScript Development
 
-### Setup
-
-TypeScript developers don't need Ruby installed. Docker Compose from the repository root starts the backend using a prebuilt image:
-
-```bash
-docker compose up -d
-```
-
-This boots PostgreSQL, Redis, Meilisearch, and the Spree backend automatically (no `pnpm server:setup` needed). The API is available at `http://localhost:3000`.
-
-Then install dependencies and start all packages in watch mode:
-
-```bash
-pnpm install
-pnpm dev
-```
+The backend setup is the same as for Ruby work — see [Setup](#setup) above. With `pnpm server:setup` done, the Rails backend is running and you can start the packages you want to work on.
 
 ### Packages
 
-| Package | Path | Description |
-|---|---|---|
-| `@spree/sdk` | `packages/sdk` | TypeScript SDK for the Spree Store API |
-| `@spree/cli` | `packages/cli` | CLI for managing Spree Commerce projects |
-| `create-spree-app` | `packages/create-spree-app` | Project scaffolding (`npm create spree-app`) |
-| `@spree/docs` | `packages/docs` | Developer documentation for AI agents and local reference |
-
-Internal packages (`@spree/admin-sdk`, `@spree/sdk-core`) are also part of the workspace but are not published to npm.
+| Package | Path | Published | Description |
+|---|---|---|---|
+| `@spree/sdk` | `packages/sdk` | yes | TypeScript SDK for the Spree Store API |
+| `@spree/admin-sdk` | `packages/admin-sdk` | yes | TypeScript SDK for the Spree Admin API |
+| `@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-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 |
 
 ### Common commands
 
@@ -206,7 +226,7 @@ Run from the repository root — [Turborepo](https://turbo.build/) orchestrates
 
 | Command | Description |
 |---|---|
-| `pnpm dev` | Start Docker backend + watch mode for all packages |
+| `pnpm dev` | Watch mode for all packages (does not boot the backend — use `pnpm server:dev` for that) |
 | `pnpm build` | Build all packages (Turbo resolves dependency order) |
 | `pnpm test` | Run tests in all packages |
 | `pnpm lint` | Lint all packages |
@@ -225,21 +245,86 @@ pnpm --filter @spree/sdk generate:zod
 
 Tests use [Vitest](https://vitest.dev/) with [MSW](https://mswjs.io/) for API mocking at the network level.
 
-### Type generation
+### Working on the React dashboard
+
+The dashboard runs as a Vite dev server (port 5173) that proxies `/api/*` to the Rails backend on port 3000 — required for the auth refresh cookie to work over plain HTTP.
+
+```bash
+# Terminal 1: backend
+pnpm server:dev
+
+# Terminal 2: dashboard
+cd packages/dashboard
+pnpm dev   # http://localhost:5173
+```
+
+Sign in with `spree@example.com` / `spree123`. To point at a non-default backend, set `VITE_SPREE_API_URL` (also needs to be set at build time for production bundles, not just dev):
+
+```bash
+VITE_SPREE_API_URL=https://my-spree.example.com pnpm dev
+```
+
+**Gotcha:** the dashboard imports `@spree/admin-sdk` from its **built** `dist/`, not source. If you edit `admin-sdk` (or `sdk-core`, or `sdk`) and want the dashboard to see the changes, run `pnpm build` from the monorepo root first (Turbo-cached). Editing dashboard code alone doesn't need this.
+
+See the [dashboard README](https://github.com/spree/spree/blob/main/packages/dashboard/README.md) for the full architecture (auth, permissions, extension points, the three-package split between `dashboard`, `dashboard-core`, and `dashboard-ui`).
+
+### Dashboard E2E tests
+
+The React dashboard ships an end-to-end suite running on [Playwright](https://playwright.dev/) against a real Rails backend — no mocks. The spec files exercise the full UI: login, staff invitation, invitee signup. CI runs the same suite via the `dashboard-e2e` job in `.github/workflows/packages.yml`.
 
-TypeScript types in `packages/sdk/src/types/generated/` are auto-generated from the Rails API serializers using [typelizer](https://github.com/skryukov/typelizer). To regenerate after changing serializers:
+To run locally you need Ruby (the suite boots a real Rails server) and a one-time browser install:
 
 ```bash
+# Make sure the dummy Rails app exists (one-time, after a fresh checkout).
 cd spree/api
-mise install --yes # to install Ruby if you don't have it already
-bundle install # to install dependencies
-bundle exec rake typelizer:generate
+bundle install
+bundle exec rake test_app
+
+# Install Playwright's Chromium (one-time per machine).
+cd ../../packages/dashboard
+pnpm test:e2e:install
+
+# Run the suite. Boots Rails on :3010 + Vite on :5174, runs all specs, tears
+# both down. Safe to re-run repeatedly — the SQLite DB resets each run.
+pnpm test:e2e
 ```
 
-After regenerating types, update the Zod schemas:
+For interactive debugging (time-travel through actions, inspect the DOM at each step):
 
 ```bash
-pnpm --filter @spree/sdk generate:zod
+pnpm test:e2e:ui
+```
+
+Filter to a single spec or test name:
+
+```bash
+pnpm test:e2e e2e/auth.spec.ts
+pnpm test:e2e -g "invites a teammate"
+```
+
+When a test fails, Playwright drops a screenshot, video, and DOM snapshot in `packages/dashboard/test-results/<spec>/` — usually enough to diagnose without re-running.
+
+### Type generation
+
+TypeScript types in `packages/sdk/src/types/generated/` (Store API) and `packages/admin-sdk/src/types/generated/` (Admin API) are auto-generated from the Rails serializers using [typelizer](https://github.com/skryukov/typelizer). Zod schemas in `packages/sdk/src/zod/generated/` are derived from the TS types.
+
+A **Lefthook pre-commit hook** regenerates both whenever you commit a change to `spree/api/app/serializers/**/*.rb` and re-stages the generated output. You don't need to run anything manually for the common case.
+
+To regenerate manually (useful when iterating on serializers before committing):
+
+```bash
+cd server
+pnpm exec spree rake typelizer:generate     # regenerate TS types
+cd ../packages/sdk
+pnpm generate:zod                            # regenerate Zod schemas
+```
+
+If you'd rather avoid the Docker round-trip and have Ruby on your host, the native equivalent works too:
+
+```bash
+cd spree/api
+bundle install
+bundle exec rake typelizer:generate
 ```
 
 ### Releasing packages
@@ -247,29 +332,33 @@ pnpm --filter @spree/sdk generate:zod
 Published packages use [Changesets](https://github.com/changesets/changesets) for version management. Each package owns its own `.changeset/` folder, so changesets must be created from inside the package directory:
 
 ```bash
-cd packages/sdk    # or packages/cli, packages/create-spree-app
+cd packages/sdk    # or packages/admin-sdk, packages/cli, packages/create-spree-app
 pnpm changeset
 ```
 
 This creates a changeset file describing your changes. Commit it with your PR. When merged to `main`, a GitHub Action creates a "Version Packages" PR that bumps the version and publishes to npm.
 
+Private packages (`@spree/dashboard`, `@spree/dashboard-core`, `@spree/dashboard-ui`, `@spree/sdk-core`) don't need changesets.
+
 ## Code Style
 
 Consistent code style is enforced via automated linters. Please make sure your changes pass linting before submitting a PR.
 
-**Ruby:** We use [RuboCop](https://rubocop.org/) for Ruby code. The configuration lives in `server/.rubocop.yml` and is shipped with [spree-starter](https://github.com/spree/spree-starter), so it's only available after running `pnpm server:setup`. Run it from the `server/` directory:
+**Ruby:** We use [RuboCop](https://rubocop.org/) for Ruby code. The configuration lives in `server/.rubocop.yml` and is shipped with [spree-starter](https://github.com/spree/spree-starter), so it's only available after running `pnpm server:setup`. Run it inside the container via the CLI:
 
 ```bash
 cd server
-bundle exec rubocop
+pnpm exec spree exec bundle exec rubocop
 ```
 
 To auto-fix correctable offenses:
 
 ```bash
-bundle exec rubocop -a
+pnpm exec spree exec bundle exec rubocop -a
 ```
 
+(On the native path, drop the `pnpm exec spree exec` prefix and run `bundle exec rubocop` directly.)
+
 **TypeScript:** We use [Biome](https://biomejs.dev/) for linting and formatting TypeScript code. Run it from the repository root:
 
 ```bash
@@ -319,7 +408,7 @@ To help us review your PR quickly:
 - **Describe your changes.** Explain what you changed and why. Include screenshots for UI changes.
 - **Add tests.** All new features and bug fixes should include appropriate test coverage.
 - **Update documentation.** If your change affects user-facing behavior, update the relevant docs.
-- **Include a changeset** if your change affects a published TypeScript package (`@spree/sdk`, `@spree/cli`, or `create-spree-app`). Run `pnpm changeset` from inside that package's directory — each package owns its own `.changeset/` folder.
+- **Include a changeset** if your change affects a published TypeScript package (`@spree/sdk`, `@spree/admin-sdk`, `@spree/cli`, or `create-spree-app`). Run `pnpm changeset` from inside that package's directory — each package owns its own `.changeset/` folder.
 - **Ensure CI passes.** PRs with failing CI will not be reviewed.
 
 ## Reporting Bugs