@mercurjs/docs 2.2.0-canary.40

package/README.md

@@ -0,0 +1,24 @@
+# @mercurjs/docs
+
+Bundled Mercur documentation, shipped as a dependency so AI agents can read it
+locally — offline and version-matched to the installed packages.
+
+## For agents
+
+1. Read `llms.txt` — a grouped index of every page with its description.
+2. Open the referenced file under `content/` for the full page before implementing.
+
+Paths in `llms.txt` are relative to this package
+(`node_modules/@mercurjs/docs/`).
+
+## Contents
+
+- `llms.txt` — the index.
+- `content/**/*.mdx` — the documentation pages, mirroring the structure of the
+  docs site (`learn/`, `resources/`, `tools/`, `references/`, `user-guide/`,
+  `migration/`).
+
+## Build
+
+`content/` and `llms.txt` are generated from `apps/docs/rc` by
+`scripts/build.mjs` (run via `turbo run build`). They are not committed.

package/content/blocks.mdx

@@ -0,0 +1,209 @@
+---
+title: "Official Blocks"
+sidebarTitle: "Official Blocks"
+description: "Modular blocks from the official Mercur registry — install only what you need."
+mode: "custom"
+---
+
+<div className="max-w-5xl mx-auto px-6 py-16">
+
+  <div className="mb-12">
+    <h1 className="text-4xl font-bold tracking-tight mb-4">Official Blocks</h1>
+    <p className="text-lg text-gray-500 dark:text-gray-400 max-w-2xl mb-6">
+      Blocks are modular pieces of marketplace functionality — API routes, workflows, UI pages, and data models. Each block is copied directly into your project. You own the code.
+    </p>
+    <div className="inline-flex items-center gap-3 px-4 py-2.5 rounded-lg border border-gray-200 dark:border-gray-700 bg-gray-50 dark:bg-gray-800">
+      <code className="text-sm font-mono text-gray-800 dark:text-gray-100">bunx @mercurjs/cli@rc add &lt;block-name&gt;</code>
+    </div>
+  </div>
+
+  <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
+
+    <div className="p-5 rounded-xl border border-gray-200 dark:border-gray-800">
+      <div className="flex items-center gap-3 mb-1">
+        <span className="text-base">⭐</span>
+        <h3 className="font-semibold text-base m-0">reviews</h3>
+      </div>
+      <p className="text-sm text-gray-500 dark:text-gray-400 mb-3">Product and seller reviews with ratings, customer/vendor/admin API routes, and workflows.</p>
+      <div className="flex flex-wrap gap-1.5">
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">module</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">workflow</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">api</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">admin</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">vendor</span>
+      </div>
+    </div>
+
+    <div className="p-5 rounded-xl border border-gray-200 dark:border-gray-800">
+      <div className="flex items-center gap-3 mb-1">
+        <span className="text-base">👥</span>
+        <h3 className="font-semibold text-base m-0">team-management</h3>
+      </div>
+      <p className="text-sm text-gray-500 dark:text-gray-400 mb-3">Team member management with invitations, roles, and vendor portal pages.</p>
+      <div className="flex flex-wrap gap-1.5">
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">module</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">workflow</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">api</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">vendor</span>
+      </div>
+    </div>
+
+    <div className="p-5 rounded-xl border border-gray-200 dark:border-gray-800">
+      <div className="flex items-center gap-3 mb-1">
+        <span className="text-base">🔖</span>
+        <h3 className="font-semibold text-base m-0">wishlist</h3>
+      </div>
+      <p className="text-sm text-gray-500 dark:text-gray-400 mb-3">Customer wishlist with product bookmarking, pricing context, and store API endpoints.</p>
+      <div className="flex flex-wrap gap-1.5">
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">module</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">workflow</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">api</span>
+      </div>
+    </div>
+
+    <div className="p-5 rounded-xl border border-gray-200 dark:border-gray-800">
+      <div className="flex items-center gap-3 mb-1">
+        <span className="text-base">🔔</span>
+        <h3 className="font-semibold text-base m-0">vendor-notifications</h3>
+      </div>
+      <p className="text-sm text-gray-500 dark:text-gray-400 mb-3">Vendor notification feed with bell icon in the navbar and a vendor API endpoint.</p>
+      <div className="flex flex-wrap gap-1.5">
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">api</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">vendor</span>
+      </div>
+    </div>
+
+    <div className="p-5 rounded-xl border border-gray-200 dark:border-gray-800">
+      <div className="flex items-center gap-3 mb-1">
+        <span className="text-base">🔍</span>
+        <h3 className="font-semibold text-base m-0">algolia</h3>
+      </div>
+      <p className="text-sm text-gray-500 dark:text-gray-400 mb-3">Algolia search integration with product indexing, event-driven sync, and store search API.</p>
+      <div className="flex flex-wrap gap-1.5">
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">module</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">workflow</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">api</span>
+      </div>
+    </div>
+
+    <div className="p-5 rounded-xl border border-gray-200 dark:border-gray-800">
+      <div className="flex items-center gap-3 mb-1">
+        <span className="text-base">🔎</span>
+        <h3 className="font-semibold text-base m-0">meilisearch</h3>
+      </div>
+      <p className="text-sm text-gray-500 dark:text-gray-400 mb-3">Meilisearch search integration with product indexing, seller moderation sync, filtering, and store/admin API.</p>
+      <div className="flex flex-wrap gap-1.5">
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">module</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">workflow</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">api</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">subscriber</span>
+      </div>
+    </div>
+
+    <div className="p-5 rounded-xl border border-gray-200 dark:border-gray-800">
+      <div className="flex items-center gap-3 mb-1">
+        <span className="text-base">✅</span>
+        <h3 className="font-semibold text-base m-0">requests</h3>
+      </div>
+      <p className="text-sm text-gray-500 dark:text-gray-400 mb-3">Admin approval system for entity requests — list, review, accept or reject submissions.</p>
+      <div className="flex flex-wrap gap-1.5">
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">workflow</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">api</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">admin</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">vendor</span>
+      </div>
+    </div>
+
+    <div className="p-5 rounded-xl border border-gray-200 dark:border-gray-800">
+      <div className="flex items-center gap-3 mb-1">
+        <span className="text-base">📦</span>
+        <h3 className="font-semibold text-base m-0">product-import-export</h3>
+      </div>
+      <p className="text-sm text-gray-500 dark:text-gray-400 mb-3">CSV product import & export for vendors. Includes API routes, workflows, and portal drawers.</p>
+      <div className="flex flex-wrap gap-1.5">
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">workflow</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">api</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">vendor</span>
+      </div>
+    </div>
+
+    <div className="p-5 rounded-xl border border-gray-200 dark:border-gray-800">
+      <div className="flex items-center gap-3 mb-1">
+        <span className="text-base">💬</span>
+        <h3 className="font-semibold text-base m-0">vendor-chat</h3>
+      </div>
+      <p className="text-sm text-gray-500 dark:text-gray-400 mb-3">TalkJS chat integration for vendors — API endpoint for seller conversations and a Messages page.</p>
+      <div className="flex flex-wrap gap-1.5">
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">api</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">vendor</span>
+      </div>
+    </div>
+
+    <div className="p-5 rounded-xl border border-gray-200 dark:border-gray-800">
+      <div className="flex items-center gap-3 mb-1">
+        <span className="text-base">✉️</span>
+        <h3 className="font-semibold text-base m-0">messaging</h3>
+      </div>
+      <p className="text-sm text-gray-500 dark:text-gray-400 mb-3">Buyer-vendor messaging with real-time SSE, content filtering, chat blocking, rate limiting, and admin oversight.</p>
+      <div className="flex flex-wrap gap-1.5">
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">module</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">workflow</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">api</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">admin</span>
+        <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">vendor</span>
+      </div>
+    </div>
+
+  </div>
+
+  <div className="mt-10 p-5 rounded-xl border border-gray-200 dark:border-gray-800">
+    <p className="text-sm text-gray-500 dark:text-gray-400 m-0">
+      Blocks are copied directly into your project — no runtime dependencies on Mercur.
+      After installing, follow the setup steps in the <a href="/developer-guide/blocks" className="text-gray-900 dark:text-gray-100 font-medium underline underline-offset-2">Developer Guide</a>.
+      Want to build your own? See the <a href="/developer-guide/registry" className="text-gray-900 dark:text-gray-100 font-medium underline underline-offset-2">Registry Guide</a>.
+    </p>
+  </div>
+
+  <div className="mt-12 mb-4">
+    <h2 className="text-2xl font-bold tracking-tight mb-4">Quick Start</h2>
+
+    <h3 className="text-lg font-semibold mb-2">Install a block</h3>
+
+```bash
+bunx @mercurjs/cli@rc add reviews
+```
+
+This copies the block source code into your project:
+
+```
+src/
+├── modules/reviews/          # Data model and service
+│   ├── models/
+│   ├── service.ts
+│   └── index.ts
+├── workflows/reviews/        # Business logic
+│   ├── create-review.ts
+│   └── index.ts
+├── api/
+│   ├── admin/reviews/        # Admin API routes
+│   ├── vendor/reviews/       # Vendor API routes
+│   └── store/reviews/        # Storefront API routes
+└── admin/
+    └── routes/reviews/       # Admin dashboard pages
+```
+
+    <h3 className="text-lg font-semibold mt-6 mb-2">Search blocks</h3>
+
+```bash
+bunx @mercurjs/cli@rc search -q "reviews"
+```
+
+    <h3 className="text-lg font-semibold mt-6 mb-2">Compare local changes against registry</h3>
+
+```bash
+bunx @mercurjs/cli@rc diff reviews
+```
+
+  </div>
+
+</div>

package/content/learn/architecture.mdx

@@ -0,0 +1,215 @@
+---
+title: "Overview"
+description: "How Mercur is built — architecture, technology stack, and how the pieces fit together."
+---
+
+Mercur is a marketplace platform built on top of [MedusaJS](https://medusajs.com), an open-source headless commerce framework. Rather than being a standalone application, Mercur extends Medusa with marketplace-specific logic — sellers, commissions, order splitting, payouts — while Medusa handles the foundational commerce layer.
+
+This page explains how the system is structured and how its components interact.
+
+## Architecture
+
+Mercur follows a layered architecture where each layer has a distinct responsibility:
+
+```mermaid
+graph TD
+    subgraph Frontend Layer
+        A[Admin Panel]
+        B[Vendor Portal]
+        C[Storefront]
+    end
+
+    subgraph API Layer
+        D["/admin/*"]
+        E["/vendor/*"]
+        F["/store/*"]
+    end
+
+    subgraph Marketplace Layer - Mercur
+        G[Modules · Workflows · Links · Subscribers · Events]
+    end
+
+    subgraph Commerce Layer - Medusa
+        H[Products · Orders · Carts · Payments · Fulfillment]
+    end
+
+    I[(PostgreSQL)]
+
+    A --> D
+    B --> E
+    C --> F
+    D --> G
+    E --> G
+    F --> G
+    G --> H
+    H --> I
+```
+
+### Commerce layer
+
+Medusa provides the core commerce engine — products, pricing, carts, orders, payments, fulfillment, promotions, and inventory. Mercur does not replace any of this. Instead, it builds on top using Medusa's extension model: custom modules, links, workflows, and API routes.
+
+### Marketplace layer
+
+This is where Mercur's code lives. It introduces marketplace modules — **Seller**, **Commission**, **Offer**, **Payout**, **Product Attribute**, and **Product Edit**, among others — along with workflows that coordinate marketplace-specific operations like order splitting, product approvals, and commission calculation. Links connect these modules to Medusa's core entities (products, orders, customers) without modifying the original models.
+
+### API layer
+
+Mercur exposes three sets of HTTP endpoints:
+
+| API | Path | Purpose |
+|-----|------|---------|
+| **Admin** | `/admin/*` | Platform administration — manage sellers, configure commission rates, view payouts |
+| **Vendor** | `/vendor/*` | Seller operations — manage products, orders, fulfillment, shipping, inventory, payouts |
+| **Store** | `/store/*` | Storefront — browse sellers, manage carts, checkout with order splitting |
+
+Each API route is composed of a request handler, middleware, query configuration, and Zod validators.
+
+### Frontend layer
+
+Three interfaces consume the APIs:
+
+- **Admin Panel** — Built with React and Medusa UI components. Operators use it to manage the marketplace: approve sellers, set commission rates, handle disputes.
+- **Vendor Portal** — A React application for sellers to manage their products, orders, fulfillment, and payouts. Uses file-based routing via the Dashboard SDK.
+- **Storefront** — Customer-facing application. Can be built with any frontend technology that consumes the Store API.
+
+## Technology stack
+
+| Layer | Technology |
+|-------|-----------|
+| Runtime | Node.js 20+, TypeScript |
+| Framework | MedusaJS v2 |
+| Database | PostgreSQL |
+| Frontend | React 18, React Router, Vite |
+| Data fetching | TanStack React Query |
+| UI components | Medusa UI, Radix UI |
+| Form handling | React Hook Form, Zod |
+| Tables | TanStack React Table |
+| Build | Turborepo (monorepo), Bun (package manager), tsup |
+| Internationalization | i18next |
+
+## Core plugin
+
+The core plugin (`@mercurjs/core`) is the main package that contains all marketplace logic. It's structured as a standard MedusaJS plugin:
+
+```
+core/src/
+├── modules/          # Data models and services
+│   ├── seller/       # Seller registration, profiles, members, order groups
+│   ├── commission/   # Commission rates, rules, calculation
+│   ├── offer/        # Seller listings against the shared product catalog
+│   ├── payout/       # Payout accounts, onboarding, payouts
+│   ├── product-attribute/  # Typed attribute catalog and values
+│   ├── product-edit/ # Product change requests and audit trail
+│   └── ...           # Media, custom fields, search
+├── links/            # Relationships between modules
+├── workflows/        # Multi-step business processes
+│   ├── seller/       # Seller CRUD workflows
+│   ├── cart/         # Cart completion with order splitting
+│   ├── commission/   # Commission rate and line management
+│   ├── payout/       # Payout processing and crediting
+│   ├── offer/        # Offer lifecycle
+│   ├── product/      # Product approval and seller linking
+│   ├── product-edit/ # Change-request lifecycle
+│   ├── order-group/  # Order group operations
+│   └── ...           # Attributes, shipping, inventory, promotions, etc.
+├── api/              # HTTP route handlers
+│   ├── admin/        # Admin API routes
+│   ├── vendor/       # Vendor API routes
+│   ├── store/        # Store API routes
+│   └── hooks/        # Webhook handlers
+├── subscribers/      # Event listeners
+├── providers/        # Third-party provider integrations
+└── jobs/             # Scheduled background tasks
+```
+
+### Modules
+
+Modules encapsulate data models and business logic for a specific domain. Each module is self-contained with its own models, service, migrations, and repositories. Modules don't reference each other directly — they communicate through links and workflows.
+
+### Links
+
+Links define relationships between Mercur modules and Medusa core entities. For example, the `product-seller-link` connects a Medusa `Product` to a Mercur `Seller` without modifying either model. Dozens of links wire the marketplace layer into the commerce layer — connecting sellers to their scoped resources (orders, customers, shipping, inventory, promotions), offers to products, variants, prices, and line items, order groups to carts and orders, and attributes to Medusa's native product options.
+
+### Workflows
+
+Workflows orchestrate multi-step operations that span multiple modules. They support compensation (automatic rollback on failure) and hooks (extension points for custom logic). The most significant workflow is `completeCartWithSplitOrdersWorkflow`, which handles the entire checkout process — validating items, splitting by seller, creating orders, allocating payments, and calculating commissions.
+
+### Subscribers and events
+
+Subscribers listen for events emitted by workflows and trigger asynchronous side effects — sending notifications, updating external systems, or processing webhooks. This keeps the core workflows focused on their primary job while allowing the system to react to changes.
+
+## How data flows
+
+A typical customer purchase flows through the system like this:
+
+1. **Customer adds items** from multiple sellers to their cart (Store API)
+2. **Cart completion** triggers the split order workflow (Marketplace Layer)
+3. Items are **grouped by seller**, and a separate order is created for each (Commerce + Marketplace Layer)
+4. **Commission lines** are calculated for each order based on matching rates (Commission Module)
+5. **Payment is split** proportionally across seller orders (Commerce Layer)
+6. Each seller's order is **credited to their payout account** after commission deduction (Payout Module)
+7. **Events are emitted** — triggering notifications, webhook calls, and other side effects (Subscribers)
+8. Sellers **manage their orders** through the Vendor Portal (Vendor API)
+9. The admin **monitors everything** through the Admin Panel (Admin API)
+
+## Block-based distribution
+
+Mercur uses a **block-based architecture** for distribution. Instead of installing an opaque package, the CLI copies source code directly into your project. Each block is a self-contained piece of functionality — a module, a workflow, an API route, or a UI extension.
+
+This means:
+- You own every line of code in your project
+- You can modify any block to fit your business requirements
+- There are no hidden abstractions or version conflicts
+- Updates are explicit — you diff and apply changes from the registry
+
+The CLI (`@mercurjs/cli@rc`) manages this process: scaffolding projects, installing blocks, searching the registry, and comparing local changes against upstream versions.
+
+## Workflow example
+
+Here is a simplified example of how a Mercur workflow is structured. Workflows coordinate multi-step operations with automatic rollback on failure:
+
+```typescript
+import {
+  createWorkflow,
+  createStep,
+  StepResponse,
+  WorkflowResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { MercurModules } from "@mercurjs/types"
+
+const validateSellerStep = createStep(
+  "validate-seller",
+  async ({ seller_id }: { seller_id: string }, { container }) => {
+    const sellerService = container.resolve(MercurModules.SELLER)
+    const seller = await sellerService.retrieveSeller(seller_id)
+
+    if (seller.status !== "open") {
+      throw new Error("Seller is not active")
+    }
+
+    return new StepResponse(seller)
+  }
+)
+
+const createProductForSellerWorkflow = createWorkflow(
+  "create-product-for-seller",
+  (input: { seller_id: string }) => {
+    const seller = validateSellerStep({ seller_id: input.seller_id })
+
+    // Additional steps: create product, link to seller, etc.
+
+    return new WorkflowResponse({ seller })
+  }
+)
+```
+
+## Design principles
+
+**Modular over monolithic** — Each marketplace feature is a separate module that can be installed, modified, or replaced independently. You don't need to use all of Mercur to benefit from it.
+
+**Explicit over implicit** — Relationships between modules are defined through links, not hidden in service code. Workflows make multi-step operations visible and debuggable. API routes are file-based and predictable.
+
+**Extensible over configurable** — Rather than exposing hundreds of configuration options, Mercur provides extension points. Workflows have hooks. Providers are pluggable. Models can be extended through Medusa's framework. When configuration isn't enough, you modify the source code directly.
+
+**Commerce-aware** — Mercur doesn't reinvent commerce. It delegates products, pricing, orders, payments, and fulfillment to Medusa, and focuses exclusively on the marketplace logic that multi-vendor systems need.

package/content/learn/attributes.mdx

@@ -0,0 +1,89 @@
+---
+title: "Product Attributes"
+description: "Typed, filterable product attributes on top of Medusa's native product options — including variant axes shared across the catalog."
+---
+
+Product attributes extend the master catalog with structured, typed data — "Material: Cotton", "Weight: 10kg", "Waterproof: yes". The operator defines the attribute catalog; products reference it. Attributes power filtering, enforce consistent values across sellers, and — for select attributes — can drive variant generation.
+
+## Attribute types
+
+| Type | Values | Example |
+|------|--------|---------|
+| `multi_select` | Multiple values from a defined list | Color: Red, Blue, Green |
+| `single_select` | One value from a defined list | Condition: New |
+| `text` | Free text | Care instructions |
+| `unit` | A measured value | Weight: 10kg |
+| `toggle` | Boolean — fixed `true` / `false` values | Waterproof |
+
+## Attribute fields
+
+| Field | Description |
+|-------|-------------|
+| `name` / `handle` | Display name and unique handle |
+| `type` | One of the types above |
+| `is_variant_axis` | Whether the attribute generates product variants — only allowed for `multi_select` |
+| `is_filterable` | Whether the attribute is exposed as a storefront filter |
+| `is_required` | Whether products must set a value |
+| `rank` | Ordering in listings and forms |
+| `is_active` | Soft enable/disable |
+| `product_id` | `null` for global attributes; set when the attribute is product-scoped |
+
+Each select attribute owns a ranked list of **values** (`ProductAttributeValue`), managed by the operator in the Admin Panel.
+
+## Global vs product-scoped
+
+- **Global attributes** (`product_id = null`) live in the marketplace-wide catalog. They can be attached to any product and linked to categories, so the right attributes surface for the right product types.
+- **Product-scoped attributes** are created inline from a single product's form — a one-off axis or field that doesn't belong in the shared catalog. They don't appear in the global attribute list.
+
+## Variant axes and native product options
+
+Attributes marked `is_variant_axis` are not a parallel system — **a variant-axis attribute is backed by a native Medusa global product option**. The attribute and its values mirror one-to-one onto a `ProductOption` and its option values:
+
+- A **global** axis attribute maps to a shared product option that many products link to, each restricted to its selected subset of values.
+- A **product-scoped** axis attribute maps to an exclusive, product-owned option.
+
+Because axes are real product options, variants are built with Medusa's standard machinery — `variants[].options` maps axis titles to value names, exactly as in a plain Medusa project. Non-axis attributes never become options; they attach as plain value links.
+
+Only `multi_select` attributes can be variant axes — an axis needs an enumerable set of values to combine into variants.
+
+## Attaching attributes to products
+
+Products manage their attributes through a single **batch** endpoint that adds, removes, and updates in one request:
+
+```bash
+curl -X POST "http://localhost:9000/vendor/products/prod_123/attributes/batch" \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "add": [
+      { "id": "pattr_material", "value_ids": ["pattrval_cotton"] },
+      { "title": "Fit", "values": ["Slim", "Regular"], "is_variant_axis": true }
+    ],
+    "remove": ["pattr_old"]
+  }'
+```
+
+An entry either references an **existing** attribute by `id` (with the selected `value_ids`, or a `value` for text/unit/toggle types) or defines an **inline** one by `title` — created product-scoped on the fly.
+
+At product create time, the same shape is passed as a unified `attributes[]` array.
+
+## Who manages what
+
+| Surface | Capability |
+|---------|-----------|
+| Admin Panel | Owns the attribute catalog — create attributes, manage possible values, set ranking, edit flags |
+| Vendor Portal | Consumes attributes on products — select values, propose inline attributes as part of product submissions |
+| Store API | Reads attributes for display and filtering |
+
+Attribute changes on products submitted by vendors flow through the same [change-request pipeline](/rc/learn/product-requests) as other product edits.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Products" href="/rc/learn/products">
+    The master catalog attributes describe.
+  </Card>
+  <Card title="Product Requests & Approvals" href="/rc/learn/product-requests">
+    How attribute edits are reviewed.
+  </Card>
+</CardGroup>

package/content/learn/blocks.mdx

@@ -0,0 +1,99 @@
+---
+title: "Blocks"
+description: "Self-contained pieces of marketplace functionality that get copied into your project as source code."
+---
+
+Blocks are the unit of distribution in Mercur. Each block is a self-contained feature — a reviews system, a wishlist, product import/export — that you install directly into your project. Unlike packages, blocks are copied as source code. You own every file and can modify anything.
+
+## Installing blocks
+
+```bash
+bunx @mercurjs/cli@rc add reviews
+bunx @mercurjs/cli@rc add wishlist product-import-export
+```
+
+The CLI fetches the block from the [registry](/rc/learn/registry), resolves dependencies, transforms imports to match your project's path aliases, and copies the files into the right directories.
+
+## What's inside a block
+
+A block can contain any combination of:
+
+| Type | What it is | Example |
+|------|-----------|---------|
+| **Modules** | Data models and business logic | Review model, wishlist service |
+| **Workflows** | Multi-step business processes | Create review, export products |
+| **API Routes** | HTTP endpoints | `GET /store/reviews`, `POST /vendor/products/import` |
+| **Links** | Relationships between modules | Product-review link, customer-wishlist link |
+| **Vendor extensions** | Vendor portal pages and components | Reviews list page, import drawer |
+| **Admin extensions** | Admin panel pages and components | Reviews moderation page |
+
+For example, the `reviews` block includes a module (data model + service), workflows (create/update/delete), API routes (store, vendor, admin), links (product-review, seller-review), and UI pages for both the vendor portal and admin panel.
+
+## Block structure
+
+Blocks follow a consistent directory convention:
+
+```
+reviews/
+├── modules/reviews/       # Data model, service, types
+├── workflows/review/      # Steps and workflow definitions
+├── links/                 # product-review, seller-review, etc.
+├── api/
+│   ├── admin/reviews/     # Admin API routes
+│   ├── vendor/reviews/    # Vendor API routes
+│   └── store/reviews/     # Store API routes
+├── vendor/pages/reviews/  # Vendor portal UI
+└── admin/pages/reviews/   # Admin panel UI
+```
+
+Files are placed into your project based on the aliases in your `blocks.json`:
+
+```json blocks.json
+{
+  "aliases": {
+    "api": "packages/api/src",
+    "vendor": "apps/vendor/src",
+    "admin": "apps/admin/src"
+  }
+}
+```
+
+## Post-installation
+
+After adding a block, the CLI shows setup instructions. Typically you need to:
+
+1. **Register the module** in `medusa-config.ts`
+2. **Add middlewares** to your `api/middlewares.ts`
+3. **Run migrations** with `bunx medusa db:generate` and `bunx medusa db:migrate`
+4. **Regenerate types** with `bunx @mercurjs/cli@rc codegen`
+
+## Updating blocks
+
+Check for changes against the registry:
+
+```bash
+bunx @mercurjs/cli@rc diff reviews
+```
+
+If there are updates you want, re-install with the overwrite flag:
+
+```bash
+bunx @mercurjs/cli@rc add reviews --overwrite
+```
+
+Since blocks are source code in your project, you control when and how updates are applied.
+
+## Available blocks
+
+Search the registry to see what's available:
+
+```bash
+bunx @mercurjs/cli@rc search
+bunx @mercurjs/cli@rc search --query wishlist
+```
+
+View details about a specific block:
+
+```bash
+bunx @mercurjs/cli@rc view reviews
+```