Skip to content

armgit / spree

Public Imported from GitHub
0

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.

Fix: Made AGENTS.md the agent instructions file and added an agent skills prompt (#14906)

Damian Legawiec6bcdb66e72b7
diff --git a/.changeset/agents-md-and-agent-skills.md b/.changeset/agents-md-and-agent-skills.md
new file mode 100644
index 0000000000..9cce8bd73b
--- /dev/null
+++ b/.changeset/agents-md-and-agent-skills.md
@@ -0,0 +1,6 @@
+---
+"create-spree-app": minor
+"@spree/cli": patch
+---
+
+New projects now ask whether to install the Spree agent skills (default yes; `--agent-skills` / `--no-agent-skills` skip the question). The generated `AGENTS.md` is now the main instructions file for coding agents, with `CLAUDE.md` importing it, and it requires agents to run every command through the Spree CLI. `spree add dashboard` and `spree add seller-dashboard` now include a `CLAUDE.md` that imports the app's `AGENTS.md`, so Claude Code reads it too.
diff --git a/.changeset/seller-client-export.md b/.changeset/seller-client-export.md
new file mode 100644
index 0000000000..a7bc3789ac
--- /dev/null
+++ b/.changeset/seller-client-export.md
@@ -0,0 +1,5 @@
+---
+"@spree/seller-dashboard": minor
+---
+
+`sellerClient` is now exported, so seller panel customizations can call the Seller API from their own hooks.
diff --git a/.github/workflows/packages.yml b/.github/workflows/packages.yml
index f37e34826b..96117c00c7 100644
--- a/.github/workflows/packages.yml
+++ b/.github/workflows/packages.yml
@@ -151,7 +151,7 @@ jobs:
run: |
CLI_TARBALL=$(ls "$RUNNER_TEMP"/tarballs/spree-cli-*.tgz)
SPREE_CLI_VERSION="file:$CLI_TARBALL" node packages/create-spree-app/dist/index.js "$RUNNER_TEMP/app" \
- --no-start --no-storefront --seller-dashboard --use-pnpm
+ --no-start --no-storefront --seller-dashboard --no-agent-skills --use-pnpm
# The apps pin @spree/* to npm ranges. Overriding every package with its
# tarball also replaces the copies other @spree/* packages depend on.
diff --git a/docs/developer/agentic/agent-skills.mdx b/docs/developer/agentic/agent-skills.mdx
index 5c181a903d..87adbead8a 100644
--- a/docs/developer/agentic/agent-skills.mdx
+++ b/docs/developer/agentic/agent-skills.mdx
@@ -15,7 +15,7 @@ The skills target Spree 6. For a Spree 5 project, use the [`v0.3.0` release](htt
</Note>
-Run from your project directory:
+Projects created with [create-spree-app](/developer/create-spree-app/quickstart) install every skill during setup, unless you answer no or pass `--no-agent-skills`. To add them to any other project, run from your project directory:
```bash
npx skills add spree/agent-skills
diff --git a/docs/developer/agentic/llm-docs.mdx b/docs/developer/agentic/llm-docs.mdx
index e5f7fec805..9796159cc4 100644
--- a/docs/developer/agentic/llm-docs.mdx
+++ b/docs/developer/agentic/llm-docs.mdx
@@ -55,4 +55,4 @@ Projects scaffolded with [create-spree-app](/developer/create-spree-app/quicksta
## 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.
+`create-spree-app` scaffolds every project with an `AGENTS.md` that tells coding agents where the local docs live, how to inspect live data with `spree api`, and that every command goes through the [Spree CLI](/developer/cli/quickstart) — `spree migrate`, `spree console`, `spree rspec` — never `bin/rails`, `bundle` or `rake` directly. `server/AGENTS.md` adds the customization patterns to follow. Each directory also has a `CLAUDE.md` that imports its `AGENTS.md`, so Claude Code reads the same instructions as every other agent. The scaffold also installs the [agent skills](/developer/agentic/agent-skills) unless you opt out.
diff --git a/docs/developer/agentic/mcp.mdx b/docs/developer/agentic/mcp.mdx
index 6dbdc1b1ff..591597d18c 100644
--- a/docs/developer/agentic/mcp.mdx
+++ b/docs/developer/agentic/mcp.mdx
@@ -70,5 +70,5 @@ The server exposes two tools: full-text **search** across the documentation, and
| **[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 `AGENTS.md` and `CLAUDE.md` already points agents at the local `@spree/docs` package first — MCP complements it for anything newer than your installed docs version.
+ In create-spree-app projects the generated `AGENTS.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.mdx
index 52f8210afc..23f82dd284 100644
--- a/docs/developer/agentic/overview.mdx
+++ b/docs/developer/agentic/overview.mdx
@@ -17,7 +17,7 @@ Spree ships first-class tooling for AI-assisted development. Whether you use Cla
<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.
+ 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.
@@ -32,8 +32,8 @@ Spree ships first-class tooling for AI-assisted development. Whether you use Cla
## 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.
+1. **Scaffold** a project with `npx create-spree-app@latest my-store` — it generates an `AGENTS.md`, installs `@spree/docs` for local reference, and wires up the CLI.
+2. **Keep the agent skills** the scaffold offers to install (or add them later 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`.
diff --git a/docs/developer/create-spree-app/quickstart.mdx b/docs/developer/create-spree-app/quickstart.mdx
index 01e0992b23..e4f487a6ad 100644
--- a/docs/developer/create-spree-app/quickstart.mdx
+++ b/docs/developer/create-spree-app/quickstart.mdx
@@ -13,8 +13,9 @@ npx create-spree-app@latest my-store
The CLI walks you through an interactive setup:
1. Include **Next.js Storefront** (default: yes)
-2. Optionally load **sample data** (products, categories, images)
-3. Optionally **start Docker services** immediately
+2. Include the **Seller Panel**, for marketplaces (default: yes)
+3. Install the **[Spree agent skills](/developer/agentic/agent-skills)**, which teach AI coding agents how to work with Spree (default: yes)
+4. **Start Docker services** immediately (default: yes)
Once complete, your store is running at [http://localhost:3000](http://localhost:3000) — setup pulls the latest Spree image, seeds the database, and configures API keys, then prints a summary with your admin credentials and keys. If you skipped starting services, the first `pnpm dev` completes setup automatically.
@@ -39,6 +40,8 @@ npx create-spree-app@latest my-store --no-seller-dashboard --no-storefront --no-
| `--seller-dashboard` | Include the marketplace seller panel without asking |
| `--no-seller-dashboard` | Skip the marketplace seller panel |
| `--no-storefront` | Skip Next.js storefront setup |
+| `--agent-skills` | Install the Spree agent skills without asking |
+| `--no-agent-skills` | Skip installing the Spree agent skills |
| `--no-start` | Don't start Docker services after scaffolding |
| `--port <number>` | Port for the Spree backend (default: `3000`) |
| `--use-npm` | Use npm as package manager |
@@ -76,12 +79,13 @@ my-store/
├── .dockerignore # Keeps the production build context to sources
├── .gitignore
├── package.json # Scripts and the pinned @spree/cli
+├── .agents/skills/ # Spree agent skills (unless --no-agent-skills)
├── AGENTS.md # Instructions for coding agents
-├── CLAUDE.md # Project layout and conventions
+├── CLAUDE.md # Imports AGENTS.md for Claude Code
└── README.md # How to run everything
```
-**`server/` is the only part that is Spree's.** The apps under `apps/` are ordinary Vite and Next.js projects you own — restyle, restructure or replace them without forking anything. Each carries its own instructions (`server/CLAUDE.md`, `apps/dashboard/AGENTS.md`), which is also what a coding agent reads.
+**`server/` is the only part that is Spree's.** The apps under `apps/` are ordinary Vite and Next.js projects you own — restyle, restructure or replace them without forking anything. Each carries its own instructions for coding agents (`server/AGENTS.md`, `apps/dashboard/AGENTS.md`).
### What's in docker-compose.yml
diff --git a/docs/developer/getting-started/quickstart.mdx b/docs/developer/getting-started/quickstart.mdx
index 3554c900cf..af66b7f4e5 100644
--- a/docs/developer/getting-started/quickstart.mdx
+++ b/docs/developer/getting-started/quickstart.mdx
@@ -38,7 +38,7 @@ my-store/
├── docker-compose.yml # The local stack
├── package.json # Scripts and the pinned @spree/cli
├── AGENTS.md # Instructions for coding agents
-├── CLAUDE.md # Project layout and conventions
+├── CLAUDE.md # Imports AGENTS.md for Claude Code
└── README.md # How to run everything
```
@@ -71,7 +71,7 @@ See the [Spree CLI guide](/developer/cli/quickstart) for all commands and the [A
In a hurry? Jump straight to the [tutorial](/developer/tutorial/introduction) to build a feature end to end, the [Next.js Storefront](/developer/storefront/nextjs/quickstart) to put a storefront in front of it, or the [API reference](/api-reference/admin-api/introduction) to see what you can do with the Admin API.
<Tip>
- Using an AI coding agent? Run `npx skills add spree/agent-skills` in your new project — it teaches your agent the customization patterns before you write a line of code. See [Agentic Development](/developer/agentic/overview).
+ Using an AI coding agent? `create-spree-app` installs the [Spree agent skills](/developer/agentic/agent-skills) unless you said no — if you skipped them, run `npx skills add spree/agent-skills` in your project. They teach your agent the customization patterns before you write a line of code. See [Agentic Development](/developer/agentic/overview).
</Tip>
---
diff --git a/packages/create-spree-app/README.md b/packages/create-spree-app/README.md
index ca8a4b3b08..2663ab1f15 100644
--- a/packages/create-spree-app/README.md
+++ b/packages/create-spree-app/README.md
@@ -14,6 +14,8 @@ npx create-spree-app my-store
| `--seller-dashboard` | Include the marketplace seller panel without asking |
| `--no-seller-dashboard` | Skip the marketplace seller panel (also available later via `spree add seller-dashboard`) |
| `--no-storefront` | Skip Next.js storefront setup |
+| `--agent-skills` | Install the Spree agent skills without asking |
+| `--no-agent-skills` | Skip installing the Spree agent skills |
| `--no-start` | Don't start Docker services (the first `dev` run completes setup instead) |
| `--port <number>` | Port for the Spree backend (default: `3000`) |
| `--use-npm` / `--use-yarn` / `--use-pnpm` | Package manager (auto-detected from how you run the command) |
diff --git a/packages/create-spree-app/src/agent-skills.ts b/packages/create-spree-app/src/agent-skills.ts
new file mode 100644
index 0000000000..d7c6f8881c
--- /dev/null
+++ b/packages/create-spree-app/src/agent-skills.ts
@@ -0,0 +1,24 @@
+import { execa } from 'execa'
+import { AGENT_SKILLS_REPO } from './constants.js'
+import type { PackageManager } from './types.js'
+import { dlxCommand } from './utils.js'
+
+/**
+ * Install every Spree agent skill into the project, for each coding agent the
+ * `skills` CLI detects, without prompting.
+ *
+ * @param projectDir absolute path to the generated project
+ * @param pm the scaffold's package manager, which runs the `skills` CLI
+ */
+export async function installAgentSkills(projectDir: string, pm: PackageManager): Promise<void> {
+ const [command, ...runnerArgs] = dlxCommand(pm).split(' ')
+ // npx asks before downloading a package it has not cached; --yes answers it.
+ if (pm === 'npm') runnerArgs.push('--yes')
+
+ await execa(
+ command,
+ [...runnerArgs, 'skills', 'add', AGENT_SKILLS_REPO, '--skill', '*', '--yes'],
+ // A stalled download must fail, so the scaffold can warn and move on.
+ { cwd: projectDir, stdio: 'ignore', timeout: 120_000 },
+ )
+}
diff --git a/packages/create-spree-app/src/constants.ts b/packages/create-spree-app/src/constants.ts
index 232a20097d..01619ec76a 100644
--- a/packages/create-spree-app/src/constants.ts
+++ b/packages/create-spree-app/src/constants.ts
@@ -6,6 +6,7 @@ export const SELLER_DASHBOARD_PORT = 5174
export const DOCS_MCP_URL = 'https://spreecommerce.org/docs/mcp'
export const STOREFRONT_REPO = 'https://github.com/spree/storefront.git'
+export const AGENT_SKILLS_REPO = 'spree/agent-skills'
/**
* pnpm pinned into the generated root package.json's `packageManager` field.
diff --git a/packages/create-spree-app/src/index.ts b/packages/create-spree-app/src/index.ts
index 8de72f4a15..87fd2291f3 100644
--- a/packages/create-spree-app/src/index.ts
+++ b/packages/create-spree-app/src/index.ts
@@ -18,6 +18,8 @@ const program = new Command()
.option('--seller-dashboard', 'include the marketplace seller dashboard')
.option('--no-seller-dashboard', 'skip the marketplace seller dashboard')
.option('--no-storefront', 'skip Next.js storefront setup')
+ .option('--agent-skills', 'install the Spree agent skills without asking')
+ .option('--no-agent-skills', 'skip installing the Spree agent skills')
// Deprecated: the dashboard is included by default. Hidden, kept so
// existing scripts keep working.
.addOption(new Option('--react-dashboard').hideHelp())
@@ -46,6 +48,7 @@ const program = new Command()
noSellerDashboard:
flags.sellerDashboard === undefined ? undefined : flags.sellerDashboard === false,
noDashboard: flags.dashboard === false,
+ noAgentSkills: flags.agentSkills === undefined ? undefined : flags.agentSkills === false,
noStart: flags.start === false ? true : undefined,
packageManager,
})
diff --git a/packages/create-spree-app/src/prompts.ts b/packages/create-spree-app/src/prompts.ts
index 749db66b34..6d7ca7f090 100644
--- a/packages/create-spree-app/src/prompts.ts
+++ b/packages/create-spree-app/src/prompts.ts
@@ -7,6 +7,7 @@ interface PromptFlags {
noStorefront?: boolean
noSellerDashboard?: boolean
noDashboard?: boolean
+ noAgentSkills?: boolean
noStart?: boolean
packageManager?: PackageManager
}
@@ -68,6 +69,22 @@ export async function runPrompts(
sellerDashboard = sellerResult
}
+ let agentSkills: boolean
+ if (flags.noAgentSkills !== undefined) {
+ agentSkills = !flags.noAgentSkills
+ } else {
+ const skillsResult = await p.confirm({
+ message: `Install Spree agent skills?\n${pc.dim('Teaches AI coding agents (Claude Code, Codex, Cursor, Copilot and others) how to work with Spree')}`,
+ initialValue: true,
+ })
+
+ if (p.isCancel(skillsResult)) {
+ p.cancel('Setup cancelled.')
+ process.exit(0)
+ }
+ agentSkills = skillsResult
+ }
+
let start: boolean
if (flags.noStart !== undefined) {
start = !flags.noStart
@@ -89,6 +106,7 @@ export async function runPrompts(
storefront,
dashboard,
sellerDashboard,
+ agentSkills,
start,
packageManager: flags.packageManager ?? 'npm',
}
diff --git a/packages/create-spree-app/src/scaffold.ts b/packages/create-spree-app/src/scaffold.ts
index 92e5ad5730..ac1c9dc42a 100644
--- a/packages/create-spree-app/src/scaffold.ts
+++ b/packages/create-spree-app/src/scaffold.ts
@@ -3,7 +3,9 @@ import path from 'node:path'
import * as p from '@clack/prompts'
import { execa } from 'execa'
import pc from 'picocolors'
+import { installAgentSkills } from './agent-skills.js'
import {
+ AGENT_SKILLS_REPO,
DASHBOARD_PORT,
DOCS_MCP_URL,
SELLER_DASHBOARD_PORT,
@@ -12,7 +14,7 @@ import {
import { scaffoldApp } from './dashboard.js'
import { downloadServer } from './server.js'
import { installRootDeps, scaffoldStorefront } from './storefront.js'
-import { agentsMdContent, rootClaudeMdContent } from './templates/claude-md.js'
+import { agentsMdContent, claudeMdContent } from './templates/agents-md.js'
import { dependabotContent } from './templates/dependabot.js'
import { envContent } from './templates/env.js'
import { dockerignoreContent, gitignoreContent } from './templates/gitignore.js'
@@ -104,7 +106,6 @@ export async function scaffold(options: ScaffoldOptions): Promise<void> {
)
fs.writeFileSync(path.join(projectDir, '.gitignore'), gitignoreContent())
fs.writeFileSync(path.join(projectDir, '.dockerignore'), dockerignoreContent())
- fs.writeFileSync(path.join(projectDir, 'AGENTS.md'), agentsMdContent())
s.stop('Project structure created.')
@@ -165,14 +166,10 @@ export async function scaffold(options: ScaffoldOptions): Promise<void> {
),
)
fs.writeFileSync(
- path.join(projectDir, 'CLAUDE.md'),
- rootClaudeMdContent(
- storefrontReady,
- dashboardReady,
- options.packageManager,
- sellerDashboardReady,
- ),
+ path.join(projectDir, 'AGENTS.md'),
+ agentsMdContent(storefrontReady, dashboardReady, options.packageManager, sellerDashboardReady),
)
+ fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), claudeMdContent())
const githubDir = path.join(projectDir, '.github')
fs.mkdirSync(githubDir, { recursive: true })
fs.writeFileSync(
@@ -180,6 +177,23 @@ export async function scaffold(options: ScaffoldOptions): Promise<void> {
dependabotContent(storefrontReady, dashboardReady, sellerDashboardReady),
)
+ // A failed install warns and continues, like the apps: skills are a
+ // convenience, never a reason to stop before Phase 4.
+ let agentSkillsReady = false
+ if (options.agentSkills) {
+ s.start('Installing Spree agent skills...')
+ try {
+ await installAgentSkills(projectDir, options.packageManager)
+ agentSkillsReady = true
+ s.stop('Spree agent skills installed.')
+ } catch (err) {
+ s.stop('Spree agent skills were not installed.')
+ p.log.warn(
+ `Install them later with ${pc.bold(`${dlxCommand(options.packageManager)} skills add ${AGENT_SKILLS_REPO}`)}.\n${errorMessage(err)}`,
+ )
+ }
+ }
+
// Phase 4: Initialize and start services
if (options.start) {
// Sample data is never part of a scaffold: first-run setup configures the
@@ -221,6 +235,7 @@ export async function scaffold(options: ScaffoldOptions): Promise<void> {
storefrontReady,
dashboardReady,
sellerDashboardReady,
+ agentSkillsReady,
options.packageManager,
)
}
@@ -232,6 +247,7 @@ function printSuccessWithoutDocker(
hasStorefront: boolean,
hasDashboard: boolean,
hasSellerDashboard: boolean,
+ hasAgentSkills: boolean,
pm: PackageManager,
): void {
const run = runCommand(pm)
@@ -292,11 +308,19 @@ function printSuccessWithoutDocker(
` ${run} spree eject`,
` ${pc.dim('# Then edit server/ — the Rails API app (Gemfile, app/, config/)')}`,
'',
- `${pc.bold('Agent skills (optional)')}`,
- ` ${dlxCommand(pm)} skills add spree/agent-skills`,
- ` ${pc.dim('# Adds 23 Spree skills to whichever AI agent(s) you use')}`,
- ` ${pc.dim('# (Claude Code, Codex, Cursor, Copilot, Cline, Aider, +60 others)')}`,
- '',
+ )
+
+ if (!hasAgentSkills) {
+ lines.push(
+ `${pc.bold('Agent skills (optional)')}`,
+ ` ${dlxCommand(pm)} skills add ${AGENT_SKILLS_REPO}`,
+ ` ${pc.dim('# Teaches whichever AI agents you use how to work with Spree')}`,
+ ` ${pc.dim('# (Claude Code, Codex, Cursor, Copilot, Cline, Aider, +60 others)')}`,
+ '',
+ )
+ }
+
+ lines.push(
`${pc.bold('Spree docs MCP server (optional)')}`,
` claude mcp add --transport http spree-docs ${DOCS_MCP_URL}`,
` ${pc.dim('# Lets your AI agent search the latest Spree docs. Other agents:')}`,
diff --git a/packages/create-spree-app/src/templates/agents-md.ts b/packages/create-spree-app/src/templates/agents-md.ts
new file mode 100644
index 0000000000..2a1c558cff
--- /dev/null
+++ b/packages/create-spree-app/src/templates/agents-md.ts
@@ -0,0 +1,148 @@
+import type { PackageManager } from '../types.js'
+import { dlxCommand, runCommand } from '../utils.js'
+
+/**
+ * Root CLAUDE.md for a generated project. Claude Code reads CLAUDE.md, not
+ * AGENTS.md, so it imports AGENTS.md — the one file every agent shares.
+ */
+export function claudeMdContent(): string {
+ return '@AGENTS.md\n'
+}
+
+/**
+ * Root AGENTS.md for a generated project. Command examples are rendered for
+ * the scaffold's package manager `pm` (default pnpm, matching detection).
+ */
+export function agentsMdContent(
+ hasStorefront: boolean,
+ hasDashboard = false,
+ pm: PackageManager = 'pnpm',
+ hasSellerDashboard = hasDashboard,
+): string {
+ const spree = `${runCommand(pm)} spree`
+ const lines = [
+ '# Spree Commerce Project',
+ '',
+ 'Instructions for coding agents. `CLAUDE.md` only imports this file — edit this one.',
+ '',
+ '## Project Structure',
+ '',
+ '| Directory | Description | Agent instructions |',
+ '|-----------|-------------|--------------------|',
+ '| `server/` | The Spree API — a Rails application | `server/AGENTS.md` |',
+ ]
+
+ if (hasDashboard) {
+ lines.push('| `apps/dashboard/` | Admin Dashboard — React SPA | `apps/dashboard/AGENTS.md` |')
+ }
+
+ if (hasSellerDashboard) {
+ lines.push(
+ '| `apps/seller-dashboard/` | Seller Panel — marketplace seller SPA | `apps/seller-dashboard/AGENTS.md` |',
+ )
+ }
+
+ if (hasStorefront) {
+ lines.push('| `apps/storefront/` | Next.js storefront | `apps/storefront/CLAUDE.md` |')
+ }
+
+ lines.push(
+ '',
+ 'Read the instructions for the directory you are working in before changing anything there.',
+ '',
+ '## Run everything through the Spree CLI',
+ '',
+ 'The Spree API, its database and its background jobs run in Docker containers managed by',
+ 'the Spree CLI (`@spree/cli`, installed in this directory). The CLI is the only supported',
+ 'way to run commands against the API.',
+ '',
+ `- Run it from this directory as \`${spree} <command>\`.`,
+ '- **Never run `bin/rails`, `bin/rake`, `rake`, `bundle`, `rspec`, `bin/setup`, `bin/dev`, `ruby` or `rails` directly** —',
+ ' not on the host and not through `docker compose exec`. They run against the wrong Ruby, the',
+ ' wrong database, or no database at all.',
+ '- **Never call `docker compose` directly.** The CLI picks the right compose files and environment.',
+ `- **Don't use the \`package.json\` scripts in this directory** (\`${pm} run dev\`, \`${pm} run console\`, …).`,
+ ' They are shortcuts for humans that wrap the CLI — call the CLI command itself.',
+ `- When no dedicated command exists, fall back to \`${spree} rails <args>\`, \`${spree} rake <task>\` or`,
+ ` \`${spree} exec <command>\`, which run inside the container.`,
+ '',
+ 'The apps under `apps/` are ordinary JavaScript projects with their own tooling — inside them,',
+ 'follow their own instructions.',
+ '',
+ '```bash',
+ `${spree} dev --no-open # start the stack in the foreground (the developer usually has it running)`,
+ `${spree} stop # stop it`,
+ `${spree} restart # reload after initializer changes`,
+ `${spree} logs # API logs`,
+ `${spree} console # Rails console`,
+ `${spree} migrate # run pending migrations`,
+ `${spree} generate <generator> # Rails and Spree generators`,
+ `${spree} bundle add <gem> # add a gem`,
+ `${spree} rspec [path] # run tests against the test database`,
+ `${spree} routes # list routes`,
+ `${spree} --help # every command`,
+ '```',
+ '',
+ '`server/AGENTS.md` maps every Rails command to its CLI equivalent.',
+ '',
+ `Never run \`${spree} db:reset\` or \`${spree} eject\` without asking the developer first.`,
+ '',
+ '### Changes to `server/` need an ejected project',
+ '',
+ 'A new project runs the prebuilt Spree Docker image, so edits in `server/` — including files',
+ `written by \`${spree} generate\` and gems added with \`${spree} bundle\` — have no effect until the`,
+ `developer runs \`${spree} eject\`, which builds the API from \`server/\` with live reloading. The`,
+ 'project is ejected when `docker-compose.yml` mounts `./server:/rails`.',
+ '',
+ '## Querying the Admin API',
+ '',
+ 'Project setup mints a read-only secret key into `.spree/credentials.json`',
+ '(gitignored) — and `spree api` mints it on first use if setup was skipped —',
+ 'so the Admin API client works without further configuration. Use it to',
+ 'inspect live data instead of guessing at the schema:',
+ '',
+ '```bash',
+ `${spree} api get products # list products`,
+ `${spree} api get orders -q status_eq=placed # Ransack filters`,
+ `${spree} api endpoints # every endpoint + its required scope`,
+ `${spree} api schema "POST /products" # request/response schema for an operation`,
+ '```',
+ '',
+ 'The default key is read-only. For writes, create a scoped key and pass it via',
+ `\`SPREE_API_KEY\`: \`${spree} api-key create --name "Agent writes" --type secret --scopes write_products\`, then`,
+ `\`SPREE_API_KEY=sk_... ${spree} api post products --data '{"name":"New product","prices":[{"currency":"USD","amount":"29.99"}]}'\`.`,
+ '',
+ '## Spree Documentation',
+ '',
+ 'The full developer documentation is installed locally as Markdown:',
+ '',
+ '```',
+ 'node_modules/@spree/docs/dist/',
+ '├── developer/',
+ '│ ├── core-concepts/ # Products, orders, payments, inventory, etc.',
+ '│ ├── customization/ # Events, workflow hooks, dependencies, extensions',
+ '│ ├── cli/ # Every Spree CLI command',
+ '│ ├── dashboard/ # Admin Dashboard: customization, recipes, plugins',
+ '│ ├── storefront/ # Storefront building guides',
+ '│ ├── sdk/ # TypeScript SDK documentation',
+ '│ └── tutorial/ # Step-by-step tutorials',
+ '├── api-reference/',
+ '│ ├── store-api/ # Store API v3 guides',
+ '│ ├── admin-api/ # Admin API v3 guides',
+ '│ ├── store.yaml # Store API OpenAPI spec (endpoints, params, schemas)',
+ '│ └── admin.yaml # Admin API OpenAPI spec',
+ '└── integrations/ # Stripe, Meilisearch, etc.',
+ '```',
+ '',
+ 'Read these files when you need Spree-specific guidance.',
+ '',
+ '## Spree agent skills',
+ '',
+ 'The official Spree skills cover API conventions, the data model, events, testing,',
+ 'security, deployment, the Admin Dashboard and the storefront. If `.agents/skills/`',
+ `is missing, install them with \`${dlxCommand(pm)} skills add spree/agent-skills\`.`,
+ '',
+ )
+
+ return lines.join('\n')
+}
diff --git a/packages/create-spree-app/src/templates/claude-md.ts b/packages/create-spree-app/src/templates/claude-md.ts
deleted file mode 100644
index 2610f798a9..0000000000
--- a/packages/create-spree-app/src/templates/claude-md.ts
+++ /dev/null
@@ -1,141 +0,0 @@
-import type { PackageManager } from '../types.js'
-import { runCommand } from '../utils.js'
-
-export function agentsMdContent(): string {
- return `# Agent Instructions
-
-See [CLAUDE.md](./CLAUDE.md) for the project layout and where each part is
-documented. Each application carries its own instructions — read the one for
-the directory you are working in before changing anything there.
-
-## Spree-specific agent skills
-
-For deeper Spree-specific guidance (API conventions, the data model, event system,
-testing patterns, security, deployment, the admin dashboard, the Next.js
-storefront, etc.), install the official skill set:
-
-\`\`\`bash
-npx skills add spree/agent-skills
-\`\`\`
-
-Works for Claude Code, Codex, Cursor, GitHub Copilot, Cline, Aider, Zed, Windsurf,
-and 60+ other agentic CLIs. See https://github.com/spree/agent-skills for the
-full skill list.
-`
-}
-
-/**
- * Root CLAUDE.md for a generated project. Command examples are rendered for
- * the scaffold's package manager `pm` (default pnpm, matching detection).
- */
-export function rootClaudeMdContent(
- hasStorefront: boolean,
- hasDashboard = false,
- pm: PackageManager = 'pnpm',
- hasSellerDashboard = hasDashboard,
-): string {
- const run = runCommand(pm)
- const lines = [
- '# Spree Commerce Application',
- '',
- '## Project Structure',
- '',
- '| Directory | Description |',
- '|-----------|-------------|',
- '| `server/` | Rails API application (Spree Commerce) |',
- ]
-
- if (hasStorefront) {
- lines.push('| `apps/storefront/` | Next.js storefront |')
- }
-
- if (hasDashboard) {
- lines.push('| `apps/dashboard/` | Admin Dashboard — React SPA |')
- }
-
- if (hasSellerDashboard) {
- lines.push('| `apps/seller-dashboard/` | Seller Panel — marketplace seller SPA |')
- }
-
- lines.push(
- '',
- '## Agent Instructions',
- '',
- '- **Server work** (Ruby/Rails, Spree models, API, database): See `server/CLAUDE.md`',
- )
-
- if (hasStorefront) {
- lines.push(
- '- **Storefront work** (Next.js, React, TypeScript): See `apps/storefront/CLAUDE.md`',
- )
- }
-
- if (hasDashboard) {
- lines.push(
- '- **Dashboard work** (admin SPA, React, TypeScript): See `apps/dashboard/AGENTS.md`',
- )
- }
-
- if (hasSellerDashboard) {
- lines.push(
- '- **Seller Panel work** (marketplace seller SPA): See `apps/seller-dashboard/AGENTS.md`',
- )
- }
-
- lines.push(
- '',
- '## Spree Documentation',
- '',
- 'Full developer docs are installed locally:',
- '',
- '```',
- 'node_modules/@spree/docs/dist/',
- '├── developer/',
- '│ ├── core-concepts/ # Products, orders, payments, inventory, etc.',
- '│ ├── customization/ # Decorators, extensions, configuration, dependencies',
- '│ ├── dashboard/ # Admin dashboard: customization, recipes, plugins',
- '│ ├── storefront/ # Storefront building guides',
- '│ ├── sdk/ # TypeScript SDK documentation',
- '│ └── tutorial/ # Step-by-step tutorials',
- '├── api-reference/',
- '│ ├── store-api/ # Store API v3 guides',
- '│ ├── admin-api/ # Admin API v3 guides',
- '│ └── store.yaml # OpenAPI 3.0 spec (all endpoints, params, schemas)',
- '└── integrations/ # Stripe, Meilisearch, etc.',
- '```',
- '',
- 'Read these files when you need Spree-specific guidance.',
- '',
- '## Querying the Admin API',
- '',
- 'Project setup mints a read-only secret key into `.spree/credentials.json`',
- '(gitignored) — and `spree api` mints it on first use if setup was skipped —',
- 'so the Admin API client works without further configuration. Use it to',
- 'inspect live data instead of guessing at the schema:',
- '',
- '```bash',
- `${run} spree api get products # list products`,
- `${run} spree api get "orders?q[status_eq]=complete" # Ransack filters`,
- `${run} spree api endpoints # every endpoint + its required scope`,
- `${run} spree api schema "POST /products" # request/response schema for an operation`,
- '```',
- '',
- 'The default key is read-only. For writes, create a scoped key and pass it via',
- `\`SPREE_API_KEY\`: \`${run} spree api-key create --scopes write_products\`, then`,
- `\`SPREE_API_KEY=sk_... ${run} spree api post products --data '{"name":"New product","prices":[{"currency":"USD","amount":"29.99"}]}'\`.`,
- '',
- '## Common Commands',
- '',
- '```bash',
- `${pm} run dev # Start the Spree API (Docker)`,
- `${pm} run stop # Stop services`,
- `${pm} run console # Rails console`,
- `${pm} run logs # Server logs`,
- `${run} spree api get products # Query the Admin API (read-only key preconfigured)`,
- `${run} spree eject # Build the API locally from server/`,
- '```',
- '',
- )
-
- return lines.join('\n')
-}
diff --git a/packages/create-spree-app/src/types.ts b/packages/create-spree-app/src/types.ts
index 581cadd4f6..1adf41dbf1 100644
--- a/packages/create-spree-app/src/types.ts
+++ b/packages/create-spree-app/src/types.ts
@@ -5,6 +5,7 @@ export interface ScaffoldOptions {
storefront: boolean
dashboard: boolean
sellerDashboard: boolean
+ agentSkills: boolean
start: boolean
packageManager: PackageManager
port: number
diff --git a/packages/create-spree-app/tests/prompts.test.ts b/packages/create-spree-app/tests/prompts.test.ts
index 2a92049470..c03e2310d2 100644
--- a/packages/create-spree-app/tests/prompts.test.ts
+++ b/packages/create-spree-app/tests/prompts.test.ts
@@ -14,6 +14,7 @@ const ANSWERED = {
directory: './my-store',
noStorefront: true,
noSellerDashboard: false,
+ noAgentSkills: false,
noStart: true,
packageManager: 'pnpm',
} as const
@@ -43,6 +44,22 @@ describe('runPrompts', () => {
)
})
+ it('asks about the agent skills, defaulting to yes', async () => {
+ const { confirm } = await import('@clack/prompts')
+ vi.mocked(confirm).mockClear()
+ vi.mocked(confirm).mockResolvedValueOnce(true)
+
+ const options = await runPrompts({ ...ANSWERED, noAgentSkills: undefined })
+
+ expect(options.agentSkills).toBe(true)
+ expect(vi.mocked(confirm)).toHaveBeenCalledWith(
+ expect.objectContaining({
+ message: expect.stringContaining('Install Spree agent skills?'),
+ initialValue: true,
+ }),
+ )
+ })
+
// Sample data is loaded on demand with `spree sample-data`, never as part of
// the scaffold: the seed runs before the store is configured through the
// first-run setup UI.
diff --git a/packages/create-spree-app/tests/scaffold.test.ts b/packages/create-spree-app/tests/scaffold.test.ts
index 908f7c5fe3..f20654ee34 100644
--- a/packages/create-spree-app/tests/scaffold.test.ts
+++ b/packages/create-spree-app/tests/scaffold.test.ts
@@ -350,6 +350,69 @@ describe('scaffold (no-start)', () => {
)
})
+ it('writes AGENTS.md with CLAUDE.md importing it', async () => {
+ const projectDir = getTempProjectDir()
+
+ await scaffold({
+ directory: projectDir,
+ storefront: false,
+ dashboard: false,
+ start: false,
+ packageManager: 'npm',
+ port: 3000,
+ })
+
+ expect(fs.readFileSync(path.join(projectDir, 'AGENTS.md'), 'utf-8')).toContain(
+ 'Run everything through the Spree CLI',
+ )
+ expect(fs.readFileSync(path.join(projectDir, 'CLAUDE.md'), 'utf-8')).toBe('@AGENTS.md\n')
+ })
+
+ it('installs the agent skills when chosen', async () => {
+ const { execa } = await import('execa')
+ vi.mocked(execa).mockClear()
+ const projectDir = getTempProjectDir()
+
+ await scaffold({
+ directory: projectDir,
+ storefront: false,
+ dashboard: false,
+ agentSkills: true,
+ start: false,
+ packageManager: 'npm',
+ port: 3000,
+ })
+
+ expect(vi.mocked(execa)).toHaveBeenCalledWith(
+ 'npx',
+ ['--yes', 'skills', 'add', 'spree/agent-skills', '--skill', '*', '--yes'],
+ expect.objectContaining({ cwd: path.resolve(projectDir) }),
+ )
+ })
+
+ // Skills are a convenience: a failed install must not stop first-run setup.
+ it('continues to first-run setup when the agent skills fail to install', async () => {
+ const { execa } = await import('execa')
+ vi.mocked(execa).mockClear()
+ vi.mocked(execa).mockImplementation((async (_command: string, args: string[]) => {
+ if (args.includes('skills')) throw new Error('network down')
+ }) as never)
+
+ await scaffold({
+ directory: getTempProjectDir(),
+ storefront: false,
+ dashboard: false,
+ agentSkills: true,
+ start: true,
+ packageManager: 'pnpm',
+ port: 3000,
+ })
+
+ const init = vi.mocked(execa).mock.calls.find(([, args]) => (args as string[])?.[1] === 'init')
+ expect(init).toBeDefined()
+ vi.mocked(execa).mockReset()
+ })
+
it('rejects non-empty directory', async () => {
const projectDir = getTempProjectDir()
fs.mkdirSync(projectDir, { recursive: true })
diff --git a/packages/create-spree-app/tests/templates.test.ts b/packages/create-spree-app/tests/templates.test.ts
index da5b6f288a..8448900028 100644
--- a/packages/create-spree-app/tests/templates.test.ts
+++ b/packages/create-spree-app/tests/templates.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, it } from 'vitest'
-import { rootClaudeMdContent } from '../src/templates/claude-md'
+import { agentsMdContent, claudeMdContent } from '../src/templates/agents-md'
import { dependabotContent } from '../src/templates/dependabot'
import { envContent, storefrontEnvContent } from '../src/templates/env'
import { gitignoreContent } from '../src/templates/gitignore'
@@ -218,33 +218,48 @@ describe('readmeContent', () => {
})
})
-describe('rootClaudeMdContent', () => {
+describe('agentsMdContent', () => {
it('lists apps/dashboard when the dashboard is included', () => {
- const content = rootClaudeMdContent(true, true)
+ const content = agentsMdContent(true, true)
expect(content).toContain('`apps/dashboard/`')
// Each app carries its own instructions; the root file points at them.
+ expect(content).toContain('server/AGENTS.md')
expect(content).toContain('apps/dashboard/AGENTS.md')
expect(content).toContain('apps/seller-dashboard/AGENTS.md')
})
- it('renders commands for the chosen package manager', () => {
- const content = rootClaudeMdContent(true, true, 'pnpm')
- expect(content).toContain('pnpm run dev')
+ it('renders CLI commands for the chosen package manager', () => {
+ const content = agentsMdContent(true, true, 'pnpm')
+ expect(content).toContain('pnpm spree dev')
expect(content).toContain('pnpm spree api get products')
expect(content).not.toContain('npx spree')
})
+ // Agents must drive the stack through the CLI, never through Rails
+ // binaries or the root package.json shortcuts.
+ it('forbids running Rails commands directly', () => {
+ const content = agentsMdContent(false)
+ expect(content).toContain('Never run `bin/rails`')
+ expect(content).toContain("Don't use the `package.json` scripts")
+ })
+
it('omits apps/dashboard by default', () => {
- expect(rootClaudeMdContent(true)).not.toContain('apps/dashboard')
+ expect(agentsMdContent(true)).not.toContain('apps/dashboard')
})
it('omits the seller panel when it was not installed', () => {
- const content = rootClaudeMdContent(true, true, 'pnpm', false)
+ const content = agentsMdContent(true, true, 'pnpm', false)
expect(content).toContain('apps/dashboard/AGENTS.md')
expect(content).not.toContain('apps/seller-dashboard')
})
})
+describe('claudeMdContent', () => {
+ it('imports AGENTS.md', () => {
+ expect(claudeMdContent()).toBe('@AGENTS.md\n')
+ })
+})
+
describe('gitignoreContent', () => {
const content = gitignoreContent()
diff --git a/packages/dashboard-starter/AGENTS.md b/packages/dashboard-starter/AGENTS.md
index 03493b3e10..0c7f4a37f0 100644
--- a/packages/dashboard-starter/AGENTS.md
+++ b/packages/dashboard-starter/AGENTS.md
@@ -1,11 +1,20 @@
# Agent Instructions
+`CLAUDE.md` only imports this file — edit this one.
+
This is the Spree admin dashboard for this project — a Vite + React app. The
shell (routes, chrome, resource pages) ships in `@spree/dashboard`; this
project holds your customizations.
Full docs: https://spreecommerce.org/docs/developer/dashboard/overview
+## Running it
+
+`spree dev`, run from the project root (`../..`), starts this app's dev server
+together with the Spree API — don't start a second copy with `pnpm dev`. The
+Spree API itself is only ever run through the Spree CLI; see the project
+root's `AGENTS.md`.
+
## Imports
Import from `@spree/dashboard` — it re-exports the framework and the design
@@ -44,8 +53,10 @@ of what exists, not an implementation.
- **Wrap API calls in a hook.** Components never call `adminClient` directly.
- **Query keys are store-scoped.** Build them with `useResourceKey`; a bare
`['brands']` key leaks one store's data into another after a store switch.
-- **Writes go through `useResourceMutation`**, which maps 422 responses onto
- form fields instead of firing a toast.
+- **Writes go through `useResourceMutation`.** It shows a toast for network
+ and server failures but not for 422 validation errors — catch those in the
+ form's submit handler with `mapSpreeErrorsToForm`, which puts each message on
+ its field.
- **Every visible string goes through i18next** — page titles, column labels,
buttons, empty states, toasts. Never hardcode English in JSX or in a table
definition. Add each new key to every locale file the project ships.
@@ -55,12 +66,15 @@ of what exists, not an implementation.
walks every nested key and the SDK's object graph overflows the TypeScript
compiler.
- **A sortable or filterable column must be allowlisted for Ransack** on the
- model, or the request fails at runtime.
+ model, or the request fails at runtime. That change belongs to the Spree API
+ in `../../server/` — follow `../../server/AGENTS.md`.
- **Destructive actions that fire straight from a click need a confirm** —
`useConfirm()` with `variant: 'destructive'`.
## Checks
+Run these with the project's package manager (`pnpm`, `npm run` or `yarn`):
+
```bash
pnpm typecheck
pnpm lint
diff --git a/packages/dashboard-starter/CLAUDE.md b/packages/dashboard-starter/CLAUDE.md
new file mode 100644
index 0000000000..43c994c2d3
--- /dev/null
+++ b/packages/dashboard-starter/CLAUDE.md
@@ -0,0 +1 @@
diff --git a/packages/seller-dashboard-starter/AGENTS.md b/packages/seller-dashboard-starter/AGENTS.md
index 8dce2416d9..abdc1556bf 100644
--- a/packages/seller-dashboard-starter/AGENTS.md
+++ b/packages/seller-dashboard-starter/AGENTS.md
@@ -1,13 +1,19 @@
# Agent Instructions
+`CLAUDE.md` only imports this file — edit this one.
+
This is the Spree seller panel for this marketplace — a Vite + React app. The
shell ships in `@spree/seller-dashboard`; this project holds your
customizations. Sellers manage their own catalog and orders here.
Full docs: https://spreecommerce.org/docs/developer/dashboard/overview
-The admin dashboard is the reference implementation: when a component is
-useful to both, extract it rather than copying it.
+## Running it
+
+Start the Spree API with `spree dev` from the project root (`../..`) — it is
+only ever run through the Spree CLI; see the project root's `AGENTS.md`. Then
+run this app's own dev server here with `pnpm dev` (or `npm run dev`); the
+Spree CLI does not start the seller panel for you.
## Imports
@@ -15,7 +21,7 @@ Import from `@spree/seller-dashboard` — it re-exports the framework and the de
system, so there is no need to work out which package an export lives in.
```ts
-import { defineDashboardPlugin, useStore, Button, ResourceTable } from '@spree/seller-dashboard'
+import { defineDashboardPlugin, sellerClient, Button, ResourceTable } from '@spree/seller-dashboard'
```
`@spree/dashboard-core` and `@spree/dashboard-ui` stay importable for the few
@@ -30,26 +36,35 @@ uses internally.
| Directory | Holds | Naming |
|---|---|---|
| `src/plugins.ts` | Registrations only: nav, slots, tables | one file |
-| `src/pages/` | One screen each | `brands.tsx` |
-| `src/hooks/` | Admin API wrappers | `use-brands.ts` |
+| `src/pages/` | Larger components rendered inside slots | `payout-summary.tsx` |
+| `src/hooks/` | Seller API wrappers | `use-payouts.ts` |
| `src/tables/` | `defineTable` calls | `brands.tsx` |
| `src/schemas/` | Zod schema + `FormValues` | `brand.ts` |
| `src/slots/` | Widgets injected into built-in pages | `seller-payout-card.tsx` |
| `src/locales/` | Your `admin.*` translation keys | `en.json` |
-Adding a resource touches one file in each directory. Keep `plugins.ts` a map
-of what exists, not an implementation.
+Keep `plugins.ts` a map of what exists, not an implementation.
+
+The seller panel does not support adding new pages yet: plugins can remove
+built-in navigation entries, add widgets to the slots built-in screens expose,
+and add table columns. A navigation entry pointing at a path the panel does
+not have leads to a "not found" screen.
## Rules
-- **The Admin API is the only data source.** Never reach into the Rails app or
+- **The Seller API is the only data source.** Never reach into the Rails app or
import server-rendered HTML. Seller endpoints are scoped to the signed-in
seller by the server, never by the client. A missing endpoint is added to the API first.
-- **Wrap API calls in a hook.** Components never call `adminClient` directly.
-- **Query keys are store-scoped.** Build them with `useResourceKey`; a bare
- `['brands']` key leaks one store's data into another after a store switch.
-- **Writes go through `useResourceMutation`**, which maps 422 responses onto
- form fields instead of firing a toast.
+- **Use the Seller API, through a hook.** Hooks call `sellerClient()`;
+ components never call it directly. Never use `adminClient` here — it targets
+ the Admin API, which sellers cannot sign in to.
+- **There is no store context.** The panel's tenant is the signed-in seller, so
+ `useStore()` throws here. Build query keys with `useResourceKey`, which scopes
+ them to the seller.
+- **Writes go through `useResourceMutation`.** It shows a toast for network
+ and server failures but not for 422 validation errors — catch those in the
+ form's submit handler with `mapSpreeErrorsToForm`, which puts each message on
+ its field.
- **Every visible string goes through i18next** — page titles, column labels,
buttons, empty states, toasts. Never hardcode English in JSX or in a table
definition. Add each new key to every locale file the project ships.
@@ -59,12 +74,15 @@ of what exists, not an implementation.
walks every nested key and the SDK's object graph overflows the TypeScript
compiler.
- **A sortable or filterable column must be allowlisted for Ransack** on the
- model, or the request fails at runtime.
+ model, or the request fails at runtime. That change belongs to the Spree API
+ in `../../server/` — follow `../../server/AGENTS.md`.
- **Destructive actions that fire straight from a click need a confirm** —
`useConfirm()` with `variant: 'destructive'`.
## Checks
+Run these with the project's package manager (`pnpm`, `npm run` or `yarn`):
+
```bash
pnpm typecheck
pnpm lint
diff --git a/packages/seller-dashboard-starter/CLAUDE.md b/packages/seller-dashboard-starter/CLAUDE.md
new file mode 100644
index 0000000000..43c994c2d3
--- /dev/null
+++ b/packages/seller-dashboard-starter/CLAUDE.md
@@ -0,0 +1 @@
diff --git a/packages/seller-dashboard-starter/src/plugins.ts b/packages/seller-dashboard-starter/src/plugins.ts
index aff8ed4254..b643033dcb 100644
--- a/packages/seller-dashboard-starter/src/plugins.ts
+++ b/packages/seller-dashboard-starter/src/plugins.ts
@@ -7,26 +7,27 @@
// before the panel renders.
//
// Keep this file a map of what you added: the registrations live here, the
-// implementations live in pages/, hooks/, tables/ and schemas/ — one file per
+// implementations live in slots/, pages/, hooks/, tables/ and schemas/ — one file per
// resource, the same layout the seller panel uses internally. Translations go
// in locales/ and merge in with `i18n.addResourceBundle`.
//
-// Example — add a payouts page and drop the built-in team screen:
+// Example — add a card to the team screen and drop the built-in team entry
+// from the navigation (the seller panel does not support new pages yet):
//
// import { defineDashboardPlugin } from '@spree/seller-dashboard'
-// import { PayoutsPage } from './pages/payouts'
+// import { TeamAuditCard } from './slots/team-audit-card'
//
// defineDashboardPlugin({
-// nav: {
-// add: [{ key: 'payouts', label: 'Payouts', path: '/payouts', position: 300 }],
-// remove: ['team'],
-// },
+// nav: { remove: ['team'] },
// slots: {
// 'seller.team.after': [{ id: 'audit', component: TeamAuditCard }],
// },
// })
//
-// Slots the built-in screens expose: `seller.team.actions`, `seller.team.after`.
+// Slots the built-in screens expose: `seller.team.actions`, `seller.team.after`,
+// `seller.product.form_sidebar`, `seller.order.form_sidebar`,
+// `seller.payout.form_sidebar`, `seller.profile.form_main`,
+// `seller.profile.form_sidebar`.
//
// `@spree/dashboard-core` and `@spree/dashboard-ui` are already installed —
// import hooks, providers and UI primitives straight from them.
diff --git a/packages/seller-dashboard/src/index.ts b/packages/seller-dashboard/src/index.ts
index 552242644a..22260fc834 100644
--- a/packages/seller-dashboard/src/index.ts
+++ b/packages/seller-dashboard/src/index.ts
@@ -34,6 +34,7 @@ export {
createSellerApiClient,
rememberedSeller,
rememberSeller,
+ sellerClient,
setActiveSeller,
} from './api-client'
export { CenteredMessage } from './components/centered-message'