Skip to content

The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.

docs: linear-task skill targets main instead of canary (#1176)

Viktor Holik5ace0c624a89
diff --git a/.claude/skills/admin-form-ui/SKILL.md b/.claude/skills/admin-form-ui/SKILL.md
deleted file mode 100644
index b2f873b56..000000000
--- a/.claude/skills/admin-form-ui/SKILL.md
+++ /dev/null
@@ -1,244 +0,0 @@
----
-name: admin-form-ui
-description: Enforce correct form UI patterns when creating or modifying forms in packages/admin. Use when writing form fields, edit drawers, create modals, or any form-based UI in the admin package. Covers Form.Field pattern, labels, errors, hints, grids, submit guards, drawer/modal structure.
----
-
-# Admin Form UI Patterns
-
-Use this skill when:
-- creating new form fields in the admin
-- building edit forms in RouteDrawer
-- building create forms in RouteFocusModal
-- adding fields to existing forms
-- reviewing form code for UI consistency
-
-**Not for**: creating tabbed wizard forms (use `admin-tab-ui`), creating pages/sections (use `admin-page-ui`).
-
-Before introducing new custom field wrappers, overlays, selectors, or interactive form primitives, first apply `medusa-ui-conformance`.
-
-Read next (as needed):
-- `references/form-field-patterns.md` — exact code examples for every field type
-- `references/drawer-modal-patterns.md` — RouteDrawer and RouteFocusModal form structure
-
-## Core Rule
-
-**NEVER** use raw `Controller` from react-hook-form or raw `Label` from `@medusajs/ui` in admin forms. Always use the `Form.*` compound components.
-
-## Form Field Pattern (mandatory)
-
-Every form field MUST follow this structure:
-
-```tsx
-<Form.Field
- control={form.control}
- name="field_name"
- render={({ field }) => (
- <Form.Item>
- <Form.Label>{t("scope.fields.field_name.label")}</Form.Label>
- <Form.Control>
- <Input {...field} />
- </Form.Control>
- <Form.ErrorMessage />
- </Form.Item>
- )}
-/>
-```
-
-## Hard Rules (DO NOT)
-
-1. Do NOT use raw `Controller` — always use `Form.Field` (wraps Controller with context).
-2. Do NOT use `<Label>` from `@medusajs/ui` — use `<Form.Label>` (supports `optional`, `tooltip`, accessibility).
-3. Do NOT manually render errors (`fieldState.error && <span>`) — use `<Form.ErrorMessage />` (auto-reads form state).
-4. Do NOT mark required fields with `*` in text — omit `optional` prop (absence = required). Use `<Form.Label optional>` for optional fields.
-5. Do NOT use hardcoded strings — use `t("...")` from `useTranslation()` for all user-visible text.
-6. Do NOT use custom `<div className="flex flex-col gap-y-2">` wrappers around fields — use `<Form.Item>` (renders `flex flex-col space-y-2`).
-7. Do NOT skip `data-testid` on form fields and buttons.
-8. Do NOT skip `<Form.ErrorMessage />` — include it even if you think validation won't fail.
-9. Do NOT use `window.confirm` — use `usePrompt()` for confirmations.
-10. Do NOT use raw `<form>` — use `<KeyboundForm>` for Ctrl/Cmd+Enter support.
-11. Do NOT skip `isPending` guard on submit — both button `isLoading` AND keyboard submit must check it.
-12. Do NOT hand-roll custom input components — ALWAYS check `packages/admin/src/components/inputs/` and the Field Types Reference table below FIRST. If a component exists (HandleInput, ChipInput, SwitchBox, etc.), use it. Never create a custom wrapper for something that already has a reusable component.
-13. Do NOT call `useRouteModal()` outside of `RouteDrawer` or `RouteFocusModal` — it requires the provider. Split into outer shell (RouteDrawer + data fetch) and inner form component (useRouteModal + form logic). See RouteDrawer Form Structure below.
-
-## Form.Label Features
-
-```tsx
-// Required field (default — no special markup needed)
-<Form.Label>{t("fields.title")}</Form.Label>
-
-// Optional field
-<Form.Label optional>{t("fields.subtitle")}</Form.Label>
-
-// With tooltip
-<Form.Label tooltip={t("fields.handle.tooltip")}>{t("fields.handle")}</Form.Label>
-
-// Optional + tooltip
-<Form.Label optional tooltip={t("fields.sku.tooltip")}>{t("fields.sku")}</Form.Label>
-```
-
-## Grid Layouts
-
-```tsx
-// 2-column grid
-<div className="grid grid-cols-1 gap-4 md:grid-cols-2">
- <Form.Field ... />
- <Form.Field ... />
-</div>
-
-// 3-column grid
-<div className="grid grid-cols-1 gap-4 md:grid-cols-3">
- <Form.Field ... />
- <Form.Field ... />
- <Form.Field ... />
-</div>
-
-// Label-left layout (label + hint in left column, field in right)
-<div className="grid grid-cols-1 gap-4 md:grid-cols-2">
- <div>
- <Form.Label optional>{t("fields.shipping_profile.label")}</Form.Label>
- <Form.Hint><Trans i18nKey="fields.shipping_profile.hint" /></Form.Hint>
- </div>
- <Form.Field control={form.control} name="shipping_profile_id" render={...} />
-</div>
-```
-
-## Form.Hint Usage
-
-```tsx
-// Below a label (inside Form.Item or standalone)
-<Form.Label optional>{t("fields.sales_channels.label")}</Form.Label>
-<Form.Hint><Trans i18nKey="fields.sales_channels.hint" /></Form.Hint>
-
-// In header with action button
-<div className="flex items-start justify-between gap-x-4">
- <div className="flex flex-col">
- <Form.Label>{t("fields.options.label")}</Form.Label>
- <Form.Hint>{t("fields.options.hint")}</Form.Hint>
- </div>
- <Button size="small" variant="secondary" type="button" onClick={handleAdd}>
- {t("actions.add")}
- </Button>
-</div>
-```
-
-## Submit Pattern
-
-```tsx
-const { mutateAsync, isPending } = useMutation()
-
-const handleSubmit = form.handleSubmit(async (data) => {
- // Guard for async dependencies
- if (isRegionsPending) return
-
- await mutateAsync(data, {
- onSuccess: () => {
- toast.success(t("scope.successToast"))
- handleSuccess() // from useRouteModal()
- },
- })
-})
-
-return (
- <KeyboundForm onSubmit={handleSubmit}>
- {/* ... form content ... */}
- <Button type="submit" isLoading={isPending}>
- {t("actions.save")}
- </Button>
- </KeyboundForm>
-)
-```
-
-## RouteDrawer Form Structure
-
-```tsx
-<RouteDrawer>
- <RouteDrawer.Header>
- <Heading>{t("scope.edit.header")}</Heading>
- </RouteDrawer.Header>
- <RouteDrawer.Form form={form}>
- <KeyboundForm onSubmit={handleSubmit}>
- <RouteDrawer.Body>
- {/* Form fields here */}
- </RouteDrawer.Body>
- <RouteDrawer.Footer>
- <div className="flex items-center justify-end gap-x-2">
- <RouteDrawer.Close asChild>
- <Button variant="secondary">{t("actions.cancel")}</Button>
- </RouteDrawer.Close>
- <Button type="submit" isLoading={isPending}>
- {t("actions.save")}
- </Button>
- </div>
- </RouteDrawer.Footer>
- </KeyboundForm>
- </RouteDrawer.Form>
-</RouteDrawer>
-```
-
-## RouteFocusModal Form Structure
-
-```tsx
-<RouteFocusModal>
- <RouteFocusModal.Form form={form}>
- <KeyboundForm onSubmit={handleSubmit} className="flex flex-1 flex-col overflow-hidden">
- <RouteFocusModal.Header />
- <RouteFocusModal.Body className="flex flex-1 flex-col items-center overflow-y-auto py-16">
- <div className="flex w-full max-w-[720px] flex-col gap-y-8">
- <div>
- <Heading>{t("scope.create.header")}</Heading>
- <Text size="small">{t("scope.create.hint")}</Text>
- </div>
- {/* Form fields (grids) */}
- </div>
- </RouteFocusModal.Body>
- <RouteFocusModal.Footer>
- <div className="flex items-center justify-end gap-x-2">
- <RouteFocusModal.Close asChild>
- <Button variant="secondary">{t("actions.cancel")}</Button>
- </RouteFocusModal.Close>
- <Button type="submit" isLoading={isPending}>
- {t("actions.create")}
- </Button>
- </div>
- </RouteFocusModal.Footer>
- </KeyboundForm>
- </RouteFocusModal.Form>
-</RouteFocusModal>
-```
-
-## Field Types Reference
-
-| Field Type | Component | Import |
-|------------|-----------|--------|
-| Text input | `<Input {...field} />` | `@medusajs/ui` |
-| Textarea | `<Textarea {...field} />` | `@medusajs/ui` |
-| Select/Combobox | `<Combobox {...field} options={...} />` | local |
-| Switch | `<SwitchBox control={form.control} name="..." label="..." description="..." />` | local |
-| Number | `<Input type="number" {...field} onChange={...} />` | `@medusajs/ui` |
-| Handle/Slug | `<HandleInput {...field} />` | local |
-| Chips (tags) | `<ChipInput {...field} variant="contrast" />` | local |
-| File upload | `<FileUpload />` | local |
-
-## Imports Checklist
-
-```tsx
-// Form components — from local form module
-import { Form } from "@components/common/form" // Form.Field, Form.Item, Form.Label, etc.
-import { KeyboundForm } from "@components/utilities/keybound-form"
-import { SwitchBox } from "@components/common/switch-box"
-import { HandleInput } from "@components/inputs/handle-input"
-
-// UI primitives — from @medusajs/ui
-import { Input, Textarea, Heading, Text, Button } from "@medusajs/ui"
-
-// Modal/drawer — from local route components
-import { RouteDrawer, useRouteModal } from "@components/modals"
-import { RouteFocusModal } from "@components/modals"
-
-// i18n
-import { useTranslation, Trans } from "react-i18next"
-
-// Hooks
-import { useForm } from "react-hook-form"
-import { zodResolver } from "@hookform/resolvers/zod"
-```
diff --git a/.claude/skills/admin-form-ui/references/drawer-modal-patterns.md b/.claude/skills/admin-form-ui/references/drawer-modal-patterns.md
deleted file mode 100644
index 61fa6a53a..000000000
--- a/.claude/skills/admin-form-ui/references/drawer-modal-patterns.md
+++ /dev/null
@@ -1,294 +0,0 @@
-# RouteDrawer & RouteFocusModal Form Patterns
-
-## RouteDrawer — Full Edit Form Example
-
-Based on: `pages/customers/customer-edit/`
-
-```tsx
-// customer-edit.tsx — outer wrapper
-export const CustomerEdit = () => {
- const { t } = useTranslation()
- const { id } = useParams()
- const { customer, isLoading, isError, error } = useCustomer(id!)
-
- if (isError) {
- throw error
- }
-
- return (
- <RouteDrawer>
- <RouteDrawer.Header>
- <Heading>{t("customers.edit.header")}</Heading>
- </RouteDrawer.Header>
- {!isLoading && customer && <EditCustomerForm customer={customer} />}
- </RouteDrawer>
- )
-}
-```
-
-```tsx
-// edit-customer-form.tsx — form component
-type EditCustomerFormProps = {
- customer: HttpTypes.AdminCustomer
-}
-
-const EditCustomerFormSchema = z.object({
- first_name: z.string().optional(),
- last_name: z.string().optional(),
- email: z.string().email(),
- phone: z.string().optional(),
- company_name: z.string().optional(),
-})
-
-export const EditCustomerForm = ({ customer }: EditCustomerFormProps) => {
- const { t } = useTranslation()
- const { handleSuccess } = useRouteModal()
-
- const form = useForm<z.infer<typeof EditCustomerFormSchema>>({
- defaultValues: {
- first_name: customer.first_name || "",
- last_name: customer.last_name || "",
- email: customer.email,
- phone: customer.phone || "",
- company_name: customer.company_name || "",
- },
- resolver: zodResolver(EditCustomerFormSchema),
- })
-
- const { mutateAsync, isPending } = useUpdateCustomer(customer.id)
-
- const handleSubmit = form.handleSubmit(async (data) => {
- await mutateAsync(data, {
- onSuccess: () => {
- toast.success(t("customers.edit.successToast"))
- handleSuccess()
- },
- })
- })
-
- return (
- <RouteDrawer.Form form={form}>
- <KeyboundForm
- onSubmit={handleSubmit}
- className="flex flex-1 flex-col overflow-hidden"
- >
- <RouteDrawer.Body className="flex flex-1 flex-col gap-y-8 overflow-y-auto">
- <div className="grid grid-cols-2 gap-4">
- <Form.Field
- control={form.control}
- name="first_name"
- render={({ field }) => (
- <Form.Item>
- <Form.Label optional>
- {t("fields.firstName")}
- </Form.Label>
- <Form.Control>
- <Input {...field} />
- </Form.Control>
- <Form.ErrorMessage />
- </Form.Item>
- )}
- />
- <Form.Field
- control={form.control}
- name="last_name"
- render={({ field }) => (
- <Form.Item>
- <Form.Label optional>
- {t("fields.lastName")}
- </Form.Label>
- <Form.Control>
- <Input {...field} />
- </Form.Control>
- <Form.ErrorMessage />
- </Form.Item>
- )}
- />
- </div>
- <Form.Field
- control={form.control}
- name="email"
- render={({ field }) => (
- <Form.Item>
- <Form.Label>{t("fields.email")}</Form.Label>
- <Form.Control>
- <Input {...field} />
- </Form.Control>
- <Form.ErrorMessage />
- </Form.Item>
- )}
- />
- </RouteDrawer.Body>
- <RouteDrawer.Footer>
- <div className="flex items-center justify-end gap-x-2">
- <RouteDrawer.Close asChild>
- <Button variant="secondary" size="small">
- {t("actions.cancel")}
- </Button>
- </RouteDrawer.Close>
- <Button
- type="submit"
- variant="primary"
- size="small"
- isLoading={isPending}
- >
- {t("actions.save")}
- </Button>
- </div>
- </RouteDrawer.Footer>
- </KeyboundForm>
- </RouteDrawer.Form>
- )
-}
-```
-
-## RouteFocusModal — Full Create Form Example
-
-Based on: `pages/customers/customer-create/`
-
-```tsx
-// customer-create.tsx — outer wrapper
-export const CustomerCreate = () => {
- return (
- <RouteFocusModal>
- <CreateCustomerForm />
- </RouteFocusModal>
- )
-}
-```
-
-```tsx
-// create-customer-form.tsx — form component
-export const CreateCustomerForm = () => {
- const { t } = useTranslation()
- const { handleSuccess } = useRouteModal()
-
- const form = useForm<z.infer<typeof CreateCustomerFormSchema>>({
- defaultValues: {
- email: "",
- first_name: "",
- last_name: "",
- phone: "",
- company_name: "",
- },
- resolver: zodResolver(CreateCustomerFormSchema),
- })
-
- const { mutateAsync, isPending } = useCreateCustomer()
-
- const handleSubmit = form.handleSubmit(async (data) => {
- await mutateAsync(data, {
- onSuccess: ({ customer }) => {
- toast.success(t("customers.create.successToast"))
- handleSuccess(`/customers/${customer.id}`)
- },
- })
- })
-
- return (
- <RouteFocusModal.Form form={form}>
- <KeyboundForm
- onSubmit={handleSubmit}
- className="flex flex-1 flex-col overflow-hidden"
- >
- <RouteFocusModal.Header />
- <RouteFocusModal.Body className="flex flex-1 flex-col items-center overflow-y-auto py-16">
- <div className="flex w-full max-w-[720px] flex-col gap-y-8">
- <div>
- <Heading>{t("customers.create.header")}</Heading>
- <Text size="small" className="text-ui-fg-subtle">
- {t("customers.create.hint")}
- </Text>
- </div>
- <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
- <Form.Field
- control={form.control}
- name="first_name"
- render={({ field }) => (
- <Form.Item>
- <Form.Label optional>{t("fields.firstName")}</Form.Label>
- <Form.Control>
- <Input {...field} />
- </Form.Control>
- <Form.ErrorMessage />
- </Form.Item>
- )}
- />
- {/* ... more fields ... */}
- </div>
- </div>
- </RouteFocusModal.Body>
- <RouteFocusModal.Footer>
- <div className="flex items-center justify-end gap-x-2">
- <RouteFocusModal.Close asChild>
- <Button variant="secondary" size="small">
- {t("actions.cancel")}
- </Button>
- </RouteFocusModal.Close>
- <Button
- type="submit"
- variant="primary"
- size="small"
- isLoading={isPending}
- >
- {t("actions.create")}
- </Button>
- </div>
- </RouteFocusModal.Footer>
- </KeyboundForm>
- </RouteFocusModal.Form>
- )
-}
-```
-
-## Key Differences: Drawer vs Modal
-
-| Aspect | RouteDrawer | RouteFocusModal |
-|--------|-------------|-----------------|
-| Use case | Edit existing resource | Create new resource |
-| Size | Side panel | Full-screen centered |
-| Header | `<Heading>` inside `RouteDrawer.Header` | Auto-generated `RouteFocusModal.Header />` |
-| Body | `RouteDrawer.Body` (direct fields) | `RouteFocusModal.Body` with centered `max-w-[720px]` layout |
-| Page heading | None (drawer header serves as title) | `<Heading>` + `<Text>` inside body |
-| Success | `handleSuccess()` (closes drawer) | `handleSuccess("/path/to/new")` (navigates) |
-| Save button text | `t("actions.save")` | `t("actions.create")` |
-
-## Footer Pattern (same for both)
-
-```tsx
-<div className="flex items-center justify-end gap-x-2">
- <XxxDrawerOrModal.Close asChild>
- <Button variant="secondary" size="small">
- {t("actions.cancel")}
- </Button>
- </XxxDrawerOrModal.Close>
- <Button
- type="submit"
- variant="primary"
- size="small"
- isLoading={isPending}
- >
- {t("actions.save")}
- </Button>
-</div>
-```
-
-## Form Setup Pattern
-
-```tsx
-const form = useForm<z.infer<typeof Schema>>({
- defaultValues: { ... },
- resolver: zodResolver(Schema),
-})
-
-const { mutateAsync, isPending } = useMutation(id)
-
-const handleSubmit = form.handleSubmit(async (data) => {
- await mutateAsync(data, {
- onSuccess: (response) => {
- toast.success(t("scope.successToast"))
- handleSuccess() // or handleSuccess(`/path/${response.id}`)
- },
- })
-})
-```
diff --git a/.claude/skills/admin-form-ui/references/form-field-patterns.md b/.claude/skills/admin-form-ui/references/form-field-patterns.md
deleted file mode 100644
index 0e05901f5..000000000
--- a/.claude/skills/admin-form-ui/references/form-field-patterns.md
+++ /dev/null
@@ -1,444 +0,0 @@
-# Form Field Patterns — Exact Code Examples
-
-## Standard Text Input
-
-```tsx
-<Form.Field
- control={form.control}
- name="title"
- render={({ field }) => (
- <Form.Item data-testid="product-create-title">
- <Form.Label data-testid="product-create-title-label">
- {t("products.fields.title.label")}
- </Form.Label>
- <Form.Control data-testid="product-create-title-control">
- <Input
- {...field}
- placeholder={t("products.fields.title.placeholder")}
- data-testid="product-create-title-input"
- />
- </Form.Control>
- <Form.ErrorMessage />
- </Form.Item>
- )}
-/>
-```
-
-## Optional Text Input with Tooltip
-
-```tsx
-<Form.Field
- control={form.control}
- name="handle"
- render={({ field }) => (
- <Form.Item>
- <Form.Label
- tooltip={t("products.fields.handle.tooltip")}
- optional
- >
- {t("fields.handle")}
- </Form.Label>
- <Form.Control>
- <HandleInput
- {...field}
- placeholder={t("products.fields.handle.placeholder")}
- />
- </Form.Control>
- <Form.ErrorMessage />
- </Form.Item>
- )}
-/>
-```
-
-## Textarea
-
-```tsx
-<Form.Field
- control={form.control}
- name="description"
- render={({ field }) => (
- <Form.Item>
- <Form.Label optional>
- {t("products.fields.description.label")}
- </Form.Label>
- <Form.Control>
- <Textarea
- {...field}
- placeholder={t("products.fields.description.placeholder")}
- />
- </Form.Control>
- <Form.ErrorMessage />
- </Form.Item>
- )}
-/>
-```
-
-## Combobox (Select with Search)
-
-```tsx
-<Form.Field
- control={form.control}
- name="type_id"
- render={({ field }) => (
- <Form.Item>
- <Form.Label optional>
- {t("products.fields.type.label")}
- </Form.Label>
- <Form.Control>
- <Combobox
- {...field}
- options={types.options}
- searchValue={types.searchValue}
- onSearchValueChange={types.onSearchValueChange}
- fetchNextPage={types.fetchNextPage}
- />
- </Form.Control>
- <Form.ErrorMessage />
- </Form.Item>
- )}
-/>
-```
-
-## SwitchBox (Toggle)
-
-```tsx
-<SwitchBox
- control={form.control}
- name="discountable"
- label={t("products.fields.discountable.label")}
- description={t("products.fields.discountable.hint")}
- optional
-/>
-```
-
-## Number Input
-
-```tsx
-<Form.Field
- control={form.control}
- name={`variants.${variantIndex}.inventory.${inventoryIndex}.required_quantity`}
- render={({ field: { onChange, value, ...field } }) => (
- <Form.Item>
- <Form.Control>
- <Input
- type="number"
- className="bg-ui-bg-field-component"
- min={0}
- value={value}
- onChange={(e) => {
- const value = e.target.value
- if (value === "") {
- onChange(null)
- } else {
- onChange(Number(value))
- }
- }}
- {...field}
- />
- </Form.Control>
- <Form.ErrorMessage />
- </Form.Item>
- )}
-/>
-```
-
-## ChipInput (Tags / Comma-Separated Values)
-
-```tsx
-<Controller
- control={form.control}
- name={`options.${index}.values`}
- render={({ field: { onChange, ...field } }) => (
- <ChipInput
- {...field}
- variant="contrast"
- onChange={(values) => onChange(values)}
- placeholder={t("products.fields.options.variantions.placeholder")}
- />
- )}
-/>
-```
-
-Note: ChipInput is an exception where raw `Controller` may be used because it's a specialized component that doesn't fit the `Form.Item` wrapper pattern.
-
-## Array Field with Add Button
-
-```tsx
-<Form.Field
- control={form.control}
- name="options"
- render={() => (
- <Form.Item>
- <div className="flex items-start justify-between gap-x-4">
- <div className="flex flex-col">
- <Form.Label>
- {t("products.create.variants.productOptions.label")}
- </Form.Label>
- <Form.Hint>
- {t("products.create.variants.productOptions.hint")}
- </Form.Hint>
- </div>
- <Button
- size="small"
- variant="secondary"
- type="button"
- onClick={handleAddOption}
- >
- {t("actions.add")}
- </Button>
- </div>
- <ul className="flex flex-col gap-y-4">
- {options.fields.map((option, index) => (
- <li
- key={option.id}
- className="bg-ui-bg-component shadow-elevation-card-rest rounded-xl p-3"
- >
- {/* Row content: input + delete button */}
- </li>
- ))}
- </ul>
- </Form.Item>
- )}
-/>
-```
-
-## ChipGroup (Selected Items Display)
-
-```tsx
-<Form.Field
- control={form.control}
- name="sales_channels"
- render={() => (
- <Form.Item>
- <div className="flex items-start justify-between gap-x-4">
- <div>
- <Form.Label optional>
- {t("products.fields.sales_channels.label")}
- </Form.Label>
- <Form.Hint>
- <Trans i18nKey="products.fields.sales_channels.hint" />
- </Form.Hint>
- </div>
- <StackedFocusModal.Trigger asChild>
- <Button size="small" variant="secondary" type="button">
- {t("actions.add")}
- </Button>
- </StackedFocusModal.Trigger>
- </div>
- <Form.Control className="mt-0">
- {fields.length > 0 && (
- <ChipGroup onClearAll={handleClearAll} onRemove={handleRemove} className="py-4">
- {fields.map((field, index) => (
- <ChipGroup.Chip key={field.key} index={index}>
- {field.name}
- </ChipGroup.Chip>
- ))}
- </ChipGroup>
- )}
- </Form.Control>
- </Form.Item>
- )}
-/>
-```
-
-## Inline Editable Row (Dynamic Array with Grid Layout)
-
-Used for inventory kits, variant options, price list items — any dynamic list where each row
-has multiple inline fields (label + input pairs) and a delete button.
-
-### Row Structure
-
-```tsx
-<li className="bg-ui-bg-component shadow-elevation-card-rest grid grid-cols-[1fr_28px] items-center gap-1.5 rounded-xl p-1.5">
- {/* Left: field pairs in horizontal grid */}
- <div className="grid grid-cols-[min-content,1fr] items-center gap-1.5">
- {/* Label + Input pair 1 */}
- <div className="flex items-center px-2 py-1.5">
- <Label size="xsmall" weight="plus" className="text-ui-fg-subtle">
- {t("fields.item")}
- </Label>
- </div>
- <Form.Field
- control={form.control}
- name={`variants.${variantIndex}.inventory.${inventoryIndex}.inventory_item_id`}
- render={({ field }) => (
- <Form.Item>
- <Form.Control>
- <Combobox
- {...field}
- options={items.options}
- className="bg-ui-bg-field-component hover:bg-ui-bg-field-component-hover"
- placeholder={t("scope.itemPlaceholder")}
- />
- </Form.Control>
- </Form.Item>
- )}
- />
-
- {/* Label + Input pair 2 */}
- <div className="flex items-center px-2 py-1.5">
- <Label size="xsmall" weight="plus" className="text-ui-fg-subtle">
- {t("fields.quantity")}
- </Label>
- </div>
- <Form.Field
- control={form.control}
- name={`variants.${variantIndex}.inventory.${inventoryIndex}.required_quantity`}
- render={({ field: { onChange, value, ...field } }) => (
- <Form.Item>
- <Form.Control>
- <Input
- type="number"
- className="bg-ui-bg-field-component"
- min={0}
- value={value}
- onChange={(e) => {
- const value = e.target.value
- if (value === "") {
- onChange(null)
- } else {
- onChange(Number(value))
- }
- }}
- {...field}
- />
- </Form.Control>
- <Form.ErrorMessage />
- </Form.Item>
- )}
- />
- </div>
-
- {/* Right: delete button (28px column) */}
- <IconButton
- type="button"
- size="small"
- variant="transparent"
- className="text-ui-fg-muted"
- onClick={onRemove}
- >
- <XMarkMini />
- </IconButton>
-</li>
-```
-
-### Key layout classes:
-- Outer: `grid grid-cols-[1fr_28px]` — content + delete button
-- Inner: `grid grid-cols-[min-content,1fr]` — label + input pairs
-- Card: `bg-ui-bg-component shadow-elevation-card-rest rounded-xl p-1.5`
-- Labels: `Label size="xsmall" weight="plus" className="text-ui-fg-subtle"` (NOT Form.Label — inline rows use raw Label for compact sizing)
-- Inputs: `className="bg-ui-bg-field-component"` for contrast background
-- Delete: `IconButton size="small" variant="transparent"` with `XMarkMini`
-
-### Section Wrapper with useFieldArray
-
-```tsx
-function SectionWithDynamicRows({ parentIndex }: { parentIndex: number }) {
- const form = useTabbedForm<SchemaType>()
- const { t } = useTranslation()
-
- const items = useFieldArray({
- control: form.control,
- name: `parent.${parentIndex}.items`,
- })
-
- return (
- <div className="grid gap-y-4">
- {/* Header with label + Add button */}
- <div className="flex items-start justify-between gap-x-4">
- <div className="flex flex-col">
- <Form.Label>{t("scope.section.label")}</Form.Label>
- <Form.Hint>{t("scope.section.hint")}</Form.Hint>
- </div>
- <Button
- size="small"
- variant="secondary"
- type="button"
- onClick={() => items.append({ field_a: "", field_b: "" })}
- >
- {t("actions.add")}
- </Button>
- </div>
-
- {/* Dynamic rows */}
- {items.fields.map((item, index) => (
- <InlineEditableRow
- key={item.id}
- parentIndex={parentIndex}
- itemIndex={index}
- onRemove={() => items.remove(index)}
- />
- ))}
- </div>
- )
-}
-```
-
-### Duplicate Prevention Pattern
-
-```tsx
-const formData = useWatch({
- control: form.control,
- name: `parent.${parentIndex}.items`,
-})
-
-const isOptionDisabled = (option: { value: string }, currentIndex: number) => {
- return !!formData?.some(
- (item, i) => i !== currentIndex && item.field_id === option.value
- )
-}
-```
-
-## WRONG vs RIGHT Comparison
-
-### Field Label
-```tsx
-// WRONG — raw Label, asterisk in text
-<Label htmlFor="seo-title">SEO Title *</Label>
-
-// RIGHT — Form.Label, optional prop for optional fields
-<Form.Label>{t("products.fields.seo_title.label")}</Form.Label>
-<Form.Label optional>{t("products.fields.seo_title.label")}</Form.Label>
-```
-
-### Error Display
-```tsx
-// WRONG — manual error rendering
-{fieldState.error && (
- <span className="text-ui-fg-error text-small">
- {fieldState.error.message}
- </span>
-)}
-
-// RIGHT — auto error component
-<Form.ErrorMessage />
-```
-
-### Field Wrapper
-```tsx
-// WRONG — manual div wrapper
-<div className="flex flex-col gap-y-2">
- <Label>...</Label>
- <Input />
-</div>
-
-// RIGHT — Form.Item
-<Form.Item>
- <Form.Label>...</Form.Label>
- <Form.Control>
- <Input />
- </Form.Control>
- <Form.ErrorMessage />
-</Form.Item>
-```
-
-### Strings
-```tsx
-// WRONG — hardcoded
-<Form.Label>SEO Title</Form.Label>
-<Input placeholder="Enter SEO title..." />
-
-// RIGHT — i18n
-<Form.Label>{t("products.fields.seo_title.label")}</Form.Label>
-<Input placeholder={t("products.fields.seo_title.placeholder")} />
-```
diff --git a/.claude/skills/admin-page-ui/SKILL.md b/.claude/skills/admin-page-ui/SKILL.md
deleted file mode 100644
index 4e4142ec2..000000000
--- a/.claude/skills/admin-page-ui/SKILL.md
+++ /dev/null
@@ -1,306 +0,0 @@
----
-name: admin-page-ui
-description: Enforce correct page and section UI patterns when creating or modifying admin pages. Use when building list pages, detail pages, Container sections, action menus, empty states, delete flows, or any page-level UI in packages/admin.
----
-
-# Admin Page UI Patterns
-
-Use this skill when:
-- creating a new list page (table with filters, search, pagination)
-- creating a new detail page (two-column layout with sections)
-- building Container sections (cards with headers, actions, data rows)
-- adding action menus (edit, delete dropdowns)
-- implementing empty states
-- implementing delete confirmation flows
-- adding status badges
-
-**Not for**: form fields inside pages (use `admin-form-ui`), tabbed wizard forms (use `admin-tab-ui`).
-
-Before building new custom UI, first apply `medusa-ui-conformance`.
-
-Read next (as needed):
-- `references/list-page-patterns.md` — list page compound component structure
-- `references/detail-page-patterns.md` — detail page sections, Container cards, SectionRow
-
-## Hard Rules (DO NOT)
-
-1. Do NOT use hardcoded strings — use `t("...")` from `useTranslation()`.
-2. Do NOT use `window.confirm` or `window.alert` — use `usePrompt()` for delete confirmations.
-3. Do NOT create context/provider for detail pages — Root fetches data, passes as props to sections.
-4. Do NOT create a separate `Layout` wrapper — inline `TwoColumnPage` directly in Root.
-5. Do NOT use render props (`header={<Custom />}`) — use nested compound components with `Children.count`.
-6. Do NOT use `Heading level="h1"` in sections — h1 is for page title only, h2 for sections.
-7. Do NOT skip `data-testid` on key elements.
-8. Do NOT build custom dropdown menus — use `ActionMenu` component.
-9. Do NOT build custom empty states — use `NoRecords` / `NoResults` components.
-10. Do NOT skip error boundaries — wrap data fetching pages with `isError` + `throw error`.
-
-## Page Types
-
-### List Page
-
-```
-SingleColumnPage
- └─ Table (compound)
- ├─ Header
- │ ├─ Title (Heading)
- │ └─ Actions
- │ └─ CreateButton (Link + Button)
- └─ DataTable (_DataTable with filters, search, pagination)
-```
-
-### Detail Page
-
-```
-TwoColumnPage
- ├─ Main (first child)
- │ ├─ MainGeneralSection (Container card)
- │ ├─ MainMediaSection
- │ └─ MainVariantSection
- └─ Sidebar (second child)
- ├─ SidebarOrganizationSection
- └─ SidebarSellerSection
-```
-
-## Container Section Pattern (Detail Page Cards)
-
-```tsx
-<Container className="divide-y p-0">
- {/* Header row */}
- <div className="flex items-center justify-between px-6 py-4">
- <Heading level="h2">{t("scope.section.title")}</Heading>
- <div className="flex items-center gap-x-2">
- <StatusBadge color={statusColor}>
- {t(`scope.status.${status}`)}
- </StatusBadge>
- <ActionMenu
- groups={[
- {
- actions: [
- {
- label: t("actions.edit"),
- icon: <PencilSquare />,
- to: "edit",
- },
- ],
- },
- {
- actions: [
- {
- label: t("actions.delete"),
- icon: <Trash />,
- onClick: handleDelete,
- },
- ],
- },
- ]}
- />
- </div>
- </div>
-
- {/* Data rows */}
- <SectionRow title={t("fields.name")} value={data.name || "-"} />
- <SectionRow title={t("fields.email")} value={data.email || "-"} />
- <SectionRow title={t("fields.phone")} value={data.phone || "-"} />
-</Container>
-```
-
-## ActionMenu Pattern
-
-```tsx
-import { ActionMenu } from "@components/common/action-menu"
-import { PencilSquare, Trash } from "@medusajs/icons"
-
-<ActionMenu
- groups={[
- {
- actions: [
- {
- icon: <PencilSquare />,
- label: t("actions.edit"),
- to: `/resource/${id}/edit`, // navigation
- },
- ],
- },
- {
- actions: [
- {
- icon: <Trash />,
- label: t("actions.delete"),
- onClick: handleDelete, // callback
- },
- ],
- },
- ]}
-/>
-```
-
-**Action type**: either `to` (navigation link) or `onClick` (callback), never both.
-**Groups**: separate edit actions from destructive actions with different groups.
-
-## Delete Confirmation Pattern
-
-```tsx
-import { usePrompt } from "@medusajs/ui"
-
-const prompt = usePrompt()
-
-const handleDelete = async () => {
- const res = await prompt({
- title: t("scope.delete.title"),
- description: t("scope.delete.description", { name: item.name }),
- verificationInstruction: t("general.typeToConfirm"),
- verificationText: item.name,
- confirmText: t("actions.delete"),
- cancelText: t("actions.cancel"),
- })
-
- if (!res) return
-
- await mutateAsync(undefined, {
- onSuccess: () => {
- toast.success(t("scope.delete.successToast"))
- navigate("/resource-list", { replace: true })
- },
- })
-}
-```
-
-## Empty State Patterns
-
-### NoRecords (table completely empty)
-```tsx
-<_DataTable
- table={table}
- columns={columns}
- noRecords={{
- message: t("scope.list.noRecordsMessage"),
- }}
-/>
-```
-
-### NoRecords (section with no data)
-```tsx
-import { NoRecords } from "@components/common/empty-table-content"
-
-{items.length === 0 && (
- <NoRecords
- className="flex h-full flex-col overflow-hidden border-t p-6"
- icon={null}
- title={t("general.noRecordsTitle")}
- message={t("general.noRecordsMessage")}
- />
-)}
-```
-
-## StatusBadge Pattern
-
-```tsx
-import { StatusBadge } from "@medusajs/ui"
-
-// Color helper function
-const productStatusColor = (status: string): "green" | "orange" | "red" | "grey" => {
- switch (status) {
- case "published": return "green"
- case "draft": return "orange"
- case "rejected": return "red"
- default: return "grey"
- }
-}
-
-<StatusBadge color={productStatusColor(product.status)}>
- {t(`products.productStatus.${product.status}`)}
-</StatusBadge>
-```
-
-## Typography Rules
-
-| Element | Component | Level | Where |
-|---------|-----------|-------|-------|
-| Page title | `<Heading>` | (default) | Page root / modal body |
-| Section title | `<Heading level="h2">` | h2 | Inside Container header |
-| Drawer title | `<Heading>` | (default) | RouteDrawer.Header |
-| Description | `<Text size="small">` | — | Below heading |
-| Subtle text | `<Text size="small" className="text-ui-fg-subtle">` | — | Hints, descriptions |
-
-## Data Loading Pattern
-
-```tsx
-const Root = () => {
- const { id } = useParams()
- const { data, isPending, isError, error } = useQuery(id!)
-
- if (isError) {
- throw error
- }
-
- const ready = !isPending && !!data
-
- return ready ? (
- <TwoColumnPage hasOutlet showJSON showMetadata data={data}>
- <TwoColumnPage.Main>
- <MainGeneralSection data={data} />
- </TwoColumnPage.Main>
- <TwoColumnPage.Sidebar>
- <SidebarInfoSection data={data} />
- </TwoColumnPage.Sidebar>
- </TwoColumnPage>
- ) : (
- <TwoColumnPageSkeleton mainSections={2} sidebarSections={1} />
- )
-}
-```
-
-## Compound Component Structure (List Page)
-
-```tsx
-const Root = ({ children }: { children?: ReactNode }) => {
- return (
- <SingleColumnPage>
- {Children.count(children) > 0 ? children : <ResourceListTable />}
- </SingleColumnPage>
- )
-}
-
-export const ResourceListPage = Object.assign(Root, {
- Table: ResourceListTable,
- Header: ResourceListHeader,
- HeaderTitle: ResourceListTitle,
- HeaderActions: ResourceListActions,
- HeaderCreateButton: ResourceListCreateButton,
- DataTable: ResourceListDataTable,
-})
-```
-
-## Compound Component Structure (Detail Page)
-
-```tsx
-const Root = ({ children }: { children?: ReactNode }) => {
- const { id } = useParams()
- const { data, isPending, isError, error } = useQuery(id!)
-
- if (isError) throw error
- const ready = !isPending && !!data
- if (!ready) return <TwoColumnPageSkeleton ... />
-
- return (
- <TwoColumnPage hasOutlet showJSON showMetadata data={data}>
- {Children.count(children) > 0 ? children : (
- <>
- <TwoColumnPage.Main>
- <MainGeneralSection data={data} />
- </TwoColumnPage.Main>
- <TwoColumnPage.Sidebar>
- <SidebarInfoSection data={data} />
- </TwoColumnPage.Sidebar>
- </>
- )}
- </TwoColumnPage>
- )
-}
-
-export const ResourceDetailPage = Object.assign(Root, {
- MainGeneralSection,
- SidebarInfoSection,
-})
-```
diff --git a/.claude/skills/admin-tab-ui/SKILL.md b/.claude/skills/admin-tab-ui/SKILL.md
deleted file mode 100644
index 658e590db..000000000
--- a/.claude/skills/admin-tab-ui/SKILL.md
+++ /dev/null
@@ -1,294 +0,0 @@
----
-name: admin-tab-ui
-description: Enforce correct tab UI patterns when creating custom tabs for TabbedForm wizards in packages/admin. Use when adding new tabs to product create, price list create, or any multi-step form wizard. Covers defineTabMeta, layout, heading levels, section structure, i18n.
----
-
-# Admin Tab UI Patterns
-
-Use this skill when:
-- adding a custom tab to a TabbedForm (e.g., SEO tab in product create)
-- creating a new multi-step wizard form with tabs
-- reviewing tab code for UI consistency
-
-**Not for**: form fields inside tabs (use `admin-form-ui` for field patterns), page structure (use `admin-page-ui`).
-
-Before introducing custom interactive UI inside a tab, first apply `medusa-ui-conformance`.
-
-Read next (as needed):
-- `references/tab-anatomy.md` — exact code structure for tabs with sections
-
-## Hard Rules (DO NOT)
-
-1. Do NOT use raw `_tabMeta = { ... }` — use `defineTabMeta<SchemaType>({...})` for type safety.
-2. Do NOT use `<Heading level="h1">` in tabs — use `<Heading level="h2">` (h1 is page-level only).
-3. Do NOT use hardcoded strings — use `t("...")` for all labels, headings, placeholders.
-4. Do NOT skip `data-testid` on the tab root and major sections.
-5. Do NOT use raw `Controller` for form fields — use `Form.Field` pattern (see `admin-form-ui` skill).
-6. Do NOT put all fields in one flat list — group them into sections with clear headers.
-7. Do NOT forget `validationFields` in `defineTabMeta` — list fields validated on forward navigation.
-8. Do NOT use `<Container>` as the only top-level wrapper inside a tab — follow the section-based layout.
-9. Do NOT use `label` in tabMeta for display — use `labelKey` (i18n key) for translation support.
-
-## Tab Layout Structure
-
-Every tab MUST follow this outer layout:
-
-```tsx
-const MyTab = () => {
- const form = useTabbedForm()
-
- return (
- <div
- className="flex flex-col items-center p-16"
- data-testid="my-tab-root"
- >
- <div className="flex w-full max-w-[720px] flex-col gap-y-8">
- <Header /> {/* Heading h2 + optional description */}
- <SectionOne /> {/* Grouped fields */}
- <Divider /> {/* Optional separator */}
- <SectionTwo /> {/* More grouped fields */}
- </div>
- </div>
- )
-}
-```
-
-**Fixed classes:**
-- Outer: `flex flex-col items-center p-16`
-- Inner: `flex w-full max-w-[720px] flex-col gap-y-8`
-- Between sections: `gap-y-8` (32px)
-- Between fields within section: `gap-y-6` (24px)
-
-## Tab Header
-
-```tsx
-// Simple header
-<Heading level="h2">{t("products.create.tabs.seo.header")}</Heading>
-
-// Header with description
-<div>
- <Heading level="h2">{t("products.create.tabs.seo.header")}</Heading>
- <Text size="small" className="text-ui-fg-subtle">
- {t("products.create.tabs.seo.description")}
- </Text>
-</div>
-```
-
-## Tab Metadata (defineTabMeta)
-
-```tsx
-import { defineTabMeta } from "@components/tabbed-form/types"
-import type { ProductCreateSchemaType } from "./schema"
-
-MyTab._tabMeta = defineTabMeta<ProductCreateSchemaType>({
- id: "seo",
- labelKey: "products.create.tabs.seo", // i18n key — NOT raw text
- validationFields: ["seo_title", "seo_slug"], // fields validated on forward nav
-})
-```
-
-**Rules:**
-- `id` — unique tab identifier (lowercase, kebab-case)
-- `labelKey` — i18n translation key (the tab label shown in the progress bar)
-- `validationFields` — array of form field names validated when navigating forward from this tab
-- Omit `validationFields` for full-form validation on this tab
-
-## Section Structure
-
-```tsx
-// Section with label-header (fields grouped under a heading)
-<div id="general" className="flex flex-col gap-y-6" data-testid="seo-general-section">
- <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
- <Form.Field control={form.control} name="seo_title" render={...} />
- <Form.Field control={form.control} name="seo_slug" render={...} />
- </div>
- <Form.Field control={form.control} name="seo_description" render={...} />
-</div>
-
-// Section with header + action button
-<div className="flex flex-col gap-y-6">
- <div className="flex items-start justify-between gap-x-4">
- <div className="flex flex-col">
- <Form.Label>{t("scope.section.label")}</Form.Label>
- <Form.Hint>{t("scope.section.hint")}</Form.Hint>
- </div>
- <Button size="small" variant="secondary" type="button" onClick={handleAdd}>
- {t("actions.add")}
- </Button>
- </div>
- {/* Field list */}
-</div>
-```
-
-## Section with Switch Toggle
-
-```tsx
-<div className="flex flex-col gap-y-6">
- <Heading level="h2">{t("scope.section.header")}</Heading>
- <SwitchBox
- control={form.control}
- name="enable_feature"
- label={t("scope.fields.enable_feature.label")}
- description={t("scope.fields.enable_feature.hint")}
- />
-</div>
-```
-
-## Complete Tab Example (Correct)
-
-```tsx
-import { useTabbedForm } from "@mercurjs/admin"
-import { defineTabMeta } from "@components/tabbed-form/types"
-import { Form } from "@components/common/form"
-import { Heading, Input, Textarea, Text } from "@medusajs/ui"
-import { useTranslation } from "react-i18next"
-import type { ExtendedProductCreateSchemaType } from "../schema"
-
-const SEOTab = () => {
- const { t } = useTranslation()
- const form = useTabbedForm()
-
- return (
- <div className="flex flex-col items-center p-16" data-testid="seo-tab">
- <div className="flex w-full max-w-[720px] flex-col gap-y-8">
- <div>
- <Heading level="h2">
- {t("products.create.tabs.seo.header")}
- </Heading>
- <Text size="small" className="text-ui-fg-subtle">
- {t("products.create.tabs.seo.description")}
- </Text>
- </div>
- <div className="flex flex-col gap-y-6" data-testid="seo-fields-section">
- <Form.Field
- control={form.control}
- name="seo_title"
- render={({ field }) => (
- <Form.Item>
- <Form.Label>
- {t("products.fields.seo_title.label")}
- </Form.Label>
- <Form.Control>
- <Input
- {...field}
- placeholder={t("products.fields.seo_title.placeholder")}
- />
- </Form.Control>
- <Form.ErrorMessage />
- </Form.Item>
- )}
- />
- <Form.Field
- control={form.control}
- name="seo_description"
- render={({ field }) => (
- <Form.Item>
- <Form.Label optional>
- {t("products.fields.seo_description.label")}
- </Form.Label>
- <Form.Control>
- <Textarea
- {...field}
- placeholder={t("products.fields.seo_description.placeholder")}
- />
- </Form.Control>
- <Form.ErrorMessage />
- </Form.Item>
- )}
- />
- <Form.Field
- control={form.control}
- name="seo_slug"
- render={({ field }) => (
- <Form.Item>
- <Form.Label optional>
- {t("products.fields.seo_slug.label")}
- </Form.Label>
- <Form.Control>
- <Input
- {...field}
- placeholder={t("products.fields.seo_slug.placeholder")}
- />
- </Form.Control>
- <Form.ErrorMessage />
- </Form.Item>
- )}
- />
- </div>
- </div>
- </div>
- )
-}
-
-SEOTab._tabMeta = defineTabMeta<ExtendedProductCreateSchemaType>({
- id: "seo",
- labelKey: "products.create.tabs.seo",
- validationFields: ["seo_title", "seo_description", "seo_slug"],
-})
-
-export { SEOTab }
-```
-
-## WRONG vs RIGHT Examples
-
-### Tab Metadata
-```tsx
-// WRONG — raw object, no type safety
-SEOTab._tabMeta = {
- id: "seo",
- label: "SEO",
- labelKey: "SEO",
- validationFields: ["seo_title"],
-}
-
-// RIGHT — defineTabMeta with generic type
-SEOTab._tabMeta = defineTabMeta<ExtendedProductCreateSchemaType>({
- id: "seo",
- labelKey: "products.create.tabs.seo",
- validationFields: ["seo_title"],
-})
-```
-
-### Tab Heading
-```tsx
-// WRONG — h1 in a tab
-<Heading level="h1">SEO Settings</Heading>
-
-// RIGHT — h2 with i18n
-<Heading level="h2">{t("products.create.tabs.seo.header")}</Heading>
-```
-
-### Tab Field
-```tsx
-// WRONG — raw Controller, manual error, hardcoded string
-<Controller
- control={form.control}
- name="seo_title"
- render={({ field, fieldState }) => (
- <div className="flex flex-col gap-y-2">
- <Label htmlFor="seo-title">SEO Title *</Label>
- <Input id="seo-title" placeholder="Enter SEO title..." {...field} />
- {fieldState.error && (
- <span className="text-ui-fg-error text-small">
- {fieldState.error.message}
- </span>
- )}
- </div>
- )}
-/>
-
-// RIGHT — Form.Field, Form.Label, Form.ErrorMessage, i18n
-<Form.Field
- control={form.control}
- name="seo_title"
- render={({ field }) => (
- <Form.Item>
- <Form.Label>{t("products.fields.seo_title.label")}</Form.Label>
- <Form.Control>
- <Input {...field} placeholder={t("products.fields.seo_title.placeholder")} />
- </Form.Control>
- <Form.ErrorMessage />
- </Form.Item>
- )}
-/>
-```
diff --git a/.claude/skills/admin-ui-review/SKILL.md b/.claude/skills/admin-ui-review/SKILL.md
deleted file mode 100644
index 2e9893022..000000000
--- a/.claude/skills/admin-ui-review/SKILL.md
+++ /dev/null
@@ -1,164 +0,0 @@
----
-name: admin-ui-review
-description: Review admin UI code for consistency with established patterns. Use after writing any UI code in packages/admin to catch anti-patterns — wrong form components, hardcoded strings, missing i18n, incorrect heading levels, manual error rendering, missing data-testid, raw Controller usage.
-allowed-tools: Read, Grep, Glob
----
-
-# Admin UI Review
-
-Use this skill when:
-- you just wrote new UI code in packages/admin and want to verify consistency
-- reviewing a PR or diff that touches admin UI
-- the user asks to check UI code quality
-
-This skill checks ALL admin UI patterns. For implementation guidance, see:
-- `admin-form-ui` — form field patterns
-- `admin-page-ui` — page and section patterns
-- `admin-tab-ui` — tab patterns in TabbedForm wizards
-
-## Review Process
-
-1. Identify all changed/new UI files in `packages/admin/src/`
-2. Run each file through the checklist below
-3. Report findings ordered by severity: **P1** (breaks UX/a11y), **P2** (inconsistency), **P3** (style)
-4. Provide exact code fixes for each finding
-
-## Checklist
-
-### Form Fields (P1)
-
-- [ ] Uses `Form.Field` (not raw `Controller` from react-hook-form)
-- [ ] Uses `Form.Item` wrapper (not manual `<div className="flex flex-col gap-y-2">`)
-- [ ] Uses `Form.Label` (not `<Label>` from `@medusajs/ui`)
-- [ ] Uses `Form.Control` around input elements
-- [ ] Uses `Form.ErrorMessage` (not manual `fieldState.error && <span>`)
-- [ ] Required fields: no `*` in label text — just omit `optional` prop
-- [ ] Optional fields: `<Form.Label optional>` is present
-- [ ] Hints use `Form.Hint` component (not custom divs)
-
-### Internationalization (P1)
-
-- [ ] ALL user-visible strings use `t("...")` from `useTranslation()`
-- [ ] Labels: `t("scope.fields.field_name.label")`
-- [ ] Placeholders: `t("scope.fields.field_name.placeholder")`
-- [ ] Headings: `t("scope.section.header")`
-- [ ] Buttons: `t("actions.save")`, `t("actions.cancel")`, `t("actions.create")`, `t("actions.delete")`
-- [ ] Toast messages: `t("scope.action.successToast")`
-- [ ] Tab labels: `labelKey: "scope.create.tabs.tab_name"` (not raw text)
-- [ ] No hardcoded English strings in JSX
-
-### Typography (P2)
-
-- [ ] Page title: `<Heading>` (default level, no level prop)
-- [ ] Section title: `<Heading level="h2">` (inside Container/card headers)
-- [ ] Tab heading: `<Heading level="h2">` (NEVER h1 in tabs)
-- [ ] Drawer title: `<Heading>` inside `RouteDrawer.Header`
-- [ ] Description text: `<Text size="small">` or `<Text size="small" className="text-ui-fg-subtle">`
-- [ ] No raw `<h1>`, `<h2>`, `<p>` tags — use Heading/Text components
-
-### Tab Metadata (P1 if in TabbedForm)
-
-- [ ] Uses `defineTabMeta<SchemaType>({...})` (not raw object `{ id, label, ... }`)
-- [ ] Has `labelKey` (i18n key, not `label` with raw text)
-- [ ] Has `validationFields` array listing fields for this tab
-- [ ] Generic type matches the form schema type
-
-### Layout & Spacing (P2)
-
-- [ ] Tab layout: outer `p-16`, inner `max-w-[720px]` + `gap-y-8`
-- [ ] Section spacing: `gap-y-8` between sections, `gap-y-6` between fields
-- [ ] Grid: `grid-cols-1 gap-4 md:grid-cols-{2,3}` (not custom breakpoints)
-- [ ] Container sections: `Container className="divide-y p-0"` with header `px-6 py-4`
-- [ ] Modal body: `py-16` + centered `max-w-[720px]`
-- [ ] Footer buttons: `flex items-center justify-end gap-x-2`
-
-### Inline Editable Rows / Dynamic Arrays (P2)
-
-- [ ] Row card: `<li>` with `bg-ui-bg-component shadow-elevation-card-rest rounded-xl p-1.5`
-- [ ] Outer grid: `grid grid-cols-[1fr_28px]` (content + delete button)
-- [ ] Inner grid: `grid grid-cols-[min-content,1fr]` (label + input pairs horizontally)
-- [ ] Row labels: `<Label size="xsmall" weight="plus" className="text-ui-fg-subtle">` (compact inline labels — NOT Form.Label)
-- [ ] Row inputs: `className="bg-ui-bg-field-component"` for contrast background
-- [ ] Delete button: `<IconButton size="small" variant="transparent">` with `<XMarkMini />`
-- [ ] Dynamic rows: `useFieldArray` with append/remove
-- [ ] Section header: `Form.Label` + `Form.Hint` + Add `<Button size="small" variant="secondary">`
-- [ ] Duplicate prevention: `useWatch` + `isOptionDisabled` pattern when rows select from shared pool
-
-### Components (P2)
-
-- [ ] Action menus: `ActionMenu` component (not custom dropdowns)
-- [ ] Delete confirmation: `usePrompt()` (not `window.confirm`)
-- [ ] Empty states: `NoRecords` / `NoResults` (not custom empty divs)
-- [ ] Status indicators: `StatusBadge` (not custom colored spans)
-- [ ] Forms: `KeyboundForm` (not raw `<form>`)
-- [ ] Close buttons: `RouteDrawer.Close` / `RouteFocusModal.Close` (not manual navigate)
-
-### Submit Safety (P1)
-
-- [ ] Uses `KeyboundForm` (not raw `<form>`)
-- [ ] Submit handler has `isPending` guard
-- [ ] Button has `isLoading={isPending}`
-- [ ] Keyboard submit (Ctrl/Cmd+Enter) respects loading state
-- [ ] Async dependencies (e.g., regions loading) are guarded in submit handler
-- [ ] Success: `toast.success()` + `handleSuccess()` from `useRouteModal()`
-
-### Data Loading (P2)
-
-- [ ] `isError` → `throw error` for error boundary
-- [ ] Loading state shows skeleton (not blank page)
-- [ ] Data fetching in Root, passed as props to sections (not context)
-
-### Testing (P3)
-
-- [ ] `data-testid` on root elements, form fields, buttons
-- [ ] Test IDs follow kebab-case naming: `data-testid="product-create-title-input"`
-
-## Output Format
-
-### When findings exist:
-
-```
-## UI Review: {file_path}
-
-### P1 (Critical)
-1. **Raw Controller** at line {N}: Uses `Controller` instead of `Form.Field`
- Fix: Replace with `Form.Field` + `Form.Item` + `Form.Label` + `Form.Control` + `Form.ErrorMessage`
-
-2. **Hardcoded string** at line {N}: `"SEO Title *"` should be `t("products.fields.seo_title.label")`
-
-### P2 (Inconsistency)
-1. **Wrong heading level** at line {N}: `<Heading level="h1">` in tab — should be `level="h2"`
-
-### P3 (Style)
-1. **Missing data-testid** at line {N}: Tab root div missing `data-testid`
-```
-
-### When no findings:
-
-```
-## UI Review: {file_path}
-
-No findings. Code follows all admin UI patterns.
-
-Verified:
-- Form.Field pattern ✓
-- i18n strings ✓
-- Correct heading levels ✓
-- defineTabMeta ✓
-- data-testid ✓
-```
-
-## Common Anti-Patterns (quick reference)
-
-| Anti-Pattern | Correct Pattern |
-|-------------|----------------|
-| `<Controller>` | `<Form.Field>` |
-| `<Label>` from @medusajs/ui | `<Form.Label>` |
-| `fieldState.error && <span>` | `<Form.ErrorMessage />` |
-| `"Title *"` | `<Form.Label>{t("...")}</Form.Label>` (no `optional`) |
-| `_tabMeta = { id: "x" }` | `defineTabMeta<T>({ id: "x", ... })` |
-| `<Heading level="h1">` in tab | `<Heading level="h2">` |
-| `window.confirm(...)` | `usePrompt()` |
-| `<form onSubmit>` | `<KeyboundForm onSubmit>` |
-| `<div className="flex flex-col gap-y-2">` (field wrapper) | `<Form.Item>` |
-| Hardcoded `"Save"` | `t("actions.save")` |
diff --git a/.claude/skills/cc-alignment/SKILL.md b/.claude/skills/cc-alignment/SKILL.md
deleted file mode 100644
index df56192f8..000000000
--- a/.claude/skills/cc-alignment/SKILL.md
+++ /dev/null
@@ -1,89 +0,0 @@
----
-name: cc-alignment
-description: Align existing Compound Component pages to vendor standard naming and structure. Use when renaming CC exports, adding slot prefixes, refactoring list headers to nested compounds, updating barrel exports, fixing DTS build blockers, or updating testing registry consumer pages.
----
-
-# CC Alignment (Compound Components → Vendor Standard)
-
-Use this skill when:
-- renaming existing CC exports to match vendor naming (`XxxDetail` → `XxxDetailPage`)
-- adding `Main`/`Sidebar` prefix to existing section slots
-- refactoring list page headers from render props to nested compounds
-- updating `pages/index.ts` barrel exports after CC rename
-- fixing DTS build blockers in `tsup` pipeline
-- updating testing registry consumer pages to use new CC API
-
-**Not for**: initial CC migration from scratch (use `compound-components-migration` skill instead).
-
-Read next (as needed):
-- `references/alignment-checklist.md` — step-by-step alignment workflow
-- `references/build-pipeline.md` — tsup, DTS, dist verification
-- `references/testing-registry.md` — consumer page patterns
-
-## Workflow
-
-1. **Identify what needs alignment** — compare current exports against vendor standard:
- - Root name has `Page` suffix?
- - Slots have `Main`/`Sidebar` prefix?
- - List header uses nested compounds (not render props)?
- - No context/provider? (data passed as props from Root to sections)
- - No Layout wrapper? (TwoColumnPage inlined in Root)
-
-2. **Rename + restructure** in this order:
- 1. Component file — rename export, prefix slots, add missing slots (e.g., `SidebarSellerSection`), remove context/provider if present, pass data as props
- 2. Route `index.ts` — update `as Component` export
- 3. `pages/index.ts` barrel — new names
- 4. Testing registry consumers — update to use new slot names
-
-3. **Build + verify**:
- - `npx tsup` — must pass both ESM and DTS
- - If DTS fails on pre-existing errors in OTHER files, fix them (they block the whole DTS emit)
- - Grep for old export names — must return zero hits in `pages/index.ts`
- - Verify `dist/pages/index.js` contains new exports
-
-4. **Test in testing registry**:
- - Consumer pages import from `@mercurjs/admin/pages` — must resolve without errors
- - No `implicit any` warnings on import
-
-## Hard Rules
-
-1. Do NOT create backward-compat aliases (`ProductDetail` re-export alongside `ProductDetailPage`). Clean rename only.
-2. Do NOT change component behavior during alignment — only rename/restructure exports.
-3. Do NOT skip DTS build — consumers need type declarations.
-4. Do NOT fix pre-existing TS errors with `any` casts — use proper types (`HttpTypes.*`, `Omit<>`, etc.).
-5. Do NOT forget to update ALL consumers (barrel, route index, testing registry).
-6. Do NOT use `header?: ReactNode` prop pattern for list headers — use nested compound components.
-7. DO preserve all existing `data-testid` attributes.
-8. DO preserve `hasOutlet` on `TwoColumnPage` in Root's default composition.
-9. DO preserve `location.search` on export/import links.
-10. Do NOT create a separate `Layout` wrapper component in detail pages. Inline `TwoColumnPage` directly in `Root`'s default composition (vendor standard). `data`, `hasOutlet`, `showJSON`, `showMetadata` go directly on the `TwoColumnPage` in Root.
-10. Do NOT keep nested detail routes as direct `:id -> Component: DetailPage`; use `:id -> Component: Outlet` and child `path: "" -> DetailPage`.
-11. Do NOT use broad override switch (`Children.count(children) > 0`) for detail pages with nested routes/extensions; use explicit compound composition guard.
-12. DO reuse shared composition helper (`src/lib/compound-composition.ts`) where override guard is needed.
-
-## Naming Convention Reference
-
-### Detail pages
-```
-Root: XxxDetailPage (e.g., ProductDetailPage)
-Slots: Main{Section} — MainGeneralSection, MainMediaSection
- Sidebar{Section} — SidebarOrganizationSection, SidebarSellerSection
-Fixed: Main, Sidebar
-```
-
-### List pages
-```
-Root: XxxListPage (e.g., ProductListPage)
-Slots: Table — Container (Header + DataTable + Outlet)
- Header — title + actions (Children.count override)
- HeaderTitle — Heading component
- HeaderActions — button container (Children.count override)
- Header{Action}Button — individual buttons (Create, Export, Import)
- DataTable — raw data grid (self-contained fetch)
-```
-
-### Barrel (`pages/index.ts`)
-```typescript
-export { XxxDetailPage } from "./path/to/xxx-detail"
-export { XxxListPage } from "./path/to/xxx-list"
-```
diff --git a/.claude/skills/cc-alignment/references/alignment-checklist.md b/.claude/skills/cc-alignment/references/alignment-checklist.md
deleted file mode 100644
index f4c8eb283..000000000
--- a/.claude/skills/cc-alignment/references/alignment-checklist.md
+++ /dev/null
@@ -1,85 +0,0 @@
-# CC Alignment Checklist
-
-Step-by-step workflow for aligning an existing CC page to vendor standard.
-
-## Pre-flight
-
-- [ ] Read current component file — identify export name, slot names, missing slots
-- [ ] Read current `index.ts` — identify `as Component` export
-- [ ] Read `pages/index.ts` — identify current barrel export
-- [ ] Check if testing registry has consumer pages for this component
-
-## Detail Page Alignment
-
-### 1. Component file (`xxx-detail.tsx`)
-
-- [ ] Rename export: `XxxDetail` → `XxxDetailPage`
-- [ ] Prefix main slots: `GeneralSection` → `MainGeneralSection`, etc.
-- [ ] Prefix sidebar slots: `SalesChannelSection` → `SidebarSalesChannelSection`, etc.
-- [ ] Add missing slots (e.g., `SidebarSellerSection` if seller section exists in default composition)
-- [ ] Remove dead slots (e.g., references to non-existent components)
-- [ ] Verify: NO context/provider — Root fetches data and passes as props to sections
-- [ ] Verify: NO `Layout` wrapper — `TwoColumnPage` inlined directly in Root's default composition (with `data`, `hasOutlet`, `showJSON`, `showMetadata`)
-- [ ] Verify: `Main`, `Sidebar` slots remain on compound (NO `useContext`, NO `Layout`)
-- [ ] Verify: default composition JSX unchanged (only Object.assign keys change)
-- [ ] If detail page can receive nested route/extension children, use explicit compound composition guard (not generic `Children.count(children) > 0`)
-- [ ] Prefer shared helper: `src/lib/compound-composition.ts`
-
-### 2. Route index (`xxx-detail/index.ts`)
-
-- [ ] `XxxDetail as Component` → `XxxDetailPage as Component`
-- [ ] Remove any `export type { XxxDetailContextValue }` (no context)
-
-### 2.5 Route map topology (`get-route-map.tsx`)
-
-- [ ] For nested detail pages, `:id` route uses `Component: Outlet` (not detail page component directly)
-- [ ] Detail page is mounted at child route `path: ""`
-- [ ] Nested drawers/modals (`edit`, `metadata`, etc.) remain children of that `path: ""` detail node
-
-### 3. Barrel (`pages/index.ts`)
-
-- [ ] Replace old named export with new: `export { XxxDetailPage } from "..."`
-- [ ] Remove any context type exports (no context)
-
-### 4. Testing registry consumer
-
-- [ ] Remove fallback aliases (e.g., `?? AdminPages.ProductDetail`)
-- [ ] Use new slot names directly: `ProductDetailPage.MainGeneralSection`
-- [ ] Import directly: `import { ProductDetailPage } from "@mercurjs/admin/pages"`
-
-## List Page Alignment
-
-### 1. Table component file (`xxx-list-table.tsx`)
-
-- [ ] Extract individual button components (`CreateButton`, `ExportButton`, etc.)
-- [ ] Extract `XxxListTitle` component
-- [ ] Extract `XxxListActions` with `Children.count` override
-- [ ] Extract `XxxListHeader` with `Children.count` override
-- [ ] Extract `XxxListDataTable` (data grid without header)
-- [ ] Refactor `XxxListTable` from `header?: ReactNode` prop to `children?: ReactNode`
-- [ ] Verify: `location.search` preserved on export/import links
-- [ ] Verify: `<Outlet />` still rendered in Table
-
-### 2. Table barrel (`xxx-list-table/index.ts`)
-
-- [ ] Export all new sub-components
-
-### 3. Root component file (`xxx-list.tsx`)
-
-- [ ] Rename export: `XxxList` → `XxxListPage`
-- [ ] `Object.assign` exposes: `Table`, `Header`, `HeaderTitle`, `HeaderActions`, `HeaderCreateButton`, `HeaderExportButton`, `HeaderImportButton`, `DataTable`
-
-### 4. Route index, barrel, testing registry — same as detail page
-
-## Post-flight
-
-- [ ] `npx tsup` passes (ESM + DTS)
-- [ ] Dev server rebuilt/reloaded after package changes (to avoid stale bundle false positives)
-- [ ] Grep: no old export names in `pages/index.ts`
-- [ ] Grep: no dead slot references (e.g., `AdditionalAttributeSection`)
-- [ ] `dist/pages/index.js` contains new exports
-- [ ] `dist/pages/index.d.ts` exists and has types
-- [ ] Testing registry imports resolve without `implicit any` error
-- [ ] Customer/Product/Order detail pages do not render duplicated section stacks
-- [ ] Grep: no `Layout` wrapper in any `*-detail.tsx` compound (vendor standard: inline `TwoColumnPage` in Root)
-- [ ] Grep: no `.Layout` usage in testing registry consumer pages
diff --git a/.claude/skills/cc-alignment/references/build-pipeline.md b/.claude/skills/cc-alignment/references/build-pipeline.md
deleted file mode 100644
index 2844478dc..000000000
--- a/.claude/skills/cc-alignment/references/build-pipeline.md
+++ /dev/null
@@ -1,82 +0,0 @@
-# Build Pipeline — tsup + DTS
-
-## How admin package is built
-
-- **Tool**: `tsup` (config in `packages/admin/tsup.config.ts`)
-- **Entry points**: `src/index.ts`, `src/index.css`, `src/pages/index.ts`
-- **Format**: ESM only
-- **DTS**: Enabled — generates `.d.ts` files alongside `.js`
-- **Output**: `dist/` directory
-
-## Package exports (`package.json`)
-
-```json
-{
- "exports": {
- ".": {
- "types": "./dist/index.d.ts",
- "import": "./dist/index.js"
- },
- "./pages": {
- "types": "./dist/pages/index.d.ts",
- "import": "./dist/pages/index.js"
- }
- }
-}
-```
-
-Consumers import via `@mercurjs/admin/pages` which resolves to `dist/pages/index.js`.
-
-## DTS build is all-or-nothing
-
-**Critical**: DTS build fails if ANY file reachable from entry points has a TS error. This means pre-existing errors in unrelated files (e.g., `order-detail.tsx`) will block DTS generation for `pages/index.ts`.
-
-### Common DTS blockers and fixes
-
-| Error | Root cause | Fix |
-|-------|-----------|-----|
-| `$id` missing from query type | SDK hook type includes `$id` but hook adds it internally | `Omit<InferClientInput<...>, "$id">` on the hook's query param |
-| `InventoryNext` not found | Removed namespace in `@medusajs/types` v2 | Replace with `HttpTypes.AdminInventoryItem` |
-| `Property 'rules' not on AdminPrice` | Runtime API field not in SDK types | Safe cast: `((p as unknown) as { rules?: Record<string, unknown> }).rules` |
-| `Property 'inventory' not on AdminProductVariant` | Wrong property name | Use `inventory_items` (correct field name) |
-| `InventoryItemDTO` not found | Old import path | Use `HttpTypes.AdminInventoryItem` |
-
-### Fix strategy
-
-1. **Never use `any`** to silence DTS errors
-2. Use `Omit<>` when a hook internally adds fields the consumer shouldn't pass
-3. Use `HttpTypes.*` when old type imports are broken
-4. Use safe casts (`as unknown as { field: Type }`) only for runtime-only fields missing from types
-5. Fix at the source (hook definition, type definition) — not at the call site
-
-## Build commands
-
-```bash
-# Full build (ESM + DTS)
-npx tsup
-
-# Quick build without types (for testing ESM output)
-npx tsup --no-dts
-
-# Dev mode (watch)
-npx tsup --watch
-```
-
-## Verification after build
-
-```bash
-# Check new exports exist in built output
-grep "ProductListPage\|ProductDetailPage" dist/pages/index.js
-
-# Check DTS was generated
-ls -la dist/pages/index.d.ts
-
-# Check file size (should be > 0)
-wc -c dist/pages/index.d.ts
-```
-
-## Testing registry integration
-
-After rebuild, the testing registry (`mercur-testing-registry/apps/admin/`) picks up changes via workspace linking. If dev server is running, it needs a page reload (Vite HMR doesn't always catch `dist/` changes from linked packages).
-
-If UI behavior appears unchanged after code fixes (e.g., duplicate sections still visible), force a clean rebuild of `@mercurjs/admin` and restart/reload the consumer app before debugging further.
diff --git a/.claude/skills/cc-alignment/references/testing-registry.md b/.claude/skills/cc-alignment/references/testing-registry.md
deleted file mode 100644
index ddaec965c..000000000
--- a/.claude/skills/cc-alignment/references/testing-registry.md
+++ /dev/null
@@ -1,128 +0,0 @@
-# Testing Registry — Consumer Page Patterns
-
-## Location
-
-Testing registry consumer pages live at:
-```
-/Users/jakubsieradzki/workspace/testing-mercur/mercur-testing-registry/apps/admin/src/pages/
-```
-
-These pages are file-based routed (same as main admin app via `@mercurjs/dashboard-sdk`).
-
-## Purpose
-
-Consumer pages test that CC compound components are properly composable from an external consumer perspective. They import from `@mercurjs/admin/pages` and customize layout by overriding children.
-
-## Pattern: Detail Page Consumer
-
-Consumer fetches data with their own hook and passes as props to sections:
-
-```typescript
-import { ProductDetailPage } from "@mercurjs/admin/pages"
-import { HttpTypes } from "@medusajs/types"
-import { useParams } from "react-router-dom"
-import { useQuery } from "@tanstack/react-query"
-import { client } from "../../../lib/client"
-
-// Consumer's own hook — fetches product data
-function useProduct(id: string) {
- const { data, ...rest } = useQuery({
- queryKey: ["products", id],
- queryFn: () => client.admin.products.$id.query({ $id: id }),
- })
- return { product: data?.product as HttpTypes.AdminProduct | undefined, ...rest }
-}
-
-const Page = () => {
- const { id } = useParams()
- const { product, isLoading } = useProduct(id!)
-
- if (isLoading || !product) {
- return <div>Loading...</div>
- }
-
- return (
- <ProductDetailPage>
- <ProductDetailPage.Main>
- <CustomWidget product={product} />
- <ProductDetailPage.MainGeneralSection product={product} />
- <ProductDetailPage.MainOptionSection product={product} />
- <ProductDetailPage.MainVariantSection product={product} />
- </ProductDetailPage.Main>
- <ProductDetailPage.Sidebar>
- <ProductDetailPage.SidebarSalesChannelSection product={product} />
- <ProductDetailPage.SidebarOrganizationSection product={product} />
- </ProductDetailPage.Sidebar>
- </ProductDetailPage>
- )
-}
-
-export default Page
-```
-
-Key points:
-- Consumer fetches data with own hook (NOT `useLoaderData` — loader is lost during dashboard-sdk route merge)
-- Sections accept data as props (no context/provider)
-- Import compound root directly (no `* as AdminPages` + cast)
-- Slots accessed as `ProductDetailPage.MainGeneralSection`
-- Custom components can be inserted between slot sections
-- Sections can be omitted or reordered
-- Root wraps consumer children in `TwoColumnPage` (layout works automatically)
-
-## Pattern: List Page Consumer
-
-```typescript
-import { ProductListPage } from "@mercurjs/admin/pages"
-
-const page = () => {
- return (
- <ProductListPage>
- <ProductListPage.Table>
- <ProductListPage.Header>
- <ProductListPage.HeaderTitle />
- <ProductListPage.HeaderActions>
- <ProductListPage.HeaderCreateButton />
- {/* Export and Import buttons omitted */}
- </ProductListPage.HeaderActions>
- </ProductListPage.Header>
- <ProductListPage.DataTable />
- </ProductListPage.Table>
- </ProductListPage>
- )
-}
-
-export default page
-```
-
-Key points:
-- Override at any granularity: whole header, just actions, or individual buttons
-- `DataTable` is self-contained (fetches data internally)
-- `Table` renders `<Outlet />` for nested routes (export/import modals)
-
-## Anti-patterns (do NOT use)
-
-```typescript
-// BAD: wildcard import + cast to any
-import * as AdminPages from "@mercurjs/admin/pages"
-const ProductDetailPage = (AdminPages as any).ProductDetailPage
-
-// BAD: fallback aliases for backward compat
-const MainGeneralSection = ProductDetailPage.MainGeneralSection ?? ProductDetailPage.GeneralSection
-
-// BAD: useLoaderData — loader is lost during dashboard-sdk route merge
-const data = useLoaderData() as { product: HttpTypes.AdminProduct } // undefined!
-
-// BAD: trying to use context (doesn't exist)
-const ctx = ProductDetailPage.useContext()
-```
-
-## Why useLoaderData doesn't work
-
-Dashboard-sdk's `mergeRoutes()` does a shallow spread: `{ ...baseRoute, ...customRest }`. When consumer overrides `Component`, admin's `loader` is lost. Consumer must fetch data themselves.
-
-## When to update consumer pages
-
-- After renaming CC exports (new import name)
-- After adding/removing/renaming slots (new property names on compound)
-- After changing composition API (e.g., `header` prop → `children`)
-- Always test that `export default Page` still renders correctly
diff --git a/.claude/skills/code-review/SKILL.md b/.claude/skills/code-review/SKILL.md
deleted file mode 100644
index 571099b06..000000000
--- a/.claude/skills/code-review/SKILL.md
+++ /dev/null
@@ -1,108 +0,0 @@
----
-name: code-review
-description: Review code changes for contract compliance, type safety, and regression risk. Use after completing any non-trivial implementation, before merging PRs, or when asked to review code quality across any mercur package.
-allowed-tools: Read, Grep, Glob
----
-
-# Code Review
-
-Use this skill when:
-- reviewing a PR or diff across any mercur package
-- completing a non-trivial implementation and want a self-check
-- asked to review code quality, contract compliance, or regression risk
-- `admin-ui-review` is too narrow (backend, registry, cross-package changes)
-
-For admin UI-specific review, prefer `admin-ui-review` — it has deeper UI pattern coverage.
-
-## Review Process
-
-1. Identify all changed files (staged + unstaged if relevant)
-2. Classify each change by area: API, types, registry, admin, vendor, config, docs
-3. Run the area-specific checks from `references/review-checklist.md`
-4. Report findings ordered by severity
-5. State what was verified and what remains untested
-
-## Severity Levels
-
-- **P1 (Blocker)**: breaks a public contract, introduces runtime error, security issue, data loss risk
-- **P2 (Should fix)**: type safety gap, missing validation, inconsistent pattern, missing i18n
-- **P3 (Suggestion)**: naming, style, minor improvement, documentation gap
-
-## Hard Rules
-
-1. Do not approve changes that silently alter public contract surfaces (see constitution)
-2. Do not approve `any` types on public API boundaries or shared DTOs
-3. Do not approve registry blocks that import from `@components/`, `@hooks/`, `@lib/`
-4. Do not approve barrel `index.ts` in registry `workflows/` or `steps/`
-5. Do not approve route handlers without concrete generics on `AuthenticatedMedusaRequest<T>` / `MedusaResponse<T>`
-6. Flag keyboard submit paths that lack handler-level guards
-7. Flag missing migration/compatibility notes when frozen surfaces change
-
-## What to Check First
-
-Prioritize checks by blast radius:
-
-1. **Contract changes** — API paths, response shapes, generated types, CLI commands
-2. **Type safety** — `any` on boundaries, missing generics, type widening
-3. **Registry integrity** — import paths, barrel files, file layout, docs field
-4. **Behavioral regression** — submit guards, loading states, error handling
-5. **Cross-package impact** — changes that touch multiple package boundaries
-6. **Pattern consistency** — last, after safety is confirmed
-
-## Output Format
-
-### When findings exist:
-
-```
-## Code Review: [scope description]
-
-### P1 (Blocker)
-1. **[Issue]** in `file:line` — [description]
- Fix: [concrete suggestion]
-
-### P2 (Should fix)
-1. **[Issue]** in `file:line` — [description]
-
-### P3 (Suggestion)
-1. **[Issue]** in `file:line` — [description]
-
-### Verified
-- [what was checked]
-
-### Not verified
-- [what was skipped and why]
-
-### Residual risk
-- [any remaining concerns]
-```
-
-### When no findings:
-
-```
-## Code Review: [scope description]
-
-No findings. Changes are consistent with mercur patterns and contracts.
-
-### Verified
-- [list of checks performed]
-
-### Not verified
-- [anything skipped]
-```
-
-## Cross-Package Reviews
-
-When changes span multiple packages:
-1. Check each package against constitution package boundaries
-2. Verify contract surfaces at package boundaries
-3. Check that codegen inputs/outputs are consistent
-4. Flag any missing spec (changes spanning 3+ packages require a spec per constitution governance)
-
-## Self-Review Mode
-
-When reviewing your own implementation:
-1. Step back from implementation mindset
-2. Re-read the original request/spec
-3. Check if you introduced anything beyond what was asked
-4. Run the checklist as if reviewing someone else's code
-5. Be honest about what you didn't test
diff --git a/.claude/skills/code-review/references/review-checklist.md b/.claude/skills/code-review/references/review-checklist.md
deleted file mode 100644
index bca142501..000000000
--- a/.claude/skills/code-review/references/review-checklist.md
+++ /dev/null
@@ -1,64 +0,0 @@
-# Code Review Checklist
-
-Area-specific checks for mercur code review. Use alongside the main `SKILL.md`.
-
-## API Routes (`packages/core/`, `packages/registry/`)
-
-- [ ] Route handler has concrete generics: `AuthenticatedMedusaRequest<BodyType>`, `MedusaResponse<ResponseType>`
-- [ ] Request validation matches the generic body type
-- [ ] Response envelope shape is consistent with existing routes
-- [ ] New routes are documented or have a docs field in registry.json
-- [ ] Middleware is registered (per-resource array pattern for registry blocks)
-- [ ] Auth guards are appropriate (authenticated vs public)
-- [ ] No `any` on request/response types
-
-## Type Safety (`packages/types/`, shared DTOs)
-
-- [ ] Public types use explicit interfaces, not `Record<string, any>`
-- [ ] Generic parameters are concrete, not `any`
-- [ ] Exported types don't leak internal implementation details
-- [ ] Changes to shared types are backward-compatible (or spec'd)
-
-## Registry Blocks (`packages/registry/`)
-
-- [ ] No imports from `@components/`, `@hooks/`, `@lib/` — use `@mercurjs/dashboard-shared`
-- [ ] No barrel `index.ts` in `workflows/` or `steps/`
-- [ ] File layout matches CLI `resolveNestedFilePath()` expectations
-- [ ] `registry.json` entry has `docs` field with setup instructions
-- [ ] External npm dependencies listed in `dependencies` array
-- [ ] Pages are `page.tsx` with `export default`
-- [ ] Workflows grouped: `workflows/<entity>/steps/` + `workflows/<entity>/workflows/`
-
-## Public Exports & Codegen
-
-- [ ] No silent changes to public package exports or entrypoints
-- [ ] Route type codegen generics are present and correct
-- [ ] Generated `Routes` types still match after changes
-- [ ] CLI command names/options unchanged (or spec'd)
-
-## Admin / Vendor UI (`packages/admin/`, `packages/vendor/`)
-
-- [ ] Forms use `KeyboundForm` with handler-level submit guard
-- [ ] i18n: all user-visible strings use `t("...")`
-- [ ] `useRouteModal()` is inside `<RouteDrawer>` / `<RouteFocusModal>`, not top-level
-- [ ] Loading/error states are preserved after refactoring
-- [ ] For detailed UI review, defer to `admin-ui-review` skill
-
-## Database & Migrations
-
-- [ ] Schema changes have migration notes in spec
-- [ ] No destructive column drops without migration path
-- [ ] Module registration documented for downstream users
-
-## Configuration
-
-- [ ] `medusa-config.ts` changes documented (including `admin-ui`/`vendor-ui` module options if dashboard mounting changed)
-- [ ] `blocks.json` alias impact considered
-- [ ] Environment variable additions documented
-- [ ] `vite.config.ts` changes in `apps/admin` or `apps/vendor` reviewed (plugin config, `medusaConfigPath`)
-
-## Documentation
-
-- [ ] Public-facing behavior changes reflected in docs
-- [ ] API examples updated if request/response changed
-- [ ] Setup instructions updated if configuration changed
diff --git a/.claude/skills/compound-components-migration-review/SKILL.md b/.claude/skills/compound-components-migration-review/SKILL.md
deleted file mode 100644
index 90f47f8b0..000000000
--- a/.claude/skills/compound-components-migration-review/SKILL.md
+++ /dev/null
@@ -1,126 +0,0 @@
----
-name: compound-components-migration
-description: Plan, implement, and review admin page migrations to Compound Components and TabbedForm with strict regression prevention (loading/error gating, keyboard submit paths, dynamic tab visibility, context typing, and dead abstraction APIs). Use when writing or reviewing migration code in packages/admin.
-allowed-tools: Read, Grep, Glob
----
-
-# Compound Components Migration (Implementation + Review)
-
-Use this skill when:
-- migrating admin pages/forms to `Object.assign(Root, { ... })`
-- introducing context providers for detail pages
-- migrating manual tab flows to `TabbedForm`
-- reviewing diffs from Codex, Claude, or other LLMs for migration regressions
-
-Primary goal:
-- prevent behavioral regressions while improving composability
-
-Read next (as needed):
-- `references/review-checklist.md` for implementation + review checklist
-- `references/common-regressions.md` for known failure modes from this repo
-
-## Modes
-
-- **Implementation mode (default)**: you are writing migration code.
-- **Review mode**: you are reviewing someone else's diff.
-
-Start in implementation mode unless the user explicitly asks only for review.
-
-## Workflow (implementation mode)
-
-1. Identify migration type:
-- list page (compound only)
-- detail page (compound + context)
-- tabbed form (`TabbedForm`)
-2. Open repo migration source of truth:
-- `packages/admin/COMPOUND_COMPONENTS_MIGRATION.md`
-3. Find a reference implementation (prefer vendor equivalent) before editing.
-4. Implement in small steps, preserving behavior after each step:
-- component API / `Root` + `Children.count`
-- provider/context boundary (detail pages)
-- tab abstraction migration (`TabbedForm`, `_tabMeta`, `validationFields`)
-- dynamic tab visibility (`isVisible`) behavior
-- submit/keyboard guards + async gating
-5. Run a self-check against `references/review-checklist.md` before finalizing.
-6. If possible, run targeted tests or at least manual smoke checks for keyboard and dynamic tabs.
-
-## Workflow (review mode)
-
-1. Review `git diff --cached` and `git diff` separately (staged vs unstaged).
-2. Identify migration type:
-- list page (compound only)
-- detail page (compound + context)
-- tabbed form (`TabbedForm`)
-3. Check regression hotspots first (before style):
-- loading / error / ready gating moved or removed
-- keyboard submit paths (`Enter`, `Ctrl/Cmd+Enter`)
-- dynamic tabs (`isVisible`) + active tab state
-- validation scope (`validationFields`)
-- context typing (`any`, `Record<string, any>`)
-4. Only after behavior is safe, review API ergonomics:
-- canonical layout wrapper (`Layout`)
-- exported subcomponents shape
-- context hook boundaries
-5. Recommend tests for new behavior (especially keyboard + dynamic tabs).
-
-## Hard Rules (DO NOT)
-
-1. Do not move fetches into child components without preserving `isPending/isError/ready` behavior.
-2. Do not trust button `disabled/isLoading` alone to block submit; keyboard shortcuts can bypass UI.
-3. Do not add metadata APIs (`_tabMeta`, `validationFields`) unless runtime logic uses them.
-4. Do not assume tabs are static if `isVisible` exists.
-5. Do not introduce `any` in context/provider types.
-6. Do not export compound subcomponents without a safe wrapper when composition requires provider/layout.
-7. Do not widen per-tab validation to full-form validation unless explicitly intended.
-8. Do not merge a `TabbedForm` migration without verifying keyboard submit behavior.
-9. Do not move query hooks into nested tabs/sections unless submit normalization is still safe when queries are pending.
-10. Do not use generic `Children.count(children) > 0` as the only override switch for detail pages that can receive nested route/extension children.
-11. Do not keep detail route as direct `:id -> Component: DetailPage` when nested routes exist; use `:id -> Component: Outlet` and `path: "" -> DetailPage`.
-12. Do reuse shared composition-guard helper (`src/lib/compound-composition.ts`) instead of copy-pasted local implementations.
-
-## Implementation Checklist (must apply while coding)
-
-1. Preserve runtime behavior first, then improve API shape.
-2. Add local submit guards for async dependencies used in payload normalization.
-3. If tabs are dynamic (`isVisible`), normalize active tab state when visible tab set changes.
-4. If introducing `_tabMeta` / `validationFields`, wire runtime behavior in the same patch.
-5. Keep context/provider typed with domain types (`HttpTypes.*` or explicit alias).
-6. Export a canonical composition wrapper (`Layout`/`Page`) when subcomponents need provider/layout context.
-
-## Output Format (review mode)
-
-When asked for review:
-- Findings first, ordered by severity (`P1`, `P2`, `P3`)
-- Include file + line references
-- Briefly list what was verified and what remains untested
-
-When no findings:
-- Explicitly say no findings
-- Mention residual risks / test gaps
-
-## Output Format (implementation mode)
-
-When delivering a migration or fix:
-- Summarize what behavior was preserved (especially async gating, keyboard submit, dynamic tabs)
-- List files changed
-- Mention tests run or not run
-- Call out residual risks if behavior was not verified
-
-## Implementation Guidance (when fixing)
-
-Prefer minimal patches that:
-- restore previous behavioral guarantees first
-- keep new compound API shape intact if possible
-- add local guards in submit handlers for critical async dependencies
-- add state normalization when dynamic tabs change visibility
-
-## Repo-specific Notes
-
-- Source of truth for migration strategy:
- `packages/admin/COMPOUND_COMPONENTS_MIGRATION.md`
-- This repo has already seen regressions in:
-- `regions` loading vs submit payload normalization
-- `Ctrl/Cmd+Enter` bypassing loading state
-- hidden active tab causing invalid tab state in `TabbedForm`
-- dead `_tabMeta.validationFields` API (metadata declared but not used by runtime)
-- duplicate detail screen rendering due to route topology + broad children override
diff --git a/.claude/skills/compound-components-migration-review/references/common-regressions.md b/.claude/skills/compound-components-migration-review/references/common-regressions.md
deleted file mode 100644
index fa24b00ac..000000000
--- a/.claude/skills/compound-components-migration-review/references/common-regressions.md
+++ /dev/null
@@ -1,118 +0,0 @@
-# Common Migration Regressions (Repo-specific)
-
-These are recurring failure modes seen during `packages/admin` migrations to Compound Components / `TabbedForm`.
-
-## 1. Fetch moved to child, gating left behind
-
-Pattern:
-- parent used to block rendering/submit until query was ready
-- query moved into child form/section
-- submit logic still depends on query-derived data
-
-Impact:
-- invalid payloads (e.g. missing mapping data)
-- race conditions visible only under slow network
-
-What to check:
-- search for moved hooks like `useRegions`, `useStore`, `usePricePreferences`
-- check submit handlers for derived maps or normalization dependencies
-
-How to prevent while coding:
-- move `isPending/isError` handling together with the query
-- add submit guard when normalization depends on query data
-- verify keyboard submit path, not only button clicks
-
-## 2. Keyboard submit bypasses loading state
-
-Pattern:
-- buttons show `isLoading` / disabled
-- `KeyboundForm` / keyboard handler still calls `onSubmit`
-
-Impact:
-- submit during async preload
-- duplicate submit paths not protected by UI state
-
-What to check:
-- `Enter`, `Ctrl/Cmd+Enter`, custom keyboard handlers
-- logic-level guard in submit handler
-
-How to prevent while coding:
-- add a submit-level guard for critical async dependencies
-- if `TabbedForm`/keyboard wrapper exists, ensure it checks loading before calling `onSubmit`
-
-## 3. Dynamic tabs hide active tab
-
-Pattern:
-- `isVisible` changes based on form values
-- active tab disappears
-- tab state logic assumes active tab still exists
-
-Impact:
-- inconsistent UI state
-- runtime errors (`findIndex` = `-1`, invalid array access)
-
-What to check:
-- normalization of `activeTabId` when `visibleTabs` changes
-- guards around `currentIndex === -1`
-
-How to prevent while coding:
-- treat `visibleTabs` as dynamic from day one
-- add fallback active-tab resolution in effect/state sync code before wiring validation ranges
-
-## 4. Dead abstraction API
-
-Pattern:
-- new metadata/props introduced (`validationFields`, etc.)
-- runtime logic ignores them
-
-Impact:
-- false confidence
-- regressions hidden behind “cleaner” API
-
-What to check:
-- trace new API from declaration -> read -> actual behavior
-
-How to prevent while coding:
-- never commit metadata-only changes without runtime integration in the same patch
-- add at least one usage path/test/manual verification for the new abstraction field
-
-## 5. Context typing degraded
-
-Pattern:
-- prop drilling removed
-- context added with `Record<string, any>`
-
-Impact:
-- type safety lost across all sections
-- future migrations easier to break
-
-What to check:
-- context types in `context.tsx`
-- provider value type and hook return type
-
-How to prevent while coding:
-- copy the concrete page/domain type first, then refactor sections
-- treat context/provider files as typed API boundaries, not temporary plumbing
-
-## 6. Duplicate detail page rendering after CC migration
-
-Pattern:
-- detail page route remains direct (`:id -> Component: DetailPage`) while nested routes are attached
-- `Root` override check uses only `Children.count(children) > 0`
-- non-compound children from route/extensions are treated as full custom composition
-
-Impact:
-- duplicated sections/layout on detail screen
-- visual "double page" rendering
-
-What to check:
-- route topology in `get-route-map.tsx`:
- - parent `:id` should render `Outlet`
- - detail page should be child `path: ""`
-- detail root override guard:
- - activates only for known compound nodes (`Layout`, `Main`, `Sidebar`, etc.)
- - does not switch to custom mode for arbitrary children
-
-How to prevent while coding:
-- use explicit composition guard and shared helper (`src/lib/compound-composition.ts`)
-- follow vendor route structure for nested detail pages
diff --git a/.claude/skills/compound-components-migration-review/references/review-checklist.md b/.claude/skills/compound-components-migration-review/references/review-checklist.md
deleted file mode 100644
index e5dbeff3c..000000000
--- a/.claude/skills/compound-components-migration-review/references/review-checklist.md
+++ /dev/null
@@ -1,63 +0,0 @@
-# Compound Components / TabbedForm Migration Checklist (Implementation + Review)
-
-Use this checklist during coding and again before merge.
-
-## 0. Before Coding (design checks)
-
-- Did you identify the migration type (list / detail+context / tabbed form)?
-- Did you open the vendor/admin reference implementation first?
-- Did you list the current behavioral contracts that must not change (loading/error gating, keyboard shortcuts, dynamic tab visibility)?
-- If moving fetches between components, did you decide where `ready/isPending/isError` logic will live after migration?
-
-## 1. During Coding (behavior-preserving changes)
-
-- `Root` supports child override (`Children.count(children) > 0`)?
-- For detail pages with nested routes/extensions, is override guard explicit (compound nodes only) and not just `Children.count(children) > 0`?
-- Default composition still renders the same page anatomy?
-- Provider wraps default composition (detail pages)?
-- `useContext` hook throws outside provider?
-- Context/provider types remain domain-safe (no new `any`)?
-- If exporting `Main`/`Sidebar`/sections, is there a safe/canonical wrapper (`Layout`)?
-
-## 2. Data / Async Safety
-
-- If fetch moved from parent to child, were `ready`, `isPending`, and `isError` behaviors preserved?
-- Can submit run before required query data exists?
-- Does submit logic have a guard for required async dependencies?
-
-## 3. Keyboard Paths
-
-- `Enter` behavior still matches previous UX?
-- `Ctrl/Cmd+Enter` respects loading/disabled state?
-- Keyboard shortcuts do not bypass critical validation or loading guards?
-
-## 4. TabbedForm / Wizard Behavior
-
-- `validationFields` are actually used by runtime logic?
-- Forward navigation validates only intended tab scope?
-- Backward navigation is unblocked?
-- Dynamic tab visibility (`isVisible`) handles active tab disappearing?
-- No crash when visible tab set changes?
-- If tab metadata was introduced, was runtime wiring added in the same patch?
-
-## 5. Compound Component API
-
-- Exported subcomponents are named consistently and are hard to misuse?
-- Canonical usage example exists (inline comment, doc, or obvious exported `Layout`)?
-- Custom composition path preserves provider/layout/data requirements?
-- Detail route topology for nested pages follows `:id -> Outlet` + child `path: "" -> DetailPage`?
-
-## 6. Typing
-
-- No new `any` or `Record<string, any>` in context/providers?
-- Domain types use `HttpTypes.*` or explicit local aliases?
-- New abstraction APIs are typed and constrained?
-
-## 7. Regression Validation (before merge)
-
-- Manual smoke test default page composition
-- Manual smoke test one custom composition (if API changed)
-- Manual smoke test that detail sections/layout are not duplicated
-- Manual or automated test for keyboard submit
-- Manual or automated test for dynamic tab visibility (if present)
-- Manual or automated test for one async-loading submit dependency path (if present)
diff --git a/.claude/skills/linear-task/SKILL.md b/.claude/skills/linear-task/SKILL.md
index 96ed2ae73..4fb7ec7f0 100644
--- a/.claude/skills/linear-task/SKILL.md
+++ b/.claude/skills/linear-task/SKILL.md
@@ -1,6 +1,6 @@
---
name: linear-task
-description: Pick up a Linear issue from a URL or identifier, drive it end-to-end (read → implement → verify → PR to `canary`), and manage the Linear status columns ("In Progress" → "Waiting For Review", or "Blocked") along the way. Trigger whenever the user pastes a Linear URL (e.g. https://linear.app/rigbyjs/issue/MER-130/...) or a bare identifier like `MER-130`, or says things like "work on", "pick up", "implement", "take this ticket", "do this Linear task", or "ship this issue". Also trigger when the user describes the workflow in their own words ("move it to in progress, do the work, then open a PR") even without naming Linear. Prefer this skill over implementing-and-then-asking-about-status, because the column transitions are the contract: the rest of the team relies on them.
+description: Pick up a Linear issue from a URL or identifier, drive it end-to-end (read → implement → verify → PR to `main`), and manage the Linear status columns ("In Progress" → "Waiting For Review", or "Blocked") along the way. Trigger whenever the user pastes a Linear URL (e.g. https://linear.app/rigbyjs/issue/MER-130/...) or a bare identifier like `MER-130`, or says things like "work on", "pick up", "implement", "take this ticket", "do this Linear task", or "ship this issue". Also trigger when the user describes the workflow in their own words ("move it to in progress, do the work, then open a PR") even without naming Linear. Prefer this skill over implementing-and-then-asking-about-status, because the column transitions are the contract: the rest of the team relies on them.
---
# linear-task
@@ -39,10 +39,10 @@ You do *not* switch branches in the user's current working tree. The user may be
- `bun install`, builds, and the dev server run in the worktree without colliding with their main checkout.
- After the PR merges, the worktree is removed in one command and nothing in the main tree changed.
-Before creating the worktree, just confirm `origin/canary` is fresh:
+Before creating the worktree, just confirm `origin/main` is fresh:
```bash
-git fetch origin canary
+git fetch origin main
```
You don't need to check `git status` of the main tree — you're not going to write to it.
@@ -59,7 +59,7 @@ The worktree lives as a sibling directory to the main repo, named after the issu
```bash
WORKTREE="../mercur-MER-NNN" # sibling of the current repo dir
-git worktree add "$WORKTREE" -b <gitBranchName> origin/canary
+git worktree add "$WORKTREE" -b <gitBranchName> origin/main
cd "$WORKTREE"
bun install # node_modules is per-worktree; install before building
```
@@ -68,7 +68,7 @@ Use Linear's `gitBranchName` verbatim (the team greps PRs by it).
Existing-state cases — handle them, don't paper over them:
-- **Worktree path already exists** (`mercur-MER-NNN` is there from a previous attempt): cd into it, `git fetch origin canary && git rebase origin/canary`, and reuse it. Don't blow it away — it may already contain progress.
+- **Worktree path already exists** (`mercur-MER-NNN` is there from a previous attempt): cd into it, `git fetch origin main && git rebase origin/main`, and reuse it. Don't blow it away — it may already contain progress.
- **Branch with `gitBranchName` already exists** but no worktree: `git worktree add "$WORKTREE" <gitBranchName>` (without `-b`) attaches the existing branch. Then rebase as above.
- **Both already exist and the branch has commits you didn't make**: stop and ask the user before doing anything destructive. Someone else may have been working on this ticket.
@@ -81,7 +81,7 @@ This is the part that varies by ticket. Anchor on:
- **`CLAUDE.md`, `docs/PRODUCT.md`, `docs/ARCHITECTURE.md`, `docs/UI-ARCHITECTURE.md`** — already in your context. The team's conventions live there; follow them.
- **Existing skills** — if the ticket touches admin pages, forms, or tabs, the `admin-page-ui` / `admin-form-ui` / `admin-tab-ui` / `medusa-ui-conformance` skills already encode the rules. Use them; don't re-derive.
- **Tests** — per `CLAUDE.md`: bug fixes and new features must include tests. For a reproducible bug, write the failing test first.
-- **Conventional Commits & branch conventions** — follow the rules in `@CLAUDE.md` (Conventional Commits: `feat(scope):`, `fix(scope):`, `docs:`, `chore:`, `refactor(scope):`; `!` for breaking changes; PRs target `canary`). The scope usually matches the Mercur area (e.g. `orders`, `admin`, `vendor`, `core`). For the branch name itself, use Linear's `gitBranchName` verbatim (see step 4).
+- **Conventional Commits & branch conventions** — follow the rules in `@CLAUDE.md` (Conventional Commits: `feat(scope):`, `fix(scope):`, `docs:`, `chore:`, `refactor(scope):`; `!` for breaking changes; PRs target `main`). The scope usually matches the Mercur area (e.g. `orders`, `admin`, `vendor`, `core`). For the branch name itself, use Linear's `gitBranchName` verbatim (see step 4).
If during implementation you hit something you can't resolve without input — credentials you don't have, an ambiguous spec where two valid interpretations would produce different UX, a dependency on work in another repo — that's a real blocker. Go to step 7b.
@@ -119,7 +119,7 @@ Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>"
git push -u origin <gitBranchName>
-gh pr create --base canary --title "<same as commit subject>" --body "$(cat <<'EOF'
+gh pr create --base main --title "<same as commit subject>" --body "$(cat <<'EOF'
## Summary
<1-3 bullets — what changed and why>
@@ -183,7 +183,7 @@ Auto mode is fine for the happy path, but these warrant a confirmation:
## Mercur-specific defaults
-- **Base branch:** `canary`. Never target `main` directly from this skill.
+- **Base branch:** `main`. All PRs from this skill target `main`.
- **Repo:** `mercurjs/mercur`.
- **Linear team:** `MER`.
- **Status names** are exact: `In Progress`, `Waiting For Review`, `Blocked`. They're case-sensitive in Linear's UI but `save_issue` matches by name; if a lookup fails, list statuses with `mcp__claude_ai_Linear__list_issue_statuses` and use the ID instead.
diff --git a/.claude/skills/medusa-ui-conformance/SKILL.md b/.claude/skills/medusa-ui-conformance/SKILL.md
deleted file mode 100644
index d0c808a0d..000000000
--- a/.claude/skills/medusa-ui-conformance/SKILL.md
+++ /dev/null
@@ -1,126 +0,0 @@
----
-name: medusa-ui-conformance
-description: Keep custom admin and vendor UI aligned with @medusajs/ui and Radix UI. Use when adding or modifying reusable UI, page-level interaction patterns, overlays, menus, form primitives, or any custom component in Mercur dashboards.
----
-
-# Medusa UI Conformance
-
-Use this skill when:
-- adding new custom UI in `packages/admin` or `packages/vendor`
-- modifying reusable UI components or local wrappers
-- introducing dropdowns, dialogs, drawers, tabs, accordions, tooltips, popovers, selects, or other interactive primitives
-- deciding whether a new UI need should use an existing component, a wrapper, or a new primitive-based component
-
-This skill is the system-level gate for Mercur dashboard UI.
-
-Apply this decision order:
-1. use an existing local wrapper or established package pattern
-2. use `@medusajs/ui`
-3. compose with `@medusajs/ui` plus existing local wrappers
-4. use `Radix UI` primitives only if the previous options do not cover the interaction
-5. build a new reusable local component only when the UI gap is real and reusable
-
-## First checks
-
-Before writing custom UI, check:
-- whether the same pattern already exists in `components/common`, `components/layout`, `components/modals`, or page-local shared components
-- whether `@medusajs/ui` already provides the needed primitive or pattern
-- whether the task is really page/form/tab work and should also load `admin-page-ui`, `admin-form-ui`, or `admin-tab-ui`
-
-## Hard rules
-
-1. Do not build a custom dropdown, dialog, drawer, tooltip, popover, select, accordion, tabs, or button if `@medusajs/ui` already covers it.
-2. Do not import `radix-ui` or `@radix-ui/*` just because it feels lower-level or more flexible. Use it only when `@medusajs/ui` does not cover the case.
-3. Do not add page-local one-off interaction primitives if the pattern is reusable. Put reusable UI in shared components.
-4. Do not ship custom interactive UI without keyboard behavior, focus management, and accessible labeling.
-5. Do not hardcode visual language outside Mercur and Medusa conventions. Prefer Medusa UI components, tokens, spacing, and composition.
-6. Do not use `asChild` with a child component that fails to spread props or forward refs.
-7. Do not bypass existing local wrappers such as `Form`, `ActionMenu`, route modal wrappers, or other shared abstractions when they already solve the problem.
-8. Do not introduce custom UI copy without i18n and stable `data-testid` coverage for important interaction points.
-
-## Decision tree
-
-### 1. Local wrapper first
-
-Prefer existing Mercur wrappers when the pattern already exists.
-
-Typical examples in this repo:
-- `Form` wrappers for field composition and accessibility
-- `ActionMenu` for row and section actions
-- route-level drawer or modal wrappers
-- shared layout primitives such as pages, sections, and empty states
-
-If a local wrapper exists, extend or reuse it instead of rebuilding the interaction from scratch.
-
-### 2. `@medusajs/ui` second
-
-If no local wrapper fits, prefer `@medusajs/ui`.
-
-Use Medusa UI for:
-- buttons, inputs, textareas, badges, headings, text
-- drawers, modals, prompts, dropdown menus, tooltips, popovers
-- containers, tabs, progress tabs, tables, labels, hints
-
-Default assumption:
-- visual styling comes from `@medusajs/ui`
-- interaction semantics should stay compatible with `@medusajs/ui`
-
-### 3. Compose before inventing
-
-If the exact UI does not exist, first try to compose it from:
-- `@medusajs/ui`
-- existing local wrappers
-- existing package layout primitives
-
-Prefer composition over custom primitives when the behavior is mostly already solved.
-
-### 4. Radix only for genuine gaps
-
-Use Radix only when you need a lower-level primitive not already covered well enough by `@medusajs/ui` or local wrappers.
-
-Good reasons:
-- custom composite control behavior
-- advanced accordion, dialog, collapsible, popover, or slot composition
-- accessibility primitives for a reusable shared component
-
-Bad reasons:
-- wanting to restyle a solved Medusa UI component
-- avoiding an existing local wrapper
-- building page-local novelty UI
-
-## `asChild` and composition rules
-
-Mercur already uses `asChild` heavily. When composing with Medusa UI or Radix:
-- the child component must spread incoming props
-- the child component must forward the ref
-- the child component must preserve semantic element behavior
-
-If those conditions are not true, do not use `asChild`.
-
-## Where new reusable UI should live
-
-If you genuinely need a new shared component:
-- place it under the relevant shared components area, usually `components/common`, `components/layout`, or another existing shared subtree
-- give it an API that feels consistent with Medusa UI and Mercur wrappers
-- keep styling and spacing compatible with existing dashboard patterns
-- prefer a reusable abstraction over page-local duplication
-
-If the UI is only page-specific and not reusable, keep it local, but still build it from Medusa UI and existing wrappers.
-
-## Review checklist
-
-Before finishing, check:
-- did I reuse a local wrapper where one already exists?
-- if not, did I prefer `@medusajs/ui`?
-- if I used Radix, is there a concrete gap that justified it?
-- if I used `asChild`, does the child spread props and forward refs?
-- is the UI translated, accessible, and testable?
-- did I avoid introducing a parallel design language or one-off primitive?
-
-## Verification
-
-For non-trivial custom UI:
-- run the relevant package lint/build
-- manually check keyboard behavior and focus flow
-- verify translated copy and labels
-- verify visible loading, empty, error, and success behavior where applicable
diff --git a/.claude/skills/mercur-blocks/SKILL.md b/.claude/skills/mercur-blocks/SKILL.md
deleted file mode 100644
index 3c315638f..000000000
--- a/.claude/skills/mercur-blocks/SKILL.md
+++ /dev/null
@@ -1,76 +0,0 @@
----
-name: mercur-blocks
-description: Discover, evaluate, install, and verify Mercur blocks safely using `blocks.json` aliases and Mercur CLI workflows. Use when adding or updating blocks in a Mercur project.
-argument-hint: "[block-name]"
----
-
-# Mercur Blocks Workflow
-
-Use this skill when:
-- evaluating whether a block fits a project
-- adding a block through Mercur CLI
-- reviewing the impact of an installed block
-- updating a block and checking for drift
-
-## Read first
-
-Start with:
-- project root `blocks.json`
-- the Mercur CLI command that matches the task: `search`, `view`, `add`, or `diff`
-
-## `blocks.json` alias model
-
-In the basic starter, aliases route block files into:
-- `api` -> `packages/api/src`
-- `admin` -> `apps/admin/src`
-- `vendor` -> `apps/vendor/src`
-
-Always reason about a block by alias destination, not just by the block name.
-
-## Decision flow
-
-1. Search for the block if the exact name is not known.
-2. View the block before adding it.
-3. Identify which aliases and workspaces it will touch.
-4. Add the block.
-5. Inspect installed files and configuration impact.
-6. Run the smallest relevant verification set.
-
-## Post-install checklist
-
-- Which aliases were used: `api`, `admin`, `vendor`?
-- Did the block add routes, modules, links, workflows, or subscribers?
-- Does `packages/api/medusa-config.ts` need module registration or options?
-- Did the block add API routes that require route type codegen?
-- Did the block add UI routes that require admin or vendor build verification?
-- Did the block include docs telling the user to configure env vars, providers, or middleware?
-
-## Useful commands
-
-```bash
-npx @mercurjs/cli@canary search --query <keyword>
-npx @mercurjs/cli@canary view <block>
-npx @mercurjs/cli@canary add <block>
-npx @mercurjs/cli@canary diff <block>
-```
-
-## Verification defaults
-
-- Backend touched: run backend build and the relevant tests
-- Admin touched: run admin build or lint
-- Vendor touched: run vendor build or lint
-- Routes or SDK types touched: run codegen and confirm generated types still make sense
-
-## Avoid
-
-- adding a block without checking its docs or install impact first
-- assuming a block only writes into one workspace
-- leaving `medusa-config.ts` or env setup stale after install
-- updating blocks blindly without checking `diff`
-
-## Output expectations
-
-When summarizing a block task:
-- name the block
-- list which aliases/workspaces it touched
-- state any config, codegen, or verification follow-up
diff --git a/.claude/skills/mercur-cli/SKILL.md b/.claude/skills/mercur-cli/SKILL.md
deleted file mode 100644
index 184d1b085..000000000
--- a/.claude/skills/mercur-cli/SKILL.md
+++ /dev/null
@@ -1,85 +0,0 @@
----
-name: mercur-cli
-description: Use Mercur CLI commands correctly for project setup, block discovery, block installation, and starter maintenance. Use when working with `create`, `init`, `add`, `search`, `view`, or `diff`.
-argument-hint: "[command]"
----
-
-# Mercur CLI
-
-Use this skill when:
-- creating a new Mercur project
-- initializing `blocks.json`
-- searching for blocks
-- viewing block details before installation
-- adding blocks to a project
-- diffing installed blocks against the registry
-
-## Command map
-
-- `create` — create a new Mercur project from a template
-- `init` — create `blocks.json` in an existing project
-- `search` — search block names and descriptions
-- `view` — inspect a block before adding it
-- `add` — install one or more blocks into a project
-- `diff` — compare installed block files with the registry version
-
-## Workdir rules
-
-- Run CLI registry commands from the project root where `blocks.json` lives.
-- Run backend verification from the backend workspace after installation if the block touched backend code.
-- Prefer the package manager selected by the project instead of hardcoding `npm`.
-
-## Starter flows
-
-### Create a new project
-
-```bash
-npx @mercurjs/cli@canary create my-mercur --template basic
-```
-
-### Initialize block config in an existing project
-
-```bash
-npx @mercurjs/cli@canary init
-```
-
-### Discover and inspect blocks
-
-```bash
-npx @mercurjs/cli@canary search --query review
-npx @mercurjs/cli@canary view reviews
-```
-
-### Add a block
-
-```bash
-npx @mercurjs/cli@canary add reviews
-```
-
-### Check a block against the registry
-
-```bash
-npx @mercurjs/cli@canary diff reviews
-```
-
-## After `add`
-
-Always inspect what changed:
-- where files landed based on `blocks.json` aliases
-- whether `medusa-config.ts` needs a module or config update
-- whether route or SDK types require codegen
-- whether build or tests need to run in touched workspaces
-
-## Avoid
-
-- guessing block names without `search` or `view`
-- running `add` outside the project root
-- assuming blocks are UI-only; many also add backend modules, routes, or workflows
-- skipping post-install review of changed files and configuration
-
-## Output expectations
-
-When using the CLI in a task summary:
-- name the command used
-- explain why that command was chosen instead of another
-- call out any follow-up verification still required
diff --git a/.claude/skills/migration-guide/SKILL.md b/.claude/skills/migration-guide/SKILL.md
deleted file mode 100644
index afc71462f..000000000
--- a/.claude/skills/migration-guide/SKILL.md
+++ /dev/null
@@ -1,74 +0,0 @@
----
-name: migration-guide
-description: Plan and execute migration from Mercur 1.x to 2.0. Classifies project difficulty, reads relevant migration docs, and follows stop conditions.
-argument-hint: "[path-to-old-project]"
----
-
-# Migration Guide Workflow
-
-Use this skill when:
-- Planning a migration from Mercur 1.x to 2.0
-- Executing migration steps for a specific project
-- Evaluating migration feasibility or effort
-
-## Read first
-
-Before any action, read:
-1. `docs/migrations/mercur-1.x-to-2.0/README.md` — entry point, version check, package/directory mapping, approach
-
-## Workflow
-
-### Step 1: Classify the project
-
-Read `references/decision-tree.md` in this skill directory, then:
-
-1. Inventory the source project:
- - Read `package.json` — note `@mercurjs/b2c-core` version to determine 1.x version
- - If version < 1.4.0: custom admin code is inside the backend repo (not `apps/admin/`) — search there when scanning for custom dashboard pages
- - Count custom modules, workflows, API routes, subscribers, links
- - Identify third-party integrations
- - Note custom admin/vendor pages
-2. Classify as: **starter**, **light-custom**, or **heavy-custom**
-3. Communicate the classification and its implications to the user
-
-### Step 2: Read relevant migration docs
-
-Based on classification, read from `docs/migrations/mercur-1.x-to-2.0/`:
-
-| Document | Starter | Light Custom | Heavy Custom |
-|----------|---------|-------------|-------------|
-| README.md | Required | Required | Required |
-| dashboards.md | Skim | Required | Required |
-
-### Step 3: Execute migration
-
-1. Set up fresh 2.0 project (see README.md)
-2. Update `medusa-config.ts` (plugins, modules, providers)
-3. Add registry blocks (`bunx @mercurjs/cli@latest add <block>`)
-4. Port custom backend code in order: providers → modules → workflows → links → subscribers → API routes → middlewares
-5. Port dashboard code (if applicable)
-6. Verify at each checkpoint
-
-### Step 4: Verify completion
-
-- Server starts without errors
-- All custom endpoints respond
-- Dashboard builds without errors
-- Custom pages render in browser
-
-## Stop conditions
-
-Stop and ask the user when:
-- A custom module depends on internal APIs not exposed in `@mercurjs/core`
-- A third-party integration (Resend, Stripe Connect, Stripe Tax) is a launch blocker and has no 2.0 equivalent
-- Database schema conflicts cannot be resolved with standard migrations
-- The project uses MedusaJS core modifications
-- You cannot classify the project's difficulty level
-- A verification checkpoint fails with an unclear root cause
-
-## Avoid
-
-- Do not attempt in-place upgrades of 1.x projects
-- Do not install 1.x packages in a 2.0 project
-- Do not skip verification checkpoints
-- Do not reference or depend on `.migration/` or any private test directories
diff --git a/.claude/skills/migration-guide/references/decision-tree.md b/.claude/skills/migration-guide/references/decision-tree.md
deleted file mode 100644
index 914481886..000000000
--- a/.claude/skills/migration-guide/references/decision-tree.md
+++ /dev/null
@@ -1,57 +0,0 @@
-# Migration Difficulty Decision Tree
-
-Use this tree to classify a project before starting migration.
-
-## Step 1: Custom modules?
-
-Does the 1.x project have custom MedusaJS modules (not from `@mercurjs/b2c-core` or standard packages)?
-
-- **No** → go to Step 2
-- **Yes** → classify as **heavy-custom** (minimum)
-
-## Step 2: Custom workflow count
-
-How many custom workflows exist (beyond those provided by Mercur packages)?
-
-- **0** → go to Step 3
-- **1–5** → go to Step 3 (light-custom candidate)
-- **> 5** → go to Step 4
-
-## Step 3: Custom endpoints
-
-How many custom API endpoints exist?
-
-- **0** → **Starter**
-- **1–10** with ≤ 5 workflows → **Light custom**
-- **> 10** → **Heavy custom**
-
-## Step 4: Dashboard customization
-
-How extensive are admin/vendor dashboard changes?
-
-- **No custom pages, only config** → stays at current level
-- **< 5 custom pages, no custom extensions** → stays at current level
-- **Custom pages + widget zones + custom hooks** → **Heavy custom**
-
-## Step 5: Third-party integrations
-
-Does the project use integrations beyond what 2.0 supports?
-
-- **No** (only Stripe standard, Algolia via block, etc.) → stays at current level
-- **Yes** (Stripe Connect, Resend, TalkJS, custom providers) → elevate to at least **light-custom**, check `docs/migrations/mercur-1.x-to-2.0/README.md` for the known-gaps section
-
-## Summary Matrix
-
-| Indicator | Starter | Light Custom | Heavy Custom |
-|-----------|---------|-------------|-------------|
-| Custom modules | 0 | 0 | ≥ 1 |
-| Custom workflows | 0 | 1–5 | > 5 |
-| Custom API endpoints | 0 | 1–10 | > 10 |
-| Custom admin/vendor pages | 0 | 0–5 | > 5 or extensions |
-| No-equivalent integrations | 0 | 0–1 (non-blocking) | ≥ 1 (may block) |
-
-## Edge Cases
-
-- **Custom storefront only, no backend changes**: Still **starter** for Mercur migration (storefront is out of scope)
-- **Many workflows but all from registry blocks**: **Light custom** (block workflows are managed by the block)
-- **Custom modules but < 5 workflows**: Still **heavy-custom** (modules are the complexity driver)