Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Added agentic development docs + updated tutorial
Damian Legawiec5be7bdf28084
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.mdindex c4cb0bd558..aa055860e7 100644--- a/.github/CONTRIBUTING.md+++ b/.github/CONTRIBUTING.md@@ -466,16 +466,14 @@ Issues that are open for 14 days without actionable information or activity willSpree comes with an [AGENTS.md](../AGENTS.md) file that instructs coding agents like Claude Code or Codex to help you with your development.-We also have an MCP server built on top of our Documentation website to help you with your development.+We also ship [agent skills](https://spreecommerce.org/docs/developer/agentic/agent-skills) (`npx skills add spree/agent-skills`), a [docs MCP server](https://spreecommerce.org/docs/developer/agentic/mcp), and [LLM-ready documentation](https://spreecommerce.org/docs/developer/agentic/llm-docs) — see the [Agentic Development docs](https://spreecommerce.org/docs/developer/agentic/overview) for setup across Claude Code, Cursor, Copilot, and other tools.-Add this URL to your AI tools:+The MCP server URL for quick setup:```https://spreecommerce.org/docs/mcp```-In Claude Code you need to go to [Connectors](https://claude.ai/settings/connectors) settings and add the URL.-## That's a wrap!Thank you for participating in Open Source and improving Spree - you're awesome!diff --git a/docs/api-reference/admin-api/introduction.mdx b/docs/api-reference/admin-api/introduction.mdxindex ca2e9ca075..d0813aea76 100644--- a/docs/api-reference/admin-api/introduction.mdx+++ b/docs/api-reference/admin-api/introduction.mdx@@ -8,10 +8,6 @@ import { Since } from '/snippets/since.mdx';<Since version="5.5" />-<Warning>-**Developer Preview.** The Admin API is in active development and may change between major versions.-</Warning>-The Admin API is a REST API for managing Spree stores programmatically — products, orders, customers, fulfillments, payments, and more. It is intended for backend integrations, custom admin tooling, and automation.All routes are prefixed with `/api/v3/admin`. During development the API is available under `http://localhost:3000/api/v3/admin`. For production, replace `http://localhost:3000` with your Spree application URL.@@ -58,16 +54,6 @@ const { data: orders } = await client.orders.list({})```-## What's covered--The Admin API today (in Spree 5.5) covers:--- **Catalog** — products, variants, prices-- **Orders** — list, create, update, items, complete, cancel, approve, resume; nested fulfillments, payments, refunds, gift cards, store credits-- **Customers** — full CRUD, addresses, store credits, credit cards--See the **Endpoints** section in the sidebar for the complete reference, generated from the OpenAPI spec.-Before integrating, read:- [Authentication](/api-reference/admin-api/authentication) — secret API keys, scopes, and JWT tokensdiff --git a/docs/developer/agentic/agent-skills.mdx b/docs/developer/agentic/agent-skills.mdxnew file mode 100644index 0000000000..a73cf6bc2d--- /dev/null+++ b/docs/developer/agentic/agent-skills.mdx@@ -0,0 +1,64 @@+---+title: "Agent Skills"+sidebarTitle: Agent Skills+description: "Teach your AI coding agent Spree's conventions — 25 installable skills, a Spree expert subagent, slash commands, and safety hooks."+---++[spree/agent-skills](https://github.com/spree/agent-skills) is a collection of agent skills for Spree Commerce. Skills are markdown instructions your coding agent loads on demand — they encode Spree's conventions, customization decision trees, API patterns, and upgrade flows, so the agent does things the Spree way instead of improvising from training data.++The skills work with Claude Code, Codex, Cursor, GitHub Copilot, Cline, Aider, Zed, Windsurf, OpenCode, and 60+ other agentic tools.++## Install++Run from your project directory:++```bash+npx skills add spree/agent-skills+```++The [skills CLI](https://github.com/vercel-labs/skills) auto-detects which agent tools you have configured and copies the skill files into each tool's native location.++Useful variants:++```bash+npx skills add spree/agent-skills --list # see what's available without installing+npx skills add spree/agent-skills --skill spree-api-v3 # install a subset+npx skills update # update installed skills later+```++## What's inside++| | |+|---|---|+| **25 skills** | Project conventions, the customization decision tree (subscriber vs decorator vs dependency injection vs generator), the v3 Store + Admin API, the `spree:model` / `spree:api_resource` generators, TypeScript SDKs, upgrades, and domain deep-dives: catalog, checkout, payments, promotions, pricing, shipping, i18n, testing, security, performance, deployment. |+| **`spree-expert` subagent** | A Claude Code agent for multi-step investigations (upgrade audits, checkout-flow debugging, API surface planning). It researches in its own context window and returns a focused report, keeping your main session lean. |+| **2 slash commands** | `/spree:doctor` diagnoses the local dev stack (containers, env, migrations, job queues) and prescribes fixes. `/spree:audit-upgrade [version]` runs a read-only upgrade-readiness audit against your codebase. |+| **2 safety hooks** | Block destructive database commands (`db:drop`, `DROP TABLE spree_*`, mass deletes, force-pushes to main) and warn when an edit introduces a hardcoded secret (Stripe live keys, AWS keys, API tokens). Disable with `SPREE_HOOKS_DISABLE=1`. |++Skills activate automatically based on what you're working on — asking your agent to "add a Brand model with an API" pulls in the resource-generator skill; "why is this promotion not applying" pulls in the promotions skill. There's nothing to invoke manually.++## Claude Code plugin (adds commands + hooks)++The `npx skills add` path installs the skills and the subagent. The slash commands and safety hooks need the Claude Code plugin install — run inside a Claude Code session:++```text+/plugin marketplace add spree/agent-skills+/plugin install spree@spree+```++The plugin delivers everything the skills CLI does **plus** `/spree:doctor`, `/spree:audit-upgrade`, and the two safety hooks. Use one install path or the other — installing both makes the skills collide.++## Works in any Spree project++The skills detect your project flavor before running commands:++- **create-spree-app projects** (Docker, Rails app in `backend/`) — commands route through the [Spree CLI](/developer/cli/quickstart) (`spree migrate`, `spree console`, …).+- **Classic Rails apps** (Spree gems in a plain Rails app, no Docker — typical for apps created before Spree 5.4) — the skills fall back to native commands (`bin/rails`, `bundle exec rake`) from the app root.++## Updating++```bash+npx skills update # skills CLI installs+```++Plugin installs update through Claude Code's plugin system (`/plugin` → check for updates). New Spree releases ship matching skill updates — update the skills when you upgrade Spree so the guidance matches your installed version.diff --git a/docs/developer/agentic/llm-docs.mdx b/docs/developer/agentic/llm-docs.mdxnew file mode 100644index 0000000000..a3cf0777ee--- /dev/null+++ b/docs/developer/agentic/llm-docs.mdx@@ -0,0 +1,57 @@+---+title: "LLM-Ready Documentation"+sidebarTitle: LLM-Ready Docs+description: "Every page of the Spree docs is consumable by LLMs — llms.txt indexes, per-page Markdown, and a local npm package for offline agent reads."+---++Beyond the [MCP server](/developer/agentic/mcp), the Spree documentation is published in formats designed for direct LLM consumption. Use these when you want to feed docs into a prompt, point a custom agent at an index, or give agents fast local file access.++## llms.txt++Following the [llms.txt convention](https://llmstxt.org), two indexes are published:++| URL | Contents |+|---|---|+| [`spreecommerce.org/docs/llms.txt`](https://spreecommerce.org/docs/llms.txt) | An index of every documentation page with links — lets an agent discover and fetch exactly the pages it needs |+| [`spreecommerce.org/docs/llms-full.txt`](https://spreecommerce.org/docs/llms-full.txt) | The entire documentation in one file — for tools that ingest a single context dump |++## Per-page Markdown++Append `.md` to any docs URL to get the raw Markdown for that page — ideal for fetching a single authoritative page into context:++```text+https://spreecommerce.org/docs/developer/cli/quickstart.md+https://spreecommerce.org/docs/developer/core-concepts/orders.md+```++## The `@spree/docs` npm package++The full developer documentation also ships as an npm package, so agents working in your repository can `Read` doc files locally — no network round-trips, works offline, and version-pinned to what you installed:++```bash+npm install --save-dev @spree/docs+```++```text+node_modules/@spree/docs/dist/+├── developer/+│ ├── getting-started/ # setup and quickstarts+│ ├── core-concepts/ # products, orders, payments, inventory, …+│ ├── customization/ # decorators, dependencies, events, …+│ ├── storefront/ # Next.js storefront guides+│ ├── sdk/ # TypeScript SDK docs+│ ├── admin/ # admin customization, form builder, components+│ └── how-to/ # focused guides+└── api-reference/+ └── store.yaml # the full Store API OpenAPI spec+```++Projects scaffolded with [create-spree-app](/developer/create-spree-app/quickstart) install it automatically.++<Note>+ The package tracks the docs published at install time and is versioned independently of your Spree gems — run your package manager's update to refresh it, and prefer the [MCP server](/developer/agentic/mcp) when you need the absolute latest.+</Note>++## Generated agent instructions++`create-spree-app` scaffolds every project with a `CLAUDE.md` that tells coding agents where the local docs live, which CLI commands to use (`spree dev`, `spree migrate`, `spree console`), and the customization patterns to follow — so an agent dropped into a fresh project is productive without any prompting. The scaffold's next-steps also suggest installing the [agent skills](/developer/agentic/agent-skills) for the full experience.diff --git a/docs/developer/agentic/mcp.mdx b/docs/developer/agentic/mcp.mdxnew file mode 100644index 0000000000..416a40edf3--- /dev/null+++ b/docs/developer/agentic/mcp.mdx@@ -0,0 +1,74 @@+---+title: "Docs MCP Server"+sidebarTitle: MCP+description: "Connect your AI agent to the Spree documentation MCP server to search and read the latest docs while building."+---++Spree hosts a [Model Context Protocol](https://modelcontextprotocol.io) server on top of this documentation. Once connected, your agent can search the docs and read full pages on demand — answering questions from the latest published documentation instead of stale training data.++```text+https://spreecommerce.org/docs/mcp+```++The server exposes two tools: full-text **search** across the documentation, and **reading** doc pages as Markdown.++## Setup++<Tabs>+ <Tab title="Claude Code">+ ```bash+ claude mcp add --transport http spree-docs https://spreecommerce.org/docs/mcp+ ```++ Scope it to the project (`--scope project`) to share the connection with your team via `.mcp.json`, or keep the default local scope for just yourself.+ </Tab>+ <Tab title="Claude.ai / Claude Desktop">+ Go to [Settings → Connectors](https://claude.ai/settings/connectors), click **Add custom connector**, and paste the URL:++ ```text+ https://spreecommerce.org/docs/mcp+ ```+ </Tab>+ <Tab title="Cursor">+ Add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` globally):++ ```json+ {+ "mcpServers": {+ "spree-docs": {+ "url": "https://spreecommerce.org/docs/mcp"+ }+ }+ }+ ```+ </Tab>+ <Tab title="VS Code (Copilot)">+ Add to `.vscode/mcp.json` in your project:++ ```json+ {+ "servers": {+ "spree-docs": {+ "type": "http",+ "url": "https://spreecommerce.org/docs/mcp"+ }+ }+ }+ ```+ </Tab>+ <Tab title="Other tools">+ Any MCP client that supports remote servers over streamable HTTP can connect — point it at `https://spreecommerce.org/docs/mcp`. No authentication is required.+ </Tab>+</Tabs>++## When to use MCP vs the other doc channels++| Channel | Best for |+|---|---|+| **MCP server** (this page) | The latest published docs; agents working outside a scaffolded project; questions the installed skills don't cover |+| **[`@spree/docs` npm package](/developer/agentic/llm-docs)** | Fast local reads inside a project — no network round-trip, works offline, pinned to what you installed |+| **[Agent skills](/developer/agentic/agent-skills)** | Conventions and how-to knowledge the agent should apply without searching at all |++<Note>+ In create-spree-app projects the generated `CLAUDE.md` already points agents at the local `@spree/docs` package first — MCP complements it for anything newer than your installed docs version.+</Note>diff --git a/docs/developer/agentic/overview.mdx b/docs/developer/agentic/overview.mdxnew file mode 100644index 0000000000..e2bca1b049--- /dev/null+++ b/docs/developer/agentic/overview.mdx@@ -0,0 +1,41 @@+---+title: "Agentic Development"+sidebarTitle: Overview+description: "Build, customize, and upgrade Spree with AI coding agents — agent skills, a docs MCP server, and LLM-ready documentation."+---++Spree ships first-class tooling for AI-assisted development. Whether you use Claude Code, Cursor, Codex, Copilot, or any other coding agent, your agent can learn Spree's conventions, read the right docs at the right time, and run the project safely.++## Why Spree works well with AI agents++- **Strong conventions** — everything is namespaced under `Spree::`, models follow predictable patterns (prefixed IDs, `Spree.base_class`, service objects, events), and the v3 REST API uses flat request/response shapes. Conventions are what agents are best at following.+- **Docs designed for machine consumption** — the full documentation is available as [llms.txt, per-page Markdown, and a local npm package](/developer/agentic/llm-docs), so agents read authoritative content instead of guessing from training data.+- **A guided project workflow** — [create-spree-app](/developer/create-spree-app/quickstart) scaffolds projects with a generated `CLAUDE.md`, local docs, and the [Spree CLI](/developer/cli/quickstart), so an agent can boot, migrate, generate code, and run tests without bespoke setup.++## The toolbox++<CardGroup cols={2}>+ <Card title="Agent Skills" icon="graduation-cap" href="/developer/agentic/agent-skills">+ 25 skills teaching agents Spree's conventions, customization patterns, and upgrade flows — installable into 60+ agent tools, plus a Claude Code plugin with slash commands and safety hooks.+ </Card>+ <Card title="Docs MCP Server" icon="plug" href="/developer/agentic/mcp">+ Connect your agent to the Spree documentation MCP server to search and read the latest docs while building.+ </Card>+ <Card title="LLM-Ready Docs" icon="file-text" href="/developer/agentic/llm-docs">+ llms.txt, per-page Markdown, and the `@spree/docs` npm package for fast local reads.+ </Card>+ <Card title="Spree CLI" icon="square-terminal" href="/developer/cli/quickstart">+ A predictable command surface (`spree dev`, `spree generate`, `spree migrate`, `spree upgrade`) that agents can drive end-to-end.+ </Card>+</CardGroup>++## A typical agentic workflow++1. **Scaffold** a project with `npx create-spree-app@latest my-store` — it generates a `CLAUDE.md`, installs `@spree/docs` for local reference, and wires up the CLI.+2. **Install the agent skills** with `npx skills add spree/agent-skills` so your agent knows the decision tree for customizations (subscriber vs decorator vs dependency injection vs generator) before it writes a line of code.+3. **Connect the docs MCP server** so questions the skills don't cover get answered from the live documentation.+4. **Let the agent work** — generate an API resource (`spree generate api_resource Brand name:string`), customize checkout, integrate a payment provider, or run an upgrade with `spree upgrade`.++<Tip>+ Skills, local docs, and MCP are complementary: skills encode *how to do things the Spree way*, local docs give *fast authoritative lookups*, and MCP covers *the latest published documentation*. Most teams use all three.+</Tip>diff --git a/docs/developer/contributing/developing-spree.mdx b/docs/developer/contributing/developing-spree.mdxindex 49d0a2d1a7..f61bd8f794 100644--- a/docs/developer/contributing/developing-spree.mdx+++ b/docs/developer/contributing/developing-spree.mdx@@ -432,16 +432,14 @@ Issues that are open for 14 days without actionable information or activity willSpree comes with an [AGENTS.md](https://github.com/spree/spree/blob/main/AGENTS.md) file that instructs coding agents like Claude Code or Codex to help you with your development.-We also have an MCP server built on top of our Documentation website to help you with your development.+We also ship [agent skills](/developer/agentic/agent-skills) (`npx skills add spree/agent-skills`), a [docs MCP server](/developer/agentic/mcp), and [LLM-ready documentation](/developer/agentic/llm-docs) — see the [Agentic Development docs](/developer/agentic/overview) for setup across Claude Code, Cursor, Copilot, and other tools.-Add this URL to your AI tools:+The MCP server URL for quick setup:```https://spreecommerce.org/docs/mcp```-In Claude Code you need to go to [Connectors](https://claude.ai/settings/connectors) settings and add the URL.-## That's a wrap!Thank you for participating in Open Source and improving Spree - you're awesome!diff --git a/docs/developer/customization/api.mdx b/docs/developer/customization/api.mdxindex 81ce80b78f..65d886dcfb 100644--- a/docs/developer/customization/api.mdx+++ b/docs/developer/customization/api.mdx@@ -6,7 +6,7 @@ description: >-Before you start customizing Spree API endpoints, make sure you reviewed all existing API endpoints in the [Spree API docs](/api-reference).-For a step-by-step walkthrough of adding a complete new resource (model, serializer, controller, routes), see the [Store API tutorial](/developer/tutorial/store-api).+For a step-by-step walkthrough of adding a complete new resource (model, serializer, controller, routes), see the [API tutorial](/developer/tutorial/api).## Customizing JSON Responses@@ -36,7 +36,7 @@ Restart the server and the Product API will include your new attribute.### Adding an Association-Let's say you've created a `Spree::Brand` model that belongs to `Product` (see the [tutorial](/developer/tutorial/store-api) for the full example).+Let's say you've created a `Spree::Brand` model that belongs to `Product` (see the [tutorial](/developer/tutorial/api) for the full example).Create a serializer for the new model:diff --git a/docs/developer/sdk/extending.mdx b/docs/developer/sdk/extending.mdxindex 604961237b..198e893ac7 100644--- a/docs/developer/sdk/extending.mdx+++ b/docs/developer/sdk/extending.mdx@@ -30,4 +30,4 @@ const nike = await client.request<Brand>('GET', '/brands/nike')`client.request` uses the same auth headers, retry logic, and locale/currency defaults as `client.products.list()` or any other built-in resource.-For a complete walkthrough — creating the API endpoints on the backend, defining TypeScript types, filtering, and expanding associations — see the [Store API](/developer/tutorial/store-api) and [SDK](/developer/tutorial/sdk) tutorials.+For a complete walkthrough — creating the API endpoints on the backend, defining TypeScript types, filtering, and expanding associations — see the [API](/developer/tutorial/api) and [SDK](/developer/tutorial/sdk) tutorials.diff --git a/docs/developer/tutorial/admin.mdx b/docs/developer/tutorial/admin.mdxindex 91eff6c747..9bf76d4ceb 100644--- a/docs/developer/tutorial/admin.mdx+++ b/docs/developer/tutorial/admin.mdx@@ -1,26 +1,32 @@---title: Admin Dashboard-description: Learn how to create Admin Dashboard UI to manage Brands+description: Scaffold the admin UI for Brands, then add the rich text editor, logo upload, and a custom table column----Now that we've created a complete "Brand" model, let's create an Admin Dashboard interface so our admins can manage the brands.+Now that we've created the `Brand` model, let's create an Admin Dashboard interface so admins can manage brands — including editing the rich text description and uploading the logo.-## Step 1: Create the boilerplate Admin Dashboard UI+## Step 1: Scaffold the Admin UI-Admin Scaffold generator is a tool that helps us create a complete Admin Dashboard UI for our new resource.+The Admin Scaffold generator creates a complete admin section for a resource:-Run the following command in our Spree application root directory:+<CodeGroup>-```bash+```bash Spree CLI (Docker)+spree generate spree:admin:scaffold Spree::Brand+```++```bash Rails (native)bin/rails g spree:admin:scaffold Spree::Brand```+</CodeGroup>+This will create the following files:| File Type | Path | Description ||-----------|------|-------------|| Controller | `app/controllers/spree/admin/brands_controller.rb` | Handles the logic for the brands resource. |-| View | `app/views/spree/admin/brands/index.html.erb` | Displays the list of brands using the new tables system. |+| View | `app/views/spree/admin/brands/index.html.erb` | Displays the list of brands using the tables system. || View | `app/views/spree/admin/brands/new.html.erb` | Displays the new brand form. || View | `app/views/spree/admin/brands/edit.html.erb` | Displays the edit brand form. || Partial | `app/views/spree/admin/brands/_form.html.erb` | The form partial used in new and edit views. |@@ -37,7 +43,54 @@ endYou will now be able to access the brands resource at `http://localhost:3000/admin/brands` in your browser. To reference this route in your code, you can use the `spree.admin_brands_path` helper.-## Step 2: Customize the Table Columns+## Step 2: Add the Description Editor and Logo Upload++The generated form only knows about the `name` column. Let's add the rich text editor for `description` and the upload field for `logo` using Spree's [admin form builder](/developer/admin/form-builder):++```erb app/views/spree/admin/brands/_form.html.erb {4,9-16}+<div class="card mb-6">+ <div class="card-body">+ <%= f.spree_text_field :name, required: true, autofocus: true %>+ <%= f.spree_rich_text_area :description %>+ </div>+</div>++<div class="card mb-6">+ <div class="card-header">+ <h5 class="card-title"><%= Spree.t(:logo) %></h5>+ </div>+ <div class="card-body">+ <%= f.spree_file_field :logo, width: 300, height: 300 %>+ </div>+</div>+```++- **`spree_rich_text_area`** renders a WYSIWYG editor (Trix) for the Action Text description.+- **`spree_file_field`** handles drag-and-drop upload, image preview, and direct upload to storage. Add `crop: true` to enable image cropping with a recommended-size indicator.++Then permit the two new attributes in the controller:++```ruby app/controllers/spree/admin/brands_controller.rb {7-11}+module Spree+ module Admin+ class BrandsController < ResourceController+ private++ def permitted_resource_params+ params.require(:brand).permit(+ :name,+ :description,+ :logo+ )+ end+ end+ end+end+```++Open `http://localhost:3000/admin/brands/new`, create a brand with a formatted description and a logo — everything saves through the standard form.++## Step 3: Customize the Table ColumnsThe scaffold generator creates a table initializer at `config/initializers/spree_admin_brands_table.rb` with default columns:@@ -71,23 +124,38 @@ Rails.application.config.after_initialize doend```-You can customize this file to add more columns based on your model's attributes. For example, to add a description column:+### Show the logo next to the name-```ruby-Spree.admin.tables.brands.add :description,- label: :description,- type: :string,- sortable: false,+To render the logo thumbnail in the name column — the same pattern the Products table uses — switch the column to a custom partial:++```ruby config/initializers/spree_admin_brands_table.rb+Spree.admin.tables.brands.add :name,+ label: :name,+ type: :custom,+ partial: 'spree/admin/tables/columns/brand_name',+ sortable: true,filterable: true,default: true,- position: 15+ position: 10+```++And create the partial:++```erb app/views/spree/admin/tables/columns/_brand_name.html.erb+<%# locals: (record:, column:, value:) %>+<%= link_to spree.edit_admin_brand_path(record), class: 'flex items-center gap-3 no-underline', data: { turbo_frame: '_top' } do %>+ <% if record.logo.attached? %>+ <%= spree_image_tag record.logo, width: 48, height: 48, class: 'rounded' %>+ <% end %>+ <span class="text-gray-900 font-medium"><%= record.name %></span>+<% end %>```<Info>For complete table customization options including column types, filtering, sorting, and bulk actions, see the [Admin Tables](/developer/admin/tables) guide.</Info>-## Step 3: Customize Navigation+## Step 4: Customize NavigationThe scaffold generator also creates a navigation initializer at `config/initializers/spree_admin_brands_navigation.rb`:@@ -134,5 +202,9 @@ endAfter restarting your server, you'll see the new "Brands" navigation link in the admin sidebar!<Info>-For complete navigation API documentation including all available options, submenu creation, badges, and more, see the [Admin Navigation](/developer/admin/navigation) guide.+For complete navigation API documentation including all available options, submenu creation, badges, and more, see the [Admin Navigation](/developer/admin/navigation) guide. The form helpers used in Step 2 are documented in [Form Builder](/developer/admin/form-builder) and [Components](/developer/admin/components).</Info>++## Next Step++Brands are manageable in the admin. Now let's connect them to Products: [Extending Core Models](/developer/tutorial/extending-models).diff --git a/docs/developer/tutorial/store-api.mdx b/docs/developer/tutorial/api.mdxsimilarity index 72%rename from docs/developer/tutorial/store-api.mdxrename to docs/developer/tutorial/api.mdxindex dbed0da3d1..e99bad9acf 100644--- a/docs/developer/tutorial/store-api.mdx+++ b/docs/developer/tutorial/api.mdx@@ -1,9 +1,9 @@----title: Store API-description: Expose your Brand model through the Store API with serializers, controllers, and routes+title: API+description: Expose your Brand model through the Store and Admin APIs with serializers, controllers, and routes----In this tutorial, we'll create Store API endpoints for our Brand model so that storefronts can list and display brands. We'll also extend the existing Product serializer to include brand data.+In this tutorial, we'll expose our Brand model through Spree's v3 API — the customer-facing **Store API** that storefronts read from, and the back-office **Admin API** with full CRUD for apps and integrations. We'll also extend the existing Product serializer to include brand data.<Info>This guide assumes you've completed the [Model](/developer/tutorial/model), [Admin](/developer/tutorial/admin), and [Extending Core Models](/developer/tutorial/extending-models) tutorials.@@ -13,11 +13,47 @@ In this tutorial, we'll create Store API endpoints for our Brand model so that sBy the end of this tutorial, you'll have:-- `GET /api/v3/store/brands` — list all brands-- `GET /api/v3/store/brands/:id` — get a single brand by prefixed ID or slug+- `GET /api/v3/store/brands` and `GET /api/v3/store/brands/:id` — customer-facing, read-only, lookup by prefixed ID or slug+- Full CRUD on `/api/v3/admin/brands` — for back-office apps and integrations- Brand data included in Product responses via `?expand=brand`- Understanding of how to add new API endpoints and extend existing serializers+## The Fast Path: One Generator Command++Everything this page builds by hand can be generated in one command with `spree:api_resource`:++<CodeGroup>++```bash Spree CLI (Docker)+spree generate api_resource Brand+```++```bash Rails (native)+bin/rails g spree:api_resource Brand+```++</CodeGroup>++Because the Brand model already exists, the generator leaves it (and its migration) untouched and produces only the API surface — no conflict prompts, no overwrites. Your model is "owned once": after creation, domain code belongs to you, and the generator only ever adds API files around it. You'll see this in the output:++```text+ skip model app/models/spree/brand.rb (owned-once; already exists)+ skip migration (model already exists; add a new migration for schema changes)+ create app/controllers/spree/api/v3/store/brands_controller.rb+ create app/controllers/spree/api/v3/admin/brands_controller.rb+ create app/serializers/spree/api/v3/brand_serializer.rb+ create app/serializers/spree/api/v3/admin/brand_serializer.rb+ create spec/factories/spree/brand_factory.rb+```++For a brand-new resource you'd pass the attributes too (`spree generate api_resource Brand name:string:uniq`) and get the model and migration in the same run.++If you just want a working API, run the generator and skip ahead to [Step 5: Test the Endpoints](#step-5-test-the-endpoints). The rest of this page builds the Store side by hand so you understand what the generator produces and how to customize it — the [Admin API section](#the-admin-api) then shows how little the back-office surface adds on top.++<Tip>+ Using an AI agent? The [Spree agent skills](/developer/agentic/agent-skills) include a dedicated resource-generator skill — your agent knows the field syntax, the flags, and the generated-file contract.+</Tip>+## How the Store API WorksEvery Store API endpoint follows the same pattern:@@ -31,22 +67,30 @@ Every Store API endpoint follows the same pattern:Store API requires two things from models:-1. **Prefixed IDs** — Stripe-style IDs like `brand_k5nR8xLq` instead of raw database IDs+1. **Prefixed IDs** — Stripe-style IDs like `brand_k5nR8xLq` instead of raw database IDs. The `spree:model` generator already added `has_prefix_id :brand` in the [Model step](/developer/tutorial/model), so this is done.2. **Slugs** — human-readable URL identifiers like `nike` for `GET /brands/nike`-First, add a `slug` column if you haven't already:+Add a `slug` column:-```bash+<CodeGroup>++```bash Spree CLI (Docker)+spree generate migration AddSlugToSpreeBrands slug:string:uniq+spree migrate+```++```bash Rails (native)bin/rails g migration AddSlugToSpreeBrands slug:string:uniqbin/rails db:migrate```-Then update the Brand model with `PrefixedId` and `FriendlyId`:+</CodeGroup>++Then add `FriendlyId` to the Brand model:-```ruby app/models/spree/brand.rb {3-7}+```ruby app/models/spree/brand.rb {3,6}module Spree- class Brand < Spree::Base- include Spree::PrefixedId+ class Brand < Spree.base_classextend FriendlyIdhas_prefix_id :brand@@ -54,10 +98,14 @@ module Spreehas_many :products, class_name: 'Spree::Product', dependent: :nullify- has_one_attached :logohas_rich_text :description+ has_one_attached :logovalidates :name, presence: true++ self.whitelisted_ransackable_attributes = %w[name]+ self.whitelisted_ransackable_associations = %w[]+ self.whitelisted_ransackable_scopes = %w[]endend```@@ -66,7 +114,7 @@ Now:- `Spree::Brand.first.prefixed_id` returns `brand_k5nR8xLq`- `Spree::Brand.find_by_prefix_id!('brand_k5nR8xLq')` finds by prefixed ID- `Spree::Brand.friendly.find('nike')` finds by slug-- Slugs are auto-generated from the `name` via `slug_candidates` (inherited from `Spree::Base`)+- Slugs are auto-generated from the `name` via `slug_candidates` (inherited from the Spree base class)## Step 2: Create the Serializer@@ -265,6 +313,69 @@ List response:}```+## The Admin API++The Admin API is the other half of v3 — same protocol, same serializer/controller patterns, but authenticated with secret keys (`sk_*`) or admin JWTs, and **full CRUD by default**. The `spree:api_resource` generator produces both pieces; here's what they look like:++```ruby app/serializers/spree/api/v3/admin/brand_serializer.rb+module Spree+ module Api+ module V3+ module Admin+ class BrandSerializer < V3::BrandSerializer+ attributes :created_at, :updated_at+ end+ end+ end+ end+end+```++```ruby app/controllers/spree/api/v3/admin/brands_controller.rb+module Spree+ module Api+ module V3+ module Admin+ class BrandsController < ResourceController+ protected++ def model_class+ Spree::Brand+ end++ def serializer_class+ Spree::Api::V3::Admin::BrandSerializer+ end++ def permitted_params+ params.permit(:name)+ end+ end+ end+ end+ end+end+```++Two conventions to notice:++- **The Admin serializer extends the Store serializer** — public fields stay in sync automatically, and the Admin side adds back-office data (timestamps here; cost prices, internal notes, and audit fields on richer resources). Customers never see those fields because storefronts use the Store serializer.+- **`Admin::ResourceController` ships full CRUD** — `index`, `show`, `create`, `update`, and `destroy` are inherited; `permitted_params` lists the writable attributes with flat params (no nested `brand: {...}` wrapping).++With the routes registered (`resources :brands` under the `admin` namespace — the generator injects this), back-office clients get:++```bash+# Create a brand with a secret API key+curl -X POST -H "X-Spree-API-Key: sk_YOUR_KEY" \+ -H "Content-Type: application/json" \+ -d '{"name": "Adidas"}' \+ http://localhost:3000/api/v3/admin/brands+```++<Info>+ Secret keys carry scopes (`read_brands`, `write_brands` style) and JWT admin users go through CanCanCan abilities — see [API authentication](/developer/customization/api) for the full model.+</Info>+## Step 6: Add Brand to Product ResponsesNow let's extend the Product serializer so that brand data is included when a storefront requests `?expand=brand`.diff --git a/docs/developer/tutorial/extending-models.mdx b/docs/developer/tutorial/extending-models.mdxindex 8ebce76d31..bc1a534ea9 100644--- a/docs/developer/tutorial/extending-models.mdx+++ b/docs/developer/tutorial/extending-models.mdx@@ -6,7 +6,7 @@ description: Tutorial — extend Spree's core models with a custom Brand resourcIn this tutorial, we'll connect our custom Brand model with Spree's core Product model. This is a common pattern when building features that need to integrate with existing Spree functionality.<Info>- This guide assumes you've completed the [Model](/developer/tutorial/model), [Admin](/developer/tutorial/admin), and [File Uploads](/developer/tutorial/file-uploads) tutorials.+ This guide assumes you've completed the [Model](/developer/tutorial/model) and [Admin](/developer/tutorial/admin) tutorials.</Info>## What We're Building@@ -81,10 +81,18 @@ The key line is `Product.prepend(ProductDecorator)` - this inserts your module aFirst, add a `brand_id` column to the products table:-```bash+<CodeGroup>++```bash Spree CLI (Docker)+spree generate migration AddBrandIdToSpreeProducts brand_id:integer:index+```++```bash Rails (native)bin/rails g migration AddBrandIdToSpreeProducts brand_id:integer:index```+</CodeGroup>+Edit the migration to add an index (but no foreign key constraint, keeping it optional):```ruby db/migrate/XXXXXXXXXXXXXX_add_brand_id_to_spree_products.rb@@ -98,10 +106,18 @@ endRun the migration:-```bash+<CodeGroup>++```bash Spree CLI (Docker)+spree migrate+```++```bash Rails (native)bin/rails db:migrate```+</CodeGroup>+<Info>We intentionally don't add a foreign key constraint. This keeps the association optional and avoids issues if brands are deleted. Spree follows this pattern for flexibility.</Info>@@ -110,10 +126,18 @@ bin/rails db:migrateSpree provides a generator to create decorator files with the correct structure:-```bash+<CodeGroup>++```bash Spree CLI (Docker)+spree generate model_decorator Spree::Product+```++```bash Rails (native)bin/rails g spree:model_decorator Spree::Product```+</CodeGroup>+This creates `app/models/spree/product_decorator.rb`:```ruby app/models/spree/product_decorator.rb@@ -393,7 +417,7 @@ Spree::PermittedAttributes.product_attributes << :brand_idNow that Brands are connected to Products, let's expose them through the Store API:-<Card title="6. Store API" icon="code" href="/developer/tutorial/store-api">+<Card title="6. API" icon="code" href="/developer/tutorial/api">Create API endpoints for brands and extend the Product API response</Card>@@ -401,7 +425,7 @@ Now that Brands are connected to Products, let's expose them through the Store A- [Model Tutorial](/developer/tutorial/model) - Creating the Brand model- [Admin Tutorial](/developer/tutorial/admin) - Building the admin interface-- [Store API Tutorial](/developer/tutorial/store-api) - Exposing brands through the API+- [API Tutorial](/developer/tutorial/api) - Exposing brands through the API- [Events](/developer/core-concepts/events) - Subscribe to model changes without decorators- [Webhooks](/developer/core-concepts/webhooks) - HTTP callbacks for external integrations- [Decorators](/developer/customization/decorators) - Full decorator referencediff --git a/docs/developer/tutorial/file-uploads.mdx b/docs/developer/tutorial/file-uploads.mdxdeleted file mode 100644index baef6f688a..0000000000--- a/docs/developer/tutorial/file-uploads.mdx+++ /dev/null@@ -1,124 +0,0 @@-----title: File Uploads-description: Learn how to add file uploads to the Brands feature------<Info>- This guide assumes you've completed the [Model](/developer/tutorial/model), [Admin](/developer/tutorial/admin), and [Rich Text](/developer/tutorial/rich-text) tutorials.-</Info>--In this tutorial, we'll add a logo image upload to our Brand model. Spree uses [Rails Active Storage](https://guides.rubyonrails.org/active_storage_overview.html) for handling file attachments, image processing, and storage.--## Step 1: Add Attachment to the Model--First, let's add a logo attachment to the Brand model:--```ruby app/models/spree/brand.rb {3}-module Spree- class Brand < Spree::Base- has_one_attached :logo-- # ... existing code ...- end-end-```--## Step 2: Permit the Attachment Attribute--For the admin form to accept the file upload, we need to permit the `logo` attribute in the controller.--Update your brands controller:--```ruby app/controllers/spree/admin/brands_controller.rb {10}-module Spree- module Admin- class BrandsController < ResourceController- private-- def permitted_resource_params- params.require(:brand).permit(- :name,- :description,- :logo- )- end- end- end-end-```--## Step 3: Add File Upload Field to the Admin Form--Now let's add the file upload field to the brand form. Spree provides a `spree_file_field` helper that handles everything including:--- Drag and drop upload-- Image preview-- Direct upload to storage-- Optional image cropping--Update your brand form partial:--```erb app/views/spree/admin/brands/_form.html.erb {11-19}-<div class="card mb-6">- <div class="card-header">- <h5 class="card-title"><%= Spree.t(:general_settings) %></h5>- </div>- <div class="card-body">- <%= f.spree_text_field :name, required: true %>- <%= f.spree_rich_text_area :description %>- </div>-</div>--<div class="card mb-6">- <div class="card-header">- <h5 class="card-title"><%= Spree.t(:logo) %></h5>- </div>- <div class="card-body">- <%= f.spree_file_field :logo, width: 300, height: 300 %>- </div>-</div>-```--### Add cropping functionality--To enable cropping functionality, add the `crop: true` option to the `spree_file_field` helper.--## Step 4: Display the Logo in the Index Table--Let's show a thumbnail of the brand logo in the admin index view.--Update the table header partial:--```erb app/views/spree/admin/brands/_table_header.html.erb {2}-<tr>- <th><%= Spree.t(:logo) %></th>- <th><%= Spree.t(:name) %></th>- <th></th>-</tr>-```--Update the table row partial to display the logo:--```erb app/views/spree/admin/brands/_table_row.html.erb {3-12}-<tr id="<%= spree_dom_id brand %>" class="cursor-pointer" data-controller="row-link">- <td data-action="click->row-link#openLink" class="w-70">- <div class="d-flex align-items-center gap-2">- <% if brand.logo.attached? %>- <%= spree_image_tag brand.logo, width: 48, height: 48, class: 'rounded' %>- <% else %>- <div class="bg-light rounded d-flex align-items-center justify-content-center" style="width: 48px; height: 48px;">- <%= icon('photo-off', class: 'text-muted') %>- </div>- <% end %>- <span class="font-weight-bold"><%= brand.name %></span>- </div>- </td>- <td data-action="click->row-link#openLink" class="w-20">- <%= spree_date(brand.created_at) %>- </td>- <td class="actions w-10">- <%= link_to_edit(brand, data: { row_link_target: :link, turbo_frame: '_top' }) if can? :edit, brand %>- </td>-</tr>-```-diff --git a/docs/developer/tutorial/introduction.mdx b/docs/developer/tutorial/introduction.mdxindex 290c601704..10df0b5af0 100644--- a/docs/developer/tutorial/introduction.mdx+++ b/docs/developer/tutorial/introduction.mdx@@ -1,52 +1,59 @@---title: TutorialsidebarTitle: Introduction-description: Learn how to build a custom feature from scratch, covering models, Admin dashboard and API.+description: Build a complete custom feature — model, admin UI, Store API, and TypeScript storefront integration — the Spree way.----This tutorial walks you through creating a complete Spree feature from scratch, covering models, Admin dashboard, Store API, and TypeScript SDK integration.-You will also learn how to extend core Spree features to connect them with your new feature.-By the end, you'll understand how to add new manageable features to the Spree platform.+This tutorial walks you through creating a complete Spree feature from scratch: a "Brands" feature that lets admins manage [Product](/developer/core-concepts/products) brands, exposes them through the Store API, and consumes them from TypeScript.-## Overview+It's written for **both backend and frontend developers**. The Ruby you'll write is minimal and mostly generated — Spree's generators produce convention-correct models, admin UIs, and API endpoints, and the TypeScript SDK gives you typed access from your storefront. You don't need to be a Rails expert to follow along.-To fully implement a new feature, you will typically create the following components:+## Before you start-* Database model-* Admin Dashboard controllers and views-* Store API endpoints and serializers-* TypeScript SDK integration-* Automated tests+You need a running Spree app. The fastest path is [create-spree-app](/developer/create-spree-app/quickstart) — a Docker-based project with the [Spree CLI](/developer/cli/quickstart), no local Ruby required:++```bash+npx create-spree-app@latest my-store+```++A classic Rails app with Spree gems works just as well. **Every command in this tutorial is shown in two forms** — `spree <command>` (Spree CLI, runs inside Docker) and `bin/rails …` (native) — pick the column that matches your setup and ignore the other.++<Note>+ **create-spree-app projects:** run `spree eject` once before starting. Fresh projects use a prebuilt Docker image; ejecting switches to the dev setup that mounts `backend/` into the container, so the files the generators create land in your project (and reload live as you edit them).+</Note>++<Tip>+ Using an AI coding agent? Install the [Spree agent skills](/developer/agentic/agent-skills) (`npx skills add spree/agent-skills`) and connect the [docs MCP server](/developer/agentic/mcp) before starting — your agent will know the conventions this tutorial teaches and can follow along with you. See [Agentic Development](/developer/agentic/overview).+</Tip>++## What you'll build++* A `Brand` model with a rich text description and an uploadable logo — one generator command+* An admin UI for managing brands — one generator command, then customized+* A `brand` association on Products, surfaced in the product admin form+* Store API endpoints (`GET /api/v3/store/brands`) with serializers and prefixed IDs+* Typed TypeScript access to brands from your storefront via `@spree/sdk`+* Automated tests for all of it## Tutorial Sections<CardGroup cols={2}><Card title="1. Model" icon="database" href="/developer/tutorial/model">- Create the Brand model with migrations, validations, and associations+ Generate the Brand model — columns, rich text description, and logo upload in one command</Card><Card title="2. Admin Dashboard" icon="gauge" href="/developer/tutorial/admin">- Build admin interface for managing brands- </Card>- <Card title="3. Rich Text" icon="align-left" href="/developer/tutorial/rich-text">- Add rich text descriptions using Action Text- </Card>- <Card title="4. File Uploads" icon="image" href="/developer/tutorial/file-uploads">- Add logo images with Active Storage+ Scaffold the admin UI, then add the description editor, logo upload, and table columns</Card>- <Card title="5. Extending Core Models" icon="plug" href="/developer/tutorial/extending-models">- Connect Brands to Products using associations+ <Card title="3. Extending Core Models" icon="plug" href="/developer/tutorial/extending-models">+ Connect Brands to Products using a decorator and an association</Card>- <Card title="6. Store API" icon="code" href="/developer/tutorial/store-api">- Expose Brands through the Store API with serializers, controllers, and routes+ <Card title="4. API" icon="code" href="/developer/tutorial/api">+ Expose Brands through the Store and Admin APIs — generated in one command, or hand-built to learn the pieces</Card>- <Card title="7. SDK" icon="js" href="/developer/tutorial/sdk">+ <Card title="5. SDK" icon="js" href="/developer/tutorial/sdk">Consume Brand endpoints from TypeScript using the SDK</Card>- <Card title="8. Testing" icon="flask-vial" href="/developer/tutorial/testing">+ <Card title="6. Testing" icon="flask-vial" href="/developer/tutorial/testing">Write automated tests for your feature</Card></CardGroup>--## Example: Building a Brands Feature--In this guide we will create a complete "Brands" feature that allows admins to manage [Product](/developer/core-concepts/products) brands.diff --git a/docs/developer/tutorial/model.mdx b/docs/developer/tutorial/model.mdxindex e9f3198eba..1d6b526742 100644--- a/docs/developer/tutorial/model.mdx+++ b/docs/developer/tutorial/model.mdx@@ -1,41 +1,112 @@---title: Model-description: Learn how to create a database model for the Brands feature+description: Create the Brand model — columns, rich text description, and logo upload — with a single generator command----## Step 1: Create the Model and Database Migration+In this step we'll create the `Spree::Brand` model with everything it needs: a `name` column, a rich text `description`, and an uploadable `logo`.-To create a new model and database migration file, run the following command:+## Step 1: Generate the Model-```bash-bin/rails g spree:model Spree::Brand name:string:index+Spree ships a `spree:model` generator that produces a model and migration following all Spree conventions — `Spree::` namespacing, prefixed IDs, presence validations, and API filtering allowlists. It understands Rails attribute types including the virtual ones, so rich text and file attachments are part of the same command:++<CodeGroup>++```bash Spree CLI (Docker)+spree generate model Brand name:string:index description:rich_text logo:attachment+```++```bash Rails (native)+bin/rails g spree:model Brand name:string:index description:rich_text logo:attachment```-This will create a couple of files:-- `app/models/spree/brand.rb` - the model file-- `db/migrate/XXXXXXXXXXXXXX_create_spree_brands.rb` - the database migration file+</CodeGroup>++<Info>+ Throughout this tutorial every command is shown in two forms. **Spree CLI** is for projects created with [create-spree-app](/developer/create-spree-app/quickstart), where the app runs in Docker and `spree <command>` routes into the container. **Rails (native)** is for classic Rails apps running Spree directly on your machine.+</Info>++This creates two files:++- `app/models/spree/brand.rb` — the model+- `db/migrate/XXXXXXXXXXXXXX_create_spree_brands.rb` — the migration++Now apply the migration:-Now run the migration:+<CodeGroup>-```bash+```bash Spree CLI (Docker)+spree migrate+```++```bash Rails (native)bin/rails db:migrate```-This will create the table `spree_brands` with the column `name` in the database. The `name` column is indexed for faster lookups. Also the model file `app/models/spree/brand.rb` is created.+</CodeGroup>-## Step 2: Extend the Model file+This creates the `spree_brands` table with an indexed `name` column. The `description` and `logo` attributes don't add columns — rich text lives in Action Text's `action_text_rich_texts` table, and uploads live in Active Storage's tables.-Now that the model file is created, let's add some additional functionality to it, starting with validations:+## Step 2: Understand the Generated Model-```ruby app/models/spree/brand.rb {3-4}+Open `app/models/spree/brand.rb`:++```ruby app/models/spree/brand.rbmodule Spree- class Brand < Spree::Base- # Validations+ class Brand < Spree.base_class+ has_prefix_id :brand++ has_rich_text :description+ has_one_attached :logo+validates :name, presence: true++ self.whitelisted_ransackable_attributes = %w[name]+ self.whitelisted_ransackable_associations = %w[]+ self.whitelisted_ransackable_scopes = %w[]endend```-This is a standard [Ruby on Rails ActiveRecord model](https://guides.rubyonrails.org/active_record_basics.html). Let's break down each part:-- Inherits from `Spree::Base` to automatically inherit all Spree functionality. Also the model itself is namespaced under `Spree::` module, so it's available as `Spree::Brand` in the application.-- `validates :name, presence: true` - using ActiveRecord validations to ensure that the name is present.+Line by line:++- **`Spree.base_class`** — inherits all Spree model functionality (multi-store scoping helpers, preferences, and more). The class is namespaced under `Spree::`, so it's available as `Spree::Brand`.+- **`has_prefix_id :brand`** — records get Stripe-style public IDs like `brand_k5nR8xLq`. APIs never expose raw database IDs.+- **`has_rich_text :description`** — formatted content via [Action Text](https://guides.rubyonrails.org/action_text_overview.html).+- **`has_one_attached :logo`** — file uploads via [Active Storage](https://guides.rubyonrails.org/active_storage_overview.html), with image processing and direct-to-storage uploads.+- **`validates :name, presence: true`** — generated automatically for required columns.+- **`whitelisted_ransackable_attributes`** — controls which attributes API clients may filter and sort by. Only allowlisted attributes are queryable, so adding `name` here is what later makes `?q[name_cont]=nike` work.++## Step 3: Try It in the Console++<CodeGroup>++```bash Spree CLI (Docker)+spree console+```++```bash Rails (native)+bin/rails console+```++</CodeGroup>++```ruby+brand = Spree::Brand.create!(name: "Wilson")+brand.prefixed_id # => "brand_k5nR8xLq"++brand.update!(description: "<h1>Hello</h1><p>World</p>")+brand.description.to_s # => rendered rich text HTML+brand.description.to_plain_text # => "Hello World"++Spree::Brand.find_by_prefix_id!("brand_k5nR8xLq") # lookup by public ID+```++We'll upload the logo through the admin UI in the next step — the model side is already done.++<Tip>+ The generator accepts more attribute types and options — references with auto-resolved class names (`user:belongs_to`), unique indexes (`slug:string:uniq`), soft delete (`--paranoid`), and custom fields support (`--metafields`). Run it with `--help` to see everything.+</Tip>++## Next Step++The model is complete. Now let's give admins a UI to manage brands: [Admin Dashboard](/developer/tutorial/admin).diff --git a/docs/developer/tutorial/rich-text.mdx b/docs/developer/tutorial/rich-text.mdxdeleted file mode 100644index 7482ee7b3a..0000000000--- a/docs/developer/tutorial/rich-text.mdx+++ /dev/null@@ -1,75 +0,0 @@-----title: Rich Text-description: Learn how to add rich text content to the Brands feature using Action Text------<Info>- This guide assumes you've completed the [Model](/developer/tutorial/model) and [Admin](/developer/tutorial/admin) tutorials.-</Info>--Our Brand model has a `name` attribute to store the brand name. However it's missing a description. That's because we're going to use [Action Text](https://guides.rubyonrails.org/action_text_overview.html) to handle the rich text content.--## Step 1: Add Action Text to the Model--```ruby app/models/spree/brand.rb {4-5}-module Spree- class Brand < Spree::Base- # Action text for rich text content- has_rich_text :description-- # ... other code ...- end-end-```--You don't need to run any migrations, as we won't be adding any new columns to the `spree_brands` table. That's because [Action Text](https://guides.rubyonrails.org/action_text_overview.html) stores all the rich text content in a separate table called `action_text_rich_texts`.--You can access the description content in code like this:--```ruby-brand.description.to_s-# => "<h1>Hello</h1><p>World</p>"-```--Or if you prefer plain text:--```ruby-brand.description.to_plain_text-# => "Hello World"-```--## Step 2: Add a WYSIWYG editor to the Admin Dashboard--In the Admin dashboard we want to use a WYSIWYG editor to add formatted text to the brand description. To do this, edit the `app/views/spree/admin/brands/_form.html.erb` file and add the following code:--```erb app/views/spree/admin/brands/_form.html.erb {4}-<div class="card mb-6">- <div class="card-body">- <%= f.spree_text_field :name %>- <%= f.spree_rich_text_area :description %>- </div>-</div>-```--This will render a WYSIWYG editor to the brand description field in the Admin dashboard.--## Step 3: Update permitted parameters in controller--To permit the `description` attribute to be saved, we need to update the permitted parameters in the controller file and add the following code:--```ruby app/controllers/spree/admin/brands_controller.rb {9}-module Spree- module Admin- class BrandsController < ResourceController- private-- def permitted_resource_params- params.require(:brand).permit(- :name,- :description- )- end- end- end-end-```\ No newline at end of filediff --git a/docs/developer/tutorial/sdk.mdx b/docs/developer/tutorial/sdk.mdxindex e1cc386b08..5ca9537917 100644--- a/docs/developer/tutorial/sdk.mdx+++ b/docs/developer/tutorial/sdk.mdx@@ -3,10 +3,10 @@ title: SDKdescription: Use the TypeScript SDK to consume your custom Brand endpoints and extended Product data----In this tutorial, we'll use the `@spree/sdk` TypeScript SDK to consume the Brand API endpoints we created in the [Store API tutorial](/developer/tutorial/store-api), and work with the extended Product data that now includes brand information.+In this tutorial, we'll use the `@spree/sdk` TypeScript SDK to consume the Brand API endpoints we created in the [API tutorial](/developer/tutorial/api), and work with the extended Product data that now includes brand information.<Info>- This guide assumes you've completed the [Store API](/developer/tutorial/store-api) tutorial and have the Brand endpoints running.+ This guide assumes you've completed the [API](/developer/tutorial/api) tutorial and have the Brand endpoints running.</Info>## What We're Building@@ -117,7 +117,7 @@ const full = await client.products.get(### Filtering Products by Brand-Ransack predicates work on whitelisted attributes and associations. The [Store API tutorial](/developer/tutorial/store-api) shows how to register `brand_id` and `brand` via `Spree.ransack` — once that's done, you can filter:+Ransack predicates work on whitelisted attributes and associations. The [API tutorial](/developer/tutorial/api) shows how to register `brand_id` and `brand` via `Spree.ransack` — once that's done, you can filter:```typescript// Products from a specific brand@@ -168,6 +168,7 @@ products.data.forEach(p => {## Related Documentation-- [Store API Tutorial](/developer/tutorial/store-api) - Creating the Brand API endpoints+- [API Tutorial](/developer/tutorial/api) - Creating the Brand API endpoints- [SDK Overview](/sdk) - Full SDK documentation- [Search & Filtering](/developer/core-concepts/search-filtering) - Ransack predicates and sorting+- [Agentic Development](/developer/agentic/overview) - Agent skills and the docs MCP server cover the SDK patterns used herediff --git a/docs/developer/tutorial/testing.mdx b/docs/developer/tutorial/testing.mdxindex 0a1f082506..11a239d672 100644--- a/docs/developer/tutorial/testing.mdx+++ b/docs/developer/tutorial/testing.mdx@@ -8,31 +8,36 @@ Spree uses [RSpec](https://rspec.info), [Factory Bot](https://github.com/thoughtWe also provide the `spree_dev_tools` gem that helps you write Spree-specific tests.<Info>- This guide assumes you've completed all previous tutorials through [Store API](/developer/tutorial/store-api). You should have a complete `Spree::Brand` model with admin features and API endpoints.+ This guide assumes you've completed all previous tutorials through [API](/developer/tutorial/api). You should have a complete `Spree::Brand` model with admin features and API endpoints.</Info>## Setup-### Step 1: Set RSpec as the Test Framework+**If your app came from [create-spree-app](/developer/create-spree-app/quickstart) or [spree-starter](https://github.com/spree/spree-starter), the test environment is already set up** — RSpec, Factory Bot, Capybara, DatabaseCleaner, and the `spree_dev_tools` helpers (`stub_authorization!`, the `'API v3 Store'` shared context, Spree factories) ship preconfigured in `spec/support/`. Skip to creating the fixtures file below.-```bash-bin/rails g rspec:install-```+<Accordion title="Setting up an app that doesn't have RSpec yet">-### Step 2: Run the spree\_dev\_tools Generator+For an existing Rails app without test setup, install RSpec and the Spree test helpers:-```bash+<CodeGroup>++```bash Spree CLI (Docker)+spree generate rspec:install+spree generate spree_dev_tools:install+```++```bash Rails (native)+bin/rails g rspec:installbin/rails g spree_dev_tools:install```-This adds Spree-specific test helpers to your `spec/support/` directory, including:+</CodeGroup>++The `spree_dev_tools` generator adds the Spree-specific helpers to `spec/support/`: authorization helpers (`stub_authorization!`), Factory Bot configuration, Capybara setup for feature tests, and more.-* Authorization helpers (`stub_authorization!`)-* Factory Bot configuration-* Capybara setup for feature tests-* and more…+</Accordion>-### Step 3: Create the Fixtures Directory and File+### Create the Fixtures Directory and FileWhen writing tests that involve file attachments (like images, PDFs, etc.), you need fixture files that your factories can use. Here's how to set them up.@@ -40,13 +45,11 @@ When writing tests that involve file attachments (like images, PDFs, etc.), youmkdir -p spec/fixtures/files && printf '\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01\x08\x02\x00\x00\x00\x90wS\xde\x00\x00\x00\x0cIDATx\x9cc\xf8\x0f\x00\x00\x01\x01\x00\x05\x18\xd8N\x00\x00\x00\x00IEND\xaeB`\x82' > spec/fixtures/files/logo.png```-### Step 4: Generate Test Files+### What the generators already created-```bash-bin/rails g rspec:model Spree::Brand-```+If you used `spree generate api_resource` in the [API step](/developer/tutorial/api), you already have controller specs (`spec/controllers/spree/api/v3/store/brands_controller_spec.rb` and `…/admin/brands_controller_spec.rb`) and a factory (`spec/factories/spree/brand_factory.rb`). The sections below build the same things by hand — compare as you go, and keep whichever you prefer.-This creates `spec/models/spree/brand_spec.rb`.+For the model spec, create `spec/models/spree/brand_spec.rb` — we'll fill it in below.## Writing Factories@@ -215,10 +218,11 @@ Controller tests verify that your endpoints respond correctly and perform the ex### Store API Controller Tests-Test the API endpoints we created in the [Store API tutorial](/developer/tutorial/store-api). Store API tests use the `'API v3 Store'` shared context which sets up a store, publishable API key, and JWT tokens.+Test the API endpoints we created in the [API tutorial](/developer/tutorial/api). Store API tests use the `'API v3 Store'` shared context which sets up a store, publishable API key, and JWT tokens — it ships in the `spree_api` gem, so require `spree/api/testing_support/v3/base` at the top of the spec.```ruby spec/controllers/spree/api/v3/store/brands_controller_spec.rbrequire 'rails_helper'+require 'spree/api/testing_support/v3/base'RSpec.describe Spree::Api::V3::Store::BrandsController, type: :controller dorender_views@@ -322,6 +326,7 @@ Test that the custom Product serializer includes brand data:```ruby spec/controllers/spree/api/v3/store/products_brand_spec.rbrequire 'rails_helper'+require 'spree/api/testing_support/v3/base'RSpec.describe Spree::Api::V3::Store::ProductsController, type: :controller dorender_views@@ -584,23 +589,37 @@ expect(page).to have_content('Success!')## Running Tests-```bash-# Run all tests-bundle exec rspec+In the Docker flow the container's `DATABASE_URL` points at the development database, so tests need two overrides: a dedicated test database, and DatabaseCleaner's opt-in for non-localhost database hosts (its safeguard against cleaning a database it doesn't own). One-time test database setup:++```bash Spree CLI (Docker) — one-time setup+spree exec env RAILS_ENV=test DATABASE_URL=postgres://postgres@postgres:5432/spree_test bin/rails db:prepare+```++Then run tests:-# Run specific test file-bundle exec rspec spec/models/spree/brand_spec.rb+<CodeGroup>-# Run specific test-bundle exec rspec spec/models/spree/brand_spec.rb:15+```bash Spree CLI (Docker)+# Define once per shell (or add as an alias):+alias spree-rspec='spree exec env RAILS_ENV=test DATABASE_URL=postgres://postgres@postgres:5432/spree_test DATABASE_CLEANER_ALLOW_REMOTE_DATABASE_URL=true bundle exec rspec'-# Run with documentation format-bundle exec rspec --format documentation+spree-rspec # all tests+spree-rspec spec/models/spree/brand_spec.rb # specific file+spree-rspec spec/models/spree/brand_spec.rb:15 # specific test+spree-rspec --format documentation # documentation format+spree-rspec spec/features/ # only feature tests+```-# Run only feature tests-bundle exec rspec spec/features/+```bash Rails (native)+bundle exec rspec # all tests+bundle exec rspec spec/models/spree/brand_spec.rb # specific file+bundle exec rspec spec/models/spree/brand_spec.rb:15 # specific test+bundle exec rspec --format documentation # documentation format+bundle exec rspec spec/features/ # only feature tests```+</CodeGroup>+## Best Practices<CardGroup cols={2}>@@ -669,7 +688,7 @@ spec/* [Model Tutorial](/developer/tutorial/model) - Creating the Brand model* [Admin Tutorial](/developer/tutorial/admin) - Building the admin interface* [Extending Core Models](/developer/tutorial/extending-models) - Connecting Brands to Products-* [Store API Tutorial](/developer/tutorial/store-api) - Creating Brand API endpoints+* [API Tutorial](/developer/tutorial/api) - Creating Brand API endpoints* [RSpec Documentation](https://rspec.info/documentation/) - Official RSpec docs* [Factory Bot Documentation](https://github.com/thoughtbot/factory_bot/blob/main/GETTING_STARTED.md) - Factory Bot guidediff --git a/docs/docs.json b/docs/docs.jsonindex 3b40507751..0e4d166515 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -118,10 +118,30 @@{"source": "/api-reference/introduction","destination": "/api-reference"+ },+ {+ "source": "/developer/tutorial/rich-text",+ "destination": "/developer/tutorial/model"+ },+ {+ "source": "/developer/tutorial/file-uploads",+ "destination": "/developer/tutorial/admin"+ },+ {+ "source": "/developer/tutorial/store-api",+ "destination": "/developer/tutorial/api"}],"contextual": {- "options": ["copy", "view", "chatgpt", "claude", "mcp", "cursor", "vscode"]+ "options": [+ "copy",+ "view",+ "chatgpt",+ "claude",+ "mcp",+ "cursor",+ "vscode"+ ]},"navigation": {"tabs": [@@ -136,7 +156,9 @@{"group": "Getting started","icon": "rocket",- "pages": ["developer/getting-started/quickstart"]+ "pages": [+ "developer/getting-started/quickstart"+ ]},{"group": "Platform",@@ -213,7 +235,9 @@},{"group": "Custom Frontend",- "pages": ["developer/storefront/custom/quickstart"]+ "pages": [+ "developer/storefront/custom/quickstart"+ ]}]},@@ -264,10 +288,8 @@"developer/tutorial/introduction","developer/tutorial/model","developer/tutorial/admin",- "developer/tutorial/rich-text",- "developer/tutorial/file-uploads","developer/tutorial/extending-models",- "developer/tutorial/store-api",+ "developer/tutorial/api","developer/tutorial/sdk","developer/tutorial/testing"]@@ -316,37 +338,51 @@{"group": "Order Routing","icon": "route",- "pages": ["developer/how-to/custom-order-routing"]+ "pages": [+ "developer/how-to/custom-order-routing"+ ]},{"group": "Stock Splitters","icon": "boxes-stacked",- "pages": ["developer/how-to/custom-stock-splitter"]+ "pages": [+ "developer/how-to/custom-stock-splitter"+ ]},{"group": "Payments","icon": "credit-card",- "pages": ["developer/how-to/custom-payment-method"]+ "pages": [+ "developer/how-to/custom-payment-method"+ ]},{"group": "Promotions","icon": "tag",- "pages": ["developer/how-to/custom-promotion"]+ "pages": [+ "developer/how-to/custom-promotion"+ ]},{"group": "Reports","icon": "chart-bar",- "pages": ["developer/how-to/custom-report"]+ "pages": [+ "developer/how-to/custom-report"+ ]},{"group": "Search","icon": "search",- "pages": ["developer/how-to/custom-search-provider"]+ "pages": [+ "developer/how-to/custom-search-provider"+ ]},{"group": "Authentication","icon": "key",- "pages": ["developer/how-to/custom-api-authentication"]+ "pages": [+ "developer/how-to/custom-api-authentication"+ ]}]},@@ -461,7 +497,9 @@},{"group": "Admin API",- "pages": ["developer/sdk/admin/quickstart"]+ "pages": [+ "developer/sdk/admin/quickstart"+ ]}]},@@ -472,7 +510,9 @@"groups": [{"group": "CLI",- "pages": ["developer/cli/quickstart"]+ "pages": [+ "developer/cli/quickstart"+ ]}]},@@ -483,7 +523,25 @@"groups": [{"group": "create-spree-app",- "pages": ["developer/create-spree-app/quickstart"]+ "pages": [+ "developer/create-spree-app/quickstart"+ ]+ }+ ]+ },+ {+ "item": "Agentic Development",+ "icon": "bot",+ "description": "Build Spree with AI coding agents",+ "groups": [+ {+ "group": "Agentic Development",+ "pages": [+ "developer/agentic/overview",+ "developer/agentic/agent-skills",+ "developer/agentic/mcp",+ "developer/agentic/llm-docs"+ ]}]}@@ -552,7 +610,9 @@"groups": [{"group": "Webhooks",- "pages": ["api-reference/webhooks-events"]+ "pages": [+ "api-reference/webhooks-events"+ ]}]},@@ -580,7 +640,9 @@},{"group": "Storefront API",- "pages": ["api-reference/storefront/authentication"],+ "pages": [+ "api-reference/storefront/authentication"+ ],"openapi": {"source": "api-reference/storefront.yaml","directory": "api-reference/storefront"@@ -588,7 +650,9 @@},{"group": "Platform API",- "pages": ["api-reference/platform/authentication"],+ "pages": [+ "api-reference/platform/authentication"+ ],"openapi": {"source": "api-reference/platform.yaml","directory": "api-reference/platform"@@ -603,7 +667,9 @@"groups": [{"group": "Integrations",- "pages": ["integrations/integrations"]+ "pages": [+ "integrations/integrations"+ ]},{"group": "Payments",@@ -616,11 +682,15 @@},{"group": "Tax",- "pages": ["integrations/tax/avalara"]+ "pages": [+ "integrations/tax/avalara"+ ]},{"group": "Search",- "pages": ["integrations/search/meilisearch"]+ "pages": [+ "integrations/search/meilisearch"+ ]},{"group": "Analytics",@@ -631,7 +701,9 @@},{"group": "Marketing",- "pages": ["integrations/marketing/klaviyo"]+ "pages": [+ "integrations/marketing/klaviyo"+ ]},{"group": "SSO, MFA & Social Login",@@ -655,7 +727,9 @@},{"group": "Migration",- "pages": ["user/migration/migrate-from-shopify"]+ "pages": [+ "user/migration/migrate-from-shopify"+ ]},{"group": "How-to Guides",@@ -778,7 +852,9 @@},{"group": "Security",- "pages": ["user/security"]+ "pages": [+ "user/security"+ ]}]},@@ -787,7 +863,9 @@"groups": [{"group": "Overview",- "pages": ["use-case/overview"]+ "pages": [+ "use-case/overview"+ ]},{"group": "B2B Commerce",@@ -838,7 +916,10 @@},"api": {"examples": {- "languages": ["javascript", "curl"]+ "languages": [+ "javascript",+ "curl"+ ]},"openapi": ["api-reference/store.yaml",@@ -846,7 +927,9 @@"api-reference/platform.yaml"],"mdx": {- "server": ["http://localhost:3000"]+ "server": [+ "http://localhost:3000"+ ]}},"navbar": {diff --git a/docs/plans/5.5-agent-skills.md b/docs/plans/5.5-agent-skills.mdindex 9c90674283..0d4e6bb17f 100644--- a/docs/plans/5.5-agent-skills.md+++ b/docs/plans/5.5-agent-skills.md@@ -8,7 +8,7 @@## Summary-`spree/agent-skills` is a standalone GitHub repository ([github.com/spree/agent-skills](https://github.com/spree/agent-skills)) that ships agent-readable guidance for Spree Commerce projects: 26 Claude Code skills (model-invoked, progressive disclosure), a `spree-expert` subagent for multi-step investigations, two safety hooks (block destructive db commands, warn on hardcoded secrets), and an [agents.md](https://agents.md)-spec `AGENTS.md` for cross-tool discovery.+`spree/agent-skills` is a standalone GitHub repository ([github.com/spree/agent-skills](https://github.com/spree/agent-skills)) that ships agent-readable guidance for Spree Commerce projects: 25 Claude Code skills (model-invoked, progressive disclosure), a `spree-expert` subagent for multi-step investigations, two slash commands (`/spree:doctor`, `/spree:audit-upgrade`), two safety hooks (block destructive db commands, warn on hardcoded secrets), and an [agents.md](https://agents.md)-spec `AGENTS.md` for cross-tool discovery.Distribution uses the [`skills`](https://github.com/vercel-labs/skills) CLI from the skills.sh ecosystem — the same channel adopted by Medusa, shadcn/ui, Anthropic, and Vercel for their respective skill sets. End users install with a single command:@@ -16,7 +16,7 @@ Distribution uses the [`skills`](https://github.com/vercel-labs/skills) CLI fromnpx skills add spree/agent-skills```-This installs into the user's project for whichever agent(s) they have configured — Claude Code, Codex, Cursor, GitHub Copilot, Cline, Aider, Zed, Windsurf, OpenCode, and 60+ others — using each tool's native file convention. Claude Code users who want the two safety hooks can additionally install via the plugin marketplace path (`/plugin marketplace add spree/agent-skills` → `/plugin install spree@spree`) which delivers the hooks alongside the skills.+This installs into the user's project for whichever agent(s) they have configured — Claude Code, Codex, Cursor, GitHub Copilot, Cline, Aider, Zed, Windsurf, OpenCode, and 60+ others — using each tool's native file convention. Claude Code users who want the two safety hooks can additionally install via the plugin marketplace path (`/plugin marketplace add spree/agent-skills` → `/plugin install spree@spree`) which delivers the slash commands and hooks alongside the skills.This is **for Spree users, not monorepo contributors.** Skills reference `backend/`, published gems, the `@spree/cli` Docker stack, and the public API surfaces — not the monorepo's `server/` or `SPREE_PATH` workflows.@@ -25,8 +25,8 @@ This is **for Spree users, not monorepo contributors.** Skills reference `backen- **Standalone repository at [`spree/agent-skills`](https://github.com/spree/agent-skills)**, not a package inside the monorepo. The skills repo evolves independently from gem releases — skill content changes when API surface or conventions shift, not in lockstep with `spree-5.5.x` tags. Matches Medusa's precedent (`medusajs/medusa-agent-skills`).- **Distribution channel is the [`skills`](https://github.com/vercel-labs/skills) CLI** (`npx skills add spree/agent-skills`). Tool-agnostic, supports 70+ agentic CLIs out of the box, free, automatic listing at [skills.sh](https://skills.sh). No `npm install`, no bespoke `@spree/cli` subcommand for installing skills.- **No npm package.** Skills live in the GitHub repo. Neither `create-spree-app` nor any other tool needs the path-index `dist/index.js` we previously published.-- **Claude Code plugin install (`/plugin install spree@spree`) is the secondary path**, used by Claude Code users who want the two safety hooks (which `npx skills` doesn't deliver). `.claude-plugin/plugin.json` is committed in the same standalone repo so both install paths point at the same source.-- **26 skills, one subagent, two hooks.** The skill set was sized to match OrcaQubits' reference plugin parity (promotions, payments, performance, deployment, checkout, catalog, pricing, shipping, API v3, events+webhooks, SDK, i18n, legacy v2 migration, security, testing) plus Spree-specific (`spree-project`, `spree-customization`, `spree-resource`, `spree-decorators`, `spree-dependencies`, `spree-upgrade`, `spree-data-model`, `spree-extensions`, `spree-admin`, `spree-dashboard`, `spree-storefront`).+- **Claude Code plugin install (`/plugin install spree@spree`) is the secondary path**, used by Claude Code users who want the two slash commands and two safety hooks (which `npx skills` doesn't deliver). `.claude-plugin/plugin.json` is committed in the same standalone repo so both install paths point at the same source.+- **25 skills, one subagent, two commands, two hooks.** The skill set was sized to match OrcaQubits' reference plugin parity (promotions, payments, performance, deployment, checkout, catalog, pricing, shipping, API v3, events+webhooks, SDK, i18n, legacy v2 migration, security, testing) plus Spree-specific (`spree-project`, `spree-customization`, `spree-resource`, `spree-decorators`, `spree-dependencies`, `spree-upgrade`, `spree-data-model`, `spree-extensions`, `spree-admin`, `spree-storefront`). The `spree-dashboard` skill (React admin extension) is held back until the React admin GAs with Spree 6.0 — shipping instructions for an unreleased admin would misroute 5.x users; it returns to the set at 6.0.- **`AGENTS.md` at the repo root for cross-tool discovery.** Tools that walk up from cwd looking for `AGENTS.md` (Codex CLI, Aider, Zed, Copilot, Cursor fallback) find it automatically when the user has cloned/installed into their project.- **Plugin needs a `version` field** in `.claude-plugin/plugin.json`. Without one, every commit looks like a new version to Claude Code (documented friction in `anthropics/claude-plugins-official#615`). Bump on each release, tag the commit with the matching `v<x.y.z>`.- **`create-spree-app` does NOT bundle skills into scaffolded projects.** It prints a "next steps" hint after scaffold pointing users at `npx skills add spree/agent-skills`. The scaffolded project's root `AGENTS.md` template also documents this command. Decoupling the scaffold from the skill content lets each release on its own cadence.@@ -46,7 +46,7 @@ agent-skills/│ ├── block_destructive_db.sh│ └── warn_on_secrets.sh├── skills/-│ └── <skill-name>/SKILL.md # 26 skills, each YAML frontmatter (name, description) + markdown body+│ └── <skill-name>/SKILL.md # 25 skills, each YAML frontmatter (name, description) + markdown body├── AGENTS.md # Cross-tool entry point (agents.md spec)├── README.md # User-facing install docs leading with `npx skills add`├── LICENSE # MIT@@ -55,7 +55,7 @@ agent-skills/No `package.json`, no `src/`, no TypeScript build, no `dist/`. Just content + manifests. Matches `anthropics/skills` convention.-### The 26 skills+### The 25 skills| Skill | Coverage ||---|---|@@ -78,7 +78,6 @@ No `package.json`, no `src/`, no TypeScript build, no `dist/`. Just content + ma| `spree-pricing` | Multi-currency, price lists (5.5), EU Omnibus / PriceHistory || `spree-shipping-fulfillment` | Shipments, methods, rates, stock locations, the 6.0 Fulfillment rename || `spree-admin` | Legacy Rails admin customization (5.x default) |-| `spree-dashboard` | 6.0 React SPA extension via `defineDashboardPlugin` || `spree-storefront` | Next.js storefront + `@spree/sdk` || `spree-i18n` | UI translations (`Spree.t`) + data translations (Mobility) || `spree-testing` | RSpec + Factory Bot + `spree_dev_tools` |@@ -142,7 +141,7 @@ The scaffold **does not bundle skills** any more. Instead:```textAgent skills (optional)npx skills add spree/agent-skills- # Adds 26 Spree skills to whichever AI agent(s) you use+ # Adds 25 Spree skills to whichever AI agent(s) you use# (Claude Code, Codex, Cursor, Copilot, Cline, Aider, +60 others)```