@spree/docs 0.1.254 → 0.1.255

package/dist/developer/cli/quickstart.md

@@ -233,7 +233,7 @@ spree generate subscriber OmsOrderSync order.placed              # runs spree:su
 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:api_resource` scaffolds the full v3 surface: model, migration, Store + Admin controllers and serializers, factory, controller specs, routes, and the `read_<resources>` / `write_<resources>` permissions that let staff roles and secret API keys reach the Admin API.
 
 ### `spree migrate`
 

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

@@ -23,10 +23,10 @@ In this guide we build `spree_reviews`: customers read product reviews through t
 
 ## Generate the extension
 
-Install the Spree extension generator:
+Install the Spree extension generator. Spree 6 needs version 2.0 or newer — earlier versions generate a Spree 5 scaffold built around the Rails admin:
 
 ```bash
-gem install spree_extension
+gem install spree_extension -v '>= 2.0'
 ```
 
 Run the following command from a directory outside your Spree application:
@@ -35,14 +35,12 @@ Run the following command from a directory outside your Spree application:
 spree-extension create reviews
 ```
 
-This creates a `spree_reviews` directory containing the engine, a gemspec, a test setup and continuous integration configuration. Change to its directory:
+This creates a `spree_reviews` directory containing the engine, a gemspec, a test setup and continuous integration configuration. Its `config/routes.rb` and `config/initializers/spree.rb` come with commented-out Spree 6 examples — API routes, permission scopes, workflow hooks and event subscribers — that the steps below fill in. Change to its directory:
 
 ```bash
 cd spree_reviews
 ```
 
-> **WARNING:** The generated scaffold still declares a dependency on `spree_admin`, the Spree 5 Rails admin, which does not exist in Spree 6. Remove the `spree_admin` lines from both the `.gemspec` and the `Gemfile` before running `bundle install`. The JavaScript, importmap and asset setup in the scaffold is only used by the Spree 5 admin, so you can delete it too.
-
 ## Add a model
 
 Create the migration in `db/migrate/`:
@@ -288,10 +286,10 @@ module SpreeReviews
 end
 ```
 
-Subscribers are not discovered automatically. Register them from the engine:
+Subscribers are not discovered automatically. Register them in the extension's initializer — `bin/rails g spree:subscriber` adds the line for you:
 
-```ruby lib/spree_reviews/engine.rb
-config.after_initialize do
+```ruby config/initializers/spree.rb
+Rails.application.config.after_initialize do
   Spree.subscribers << SpreeReviews::ReviewRequestSubscriber
 end
 ```
@@ -312,15 +310,7 @@ end
 Spree::Product.prepend SpreeReviews::ProductDecorator
 ```
 
-Decorators are not loaded automatically. Load them from your engine:
-
-```ruby lib/spree_reviews/engine.rb
-config.to_prepare do
-  Dir.glob(root.join('app/**/*_decorator*.rb')) do |decorator|
-    Rails.configuration.cache_classes ? require(decorator) : load(decorator)
-  end
-end
-```
+Rails does not load decorators on its own, so the scaffold's engine does it for you: `lib/spree_reviews/engine.rb` loads every `app/**/*_decorator*.rb` file at boot and again on each code reload in development. Name the file with a `_decorator` suffix and there is nothing else to wire up.
 
 ## Add admin screens
 

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

@@ -27,13 +27,13 @@ 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 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.
+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. `spree plugin new` scaffolds ranges starting at the admin SDK and dashboard versions released alongside your `@spree/cli`.
 
 `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.
 
 ## Choose what to publish
 
-The scaffold's `package.json` ships TS source by default. Two options:
+The scaffold's `package.json` ships TS source by default, and its `build` script type-checks that source. Two options:
 
 ### Option A — Ship pre-built JS
 
@@ -70,7 +70,7 @@ Pick A if you're going to npm in earnest. Pick B for internal-only packages used
 
 ## Side-effects flag
 
-The plugin's whole purpose is side effects (`defineDashboardPlugin` registers stuff at module-load time). **Tell bundlers not to tree-shake it:**
+The plugin's whole purpose is side effects (`defineDashboardPlugin` registers stuff at module-load time). **Tell bundlers not to tree-shake it.** The scaffold lists its source entry, `./src/index.tsx`; add the `dist/` entries if you ship pre-built JS:
 
 ```json
 {
@@ -133,7 +133,7 @@ Set `"private": false` and remove the `"publishConfig.access": "restricted"` if
 
 ## Avoiding lock-step releases
 
-Your plugin should compile against a **range** of dashboard versions. Run the build against the lowest supported version locally (`pnpm add -D @spree/dashboard-core@6.0.0`) and add a CI matrix job that bumps to the next minor and rebuilds. That's the cheapest way to catch "I depended on something that doesn't exist in 6.0.0".
+Your plugin should compile against a **range** of dashboard versions. Run the build against the lowest version your peer range allows (for example `pnpm add -D @spree/dashboard-core@1.0.0-beta.3`) and add a CI matrix job that bumps to the next minor and rebuilds. That's the cheapest way to catch "I depended on something the oldest supported dashboard doesn't have".
 
 ## Reference
 

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

@@ -1,7 +1,7 @@
 ---
 title: Scaffolding
 sidebarTitle: Scaffolding
-description: Generate a new dashboard plugin monorepo with `@spree/cli` in one command. Includes TypeScript, biome, tsup, a working example entry-point, and translations.
+description: Generate a new dashboard plugin monorepo with `@spree/cli` in one command. Includes TypeScript, biome, a working example entry-point, and translations.
 ---
 
 `@spree/cli` ships a `plugin new` command that scaffolds the whole plugin monorepo for you. Generated layout:
@@ -68,14 +68,14 @@ For CI and scripted use, `-y` / `--yes` accepts the default for anything the fla
 npx @spree/cli plugin new my-plugin -y
 ```
 
-`--force` overwrites an existing directory. `--no-dashboard` skips the dashboard package (Rails-engine-only plugins). `--no-engine` is reserved — engine scaffolding lands later.
+`--force` overwrites an existing directory. `--no-dashboard` and `--no-engine` are reserved for when engine scaffolding lands — today the dashboard package is the only half the CLI generates, so `--no-dashboard` leaves nothing to scaffold.
 
 ## After scaffolding
 
 ```bash
 cd my-plugin
 pnpm install          # runs by default unless --no-install
-pnpm build
+pnpm build            # type-checks the plugin — it ships TypeScript source
 ```
 
 You now have a buildable plugin. The next page covers what to put in `package.json` for publishing — but if you're using it internally and importing by path, you can stop here and skip [Publishing](publishing.md).

package/dist/developer/deployment/background_jobs.md

@@ -23,7 +23,21 @@ Every deployment ships [Mission Control](https://github.com/rails/mission_contro
 
 ## Recurring Jobs
 
-Scheduled work — releasing expired stock reservations, pruning price history, queue housekeeping — is defined in `config/recurring.yml`, Solid Queue's built-in cron. Add your own:
+Scheduled work is defined in `config/recurring.yml`, Solid Queue's built-in cron. A new project already schedules everything Spree needs:
+
+| Schedule | Job | What it does |
+|---|---|---|
+| Every minute | `Spree::StockReservations::ExpireJob` | Releases checkout stock reservations whose hold expired |
+| Every 5 minutes | `Spree::Orders::FinalizeStaleDraftsJob` | Finishes orders whose payment succeeded but whose completion never committed; never refunds |
+| Hourly | `Spree::Carts::ReapExpiredJob` | Deletes abandoned carts past their expiry; carts with a live payment are kept |
+| Hourly | `Spree::Collections::RegenerateTimeBasedJob` | Refreshes automatic collections with time-based rules, such as "available on" |
+| Daily | `spree:price_history:prune` task | Deletes price history older than each store's retention period (EU Omnibus) |
+| Daily | `Spree::SellerPayouts::SweepDueJob` | Settles marketplace sellers who are due a payout (see below) |
+| Hourly | `Spree::SellerTransfers::ExecutePendingDueJob` | Retries seller earnings a payout provider refused |
+
+The marketplace jobs do nothing on a store with no sellers, so keep them enabled. If your project predates any of these, copy the missing entries from the [starter's `config/recurring.yml`](https://github.com/spree/spree-starter/blob/main/config/recurring.yml).
+
+Add your own:
 
 ```yaml config/recurring.yml
 production:
@@ -110,6 +124,37 @@ Move the `config/recurring.yml` schedules to sidekiq-cron (it auto-loads `config
 expire_stock_reservations:
   cron: "* * * * *"
   class: Spree::StockReservations::ExpireJob
+finalize_stale_draft_orders:
+  cron: "*/5 * * * *"
+  class: Spree::Orders::FinalizeStaleDraftsJob
+reap_expired_carts:
+  cron: "7 * * * *"
+  class: Spree::Carts::ReapExpiredJob
+regenerate_time_based_collections:
+  cron: "17 * * * *"
+  class: Spree::Collections::RegenerateTimeBasedJob
+prune_price_history:
+  cron: "0 4 * * *"
+  class: PrunePriceHistoryJob
+sweep_due_seller_payouts:
+  cron: "0 3 * * *"
+  class: Spree::SellerPayouts::SweepDueJob
+execute_pending_seller_transfers:
+  cron: "27 * * * *"
+  class: Spree::SellerTransfers::ExecutePendingDueJob
+```
+
+sidekiq-cron schedules jobs, not commands, so price history pruning needs a small job that runs the task:
+
+```ruby app/jobs/prune_price_history_job.rb
+require 'rake'
+
+class PrunePriceHistoryJob < ApplicationJob
+  def perform
+    Rails.application.load_tasks unless Rake::Task.task_defined?('spree:price_history:prune')
+    Rake::Task['spree:price_history:prune'].tap(&:reenable).invoke
+  end
+end
 ```
 
 The `/jobs` dashboard is Solid Queue-specific — mount [Sidekiq's Web UI](https://github.com/sidekiq/sidekiq/wiki/Monitoring) instead:

package/dist/developer/tutorial/model-and-api.md

@@ -28,6 +28,8 @@ The generator reports what it created:
     create  spec/factories/spree/brand_factory.rb
     create  spec/controllers/spree/api/v3/store/brands_controller_spec.rb
     create  spec/controllers/spree/api/v3/admin/brands_controller_spec.rb
+    append  config/initializers/spree.rb
+    create  config/locales/spree_brands.en.yml
 
 ✓ Generated Spree::Brand API resource
 
@@ -55,7 +57,7 @@ Attributes follow the familiar `name:type:index` form, with the Spree convention
 | `active:boolean` | A boolean column with a default |
 | `user:belongs_to` | A reference with the class name resolved |
 
-Useful flags: `--paranoid` for soft delete, `--custom-fields` for [custom fields](../core-concepts/metafields.md) support, `--writable` to give the Store API create, update and destroy as well, and `--no-store` or `--no-admin` to generate only one side. Run the generator with `--help` for the full list.
+Useful flags: `--paranoid` for soft delete, `--custom-fields` for [custom fields](../core-concepts/metafields.md) support, `--writable` to give the Store API create, update and destroy as well, `--permission-group` to choose where the brand permissions appear in the role editor (`catalog` by default), and `--no-store` or `--no-admin` to generate only one side. Run the generator with `--help` for the full list.
 
 ## Step 2: What you got
 
@@ -76,7 +78,9 @@ The Store API is read-only by default — a shopper cannot create a brand. Pass
 
 **Brands belong to a store.** Every resource you generate is scoped to one, because commerce data — catalog, configuration, orders — is always per-store. A new record picks up its store automatically, and a field marked unique is unique *within* a store, so two stores can each have a brand called `wilson`. Only genuinely global reference data, like countries, opts out with `--no-store-scoped`.
 
-> **WARNING:** One decision is still yours: **authorization**. Give the resource a permission rule before exposing it, and read lookups through the store (`current_store.brands`) rather than the whole table. Scoping by association is the cheapest defence against one store reading another's records — filtering by role is not a substitute.
+**Access to the Admin API is a permission.** The generator registers `read_brands` and `write_brands` in `config/initializers/spree.rb`, so you can grant them to a staff role in **Settings → Roles** or to a secret API key, and labels them for the role editor in `config/locales/spree_brands.en.yml`. Until you grant them, only store admins and full-access keys reach the endpoint. See [Permissions](../customization/permissions.md).
+
+> **WARNING:** Read lookups through the store (`current_store.brands`) rather than the whole table. Scoping by association is the cheapest defence against one store reading another's records — a permission decides *whether* someone may read brands, not *which* ones.
 
 ## Step 3: Try it
 

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

@@ -726,7 +726,7 @@ Old initializers fail loudly at boot: the set constants raise `NameError`, and `
 
 ```ruby
 # db/seeds.rb — "roles as code" is plain ActiveRecord now
-Spree::Role.find_or_create_by!(name: 'support')
+Spree::Store.default.roles.find_or_create_by!(name: 'support')
   .update!(permissions: %w[read_orders read_customers])
 ```
 

package/package.json

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