@thorprovider/adapters 4.2.0 → 4.2.2

package/docs/RETRY_SOLUTION_SUMMARY.md

@@ -1,13 +1,24 @@
-# Resumen Ejecutivo - Solución a Errores de Fetch
+---
+title: Retry Solution Summary
+purpose: Executive summary of the fetch retry and circuit breaker resilience solution
+type: reference
+tags: [resilience, retry, fetch, summary]
+related:
+  - fetch-reliability-solution.md
+updated: 2026-05-03
+---
+
+# Resumen Ejecutivo — Solución a Errores de Fetch
 
 ## ❌ Problema
 Errores frecuentes `Failed to fetch products: fetch failed` en el V0 starter al cargar productos desde el backend de Medusa.
 
 ## ✅ Solución Implementada
 
-### 1. Nuevo Módulo de Retry Logic (`fetch-utils.ts`)
+### 1. Módulo de Retry Logic (`fetch-utils.ts`)
 - **Ubicación**: `packages/adapters/src/core/fetch-utils.ts`
-- **Funcionalidad**: 
+- **Importación**: utilidad interna — no está re-exportada desde `@thorprovider/adapters`. Úsala dentro del paquete como `import { fetchWithRetry } from '../core/fetch-utils'`.
+- **Funcionalidad**:
   - Reintentos automáticos con exponential backoff
   - Timeout configurable (10s por defecto)
   - Detección inteligente de errores retryables
@@ -17,10 +28,14 @@ Errores frecuentes `Failed to fetch products: fetch failed` en el V0 starter al
 - **Ubicación**: `packages/adapters/src/providers/medusa/index.ts`
 - **Cambios**:
   - Nueva propiedad `retry?: RetryConfig` en `MedusaProviderConfig`
-  - Método privado `withRetry()` que envuelve todas las llamadas al SDK
-  - Métodos `getProduct()` y `getProducts()` actualizados para usar retry logic
+  - Custom fetch inyectado en el constructor del SDK
+
+### 3. Circuit Breaker (implementado)
+- **Ubicación**: `packages/adapters/src/resilience/`
+- **Estado**: ✅ Implementado y exportado desde `@thorprovider/adapters`
+- **Uso**: `import { CircuitBreaker, backendCircuitBreaker } from '@thorprovider/adapters'`
 
-### 3. Configuración por Defecto en V0 Starter
+### 4. Configuración por Defecto en V0 Starter
 - **Ubicación**: `packages/core/lib/commerce.ts`
 - **Configuración**:
   ```typescript
@@ -33,7 +48,7 @@ Errores frecuentes `Failed to fetch products: fetch failed` en el V0 starter al
   }
   ```
 
-## 📊 Impacto Esperado
+## 📊 Impacto
 - **90-98% reducción** en errores visibles al usuario
 - Resiliencia ante problemas de red transitorios
 - Mejor experiencia de usuario sin interrupciones
@@ -41,15 +56,15 @@ Errores frecuentes `Failed to fetch products: fetch failed` en el V0 starter al
 ## 🧪 Estado
 - ✅ Código compila sin errores TypeScript
 - ✅ Build de adapters exitoso
-- ✅ Build de elements exitoso
-- ✅ Documentación completa creada
-- 🔄 Pendiente: Testing en dev/staging
+- ✅ Tests unitarios con vitest (`yarn workspace @thorprovider/adapters test`)
+- ✅ Circuit Breaker implementado
+- 🔄 Pendiente: Validación en staging con métricas reales
 
 ## 📝 Documentación Completa
 Ver [fetch-reliability-solution.md](./fetch-reliability-solution.md) para análisis detallado de causas, soluciones, y configuraciones avanzadas.
 
 ## 🚀 Next Steps
-1. Probar en desarrollo: `yarn dev:showcase` o `yarn workspace @thorprovider/core dev`
+1. Probar en desarrollo: `yarn workspace @thorprovider/core dev`
 2. Verificar logs en consola mostrando reintentos
 3. Confirmar reducción de errores en producción
 4. (Opcional) Ajustar configuración de retry según métricas reales

package/docs/authentication.md

@@ -1,54 +1,61 @@
-# Authentication
-
 ---
+title: Authentication
+purpose: Guide for setting up and using customer authentication with Thor adapters
 type: how-to
 tags: [auth, security, login, jwt, session, registration]
 related:
   - profile-management.md
   - services-overview.md
   - getting-started.md
-updated: 2026-02-28
+updated: 2026-05-03
 ---
 
+# Authentication
+
 Complete guide to setting up and using authentication with Thor adapters.
 
+> ⚠️ **Backend Disparity:** Authentication is only available on providers that expose an `auth` object. Check `commerce.auth` before calling any auth method. Stel Order and Mock providers do not support customer authentication.
+
 ## Prerequisites
 
-- [Thor Adapters installed](getting-started.md#installation)
+- [Thor Adapters installed](getting-started.md)
 - A Medusa.js v2 backend configured with authentication providers
 
 ## Quick Example
 
 ```typescript
-import { commerce } from '@/lib/commerce';
+import { createProvider } from '@thorprovider/adapters';
+
+const commerce = createProvider({
+  provider: 'medusa',
+  config: {
+    baseUrl: process.env.NEXT_PUBLIC_COMMERCE_API_URL!,
+    publishableKey: process.env.NEXT_PUBLIC_COMMERCE_API_KEY!,
+  },
+});
+
+if (!commerce.auth) throw new Error('Auth not available for this provider');
 
-// Simple login
+// Login
 const { customer } = await commerce.auth.login({
   email: 'user@example.com',
   password: 'SecurePassword123!',
 });
 
-console.log(`Welcome back, ${customer.first_name}!`);
+console.log(`Welcome back, ${customer?.first_name}!`);
 ```
 
 ## Step-by-Step Instructions
 
-### Step 1: Configure Auth Method
+### Step 1: Check Auth Availability
 
-Choose between JWT (SPAs) or Session (SSR) in your provider configuration.
+Not all providers support authentication. Always guard before calling auth methods.
 
 ```typescript
-// lib/commerce.ts
-export const commerce = createProvider({
-  provider: 'medusa',
-  config: {
-    // ... basic config
-    auth: {
-      method: 'jwt',           // Recommended for SPAs
-      storage: 'localStorage', // Where to persist tokens
-    },
-  },
-});
+if (!commerce.auth) {
+  // Provider does not support customer auth (e.g. StelOrder, Mock)
+  return;
+}
 ```
 
 ### Step 2: Handle Registration
@@ -66,69 +73,89 @@ const { customer } = await commerce.auth.register({
 
 ### Step 3: Implement Login Flow
 
-Create a login handler in your UI components.
-
 ```typescript
-async function handleLogin(credentials) {
+async function handleLogin(credentials: { email: string; password: string }) {
+  if (!commerce.auth) throw new Error('Auth not supported');
+
   try {
-    await commerce.auth.login(credentials);
-    // Redirect on success
+    const { customer } = await commerce.auth.login(credentials);
+    return customer;
   } catch (error) {
-    // Handle AuthError
+    // Handle CommerceError / invalid credentials
+    throw error;
   }
 }
 ```
 
 ### Step 4: Check Auth State
 
-Protect routes or update UI based on authentication status.
-
 ```typescript
 const isAuth = await commerce.auth.isAuthenticated();
 const customer = await commerce.auth.getCurrentCustomer();
 ```
 
-## ✅ DO's
+### Step 5: Logout
 
-1. **Use JWT for Headless SPAs:** It's more flexible and works better across different origins.
-2. **Use Session for SSR:** If you use Next.js Server Components, Session cookies are more secure.
-3. **Handle AuthErrors specifically:** Use `instanceof AuthError` to show user-friendly messages.
-4. **Enable Auto-refresh:** Keep `autoRefresh: true` (default) to ensure seamless user sessions.
-5. **Clear local state on logout:** Always call `commerce.auth.logout()` to clear stored tokens.
+```typescript
+await commerce.auth.logout();
+```
 
-## ❌ DONT's
+## Password Management
 
-1. **Don't store sensitive data in customer object:** Only use public profile fields.
-2. **Don't handle JWT tokens manually:** Let the adapter manage storage and refresh headers.
-3. **Don't use Secret Keys in the browser:** Authentication should only use Publishable Keys.
-4. **Don't ignore the `isAuthenticated` check:** Verify auth status before performing protected operations.
-5. **Don't hardcode login URLs:** The adapter knows where to send requests based on the provider.
+### Request Password Reset
+
+```typescript
+await commerce.auth.requestPasswordReset('user@example.com');
+// Backend sends reset email
+```
 
-## Common Patterns
+### Confirm Password Reset
 
-### Protected Route Hook (React)
 ```typescript
-function useRequireAuth() {
-  const { customer, loading } = useAuth(); // custom hook
-  const router = useRouter();
-
-  useEffect(() => {
-    if (!loading && !customer) router.push('/login');
-  }, [customer, loading]);
-  
-  return { customer, loading };
-}
+await commerce.auth.resetPassword(tokenFromEmail, 'NewPassword123!');
 ```
 
-### Server-Side Auth Check (Next.js)
+## Address Management
+
+Auth providers also expose address operations:
+
 ```typescript
-export async function getServerSideProps() {
-  const customer = await commerce.auth.getCurrentCustomer();
-  if (!customer) return { redirect: { destination: '/login' } };
-  return { props: { customer } };
-}
+// List addresses
+const addresses = await commerce.auth.getAddresses();
+
+// Create address
+const address = await commerce.auth.createAddress({
+  firstName: 'Jane',
+  lastName: 'Doe',
+  address1: '123 Main St',
+  city: 'Madrid',
+  postalCode: '28001',
+  countryCode: 'ES',
+});
+
+// Update address
+await commerce.auth.updateAddress(address.id, { city: 'Barcelona' });
+
+// Delete address
+await commerce.auth.deleteAddress(address.id);
 ```
 
+## ✅ DO's
+
+1. **Guard with `commerce.auth`:** Always check the property exists before calling auth methods.
+2. **Use JWT for headless SPAs:** More flexible and works better across different origins.
+3. **Use Session for SSR:** Cookie-based sessions are more secure in server-rendered contexts.
+4. **Handle errors specifically:** Catch and surface meaningful messages to the user.
+5. **Clear state on logout:** Always call `commerce.auth.logout()` to clear stored tokens.
+
+## ❌ DONT's
+
+1. **Don't store sensitive data in the customer object:** Only use public profile fields.
+2. **Don't handle JWT tokens manually:** Let the adapter manage storage and refresh headers.
+3. **Don't use Secret Keys in the browser:** Authentication should only use Publishable Keys.
+4. **Don't ignore the `isAuthenticated` check:** Verify auth status before protected operations.
+5. **Don't import React or Next.js in adapter code:** Keep adapters framework-agnostic.
+
 ## Common Errors & Solutions
 
 ### Error: `AUTH_FAILED`
@@ -148,15 +175,15 @@ export async function getServerSideProps() {
 > ⚠️ **Pitfall 1: CORS issues with Session cookies**
 > Session-based auth requires matching domains or properly configured `cross-site` cookies in the backend.
 
-> ⚠️ **Pitfall 2: LocalStorage availability in SSR**
-> Ensure token management logic checks for `window` availability if using `localStorage`.
+> ⚠️ **Pitfall 2: `commerce.auth` is undefined**
+> Not all providers implement auth. Always check `if (commerce.auth)` before calling any method.
 
 ## Troubleshooting
 
 | Issue | Solution |
 |-------|----------|
-| Token not sent in headers | Check if `auth.method` matches backend expectation |
-| Login works but profile fails | Verify `storage` type is correctly configured and working |
+| Token not sent in headers | Verify the provider config and that `publishableKey` is set |
+| Login works but profile fails | Ensure `commerce.auth.getCurrentCustomer()` is called after login |
 | Infinite login loop | Check cookie path and domain settings on the backend |
 
 ## Next Steps

package/docs/capabilities-system.md

@@ -1,14 +1,16 @@
-# Capabilities System
-
 ---
+title: Capabilities System
+purpose: Reference for backend capability detection and matrices
 type: reference
 tags: [architecture, capabilities, backend, detection]
 related:
   - providers-overview.md
   - services-overview.md
-updated: 2026-02-28
+updated: 2026-05-23
 ---
 
+# Capabilities System
+
 The capabilities system exposes which operations each backend provider supports, enabling adaptive UIs across platforms.
 
 ## Quick Reference
@@ -35,27 +37,52 @@ if (commerce.capabilities.updateEmail) {
 | `changePasswordViaEmail` | `boolean` | Supports `requestPasswordReset` method. |
 | `deleteAccount` | `boolean` | Supports `deleteAccount` method. |
 | `uploadAvatar` | `boolean` | Supports native file upload for avatars. |
+| `avatarViaMetadata` | `boolean` | Can store avatar URL in customer metadata/attributes. |
+| `customAttributes` | `boolean` | Supports custom customer attributes/metadata. |
+
+### Order Management
+
+| Capability | Type | Description |
+|------------|------|-------------|
+| `fetchOrders` | `boolean` | Can fetch customer order history. |
+| `cancelOrder` | `boolean` | Can cancel orders before fulfillment. |
+
+### Address Management
+
+| Capability | Type | Description |
+|------------|------|-------------|
+| `manageAddresses` | `boolean` | Can add/update/delete shipping addresses. |
+| `defaultAddress` | `boolean` | Can set a default shipping address. |
+
+### Cart & Checkout
 
-### Cart Operations
+| Capability | Type | Description |
+|------------|------|-------------|
+| `applyDiscounts` | `boolean` | Can apply discount codes to cart. |
+| `shippingCalculation` | `boolean` | Can calculate shipping rates before checkout. |
+| `guestCheckout` | `boolean` | Supports checkout without an account. |
+| `savedPaymentMethods` | `boolean` | Can save payment methods for future use. |
+| `listPaymentProviders` | `boolean` | Can list available payment providers dynamically. |
+| `regionSpecificPayments` | `boolean` | Payment providers vary by region. |
+
+### Discovery & Search
 
 | Capability | Type | Description |
 |------------|------|-------------|
-| `cartPromoCode` | `boolean` | Can apply discount/promo codes to cart. |
-| `cartGiftCards` | `boolean` | Supports gift card application. |
-| `cartNotes` | `boolean` | Supports order/cart notes. |
-| `cartCustomAttributes` | `boolean` | Supports metadata/attributes at cart level. |
+| `advancedSearch` | `boolean` | Supports full-text / filtered product search. |
+| `facetedFilters` | `boolean` | Supports faceted filtering by attributes. |
 
-### Product & Discovery
+### Social & Loyalty
 
 | Capability | Type | Description |
 |------------|------|-------------|
-| `productVariants` | `boolean` | Backend supports multiple variants per product. |
-| `productCategories` | `boolean` | Supports nested categories or collections. |
-| `productInventory` | `boolean` | Real-time inventory tracking available. |
-| `productDigital` | `boolean` | Supports digital/downloadable products. |
-| `productReviews` | `boolean` | Native review system support. |
+| `productReviews` | `boolean` | Native product reviews/ratings system. |
+| `wishlist` | `boolean` | Native wishlist/favorites feature. |
+| `loyaltyProgram` | `boolean` | Native loyalty/rewards program. |
+
+## Type Definition (source of truth)
 
-## Type Definitions
+> Canonical source: `packages/types/src/commerce-provider.ts` — `BackendCapabilities`
 
 ```typescript
 export interface BackendCapabilities {
@@ -66,28 +93,33 @@ export interface BackendCapabilities {
   changePasswordViaEmail: boolean;
   deleteAccount: boolean;
   uploadAvatar: boolean;
-  
-  // Avatar Extensions
   avatarViaMetadata: boolean;
-  
-  // Cart
-  cartPromoCode: boolean;
-  cartGiftCards: boolean;
-  cartNotes: boolean;
-  cartCustomAttributes: boolean;
-  
-  // Products
-  productVariants: boolean;
-  productCategories: boolean;
-  productInventory: boolean;
-  productDigital: boolean;
+  customAttributes: boolean;
+
+  // Orders
+  fetchOrders: boolean;
+  cancelOrder: boolean;
+
+  // Addresses
+  manageAddresses: boolean;
+  defaultAddress: boolean;
+
+  // Cart / Checkout
+  applyDiscounts: boolean;
+  shippingCalculation: boolean;
+  guestCheckout: boolean;
+  savedPaymentMethods: boolean;
+  listPaymentProviders: boolean;
+  regionSpecificPayments: boolean;
+
+  // Discovery
+  advancedSearch: boolean;
+  facetedFilters: boolean;
+
+  // Social / Loyalty
   productReviews: boolean;
-  
-  // Auth Integration
-  authJWT: boolean;
-  authSession: boolean;
-  authOAuth: boolean;
-  authPasswordless: boolean;
+  wishlist: boolean;
+  loyaltyProgram: boolean;
 }
 ```
 
@@ -109,15 +141,15 @@ return (
 async function handleAvatarUpdate(file: File) {
   if (caps.uploadAvatar) {
     return await commerce.auth.uploadAvatar(file);
-  } 
-  
+  }
+
   if (caps.avatarViaMetadata) {
     const url = await externalUpload(file);
     return await commerce.auth.updateCustomer({
       metadata: { avatar_url: url }
     });
   }
-  
+
   throw new Error('Avatar updates not supported on this backend');
 }
 ```
@@ -141,3 +173,33 @@ Capabilities are calculated once during provider initialization. Accessing `comm
 
 - [Providers Overview](providers-overview.md)
 - [Services Overview](services-overview.md)
+
+## Per-Provider Capability Matrix
+
+### Stel Order (ERP Adapter)
+
+| Capability | Value | Notes |
+|------------|-------|-------|
+| `fetchOrders` | ✅ true | Read sales orders via `/salesOrders` |
+| `listPaymentProviders` | ✅ true | List STEL payment options via `/paymentOptions` |
+| `manageAddresses` | ✅ true | Via client main-address (PUT /clients) |
+| `updateProfile` | ❌ false | No customer self-service (ERP admin only) |
+| `updateEmail` | ❌ false | — |
+| `changePasswordDirect` | ❌ false | No auth system |
+| `changePasswordViaEmail` | ❌ false | No auth system |
+| `deleteAccount` | ❌ false | — |
+| `uploadAvatar` | ❌ false | — |
+| `avatarViaMetadata` | ❌ false | — |
+| `customAttributes` | ❌ false | — |
+| `cancelOrder` | ❌ false | ERP orders are read-only from adapter |
+| `defaultAddress` | ❌ false | — |
+| `applyDiscounts` | ❌ false | No cart/checkout |
+| `shippingCalculation` | ❌ false | No cart/checkout |
+| `guestCheckout` | ❌ false | No cart/checkout |
+| `savedPaymentMethods` | ❌ false | — |
+| `regionSpecificPayments` | ❌ false | Single-company ERP |
+| `wishlist` | ❌ false | — |
+| `advancedSearch` | ❌ false | Client-side text filter only |
+| `facetedFilters` | ❌ false | — |
+| `productReviews` | ❌ false | — |
+| `loyaltyProgram` | ❌ false | — |

package/docs/category-customization.md

@@ -1,3 +1,15 @@
+---
+title: Category Customization & Inheritance
+purpose: Explains the 5-phase system for hiding, renaming, and adding custom categories on top of backend-provided ones
+type: guide
+tags: [categories, customization, metadata, multi-tenant, architecture]
+related:
+  - providers-overview.md
+  - services-overview.md
+  - multi-tenant-channel-scoping.md
+updated: 2026-05-03
+---
+
 # Category Customization & Inheritance
 
 ## The Problem (Simple Version)
@@ -58,7 +70,7 @@ Your store sells **only shoes**. But the backend (Medusa) gives you 10 categorie
     "hidden": ["sandalias"],
     "renamed": { "accesorios": "Extras" },
     "custom": [
-      { "id": "bestsellers", "name": "Bestsellers", ... }
+      { "id": "bestsellers", "name": "Bestsellers" }
     ]
   }
 }
@@ -74,7 +86,9 @@ What is a customization?
 → { hidden: ["id1", "id2"], renamed: {id: "newname"}, custom: [{...}] }
 ```
 
-We define this **once** in `@thorprovider/types` so every layer speaks the same language.
+Defined once in `@thorprovider/types` so every layer speaks the same language.
+
+> ⚠️ **Implementation status**: Category customization types are planned but not yet merged into `@thorprovider/types`. This document describes the intended architecture.
 
 ---
 
@@ -87,12 +101,12 @@ BackendMetadataAdapter
 Your customizations
 ```
 
-**Key principle**: We use the backend's native **metadata storage**, not a separate database.
+**Key principle**: Uses the backend's native **metadata storage**, not a separate database.
 
 Why?
 - **Simple**: No external SQLite/Supabase
 - **Multi-tenant ready**: Each sales channel has its own metadata
-- **Agnóstic**: Medusa, Shopify, WordPress — same interface
+- **Agnostic**: Medusa, Shopify, WordPress — same interface
 
 ---
 
@@ -114,6 +128,8 @@ Output:
 
 **Why L2?** This is business logic (not UI, not type definition). It belongs with the adapter.
 
+> ⚠️ **Implementation status**: `mergeCategories()` service is planned. Not yet implemented in `packages/adapters/src/`.
+
 ---
 
 ### Phase 4: Expose via API (L5 — Route Handler)
@@ -123,13 +139,12 @@ GET /api/admin/categories
 
 POST /api/admin/categories
 → Dashboard sends new customizations, backend saves them
-
-PUT /api/admin/categories
-→ (Optional) Update a single category (hide/rename)
 ```
 
 **Why L5?** Only the app knows HTTP. Only the app can validate requests.
 
+> ⚠️ **Implementation status**: API route is planned. Not yet implemented in `packages/core/`.
+
 ---
 
 ### Phase 5: Dashboard UI (L4 — Component)
@@ -149,18 +164,17 @@ PUT /api/admin/categories
 │ ✨ Bestsellers                  │
 │    [Edit] [Delete]              │
 ├─────────────────────────────────┤
-│                                 │
 │     [+ Add Custom]  [Save]      │
 └─────────────────────────────────┘
 ```
 
-**Why L4?** Reusable component (could work in different apps). Doesn't know about HTTP/databases.
+> ⚠️ **Implementation status**: Dashboard component is planned. Not yet implemented in `packages/components/`.
 
 ---
 
-## Why This Architecture Is "Agnóstic"
+## Why This Architecture Is "Agnostic"
 
-**Agnóstic** = "Works with any backend, no vendor lock-in."
+**Agnostic** = "Works with any backend, no vendor lock-in."
 
 ### Data Flow
 
@@ -176,7 +190,6 @@ PUT /api/admin/categories
 │    BackendMetadataAdapter (Interface)│
 │ - getMetadata()                      │
 │ - setMetadata()                      │
-│ (Same methods for all backends)      │
 └──────────┬───────────────────────────┘
            │ (Phase 3: mergeCategories)
            ↓
@@ -210,8 +223,6 @@ PUT /api/admin/categories
 - Phase 4 (API route)
 - Phase 5 (UI component)
 
-**Why?** All non-Phase-2 code depends on the **interface**, not the **implementation**.
-
 ---
 
 ## Key Concepts
@@ -243,21 +254,17 @@ Medusa: sales_channel.metadata = { category_customizations: {...} }
 Shopify: custom field or app data store (same interface)
 ```
 
-Result: One less database to maintain.
-
 ---
 
 ## Implementation Order (For Next Agent)
 
-See `.development-guides/category-customization-implementation.md` for detailed step-by-step.
-
 **TL;DR:**
-1. Add types in L1
-2. Extend metadata adapter in L2
+1. Add types in L1 (`@thorprovider/types`)
+2. Extend metadata adapter in L2 (`BackendMetadataAdapter`)
 3. Create `mergeCategories()` service in L2
 4. Integrate into `CommerceProvider.getCategories()` in L2
-5. Create API route in L5
-6. Create UI component in L4
+5. Create API route in L5 (`packages/core/app/api/admin/categories/route.ts`)
+6. Create UI component in L4 (`packages/components/`)
 7. Integrate into dashboard in L5
 
 ---
@@ -299,11 +306,12 @@ Storefront should render it like base categories.
 
 ## Related Files
 
-- **Implementation plan**: `.development-guides/category-customization-implementation.md`
-- **Types**: `packages/types/src/admin/category-customizations.ts`
-- **Metadata adapter**: `packages/adapters/src/backend/BackendMetadataAdapter.ts`
-- **Service**: `packages/adapters/src/services/category-service.ts`
-- **Provider integration**: `packages/adapters/src/providers/medusa/index.ts` (getCategories)
-- **API route**: `packages/core/app/api/admin/categories/route.ts`
-- **Component**: `packages/components/src/patterns/modules/dashboard/CategoryCustomization.tsx`
+> ⚠️ The following files are **planned** and do not yet exist in the codebase:
 
+| File | Status |
+|------|--------|
+| `packages/types/src/admin/category-customizations.ts` | 🗓️ Planned |
+| `packages/adapters/src/backend/BackendMetadataAdapter.ts` | ✅ Exists (extend for categories) |
+| `packages/adapters/src/services/category-service.ts` | 🗓️ Planned |
+| `packages/core/app/api/admin/categories/route.ts` | 🗓️ Planned |
+| `packages/components/src/patterns/modules/dashboard/CategoryCustomization.tsx` | 🗓️ Planned |