feat(ecommerce): ADR 0009 - checkout con direccion y seleccion de envio

Siguiente corte tras el carrito real: pagina /checkout de 3 pasos
(direccion -> envio -> confirmar) contra el Store API real, usando la
shipping option que ya se verifico en produccion. Endpoints nuevos
(setShippingAddress, getShippingOptions, addShippingMethod) probados
en vivo con un carrito de prueba real antes de escribir el codigo --
direccion, opciones de envio y total ya confirmados correctos
(80.000 + 5.000 = 95.000).

El pago (PayU custom) sigue sin existir, asi que el ultimo paso sigue
siendo WhatsApp -- pero ahora el mensaje incluye direccion, metodo de
envio y total real en vez de solo la lista de productos. El boton del
CartDrawer pasa de abrir WhatsApp directo a llevar a /checkout.

.gitea/workflows/build.yaml

@@ -122,11 +122,12 @@ jobs:
     needs: gitleaks
     if: github.event_name == 'push'
     runs-on: ubuntu-latest
-    timeout-minutes: 20
+    timeout-minutes: 30
 
     env:
       APP_DIR: workloads/ecommerce
       MANIFEST_FILE: workloads/ecommerce/frontend/patches/deployment.yaml
+      KUSTOMIZE_DIR: workloads/ecommerce/frontend
       IMAGE_NAME: gitea.cruzcloud.net/devops/ecommerce-frontend
 
     steps:
@@ -213,22 +214,25 @@ jobs:
             exit 1
           }
 
-          grep -q 'currentCollection' "${NAVBAR_FILE}" || {
-            echo "ERROR: navbar.tsx no calcula currentCollection."
+          # Desde Etapa 2 sub-fase 2 (2026-08-25) el nav es data-driven
+          # contra el arbol real de categorias de Medusa, no un array
+          # hardcodeado -- esta version anterior del check no detectaba
+          # que "category=Mochilas"/"collection=Marvel" eran strings
+          # hardcodeadas que ya no correspondian a ningun dato real (rotas
+          # en silencio desde que se elimino legacyProductMeta, PR #29).
+          # "currentCollection" tampoco existe mas: las colecciones ya no
+          # se usan para resaltar el item activo del menu de categorias.
+          grep -q 'buildCategoryTree' "${NAVBAR_FILE}" || {
+            echo "ERROR: navbar.tsx ya no arma el arbol de categorias desde datos reales."
             exit 1
           }
 
-          grep -q 'collection=Marvel' "${NAVBAR_FILE}" || {
-            echo "ERROR: falta collection=Marvel en navbar.tsx."
+          grep -q 'encodeURIComponent(root.name)' "${NAVBAR_FILE}" || {
+            echo "ERROR: navbar.tsx ya no linkea por el nombre real de categoria."
             exit 1
           }
 
-          grep -q 'category=Mochilas' "${NAVBAR_FILE}" || {
-            echo "ERROR: falta category=Mochilas en navbar.tsx."
-            exit 1
-          }
-
-          grep -q 'aria-current={active ? "page" : undefined}' "${NAVBAR_FILE}" || {
+          grep -q 'aria-current={isActive(' "${NAVBAR_FILE}" || {
             echo "ERROR: navbar.tsx no expone correctamente el menú activo."
             exit 1
           }
@@ -257,7 +261,7 @@ jobs:
 
           echo "Validando remontaje por parámetros: ${PAGE_FILE}"
 
-          grep -q 'key={`${category}:${collection}:${query}:${section}`}' "${PAGE_FILE}" || {
+          grep -q 'key={`${category}:${collection}:${query}`}' "${PAGE_FILE}" || {
             echo "ERROR: app/catalog/page.tsx no remonta CatalogClient al cambiar la URL."
             exit 1
           }
@@ -276,6 +280,32 @@ jobs:
           chmod +x /tmp/trivy
           /tmp/trivy version
 
+      - name: Instalar kubectl
+        shell: bash
+        run: |
+          set -euo pipefail
+          KUBECTL_VERSION="v1.31.2"
+          curl -sSfL \
+            "https://dl.k8s.io/release/${KUBECTL_VERSION}/bin/linux/amd64/kubectl" \
+            -o /tmp/kubectl
+          chmod +x /tmp/kubectl
+          /tmp/kubectl version --client
+
+      # ${MANIFEST_FILE} es solo el patch de Kustomize del Deployment, no el
+      # manifiesto que de verdad corre en el clúster -- escanearlo directo
+      # generaba falsos positivos en todo lo que hereda del base remoto de
+      # platform-templates (runAsNonRoot, seccompProfile), porque ese patch
+      # nunca repite lo que ya trae el base (visto en vivo 2026-08-24:
+      # comparando el patch aislado contra el output real de
+      # "kubectl kustomize", 2 de 5 hallazgos desaparecían). Renderizamos el
+      # kustomization completo (${KUSTOMIZE_DIR}, que sí trae el base vía
+      # git remoto) y escaneamos eso.
+      - name: Renderizar manifiesto Kustomize
+        shell: bash
+        run: |
+          set -euo pipefail
+          /tmp/kubectl kustomize "${KUSTOMIZE_DIR}" > /tmp/frontend-rendered.yaml
+
       # Escanea el manifiesto Kubernetes real del frontend (no la imagen):
       # contenedores como root, falta de resource limits, falta de
       # readiness/liveness probes, etc. Informativo por ahora — no bloquea
@@ -287,7 +317,7 @@ jobs:
           /tmp/trivy config \
             --severity CRITICAL,HIGH,MEDIUM \
             --exit-code 0 \
-            "${MANIFEST_FILE}"
+            /tmp/frontend-rendered.yaml
 
       # Instalado directo con pip (no como container aparte): el runner de
       # Gitea ejecuta cada job ya dentro de un contenedor propio que habla
@@ -367,6 +397,12 @@ jobs:
 
       # CRITICAL bloquea el pipeline: no se sube una imagen con una CVE
       # crítica conocida y con fix disponible.
+      # --timeout 15m0s: el default de Trivy (5m) dejó de alcanzar también
+      # para el frontend (visto en vivo: "context deadline exceeded" a los
+      # ~4m45s, en un run justo después de terminar el docker build, con
+      # el host bajo la misma inestabilidad de nodo vista ese día). Mismo
+      # fix ya aplicado en build-medusa.yaml el 2026-08-16 -- el supuesto
+      # de que el frontend era más liviano y no lo necesitaba ya no vale.
       - name: Escanear imagen (Trivy) — CRITICAL bloquea
         shell: bash
         run: |
@@ -375,6 +411,7 @@ jobs:
             --severity CRITICAL \
             --exit-code 1 \
             --ignore-unfixed \
+            --timeout 15m0s \
             "${IMAGE_NAME}:${{ steps.vars.outputs.VERSION }}"
 
       # HIGH solo informa por ahora — no bloquea mientras aprendemos a leer
@@ -387,6 +424,7 @@ jobs:
             --severity HIGH \
             --exit-code 0 \
             --ignore-unfixed \
+            --timeout 15m0s \
             "${IMAGE_NAME}:${{ steps.vars.outputs.VERSION }}"
 
       # SBOM de la imagen que ya pasó el gate de CRITICAL — describe

apps/monitoring-app.yaml

@@ -1,40 +0,0 @@
-apiVersion: argoproj.io/v1alpha1
-kind: Application
-
-metadata:
-  name: monitoring-app
-  namespace: argocd
-
-spec:
-  project: default
-
-  source:
-    repoURL: https://prometheus-community.github.io/helm-charts
-    chart: kube-prometheus-stack
-    targetRevision: 58.3.3
-
-    helm:
-      parameters:
-        - name: prometheusOperator.admissionWebhooks.patch.ttlSecondsAfterFinished
-          value: "60"
-
-      valuesObject:
-        grafana:
-          ingress:
-            enabled: true
-            ingressClassName: traefik
-            hosts:
-              - grafana.cruzcloud.net
-
-  destination:
-    server: https://kubernetes.default.svc
-    namespace: monitoring
-
-  syncPolicy:
-    automated:
-      prune: true
-      selfHeal: true
-
-    syncOptions:
-      - CreateNamespace=true
-      - ServerSideApply=true

apps/monitoring-governance-app.yaml

@@ -1,20 +0,0 @@
-apiVersion: argoproj.io/v1alpha1
-kind: Application
-metadata:
-  name: monitoring-governance
-  namespace: argocd
-spec:
-  project: default
-  source:
-    repoURL: https://gitea.cruzcloud.net/devops/platform-infra.git
-    path: monitoring-governance
-    targetRevision: main
-  destination:
-    server: https://kubernetes.default.svc
-    namespace: monitoring
-  syncPolicy:
-    automated:
-      prune: true
-      selfHeal: true
-    syncOptions:
-      - CreateNamespace=true

workloads/commerce-backend/Dockerfile

@@ -21,7 +21,9 @@ ENV CI=true \
     S3_ACCESS_KEY_ID=build-access-key \
     S3_SECRET_ACCESS_KEY=build-secret-key \
     S3_BUCKET=ari-shopping \
-    S3_ENDPOINT=http://127.0.0.1:9000
+    S3_ENDPOINT=http://127.0.0.1:9000 \
+    MEILISEARCH_HOST=http://127.0.0.1:7700 \
+    MEILISEARCH_API_KEY=build-only-meili-key
 
 COPY package.json package-lock.json .npmrc ./
 

workloads/commerce-backend/medusa-config.ts

@@ -10,6 +10,91 @@ const required = (name: string): string => {
   return value
 }
 
+// Mismos campos derivados de metadata/categories/collection/variants que
+// mapProduct() en workloads/ecommerce/lib/headless/providers/medusa.ts --
+// el documento indexado debe reflejar exactamente lo que el storefront
+// ya muestra, no una vista distinta del catálogo.
+function stringMetadata(
+  metadata: Record<string, unknown> | null | undefined,
+  key: string,
+): string {
+  const value = metadata?.[key]
+  return typeof value === "string" ? value : ""
+}
+
+function booleanMetadata(
+  metadata: Record<string, unknown> | null | undefined,
+  key: string,
+): boolean {
+  const value = metadata?.[key]
+  return value === true || value === "true"
+}
+
+async function meilisearchProductTransformer(
+  document: Record<string, unknown>,
+) {
+  const metadata = (document.metadata ?? null) as Record<
+    string,
+    unknown
+  > | null
+  const categories = document.categories as
+    | Array<{ name?: string | null }>
+    | null
+    | undefined
+  const collection = document.collection as { title?: string | null } | null
+  const variants = document.variants as
+    | Array<{
+        inventory_quantity?: number | null
+        manage_inventory?: boolean | null
+        allow_backorder?: boolean | null
+        prices?: Array<{
+          amount?: number | null
+          currency_code?: string | null
+        }> | null
+      }>
+    | null
+    | undefined
+  const variant = variants?.[0]
+  const tags = document.tags as Array<{ value?: string | null }> | null
+
+  const category =
+    categories?.[0]?.name || stringMetadata(metadata, "category") || "Variedades"
+
+  const available =
+    !variant ||
+    variant.allow_backorder === true ||
+    variant.manage_inventory === false ||
+    (variant.inventory_quantity ?? 0) > 0
+
+  // variants.calculated_price requiere currency_code/region_id en el
+  // contexto de pricing, que el workflow de sync interno del plugin no
+  // provee -- hace fallar TODO el job de indexado (confirmado en vivo:
+  // "Method calculatePrices requires currency_code in the pricing
+  // context"). variants.prices es la lista cruda de precios (sin
+  // resolver promociones/reglas), no necesita contexto -- alcanza para
+  // el filtro/orden por precio en la busqueda, que no necesita el
+  // precio final promocional.
+  const copPrice = variant?.prices?.find(
+    (price) => price.currency_code?.toLowerCase() === "cop",
+  )
+
+  return {
+    id: document.id,
+    name: document.title || "Producto ARI Shopping",
+    shortDescription: document.subtitle || document.title || "",
+    description: document.description || "",
+    category,
+    collection: collection?.title || stringMetadata(metadata, "collection") || "",
+    brand: stringMetadata(metadata, "brand") || "ARI Shopping",
+    ageRange: stringMetadata(metadata, "ageRange") || "Todas",
+    tags: (tags || []).map((tag) => tag.value).filter(Boolean),
+    price: typeof copPrice?.amount === "number" ? copPrice.amount : null,
+    available,
+    isNew: booleanMetadata(metadata, "isNew"),
+    featured: booleanMetadata(metadata, "featured"),
+  }
+}
+
 module.exports = defineConfig({
   projectConfig: {
     databaseUrl: required("DATABASE_URL"),
@@ -73,4 +158,72 @@ module.exports = defineConfig({
       },
     },
   ],
+
+  // ADR 0006 Etapa 2. Sin required(): a diferencia de S3/DB, Meilisearch
+  // es un servicio nuevo y todavia no probado en produccion en un host
+  // con historial de swap saturado -- si esta caido o mal configurado,
+  // el plugin se degrada solo (soporta enabled:false, "silently skipped"
+  // segun su propio README) en vez de tumbar el arranque de Medusa
+  // entero, que es lo que si haria required().
+  plugins: [
+    {
+      resolve: "@rokmohar/medusa-plugin-meilisearch",
+      options: {
+        config: {
+          host: process.env.MEILISEARCH_HOST ?? "",
+          apiKey: process.env.MEILISEARCH_API_KEY ?? "",
+        },
+        settings: {
+          products: {
+            type: "products",
+            enabled: Boolean(process.env.MEILISEARCH_HOST),
+            primaryKey: "id",
+            // Campos que el plugin pide via query.graph antes de pasarlos
+            // al transformer de arriba -- si falta alguno acá, llega
+            // undefined al transformer sin importar lo que este haga.
+            fields: [
+              "id",
+              "title",
+              "subtitle",
+              "description",
+              "handle",
+              "status",
+              "thumbnail",
+              "metadata",
+              "tags.value",
+              "categories.name",
+              "collection.title",
+              "variants.inventory_quantity",
+              "variants.manage_inventory",
+              "variants.allow_backorder",
+              "variants.prices.amount",
+              "variants.prices.currency_code",
+            ],
+            indexSettings: {
+              // Tabla de ADR 0006 §3: Buscable / Filtrable-faceta / Ordenable.
+              searchableAttributes: [
+                "name",
+                "shortDescription",
+                "description",
+                "category",
+                "collection",
+                "brand",
+                "tags",
+              ],
+              filterableAttributes: [
+                "category",
+                "collection",
+                "brand",
+                "ageRange",
+                "price",
+                "available",
+              ],
+              sortableAttributes: ["price", "isNew", "featured"],
+            },
+            transformer: meilisearchProductTransformer,
+          },
+        },
+      },
+    },
+  ],
 })

workloads/commerce-backend/package-lock.json

@@ -12,7 +12,8 @@
         "@medusajs/admin-sdk": "2.18.0",
         "@medusajs/cli": "2.18.0",
         "@medusajs/framework": "2.18.0",
-        "@medusajs/medusa": "2.18.0"
+        "@medusajs/medusa": "2.18.0",
+        "@rokmohar/medusa-plugin-meilisearch": "^1.4.1"
       },
       "devDependencies": {
         "@swc/core": "^1.7.28",
@@ -6561,6 +6562,28 @@
         "node": ">=14.0.0"
       }
     },
+    "node_modules/@rokmohar/medusa-plugin-meilisearch": {
+      "version": "1.4.3",
+      "resolved": "https://registry.npmjs.org/@rokmohar/medusa-plugin-meilisearch/-/medusa-plugin-meilisearch-1.4.3.tgz",
+      "integrity": "sha512-+iStv5sc2vuLk+O7OcQLlNR99fMBhGdBOJMCmDJYoTFGhzBA4ZEV18IIr2xqxUDgdQo1haF0TtYv3JmRQUuY1w==",
+      "license": "MIT",
+      "dependencies": {
+        "meilisearch": "^0.56.0"
+      },
+      "engines": {
+        "node": ">=22"
+      },
+      "peerDependencies": {
+        "@medusajs/admin-sdk": "^2.15.2",
+        "@medusajs/framework": "^2.15.2",
+        "@medusajs/medusa": "^2.15.2",
+        "@medusajs/ui": "^4.1.12",
+        "@tanstack/react-query": "5.64.2",
+        "awilix": "^8.0.1",
+        "react": "^18",
+        "react-dom": "^18"
+      }
+    },
     "node_modules/@rolldown/pluginutils": {
       "version": "1.0.0-beta.27",
       "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-beta.27.tgz",
@@ -11774,6 +11797,12 @@
         "node": ">= 0.6"
       }
     },
+    "node_modules/meilisearch": {
+      "version": "0.56.0",
+      "resolved": "https://registry.npmjs.org/meilisearch/-/meilisearch-0.56.0.tgz",
+      "integrity": "sha512-kBXba8DcSrLWHYqopCm2JL90oBy97VdIfHkP1ii7/eHufeEEEk9Zu5Vv/IFQpNzmhEpWszVFVlGvZoI6QJeGzA==",
+      "license": "MIT"
+    },
     "node_modules/merge-descriptors": {
       "version": "1.0.3",
       "resolved": "https://registry.npmjs.org/merge-descriptors/-/merge-descriptors-1.0.3.tgz",

workloads/commerce-backend/package.json

@@ -14,7 +14,8 @@
     "@medusajs/admin-sdk": "2.18.0",
     "@medusajs/cli": "2.18.0",
     "@medusajs/framework": "2.18.0",
-    "@medusajs/medusa": "2.18.0"
+    "@medusajs/medusa": "2.18.0",
+    "@rokmohar/medusa-plugin-meilisearch": "^1.4.1"
   },
   "devDependencies": {
     "@swc/core": "^1.7.28",

workloads/commerce-backend/src/api/store/search/route.ts

@@ -0,0 +1,197 @@
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework";
+import {
+  ContainerRegistrationKeys,
+  QueryContext,
+} from "@medusajs/framework/utils";
+import {
+  MEILISEARCH_MODULE,
+  type MeiliSearchService,
+} from "@rokmohar/medusa-plugin-meilisearch";
+
+// Las rutas /store/meilisearch/* que trae el plugin (ver ADR 0006 nota de
+// implementacion) no devuelven facetDistribution -- necesitamos esta
+// ruta propia para pedirlo explicitamente via additionalOptions.facets,
+// que el servicio del plugin reenvia tal cual al cliente Meilisearch.
+const FACETS = ["category", "collection", "brand", "ageRange"];
+
+// Mismos campos que ya usa el storefront contra /store/products
+// (workloads/ecommerce/lib/headless/providers/medusa.ts) -- una vez que
+// Meilisearch nos da los ids candidatos, volvemos a Medusa via
+// query.graph para precio/inventario reales, nunca confiamos en el
+// valor indexado (puede tener unos segundos de retraso respecto al
+// evento de sincronizacion).
+const PRODUCT_FIELDS = [
+  "id",
+  "handle",
+  "title",
+  "subtitle",
+  "description",
+  "thumbnail",
+  "external_id",
+  "metadata",
+  "images.url",
+  "tags.value",
+  "categories.name",
+  "collection.title",
+  "variants.id",
+  "variants.title",
+  "variants.sku",
+  "variants.manage_inventory",
+  "variants.allow_backorder",
+  "variants.inventory_quantity",
+  "variants.calculated_price.calculated_amount",
+  "variants.calculated_price.original_amount",
+  "variants.calculated_price.currency_code",
+  "variants.options.value",
+  "variants.options.option.title",
+];
+
+function stringParam(
+  query: MedusaRequest["query"],
+  name: string,
+): string | undefined {
+  const value = query[name];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function numberParam(
+  query: MedusaRequest["query"],
+  name: string,
+): number | undefined {
+  const value = stringParam(query, name);
+  if (!value) return undefined;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+// Meilisearch usa comillas dobles para valores de filtro con espacios;
+// escapamos las que vengan en el propio valor para no romper la sintaxis.
+function escapeFilterValue(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+export async function GET(req: MedusaRequest, res: MedusaResponse) {
+  const meilisearchService = req.scope.resolve<MeiliSearchService>(
+    MEILISEARCH_MODULE,
+  );
+  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY);
+
+  const q = stringParam(req.query, "q") ?? "";
+  const limit = numberParam(req.query, "limit") ?? 24;
+  const offset = numberParam(req.query, "offset") ?? 0;
+  // calculated_price exige region_id/currency_code en el contexto de
+  // pricing o query.graph tira "Method calculatePrices requires
+  // currency_code in the pricing context" (mismo error que ya rompio el
+  // job de sync -- ver medusa-config.ts). El storefront ya manda
+  // region_id contra /store/products (medusa.ts, regionId()); esta ruta
+  // espera el mismo query param.
+  const regionId = stringParam(req.query, "region_id");
+
+  const filterParts: string[] = [];
+  for (const facet of ["category", "collection", "brand", "ageRange"]) {
+    const value = stringParam(req.query, facet);
+    if (value) {
+      filterParts.push(`${facet} = "${escapeFilterValue(value)}"`);
+    }
+  }
+  const minPrice = numberParam(req.query, "minPrice");
+  const maxPrice = numberParam(req.query, "maxPrice");
+  if (typeof minPrice === "number") filterParts.push(`price >= ${minPrice}`);
+  if (typeof maxPrice === "number") filterParts.push(`price <= ${maxPrice}`);
+
+  const indexes = await meilisearchService.getIndexesByType("products");
+
+  if (indexes.length === 0) {
+    // Meilisearch no configurado o el indice "products" esta
+    // deshabilitado -- degradar a "sin resultados" en vez de 500, el
+    // frontend cae de nuevo a su propio filtrado si esta ruta falla.
+    res.json({ products: [], facetDistribution: {}, count: 0, limit, offset });
+    return;
+  }
+
+  const results = await Promise.all(
+    indexes.map((indexKey) =>
+      meilisearchService.search(indexKey, q, {
+        filter: filterParts.length ? filterParts.join(" AND ") : undefined,
+        paginationOptions: { limit, offset },
+        additionalOptions: { facets: FACETS },
+      }),
+    ),
+  );
+
+  const hits = results.flatMap((result) => result.hits);
+  const totalCount = results.reduce(
+    (sum, result) => sum + result.estimatedTotalHits,
+    0,
+  );
+
+  const facetDistribution: Record<string, Record<string, number>> = {};
+  for (const result of results) {
+    const resultFacets = (
+      result as unknown as {
+        facetDistribution?: Record<string, Record<string, number>>;
+      }
+    ).facetDistribution;
+    if (!resultFacets) continue;
+    for (const [facet, values] of Object.entries(resultFacets)) {
+      facetDistribution[facet] ??= {};
+      for (const [value, count] of Object.entries(values)) {
+        facetDistribution[facet][value] =
+          (facetDistribution[facet][value] ?? 0) + count;
+      }
+    }
+  }
+
+  const productIds = hits.map((hit) => (hit as { id: string }).id);
+
+  if (productIds.length === 0) {
+    res.json({ products: [], facetDistribution, count: 0, limit, offset });
+    return;
+  }
+
+  // calculatePrices exige currency_code en el contexto -- no alcanza con
+  // region_id solo (a diferencia de /store/products nativo, que lo
+  // resuelve el middleware setPricingContext; esta ruta no pasa por esa
+  // cadena). Resolvemos la moneda real de la region en vez de asumir COP
+  // fijo, por si el catalogo suma otra region/moneda mas adelante.
+  let currencyCode: string | undefined;
+  if (regionId) {
+    const { data: regions = [] } = await query.graph({
+      entity: "region",
+      fields: ["id", "currency_code"],
+      filters: { id: regionId },
+    });
+    currencyCode = regions[0]?.currency_code;
+  }
+
+  const { data: products = [] } = await query.graph({
+    entity: "product",
+    fields: PRODUCT_FIELDS,
+    filters: { id: productIds },
+    context:
+      regionId && currencyCode
+        ? {
+            variants: {
+              calculated_price: QueryContext({
+                region_id: regionId,
+                currency_code: currencyCode,
+              }),
+            },
+          }
+        : {},
+  });
+
+  // Preserva el ranking de relevancia de Meilisearch -- query.graph no
+  // garantiza el mismo orden que la busqueda.
+  const orderedProducts = [...products].sort(
+    (a, b) => productIds.indexOf(a.id) - productIds.indexOf(b.id),
+  );
+
+  res.json({
+    products: orderedProducts,
+    facetDistribution,
+    count: totalCount,
+    limit,
+    offset,
+  });
+}

workloads/docs-portal/docs/aprendizajes/notas-sueltas.md

@@ -1,20 +1,9 @@
 # Notas sueltas / aprendizajes
 
-> **TODO (fase 2+):** esto es un scratchpad estructurado, no un
-> playbook — va creciendo con notas cortas a medida que aparecen. Las
-> entradas de abajo son semillas reales extraídas de incidentes ya
-> documentados; expandir cada una con más contexto en fases siguientes.
-
-## Qué haría distinto
-
-- **Fijar `TUNNEL_TRANSPORT_PROTOCOL=http2` desde el día uno**, no
-  después de un incidente — QUIC/UDP sobre NAT doméstico fue un problema
-  predecible en retrospectiva. Ver [ADR 0003](../decisiones/0003-por-que-http2-sobre-quic-tunnel.md).
-- **Separar siempre "chequeo de disponibilidad" de "migraciones"** en
-  init containers distintos, y que el chequeo use el mínimo de
-  parámetros posible (host/puerto/usuario/db) en vez de reusar una URI
-  de conexión pensada para la app. Confirmado como decisión correcta en
-  el [incidente de crashloop de Medusa](../playbooks/incidente-crashloop-medusa.md).
+> Esto es un scratchpad estructurado, no un playbook — sigue creciendo
+> con notas cortas a medida que aparecen. Cada entrada está extraída de
+> un incidente o hallazgo real ya documentado en otra parte del sitio,
+> no es especulación.
 
 ## Gotchas de Medusa v2
 
@@ -26,8 +15,70 @@
   del array `images` — hay que setearlo explícito desde el Admin si el
   frontend lo usa como imagen hero en listados.
 
-## TODO
+## MinIO / S3 provider
 
-- Notas sobre MinIO / S3 provider.
-- Notas sobre el subscriber `revalidate-storefront.ts` y sus límites.
-- Qué automatizaría si volviera a montar este lab desde cero.
+- Medusa sube imágenes de producto a MinIO (`minio-svc:9000`, bucket
+  `ari-products`) usando el provider S3-compatible estándar — MinIO no
+  sabe que no es AWS real, y Medusa tampoco necesita saberlo.
+- La URL pública que termina viendo el navegador **no** es la interna
+  (`minio-svc:9000`): es `S3_FILE_URL=https://media.cruzcloud.net/ari-products`,
+  un dominio propio proxied por NPM hacia el mismo MinIO. Esto tiene
+  una consecuencia directa que ya rompió producción una vez: si
+  `media.cruzcloud.net` deja de rutear bien (mismo patrón de
+  `forward_host` roto que el resto del sitio), **todas** las imágenes
+  de producto del storefront se caen aunque MinIO y Medusa estén
+  perfectamente sanos — porque el navegador nunca habla con MinIO
+  directo, solo con esa URL pública. Ver [Red y exposición](../arquitectura/red-y-exposicion.md).
+
+## Subscriber `revalidate-storefront.ts` y sus límites
+
+- Escucha 6 eventos de Medusa (`product.created/updated/deleted` +
+  los 3 equivalentes de `product-variant`) y por cada uno hace un
+  único `POST` a `${STOREFRONT_URL}/api/revalidate` con un header
+  secreto (`x-revalidate-secret`) — esa ruta del frontend llama
+  `revalidateTag("medusa-products")` de Next.js.
+- **Se degrada solo, no tira el evento entero**: si
+  `STOREFRONT_URL`/`REVALIDATE_SECRET` no están configurados, o el
+  `fetch` falla, solo loguea un `warn` y sigue — un fallo de red hacia
+  el frontend nunca revierte ni bloquea la operación real en Medusa
+  (crear/editar un producto). Mismo criterio de "degradar, no romper"
+  que se repite en el resto del storefront (`searchWithFacets`
+  opcional, `/api/search` cayendo a `{}` si Meilisearch no responde).
+- **Límite real, todavía no un problema**: no hay debounce ni
+  deduplicación — si una operación dispara varios eventos juntos (ej.
+  editar un producto con 3 variantes a la vez), son varios `POST`
+  independientes al mismo endpoint. `revalidateTag` de Next.js es
+  barato e idempotente, así que hoy no se nota, pero si el catálogo
+  creciera mucho y las ediciones masivas se volvieran frecuentes, sería
+  el primer lugar donde agregar algún tipo de agrupación.
+
+## Qué haría distinto si volviera a montar este lab desde cero
+
+- **Fijar `TUNNEL_TRANSPORT_PROTOCOL=http2` desde el día uno** (ver
+  [ADR 0003](../decisiones/0003-por-que-http2-sobre-quic-tunnel.md)) y
+  **ajustar el MTU de `flannel.1` desde el primer `deploy-lab.sh`** —
+  ambos terminaron siendo incidentes reales
+  (504 intermitente, blackhole cross-node) que en retrospectiva eran
+  predecibles: red doméstica con NAT agresivo + Docker-in-Docker
+  multi-nodo son una combinación conocida para tener problemas de MTU
+  y de transporte UDP. Hoy los dos ya están automatizados
+  (`fix_flannel_mtu` en `deploy-lab.sh`, la variable de entorno del
+  túnel), pero se aprendieron reactivamente, no se anticiparon.
+- **Usar `git merge-base --is-ancestor` para la promoción segura del
+  CI desde el primer pipeline**, no después de ver la condición de
+  carrera en vivo (dos pipelines corriendo en serie sobre el mismo
+  commit, el segundo pisando o saltándose la promoción del primero).
+  El patrón correcto no es complicado una vez que se conoce — el costo
+  fue no anticiparlo.
+- **Separar siempre "chequeo de disponibilidad" de "migraciones"** en
+  init containers distintos, y que el chequeo use el mínimo de
+  parámetros posible (host/puerto/usuario/db) en vez de reusar una URI
+  de conexión pensada para la app. Confirmado como decisión correcta en
+  el [incidente de crashloop de Medusa](../playbooks/incidente-crashloop-medusa.md).
+- **No escribir un script que regenere credenciales completas en cada
+  corrida** (`create-commerce-secrets.sh` rota JWT/COOKIE/passwords de
+  Postgres/Redis/MinIO enteros cada vez que se ejecuta, incluso si solo
+  hacía falta agregar una clave nueva) — un script de setup inicial y
+  uno de "agregar una clave a un secret ya vivo" deberían haber sido
+  dos herramientas distintas desde el principio, no una sola que hay
+  que saber cuándo NO correr completa.

workloads/docs-portal/docs/arquitectura/agente-monitoreo.md

@@ -0,0 +1,307 @@
+# Agente de diagnóstico/corrección (lab-agent)
+
+Wrapper headless (`scripts/lab-agent/lab-agent.sh`) que corre `claude -p`
+periódicamente para diagnosticar el estado del lab y, solo para un
+conjunto explícito y aprobado de recursos, ejecutar una acción
+correctiva de bajo riesgo. Este documento es tanto referencia técnica
+como decisión de gobernanza — la lista blanca de abajo es lo que
+autoriza al agente a actuar sin intervención humana, y debe poder
+auditarse.
+
+Estado: **timer de systemd ACTIVO desde 2026-08-26** (`lab-agent.timer`,
+usuario `devops`, cada 60 min entre 06:00–23:00 hora local — bajado de
+15 a 60 min el mismo día para reducir costo). Script,
+Telegram y las unidades systemd, todo validado en vivo antes de
+activar.
+
+## Lista blanca de acciones correctivas automáticas
+
+Aprobada 2026-08-25, antes de escribir una sola línea de código.
+
+### 1. `kubectl rollout restart deployment/<nombre>`
+
+| Condición | Valor |
+|---|---|
+| Trigger | Deployment con `readyReplicas < replicas` o condición `Available=False` durante **≥10 minutos consecutivos** |
+| Namespace elegible | `ecommerce` (todos los deployments detectados ahí en el momento de la corrida) |
+| Excepción | `medusa-deploy` — el deployment real de "commerce-backend" en la terminología de `CLAUDE.md` (confirmado en vivo 2026-08-25: no existe un deployment llamado literalmente `commerce-backend`) — solo elegible si además la hora **local** del host está entre **00:00–06:00** |
+| Namespaces excluidos siempre | `argocd`, `kube-system`, cualquier otro namespace de plataforma |
+
+### 2. `docker restart <contenedor>`
+
+| Condición | Valor |
+|---|---|
+| Contenedores elegibles | **Únicamente `gitea-runner`** |
+| Trigger | Contenedor no está en estado `running` durante ≥10 min, **o** la API de Gitea Actions reporta un run en estado `running` atascado por más de 10 min sin terminar (señal del incidente de runner zombie del 2026-08-16) |
+| Degradación segura | Si no hay `GITEA_TOKEN_FILE` configurado o la API falla, esa señal se omite — nunca dispara una acción sobre una lectura no verificada, solo queda la señal de "contenedor caído" |
+| Excluidos siempre | `gitea`, `nginxproxymanager`, `cloudflared` |
+
+### 3. Fuera de alcance automático — SIEMPRE (solo diagnóstico + notificación)
+
+- Borrar cualquier recurso, escalar réplicas, tocar `ConfigMap`/`Secret`/configuración.
+- Reiniciar `gitea`, `nginxproxymanager`, `cloudflared`.
+- Cualquier acción sobre `medusa-deploy` fuera de la ventana 00:00–06:00.
+- Cualquier namespace/deployment no detectado explícitamente en `ecommerce`.
+
+### 4. Límites obligatorios
+
+- **Rate limit:** máx. 1 acción correctiva por recurso cada 30 min.
+- **Sin reintento silencioso:** tras un primer intento cuyo problema no
+  se resuelve, el recurso queda `blocked` — solo notificación, hasta
+  que un humano limpie la entrada en `state.json` o el recurso se
+  recupere solo.
+- **Logging completo:** cada decisión (actúe o no) se registra en
+  `actions.jsonl` con timestamp, recurso, decisión, resultado y motivo.
+- **Notificación siempre:** toda acción correctiva o anomalía dispara
+  notificación — nunca es silenciosa.
+
+## Diseño de seguridad: por qué Claude nunca ejecuta comandos
+
+`claude -p` se invoca con `--allowedTools ""` (cero herramientas) y
+`--json-schema`, así que el modelo **nunca** ejecuta un comando —
+solo devuelve una decisión estructurada
+(`{"actions":[{"resource","decision","reason"}], "summary"}`). El
+script bash es el único que ejecuta `kubectl`/`docker`, y solo después
+de revalidar la decisión contra su propio cálculo de elegibilidad —
+nunca confía en el JSON de Claude por sí solo.
+
+Se descartó dar a Claude un `Bash` tool con un patrón tipo
+`Bash(kubectl rollout restart deployment/medusa-deploy -n ecommerce)`
+porque se comprobó en vivo (2026-08-25) que `--allowedTools` hace
+**coincidencia por prefijo, no exacta**: un patrón `Bash(echo pintest)`
+también permite ejecutar `echo pintest && echo INJECTED` o
+`echo pintest; rm -rf /`. Para un comando root-capaz eso no es un
+límite seguro. Con `--allowedTools ""`, el peor caso posible es que
+Claude proponga una decisión incorrecta en el JSON — y el wrapper la
+rechaza si el recurso no está en su propia lista de elegibles.
+
+El prompt también advierte contra prompt injection: los datos de
+diagnóstico (estado de pods, logs) podrían contener texto arbitrario
+si algo en el cluster está comprometido, e instruye a Claude a ignorar
+cualquier instrucción incrustada ahí.
+
+## Autenticación: login de suscripción, no API key
+
+`ANTHROPIC_API_KEY_FILE` queda vacío por defecto — `claude -p` usa el
+login de suscripción ya activo del usuario que corre el script
+(`~/.claude/.credentials.json`), el mismo que usa una sesión
+interactiva normal. Esta decisión se tomó en vivo (2026-08-26) al
+confirmar que no había una API key real disponible; el diseño original
+pedía un secreto root-only para la API key, pero se simplificó porque:
+
+1. No hacía falta una API key aparte — la suscripción ya cubre esto.
+2. Elimina la necesidad de crear secretos root-only vía `sudo` (que
+   además está bloqueado para una sesión de Claude Code interactiva
+   por diseño — ver `feedback_scoped_root_access_pattern` en memoria
+   del proyecto).
+
+**Consecuencia directa:** el servicio systemd (cuando se active) debe
+correr como usuario `devops`, no como `root` — root no tiene acceso a
+ese login. `CLAUDE_BIN`/`KUBECTL_BIN` apuntan por ruta absoluta a
+`/DATA/AppData/home-devops/.local/bin/` porque ese directorio no está
+en el `PATH` de root ni de systemd (confirmado en vivo: `sudo which
+claude` no lo encuentra).
+
+El único secreto que queda es `GITEA_TOKEN_FILE` (token de Gitea
+Actions, opcional, scope lectura), dueño `devops`, `600` — sin sudo.
+
+## Prueba end-to-end (2026-08-26)
+
+Ejecutada contra el cluster real, rama `fix/lab-agent-diagnostico-headless`.
+Umbral bajado a 2 minutos solo para esta prueba (`UNHEALTHY_THRESHOLD_MIN`,
+valor real en producción: 10). Canario desechable: `deployment/test-agent-canary`
+en `ecommerce`, imagen `busybox:stable` con `command: ["sh","-c","exit 1"]`
+— garantiza `CrashLoopBackOff` predecible, sin relación con
+`catalog-api-deploy`/`frontend-deploy`/`medusa-deploy`.
+
+### Bugs encontrados y corregidos durante la prueba
+
+1. **Subshell perdía el resultado de la acción.** `execute_corrective_action`
+   se invocaba como `result="$(execute_corrective_action "$resource")"` —
+   al correr en un subshell, las variables `LAST_ACTION_CMD`/`STDOUT`/`STDERR`
+   nunca volvían al script principal → crash con `unbound variable`.
+   Corregido: la función ahora devuelve éxito/fallo por exit status, invocada
+   directamente (sin `$(...)`) para que sus variables globales persistan.
+2. **DRY_RUN contaminaba el estado real.** El wrapper marcaba `blocked=true`
+   en `state.json` incluso en modo simulación, lo que habría bloqueado
+   incorrectamente una corrida real posterior sobre el mismo recurso.
+   Corregido: la actualización de `state.json` (bloqueo/rate-limit) solo
+   ocurre fuera de `DRY_RUN`.
+3. **`claude`/`kubectl` fuera del PATH de root/systemd** — ver sección de
+   autenticación arriba. Corregido con `CLAUDE_BIN`/`KUBECTL_BIN` por ruta
+   absoluta.
+
+### Evidencia por paso
+
+**DRY_RUN (elegibilidad + decisión, sin tocar el cluster):**
+
+- 1ª corrida (recién detectado): `elegibilidad=not_eligible:bajo_umbral(0m<2m)`
+  → Claude devolvió `notify_only` para los 5 recursos.
+- 2ª corrida (&gt;2 min después): `elegibilidad=eligible` para
+  `test-agent-canary` → Claude devolvió `decision:"restart"` solo para
+  ese recurso, `notify_only` para los otros 4 (sanos).
+- Log: `ACCIÓN EJECUTADA: kubectl -n ecommerce rollout restart
+  deployment/test-agent-canary -> OK`, pero verificado en el cluster real
+  que **no hubo restart** (sin anotación `restartedAt`, mismo pod, misma
+  edad). `actions.jsonl` registra `"dry_run": true`.
+
+**Ejecución real (`--live`):**
+
+- Misma decisión de Claude (`restart` para el canario, `notify_only` para
+  el resto).
+- Verificado en el cluster: nueva anotación
+  `kubectl.kubernetes.io/restartedAt` en el deployment, evento
+  `ScalingReplicaSet` de un ReplicaSet **nuevo**, pod nuevo en otro nodo.
+- `actions.jsonl`: `"result": "success", "dry_run": false`.
+- `state.json`: `last_action_at` seteado, `blocked: true`.
+
+**Rate limit / sin reintento silencioso:**
+
+- El canario (siempre crashea por diseño) volvió a estar unhealthy sin
+  intervención extra.
+- Corrida siguiente: `elegibilidad=not_eligible:blocked_tras_intento_previo_sin_recuperacion`.
+- Claude devolvió `notify_only` para **todos** los recursos, incluido el
+  canario — ningún segundo restart propuesto ni ejecutado.
+- `state.json` sin cambios (mismo `last_action_at` que la corrida real
+  anterior) — confirma que no hubo reintento.
+- Notificación real entregada vía ntfy.sh, confirmada leyendo el propio
+  historial del topic (no solo el log del script).
+
+**Limpieza:** `deployment/test-agent-canary` eliminado, entrada
+correspondiente en `state.json` borrada. Los logs de la prueba
+(`actions.jsonl`, `run-*.log`) se conservan como evidencia auditable —
+no se purgaron.
+
+## Notificaciones
+
+**Canal: Telegram Bot API** (reemplaza a ntfy, cambiado 2026-08-26 por
+preferencia — no por costo, ver sección de costo abajo). Bot creado
+manualmente vía [@BotFather](https://t.me/BotFather); el token vive en
+`TELEGRAM_BOT_TOKEN_FILE` (dueño `devops`, `600` — **no** root-only,
+mismo criterio que `GITEA_TOKEN_FILE`: el servicio corre como `devops`
+por el login de suscripción, un archivo `root:root` le sería ilegible).
+`TELEGRAM_CHAT_ID` no es secreto, va directo en `lab-agent.env`.
+
+El mensaje se manda como texto plano, sin `parse_mode`: el motivo que
+devuelve Claude es texto libre y puede traer `_`, `*`, `[`, `]` — con
+Markdown/MarkdownV2 esos caracteres rompen el parser de Telegram (`400
+Bad Request`) si no se escapan con cuidado. Se prioriza entrega
+confiable sobre formato.
+
+**Validado en vivo 2026-08-26** con el mismo código que usa
+`notify_send()` (lectura del token, `sendMessage` vía `curl
+--data-urlencode`, formato `[title]\nmessage`): entrega confirmada
+(`"ok":true`) y contenido recibido tal cual en Telegram. Gotcha
+encontrado durante la prueba: el primer intento falló con `400 chat not
+found` porque el `chat_id` pegado correspondía a otro bot — el `chat_id`
+de un usuario es el mismo across bots, pero Telegram igual devuelve
+`chat not found` si *ese bot puntual* nunca recibió un mensaje de esa
+persona. Se resolvió confirmando el `chat_id` real vía `getUpdates` del
+bot correcto.
+
+**Formato:** cada notificación lleva un ícono según su naturaleza
+(✅ acción ok, 🛑 acción falló/rechazada, 🚨 alerta de seguridad,
+❌ error operativo, 👀 solo diagnóstico) y el log completo de esa
+corrida va adjunto como documento (`sendDocument`), no solo como ruta —
+útil para revisar desde el celular sin acceso a shell.
+
+**Notificación silenciosa y respuestas en hilo (2026-08-26):** el nivel
+`info` (nada elegible, todo diagnóstico rutinario) se manda con
+`disable_notification=true` — no interrumpe; acciones, fallas y alertas
+de seguridad sí suenan. Cuando se ejecuta una acción correctiva, el
+`message_id` de Telegram queda guardado por recurso en `state.json`
+(`telegram_message_id`); si ese recurso se recupera solo en una corrida
+posterior, se manda un aviso silencioso como **respuesta** (hilo) al
+mensaje original antes de limpiar el estado — agrupa visualmente todo
+un incidente. Limitación conocida: si un humano desbloquea el recurso a
+mano borrando su entrada de `state.json` (ver más abajo), el
+`message_id` se pierde con esa entrada, así que ese caso puntual no
+queda threadeado — solo el "se recuperó solo" está cubierto hoy.
+Validado en vivo con el canario: acción real → `message_id` capturado →
+canario parcheado a una imagen sana → reply en hilo confirmado,
+silencioso, al recuperarse.
+
+## Horario activo y costo
+
+**Pausa nocturna (`ACTIVE_HOURS_START`/`END`, hora local del host):**
+activo `06:00`–`23:00`, pausado `23:00`–`06:00`. El script chequea esto
+como lo primero que hace tras inicializar logging — si está fuera de
+horario, sale **antes** de tocar `kubectl`/`docker`/`curl` o invocar
+`claude -p`, así que la pausa ahorra el costo completo de la corrida,
+no solo la notificación. El timer de systemd además solo dispara dentro
+de esa ventana (`OnCalendar=*-*-* 06..22:00:00`) — la doble
+verificación es deliberada: si alguien edita la unidad de systemd sin
+tocar `lab-agent.env` (o corre el script a mano), el chequeo interno
+sigue protegiendo.
+
+**Tensión sin resolver con la ventana de `medusa-deploy`:** la ventana
+de auto-restart para `medusa-deploy` (`COMMERCE_BACKEND_WINDOW_*`,
+`00:00`–`06:00`) **no se solapa** con el horario activo del agente
+(`06:00`–`23:00`). Esto significa que, en la práctica, `medusa-deploy`
+nunca es candidato real a auto-restart: la única ventana en la que la
+política lo permitiría es exactamente cuando el agente está pausado y
+ni siquiera corre. La regla sigue viva en el código (por si el horario
+activo cambia más adelante) pero hoy es efectivamente inalcanzable.
+Pendiente de decisión: mover la ventana de `medusa-deploy` a que caiga
+dentro del horario activo, o aceptar que ese recurso queda cubierto
+solo por diagnóstico/notificación manual.
+
+**Estimación de costo mensual — actualizada 2026-08-26, frecuencia
+bajada de 15 a 60 min explícitamente para reducir costo:**
+
+| | |
+|---|---|
+| Corridas/día (17h activas ÷ 60 min) | 17 |
+| Costo por corrida | ~US$0.04–0.12 — **más alto por corrida que a 15 min**: el cache de prompt de Claude Code dura ~1h, y con corridas espaciadas 60 min casi siempre expira entre una y la siguiente, así que la mayoría de las corridas pagan cache "fría" en vez de "tibia" |
+| **Estimado mensual (× 30 días)** | **~US$20–60** (punto medio ~US$35) |
+
+Ojo con la intuición: bajar la frecuencia 4× (68→17 corridas/día) NO
+baja el costo 4× — el ahorro real es más cercano a 1.5–2× frente a la
+estimación anterior (~US$60–65/mes), porque cada corrida individual
+sale más cara al perder la ventaja del cache tibio. Sigue siendo menos
+costo total, solo que no linealmente. Basado en pocas corridas reales
+medidas — revisar el costo real después de la primera semana en
+producción (Telegram/Gitea Actions no cambian este número, el costo es
+100% de la API de Claude).
+
+**Trade-off de latencia de detección:** con corridas cada 60 min en vez
+de 15, un problema que recién cruza el umbral de 10 minutos puede
+tardar hasta ~70 min en ser detectado y potencialmente corregido (antes
+era hasta ~25 min). Aceptado a cambio del ahorro de costo — si en la
+práctica resulta muy lento para algún incidente real, la frecuencia se
+puede volver a subir sin tocar nada más (`OnCalendar` en
+`lab-agent.timer`).
+
+## Activación del timer (2026-08-26)
+
+Habilitado tras confirmación explícita del propietario del lab, viendo
+antes el costo mensual estimado. Unidad de usuario (`systemctl --user`,
+corre como `devops`, no `root`), con límites de CPU/memoria (`CPUQuota`,
+`MemoryMax`) — instalada en `/DATA/.config/systemd/user/`, no en el
+`~/.config/...` de una shell interactiva.
+
+**Gotcha encontrado y corregido en vivo:** el manager de `systemd
+--user` de `devops` arranca con `HOME=/DATA` (el valor de
+`/etc/passwd`), no `/DATA/AppData/home-devops` — ese override solo se
+aplica al abrir una shell interactiva vía
+`/etc/profile.d/zz-devops-home.sh`, que el manager de systemd nunca
+carga. Sin corregirlo, `claude -p` habría buscado
+`~/.claude/.credentials.json` en `/DATA/.claude/` (no existe) y la
+autenticación habría fallado en cada corrida del timer, silenciosamente,
+hasta la primera vez que alguien mirara el log. `lab-agent.service`
+fija `Environment=HOME=/DATA/AppData/home-devops` explícitamente para
+evitarlo. Se detectó y corrigió *antes* de habilitar el timer, corriendo
+el servicio manualmente vía `systemctl --user start` con el entorno
+real (no desde una shell interactiva) como último paso de validación.
+
+También requirió `sudo loginctl enable-linger devops` (una vez) — sin
+eso, `systemctl --user` ni siquiera conecta (no hay `/run/user/<uid>`
+sin una sesión de login o linger activo).
+
+**Pendiente, no bloqueante:**
+
+- Opcional: `GITEA_TOKEN_FILE` para activar la señal de "runner
+  atascado" vía API de Gitea Actions (hoy se omite, degradación segura).
+- Decidir la tensión con la ventana de `medusa-deploy` (ver arriba) —
+  sigue sin resolver, el timer se activó igual porque no bloquea el
+  resto de la lista blanca.

workloads/docs-portal/docs/arquitectura/gitops-flujo.md

@@ -1,9 +1,9 @@
 # Del commit al despliegue: flujo GitOps
 
-> **TODO (fase 2+):** narrar cada paso con ejemplos reales tomados de
-> `.gitea/workflows/build-medusa.yaml` y `build.yaml`. El diagrama de
-> secuencia de abajo refleja el pipeline real (build → push imagen →
-> promoción segura → commit del tag → sync de Argo CD).
+El diagrama de abajo refleja el pipeline real (build → push imagen →
+promoción segura → commit del tag → sync de Argo CD). Después del
+diagrama hay un ejemplo con hashes de commit reales, tomado de un
+cambio real hecho sobre este mismo repo.
 
 ## Secuencia: un commit hasta quedar corriendo en el cluster
 
@@ -42,9 +42,53 @@ sequenceDiagram
   evita que un pipeline viejo sobreescriba el tag con una versión
   anterior si hubo un push más reciente mientras corría.
 
-## TODO
+## Ejemplo real: un commit de principio a fin
 
-- Ejemplo real con hashes de commit (tomar del historial de
-  `apps-registry`).
-- Explicar `syncPolicy.automated.selfHeal` con un caso concreto (qué
-  pasa si alguien hace `kubectl edit` a mano).
+Fase 3b del ADR 0006 (facetas del sidebar del catálogo, ver
+`decisiones/0006-motor-busqueda-facetas.md`) recorrió el flujo
+completo dos veces seguidas el mismo día:
+
+| Paso | Commit / evento real |
+|---|---|
+| Feature | `83d448b` — `feat(ecommerce): facetas reales de Meilisearch en el sidebar del catalogo`, en `fix/adr0006-etapa2-fase3b-facetas-sidebar` |
+| Merge a `main` | `6b5450f` |
+| CI build+push | Gitea Actions task 258, imagen `gitea.cruzcloud.net/devops/ecommerce-frontend` |
+| Release commit (CD) | `951682a` — `chore: release v1.0.171 [skip ci]`, bump automático del tag en `frontend/patches/deployment.yaml` |
+| Sync de Argo CD | dos ciclos distintos: primero sincronizó contra `6b5450f` (el merge, todavía con el tag viejo), y en el ciclo siguiente detectó `951682a` y aplicó el tag nuevo |
+| Rollout | `frontend-deploy` con 2/2 réplicas en `v1.0.171` |
+
+El gate en vivo contra ese mismo cambio encontró un bug real
+(`estimatedTotalHits` en 0 con `limit=0` en Meilisearch) — el fix
+repitió el mismo ciclo completo: `884dbd1` → merge `ba3e6c7` → release
+`v1.0.172` → sync → rollout. Dos vueltas completas del diagrama de
+arriba en la misma sesión, cada una verificada contra el endpoint real
+antes de darla por cerrada.
+
+**Detalle no obvio:** Argo CD sincroniza el *merge commit* primero
+(todavía con la imagen vieja, porque el bump de tag es un commit
+*posterior* que hace el propio pipeline) y recién en un segundo ciclo
+de poll detecta el commit de release. Son dos sincronizaciones
+distintas, no una sola — hay que esperar ambas antes de asumir que el
+pod nuevo está corriendo.
+
+## `selfHeal`, con la configuración real
+
+Todas las Applications de este repo comparten el mismo `syncPolicy`
+(`apps/ecommerce-app.yaml`):
+
+```yaml
+syncPolicy:
+  automated:
+    prune: true
+    selfHeal: true
+```
+
+Con `selfHeal: true`, si alguien corre `kubectl scale deployment
+frontend-deploy --replicas=1` directo contra el cluster (saltándose
+Git por completo), Argo CD no se queda en mostrar `OutOfSync` — en el
+siguiente ciclo de reconciliación vuelve a aplicar el manifiesto tal
+como está en `main` y el Deployment queda otra vez en las réplicas
+declaradas ahí. El cambio manual no se pierde silenciosamente: queda
+un instante como drift visible en la UI de Argo CD, pero nunca se
+vuelve el estado final. La única forma de que ese cambio persista es
+que exista en Git — lo mismo que describe [ADR 0002](../decisiones/0002-por-que-argocd-vs-manual.md).

workloads/docs-portal/docs/arquitectura/glosario.md

@@ -65,9 +65,142 @@ plantillas (a diferencia de Helm).
 incluir y qué parches aplicarles, sin necesidad de un lenguaje de
 templating separado.
 
-## TODO
+## Namespace
 
-- Namespace, ResourceQuota, LimitRange, NetworkPolicy
-- Ingress vs. Service vs. Deployment
-- StatefulSet (por qué Postgres lo usa y el frontend no)
-- Init container
+**En una frase:** una partición lógica dentro del mismo cluster físico
+— agrupa recursos relacionados y les pone un límite alrededor.
+
+**Detalle:** este lab tiene un namespace por dominio de negocio
+(`ecommerce`, `docs-portal`) más `argocd` para el propio Argo CD. Todo
+lo que gobierna a un namespace (cuotas, políticas de red) vive en
+`platform-infra`, separado de los manifiestos de la app — así una app
+nueva no puede "olvidarse" de traer su propia gobernanza.
+
+## ResourceQuota
+
+**En una frase:** el techo total de recursos que un namespace entero
+puede consumir, sumando todos sus pods.
+
+**Detalle:** la cuota real de `ecommerce`
+(`platform-infra/ecommerce-governance/resourcequota.yaml`):
+
+```yaml
+hard:
+  requests.cpu: "3"
+  requests.memory: 4Gi
+  limits.cpu: "8"
+  limits.memory: 8Gi
+  pods: "12"
+  persistentvolumeclaims: "6"
+  requests.storage: 80Gi
+```
+
+Si un Deployment nuevo pidiera más `requests.memory` del que queda
+disponible bajo ese techo, Kubernetes rechaza el pod directamente — no
+lo deja arrancar y luego fallar.
+
+## LimitRange
+
+**En una frase:** los valores por defecto (y los mínimos/máximos) que
+aplican a un contenedor *individual* dentro de un namespace, para
+cuando el manifiesto no los declara explícitos.
+
+**Detalle:** complementa a `ResourceQuota` (que mira el namespace
+entero) a nivel de un solo contenedor. La de `ecommerce`
+(`limitrange.yaml`) pone `defaultRequest: 100m/128Mi`,
+`default: 500m/512Mi` (límites si el contenedor no los declara), y un
+rango permitido de `10m/16Mi` a `2 CPU/1Gi` por contenedor — evita
+tanto el contenedor que no pide nada y termina compitiendo mal por
+recursos, como el que pide de más y se come la cuota del namespace
+entero él solo.
+
+## NetworkPolicy
+
+**En una frase:** un firewall a nivel de Kubernetes — qué tráfico de
+red se permite entrar (o salir) de un pod.
+
+**Detalle:** sin ninguna `NetworkPolicy`, todos los pods de un cluster
+pueden hablarse entre sí libremente. La de `ecommerce`
+(`networkpolicy.yaml`) usa `podSelector: {}` (aplica a todos los pods
+del namespace) y permite ingress solo desde `namespaceSelector: {}`
+(cualquier namespace del cluster, típicamente Traefik llegando desde
+`kube-system` o el namespace de ingress) — bloquea tráfico externo al
+cluster que intentara saltarse Traefik y pegarle directo a un Service
+interno.
+
+## Deployment
+
+**En una frase:** el controlador para cargas de trabajo **sin
+estado** — réplicas intercambiables entre sí, ninguna con identidad
+propia.
+
+**Detalle:** `frontend-deploy` es un Deployment de 2 réplicas: no
+importa cuál de las dos atienda una petición, ambas sirven exactamente
+lo mismo y ninguna guarda datos propios en disco. Si un pod muere,
+Kubernetes crea otro cualquiera para reemplazarlo — no hay "el pod
+original" que recuperar. Contrastar con **StatefulSet** abajo.
+
+## Service
+
+**En una frase:** un nombre de red estable que apunta a un grupo de
+pods, aunque esos pods cambien.
+
+**Detalle:** los pods son efímeros (mueren y se recrean con IP nueva
+cada vez); un Service (ej. `frontend-svc`, `postgres-svc`) les da un
+nombre DNS interno fijo (`frontend-svc.ecommerce.svc.cluster.local`,
+o simplemente `frontend-svc` desde dentro del mismo namespace) que no
+cambia aunque los pods de atrás sí. `postgres-svc` en este lab es
+además un Service `clusterIP: None` ("headless") — necesario porque
+`commerce-postgres` es un StatefulSet y cada pod necesita su propia
+identidad de red estable, no una IP compartida balanceada entre
+réplicas.
+
+## Ingress
+
+**En una frase:** la regla que dice "las peticiones a este dominio y
+esta ruta van a este Service", para tráfico HTTP que entra al cluster.
+
+**Detalle:** `ecommerce-ingress` enruta por *path*, no solo por
+dominio: `shop.cruzcloud.net/api/catalog` va a `catalog-api-svc`, y
+todo lo demás (`/`) va a `frontend-svc` — un solo objeto Ingress con
+dos backends distintos según el prefijo de la URL. Es Traefik (el
+Ingress Controller del cluster) quien lee estos objetos y hace el
+enrutamiento real; el Ingress en sí es solo la declaración de la
+regla, no el componente que la ejecuta.
+
+## StatefulSet
+
+**En una frase:** el controlador para cargas de trabajo **con
+estado** — cada réplica tiene identidad propia y almacenamiento propio
+que sobrevive a que el pod se reinicie.
+
+**Detalle:** `commerce-postgres` es un StatefulSet, no un Deployment,
+porque el frontend puede tener 2 réplicas idénticas sin datos propios,
+pero Postgres no — sus datos tienen que vivir en un disco específico
+que sobreviva un reinicio del pod y sepa exactamente cuál pod es
+"el suyo". Cada pod de un StatefulSet obtiene su propio
+`PersistentVolumeClaim` vía `volumeClaimTemplates` (acá,
+`postgres-data`, 10Gi en `local-path`) y un nombre de red estable y
+numerado (`commerce-postgres-0`), a diferencia de los nombres
+aleatorios de un Deployment. Meilisearch, Redis y MinIO en este lab
+siguen el mismo patrón por la misma razón — todos guardan datos en
+disco que tienen que sobrevivir al pod.
+
+## Init container
+
+**En una frase:** un contenedor que corre **antes** que los
+contenedores principales de un pod, y tiene que terminar bien (exit
+0) para que el resto arranque.
+
+**Detalle:** `medusa-deploy` usa dos, y a propósito están separados en
+vez de ser uno solo: `wait-for-postgres` (`pg_isready` en loop, solo
+espera a que Postgres acepte conexiones) y `migrations`
+(`db:migrate`, corre las migraciones de verdad). Un incidente real
+mostró por qué separarlos importa: cuando el chequeo de disponibilidad
+reusaba la misma `DATABASE_URL` completa de la app (con
+`?sslmode=disable` incluido), el parser de `pg_isready` no la entendía
+y el pod quedaba atascado en `Init` — reportado como si fuera
+`CrashLoopBackOff`, sin serlo. El fix fue que el chequeo de
+disponibilidad use el mínimo de parámetros posible
+(host/puerto/usuario/db), nunca la URI completa pensada para la app.
+Ver el [playbook del crashloop de Medusa](../playbooks/incidente-crashloop-medusa.md).

workloads/docs-portal/docs/arquitectura/red-y-exposicion.md

@@ -1,8 +1,7 @@
 # Red y exposición
 
-> **TODO (fase 2+):** explicar cada dominio, por qué está proxied vs
-> DNS-only en Cloudflare, y el manejo de TLS extremo a extremo. Tabla
-> de dominios abajo es real, pendiente de expandir con capturas/ejemplos.
+Los 5 dominios de abajo son reales y comparten exactamente el mismo
+camino de red — ninguno tiene un caso especial.
 
 ## Dominios activos
 
@@ -14,12 +13,63 @@
 | `gitea.cruzcloud.net` | Gitea | — | Cloudflare (edge) |
 | `docs.cruzcloud.net` | Este portal | `docs` | Cloudflare (edge) |
 
-## TODO
+## Por qué todos van "proxied" (naranja), ninguno "DNS-only"
 
-- Diagrama de TLS termination (dónde termina TLS realmente: en
-  Cloudflare, no en Traefik — el tráfico interno NPM→k3d es HTTP plano).
-- Explicar por qué el transporte del túnel se fijó a HTTP/2 en vez de
-  QUIC (ver [ADR 0003](../decisiones/0003-por-que-http2-sobre-quic-tunnel.md)
-  y el [playbook del 504](../playbooks/incidente-504-gitea-tunnel.md)).
-- Patrón de diagnóstico "interno sano, público roto" (ver
-  [playbook de imágenes NPM](../playbooks/incidente-imagenes-npm.md)).
+Un registro DNS-only en Cloudflare expondría directamente la IP real
+del túnel — pero acá no hay IP pública fija que exponer: el NAS está
+detrás de NAT residencial. El modo proxied es lo que hace que
+Cloudflare Tunnel tenga sentido en primer lugar (el tráfico entra por
+el edge de Cloudflare, nunca directo al origen), así que no hay ningún
+dominio de este lab para el que DNS-only sea una opción real.
+
+## Dónde termina TLS de verdad
+
+```mermaid
+flowchart LR
+    User(["Usuario"]) -->|HTTPS| CF["Cloudflare edge<br/>🔒 TLS termina acá"]
+    CF -->|túnel cifrado, HTTP/2| CFD["cloudflared"]
+    CFD -->|HTTP plano| NPM["Nginx Proxy Manager"]
+    NPM -->|HTTP plano| LB["k3d-proxy :90"]
+    LB -->|HTTP plano| TR["Traefik"]
+    TR -->|HTTP plano| SVC["Service interno"]
+```
+
+TLS termina en el **edge de Cloudflare**, no en Traefik ni en NPM. De
+ahí hacia adentro (`cloudflared` → NPM → `k3d-proxy` → Traefik →
+Service) todo el tráfico va en HTTP plano — seguro en este contexto
+porque ese tramo entero vive dentro de la red local del NAS, nunca
+sale a internet. Ningún componente interno necesita certificado propio
+ni gestionar renovación de TLS.
+
+## Por qué HTTP/2 y no QUIC en el túnel
+
+`cloudflared` puede usar QUIC (UDP) o HTTP/2 (TCP) para sus conexiones
+salientes hacia el edge. Este lab fuerza HTTP/2 explícitamente — no es
+el default. Un incidente real de `504 Gateway Timeout` intermitente en
+**todos** los subdominios (no solo uno) se rastreó hasta fallos
+recurrentes del "control stream" de QUIC sobre la red doméstica del
+NAS. Ver [ADR 0003](../decisiones/0003-por-que-http2-sobre-quic-tunnel.md)
+para la decisión completa y el [playbook del 504](../playbooks/incidente-504-gitea-tunnel.md)
+para el diagnóstico paso a paso.
+
+## Patrón de diagnóstico: "interno sano, público roto"
+
+Cuando un dominio público falla pero todo dentro del cluster responde
+bien (pods `Running`, probes verdes, `kubectl exec` con `curl` al
+Service funciona), la causa casi nunca está en Kubernetes — está en la
+capa NPM. La forma rápida de confirmarlo es saltarse NPM a propósito:
+`curl -H "Host: <dominio>" http://192.168.68.61:90/` habla directo con
+`k3d-proxy`/Traefik sin pasar por NPM. Si eso funciona pero el dominio
+público no, el problema está específicamente en el `forward_host`/
+`forward_port` del proxy host en NPM (ej.: un scheme o un path colado
+en `forward_host`, que rompe todo el enrutamiento).
+
+Este patrón se repitió dos veces en este lab con la misma causa raíz
+exacta: el [incidente de imágenes en `media.cruzcloud.net`](../playbooks/incidente-imagenes-npm.md)
+(playbook completo) y un incidente posterior de `commerce.cruzcloud.net`
+devolviendo 400 por el mismo tipo de `forward_host` roto (sin playbook
+propio todavía). Una lección adicional de ese segundo incidente:
+editar el `proxy_host` a mano en el sqlite de NPM **no** regenera el
+`.conf` de nginx automáticamente — el cambio tiene que pasar por la
+propia UI/API de NPM, o el `.conf` hay que parchearlo a mano y
+recargar nginx.

workloads/docs-portal/docs/arquitectura/sesion-tmux-persistente.md

@@ -0,0 +1,225 @@
+# Sesión persistente de Claude Code (tmux en Docker)
+
+## Problema que resuelve
+
+Correr Claude Code directo en una shell SSH sobre el NAS lo ata al
+ciclo de vida de esa conexión: un corte de red, cambiar de laptop a
+tablet, o cerrar la terminal por accidente mata el proceso y con él
+todo el contexto de trabajo en curso — no hay forma de "retomar
+donde quedó" porque el proceso ya no existe.
+
+**Esto es un problema distinto al de los límites de uso/cuota de
+Claude Code.** Este setup no aumenta cuota de mensajes ni tokens —
+eso lo controla el backend de Anthropic sin importar dónde corra el
+CLI. Lo único que resuelve es que la *sesión de terminal* sobreviva
+a cortes de red o cambios de dispositivo; si la cuota se agota, sigue
+agotada exactamente igual dentro de este setup.
+
+## Por qué Docker y no instalación nativa
+
+ZimaOS no tiene gestor de paquetes tradicional utilizable para esto:
+`/` está montado como `squashfs` de solo lectura (imagen del SO
+inmutable), y `/usr` es un overlay de solo lectura sobre eso —
+`/usr/local/bin` ni siquiera existe y no se puede crear, tampoco como
+root (`mkdir` falla con "Read-only file system"). No hay dónde
+instalar Node.js, npm ni tmux directamente sobre el host.
+
+Un contenedor Docker sortea esto por completo: tiene su propio
+filesystem de escritura (overlay2), independiente del `squashfs` del
+host — ahí es donde `npm install -g` deja el binario de `claude` sin
+tocar el host en absoluto. Lo único que el contenedor toma del host
+es lo que se monta explícitamente como volumen.
+
+## Arquitectura
+
+```mermaid
+flowchart LR
+    SSH["Cliente SSH<br/>(laptop / tablet / lo que sea)"] -->|docker exec| C["Contenedor tmux-host<br/>--network host, --restart unless-stopped"]
+    C --> T["tmux server<br/>sesión 'lab'"]
+    T --> CC["proceso claude<br/>(Claude Code)"]
+    C -.->|bind mount| DATA["/DATA (host)<br/>repos y configs del lab"]
+    C -.->|bind mount| SOCK["/var/run/docker.sock (host)<br/>control de Docker/k3d"]
+    C -.->|bind mount| HOME["/DATA/AppData/k3d-lab-v3/claude-code-home (host)<br/>-> /root/.claude"]
+```
+
+El contenedor sigue vivo aunque la conexión SSH se corte — es el
+servidor tmux, no la shell del cliente, el que sostiene el proceso de
+Claude Code. `--restart unless-stopped` además lo revive si el NAS
+reinicia.
+
+## Contenedor: `tmux-host`
+
+```bash
+docker run -d \
+  --name tmux-host \
+  --restart unless-stopped \
+  -v /DATA:/DATA \
+  -v /media/HDD-Storage:/media/HDD-Storage \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  -v /DATA/AppData/k3d-lab-v3/claude-code-home:/root/.claude \
+  -v /DATA/AppData/k3d-lab-v3/claude-code-home.json:/root/.claude.json \
+  --network host \
+  alpine sh -c "apk add --no-cache tmux docker-cli bash curl git kubectl nodejs npm && npm install -g @anthropic-ai/claude-code && git config --global --add safe.directory '*' && tail -f /dev/null"
+```
+
+| Volumen | Destino | Por qué |
+|---|---|---|
+| `/DATA` | `/DATA` | Acceso a los repos (`apps-registry`, `platform-infra`, `scripts`) y configs del lab, mismos paths que en el host |
+| `/media/HDD-Storage` | `/media/HDD-Storage` | Ver "Gotcha: el symlink `/DATA/AppData`" abajo — sin esto, los repos no se ven dentro del contenedor pese a montar `/DATA` |
+| `/var/run/docker.sock` | `/var/run/docker.sock` | Seguir controlando Docker y k3d (contenedores, `k3d node`, etc.) desde dentro del contenedor |
+| `/DATA/AppData/k3d-lab-v3/claude-code-home` | `/root/.claude` | Persistir login/config de Claude Code — sobrevive no solo a un `docker restart`, sino a recrear el contenedor entero |
+| `/DATA/AppData/k3d-lab-v3/claude-code-home.json` | `/root/.claude.json` | Ver "Gotcha: la confianza del folder no persistía" abajo — es un archivo suelto, no vive dentro de `~/.claude/` |
+
+## Gotcha: el symlink `/DATA/AppData`
+
+Montar `-v /DATA:/DATA` **no alcanza** para ver los repos dentro del
+contenedor. `/DATA/AppData` en el host es un symlink *absoluto*:
+
+```
+/DATA/AppData -> /media/HDD-Storage/AppData
+```
+
+Los repos del lab (`lab-cruzcloud`) viven físicamente en el disco
+btrfs `/media/HDD-Storage`, no en el ext4 de `/DATA` — ZimaOS lo
+expone dentro de `/DATA` como submount (`/DATA/.media/HDD-Storage/...`,
+que sí viaja al contenedor porque Docker hace bind recursivo por
+defecto) pero el path "bonito" `/DATA/AppData/...` que usan `CLAUDE.md`
+y todos los scripts del lab llega ahí vía ese symlink absoluto, no vía
+el submount. Un symlink absoluto que apunta fuera del árbol montado
+queda roto dentro del contenedor aunque el submount subyacente esté
+perfectamente accesible por otra ruta.
+
+**Cómo se detectó:** todo el trabajo de configuración inicial de este
+mismo setup se hizo con `git`/`docker exec` corriendo *en el host*, no
+dentro del contenedor — nadie había probado `cd
+/DATA/AppData/k3d-lab-v3/lab-cruzcloud` desde una sesión `lab` real
+hasta que se preguntó explícitamente por esto. `ls` devolvía "No such
+file or directory" pese a que el volumen de `/DATA` estaba montado y
+"andando".
+
+**Fix:** montar también `-v /media/HDD-Storage:/media/HDD-Storage`,
+para que el symlink resuelva exactamente igual que en el host.
+
+## Gotcha: git "dubious ownership" dentro del contenedor
+
+Con el mount anterior ya arreglado, `git status`/`git log` dentro del
+contenedor fallan con:
+
+```
+fatal: detected dubious ownership in repository at '/media/HDD-Storage/...'
+```
+
+Los archivos en `/DATA`/`/media/HDD-Storage` pertenecen al usuario
+`devops` del host (via samba), pero los procesos dentro del
+contenedor corren como `root` (UID 0) — git, desde la versión que
+introdujo la protección CVE-2022-24765, rechaza operar sobre un repo
+cuyo dueño no coincide con el UID del proceso, a menos que el path
+esté explícitamente marcado como seguro.
+
+**Fix:** `git config --global --add safe.directory '*'` dentro del
+contenedor. El wildcard (en vez de listar cada repo) es intencional
+acá: este contenedor ya tiene acceso root-equivalente al host vía el
+volumen de `/var/run/docker.sock`, así que restringir `safe.directory`
+por repo no suma aislamiento real.
+
+**Por qué está en el comando de arranque y no como paso manual
+aparte:** igual que los paquetes `apk`, esta configuración vive en el
+filesystem efímero del contenedor (`/root/.gitconfig`, que no está
+bajo el volumen de `/root/.claude`) — se perdería si el contenedor se
+recrea. Ponerla en el `sh -c` de arranque la deja recreándose sola
+cada vez, sin pasos manuales que recordar.
+
+## Gotcha: la confianza del folder no persistía
+
+Al abrir `claude` por primera vez en un directorio, pide confirmar un
+diálogo de "¿confiás en este folder?" (más aún acá, porque este repo
+trae un `.claude/settings.local.json` con permisos pre-aprobados). Esa
+confirmación se guarda en `~/.claude.json` — un **archivo suelto en
+`/root`**, no dentro de la carpeta `~/.claude/` que ya estaba montada
+como volumen. Resultado: aunque el login (`~/.claude/.credentials.json`)
+sí persistía, el diálogo de confianza volvía a aparecer cada vez que
+se recreaba el contenedor — justo el tipo de "reconfigurar de nuevo"
+que este setup existe para evitar.
+
+**Cómo se detectó:** al confirmar el diálogo por primera vez, se
+comparó `/root/.claude.json` dentro del contenedor contra sí mismo
+antes y después — mismo tamaño y mismo `mtime`, es decir, la
+confirmación en pantalla nunca se había registrado. La causa real:
+la primera vez se movió el selector con las flechas pero nunca se
+presionó Enter, así que en rigor el diálogo seguía sin confirmar; una
+vez confirmado *de verdad* (`tmux send-keys` moviendo el cursor a
+"Yes, I trust this folder" + Enter), el archivo saltó de 2.2 KB a
+40 KB y apareció la clave `projects` con la ruta del repo adentro.
+
+**Fix:** copiar ese `.claude.json` ya confirmado a
+`/DATA/AppData/k3d-lab-v3/claude-code-home.json` en el host, y
+montarlo **archivo a archivo** (no como carpeta) en
+`-v .../claude-code-home.json:/root/.claude.json`. A diferencia de
+los demás volúmenes de este setup, este necesitó sembrarse con
+contenido real primero — un bind mount de archivo con un origen que
+no existe todavía en el host termina creando un directorio vacío en
+su lugar, no un archivo, y rompe el arranque del contenedor.
+Verificado en vivo: tras recrear el contenedor con este mount, `claude`
+arrancó directo en la sesión normal, sin volver a pedir el diálogo de
+confianza.
+
+Sobre paquetes: alpine (imagen `alpine` sin pin de versión, la misma
+que uso este setup) sí trae `kubectl` en sus repos — no hizo falta
+cambiar de imagen base ni instalarlo por binario aparte, contrario a
+lo que se sospechaba inicialmente. `nodejs`/`npm` (v24/v11 al momento
+de escribir esto) también están en los repos de alpine y cumplen de
+sobra el mínimo que pide Claude Code.
+
+**Nota sobre `--network host` + `docker.sock`:** el contenedor tiene,
+en la práctica, control equivalente a root sobre el NAS (puede lanzar
+cualquier otro contenedor con cualquier mount). Es una concesión
+deliberada — es exactamente lo que hace falta para seguir operando
+Docker/k3d desde dentro — no un descuido.
+
+## Reconexión: un solo comando
+
+```bash
+/media/HDD-Storage/AppData/k3d-lab-v3/lab-cruzcloud/scripts/lab-session.sh
+```
+
+El script (`scripts/lab-session.sh`) es intencionalmente el mismo
+comando sin importar el estado previo:
+
+```bash
+docker exec -it "$CONTAINER" tmux attach -t "$SESSION" || \
+  docker exec -it "$CONTAINER" tmux new -s "$SESSION"
+```
+
+Si la sesión `lab` existe, se adjunta a ella (mismo shell, mismo
+`claude` corriendo, mismo directorio de trabajo). Si no existe —por
+ejemplo justo después de que el contenedor se recreó desde cero— la
+crea. No hay que recordar cuál de los dos casos aplica.
+
+## Qué sobrevive a qué
+
+| Evento | ¿Sobrevive la sesión tmux (`lab`)? | ¿Sobrevive el login de Claude Code? |
+|---|---|---|
+| Corte de SSH / cerrar la terminal / cambiar de dispositivo | Sí — es exactamente el caso que este setup resuelve | Sí |
+| `docker restart tmux-host` (reinicio del NAS) | **No** — el proceso `tmux server` muere con el contenedor; `lab-session.sh` crea una sesión nueva automáticamente | Sí, vía el volumen montado en `/root/.claude` |
+| `docker rm` + recrear el contenedor desde cero | No | Sí, vía el mismo volumen — no hace falta volver a autenticar ni reconfirmar el diálogo de confianza del folder (ver el mount de `claude-code-home.json`) |
+
+## Validación en vivo
+
+Confirmado en este mismo lab (2026-08-27): se dejó una variable de
+entorno (`export MARCA_PERSISTENCIA=ok_<timestamp>`) corriendo dentro
+de la sesión `lab` vía `tmux send-keys`, y una invocación
+*completamente separada* de `docker exec` (equivalente a una nueva
+conexión) leyó de vuelta el mismo valor — confirma que el estado vive
+en el servidor tmux del contenedor, no en el cliente que se conecta.
+`claude --version` respondió `2.1.250` dentro de esa misma sesión, y
+un archivo de prueba escrito en `/root/.claude` dentro del contenedor
+apareció de inmediato en
+`/DATA/AppData/k3d-lab-v3/claude-code-home` en el host, confirmando
+el bind mount de credenciales.
+
+Después de agregar el mount de `/media/HDD-Storage` y el
+`safe.directory`, se validó además: `md5sum` de `CLAUDE.md` idéntico
+leído desde el host y desde dentro del contenedor (vía el path con
+symlink `/DATA/AppData/...`), y `git log`/`git status` corriendo sin
+error sobre `apps-registry` y `scripts` desde una shell dentro de
+`tmux-host`.

workloads/docs-portal/docs/arquitectura/vision-general.md

@@ -1,10 +1,10 @@
 # Visión general
 
-> **TODO (fase 2+):** narrativa completa explicando cada capa del
-> diagrama, con foco en el "por qué" de cada frontera de confianza. El
-> diagrama de abajo es real (validado contra `docs/known-issues.md` y
-> los playbooks de incidentes de `apps-registry`), pero el texto que lo
-> acompaña es solo el esqueleto.
+Este lab corre sobre un NAS ZimaOS doméstico, sin IP pública ni
+presupuesto de nube — cada capa del diagrama de abajo existe por una
+razón concreta de ese contexto, no por moda arquitectónica. Esta
+página explica el "por qué" de cada frontera; el "cómo" vive en las
+páginas enlazadas al final de cada sección.
 
 ## Flujo de una petición pública
 
@@ -40,4 +40,52 @@ flowchart LR
 | Argo CD | Sincroniza el estado del cluster con Git (patrón App of Apps) | Namespace `argocd` |
 | Gitea | Origen de verdad de los manifiestos y del código de las apps | Contenedor propio, expuesto vía túnel |
 
+## Por qué cada frontera está donde está
+
+**Cloudflare Tunnel, no port-forwarding.** El NAS vive detrás de NAT
+residencial, sin IP pública fija. En vez de abrir puertos en el router
+(superficie de ataque directa contra el hogar), `cloudflared` abre una
+conexión **saliente** hacia Cloudflare y todo el tráfico público viaja
+hacia adentro por esa misma conexión — el origen nunca expone un
+puerto escuchando en internet. El transporte de esa conexión se fijó a
+HTTP/2 en vez del QUIC por defecto tras un incidente real de
+inestabilidad; ver [ADR 0003](../decisiones/0003-por-que-http2-sobre-quic-tunnel.md).
+
+**Nginx Proxy Manager, fuera del cluster.** No todo lo que sirve
+`*.cruzcloud.net` vive dentro de k3d — Gitea, por ejemplo, corre como
+contenedor Docker aparte. NPM es el único punto de enrutamiento por
+dominio que necesita conocer *ambos* mundos (cluster y no-cluster), así
+que vive fuera de Kubernetes a propósito, no por descuido.
+
+**`k3d-lab-cluster-serverlb`, la frontera de entrada al cluster.** Es
+el load balancer que el propio k3d monta automáticamente para publicar
+puertos del host hacia los nodos internos — no es un componente que
+este lab configuró a mano, viene con la topología multi-nodo elegida
+en [ADR 0001](../decisiones/0001-por-que-k3d.md).
+
+**Traefik, enrutamiento por `Host` dentro del cluster.** Una vez el
+tráfico entra al cluster por un único puerto (90/9443), Traefik es
+quien decide a qué Service mandarlo según el header `Host` de cada
+petición — así NPM solo necesita saber "todo `*.cruzcloud.net` va al
+puerto 90 del cluster", sin tener que aprender un forward_host nuevo
+cada vez que se agrega un servicio interno. Cuando esta capa falla en
+silencio (`forward_host`/`forward_port` mal apuntado en NPM), el
+síntoma es siempre el mismo: "internamente sano, públicamente roto" —
+ver [Red y exposición](red-y-exposicion.md).
+
+**Argo CD, el único escritor del cluster.** Ningún pipeline de CI ni
+ninguna persona corre `kubectl apply` contra producción — Argo CD es
+la única pieza con permisos de escritura, y reconstruye
+automáticamente cualquier diferencia entre Git y el cluster real
+(`selfHeal: true`). El porqué completo de esa elección está en
+[ADR 0002](../decisiones/0002-por-que-argocd-vs-manual.md); el paso a
+paso de un commit real hasta quedar corriendo, en
+[Flujo GitOps](gitops-flujo.md).
+
+**Gitea, autoalojado.** Además de alojar el código, Gitea corre el CI
+(Gitea Actions) y el registry de imágenes en el mismo lugar — un solo
+componente autoalojado en vez de depender de la disponibilidad y los
+límites de un servicio externo gratuito para un lab que ya de por sí
+no tiene presupuesto de nube.
+
 Ver también: [Red y exposición](red-y-exposicion.md) · [Flujo GitOps](gitops-flujo.md) · [Glosario](glosario.md)

workloads/docs-portal/docs/decisiones/0001-por-que-k3d.md

@@ -1,33 +1,67 @@
 # ADR 0001 — Por qué k3d (y no k3s directo, minikube, o un cluster cloud)
 
-> **TODO (fase 2+):** completar contexto/opciones/consecuencias con
-> criterio real (recursos del NAS ZimaOS, necesidad de multi-nodo para
-> reproducir el blackhole de MTU documentado en `known-issues.md`,
-> costo cero vs. cluster gestionado).
-
-**Estado:** aceptada (placeholder — pendiente de redactar)
-**Fecha:** TODO
+**Estado:** aceptada
+**Fecha:** 2026-08 (retroactiva — decisión tomada al arrancar el lab, documentada en Fase 2 del portal)
 
 ## Contexto
 
-TODO
+El lab corre sobre un NAS ZimaOS doméstico, sin presupuesto para un
+cluster gestionado y con recursos modestos y compartidos con otras
+apps del NAS (Gitea, Nginx Proxy Manager, este mismo portal). El
+propósito del lab es doble: servir de portafolio técnico real y de
+material de estudio para el hijo del usuario (7mo semestre de
+Ingeniería de Sistemas) — ver [guía del estudiante](../guia-estudiante/README.md).
+Para que ambos objetivos tengan sentido, el cluster necesitaba
+comportarse como un Kubernetes real y multi-nodo, no como una caja de
+arena de un solo proceso: patrones como afinidad de pods, StatefulSets
+con almacenamiento persistente por nodo, y tráfico cross-node debían
+poder reproducirse y depurarse de verdad, no simularse.
+
+También pesó la restricción del propio sistema operativo: `/` en
+ZimaOS es un `squashfs` de solo lectura y `/usr` es un overlay
+igualmente inmutable — instalar un binario nativo como `k3s` que
+espera escribir en `/usr/local/bin`, `/etc/rancher`, etc. de forma
+persistente no encaja bien con ese filesystem sin trabajo extra de
+por medio.
 
 ## Opciones consideradas
 
 | Opción | A favor | En contra |
 |---|---|---|
-| k3d | | |
-| k3s directo (sin Docker) | | |
-| minikube | | |
-| Cluster gestionado (cloud) | | |
+| **k3d** | Multi-nodo real corriendo como contenedores Docker (server + agent), se crea/destruye en segundos, no toca el filesystem inmutable de ZimaOS más allá de `/DATA` | Al ser Docker-in-Docker, hereda las capas de red de Docker — un blackhole de MTU/PMTUD real apareció por esto (ver Consecuencias) |
+| k3s directo (sin Docker) | Sin la capa extra de red de Docker-in-Docker, más cercano a un nodo "real" | Necesita instalar servicios systemd y escribir en rutas de sistema (`/usr/local/bin`, `/etc/rancher`) que en ZimaOS son de solo lectura o requieren workarounds — solo `/DATA` y `/etc` quedan escribibles |
+| minikube | Instalación simple, muy documentado, ideal para aprender lo básico | Single-node por defecto — no permite reproducir tráfico cross-node, afinidad de pods, ni el tipo de incidentes de infraestructura real que este lab busca documentar como aprendizaje |
+| Cluster gestionado (cloud) | Cero mantenimiento de infraestructura, SLA real | Costo recurrente que este lab no tiene presupuestado; además reduce el valor de aprendizaje — gran parte de lo documentado en `playbooks/` (MTU, DNS, límites de recursos) es justamente lo que un proveedor gestionado abstrae |
 
 ## Decisión
 
-TODO
+k3d, multi-nodo (hoy: 1 server + 1 agent, `k3d-lab-cluster-server-0` /
+`k3d-lab-cluster-agent-0`), corriendo como contenedores Docker sobre
+el propio NAS.
 
 ## Consecuencias
 
-TODO — mencionar explícitamente el blackhole de red cross-node
-(MTU/PMTUD) como consecuencia real y documentada de correr multi-nodo
-sobre Docker-in-Docker sin ajuste de MTU (ver
-[playbook del crashloop de Medusa](../playbooks/incidente-crashloop-medusa.md)).
+- **Se ganó** un cluster real y gratuito, reproducible con un solo
+  script (`scripts/deploy-lab.sh`), y suficientemente parecido a un
+  Kubernetes de producción como para que los incidentes documentados
+  en `playbooks/` sean transferibles a un entorno cloud real.
+- **Se pagó** con un blackhole de red cross-node real: cualquier pod
+  agendado en un nodo distinto al de `commerce-postgres-0`
+  (StatefulSet, fijo a un nodo) fallaba de forma consistente al hablar
+  con Postgres — diagnosticado hasta el bit exacto (payload interno
+  1420 bytes OK, 1450 bytes blackhole total, sin ICMP "frag needed")
+  y resuelto ajustando el MTU real de la interfaz `flannel.1` a 1400
+  en cada nodo. Ver [known-issues.md](https://gitea.cruzcloud.net/devops/apps-registry/src/branch/main/docs/known-issues.md)
+  y el [playbook del crashloop de Medusa](../playbooks/incidente-crashloop-medusa.md)
+  para el diagnóstico completo. El fix no persiste solo — está
+  automatizado en `scripts/deploy-lab.sh` (función `fix_flannel_mtu`),
+  se reaplica cada vez que el cluster arranca o se recrea.
+- **Deuda aceptada a propósito**: el `podAffinity` que fuerza a
+  `medusa-deploy` a compartir nodo con Postgres se dejó como red de
+  contención extra después del fix de fondo — no es estrictamente
+  necesario, pero es barato mantenerlo.
+- **Para revertir esta decisión** haría falta migrar a un cluster
+  gestionado o a `k3s` nativo, lo que implicaría asumir el costo
+  recurrente (cloud) o resolver las restricciones de filesystem
+  inmutable de ZimaOS (k3s nativo) — ninguna de las dos se justifica
+  hoy con el tamaño real del lab.

workloads/docs-portal/docs/decisiones/0002-por-que-argocd-vs-manual.md

@@ -1,30 +1,80 @@
 # ADR 0002 — Por qué Argo CD (y no `kubectl apply` manual o un script de CI)
 
-> **TODO (fase 2+):** completar con el criterio real detrás de elegir
-> reconciliación continua (`selfHeal`) sobre despliegue imperativo desde
-> CI.
-
-**Estado:** aceptada (placeholder — pendiente de redactar)
-**Fecha:** TODO
+**Estado:** aceptada
+**Fecha:** 2026-08 (retroactiva — decisión tomada al arrancar el lab, documentada en Fase 2 del portal)
 
 ## Contexto
 
-TODO
+Desde el principio el lab iba a tener más de un repo Git (hoy:
+`apps-registry` para las Applications y los manifiestos reales de los
+workloads, `platform-infra` para la gobernanza de cada namespace,
+`scripts` para bootstrap/operación) y más de una app corriendo en el
+cluster (ecommerce, docs-portal, nginx, cada una con su propia
+gobernanza). Se necesitaba una forma de mantener el estado del
+cluster sincronizado con lo declarado en Git que escalara a "agregar
+una app nueva" sin volverse un proceso manual que dependiera de que
+una sola persona recordara qué `kubectl apply` correr y en qué orden.
+
+También importaba la trazabilidad: en un lab que sirve de portafolio,
+poder señalar "este commit es exactamente lo que está corriendo en
+producción" (y por qué) tiene valor por sí mismo — no solo operativo.
 
 ## Opciones consideradas
 
 | Opción | A favor | En contra |
 |---|---|---|
-| Argo CD (GitOps, pull-based) | | |
-| `kubectl apply` manual | | |
-| `kubectl apply` desde el pipeline de CI (push-based) | | |
+| **Argo CD (GitOps, pull-based)** | Reconciliación continua: un proceso dentro del cluster compara el estado real contra Git y corrige la diferencia solo, sin que nadie tenga que acordarse de aplicar nada. Patrón App of Apps nativo — agregar una app nueva es un archivo YAML más en `apps/`, no un paso manual nuevo | Componente extra que mantener sano (su propio namespace, su propio consumo de recursos) |
+| `kubectl apply` manual | Cero infraestructura extra, control total en cada comando | Sin detección de drift — si alguien edita algo a mano y lo olvida, nadie se entera hasta que rompe; no escala más allá de un solo operador que recuerde el estado completo de memoria |
+| `kubectl apply` desde el pipeline de CI (push-based) | No agrega un componente nuevo al cluster, reutiliza el CI que ya existe para construir imágenes | El pipeline de CI necesitaría credenciales de escritura amplias sobre el cluster — más superficie de riesgo si esas credenciales se filtran. Push-based además significa que nada vuelve a comparar el estado después de aplicado: un drift posterior (alguien con `kubectl` directo) queda invisible hasta el siguiente deploy |
 
 ## Decisión
 
-TODO
+Argo CD, patrón App of Apps: una Application raíz
+(`apps-registry/application.yaml`) vigila la carpeta `apps/`, y cada
+archivo ahí dentro es una Application hija que apunta a un workload
+real. Toda Application se declara con el mismo `syncPolicy`:
+
+```yaml
+syncPolicy:
+  automated:
+    prune: true
+    selfHeal: true
+  syncOptions:
+    - CreateNamespace=true
+```
+
+(configuración real de `apps/ecommerce-app.yaml`, repetida en cada
+Application del repo)
 
 ## Consecuencias
 
-TODO — mencionar el patrón App of Apps (`application.yaml` +
-`apps/*.yaml`) y cómo `selfHeal:true` cambia el modelo mental de
-"quién puede tocar el cluster".
+- **`selfHeal: true` cambia el modelo mental de quién puede tocar el
+  cluster de verdad.** No es solo que Argo CD detecte diferencias y
+  las muestre como `OutOfSync` — las revierte activamente. Si alguien
+  corre `kubectl scale` o `kubectl edit` directo contra un recurso
+  gestionado, en el siguiente ciclo de reconciliación (poll periódico,
+  o inmediato si el commit llegó por webhook) Argo CD lo vuelve a
+  dejar exactamente como dice Git. Git deja de ser "la intención" y
+  pasa a ser literalmente la única fuente de la que el cluster puede
+  aprender su propio estado — ver [flujo GitOps](../arquitectura/gitops-flujo.md).
+- **`prune: true`** significa que borrar un recurso del repo (por
+  ejemplo, quitar `meilisearch.yaml` de una `kustomization.yaml`) lo
+  borra también del cluster en el siguiente sync, sin un paso manual
+  de limpieza — confirmado en la práctica en varias fases de este lab
+  (ver los ADRs de rediseño del storefront y de Meilisearch).
+- **El rol de CI se redujo a "construir, publicar imagen, y dejar un
+  commit en Git"** — nunca aplica nada directo al cluster. Esto evitó
+  tener que darle a CI credenciales de cluster, y dejó un problema real
+  documentado (la condición de carrera de promoción cuando dos
+  pipelines corren en serie sobre el mismo commit) resoluble
+  comparando contra Git (`git merge-base --is-ancestor`) en vez de
+  contra el estado del cluster.
+- **Se paga con un componente más que mantener sano**: Argo CD corre
+  en su propio namespace, con su propio consumo de recursos y su
+  propia superficie de fallo — un Argo CD caído no rompe lo que ya
+  está corriendo (el cluster sigue con el último estado aplicado),
+  pero sí detiene la sincronización de cambios nuevos.
+- **Para revertir esta decisión** haría falta volver a un modelo
+  push-based (CI aplicando directo) o puramente manual, perdiendo la
+  reconciliación continua y aceptando que un drift manual pueda pasar
+  desapercibido.

workloads/docs-portal/docs/decisiones/0004-evaluacion-stack-multi-categoria.md

@@ -109,7 +109,10 @@ Un motor de búsqueda dedicado (Meilisearch, autohospedado) queda
 identificado como el siguiente paso natural una vez el catálogo
 crezca más allá de ~100 productos activos, pero no es parte del
 alcance inmediato de Etapa 2 — se revisará cuando ese techo esté
-cerca.
+cerca. **Actualización 2026-08-25:** terminada la Etapa 2 (ver
+[ADR 0005](0005-rediseno-storefront.md)), el disparador real resultó
+ser la complejidad de facetas de la taxonomía, no el volumen de
+productos — ver [ADR 0006](0006-motor-busqueda-facetas.md).
 
 **Compatibilidad con Medusa Admin confirmada:** ninguna de las tres
 opciones evaluadas, incluida la elegida, toca

workloads/docs-portal/docs/decisiones/0005-rediseno-storefront.md

@@ -1,13 +1,14 @@
 # ADR 0005 — Rediseño del storefront para catálogo multi-categoría
 
-**Estado:** propuesta — pendiente de aprobación antes de Etapa 2
-**Fecha:** 2026-08-23
+**Estado:** aceptada — Etapa 2 implementada y en producción
+**Fecha:** 2026-08-23 (Etapa 1) — actualizado 2026-08-25 (Etapa 2 completa)
 
-> Este documento es la propuesta de Etapa 1 del rediseño de ARI
-> Shopping. No incluye código de producción — solo auditoría,
-> decisión (ver también [ADR 0004](0004-evaluacion-stack-multi-categoria.md)),
-> patrones de UX y datos demo ya creados y visibles en producción
-> como línea base.
+> Este documento arrancó como la propuesta de Etapa 1 del rediseño de
+> ARI Shopping (auditoría, decisión — ver también [ADR 0004](0004-evaluacion-stack-multi-categoria.md) —
+> patrones de UX y datos demo). Etapa 2 fue aprobada y se implementó
+> completa en tres sub-fases (datos/categorías, navegación,
+> componentes visuales) — ver la sección 6 para el detalle de cada
+> sub-fase y sus PRs.
 
 ## 1. Resumen de la auditoría
 
@@ -255,12 +256,33 @@ objetivo es validar la tubería Admin → MinIO → NPM → frontend, no el
 contenido visual final.
 
 Usuario admin temporal `[email protected]` usado para esta
-auditoría — pendiente de borrar una vez aprobada esta propuesta.
+auditoría — pendiente de borrar (ver sección 6).
 
-## 6. Próximos pasos
+## 6. Etapa 2 — implementada (2026-08-23 a 2026-08-25)
 
-Pendiente de tu aprobación explícita antes de iniciar Etapa 2. Cuando
-apruebes, Etapa 2 se dividirá en sub-fases (datos/categorías primero,
-luego navegación, luego componentes visuales), validando en cada paso
-contra estos 9 productos demo que precio/descripción/imágenes siguen
-actualizándose correctamente desde Admin.
+Aprobada y ejecutada en tres sub-fases, cada una validada en vivo
+contra estos 9 productos demo:
+
+1. **Datos/categorías** (2026-08-23/24): fix del bug de Store API que
+   impedía ver la categoría real de un producto (causa raíz del ADR
+   0004); 21 categorías/9 productos demo creados; `legacyProductMeta`
+   eliminado (PR #29) — 17 productos legacy con categoría/colección/
+   marca/rango de edad reales.
+2. **Navegación** (2026-08-25): navbar y tiles del home pasaron de
+   arrays hardcodeados a data-driven contra el árbol real de
+   categorías (`getCategories()`, PR #32); guard de CI actualizado
+   (PR #33); fix de tipos (PR #34); home/layout forzados a render
+   dinámico para evitar que quedaran cacheados con datos mock (PR #35).
+3. **Componentes visuales** (2026-08-25), los 4 patrones de la
+   sección 3 más el breadcrumb/facetas de Amazon: mega-menú
+   "Departamentos" multi-columna (PR #36), badges antes/ahora
+   (PR #37), swatches de variante inline (PR #38), mensaje de
+   urgencia por inventario real (PR #39), breadcrumb real + conteos
+   por filtro en el catálogo (PR #40), tiles promocionales
+   intercalados en la grilla (PR #41, con fix-forward de tipos en
+   PR #42).
+
+El usuario admin temporal `[email protected]` (creado para la
+auditoría de la sección 5) fue borrado el 2026-08-27 vía Medusa Admin.
+Sin próxima etapa definida todavía — este ADR no especifica una
+Etapa 3.

workloads/docs-portal/docs/decisiones/0006-motor-busqueda-facetas.md

@@ -0,0 +1,330 @@
+# ADR 0006 — Motor de búsqueda y filtros facetados (Fase 5, Etapa 3)
+
+**Estado:** aceptada — Etapa 2 en implementación (aprobada 2026-08-26 tras diagnóstico de memoria del host)
+**Fecha:** 2026-08-25
+
+## Contexto
+
+[ADR 0004](0004-evaluacion-stack-multi-categoria.md) ya identificó un
+motor de búsqueda dedicado (Meilisearch, autohospedado) como "el
+siguiente paso natural" para ARI Shopping, pero lo dejó fuera del
+alcance de Etapa 2 explícitamente hasta que el catálogo se acercara al
+techo real de ~100 productos activos que impone
+`fetchProducts(filters, limit = 100)` en `medusa.ts`.
+
+**Ese techo todavía no llegó** — el catálogo real hoy son 26 productos
+(17 legacy + 9 demo, ver [ADR 0005](0005-rediseno-storefront.md)
+sección 5), lejos de 100. El disparador de esta propuesta no es el
+techo de volumen sino la **complejidad de facetas**: la Etapa 2 ya
+construyó una taxonomía real de 6 categorías raíz / 21 nodos
+(navegación, mega-menú, breadcrumb — PRs #36-42) y un filtrado con
+conteo por valor (`categoryCounts`/`brandCounts`/`ageCounts` en
+`catalog-client.tsx`, PR #40) que hoy se calcula **100% client-side**
+sobre los productos ya traídos — el mismo patrón de "deuda de
+alcance" que el hallazgo #4 de ADR 0004 ya señaló, ahora con más
+dimensiones de filtro que multiplicar. Sigue siendo tratable a 26
+productos; deja de serlo mucho antes de llegar a 100 si el catálogo
+crece a la vez en número de productos y en dimensiones filtrables.
+
+Restricción no negociable, igual que en toda la Fase 5: el flujo
+**Admin → evento `product.updated` → `revalidate-storefront.ts` →
+`revalidateTag("medusa-products")`**, que hoy mantiene el storefront
+sincronizado sin intervención manual, no se toca. Cualquier índice de
+búsqueda debe sincronizarse por el mismo mecanismo de eventos, nunca
+por un cron ni un paso manual.
+
+## 1. Estado real de la integración Medusa v2 + Meilisearch
+
+Verificado contra la documentación oficial vigente el 2026-08-25, no
+contra memoria de entrenamiento:
+
+- **Medusa no tiene un módulo de búsqueda propio integrado con
+  Meilisearch hoy.** La guía oficial
+  (`docs.medusajs.com/resources/integrations/guides/meilisearch`) es
+  un tutorial de módulo custom desde cero (`npm install meilisearch` +
+  workflows/subscribers propios) — no un paquete instalable.
+- **Medusa sí introdujo un "Search Module" propio en la versión
+  2.19.0.** El paquete comunitario `@rokmohar/medusa-plugin-meilisearch`
+  (el más usado y mantenido para Meilisearch+Medusa) se conecta a ese
+  Search Module desde su versión `^2.0.0`, pero esa versión del plugin
+  **requiere Medusa `^2.19.0`**.
+- **Nuestro backend corre Medusa `2.18.0`** (`commerce-backend/package.json`)
+  — justo por debajo de ese corte. La tabla de compatibilidad del
+  plugin (`github.com/rokmohar/medusa-plugin-meilisearch`) resuelve
+  esto: la línea `^1.4.1` soporta `Medusa >= 2.15 < 2.19`, servidor
+  Meilisearch `>= 1.5`, Node `>= 22`. El propio repo lo explica: *"The
+  2.19 release removed the search interface the v1 line was written
+  against, so the two lines do not overlap: v1 stops at Medusa 2.18,
+  v2 starts at 2.19."*
+- Node de `commerce-backend` ya es `22.18.0` (Dockerfile) — cumple el
+  mínimo del plugin sin cambios.
+
+**Implicación concreta:** para adoptar Meilisearch sin subir de
+versión Medusa (fuera de alcance de este ADR — sería su propia
+migración), la pieza a instalar es `@rokmohar/medusa-plugin-meilisearch@^1.4.1`,
+no la última versión del plugin. Esto es deuda técnica documentada,
+no un obstáculo: si en el futuro se sube Medusa a `2.19+`, migrar a la
+línea `^2.0.0` del plugin (y al Search Module nativo) es el camino
+recto.
+
+## 2. Impacto de recursos
+
+Estado real del host ZimaOS al momento de esta auditoría (`free -h`,
+`docker stats`): 15 GiB RAM totales, **swap al 100% (5.2/5.2 GiB
+usados)**, solo 351 MiB realmente libres (6.5 GiB "available" vía
+cache reclamable), 4 vCPU — la misma clase de contención que ya forzó
+el fix de `cpu_shares` de Gitea. Cualquier servicio nuevo en este host
+es una decisión de capacidad real, no teórica.
+
+- **Meilisearch no publica un mínimo de RAM oficial.** Su propio FAQ
+  (`meilisearch.com/docs/resources/help/faq`) solo dice que "más RAM
+  implica búsquedas más rápidas" y recomienda ~10x el tamaño del
+  dataset crudo en disco — sin piso duro. La cifra de "~1 GiB
+  cómodo" que circula en blogs de la comunidad es una estimación, no
+  una garantía del proveedor — se cita aquí como referencia, no como
+  hecho verificado.
+- Meilisearch usa almacenamiento memory-mapped: el índice puede vivir
+  parcialmente en disco cuando no entra en RAM, degradando latencia en
+  vez de fallar. A la escala actual (26 productos, dataset de KB) el
+  uso real de RAM del índice en sí es insignificante — el costo es el
+  proceso base de Meilisearch, no el dataset.
+- **Comparación con Typesense** (pedida explícitamente, mantenida
+  breve porque la diferencia relevante para este caso es clara y no
+  requiere más profundidad): Typesense mantiene el índice completo en
+  RAM (~30% más RAM que Meilisearch para el mismo dataset, según
+  benchmarks públicos) y, a diferencia de Meilisearch, **no tiene
+  ningún plugin ni integración con Medusa** — habría que escribir la
+  sincronización completa desde cero igual que con la guía "custom"
+  de Meilisearch, pero sin ninguna base comunitaria mantenida
+  compatible con nuestra versión de Medusa. Con Meilisearch ya
+  teniendo un plugin activo para `Medusa 2.18` y menor huella de RAM,
+  no hay motivo para evaluar Typesense más a fondo en este caso.
+- **Recomendación:** desplegar Meilisearch en k3d con `requests`/`limits`
+  explícitos y conservadores desde el día uno (ej. `request: 256Mi/0.1
+  CPU`, `limit: 768Mi/0.5 CPU` — a ajustar con datos reales de uso, no
+  supuestos), y tratarlo como el mismo tipo de riesgo operativo que ya
+  se vivió con Gitea: monitorear consumo real post-despliegue antes de
+  darlo por estable. Dado el swap ya saturado, este es el punto de
+  mayor incertidumbre de toda la propuesta — más que la elección de
+  motor de búsqueda en sí.
+
+## 3. Modelo de indexación
+
+Basado en la taxonomía real ya viva en Medusa (Etapa 2) y en
+`Product`/`Category` de `lib/headless/types.ts`:
+
+| Campo | Buscable (texto, tolerante a typos) | Filtrable / faceta | Ordenable |
+|---|---|---|---|
+| `name` | Sí | No | No |
+| `shortDescription` / `description` | Sí | No | No |
+| `category` (nombre de la hoja real) | Sí | Sí (con conteo) | No |
+| `collection` | Sí | Sí (con conteo) | No |
+| `brand` | Sí | Sí (con conteo) | No |
+| `ageRange` | No | Sí (con conteo) | No |
+| `tags` | Sí | No | No |
+| `price` | No | Sí (rango) | Sí |
+| `compareAtPrice` | No | No | No (solo se usa para el badge, no como filtro) |
+| `isNew` / `featured` | No | No | Sí (orden "Novedades"/"Destacados", igual que hoy) |
+| `available` | No | Sí (booleano) | No |
+| `slug`, `thumbnail`, `id` | No | No | No (solo se devuelven, no se indexan como facetas) |
+
+La jerarquía de categorías (raíz/hija) no se indexa como un campo
+aparte: el índice guarda el nombre de la hoja real tal como hoy lo
+hace `product.category`, y el breadcrumb/mega-menú siguen resolviendo
+la jerarquía contra `/store/product-categories` (sin cambios, ya
+funciona desde la sub-fase 2). El motor de búsqueda resuelve
+**búsqueda de texto + conteo de facetas**, no reemplaza la fuente de
+la jerarquía.
+
+## 4. Diseño de sincronización
+
+Mismo patrón que `revalidate-storefront.ts`, no uno nuevo: un
+subscriber adicional en `commerce-backend/src/subscribers/` (ej.
+`sync-search-index.ts`) que reacciona a eventos y le pide al plugin
+que reindexe el documento afectado — nunca Medusa escribiendo
+directamente en Meilisearch fuera de este canal.
+
+Eventos a escuchar, confirmados en la documentación oficial de
+eventos de Medusa (`docs.medusajs.com/resources/events-reference`):
+
+- `product.created` / `product.updated` / `product.deleted`
+- `product-variant.created` / `product-variant.updated` / `product-variant.deleted`
+  (mismo set que ya usa `revalidate-storefront.ts`, hoy validado en
+  producción)
+- **Nuevo respecto al subscriber actual:** `product-category.created`
+  / `product-category.updated` / `product-category.deleted` — un
+  cambio de nombre o jerarquía de categoría debe refrescar las
+  facetas del índice, y hoy `revalidate-storefront.ts` no escucha
+  estos eventos porque el storefront los resuelve en cada request
+  contra `/store/product-categories` directamente, sin necesidad de
+  revalidación. El índice de búsqueda sí necesita enterarse.
+
+**Punto a verificar en vivo en Etapa 2, no asumido aquí:** existe al
+menos un reporte público de un evento `product-collection.updated`
+que no se disparaba de forma confiable en ciertas versiones de Medusa
+(`github.com/medusajs/medusa/issues/11197`). Antes de dar por cerrado
+el diseño de sincronización hay que repetir exactamente la validación
+que ya se hizo para `revalidate-storefront.ts` en la auditoría de
+Etapa 1 de Fase 5: crear/editar una categoría real vía Admin y
+confirmar en vivo que el evento llega al subscriber, no confiar en que
+la documentación coincide con el comportamiento real de `2.18.0`
+(el mismo tipo de brecha que ya se encontró una vez con la relación
+`+categories` de `/store/products`).
+
+## 5. Diseño de UI — filtros facetados y búsqueda
+
+**Filtros facetados (sidebar de `/catalog`):** mismo layout que ya
+construyó la sub-fase 3 (`catalog-client.tsx`, PR #40) — sidebar con
+"Categoría"/"Marca"/"Edad" como pills con conteo entre paréntesis y
+slider de precio máximo. Lo único que cambia es **de dónde sale el
+conteo**: hoy `categoryCounts`/`brandCounts`/`ageCounts` se calculan
+recorriendo el arreglo de productos ya traído en el cliente; con el
+motor de búsqueda, esos conteos vienen del propio Meilisearch
+(`facetDistribution`) en la misma respuesta que trae los productos
+filtrados, sin recorrer nada en el navegador. El breadcrumb no cambia
+— sigue resolviéndose contra la jerarquía real de categorías, no
+contra el índice de búsqueda.
+
+```
+Inicio > Mochilas y morrales > Marvel                 breadcrumb real (sin cambios)
+┌────────────┬──────────────────────────────────────┐
+│ Categoría  │  [buscador con autocompletado]        │  ← nuevo
+│ ☐ Marvel(6)│  [card][card][card]                   │
+│ ☐ Frozen(4)│  [card][card][card]                   │
+│ Marca      │                                        │
+│ ☐ Disney(2)│  conteos ahora vienen de Meilisearch,  │
+│ Precio     │  no de recorrer el arreglo en cliente  │
+│ [====○===] │                                        │
+└────────────┴──────────────────────────────────────┘
+```
+
+**Búsqueda con autocompletado (barra del navbar):** hoy
+`PredictiveSearch` (`components/search/predictive-search.tsx`) filtra
+por substring sobre los productos ya cargados en memoria del cliente —
+funciona a 26 productos, no escala y no tolera errores de tipeo (ADR
+0004, hallazgo #5). Se reemplaza la fuente de datos del mismo
+componente visual por `searchProducts(query)` del `CatalogProvider`
+(interfaz que **ya existe** en `lib/headless/types.ts`, sin necesidad
+de un tipo nuevo) apuntando a Meilisearch en vez de al `?q=` de
+Medusa: tolerancia a typos y ranking por relevancia nativos del motor,
+mismo contrato de datos que ya consume el dropdown de resultados —
+cero cambio de componente React, solo de qué hay detrás de
+`CatalogProvider.searchProducts`.
+
+## Opciones consideradas
+
+| Opción | A favor | En contra |
+|---|---|---|
+| **Meilisearch autohospedado** (`@rokmohar/medusa-plugin-meilisearch@^1.4.1`, sincronizado por eventos) | Plugin comunitario activo y compatible con nuestra versión exacta de Medusa (2.18); menor huella de RAM que la alternativa evaluada; almacenamiento memory-mapped se degrada en vez de fallar bajo presión de memoria; mismo patrón de subscriber que `revalidate-storefront.ts`, cero riesgo para ese flujo | Ningún paquete "oficial" de Medusa (el plugin es comunitario, no del core); atado a la línea `v1` del plugin mientras no se suba Medusa a 2.19+; un servicio más para operar en un host ya con swap saturado |
+| **Typesense autohospedado** | Autocompletado ~2x más rápido según benchmarks públicos | Cero integración con Medusa (habría que escribir la sincronización completa desde cero, igual esfuerzo que la guía "custom" de Meilisearch pero sin base comunitaria); ~30% más RAM que Meilisearch para el mismo dataset, el peor trade-off posible dado el estado actual del host |
+| **Módulo custom desde cero** (seguir la guía oficial de Medusa, sin el plugin de rokmohar) | Sin dependencia de un paquete de terceros; control total | Reimplementa lo que el plugin comunitario ya resuelve (declaración de índices, reindexado atómico, tracking de escrituras); más superficie propia para mantener sin ganancia clara sobre usar el plugin ya compatible con 2.18 |
+| **No adoptar motor de búsqueda todavía** (seguir con filtrado 100% client-side) | Cero riesgo, cero componente nuevo | No resuelve la deuda de facetas ya identificada en ADR 0004 y agravada por la sub-fase 3; el techo de complejidad de filtros llega antes que el de 100 productos si el catálogo sigue creciendo en categorías |
+
+## Decisión
+
+**Meilisearch autohospedado**, vía `@rokmohar/medusa-plugin-meilisearch@^1.4.1`
+(no la última versión del plugin — esa exige Medusa 2.19+, fuera de
+alcance), sincronizado por el mismo patrón de subscriber por eventos
+que ya usa `revalidate-storefront.ts`, con `product-category.*` sumado
+al set de eventos existente. Se despliega en k3d con límites de
+recursos conservadores desde el primer día y se trata como
+experimento a monitorear, no como capacidad garantizada, dado el
+estado actual de memoria del host.
+
+**No se sube la versión de Medusa como parte de esta decisión** —
+queda como deuda técnica documentada para cuando se justifique
+migrar a la línea `v2` del plugin y al Search Module nativo de
+Medusa.
+
+## Consecuencias
+
+- Se gana: conteo de facetas real (no client-side), búsqueda tolerante
+  a errores de tipeo con ranking por relevancia, y una arquitectura
+  que ya no depende del techo de 100 productos de `fetchProducts`.
+- Se acepta como deuda técnica: quedar atado a la línea `v1` del
+  plugin de Meilisearch mientras Medusa siga en `2.18.x`; migrar a
+  Medusa `2.19+` es un proyecto aparte, no parte de esta Etapa 3.
+- Riesgo operativo real y no resuelto todavía por este ADR: el host ya
+  corre con el swap saturado — el despliegue de Etapa 2 debe empezar
+  con límites de recursos conservadores y validación en vivo de
+  consumo real antes de confiar en el servicio, siguiendo la misma
+  lección que dejó el incidente de recursos de Gitea.
+- Revertir esta decisión implica desinstalar el plugin y el
+  subscriber nuevo, y volver el buscador/filtrado a 100% client-side
+  — no hay migración de datos que deshacer, porque Meilisearch nunca
+  es la fuente de verdad, solo una copia de solo lectura indexada
+  desde Medusa.
+
+## Nota de implementación (2026-08-26, antes de escribir código de Etapa 2)
+
+Antes de tocar código se verificó el código fuente real de
+`@rokmohar/medusa-plugin-meilisearch` en el tag exacto `v1.4.1`
+(`github.com/rokmohar/medusa-plugin-meilisearch`), no su README
+genérico ni memoria de entrenamiento — misma disciplina que ya destapó
+el bug de `+categories` en `/store/products`. Aparecieron tres
+desviaciones reales respecto al diseño de §4/§5 de este ADR:
+
+1. **No se escribe un subscriber nuevo.** El plugin trae sus propios
+   subscribers (`meilisearch-product-upsert.ts`,
+   `meilisearch-category-upsert.ts`, variantes/colección/inventario),
+   auto-registrados al instalar el paquete — el propio README dice
+   *"You don't need custom subscribers anymore, you can remove them."*
+   Escribir `sync-search-index.ts` como describe §4 causaría doble
+   indexado. La escucha de `product-category.*` que pedía §4 ya viene
+   incluida en los subscribers del plugin.
+2. **Las rutas Store API del plugin no devuelven `facetDistribution`**,
+   pese a que §5 asume que sí. El servicio interno
+   (`MeiliSearchService.search()`) sí puede pedirlo vía
+   `additionalOptions: { facets: [...] }`, pero las rutas
+   empaquetadas nunca lo piden ni lo reenvían. Se agrega una ruta
+   Store API propia (`src/api/store/search/route.ts`) que resuelve el
+   servicio del plugin desde el container y arma
+   `{ products, facetDistribution }`. Consecuencia positiva no
+   buscada: Meilisearch queda 100% `ClusterIP`-only, sin Ingress, sin
+   key pública ni ruta de red navegador→Meilisearch — todo pasa por
+   Medusa.
+3. **El plugin se conecta vía un array `plugins:` nuevo en
+   `medusa-config.ts`**, no otra entrada en `modules:` (el único
+   precedente en este repo, el file-provider S3, usa `modules:`), y
+   usa nombres de env var propios (`MEILISEARCH_HOST`/
+   `MEILISEARCH_API_KEY`, leídos por el plugin) distintos del env var
+   del servidor Meilisearch en sí (`MEILI_MASTER_KEY`, leído por el
+   contenedor `getmeili/meilisearch`) — mismo valor, dos nombres de
+   secret.
+
+Ninguna de las tres cambia la decisión ni sus consecuencias — cambian
+el cómo, no el qué. Plan de implementación completo, fase por fase,
+en la sesión que aprobó esta Etapa 2 (2026-08-26).
+
+## Nota de implementación 2 (2026-08-26, gate en vivo de Fase 2)
+
+Dos bugs reales encontrados y corregidos durante el gate de
+verificación en vivo (crear/editar productos, categoría y colección
+reales y confirmar que llegan a Meilisearch), ambos con la misma causa
+raíz: `variants.calculated_price` de Medusa exige `region_id` **y**
+`currency_code` resueltos en el contexto de pricing de la consulta, y
+ninguno de los dos caminos nuevos de este ADR pasa por el middleware
+nativo (`setPricingContext`) que se lo da gratis a `/store/products`:
+
+1. El job de sync inicial del plugin (`sync-products.js`, corre una
+   vez al boot) hacía fallar el indexado de **todos** los productos
+   con `Method calculatePrices requires currency_code in the pricing
+   context` — las categorías sí indexaban bien (no llevan precio).
+   Arreglado indexando el precio crudo (`variants.prices`, sin
+   resolver promociones/reglas) en vez de `calculated_price` — alcanza
+   para el filtro/orden por precio de la búsqueda.
+2. La ruta propia `/store/search` pegaba el mismo error al re-hidratar
+   productos vía `query.graph`. Pasar `region_id` solo no alcanzó;
+   hubo que resolver el `currency_code` real de la región con una
+   consulta adicional antes de armar el `QueryContext`.
+
+Confirmado en vivo, con el fix aplicado: búsqueda por texto, facetas
+sobre las 27 unidades del catálogo real, y precio calculado correcto
+(`calculated_amount`/`currency_code`) en la respuesta de
+`/store/search`. También confirmado en vivo que los tres eventos que
+el ADR original marcaba como "verificar, no asumir" — `product.*`,
+`product-category.*` y **`product-collection.updated`** (el que tenía
+un reporte público de no disparar siempre) — sí sincronizan de forma
+confiable en esta combinación exacta (Medusa 2.18.0 + plugin 1.4.1),
+propagando un rename de categoría/colección al documento indexado en
+menos de 10 segundos.

workloads/docs-portal/docs/decisiones/0007-identidad-visual-propia.md

@@ -0,0 +1,232 @@
+# ADR 0007 — Identidad visual propia para ARI Shopping
+
+**Estado:** reemplazada por [ADR 0008](0008-identidad-navy-coral.md) (2026-08-27)
+**Fecha:** 2026-08-27
+
+> **Superseded (2026-08-27):** la Opción 2 "Atelier cálido" (ciruela/
+> carbón/cobre + Domine) descrita en este ADR se descartó — no
+> convenció combinada con el resto del sitio sin cambiar (header,
+> footer, home y producto seguían con la paleta anterior, ver §7). El
+> ADR 0008 documenta la dirección final ("Navy & Coral") y su
+> cronología completa. Este documento se conserva como registro
+> histórico, sin editar el resto de su contenido.
+
+> **Corrección de dirección #1 (2026-08-27):** la primera versión de
+> este ADR proponía clonar la estética visual de Amazon. Se corrigió a
+> adoptar *principios* de UX, no la estética de un competidor —
+> resultó en una paleta "cálida, confiable, ligeramente lúdica"
+> (terracota/espresso/pino/crema, Fraunces).
+
+> **Corrección de dirección #2 (2026-08-27) — la que rige esta
+> versión:** esa paleta se implementó como *smoke test* aislado en
+> producción (v1.0.176: solo el botón CTA de `ProductCard` en
+> terracota + el precio en Fraunces) y se revirtió por dos motivos
+> reales, no de gusto superficial:
+>
+> 1. **Error de proceso**: un token aislado rodeado del resto del
+>    esquema viejo (badges en fucsia/amarillo neón, fondo blanco) no
+>    es evaluable — el choque visual que se vio no era "la dirección
+>    de marca", era la mezcla incompleta. Ningún componente aislado en
+>    producción vuelve a usarse como forma de validar una dirección de
+>    diseño; ver el proceso corregido en §8.
+> 2. **Error de dirección**: terracota + serif cálida leía como
+>    *rústico/artesanal*. Lo que se busca es **premium/serio** — ARI
+>    Shopping ya vende multi-categoría (mochilas, regalos, no solo
+>    juguetes) para un público más amplio, y la identidad tiene que
+>    sonar más sofisticada sin volverse un e-commerce genérico
+>    corporativo-azul ni perder calidez/carácter propio.
+>
+> §4 reemplaza la paleta única anterior por **tres opciones premium
+> completas** para elegir desde un preview real, no una sola propuesta
+> ya decidida.
+
+> Alcance (sin cambios): **solo visual** (paleta, tipografía, radios,
+> densidad) — ARI Shopping sigue siendo la marca, el catálogo sigue
+> siendo el mismo. No se toca taxonomía, backend, ni la estructura de
+> navegación ya construida en el ADR 0005 — se re-expresa visualmente
+> sobre esa misma estructura.
+
+## 1. Resumen de la auditoría del estado actual
+
+(Sin cambios — sigue siendo la descripción real del código, no de la
+propuesta.)
+
+El storefront hoy tiene una identidad visual deliberadamente lúdica,
+tipo "juguetería": paleta arcoíris de alta saturación
+(`--color-ari-cyan/magenta/yellow`, gradientes `cyan→violet→fuchsia`),
+`rounded-full` en casi todo, `font-black`/`font-extrabold` como
+default en título, precio, botones y texto secundario por igual. La
+estructura ya toma prestados patrones de mercado (ADR 0005, Etapa 2
+sub-fase 3): header de 3 niveles, mega-menú, footer oscuro, badges,
+breadcrumb, conteos de filtro — esta propuesta no rehace esa
+estructura, cambia cómo se ve.
+
+## 2. Principios de UX a adoptar (funcionales, no estéticos)
+
+(Sin cambios respecto a la revisión anterior.)
+
+| Principio | Por qué funciona | Cómo se aplica sin copiar estética |
+|---|---|---|
+| Jerarquía visual clara precio/CTA/info secundaria | Si todo pesa igual, el ojo no sabe dónde mirar primero | Precio y CTA son los únicos elementos con peso reservado; categoría/SKU bajan a texto liviano |
+| Alta densidad sin saturación | Más información real visible compite mejor que decoración vacía | Los gradientes decorativos se liberan para mostrar señales reales del producto |
+| Señales de confianza visibles | Urgencia de inventario, garantías, envíos leídos como información seria | Se conservan/refuerzan elementos reales ya existentes ("Quedan N", `TrustBar`) en colores serios |
+| Contraste suficiente para escaneo rápido | Un usuario escanea, no lee | Cada par de color se valida contra WCAG AA con números reales, no se asume |
+
+## 3. Por qué no clonar la estética de un competidor
+
+(Sin cambios — sigue vigente independientemente de qué opción de §4
+se elija.)
+
+## 4. Tres opciones premium completas
+
+Las tres evitan por igual: azul corporativo genérico, la paleta
+arcoíris actual, y el terracota/serif "rústico" ya descartado. Las
+tres se apoyan en los mismos principios de §2. Difieren en cuánta
+calidez vs. formalidad tienen, y en el carácter tipográfico exacto.
+Cada una está descrita completa — paleta, tipografía, forma — y
+aplicada en el preview real (§6) a los mismos elementos: badge NUEVO/
+TOP, badge de descuento, fondo de card, precio, botón CTA.
+
+### Opción 1 — "Boutique de regalos"
+
+La más formal de las tres. Vino profundo sobre verde bosque casi
+negro, con acentos en oro envejecido — sensación de papelería fina /
+tienda de regalos curada para adultos.
+
+| Rol | Token | Valor |
+|---|---|---|
+| CTA / acción única | `--color-ari-vino` | `#8C2F4B` |
+| Ancla oscura (header/footer) | `--color-ari-bosque` | `#1B2A22` |
+| Acento (destacado/confianza) | `--color-ari-oro-viejo` | `#C9A227` |
+| Fondo general | `--color-ari-marfil` | `#FAF6EF` |
+| Texto principal | `--color-ari-carbon` | `#241C1A` |
+| Badge descuento | `--color-ari-vino-oscuro` | `#6E2338` |
+
+- **Tipografía**: [Playfair Display](https://fonts.google.com/specimen/Playfair+Display)
+  para titulares/precio (serif editorial, dramática, con contraste
+  alto entre trazos gruesos/finos — la más "premium boutique" de las
+  tres) + Inter para cuerpo/UI.
+- **Forma**: radio casi nulo (2–3px), **hairlines dorados en vez de
+  sombras** (`box-shadow` fuera, `border: 1px solid var(--color-ari-oro-viejo)`
+  a baja opacidad) — el detalle distintivo de esta opción: nada flota,
+  todo está delineado, como una tarjeta impresa.
+- **Contraste validado**: blanco/bosque 15.8:1, blanco/vino 6.1:1,
+  carbón/marfil 13.1:1 — todos superan AA con margen amplio.
+
+### Opción 2 — "Atelier cálido"
+
+Punto medio: sigue siendo premium pero con más calidez que la Opción 1
+— ciruela en vez de vino (menos "formal/rojo", más "artesanía fina"),
+cobre en vez de oro.
+
+| Rol | Token | Valor |
+|---|---|---|
+| CTA / acción única | `--color-ari-ciruela` | `#5B3256` |
+| Ancla oscura | `--color-ari-carbon-oscuro` | `#221D1A` |
+| Acento | `--color-ari-cobre` | `#B5723A` |
+| Fondo general | `--color-ari-hueso` | `#F7F1E6` |
+| Texto principal | `--color-ari-carbon` | `#2A2420` |
+| Badge descuento | `--color-ari-terracota-oscuro` | `#9C4A2E` |
+
+- **Tipografía**: [Domine](https://fonts.google.com/specimen/Domine)
+  para titulares/precio (serif con más peso y autoridad que Fraunces,
+  menos "suave/artesanal", sin el dramatismo editorial de Playfair —
+  el punto medio deliberado entre las otras dos opciones) + Inter.
+- **Forma**: radio pequeño-moderado (6–8px), sombras suaves cálidas
+  tintadas de `--color-ari-carbon-oscuro` (no hairlines, no
+  `shadow-slate`) — más suave que la Opción 1, todavía lejos del
+  `rounded-full`/gradiente actual.
+- **Contraste validado**: blanco/carbón-oscuro 15.1:1, blanco/ciruela
+  8.9:1, carbón/hueso 11.7:1 — todos superan AA con margen amplio.
+
+### Opción 3 — "Minimal cálido"
+
+La más restringida de las tres — casi monocromática, un solo acento
+de color por composición, mucho blanco. Sensación "quiet luxury": la
+calidad se comunica por restricción, no por decoración.
+
+| Rol | Token | Valor |
+|---|---|---|
+| CTA / acción única | `--color-ari-ambar` | `#B8842E` |
+| Ancla oscura | `--color-ari-negro-calido` | `#1C1917` |
+| Acento secundario | `--color-ari-oliva` | `#5C6650` |
+| Fondo general | `--color-ari-blanco-calido` | `#FAF8F5` |
+| Texto principal | `--color-ari-negro-calido` | `#1C1917` |
+| Badge descuento | `--color-ari-negro-calido` con texto ámbar | `#1C1917` / `#B8842E` |
+
+- **Tipografía**: [Newsreader](https://fonts.google.com/specimen/Newsreader)
+  itálica para precio/titulares (serif moderna diseñada para lectura,
+  calmada, "editorial silencioso" — la menos decorativa de las tres)
+  + Inter.
+- **Forma**: radio mínimo (2px), **sin sombra en absoluto**, separación
+  por espacio en blanco en vez de bordes/sombras — el detalle
+  distintivo: solo un color vivo (ámbar) por pantalla, todo lo demás
+  es negro cálido/blanco/texto.
+- **Contraste validado**: negro-cálido/blanco-cálido 17.9:1, blanco/
+  ámbar 3.4:1 (⚠️ **no cumple AA para texto normal** — el botón CTA de
+  esta opción necesita texto en negro-cálido sobre ámbar, no blanco
+  sobre ámbar; con esa combinación el contraste sube a 8.1:1, sí
+  cumple), oliva/blanco-cálido 4.9:1.
+
+## 5. Tabla comparativa rápida
+
+| | Opción 1 · Boutique | Opción 2 · Atelier | Opción 3 · Minimal |
+|---|---|---|---|
+| CTA | Vino `#8C2F4B` | Ciruela `#5B3256` | Ámbar `#B8842E` |
+| Ancla oscura | Bosque `#1B2A22` | Carbón oscuro `#221D1A` | Negro cálido `#1C1917` |
+| Acento | Oro viejo `#C9A227` | Cobre `#B5723A` | Oliva `#5C6650` |
+| Fondo | Marfil `#FAF6EF` | Hueso `#F7F1E6` | Blanco cálido `#FAF8F5` |
+| Display | Playfair Display | Domine | Newsreader (itálica) |
+| Radio | 2–3px | 6–8px | 2px |
+| Elevación | Hairline dorado, sin sombra | Sombra suave tintada | Sin sombra, solo espacio |
+| Personalidad | Formal, editorial, "boutique" | Cálido, artesanal-fino, punto medio | Restringido, "quiet luxury" |
+
+## 6. Decisión final: Opción 2 — "Atelier cálido"
+
+El usuario delegó la elección final entre las 3 opciones de §4 en vez
+de revisarlas una por una. Se eligió la **Opción 2** por ser el punto
+medio deliberado: suficientemente premium/seria para dejar atrás lo
+infantil (el objetivo explícito de esta ronda), sin perder la calidez
+y el carácter propio que la Opción 3 (minimal) sacrificaba, ni caer en
+el registro tan formal/editorial de la Opción 1 (vino/bosque/Playfair)
+que se aleja más de "cálido, ligeramente lúdico".
+
+## 7. Decisión de proceso (corregida)
+
+Se descartó construir un `/design-preview` de comparación de las 3
+opciones — el usuario pidió explícitamente decidir directo y revisar
+el resultado ya aplicado, no volver a mediar cada paso. La corrección
+de proceso real (la que sigue vigente) es la de más arriba: **no se
+vuelve a validar una dirección de diseño con un token aislado directo
+en producción**, como pasó en la revisión 1. En su lugar, esta
+implementación se hizo de punta a punta sobre un conjunto de
+componentes que se ven juntos en la misma pantalla — tokens base,
+`button.tsx`, `badge.tsx`, `product-card.tsx` y los estados
+interactivos de `catalog-client.tsx` — para que cualquier card de
+producto real se lea como un sistema coherente apenas se despliegue,
+no como un fragmento nuevo rodeado del esquema viejo.
+
+Header, footer, home y página de producto/drawers (Sub-fases 2, 4 y 5
+del plan original) **quedan pendientes** de una siguiente pasada —
+mientras tanto se van a ver con la paleta anterior, a propósito, no
+por un olvido.
+
+## 8. Consecuencias
+
+- Producto de esta pasada: catálogo (`/catalog`) y sus cards quedan
+  con una identidad completa y coherente entre sí. Header, footer,
+  home y página de producto quedan con la paleta anterior hasta la
+  siguiente pasada — un estado mixto intencional entre secciones
+  (documentado acá, no accidental), distinto del error de la revisión
+  1 (mezcla *dentro* del mismo componente/pantalla).
+- El catálogo, backend, taxonomía y flujo de búsqueda/facetas (ADR
+  0006) quedan completamente intactos.
+- Trabajo puramente de frontend: no requiere cambios en
+  `commerce-backend`, `platform-infra`, ni CI nuevo.
+- Al redefinir directamente las variants existentes de `button.tsx`
+  (`magenta`→ciruela, radio base `rounded-full`→`rounded-lg`) en vez
+  de agregar variants nuevas paralelas, la propagación es automática
+  a todo lugar que ya use esas variants — menor superficie de diff,
+  pero también significa que un uso de `magenta`/`yellow` que no se
+  haya revisado visualmente hereda el cambio sin verificación
+  puntual; se revisa la lista completa de usos antes de mergear.

workloads/docs-portal/docs/decisiones/0008-identidad-navy-coral.md

@@ -0,0 +1,170 @@
+# ADR 0008 — Identidad visual "Navy & Coral" para ARI Shopping
+
+**Estado:** aceptada (implementación en curso, por sub-fases)
+**Fecha:** 2026-08-27
+**Reemplaza a:** [ADR 0007](0007-identidad-visual-propia.md) (Opción 2, "Atelier cálido")
+
+## 1. Contexto
+
+Este es el tercer intento de identidad visual propia para ARI Shopping,
+después de dos ciclos de implementar-y-descartar en producción (ver
+cronología en §2). El costo real de esos dos ciclos no fue el tiempo
+de escribir el código, fue el tiempo de verlo mal en producción antes
+de poder juzgarlo — y en ambos casos el veredicto real no era sobre la
+paleta en sí, sino sobre verla mezclada con partes del sitio que
+todavía no se habían tocado.
+
+## 2. Cronología completa
+
+1. **Arcoíris original** — la identidad "juguetería" con la que arrancó
+   el storefront: paleta de alta saturación (cian/violeta/fucsia/ámbar/
+   amarillo/lima), `rounded-full` en casi todo, `font-black` como
+   default. Nunca fue una decisión de marca, era el estado por defecto
+   del scaffold inicial.
+2. **Intento de clon de Amazon** (descartado antes de implementarse) —
+   la primera versión de ADR 0007 proponía clonar la estética visual de
+   un competidor directamente. Se corrigió a adoptar *principios* de UX
+   (jerarquía, densidad, señales de confianza), no la estética de nadie
+   — ver la memoria de este cambio de dirección.
+3. **Terracota/espresso/pino/crema + Fraunces** ("cálido, confiable,
+   ligeramente lúdico") — se implementó como *smoke test* aislado en
+   producción (v1.0.176: solo el botón CTA de `ProductCard` en
+   terracota + precio en Fraunces, todo lo demás sin tocar) y se
+   revirtió. Dos motivos reales: (a) un token aislado rodeado del resto
+   del esquema viejo (badges fucsia/amarillo neón) no es evaluable — el
+   choque visual no era "la dirección de marca", era la mezcla
+   incompleta; (b) terracota + serif cálida leía como *rústico/
+   artesanal*, y el objetivo era premium/serio.
+4. **Ciruela/carbón/cobre "Atelier cálido"** (ADR 0007, Opción 2 de 3) —
+   esta vez la implementación cubrió un conjunto completo de
+   componentes que se ven juntos en la misma pantalla (tokens base,
+   `button.tsx`, `badge.tsx`, `product-card.tsx`,
+   `catalog-client.tsx`), evitando el error de proceso del punto
+   anterior. Aun así, header, footer, home y página de producto/drawers
+   quedaron deliberadamente pendientes de una siguiente pasada (ADR
+   0007 §7). Resultado: se descartó — no convenció combinada con el
+   resto del sitio sin cambiar. El catálogo aislado se veía coherente,
+   pero el sitio completo (con el header/footer viejos alrededor)
+   seguía sin leerse como una marca terminada.
+5. **"Navy & Coral"** (esta dirección, final) — marino/coral/coral
+   claro + Poppins para momentos de marca. Ver especificación completa
+   en §4.
+
+## 3. Mejora de proceso: validar barato antes de implementar
+
+A diferencia de los dos intentos anteriores, esta dirección se validó
+visualmente con el usuario mediante mockups de referencia simulados
+**fuera de este entorno, antes de tocar código real**. Ningún ciclo de
+implementación se gastó en generar opciones que después se
+descartarían por gusto — el código de esta ADR se escribe ya sobre una
+dirección aprobada.
+
+Esto vale la pena dejarlo como práctica para el playbook de diseño de
+este proyecto: cuando el costo de deshacer una implementación en
+producción es alto (como pasó en los puntos 3 y 4 de §2), vale la pena
+invertir primero en una validación visual barata y rápida (mockup,
+preview, captura) antes de comprometer ciclos de implementación real,
+en vez de decidir la dirección *mientras* se implementa.
+
+## 4. Especificación de marca
+
+### Paleta
+
+| Rol | Token | Valor |
+|---|---|---|
+| Ancla (header, footer, badge "Nuevo", fondo de hero) | `--color-ari-marino` | `#122844` |
+| Acento único de acción (CTA "Agregar al carrito", precio destacado) | `--color-ari-coral` | `#D85A30` |
+| Acento secundario (subtítulos sobre marino, ala inferior del isotipo) | `--color-ari-coral-claro` | `#F0997B` |
+| Fondo general | — | `#FFFFFF` (blanco puro; reemplaza `--color-ari-hueso`) |
+| Texto secundario / bordes | escala `slate-*` ya usada en el proyecto | sin token nuevo |
+
+### Tipografía
+
+- **Poppins, peso 700** — solo para los "momentos de marca": wordmark
+  del logo, títulos de sección (`h1`/`h2`), precio de producto, texto
+  de CTA. Es el único peso que se carga.
+- **Inter** (ya integrada) se mantiene para body/UI/navegación — no
+  todo el sitio pasa a Poppins.
+- Domine (Opción 2 de ADR 0007) se elimina por completo, incluida su
+  carga vía `next/font`.
+
+### Isotipo
+
+Mariposa geométrica simplificada, construida con 4 elipses (no el
+filigrana intrincado del logo original, que se perdía en tamaños
+chicos):
+
+| Elemento | Parámetros | Color |
+|---|---|---|
+| Ala superior izquierda | elipse `rx=9 ry=7`, `cx=10 cy=8`, rotada -18° | `#D85A30` |
+| Ala superior derecha | elipse `rx=9 ry=7`, `cx=24 cy=8`, rotada 18° | `#D85A30` |
+| Ala inferior izquierda | elipse `rx=6 ry=5`, `cx=12 cy=16`, rotada -10° | `#F0997B` |
+| Ala inferior derecha | elipse `rx=6 ry=5`, `cx=22 cy=16`, rotada 10° | `#F0997B` |
+| Cuerpo | rectángulo `x=16 y=3 width=2 height=18`, redondeado | `#122844` |
+
+Coordenadas base sobre `viewBox 34x24`, sobre fondo circular marino.
+Wordmark "ARI" (Poppins 700, blanco) + "shopping" debajo (Poppins 700,
+`#F0997B`, más chico, letter-spacing amplio).
+
+Assets: `public/images/brand/logo-ari.svg` (lockup completo,
+reemplaza `logo-ari.png`) y `app/icon.svg` (versión reducida — solo
+círculo + mariposa, sin wordmark — favicon/app icon vía la convención
+de Next.js App Router).
+
+## 5. Hallazgo: causa raíz del estado mixto anterior
+
+Al auditar `navbar.tsx` para esta implementación se encontró que,
+desde el arranque de este proyecto de reskin, nunca se había tocado:
+una barra superior con gradiente `from-amber-300 via-yellow-200
+to-lime-200` y una línea decorativa `from-cyan-400 via-violet-500
+to-fuchsia-500`, ambas del esquema arcoíris original (punto 1 de §2).
+Esto confirma que el "estado mixto" visto en producción durante ADR
+0007 no era solo "header pendiente de una pasada futura" en abstracto
+— eran restos concretos y nunca inventariados del esquema anterior,
+conviviendo con cada iteración de paleta desde entonces sin que nadie
+los marcara como deuda. Se eliminan en la sub-fase 2 de esta
+implementación.
+
+## 6. Plan de implementación
+
+Por sub-fases, cada una con rama `fix/*`, diff mostrado y PR sin
+mergear hasta confirmación explícita del usuario. Cada sub-fase debe
+dejar el sitio en un estado internamente coherente (no fragmentos
+aislados en producción — la lección de los puntos 3 y 4 de §2) y debe
+confirmar con evidencia real (no supuesta) que el flujo de
+auto-refresh desde Medusa Admin (precio/descripción/imagen) sigue
+funcionando.
+
+1. Tokens base + logo (`globals.css`, `logo-ari.svg`, favicon).
+2. Header + footer (`navbar.tsx` — incluida la limpieza de §5 —,
+   `footer.tsx`, logo aplicado).
+3. Product card + grid de catálogo + badges.
+4. Home (hero, tiles de categoría, secciones).
+5. Página de producto + drawers de carrito/wishlist.
+
+### Nota de implementación: alias de compatibilidad de tokens
+
+La sub-fase 1 solo toca `globals.css`/`layout.tsx`/assets — no
+`catalog-client.tsx`, `product-card.tsx` ni `button.tsx`, que hoy
+siguen usando los nombres de token de ADR 0007
+(`ari-ciruela`, `ari-carbon-oscuro`, `ari-cobre`, `ari-carbon`,
+`ari-terracota-oscuro`, `ari-hueso`). Para no dejar esos usos sin
+estilo entre sub-fases, `globals.css` define esos nombres como alias
+temporales resueltos ya contra la paleta nueva. Cada sub-fase que
+toque esos archivos reemplaza el nombre de clase por el token
+definitivo; los alias se eliminan por completo al cerrar la sub-fase
+5.
+
+## 7. Consecuencias
+
+- El sitio completo adopta la paleta nueva en un solo despliegue desde
+  la sub-fase 1 (vía los alias de §6), incluso antes de que cada
+  componente migre al nombre de token definitivo — evita repetir el
+  error de "token aislado rodeado del esquema viejo" de los puntos 3 y
+  4 de §2.
+- Domine y su carga de fuente se eliminan; Poppins se agrega mínimo
+  (solo peso 700).
+- Trabajo puramente de frontend: no requiere cambios en
+  `commerce-backend`, `platform-infra`, ni CI nuevo.
+- `docs-portal` se actualiza con capturas/descripción del resultado
+  final una vez cada sub-fase esté validada en producción, no antes.

workloads/docs-portal/docs/decisiones/0009-checkout-real.md

@@ -0,0 +1,227 @@
+# ADR 0009 — Checkout real (pago en línea + envíos) para ARI Shopping
+
+**Estado:** aceptada — proveedor de pago decidido (PayU, §3);
+implementación real (credenciales, shipping options, código) pendiente
+**Fecha:** 2026-08-28
+
+## Contexto
+
+El carrito hoy no completa una transacción real: arma el pedido en el
+cliente y lo cierra con un botón "Continuar por WhatsApp"
+(`components/layout/navbar.tsx`, `mobile-add-to-cart.tsx`) — un
+placeholder intencional, no un bug. El diálogo de cuenta ya lo admite
+explícitamente ("El inicio de sesión quedará conectado al backend
+headless. Mientras tanto..."). Ni checkout ni auth de clientes tienen
+ADR previo ni intento de implementación en el historial de git de
+ningún repo del lab — este es terreno nuevo.
+
+Investigación previa a este ADR (2026-08-28, confirmado contra código
+real y documentación oficial vigente, no memoria de entrenamiento —
+misma disciplina que ADR 0006):
+
+- **Pagos:** `commerce-backend/medusa-config.ts` no registra ningún
+  provider de pago — el único módulo configurado hoy es
+  `@medusajs/medusa/file` (storage S3).
+- **Envíos:** existe una sola región ("Colombia", COP), creada a mano
+  vía Admin API durante el incidente de precios de agosto
+  (`incidente-medusa-precios-region-id-2026-08.md`), no vía ningún
+  script de seed — no existe ningún script de seed en el repo. **No
+  hay ninguna shipping option configurada en ningún lado.** Sin esto
+  el checkout no puede completarse aunque el pago ya funcione — es un
+  prerequisito invisible, independiente del proveedor de pago elegido.
+- **Auth:** cero código de cliente/login en todo el storefront (grep
+  sobre `lib/`, `app/`, `components/` sin resultados para
+  `customer`/`login`/`useAuth`/`/store/customers`). El módulo de
+  auth/customer de Medusa viene incluido en el core — falta
+  enteramente el lado del storefront, no el backend. **Medusa soporta
+  checkout como invitado**, así que auth no bloquea checkout y puede
+  secuenciarse por separado — fuera de alcance de este ADR.
+
+## 1. Flujo de checkout real en Medusa v2 (Store API)
+
+Confirmado contra `docs.medusajs.com` (2026-08-28): el flujo son 7
+pasos encadenados — crear carrito → agregar items → dirección de envío
+→ **seleccionar método de envío** (`POST` a la ruta de shipping method
+del carrito, requiere que ya exista al menos una shipping option) →
+payment collection → payment session → completar orden. Ningún paso
+es opcional; el paso de método de envío es exactamente el que hoy no
+tiene ninguna shipping option que ofrecer.
+
+## 2. Estado real de soporte de pago en Medusa 2.18.0
+
+- **Stripe es de primera clase** (`@medusajs/medusa/payment-stripe`,
+  incluido en el core, no un plugin de terceros — a diferencia de la
+  situación de Meilisearch en ADR 0006). Configuración mínima
+  verificada:
+
+  ```ts
+  {
+    resolve: "@medusajs/medusa/payment",
+    options: {
+      providers: [{
+        resolve: "@medusajs/medusa/payment-stripe",
+        id: "stripe",
+        options: { apiKey: process.env.STRIPE_API_KEY },
+      }],
+    },
+  }
+  ```
+
+  Env vars: `STRIPE_API_KEY` (siempre) y `STRIPE_WEBHOOK_SECRET`
+  (obligatorio en producción). Tras configurar, hay que habilitar el
+  provider **en la región** desde el Admin — un paso manual aparte,
+  igual que ya pasó con la región misma.
+
+- **Bloqueador real de negocio, no técnico: Stripe no acepta cuentas
+  de comercio registradas en Colombia.** Confirmado contra
+  `stripe.com/global` (2026-08-28) — Brasil y México sí están en la
+  lista de países soportados para abrir cuenta, Colombia no aparece.
+  La única vía sería registrar una entidad de negocio en un país
+  soportado, fuera de alcance realista para este lab. Esto invalida a
+  Stripe como opción pese a ser la integración técnicamente más
+  simple y mejor documentada.
+- **Alternativas con presencia real en Colombia y algún plugin de
+  Medusa existente:**
+  - **PayU** (`@tax1driver/medusa-payu`): el propio repo declara
+    compatibilidad explícita con Medusa `v2.4.0+` — cubre nuestra
+    versión (2.18.0). Webhook auto-registrado en `/hooks/payment/payu`.
+  - **Wompi** (`medusa-payment-wompi-col`, respaldado por Bancolombia,
+    liquidación directa en COP): revisé el repo directamente
+    (2026-08-28) y **no documenta contra qué versión de Medusa se
+    probó, ni tiene releases/actividad reciente visible** — mayor
+    riesgo de compatibilidad no verificada que PayU, aunque el
+    encaje de negocio (banco local, moneda nativa) sea el más
+    directo. Antes de elegirlo habría que repetir el nivel de
+    verificación que ADR 0006 le hizo al plugin de Meilisearch: leer
+    el código fuente real, no confiar en el README.
+- **Riesgo de red ya conocido, no nuevo:** cualquier webhook de pago
+  entra por la misma cadena Cloudflare → NPM → Traefik que ya causó
+  un incidente real con otro servicio
+  (`incidente-cloudflared-504-quic-2026-08.md`). Validar la entrega de
+  webhooks en vivo antes de confiar en el flujo, no asumir que
+  "funciona igual que todo lo demás".
+
+## 3. Decisión de proveedor — PayU
+
+Dato de negocio real que decidió esto (aportado por el usuario,
+2026-08-28): las cuentas bancarias disponibles son Davivienda, Lulo
+Bank y Banco de Bogotá — **ninguna es Bancolombia ni Nequi**.
+
+Verificado contra fuentes reales el mismo día (no memoria):
+
+- **Wompi exige cuenta Bancolombia o, como mínimo, cuenta Nequi para
+  poder registrarse como comercio** (modelo Agregador) — confirmado
+  contra el reglamento de comercios de Wompi y su centro de soporte.
+  La liquidación de ventas sí puede ir después a cualquier banco
+  colombiano, pero la puerta de entrada al registro sigue siendo
+  Bancolombia/Nequi. Con los bancos disponibles hoy, esto exigiría
+  abrir una cuenta Nequi nueva solo para poder registrarse — paso
+  extra evitable.
+- **PayU solo exige "cuenta bancaria colombiana a nombre del
+  comercio"**, sin banco específico — Davivienda, Lulo Bank o Banco de
+  Bogotá califican igual, sin pasos previos. Además ya soporta **PSE**
+  (transferencia desde cualquier banco colombiano del cliente, sin
+  relación con el banco del comercio), **Nequi** y **Daviplata** como
+  métodos de pago para los clientes vía redirección — cubre exactamente
+  los métodos que se pidieron (PSE + Nequi "y demás bancos") sin que
+  la cuenta bancaria propia del comercio sea Bancolombia.
+
+**Decisión:** PayU como proveedor de pago (negocio) se mantiene. La vía
+técnica cambió el 2026-08-29 — ver nota de implementación al final de
+este documento: ningún plugin comunitario de Medusa sirve para PayU
+LatAm, hace falta un módulo de pago custom. Wompi queda descartado por
+el requisito de registro Bancolombia/Nequi, no por limitación técnica.
+
+**Pendiente antes de implementar (no resoluble en este ADR):**
+
+- Registro real de comercio en PayU (persona natural o jurídica —
+  jurídica pide NIT, representante legal y estados financieros
+  básicos) y credenciales reales (`apiLogin`, `apiKey`, `merchantId`,
+  `accountId` — terminología real de la API de PayU LatAm, ver nota de
+  implementación) — nunca generadas ni asumidas por mí.
+- Escribir el módulo de pago custom para PayU LatAm (no instalar un
+  plugin — no existe ninguno real para esta API, ver nota de
+  implementación).
+
+## Opciones consideradas
+
+| Opción | A favor | En contra |
+|---|---|---|
+| **Stripe** | Integración core de Medusa, mejor documentada, configuración mínima | No acepta comercios registrados en Colombia — bloqueador de negocio, no técnico |
+| **PayU** — **elegido** (proveedor de negocio; integración técnica ahora es custom, ver nota de implementación) | Solo exige cuenta bancaria colombiana a nombre del comercio, sin banco específico (encaja con Davivienda/Lulo Bank/Banco de Bogotá); soporta PSE + Nequi + Daviplata para el cliente sin importar el banco del comercio | Ningún plugin de Medusa real sirve para su API LatAm (`apiLogin`/`apiKey`/`accountId`) — los dos paquetes que parecían encajar por nombre son en realidad para PayU Polonia/CEE (`clientId`/`posId`/`secondKey`), uno de ellos archivado; requiere módulo de pago custom |
+| **Wompi** (`medusa-payment-wompi-col`) | Liquidación directa en COP vía Bancolombia | Exige cuenta Bancolombia o, como mínimo, Nequi solo para **registrarse** como comercio — ninguno de los bancos disponibles (Davivienda/Lulo Bank/Banco de Bogotá) califica sin abrir una cuenta nueva; además, sin versión de Medusa documentada ni actividad reciente visible en el plugin |
+| **Seguir con WhatsApp** (no pago en línea) | Cero riesgo nuevo, cero dependencia externa | No resuelve el objetivo real (transacción completa sin intervención manual); no es checkout, es lo que ya existe hoy |
+
+## Consecuencias
+
+- Las shipping options son un prerequisito independiente del proveedor
+  y deben configurarse primero — sin ellas ningún flujo de checkout
+  completa, sea cual sea el pago.
+- El pago de PayU se implementa como módulo custom (`AbstractPaymentProvider`
+  de Medusa) contra la API real de PayU LatAm, no como instalación de
+  un plugin de terceros — más superficie propia para mantener, mismo
+  patrón de esfuerzo que ya se identificó para EnvíoClick en §2.
+- Los webhooks de pago (a definir en el módulo custom, apuntando a la
+  URL de notificación real de PayU LatAm) deben validarse en vivo
+  contra la cadena de red real del lab antes de confiar en el flujo,
+  dado el precedente de `incidente-cloudflared-504-quic-2026-08.md`.
+- Se acepta como deuda: si en el futuro se abre una cuenta Bancolombia
+  o Nequi, Wompi (liquidación más directa en COP) vuelve a ser una
+  opción válida a reevaluar — no se descarta por limitación técnica,
+  solo por el requisito de registro actual.
+- Revertir esta decisión implica deshabilitar el provider en la región
+  y volver al botón de WhatsApp — el carrito y el catálogo no cambian
+  de forma, solo el paso final.
+
+## Nota de implementación (2026-08-29): shipping options creadas
+
+Bloqueador de §1 resuelto en producción, verificado extremo a extremo
+contra el Store API real (no solo creado en Admin):
+
+- Stock location "Bodega principal ARI Shopping" (`sloc_01M15G3D1336V8WQW3VZQRP6AN`).
+- Fulfillment set + zona de servicio "Colombia" (`geo_zone` tipo país, `co`).
+- Provider `manual_manual` habilitado en la ubicación.
+- Shipping option "Envío nacional estándar", tarifa fija $15.000 COP
+  (placeholder de negocio dentro del rango real de mercado
+  $12.000–$18.000 que dio el usuario, no un cálculo por peso/volumen —
+  eso es justamente lo que EnvíoClick resolvería más adelante),
+  vinculada al Default Shipping Profile y a la región Colombia/COP.
+- **Paso no documentado en ningún lado y que rompía todo en silencio:**
+  la stock location tiene que estar vinculada al Sales Channel
+  (`/admin/stock-locations/{id}/sales-channels`) para que el Store API
+  devuelva la shipping option — sin esto, `GET /store/shipping-options`
+  devolvía `[]` vacío pese a que el fulfillment set, la zona de
+  servicio y el provider ya estaban bien configurados. Confirmado con
+  un carrito de prueba real (dirección `co` + `cart_id`) antes y
+  después del vínculo.
+
+## Nota de implementación 2 (2026-08-29): corrección — no existe plugin real para PayU LatAm
+
+Antes de instalar nada se verificó el código/README real de los dos
+únicos paquetes de Medusa que aparecen buscando "PayU" — misma
+disciplina que ya aplicó ADR 0006 al plugin de Meilisearch, esta vez
+con un resultado distinto: **ninguno de los dos sirve.**
+
+- `@tax1driver/medusa-payu`: opciones de configuración `clientId`,
+  `clientSecret`, `merchantPosId`, `secondKey` — terminología exacta
+  de la API de **PayU Polonia/CEE** (OAuth + `posId`), no de PayU
+  LatAm.
+- `medusa-plugin-payu` (`rigby-sh/medusa-plugin-payu`): mismo problema
+  (`clientId`, `posId`, sandbox en `secure.snd.payu.com`, dominio de
+  PayU Europa) y además **archivado desde 2025-03-21** — sin
+  mantenimiento.
+- La API real que se necesita, PayU LatAm
+  (`developers.payulatam.com`, la que cubre Colombia junto con
+  Argentina/Brasil/Chile/México/Panamá/Perú), autentica con
+  `apiLogin`/`apiKey` en el objeto merchant y `accountId` en el
+  objeto order — un modelo de autenticación distinto, no solo nombres
+  de campo distintos.
+
+"PayU" es una marca compartida por dos productos/API históricamente
+separados (LatAm vs. Europa/CEE); un paquete que dice "PayU" a secas
+sin especificar LatAm es, con alta probabilidad, para el producto
+europeo. **Consecuencia:** la integración de pago se implementa como
+módulo custom de Medusa (`AbstractPaymentProvider`) contra
+`developers.payulatam.com` directamente — mismo tipo de esfuerzo que
+ya se había anticipado para EnvíoClick en §2, no una instalación de
+plugin como asumía la decisión original de este ADR.

workloads/docs-portal/mkdocs.yml

@@ -84,6 +84,8 @@ nav:
       - Visión general: arquitectura/vision-general.md
       - Red y exposición: arquitectura/red-y-exposicion.md
       - Flujo GitOps: arquitectura/gitops-flujo.md
+      - Agente de monitoreo: arquitectura/agente-monitoreo.md
+      - Sesión tmux persistente: arquitectura/sesion-tmux-persistente.md
       - Glosario: arquitectura/glosario.md
   - Decisiones (ADRs):
       - "0001 · Por qué k3d": decisiones/0001-por-que-k3d.md
@@ -91,6 +93,10 @@ nav:
       - "0003 · HTTP/2 sobre QUIC": decisiones/0003-por-que-http2-sobre-quic-tunnel.md
       - "0004 · Stack multi-categoría": decisiones/0004-evaluacion-stack-multi-categoria.md
       - "0005 · Rediseño storefront": decisiones/0005-rediseno-storefront.md
+      - "0006 · Motor de búsqueda y facetas": decisiones/0006-motor-busqueda-facetas.md
+      - "0007 · Identidad visual propia": decisiones/0007-identidad-visual-propia.md
+      - "0008 · Identidad Navy & Coral": decisiones/0008-identidad-navy-coral.md
+      - "0009 · Checkout real": decisiones/0009-checkout-real.md
       - Plantilla ADR: decisiones/plantilla-adr.md
   - Playbooks:
       - Crashloop Medusa: playbooks/incidente-crashloop-medusa.md

workloads/docs-portal/patches/deployment.yaml

@@ -25,7 +25,7 @@ spec:
         runAsNonRoot: false
       containers:
         - name: app
-          image: gitea.cruzcloud.net/devops/docs-portal:v1.0.125
+          image: gitea.cruzcloud.net/devops/docs-portal:v1.0.207
           # El base saca TODAS las capabilities. Probado en vivo y
           # revertido: con drop: ALL (aunque se agregue NET_BIND_SERVICE
           # de vuelta) el propio entrypoint de nginx:1.27-alpine falla al

workloads/ecommerce/app/api/cart/address/route.ts

@@ -0,0 +1,14 @@
+import { setShippingAddress } from "@/lib/headless/providers/medusa-cart";
+
+export async function POST(request: Request) {
+  const { cartId, ...address } = await request.json();
+  if (!cartId || !address.firstName || !address.address1 || !address.city || !address.phone || !address.email) {
+    return Response.json({ error: "Faltan campos obligatorios de la dirección" }, { status: 400 });
+  }
+  try {
+    const cart = await setShippingAddress(cartId, address);
+    return Response.json(cart);
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 502 });
+  }
+}

workloads/ecommerce/app/api/cart/items/[lineItemId]/route.ts

@@ -0,0 +1,31 @@
+import { removeLineItem, updateLineItemQuantity } from "@/lib/headless/providers/medusa-cart";
+
+interface RouteParams { params: Promise<{ lineItemId: string }> }
+
+export async function POST(request: Request, { params }: RouteParams) {
+  const { lineItemId } = await params;
+  const { cartId, quantity } = await request.json();
+  if (!cartId || typeof quantity !== "number") {
+    return Response.json({ error: "cartId y quantity son obligatorios" }, { status: 400 });
+  }
+  try {
+    const cart = await updateLineItemQuantity(cartId, lineItemId, quantity);
+    return Response.json(cart);
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 502 });
+  }
+}
+
+export async function DELETE(request: Request, { params }: RouteParams) {
+  const { lineItemId } = await params;
+  const cartId = new URL(request.url).searchParams.get("cartId");
+  if (!cartId) {
+    return Response.json({ error: "cartId es obligatorio" }, { status: 400 });
+  }
+  try {
+    const cart = await removeLineItem(cartId, lineItemId);
+    return Response.json(cart);
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 502 });
+  }
+}

workloads/ecommerce/app/api/cart/items/route.ts

@@ -0,0 +1,14 @@
+import { addLineItem } from "@/lib/headless/providers/medusa-cart";
+
+export async function POST(request: Request) {
+  const { cartId, variantId, quantity } = await request.json();
+  if (!cartId || !variantId) {
+    return Response.json({ error: "cartId y variantId son obligatorios" }, { status: 400 });
+  }
+  try {
+    const cart = await addLineItem(cartId, variantId, quantity ?? 1);
+    return Response.json(cart);
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 502 });
+  }
+}

workloads/ecommerce/app/api/cart/route.ts

@@ -0,0 +1,28 @@
+import { createCart, getCart } from "@/lib/headless/providers/medusa-cart";
+
+// cart-store.ts es "use client" y no puede pegarle directo a Medusa
+// (MEDUSA_BACKEND_URL es DNS interno del cluster, no resuelve desde el
+// navegador) -- mismo motivo que /api/search. Nunca cachear: es
+// estado mutable por sesion, no catalogo.
+
+export async function POST() {
+  try {
+    const cart = await createCart();
+    return Response.json(cart);
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 502 });
+  }
+}
+
+export async function GET(request: Request) {
+  const cartId = new URL(request.url).searchParams.get("cartId");
+  if (!cartId) {
+    return Response.json({ error: "cartId es obligatorio" }, { status: 400 });
+  }
+  try {
+    const cart = await getCart(cartId);
+    return Response.json(cart);
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 502 });
+  }
+}

workloads/ecommerce/app/api/cart/shipping-method/route.ts

@@ -0,0 +1,14 @@
+import { addShippingMethod } from "@/lib/headless/providers/medusa-cart";
+
+export async function POST(request: Request) {
+  const { cartId, optionId } = await request.json();
+  if (!cartId || !optionId) {
+    return Response.json({ error: "cartId y optionId son obligatorios" }, { status: 400 });
+  }
+  try {
+    const cart = await addShippingMethod(cartId, optionId);
+    return Response.json(cart);
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 502 });
+  }
+}

workloads/ecommerce/app/api/cart/shipping-options/route.ts

@@ -0,0 +1,14 @@
+import { getShippingOptions } from "@/lib/headless/providers/medusa-cart";
+
+export async function GET(request: Request) {
+  const cartId = new URL(request.url).searchParams.get("cartId");
+  if (!cartId) {
+    return Response.json({ error: "cartId es obligatorio" }, { status: 400 });
+  }
+  try {
+    const options = await getShippingOptions(cartId);
+    return Response.json({ options });
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 502 });
+  }
+}

workloads/ecommerce/app/api/search/route.ts

@@ -0,0 +1,45 @@
+import { searchWithFacets } from "@/lib/headless/client";
+import type { ProductFilters } from "@/lib/headless/types";
+
+// PredictiveSearch es un componente cliente y no puede pegarle directo
+// al provider server-side (MEDUSA_BACKEND_URL es un nombre DNS interno
+// del cluster, no resuelve desde el navegador) -- esta ruta es el
+// puente same-origin.
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url);
+
+  const filters: ProductFilters = {
+    query: searchParams.get("q") ?? undefined,
+    category: searchParams.get("category") ?? undefined,
+    collection: searchParams.get("collection") ?? undefined,
+    brand: searchParams.get("brand") ?? undefined,
+    ageRange: searchParams.get("ageRange") ?? undefined,
+  };
+
+  const minPrice = searchParams.get("minPrice");
+  if (minPrice) filters.minPrice = Number(minPrice);
+  const maxPrice = searchParams.get("maxPrice");
+  if (maxPrice) filters.maxPrice = Number(maxPrice);
+  const limit = searchParams.get("limit");
+  if (limit) filters.limit = Number(limit);
+
+  try {
+    const result = await searchWithFacets(filters);
+    // provider actual no implementa searchWithFacets (mock/shopify) --
+    // degradar a vacío, no a 500; el componente cliente cae de nuevo a
+    // su propio filtrado si esta ruta no trae nada útil.
+    return Response.json(
+      result ?? { products: [], facetDistribution: {}, count: 0 },
+    );
+  } catch (error) {
+    return Response.json(
+      {
+        products: [],
+        facetDistribution: {},
+        count: 0,
+        error: (error as Error).message,
+      },
+      { status: 502 },
+    );
+  }
+}

workloads/ecommerce/app/catalog/page.tsx

@@ -1,6 +1,6 @@
 import type { Metadata } from "next";
 import { CatalogClient } from "@/components/catalog/catalog-client";
-import { getProducts } from "@/lib/headless/client";
+import { getCategories, getProducts } from "@/lib/headless/client";
 
 export const metadata: Metadata = {
   title: "Catálogo",
@@ -17,17 +17,32 @@ function single(value: string | string[] | undefined): string {
 
 export default async function CatalogPage({ searchParams }: CatalogPageProps) {
   const params = await searchParams;
-  const products = await getProducts();
+  const [products, categories] = await Promise.all([getProducts(), getCategories()]);
 
   const category = single(params.category) || "Todos";
   const collection = single(params.collection);
   const query = single(params.q);
-  const section = single(params.section);
+
+  // Los links de navbar/tiles apuntan a categorias raiz (ej. "Mochilas y
+  // morrales"), pero ningun producto tiene esa categoria asignada
+  // directamente -- solo sus hijos ("Marvel", "Frozen", etc.). Este mapa
+  // expande cada raiz-con-hijos al nombre real de sus hijos para que el
+  // filtro siga funcionando por igualdad exacta de `product.category`.
+  const categoryGroups: Record<string, string[]> = {};
+  for (const node of categories) {
+    if (node.parentId) continue;
+    const children = categories.filter((child) => child.parentId === node.id);
+    if (children.length > 0) {
+      categoryGroups[node.name] = children.map((child) => child.name);
+    }
+  }
 
   return (
     <CatalogClient
-      key={`${category}:${collection}:${query}:${section}`}
+      key={`${category}:${collection}:${query}`}
       products={products}
+      categories={categories}
+      categoryGroups={categoryGroups}
       initialCategory={category}
       initialCollection={collection}
       initialQuery={query}

workloads/ecommerce/app/checkout/page.tsx

@@ -0,0 +1,5 @@
+import { CheckoutClient } from "@/components/checkout/checkout-client";
+
+export default function CheckoutPage() {
+  return <CheckoutClient />;
+}

workloads/ecommerce/app/globals.css

@@ -1,10 +1,27 @@
 @import "tailwindcss";
 
 @theme {
-  --color-ari-cyan: #06b6d4;
-  --color-ari-magenta: #ec4899;
-  --color-ari-yellow: #fde047;
-  --color-ari-blue: #0f172a;
+  /* ADR 0008 -- paleta final "Azul & Amarillo" (inspirada en Walmart),
+     iteracion sobre "Navy & Coral". Ver
+     docs-portal/docs/decisiones/0008-identidad-navy-coral.md */
+  --color-ari-marino: #0055B8;        /* ancla: header, footer, badge "Nuevo", fondo de hero */
+  --color-ari-coral: #0055B8;         /* boton de accion (CTA): azul solido, nunca amarillo */
+  --color-ari-coral-claro: #FFC220;   /* acento: badges de oferta/descuento/urgencia, detalles del isotipo -- nunca en botones */
+
+  /* Alias de compatibilidad -- ADR 0007 definio estos nombres y hoy los
+     siguen consumiendo catalog-client.tsx, product-card.tsx y button.tsx
+     (migracion pendiente en las sub-fases 3-5 del ADR 0008). Se resuelven
+     ya contra la paleta nueva para que ningun uso existente quede sin
+     estilo entre sub-fases; se eliminan por completo al cerrar la
+     sub-fase 5. No usar estos alias en código nuevo. */
+  --color-ari-ciruela: var(--color-ari-coral);
+  --color-ari-carbon-oscuro: var(--color-ari-marino);
+  --color-ari-cobre: var(--color-ari-coral-claro);
+  --color-ari-carbon: var(--color-ari-marino);
+  --color-ari-terracota-oscuro: var(--color-ari-coral);
+  --color-ari-hueso: #FFFFFF;
+
+  --font-display: var(--font-poppins), ui-sans-serif, system-ui, sans-serif;
   --animate-accordion-down: accordion-down .2s ease-out;
   --animate-accordion-up: accordion-up .2s ease-out;
 }
@@ -15,10 +32,10 @@
 :root { color-scheme: light; }
 * { border-color: rgb(226 232 240); }
 html { scroll-behavior: smooth; }
-body { margin: 0; background: #fff; color: #0f172a; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; text-rendering: optimizeLegibility; }
+body { margin: 0; background: #FFFFFF; color: var(--color-slate-900); font-family: var(--font-inter), ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; text-rendering: optimizeLegibility; }
 button, a { -webkit-tap-highlight-color: transparent; }
-button:focus-visible, a:focus-visible, input:focus-visible, select:focus-visible { outline: 3px solid rgb(167 139 250 / .55); outline-offset: 3px; }
-::selection { background: #fde047; color: #0f172a; }
+button:focus-visible, a:focus-visible, input:focus-visible, select:focus-visible { outline: 3px solid rgb(0 85 184 / .5); outline-offset: 3px; }
+::selection { background: rgb(0 85 184 / .15); color: var(--color-slate-900); }
 
 .content-auto {
   content-visibility: auto;

workloads/ecommerce/app/icon.svg

@@ -0,0 +1,15 @@
+<!-- ADR 0008, paleta final "Azul & Amarillo" (Walmart-inspirada). Version
+     reducida del isotipo para favicon/app icon: solo circulo azul +
+     mariposa, sin wordmark (no cabe legible a este tamano). Convencion de
+     Next.js App Router: este archivo se sirve automaticamente como
+     favicon/app icon. -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 34 34" role="img" aria-label="ARI shopping">
+  <circle cx="17" cy="17" r="17" fill="#0055B8"/>
+  <g transform="translate(0 5)">
+    <ellipse cx="10" cy="8" rx="9" ry="7" transform="rotate(-18 10 8)" fill="#FFC220"/>
+    <ellipse cx="24" cy="8" rx="9" ry="7" transform="rotate(18 24 8)" fill="#FFC220"/>
+    <ellipse cx="12" cy="16" rx="6" ry="5" transform="rotate(-10 12 16)" fill="#FFDD73"/>
+    <ellipse cx="22" cy="16" rx="6" ry="5" transform="rotate(10 22 16)" fill="#FFDD73"/>
+    <rect x="16" y="3" width="2" height="18" rx="1" fill="#0055B8"/>
+  </g>
+</svg>

workloads/ecommerce/app/layout.tsx

@@ -1,10 +1,18 @@
 import type { Metadata, Viewport } from "next";
+import { Inter, Poppins } from "next/font/google";
 import "./globals.css";
 import { CartDrawer } from "@/components/cart/cart-drawer";
 import { Footer } from "@/components/layout/footer";
 import { Navbar } from "@/components/layout/navbar";
 import { WishlistDrawer } from "@/components/wishlist/wishlist-drawer";
-import { getProducts } from "@/lib/headless/client";
+import { getCategories, getProducts } from "@/lib/headless/client";
+
+// El Navbar (categorias/colecciones/predictive search) vive en este layout
+// compartido -- si alguna pagina futura queda estatica, este fetch se
+// congelaria con datos de build time (mock) igual que le paso al home
+// (ver app/page.tsx). Forzarlo aca protege el nav en cualquier ruta, no
+// solo en las que hoy ya son dinamicas por otro motivo (searchParams, etc.).
+export const dynamic = "force-dynamic";
 
 export const metadata: Metadata = {
   metadataBase: new URL(process.env.NEXT_PUBLIC_SITE_URL ?? "https://shop.cruzcloud.net"),
@@ -13,9 +21,15 @@ export const metadata: Metadata = {
   openGraph: { title: "ARI Shopping", description: "Tesoros para cada aventura.", type: "website", locale: "es_CO" },
 };
 
-export const viewport: Viewport = { width: "device-width", initialScale: 1, themeColor: "#0f172a" };
+export const viewport: Viewport = { width: "device-width", initialScale: 1, themeColor: "#0055B8" };
+
+// ADR 0008 ("Navy & Coral"): Poppins peso 700 para los "momentos de marca"
+// (wordmark, h1/h2, precio, CTA) + Inter para body/UI -- solo se carga el
+// peso 700, es el unico que usa --font-display.
+const inter = Inter({ subsets: ["latin"], variable: "--font-inter", display: "swap" });
+const poppins = Poppins({ subsets: ["latin"], weight: ["700"], variable: "--font-poppins", display: "swap" });
 
 export default async function RootLayout({ children }: Readonly<{ children: React.ReactNode }>) {
-  const products = await getProducts();
-  return <html lang="es"><body><Navbar products={products} /><main>{children}</main><Footer /><CartDrawer /><WishlistDrawer /></body></html>;
+  const [products, categories] = await Promise.all([getProducts(), getCategories()]);
+  return <html lang="es" className={`${inter.variable} ${poppins.variable}`}><body><Navbar products={products} categories={categories} /><main>{children}</main><Footer /><CartDrawer /><WishlistDrawer /></body></html>;
 }

workloads/ecommerce/app/not-found.tsx

@@ -2,5 +2,5 @@ import Link from "next/link";
 import { Button } from "@/components/ui/button";
 
 export default function NotFound() {
-  return <section className="grid min-h-[60vh] place-items-center px-4 text-center"><div><span className="text-7xl font-black text-cyan-500">404</span><h1 className="mt-3 text-3xl font-black">Este tesoro no existe</h1><p className="mt-3 text-slate-500">Regresa al catálogo para continuar explorando.</p><Button asChild variant="magenta" className="mt-6"><Link href="/catalog">Ir al catálogo</Link></Button></div></section>;
+  return <section className="grid min-h-[60vh] place-items-center px-4 text-center"><div><span className="text-7xl font-black text-cyan-500">404</span><h1 className="mt-3 text-3xl font-black">Este tesoro no existe</h1><p className="mt-3 text-slate-500">Regresa al catálogo para continuar explorando.</p><Button asChild variant="primary" className="mt-6"><Link href="/catalog">Ir al catálogo</Link></Button></div></section>;
 }

workloads/ecommerce/app/page.tsx

@@ -1,14 +1,41 @@
+import Image from "next/image";
 import Link from "next/link";
 import { ArrowRight } from "lucide-react";
 import { CategoryTiles } from "@/components/home/category-tiles";
-import { HeroBento } from "@/components/home/hero-bento";
+import { HeroCarousel } from "@/components/home/hero-carousel";
 import { TrustBar } from "@/components/home/trust-bar";
 import { ProductCarousel } from "@/components/product/product-carousel";
 import { Button } from "@/components/ui/button";
-import { getProducts } from "@/lib/headless/client";
+import { getCategories, getProducts } from "@/lib/headless/client";
+
+// Sin esto, Next.js prerenderiza "/" en build time dentro del Dockerfile,
+// donde HEADLESS_PROVIDER/MEDUSA_* todavia no existen (solo se inyectan en
+// runtime via el Deployment) -- cae al provider mock y ese HTML queda
+// cacheado 1 año (visto en vivo: x-nextjs-prerender:1, s-maxage=31536000),
+// violando el flujo Admin -> revalidate del ADR 0005 justo en el home.
+export const dynamic = "force-dynamic";
 
 export default async function HomePage() {
-  const products = await getProducts();
+  const [products, categories] = await Promise.all([getProducts(), getCategories()]);
   const treasures = products.filter((product) => product.isNew || product.featured).slice(0, 8);
-  return <><HeroBento /><TrustBar /><div className="content-auto"><CategoryTiles /></div><section className="content-auto mx-auto max-w-7xl px-4 py-14"><div className="mb-8 flex items-end justify-between gap-5"><div><span className="text-xs font-black uppercase tracking-[.18em] text-fuchsia-600">Novedades</span><h2 className="mt-2 text-4xl font-black tracking-tight sm:text-5xl">Tesoros recién llegados</h2><p className="mt-3 text-slate-500">Desliza y encuentra nuevos favoritos.</p></div><Button asChild variant="outline" className="hidden sm:inline-flex"><Link href="/catalog">Ver catálogo <ArrowRight className="size-4" /></Link></Button></div><ProductCarousel products={treasures} /></section><section className="content-auto mx-auto max-w-7xl px-4 pb-20"><div className="grid overflow-hidden rounded-[2rem] bg-gradient-to-r from-cyan-500 via-blue-600 to-violet-600 text-white shadow-2xl lg:grid-cols-[1fr_.7fr]"><div className="p-8 sm:p-12"><span className="text-xs font-black uppercase tracking-[.18em] text-yellow-300">Club ARI</span><h2 className="mt-3 text-4xl font-black tracking-tight sm:text-6xl">Promociones, lanzamientos y mucha diversión.</h2><p className="mt-5 max-w-xl text-white/80">Únete a nuestra comunidad y recibe primero las novedades del catálogo.</p><Button variant="yellow" size="lg" className="mt-7">Quiero unirme</Button></div><div className="min-h-64 bg-[url('/images/promo/promo-backpacks.webp')] bg-cover bg-center" /></div></section></>;
+  return <><HeroCarousel /><TrustBar /><div className="content-auto"><CategoryTiles categories={categories} /></div><section className="content-auto mx-auto max-w-7xl px-4 py-14"><div className="mb-8 flex items-end justify-between gap-5"><div><span className="text-xs font-black uppercase tracking-[.18em] text-ari-coral">Novedades</span><h2 className="mt-2 text-4xl font-black tracking-tight sm:text-5xl">Tesoros recién llegados</h2><p className="mt-3 text-slate-500">Desliza y encuentra nuevos favoritos.</p></div><Button asChild variant="outline" className="hidden sm:inline-flex"><Link href="/catalog">Ver catálogo <ArrowRight className="size-4" /></Link></Button></div><ProductCarousel products={treasures} /></section><section className="content-auto mx-auto max-w-7xl px-4 pb-20"><div className="grid overflow-hidden rounded-[2rem] bg-ari-marino text-white shadow-2xl lg:grid-cols-[1fr_.7fr]"><div className="p-8 sm:p-12"><span className="text-xs font-black uppercase tracking-[.18em] text-ari-coral-claro">Club ARI</span><h2 className="mt-3 text-4xl font-black tracking-tight sm:text-6xl">Promociones, lanzamientos y mucha diversión.</h2><p className="mt-5 max-w-xl text-white/80">Únete a nuestra comunidad y recibe primero las novedades del catálogo.</p><Button variant="yellow" size="lg" className="mt-7">Quiero unirme</Button></div>{/* No hay herramienta de generacion de imagenes disponible para crear un
+    asset nuevo -- se reconstruye el mismo efecto (fondo punteado +
+    fotos estilo polaroid) con CSS y fotos reales de producto ya
+    existentes, en azul/amarillo de marca en vez del violeta original
+    de promo-backpacks.webp. */}
+<div className="relative min-h-64 overflow-hidden bg-ari-coral-claro">
+  <div className="absolute inset-0 [background-image:radial-gradient(rgba(0,85,184,0.35)_1.5px,transparent_1.5px)] [background-size:18px_18px]" />
+  <div className="absolute -bottom-12 -left-12 size-52 rounded-full bg-ari-marino" />
+  <div className="absolute inset-0 flex items-center justify-center gap-3 p-6">
+    <div className="relative size-28 -rotate-6 overflow-hidden rounded-xl border-4 border-white bg-white shadow-xl sm:size-32">
+      <Image src="/images/products/ari-011-mochila-escolar-de-spider-man-de-disney-.webp" alt="" fill sizes="128px" className="object-cover" />
+    </div>
+    <div className="relative size-28 rotate-3 overflow-hidden rounded-xl border-4 border-white bg-white shadow-xl sm:size-32">
+      <Image src="/images/products/ari-016-disney-mochila-iron-man-de-poliester-ult.webp" alt="" fill sizes="128px" className="object-cover" />
+    </div>
+    <div className="relative hidden size-28 -rotate-3 overflow-hidden rounded-xl border-4 border-white bg-white shadow-xl sm:block sm:size-32">
+      <Image src="/images/products/ari-009-mochilas-disney-coleccion-marvel.webp" alt="" fill sizes="128px" className="object-cover" />
+    </div>
+  </div>
+</div></div></section></>;
 }

workloads/ecommerce/app/product/[slug]/page.tsx

@@ -33,5 +33,5 @@ export default async function ProductPage({ params }: ProductPageProps) {
   if (!product) notFound();
   const products = await getProducts();
   const recommended = products.filter((candidate) => candidate.id !== product.id && (candidate.category === product.category || candidate.collection === product.collection)).slice(0, 8);
-  return <><section className="mx-auto grid max-w-7xl gap-10 px-4 py-10 lg:grid-cols-[1.08fr_.92fr] lg:py-16"><ProductGallery images={product.images} name={product.name} /><div><span className="text-xs font-black uppercase tracking-[.18em] text-fuchsia-600">{product.category} · {product.collection}</span><h1 className="mt-3 text-4xl font-black tracking-tight sm:text-6xl">{product.name}</h1><p className="mt-5 text-lg leading-8 text-slate-600">{product.description}</p><div className="mt-8"><ProductPurchase product={product} /></div><Accordion type="single" collapsible className="mt-8"><AccordionItem value="details"><AccordionTrigger>Detalles del producto</AccordionTrigger><AccordionContent>Marca: {product.brand}. Edad recomendada: {product.ageRange}. La disponibilidad y presentación final se confirman con Ari Shopping.</AccordionContent></AccordionItem><AccordionItem value="shipping"><AccordionTrigger>Envíos y entregas</AccordionTrigger><AccordionContent>Coordinamos envíos nacionales y entrega según ubicación. Los tiempos se confirman durante la cotización.</AccordionContent></AccordionItem></Accordion></div></section>{recommended.length > 0 && <section className="mx-auto max-w-7xl px-4 pb-24"><h2 className="mb-7 text-3xl font-black">También te puede gustar</h2><ProductCarousel products={recommended} /></section>}<MobileAddToCart product={product} /></>;
+  return <><section className="mx-auto grid max-w-7xl gap-10 px-4 py-10 lg:grid-cols-[1.08fr_.92fr] lg:py-16"><ProductGallery images={product.images} name={product.name} /><div><span className="text-xs font-black uppercase tracking-[.18em] text-ari-coral">{product.category} · {product.collection}</span><h1 className="mt-3 text-4xl font-black tracking-tight sm:text-6xl">{product.name}</h1><p className="mt-5 text-lg leading-8 text-slate-600">{product.description}</p><div className="mt-8"><ProductPurchase product={product} /></div><Accordion type="single" collapsible className="mt-8"><AccordionItem value="details"><AccordionTrigger>Detalles del producto</AccordionTrigger><AccordionContent>Marca: {product.brand}. Edad recomendada: {product.ageRange}. La disponibilidad y presentación final se confirman con Ari Shopping.</AccordionContent></AccordionItem><AccordionItem value="shipping"><AccordionTrigger>Envíos y entregas</AccordionTrigger><AccordionContent>Coordinamos envíos nacionales y entrega según ubicación. Los tiempos se confirman durante la cotización.</AccordionContent></AccordionItem></Accordion></div></section>{recommended.length > 0 && <section className="mx-auto max-w-7xl px-4 pb-24"><h2 className="mb-7 text-3xl font-black">También te puede gustar</h2><ProductCarousel products={recommended} /></section>}<MobileAddToCart product={product} /></>;
 }

workloads/ecommerce/commerce/configmap.yaml

@@ -19,3 +19,8 @@ data:
   S3_ENDPOINT: http://minio-svc:9000
   S3_REGION: us-east-1
   S3_BUCKET: ari-products
+
+  # Leido por el plugin @rokmohar/medusa-plugin-meilisearch (nombre de
+  # env var del plugin, no del servidor Meilisearch en si -- ver
+  # MEILI_MASTER_KEY en secrets.template.yaml).
+  MEILISEARCH_HOST: http://meilisearch-svc:7700

workloads/ecommerce/commerce/ingress-commerce.yaml

@@ -4,6 +4,7 @@ metadata:
   name: commerce-ingress
   annotations:
     traefik.ingress.kubernetes.io/router.entrypoints: web
+    traefik.ingress.kubernetes.io/router.middlewares: ecommerce-commerce-redirect-app@kubernetescrd
 spec:
   ingressClassName: traefik
   rules:

workloads/ecommerce/commerce/kustomization.yaml

@@ -7,5 +7,7 @@ resources:
   - redis.yaml
   - minio.yaml
   - minio-bootstrap-job.yaml
+  - meilisearch.yaml
   - medusa/
   - ingress-commerce.yaml
+  - middleware-commerce-redirect.yaml

workloads/ecommerce/commerce/medusa/patches/deployment.yaml

@@ -65,7 +65,7 @@ spec:
               memory: 64Mi
 
         - name: migrations
-          image: gitea.cruzcloud.net/devops/ecommerce-medusa:v1.0.121
+          image: gitea.cruzcloud.net/devops/ecommerce-medusa:v1.0.168
           imagePullPolicy: IfNotPresent
           command:
             - node
@@ -86,7 +86,7 @@ spec:
 
       containers:
         - name: app
-          image: gitea.cruzcloud.net/devops/ecommerce-medusa:v1.0.121
+          image: gitea.cruzcloud.net/devops/ecommerce-medusa:v1.0.168
           imagePullPolicy: IfNotPresent
           envFrom:
             - configMapRef:

workloads/ecommerce/commerce/meilisearch.yaml

@@ -0,0 +1,86 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: meilisearch-svc
+spec:
+  selector:
+    app: commerce-meilisearch
+  ports:
+    - name: http
+      port: 7700
+      targetPort: 7700
+---
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: commerce-meilisearch
+spec:
+  serviceName: meilisearch-svc
+  replicas: 1
+  selector:
+    matchLabels:
+      app: commerce-meilisearch
+  template:
+    metadata:
+      labels:
+        app: commerce-meilisearch
+    spec:
+      terminationGracePeriodSeconds: 30
+      containers:
+        - name: meilisearch
+          image: getmeili/meilisearch:v1.53.1
+          imagePullPolicy: IfNotPresent
+          env:
+            - name: MEILI_MASTER_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: commerce-secrets
+                  key: MEILI_MASTER_KEY
+            - name: MEILI_ENV
+              value: production
+            # Sin telemetria a un tercero por defecto (misma postura del
+            # resto del namespace: nada de egress no explicado).
+            - name: MEILI_NO_ANALYTICS
+              value: "true"
+          ports:
+            - name: http
+              containerPort: 7700
+          # /health no requiere auth (confirmado en vivo) -- sirve tal
+          # cual para las dos probes, igual que minio usa sus propios
+          # endpoints /minio/health/*.
+          readinessProbe:
+            httpGet:
+              path: /health
+              port: http
+            initialDelaySeconds: 5
+            periodSeconds: 10
+            timeoutSeconds: 5
+            failureThreshold: 6
+          livenessProbe:
+            httpGet:
+              path: /health
+              port: http
+            initialDelaySeconds: 15
+            periodSeconds: 20
+            timeoutSeconds: 5
+            failureThreshold: 6
+          resources:
+            requests:
+              cpu: 100m
+              memory: 256Mi
+            limits:
+              cpu: 500m
+              memory: 768Mi
+          volumeMounts:
+            - name: meilisearch-data
+              mountPath: /meili_data
+  volumeClaimTemplates:
+    - metadata:
+        name: meilisearch-data
+      spec:
+        accessModes:
+          - ReadWriteOnce
+        storageClassName: local-path
+        resources:
+          requests:
+            storage: 5Gi

workloads/ecommerce/commerce/middleware-commerce-redirect.yaml

@@ -0,0 +1,16 @@
+apiVersion: traefik.io/v1alpha1
+kind: Middleware
+metadata:
+  name: commerce-redirect-app
+spec:
+  # Redirige solo la raíz exacta de commerce.cruzcloud.net a /app (admin de
+  # Medusa) — el regex incluye el host a propósito: esta Middleware se
+  # referencia desde el mismo Ingress que también enruta media.cruzcloud.net,
+  # y sin el host en el regex un request a la raíz de ese otro dominio
+  # también matchearía (ambas rutas comparten Ingress -> mismas
+  # router.middlewares). Si el regex no matchea, Traefik deja pasar el
+  # request sin modificarlo.
+  redirectRegex:
+    regex: "^https?://commerce\\.cruzcloud\\.net/$"
+    replacement: "https://commerce.cruzcloud.net/app"
+    permanent: true

workloads/ecommerce/commerce/secrets.template.yaml

@@ -23,6 +23,14 @@ stringData:
   JWT_SECRET: CAMBIAR
   COOKIE_SECRET: CAMBIAR
 
+  # Master key del servidor Meilisearch (StatefulSet commerce-meilisearch,
+  # env MEILI_MASTER_KEY del propio contenedor getmeili/meilisearch) Y
+  # credencial que usa el plugin de Medusa para autenticarse contra el
+  # -- MISMO valor, dos nombres de secret porque cada lado (servidor vs.
+  # plugin cliente) usa su propia convencion de nombre de env var.
+  MEILI_MASTER_KEY: CAMBIAR
+  MEILISEARCH_API_KEY: CAMBIAR
+
   # Debe ser el MISMO valor que REVALIDATE_SECRET en el Secret
   # commerce-storefront: el subscriber de Medusa lo envía como header
   # x-revalidate-secret al invocar POST /api/revalidate en el storefront.

workloads/ecommerce/components/cart/cart-drawer.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import Image from "next/image";
+import Link from "next/link";
 import { Minus, Plus, ShoppingBag, Trash2 } from "lucide-react";
 import { Button } from "@/components/ui/button";
 import { Progress } from "@/components/ui/progress";
@@ -17,13 +18,6 @@ export function CartDrawer() {
   const progress = pricedItems ? Math.min(100, (subtotal / FREE_SHIPPING_THRESHOLD) * 100) : 0;
   const count = items.reduce((sum, item) => sum + item.quantity, 0);
 
-  const checkout = () => {
-    const lines = items.map((item) => `• ${item.quantity} x ${item.product.name}`).join("\n");
-    const message = `Hola Ari Shopping 👋\nQuiero consultar disponibilidad para:\n\n${lines}\n\nNombre:\nCiudad:\nForma de entrega:`;
-    void navigator.clipboard?.writeText(message);
-    window.open(process.env.NEXT_PUBLIC_WHATSAPP_URL ?? "https://wa.link/rvcqqc", "_blank", "noopener,noreferrer");
-  };
-
   return (
     <Sheet open={isOpen} onOpenChange={(open) => { if (!open) closeCart(); }}>
       <SheetContent>
@@ -49,7 +43,15 @@ export function CartDrawer() {
         <div className="space-y-4 border-t border-slate-100 p-6">
           <div><div className="mb-2 flex justify-between text-xs font-bold text-slate-600"><span>{pricedItems ? "Progreso para envío gratis" : "Cotización personalizada"}</span><span>{pricedItems ? `${Math.round(progress)}%` : "Por confirmar"}</span></div><Progress value={progress} /></div>
           <div className="flex items-center justify-between"><span className="font-bold text-slate-600">Subtotal</span><strong className="text-xl font-black">{pricedItems ? formatMoney(subtotal) : "Por confirmar"}</strong></div>
-          <Button variant="magenta" size="lg" className="w-full" disabled={!items.length} onClick={checkout}>Continuar por WhatsApp</Button>
+          {/* Button asChild + disabled no funciona sobre un <a> (:disabled
+              es pseudo-clase de elementos de formulario, un Link nunca la
+              cumple) -- se ramifica en vez de confiar en el prop disabled
+              sobre un Link. */}
+          {items.length > 0 ? (
+            <Button asChild variant="primary" size="lg" className="w-full"><Link href="/checkout" onClick={closeCart}>Confirmar pedido</Link></Button>
+          ) : (
+            <Button variant="primary" size="lg" className="w-full" disabled>Confirmar pedido</Button>
+          )}
           <Button variant="ghost" className="w-full" disabled={!items.length} onClick={clearCart}>Vaciar carrito</Button>
         </div>
       </SheetContent>

workloads/ecommerce/components/catalog/catalog-client.tsx

@@ -1,21 +1,71 @@
 "use client";
 
-import { SlidersHorizontal, X } from "lucide-react";
+import Link from "next/link";
+import { ChevronRight, SlidersHorizontal, X } from "lucide-react";
 import { useEffect, useMemo, useState } from "react";
+import { PromoTile } from "@/components/home/category-tiles";
 import { ProductCard } from "@/components/product/product-card";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
-import type { Product } from "@/lib/headless/types";
+import type { Category, FacetDistribution, Product } from "@/lib/headless/types";
+
+// Cada cuantas tarjetas de producto se intercala un tile promocional en
+// la grilla (patron Walmart, ADR 0005 seccion 3): grid con tiles
+// promocionales intercalados, no solo tarjetas homogeneas.
+const PROMO_TILE_INTERVAL = 8;
+
+type GridItem = { type: "product"; product: Product } | { type: "promo"; category: Category };
 
 type CatalogClientProps = {
   products: Product[];
+  categories?: Category[];
+  categoryGroups?: Record<string, string[]>;
   initialCategory?: string;
   initialCollection?: string;
   initialQuery?: string;
 };
 
+function matchesQuery(product: Product, query: string): boolean {
+  if (!query) return true;
+  const search = [product.name, product.category, product.collection, product.brand].join(" ").toLowerCase();
+  return search.includes(query.toLowerCase());
+}
+function matchesCategory(product: Product, allowedCategories: string[]): boolean {
+  return allowedCategories.includes(product.category);
+}
+function matchesCollection(product: Product, collection: string): boolean {
+  return !collection || product.collection === collection;
+}
+function matchesBrand(product: Product, brand: string): boolean {
+  return brand === "Todas" || product.brand === brand;
+}
+function matchesAge(product: Product, age: string): boolean {
+  return age === "Todas" || product.ageRange === age;
+}
+function matchesPrice(product: Product, maxPrice: number): boolean {
+  return product.price === null || maxPrice === 0 || product.price <= maxPrice;
+}
+
+// Camina parentId hacia arriba desde la categoria seleccionada para armar
+// el breadcrumb real (Inicio > raiz > hija), igual que en Amazon.
+function buildBreadcrumb(categories: Category[], name: string): Category[] {
+  const node = categories.find((category) => category.name === name);
+  if (!node) return [];
+  const trail = [node];
+  let current = node;
+  while (current.parentId) {
+    const parent = categories.find((category) => category.id === current.parentId);
+    if (!parent) break;
+    trail.unshift(parent);
+    current = parent;
+  }
+  return trail;
+}
+
 export function CatalogClient({
   products,
+  categories: categoryNodes = [],
+  categoryGroups = {},
   initialCategory = "Todos",
   initialCollection = "",
   initialQuery = "",
@@ -48,28 +98,30 @@ export function CatalogClient({
     setMaxPrice(maxCatalogPrice);
   }, [initialCategory, initialCollection, initialQuery, maxCatalogPrice]);
 
+  // Si `category` es una raiz con hijos (ej. "Mochilas y morrales"), se
+  // expande a la lista de nombres reales de sus hijos -- ningun producto
+  // tiene la raiz asignada directamente. Si no es una raiz conocida, se
+  // trata como el nombre de categoria exacto de siempre.
+  const allowedCategories = categoryGroups[category] ?? [category];
+  const breadcrumb = useMemo(() => (category === "Todos" ? [] : buildBreadcrumb(categoryNodes, category)), [categoryNodes, category]);
+  // No promociona la misma categoria raiz que el usuario ya esta viendo.
+  const promoRoots = useMemo(() => {
+    const excludeRootId = breadcrumb[0]?.id;
+    return categoryNodes.filter((node) => !node.parentId && node.id !== excludeRootId);
+  }, [categoryNodes, breadcrumb]);
+
   const filtered = useMemo(
     () =>
       products
-        .filter((product) => {
-          const search = [
-            product.name,
-            product.category,
-            product.collection,
-            product.brand,
-          ]
-            .join(" ")
-            .toLowerCase();
-
-          return (
-            (!query || search.includes(query.toLowerCase())) &&
-            (category === "Todos" || product.category === category) &&
-            (!collection || product.collection === collection) &&
-            (brand === "Todas" || product.brand === brand) &&
-            (age === "Todas" || product.ageRange === age) &&
-            (product.price === null || maxPrice === 0 || product.price <= maxPrice)
-          );
-        })
+        .filter(
+          (product) =>
+            matchesQuery(product, query) &&
+            (category === "Todos" || matchesCategory(product, allowedCategories)) &&
+            matchesCollection(product, collection) &&
+            matchesBrand(product, brand) &&
+            matchesAge(product, age) &&
+            matchesPrice(product, maxPrice),
+        )
         .sort((a, b) =>
           sort === "name"
             ? a.name.localeCompare(b.name, "es")
@@ -77,7 +129,183 @@ export function CatalogClient({
               ? Number(b.isNew) - Number(a.isNew)
               : Number(b.featured) - Number(a.featured),
         ),
-    [age, brand, category, collection, maxPrice, products, query, sort],
+    [age, allowedCategories, brand, category, collection, maxPrice, products, query, sort],
+  );
+
+  // Intercala un tile promocional cada PROMO_TILE_INTERVAL productos,
+  // ciclando por las categorias raiz -- si no hay jerarquia de
+  // categorias disponible, la grilla queda igual que antes (solo
+  // productos).
+  const gridItems = useMemo<GridItem[]>(() => {
+    if (promoRoots.length === 0) return filtered.map((product) => ({ type: "product", product }));
+
+    const items: GridItem[] = [];
+    let promoIndex = 0;
+    filtered.forEach((product, index) => {
+      items.push({ type: "product", product });
+      const isLast = index === filtered.length - 1;
+      const promoCategory = promoRoots[promoIndex % promoRoots.length];
+      if (!isLast && (index + 1) % PROMO_TILE_INTERVAL === 0 && promoCategory) {
+        items.push({ type: "promo", category: promoCategory });
+        promoIndex += 1;
+      }
+    });
+    return items;
+  }, [filtered, promoRoots]);
+
+  // Conteos por valor de filtro (patron Amazon: "Marca (12)"), calculados
+  // sobre los productos que ya pasan el resto de filtros activos -- cada
+  // dimension se cuenta excluyendose a si misma para reflejar cuantos
+  // resultados habria si se eligiera ese valor. Sirven de fallback cuando
+  // el provider activo no soporta facetas reales (mock/shopify) o cuando
+  // la busqueda en vivo todavia no respondio.
+  const fallbackCategoryCounts = useMemo(() => {
+    const base = products.filter(
+      (product) => matchesQuery(product, query) && matchesCollection(product, collection) && matchesBrand(product, brand) && matchesAge(product, age) && matchesPrice(product, maxPrice),
+    );
+    const counts: Record<string, number> = { Todos: base.length };
+    for (const name of categories) {
+      if (name === "Todos") continue;
+      const allowed = categoryGroups[name] ?? [name];
+      counts[name] = base.filter((product) => matchesCategory(product, allowed)).length;
+    }
+    return counts;
+  }, [age, brand, categories, categoryGroups, collection, maxPrice, products, query]);
+
+  const fallbackBrandCounts = useMemo(() => {
+    const base = products.filter(
+      (product) =>
+        matchesQuery(product, query) &&
+        (category === "Todos" || matchesCategory(product, allowedCategories)) &&
+        matchesCollection(product, collection) &&
+        matchesAge(product, age) &&
+        matchesPrice(product, maxPrice),
+    );
+    const counts: Record<string, number> = { Todas: base.length };
+    for (const value of brands) {
+      if (value === "Todas") continue;
+      counts[value] = base.filter((product) => product.brand === value).length;
+    }
+    return counts;
+  }, [age, allowedCategories, brands, category, collection, maxPrice, products, query]);
+
+  const fallbackAgeCounts = useMemo(() => {
+    const base = products.filter(
+      (product) =>
+        matchesQuery(product, query) &&
+        (category === "Todos" || matchesCategory(product, allowedCategories)) &&
+        matchesCollection(product, collection) &&
+        matchesBrand(product, brand) &&
+        matchesPrice(product, maxPrice),
+    );
+    const counts: Record<string, number> = { Todas: base.length };
+    for (const value of ages) {
+      if (value === "Todas") continue;
+      counts[value] = base.filter((product) => product.ageRange === value).length;
+    }
+    return counts;
+  }, [ages, allowedCategories, brand, category, collection, maxPrice, products, query]);
+
+  // "Mochilas y morrales" etc.: nombre sintetico de grupo que no existe
+  // como valor indexado en Meilisearch (ningun producto lo tiene como
+  // category real, solo sus hijos -- ver categoryGroups arriba). Mientras
+  // esa sea la categoria activa, las facetas en vivo de marca/edad no
+  // pueden filtrar por ella y se degrada al conteo client-side, que si
+  // sabe expandir el grupo via matchesCategory/allowedCategories.
+  const categoryIsLeafOrNone = category === "Todos" || !categoryGroups[category];
+
+  // Conteos reales via Meilisearch (ADR 0006 Etapa 2 Fase 3b): un fetch
+  // por dimension contra /api/search, cada uno omitiendo su propio filtro
+  // (mismo criterio de auto-exclusion que el fallback de arriba) para que
+  // los conteos reflejen el subconjunto ya filtrado por las OTRAS
+  // dimensiones y se puedan seguir eligiendo otros valores. `limit=0` evita
+  // rehidratar precios de productos que no vamos a mostrar -- solo importan
+  // `facetDistribution` y `count`.
+  const [liveFacets, setLiveFacets] = useState<{
+    category: Record<string, number> | null;
+    categoryTotal: number | null;
+    brand: Record<string, number> | null;
+    brandTotal: number | null;
+    ageRange: Record<string, number> | null;
+    ageTotal: number | null;
+  }>({ category: null, categoryTotal: null, brand: null, brandTotal: null, ageRange: null, ageTotal: null });
+
+  useEffect(() => {
+    const controller = new AbortController();
+
+    function buildParams(omit: "category" | "brand" | "ageRange"): URLSearchParams {
+      const params = new URLSearchParams({ limit: "0" });
+      if (query) params.set("q", query);
+      if (collection) params.set("collection", collection);
+      if (omit !== "category" && category !== "Todos" && categoryIsLeafOrNone) {
+        params.set("category", category);
+      }
+      if (omit !== "brand" && brand !== "Todas") params.set("brand", brand);
+      if (omit !== "ageRange" && age !== "Todas") params.set("ageRange", age);
+      if (maxPrice > 0) params.set("maxPrice", String(maxPrice));
+      return params;
+    }
+
+    async function fetchFacet(omit: "category" | "brand" | "ageRange") {
+      const response = await fetch(`/api/search?${buildParams(omit).toString()}`, {
+        signal: controller.signal,
+      });
+      return (await response.json()) as { facetDistribution?: FacetDistribution };
+    }
+
+    // El "count"/estimatedTotalHits que devuelve /api/search viene en 0 con
+    // limit=0 (confirmado en vivo contra Meilisearch real -- limit>=1 lo
+    // reporta bien, limit=0 no). facetDistribution si es correcto con
+    // limit=0, y cada producto tiene siempre un valor para cada dimension
+    // (mapProduct usa defaults como "ARI Shopping"/"Todas", nunca null), asi
+    // que sumar sus valores da el total real sin depender de ese campo.
+    function sumFacetValues(facet: Record<string, number> | null): number {
+      return facet ? Object.values(facet).reduce((sum, value) => sum + value, 0) : 0;
+    }
+
+    const timer = setTimeout(() => {
+      Promise.all([fetchFacet("category"), fetchFacet("brand"), fetchFacet("ageRange")])
+        .then(([categoryRes, brandRes, ageRes]) => {
+          // Un facetDistribution vacio ({}) es la senal de degrade explicita
+          // de /api/search (provider sin searchWithFacets, o Meilisearch
+          // sin indices todavia) -- distinto de una faceta real con 0
+          // resultados, que igual trae la clave presente.
+          const categoryFacet = categoryRes.facetDistribution && "category" in categoryRes.facetDistribution ? categoryRes.facetDistribution.category : null;
+          const brandFacet = brandRes.facetDistribution && "brand" in brandRes.facetDistribution ? brandRes.facetDistribution.brand : null;
+          const ageFacet = ageRes.facetDistribution && "ageRange" in ageRes.facetDistribution ? ageRes.facetDistribution.ageRange : null;
+          setLiveFacets({
+            category: categoryFacet,
+            categoryTotal: categoryFacet ? sumFacetValues(categoryFacet) : null,
+            brand: categoryIsLeafOrNone ? brandFacet : null,
+            brandTotal: categoryIsLeafOrNone && brandFacet ? sumFacetValues(brandFacet) : null,
+            ageRange: categoryIsLeafOrNone ? ageFacet : null,
+            ageTotal: categoryIsLeafOrNone && ageFacet ? sumFacetValues(ageFacet) : null,
+          });
+        })
+        .catch((error) => {
+          if ((error as Error).name !== "AbortError") {
+            setLiveFacets({ category: null, categoryTotal: null, brand: null, brandTotal: null, ageRange: null, ageTotal: null });
+          }
+        });
+    }, 300);
+
+    return () => {
+      clearTimeout(timer);
+      controller.abort();
+    };
+  }, [age, brand, category, categoryIsLeafOrNone, collection, maxPrice, query]);
+
+  const categoryCounts = useMemo(
+    () => (liveFacets.category ? { Todos: liveFacets.categoryTotal ?? 0, ...liveFacets.category } : fallbackCategoryCounts),
+    [fallbackCategoryCounts, liveFacets.category, liveFacets.categoryTotal],
+  );
+  const brandCounts = useMemo(
+    () => (liveFacets.brand ? { Todas: liveFacets.brandTotal ?? 0, ...liveFacets.brand } : fallbackBrandCounts),
+    [fallbackBrandCounts, liveFacets.brand, liveFacets.brandTotal],
+  );
+  const ageCounts = useMemo(
+    () => (liveFacets.ageRange ? { Todas: liveFacets.ageTotal ?? 0, ...liveFacets.ageRange } : fallbackAgeCounts),
+    [fallbackAgeCounts, liveFacets.ageRange, liveFacets.ageTotal],
   );
 
   const reset = () => {
@@ -93,23 +321,44 @@ export function CatalogClient({
   return (
     <div className="mx-auto max-w-7xl px-4 py-10">
       <div className="mb-8">
-        <span className="text-xs font-black uppercase tracking-[.18em] text-fuchsia-600">
+        {breadcrumb.length > 0 && (
+          <nav aria-label="Breadcrumb" className="mb-4 flex flex-wrap items-center gap-1.5 text-xs font-bold text-slate-500">
+            <Link href="/catalog" prefetch={false} className="hover:text-ari-coral">
+              Inicio
+            </Link>
+            {breadcrumb.map((node, index) => (
+              <span key={node.id} className="flex items-center gap-1.5">
+                <ChevronRight className="size-3" />
+                {index === breadcrumb.length - 1 ? (
+                  <span aria-current="page" className="text-ari-marino">
+                    {node.name}
+                  </span>
+                ) : (
+                  <Link href={`/catalog?category=${encodeURIComponent(node.name)}`} prefetch={false} className="hover:text-ari-coral">
+                    {node.name}
+                  </Link>
+                )}
+              </span>
+            ))}
+          </nav>
+        )}
+        <span className="text-xs font-black uppercase tracking-[.18em] text-ari-coral">
           Catálogo completo
         </span>
-        <h1 className="mt-2 text-5xl font-black tracking-tight">Todos los tesoros</h1>
+        <h1 className="font-display mt-2 text-5xl font-bold tracking-tight text-ari-marino">Todos los tesoros</h1>
         <p className="mt-3 text-slate-500">
           Filtra por categoría, marca o edad sin recargar la página.
         </p>
       </div>
 
       <div className="grid gap-8 lg:grid-cols-[260px_1fr]">
-        <aside className="h-fit space-y-6 rounded-3xl border border-slate-100 bg-white p-6 shadow-lg shadow-slate-900/5 lg:sticky lg:top-44">
+        <aside className="h-fit space-y-6 rounded-lg border border-slate-100 bg-white p-6 shadow-lg shadow-ari-marino/5 lg:sticky lg:top-44">
           <div className="flex items-center justify-between">
             <strong className="flex items-center gap-2 text-lg font-black">
-              <SlidersHorizontal className="size-5 text-cyan-600" />
+              <SlidersHorizontal className="size-5 text-ari-coral-claro" />
               Filtros
             </strong>
-            <button onClick={reset} className="text-xs font-black text-fuchsia-600">
+            <button onClick={reset} className="text-xs font-black text-ari-coral">
               <X className="mr-1 inline size-3" />
               Limpiar
             </button>
@@ -126,9 +375,10 @@ export function CatalogClient({
             values={categories}
             selected={category}
             onChange={setCategory}
+            counts={categoryCounts}
           />
-          <Filter title="Marca" values={brands} selected={brand} onChange={setBrand} />
-          <Filter title="Edad" values={ages} selected={age} onChange={setAge} />
+          <Filter title="Marca" values={brands} selected={brand} onChange={setBrand} counts={brandCounts} />
+          <Filter title="Edad" values={ages} selected={age} onChange={setAge} counts={ageCounts} />
 
           <fieldset>
             <legend className="mb-3 text-sm font-black">Precio máximo</legend>
@@ -142,7 +392,7 @@ export function CatalogClient({
                   step={5000}
                   value={maxPrice}
                   onChange={(event) => setMaxPrice(Number(event.target.value))}
-                  className="w-full accent-fuchsia-500"
+                  className="w-full accent-ari-coral"
                 />
                 <p className="mt-2 text-xs font-bold text-slate-500">
                   Hasta ${maxPrice.toLocaleString("es-CO")}
@@ -162,7 +412,7 @@ export function CatalogClient({
             <select
               value={sort}
               onChange={(event) => setSort(event.target.value)}
-              className="h-11 rounded-full border border-slate-200 bg-white px-4 text-sm font-bold"
+              className="h-11 rounded-lg border border-slate-200 bg-white px-4 text-sm font-bold"
             >
               <option value="featured">Destacados</option>
               <option value="new">Novedades</option>
@@ -172,15 +422,19 @@ export function CatalogClient({
 
           {filtered.length ? (
             <div className="grid gap-5 sm:grid-cols-2 xl:grid-cols-3">
-              {filtered.map((product) => (
-                <ProductCard key={product.id} product={product} />
-              ))}
+              {gridItems.map((item, index) =>
+                item.type === "product" ? (
+                  <ProductCard key={item.product.id} product={item.product} />
+                ) : (
+                  <PromoTile key={`promo-${index}`} category={item.category} className="min-h-[22rem]" />
+                ),
+              )}
             </div>
           ) : (
-            <div className="grid min-h-80 place-items-center rounded-3xl border border-dashed border-slate-300 text-center">
+            <div className="grid min-h-80 place-items-center rounded-lg border border-dashed border-slate-300 text-center">
               <div>
                 <p className="text-xl font-black">No encontramos productos</p>
-                <Button variant="magenta" className="mt-4" onClick={reset}>
+                <Button variant="primary" className="mt-4" onClick={reset}>
                   Restablecer filtros
                 </Button>
               </div>
@@ -197,11 +451,13 @@ function Filter({
   values,
   selected,
   onChange,
+  counts,
 }: {
   title: string;
   values: string[];
   selected: string;
   onChange: (value: string) => void;
+  counts?: Record<string, number>;
 }) {
   return (
     <fieldset>
@@ -212,13 +468,14 @@ function Filter({
             type="button"
             key={value}
             onClick={() => onChange(value)}
-            className={`rounded-full px-3 py-2 text-xs font-bold transition ${
+            className={`rounded-md px-3 py-2 text-xs font-bold transition ${
               selected === value
-                ? "bg-slate-950 text-white"
-                : "bg-slate-100 text-slate-600 hover:bg-cyan-100"
+                ? "bg-ari-marino text-white"
+                : "bg-slate-100 text-slate-600 hover:bg-ari-coral-claro/10"
             }`}
           >
             {value}
+            {counts && <span className="ml-1 opacity-60">({counts[value] ?? 0})</span>}
           </button>
         ))}
       </div>

workloads/ecommerce/components/checkout/checkout-client.tsx

@@ -0,0 +1,184 @@
+"use client";
+
+import Image from "next/image";
+import Link from "next/link";
+import { ArrowLeft, MapPin, MessageCircle, Truck } from "lucide-react";
+import { type FormEvent, useState } from "react";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { formatMoney } from "@/lib/utils";
+import { useCartStore } from "@/store/cart-store";
+
+// ADR 0009, siguiente corte tras el carrito real: direccion + seleccion de
+// envio contra el Store API real (mismos endpoints ya verificados en vivo
+// para las shipping options). El pago (PayU custom) todavia no existe --
+// el ultimo paso sigue siendo WhatsApp, ahora con el pedido completo
+// (direccion, envio, total real) en vez de solo la lista de productos.
+
+interface ShippingOption {
+  id: string;
+  name: string;
+  amount: number;
+}
+
+type Step = "address" | "shipping" | "review";
+
+async function postJson(url: string, body: unknown) {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  return response.json();
+}
+
+export function CheckoutClient() {
+  const { cartId, items, hasHydrated } = useCartStore();
+  const [step, setStep] = useState<Step>("address");
+  const [form, setForm] = useState({ firstName: "", lastName: "", address1: "", city: "", province: "", phone: "", email: "" });
+  const [shippingOptions, setShippingOptions] = useState<ShippingOption[]>([]);
+  const [selectedOptionId, setSelectedOptionId] = useState<string | null>(null);
+  const [shippingTotal, setShippingTotal] = useState(0);
+  const [total, setTotal] = useState(0);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const itemsSubtotal = items.reduce((sum, item) => sum + (item.product.price ?? 0) * item.quantity, 0);
+  const currency = items[0]?.product.currency;
+
+  async function submitAddress(event: FormEvent) {
+    event.preventDefault();
+    if (!cartId) return;
+    setLoading(true);
+    setError(null);
+    try {
+      const cart = await postJson("/api/cart/address", { cartId, ...form });
+      if (cart.error) throw new Error(cart.error);
+      const response = await fetch(`/api/cart/shipping-options?cartId=${cartId}`);
+      const data = await response.json();
+      const options: ShippingOption[] = data.options ?? [];
+      setShippingOptions(options);
+      setSelectedOptionId(options[0]?.id ?? null);
+      setStep("shipping");
+    } catch (submitError) {
+      setError((submitError as Error).message);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  async function submitShipping() {
+    if (!cartId || !selectedOptionId) return;
+    setLoading(true);
+    setError(null);
+    try {
+      const cart = await postJson("/api/cart/shipping-method", { cartId, optionId: selectedOptionId });
+      if (cart.error) throw new Error(cart.error);
+      setShippingTotal(cart.shippingTotal ?? 0);
+      setTotal(cart.total ?? itemsSubtotal);
+      setStep("review");
+    } catch (submitError) {
+      setError((submitError as Error).message);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  function continueOnWhatsApp() {
+    const lines = items.map((item) => `• ${item.quantity} x ${item.product.name}`).join("\n");
+    const message = `Hola Ari Shopping 👋\nQuiero confirmar mi pedido:\n\n${lines}\n\nSubtotal: ${formatMoney(itemsSubtotal, currency)}\nEnvío: ${formatMoney(shippingTotal, currency)}\nTotal: ${formatMoney(total, currency)}\n\nNombre: ${form.firstName} ${form.lastName}\nDirección: ${form.address1}, ${form.city}${form.province ? `, ${form.province}` : ""}\nTeléfono: ${form.phone}`;
+    void navigator.clipboard?.writeText(message);
+    window.open(process.env.NEXT_PUBLIC_WHATSAPP_URL ?? "https://wa.link/rvcqqc", "_blank", "noopener,noreferrer");
+  }
+
+  if (!hasHydrated) return null;
+
+  if (items.length === 0) {
+    return (
+      <div className="mx-auto max-w-lg px-4 py-24 text-center">
+        <p className="text-lg font-bold">Tu carrito está vacío.</p>
+        <Button asChild variant="primary" className="mt-6"><Link href="/catalog">Ver catálogo</Link></Button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="mx-auto grid max-w-5xl gap-10 px-4 py-10 lg:grid-cols-[1fr_.8fr] lg:py-16">
+      <div>
+        <Link href="/" className="mb-6 inline-flex items-center gap-1.5 text-sm font-bold text-slate-500 hover:text-ari-marino"><ArrowLeft className="size-4" />Seguir comprando</Link>
+        <h1 className="text-3xl font-black tracking-tight sm:text-4xl">Confirmar pedido</h1>
+
+        {step === "address" && (
+          <form onSubmit={submitAddress} className="mt-8 space-y-4">
+            <div className="grid gap-4 sm:grid-cols-2">
+              <Input placeholder="Nombre" required value={form.firstName} onChange={(event) => setForm({ ...form, firstName: event.target.value })} />
+              <Input placeholder="Apellido" required value={form.lastName} onChange={(event) => setForm({ ...form, lastName: event.target.value })} />
+            </div>
+            <Input placeholder="Dirección" required value={form.address1} onChange={(event) => setForm({ ...form, address1: event.target.value })} />
+            <div className="grid gap-4 sm:grid-cols-2">
+              <Input placeholder="Ciudad" required value={form.city} onChange={(event) => setForm({ ...form, city: event.target.value })} />
+              <Input placeholder="Departamento" value={form.province} onChange={(event) => setForm({ ...form, province: event.target.value })} />
+            </div>
+            <div className="grid gap-4 sm:grid-cols-2">
+              <Input placeholder="Teléfono" required value={form.phone} onChange={(event) => setForm({ ...form, phone: event.target.value })} />
+              <Input type="email" placeholder="Correo" required value={form.email} onChange={(event) => setForm({ ...form, email: event.target.value })} />
+            </div>
+            {error && <p className="text-sm font-bold text-rose-600">{error}</p>}
+            <Button type="submit" variant="primary" size="lg" className="w-full" disabled={loading}>{loading ? "Guardando…" : "Continuar a envío"}</Button>
+          </form>
+        )}
+
+        {step === "shipping" && (
+          <div className="mt-8 space-y-4">
+            <p className="flex items-center gap-2 text-sm font-bold text-slate-500"><MapPin className="size-4" />{form.address1}, {form.city}{form.province ? `, ${form.province}` : ""}</p>
+            <div className="space-y-3">
+              {shippingOptions.map((option) => (
+                <label key={option.id} className={`flex cursor-pointer items-center justify-between rounded-2xl border-2 p-4 transition ${selectedOptionId === option.id ? "border-ari-marino bg-ari-marino/5" : "border-slate-200"}`}>
+                  <span className="flex items-center gap-3 font-bold"><Truck className="size-5 text-ari-marino" />{option.name}</span>
+                  <span className="flex items-center gap-3">
+                    <span className="font-black">{formatMoney(option.amount, currency)}</span>
+                    <input type="radio" name="shipping" checked={selectedOptionId === option.id} onChange={() => setSelectedOptionId(option.id)} />
+                  </span>
+                </label>
+              ))}
+              {shippingOptions.length === 0 && <p className="text-sm text-slate-500">No hay opciones de envío disponibles para esta dirección.</p>}
+            </div>
+            {error && <p className="text-sm font-bold text-rose-600">{error}</p>}
+            <Button variant="primary" size="lg" className="w-full" disabled={loading || !selectedOptionId} onClick={submitShipping}>{loading ? "Guardando…" : "Continuar"}</Button>
+          </div>
+        )}
+
+        {step === "review" && (
+          <div className="mt-8 space-y-4">
+            <div className="rounded-2xl border border-slate-200 p-5">
+              <p className="text-xs font-black uppercase tracking-wide text-slate-400">Entrega</p>
+              <p className="mt-1 font-bold">{form.firstName} {form.lastName}</p>
+              <p className="text-sm text-slate-500">{form.address1}, {form.city}{form.province ? `, ${form.province}` : ""}</p>
+              <p className="text-sm text-slate-500">{form.phone}</p>
+            </div>
+            <p className="text-sm text-slate-500">El pago en línea todavía no está disponible — confirmamos tu pedido por WhatsApp con estos datos.</p>
+            <Button variant="primary" size="lg" className="w-full" onClick={continueOnWhatsApp}><MessageCircle className="size-5" />Confirmar por WhatsApp</Button>
+          </div>
+        )}
+      </div>
+
+      <div className="h-fit rounded-3xl border border-slate-200 p-6">
+        <h2 className="font-black">Tu pedido</h2>
+        <div className="mt-4 space-y-3">
+          {items.map((item) => (
+            <div key={item.lineItemId} className="flex items-center gap-3">
+              <div className="relative size-14 shrink-0 overflow-hidden rounded-xl bg-slate-100"><Image src={item.product.thumbnail} alt={item.product.name} fill sizes="56px" className="object-cover" /></div>
+              <div className="flex-1"><p className="text-sm font-bold leading-5">{item.product.name}</p><p className="text-xs text-slate-500">Cantidad: {item.quantity}</p></div>
+              <p className="text-sm font-black">{formatMoney((item.product.price ?? 0) * item.quantity, item.product.currency)}</p>
+            </div>
+          ))}
+        </div>
+        <div className="mt-5 space-y-2 border-t border-slate-100 pt-4 text-sm">
+          <div className="flex justify-between"><span className="text-slate-500">Subtotal</span><span className="font-bold">{formatMoney(itemsSubtotal, currency)}</span></div>
+          {step === "review" && <div className="flex justify-between"><span className="text-slate-500">Envío</span><span className="font-bold">{formatMoney(shippingTotal, currency)}</span></div>}
+          <div className="flex justify-between text-base"><span className="font-black">Total</span><span className="font-black">{formatMoney(step === "review" ? total : itemsSubtotal, currency)}</span></div>
+        </div>
+      </div>
+    </div>
+  );
+}

workloads/ecommerce/components/home/category-tiles.tsx

@@ -1,14 +1,84 @@
 import Image from "next/image";
 import Link from "next/link";
 import { ArrowUpRight } from "lucide-react";
+import type { Category } from "@/lib/headless/types";
+import { cn } from "@/lib/utils";
 
-const categories = [
-  { title: "Juguetes", subtitle: "Personajes que inspiran", image: "/images/categories/figuras.webp", href: "/catalog?category=Figuras", color: "from-yellow-300 to-orange-400" },
-  { title: "Peluches", subtitle: "Compañeros para regalar", image: "/images/categories/peluches.webp", href: "/catalog?category=Peluches", color: "from-pink-400 to-fuchsia-500" },
-  { title: "Mochilas", subtitle: "Estilo para cada aventura", image: "/images/categories/mochilas.webp", href: "/catalog?category=Mochilas", color: "from-cyan-400 to-blue-500" },
-  { title: "Marvel", subtitle: "Tu héroe favorito", image: "/images/categories/marvel.webp", href: "/catalog?collection=Marvel", color: "from-red-500 to-rose-700" },
-];
+type TileContent = { subtitle: string; image?: string; color: string };
 
-export function CategoryTiles() {
-  return <section className="mx-auto max-w-7xl px-4 py-14"><div className="mb-8 flex items-end justify-between gap-4"><div><span className="text-xs font-black uppercase tracking-[.18em] text-fuchsia-600">Explora por mundos</span><h2 className="mt-2 text-4xl font-black tracking-tight sm:text-5xl">Encuentra tu próximo tesoro</h2></div><Link href="/catalog" className="hidden font-black text-cyan-700 sm:block">Ver todo →</Link></div><div className="grid gap-5 sm:grid-cols-2 lg:grid-cols-4">{categories.map((item) => <Link key={item.title} href={item.href} className={`group relative min-h-80 overflow-hidden rounded-[2rem] bg-gradient-to-br ${item.color} shadow-xl`}><Image src={item.image} alt={item.title} fill sizes="(max-width: 640px) 100vw, 25vw" className="object-cover transition duration-500 group-hover:scale-105" /><div className="absolute inset-0 bg-gradient-to-t from-slate-950/80 via-transparent to-white/5" /><div className="absolute inset-x-0 bottom-0 flex items-end justify-between p-6 text-white"><div><h3 className="text-2xl font-black">{item.title}</h3><p className="mt-1 text-sm font-semibold text-white/80">{item.subtitle}</p></div><span className="grid size-11 place-items-center rounded-full bg-white text-slate-950 transition group-hover:rotate-45"><ArrowUpRight /></span></div></Link>)}</div></section>;
+// No hay fotografia real todavia para las 6 categorias raiz de la taxonomia
+// (ver ADR 0005) -- solo se mapean imagen/subtitulo para las que ya tienen
+// un asset en public/images/categories/. Las demas caen al tile de solo
+// gradiente en vez de mostrar una imagen que no les corresponde.
+// Fondos pastel solidos (patron Walmart-inspirado, ADR 0008 sub-fase 4)
+// en vez de los gradientes saturados originales del esquema arcoiris --
+// un tono pastel distinto por categoria, no una escala de marca (serian
+// todos casi iguales), pero coordinados en la misma temperatura suave.
+const tileContent: Record<string, TileContent> = {
+  juguetes: { subtitle: "Personajes que inspiran", image: "/images/categories/figuras.webp", color: "bg-amber-100" },
+  "mochilas-y-morrales": { subtitle: "Estilo para cada aventura", image: "/images/categories/mochilas.webp", color: "bg-sky-100" },
+  "bebes-y-primera-infancia": { subtitle: "Primeros descubrimientos", color: "bg-rose-100" },
+  educativos: { subtitle: "Aprender jugando", color: "bg-emerald-100" },
+  "accion-y-aventura": { subtitle: "Para explorar sin límites", color: "bg-orange-100" },
+  variedades: { subtitle: "Un poco de todo", color: "bg-violet-100" },
+};
+
+const defaultTile: TileContent = { subtitle: "Explora esta categoría", color: "bg-slate-100" };
+
+// Tile individual reutilizado tanto por la seccion de mundos del home
+// como por el grid del catalogo (tiles promocionales intercalados,
+// ADR 0005 seccion 3, patron Walmart) -- mismo primitivo visual, no un
+// componente nuevo.
+export function PromoTile({ category, className = "" }: { category: Category; className?: string }) {
+  const content = tileContent[category.handle] ?? defaultTile;
+
+  return (
+    <Link
+      href={`/catalog?category=${encodeURIComponent(category.name)}`}
+      className={cn(`group relative min-h-64 overflow-hidden rounded-[2rem] ${content.color} shadow-sm ring-1 ring-slate-900/5`, className)}
+    >
+      {/* Patron Walmart: foto recortada (object-cover) llenando casi toda
+          la tarjeta, con solo un margen delgado del pastel como marco --
+          no flotando chica con espacio muerto alrededor (object-contain,
+          intento anterior, reportado como "no aprovecha el espacio"), ni
+          a pantalla completa sin marco (el intento antes de ese). */}
+      {content.image && (
+        <div className="absolute inset-3 bottom-24 overflow-hidden rounded-2xl">
+          <Image src={content.image} alt="" fill sizes="(max-width: 640px) 45vw, (max-width: 1024px) 25vw, 14vw" className="object-cover transition duration-500 group-hover:scale-105" />
+        </div>
+      )}
+      <div className="absolute inset-x-0 bottom-0 flex items-end justify-between p-6 text-slate-900">
+        <div>
+          <h3 className="text-xl font-black">{category.name}</h3>
+          <p className="mt-1 text-sm font-semibold text-slate-600">{content.subtitle}</p>
+        </div>
+        <span className="grid size-11 shrink-0 place-items-center rounded-full bg-ari-marino text-white transition group-hover:rotate-45">
+          <ArrowUpRight />
+        </span>
+      </div>
+    </Link>
+  );
+}
+
+export function CategoryTiles({ categories }: { categories: Category[] }) {
+  const roots = categories.filter((category) => !category.parentId);
+
+  if (roots.length === 0) return null;
+
+  return (
+    <section className="mx-auto max-w-7xl px-4 py-14">
+      <div className="mb-8 flex items-end justify-between gap-4">
+        <div>
+          <span className="text-xs font-black uppercase tracking-[.18em] text-ari-coral">Explora por mundos</span>
+          <h2 className="mt-2 text-4xl font-black tracking-tight sm:text-5xl">Encuentra tu próximo tesoro</h2>
+        </div>
+        <Link href="/catalog" className="hidden font-black text-ari-marino sm:block">Ver todo →</Link>
+      </div>
+      <div className="grid gap-5 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-6">
+        {roots.map((category) => (
+          <PromoTile key={category.id} category={category} />
+        ))}
+      </div>
+    </section>
+  );
 }

workloads/ecommerce/components/home/hero-bento.tsx

@@ -1,42 +0,0 @@
-"use client";
-
-import Image from "next/image";
-import Link from "next/link";
-import { ArrowRight, BadgePercent, Sparkles } from "lucide-react";
-import { motion, useReducedMotion } from "motion/react";
-import { Button } from "@/components/ui/button";
-
-export function HeroBento() {
-  const reduceMotion = useReducedMotion();
-  const initial = reduceMotion ? false : { opacity: 0, y: 20 };
-
-  return (
-    <section className="mx-auto max-w-7xl px-4 py-7 lg:py-10">
-      <div className="grid gap-5 lg:grid-cols-[1.55fr_.8fr]">
-        <motion.article initial={initial} animate={{ opacity: 1, y: 0 }} className="grid min-h-[470px] overflow-hidden rounded-[2rem] bg-fuchsia-500 text-white shadow-2xl lg:min-h-[560px] lg:grid-cols-[.82fr_1.18fr]">
-          <div className="relative z-10 flex flex-col justify-center bg-gradient-to-br from-fuchsia-600 via-pink-500 to-rose-500 p-7 lg:p-11">
-            <div className="mb-5 inline-flex w-fit items-center gap-2 rounded-full bg-yellow-300 px-4 py-2 text-xs font-black uppercase tracking-wider text-slate-950"><Sparkles className="size-4" />Celebración ARI</div>
-            <h1 className="text-5xl font-black leading-[.92] tracking-[-.06em] sm:text-6xl lg:text-7xl"><span className="block">Hasta</span><span className="text-yellow-300">50% OFF</span><span className="mt-3 block text-3xl tracking-tight sm:text-4xl">en tesoros seleccionados</span></h1>
-            <p className="mt-6 max-w-md text-base font-semibold text-white/95 sm:text-lg">Personajes, mochilas y regalos que convierten cualquier día en una celebración.</p>
-            <Button asChild variant="yellow" size="lg" className="mt-8 w-fit"><Link href="/catalog">Comprar ahora <ArrowRight className="size-5" /></Link></Button>
-          </div>
-          <div className="relative min-h-[360px] bg-white lg:min-h-full">
-            <Image src="/images/promo/hero-vibrant.webp" alt="Promoción principal de Ari Shopping" fill priority sizes="(max-width: 1024px) 100vw, 42vw" className="object-cover object-center" />
-          </div>
-        </motion.article>
-
-        <div className="grid gap-5 sm:grid-cols-2 lg:grid-cols-1">
-          <motion.article initial={reduceMotion ? false : { opacity: 0, x: 18 }} animate={{ opacity: 1, x: 0 }} transition={{ delay: .08 }} className="grid min-h-60 overflow-hidden rounded-[2rem] bg-red-600 text-white shadow-xl sm:grid-cols-[.9fr_1.1fr] lg:min-h-0">
-            <div className="relative z-10 flex flex-col justify-center bg-gradient-to-br from-red-600 to-rose-700 p-6"><span className="text-xs font-black uppercase tracking-wider text-yellow-300">Héroes favoritos</span><h2 className="mt-2 text-3xl font-black leading-none">Acción y aventura</h2><Button asChild variant="yellow" size="sm" className="mt-5 w-fit"><Link href="/catalog?collection=Marvel">Comprar ahora</Link></Button></div>
-            <div className="relative min-h-56 bg-white"><Image src="/images/promo/promo-marvel.webp" alt="Colección Marvel" fill sizes="(max-width: 1024px) 50vw, 18vw" className="object-cover object-center" /></div>
-          </motion.article>
-
-          <motion.article initial={reduceMotion ? false : { opacity: 0, x: 18 }} animate={{ opacity: 1, x: 0 }} transition={{ delay: .14 }} className="grid min-h-60 overflow-hidden rounded-[2rem] bg-violet-600 text-white shadow-xl sm:grid-cols-[.9fr_1.1fr] lg:min-h-0">
-            <div className="relative z-10 flex flex-col justify-center bg-gradient-to-br from-violet-600 to-cyan-600 p-6"><div className="inline-flex w-fit items-center gap-1 rounded-full bg-white px-3 py-1 text-xs font-black text-fuchsia-600"><BadgePercent className="size-4" />Novedad</div><h2 className="mt-3 text-3xl font-black leading-none">Tesoros para regalar</h2><Button asChild variant="outline" size="sm" className="mt-5 w-fit border-white bg-white"><Link href="/catalog">Descubrir</Link></Button></div>
-            <div className="relative min-h-56 bg-white"><Image src="/images/promo/promo-characters.webp" alt="Personajes y peluches" fill sizes="(max-width: 1024px) 50vw, 18vw" className="object-cover object-center" /></div>
-          </motion.article>
-        </div>
-      </div>
-    </section>
-  );
-}

workloads/ecommerce/components/home/hero-carousel.tsx

@@ -0,0 +1,114 @@
+"use client";
+
+import Image from "next/image";
+import Link from "next/link";
+import { ArrowRight, BadgePercent, Sparkles } from "lucide-react";
+import { AnimatePresence, motion, useReducedMotion } from "motion/react";
+import { useEffect, useState } from "react";
+import { Button } from "@/components/ui/button";
+
+// ADR 0008 sub-fase 4: hero azul con dots de paginacion (carrusel), en vez
+// del bento estatico de 3 tarjetas en fucsia/rojo/violeta del esquema
+// arcoiris original. Un slide a la vez, fondo azul de marca en los tres,
+// para leerse como una sola pieza de marca en vez de 3 bloques de colores
+// distintos.
+const slides = [
+  {
+    id: "celebracion",
+    badge: "Celebración ARI",
+    icon: Sparkles,
+    title: "Hasta 50% OFF",
+    subtitle: "en tesoros seleccionados",
+    description: "Personajes, mochilas y regalos que convierten cualquier día en una celebración.",
+    href: "/catalog",
+    image: "/images/promo/hero-vibrant.webp",
+    imageAlt: "Promoción principal de Ari Shopping",
+  },
+  {
+    id: "marvel",
+    badge: "Héroes favoritos",
+    icon: BadgePercent,
+    title: "Acción y aventura",
+    subtitle: "colección Marvel",
+    description: "Figuras, mochilas y sets listos para la próxima misión.",
+    href: "/catalog?collection=Marvel",
+    image: "/images/promo/promo-marvel.webp",
+    imageAlt: "Colección Marvel",
+  },
+  {
+    id: "regalos",
+    badge: "Novedad",
+    icon: Sparkles,
+    title: "Tesoros para regalar",
+    subtitle: "",
+    description: "Personajes y peluches para sorprender en cualquier ocasión.",
+    href: "/catalog",
+    image: "/images/promo/promo-characters.webp",
+    imageAlt: "Personajes y peluches",
+  },
+];
+
+const AUTOPLAY_MS = 6000;
+
+export function HeroCarousel() {
+  const reduceMotion = useReducedMotion();
+  const [index, setIndex] = useState(0);
+
+  useEffect(() => {
+    if (reduceMotion) return;
+    const timer = setInterval(() => setIndex((current) => (current + 1) % slides.length), AUTOPLAY_MS);
+    return () => clearInterval(timer);
+  }, [reduceMotion]);
+
+  const slide = slides[index];
+  if (!slide) return null;
+  const Icon = slide.icon;
+
+  return (
+    <section className="mx-auto max-w-7xl px-4 py-7 lg:py-10">
+      <div className="relative overflow-hidden rounded-[2rem] bg-ari-marino text-white shadow-2xl">
+        <AnimatePresence mode="wait">
+          <motion.article
+            key={slide.id}
+            initial={reduceMotion ? false : { opacity: 0 }}
+            animate={{ opacity: 1 }}
+            exit={reduceMotion ? undefined : { opacity: 0 }}
+            transition={{ duration: 0.4 }}
+            className="grid min-h-[420px] lg:min-h-[500px] lg:grid-cols-2"
+          >
+            <div className="relative z-10 flex flex-col justify-center p-7 lg:p-14">
+              <div className="mb-5 inline-flex w-fit items-center gap-2 rounded-full bg-ari-coral-claro px-4 py-2 text-xs font-black uppercase tracking-wider text-ari-marino">
+                <Icon className="size-4" />
+                {slide.badge}
+              </div>
+              <h1 className="text-5xl font-black leading-[.95] tracking-[-.04em] sm:text-6xl">{slide.title}</h1>
+              {slide.subtitle && <p className="mt-2 text-2xl font-bold text-ari-coral-claro">{slide.subtitle}</p>}
+              <p className="mt-6 max-w-md text-base font-semibold text-white/90 sm:text-lg">{slide.description}</p>
+              <Button asChild variant="yellow" size="lg" className="mt-8 w-fit">
+                <Link href={slide.href}>
+                  Comprar ahora <ArrowRight className="size-5" />
+                </Link>
+              </Button>
+            </div>
+            <div className="relative min-h-[280px] bg-white lg:min-h-full">
+              <Image src={slide.image} alt={slide.imageAlt} fill priority={index === 0} sizes="(max-width: 1024px) 100vw, 50vw" className="object-cover object-center" />
+            </div>
+          </motion.article>
+        </AnimatePresence>
+
+        <div className="absolute inset-x-0 bottom-5 z-20 flex justify-center gap-2">
+          {slides.map((item, itemIndex) => (
+            <button
+              key={item.id}
+              type="button"
+              aria-label={`Ir a la diapositiva ${itemIndex + 1}: ${item.badge}`}
+              aria-current={itemIndex === index ? "true" : undefined}
+              onClick={() => setIndex(itemIndex)}
+              className={`h-2.5 rounded-full transition-all ${itemIndex === index ? "w-7 bg-ari-coral-claro" : "w-2.5 bg-white/50 hover:bg-white/80"}`}
+            />
+          ))}
+        </div>
+      </div>
+    </section>
+  );
+}

workloads/ecommerce/components/layout/footer.tsx

@@ -1,11 +1,10 @@
-import Image from "next/image";
 import Link from "next/link";
 import { Facebook, Instagram, MessageCircle } from "lucide-react";
 
 export function Footer() {
-  return <footer className="bg-slate-950 text-white"><div className="mx-auto grid max-w-7xl gap-10 px-4 py-14 sm:grid-cols-2 lg:grid-cols-4"><div><div className="flex items-center gap-4"><div className="relative size-16 overflow-hidden rounded-full"><Image src="/images/brand/logo-ari.png" alt="ARI Shopping" fill sizes="64px" className="object-cover" /></div><div><strong className="text-xl font-black">ARI Shopping</strong><p className="text-xs text-white/60">Tesoros para cada aventura.</p></div></div><div className="mt-5 flex gap-3"><Instagram /><Facebook /><MessageCircle /></div></div><FooterColumn title="Compra" links={["Novedades", "Juguetes", "Mochilas", "Regalos"]} /><FooterColumn title="Ayuda" links={["Preguntas frecuentes", "Envíos", "Cambios", "Contacto"]} /><div><h3 className="font-black">Newsletter</h3><p className="mt-3 text-sm leading-6 text-white/60">Recibe lanzamientos y promociones especiales.</p><div className="mt-4 flex rounded-full bg-white p-1"><input className="min-w-0 flex-1 bg-transparent px-4 text-sm text-slate-950 outline-none" placeholder="Tu correo" /><button className="rounded-full bg-yellow-300 px-4 text-sm font-black text-slate-950">Unirme</button></div></div></div><div className="border-t border-white/10 py-5 text-center text-xs text-white/50">© 2026 ARI Shopping · Frontend headless v4.1 · GitOps</div></footer>;
+  return <footer className="bg-ari-marino text-white"><div className="mx-auto grid max-w-7xl gap-10 px-4 py-14 sm:grid-cols-2 lg:grid-cols-4"><div><div className="flex flex-col items-start gap-3"><img src="/images/brand/logo-ari.svg" alt="ARI shopping" className="h-11 w-auto" width={200} height={64} />{/* eslint-disable-line @next/next/no-img-element -- vector propio, next/image no optimiza SVG sin habilitar dangerouslyAllowSVG */}<p className="text-xs text-white/60">Tesoros para cada aventura.</p></div><div className="mt-5 flex gap-3"><Instagram /><Facebook /><MessageCircle /></div></div><FooterColumn title="Compra" links={["Novedades", "Juguetes", "Mochilas", "Regalos"]} /><FooterColumn title="Ayuda" links={["Preguntas frecuentes", "Envíos", "Cambios", "Contacto"]} /><div><h3 className="font-black">Newsletter</h3><p className="mt-3 text-sm leading-6 text-white/60">Recibe lanzamientos y promociones especiales.</p><div className="mt-4 flex rounded-full bg-white p-1"><input className="min-w-0 flex-1 bg-transparent px-4 text-sm text-slate-950 outline-none" placeholder="Tu correo" /><button className="rounded-full bg-ari-coral px-4 text-sm font-black text-white">Unirme</button></div></div></div><div className="border-t border-white/10 py-5 text-center text-xs text-white/50">© 2026 ARI Shopping · Frontend headless v4.1 · GitOps</div></footer>;
 }
 
 function FooterColumn({ title, links }: { title: string; links: string[] }) {
-  return <div><h3 className="font-black">{title}</h3><div className="mt-4 grid gap-3 text-sm text-white/60">{links.map((link) => <Link key={link} href="/catalog" className="hover:text-yellow-300">{link}</Link>)}</div></div>;
+  return <div><h3 className="font-black">{title}</h3><div className="mt-4 grid gap-3 text-sm text-white/60">{links.map((link) => <Link key={link} href="/catalog" className="hover:text-ari-coral-claro">{link}</Link>)}</div></div>;
 }

workloads/ecommerce/components/layout/navbar.tsx

@@ -1,44 +1,29 @@
 "use client";
 
-import Image from "next/image";
 import Link from "next/link";
 import { usePathname, useSearchParams } from "next/navigation";
-import { Heart, Menu, MessageCircle, PackageCheck, ShoppingCart, UserRound } from "lucide-react";
-import { Suspense, useState } from "react";
+import { ChevronDown, Heart, LayoutGrid, Menu, MessageCircle, PackageCheck, ShoppingCart, UserRound } from "lucide-react";
+import { Suspense, useEffect, useMemo, useRef, useState } from "react";
 import { PredictiveSearch } from "@/components/search/predictive-search";
 import { Button } from "@/components/ui/button";
 import { Dialog, DialogContent } from "@/components/ui/dialog";
 import { Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle } from "@/components/ui/sheet";
-import type { Product } from "@/lib/headless/types";
+import type { Category, Product } from "@/lib/headless/types";
 import { useCartStore } from "@/store/cart-store";
 import { useWishlistStore } from "@/store/wishlist-store";
 
-type CategoryLink = {
-  label: string;
-  href: string;
-  category?: string;
-  collection?: string;
-  section?: string;
-  root?: boolean;
-};
+type CategoryNode = Category & { children: Category[] };
 
-const categories: CategoryLink[] = [
-  { label: "Juguetes para bebés", href: "/catalog?category=Figuras", category: "Figuras" },
-  {
-    label: "Educativos",
-    href: "/catalog?category=Figuras&section=educativos",
-    category: "Figuras",
-    section: "educativos",
-  },
-  { label: "Muñecas y peluches", href: "/catalog?category=Peluches", category: "Peluches" },
-  { label: "Acción y aventura", href: "/catalog?collection=Marvel", collection: "Marvel" },
-  { label: "Mochilas", href: "/catalog?category=Mochilas", category: "Mochilas" },
-  { label: "Variedades", href: "/catalog", root: true },
-];
+function buildCategoryTree(categories: Category[]): CategoryNode[] {
+  return categories
+    .filter((category) => !category.parentId)
+    .map((root) => ({
+      ...root,
+      children: categories.filter((category) => category.parentId === root.id),
+    }));
+}
 
-const collections = ["Toy Story", "Marvel", "Intensamente", "Lilo & Stitch", "Frozen"];
-
-export function Navbar({ products }: { products: Product[] }) {
+export function Navbar({ products, categories }: { products: Product[]; categories: Category[] }) {
   const [menuOpen, setMenuOpen] = useState(false);
   const [accountOpen, setAccountOpen] = useState(false);
   const items = useCartStore((state) => state.items);
@@ -50,35 +35,48 @@ export function Navbar({ products }: { products: Product[] }) {
   const count = cartHydrated ? items.reduce((sum, item) => sum + item.quantity, 0) : 0;
   const wishlistCount = wishlistHydrated ? wishlistProducts.length : 0;
 
+  const tree = useMemo(() => buildCategoryTree(categories), [categories]);
+  // Derivado de los productos reales (no de un endpoint de colecciones):
+  // solo aparecen colecciones que de verdad tienen productos hoy.
+  const collections = useMemo(
+    () => [...new Set(products.map((product) => product.collection).filter(Boolean))],
+    [products],
+  );
+
   return (
     <header className="sticky top-0 z-40 border-b border-slate-200/80 bg-white/95 shadow-sm backdrop-blur-xl">
-      <div className="bg-gradient-to-r from-amber-300 via-yellow-200 to-lime-200 px-4 py-2 text-center text-xs font-black text-slate-950 sm:text-sm">
-        Paga tus compras a cuotas · Envíos nacionales · <span className="underline decoration-2 underline-offset-2">Compra segura con ARI</span>
+      <div className="bg-ari-marino px-4 py-2 text-center text-xs font-black text-white sm:text-sm">
+        Paga tus compras a cuotas · Envíos nacionales · <span className="underline decoration-ari-coral-claro decoration-2 underline-offset-2">Compra segura con ARI</span>
       </div>
 
       <div className="relative overflow-visible bg-white">
-        <div className="pointer-events-none absolute inset-x-0 top-0 h-1 bg-gradient-to-r from-cyan-400 via-violet-500 to-fuchsia-500" />
-        <div className="mx-auto grid max-w-7xl grid-cols-[72px_1fr_auto] items-center gap-4 px-4 py-4 lg:grid-cols-[92px_minmax(420px,1fr)_auto] lg:gap-8">
-          <Link href="/" className="relative size-16 overflow-hidden rounded-full border-2 border-slate-900 bg-black shadow-lg lg:size-20">
-            <Image src="/images/brand/logo-ari.png" alt="ARI Shopping" fill priority sizes="80px" className="object-cover" />
+        <div className="pointer-events-none absolute inset-x-0 top-0 h-1 bg-ari-coral-claro" />
+        <div className="mx-auto grid max-w-7xl grid-cols-[auto_1fr_auto] items-center gap-4 px-4 py-4 lg:gap-8">
+          {/* Isotipo circular con icono + wordmark integrados (como en la
+              version previa a ADR 0008), pedido explicito del usuario en
+              vez del lockup rectangular. logo-ari.svg (rectangular) se
+              mantiene para el footer. */}
+          <Link href="/" aria-label="ARI shopping" className="shrink-0">
+            {/* eslint-disable-next-line @next/next/no-img-element -- vector propio, next/image no optimiza SVG sin habilitar dangerouslyAllowSVG */}
+            <img src="/images/brand/logo-ari-circular.svg" alt="ARI shopping" className="size-16 lg:size-20" width={200} height={200} />
           </Link>
-          <PredictiveSearch products={products} />
+          <PredictiveSearch />
           <div className="flex items-center gap-2">
-            <Button variant="outline" size="icon" aria-label="Mi cuenta" className="hidden border-slate-300 bg-white text-slate-900 hover:border-violet-400 hover:bg-violet-50 sm:inline-flex" onClick={() => setAccountOpen(true)}><UserRound /></Button>
-            <Button variant="outline" size="icon" aria-label={`Favoritos: ${wishlistCount}`} className="relative hidden border-slate-300 bg-white text-slate-900 hover:border-fuchsia-400 hover:bg-fuchsia-50 sm:inline-flex" onClick={openWishlist}>
+            <Button variant="outline" size="icon" aria-label="Mi cuenta" className="hidden border-slate-300 bg-white text-slate-900 hover:border-ari-coral hover:bg-ari-coral/10 sm:inline-flex" onClick={() => setAccountOpen(true)}><UserRound /></Button>
+            <Button variant="outline" size="icon" aria-label={`Favoritos: ${wishlistCount}`} className="relative hidden border-slate-300 bg-white text-slate-900 hover:border-ari-coral hover:bg-ari-coral/10 sm:inline-flex" onClick={openWishlist}>
               <Heart />
-              {wishlistCount > 0 && <span className="absolute -right-1.5 -top-1.5 grid size-5 place-items-center rounded-full bg-violet-600 text-[10px] font-black text-white">{wishlistCount}</span>}
+              {wishlistCount > 0 && <span className="absolute -right-1.5 -top-1.5 grid size-5 place-items-center rounded-full bg-ari-marino text-[10px] font-black text-white">{wishlistCount}</span>}
             </Button>
-            <Button variant="magenta" size="icon" onClick={openCart} aria-label={`Carrito con ${count} productos`} className="relative shadow-lg shadow-fuchsia-500/20">
+            <Button variant="primary" size="icon" onClick={openCart} aria-label={`Carrito con ${count} productos`} className="relative">
               <ShoppingCart />
-              <span className="absolute -right-2 -top-2 grid size-6 place-items-center rounded-full bg-yellow-300 text-[11px] font-black text-slate-950">{count}</span>
+              <span className="absolute -right-2 -top-2 grid size-6 place-items-center rounded-full bg-ari-marino text-[11px] font-black text-white">{count}</span>
             </Button>
           </div>
         </div>
       </div>
 
-      <Suspense fallback={<DesktopCategoryNavigationFallback onOpenMenu={() => setMenuOpen(true)} />}>
-        <DesktopCategoryNavigation onOpenMenu={() => setMenuOpen(true)} />
+      <Suspense fallback={<DesktopCategoryNavigationFallback tree={tree} onOpenMenu={() => setMenuOpen(true)} />}>
+        <DesktopCategoryNavigation tree={tree} onOpenMenu={() => setMenuOpen(true)} />
       </Suspense>
 
       <Sheet open={menuOpen} onOpenChange={setMenuOpen}>
@@ -88,16 +86,20 @@ export function Navbar({ products }: { products: Product[] }) {
             <SheetDescription>Categorías y colecciones del catálogo.</SheetDescription>
           </SheetHeader>
           <div className="flex-1 overflow-y-auto p-6">
-            <p className="mb-3 text-xs font-black uppercase tracking-[.16em] text-fuchsia-600">Categorías</p>
+            <p className="mb-3 text-xs font-black uppercase tracking-[.16em] text-ari-coral">Categorías</p>
             <div className="grid gap-2">
-              <Suspense fallback={<MobileCategoryLinksFallback onNavigate={() => setMenuOpen(false)} />}>
-                <MobileCategoryLinks onNavigate={() => setMenuOpen(false)} />
+              <Suspense fallback={<MobileCategoryLinksFallback tree={tree} onNavigate={() => setMenuOpen(false)} />}>
+                <MobileCategoryLinks tree={tree} onNavigate={() => setMenuOpen(false)} />
               </Suspense>
             </div>
-            <p className="mb-3 mt-8 text-xs font-black uppercase tracking-[.16em] text-violet-600">Colecciones</p>
-            <div className="flex flex-wrap gap-2">
-              {collections.map((collection) => <Link key={collection} href={`/catalog?collection=${encodeURIComponent(collection)}`} onClick={() => setMenuOpen(false)} className="rounded-full bg-slate-100 px-4 py-2 text-sm font-bold hover:bg-violet-100 hover:text-violet-700">{collection}</Link>)}
-            </div>
+            {collections.length > 0 && (
+              <>
+                <p className="mb-3 mt-8 text-xs font-black uppercase tracking-[.16em] text-ari-marino">Colecciones</p>
+                <div className="flex flex-wrap gap-2">
+                  {collections.map((collection) => <Link key={collection} href={`/catalog?collection=${encodeURIComponent(collection)}`} onClick={() => setMenuOpen(false)} className="rounded-full bg-slate-100 px-4 py-2 text-sm font-bold hover:bg-ari-coral/10 hover:text-ari-coral">{collection}</Link>)}
+                </div>
+              </>
+            )}
             <div className="mt-8 grid grid-cols-2 gap-3 sm:hidden">
               <Button variant="outline" onClick={() => { setMenuOpen(false); setAccountOpen(true); }}><UserRound className="size-4" />Cuenta</Button>
               <Button variant="outline" onClick={() => { setMenuOpen(false); openWishlist(); }}><Heart className="size-4" />Favoritos</Button>
@@ -109,11 +111,11 @@ export function Navbar({ products }: { products: Product[] }) {
       <Dialog open={accountOpen} onOpenChange={setAccountOpen}>
         <DialogContent className="max-w-lg p-7">
           <div className="pr-10">
-            <span className="text-xs font-black uppercase tracking-[.16em] text-violet-600">Atención personalizada</span>
+            <span className="text-xs font-black uppercase tracking-[.16em] text-ari-coral">Atención personalizada</span>
             <h2 className="mt-3 text-3xl font-black">Tu cuenta ARI</h2>
             <p className="mt-3 text-sm leading-6 text-slate-600">El inicio de sesión quedará conectado al backend headless. Mientras tanto, puedes gestionar pedidos y disponibilidad directamente por WhatsApp.</p>
             <div className="mt-6 grid gap-3">
-              <Button asChild variant="magenta" size="lg"><a href={process.env.NEXT_PUBLIC_WHATSAPP_URL ?? "https://wa.link/rvcqqc"} target="_blank" rel="noopener noreferrer"><MessageCircle />Hablar con ARI</a></Button>
+              <Button asChild variant="primary" size="lg"><a href={process.env.NEXT_PUBLIC_WHATSAPP_URL ?? "https://wa.link/rvcqqc"} target="_blank" rel="noopener noreferrer"><MessageCircle />Hablar con ARI</a></Button>
               <Button asChild variant="outline"><Link href="/catalog" onClick={() => setAccountOpen(false)}><PackageCheck />Ver mis opciones de compra</Link></Button>
             </div>
           </div>
@@ -127,140 +129,218 @@ function useCategoryNavigationState() {
   const pathname = usePathname();
   const searchParams = useSearchParams();
   const currentCategory = searchParams.get("category") ?? "";
-  const currentCollection = searchParams.get("collection") ?? "";
-  const currentSection = searchParams.get("section") ?? "";
   const isCatalog = pathname === "/catalog";
 
-  const isCategoryActive = (item: CategoryLink) => {
-    if (!isCatalog) return false;
-
-    if (item.root) {
-      return !currentCategory && !currentCollection && !currentSection;
-    }
-
-    return (
-      (item.category ?? "") === currentCategory &&
-      (item.collection ?? "") === currentCollection &&
-      (item.section ?? "") === currentSection
-    );
+  return {
+    isAllActive: isCatalog && !currentCategory,
+    isActive: (name: string) => isCatalog && currentCategory === name,
   };
-
-  return { isCategoryActive };
 }
 
-function DesktopCategoryNavigation({ onOpenMenu }: { onOpenMenu: () => void }) {
-  const { isCategoryActive } = useCategoryNavigationState();
+function pillClass(active: boolean): string {
+  return `shrink-0 rounded-full px-4 py-2 text-sm font-extrabold transition ${
+    active
+      ? "bg-white text-ari-marino shadow-lg shadow-black/10"
+      : "text-white/90 hover:bg-white/10 hover:text-white"
+  }`;
+}
 
+function mobileLinkClass(active: boolean): string {
+  return `rounded-2xl border px-4 py-3 font-extrabold transition ${
+    active
+      ? "border-ari-coral bg-ari-coral/5 text-ari-coral"
+      : "border-slate-200 hover:border-ari-coral/50 hover:bg-ari-coral/5"
+  }`;
+}
+
+function DesktopCategoryNavigation({ tree, onOpenMenu }: { tree: CategoryNode[]; onOpenMenu: () => void }) {
+  const { isActive, isAllActive } = useCategoryNavigationState();
+  return <CategoryNavBar tree={tree} onOpenMenu={onOpenMenu} isActive={isActive} isAllActive={isAllActive} />;
+}
+
+function DesktopCategoryNavigationFallback({ tree, onOpenMenu }: { tree: CategoryNode[]; onOpenMenu: () => void }) {
+  return <CategoryNavBar tree={tree} onOpenMenu={onOpenMenu} isActive={() => false} isAllActive={false} />;
+}
+
+function CategoryNavBar({
+  tree,
+  onOpenMenu,
+  isActive,
+  isAllActive,
+}: {
+  tree: CategoryNode[];
+  onOpenMenu: () => void;
+  isActive: (name: string) => boolean;
+  isAllActive: boolean;
+}) {
   return (
-    <nav className="border-b-4 border-fuchsia-500 bg-slate-950 text-white">
-      <div className="mx-auto flex max-w-7xl items-center gap-1 overflow-x-auto px-4 py-2 [scrollbar-width:none]">
+    <nav className="bg-ari-marino text-white">
+      <div className="relative mx-auto flex max-w-7xl items-center gap-1 px-4 py-2">
         <Button
           variant="ghost"
           size="icon"
           onClick={onOpenMenu}
           aria-label="Abrir menú principal"
-          className="mr-3 shrink-0 text-white hover:bg-white/10"
+          className="mr-2 shrink-0 text-white hover:bg-white/10"
         >
           <Menu />
         </Button>
 
-        {categories.map((category) => {
-          const active = isCategoryActive(category);
+        <DepartmentsMegaMenu tree={tree} isActive={isActive} />
 
-          return (
-            <Link
-              key={category.label}
-              href={category.href}
-              prefetch={false}
-              aria-current={active ? "page" : undefined}
-              className={`shrink-0 rounded-full px-4 py-2 text-sm font-extrabold transition ${
-                active
-                  ? "bg-gradient-to-r from-cyan-500 to-violet-500 text-white shadow-lg shadow-violet-950/30"
-                  : "text-white/90 hover:bg-gradient-to-r hover:from-cyan-500 hover:to-violet-500 hover:text-white"
-              }`}
-            >
-              {category.label}
-            </Link>
-          );
-        })}
-      </div>
-    </nav>
-  );
-}
-
-function DesktopCategoryNavigationFallback({ onOpenMenu }: { onOpenMenu: () => void }) {
-  return (
-    <nav className="border-b-4 border-fuchsia-500 bg-slate-950 text-white">
-      <div className="mx-auto flex max-w-7xl items-center gap-1 overflow-x-auto px-4 py-2 [scrollbar-width:none]">
-        <Button
-          variant="ghost"
-          size="icon"
-          onClick={onOpenMenu}
-          aria-label="Abrir menú principal"
-          className="mr-3 shrink-0 text-white hover:bg-white/10"
-        >
-          <Menu />
-        </Button>
-
-        {categories.map((category) => (
-          <Link
-            key={category.label}
-            href={category.href}
-            prefetch={false}
-            className="shrink-0 rounded-full px-4 py-2 text-sm font-extrabold text-white/90 transition hover:bg-gradient-to-r hover:from-cyan-500 hover:to-violet-500 hover:text-white"
-          >
-            {category.label}
-          </Link>
-        ))}
-      </div>
-    </nav>
-  );
-}
-
-function MobileCategoryLinks({ onNavigate }: { onNavigate: () => void }) {
-  const { isCategoryActive } = useCategoryNavigationState();
-
-  return (
-    <>
-      {categories.map((category) => {
-        const active = isCategoryActive(category);
-
-        return (
-          <Link
-            key={category.label}
-            href={category.href}
-            prefetch={false}
-            aria-current={active ? "page" : undefined}
-            onClick={onNavigate}
-            className={`rounded-2xl border px-4 py-3 font-extrabold transition ${
-              active
-                ? "border-violet-500 bg-violet-50 text-violet-700"
-                : "border-slate-200 hover:border-cyan-400 hover:bg-cyan-50"
-            }`}
-          >
-            {category.label}
-          </Link>
-        );
-      })}
-    </>
-  );
-}
-
-function MobileCategoryLinksFallback({ onNavigate }: { onNavigate: () => void }) {
-  return (
-    <>
-      {categories.map((category) => (
-        <Link
-          key={category.label}
-          href={category.href}
-          prefetch={false}
-          onClick={onNavigate}
-          className="rounded-2xl border border-slate-200 px-4 py-3 font-extrabold transition hover:border-cyan-400 hover:bg-cyan-50"
-        >
-          {category.label}
+        <Link href="/catalog" prefetch={false} aria-current={isAllActive ? "page" : undefined} className={pillClass(isAllActive)}>
+          Todo
         </Link>
+      </div>
+    </nav>
+  );
+}
+
+function DepartmentsMegaMenu({ tree, isActive }: { tree: CategoryNode[]; isActive: (name: string) => boolean }) {
+  const [open, setOpen] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!open) return;
+    function handlePointerDown(event: PointerEvent) {
+      if (containerRef.current && !containerRef.current.contains(event.target as Node)) setOpen(false);
+    }
+    function handleKeyDown(event: KeyboardEvent) {
+      if (event.key === "Escape") setOpen(false);
+    }
+    document.addEventListener("pointerdown", handlePointerDown);
+    document.addEventListener("keydown", handleKeyDown);
+    return () => {
+      document.removeEventListener("pointerdown", handlePointerDown);
+      document.removeEventListener("keydown", handleKeyDown);
+    };
+  }, [open]);
+
+  return (
+    <div ref={containerRef} className="shrink-0" onMouseEnter={() => setOpen(true)} onMouseLeave={() => setOpen(false)}>
+      <button
+        type="button"
+        onClick={() => setOpen((value) => !value)}
+        aria-expanded={open}
+        aria-haspopup="true"
+        className={`flex items-center gap-1.5 ${pillClass(open)}`}
+      >
+        <LayoutGrid className="size-4" />
+        Departamentos
+        <ChevronDown className={`size-3.5 opacity-70 transition-transform ${open ? "rotate-180" : ""}`} />
+      </button>
+
+      {open && (
+        <div className="absolute left-0 top-full z-50 mt-1 max-h-[80vh] w-[min(92vw,64rem)] overflow-y-auto rounded-2xl border border-white/10 bg-ari-marino p-6 shadow-2xl">
+          <div className="grid grid-cols-2 gap-x-6 gap-y-5 sm:grid-cols-3 lg:grid-cols-6">
+            {tree.map((root) => (
+              <div key={root.id}>
+                <Link
+                  href={`/catalog?category=${encodeURIComponent(root.name)}`}
+                  prefetch={false}
+                  aria-current={isActive(root.name) ? "page" : undefined}
+                  onClick={() => setOpen(false)}
+                  className={`block text-sm font-black uppercase tracking-wide transition ${
+                    isActive(root.name) ? "text-ari-coral-claro" : "text-white hover:text-ari-coral-claro"
+                  }`}
+                >
+                  {root.name}
+                </Link>
+                {root.children.length > 0 && (
+                  <ul className="mt-2.5 grid gap-1.5">
+                    {root.children.map((child) => (
+                      <li key={child.id}>
+                        <Link
+                          href={`/catalog?category=${encodeURIComponent(child.name)}`}
+                          prefetch={false}
+                          aria-current={isActive(child.name) ? "page" : undefined}
+                          onClick={() => setOpen(false)}
+                          className={`block text-sm transition ${isActive(child.name) ? "font-bold text-ari-coral-claro" : "text-white/70 hover:text-white"}`}
+                        >
+                          {child.name}
+                        </Link>
+                      </li>
+                    ))}
+                  </ul>
+                )}
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+function MobileCategoryLinks({ tree, onNavigate }: { tree: CategoryNode[]; onNavigate: () => void }) {
+  const { isActive, isAllActive } = useCategoryNavigationState();
+
+  return (
+    <>
+      <Link
+        href="/catalog"
+        prefetch={false}
+        aria-current={isAllActive ? "page" : undefined}
+        onClick={onNavigate}
+        className={mobileLinkClass(isAllActive)}
+      >
+        Todo el catálogo
+      </Link>
+
+      {tree.map((root) => (
+        <div key={root.id} className="contents">
+          <Link
+            href={`/catalog?category=${encodeURIComponent(root.name)}`}
+            prefetch={false}
+            aria-current={isActive(root.name) ? "page" : undefined}
+            onClick={onNavigate}
+            className={mobileLinkClass(isActive(root.name))}
+          >
+            {root.name}
+          </Link>
+          {root.children.map((child) => (
+            <Link
+              key={child.id}
+              href={`/catalog?category=${encodeURIComponent(child.name)}`}
+              prefetch={false}
+              aria-current={isActive(child.name) ? "page" : undefined}
+              onClick={onNavigate}
+              className={`${mobileLinkClass(isActive(child.name))} ml-4 text-sm`}
+            >
+              {child.name}
+            </Link>
+          ))}
+        </div>
       ))}
     </>
   );
 }
 
+function MobileCategoryLinksFallback({ tree, onNavigate }: { tree: CategoryNode[]; onNavigate: () => void }) {
+  return (
+    <>
+      <Link href="/catalog" prefetch={false} onClick={onNavigate} className={mobileLinkClass(false)}>
+        Todo el catálogo
+      </Link>
+
+      {tree.map((root) => (
+        <div key={root.id} className="contents">
+          <Link href={`/catalog?category=${encodeURIComponent(root.name)}`} prefetch={false} onClick={onNavigate} className={mobileLinkClass(false)}>
+            {root.name}
+          </Link>
+          {root.children.map((child) => (
+            <Link
+              key={child.id}
+              href={`/catalog?category=${encodeURIComponent(child.name)}`}
+              prefetch={false}
+              onClick={onNavigate}
+              className={`${mobileLinkClass(false)} ml-4 text-sm`}
+            >
+              {child.name}
+            </Link>
+          ))}
+        </div>
+      ))}
+    </>
+  );
+}

workloads/ecommerce/components/product/mobile-add-to-cart.tsx

@@ -7,5 +7,5 @@ import { useCartStore } from "@/store/cart-store";
 
 export function MobileAddToCart({ product }: { product: Product }) {
   const addItem = useCartStore((state) => state.addItem);
-  return <div className="fixed inset-x-0 bottom-0 z-40 border-t border-slate-200 bg-white/95 p-3 shadow-2xl backdrop-blur lg:hidden"><Button variant="magenta" size="lg" className="w-full" onClick={() => addItem(product, product.variants[0]?.id)}><ShoppingBag />Añadir al carrito</Button></div>;
+  return <div className="fixed inset-x-0 bottom-0 z-40 border-t border-slate-200 bg-white/95 p-3 shadow-2xl backdrop-blur lg:hidden"><Button variant="primary" size="lg" className="w-full" onClick={() => addItem(product, product.variants[0]?.id)}><ShoppingBag />Añadir al carrito</Button></div>;
 }

workloads/ecommerce/components/product/product-card.tsx

@@ -2,11 +2,12 @@
 
 import Image from "next/image";
 import Link from "next/link";
-import { Heart, ShoppingBag, Sparkles } from "lucide-react";
+import { Heart, ShoppingBag, Sparkles, TriangleAlert } from "lucide-react";
+import { useState } from "react";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
 import type { Product } from "@/lib/headless/types";
-import { formatMoney } from "@/lib/utils";
+import { formatMoney, LOW_STOCK_THRESHOLD } from "@/lib/utils";
 import { useCartStore } from "@/store/cart-store";
 import { useWishlistStore } from "@/store/wishlist-store";
 
@@ -16,19 +17,63 @@ export function ProductCard({ product, priority = false }: { product: Product; p
   const wishlistHydrated = useWishlistStore((state) => state.hasHydrated);
   const toggleProduct = useWishlistStore((state) => state.toggleProduct);
   const isFavorite = wishlistHydrated && wishlistProducts.some((item) => item.id === product.id);
+  const discountPercent =
+    product.compareAtPrice && product.price
+      ? Math.round((1 - product.price / product.compareAtPrice) * 100)
+      : null;
+
+  const [selectedVariantId, setSelectedVariantId] = useState(product.variants[0]?.id);
+  const selectedVariant = product.variants.find((variant) => variant.id === selectedVariantId) ?? product.variants[0];
+  const lowStock =
+    selectedVariant?.inventoryQuantity !== null &&
+    selectedVariant?.inventoryQuantity !== undefined &&
+    selectedVariant.inventoryQuantity > 0 &&
+    selectedVariant.inventoryQuantity <= LOW_STOCK_THRESHOLD
+      ? selectedVariant.inventoryQuantity
+      : null;
 
   return (
-    <article className="group flex h-full flex-col overflow-hidden rounded-3xl border border-slate-100 bg-white shadow-lg shadow-slate-900/5 transition duration-300 hover:-translate-y-1.5 hover:shadow-2xl hover:shadow-violet-500/10">
-      <div className="relative aspect-square overflow-hidden bg-slate-50">
+    <article className="group flex h-full flex-col overflow-hidden rounded-lg border border-slate-100 bg-white shadow-lg shadow-ari-marino/5 transition duration-300 hover:-translate-y-1.5 hover:shadow-2xl hover:shadow-ari-coral/10">
+      <div className="relative aspect-square overflow-hidden bg-white">
         <Link href={`/product/${product.slug}`} prefetch={false}><Image src={product.thumbnail} alt={product.name} fill priority={priority} sizes="(max-width: 640px) 82vw, (max-width: 1024px) 44vw, 280px" className="object-cover transition duration-500 group-hover:scale-[1.035]" /></Link>
-        <div className="absolute left-3 top-3 flex gap-2">{product.isNew && <Badge className="bg-fuchsia-500 text-white">Nuevo</Badge>}{product.featured && <Badge className="bg-yellow-300 text-slate-950"><Sparkles className="mr-1 size-3" />Top</Badge>}</div>
-        <button type="button" aria-label={isFavorite ? "Quitar de favoritos" : "Agregar a favoritos"} aria-pressed={isFavorite} className={`absolute right-3 top-3 rounded-full p-2.5 shadow-lg backdrop-blur transition ${isFavorite ? "bg-fuchsia-500 text-white" : "bg-white/95 text-slate-900 hover:text-fuchsia-500"}`} onClick={() => toggleProduct(product)}><Heart className={`size-4 ${isFavorite ? "fill-current" : ""}`} /></button>
+        <div className="absolute left-3 top-3 flex gap-2">{discountPercent && discountPercent > 0 && <Badge className="bg-ari-coral-claro text-ari-marino">-{discountPercent}%</Badge>}{product.isNew && <Badge className="bg-ari-marino text-white">Nuevo</Badge>}{product.featured && <Badge className="bg-ari-coral-claro text-ari-marino"><Sparkles className="mr-1 size-3" />Top</Badge>}</div>
+        <button type="button" aria-label={isFavorite ? "Quitar de favoritos" : "Agregar a favoritos"} aria-pressed={isFavorite} className={`absolute right-3 top-3 rounded-full p-2.5 shadow-lg backdrop-blur transition ${isFavorite ? "bg-ari-coral text-white" : "bg-white/95 text-slate-900 hover:text-ari-coral"}`} onClick={() => toggleProduct(product)}><Heart className={`size-4 ${isFavorite ? "fill-current" : ""}`} /></button>
       </div>
       <div className="flex flex-1 flex-col space-y-3 p-5">
-        <div className="flex items-center justify-between gap-2 text-xs font-bold text-slate-500"><span>{product.category}</span><span className="rounded-full bg-cyan-50 px-2 py-1 text-cyan-700">{product.collection}</span></div>
-        <Link href={`/product/${product.slug}`} prefetch={false}><h3 className="line-clamp-2 min-h-12 text-lg font-black leading-6 text-slate-950 group-hover:text-fuchsia-600">{product.name}</h3></Link>
+        <div className="flex items-center justify-between gap-2 text-xs font-bold text-slate-500"><span>{product.category}</span><span className="rounded-md bg-ari-coral-claro/10 px-2 py-1 text-ari-marino">{product.collection}</span></div>
+        <Link href={`/product/${product.slug}`} prefetch={false}><h3 className="line-clamp-2 min-h-12 text-lg font-black leading-6 text-ari-marino group-hover:text-ari-coral">{product.name}</h3></Link>
         <p className="line-clamp-2 min-h-10 text-sm leading-5 text-slate-500">{product.shortDescription}</p>
-        <div className="mt-auto flex items-center justify-between gap-3 pt-1"><strong className="text-sm font-black">{formatMoney(product.price, product.currency)}</strong><Button variant="magenta" size="sm" onClick={() => addItem(product, product.variants[0]?.id)}><ShoppingBag className="size-4" />Agregar</Button></div>
+        {product.variants.length > 1 && (
+          <div className="flex flex-wrap gap-1.5">
+            {product.variants.map((variant) => (
+              <button
+                key={variant.id}
+                type="button"
+                disabled={!variant.available}
+                aria-pressed={selectedVariantId === variant.id}
+                aria-label={`${variant.name}: ${variant.value}`}
+                onClick={() => setSelectedVariantId(variant.id)}
+                className={`rounded-md border px-2.5 py-1 text-xs font-bold transition ${
+                  selectedVariantId === variant.id
+                    ? "border-ari-coral bg-ari-coral/10 text-ari-coral"
+                    : "border-slate-200 text-slate-600 hover:border-slate-400"
+                } ${!variant.available ? "cursor-not-allowed opacity-40" : ""}`}
+              >
+                {variant.value}
+              </button>
+            ))}
+          </div>
+        )}
+        {lowStock !== null && (
+          <span className="flex items-center gap-1.5 text-xs font-bold text-amber-600"><TriangleAlert className="size-3.5" />Quedan {lowStock}</span>
+        )}
+        <div className="mt-auto flex items-center justify-between gap-3 pt-1">
+          <div className="flex flex-col">
+            {product.compareAtPrice && <span className="text-xs font-bold text-slate-400 line-through">{formatMoney(product.compareAtPrice, product.currency)}</span>}
+            <strong className="font-display text-base font-bold text-ari-marino">{formatMoney(product.price, product.currency)}</strong>
+          </div>
+          <Button variant="primary" size="sm" onClick={() => addItem(product, selectedVariantId)}><ShoppingBag className="size-4" />Agregar</Button>
+        </div>
       </div>
     </article>
   );

workloads/ecommerce/components/product/product-purchase.tsx

@@ -1,14 +1,22 @@
 "use client";
 
-import { CheckCircle2, ShoppingBag, Truck } from "lucide-react";
+import { CheckCircle2, ShoppingBag, TriangleAlert, Truck } from "lucide-react";
 import { useState } from "react";
 import { Button } from "@/components/ui/button";
 import type { Product } from "@/lib/headless/types";
-import { formatMoney } from "@/lib/utils";
+import { formatMoney, LOW_STOCK_THRESHOLD } from "@/lib/utils";
 import { useCartStore } from "@/store/cart-store";
 
 export function ProductPurchase({ product }: { product: Product }) {
   const [variantId, setVariantId] = useState(product.variants[0]?.id);
   const addItem = useCartStore((state) => state.addItem);
-  return <div><div className="mb-5 flex flex-wrap gap-2">{product.variants.map((variant) => <button key={variant.id} onClick={() => setVariantId(variant.id)} className={`rounded-full border px-4 py-2 text-sm font-bold ${variantId === variant.id ? "border-fuchsia-500 bg-fuchsia-50 text-fuchsia-700" : "border-slate-200"}`}>{variant.value}</button>)}</div><div className="mb-6 flex items-end gap-3"><strong className="text-3xl font-black">{formatMoney(product.price, product.currency)}</strong>{product.compareAtPrice && <del className="text-slate-400">{formatMoney(product.compareAtPrice, product.currency)}</del>}</div><Button variant="magenta" size="lg" className="w-full" onClick={() => addItem(product, variantId)}><ShoppingBag />Añadir al carrito</Button><div className="mt-5 grid gap-3 rounded-2xl bg-slate-50 p-4 text-sm"><span className="flex items-center gap-2 font-bold"><CheckCircle2 className="size-4 text-emerald-500" />Disponibilidad por confirmar</span><span className="flex items-center gap-2 font-bold"><Truck className="size-4 text-cyan-600" />Envíos nacionales</span></div></div>;
+  const selectedVariant = product.variants.find((variant) => variant.id === variantId) ?? product.variants[0];
+  const lowStock =
+    selectedVariant?.inventoryQuantity !== null &&
+    selectedVariant?.inventoryQuantity !== undefined &&
+    selectedVariant.inventoryQuantity > 0 &&
+    selectedVariant.inventoryQuantity <= LOW_STOCK_THRESHOLD
+      ? selectedVariant.inventoryQuantity
+      : null;
+  return <div><div className="mb-5 flex flex-wrap gap-2">{product.variants.map((variant) => <button key={variant.id} onClick={() => setVariantId(variant.id)} className={`rounded-full border px-4 py-2 text-sm font-bold ${variantId === variant.id ? "border-ari-marino bg-ari-marino text-white" : "border-slate-200"}`}>{variant.value}</button>)}</div><div className="mb-6 flex items-end gap-3"><strong className="text-3xl font-black">{formatMoney(product.price, product.currency)}</strong>{product.compareAtPrice && <del className="text-slate-400">{formatMoney(product.compareAtPrice, product.currency)}</del>}</div>{/* oculto en mobile: MobileAddToCart (barra fija abajo, lg:hidden) ya cubre esa misma accion ahi -- sin el hidden aqui, ambos se mostraban a la vez. */}<Button variant="primary" size="lg" className="hidden w-full lg:inline-flex" onClick={() => addItem(product, variantId)}><ShoppingBag />Añadir al carrito</Button><div className="mt-5 grid gap-3 rounded-2xl bg-slate-50 p-4 text-sm">{lowStock !== null ? <span className="flex items-center gap-2 font-bold text-amber-600"><TriangleAlert className="size-4" />Quedan {lowStock} unidades</span> : <span className="flex items-center gap-2 font-bold"><CheckCircle2 className="size-4 text-emerald-500" />Disponibilidad por confirmar</span>}<span className="flex items-center gap-2 font-bold"><Truck className="size-4 text-cyan-600" />Envíos nacionales</span></div></div>;
 }

workloads/ecommerce/components/search/predictive-search.tsx

@@ -4,20 +4,44 @@ import Image from "next/image";
 import Link from "next/link";
 import { useRouter } from "next/navigation";
 import { Search, X } from "lucide-react";
-import { FormEvent, useMemo, useState } from "react";
-import { Input } from "@/components/ui/input";
+import { FormEvent, useEffect, useState } from "react";
 import type { Product } from "@/lib/headless/types";
 
-export function PredictiveSearch({ products }: { products: Product[] }) {
+export function PredictiveSearch() {
   const router = useRouter();
   const [query, setQuery] = useState("");
-  const normalized = query.trim().toLocaleLowerCase("es");
-  const matches = useMemo(
-    () => normalized.length < 2
-      ? []
-      : products.filter((product) => [product.name, product.category, product.collection, product.brand].join(" ").toLocaleLowerCase("es").includes(normalized)).slice(0, 6),
-    [normalized, products],
-  );
+  const [matches, setMatches] = useState<Product[]>([]);
+  const [loading, setLoading] = useState(false);
+  const normalized = query.trim();
+
+  useEffect(() => {
+    if (normalized.length < 2) {
+      setMatches([]);
+      setLoading(false);
+      return;
+    }
+
+    const controller = new AbortController();
+    setLoading(true);
+    const timer = setTimeout(() => {
+      fetch(`/api/search?q=${encodeURIComponent(normalized)}`, {
+        signal: controller.signal,
+      })
+        .then((response) => response.json())
+        .then((data: { products?: Product[] }) => {
+          setMatches((data.products ?? []).slice(0, 6));
+        })
+        .catch((error) => {
+          if ((error as Error).name !== "AbortError") setMatches([]);
+        })
+        .finally(() => setLoading(false));
+    }, 250);
+
+    return () => {
+      clearTimeout(timer);
+      controller.abort();
+    };
+  }, [normalized]);
 
   const submit = (event: FormEvent<HTMLFormElement>) => {
     event.preventDefault();
@@ -29,22 +53,49 @@ export function PredictiveSearch({ products }: { products: Product[] }) {
 
   return (
     <form onSubmit={submit} className="relative w-full">
-      <div className="rounded-full bg-gradient-to-r from-cyan-400 via-violet-500 to-fuchsia-500 p-[2px] shadow-lg shadow-violet-500/10">
-        <div className="relative rounded-full bg-white">
-          <Search className="pointer-events-none absolute left-5 top-1/2 z-10 size-5 -translate-y-1/2 text-violet-600" />
-          <Input value={query} onChange={(event) => setQuery(event.target.value)} placeholder="Busca juguetes, mochilas, personajes…" className="h-[52px] border-0 bg-transparent pl-[52px] pr-12 shadow-none focus-visible:ring-violet-300/30" />
-          {query && <button type="button" aria-label="Limpiar búsqueda" className="absolute right-4 top-1/2 -translate-y-1/2 rounded-full p-1 text-slate-400 hover:bg-slate-100" onClick={() => setQuery("")}><X className="size-4" /></button>}
-        </div>
+      <div className="flex items-center rounded-full border-2 border-slate-200 bg-white pl-5 pr-1.5 shadow-sm transition focus-within:border-ari-marino focus-within:ring-4 focus-within:ring-ari-coral-claro/30">
+        {/* input propio (no el <Input> compartido) -- ese componente trae su
+            propio focus:ring-4 focus:ring-cyan-300/30 hardcodeado que no se
+            anulaba de forma confiable via tailwind-merge dentro de este
+            contenedor compuesto (input + boton circular), causando un
+            segundo ring visible al hacer foco. Mas simple y robusto no
+            heredar clases de foco que hay que pelear despues.
+
+            focus-visible:outline-none (no outline-none a secas): globals.css
+            define un outline de accesibilidad global por teclado
+            (input:focus-visible, azul de marca) que le gana en
+            especificidad a un outline-none plano. El wrapper de este
+            componente ya tiene su propio indicador de foco visible
+            (focus-within:border-ari-marino + ring amarillo, mismo patron
+            que button.tsx) que cumple el mismo proposito de accesibilidad
+            sin duplicarlo -- variante focus-visible: en vez de la base
+            iguala la especificidad de la regla global (mismo truco que ya
+            usa button.tsx) y evita el doble indicador de foco. */}
+        <input
+          value={query}
+          onChange={(event) => setQuery(event.target.value)}
+          placeholder="Busca juguetes, mochilas, personajes…"
+          className="h-[48px] w-full border-0 bg-transparent p-0 text-sm text-slate-950 focus-visible:outline-none"
+        />
+        {query && <button type="button" aria-label="Limpiar búsqueda" className="mr-1 shrink-0 rounded-full p-1.5 text-slate-400 hover:bg-slate-100" onClick={() => setQuery("")}><X className="size-4" /></button>}
+        <button type="submit" aria-label="Buscar" className="grid size-10 shrink-0 place-items-center rounded-full bg-ari-marino text-white transition hover:brightness-110">
+          <Search className="size-4.5" />
+        </button>
       </div>
+      {loading && normalized.length >= 2 && matches.length === 0 && (
+        <div className="absolute left-0 right-0 top-[calc(100%+10px)] z-50 rounded-2xl border border-slate-200 bg-white p-4 text-center text-sm text-slate-500 shadow-2xl">
+          Buscando…
+        </div>
+      )}
       {matches.length > 0 && (
         <div className="absolute left-0 right-0 top-[calc(100%+10px)] z-50 overflow-hidden rounded-2xl border border-slate-200 bg-white p-2 shadow-2xl">
           {matches.map((product) => (
-            <Link key={product.id} href={`/product/${product.slug}`} prefetch={false} className="grid grid-cols-[54px_1fr] items-center gap-3 rounded-xl p-2 hover:bg-violet-50" onClick={() => setQuery("")}>
+            <Link key={product.id} href={`/product/${product.slug}`} prefetch={false} className="grid grid-cols-[54px_1fr] items-center gap-3 rounded-xl p-2 hover:bg-ari-marino/5" onClick={() => setQuery("")}>
               <div className="relative aspect-square overflow-hidden rounded-lg bg-slate-100"><Image src={product.thumbnail} alt="" fill sizes="54px" className="object-cover" /></div>
               <div><strong className="line-clamp-1 text-sm">{product.name}</strong><span className="text-xs text-slate-500">{product.category} · {product.collection}</span></div>
             </Link>
           ))}
-          <button type="submit" className="mt-1 w-full rounded-xl bg-slate-950 px-4 py-3 text-sm font-black text-white hover:bg-violet-700">Buscar “{query.trim()}” en todo el catálogo</button>
+          <button type="submit" className="mt-1 w-full rounded-xl bg-ari-marino px-4 py-3 text-sm font-black text-white hover:brightness-110">Buscar “{query.trim()}” en todo el catálogo</button>
         </div>
       )}
     </form>

workloads/ecommerce/components/ui/button.tsx

@@ -4,14 +4,20 @@ import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "@/lib/utils";
 
 const buttonVariants = cva(
-  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-full text-sm font-extrabold transition-all focus-visible:outline-none focus-visible:ring-4 focus-visible:ring-cyan-300/40 disabled:pointer-events-none disabled:opacity-50",
+  // ADR 0007 (Opcion 2, "Atelier calido"): radio moderado en vez de
+  // rounded-full, ring de foco tintado con el acento de marca en vez de
+  // cyan generico.
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-lg text-sm font-extrabold transition-all focus-visible:outline-none focus-visible:ring-4 focus-visible:ring-ari-cobre/40 disabled:pointer-events-none disabled:opacity-50",
   {
     variants: {
       variant: {
         default: "bg-slate-950 text-white shadow-lg hover:-translate-y-0.5 hover:bg-slate-800",
-        magenta: "bg-gradient-to-r from-fuchsia-500 to-pink-500 text-white shadow-lg shadow-pink-500/25 hover:-translate-y-0.5",
+        // Unico color reservado a accion (nunca decorativo) -- bloque
+        // solido, no gradiente, sobre toda la superficie del sitio que
+        // ya usaba esta variant (carrito, WhatsApp, checkout, "Agregar").
+        primary: "bg-ari-ciruela text-white shadow-lg shadow-ari-ciruela/25 hover:-translate-y-0.5 hover:brightness-110",
         yellow: "bg-yellow-300 text-slate-950 shadow-lg shadow-yellow-400/25 hover:-translate-y-0.5 hover:bg-yellow-200",
-        outline: "border border-slate-200 bg-white text-slate-950 hover:border-cyan-400 hover:bg-cyan-50",
+        outline: "border border-slate-200 bg-white text-slate-950 hover:border-ari-cobre hover:bg-ari-cobre/10",
         ghost: "text-slate-700 hover:bg-slate-100",
       },
       size: {

workloads/ecommerce/components/wishlist/wishlist-drawer.tsx

@@ -35,7 +35,7 @@ export function WishlistDrawer() {
               <div>
                 <Link href={`/product/${product.slug}`} onClick={closeWishlist} prefetch={false} className="text-sm font-black leading-5 hover:text-fuchsia-600">{product.name}</Link>
                 <p className="mt-1 text-xs text-slate-500">{product.category} · {product.collection}</p>
-                <Button size="sm" variant="magenta" className="mt-3" onClick={() => addItem(product, product.variants[0]?.id)}><ShoppingBag className="size-3.5" />Agregar</Button>
+                <Button size="sm" variant="primary" className="mt-3" onClick={() => addItem(product, product.variants[0]?.id)}><ShoppingBag className="size-3.5" />Agregar</Button>
               </div>
               <button className="self-start rounded-full p-2 text-slate-400 hover:bg-rose-50 hover:text-rose-600" onClick={() => removeProduct(product.id)} aria-label="Quitar favorito"><Trash2 className="size-4" /></button>
             </article>

workloads/ecommerce/data/products.json

@@ -30,7 +30,8 @@
         "id": "ari-001-toy-story-5-rex-default",
         "name": "Presentación",
         "value": "Edición original",
-        "available": true
+        "available": true,
+        "inventoryQuantity": null
       }
     ],
     "thumbnail": "/images/thumbnails/ari-001-toy-story-5-rex.webp"
@@ -66,7 +67,8 @@
         "id": "ari-002-toy-story-5-buzz-lightyear-default",
         "name": "Presentación",
         "value": "Edición original",
-        "available": true
+        "available": true,
+        "inventoryQuantity": null
       }
     ],
     "thumbnail": "/images/thumbnails/ari-002-toy-story-5-buzz-lightyear.webp"
@@ -102,7 +104,8 @@
         "id": "ari-003-toy-story-5-jessie-default",
         "name": "Presentación",
         "value": "Edición original",
-        "available": true
+        "available": true,
+        "inventoryQuantity": null
       }
     ],
     "thumbnail": "/images/thumbnails/ari-003-toy-story-5-jessie.webp"
@@ -138,7 +141,8 @@
         "id": "ari-004-toy-story-5-woody-default",
         "name": "Presentación",
         "value": "Edición original",
-        "available": true
+        "available": true,
+        "inventoryQuantity": null
       }
     ],
     "thumbnail": "/images/thumbnails/ari-004-toy-story-5-woody.webp"
@@ -174,7 +178,8 @@
         "id": "ari-005-intensamente-furia-default",
         "name": "Presentación",
         "value": "Edición original",
-        "available": true
+        "available": true,
+        "inventoryQuantity": null
       }
     ],
     "thumbnail": "/images/thumbnails/ari-005-intensamente-furia.webp"
@@ -210,7 +215,8 @@
         "id": "ari-006-intensamente-tristeza-default",
         "name": "Presentación",
         "value": "Edición original",
-        "available": true
+        "available": true,
+        "inventoryQuantity": null
       }
     ],
     "thumbnail": "/images/thumbnails/ari-006-intensamente-tristeza.webp"
@@ -246,7 +252,8 @@
         "id": "ari-007-minnie-y-mickey-mouse-default",
         "name": "Presentación",
         "value": "Edición original",
-        "available": true
+        "available": true,
+        "inventoryQuantity": null
       }
     ],
     "thumbnail": "/images/thumbnails/ari-007-minnie-y-mickey-mouse.webp"
@@ -282,7 +289,8 @@
         "id": "ari-008-angel-lilo-y-stitch-default",
         "name": "Presentación",
         "value": "Edición original",
-        "available": true
+        "available": true,
+        "inventoryQuantity": null
       }
     ],
     "thumbnail": "/images/thumbnails/ari-008-angel-lilo-y-stitch.webp"
@@ -318,7 +326,8 @@
         "id": "ari-009-mochilas-disney-coleccion-marvel-default",
         "name": "Presentación",
         "value": "Rosa",
-        "available": true
+        "available": true,
+        "inventoryQuantity": null
       }
     ],
     "thumbnail": "/images/thumbnails/ari-009-mochilas-disney-coleccion-marvel.webp"
@@ -354,7 +363,8 @@
         "id": "ari-010-mochila-ligera-y-resistente-al-agua-de-d-default",
         "name": "Presentación",
         "value": "Rosa",
-        "available": true
+        "available": true,
+        "inventoryQuantity": null
       }
     ],
     "thumbnail": "/images/thumbnails/ari-010-mochila-ligera-y-resistente-al-agua-de-d.webp"
@@ -390,7 +400,8 @@
         "id": "ari-011-mochila-escolar-de-spider-man-de-disney--default",
         "name": "Presentación",
         "value": "Rosa",
-        "available": true
+        "available": true,
+        "inventoryQuantity": null
       }
     ],
     "thumbnail": "/images/thumbnails/ari-011-mochila-escolar-de-spider-man-de-disney-.webp"
@@ -426,7 +437,8 @@
         "id": "ari-012-disney-mochila-de-poliester-ultraligera--default",
         "name": "Presentación",
         "value": "Rosa",
-        "available": true
+        "available": true,
+        "inventoryQuantity": null
       }
     ],
     "thumbnail": "/images/thumbnails/ari-012-disney-mochila-de-poliester-ultraligera-.webp"
@@ -462,7 +474,8 @@
         "id": "ari-013-mochila-pequena-bob-esponja-default",
         "name": "Presentación",
         "value": "Rosa",
-        "available": true
+        "available": true,
+        "inventoryQuantity": null
       }
     ],
     "thumbnail": "/images/thumbnails/ari-013-mochila-pequena-bob-esponja.webp"
@@ -498,7 +511,8 @@
         "id": "ari-014-mochila-casual-de-gran-capacidad-con-est-default",
         "name": "Presentación",
         "value": "Rosa",
-        "available": true
+        "available": true,
+        "inventoryQuantity": null
       }
     ],
     "thumbnail": "/images/thumbnails/ari-014-mochila-casual-de-gran-capacidad-con-est.webp"
@@ -534,7 +548,8 @@
         "id": "ari-015-mochila-escolar-estilo-britanico-de-disn-default",
         "name": "Presentación",
         "value": "Rosa",
-        "available": true
+        "available": true,
+        "inventoryQuantity": null
       }
     ],
     "thumbnail": "/images/thumbnails/ari-015-mochila-escolar-estilo-britanico-de-disn.webp"
@@ -570,7 +585,8 @@
         "id": "ari-016-disney-mochila-iron-man-de-poliester-ult-default",
         "name": "Presentación",
         "value": "Rosa",
-        "available": true
+        "available": true,
+        "inventoryQuantity": null
       }
     ],
     "thumbnail": "/images/thumbnails/ari-016-disney-mochila-iron-man-de-poliester-ult.webp"
@@ -606,7 +622,8 @@
         "id": "ari-017-mochila-de-disney-marvel-capitan-america-default",
         "name": "Presentación",
         "value": "Rosa",
-        "available": true
+        "available": true,
+        "inventoryQuantity": null
       }
     ],
     "thumbnail": "/images/thumbnails/ari-017-mochila-de-disney-marvel-capitan-america.webp"

workloads/ecommerce/frontend/patches/deployment.yaml

@@ -25,7 +25,7 @@ spec:
         runAsUser: 1001
       containers:
         - name: app
-          image: gitea.cruzcloud.net/devops/ecommerce-frontend:v1.0.122
+          image: gitea.cruzcloud.net/devops/ecommerce-frontend:v1.0.209
           env:
             - name: HEADLESS_PROVIDER
               value: medusa
@@ -64,9 +64,20 @@ spec:
           # binario de node para esto, pero eso solo funciona si el
           # bounding set del contenedor lo permite -- drop: ALL del base
           # lo bloquea igual, root o no root. Mismo motivo que docs-portal.
+          #
+          # readOnlyRootFilesystem: true -- revisado en código (2026-08-24,
+          # aún no probado en vivo con este cambio) que esta imagen sí
+          # escribe a disco en runtime, no solo en build: el servidor
+          # standalone de Next.js cachea a ./.next/cache tanto el
+          # optimizador de imágenes (next.config.ts trae remotePatterns,
+          # sin "unoptimized: true") como el revalidateTag("medusa-products")
+          # de app/api/revalidate/route.ts (cache handler por default, sin
+          # uno custom tipo Redis). De ahí los dos volumeMounts de abajo:
+          # sin ellos, con root filesystem de solo lectura, ambas rutas
+          # fallarían al intentar escribir.
           securityContext:
             allowPrivilegeEscalation: false
-            readOnlyRootFilesystem: false
+            readOnlyRootFilesystem: true
             capabilities:
               drop:
                 - ALL
@@ -79,3 +90,13 @@ spec:
             limits:
               cpu: "1"
               memory: 768Mi
+          volumeMounts:
+            - name: next-cache
+              mountPath: /app/.next/cache
+            - name: tmp
+              mountPath: /tmp
+      volumes:
+        - name: next-cache
+          emptyDir: {}
+        - name: tmp
+          emptyDir: {}

workloads/ecommerce/lib/headless/client.ts

@@ -22,3 +22,11 @@ export async function getProductBySlug(slug: string) {
 export async function searchProducts(query: string, limit?: number) {
   return provider().searchProducts(query, limit);
 }
+
+export async function getCategories() {
+  return provider().getCategories();
+}
+
+export async function searchWithFacets(filters?: ProductFilters) {
+  return provider().searchWithFacets?.(filters);
+}

workloads/ecommerce/lib/headless/providers/medusa-cart.ts

@@ -0,0 +1,242 @@
+// ADR 0009: carrito real conectado a Medusa (Store API), en vez del
+// estado 100% local que existia antes. Archivo separado de medusa.ts
+// a proposito -- ese es de solo lectura (catalogo, cacheado con
+// revalidate/tags), este es de escritura (carrito, siempre no-store,
+// nunca debe cachearse).
+//
+// Formas de respuesta verificadas en vivo contra la API real
+// (2026-08-29), no asumidas contra documentacion:
+// - crear/agregar/actualizar linea: { cart: {...} }
+// - eliminar linea: { id, object, deleted, parent: {...} } -- el
+//   carrito actualizado viene en "parent", no en "cart".
+// - agregar el mismo variant_id dos veces hace merge de cantidad en la
+//   misma linea (confirmado con un carrito de prueba real), no crea
+//   una linea duplicada -- por eso addLineItem siempre manda
+//   quantity=1 sin revisar antes si ya existe.
+
+export interface CartLineProduct {
+  id: string;
+  name: string;
+  thumbnail: string;
+  price: number | null;
+  currency: string;
+}
+
+export interface CartLine {
+  lineItemId: string;
+  product: CartLineProduct;
+  quantity: number;
+  variantId: string;
+}
+
+export interface CartSummary {
+  cartId: string;
+  currency: string;
+  subtotal: number;
+  shippingTotal: number;
+  total: number;
+  items: CartLine[];
+}
+
+export interface ShippingAddressInput {
+  firstName: string;
+  lastName: string;
+  address1: string;
+  city: string;
+  province?: string;
+  phone: string;
+  email: string;
+}
+
+export interface ShippingOption {
+  id: string;
+  name: string;
+  amount: number;
+}
+
+function backendUrl(): string {
+  const value = process.env.MEDUSA_BACKEND_URL;
+  if (!value) {
+    throw new Error("MEDUSA_BACKEND_URL no está configurado.");
+  }
+  return value.replace(/\/$/, "");
+}
+
+function regionId(): string {
+  const value = process.env.MEDUSA_REGION_ID;
+  if (!value) {
+    throw new Error("MEDUSA_REGION_ID no está configurado.");
+  }
+  return value;
+}
+
+type MedusaLineItem = {
+  id: string;
+  product_id: string;
+  variant_id: string;
+  title?: string | null;
+  product_title?: string | null;
+  thumbnail?: string | null;
+  quantity: number;
+  unit_price?: number | null;
+  product?: { images?: Array<{ url?: string | null }> | null } | null;
+};
+
+type MedusaCart = {
+  id: string;
+  currency_code: string;
+  subtotal?: number | null;
+  shipping_total?: number | null;
+  total?: number | null;
+  items?: MedusaLineItem[] | null;
+};
+
+function mapCart(cart: MedusaCart): CartSummary {
+  return {
+    cartId: cart.id,
+    currency: cart.currency_code,
+    subtotal: cart.subtotal ?? 0,
+    shippingTotal: cart.shipping_total ?? 0,
+    total: cart.total ?? cart.subtotal ?? 0,
+    items: (cart.items ?? []).map((item) => ({
+      lineItemId: item.id,
+      variantId: item.variant_id,
+      quantity: item.quantity,
+      product: {
+        id: item.product_id,
+        name: item.product_title || item.title || "Producto",
+        // item.thumbnail viene null en la practica para todo el catalogo
+        // real (confirmado contra /store/products: product.thumbnail
+        // tambien es null ahi, incluso con fotos reales cargadas) -- el
+        // catalogo ya resuelve esto cayendo a images[0] (mapProduct() en
+        // medusa.ts), asi que la linea del carrito pide esa misma relacion
+        // explicita (no viene por defecto) y aplica el mismo fallback.
+        thumbnail: item.thumbnail || item.product?.images?.[0]?.url || "/images/brand/logo-ari.png",
+        price: typeof item.unit_price === "number" ? item.unit_price : null,
+        currency: cart.currency_code,
+      },
+    })),
+  };
+}
+
+async function medusaCartFetch(
+  path: string,
+  init?: { method?: string; body?: unknown },
+): Promise<Record<string, unknown>> {
+  const publishableKey = process.env.MEDUSA_PUBLISHABLE_KEY;
+
+  const response = await fetch(`${backendUrl()}${path}`, {
+    method: init?.method ?? "GET",
+    headers: {
+      "Content-Type": "application/json",
+      ...(publishableKey ? { "x-publishable-api-key": publishableKey } : {}),
+    },
+    body: init?.body ? JSON.stringify(init.body) : undefined,
+    cache: "no-store",
+  });
+
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    throw new Error(`Medusa cart API ${response.status}: ${text.slice(0, 300)}`);
+  }
+
+  return response.json();
+}
+
+// *items.product.images no viene por defecto (verificado en vivo) y es
+// lo unico que necesitamos ademas del set por defecto -- *items ya trae
+// unit_price/product_title/variant_id/quantity sin pedirlos aparte.
+const ITEMS_FIELDS = "fields=*items,*items.product.images";
+
+export async function createCart(): Promise<CartSummary> {
+  const data = await medusaCartFetch("/store/carts", {
+    method: "POST",
+    body: { region_id: regionId() },
+  });
+  return mapCart(data.cart as MedusaCart);
+}
+
+export async function getCart(cartId: string): Promise<CartSummary> {
+  const data = await medusaCartFetch(`/store/carts/${cartId}?${ITEMS_FIELDS}`);
+  return mapCart(data.cart as MedusaCart);
+}
+
+export async function addLineItem(
+  cartId: string,
+  variantId: string,
+  quantity: number,
+): Promise<CartSummary> {
+  const data = await medusaCartFetch(`/store/carts/${cartId}/line-items?${ITEMS_FIELDS}`, {
+    method: "POST",
+    body: { variant_id: variantId, quantity },
+  });
+  return mapCart(data.cart as MedusaCart);
+}
+
+export async function updateLineItemQuantity(
+  cartId: string,
+  lineItemId: string,
+  quantity: number,
+): Promise<CartSummary> {
+  const data = await medusaCartFetch(`/store/carts/${cartId}/line-items/${lineItemId}?${ITEMS_FIELDS}`, {
+    method: "POST",
+    body: { quantity },
+  });
+  return mapCart(data.cart as MedusaCart);
+}
+
+export async function removeLineItem(cartId: string, lineItemId: string): Promise<CartSummary> {
+  const data = await medusaCartFetch(`/store/carts/${cartId}/line-items/${lineItemId}?${ITEMS_FIELDS}`, {
+    method: "DELETE",
+  });
+  // Forma distinta a las demas: el carrito actualizado viene en
+  // "parent", no en "cart" -- verificado en vivo, no documentado.
+  return mapCart(data.parent as MedusaCart);
+}
+
+export async function setShippingAddress(
+  cartId: string,
+  address: ShippingAddressInput,
+): Promise<CartSummary> {
+  const data = await medusaCartFetch(`/store/carts/${cartId}?${ITEMS_FIELDS}`, {
+    method: "POST",
+    body: {
+      email: address.email,
+      shipping_address: {
+        first_name: address.firstName,
+        last_name: address.lastName,
+        address_1: address.address1,
+        city: address.city,
+        province: address.province || undefined,
+        country_code: "co",
+        phone: address.phone,
+      },
+    },
+  });
+  return mapCart(data.cart as MedusaCart);
+}
+
+type MedusaShippingOption = {
+  id: string;
+  name: string;
+  amount?: number | null;
+  calculated_price?: { calculated_amount?: number | null } | null;
+};
+
+export async function getShippingOptions(cartId: string): Promise<ShippingOption[]> {
+  const data = await medusaCartFetch(`/store/shipping-options?cart_id=${cartId}`);
+  const options = (data.shipping_options as MedusaShippingOption[] | undefined) ?? [];
+  return options.map((option) => ({
+    id: option.id,
+    name: option.name,
+    amount: option.calculated_price?.calculated_amount ?? option.amount ?? 0,
+  }));
+}
+
+export async function addShippingMethod(cartId: string, optionId: string): Promise<CartSummary> {
+  const data = await medusaCartFetch(`/store/carts/${cartId}/shipping-methods?${ITEMS_FIELDS}`, {
+    method: "POST",
+    body: { option_id: optionId },
+  });
+  return mapCart(data.cart as MedusaCart);
+}

workloads/ecommerce/lib/headless/providers/medusa.ts

@@ -1,5 +1,8 @@
 import type {
   CatalogProvider,
+  Category,
+  FacetDistribution,
+  FacetedSearchResult,
   Product,
   ProductFilters,
   ProductVariant,
@@ -66,188 +69,16 @@ type MedusaProductsResponse = {
   offset?: number;
 };
 
-type LegacyMeta = {
-  category: string;
-  collection: string;
-  brand: string;
-  ageRange: string;
-  featured: boolean;
-  isNew: boolean;
-  fallbackImage: string;
-  fallbackThumbnail: string;
+type MedusaProductCategory = {
+  id: string;
+  name?: string | null;
+  handle?: string | null;
+  parent_category_id?: string | null;
+  rank?: number | null;
 };
 
-const legacyProductMeta: Record<string, LegacyMeta> = {
-  "toy-story-5-rex": {
-    "category": "Figuras",
-    "collection": "Toy Story",
-    "brand": "Disney Pixar",
-    "ageRange": "3+",
-    "featured": true,
-    "isNew": true,
-    "fallbackImage": "https://shop.cruzcloud.net/images/products/ari-001-toy-story-5-rex.webp",
-    "fallbackThumbnail": "https://shop.cruzcloud.net/images/thumbnails/ari-001-toy-story-5-rex.webp"
-  },
-  "toy-story-5-buzz-lightyear": {
-    "category": "Figuras",
-    "collection": "Toy Story",
-    "brand": "Disney Pixar",
-    "ageRange": "3+",
-    "featured": true,
-    "isNew": true,
-    "fallbackImage": "https://shop.cruzcloud.net/images/products/ari-002-toy-story-5-buzz-lightyear.webp",
-    "fallbackThumbnail": "https://shop.cruzcloud.net/images/thumbnails/ari-002-toy-story-5-buzz-lightyear.webp"
-  },
-  "toy-story-5-jessie": {
-    "category": "Figuras",
-    "collection": "Toy Story",
-    "brand": "Disney Pixar",
-    "ageRange": "3+",
-    "featured": true,
-    "isNew": true,
-    "fallbackImage": "https://shop.cruzcloud.net/images/products/ari-003-toy-story-5-jessie.webp",
-    "fallbackThumbnail": "https://shop.cruzcloud.net/images/thumbnails/ari-003-toy-story-5-jessie.webp"
-  },
-  "toy-story-5-woody": {
-    "category": "Figuras",
-    "collection": "Toy Story",
-    "brand": "Disney Pixar",
-    "ageRange": "3+",
-    "featured": true,
-    "isNew": true,
-    "fallbackImage": "https://shop.cruzcloud.net/images/products/ari-004-toy-story-5-woody.webp",
-    "fallbackThumbnail": "https://shop.cruzcloud.net/images/thumbnails/ari-004-toy-story-5-woody.webp"
-  },
-  "intensamente-furia": {
-    "category": "Peluches",
-    "collection": "Intensamente",
-    "brand": "Disney",
-    "ageRange": "3+",
-    "featured": true,
-    "isNew": true,
-    "fallbackImage": "https://shop.cruzcloud.net/images/products/ari-005-intensamente-furia.webp",
-    "fallbackThumbnail": "https://shop.cruzcloud.net/images/thumbnails/ari-005-intensamente-furia.webp"
-  },
-  "intensamente-tristeza": {
-    "category": "Peluches",
-    "collection": "Intensamente",
-    "brand": "Disney",
-    "ageRange": "3+",
-    "featured": true,
-    "isNew": true,
-    "fallbackImage": "https://shop.cruzcloud.net/images/products/ari-006-intensamente-tristeza.webp",
-    "fallbackThumbnail": "https://shop.cruzcloud.net/images/thumbnails/ari-006-intensamente-tristeza.webp"
-  },
-  "minnie-y-mickey-mouse": {
-    "category": "Peluches",
-    "collection": "Mickey & Minnie",
-    "brand": "Disney",
-    "ageRange": "3+",
-    "featured": true,
-    "isNew": false,
-    "fallbackImage": "https://shop.cruzcloud.net/images/products/ari-007-minnie-y-mickey-mouse.webp",
-    "fallbackThumbnail": "https://shop.cruzcloud.net/images/thumbnails/ari-007-minnie-y-mickey-mouse.webp"
-  },
-  "angel-lilo-y-stitch": {
-    "category": "Peluches",
-    "collection": "Lilo & Stitch",
-    "brand": "Disney",
-    "ageRange": "3+",
-    "featured": true,
-    "isNew": false,
-    "fallbackImage": "https://shop.cruzcloud.net/images/products/ari-008-angel-lilo-y-stitch.webp",
-    "fallbackThumbnail": "https://shop.cruzcloud.net/images/thumbnails/ari-008-angel-lilo-y-stitch.webp"
-  },
-  "mochilas-disney-coleccion-marvel": {
-    "category": "Mochilas",
-    "collection": "Marvel",
-    "brand": "Marvel",
-    "ageRange": "6+",
-    "featured": false,
-    "isNew": false,
-    "fallbackImage": "https://shop.cruzcloud.net/images/products/ari-009-mochilas-disney-coleccion-marvel.webp",
-    "fallbackThumbnail": "https://shop.cruzcloud.net/images/thumbnails/ari-009-mochilas-disney-coleccion-marvel.webp"
-  },
-  "mochila-ligera-y-resistente-al-agua-de-disney-frozen-mochila-escolar-y-de-viaje-con-multiples-compa": {
-    "category": "Mochilas",
-    "collection": "Frozen",
-    "brand": "Disney",
-    "ageRange": "6+",
-    "featured": false,
-    "isNew": false,
-    "fallbackImage": "https://shop.cruzcloud.net/images/products/ari-010-mochila-ligera-y-resistente-al-agua-de-d.webp",
-    "fallbackThumbnail": "https://shop.cruzcloud.net/images/thumbnails/ari-010-mochila-ligera-y-resistente-al-agua-de-d.webp"
-  },
-  "mochila-escolar-de-spider-man-de-disney-moda-estudiantil-libro-de-gran-capacidad-mochila-ligera": {
-    "category": "Mochilas",
-    "collection": "Marvel",
-    "brand": "Marvel",
-    "ageRange": "6+",
-    "featured": false,
-    "isNew": false,
-    "fallbackImage": "https://shop.cruzcloud.net/images/products/ari-011-mochila-escolar-de-spider-man-de-disney-.webp",
-    "fallbackThumbnail": "https://shop.cruzcloud.net/images/thumbnails/ari-011-mochila-escolar-de-spider-man-de-disney-.webp"
-  },
-  "disney-mochila-de-poliester-ultraligera-y-transpirable-de-gran-tamano-y-multiples-colores-dimension": {
-    "category": "Mochilas",
-    "collection": "Disney",
-    "brand": "Disney",
-    "ageRange": "6+",
-    "featured": false,
-    "isNew": false,
-    "fallbackImage": "https://shop.cruzcloud.net/images/products/ari-012-disney-mochila-de-poliester-ultraligera-.webp",
-    "fallbackThumbnail": "https://shop.cruzcloud.net/images/thumbnails/ari-012-disney-mochila-de-poliester-ultraligera-.webp"
-  },
-  "mochila-pequena-bob-esponja": {
-    "category": "Mochilas",
-    "collection": "Bob Esponja",
-    "brand": "Disney",
-    "ageRange": "6+",
-    "featured": false,
-    "isNew": false,
-    "fallbackImage": "https://shop.cruzcloud.net/images/products/ari-013-mochila-pequena-bob-esponja.webp",
-    "fallbackThumbnail": "https://shop.cruzcloud.net/images/thumbnails/ari-013-mochila-pequena-bob-esponja.webp"
-  },
-  "mochila-casual-de-gran-capacidad-con-estampado-de-bob-esponja-unisex-bolsa-escolar-de-dibujos-anim": {
-    "category": "Mochilas",
-    "collection": "Bob Esponja",
-    "brand": "Disney",
-    "ageRange": "6+",
-    "featured": false,
-    "isNew": false,
-    "fallbackImage": "https://shop.cruzcloud.net/images/products/ari-014-mochila-casual-de-gran-capacidad-con-est.webp",
-    "fallbackThumbnail": "https://shop.cruzcloud.net/images/thumbnails/ari-014-mochila-casual-de-gran-capacidad-con-est.webp"
-  },
-  "mochila-escolar-estilo-britanico-de-disney-con-proteccion-de-la-columna-vertebral-nueva-mochila-de": {
-    "category": "Mochilas",
-    "collection": "Disney",
-    "brand": "Disney",
-    "ageRange": "6+",
-    "featured": false,
-    "isNew": false,
-    "fallbackImage": "https://shop.cruzcloud.net/images/products/ari-015-mochila-escolar-estilo-britanico-de-disn.webp",
-    "fallbackThumbnail": "https://shop.cruzcloud.net/images/thumbnails/ari-015-mochila-escolar-estilo-britanico-de-disn.webp"
-  },
-  "disney-mochila-iron-man-de-poliester-ultraligera-y-transpirable-de-gran-tamano-dimensiones-46-cm-x": {
-    "category": "Mochilas",
-    "collection": "Marvel",
-    "brand": "Marvel",
-    "ageRange": "6+",
-    "featured": false,
-    "isNew": false,
-    "fallbackImage": "https://shop.cruzcloud.net/images/products/ari-016-disney-mochila-iron-man-de-poliester-ult.webp",
-    "fallbackThumbnail": "https://shop.cruzcloud.net/images/thumbnails/ari-016-disney-mochila-iron-man-de-poliester-ult.webp"
-  },
-  "mochila-de-disney-marvel-capitan-america-de-gran-capacidad-ligera-y-resistente-a-salpicaduras-par": {
-    "category": "Mochilas",
-    "collection": "Marvel",
-    "brand": "Marvel",
-    "ageRange": "6+",
-    "featured": false,
-    "isNew": false,
-    "fallbackImage": "https://shop.cruzcloud.net/images/products/ari-017-mochila-de-disney-marvel-capitan-america.webp",
-    "fallbackThumbnail": "https://shop.cruzcloud.net/images/thumbnails/ari-017-mochila-de-disney-marvel-capitan-america.webp"
-  }
+type MedusaCategoriesResponse = {
+  product_categories: MedusaProductCategory[];
 };
 
 function backendUrl(): string {
@@ -328,17 +159,24 @@ function mapVariant(variant: MedusaVariant): ProductVariant {
     variant.manage_inventory === false ||
     (variant.inventory_quantity ?? 0) > 0;
 
+  // null = inventario no gestionado (backorder o manage_inventory=false),
+  // no hay un numero real que mostrar como "quedan N".
+  const inventoryQuantity =
+    variant.allow_backorder === true || variant.manage_inventory === false
+      ? null
+      : (variant.inventory_quantity ?? 0);
+
   return {
     id: variant.id,
     name: option?.option?.title || "Presentación",
     value: option?.value || variant.title || "Estándar",
     available,
+    inventoryQuantity,
   };
 }
 
 function mapProduct(product: MedusaProduct): Product {
   const slug = product.handle || product.id;
-  const legacy = legacyProductMeta[slug];
 
   const variant = product.variants?.[0];
   const calculated = variant?.calculated_price;
@@ -346,24 +184,16 @@ function mapProduct(product: MedusaProduct): Product {
   const category =
     product.categories?.[0]?.name ||
     stringMetadata(product.metadata, "category") ||
-    legacy?.category ||
     "Variedades";
 
   const collection =
     product.collection?.title ||
     stringMetadata(product.metadata, "collection") ||
-    legacy?.collection ||
     "";
 
-  const brand =
-    stringMetadata(product.metadata, "brand") ||
-    legacy?.brand ||
-    "ARI Shopping";
+  const brand = stringMetadata(product.metadata, "brand") || "ARI Shopping";
 
-  const ageRange =
-    stringMetadata(product.metadata, "ageRange") ||
-    legacy?.ageRange ||
-    "Todas";
+  const ageRange = stringMetadata(product.metadata, "ageRange") || "Todas";
 
   const images = [
     ...(product.images || [])
@@ -371,15 +201,8 @@ function mapProduct(product: MedusaProduct): Product {
       .filter(Boolean),
   ];
 
-  if (images.length === 0 && legacy?.fallbackImage) {
-    images.push(legacy.fallbackImage);
-  }
-
   const thumbnail =
-    product.thumbnail ||
-    images[0] ||
-    legacy?.fallbackThumbnail ||
-    "/images/brand/logo-ari.png";
+    product.thumbnail || images[0] || "/images/brand/logo-ari.png";
 
   const price =
     typeof calculated?.calculated_amount === "number"
@@ -426,14 +249,8 @@ function mapProduct(product: MedusaProduct): Product {
     currency: normalizeCurrency(calculated?.currency_code),
     priceLabel: price === null ? "Consultar disponibilidad" : "",
     available,
-    featured:
-      booleanMetadata(product.metadata, "featured") ||
-      legacy?.featured ||
-      false,
-    isNew:
-      booleanMetadata(product.metadata, "isNew") ||
-      legacy?.isNew ||
-      false,
+    featured: booleanMetadata(product.metadata, "featured"),
+    isNew: booleanMetadata(product.metadata, "isNew"),
     image: images[0] || thumbnail,
     thumbnail,
     images: images.length > 0 ? images : [thumbnail],
@@ -528,7 +345,7 @@ async function fetchProducts(
     // region_id.
     region_id: regionId(),
     fields:
-      "+metadata,+images,+tags,+categories,+collection,+variants.inventory_quantity,+variants.calculated_price,+variants.options",
+      "+metadata,+images,+tags,+categories.*,+collection,+variants.inventory_quantity,+variants.calculated_price,+variants.options",
   });
 
   if (filters?.query) {
@@ -545,11 +362,90 @@ async function fetchProducts(
     .filter((product) => matchesFilters(product, filters));
 }
 
+async function fetchCategories(): Promise<Category[]> {
+  const params = new URLSearchParams({
+    limit: "100",
+    fields: "id,name,handle,rank,parent_category_id",
+  });
+
+  const response = await medusaFetch<MedusaCategoriesResponse>(
+    "/store/product-categories",
+    params,
+  );
+
+  // Ordenar por rank preserva el orden de la taxonomia tal como se creo
+  // (ver ADR 0005) -- los hijos de cada padre quedan en el mismo orden
+  // relativo porque el arbol se arma filtrando este arreglo ya ordenado.
+  return response.product_categories
+    .slice()
+    .sort((a, b) => (a.rank ?? 0) - (b.rank ?? 0))
+    .map((category) => ({
+      id: category.id,
+      name: category.name || "",
+      handle: category.handle || category.id,
+      parentId: category.parent_category_id ?? null,
+    }));
+}
+
+type MedusaSearchResponse = {
+  products: MedusaProduct[];
+  facetDistribution?: FacetDistribution;
+  count?: number;
+};
+
+// Pega contra /store/search (ADR 0006 Etapa 2) en vez de /store/products
+// -- Meilisearch resuelve texto tolerante a errores de tipeo y facetas
+// reales, la ruta del backend re-hidrata precio/inventario vía
+// query.graph antes de responder, así que el shape de MedusaProduct es
+// exactamente el mismo que ya mapea mapProduct().
+async function fetchWithFacets(
+  filters?: ProductFilters,
+  limit = 24,
+): Promise<FacetedSearchResult> {
+  const params = new URLSearchParams({
+    limit: String(limit),
+    region_id: regionId(),
+  });
+
+  if (filters?.query) params.set("q", filters.query);
+  if (filters?.category && filters.category !== "Todos") {
+    params.set("category", filters.category);
+  }
+  if (filters?.collection) params.set("collection", filters.collection);
+  if (filters?.brand && filters.brand !== "Todas") {
+    params.set("brand", filters.brand);
+  }
+  if (filters?.ageRange && filters.ageRange !== "Todas") {
+    params.set("ageRange", filters.ageRange);
+  }
+  if (typeof filters?.minPrice === "number") {
+    params.set("minPrice", String(filters.minPrice));
+  }
+  if (typeof filters?.maxPrice === "number") {
+    params.set("maxPrice", String(filters.maxPrice));
+  }
+
+  const response = await medusaFetch<MedusaSearchResponse>(
+    "/store/search",
+    params,
+  );
+
+  return {
+    products: response.products.map(mapProduct),
+    facetDistribution: response.facetDistribution ?? {},
+    count: response.count ?? response.products.length,
+  };
+}
+
 export const medusaCatalogProvider: CatalogProvider = {
   async getProducts(filters) {
     return fetchProducts(filters);
   },
 
+  async getCategories() {
+    return fetchCategories();
+  },
+
   async getProductBySlug(slug) {
     const params = new URLSearchParams({
       handle: slug,
@@ -559,7 +455,7 @@ export const medusaCatalogProvider: CatalogProvider = {
       // region_id.
       region_id: regionId(),
       fields:
-        "+metadata,+images,+tags,+categories,+collection,+variants.inventory_quantity,+variants.calculated_price,+variants.options",
+        "+metadata,+images,+tags,+categories.*,+collection,+variants.inventory_quantity,+variants.calculated_price,+variants.options",
     });
 
     const response = await medusaFetch<MedusaProductsResponse>(
@@ -572,6 +468,11 @@ export const medusaCatalogProvider: CatalogProvider = {
   },
 
   async searchProducts(query, limit = 8) {
-    return fetchProducts({ query }, limit);
+    const { products } = await fetchWithFacets({ query }, limit);
+    return products;
+  },
+
+  async searchWithFacets(filters) {
+    return fetchWithFacets(filters, filters?.limit ?? 24);
   },
 };

workloads/ecommerce/lib/headless/providers/mock.ts

@@ -1,5 +1,5 @@
 import catalog from "@/data/products.json";
-import type { CatalogProvider, Product, ProductFilters } from "@/lib/headless/types";
+import type { CatalogProvider, Category, Product, ProductFilters } from "@/lib/headless/types";
 
 const products = catalog satisfies Product[];
 
@@ -39,4 +39,16 @@ export const mockCatalogProvider: CatalogProvider = {
   async searchProducts(query, limit = 6) {
     return products.filter((product) => matches(product, { query })).slice(0, limit);
   },
+  async getCategories(): Promise<Category[]> {
+    // El catalogo mock no tiene jerarquia real (a diferencia de Medusa) --
+    // se devuelve una lista plana de las categorias que ya usan los
+    // productos mock, todas sin padre.
+    const names = [...new Set(products.map((product) => product.category))].filter(Boolean);
+    return names.map((name) => ({
+      id: name,
+      name,
+      handle: normalize(name).replace(/\s+/g, "-"),
+      parentId: null,
+    }));
+  },
 };

workloads/ecommerce/lib/headless/providers/shopify.ts

@@ -42,4 +42,7 @@ export const shopifyCatalogProvider: CatalogProvider = {
   async searchProducts(): Promise<Product[]> {
     return notImplemented();
   },
+  async getCategories() {
+    return notImplemented();
+  },
 };

workloads/ecommerce/lib/headless/types.ts

@@ -3,6 +3,7 @@ export interface ProductVariant {
   name: string;
   value: string;
   available: boolean;
+  inventoryQuantity: number | null;
 }
 
 export interface Product {
@@ -37,10 +38,36 @@ export interface ProductFilters {
   ageRange?: string;
   minPrice?: number;
   maxPrice?: number;
+  // Solo lo usa searchWithFacets -- limit=0 pide facetDistribution/count
+  // sin rehidratar precios de productos que no se van a mostrar (ver
+  // sidebar de facetas en catalog-client.tsx).
+  limit?: number;
+}
+
+export interface Category {
+  id: string;
+  name: string;
+  handle: string;
+  parentId: string | null;
+}
+
+// facet -> valor -> cuantos productos del resultado filtrado tienen ese
+// valor (ej. { brand: { Marvel: 5, Disney: 10 } }).
+export type FacetDistribution = Record<string, Record<string, number>>;
+
+export interface FacetedSearchResult {
+  products: Product[];
+  facetDistribution: FacetDistribution;
+  count: number;
 }
 
 export interface CatalogProvider {
   getProducts(filters?: ProductFilters): Promise<Product[]>;
   getProductBySlug(slug: string): Promise<Product | null>;
   searchProducts(query: string, limit?: number): Promise<Product[]>;
+  getCategories(): Promise<Category[]>;
+  // Opcional a propósito: mock.ts y shopify.ts no lo implementan y
+  // siguen compilando igual -- los llamadores caen de nuevo al
+  // filtrado/conteo 100% client-side que ya existe cuando no está.
+  searchWithFacets?(filters?: ProductFilters): Promise<FacetedSearchResult>;
 }

workloads/ecommerce/lib/utils.ts

@@ -13,3 +13,8 @@ export function formatMoney(value: number | null, currency = "COP"): string {
     maximumFractionDigits: 0,
   }).format(value);
 }
+
+// Umbral desde el cual mostramos "Quedan N" en vez de solo "Disponible".
+// inventoryQuantity=null significa inventario no gestionado (backorder /
+// manage_inventory=false en Medusa) -- ahi nunca mostramos el mensaje.
+export const LOW_STOCK_THRESHOLD = 5;

workloads/ecommerce/next.config.ts

@@ -42,6 +42,22 @@ const nextConfig: NextConfig = {
           },
         ],
       },
+      // Assets de marca (logo, favicon) cambian con cada iteracion de
+      // identidad visual, a diferencia de las fotos de producto -- el
+      // cache de 7 dias de la regla anterior dejaba servido el logo
+      // viejo en Cloudflare/navegador durante toda una semana despues de
+      // cada deploy (ver ADR 0008). Next.js aplica el ultimo header que
+      // matchee un mismo path, asi que esta regla, al ir despues,
+      // sobreescribe el Cache-Control solo para /images/brand/*.
+      {
+        source: "/images/brand/:path*",
+        headers: [
+          {
+            key: "Cache-Control",
+            value: "public, max-age=300, must-revalidate",
+          },
+        ],
+      },
     ];
   },
 };

workloads/ecommerce/patches/frontend-medusa-env.yaml

@@ -1,21 +0,0 @@
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: frontend-deploy
-spec:
-  template:
-    spec:
-      containers:
-        - name: web
-          env:
-            - name: HEADLESS_PROVIDER
-              value: medusa
-
-            - name: MEDUSA_BACKEND_URL
-              value: http://medusa-svc:9000
-
-            - name: MEDUSA_PUBLISHABLE_KEY
-              valueFrom:
-                secretKeyRef:
-                  name: commerce-storefront
-                  key: MEDUSA_PUBLISHABLE_KEY

workloads/ecommerce/public/images/brand/logo-ari-circular.svg

@@ -0,0 +1,17 @@
+<!-- ADR 0008, paleta "Azul & Amarillo". Isotipo circular (formato de la
+     version previa a ADR 0008, pedido explicito del usuario en vez del
+     lockup rectangular de logo-ari.svg): mariposa geometrica de 4 elipses
+     + wordmark "ARI shopping", todo dentro del mismo circulo azul.
+     Ver docs-portal/docs/decisiones/0008-identidad-navy-coral.md -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 200" role="img" aria-label="ARI shopping">
+  <circle cx="100" cy="100" r="98" fill="#0055B8"/>
+  <g transform="translate(100 68) scale(2.6) translate(-17 -11)">
+    <ellipse cx="10" cy="8" rx="9" ry="7" transform="rotate(-18 10 8)" fill="#FFC220"/>
+    <ellipse cx="24" cy="8" rx="9" ry="7" transform="rotate(18 24 8)" fill="#FFC220"/>
+    <ellipse cx="12" cy="16" rx="6" ry="5" transform="rotate(-10 12 16)" fill="#FFDD73"/>
+    <ellipse cx="22" cy="16" rx="6" ry="5" transform="rotate(10 22 16)" fill="#FFDD73"/>
+    <rect x="16" y="3" width="2" height="18" rx="1" fill="#0055B8"/>
+  </g>
+  <text x="100" y="132" text-anchor="middle" font-family="Poppins, ui-sans-serif, system-ui, sans-serif" font-weight="700" font-size="38" fill="#FFFFFF">ARI</text>
+  <text x="100" y="153" text-anchor="middle" font-family="Poppins, ui-sans-serif, system-ui, sans-serif" font-weight="700" font-size="14" letter-spacing="3" fill="#FFC220">shopping</text>
+</svg>

workloads/ecommerce/public/images/brand/logo-ari.svg

@@ -0,0 +1,16 @@
+<!-- ADR 0008, paleta final "Azul & Amarillo" (Walmart-inspirada). Isotipo:
+     mariposa geometrica de 4 elipses sobre circulo/campo azul + wordmark
+     "ARI shopping".
+     Ver docs-portal/docs/decisiones/0008-identidad-navy-coral.md -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 64" role="img" aria-label="ARI shopping">
+  <rect width="200" height="64" rx="12" fill="#0055B8"/>
+  <g transform="translate(14 20)">
+    <ellipse cx="10" cy="8" rx="9" ry="7" transform="rotate(-18 10 8)" fill="#FFC220"/>
+    <ellipse cx="24" cy="8" rx="9" ry="7" transform="rotate(18 24 8)" fill="#FFC220"/>
+    <ellipse cx="12" cy="16" rx="6" ry="5" transform="rotate(-10 12 16)" fill="#FFDD73"/>
+    <ellipse cx="22" cy="16" rx="6" ry="5" transform="rotate(10 22 16)" fill="#FFDD73"/>
+    <rect x="16" y="3" width="2" height="18" rx="1" fill="#0055B8"/>
+  </g>
+  <text x="64" y="38" font-family="Poppins, ui-sans-serif, system-ui, sans-serif" font-weight="700" font-size="26" fill="#FFFFFF">ARI</text>
+  <text x="64" y="53" font-family="Poppins, ui-sans-serif, system-ui, sans-serif" font-weight="700" font-size="11" letter-spacing="2.5" fill="#FFC220">shopping</text>
+</svg>

workloads/ecommerce/store/cart-store.ts

@@ -2,60 +2,117 @@
 
 import { create } from "zustand";
 import { createJSONStorage, persist } from "zustand/middleware";
-import type { Product } from "@/lib/headless/types";
+import type { CartLine } from "@/lib/headless/providers/medusa-cart";
 
-export interface CartItem {
-  product: Product;
-  quantity: number;
-  variantId?: string;
-}
+// ADR 0009: carrito real conectado a un cart_id de Medusa (Store API,
+// via /api/cart/*) en vez de estado 100% local -- precios y existencia
+// de linea son los que confirma el servidor, no un calculo optimista
+// en el cliente. Primer corte a proposito: sin UI de direccion/envio
+// todavia, el checkout sigue cerrando por WhatsApp (CartDrawer).
+export type CartItem = CartLine;
 
 interface CartState {
+  cartId: string | null;
   items: CartItem[];
   isOpen: boolean;
   hasHydrated: boolean;
   openCart: () => void;
   closeCart: () => void;
   setHasHydrated: (value: boolean) => void;
-  addItem: (product: Product, variantId?: string) => void;
-  removeItem: (productId: string) => void;
-  updateQuantity: (productId: string, quantity: number) => void;
-  clearCart: () => void;
+  addItem: (product: { id: string }, variantId?: string) => Promise<void>;
+  removeItem: (productId: string) => Promise<void>;
+  updateQuantity: (productId: string, quantity: number) => Promise<void>;
+  clearCart: () => Promise<void>;
+  syncCart: () => Promise<void>;
+}
+
+async function postJson(url: string, body: unknown) {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  return response.json();
 }
 
 export const useCartStore = create<CartState>()(
   persist(
-    (set) => ({
+    (set, get) => ({
+      cartId: null,
       items: [],
       isOpen: false,
       hasHydrated: false,
       openCart: () => set({ isOpen: true }),
       closeCart: () => set({ isOpen: false }),
       setHasHydrated: (value) => set({ hasHydrated: value }),
-      addItem: (product, variantId) => set((state) => {
-        const existing = state.items.find(
-          (item) => item.product.id === product.id && item.variantId === variantId,
+
+      addItem: async (product, variantId) => {
+        set({ isOpen: true });
+        if (!variantId) return;
+
+        let cartId = get().cartId;
+        if (!cartId) {
+          const cart = await (await fetch("/api/cart", { method: "POST" })).json();
+          if (!cart.cartId) return;
+          cartId = cart.cartId;
+          set({ cartId, items: cart.items ?? [] });
+        }
+
+        const cart = await postJson("/api/cart/items", { cartId, variantId, quantity: 1 });
+        if (cart.items) set({ items: cart.items });
+      },
+
+      removeItem: async (productId) => {
+        const { cartId, items } = get();
+        const line = items.find((item) => item.product.id === productId);
+        if (!cartId || !line) return;
+        const response = await fetch(`/api/cart/items/${line.lineItemId}?cartId=${cartId}`, { method: "DELETE" });
+        const cart = await response.json();
+        if (cart.items) set({ items: cart.items });
+      },
+
+      updateQuantity: async (productId, quantity) => {
+        if (quantity <= 0) return get().removeItem(productId);
+        const { cartId, items } = get();
+        const line = items.find((item) => item.product.id === productId);
+        if (!cartId || !line) return;
+        const cart = await postJson(`/api/cart/items/${line.lineItemId}`, { cartId, quantity });
+        if (cart.items) set({ items: cart.items });
+      },
+
+      clearCart: async () => {
+        const { cartId, items } = get();
+        if (!cartId) return;
+        await Promise.all(
+          items.map((item) => fetch(`/api/cart/items/${item.lineItemId}?cartId=${cartId}`, { method: "DELETE" })),
         );
-        const items = existing
-          ? state.items.map((item) => item === existing ? { ...item, quantity: item.quantity + 1 } : item)
-          : [...state.items, { product, quantity: 1, variantId }];
-        return { items, isOpen: true };
-      }),
-      removeItem: (productId) => set((state) => ({
-        items: state.items.filter((item) => item.product.id !== productId),
-      })),
-      updateQuantity: (productId, quantity) => set((state) => ({
-        items: quantity <= 0
-          ? state.items.filter((item) => item.product.id !== productId)
-          : state.items.map((item) => item.product.id === productId ? { ...item, quantity } : item),
-      })),
-      clearCart: () => set({ items: [] }),
+        set({ items: [] });
+      },
+
+      // Al recargar la pagina, el cart_id guardado en localStorage puede
+      // llevar dias -- se refresca contra el servidor en vez de confiar en
+      // el ultimo snapshot local (precios/stock pudieron cambiar).
+      syncCart: async () => {
+        const cartId = get().cartId;
+        if (!cartId) return;
+        try {
+          const response = await fetch(`/api/cart?cartId=${cartId}`);
+          if (!response.ok) return;
+          const cart = await response.json();
+          if (cart.items) set({ items: cart.items });
+        } catch {
+          // Sin red: se queda con el ultimo estado local conocido.
+        }
+      },
     }),
     {
-      name: "ari-shopping-cart-v4",
+      name: "ari-shopping-cart-v5",
       storage: createJSONStorage(() => localStorage),
-      partialize: (state) => ({ items: state.items }),
-      onRehydrateStorage: () => (state) => state?.setHasHydrated(true),
+      partialize: (state) => ({ cartId: state.cartId, items: state.items }),
+      onRehydrateStorage: () => (state) => {
+        state?.setHasHydrated(true);
+        void state?.syncCart();
+      },
     },
   ),
 );