Fase 2 fix: /store/search resuelve currency_code, no solo region_id

Confirmado en vivo: pasar solo region_id a QueryContext no alcanza -- "Method calculatePrices requires currency_code in the pricing context" persistia. A diferencia de /store/products nativo (resuelto por el middleware setPricingContext), esta ruta propia no pasa por esa cadena, asi que resuelve la moneda real de la region con un query.graph adicional antes de pedir calculated_price -- no asume COP fijo por si el catalogo suma otra region/moneda despues.
Merge fix/adr0006-etapa2-fase2-region-id-search into main
2026-08-26 16:52:04 -05:00 · 2026-08-26 16:31:24 -05:00 · 2026-08-26 16:31:21 -05:00 · 2026-08-26 21:23:08 +00:00 · 2026-08-26 16:05:03 -05:00 · 2026-08-26 16:04:59 -05:00
30 changed files with 1468 additions and 159 deletions
@@ -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
@@ -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
@@ -21,7 +21,9 @@ ENV CI=true \
    S3_ACCESS_KEY_ID=build-access-key \
    S3_SECRET_ACCESS_KEY=build-secret-key \
    S3_BUCKET=ari-shopping \
-    S3_ENDPOINT=http://127.0.0.1:9000
+    S3_ENDPOINT=http://127.0.0.1:9000 \
    MEILISEARCH_HOST=http://127.0.0.1:7700 \
    MEILISEARCH_API_KEY=build-only-meili-key
 COPY package.json package-lock.json .npmrc ./
@@ -10,6 +10,91 @@ const required = (name: string): string => {
  return value
 }
 // Mismos campos derivados de metadata/categories/collection/variants que
 // mapProduct() en workloads/ecommerce/lib/headless/providers/medusa.ts --
 // el documento indexado debe reflejar exactamente lo que el storefront
 // ya muestra, no una vista distinta del catálogo.
 function stringMetadata(
  metadata: Record<string, unknown> | null | undefined,
  key: string,
 ): string {
  const value = metadata?.[key]
  return typeof value === "string" ? value : ""
 }
 function booleanMetadata(
  metadata: Record<string, unknown> | null | undefined,
  key: string,
 ): boolean {
  const value = metadata?.[key]
  return value === true || value === "true"
 }
 async function meilisearchProductTransformer(
  document: Record<string, unknown>,
 ) {
  const metadata = (document.metadata ?? null) as Record<
    string,
    unknown
  > | null
  const categories = document.categories as
    | Array<{ name?: string | null }>
    | null
    | undefined
  const collection = document.collection as { title?: string | null } | null
  const variants = document.variants as
    | Array<{
        inventory_quantity?: number | null
        manage_inventory?: boolean | null
        allow_backorder?: boolean | null
        prices?: Array<{
          amount?: number | null
          currency_code?: string | null
        }> | null
      }>
    | null
    | undefined
  const variant = variants?.[0]
  const tags = document.tags as Array<{ value?: string | null }> | null
  const category =
    categories?.[0]?.name || stringMetadata(metadata, "category") || "Variedades"
  const available =
    !variant ||
    variant.allow_backorder === true ||
    variant.manage_inventory === false ||
    (variant.inventory_quantity ?? 0) > 0
  // variants.calculated_price requiere currency_code/region_id en el
  // contexto de pricing, que el workflow de sync interno del plugin no
  // provee -- hace fallar TODO el job de indexado (confirmado en vivo:
  // "Method calculatePrices requires currency_code in the pricing
  // context"). variants.prices es la lista cruda de precios (sin
  // resolver promociones/reglas), no necesita contexto -- alcanza para
  // el filtro/orden por precio en la busqueda, que no necesita el
  // precio final promocional.
  const copPrice = variant?.prices?.find(
    (price) => price.currency_code?.toLowerCase() === "cop",
  )
  return {
    id: document.id,
    name: document.title || "Producto ARI Shopping",
    shortDescription: document.subtitle || document.title || "",
    description: document.description || "",
    category,
    collection: collection?.title || stringMetadata(metadata, "collection") || "",
    brand: stringMetadata(metadata, "brand") || "ARI Shopping",
    ageRange: stringMetadata(metadata, "ageRange") || "Todas",
    tags: (tags || []).map((tag) => tag.value).filter(Boolean),
    price: typeof copPrice?.amount === "number" ? copPrice.amount : null,
    available,
    isNew: booleanMetadata(metadata, "isNew"),
    featured: booleanMetadata(metadata, "featured"),
  }
 }
 module.exports = defineConfig({
  projectConfig: {
    databaseUrl: required("DATABASE_URL"),
@@ -73,4 +158,72 @@ module.exports = defineConfig({
      },
    },
  ],
  // ADR 0006 Etapa 2. Sin required(): a diferencia de S3/DB, Meilisearch
  // es un servicio nuevo y todavia no probado en produccion en un host
  // con historial de swap saturado -- si esta caido o mal configurado,
  // el plugin se degrada solo (soporta enabled:false, "silently skipped"
  // segun su propio README) en vez de tumbar el arranque de Medusa
  // entero, que es lo que si haria required().
  plugins: [
    {
      resolve: "@rokmohar/medusa-plugin-meilisearch",
      options: {
        config: {
          host: process.env.MEILISEARCH_HOST ?? "",
          apiKey: process.env.MEILISEARCH_API_KEY ?? "",
        },
        settings: {
          products: {
            type: "products",
            enabled: Boolean(process.env.MEILISEARCH_HOST),
            primaryKey: "id",
            // Campos que el plugin pide via query.graph antes de pasarlos
            // al transformer de arriba -- si falta alguno acá, llega
            // undefined al transformer sin importar lo que este haga.
            fields: [
              "id",
              "title",
              "subtitle",
              "description",
              "handle",
              "status",
              "thumbnail",
              "metadata",
              "tags.value",
              "categories.name",
              "collection.title",
              "variants.inventory_quantity",
              "variants.manage_inventory",
              "variants.allow_backorder",
              "variants.prices.amount",
              "variants.prices.currency_code",
            ],
            indexSettings: {
              // Tabla de ADR 0006 §3: Buscable / Filtrable-faceta / Ordenable.
              searchableAttributes: [
                "name",
                "shortDescription",
                "description",
                "category",
                "collection",
                "brand",
                "tags",
              ],
              filterableAttributes: [
                "category",
                "collection",
                "brand",
                "ageRange",
                "price",
                "available",
              ],
              sortableAttributes: ["price", "isNew", "featured"],
            },
            transformer: meilisearchProductTransformer,
          },
        },
      },
    },
  ],
 })
@@ -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",
@@ -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",
@@ -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,
  });
 }
@@ -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.
@@ -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
@@ -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
+**Estado:** aceptada — Etapa 2 implementada y en producción
-**Fecha:** 2026-08-23
+**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
+> Este documento arrancó como la propuesta de Etapa 1 del rediseño de
-> Shopping. No incluye código de producción — solo auditoría,
+> ARI Shopping (auditoría, decisión — ver también [ADR 0004](0004-evaluacion-stack-multi-categoria.md) —
-> 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ó
-> patrones de UX y datos demo ya creados y visibles en producción
+> completa en tres sub-fases (datos/categorías, navegación,
-> como línea base.
+> 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
+Aprobada y ejecutada en tres sub-fases, cada una validada en vivo
-apruebes, Etapa 2 se dividirá en sub-fases (datos/categorías primero,
+contra estos 9 productos demo:
-luego navegación, luego componentes visuales), validando en cada paso
+
-contra estos 9 productos demo que precio/descripción/imágenes siguen
+1. **Datos/categorías** (2026-08-23/24): fix del bug de Store API que
-actualizándose correctamente desde Admin.
+   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).
 **Pendiente:** borrar el usuario admin temporal `[email protected]`
 de Medusa Admin (creado para la auditoría de la sección 5, ya no
 necesario). Sin próxima etapa definida todavía — este ADR no
 especifica una Etapa 3.
@@ -0,0 +1,297 @@
 # 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).
@@ -84,6 +84,7 @@ 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
      - Glosario: arquitectura/glosario.md
  - Decisiones (ADRs):
      - "0001 · Por qué k3d": decisiones/0001-por-que-k3d.md
@@ -91,6 +92,7 @@ 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
      - Plantilla ADR: decisiones/plantilla-adr.md
  - Playbooks:
      - Crashloop Medusa: playbooks/incidente-crashloop-medusa.md
@@ -25,7 +25,7 @@ spec:
        runAsNonRoot: false
      containers:
        - name: app
-          image: gitea.cruzcloud.net/devops/docs-portal:v1.0.125
+          image: gitea.cruzcloud.net/devops/docs-portal:v1.0.164
          # 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
@@ -41,6 +41,7 @@ export default async function CatalogPage({ searchParams }: CatalogPageProps) {
    <CatalogClient
      key={`${category}:${collection}:${query}`}
      products={products}
      categories={categories}
      categoryGroups={categoryGroups}
      initialCategory={category}
      initialCollection={collection}
@@ -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
@@ -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:
@@ -7,5 +7,7 @@ resources:
  - redis.yaml
  - minio.yaml
  - minio-bootstrap-job.yaml
  - meilisearch.yaml
  - medusa/
  - ingress-commerce.yaml
  - middleware-commerce-redirect.yaml
@@ -65,7 +65,7 @@ spec:
              memory: 64Mi
        - name: migrations
-          image: gitea.cruzcloud.net/devops/ecommerce-medusa:v1.0.127
+          image: gitea.cruzcloud.net/devops/ecommerce-medusa:v1.0.166
          imagePullPolicy: IfNotPresent
          command:
            - node
@@ -86,7 +86,7 @@ spec:
      containers:
        - name: app
-          image: gitea.cruzcloud.net/devops/ecommerce-medusa:v1.0.127
+          image: gitea.cruzcloud.net/devops/ecommerce-medusa:v1.0.166
          imagePullPolicy: IfNotPresent
          envFrom:
            - configMapRef:
@@ -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
@@ -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
@@ -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.
@@ -1,22 +1,70 @@
 "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, 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 = "",
@@ -55,29 +103,25 @@ export function CatalogClient({
  // 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) => {
+        .filter(
-          const search = [
+          (product) =>
-            product.name,
+            matchesQuery(product, query) &&
-            product.category,
+            (category === "Todos" || matchesCategory(product, allowedCategories)) &&
-            product.collection,
+            matchesCollection(product, collection) &&
-            product.brand,
+            matchesBrand(product, brand) &&
-          ]
+            matchesAge(product, age) &&
-            .join(" ")
+            matchesPrice(product, maxPrice),
-            .toLowerCase();
+        )
          return (
            (!query || search.includes(query.toLowerCase())) &&
            (category === "Todos" || allowedCategories.includes(product.category)) &&
            (!collection || product.collection === collection) &&
            (brand === "Todas" || product.brand === brand) &&
            (age === "Todas" || product.ageRange === age) &&
            (product.price === null || maxPrice === 0 || product.price <= maxPrice)
          );
        })
        .sort((a, b) =>
          sort === "name"
            ? a.name.localeCompare(b.name, "es")
@@ -88,6 +132,78 @@ export function CatalogClient({
    [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.
  const categoryCounts = 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 brandCounts = 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 ageCounts = 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]);
  const reset = () => {
    setQuery("");
    setCategory("Todos");
@@ -101,6 +217,27 @@ export function CatalogClient({
  return (
    <div className="mx-auto max-w-7xl px-4 py-10">
      <div className="mb-8">
        {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-fuchsia-600">
              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-slate-900">
                    {node.name}
                  </span>
                ) : (
                  <Link href={`/catalog?category=${encodeURIComponent(node.name)}`} prefetch={false} className="hover:text-fuchsia-600">
                    {node.name}
                  </Link>
                )}
              </span>
            ))}
          </nav>
        )}
        <span className="text-xs font-black uppercase tracking-[.18em] text-fuchsia-600">
          Catálogo completo
        </span>
@@ -134,9 +271,10 @@ export function CatalogClient({
            values={categories}
            selected={category}
            onChange={setCategory}
            counts={categoryCounts}
          />
-          <Filter title="Marca" values={brands} selected={brand} onChange={setBrand} />
+          <Filter title="Marca" values={brands} selected={brand} onChange={setBrand} counts={brandCounts} />
-          <Filter title="Edad" values={ages} selected={age} onChange={setAge} />
+          <Filter title="Edad" values={ages} selected={age} onChange={setAge} counts={ageCounts} />
          <fieldset>
            <legend className="mb-3 text-sm font-black">Precio máximo</legend>
@@ -180,9 +318,13 @@ export function CatalogClient({
          {filtered.length ? (
            <div className="grid gap-5 sm:grid-cols-2 xl:grid-cols-3">
-              {filtered.map((product) => (
+              {gridItems.map((item, index) =>
-                <ProductCard key={product.id} product={product} />
+                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">
@@ -205,11 +347,13 @@ function Filter({
  values,
  selected,
  onChange,
  counts,
 }: {
  title: string;
  values: string[];
  selected: string;
  onChange: (value: string) => void;
  counts?: Record<string, number>;
 }) {
  return (
    <fieldset>
@@ -227,6 +371,7 @@ function Filter({
            }`}
          >
            {value}
            {counts && <span className="ml-1 opacity-60">({counts[value] ?? 0})</span>}
          </button>
        ))}
      </div>
@@ -2,6 +2,7 @@ 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";
 type TileContent = { subtitle: string; image?: string; color: string };
@@ -20,6 +21,37 @@ const tileContent: Record<string, TileContent> = {
 const defaultTile: TileContent = { subtitle: "Explora esta categoría", color: "from-slate-400 to-slate-600" };
 // 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] bg-gradient-to-br ${content.color} shadow-xl`, className)}
    >
      {content.image && (
        <>
          <Image src={content.image} alt={category.name} fill sizes="(max-width: 640px) 100vw, (max-width: 1024px) 33vw, 16vw" 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-xl font-black">{category.name}</h3>
          <p className="mt-1 text-sm font-semibold text-white/80">{content.subtitle}</p>
        </div>
        <span className="grid size-11 shrink-0 place-items-center rounded-full bg-white text-slate-950 transition group-hover:rotate-45">
          <ArrowUpRight />
        </span>
      </div>
    </Link>
  );
 }
 export function CategoryTiles({ categories }: { categories: Category[] }) {
  const roots = categories.filter((category) => !category.parentId);
@@ -35,33 +67,9 @@ export function CategoryTiles({ categories }: { categories: Category[] }) {
        <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-3 xl:grid-cols-6">
-        {roots.map((category) => {
+        {roots.map((category) => (
-          const content = tileContent[category.handle] ?? defaultTile;
+          <PromoTile key={category.id} category={category} />
-
+        ))}
          return (
            <Link
              key={category.id}
              href={`/catalog?category=${encodeURIComponent(category.name)}`}
              className={`group relative min-h-64 overflow-hidden rounded-[2rem] bg-gradient-to-br ${content.color} shadow-xl`}
            >
              {content.image && (
                <>
                  <Image src={content.image} alt={category.name} fill sizes="(max-width: 640px) 100vw, (max-width: 1024px) 33vw, 16vw" 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-xl font-black">{category.name}</h3>
                  <p className="mt-1 text-sm font-semibold text-white/80">{content.subtitle}</p>
                </div>
                <span className="grid size-11 shrink-0 place-items-center rounded-full bg-white text-slate-950 transition group-hover:rotate-45">
                  <ArrowUpRight />
                </span>
              </div>
            </Link>
          );
        })}
      </div>
    </section>
  );
@@ -2,11 +2,12 @@
 import Image from "next/image";
 import Link from "next/link";
-import { Heart, ShoppingBag, Sparkles } from "lucide-react";
+import { Heart, ShoppingBag, Sparkles, TriangleAlert } from "lucide-react";
 import { useState } from "react";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
 import type { Product } from "@/lib/headless/types";
-import { formatMoney } from "@/lib/utils";
+import { formatMoney, LOW_STOCK_THRESHOLD } from "@/lib/utils";
 import { useCartStore } from "@/store/cart-store";
 import { useWishlistStore } from "@/store/wishlist-store";
@@ -16,19 +17,63 @@ export function ProductCard({ product, priority = false }: { product: Product; p
  const wishlistHydrated = useWishlistStore((state) => state.hasHydrated);
  const toggleProduct = useWishlistStore((state) => state.toggleProduct);
  const isFavorite = wishlistHydrated && wishlistProducts.some((item) => item.id === product.id);
  const discountPercent =
    product.compareAtPrice && product.price
      ? Math.round((1 - product.price / product.compareAtPrice) * 100)
      : null;
  const [selectedVariantId, setSelectedVariantId] = useState(product.variants[0]?.id);
  const selectedVariant = product.variants.find((variant) => variant.id === selectedVariantId) ?? product.variants[0];
  const lowStock =
    selectedVariant?.inventoryQuantity !== null &&
    selectedVariant?.inventoryQuantity !== undefined &&
    selectedVariant.inventoryQuantity > 0 &&
    selectedVariant.inventoryQuantity <= LOW_STOCK_THRESHOLD
      ? selectedVariant.inventoryQuantity
      : null;
  return (
    <article className="group flex h-full flex-col overflow-hidden rounded-3xl border border-slate-100 bg-white shadow-lg shadow-slate-900/5 transition duration-300 hover:-translate-y-1.5 hover:shadow-2xl hover:shadow-violet-500/10">
      <div className="relative aspect-square overflow-hidden bg-slate-50">
        <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>
+        <div className="absolute left-3 top-3 flex gap-2">{discountPercent && discountPercent > 0 && <Badge className="bg-rose-600 text-white">-{discountPercent}%</Badge>}{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>
      <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>
        <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-full border px-2.5 py-1 text-xs font-bold transition ${
                  selectedVariantId === variant.id
                    ? "border-fuchsia-500 bg-fuchsia-50 text-fuchsia-700"
                    : "border-slate-200 text-slate-600 hover:border-slate-400"
                } ${!variant.available ? "cursor-not-allowed opacity-40" : ""}`}
              >
                {variant.value}
              </button>
            ))}
          </div>
        )}
        {lowStock !== null && (
          <span className="flex items-center gap-1.5 text-xs font-bold text-amber-600"><TriangleAlert className="size-3.5" />Quedan {lowStock}</span>
        )}
        <div className="mt-auto flex items-center justify-between gap-3 pt-1">
          <div className="flex flex-col">
            {product.compareAtPrice && <span className="text-xs font-bold text-slate-400 line-through">{formatMoney(product.compareAtPrice, product.currency)}</span>}
            <strong className="text-sm font-black">{formatMoney(product.price, product.currency)}</strong>
          </div>
          <Button variant="magenta" size="sm" onClick={() => addItem(product, selectedVariantId)}><ShoppingBag className="size-4" />Agregar</Button>
        </div>
      </div>
    </article>
  );
@@ -1,14 +1,22 @@
 "use client";
-import { CheckCircle2, ShoppingBag, Truck } from "lucide-react";
+import { CheckCircle2, ShoppingBag, TriangleAlert, Truck } from "lucide-react";
 import { useState } from "react";
 import { Button } from "@/components/ui/button";
 import type { Product } from "@/lib/headless/types";
-import { formatMoney } from "@/lib/utils";
+import { formatMoney, LOW_STOCK_THRESHOLD } from "@/lib/utils";
 import { useCartStore } from "@/store/cart-store";
 export function ProductPurchase({ product }: { product: Product }) {
  const [variantId, setVariantId] = useState(product.variants[0]?.id);
  const addItem = useCartStore((state) => state.addItem);
-  return <div><div className="mb-5 flex flex-wrap gap-2">{product.variants.map((variant) => <button key={variant.id} onClick={() => setVariantId(variant.id)} className={`rounded-full border px-4 py-2 text-sm font-bold ${variantId === variant.id ? "border-fuchsia-500 bg-fuchsia-50 text-fuchsia-700" : "border-slate-200"}`}>{variant.value}</button>)}</div><div className="mb-6 flex items-end gap-3"><strong className="text-3xl font-black">{formatMoney(product.price, product.currency)}</strong>{product.compareAtPrice && <del className="text-slate-400">{formatMoney(product.compareAtPrice, product.currency)}</del>}</div><Button variant="magenta" size="lg" className="w-full" onClick={() => addItem(product, variantId)}><ShoppingBag />Añadir al carrito</Button><div className="mt-5 grid gap-3 rounded-2xl bg-slate-50 p-4 text-sm"><span className="flex items-center gap-2 font-bold"><CheckCircle2 className="size-4 text-emerald-500" />Disponibilidad por confirmar</span><span className="flex items-center gap-2 font-bold"><Truck className="size-4 text-cyan-600" />Envíos nacionales</span></div></div>;
+  const selectedVariant = product.variants.find((variant) => variant.id === variantId) ?? product.variants[0];
  const lowStock =
    selectedVariant?.inventoryQuantity !== null &&
    selectedVariant?.inventoryQuantity !== undefined &&
    selectedVariant.inventoryQuantity > 0 &&
    selectedVariant.inventoryQuantity <= LOW_STOCK_THRESHOLD
      ? selectedVariant.inventoryQuantity
      : null;
  return <div><div className="mb-5 flex flex-wrap gap-2">{product.variants.map((variant) => <button key={variant.id} onClick={() => setVariantId(variant.id)} className={`rounded-full border px-4 py-2 text-sm font-bold ${variantId === variant.id ? "border-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">{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>;
 }
@@ -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"
@@ -25,7 +25,7 @@ spec:
        runAsUser: 1001
      containers:
        - name: app
-          image: gitea.cruzcloud.net/devops/ecommerce-frontend:v1.0.143
+          image: gitea.cruzcloud.net/devops/ecommerce-frontend:v1.0.157
          env:
            - name: HEADLESS_PROVIDER
              value: medusa
@@ -157,11 +157,19 @@ 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,
  };
 }
@@ -3,6 +3,7 @@ export interface ProductVariant {
  name: string;
  value: string;
  available: boolean;
  inventoryQuantity: number | null;
 }
 export interface Product {
@@ -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;