@spree/docs 0.1.92 → 0.1.94

package/dist/developer/agentic/overview.md

@@ -19,7 +19,7 @@ Spree ships first-class tooling for AI-assisted development. Whether you use Cla
   - [Agent Skills](agent-skills.md) — 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.
   - [Docs MCP Server](mcp.md) — Connect your agent to the Spree documentation MCP server to search and read the latest docs while building.
   - [LLM-Ready Docs](llm-docs.md) — llms.txt, per-page Markdown, and the `@spree/docs` npm package for fast local reads.
-  - [Spree CLI](../cli/quickstart.md) — A predictable command surface (`spree dev`, `spree generate`, `spree migrate`, `spree upgrade`) that agents can drive end-to-end.
+  - [Spree CLI](../cli/quickstart.md) — A predictable command surface (`spree dev`, `spree generate`, `spree migrate`) plus `spree api` — call the Admin API directly to inspect and drive the store, with zero-config credentials in local dev. Agents debug and act end-to-end.
 
 
 ## A typical agentic workflow

package/dist/developer/cli/admin-api.md

@@ -0,0 +1,146 @@
+---
+title: "Call the Admin API from the CLI"
+sidebarTitle: "Admin API"
+description: "Use spree api to call the Spree Admin API with generic get/post/patch/delete commands, schema introspection, and zero-config credentials — built for scripts and AI agents."
+---
+
+The `spree api` command group turns the CLI into a first-class Admin API client: generic HTTP verbs against any endpoint, schema introspection without leaving the terminal, and credentials that resolve automatically — from a local dev project to a production store profile. It works against any Spree 5.5+ instance and is designed to be driven by both humans and AI coding agents.
+
+```bash
+spree api get /products -q status_eq=active --sort -created_at --limit 10
+spree api get /orders/ord_x8k2J9aQ --expand items,payments
+spree api post /products -d '{"name":"Classic Tee"}'
+spree api patch /orders/ord_x8k2J9aQ/cancel
+spree api endpoints --resource orders
+spree api schema "POST /orders/{id}/refunds"
+spree api status
+```
+
+## Credentials
+
+Credentials resolve through four layers — first match wins:
+
+| Layer | How |
+|---|---|
+| Flags | `--base-url` / `--api-key` (and `--profile`, which selects a saved profile explicitly) |
+| Environment | `SPREE_API_KEY` (+ `SPREE_BASE_URL`) — the path for CI and agents. `SPREE_BASE_URL` is optional: a bare key defaults to `http://localhost:3000`, so local dev needs only the key. Set it for a remote store. |
+| Project | Inside a Spree project with the dev stack running, the CLI mints a **read-only** key on first use and stores it in `.spree/credentials.json` (gitignored) |
+| Profile | `~/.config/spree/config.json`, written by `spree auth login` |
+
+Host and key resolve **together** per source — a saved or minted key is never silently re-pointed at a host from a different layer. Only `--base-url` (or `SPREE_BASE_URL` paired with `SPREE_API_KEY`) re-points a key deliberately. So against local dev:
+
+```bash
+SPREE_API_KEY=sk_xxx spree api get /products    # → http://localhost:3000
+```
+
+Zero configuration is needed for local development — the first `spree api get` inside your project just works:
+
+```bash
+cd my-store
+spree api get /products
+# No credentials found — minting a read-only API key via the dev stack...
+# Saved to .spree/credentials.json (scopes: read_all)
+```
+
+Auto-minted keys carry `read_all` only. Writes always require an explicitly created key:
+
+```bash
+spree api-key create --type secret --scopes read_orders,write_products
+```
+
+For remote stores, create a secret key in the admin under **Settings → API Keys** and save it as a profile — the key is read from a prompt, never from a flag:
+
+```bash
+spree auth login --profile prod --base-url https://store.example.com
+spree api get /orders --profile prod -q "status_eq=complete"
+spree auth status
+spree auth logout --profile prod
+```
+
+## Reading data
+
+`-q` takes [Ransack](../../api-reference/admin-api/querying.md) predicates as repeatable `key=value` pairs; sorting, pagination, and shaping flags pass through under the Admin API conventions:
+
+```bash
+spree api get /products -q name_cont=shirt -q status_eq=active
+spree api get /orders --sort -created_at --page 2 --limit 50
+spree api get /products/prod_86Rf07xd --expand variants,variants.prices
+spree api get /customers --fields id,email --format table
+```
+
+`--fields` trims the response to the attributes you name (comma-separated). The resource `id` is **always returned** even if you don't list it, so you only need to name the extra fields. `--expand` is the companion axis — `--fields` selects top-level attributes, `--expand` pulls in related resources:
+
+```bash
+spree api get /products --fields name,price          # → id + name + price
+spree api get /products --fields name --expand variants
+```
+
+### Output format
+
+Output is JSON on stdout, and it adapts to where it goes:
+
+- **In a terminal** — indented and syntax-colored, for reading.
+- **Piped or redirected** — compact, single-line, uncolored, so it stays fast and feeds cleanly into `jq` (color codes would corrupt it).
+
+```bash
+spree api get /products --limit 5 | jq '.data[].name'
+```
+
+`--format table` renders collections as a table for humans (nested objects collapse to `{…}`, arrays to `[N]`).
+
+## Writing data
+
+Request bodies are flat JSON (no root wrapping), inline, from a file, or from stdin:
+
+```bash
+spree api post /products -d '{"name":"Classic Tee","price":29.99}'
+spree api post /orders/ord_x8k2J9aQ/refunds -d @refund.json
+cat prices.json | spree api post /prices/bulk_upsert -d -
+spree api delete /products/prod_86Rf07xd
+```
+
+Mutations automatically carry an `Idempotency-Key`, so retries are safe.
+
+## Discovering endpoints and schemas
+
+The CLI bundles a snapshot of the Admin API OpenAPI spec, so discovery works offline:
+
+```bash
+spree api endpoints --resource orders          # methods, paths, required scopes
+spree api endpoints --search "gift card"
+spree api schema "POST /orders"                # parameters + request/response schema
+spree api status                               # resolved credentials + server reachability
+```
+
+`spree api endpoints` shows the `read_*` / `write_*` scope each endpoint requires (see [Authentication](../../api-reference/admin-api/authentication.md)) — useful for deciding what to grant a new key.
+
+### Shell completion
+
+Tab-completion suggests resource paths, Ransack predicate stems (`name_cont=`, `status_eq=`, …), and scope names — all offline from the bundled spec. Add the generated script to your shell:
+
+```bash
+# zsh — add to ~/.zshrc
+eval "$(spree completion zsh)"
+# bash — add to ~/.bashrc
+eval "$(spree completion bash)"
+# fish — add to ~/.config/fish/config.fish
+spree completion fish | source
+```
+
+Then `spree api get /pro⇥` completes to `/products`, and `spree api get /products -q name_⇥` offers the Ransack predicates.
+
+## Errors and exit codes
+
+API errors print the error envelope to stderr and exit `1`; usage and configuration problems exit `2`. A scope denial includes the exact remediation:
+
+```text
+access_denied: API key lacks scope: write_products
+{
+  "details": { "required_scope": "write_products" }
+}
+Hint: mint a key carrying this scope — spree api-key create --type secret --scopes write_products
+```
+
+## Using it with AI agents
+
+Agents with shell access (Claude Code, Cursor, and similar) can drive a Spree back office through `spree api` with no extra configuration: inside a project the credentials self-provision read-only, and for remote stores two environment variables (`SPREE_BASE_URL`, `SPREE_API_KEY`) are the whole contract. The `endpoints`/`schema` commands give agents request shapes on demand instead of loading the entire API surface up front, and error messages name the missing scope so agents can self-correct.

package/dist/developer/cli/quickstart.md

@@ -1,10 +1,22 @@
 ---
 title: Spree CLI
 sidebarTitle: Overview
-description: Install and use the @spree/cli to scaffold, run, build, migrate, and upgrade Docker-based Spree Commerce projects from the command line.
+description: Install and use the @spree/cli to scaffold, run, build, and migrate Spree projects — and call the Admin API directly from the command line.
 ---
 
-The Spree CLI (`@spree/cli`) manages Docker-based Spree projects created with [create-spree-app](../create-spree-app/quickstart.md).
+The Spree CLI (`@spree/cli`) does two things from your terminal:
+
+1. **Manages your Spree project** — boot the Docker stack, run generators and migrations, tail logs, open a console, upgrade versions.
+2. **Calls the Admin API** — generic `get`/`post`/`patch`/`delete` commands to read, write, and explore your store's data, with zero-config credentials in local dev. See [Admin API from the CLI](admin-api.md).
+
+```bash
+spree dev                                                  # boot the project
+spree api get /orders -q status_eq=complete --limit 10     # query the Admin API
+spree api post /products -d '{"name":"Classic Tee"}'       # create a resource
+spree api endpoints --search refund                        # discover endpoints, offline
+```
+
+The `spree api` commands work against any Spree 5.5+ instance and are built for both humans and AI agents — see the dedicated [Admin API from the CLI](admin-api.md) guide. The rest of this page covers project management.
 
 ## Installation
 
@@ -164,16 +176,39 @@ spree user create --email admin@example.com --password secret123
 
 ### `spree api-key`
 
-Manage Store and Admin API keys.
+Manage Store and Admin API keys. Secret keys carry [scopes](../../api-reference/admin-api/authentication.md) and require at least one.
 
 ```bash
 spree api-key list                                     # List all keys
 spree api-key create                                   # Interactive
-spree api-key create --name "Storefront" --type publishable  # Store API key
-spree api-key create --name "Admin" --type secret            # Admin API key
+spree api-key create --name "Storefront" --type publishable             # Store API key
+spree api-key create --name "Admin" --type secret --scopes read_all     # Admin API key
 spree api-key revoke <id>                              # Revoke a key
 ```
 
+### `spree api`
+
+Call the Admin API with generic `get`/`post`/`patch`/`delete` commands — zero-config inside a project (a read-only key is minted on first use), env vars or profiles for remote stores. See [Admin API from the CLI](admin-api.md) for the full guide.
+
+```bash
+spree api get /products -q status_eq=active --limit 10
+spree api post /products -d '{"name":"Classic Tee"}'
+spree api endpoints --resource orders    # endpoints + required scopes, offline
+spree api schema "POST /orders"          # request/response schema, offline
+spree api status
+```
+
+### `spree auth`
+
+Save Admin API credentials for remote stores as named profiles.
+
+```bash
+spree auth login --profile prod --base-url https://store.example.com
+spree api get /orders --profile prod
+spree auth status
+spree auth logout --profile prod
+```
+
 ## Dev workflow commands
 
 These mirror the Rails commands you'd run if you were running the app directly on your host — but each is routed through `docker compose exec` against the running stack.

package/dist/developer/core-concepts/addresses.md

@@ -30,7 +30,6 @@ An address represents a shipping or billing location. Every order has a shipping
 | `postal_code` | Postal code (not required for all countries) |
 | `phone` | Phone number |
 | `company` | Company name (optional) |
-| `label` | User-facing label like "Home" or "Office" (optional, unique per customer) |
 | `country_iso` | Country (ISO alpha-2 code, e.g., `US`) |
 | `state_abbr` | State/province abbreviation (required for some countries, e.g., `CA`) |
 
@@ -41,7 +40,7 @@ Whether a state or zipcode is required depends on the country. For example, the
 Customers can save multiple addresses and set a default for shipping and billing. When a customer completes checkout, the selected addresses are cloned onto the order — so editing an address later doesn't change past orders.
 
 
-```typescript SDK
+```typescript Store SDK
 // List addresses
 const { data: addresses } = await client.customer.addresses.list()
 
@@ -63,17 +62,20 @@ await client.customer.addresses.update('addr_xxx', { city: 'Brooklyn' })
 // Delete an address
 await client.customer.addresses.delete('addr_xxx')
 
-// Set as default shipping or billing address
-await client.customer.addresses.markAsDefault('addr_xxx', 'shipping')
+// Set as default shipping or billing address — pass the boolean flags to create or update
+await client.customer.addresses.update('addr_xxx', { is_default_shipping: true })
+await client.customer.addresses.update('addr_xxx', { is_default_billing: true })
 ```
 
 ```bash cURL
 # List addresses
-curl 'https://api.mystore.com/api/v3/store/customer/addresses' \
+curl 'https://api.mystore.com/api/v3/store/customers/me/addresses' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'Authorization: Bearer <jwt_token>'
 
 # Create an address
-curl -X POST 'https://api.mystore.com/api/v3/store/customer/addresses' \
+curl -X POST 'https://api.mystore.com/api/v3/store/customers/me/addresses' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'Authorization: Bearer <jwt_token>' \
   -H 'Content-Type: application/json' \
   -d '{
@@ -88,23 +90,25 @@ curl -X POST 'https://api.mystore.com/api/v3/store/customer/addresses' \
   }'
 
 # Update an address
-curl -X PATCH 'https://api.mystore.com/api/v3/store/customer/addresses/addr_xxx' \
+curl -X PATCH 'https://api.mystore.com/api/v3/store/customers/me/addresses/addr_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'Authorization: Bearer <jwt_token>' \
   -H 'Content-Type: application/json' \
   -d '{ "city": "Brooklyn" }'
 
 # Delete an address
-curl -X DELETE 'https://api.mystore.com/api/v3/store/customer/addresses/addr_xxx' \
+curl -X DELETE 'https://api.mystore.com/api/v3/store/customers/me/addresses/addr_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'Authorization: Bearer <jwt_token>'
 ```
 
 
 ### Checkout Addresses
 
-During checkout, you can either reference a saved address by ID or pass a new address inline:
+During checkout, you can either reference a saved address by ID or pass a new address inline. See the [cart and checkout SDK guide](../sdk/store/cart-checkout.md) for the full flow of passing addresses during checkout:
 
 
-```typescript SDK
+```typescript Store SDK
 // Use saved addresses
 await client.carts.update(cartId, {
   shipping_address_id: 'addr_xxx',
@@ -173,19 +177,25 @@ Each country includes metadata that drives address form behavior:
 Only countries assigned to a [Market](markets.md) are available during checkout. This lets you control exactly where you sell.
 
 
-```typescript SDK
+```typescript Store SDK
 // List all countries available in this store
 const { data: countries } = await client.countries.list()
 
 // Get a country with its states (for address form dropdowns)
-const usa = await client.countries.get('US', { include: 'states' })
+const usa = await client.countries.get('US', { expand: ['states'] })
 // usa.states => [{ name: "Alabama", abbr: "AL" }, { name: "Alaska", abbr: "AK" }, ...]
 
 // Get a country with its market (for currency/locale resolution)
-const germany = await client.countries.get('DE', { include: 'market' })
+const germany = await client.countries.get('DE', { expand: ['market'] })
 // germany.market => { currency: "EUR", default_locale: "de", tax_inclusive: true }
 ```
 
+```typescript Admin SDK
+const { data: countries } = await adminClient.countries.list()
+
+const usa = await adminClient.countries.get('US')
+```
+
 ```bash cURL
 # List all countries
 curl 'https://api.mystore.com/api/v3/store/countries' \
@@ -207,11 +217,11 @@ Use the `states_required` and `zipcode_required` fields to build adaptive addres
 
 States (provinces, regions) belong to a country and are used for address validation and zone matching. Countries like the US, Canada, Australia, and India have predefined states — for these countries, customers must select a state from the list rather than typing a name.
 
-States are fetched via the country endpoint using `?expand=states`:
+States are fetched via the country endpoint using [`?expand=states`](../../api-reference/store-api/relations.md):
 
 
-```typescript SDK
-const usa = await client.countries.get('US', { include: 'states' })
+```typescript Store SDK
+const usa = await client.countries.get('US', { expand: ['states'] })
 
 // Build a state picker from the response
 usa.states.forEach(state => {
@@ -219,6 +229,10 @@ usa.states.forEach(state => {
 })
 ```
 
+```typescript Admin SDK
+const usa = await adminClient.countries.get('US', { expand: ['states'] })
+```
+
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/countries/US?expand=states' \
   -H 'X-Spree-API-Key: pk_xxx'
@@ -263,3 +277,5 @@ Here's how geography flows through a typical checkout:
 - [Taxes](taxes.md) — How zones and addresses affect taxation
 - [Shipments](shipments.md) — How zones and addresses affect shipping availability
 - [Orders](orders.md) — Order billing and shipping addresses
+- [Account SDK guide](../sdk/store/account.md) — Managing the logged-in customer's address book with `client.customer.addresses`
+- [Store API authentication](../../api-reference/store-api/authentication.md) — How to obtain and send the customer JWT (`Authorization: Bearer` header)

package/dist/developer/core-concepts/adjustments.md

@@ -70,11 +70,11 @@ Adjustments are created by two sources:
 
 ## Store API
 
-Adjustments appear in order responses when you expand line items or fulfillments:
+Adjustments appear in order responses when you [`?expand=items,fulfillments`](../../api-reference/store-api/relations.md) on the order. The response exposes the [`amount`, `adjustment_total`, and the tax totals](../../api-reference/store-api/monetary-amounts.md) as money fields:
 
 
-```typescript SDK
-const order = await client.orders.get('or_abc123', {
+```typescript Store SDK
+const order = await client.orders.get('or_abc123', { expand: ['items', 'fulfillments'] }, {
   spreeToken: '<token>',
 })
 
@@ -86,12 +86,17 @@ order.items?.forEach(item => {
 })
 
 // Order-level totals
-order.adjustment_total    // total of all adjustments
-order.promo_total         // total promotional discounts
+order.adjustment_total       // total of all adjustments
+order.discount_total         // total promotional discounts
+order.display_discount_total // formatted promotional discounts
 order.additional_tax_total
 order.included_tax_total
 ```
 
+```typescript Admin SDK
+const order = await adminClient.orders.get('or_abc123')
+```
+
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/orders/or_abc123?expand=items,fulfillments' \
   -H 'X-Spree-API-Key: pk_xxx' \
@@ -105,3 +110,4 @@ curl 'https://api.mystore.com/api/v3/store/orders/or_abc123?expand=items,fulfill
 - [Taxes](taxes.md) — Tax adjustments
 - [Shipments](shipments.md) — Shipping adjustments
 - [Orders](orders.md) — How adjustments affect order totals
+- [Calculators](calculators.md) — How tax rate and promotion action amounts are computed

package/dist/developer/core-concepts/architecture.md

@@ -106,14 +106,14 @@ erDiagram
 
 ## APIs
 
-Spree exposes two REST APIs, both under API v3:
+Spree exposes two REST APIs:
 
 | API | Purpose | Authentication |
 |-----|---------|----------------|
-| [**Store API**](../../api-reference/introduction.md) | Customer-facing — cart, checkout, products, account | Publishable API key + JWT |
-| **Admin API** | Operational — manage products, orders, customers, settings | Secret API key |
+| [**Store API**](../../api-reference/store-api/introduction.md) | Customer-facing — cart, checkout, products, account | [Publishable API key + JWT](../../api-reference/store-api/authentication.md) |
+| [**Admin API**](../../api-reference/admin-api/introduction.md) | Operational — manage products, orders, customers, settings | [Secret API key](../../api-reference/admin-api/authentication.md) + JWT |
 
-Both APIs use [prefixed IDs](../../api-reference/introduction.md) (e.g., `prod_86Rf07xd4z`, `or_m3Rp9wXz`), flat JSON request/response structures, and full TypeScript types via the [@spree/sdk](../sdk/quickstart.md).
+Both APIs share the same list shapes, filtering, querying, and pagination, and offer fully typed TypeScript clients — [@spree/sdk](../sdk/quickstart.md) for the Store API and [@spree/admin-sdk](../sdk/admin/quickstart.md) for the Admin API.
 
 Events from both APIs can trigger [Webhooks](webhooks.md) to notify external systems in real time.
 
@@ -138,7 +138,7 @@ Spree is designed to be customized without modifying core code. The main extensi
 | **Events & Subscribers** | React to order completion, payment, shipment events | [Events Guide](events.md) |
 | **Webhooks** | Notify external systems of changes | [Webhooks Guide](webhooks.md) |
 | **Dependencies** | Swap out services (tax calculation, shipping estimation) | [Dependencies Guide](../customization/dependencies.md) |
-| **Decorators** | Modify existing model/controller behavior (use sparingly) | [Decorators Guide](../customization/decorators.md) |
+| **Decorators** | Modify existing core models & classes behavior (use sparingly) | [Decorators Guide](../customization/decorators.md) |
 
 > **INFO:** For most customizations, prefer **Events** and **Dependencies** over Decorators. They're easier to maintain and won't break during upgrades.
 
@@ -163,9 +163,9 @@ Spree is distributed as a set of packages:
 
 | Package | Purpose |
 |---------|---------|
-| [`@spree/sdk`](../sdk/quickstart.md) | TypeScript SDK for Store API and Admin API |
-
-> **INFO:** For headless commerce, you only need the `spree` package. Build your customer-facing frontend with any technology (Next.js, Nuxt, mobile apps) using the Store API and SDK.
+| [`@spree/sdk`](../sdk/quickstart.md) | TypeScript SDK for the Store API |
+| [`@spree/admin-sdk`](../sdk/admin/quickstart.md) | TypeScript SDK for the Admin API |
+| [`@spree/cli`](../cli/quickstart.md) | Command line interface for managing local environment and using the Admin API from the terminal |
 
 ## Related Documentation
 

package/dist/developer/core-concepts/calculators.md

@@ -47,7 +47,7 @@ erDiagram
 - Used by **[Tax Rates](taxes.md)** to calculate tax amounts
 - Used by **[Shipping Methods](shipments.md)** to calculate shipping costs
 - Used by **[Promotion Actions](promotions.md)** to calculate discounts
-- Calculators store preferences (rates, percentages, etc.) for their calculations
+- Calculators store [preferences (rates, percentages, etc.)](../customization/model-preferences.md) for their calculations
 
 Spree makes extensive use of the `Spree::Calculator` model and there are several subclasses provided to deal with various types of calculations flat rate, percentage discount, sales tax, VAT, etc. All calculators extend the `Spree::Calculator` class and must provide the following methods:
 
@@ -61,7 +61,7 @@ def compute(object=nil)
 end
 ```
 
-Calculators link to a `calculable` object, which are typically one of `Spree::ShippingMethod`, `Spree::TaxRate`, or `Spree::Promotion::Actions::CreateAdjustment`. These three classes use the `Spree::Core::CalculatedAdjustment` module described below to provide an easy way to calculate adjustments for their objects.
+Calculators link to a `calculable` object, which are typically one of `Spree::ShippingMethod`, `Spree::TaxRate`, or `Spree::Promotion::Actions::CreateAdjustment`. These three classes use the `Spree::CalculatedAdjustments` module described below to provide an easy way to calculate adjustments for their objects.
 
 ## Available Calculators
 
@@ -95,7 +95,7 @@ This calculator has two preferences: `amount` and `currency`. These can be set l
 
 ```ruby
 calculator.preferred_amount = 10
-calculator.currency = "USD"
+calculator.preferred_currency = "USD"
 ```
 
 The currency for this calculator is used to check to see if a shipping method is available for an order. If an order's currency does not match the shipping method's currency, then that shipping method will not be displayed on the frontend.
@@ -128,53 +128,31 @@ Thus, if you have ten items in your shopping cart, your `first_item` preference
 
 ### Per Item
 
-The Per Item calculator computes a value for every item within an order. This is useful for providing a discount for a specific product, without it affecting others.
+The Per Item calculator (`Spree::Calculator::Shipping::PerItem`) is a shipping calculator that charges a flat amount for every item in a shipment.
 
 This calculator takes two preferences:
 
-* `amount`: The amount per item to calculate.
+* `amount`: The flat amount charged per item.
 * `currency`: The currency for this calculator.
 
-This calculator depends on its `calculable` responding to a `promotion` method, which should return a `Spree::Promotion` or similar object. This object should then return a list of rules, which should respond to a `products` method. This is used to return a result of matching products.
-
-The list of matching products is compared against the line items for the order being calculated. If any of the matching products are included in the order, they are eligible for this calculator. The calculation is this:
-
-\[matching product quantity\] x \[amount\]
-
-Every matching product within an order will add to the calculator's total. For example, assuming the calculator has an `amount` of 5 and there's an order with the following line items:
-
-* Product A: `$15.00` x `2` within matching products
-* Product B: `$10.00` x `1` within matching products
-* Product C: `$20.00` x `4` excluded from matching products
-
-The calculation would be:
+It computes a flat rate per item by multiplying the `amount` preference by the total item quantity in the shipment package:
 
 ```text
-= (2 x 5) + (1 x 5)
-= 10 + 5
+[amount] x [total item quantity in package]
 ```
 
-meaning the calculator will compute an amount of 15.
+For example, with an `amount` of `5` and a package containing `3` items in total, the calculator computes an amount of `15` (`5 x 3`).
 
 ### Percent Per Item
 
-The Percent Per Item calculator works in a near-identical fashion to the [Per Item Calculator](#per-item), with the exception that rather than providing a flat-rate per item, it is a percentage.
+The Percent Per Item calculator (`Spree::Calculator::PercentOnLineItem`) applies a percentage discount to a single line item. It takes two preferences:
 
-Assuming a calculator amount of 10% and an order such as this:
+* `percent`: The percentage to apply to the line item's amount.
+* `apply_only_on_full_priced_items`: When enabled, skips line items that are already on sale.
 
-* Product A: $15.00 x 2 within matching products
-* Product B: $10.00 x 1 within matching products
-* Product C: $20.00 x 4 excluded from matching products
-
-The calculation would be:
-
-```text
-= ($15 x 2 x 10%) + ($10 x 10%)
-= ($30 x 10%) + ($10 x 10%)
-= $3 + $1
-```
+For each line item, the calculator computes `line item amount` x `percent` / `100`, capped at the line item's amount so a promotion adjustment never pushes the total negative.
 
-The calculator will calculate a discount of $4.
+For example, a `$30` line item at `10%` yields a `$3` discount (`$30 x 10% = $3`).
 
 ### Price Sack
 
@@ -269,15 +247,24 @@ end
 
 ## Calculated Adjustments
 
-If you wish to use Spree's calculator functionality for your own application, you can include the `Spree::Core::CalculatedAdjustments` module into a model of your choosing.
+If you wish to use Spree's calculator functionality for your own application, you can include the `Spree::CalculatedAdjustments` module into a model of your choosing.
 
 ```ruby app/models/plan.rb
 class Plan < ActiveRecord::Base
-  include Spree::Core::CalculatedAdjustments
+  include Spree::CalculatedAdjustments
 end
 ```
 
-To have calculators available for this class, you will need to register them:
+To have calculators available for this class, you will need to register them. `Spree.calculators` is a fixed-member struct (`SpreeCalculators`, defined in `spree/core/lib/spree/core/engine.rb`) that exposes only the four built-in buckets:
+
+* `shipping_methods`
+* `tax_rates`
+* `promotion_actions_create_adjustments`
+* `promotion_actions_create_item_adjustments`
+
+`Plan.calculators` internally calls `Spree.calculators.send(:plans)` (the tableized model name), so both registration and lookup raise `NoMethodError` until you extend the struct to add a matching `plans` member. Ruby structs cannot gain members at runtime, so this means redefining the `SpreeCalculators` struct (or reassigning `Spree.calculators` to an object that responds to `plans`) before you register anything onto it.
+
+Once the struct exposes a `plans` member you can register calculators:
 
 **Spree 5.2+:**
 
@@ -302,22 +289,15 @@ Plan.calculators
 
 Using this method, you can then display the calculators as you please. Each object for this new class will need to have a calculator associated so that adjustments can be calculated on them.
 
-This module provides a `has_one` association to a `calculator` object, as well as some convenience helpers for creating and updating adjustments for objects. Assuming that an object has a calculator associated with it first, creating an adjustment is simple:
+`Spree::CalculatedAdjustments` provides a `has_one :calculator` association (with `accepts_nested_attributes_for` and a presence validation), delegates `compute` to that calculator, exposes a `with_calculator` scope, `calculator_type` / `calculator_type=` accessors, and the `Plan.calculators` registry shown above. To work out what the calculator would compute an amount to be, call `compute` on an instance:
 
 ```ruby
-plan.create_adjustment("#{plan.name}", <target object>, <calculable object>)
+plan.compute(<calculable object>)
 ```
 
-To update this adjustment:
+The module does not define `create_adjustment`, `update_adjustment`, or `compute_amount`. If you also need to build adjustments, include `Spree::AdjustmentSource`, which adds `create_adjustment(order, adjustable, included = false)`. That method calls a `compute_amount` you define on the including model (as `Spree::TaxRate` and the `Spree::Promotion::Actions` classes do). There is no `update_adjustment` method in core.
 
-```ruby
-plan.update_adjustment(<adjustment object>, <calculable object>)
-```
-
-To work out what the calculator would compute an amount to be:
-
-```ruby
-plan.compute_amount(<calculable object>)
-```
+## Related Documentation
 
-`create_adjustment`, `update_adjustment` and `compute_amount` will call `compute` on the `Calculator` object. This `calculable` amount is whatever object your `CustomCalculator` class supports.
+- [Adjustments](adjustments.md) — the records calculators compute amounts for.
+- [Dependencies](../customization/dependencies.md) — swap out calculators via the Dependencies system.