@mercurjs/docs 2.2.1 → 2.3.0-canary.1

package/content/learn/introduction.mdx

@@ -1,71 +1,176 @@
 ---
-title: "Introduction"
-description: "Mercur is an open-source marketplace platform built on MedusaJS with a block-based architecture."
+title: "Overview"
+description: "Set up Mercur, tour the operator and seller panels, and see how a multi-vendor order flows."
 ---
 
-Mercur is an open-core **marketplace platform** built on top of the [Medusa Framework](https://medusajs.com). It follows a block-based architecture — install only the modules, workflows, API routes, and UI extensions you need directly into your project. No black-box dependencies, full code ownership.
-
 ## What is Mercur
 
-Medusa provides the underlying commerce engine — products, pricing, carts, orders, fulfillment, and events — while Mercur builds the marketplace domain layer on top of it.
-
-On top of Medusa's core, Mercur introduces marketplace entities and workflows such as sellers, onboarding, product requests, commissions, reviews, return escalations, order splitting, vendor payouts, and dedicated Admin, Vendor, and Storefront APIs.
-
-It comes with three optional interfaces:
-
-- an **Admin Panel** for marketplace operators
-- a **Vendor Portal** for seller teams
-- a **Storefront** ready for marketplace scenarios
-
-## Why Mercur
-
-### Built on a modern stack
-
-Mercur runs on a modern TypeScript backend powered by the Medusa framework, giving you a proven foundation for products, carts, orders, promotions, and payments. It integrates with technologies like Resend (notifications), Algolia (search), and Stripe Connect (payouts) — all replaceable when needed.
-
-### Block-based architecture
-
-Unlike traditional plugins, Mercur uses a **block-based** approach. Blocks are copied directly into your project via the CLI, giving you full ownership and the ability to modify any piece of code without forking.
-
-### Full extensibility and ownership
-
-Mercur is fully open-core and MIT-licensed. There are no transaction fees, no commercial lock-in, and no constraints on how your marketplace must behave. You own the entire codebase and can host it anywhere.
-
-## Building with AI
-
-Mercur is designed so AI agents can build and extend your marketplace safely — not by generating code from scratch, but by working within structured guardrails.
-
-### How AI works with Mercur
-
-Most AI coding tools generate loose snippets that you have to wire together yourself. Mercur gives AI something better to work with: a system with clear boundaries, typed contracts, and composable units.
+Mercur is the open-source enterprise marketplace platform built on Medusa. Medusa
+provides the commerce engine (products, pricing, carts, orders, fulfillment, and
+payments), and Mercur adds the marketplace layer on top: sellers and their teams,
+onboarding, the catalog change pipeline, commissions, order splitting, and vendor
+payouts.
 
-Here's what that looks like in practice:
+It gives a marketplace operator real governance: role-based access control, an
+auditable change pipeline, and per-seller settlement, while staying composable,
+API-first, and fully code-owned. You run it on your own infrastructure.
 
-- **Adding features via CLI** — An AI agent can run `bunx @mercurjs/cli@latest add reviews` to install a complete review system — data models, API routes, workflows, and UI — in one command. No guessing at file structure or imports. The CLI handles wiring automatically.
-- **Extending workflows without rebuilding them** — Need custom logic when an order is placed? AI can hook into the existing `complete-cart-with-split-orders` workflow and inject a step — without rewriting the entire cart flow. Medusa's workflow hooks make this safe and predictable.
-- **Generating typed integrations** — AI reads the generated route types from `bunx @mercurjs/cli@latest codegen` and produces API calls that are correct by construction. No hallucinated endpoints, no wrong payloads — the types are the source of truth.
-- **Building UI pages** — AI can scaffold an admin or vendor page by creating a file in `src/routes/`. The dashboard SDK picks it up automatically through file-based routing. No manual route registration, no config files to update.
-- **Modifying blocks it can diff** — AI can compare local code against the registry with `bunx @mercurjs/cli@latest diff`, understand what changed, and make targeted modifications instead of blind overwrites.
+## Requirements
 
-### Connect your AI tools
+- [Node.js v20+](https://nodejs.org/en/download) (LTS)
+- [Bun v1.3+](https://bun.sh) (recommended package manager)
+- [Git](https://git-scm.com/downloads)
+- PostgreSQL v14+
 
-To start building with AI, connect your environment to Mercur's knowledge base:
+<Tip>
+  The quickest way to run PostgreSQL locally is with Docker:
 
-- **[Building with AI](/rc/resources/ai/overview)** — How Mercur bundles version-matched docs into your project so agents build from accurate APIs, not stale training data
-- **[LLMs](/rc/resources/ai/llms)** — Feed the full Mercur documentation to any LLM via `llms.txt`
-- **[MCP Server](/rc/resources/ai/mcp)** — Let your AI tool search Mercur docs in real time (Cursor, VS Code, Claude, Claude Code)
+  ```bash
+  docker run -d --name mercur-postgres \
+    -e POSTGRES_PASSWORD=postgres \
+    -p 5432:5432 postgres:16
+  ```
+</Tip>
 
-### Why this matters
+## Create a project
 
-Traditional commerce platforms give AI no structure to reason about. The result is generated code that looks plausible but breaks in production — wrong API shapes, missing relationships, incompatible data models.
+Create a new project with the CLI. It downloads a template, installs
+dependencies, creates and migrates the database, seeds data, and starts the dev
+server.
 
-Mercur solves this with:
+```bash
+bun create mercur-app@latest
+```
 
-- **Typed API Client** — API specifications shared between server and client. AI reads real types, not documentation that may be outdated.
-- **Block Registry** — Features are discrete, well-defined units. AI can inspect what a block contains before installing it and verify the result after.
-- **Monorepo** — Backend, admin, vendor, and shared packages live in one workspace. AI has full context without jumping between repositories.
-- **Core Workflows** — Cart, orders, pricing, and vendor logic are exposed as structured steps. AI extends them through hooks rather than patching source code.
-- **Dashboard SDK** — File-based routing and virtual modules mean AI adds pages and components by creating files in the right place. The SDK handles registration.
-- **Marketplace Payments** — Payout providers follow a pluggable interface. AI can implement a new provider by conforming to the contract, not by reverse-engineering Stripe integration code.
+The CLI prompts for a project name and a template (`basic` or `plugin`), then
+handles the rest. Useful flags:
 
-The result: AI agents can compose real marketplace systems — not just write code, but add capabilities, extend business logic, and evolve your architecture with guardrails that prevent mistakes.
+| Flag | Description |
+| --- | --- |
+| `--template <template>` | Template to use (`basic` or `plugin`) |
+| `--db-connection-string <string>` | Full PostgreSQL connection string |
+| `--no-deps` | Skip dependency installation |
+| `--skip-db` | Skip database setup |
+
+## Open your marketplace
+
+Once the dev server is running, the surfaces are available at:
+
+| Surface | URL |
+| --- | --- |
+| API | `http://localhost:9000` |
+| Admin Panel | `http://localhost:9000/dashboard` |
+| Vendor Panel | `http://localhost:9000/seller` |
+
+You don't need to create any accounts to start. When the CLI finishes, it opens
+the admin invite page at `http://localhost:9000/dashboard/invite` with a token
+already filled in for `admin@mercur-test.com`. Set a password there and you are
+signed in as the operator.
+
+The seed also creates three approved demo sellers, so you can sign in to the
+Vendor Panel right away. There is no registration or approval step to go through.
+
+| Seller | Email | Password |
+| --- | --- | --- |
+| Sole Society | `seller@mercur.dev` | `supersecret` |
+| Kickz Corner | `kickz@mercur.dev` | `supersecret` |
+| Trailhead Outfitters | `trailhead@mercur.dev` | `supersecret` |
+
+To add a brand-new store instead, open the Vendor Panel and register at
+`http://localhost:9000/seller/register`, then complete the onboarding wizard. The
+new seller appears in the Admin Panel's approval queue.
+
+Restart the dev server any time from your project directory:
+
+```bash
+cd <your-project-name>
+bun dev
+```
+
+<img src="/images/admin-orders-order-groups.png" alt="Admin Panel Orders list showing order groups, each spanning one or more stores" />
+
+## Tour the platform
+
+A Mercur project ships three role-based surfaces, one per audience. Each is backed
+by the same marketplace modules and governed by role-based access.
+
+### Admin Panel
+
+The operator dashboard at `/dashboard`. This is where you run the marketplace.
+
+- **Govern sellers:** approve, suspend, or terminate stores, and manage their members and roles.
+- **Review catalog changes:** every seller edit lands in an approval queue as an attributed, immutable change you confirm or decline.
+- **Set the economics:** configure commission rules across products, categories, and sellers.
+- **Watch the money:** see orders across every seller and monitor payouts marketplace-wide.
+
+<video
+  autoPlay
+  muted
+  loop
+  playsInline
+  controls
+  className="w-full aspect-video"
+  src="/images/platform-walkthrough.mp4"
+/>
+
+### Vendor Panel
+
+The seller portal at `/seller`, scoped so a seller only ever sees its own store.
+
+- **List products:** create offers against the shared catalog with a seller's own SKU, price, inventory, and shipping.
+- **Fulfill orders:** view, fulfill, and refund orders, and handle returns.
+- **Get paid:** complete provider onboarding and track payouts.
+- **Run a team:** invite members and assign roles.
+
+<video
+  autoPlay
+  muted
+  loop
+  playsInline
+  controls
+  className="w-full aspect-video"
+  src="/images/seller-walkthrough.mp4"
+/>
+
+### Store API
+
+The storefront API under `/store/*` that your customer-facing frontend talks to.
+It exposes marketplace discovery (sellers and offers) and a cart that can span
+multiple sellers, then splits it into per-seller orders at checkout.
+
+## How a multi-vendor order flows
+
+The clearest way to see what the platform does is to follow one order from cart to
+payout. A single customer cart can hold items from several sellers.
+
+<Steps>
+  <Step title="One cart, many sellers">
+    A customer adds offers from different sellers to a single cart through the Store API.
+  </Step>
+  <Step title="Checkout splits the cart">
+    Completing the cart runs the split-order workflow. Items are grouped by seller, and a separate order is created for each, all linked under one order group with a shared display id.
+  </Step>
+  <Step title="Commissions are calculated">
+    For each order, Mercur resolves the matching commission rule and records the commission lines. All arithmetic uses arbitrary precision, so totals stay exact.
+  </Step>
+  <Step title="Each seller is settled">
+    Payment is split across the per-seller orders, and each seller's earnings settle to their connected account through the payout provider, minus commission.
+  </Step>
+</Steps>
+
+The operator sees the whole order group; each seller sees only its slice. Every
+step is governed by the same roles and recorded for audit.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Architecture" icon="sitemap" href="/learn/architecture">
+    How Mercur layers the marketplace domain on Medusa.
+  </Card>
+  <Card title="Platform" icon="cubes" href="/platform/store/overview">
+    Every marketplace capability, with its data models and workflows.
+  </Card>
+  <Card title="Build with AI" icon="robot" href="/resources/ai/overview">
+    Bundled docs, agent skills, and the MCP server.
+  </Card>
+</CardGroup>

package/content/learn/migration-to-2-0.mdx

@@ -0,0 +1,187 @@
+---
+title: "Migration to 2.0"
+sidebarTitle: "Migration to 2.0"
+description: "Port an existing Mercur 1.x project to 2.x, the latest release."
+---
+
+> A step-by-step guide to porting an existing Mercur 1.x project to 2.x, the latest release.
+
+Mercur 2.0 replaces the monolithic plugin architecture (`@mercurjs/b2c-core`) with a block-based model (`@mercurjs/core` plus registry blocks). This guide is about porting your existing 1.x code to a 2.x project. For setting up a fresh project instead, see [Installation](/learn/introduction), which already uses the latest names.
+
+## Before you start
+
+Most users do not need to migrate much. Core and the official registry blocks cover most standard marketplace functionality, and the admin and vendor panels ship 34+ pages out of the box. You only need to port your own custom modules, workflows, routes, and any domain-specific dashboard pages that core does not already provide.
+
+Here is what replaced what between 1.x and 2.x:
+
+| 1.x | 2.x |
+|-----|-----|
+| `@mercurjs/b2c-core` (monolithic) | `@mercurjs/core`, all core modules built in |
+| `@mercurjs/commission` (separate) | Built into core |
+| `@mercurjs/algolia`, reviews, requests | Registry blocks (`mercurjs add ...`) |
+| `@medusajs/admin-vite-plugin` | `@mercurjs/dashboard-sdk` (virtual modules) |
+| `@medusajs/js-sdk` (manual hooks) | `@mercurjs/client` (generated typed client) |
+| Custom admin and vendor pages | `@mercurjs/admin` and `@mercurjs/vendor`, complete panels out of the box |
+| `apps/backend/` | `packages/api/` |
+| `src/routes/` (admin) | `src/pages/` (file-based routing) |
+| Yarn plus Turbo | bun (recommended) |
+
+The MedusaJS v2 foundation (modules, workflows, links, subscribers, API routes), the data model patterns (MikroORM, service layer), and your environment variables (`DATABASE_URL`, CORS, secrets) are all unchanged.
+
+<Note>
+**Using a version older than 1.4.0?** Your admin panel code lives inside the backend repo, not a separate app. When scanning for custom admin code to port, look there instead of `apps/admin/`. Everything else in this guide applies identically.
+</Note>
+
+## Step 1: Start from a fresh 2.x project
+
+Set up a working 2.x project first (see [Installation](/learn/introduction)), then port your 1.x code into it. Do not upgrade the old project in place.
+
+## Step 2: Map your packages
+
+Replace 1.x packages with their 2.x equivalents:
+
+| 1.x package | 2.x equivalent |
+|-------------|----------------|
+| `@mercurjs/b2c-core` | `@mercurjs/core` |
+| `@mercurjs/commission` | Built into core |
+| `@mercurjs/algolia` | Block: `mercurjs add algolia` |
+| `@mercurjs/resend` | No 2.x equivalent, port manually |
+| `@mercurjs/payment-stripe-connect` | No 2.x equivalent, port manually |
+| `@mercurjs/stripe-tax-provider` | No 2.x equivalent, port manually |
+| `@medusajs/admin-vite-plugin` | `@mercurjs/dashboard-sdk` |
+| `@medusajs/js-sdk` | `@mercurjs/client` |
+
+Several features that were separate packages in 1.x are now installed as registry blocks. Install these instead of porting their 1.x package code:
+
+`reviews`, `requests`, `wishlist`, `team-management`, `algolia`, `vendor-notifications`, `vendor-chat`, `product-import-export`.
+
+The `seller`, `payout`, and `commission` modules are built into core, so there is nothing to port for those.
+
+## Step 3: Map your directories
+
+| 1.x | 2.x |
+|-----|-----|
+| `apps/backend/src/*` | `packages/api/src/*` |
+| `apps/admin/src/routes/` | `apps/admin/src/pages/` |
+| `apps/vendor/src/routes/` | `apps/vendor/src/pages/` |
+
+## Step 4: Port custom backend code
+
+Copy each kind of custom code into `packages/api/src/` and update imports from `@mercurjs/b2c-core` to `@mercurjs/core`.
+
+- **Modules**: copy to `packages/api/src/modules/` and register them in `medusa-config.ts`.
+- **Workflows**: copy to `packages/api/src/workflows/<entity>/`. Do not create barrel `index.ts` files, as they conflict with block installation.
+- **API routes**: copy to `packages/api/src/api/`. Type both generics so codegen can read them, then run `bunx @mercurjs/cli@latest codegen`.
+
+  ```typescript
+  export const GET = async (
+    req: AuthenticatedMedusaRequest<BodyType>,
+    res: MedusaResponse<ResponseType>
+  ) => { ... }
+  ```
+
+- **Links and subscribers**: copy to `packages/api/src/links/` and `src/subscribers/`. Do not duplicate links that core already provides (seller to product, seller to order, and so on).
+- **Custom providers**: copy to `packages/api/src/providers/`, then make two required changes:
+
+  ```typescript
+  // medusa-config.ts must use the ./src/ prefix
+  resolve: './src/providers/my-provider'
+
+  // provider index.ts must import from framework/utils
+  import { Modules, ModuleProvider } from "@medusajs/framework/utils"
+  ```
+
+## Step 5: Port custom dashboard code
+
+Only needed if you have custom pages that core admin and vendor do not cover. Update imports and move pages from `src/routes/` to `src/pages/` with a `export default`.
+
+| Old import | New import |
+|-----------|------------|
+| `@medusajs/js-sdk` | `@mercurjs/client` |
+| `@custom-types/*` | `@mercurjs/types` |
+| `@hooks/*`, `@components/*`, `@lib/*` | Keep local, or `@mercurjs/dashboard-shared` if the symbol exists there |
+
+## Step 6: Rename Order Set to Order Group
+
+The 1.x `OrderSet` entity is renamed to `OrderGroup` in 2.x. This is a breaking change that affects database tables, API endpoints, workflow names, event names, and types.
+
+| Aspect | 1.x | 2.x |
+|--------|-----|-----|
+| Entity and table | `order_set` | `order_group` |
+| ID prefix | `os_` | `og_` |
+| API endpoints | `/admin/order-sets`, `/store/order-set` | `/admin/order-groups`, `/store/order-groups` |
+| Workflows | `getFormattedOrderSetListWorkflow` | `getOrderGroupsListWorkflow`, `getOrderGroupDetailWorkflow` |
+| Events | `OrderSetWorkflowEvents` | `OrderGroupWorkflowEvents` |
+| Types | `OrderSetDTO` | `OrderGroupDTO` (from `@mercurjs/types`) |
+
+Two fields were removed from the group:
+
+- **`payment_collection_id`**: payment collections are now linked at the individual order level. Query the linked orders to get the payment collection.
+- **`sales_channel_id`**: the sales channel is stored on each individual order.
+
+Two fields are now computed at query time rather than stored: **`seller_count`** (distinct sellers across linked orders) and **`total`** (sum of order totals).
+
+To migrate:
+
+1. Update imports: `OrderSetDTO` to `OrderGroupDTO` (from `@mercurjs/types`).
+2. Update API calls: `/order-sets` to `/order-groups`.
+3. Update workflow references: `getFormattedOrderSetListWorkflow` to `getOrderGroupsListWorkflow`.
+4. Update event listeners: `OrderSetWorkflowEvents` to `OrderGroupWorkflowEvents`.
+5. If you read `payment_collection_id` or `sales_channel_id` from the order set, read them from the individual orders instead (via the `order_group_order` link).
+
+See [Order Group](/platform/order-group/overview) for the full 2.x data model and API reference.
+
+## Step 7: Upgrade to the latest release
+
+After 2.0, the Medusa plugin was renamed from `@mercurjs/core-plugin` to `@mercurjs/core`. The package contents are the same. If you started from a current 2.x install, you are already on the new name and can skip this step.
+
+### Swap the dependency
+
+```bash
+bun remove @mercurjs/core-plugin
+bun add @mercurjs/core
+```
+
+### Replace the name in config and source
+
+In `packages/api/medusa-config.ts` and anywhere under `packages/api/src/**`, replace every occurrence of `@mercurjs/core-plugin` with `@mercurjs/core`. A repo-wide find-and-replace is safe. This applies to `resolve` values and imports alike:
+
+```ts
+// before
+resolve: "@mercurjs/core-plugin/modules/seller"
+import { createSellerWorkflow } from "@mercurjs/core-plugin/workflows"
+
+// after
+resolve: "@mercurjs/core/modules/seller"
+import { createSellerWorkflow } from "@mercurjs/core/workflows"
+```
+
+The same applies to `@mercurjs/core-plugin/modules/<module>`, `/workflows`, `/links`, and `/api`. Installed registry blocks live under `packages/api/src/`, so the same find-and-replace covers them.
+
+### Reinstall, migrate, and rebuild
+
+```bash
+bun install
+bun run medusa db:migrate
+bun run build
+```
+
+The database migrations are non-destructive. If TypeScript still reports `@mercurjs/core-plugin`, you missed an import: re-run the find-and-replace.
+
+## Known limitations
+
+These areas do not currently have full 1.x parity and require manual migration for now:
+
+- **`TaxCode`**: no 2.x equivalent today. Port the old logic manually if your project depends on it.
+- **`SecondaryCategory`**: no 2.x equivalent, and none is planned. Port the old logic manually if your project depends on it.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Installation" href="/learn/introduction">
+    Set up a fresh 2.x project to port your code into.
+  </Card>
+  <Card title="Order Group" href="/platform/order-group/overview">
+    The full 2.x data model that replaced Order Set.
+  </Card>
+</CardGroup>

package/content/learn/why-mercur.mdx

@@ -0,0 +1,91 @@
+---
+title: "Why Mercur"
+description: "Why teams choose Mercur to run an enterprise marketplace: governance, ownership, and composability without a closed platform."
+---
+
+The enterprise marketplace platform for teams that need governance, ownership, and
+control, not a closed SaaS.
+
+Mercur runs a multi-vendor marketplace on infrastructure you own. It gives an
+operator the governance a marketplace needs (role-based access, an auditable
+change pipeline, and per-seller settlement) while staying composable, API-first,
+and AI-native. You get the control of an enterprise platform without the closed
+code or a commission on gross merchandise value.
+
+## Governance, built in
+
+A marketplace operator has to control who sells, what they change, and how money
+moves. Mercur builds that into the platform instead of bolting it on.
+
+- **Role-based access control:** members belong to stores with roles resolved per store, and every vendor request is scoped to its own seller. Access to one store never leaks into another.
+- **Auditable change pipeline:** every catalog edit is an immutable, attributed change with an approval queue, so you always know who changed what and who approved it.
+- **Per-seller settlement:** policy-based commissions, order splitting, and provider-driven payouts settle each seller independently and to the cent.
+
+## You own the platform
+
+- **Own the code:** blocks ship as source you copy into your project. There are no black-box dependencies, and you can modify any line.
+- **Own the deployment:** self-host on your own cloud, on-premise, or a private network, with no hosted vendor in the request path.
+- **No lock-in:** Mercur is MIT-licensed, with no transaction fees and no commission on gross merchandise value.
+
+## Composable, not monolithic
+
+Closed platforms give you a fixed feature set behind a console. Mercur gives you
+primitives.
+
+- Install only the modules, workflows, and UI extensions you need.
+- Extend core flows through hooks and the typed client, not by patching source.
+- Replace any layer, such as search, notifications, or payouts, with your own.
+
+Composable is not a step down from enterprise. It is how you make the platform fit
+your business instead of the other way around.
+
+## AI-native, enterprise-governed
+
+Mercur is built so AI agents extend your marketplace within guardrails. Typed
+contracts, build gates, and version-matched docs mean an agent's change is correct
+by construction or it fails to compile. Agents work inside the same roles and
+review pipeline as people. They extend the platform, they do not bypass its
+governance.
+
+## Built on Medusa
+
+Mercur runs on the Medusa commerce engine, so products, pricing, carts, orders,
+and payments are proven, maintained infrastructure. You inherit Medusa's maturity
+and extension model, and Mercur adds only the marketplace layer on top.
+
+## Mercur vs closed marketplace platforms
+
+Closed platforms such as Mirakl, VTEX, or Spryker deliver marketplace governance,
+but behind proprietary code, a fixed runtime, and a commission on your GMV. Mercur
+gives you the same operator governance with the opposite trade-offs.
+
+| | Closed platform | Mercur |
+| --- | --- | --- |
+| Code | Proprietary and opaque | Open source, you own it |
+| Hosting | Vendor-hosted | Self-hosted on your infrastructure |
+| Extensibility | Configuration only | Composable modules and workflows |
+| AI | Not agent-native | AI-native and governed |
+| Pricing | Commission on GMV | No GMV fees, MIT-licensed |
+
+## Who it's for
+
+Mercur fits teams that need to run a real multi-vendor marketplace with operator
+governance, but want to own the code and the infrastructure rather than rent a
+closed platform.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Overview" icon="rocket" href="/learn/introduction">
+    Set up Mercur and run a marketplace locally.
+  </Card>
+  <Card title="Architecture" icon="sitemap" href="/learn/architecture">
+    How Mercur layers the marketplace domain on Medusa.
+  </Card>
+  <Card title="Platform" icon="cubes" href="/platform/store/overview">
+    Every marketplace capability, with its data models and workflows.
+  </Card>
+  <Card title="Build with AI" icon="robot" href="/resources/ai/overview">
+    Bundled docs, agent skills, and the MCP server.
+  </Card>
+</CardGroup>

package/content/platform/attribute/concepts/attribute-types.mdx

@@ -0,0 +1,59 @@
+---
+title: "Attribute types"
+sidebarTitle: "Attribute types"
+description: "The five attribute types and the values they hold."
+---
+
+In this document, you'll learn about the attribute record, its five types, and
+the values attached to it.
+
+## Product attribute
+
+An attribute is a typed field in the shared catalog, represented by the
+`ProductAttribute` data model (table `product_attribute`, id prefix `pattr`).
+Each attribute carries a `name`, an optional `handle`, a `rank` for ordering, and
+a `type` that decides how its values are validated and rendered.
+
+```ts
+const { result } = await createProductAttributesWorkflow(container).run({
+  input: {
+    attributes: [
+      {
+        name: "Material",
+        type: "single_select",
+        values: [{ name: "Cotton" }, { name: "Wool" }],
+      },
+    ],
+  },
+})
+```
+
+The `type` field is one of the `AttributeType` enum values:
+
+| Type | Value | Holds |
+| --- | --- | --- |
+| Single select | `single_select` | One choice from a fixed list of values |
+| Multi select | `multi_select` | Several choices from a fixed list of values |
+| Text | `text` | A free-form string |
+| Unit | `unit` | A numeric measurement (e.g. weight, capacity) |
+| Toggle | `toggle` | A boolean, backed by seeded `true` / `false` values |
+
+## Product attribute value
+
+The choices for select-style attributes are `ProductAttributeValue` records
+(table `product_attribute_value`, id prefix `pattrval`). Each value belongs to
+one attribute (`attribute_id`), has its own `name`, `handle`, and `rank`, and is
+deleted along with its parent attribute.
+
+<Note>
+  `single_select` and `multi_select` attributes hold a list of predefined
+  `ProductAttributeValue` records. `text` and `unit` create a value on the fly
+  from the entered content when attached to a product. `toggle` is seeded with
+  its `true` / `false` values and never creates new ones.
+</Note>
+
+<Tip>
+  Use `is_required` to enforce that a product must carry a value for the
+  attribute, and `is_active` to retire an attribute from new use without deleting
+  its history.
+</Tip>

package/content/platform/attribute/concepts/global-vs-inline.mdx

@@ -0,0 +1,50 @@
+---
+title: "Global vs inline & filtering"
+sidebarTitle: "Global vs inline"
+description: "Catalog-wide attributes, product-scoped attributes, and storefront filtering."
+---
+
+In this document, you'll learn the difference between global and inline
+attributes and how an attribute becomes a storefront filter.
+
+## Scope
+
+Every `ProductAttribute` is either **global** or **inline**, decided by its
+`product_id` field:
+
+| Scope | `product_id` | Meaning |
+| --- | --- | --- |
+| Global | `null` | A catalog entry, reusable across any product, listed in the operator's attribute catalog |
+| Inline | set | A one-off attribute scoped to a single product, created from that product's form and hidden from the global catalog |
+
+```ts
+// Global: reusable across the catalog
+{ name: "Material", type: "single_select", values: [{ name: "Cotton" }] }
+
+// Inline: scoped to one product, created as it's attached
+{ title: "Gift wrap", type: "toggle", product_id: "prod_123" }
+```
+
+A global attribute is defined once and attached to many products. An inline
+attribute is created in the same step it is attached and only ever describes that
+one product. It is useful for the occasional one-off field that doesn't belong in
+the shared vocabulary.
+
+<Note>
+  Attributes describe products in the **shared master catalog**. They are never
+  owned by a store. A seller sells against a master product through an offer, and
+  the product's attributes come from the catalog, not from the seller.
+</Note>
+
+## Filtering
+
+An attribute with `is_filterable` set to `true` is exposed as a storefront
+filter, letting shoppers narrow the catalog by its values. Leave it `false` for
+descriptive-only attributes that shouldn't appear as facets.
+
+<Tip>
+  Filtering pairs naturally with variant axes: a filterable `multi_select` axis
+  like Color both generates variants and lets shoppers filter by them. A
+  descriptive `text` attribute like Care instructions is usually left
+  non-filterable.
+</Tip>