zugzbot 1.1.6 → 1.2.0

package/.opencode/agents/sdd-orchestrator.md

@@ -49,6 +49,13 @@ Eres el coordinador principal del arnés de desarrollo SDD (Spec-Driven Developm
   <f0_detect>
     1. **Inicialización Atómica**: Llama obligatoriamente a `sdd_get_initial_session_data` para obtener estado, memorias e Oh-My-Design en un solo turno.
     2. **Brain Pre-carga (OBLIGATORIO)**: Inmediatamente después, invoca `brain_read_memory({ category: "learnings" })` y `brain_read_memory({ category: "errors" })` para extraer errores y lecciones históricas que prevengan repetir problemas conocidos. Guarda el resultado en una variable interna para inyectarlo en cada brief de subagente.
+    2.5 **Detección de intención de catálogo Akash (CRÍTICO — bugfix sesión 1176)**: Analiza la petición. Si contiene ALGUNA keyword de marketing/landing/auth/composite o un nombre propio del catálogo:
+       - Keywords: `hero`, `landing`, `pricing`, `features`, `faq`, `testimonials`, `footer`, `cta`, `navbar`, `stats`, `logo cloud`, `login page`, `signup page`, `forgot password`, `chart`, `sidebar`, `dashboard section`, `comparison`, `use cases`, `how it works`, `changelog`, `cookie banner`, `newsletter`, `bento`, `marquee`, `gallery`, `integration`
+       - Nombres propios: `akash`, `akash3444`, `shadcnui-blocks`, `shadcn-ui-blocks`, `basecn`, `shadcn blocks`
+       - **Acción obligatoria**: cargar la skill `shadcn-templates` (que ahora referencia las tools MCP `sdd_akash_catalog_list_blocks` y `sdd_akash_catalog_get_block` — NUNCA uses `webfetch` directo a GitHub API, está cacheado).
+       - En modo HIL: llama `sdd_akash_catalog_list_blocks({category, limit: 5})` y presenta las 2-3 mejores opciones con `preview_url` para que el usuario elija.
+       - En modo autopiloto (`/loop`): llama `sdd_akash_catalog_get_block({name})` sobre 2-3 candidatos y elige el que mejor encaje.
+       - Esto evita el ciclo "ping-pong" de 3+ turnos que vimos en sesión 1176 donde el usuario tuvo que guiar al orquestador hacia el catálogo correcto.
     3. **Detección Fast-Track Dashboard (CRÍTICO — bugfix sesión 1186 y 1180)**: Analiza la petición del usuario. Si contiene ALGUNA de estas keywords: `dashboard`, `admin panel`, `panel de control`, `panel admin`, `crm`, `erp`, `panel`:
        - **NO preguntes NADA**. Asume todos los defaults: Stack = Next.js 16 + Shadcn UI + Tailwind v4, Persistencia = localStorage/mock, Diseño = `default` (zinc nativo de Shadcn, NO inyectar marcas de Oh-My-Design), Verificación = `console`.
        - Llama directamente a `sdd_set_phase({ phase: "F1_CONTRACT", spec_name: "dashboard-admin" })` con `coreStack: ["Next.js 16", "Shadcn UI", "Tailwind CSS v4"]` y `skip_lint_gate: true`.
@@ -85,13 +92,20 @@ Eres el coordinador principal del arnés de desarrollo SDD (Spec-Driven Developm
        - Lista resumida de `files_affected` para ESTE sprint (si dividiste)
        - Sección `brain_learnings` del brief
        - *Instrucción clave:* Indica si requiere bootstrap. Prohíbe formalmente el uso de `brain_read_memory` (ya está inyectado). Si el subagente se había quedado sin pasos y debes re-invocarlo con su `task_id`, el prompt DEBE SER EXTREMADAMENTE BREVE (ej. "Te quedaste sin pasos. Tu contexto y tareas ya están en tu historial. Revisa lo que falta y continúa."). NO incluyas código ni listas largas para no contaminar el contexto.
-    3. **Verificación de Servidor**:
+    3. **Micro-Fixes (Anti-Spec Spam)**: Si el usuario reporta un bug, un desajuste visual o pide una pequeña corrección sobre lo que acabas de entregar, **TIENES PROHIBIDO crear un nuevo spec en F1**. Debes mantener el estado actual en `activeContract`, transicionar/mantener a `F2_IMPLEMENTATION`, y delegar el arreglo al Coder. Solo crea nuevos specs en F1 si el usuario solicita una característica completamente nueva.
+       3.5 **Plantilla de prompt para chart/visual fixes (bugfix sesión 1176)**: Cuando corrijas colores de gráficos Recharts:
+          1. Cambia valores OKLCH en `globals.css` (`.dark` y `:root`).
+          2. Verifica que el `chartConfig` del componente use `'var(--color-chart-N)'` DIRECTAMENTE, NUNCA `'hsl(var(--chart-N))'` — `hsl(oklch(...))` es CSS inválido.
+          3. Si encuentras `'hsl(var(--chart-N))'` en cualquier chartConfig, reemplázalo por `'var(--color-chart-N)'` en el mismo turno.
+          4. El linter `scripts/lint-charts.js` corre automáticamente en shift-left y bloqueará la transición a F3 si quedan ocurrencias inválidas.
+    4. **Verificación de Servidor y HMR**:
        - **Si la categoría es 'script' o 'tooling' (Track Agnóstico):** No hay un dev server web que correr. Salta directamente este paso y transiciona de forma inmediata a F3.
        - **De lo contrario (Web Next/FastAPI):**
+         - Next.js y tu stack frontend usan **Hot Module Replacement (HMR)**. Queda ESTRICTAMENTE PROHIBIDO detener y reiniciar el servidor (`sdd_network_stop_server` / `start_server`) para comprobar cambios de interfaz, CSS o componentes. El servidor se actualiza solo en vivo. Únicamente reinicia el servidor si hubo cambios en `next.config.ts`, `tailwind.config`, o instalación de dependencias muy pesadas.
          - En autopiloto: Aprueba directo si el server corre sin errores fatales. Transiciona a F3.
          - En modo `console`: Dile al usuario que verifique localmente en `http://localhost:3000`. Prohibido usar Playwright.
          - En modo `visual`: Toma screenshot en `.openspec/ts-f2-hil.png` y preséntalo para aprobación.
-    4. Transiciona a `F3_VERIFICATION` llamando a `sdd_set_phase`.
+    5. Transiciona a `F3_VERIFICATION` llamando a `sdd_set_phase`. **Bajo ninguna circunstancia te saltes la fase F3 después de que el Coder haya intervenido, incluso para micro-fixes visuales**.
   </f2_implementation>
 
   <f3_verification>
@@ -115,8 +129,9 @@ Eres el coordinador principal del arnés de desarrollo SDD (Spec-Driven Developm
   </f4_deployment>
 
   <rollbacks>
-    1. Si se reportan fallos, regresa a la fase correspondiente usando `sdd_set_phase` y delega la corrección al subagente experto.
+    1. Si se reportan fallos en tests o linter en F3, haz un rollback de la estructura y regresa a `F2_IMPLEMENTATION` usando `sdd_set_phase` y delega la corrección al subagente experto (`@sdd-coder`). Bajo ninguna circunstancia puedes usar la herramienta `edit` o `write` para arreglar código, ni siquiera en modo autopiloto.
     2. Si una misma fase falla más de 2 veces consecutivas, presenta el error al usuario con el contexto completo en vez de seguir intentando.
+    3. **Estado Corrupto**: Si detectas que el estado actual es `F2_IMPLEMENTATION` o superior, pero la propiedad `activeContract` está vacía o el archivo del contrato ya no existe, asume que la sesión previa se corrompió. Limpia el estado transicionando automáticamente a `F0_DETECT` antes de procesar el requerimiento del usuario.
   </rollbacks>
 
   <completion>
@@ -126,6 +141,11 @@ Eres el coordinador principal del arnés de desarrollo SDD (Spec-Driven Developm
          - Anúnciala en 1 línea y delega la siguiente iteración completa a un NUEVO hilo `sdd-orchestrator` con contexto de 0 tokens.
        - Si `loopCurrentIteration >= loopTargetIterations` o modo normal: Concluye con `sdd_set_phase({ phase: "F0_DETECT", loopMode: false })`.
     2. **Brain save OBLIGATORIO**: Sintetiza 1-3 lecciones y regístralas con `brain_save_memory` (categoría: `learnings`, `errors`, `design` o `routing`). BLOQUEANTE — no omitir.
+    2.5 **Memory Post-Sesión para Catálogos (CRÍTICO — bugfix sesión 1176)**: Si la sesión tocó el catálogo Akash (shadcn-ui-blocks, basecn) o cualquier catálogo externo de UI, registra OBLIGATORIAMENTE en `brain.routing`:
+       - URL canónica del catálogo
+       - Comando `npx shadcn@latest add <URL>` listo para usar
+       - Nombre del autor/repo (para evitar redescubrimiento en próximas sesiones)
+       - Tool MCP del arnés a usar (`sdd_akash_catalog_list_blocks`, etc.)
     3. **Mensaje Final MÁXIMO 10 LÍNEAS**:
        ```
        ✅ Sesión SDD completada
@@ -143,6 +163,7 @@ Eres el coordinador principal del arnés de desarrollo SDD (Spec-Driven Developm
 <mcp_guidelines>
 - **MCPs**: `shadcn` (UI), `context7` (APIs Next.js/FastAPI), `playwright` (Visual tests), `lucide-icons` (Iconos).
 - `next-devtools` deshabilitado por defecto. MCPs invocados exclusivamente por subagentes.
+- **Catálogos externos (Tools internas)**: `sdd_akash_catalog_list_blocks`, `sdd_akash_catalog_get_block`, `sdd_akash_catalog_warm_index` — cachean el catálogo de Akash (shadcn-ui-blocks + basecn) en `.openspec/cache/` con TTL 7d. NUNCA uses `webfetch` directo a GitHub API para descubrir bloques Akash; usa siempre estas tools.
 </mcp_guidelines>
 
 <communication_rules>

package/.opencode/scripts/lint-charts.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+/**
+ * lint-charts.js — Linter bloqueante para configuraciones de Recharts inválidas.
+ *
+ * Bugfix sesión 1176: el coder dejó `color: "hsl(var(--chart-1))"` en
+ * `chart-area-interactive.tsx`. Como `--chart-1` está definido en OKLCH en
+ * `globals.css`, `hsl(oklch(...))` produce CSS inválido y los colores no
+ * cambian al actualizar el token.
+ *
+ * REGLA: en chartConfig, los `color:` DEBEN usar `var(--color-chart-N)`
+ * directamente, NUNCA `hsl(var(--chart-N))`.
+ *
+ * Uso:
+ *   node .opencode/scripts/lint-charts.js [paths...]
+ *
+ * Por defecto escanea `src/` y `app/`. Sale con código 1 si encuentra
+ * violaciones (BLOQUEANTE en shift-left).
+ *
+ * Salida JSON para integración programática:
+ *   node .opencode/scripts/lint-charts.js --json
+ */
+"use strict"
+
+const fs = require("fs")
+const path = require("path")
+
+// ============================================================================
+// Config
+// ============================================================================
+
+const INCLUDE_EXT = new Set([".ts", ".tsx", ".js", ".jsx"])
+const IGNORE_DIRS = new Set([
+  "node_modules",
+  ".next",
+  "dist",
+  "build",
+  "out",
+  "coverage",
+  ".openspec/cache",
+  ".openspec/__tests__",
+  ".opencode/templates",
+  ".opencode/oh-my-design"
+])
+
+// Patrones prohibidos: cualquier chartConfig que envuelva una variable CSS
+// --chart-N dentro de hsl(). Capturamos la ocurrencia exacta.
+const FORBIDDEN_PATTERNS = [
+  {
+    name: "hsl(oklch) misuse",
+    regex: /hsl\(\s*var\(\s*--chart-\d+\s*\)\s*\)/g,
+    fix: "Usa 'var(--color-chart-N)' directamente en chartConfig.color"
+  },
+  {
+    name: "hsl(--chart) sin var()",
+    regex: /hsl\(\s*--chart-\d+\s*\)/g,
+    fix: "Envuelve en var(): 'hsl(var(--chart-N))' — pero si --chart-N es OKLCH, sigue siendo inválido. Usa 'var(--color-chart-N)'."
+  }
+]
+
+// ============================================================================
+// Walk
+// ============================================================================
+
+function walk(dir, acc = []) {
+  let entries
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true })
+  } catch (e) {
+    return acc
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith(".") && entry.name !== ".opencode") continue
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      if (IGNORE_DIRS.has(entry.name)) continue
+      walk(full, acc)
+    } else if (entry.isFile()) {
+      const ext = path.extname(entry.name)
+      if (INCLUDE_EXT.has(ext)) acc.push(full)
+    }
+  }
+  return acc
+}
+
+function isInChartContext(filePath, lineContent) {
+  // Heurística: considerar chartConfig si el archivo contiene Recharts
+  // o si la línea está cerca de una mención a ChartConfig. Para mantener
+  // el linter simple y rápido, NO restringimos por contexto y reportamos
+  // cualquier coincidencia; el developer decide si aplica.
+  return true
+}
+
+// ============================================================================
+// Lint
+// ============================================================================
+
+function lintFile(filePath) {
+  const content = fs.readFileSync(filePath, "utf8")
+  const lines = content.split("\n")
+  const violations = []
+
+  lines.forEach((line, idx) => {
+    for (const pat of FORBIDDEN_PATTERNS) {
+      pat.regex.lastIndex = 0
+      let m
+      while ((m = pat.regex.exec(line)) !== null) {
+        if (!isInChartContext(filePath, line)) continue
+        violations.push({
+          file: filePath,
+          line: idx + 1,
+          column: m.index + 1,
+          match: m[0],
+          pattern: pat.name,
+          fix: pat.fix,
+          snippet: line.trim()
+        })
+      }
+    }
+  })
+
+  return violations
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+function main() {
+  const argv = process.argv.slice(2)
+  const jsonOut = argv.includes("--json")
+  const explicitPaths = argv.filter((a) => !a.startsWith("--"))
+
+  const roots =
+    explicitPaths.length > 0
+      ? explicitPaths
+      : [path.join(process.cwd(), "src"), path.join(process.cwd(), "app")].filter((p) => {
+          try {
+            return fs.statSync(p).isDirectory()
+          } catch {
+            return false
+          }
+        })
+
+  if (roots.length === 0) {
+    const msg = "No se encontraron directorios src/ ni app/ para escanear."
+    if (jsonOut) {
+      console.log(JSON.stringify({ status: "SKIPPED", message: msg, violations: [] }, null, 2))
+    } else {
+      console.log(`[lint-charts] ${msg}`)
+    }
+    process.exit(0)
+  }
+
+  const files = roots.flatMap((r) => walk(r))
+  const allViolations = files.flatMap((f) => lintFile(f))
+
+  if (jsonOut) {
+    console.log(
+      JSON.stringify(
+        {
+          status: allViolations.length === 0 ? "PASS" : "FAIL",
+          filesScanned: files.length,
+          violations: allViolations,
+          summary: allViolations.length === 0
+            ? "No se encontraron chartConfig con hsl()+oklch misuse."
+            : `${allViolations.length} violacion(es) detectada(s).`
+        },
+        null,
+        2
+      )
+    )
+  } else {
+    console.log(`[lint-charts] Escaneados ${files.length} archivos.`)
+    if (allViolations.length === 0) {
+      console.log("[lint-charts] PASS - sin violaciones.")
+    } else {
+      console.log(`[lint-charts] FAIL - ${allViolations.length} violacion(es):`)
+      for (const v of allViolations) {
+        const rel = path.relative(process.cwd(), v.file)
+        console.log(
+          `  ${rel}:${v.line}:${v.column}  ${v.pattern}\n` +
+            `    match: ${v.match}\n` +
+            `    fix:   ${v.fix}\n` +
+            `    line:  ${v.snippet}`
+        )
+      }
+    }
+  }
+
+  process.exit(allViolations.length === 0 ? 0 : 1)
+}
+
+main()

package/.opencode/skills/sdd-quickstart/SKILL.md

@@ -148,6 +148,41 @@ Copia y adapta los IDs y descripciones que apliquen. Borra los que no apliquen.
 - `AUTH-02`: Login con credenciales inválidas muestra error genérico.
 - `AUTH-03`: Logout limpia el token y redirige a `/login`.
 
+### Charts / Recharts (CRÍTICO — bugfix sesión 1176)
+
+Cuando el contrato declare un chart de Recharts (`chart-area-*`, `chart-bar-*`, `chart-pie-*`, etc.) o cualquier componente que lea `var(--chart-*)`, **debes incluir al menos UNO de los siguientes test_scenarios para forzar la validación de tema dark/light en F3**:
+
+```json
+{
+  "id": "TS-CHART-01",
+  "name": "Chart visible con contraste WCAG AA en modo oscuro",
+  "type": "visual",
+  "feature_ref": "ChartAreaInteractive",
+  "given": "el dashboard se renderiza en modo oscuro",
+  "when": "el area chart muestra las series desktop y mobile",
+  "then": "las líneas y rellenos tienen contraste >= 4.5:1 con el fondo de la card",
+  "selector": "[data-testid='chart-area-interactive']",
+  "assertion": "color-contrast-pass AND not-invisible"
+}
+```
+
+```json
+{
+  "id": "TS-CHART-02",
+  "name": "ChartConfig usa variables CSS válidas (no hsl+oklch mix)",
+  "type": "unit",
+  "feature_ref": "ChartAreaInteractive",
+  "given": "el componente importa su chartConfig",
+  "when": "el linter `node .opencode/scripts/lint-charts.js` escanea el archivo",
+  "then": "ninguna entrada usa 'hsl(var(--chart-N))'; todas usan 'var(--color-chart-N)' directamente",
+  "assertion": "lint-charts --json status == PASS"
+}
+```
+
+**Por qué importan**: en sesión 1176, el coder dejó `color: "hsl(var(--chart-1))"` que es CSS inválido porque `--chart-1` se define en OKLCH. El usuario tuvo que reportar el bug manualmente. Estos test_scenarios **activan el linter BLOQUEANTE** `sdd_testing_lint_charts` durante shift-left y fuerzan al tester a validar contraste visual con Playwright.
+
+Si el chart es solo decorativo (no necesita tema oscuro), puedes omitir `TS-CHART-01`. Pero `TS-CHART-02` debería incluirse **siempre** que el chart use tokens `--chart-*`.
+
 ---
 
 ## 2.5. Plantilla MÍNIMA viable (Fast-Track Dashboard)

package/.opencode/skills/shadcn-templates/SKILL.md

@@ -154,18 +154,33 @@ El `@sdd-coder` utiliza el template base `nextjs-shadcn`. Si el contrato no deta
 
 ## 5. Catálogo Externo Oficial: Shadcn UI Blocks (Akash)
 
-Además del catálogo nativo de Shadcn UI, dispones de acceso autónomo a más de 200 bloques de alta calidad del repositorio **Shadcn UI Blocks (por Akash)**. Si necesitas un layout, sección o componente complejo (ej. hero, footer, pricing, login, dashboard), **debes** explorar este catálogo y proponerlo.
+Además del catálogo nativo de Shadcn UI, dispones de acceso autónomo a más de 200 bloques de alta calidad del repositorio **Shadcn UI Blocks (por Akash)**. Si el usuario solicita una interfaz relacionada con landings, marketing, autenticación, footers o dashboards, **TIENES LA OBLIGACIÓN** de explorar este catálogo ANTES de proponer crear componentes desde cero.
+
+### 5.0 Herramientas MCP Nativas del Arnés (PREFERENTE — bugfix sesión 1176)
+
+**PROHIBIDO** usar `webfetch` directo a la API de GitHub para descubrir bloques. El arnés expone herramientas MCP dedicadas que **cachean el índice localmente** con TTL de 7 días, evitando redescubrimiento y latencia:
+
+- `sdd_akash_catalog_list_blocks({ category?, query?, registry?, limit?, force_refresh? })`
+  - Devuelve el listado completo del catálogo (shadcn-ui-blocks + basecn) filtrado por categoría o substring.
+  - `registry`: `"shadcn"` (Radix), `"basecn"` (Base UI) o `"both"` (default).
+  - `force_refresh: true` re-descarga aunque el cache sea fresco.
+- `sdd_akash_catalog_get_block({ name, registry?, force_refresh? })`
+  - Devuelve el código fuente, archivos y dependencias de un bloque específico.
+  - Incluye `install_command` listo: `npx shadcn@latest add https://shadcnui-blocks.com/r/radix/<name>.json --yes`.
+- `sdd_akash_catalog_warm_index({ registry? })`
+  - Pre-calienta el caché para evitar la latencia del primer `list_blocks`. Llamar al bootstrap del proyecto.
+
+Cache local en `.openspec/cache/` (`.gitignore` lo excluye automáticamente). Si el caché tiene más de 7 días, se re-descarga silenciosamente en el próximo `list_blocks`.
 
 ### 5.1 Flujo de Descubrimiento (Fase F1 - Spec-Writer)
-Si el usuario solicita una interfaz genérica o tú detectas que un bloque complejo ahorraría tiempo, consulta la lista maestra de bloques en tiempo real:
-- **Comando a usar:** Ejecuta la herramienta `webfetch` apuntando a la API de GitHub:
-  `webfetch("https://api.github.com/repos/akash3444/shadcn-ui-blocks/contents/public/r/radix")`
-- **Análisis de resultados:** El JSON devuelto listará todos los bloques (`hero-01.json`, `footer-05.json`, `pricing-02.json`, etc.). Filtra mentalmente los que coincidan con la necesidad.
+Si el usuario solicita una interfaz (ej: "necesito un hero", "haz un footer"), **llama primero a `sdd_akash_catalog_list_blocks`**:
+- **Asistido:** `sdd_akash_catalog_list_blocks({ category: "hero", limit: 5 })` → muestra las 5 mejores opciones con su `preview_url` (`https://shadcnui-blocks.com/blocks/<name>`).
+- **Autopiloto:** `sdd_akash_catalog_get_block({ name: "hero-06" })` sobre 2-3 candidatos y elige el que mejor encaje.
 
-### 5.2 Selección de Bloques
+### 5.2 Selección de Bloques (Interactiva o Autónoma)
 Cuando existan múltiples opciones para un mismo tipo de bloque (ej. 10 footers distintos):
-- **Modo Asistido (Por defecto):** Utiliza la herramienta `question` o lista en el chat las opciones disponibles, proporcionando la URL visual del catálogo (`https://www.shadcnui-blocks.com/blocks/categories/[categoria]`) para que el usuario pueda verlos y elegir. *Ejemplo: "He encontrado 5 tipos de Footers, puedes verlos aquí. ¿Cuál prefieres (footer-01 a footer-05)?"*.
-- **Modo Autopiloto (`/loop`):** Si estás actuando de forma 100% autónoma sin interacción del usuario, lee el código fuente de 2 o 3 opciones al azar utilizando `webfetch("https://raw.githubusercontent.com/akash3444/shadcn-ui-blocks/main/public/r/radix/[bloque].json")` para analizar qué código encaja mejor con la petición (ej. si pide newsletter, busca uno con `<Input>`) y elígelo autónomamente.
+- **Modo Asistido (Por defecto):** Utiliza la herramienta `question` para preguntarle al usuario o dile explícitamente en el chat: *"Tengo acceso a la galería de Shadcn UI Blocks. He encontrado X opciones de [categoria]. ¿Quieres que revise algunas en particular o te dejo el enlace visual (`https://www.shadcnui-blocks.com/blocks/categories/[categoria]`) para que elijas la que más te guste?"*.
+- **Modo Autopiloto (`/loop`):** Si estás actuando de forma 100% autónoma, lee el código fuente de 2 o 3 opciones con `sdd_akash_catalog_get_block` y elígelo autónomamente sin preguntar.
 
 ### 5.3 Inyección e Instalación (Contrato y Coder)
 - **Spec-Writer (F1):** En el `contract.json`, dentro de `frontend.components`, anota el bloque utilizando la URL remota directa:
@@ -176,9 +191,28 @@ Cuando existan múltiples opciones para un mismo tipo de bloque (ej. 10 footers
     ]
   }
   ```
-- **Coder (F2):** Para instalar estos bloques externos, utiliza la capacidad nativa de la CLI v3 de Shadcn. Ejecuta directamente el comando apuntando a la URL:
+- **Coder (F2):** Para instalar estos bloques externos, **obtén el `install_command` listo** vía `sdd_akash_catalog_get_block({ name })` (campo `install_command` del resultado) y ejecútalo. La CLI v3 de Shadcn se encarga automáticamente de descargar el código y resolver dependencias internas:
   ```bash
-  npx shadcn@latest add https://shadcnui-blocks.com/r/radix/footer-04.json
+  npx shadcn@latest add https://shadcnui-blocks.com/r/radix/footer-04.json --yes
   ```
-  La CLI se encargará automáticamente de descargar el código y resolver dependencias internas (ej. instalar `separator` o `button` si el bloque lo requiere). No es necesario configurar nada en el `components.json`.
+
+### 5.4 Validación Post-Instalación (BLOQUEANTE — bugfix sesión 1176)
+Tras instalar cualquier bloque Akash (`npx shadcn add [URL]`), ejecuta INMEDIATAMENTE:
+1. `npx tsc --noEmit` para detectar imports rotos o packages faltantes.
+2. Verifica que todos los archivos declarados en el JSON del bloque fueron creados (compara con el campo `source_files` devuelto por `sdd_akash_catalog_get_block`).
+3. Si faltan archivos, reintenta la instalación con `--overwrite`.
+4. Solo entonces reporta éxito al orquestador.
+
+**Bug conocido**: `Can't resolve 'shadcn/tailwind.css'` en Tailwind v4 requiere `npm install shadcn` antes de continuar.
+
+---
+
+## 6. Patrones Avanzados de Layout CSS
+
+### 6.1 Patrón de Fullscreen Layouts y Centrado (CRÍTICO)
+Cuando necesites crear un Hero, Landing, o Splash screen que deba ocupar el 100% de la pantalla visible y tener su contenido perfectamente centrado, evita mezclar clases CSS que peleen entre sí. Sigue **estrictamente** este patrón:
+- **Contenedor Padre**: Usa `min-h-[100dvh] flex flex-col`.
+- **Contenedor Interno (Wrapper)**: Usa `flex-1 flex items-center justify-center w-full`.
+- **Contenido Central**: Usa `mx-auto max-w-[ancho-deseado] flex flex-col items-center text-center`.
+- **PROHIBICIÓN ESTRICTA DE `w-full` EN FLEX HIJOS**: Si el contenedor padre usa `flex` con `items-center` para centrar, **NO** le pongas `w-full` al hijo interno si quieres que no se "pegue" a la izquierda en pantallas ultra anchas. El `w-full` forzará al elemento a ocupar el 100% del contenedor padre flex y anulará el centrado horizontal. Usa siempre `mx-auto` explícitamente en el elemento hijo para garantizar que quede centrado dentro de su propia columna.