zugzbot 1.1.7 → 1.3.0

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

@@ -49,6 +49,14 @@ 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 externo (CRÍTICO — bugfix sesión 1176)**: Analiza la petición. Si contiene ALGUNA keyword de marketing/landing/auth/composite, animaciones/shaders/WebGL, AI components, o un nombre propio de cualquier catálogo:
+       - Keywords marketing/landing (shadcn): `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`
+       - Keywords animaciones (reactbits): `shader`, `webgl`, `gsap`, `framer-motion`, `three.js`, `drei`, `animated background`, `animated text`, `gradient mesh`, `magnet`, `floating dock`, `cursor`, `particles`, `noise`, `orbit`, `aurora`, `dither`, `iridescence`, `blob`, `glare`, `staggered`, `magic bento`, `electric border`, `metallic paint`
+       - Nombres propios: `akash`, `akash3444`, `shadcnui-blocks`, `shadcn-ui-blocks`, `basecn`, `shadcn blocks`, `reactbits`, `react-bits`, `david haz`
+       - **Acción obligatoria**: cargar la skill `shadcn-templates` (que ahora referencia las tools MCP `sdd_catalog_list_blocks`, `sdd_catalog_get_block` y `sdd_catalog_warm_index` — NUNCA uses `webfetch` directo a GitHub/reactbits.dev; esta cacheado).
+       - En modo HIL: llama `sdd_catalog_list_blocks({category, limit: 5, registry: 'all'})` y presenta las 2-3 mejores opciones con `preview_url` para que el usuario elija. **Incluir siempre `preview_url` en la respuesta** — para reactbits el demo es animado y el usuario puede ver cómo se ve antes de instalar.
+       - En modo autopiloto (`/loop`): llama `sdd_catalog_get_block({name})` sobre 2-3 candidatos (uno de cada registry) 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`.
@@ -86,6 +94,11 @@ Eres el coordinador principal del arnés de desarrollo SDD (Spec-Driven Developm
        - 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. **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):**
@@ -129,6 +142,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ó cualquier catálogo externo de UI (Akash shadcn-ui-blocks, basecn, reactbits.dev), 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_catalog_list_blocks`, `sdd_catalog_get_block`, etc.)
     3. **Mensaje Final MÁXIMO 10 LÍNEAS**:
        ```
        ✅ Sesión SDD completada
@@ -146,6 +164,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_catalog_list_blocks`, `sdd_catalog_get_block`, `sdd_catalog_warm_index` — cachean el catálogo unificado (Akash shadcn-ui-blocks + basecn + reactbits.dev) en `.openspec/cache/` con TTL 7d (Akash/Basecn) y 1d (reactbits). NUNCA uses `webfetch` directo a GitHub o reactbits.dev para descubrir bloques; usa siempre estas tools. Solo se soportan registries con catálogo JSON oficialmente discoverable.
 </mcp_guidelines>
 
 <communication_rules>

package/.opencode/rules/sdd-global.md

@@ -33,6 +33,14 @@ Para optimizar el tiempo de desarrollo, garantizar una experiencia visual premiu
   - **Preservación de Datos Dummy**: El archivo de datos del bloque (por ejemplo, `data.json` o constantes locales) debe mantenerse intacto en su ruta inyectada por la CLI en esta Fase A para garantizar que la vista se muestre de inmediato en el navegador exactamente idéntica al demo real.
 - **Sustitución Atómica de Datos en Fase B**: Una vez que el bloque compila e interactúa en el navegador de manera idéntica al demo con los datos de ejemplo, el Coder procederá de forma exclusiva a sustituir los datos mock por lógica y fetchings de datos dinámicos del backend, manteniendo intactos los contenedores estructurales del bloque (grids de diseño, paddings y contenedores flex) sin alteración alguna para evitar aberraciones visuales.
 - **Resolución Activa de Conflictos de Ruteo por Inyección de Bloques**: Si la CLI de Shadcn inyecta automáticamente una estructura de rutas (ej: `src/app/dashboard/page.tsx`) que compite con las rutas del contrato (como un route group `(dashboard)` o una ruta raíz), el Coder **debe** borrar o refactorizar de inmediato el código inyectado por defecto para evitar bucles de redirección infinitos o colisiones en el router.
+- **Catálogo Unificado `sdd_catalog` (3 registries, todos discoverables)**: Antes de inventar cualquier layout/bloque desde cero, el Spec-Writer (F1) y el Coder (F2) **deben** consultar `sdd_catalog_list_blocks({ registry: "all", category: "<cat>" })`. El catálogo cubre 3 fuentes con catálogo JSON oficial en un solo tool:
+  1. **`shadcn`** (akash3444/shadcn-ui-blocks, GitHub Contents API) — ~540 bloques Radix/Next.js curados. **Default** para marketing, landing, auth, dashboards, footers.
+  2. **`basecn`** (akash3444/basecn, GitHub Contents API) — ~60 bloques fork Base UI. Usar solo si el proyecto está en Base UI.
+  3. **`reactbits`** (reactbits.dev, `/r/registry.json` oficial shadcn-compatible) — 134 primitivas animadas × 4 variantes (JS-CSS/JS-TW/TS-CSS/TS-TW, default `TS-TW`). **Fuente preferente** para backgrounds animados, textos con efecto, cards interactivas, cursors custom, dock flotante. Tratar como third-party trust: revisar siempre el campo `dependencies` (suelen incluir `gsap`, `three`, `@react-three/fiber`, `motion`) y validar compat con el stack target antes de instalar.
+  - **Criterio de inclusion**: solo se soportan registries con catálogo JSON oficialmente discoverable. 21st.dev fue removido porque su catálogo es JS-rendered y rompe el principio de "siempre saber qué hay disponible antes de elegir".
+  - El comando install siempre viene en el campo `install_command` del resultado de `sdd_catalog_get_block`. **Prohibido** ejecutar `npx shadcn add` con una URL adivinada; usar siempre el `install_command` literal que devuelve la tool.
+  - El catálogo guarda caché local en `.openspec/cache/` con TTL diferenciado (7d shadcn/basecn, 1d reactbits) — **NUNCA** usar `webfetch` directo a GitHub o reactbits.dev, está cacheado.
+  - Todos los items exponen `preview_url`. Para reactbits el demo es animado vivo (`https://reactbits.dev/<BaseName>`) — el orchestrator debe **siempre** presentar el `preview_url` al usuario en modo HIL para que vea cómo se ve antes de elegir.
 
 ## 4. Soporte para Subdirectorios, Monorepos (targetDir) y Estándar Corporativo `src/`
 Si el proyecto o aplicación principal vive en un subdirectorio (ej. `next-app`, `frontend`, `backend`), se deben seguir estas directivas estrictas para mantener la consistencia y el "estándar corporativo con carpeta `src/`":

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

@@ -152,35 +152,119 @@ El `@sdd-spec-writer` utiliza de manera proactiva el MCP `shadcn` (`shadcn_searc
 ### Fase F2 (Implementation)
 El `@sdd-coder` utiliza el template base `nextjs-shadcn`. Si el contrato no detalla todos los sub-componentes o el Coder necesita verificar el comportamiento de un bloque antes de acoplarlo con el backend, debe ejecutar `shadcn_get_item_examples_from_registries` para ver ejemplos funcionales del componente real. Tras ejecutar la instalación con `npx shadcn@latest add`, el Coder debe contrastar los archivos inyectados con el mapa del contrato y limpiar de inmediato cualquier archivo redundante (como una página de inicio duplicada) que no coincida con el router oficial.
 
-## 5. Catálogo Externo Oficial: Shadcn UI Blocks (Akash)
+## 5. Catálogo Unificado de Bloques Externos (`sdd_catalog`)
 
-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.
+Además del catálogo nativo de Shadcn UI, el arnés expone un catálogo unificado de **3 registries** externos (todos con catálogo JSON oficial y discoverable programáticamente). Si el usuario pide cualquier interfaz (hero, footer, dashboard, login, AI chat, animated background, etc.), **TIENES LA OBLIGACIÓN** de explorar este catálogo ANTES de inventar desde cero.
 
-### 5.1 Flujo de Descubrimiento (Fase F1 - Spec-Writer)
-Si el usuario solicita una interfaz (ej: "necesito un hero", "haz un footer"), no asumas que debes programarlo a mano. Primero 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.). Selecciona mentalmente los que coincidan con la necesidad.
+### 5.0 Registries Soportados (todos discoverables)
 
-### 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` 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 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 y elígelo autónomamente sin preguntar.
+| Registry | Fuente de catálogo | Contenido | TTL | Notas |
+|---|---|---|---|---|
+| `shadcn` | akash3444/shadcn-ui-blocks (GitHub Contents API) | ~540 bloques Radix | 7d | **Default** para marketing/landing/auth/dashboards |
+| `basecn` | akash3444/basecn (GitHub Contents API) | ~60 bloques fork Base UI | 7d | Alternativa si el proyecto usa Base UI |
+| `reactbits` | reactbits.dev/r/registry.json (JSON oficial shadcn) | 134 bases × 4 variantes = 536 items | 1d | Primitivas animadas (backgrounds, text, cards, cursors, etc.) |
 
-### 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:
+> **Criterio de inclusion**: solo se soportan registries con catálogo JSON oficialmente discoverable. 21st.dev fue removido porque su catálogo es JS-rendered y requiere scraping para descubrir items nuevos — eso rompe el principio de "siempre saber qué hay disponible antes de elegir".
+
+### 5.1 Herramientas MCP Nativas del Arnés (PREFERENTE — `sdd_catalog_*`)
+
+**PROHIBIDO** usar `webfetch` directo a GitHub o reactbits.dev para descubrir bloques. El arnés expone 3 tools MCP dedicadas que cachean en `.openspec/cache/` y evitan redescubrimiento:
+
+- `sdd_catalog_list_blocks({ category?, query?, registry?, limit?, force_refresh? })`
+  - `registry`: `"shadcn"` | `"basecn"` | `"reactbits"` | `"all"` (default).
+  - Filtra por categoria exacta (`hero`, `pricing`, `backgrounds`, `text`, `cards`, `navigation`, ...) o substring libre (sobre `name`, `description`, `tags`).
+  - Para `reactbits`: devuelve las **134 bases** (cada una con `variants[]` y `default_variant`), NO las 536 variantes. Esto evita duplicados y permite ver opciones de un vistazo.
+- `sdd_catalog_get_block({ name, registry?, variant?, force_refresh? })`
+  - Formatos de `name`:
+    - shadcn/basecn: `"hero-06"`, `"sidebar-07"`
+    - reactbits: `"Dither"` (auto-resuelve a `Dither-TS-TW` por default) **o** `"Dither-JS-CSS"` (variante canónica completa)
+    - URL directa: `"https://reactbits.dev/r/Dither-TS-TW.json"` o `"https://shadcnui-blocks.com/r/radix/hero-06.json"`
+    - Namespace shadcn: `"@acme/button"`
+  - Para reactbits, parámetro opcional `variant`: `"JS-CSS" | "JS-TW" | "TS-CSS" | "TS-TW"` (default `"TS-TW"`). Aplicar solo cuando pasas el nombre base sin sufijo de variante.
+  - `registry` autodetecta por el formato; pasalo explícito solo si necesitas forzar.
+  - Devuelve `source_files[]`, `dependencies[]`, `preview_url`, `install_command` listo y metadatos `base_name` + `variant` (para reactbits).
+- `sdd_catalog_warm_index({ registry? })`
+  - Pre-calienta caches. Llamar al bootstrap (F0) o inicio de F1.
+
+### 5.2 Flujo de Descubrimiento (Fase F1 - Spec-Writer)
+
+Cuando el usuario pide una UI, sigue este orden de prioridad:
+
+1. **Primero** `sdd_catalog_list_blocks({ registry: "all", category: "<categoria>", limit: 10 })` — devuelve candidatos de los 3 registries simultáneamente.
+2. **Si el usuario pide animaciones/shaders/efectos visuales cinematograficos**, prioriza `registry: "reactbits"` (es donde estan las primitivas animadas reales: `Dither`, `Aurora`, `GlareHover`, `Magnet`, `StaggeredMenu`, `FloatingDock`, etc.).
+3. **Si el usuario pide paginas de marketing completas** (landing, pricing, features), prioriza `registry: "shadcn"` (bloques Radix mas completos con texto, CTAs, imagenes placeholder).
+4. **Si el usuario ya dio una URL** (`https://reactbits.dev/...` o `https://shadcnui-blocks.com/...`), ve directo a `sdd_catalog_get_block` con esa URL.
+5. **Presenta opciones con `preview_url`** para que el usuario vea cada una antes de elegir:
+   - **Asistido (HIL):** muestra `preview_url` (que el usuario puede abrir en navegador) + `install_command` para los 2-3 mejores candidatos y deja que elija. Si el usuario dice "ese", ejecuta el `install_command`.
+   - **Autopiloto (`/loop`):** inspecciona 2-3 candidatos con `sdd_catalog_get_block`, analiza dependencias y compat con el stack del contrato, elige autonomamente.
+
+### 5.3 Seleccion de Bloques (Interactiva o Autonoma)
+
+Cuando hay multiples opciones para una categoria (ej. 10 heroes):
+- **Modo Asistido (default):** pregunta al usuario con `question` o en chat: *"Tengo X opciones de [categoria]. ¿Quieres revisar alguna? Puedo darte el `preview_url` (ej. `https://shadcnui-blocks.com/blocks/hero-06` o `https://reactbits.dev/Dither`) para que elijas."*
+- **Modo Autopiloto:** lee el codigo de 2-3 opciones con `sdd_catalog_get_block` y elige sin preguntar.
+
+### 5.4 Inyeccion e Instalacion (Spec-Writer + Coder)
+
+- **Spec-Writer (F1):** En el `contract.json`, dentro de `frontend.components`, anota el bloque usando **el `install_url` o el `name` canonico** que devolvio `sdd_catalog_get_block`:
   ```json
   "frontend": {
     "components": [
-      "https://shadcnui-blocks.com/r/radix/footer-04.json"
+      { "name": "hero-06", "registry": "shadcn", "source": "akash3444/shadcn-ui-blocks" },
+      { "name": "Dither", "registry": "reactbits", "variant": "TS-TW", "source": "reactbits.dev/Dither" }
     ]
   }
   ```
-- **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, usa el `install_command` literal que devuelve `sdd_catalog_get_block` (campo `block.install_command`). Ejemplos reales:
   ```bash
-  npx shadcn@latest add https://shadcnui-blocks.com/r/radix/footer-04.json
+  # Akash Radix (shadcn CLI nativo)
+  npx shadcn@latest add https://shadcnui-blocks.com/r/radix/hero-06.json --yes
+  # Basecn
+  npx shadcn@latest add https://basecn.dev/r/footer-04.json --yes
+  # reactbits (variante TS-TW explicita)
+  npx shadcn@latest add https://reactbits.dev/r/Dither-TS-TW.json --yes
   ```
-  La CLI se encargará automáticamente de descargar el código y resolver dependencias internas.
+  La CLI v3 de Shadcn negocia `Accept: application/json` automaticamente, descarga el codigo y resuelve las `registryDependencies`.
+
+### 5.5 Validacion Post-Instalacion (BLOQUEANTE)
+
+Tras instalar cualquier bloque externo, ejecuta INMEDIATAMENTE:
+1. `npx tsc --noEmit` para detectar imports rotos o packages faltantes.
+2. Verifica que todos los archivos declarados en `source_files[]` (devuelto por `sdd_catalog_get_block`) fueron creados fisicamente.
+3. Si faltan archivos, reintenta con `--overwrite`.
+4. **Para bloques reactbits con dependencias pesadas** (`gsap`, `three`, `@react-three/fiber`, `motion`): confirma que el `package.json` del proyecto las incluye; si no, `npm install <deps>` antes de continuar. Revisa el campo `dependencies[]` del JSON retornado por `sdd_catalog_get_block`.
+5. **Solo entonces** reporta exito al orquestador.
+
+**Bug conocido**: `Can't resolve 'shadcn/tailwind.css'` en Tailwind v4 requiere `npm install shadcn` antes de continuar.
+
+### 5.6 reactbits.dev - Detalles de Variantes
+
+reactbits.dev es el registry mas "vivo" del catalogo unificado. Cada componente base se publica en **4 variantes** con sufijo `-<Lang>-<Style>`:
+
+| Sufijo | Lenguaje | Styling |
+|---|---|---|
+| `JS-CSS` | JavaScript | CSS plano (.css) |
+| `JS-TW` | JavaScript | Tailwind v4 (.tw) |
+| `TS-CSS` | TypeScript | CSS plano |
+| `TS-TW` | TypeScript | Tailwind v4 |
+
+- **Default del arnés**: `TS-TW` (TypeScript + Tailwind v4, alineado al stack Next.js 16 + Shadcn + Tailwind v4 del harness).
+- **Para usar otra variante**: `sdd_catalog_get_block({ name: "Dither", variant: "JS-CSS", registry: "reactbits" })`.
+- **El preview_url es siempre por base**: `https://reactbits.dev/Dither` (muestra el demo vivo con animación real, ideal para que el usuario vea cómo se ve antes de instalar).
+- **Las dependencias son reales**: `gsap@^3.13.0`, `three`, `@react-three/fiber@^9.3.0`, `postprocessing`, `motion`. **Third-party trust obligatorio**: validar compat con el stack target antes de instalar.
+- **Mapa curado de categorias** (dentro de `sdd_catalog.ts`, constante `REACTBITS_POPULAR_BY_CATEGORY`): las ~85 bases más populares organizadas en `backgrounds`, `text`, `cards`, `navigation`, `buttons`, `animations`, `cursors`, `misc`. Las bases fuera del mapa caen en `misc` pero son buscables por `query`.
+
+### 5.7 Preview UX — Cómo se ve antes de instalar
+
+**Todos los items del catálogo unificado exponen `preview_url`** que el orchestrator debe presentar al usuario en modo HIL para que vea la animación/componente real antes de decidir:
+
+| Registry | Preview URL | Tipo de preview |
+|---|---|---|
+| shadcn | `https://shadcnui-blocks.com/blocks/<name>` | iframe del demo oficial |
+| basecn | `https://basecn.dev/blocks/<name>` | iframe del demo oficial |
+| reactbits | `https://reactbits.dev/<BaseName>` | demo vivo con animacion real + codigo a la derecha |
+
+Cuando el orchestrator presente opciones al usuario, **siempre incluir el `preview_url`** en el chat. Para reactbits en particular, el demo es animado y se ve inmediatamente cómo se mueve la UI en el navegador del usuario — esto cierra el ciclo "imaginar como se ve → ver real → decidir instalar" sin hacer conjeturas.
 
 ---
 

package/.opencode/templates/nextjs-shadcn/components.json

@@ -16,5 +16,8 @@
     "lib": "@/lib",
     "hooks": "@/hooks"
   },
-  "iconLibrary": "lucide"
+  "iconLibrary": "lucide",
+  "registries": {
+    "@react-bits": "https://reactbits.dev/r/{name}.json"
+  }
 }

package/.opencode/tools/sdd_bootstrap.ts

@@ -328,6 +328,27 @@ export const bootstrap_nextjs_shadcn = tool({
     ]
     for (const f of standardFiles) copyFileSafe(f)
 
+    // Post-copy: garantizar que components.json del target tenga los registries
+    // externos preconfigurados (idempotente: si ya existen, no los duplica).
+    const targetComponentsJson = path.resolve(targetPath, "components.json")
+    if (fs.existsSync(targetComponentsJson)) {
+      try {
+        const cfg = JSON.parse(fs.readFileSync(targetComponentsJson, "utf8"))
+        if (!cfg.registries) cfg.registries = {}
+        if (!cfg.registries["@react-bits"]) {
+          cfg.registries["@react-bits"] = "https://reactbits.dev/r/{name}.json"
+          fs.writeFileSync(
+            targetComponentsJson,
+            JSON.stringify(cfg, null, 2),
+            "utf8"
+          )
+          filesCopied.push("components.json (registries.@react-bits inyectado)")
+        }
+      } catch (e) {
+        // best-effort: si falla el parse, no bloqueamos el bootstrap
+      }
+    }
+
     if (targetDir !== ".") {
       const configFiles = [
         "tsconfig.json",