@mercurjs/docs 2.2.0-rc.0 → 2.2.0-rc.2

package/content/resources/tutorials/customize-navigation.mdx

@@ -0,0 +1,110 @@
+---
+title: "Customize navigation"
+description: "Reorder, hide, relabel, and re-parent built-in sidebar items with a single _navigation.ts file and defineNavigationConfig."
+---
+
+The built-in sidebar ships a fixed set of items — Orders, Products, Customers, and so on. To reshape them without replacing the whole sidebar, author one host-owned file: `src/_navigation.ts`. It reorders, hides, relabels, and re-parents **built-in** items, and it is the single source of truth for the sidebar's shape.
+
+<Info>
+  **When to use this vs. a `config` export.** New pages you add via [drop-in routes](/rc/resources/tutorials/custom-panel-page) place their own sidebar item through `defineRouteConfig({ label, rank, nested })`. `_navigation.ts` is for the items you *didn't* create — the built-in ones. The two layer cleanly: custom routes place themselves; `_navigation.ts` reshapes the built-ins.
+</Info>
+
+## What you'll build
+
+A vendor sidebar with Orders pinned to the top, Price Lists hidden, and Campaigns moved under Orders.
+
+## Register the typed targets (once)
+
+Nav item ids are typed and generated per panel. Register them once with a single ambient reference in your app's `src` (already shipped by `create-mercur-app`):
+
+```typescript apps/vendor/src/extension-targets.d.ts
+/// <reference types="@mercurjs/vendor/extension-targets" />
+```
+
+With it present, `id` and `nested` autocomplete and an unknown id fails `tsc`.
+
+## Author the navigation file
+
+<Steps>
+  <Step title="Create src/_navigation.ts">
+    The file is host-owned and underscore-prefixed. Default-export a `defineNavigationConfig` with an `items` array of overrides:
+
+    ```ts apps/vendor/src/_navigation.ts
+    import { defineNavigationConfig } from "@mercurjs/dashboard-sdk"
+
+    export default defineNavigationConfig({
+      items: [
+        { id: "orders", rank: 0 },              // pin to the top
+        { id: "price-lists", hidden: true },    // hide from the sidebar
+        { id: "campaigns", nested: "orders" },  // re-parent under Orders
+      ],
+    })
+    ```
+  </Step>
+  <Step title="Know the override fields">
+    Each entry targets one built-in item by its stable `id`:
+
+    | Field | Type | Effect |
+    |-------|------|--------|
+    | `id` | `NavItemId` | **Required.** The built-in item to override (top-level or nested) |
+    | `rank` | `number` | Order within its parent (lower first) |
+    | `hidden` | `boolean` | Remove it from the sidebar |
+    | `label` | `string` | Relabel (i18n key or literal) |
+    | `icon` | `ComponentType` | Replace its icon |
+    | `nested` | `NavParentId \| null` | Re-parent under another top-level item; `null` promotes a nested item to top level |
+
+    Both `id` and `nested` are checked against the panel's generated `NavItemRegistry` / `NavParentRegistry`.
+  </Step>
+  <Step title="Reload the panel">
+    Open the vendor portal — Orders sits at the top, Price Lists is gone from the menu, and Campaigns now appears under Orders. The route for a hidden item stays reachable directly by URL unless you also remove it.
+  </Step>
+</Steps>
+
+## Common recipes
+
+```ts
+export default defineNavigationConfig({
+  items: [
+    { id: "payouts", label: "Settlements" },        // relabel
+    { id: "categories", nested: null, rank: 1 },    // promote a nested item to top level
+    { id: "collections", nested: "orders" },        // move a nested item under a different parent
+    { id: "inventory", hidden: true },              // hide a built-in
+  ],
+})
+```
+
+## Verify
+
+1. The top-level order reflects your `rank` values, with `orders` first.
+2. `price-lists` no longer appears in the sidebar.
+3. `campaigns` renders as a child under Orders.
+4. Set `id: "not-an-item"` — `bun run lint` (tsc) fails against `NavItemRegistry`.
+5. Delete `_navigation.ts` — the default sidebar returns.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="Can an installed block reorder the sidebar?">
+    No. Navigation is deliberately host-only — blocks can ship pages, widgets, and custom fields, but the sidebar order stays a single source of truth in your app's `_navigation.ts`.
+  </Accordion>
+  <Accordion title="What ids can I target?">
+    Any built-in item, top-level or nested, by its own id — e.g. `orders`, `products`, `categories`, `collections`, `campaigns`, `customer-groups`. Let your editor autocomplete `id:` against `NavItemId`; the full set is generated into your panel's `extension-targets.d.ts`.
+  </Accordion>
+  <Accordion title="Does this work in the admin panel too?">
+    Yes — drop `src/_navigation.ts` in the admin app and reference `@mercurjs/admin/extension-targets`. Each panel ships its own nav id set.
+  </Accordion>
+  <Accordion title="How do I add a brand-new sidebar item?">
+    That's a [drop-in route](/rc/resources/tutorials/custom-panel-page) with a `config` export — `_navigation.ts` only reshapes built-in items, it doesn't create routes.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Add a custom panel page" href="/rc/resources/tutorials/custom-panel-page">
+    Add a new screen with its own sidebar item.
+  </Card>
+  <Card title="Add a widget" href="/rc/resources/tutorials/add-a-widget">
+    Inject a component into a built-in page.
+  </Card>
+</CardGroup>

package/content/resources/tutorials/extend-forms-and-tables.mdx

@@ -0,0 +1,188 @@
+---
+title: "Extend forms and tables"
+description: "Add validated fields to built-in forms, replace fields in detail sections, and add list columns with defineCustomFieldsConfig and createFormHelper."
+---
+
+`defineCustomFieldsConfig` is Mercur's model-scoped extension surface: from one file per model, you add validated fields to built-in create/edit forms, replace/remove/add fields in detail sections, and add columns to the list table — all wired into the built-in page, all typed against the model's generated registry.
+
+<Info>
+  **UI, not schema.** This helper is a *panel* surface — it renders, validates, and displays fields. It does not create database columns. To *store* extra data, use the backend [Custom Fields module](/rc/resources/customization/custom-fields) or your own API route/workflow. In the MVP, panel custom fields for `product` are submitted under `additional_data` and persisted onto the product's `metadata`.
+</Info>
+
+## What you'll build
+
+An `ERP ID` field on the vendor product edit form, shown in the product's detail section and as a list-table column — from a single `src/custom-fields/product.tsx`.
+
+## Register the typed targets (once)
+
+Models, form zones, display zones, and built-in field ids are typed per panel. Register them once (shipped by `create-mercur-app`):
+
+```typescript apps/vendor/src/extension-targets.d.ts
+/// <reference types="@mercurjs/vendor/extension-targets" />
+```
+
+## Build the config
+
+<Steps>
+  <Step title="Create the model file">
+    Drop `src/custom-fields/<model>.tsx` and default-export a `defineCustomFieldsConfig`. `createFormHelper` (from `@mercurjs/dashboard-shared`) turns a Zod schema into an input type + validation:
+
+    ```tsx apps/vendor/src/custom-fields/product.tsx
+    import { defineCustomFieldsConfig } from "@mercurjs/dashboard-sdk"
+    import { createFormHelper } from "@mercurjs/dashboard-shared"
+
+    type ProductWithMeta = { metadata?: Record<string, unknown> }
+    const form = createFormHelper<ProductWithMeta>()
+
+    export default defineCustomFieldsConfig({
+      model: "product",
+      forms: [
+        {
+          zone: "edit",
+          fields: {
+            erp_id: form.define({
+              validation: form.string().optional(),
+              label: "ERP ID",
+              description: "External system identifier",
+              placeholder: "ERP-000",
+              defaultValue: (data) => (data?.metadata?.erp_id as string) ?? "",
+            }),
+          },
+        },
+      ],
+    })
+    ```
+  </Step>
+  <Step title="Add a detail-section display">
+    `displays[]` targets a detail-page section by its `zone` id. Keyed by field `id`, an entry **adds**, **replaces**, or **removes** a field:
+
+    ```tsx
+    import { Text } from "@medusajs/ui"
+
+    // ...inside defineCustomFieldsConfig:
+    displays: [
+      {
+        zone: "general",
+        fields: [
+          // ADD — an unknown id appends a new read-only row
+          {
+            id: "erp_id",
+            component: ({ data }) => (
+              <Text size="small" className="text-ui-fg-subtle px-6 py-4">
+                ERP ID: {String(data?.metadata?.erp_id ?? "-")}
+              </Text>
+            ),
+          },
+          // REMOVE — a built-in id + null hides the field
+          { id: "subtitle", component: null },
+          // REPLACE — a built-in id + component overrides its render
+          {
+            id: "handle",
+            component: ({ data }) => (
+              <Text size="small" className="text-ui-fg-subtle px-6 py-4">
+                /{(data as { handle?: string })?.handle}
+              </Text>
+            ),
+          },
+        ],
+      },
+    ],
+    ```
+
+    Built-in field ids (like `subtitle`, `handle`, `status`, `title`) autocomplete from the panel's generated `CustomFieldsRegistry`; an unknown id is treated as an added row.
+  </Step>
+  <Step title="Add a list column">
+    The `list` block extends the model's list table — add or override columns by id, hide built-in columns, and reorder:
+
+    ```tsx
+    // ...inside defineCustomFieldsConfig:
+    list: {
+      columns: [
+        {
+          id: "erp_id",
+          header: "ERP",
+          component: ({ row }) => String(row.metadata?.erp_id ?? "-"),
+        },
+      ],
+      viewDefaults: {
+        columnVisibility: { collection: false }, // hide a built-in column
+        columnOrder: ["product", "erp_id", "status"], // reorder
+      },
+    },
+    ```
+  </Step>
+  <Step title="Reload the panel">
+    Open the vendor portal. The product **edit** drawer shows the ERP ID field (validated on submit and persisted via `additional_data`), the detail **general** section shows the ERP ID row (with `subtitle` removed and `handle` re-rendered), and the product **list** shows the ERP column.
+  </Step>
+</Steps>
+
+## The `createFormHelper` surface
+
+`createFormHelper<T>()` exposes a Zod-based surface that drives both the input type and its validation:
+
+```ts
+const form = createFormHelper<T>()
+
+form.define({
+  validation: form.string().min(1),   // string | number | boolean | date | array | object | null | nullable | coerce
+  label: "…",
+  description: "…",
+  placeholder: "…",
+  defaultValue: "" | ((data) => /* derive from the entity */),
+  component,                            // optional custom render component
+})
+```
+
+Fields render through the standard `Form.Field → Form.Item` chain (never a raw `Controller`) and participate in the existing `TabbedForm` / `RouteDrawer` submit and validation flow.
+
+## Linked-module data
+
+To read data from a linked module alongside the entity, declare it with `link`; those relations are fetched with the entity and become available to columns and displays:
+
+```ts
+export default defineCustomFieldsConfig({
+  model: "product",
+  link: "brand", // or ["brand", "warranty"]
+  list: {
+    columns: [{ id: "brand_name", header: "Brand", component: ({ row }) => row.brand?.name }],
+  },
+})
+```
+
+The SDK derives the fetch query from `link` and merges it into the built-in query with the `+`/`-` convention — you never hand-write the field list.
+
+## Verify
+
+1. The ERP ID field renders in the product edit drawer and validates on submit.
+2. Saving persists the value (visible on reload) via `additional_data` → `metadata`.
+3. The detail general section shows the ERP row, hides `subtitle`, and re-renders `handle`.
+4. The product list shows the ERP column, hides `collection`, and reorders columns.
+5. Set `zone: "nope"` in `forms` — `bun run lint` (tsc) fails against the model's registry.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="Which models and zones are available?">
+    Today: the `product` model in the vendor portal, with form zone `edit` and display zone `general`. The valid set per panel is generated into `CustomFieldsRegistry` in `extension-targets.d.ts` — autocomplete `model` / `zone` to see what's mounted.
+  </Accordion>
+  <Accordion title="Where is the value actually stored?">
+    In the MVP, product custom fields are submitted under `additional_data` and persisted onto `product.metadata`. `defineCustomFieldsConfig` itself doesn't create a column — for durable, queryable storage model it with the backend [Custom Fields module](/rc/resources/customization/custom-fields) or a custom route/workflow.
+  </Accordion>
+  <Accordion title="Can I extend the onboarding wizard?">
+    That's the same helper with `zone: "onboarding"` and `tab` set to a wizard step id (vendor only). It's designed but not mounted in the current MVP — the runtime host exists; the wizard mount is a follow-up.
+  </Accordion>
+  <Accordion title="Can a block ship custom fields?">
+    Yes — a [block](/rc/learn/blocks) can include `src/custom-fields/` files in its `vendor_ui` / `admin_ui` entry, aggregated like the host app's.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Custom Fields module" href="/rc/resources/customization/custom-fields">
+    Persist extra data on an entity with a generated side table.
+  </Card>
+  <Card title="Add a widget" href="/rc/resources/tutorials/add-a-widget">
+    Inject a component at a built-in zone.
+  </Card>
+</CardGroup>

package/content/resources/tutorials/extend-onboarding.mdx

@@ -0,0 +1,253 @@
+---
+title: "Extend the onboarding flow"
+description: "Add a field to the vendor store-setup surface, submit it through additional_data, and persist it durably from a workflow hook — end to end, without forking."
+---
+
+The vendor **store-setup / onboarding** surface is a widget zone (`seller.setup`) that renders the full `seller` object as its `data`. That makes onboarding a full extension seam: drop a widget to add UI, carry the new value to the API on the built-in seller routes through `additional_data`, and persist it from a workflow hook — the same three layers you'd wire in plain Medusa, kept intact by Mercur.
+
+<Info>
+  **Three layers, one flow.** The panel (a `seller.setup` widget) *renders and collects*. The vendor seller route *carries* the value through `additional_data` — no core schema change. A `sellersUpdated` workflow hook *persists* it. Each layer is additive: nothing built-in is replaced.
+</Info>
+
+## What you'll build
+
+A "Tax ID" prompt on the vendor store-setup surface. The vendor types a VAT number; it rides `additional_data` to `POST /vendor/sellers/:id`, and a workflow hook stores it durably through the [Custom Fields module](/rc/resources/customization/custom-fields).
+
+## Register the typed targets (once)
+
+Widget zones are typed ids the vendor panel generates from its own pages and ships as `@mercurjs/vendor/extension-targets`. Register them once (shipped by `create-mercur-app`):
+
+```typescript apps/vendor/src/extension-targets.d.ts
+/// <reference types="@mercurjs/vendor/extension-targets" />
+```
+
+With it present, `seller.setup` autocompletes and an invalid zone fails `tsc` instead of silently doing nothing.
+
+## 1 — Render on the onboarding surface
+
+<Steps>
+  <Step title="Add the store-setup widget">
+    Drop a file under `src/widgets/`. Export the component as the **default** and a `config` with `zone: "seller.setup.before"`. The zone hands your component the `seller` as `data`:
+
+    ```tsx apps/vendor/src/widgets/tax-id-setup.tsx
+    import "@mercurjs/vendor/extension-targets"
+    import { defineWidgetConfig } from "@mercurjs/dashboard-sdk"
+    import { SellerDTO } from "@mercurjs/types"
+    import { Container, Heading, Input, Button, Text, toast } from "@medusajs/ui"
+    import { useMutation } from "@tanstack/react-query"
+    import { useState } from "react"
+
+    import { client } from "../lib/client"
+
+    export const config = defineWidgetConfig({
+      zone: "seller.setup.before",
+    })
+
+    const TaxIdSetup = ({ data: seller }: { data?: SellerDTO }) => {
+      const [taxId, setTaxId] = useState("")
+
+      const { mutate, isPending } = useMutation({
+        mutationFn: () =>
+          client.vendor.sellers.$id.mutate({
+            $id: seller!.id,
+            // additional_data is accepted on every vendor seller route —
+            // it never touches the built-in seller columns.
+            additional_data: { tax_id: taxId },
+          }),
+        onSuccess: () => toast.success("Tax ID saved"),
+        onError: () => toast.error("Could not save Tax ID"),
+      })
+
+      if (!seller) {
+        return null
+      }
+
+      return (
+        <Container className="mb-2 flex items-end gap-x-3">
+          <div className="flex-1">
+            <Heading level="h2">Complete your tax details</Heading>
+            <Text size="small" className="text-ui-fg-subtle">
+              Add your VAT / Tax ID to finish store setup.
+            </Text>
+            <Input
+              className="mt-3"
+              placeholder="VAT-000000"
+              value={taxId}
+              onChange={(e) => setTaxId(e.target.value)}
+              data-testid="tax-id-setup-input"
+            />
+          </div>
+          <Button
+            size="small"
+            isLoading={isPending}
+            disabled={!taxId}
+            onClick={() => mutate()}
+            data-testid="tax-id-setup-save"
+          >
+            Save
+          </Button>
+        </Container>
+      )
+    }
+
+    export default TaxIdSetup
+    ```
+  </Step>
+  <Step title="Understand where it renders">
+    `seller.setup` is hosted in two places, both passing the same `seller` as `data`:
+
+    | Host | When it shows |
+    |------|---------------|
+    | The vendor shell (above the page outlet) | On top-level routes — the dashboard "home" onboarding banner |
+    | The store settings detail page | Always, above the store status banner |
+
+    A single widget file covers both. Multiple `seller.setup.before` / `.after` widgets stack in registration order.
+  </Step>
+</Steps>
+
+<Note>
+  **`client` is your app's typed SDK.** `create-mercur-app` ships `apps/vendor/src/lib/client.ts` — a `createClient<Routes>()` instance. `client.vendor.sellers.$id.mutate(...)` is the typed `POST /vendor/sellers/:id`, so the request and response types match the backend route.
+</Note>
+
+## 2 — Carry the value through `additional_data`
+
+You don't touch the seller route or its validator. Every vendor and admin seller route already wraps its body with `WithAdditionalData`, so an unknown `additional_data` object is accepted and forwarded into the workflow untouched:
+
+```ts packages/core/src/api/vendor/sellers/[id]/route.ts (built-in — for reference)
+const { additional_data, ...update } = req.validatedBody
+
+await updateSellersWorkflow(req.scope).run({
+  input: {
+    selector: { id: req.params.id },
+    update,
+    additional_data, // ← forwarded to the workflow's hooks
+  },
+})
+```
+
+That is the whole "wiring" step: your `{ tax_id }` payload arrives in the workflow as `additional_data` without a schema change.
+
+## 3 — Persist it from a workflow hook
+
+`updateSellersWorkflow` exposes a `sellersUpdated` hook that runs after the update with `{ sellers, additional_data }`. Subscribe to it in your Medusa app and persist the value.
+
+<Steps>
+  <Step title="Declare a durable field">
+    Register a `Seller` custom field so the value gets a real, queryable column (no migration to hand-write):
+
+    ```ts apps/api/medusa-config.ts
+    module.exports = defineConfig({
+      // ...
+      modules: [
+        {
+          resolve: "@mercurjs/core/modules/custom-fields",
+          options: {
+            customFields: {
+              Seller: {
+                tax_id: { type: "string", nullable: true },
+              },
+            },
+          },
+        },
+      ],
+    })
+    ```
+
+    ```bash
+    bunx medusa db:migrate
+    ```
+  </Step>
+  <Step title="Subscribe to the hook">
+    Drop a file under `src/workflows/` in your Medusa app. Medusa imports everything under `src/workflows` at boot, so registering the hook is just defining it. Read `additional_data`, upsert through the Custom Fields service:
+
+    ```ts apps/api/src/workflows/hooks/seller-tax-id.ts
+    import { updateSellersWorkflow } from "@mercurjs/core/workflows"
+    import { MercurModules } from "@mercurjs/types"
+
+    updateSellersWorkflow.hooks.sellersUpdated(
+      async ({ sellers, additional_data }, { container }) => {
+        const taxId = additional_data?.tax_id
+        if (typeof taxId !== "string") {
+          return
+        }
+
+        const customFields = container.resolve(MercurModules.CUSTOM_FIELDS)
+
+        await customFields.upsert(
+          "seller",
+          sellers.map((seller) => ({ id: seller.id, tax_id: taxId })),
+        )
+      },
+    )
+    ```
+
+    <Tip>
+      The hook fires for **every** seller update, not only your widget's — always guard on the field being present (`typeof taxId !== "string"`) so unrelated edits (name, address, status) pass through untouched.
+    </Tip>
+  </Step>
+  <Step title="Read it back">
+    The value is now linked to the seller and queryable through Medusa's remote query:
+
+    ```ts
+    const { data: [seller] } = await query.graph({
+      entity: "seller",
+      fields: ["id", "name", "custom_fields.tax_id"],
+      filters: { id: sellerId },
+    })
+    ```
+
+    Add `custom_fields.*` to the `/vendor/sellers/me` query config if you want the widget to reflect the saved value on reload.
+  </Step>
+</Steps>
+
+## How the layers connect
+
+```
+seller.setup widget  →  client.vendor.sellers.$id.mutate({ additional_data })
+        │
+        ▼
+POST /vendor/sellers/:id  →  updateSellersWorkflow({ update, additional_data })
+        │
+        ▼
+hook: sellersUpdated({ sellers, additional_data })  →  customFields.upsert("seller", …)
+        │
+        ▼
+seller.custom_fields.tax_id  (durable, queryable)
+```
+
+## Verify
+
+1. Open the vendor portal — the Tax ID prompt renders on the dashboard home and on **Settings → Store**.
+2. Enter a value and save — the mutation succeeds (`toast.success`) and hits `POST /vendor/sellers/:id`.
+3. `query.graph({ entity: "seller", fields: ["custom_fields.tax_id"] })` returns the saved value.
+4. Edit an unrelated field (store name) — the seller update still works and the guard skips the upsert.
+5. Set `zone: "not.a.zone"` on the widget — `bun run lint` (tsc) fails against `WidgetZoneId`.
+6. Delete the widget file — the prompt disappears; the seller route and hook are unaffected.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="Why additional_data instead of adding a body field?">
+    The seller routes' validators are core-owned. `additional_data` is the sanctioned escape hatch — every vendor and admin route wraps its body with `WithAdditionalData`, so you carry extra context to the workflow hooks without patching the request schema or forking the route.
+  </Accordion>
+  <Accordion title="Which seller workflows expose hooks?">
+    `updateSellersWorkflow` exposes `sellersUpdated`, and `createSellerAccountWorkflow` (the `POST /vendor/sellers` onboarding submit) exposes `sellerAccountCreated` — both carry `{ additional_data }`. Use `sellerAccountCreated` to capture data at first registration and `sellersUpdated` for later edits. See the [workflow references](/rc/references/workflows/seller/update-sellers).
+  </Accordion>
+  <Accordion title="Can I store it on the seller's metadata instead?">
+    Yes — for a quick, non-queryable value, resolve the seller module in the hook and write to `seller.metadata`. Reach for the [Custom Fields module](/rc/resources/customization/custom-fields) when you want a typed, queryable column, which is what most onboarding data (tax IDs, compliance flags) needs.
+  </Accordion>
+  <Accordion title="Does the hook run inside the request?">
+    Yes — workflow hooks run as steps of the workflow the route invokes, with the same compensation/rollback semantics. If your hook throws, the seller update rolls back. Keep slow or best-effort work (external syncs) in a subscriber on the emitted `seller.updated` event instead.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Extend a workflow" href="/rc/resources/customization/extend-a-workflow">
+    The full hook + compensation model for Mercur workflows.
+  </Card>
+  <Card title="Custom Fields module" href="/rc/resources/customization/custom-fields">
+    Durable, queryable storage for the data your hook writes.
+  </Card>
+</CardGroup>

package/content/resources/tutorials/import-export-products.mdx

@@ -6,7 +6,7 @@ description: "Install the product-import-export block and give vendors CSV impor
 Bulk catalog operations belong to vendors, not the operator — a seller migrating from another platform needs to bring hundreds of listings with them. The `product-import-export` block adds CSV import and export to the Vendor Portal: API routes, workflows built on Medusa's product CSV steps, and drawer UIs wired into the product list.
 
 <Info>
-  **This block is also a masterclass in Mercur's extension model.** It ships backend workflows and routes into your API package, and it overrides the vendor `/products` page by dropping a route file that [re-composes the built-in page's compound slots](/rc/resources/tutorials/recompose-a-page) — adding Import/Export buttons while keeping the stock table untouched. After installing, read its source; you own every file.
+  **This block is also a masterclass in Mercur's extension model.** It ships backend workflows and routes into your API package, and it adds Import/Export actions to the vendor products area through the panel extension surface. After installing, read its source; you own every file.
 </Info>
 
 ## What you'll build
@@ -87,8 +87,8 @@ A vendor product list with **Import** and **Export** header buttons, a working C
 ## Next steps
 
 <CardGroup cols={2}>
-  <Card title="Re-compose a built-in page" href="/rc/resources/tutorials/recompose-a-page">
-    The page-override technique this block uses, explained step by step.
+  <Card title="Add a widget" href="/rc/resources/tutorials/add-a-widget">
+    Inject a component at a built-in zone with `defineWidgetConfig`.
   </Card>
   <Card title="Build your own block" href="/rc/resources/tutorials/build-a-block">
     Package a feature like this one and publish it to your own registry.