fix(commerce-backend): traer name/title explicito en el importador

listProductCategories({})/listProductCollections({}) sin select
explicito devolvian name/title undefined (a diferencia de la capa HTTP
del Admin API, que si los trae completos por defecto) -- causaba un 500
"Cannot read properties of undefined (reading 'toLowerCase')" en
cualquier import real. Confirmado en vivo con una prueba de importacion
de 3 productos antes de este fix.

De paso, se agrega un filtro defensivo antes del .map() para que una
categoria/coleccion sin nombre no tumbe el import entero.

.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,12 @@ 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 \
+    GOOGLE_CLIENT_ID=build-only-google-client-id \
+    GOOGLE_CLIENT_SECRET=build-only-google-client-secret \
+    GOOGLE_CALLBACK_URL=http://localhost:9000/auth/customer/google/callback
 
 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"),
@@ -72,5 +157,97 @@ module.exports = defineConfig({
         ],
       },
     },
+    {
+      resolve: "@medusajs/medusa/auth",
+      options: {
+        providers: [
+          // emailpass se declara explicito junto con google -- una vez
+          // que el modulo auth se customiza, la doc no deja claro si el
+          // provider default (emailpass) se sigue registrando solo.
+          {
+            resolve: "@medusajs/medusa/auth-emailpass",
+            id: "emailpass",
+            options: {},
+          },
+          {
+            resolve: "@medusajs/medusa/auth-google",
+            id: "google",
+            options: {
+              clientId: required("GOOGLE_CLIENT_ID"),
+              clientSecret: required("GOOGLE_CLIENT_SECRET"),
+              callbackUrl: required("GOOGLE_CALLBACK_URL"),
+            },
+          },
+        ],
+      },
+    },
+  ],
+
+  // 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/admin/lib/sdk.ts

@@ -0,0 +1,9 @@
+import Medusa from "@medusajs/js-sdk";
+
+// baseUrl "/" -- esta pagina se sirve dentro del mismo dashboard admin
+// (mismo origen que la API), no hace falta apuntar a otra URL. auth
+// "session" reusa la cookie de sesion ya autenticada del dashboard.
+export const sdk = new Medusa({
+  baseUrl: "/",
+  auth: { type: "session" },
+});

workloads/commerce-backend/src/admin/routes/importacion/page.tsx

@@ -0,0 +1,145 @@
+import { defineRouteConfig } from "@medusajs/admin-sdk";
+import { ArrowDownTray, ArrowUpTray, CheckCircleSolid, XCircleSolid } from "@medusajs/icons";
+import { Badge, Button, Container, Heading, Text, toast } from "@medusajs/ui";
+import { useRef, useState } from "react";
+import { sdk } from "../../lib/sdk";
+
+// Importador masivo via CSV -- pensado para cargar varios productos de
+// una sola vez (comprados en Amazon/eBay/etc, no dropshipping
+// automatizado -- ver conversacion sobre por que se descarto raspar
+// tiendas de terceros). Las fotos se descargan del origen y se re-alojan
+// en el mismo MinIO/S3 del NAS que ya usa el resto del catalogo.
+
+type RowResult = {
+  row: number;
+  title: string;
+  ok: boolean;
+  error?: string;
+};
+
+function downloadTemplate() {
+  window.open("/admin/product-import", "_blank");
+}
+
+const ProductImportPanel = () => {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [loading, setLoading] = useState(false);
+  const [results, setResults] = useState<RowResult[] | null>(null);
+
+  async function handleFile(file: File) {
+    const csv = await file.text();
+    setLoading(true);
+    setResults(null);
+    try {
+      const data = await sdk.client.fetch<{ results?: RowResult[]; error?: string }>("/admin/product-import", {
+        method: "post",
+        body: { csv },
+      });
+      if (data.error) {
+        toast.error("No se pudo procesar el archivo", { description: data.error });
+        return;
+      }
+      setResults(data.results ?? []);
+      const okCount = data.results?.filter((r) => r.ok).length ?? 0;
+      const failCount = (data.results?.length ?? 0) - okCount;
+      if (failCount === 0) {
+        toast.success(`${okCount} productos importados`);
+      } else {
+        toast.warning(`${okCount} importados, ${failCount} con error`, {
+          description: "Revisa el detalle abajo.",
+        });
+      }
+    } catch (error) {
+      toast.error("No se pudo procesar el archivo", { description: (error as Error).message });
+    } finally {
+      setLoading(false);
+      if (inputRef.current) inputRef.current.value = "";
+    }
+  }
+
+  return (
+    <Container className="divide-y p-0">
+      <div className="flex items-center justify-between px-6 py-4">
+        <div>
+          <Heading level="h2">Importación de productos</Heading>
+          <Text size="small" className="text-ui-fg-subtle">
+            Carga varios productos a la vez desde un archivo CSV, con fotos, descripción y precio.
+          </Text>
+        </div>
+        <div className="flex gap-2">
+          <Button size="small" variant="secondary" onClick={downloadTemplate}>
+            <ArrowDownTray />
+            Descargar plantilla
+          </Button>
+          <Button size="small" variant="primary" isLoading={loading} onClick={() => inputRef.current?.click()}>
+            <ArrowUpTray />
+            Subir CSV
+          </Button>
+          <input
+            ref={inputRef}
+            type="file"
+            accept=".csv,text/csv"
+            className="hidden"
+            onChange={(event) => {
+              const file = event.target.files?.[0];
+              if (file) handleFile(file);
+            }}
+          />
+        </div>
+      </div>
+
+      <div className="px-6 py-4">
+        <Text size="small" className="text-ui-fg-subtle">
+          Columnas: <code>titulo, descripcion, precio, categoria, coleccion, cantidad, fotos</code>. Varias fotos se
+          separan con <code>;</code> dentro de la misma celda. <code>categoria</code>/<code>coleccion</code> deben
+          escribirse igual que en la tienda o se dejan vacías. Cada foto se descarga y se guarda en el almacenamiento
+          propio de la tienda (no queda enlazada al sitio de origen).
+        </Text>
+      </div>
+
+      {results && (
+        <div className="px-6 py-4">
+          <table className="w-full text-sm">
+            <thead>
+              <tr className="border-b text-left text-ui-fg-subtle">
+                <th className="w-10 py-2" />
+                <th className="py-2 font-medium">Fila</th>
+                <th className="py-2 font-medium">Producto</th>
+                <th className="py-2 font-medium">Detalle</th>
+              </tr>
+            </thead>
+            <tbody>
+              {results.map((result) => (
+                <tr key={result.row} className="border-b last:border-0">
+                  <td className="py-2">
+                    {result.ok ? (
+                      <CheckCircleSolid className="text-ui-tag-green-icon" />
+                    ) : (
+                      <XCircleSolid className="text-ui-tag-red-icon" />
+                    )}
+                  </td>
+                  <td className="py-2">{result.row}</td>
+                  <td className="py-2">{result.title}</td>
+                  <td className="py-2">
+                    {result.ok ? (
+                      <Badge color="green">Importado</Badge>
+                    ) : (
+                      <span className="text-rose-600">{result.error}</span>
+                    )}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )}
+    </Container>
+  );
+};
+
+export const config = defineRouteConfig({
+  label: "Importación",
+  icon: ArrowUpTray,
+});
+
+export default ProductImportPanel;

workloads/commerce-backend/src/admin/routes/inventario/page.tsx

@@ -0,0 +1,194 @@
+import { defineRouteConfig } from "@medusajs/admin-sdk";
+import { Buildings } from "@medusajs/icons";
+import { Badge, Button, Checkbox, Container, Heading, Input, Switch, Text, toast } from "@medusajs/ui";
+import { useEffect, useState } from "react";
+import { sdk } from "../../lib/sdk";
+
+// Panel simplificado para alguien no tecnico (la esposa del dueno del
+// negocio) -- una fila por producto (este catalogo es 1 variante por
+// producto, confirmado en vivo), switch para activar seguimiento de
+// stock y un input de cantidad que guarda solo. La vista nativa de
+// Medusa Admin (Inventory) sigue disponible para el dueno, esto no la
+// reemplaza, es un atajo.
+
+const LOW_STOCK_THRESHOLD = 5;
+
+type Row = {
+  productId: string;
+  variantId: string | null;
+  title: string;
+  thumbnail: string | null;
+  sku: string | null;
+  managed: boolean;
+  quantity: number;
+};
+
+async function fetchRows(): Promise<Row[]> {
+  const data = await sdk.client.fetch<{ rows: Row[] }>("/admin/inventory-panel");
+  return data.rows;
+}
+
+async function saveRow(row: { productId: string; variantId: string; managed?: boolean; quantity?: number }) {
+  await sdk.client.fetch("/admin/inventory-panel", { method: "post", body: row });
+}
+
+const InventoryPanel = () => {
+  const [rows, setRows] = useState<Row[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [selected, setSelected] = useState<Set<string>>(new Set());
+  const [savingId, setSavingId] = useState<string | null>(null);
+
+  useEffect(() => {
+    fetchRows().then((data) => {
+      setRows(data);
+      setLoading(false);
+    });
+  }, []);
+
+  function toggleSelected(productId: string, checked: boolean) {
+    setSelected((prev) => {
+      const next = new Set(prev);
+      if (checked) next.add(productId);
+      else next.delete(productId);
+      return next;
+    });
+  }
+
+  async function updateManaged(row: Row, managed: boolean) {
+    if (!row.variantId) return;
+    setSavingId(row.productId);
+    try {
+      await saveRow({ productId: row.productId, variantId: row.variantId, managed });
+      setRows((prev) =>
+        prev.map((r) => (r.productId === row.productId ? { ...r, managed } : r)),
+      );
+    } catch {
+      toast.error("No se pudo guardar", { description: row.title });
+    } finally {
+      setSavingId(null);
+    }
+  }
+
+  async function updateQuantity(row: Row, quantity: number) {
+    if (!row.variantId || Number.isNaN(quantity) || quantity < 0) return;
+    setSavingId(row.productId);
+    try {
+      await saveRow({ productId: row.productId, variantId: row.variantId, quantity });
+      setRows((prev) =>
+        prev.map((r) => (r.productId === row.productId ? { ...r, quantity } : r)),
+      );
+      toast.success("Stock actualizado", { description: row.title });
+    } catch {
+      toast.error("No se pudo guardar", { description: row.title });
+    } finally {
+      setSavingId(null);
+    }
+  }
+
+  async function bulkSetManaged(managed: boolean) {
+    const targets = rows.filter((r) => selected.has(r.productId) && r.variantId);
+    for (const row of targets) {
+      await updateManaged(row, managed);
+    }
+    setSelected(new Set());
+  }
+
+  return (
+    <Container className="divide-y p-0">
+      <div className="flex items-center justify-between px-6 py-4">
+        <div>
+          <Heading level="h2">Inventario</Heading>
+          <Text size="small" className="text-ui-fg-subtle">
+            Activa el seguimiento de stock y ajusta la cantidad disponible por producto.
+          </Text>
+        </div>
+        {selected.size > 0 && (
+          <div className="flex gap-2">
+            <Button size="small" variant="secondary" onClick={() => bulkSetManaged(true)}>
+              Activar seguimiento ({selected.size})
+            </Button>
+            <Button size="small" variant="secondary" onClick={() => bulkSetManaged(false)}>
+              Desactivar seguimiento
+            </Button>
+          </div>
+        )}
+      </div>
+
+      {loading ? (
+        <div className="px-6 py-8">
+          <Text className="text-ui-fg-subtle">Cargando…</Text>
+        </div>
+      ) : (
+        <div className="overflow-x-auto">
+          <table className="w-full text-sm">
+            <thead>
+              <tr className="border-b text-left text-ui-fg-subtle">
+                <th className="w-10 px-6 py-3" />
+                <th className="px-3 py-3 font-medium">Producto</th>
+                <th className="px-3 py-3 font-medium">SKU</th>
+                <th className="px-3 py-3 font-medium">Trackear stock</th>
+                <th className="px-3 py-3 font-medium">Cantidad disponible</th>
+                <th className="px-3 py-3 font-medium" />
+              </tr>
+            </thead>
+            <tbody>
+              {rows.map((row) => (
+                <tr key={row.productId} className="border-b last:border-0">
+                  <td className="px-6 py-3">
+                    <Checkbox
+                      checked={selected.has(row.productId)}
+                      onCheckedChange={(checked) => toggleSelected(row.productId, checked === true)}
+                    />
+                  </td>
+                  <td className="flex items-center gap-3 px-3 py-3">
+                    {row.thumbnail ? (
+                      <img src={row.thumbnail} alt="" className="size-8 rounded object-cover" />
+                    ) : (
+                      <div className="size-8 rounded bg-ui-bg-subtle" />
+                    )}
+                    <Text>{row.title}</Text>
+                  </td>
+                  <td className="px-3 py-3">
+                    <Text className="text-ui-fg-subtle">{row.sku ?? "—"}</Text>
+                  </td>
+                  <td className="px-3 py-3">
+                    <Switch
+                      checked={row.managed}
+                      disabled={savingId === row.productId}
+                      onCheckedChange={(checked) => updateManaged(row, checked)}
+                    />
+                  </td>
+                  <td className="px-3 py-3">
+                    <Input
+                      type="number"
+                      min={0}
+                      defaultValue={row.quantity}
+                      disabled={!row.managed || savingId === row.productId}
+                      className="w-24"
+                      onBlur={(event) => {
+                        const value = Number(event.target.value);
+                        if (value !== row.quantity) updateQuantity(row, value);
+                      }}
+                    />
+                  </td>
+                  <td className="px-3 py-3">
+                    {row.managed && row.quantity <= LOW_STOCK_THRESHOLD && (
+                      <Badge color="red">Stock bajo</Badge>
+                    )}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )}
+    </Container>
+  );
+};
+
+export const config = defineRouteConfig({
+  label: "Inventario",
+  icon: Buildings,
+});
+
+export default InventoryPanel;

workloads/commerce-backend/src/api/admin/inventory-panel/route.ts

@@ -0,0 +1,152 @@
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework";
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils";
+import {
+  createInventoryItemsWorkflow,
+  updateInventoryLevelsWorkflow,
+  updateProductVariantsWorkflow,
+} from "@medusajs/medusa/core-flows";
+import { attachInventoryItemToVariantWorkflow } from "../../../workflows/attach-inventory-item-to-variant";
+
+// Panel simplificado de inventario (pensado para un usuario no tecnico,
+// no reemplaza la vista nativa de Medusa Admin -- ver ADR/memoria del
+// bug de Firefox Android, tema aparte). Un producto = una variante en
+// este catalogo real (confirmado en vivo contra /store/products antes
+// de asumirlo), asi que la tabla trabaja a nivel de producto.
+
+const PRODUCT_FIELDS = [
+  "id",
+  "title",
+  "thumbnail",
+  "status",
+  "variants.id",
+  "variants.sku",
+  "variants.manage_inventory",
+  "variants.inventory_items.inventory_item_id",
+  "variants.inventory_items.inventory.location_levels.id",
+  "variants.inventory_items.inventory.location_levels.location_id",
+  "variants.inventory_items.inventory.location_levels.stocked_quantity",
+];
+
+async function defaultLocationId(req: MedusaRequest): Promise<string | null> {
+  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY);
+  const { data: locations = [] } = await query.graph({
+    entity: "stock_location",
+    fields: ["id"],
+  });
+  return locations[0]?.id ?? null;
+}
+
+export async function GET(req: MedusaRequest, res: MedusaResponse) {
+  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY);
+  const locationId = await defaultLocationId(req);
+
+  const { data: products = [] } = await query.graph({
+    entity: "product",
+    fields: PRODUCT_FIELDS,
+  });
+
+  const rows = products.map((product) => {
+    const variant = product.variants?.[0];
+    const inventoryItem = variant?.inventory_items?.[0];
+    const level = inventoryItem?.inventory?.location_levels?.find(
+      (candidate) => candidate?.location_id === locationId,
+    );
+    return {
+      productId: product.id,
+      variantId: variant?.id ?? null,
+      title: product.title,
+      thumbnail: product.thumbnail,
+      status: product.status,
+      sku: variant?.sku ?? null,
+      managed: variant?.manage_inventory ?? false,
+      quantity: level?.stocked_quantity ?? 0,
+    };
+  });
+
+  res.json({ rows, locationId });
+}
+
+type PanelUpdateBody = {
+  productId: string;
+  variantId: string;
+  managed?: boolean;
+  quantity?: number;
+};
+
+export async function POST(req: MedusaRequest<PanelUpdateBody>, res: MedusaResponse) {
+  const { productId, variantId, managed, quantity } = req.body;
+  if (!productId || !variantId) {
+    res.status(400).json({ error: "productId y variantId son obligatorios" });
+    return;
+  }
+
+  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY);
+  const locationId = await defaultLocationId(req);
+  if (!locationId) {
+    res.status(400).json({ error: "No hay una bodega (stock location) configurada" });
+    return;
+  }
+
+  const { data: products = [] } = await query.graph({
+    entity: "product",
+    fields: PRODUCT_FIELDS,
+    filters: { id: productId },
+  });
+  const variant = products[0]?.variants?.find((v: { id: string }) => v.id === variantId);
+  const inventoryItem = variant?.inventory_items?.[0];
+  let inventoryItemId: string | undefined = inventoryItem?.inventory_item_id;
+
+  if (managed === true && !inventoryItemId) {
+    // Primera vez que se activa el seguimiento para esta variante -- no
+    // trae InventoryItem todavia (confirmado en vivo: togglear
+    // manage_inventory=true en una variante existente NO crea uno solo,
+    // a diferencia de crear un producto nuevo con manage_inventory
+    // desde el inicio). Se crea con el nivel de stock inicial y se
+    // vincula aparte.
+    const { result: items } = await createInventoryItemsWorkflow(req.scope).run({
+      input: {
+        items: [
+          {
+            title: variant?.sku ? undefined : products[0]?.title,
+            sku: variant?.sku ?? undefined,
+            location_levels: [{ location_id: locationId, stocked_quantity: quantity ?? 0 }],
+          },
+        ],
+      },
+    });
+    inventoryItemId = items[0]?.id;
+    if (inventoryItemId) {
+      await attachInventoryItemToVariantWorkflow(req.scope).run({
+        input: { inventoryItemId, variantId },
+      });
+    }
+    await updateProductVariantsWorkflow(req.scope).run({
+      input: { product_variants: [{ id: variantId, manage_inventory: true }] },
+    });
+  } else {
+    if (typeof managed === "boolean") {
+      await updateProductVariantsWorkflow(req.scope).run({
+        input: { product_variants: [{ id: variantId, manage_inventory: managed }] },
+      });
+    }
+    if (typeof quantity === "number" && inventoryItemId) {
+      const level = inventoryItem?.inventory?.location_levels?.find(
+        (candidate) => candidate?.location_id === locationId,
+      );
+      await updateInventoryLevelsWorkflow(req.scope).run({
+        input: {
+          updates: [
+            {
+              id: level?.id,
+              inventory_item_id: inventoryItemId,
+              location_id: locationId,
+              stocked_quantity: quantity,
+            },
+          ],
+        },
+      });
+    }
+  }
+
+  res.json({ ok: true });
+}

workloads/commerce-backend/src/api/admin/product-import/route.ts

@@ -0,0 +1,229 @@
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework";
+import { Modules } from "@medusajs/framework/utils";
+import type {
+  IFulfillmentModuleService,
+  IProductModuleService,
+  ISalesChannelModuleService,
+  IStockLocationService,
+} from "@medusajs/framework/types";
+import {
+  createInventoryItemsWorkflow,
+  createProductsWorkflow,
+  uploadFilesWorkflow,
+} from "@medusajs/medusa/core-flows";
+import { csvRowsToObjects, parseCsv } from "../../../lib/csv";
+
+// Importador masivo de productos via CSV -- para alguien que compra
+// producto fisico en Amazon/eBay/etc. y quiere cargarlo rapido a la
+// tienda, no para dropshipping automatizado (ver conversacion: se evaluo
+// y se descarto raspar catalogos de terceros sin autorizacion). Cada
+// fila se procesa independiente (una foto rota o categoria mal escrita
+// no tumba el resto del archivo).
+//
+// Las fotos se descargan del origen y se re-alojan en el mismo
+// MinIO/S3 que ya usa el resto del catalogo (uploadFilesWorkflow ->
+// mismo File Module Provider de medusa-config.ts, ya corre en el NAS),
+// bajo el prefijo import-products/ para separarlas de ari-products/
+// (subidas manuales desde el Admin).
+
+const MAX_IMAGE_BYTES = 8 * 1024 * 1024;
+const IMAGE_FETCH_TIMEOUT_MS = 15000;
+const OPTION_TITLE = "Presentación";
+const DEFAULT_VARIANT_VALUE = "Estandar";
+
+type ImportRow = {
+  titulo: string;
+  descripcion: string;
+  precio: string;
+  categoria: string;
+  coleccion: string;
+  cantidad: string;
+  fotos: string;
+};
+
+type RowResult = {
+  row: number;
+  title: string;
+  ok: boolean;
+  error?: string;
+};
+
+function extensionFromContentType(contentType: string | null, url: string): string {
+  if (contentType?.includes("png")) return "png";
+  if (contentType?.includes("webp")) return "webp";
+  if (contentType?.includes("gif")) return "gif";
+  if (contentType?.includes("jpeg") || contentType?.includes("jpg")) return "jpg";
+  const match = url.match(/\.(jpe?g|png|webp|gif)(?:\?|$)/i);
+  return match ? match[1].toLowerCase().replace("jpeg", "jpg") : "jpg";
+}
+
+async function downloadImageAsBase64(url: string): Promise<{ content: string; mimeType: string; extension: string }> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), IMAGE_FETCH_TIMEOUT_MS);
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    if (!response.ok) {
+      throw new Error(`No se pudo descargar la imagen (${response.status})`);
+    }
+    const contentType = response.headers.get("content-type");
+    const buffer = Buffer.from(await response.arrayBuffer());
+    if (buffer.byteLength > MAX_IMAGE_BYTES) {
+      throw new Error(`Imagen supera ${MAX_IMAGE_BYTES / 1024 / 1024}MB`);
+    }
+    const extension = extensionFromContentType(contentType, url);
+    return {
+      content: buffer.toString("base64"),
+      mimeType: contentType?.split(";")[0] ?? `image/${extension === "jpg" ? "jpeg" : extension}`,
+      extension,
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export async function GET(req: MedusaRequest, res: MedusaResponse) {
+  // Plantilla descargable -- misma fuente de verdad que valida el POST,
+  // asi que las columnas nunca quedan desincronizadas entre lo que se
+  // ofrece descargar y lo que realmente se procesa.
+  const header = "titulo,descripcion,precio,categoria,coleccion,cantidad,fotos";
+  const example =
+    '"Muñeco Buzz Lightyear","Figura articulada de 30cm, edición coleccionista.",89900,"Figuras de accion","Toy Story",3,"https://ejemplo.com/foto1.jpg;https://ejemplo.com/foto2.jpg"';
+  const csv = `${header}\n${example}\n`;
+  res.setHeader("Content-Type", "text/csv; charset=utf-8");
+  res.setHeader("Content-Disposition", 'attachment; filename="plantilla-importacion.csv"');
+  res.send(csv);
+}
+
+export async function POST(req: MedusaRequest<{ csv: string }>, res: MedusaResponse) {
+  const csvText = req.body?.csv;
+  if (!csvText || typeof csvText !== "string") {
+    res.status(400).json({ error: "Falta el contenido CSV" });
+    return;
+  }
+
+  const rows = csvRowsToObjects(parseCsv(csvText)) as unknown as ImportRow[];
+  if (rows.length === 0) {
+    res.status(400).json({ error: "El archivo no tiene filas de datos" });
+    return;
+  }
+
+  const stockLocationService = req.scope.resolve<IStockLocationService>(Modules.STOCK_LOCATION);
+  const fulfillmentService = req.scope.resolve<IFulfillmentModuleService>(Modules.FULFILLMENT);
+  const salesChannelService = req.scope.resolve<ISalesChannelModuleService>(Modules.SALES_CHANNEL);
+  const productService = req.scope.resolve<IProductModuleService>(Modules.PRODUCT);
+
+  const [locations, shippingProfiles, salesChannels, categories, collections] = await Promise.all([
+    stockLocationService.listStockLocations({}),
+    fulfillmentService.listShippingProfiles({}),
+    salesChannelService.listSalesChannels({}),
+    // select explicito -- sin el, name/title llegaban undefined (el
+    // default de estos module services no siempre trae todos los
+    // escalares, a diferencia de la capa HTTP del Admin API, confirmado
+    // en vivo: la ruta /admin/product-categories con fields=id,name si
+    // los trae completos).
+    productService.listProductCategories({}, { select: ["id", "name"] }),
+    productService.listProductCollections({}, { select: ["id", "title"] }),
+  ]);
+
+  const locationId = locations[0]?.id;
+  const shippingProfileId = shippingProfiles.find((p) => p.type === "default")?.id ?? shippingProfiles[0]?.id;
+  const salesChannelId = salesChannels[0]?.id;
+
+  if (!locationId || !shippingProfileId || !salesChannelId) {
+    res.status(400).json({
+      error: "Faltan datos base de la tienda (bodega, perfil de envío o canal de venta)",
+    });
+    return;
+  }
+
+  const categoryByName = new Map(
+    categories.filter((c) => c.name).map((c) => [c.name.toLowerCase().trim(), c.id]),
+  );
+  const collectionByName = new Map(
+    collections.filter((c) => c.title).map((c) => [c.title.toLowerCase().trim(), c.id]),
+  );
+
+  const results: RowResult[] = [];
+
+  for (let index = 0; index < rows.length; index++) {
+    const rowNumber = index + 2; // +1 header, +1 base 1
+    const row = rows[index];
+    const title = row.titulo?.trim();
+    try {
+      if (!title) throw new Error("Falta el título");
+      const price = Number(row.precio);
+      if (!Number.isFinite(price) || price <= 0) throw new Error("Precio inválido");
+
+      const imageUrls = (row.fotos ?? "")
+        .split(";")
+        .map((u) => u.trim())
+        .filter(Boolean);
+      if (imageUrls.length === 0) throw new Error("Falta al menos una foto");
+
+      const downloaded = await Promise.all(imageUrls.map((url) => downloadImageAsBase64(url)));
+      const { result: uploadedFiles } = await uploadFilesWorkflow(req.scope).run({
+        input: {
+          files: downloaded.map((file, i) => ({
+            filename: `import-products/${Date.now()}-${index}-${i}.${file.extension}`,
+            mimeType: file.mimeType,
+            content: file.content,
+            access: "public" as const,
+          })),
+        },
+      });
+
+      const quantity = Number(row.cantidad);
+      const { result: inventoryItems } = await createInventoryItemsWorkflow(req.scope).run({
+        input: {
+          items: [
+            {
+              title,
+              location_levels: [
+                { location_id: locationId, stocked_quantity: Number.isFinite(quantity) && quantity >= 0 ? quantity : 1 },
+              ],
+            },
+          ],
+        },
+      });
+      const inventoryItemId = inventoryItems[0]?.id;
+      if (!inventoryItemId) throw new Error("No se pudo crear el registro de inventario");
+
+      const categoryId = row.categoria ? categoryByName.get(row.categoria.toLowerCase().trim()) : undefined;
+      const collectionId = row.coleccion ? collectionByName.get(row.coleccion.toLowerCase().trim()) : undefined;
+
+      await createProductsWorkflow(req.scope).run({
+        input: {
+          products: [
+            {
+              title,
+              description: row.descripcion || undefined,
+              status: "published",
+              thumbnail: uploadedFiles[0]?.url,
+              images: uploadedFiles.map((f) => ({ url: f.url })),
+              category_ids: categoryId ? [categoryId] : undefined,
+              collection_id: collectionId,
+              shipping_profile_id: shippingProfileId,
+              sales_channels: [{ id: salesChannelId }],
+              options: [{ title: OPTION_TITLE, values: [DEFAULT_VARIANT_VALUE] }],
+              variants: [
+                {
+                  title: DEFAULT_VARIANT_VALUE,
+                  options: { [OPTION_TITLE]: DEFAULT_VARIANT_VALUE },
+                  manage_inventory: true,
+                  inventory_items: [{ inventory_item_id: inventoryItemId }],
+                  prices: [{ amount: price, currency_code: "cop" }],
+                },
+              ],
+            },
+          ],
+        },
+      });
+
+      results.push({ row: rowNumber, title, ok: true });
+    } catch (error) {
+      results.push({ row: rowNumber, title: title || `Fila ${rowNumber}`, ok: false, error: (error as Error).message });
+    }
+  }
+
+  res.json({ results });
+}

workloads/commerce-backend/src/api/middlewares.ts

@@ -0,0 +1,22 @@
+import { defineMiddlewares } from "@medusajs/medusa"
+
+// GET /store/products descarta en silencio la relacion `categories`
+// aunque `/admin/products` si la expone -- confirmado en vivo en la
+// auditoria de Fase 5 (ver docs/decisiones/0004-evaluacion-stack-multi-categoria.md).
+// Este es el patron oficial de Medusa v2 para ampliar los campos
+// permitidos de una ruta core restringida (middleware global sobre
+// req.allowed), no un query-config custom:
+// https://docs.medusajs.com/learn/fundamentals/api-routes/retrieve-custom-links
+export default defineMiddlewares({
+  routes: [
+    {
+      matcher: "/store/products",
+      middlewares: [
+        (req, res, next) => {
+          ;(req.allowed ??= []).push("categories")
+          next()
+        },
+      ],
+    },
+  ],
+})

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/commerce-backend/src/lib/csv.ts

@@ -0,0 +1,70 @@
+// Parser CSV minimo (RFC4180: campos entre comillas, comillas escapadas
+// como "", comas y saltos de linea dentro de campos citados) -- se evita
+// sumar una dependencia nueva (papaparse/csv-parse) para un formato que
+// nosotros mismos controlamos via la plantilla descargable.
+export function parseCsv(text: string): string[][] {
+  const rows: string[][] = [];
+  let row: string[] = [];
+  let field = "";
+  let inQuotes = false;
+  let i = 0;
+  const normalized = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+
+  while (i < normalized.length) {
+    const char = normalized[i];
+    if (inQuotes) {
+      if (char === '"') {
+        if (normalized[i + 1] === '"') {
+          field += '"';
+          i += 2;
+          continue;
+        }
+        inQuotes = false;
+        i += 1;
+        continue;
+      }
+      field += char;
+      i += 1;
+      continue;
+    }
+    if (char === '"') {
+      inQuotes = true;
+      i += 1;
+      continue;
+    }
+    if (char === ",") {
+      row.push(field);
+      field = "";
+      i += 1;
+      continue;
+    }
+    if (char === "\n") {
+      row.push(field);
+      rows.push(row);
+      row = [];
+      field = "";
+      i += 1;
+      continue;
+    }
+    field += char;
+    i += 1;
+  }
+  if (field.length > 0 || row.length > 0) {
+    row.push(field);
+    rows.push(row);
+  }
+  return rows.filter((r) => r.some((cell) => cell.trim().length > 0));
+}
+
+export function csvRowsToObjects(rows: string[][]): Record<string, string>[] {
+  const [header, ...body] = rows;
+  if (!header) return [];
+  const keys = header.map((h) => h.trim().toLowerCase());
+  return body.map((cols) => {
+    const obj: Record<string, string> = {};
+    keys.forEach((key, index) => {
+      obj[key] = (cols[index] ?? "").trim();
+    });
+    return obj;
+  });
+}

workloads/commerce-backend/src/workflows/attach-inventory-item-to-variant.ts

@@ -0,0 +1,21 @@
+import { createWorkflow, WorkflowResponse } from "@medusajs/framework/workflows-sdk";
+import { attachInventoryItemToVariants } from "@medusajs/medusa/core-flows";
+
+// attachInventoryItemToVariants es un step suelto (no un workflow
+// exportado) -- confirmado leyendo el .js real instalado
+// (@medusajs/core-flows/dist/inventory/steps/attach-inventory-items.js):
+// internamente resuelve ContainerRegistrationKeys.LINK y crea el link
+// Product<->Inventory. El campo "tag" del input es el variant_id (nombre
+// generico del step, no documentado con ese detalle).
+type Input = { inventoryItemId: string; variantId: string };
+
+export const attachInventoryItemToVariantWorkflow = createWorkflow(
+  "attach-inventory-item-to-variant",
+  (input: Input) => {
+    return new WorkflowResponse(
+      attachInventoryItemToVariants([
+        { inventoryItemId: input.inventoryItemId, tag: input.variantId },
+      ]),
+    );
+  },
+);

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.123
+          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/customer/google/callback/route.ts

@@ -0,0 +1,14 @@
+import { handleGoogleCallback } from "@/lib/headless/providers/medusa-customer";
+
+export async function POST(request: Request) {
+  const { code, state } = await request.json();
+  if (!code || !state) {
+    return Response.json({ error: "Faltan parámetros de Google" }, { status: 400 });
+  }
+  try {
+    const customer = await handleGoogleCallback(code, state);
+    return Response.json(customer);
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 400 });
+  }
+}

workloads/ecommerce/app/api/customer/google/start/route.ts

@@ -0,0 +1,14 @@
+import { getGoogleAuthUrl } from "@/lib/headless/providers/medusa-customer";
+
+// Navegacion de pagina completa (no fetch/XHR) -- el boton "Continuar
+// con Google" enlaza directo aca, el browser sigue el 302 hasta la
+// pantalla real de consentimiento de Google.
+export async function GET(request: Request) {
+  try {
+    const location = await getGoogleAuthUrl();
+    return Response.redirect(location);
+  } catch (error) {
+    const message = encodeURIComponent((error as Error).message);
+    return Response.redirect(new URL(`/?googleAuthError=${message}`, request.url));
+  }
+}

workloads/ecommerce/app/api/customer/login/route.ts

@@ -0,0 +1,14 @@
+import { loginCustomer } from "@/lib/headless/providers/medusa-customer";
+
+export async function POST(request: Request) {
+  const { email, password } = await request.json();
+  if (!email || !password) {
+    return Response.json({ error: "Correo y contraseña son obligatorios" }, { status: 400 });
+  }
+  try {
+    const customer = await loginCustomer(email, password);
+    return Response.json(customer);
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 400 });
+  }
+}

workloads/ecommerce/app/api/customer/me/route.ts

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

workloads/ecommerce/app/api/customer/register/route.ts

@@ -0,0 +1,14 @@
+import { registerCustomer } from "@/lib/headless/providers/medusa-customer";
+
+export async function POST(request: Request) {
+  const { email, password, firstName, lastName } = await request.json();
+  if (!email || !password || !firstName || !lastName) {
+    return Response.json({ error: "Faltan campos obligatorios" }, { status: 400 });
+  }
+  try {
+    const customer = await registerCustomer(email, password, firstName, lastName);
+    return Response.json(customer);
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 400 });
+  }
+}

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/auth/google/callback/page.tsx

@@ -0,0 +1,10 @@
+import { Suspense } from "react";
+import { GoogleCallbackClient } from "@/components/account/google-callback-client";
+
+export default function GoogleCallbackPage() {
+  return (
+    <Suspense>
+      <GoogleCallbackClient />
+    </Suspense>
+  );
+}

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.220
           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.220
           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/account/account-dialog.tsx

@@ -0,0 +1,99 @@
+"use client";
+
+import Link from "next/link";
+import { LogOut, MessageCircle, PackageCheck } from "lucide-react";
+import { type FormEvent, useState } from "react";
+import { Button } from "@/components/ui/button";
+import { Dialog, DialogContent } from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { useCustomerStore } from "@/store/customer-store";
+
+type Mode = "login" | "register";
+
+function GoogleIcon() {
+  return (
+    <svg viewBox="0 0 48 48" className="size-4" aria-hidden="true">
+      <path fill="#FFC107" d="M43.6 20.5H42V20H24v8h11.3c-1.6 4.7-6.1 8-11.3 8-6.6 0-12-5.4-12-12s5.4-12 12-12c3.1 0 5.8 1.1 8 3l6-6C34 5.1 29.3 3 24 3 12.4 3 3 12.4 3 24s9.4 21 21 21 21-9.4 21-21c0-1.4-.1-2.7-.4-3.5z" />
+      <path fill="#FF3D00" d="M6.3 14.7l6.6 4.8C14.6 15.9 18.9 13 24 13c3.1 0 5.8 1.1 8 3l6-6C34 5.1 29.3 3 24 3 16.1 3 9.3 7.6 6.3 14.7z" />
+      <path fill="#4CAF50" d="M24 45c5.2 0 9.9-2 13.4-5.2l-6.2-5.2c-2 1.5-4.6 2.4-7.2 2.4-5.2 0-9.6-3.3-11.3-8l-6.5 5C9.2 40.3 16 45 24 45z" />
+      <path fill="#1976D2" d="M43.6 20.5H42V20H24v8h11.3c-.8 2.3-2.2 4.3-4.1 5.6l6.2 5.2C41.4 35.9 45 30.5 45 24c0-1.4-.1-2.7-.4-3.5z" />
+    </svg>
+  );
+}
+
+export function AccountDialog({ open, onOpenChange }: { open: boolean; onOpenChange: (open: boolean) => void }) {
+  const { customer, hasHydrated, loading, error, login, register, logout } = useCustomerStore();
+  const [mode, setMode] = useState<Mode>("login");
+  const [form, setForm] = useState({ email: "", password: "", firstName: "", lastName: "" });
+
+  async function submit(event: FormEvent) {
+    event.preventDefault();
+    const ok = mode === "login"
+      ? await login(form.email, form.password)
+      : await register(form.email, form.password, form.firstName, form.lastName);
+    if (ok) setForm({ email: "", password: "", firstName: "", lastName: "" });
+  }
+
+  const isLoggedIn = hasHydrated && customer !== null;
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="max-w-lg p-7">
+        <div className="pr-10">
+          {isLoggedIn ? (
+            <>
+              <span className="text-xs font-black uppercase tracking-[.16em] text-ari-coral">Tu cuenta</span>
+              <h2 className="mt-3 text-3xl font-black">Hola, {customer.firstName ?? customer.email}</h2>
+              <p className="mt-3 text-sm leading-6 text-slate-600">{customer.email}</p>
+              <div className="mt-6 grid gap-3">
+                <Button asChild variant="outline"><Link href="/catalog" onClick={() => onOpenChange(false)}><PackageCheck />Ver mis opciones de compra</Link></Button>
+                <Button variant="ghost" onClick={logout}><LogOut className="size-4" />Cerrar sesión</Button>
+              </div>
+            </>
+          ) : (
+            <>
+              <span className="text-xs font-black uppercase tracking-[.16em] text-ari-coral">Atención personalizada</span>
+              <h2 className="mt-3 text-3xl font-black">{mode === "login" ? "Inicia sesión" : "Crea tu cuenta"}</h2>
+              <form onSubmit={submit} className="mt-5 space-y-3">
+                {mode === "register" && (
+                  <div className="grid gap-3 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 type="email" placeholder="Correo" required value={form.email} onChange={(event) => setForm({ ...form, email: event.target.value })} />
+                <Input type="password" placeholder="Contraseña" required minLength={8} value={form.password} onChange={(event) => setForm({ ...form, password: event.target.value })} />
+                {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 ? "Un momento…" : mode === "login" ? "Iniciar sesión" : "Crear cuenta"}
+                </Button>
+              </form>
+              <div className="mt-3 flex items-center gap-3 text-xs font-bold uppercase tracking-wide text-slate-400">
+                <span className="h-px flex-1 bg-slate-100" />o<span className="h-px flex-1 bg-slate-100" />
+              </div>
+              <Button asChild variant="outline" size="lg" className="mt-3 w-full">
+                <a href="/api/customer/google/start">
+                  <GoogleIcon />Continuar con Google
+                </a>
+              </Button>
+              <button
+                type="button"
+                className="mt-3 text-sm font-bold text-ari-marino hover:underline"
+                onClick={() => setMode(mode === "login" ? "register" : "login")}
+              >
+                {mode === "login" ? "¿No tienes cuenta? Regístrate" : "¿Ya tienes cuenta? Inicia sesión"}
+              </button>
+              <div className="mt-6 border-t border-slate-100 pt-5">
+                <Button asChild variant="outline" className="w-full">
+                  <a href={process.env.NEXT_PUBLIC_WHATSAPP_URL ?? "https://wa.link/rvcqqc"} target="_blank" rel="noopener noreferrer">
+                    <MessageCircle />Hablar con ARI
+                  </a>
+                </Button>
+              </div>
+            </>
+          )}
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}

workloads/ecommerce/components/account/google-callback-client.tsx

@@ -0,0 +1,44 @@
+"use client";
+
+import { useRouter, useSearchParams } from "next/navigation";
+import { useEffect, useRef, useState } from "react";
+import { useCustomerStore } from "@/store/customer-store";
+
+export function GoogleCallbackClient() {
+  const router = useRouter();
+  const searchParams = useSearchParams();
+  const loginWithGoogle = useCustomerStore((state) => state.loginWithGoogle);
+  const [error, setError] = useState<string | null>(null);
+  const ran = useRef(false);
+
+  useEffect(() => {
+    // Guard contra el doble-mount de StrictMode -- el code de Google es
+    // de un solo uso, un segundo intento con el mismo code fallaria.
+    if (ran.current) return;
+    ran.current = true;
+
+    const code = searchParams.get("code");
+    const state = searchParams.get("state");
+    if (!code || !state) {
+      setError("Faltan parámetros de Google en la URL de retorno.");
+      return;
+    }
+
+    loginWithGoogle(code, state).then((ok) => {
+      router.replace(ok ? "/" : "/?googleAuthError=1");
+    });
+  }, [searchParams, loginWithGoogle, router]);
+
+  return (
+    <div className="flex min-h-[60vh] flex-col items-center justify-center gap-3 text-center">
+      {error ? (
+        <>
+          <p className="text-lg font-black text-rose-600">No se pudo iniciar sesión con Google</p>
+          <p className="text-sm text-slate-600">{error}</p>
+        </>
+      ) : (
+        <p className="text-sm font-bold text-slate-600">Conectando con Google…</p>
+      )}
+    </div>
+  );
+}

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,228 @@
+"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 { ciudadesPorDepartamento, departamentos } from "@/lib/data/colombia";
+import { formatMoney } from "@/lib/utils";
+import { useCartStore } from "@/store/cart-store";
+
+const SELECT_CLASS =
+  "h-12 w-full rounded-full border border-slate-200 bg-white px-5 text-sm text-slate-950 outline-none transition focus:border-cyan-500 focus:ring-4 focus:ring-cyan-300/30 disabled:opacity-50";
+
+// 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: "",
+    // Se guarda el id DIVIPOLA seleccionado, no el texto libre -- ver
+    // lib/data/colombia.ts. El nombre real se deriva de este id para
+    // mandarlo a Medusa (que solo espera texto en shipping_address).
+    departmentId: null as number | null,
+    cityId: null as number | null,
+    phone: "",
+    email: "",
+  });
+  const availableCities = form.departmentId ? ciudadesPorDepartamento(form.departmentId) : [];
+  const selectedDepartamento = departamentos.find((departamento) => departamento.id === form.departmentId);
+  const selectedCiudad = availableCities.find((ciudad) => ciudad.id === form.cityId);
+  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 || !selectedCiudad || !selectedDepartamento) return;
+    setLoading(true);
+    setError(null);
+    try {
+      const cart = await postJson("/api/cart/address", {
+        cartId,
+        firstName: form.firstName,
+        lastName: form.lastName,
+        address1: form.address1,
+        city: selectedCiudad.name,
+        province: selectedDepartamento.name,
+        phone: form.phone,
+        email: form.email,
+      });
+      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}, ${selectedCiudad?.name ?? ""}${selectedDepartamento ? `, ${selectedDepartamento.name}` : ""}\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">
+              <select
+                required
+                value={form.departmentId ?? ""}
+                onChange={(event) => setForm({ ...form, departmentId: Number(event.target.value) || null, cityId: null })}
+                className={SELECT_CLASS}
+              >
+                <option value="" disabled>Departamento</option>
+                {departamentos.map((departamento) => <option key={departamento.id} value={departamento.id}>{departamento.name}</option>)}
+              </select>
+              <select
+                required
+                disabled={!form.departmentId}
+                value={form.cityId ?? ""}
+                onChange={(event) => setForm({ ...form, cityId: Number(event.target.value) || null })}
+                className={SELECT_CLASS}
+              >
+                <option value="" disabled>Ciudad</option>
+                {availableCities.map((ciudad) => <option key={ciudad.id} value={ciudad.id}>{ciudad.name}</option>)}
+              </select>
+            </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}, {selectedCiudad?.name}{selectedDepartamento ? `, ${selectedDepartamento.name}` : ""}</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}, {selectedCiudad?.name}{selectedDepartamento ? `, ${selectedDepartamento.name}` : ""}</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,30 @@
 "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, ShoppingCart, UserRound } from "lucide-react";
+import { Suspense, useEffect, useMemo, useRef, useState } from "react";
+import { AccountDialog } from "@/components/account/account-dialog";
 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 { useCustomerStore } from "@/store/customer-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);
@@ -49,36 +35,60 @@ export function Navbar({ products }: { products: Product[] }) {
   const openWishlist = useWishlistStore((state) => state.openWishlist);
   const count = cartHydrated ? items.reduce((sum, item) => sum + item.quantity, 0) : 0;
   const wishlistCount = wishlistHydrated ? wishlistProducts.length : 0;
+  const customer = useCustomerStore((state) => state.customer);
+  const customerHydrated = useCustomerStore((state) => state.hasHydrated);
+  const isLoggedIn = customerHydrated && customer !== null;
+
+  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}>
-              <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>}
+            {/* Antes escondido en mobile (solo alcanzable desde el menu
+                hamburguesa) -- pedido explicito del usuario: visible
+                siempre en el header, con un punto verde cuando hay sesion
+                iniciada (mismo patron que el badge de cantidad del
+                carrito/favoritos, pero de presencia, no de conteo). */}
+            <Button variant="outline" size="icon" aria-label={isLoggedIn ? "Mi cuenta (sesión iniciada)" : "Mi cuenta"} className="relative inline-flex border-slate-300 bg-white text-slate-900 hover:border-ari-coral hover:bg-ari-coral/10" onClick={() => setAccountOpen(true)}>
+              <UserRound />
+              {isLoggedIn && <span className="absolute -right-1 -top-1 size-3 rounded-full border-2 border-white bg-emerald-500" />}
             </Button>
-            <Button variant="magenta" size="icon" onClick={openCart} aria-label={`Carrito con ${count} productos`} className="relative shadow-lg shadow-fuchsia-500/20">
+            <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-ari-marino text-[10px] font-black text-white">{wishlistCount}</span>}
+            </Button>
+            <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 +98,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>
@@ -106,19 +120,7 @@ export function Navbar({ products }: { products: Product[] }) {
         </SheetContent>
       </Sheet>
 
-      <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>
-            <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="outline"><Link href="/catalog" onClick={() => setAccountOpen(false)}><PackageCheck />Ver mis opciones de compra</Link></Button>
-            </div>
-          </div>
-        </DialogContent>
-      </Dialog>
+      <AccountDialog open={accountOpen} onOpenChange={setAccountOpen} />
     </header>
   );
 }
@@ -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,19 @@ 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>;
+  const outOfStock = product.variants[0]?.available === false;
+  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"
+        disabled={outOfStock}
+        onClick={() => addItem(product, product.variants[0]?.id)}
+      >
+        <ShoppingBag />
+        {outOfStock ? "Agotado" : "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,69 @@ 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 outOfStock = selectedVariant?.available === false;
+  const lowStock =
+    !outOfStock &&
+    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">{outOfStock && <Badge className="bg-rose-600 text-white">Agotado</Badge>}{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>
+        {outOfStock && <div className="pointer-events-none absolute inset-0 bg-white/40" />}
+        <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>
+        )}
+        {outOfStock && (
+          <span className="flex items-center gap-1.5 text-xs font-bold text-rose-600"><TriangleAlert className="size-3.5" />Sin stock</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" disabled={outOfStock} onClick={() => addItem(product, selectedVariantId)}><ShoppingBag className="size-4" />{outOfStock ? "Agotado" : "Agregar"}</Button>
+        </div>
       </div>
     </article>
   );

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

@@ -1,14 +1,78 @@
 "use client";
 
-import { CheckCircle2, ShoppingBag, Truck } from "lucide-react";
+import { CheckCircle2, ShoppingBag, TriangleAlert, Truck, XCircle } 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 outOfStock = selectedVariant?.available === false;
+  const lowStock =
+    !outOfStock &&
+    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.available === false ? "opacity-40" : ""}`}
+          >
+            {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"
+        disabled={outOfStock}
+        onClick={() => addItem(product, variantId)}
+      >
+        <ShoppingBag />
+        {outOfStock ? "Agotado" : "Añadir al carrito"}
+      </Button>
+      <div className="mt-5 grid gap-3 rounded-2xl bg-slate-50 p-4 text-sm">
+        {outOfStock ? (
+          <span className="flex items-center gap-2 font-bold text-rose-600">
+            <XCircle className="size-4" />
+            Agotado
+          </span>
+        ) : 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.219
           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/data/co-departamentos.json

@@ -0,0 +1,40 @@
+{
+  "data": [
+    { "id": 5, "name": "Antioquia" },
+    { "id": 8, "name": "Atlántico" },
+    { "id": 11, "name": "Bogotá D.C." },
+    { "id": 13, "name": "Bolívar" },
+    { "id": 15, "name": "Boyacá" },
+    { "id": 17, "name": "Caldas" },
+    { "id": 18, "name": "Caquetá" },
+    { "id": 19, "name": "Cauca" },
+    { "id": 20, "name": "Cesar" },
+    { "id": 23, "name": "Córdoba" },
+    { "id": 25, "name": "Cundinamarca" },
+    { "id": 27, "name": "Chocó" },
+    { "id": 41, "name": "Huila" },
+    { "id": 44, "name": "La Guajira" },
+    { "id": 47, "name": "Magdalena" },
+    { "id": 50, "name": "Meta" },
+    { "id": 52, "name": "Nariño" },
+    { "id": 54, "name": "Norte de Santander" },
+    { "id": 63, "name": "Quindío" },
+    { "id": 66, "name": "Risaralda" },
+    { "id": 68, "name": "Santander" },
+    { "id": 70, "name": "Sucre" },
+    { "id": 73, "name": "Tolima" },
+    { "id": 76, "name": "Valle del Cauca" },
+    { "id": 81, "name": "Arauca" },
+    { "id": 85, "name": "Casanare" },
+    { "id": 86, "name": "Putumayo" },
+    {
+      "id": 88,
+      "name": "Archipiélago de San Andrés, Providencia y Santa Catalina"
+    },
+    { "id": 91, "name": "Amazonas" },
+    { "id": 94, "name": "Guainía" },
+    { "id": 95, "name": "Guaviare" },
+    { "id": 97, "name": "Vaupés" },
+    { "id": 99, "name": "Vichada" }
+  ]
+}

workloads/ecommerce/lib/data/colombia.ts

@@ -0,0 +1,32 @@
+import departamentosData from "./co-departamentos.json";
+import ciudadesData from "./co-ciudades.json";
+
+// Dataset real de DIVIPOLA (Division Politico-Administrativa de Colombia,
+// codigos oficiales del DANE) -- 33 departamentos + 1123 municipios,
+// fuente: proyecto26/colombia (github.com/proyecto26/colombia), verificado
+// contra la codificacion oficial antes de incorporarlo (ej. id 5001 =
+// Medellin, departmentId 5 = Antioquia).
+//
+// Se usan los codigos (no solo los nombres) porque EnvioClick -- la
+// integracion de envios real que reemplazara la tarifa fija de ADR 0009 --
+// va a necesitar identificar la ciudad de forma inequivoca, y las
+// transportadoras colombianas en general referencian ciudades por su
+// codigo DIVIPOLA, no por texto libre.
+
+export interface Departamento {
+  id: number;
+  name: string;
+}
+
+export interface Ciudad {
+  id: number;
+  name: string;
+  departmentId: number;
+}
+
+export const departamentos: Departamento[] = departamentosData.data;
+export const ciudades: Ciudad[] = ciudadesData.data;
+
+export function ciudadesPorDepartamento(departmentId: number): Ciudad[] {
+  return ciudades.filter((ciudad) => ciudad.departmentId === departmentId);
+}

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-customer.ts

@@ -0,0 +1,167 @@
+// Cuentas de cliente reales conectadas a Medusa (Store API), mismo patron
+// que medusa-cart.ts -- server-side, nunca cacheado (auth es estado
+// mutable por sesion, no catalogo).
+//
+// Flujo verificado en vivo (2026-08-29) antes de escribir este archivo,
+// no asumido contra documentacion: registro (auth/customer/emailpass/
+// register) da un token de registro; ese token crea el customer real
+// (POST /store/customers); pero ese token de registro NO sirve como
+// sesion del customer -- hay que loguear de nuevo para obtener el token
+// de sesion real. Mensajes de error exactos confirmados: registro con
+// correo repetido -> 401 "Identity with email already exists"; login con
+// credenciales invalidas -> 401 "Invalid email or password".
+
+export interface CustomerSummary {
+  token: string;
+  id: string;
+  email: string;
+  firstName: string | null;
+  lastName: string | null;
+}
+
+function backendUrl(): string {
+  const value = process.env.MEDUSA_BACKEND_URL;
+  if (!value) {
+    throw new Error("MEDUSA_BACKEND_URL no está configurado.");
+  }
+  return value.replace(/\/$/, "");
+}
+
+async function medusaAuthFetch(
+  path: string,
+  init?: { method?: string; body?: unknown; token?: string },
+): 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 } : {}),
+      ...(init?.token ? { Authorization: `Bearer ${init.token}` } : {}),
+    },
+    body: init?.body ? JSON.stringify(init.body) : undefined,
+    cache: "no-store",
+  });
+
+  const data = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    const message = typeof data.message === "string" ? data.message : `Error ${response.status}`;
+    throw new Error(message);
+  }
+  return data;
+}
+
+type MedusaCustomer = {
+  id: string;
+  email: string;
+  first_name?: string | null;
+  last_name?: string | null;
+};
+
+export async function getCurrentCustomer(token: string): Promise<CustomerSummary> {
+  const data = await medusaAuthFetch("/store/customers/me", { token });
+  const customer = data.customer as MedusaCustomer;
+  return {
+    token,
+    id: customer.id,
+    email: customer.email,
+    firstName: customer.first_name ?? null,
+    lastName: customer.last_name ?? null,
+  };
+}
+
+export async function loginCustomer(email: string, password: string): Promise<CustomerSummary> {
+  let data: Record<string, unknown>;
+  try {
+    data = await medusaAuthFetch("/auth/customer/emailpass", {
+      method: "POST",
+      body: { email, password },
+    });
+  } catch (error) {
+    if ((error as Error).message === "Invalid email or password") {
+      throw new Error("Correo o contraseña incorrectos.");
+    }
+    throw error;
+  }
+  return getCurrentCustomer(data.token as string);
+}
+
+// Flujo Google verificado en vivo (2026-08-29) contra el pod real, no
+// solo contra la doc: GET /auth/customer/google funciona igual que el
+// POST documentado (sin body, no hace falta callback_url -- ya viene de
+// GOOGLE_CALLBACK_URL en el modulo); la respuesta no trae Set-Cookie, o
+// sea que el "state" que Google reenvia en el callback es autocontenido
+// (firmado), no depende de sesion de servidor -- confirmado con un
+// callback con code/state inventados: 401 "No state provided, or
+// session expired" (mismo mensaje que con state ausente, no un error de
+// sesion real). auth/token/refresh confirmado que exige Bearer valido
+// (401 "Unauthorized" con uno invalido, no 404).
+function decodeJwtPayload(token: string): Record<string, unknown> {
+  const payload = token.split(".")[1] ?? "";
+  const base64 = payload.replace(/-/g, "+").replace(/_/g, "/");
+  const json = Buffer.from(base64, "base64").toString("utf-8");
+  return JSON.parse(json || "{}");
+}
+
+export async function getGoogleAuthUrl(): Promise<string> {
+  const data = await medusaAuthFetch("/auth/customer/google");
+  return data.location as string;
+}
+
+export async function handleGoogleCallback(code: string, state: string): Promise<CustomerSummary> {
+  const query = new URLSearchParams({ code, state }).toString();
+  const data = await medusaAuthFetch(`/auth/customer/google/callback?${query}`, { method: "POST" });
+  const initialToken = data.token as string;
+  const payload = decodeJwtPayload(initialToken);
+  const actorId = payload.actor_id as string | undefined;
+
+  if (!actorId) {
+    // Primer login con Google -- todavia no existe el customer real.
+    const userMetadata = (payload.user_metadata as Record<string, unknown> | undefined) ?? {};
+    const email = userMetadata.email as string;
+    const firstName = (userMetadata.given_name as string) ?? (userMetadata.name as string) ?? email.split("@")[0];
+    const lastName = (userMetadata.family_name as string) ?? "";
+    await medusaAuthFetch("/store/customers", {
+      method: "POST",
+      token: initialToken,
+      body: { email, first_name: firstName, last_name: lastName },
+    });
+  }
+
+  // El token del callback (o el de recien crear el customer) todavia no
+  // sirve como sesion final -- hay que refrescarlo, tanto para usuarios
+  // nuevos como para los que ya existian (confirmado contra la doc: los
+  // dos casos convergen en el mismo paso de refresh).
+  const refreshed = await medusaAuthFetch("/auth/token/refresh", { method: "POST", token: initialToken });
+  return getCurrentCustomer(refreshed.token as string);
+}
+
+export async function registerCustomer(
+  email: string,
+  password: string,
+  firstName: string,
+  lastName: string,
+): Promise<CustomerSummary> {
+  let data: Record<string, unknown>;
+  try {
+    data = await medusaAuthFetch("/auth/customer/emailpass/register", {
+      method: "POST",
+      body: { email, password },
+    });
+  } catch (error) {
+    if ((error as Error).message === "Identity with email already exists") {
+      throw new Error("Ese correo ya está registrado — inicia sesión en vez de crear una cuenta nueva.");
+    }
+    throw error;
+  }
+  await medusaAuthFetch("/store/customers", {
+    method: "POST",
+    token: data.token as string,
+    body: { email, first_name: firstName, last_name: lastName },
+  });
+  // El token de registro crea el customer pero no queda como sesion real
+  // -- se loguea de nuevo para obtener el token de sesion (confirmado en
+  // vivo, no documentado explicitamente).
+  return loginCustomer(email, password);
+}

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();
+      },
     },
   ),
 );

workloads/ecommerce/store/customer-store.ts

@@ -0,0 +1,123 @@
+"use client";
+
+import { create } from "zustand";
+import { createJSONStorage, persist } from "zustand/middleware";
+
+// Cuenta de cliente real conectada a Medusa (Store API, via
+// /api/customer/*), mismo patron que cart-store.ts: token + datos basicos
+// persistidos en localStorage, resincronizados contra el servidor al
+// rehidratar (el token puede llevar dias, o haber sido revocado).
+export interface Customer {
+  id: string;
+  email: string;
+  firstName: string | null;
+  lastName: string | null;
+}
+
+interface CustomerState {
+  token: string | null;
+  customer: Customer | null;
+  hasHydrated: boolean;
+  loading: boolean;
+  error: string | null;
+  setHasHydrated: (value: boolean) => void;
+  register: (email: string, password: string, firstName: string, lastName: string) => Promise<boolean>;
+  login: (email: string, password: string) => Promise<boolean>;
+  loginWithGoogle: (code: string, state: string) => Promise<boolean>;
+  logout: () => void;
+  syncCustomer: () => 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();
+}
+
+function toCustomer(data: Record<string, unknown>): Customer {
+  return {
+    id: data.id as string,
+    email: data.email as string,
+    firstName: (data.firstName as string | null) ?? null,
+    lastName: (data.lastName as string | null) ?? null,
+  };
+}
+
+export const useCustomerStore = create<CustomerState>()(
+  persist(
+    (set, get) => ({
+      token: null,
+      customer: null,
+      hasHydrated: false,
+      loading: false,
+      error: null,
+      setHasHydrated: (value) => set({ hasHydrated: value }),
+
+      register: async (email, password, firstName, lastName) => {
+        set({ loading: true, error: null });
+        const result = await postJson("/api/customer/register", { email, password, firstName, lastName });
+        if (result.error) {
+          set({ loading: false, error: result.error });
+          return false;
+        }
+        set({ loading: false, token: result.token, customer: toCustomer(result) });
+        return true;
+      },
+
+      login: async (email, password) => {
+        set({ loading: true, error: null });
+        const result = await postJson("/api/customer/login", { email, password });
+        if (result.error) {
+          set({ loading: false, error: result.error });
+          return false;
+        }
+        set({ loading: false, token: result.token, customer: toCustomer(result) });
+        return true;
+      },
+
+      loginWithGoogle: async (code, state) => {
+        set({ loading: true, error: null });
+        const result = await postJson("/api/customer/google/callback", { code, state });
+        if (result.error) {
+          set({ loading: false, error: result.error });
+          return false;
+        }
+        set({ loading: false, token: result.token, customer: toCustomer(result) });
+        return true;
+      },
+
+      logout: () => set({ token: null, customer: null, error: null }),
+
+      // El token guardado en localStorage puede llevar dias o haber sido
+      // revocado -- se refresca contra el servidor en vez de confiar en el
+      // ultimo snapshot local.
+      syncCustomer: async () => {
+        const token = get().token;
+        if (!token) return;
+        try {
+          const response = await fetch(`/api/customer/me?token=${encodeURIComponent(token)}`);
+          if (!response.ok) {
+            set({ token: null, customer: null });
+            return;
+          }
+          const result = await response.json();
+          if (result.id) set({ customer: toCustomer(result) });
+        } catch {
+          // Sin red: se queda con el ultimo estado local conocido.
+        }
+      },
+    }),
+    {
+      name: "ari-shopping-customer-v1",
+      storage: createJSONStorage(() => localStorage),
+      partialize: (state) => ({ token: state.token, customer: state.customer }),
+      onRehydrateStorage: () => (state) => {
+        state?.setHasHydrated(true);
+        void state?.syncCustomer();
+      },
+    },
+  ),
+);