@spree/docs 0.1.295 → 0.1.296

package/dist/developer/cli/quickstart.md

@@ -76,14 +76,6 @@ 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.
-
-```bash
-spree update
-```
-
 ### `spree build`
 
 Rebuild the dev image after Dockerfile or `.ruby-version` changes. Only relevant after `spree eject`.
@@ -100,17 +92,27 @@ spree build --yes            # Skip confirmation prompts (for CI)
 
 ### `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.
+Upgrade your project to the latest Spree release in one go. It works for both kinds of project:
+
+1. **Update the server**
+   - On a project that runs the prebuilt image, it pulls the latest Spree image and recreates the containers. Database migrations run as the containers start.
+   - On an [ejected](#spree-eject) project, it updates the Spree gems with `bundle update`, applies pending migrations, and restarts the app so it loads the new gems.
+2. **Run data backfills** — the version-specific steps from the upgrade manifest that convert existing records.
+3. **Update the `@spree/*` packages** — `@spree/cli` in the project root, and the dashboard packages and Admin SDK in `apps/dashboard` and `apps/seller-dashboard`. Each package moves to the newest release its declared range in `package.json` allows, the same way `bundle update` respects your `Gemfile`. To move to a new major version, change the range in `package.json` first.
 
 ```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
+spree upgrade                  # Run every step, asking before each one
+spree upgrade --plan           # List the data backfills without running anything
+spree upgrade --to 6.1         # Set the target version for the data backfills
+spree upgrade --step <id>      # Re-run a single data backfill (runs nothing else)
+spree upgrade --yes            # Skip the 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.
+Your storefront is your own code, so `spree upgrade` does not change it — it tells you which `@spree/sdk` version to move to.
+
+Production upgrades only need the data backfills — installing gems and migrating happen in your deploy pipeline. See [Upgrades](../upgrades.md) for the manual production path.
+
+> **NOTE:** `spree update` is the old name for this command. It still works, prints a deprecation warning, and will be removed in a future release.
 
 ### `spree eject`
 
@@ -204,7 +206,7 @@ spree encryption init            # Add ACTIVE_RECORD_ENCRYPTION_* keys to the pr
 spree encryption init --print    # Print a fresh set without writing anything (e.g. for your hosting provider)
 ```
 
-It never overwrites keys `.env` already sets, and there is no `--force`: changing the keys makes data encrypted with them unreadable. Afterwards, recreate the containers so they load the new `.env` (`spree update`, or `spree dev` for an ejected project — `spree restart` keeps the old environment), and back the keys up in your secret manager.
+It never overwrites keys `.env` already sets, and there is no `--force`: changing the keys makes data encrypted with them unreadable. Afterwards, recreate the containers so they load the new `.env` (`spree dev` — `spree restart` keeps the old environment), and back the keys up in your secret manager.
 
 ### `spree api`
 

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

@@ -111,7 +111,7 @@ The project includes [@spree/cli](../cli/quickstart.md) for managing your Spree
 |---------|-------------|
 | `spree dev` | Run the app in the foreground — streams logs, Ctrl+C stops it. First run completes setup automatically; co-runs the Admin Dashboard dev server when `apps/dashboard` exists |
 | `spree stop` | Stop backend services |
-| `spree update` | Pull latest Spree image and restart (runs migrations automatically) |
+| `spree upgrade` | Upgrade Spree — the server, database and `@spree/*` packages |
 | `spree eject` | Switch from prebuilt image to building from `server/` |
 | `spree add dashboard` | Add the Admin Dashboard to an existing project, to customize it |
 | `spree add seller-dashboard` | Add the marketplace seller panel to an existing project |
@@ -148,10 +148,10 @@ Open [http://localhost:3001](http://localhost:3001) to see your store.
 To update to the latest Spree version:
 
 ```bash
-spree update
+spree upgrade
 ```
 
-This pulls the latest Docker image and recreates the containers. The entrypoint automatically runs database migrations.
+This updates the server (the Docker image, or the Spree gems on an ejected project), runs database migrations and data backfills, and updates the `@spree/*` packages of the project and its dashboard apps. See [`spree upgrade`](../cli/quickstart.md#spree-upgrade) for details.
 
 To pin a specific version, edit `SPREE_VERSION_TAG` in `.env`:
 

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

@@ -226,7 +226,7 @@ bin/rails db:encryption:init    # prints a set; put it in env vars or encrypted
 ```
 
 
-Recreate the containers so they pick up the new `.env` (`spree update`, or `spree dev` for an ejected project — `spree restart` keeps the old environment). Set the keys on your production host **before** deploying, and store them in your secret manager.
+Recreate the containers so they pick up the new `.env` (`spree dev` — `spree restart` keeps the old environment). Set the keys on your production host **before** deploying, and store them in your secret manager.
 
 > **WARNING:** Never change or lose the keys once data is encrypted — the encrypted records become unreadable.
 

package/dist/developer/upgrades/quickstart.md

@@ -9,6 +9,38 @@ The upgrade process is fairly easy and well described. Of course, it all boils d
 
 We strongly advise upgrading Spree incrementally, rather than in one big go.
 
+## How to upgrade
+
+An upgrade updates the server, migrates the database, runs the version's data backfills, and updates the `@spree/*` packages of your dashboard apps. Always read the guide for the version you're moving to first — it lists the behavior changes to review.
+
+**Spree CLI:**
+
+```bash
+    spree upgrade
+    ```
+
+    One command for every project: it pulls the new image, or updates the Spree gems on an [ejected](../cli/quickstart.md#spree-eject) project, then runs migrations, data backfills and the package updates. See [`spree upgrade`](../cli/quickstart.md#spree-upgrade) for its options.
+
+  **Without CLI:**
+
+Run from the project root:
+
+    ```bash
+    cd server
+    bundle update $(bundle list --name-only | grep ^spree)
+    bin/rails spree:install:migrations db:migrate
+    bin/rails spree:upgrade
+    cd ..
+
+    # The project root and each dashboard app have their own package.json
+    pnpm update "@spree/*"
+    (cd apps/dashboard && pnpm update "@spree/*")
+    (cd apps/seller-dashboard && pnpm update "@spree/*")
+    ```
+
+    On npm or Yarn, run `npm update` or `yarn upgrade` instead, naming each `@spree/*` package from that `package.json` (they do not accept the `"@spree/*"` pattern).
+
+
 ## Support
 
 If you're stuck and would want to get some professional help, you can [contact us directly](https://spreecommerce.org/contact/) and request a quote for our consulting services.

package/package.json

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