zugzbot 1.0.38 → 1.0.40

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

@@ -66,7 +66,7 @@ Eres el Programador de Código (sdd-coder) del arnés SDD. Tu trabajo es codific
   </bootstrap_obligatorio>
 
   <consolidar_instalaciones>
-    Si necesitas paquetes adicionales o componentes shadcn, instálalos agrupados en un solo comando de terminal o llamada de herramienta (`npm install a b` o `npx shadcn@2.1.8 add x y --yes`). No los instales uno a uno.
+    Si necesitas paquetes adicionales o componentes shadcn, instálalos agrupados en un solo comando de terminal o llamada de herramienta (`npm install a b` o `npx shadcn@latest add x y --yes`). No los instales uno a uno.
   </consolidar_instalaciones>
 
   <tests_y_contratos>
@@ -85,7 +85,12 @@ Eres el Programador de Código (sdd-coder) del arnés SDD. Tu trabajo es codific
 <coding_cheatsheet>
 - **Linear/Brand tokens**: Los tokens se inyectan en `globals.css` vía CSS vars. PROHIBIDO reescribir `globals.css` desde cero o usar colores Hex manuales en componentes. Usa variables como `var(--color-brand-primary)`.
 - **Estado**: Declara estados centralizados con `useState` en el componente padre (`owner` o `AppLayout`) y pásalos como props. Evita declarar estados compartidos en hijos.
-- **Instalación de Shadcn Segura**: La herramienta de shadcn a utilizar en F2 es ESTRICTAMENTE `npx shadcn@2.1.8 add <componentes>`. TIENES PROHIBIDO USAR `@latest` (ej. `npx shadcn@latest add`). Usar `@latest` rompe la aplicación instalando dependencias en pre-release de base-ui. Usa siempre `npx shadcn@2.1.8`.
+- **Instalación de Shadcn Segura**: La herramienta de shadcn a utilizar en F2 es `npx shadcn@latest add <componentes>` (o simplemente `npx shadcn add`). Utiliza siempre la última versión final estable de Shadcn para garantizar la compatibilidad con Tailwind v4 y permitir la descarga de bloques complejos de la comunidad y del registro oficial (como dashboards, sidebars y formularios modernos) sin errores 404.
+- **Next.js & Tailwind v4 Style Resolution**: En Tailwind v4, si `globals.css` importa `@import "shadcn/tailwind.css";`, debes asegurarte de instalar el paquete ejecutable `shadcn` ejecutando `npm install shadcn` o el compilador fallará.
+- **Next.js Auth Redirects robustas (Evitar bucles/parpadeo)**:
+  - Usa siempre `router.replace("/")` en lugar de `push` para redirecciones de login.
+  - Para evitar efectos concurrentes o solapados en Strict Mode, usa un `useRef(false)` en redirecciones asíncronas para dispararlas solo una vez.
+  - En layouts protegidos por SSR, para evitar que parpadeen spinners o modales antes de hidratar la sesión en cliente, declara un estado `mounted` (`useEffect` asignando `setMounted(true)`) y retorna `null` si `!mounted`.
 - **Iconos**: Importa desde `lucide-react`. Usa `data-icon="inline-start"` para espaciados automáticos.
 </coding_cheatsheet>
 

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

@@ -46,6 +46,10 @@ Eres el Validador de Contratos (sdd-tester) del flujo SDD. Tu trabajo es ejecuta
 - **Minimizar Lecturas/Búsquedas**: No realices búsquedas ciegas (`glob` repetidos) ni lecturas innecesarias. Guíate estrictamente por la lista `files_affected` provista en tu sección del brief activo para conocer qué archivos de producción se han modificado y dónde están ubicados los tests correspondientes.
 - **Memoria de Errores**: Tienes PROHIBIDO llamar a `brain_read_memory`. Toda la información histórica sobre fallos técnicos ha sido inyectada directamente en `.opencode/active-brief.md`. Consúltala allí.
 - **Restricción de Archivos**: Solo se te permite modificar/escribir archivos en la fase 'F3_VERIFICATION', y únicamente archivos que contengan 'test', 'spec', 'tests/' o '.openspec/' en su ruta. Tienes estrictamente prohibido modificar el código fuente de producción.
+- **Extensión JSX en Tests**: Todo archivo de pruebas que contenga JSX, monte componentes o simule iconos (mocks de Lucide con `<svg>`) **DEBE** tener la extensión `.tsx` obligatoriamente (nunca `.ts` ya que esbuild/Vitest fallarán en la compilación).
+- **Selectores de Formularios Robustos**: Evita usar `getByLabelText(/password/i)` si hay botones con aria-label que coincidan de forma ambigua. Prefiere placeholders como `getByPlaceholderText()` o expresiones regulares con anclajes estrictos como `/^Password$/` para aislar el input deseado.
+- **Ocultamiento CSS vs Presencia DOM**: Para barras de navegación o sidebars colapsados por CSS (`hidden`, `w-0`), evita usar `.not.toBeInTheDocument()`. El texto sigue existiendo físicamente en el DOM, por lo que el test fallará. Verifica clases CSS de visibilidad directamente o usa `.not.toBeVisible()` de `@testing-library/jest-dom`.
+- **Mocks Dinámicos de Hooks**: Mocks de hooks que controlan toggles (como `useTheme` de `next-themes`) deben usar getters locales reactivos en la definición del mock, o las pruebas sucesivas de clics de toggle reportarán el mismo valor (el mock estático no retiene el cambio).
 - **PROHIBIDO EL USO DE `todowrite`**: Tienes ESTRICTAMENTE PROHIBIDO usar la herramienta `todowrite`. El seguimiento de progreso está centralizado en el Orquestador. No la invoques en absoluto.
 - **Batcheo Extremo de ESCRITURA/EDICIÓN (CRÍTICO)**: NO modifiques ni crees archivos de tests uno a uno para luego correr el test runner cada vez en un bucle lento. Debes usar BATCH EXTREMO. Si tienes que modificar o crear 5 archivos de pruebas, debes enviar en TU MISMA respuesta todas las llamadas a `write` o `edit` necesarias al mismo tiempo (concurrencia). Solo después de enviar todos los cambios corres `vitest run` o `pytest`.
 </constraints>

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

@@ -25,8 +25,9 @@ Cuando el estado del sistema tiene `loopMode === true` (activado mediante el com
 ## 3. Uso Mandatorio de Bloques Prehechos de Shadcn UI (dashboard, sidebar, login, etc.)
 Para optimizar el tiempo de desarrollo, garantizar una experiencia visual premium y evitar la invención de layouts o formularios comunes desde cero:
 - **Prioridad de Bloques**: Al diseñar cualquier interfaz de usuario (Layouts, Dashboards, Paneles de Control, Vistas de Configuración, Páginas de Autenticación, Tablas de Datos, Gráficos), los agentes **deben** buscar y utilizar de forma prioritaria los bloques prehechos del registro oficial `@shadcn` (como `dashboard-01`, `sidebar-01` al `16`, `login-01` al `05`, `signup-01` al `05`).
-- **Búsqueda Proactiva**: El Spec-Writer **debe** consultar el registro utilizando las herramientas del MCP `shadcn` (`shadcn_search_items_in_registries`, `shadcn_list_items_in_registries`) al redactar el contrato (F1) para identificar qué bloques se ajustan a la necesidad, y declararlos en `frontend.components` y `files_affected` de `contract.json`.
-- **Implementación por Distribución y Composición**: El Coder (F2) **debe** instalar estos bloques usando `npx shadcn@latest add <block-name>` (ej: `dashboard-01`, `login-03`) en su proyecto, integrando y distribuyendo los elementos con el estado y lógica del backend, sin rediseñar o codificar layouts que ya existen de forma oficial.
+- **Búsqueda Proactiva**: El Spec-Writer **debe** consultar el registro utilizando las herramientas del MCP `shadcn` (`shadcn_search_items_in_registries`, `shadcn_list_items_in_registries`) al redactar el contrato (F1) para identificar qué bloques se ajustan a la necesidad, y declararlos en `frontend.components` y `files_affected` de `contract.json`. Además, el Spec-Writer **debe** invocar `shadcn_view_items_in_registries` sobre los bloques complejos seleccionados para inspeccionar por adelantado sus archivos, rutas y dependencias inyectadas por defecto, anticipando cualquier colisión de ruteo y documentándolo con precisión en el contrato.
+- **Implementación por Distribución y Composición**: El Coder (F2) **debe** instalar estos bloques usando `npx shadcn@latest add <block-name>` (ej: `dashboard-01`, `login-03`) en su proyecto, integrando y distribuyendo los elementos con el estado y lógica del backend, sin rediseñar o codificar layouts que ya existen de forma oficial. El Coder puede usar `shadcn_get_item_examples_from_registries` para ver ejemplos de implementación realistas y aplicarlos limpiamente a la primera, reduciendo el desvío visual.
+- **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.
 
 ## 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/`":
@@ -42,6 +43,9 @@ Cualquier desarrollo de interfaz de usuario (Dashboards, Landings, Formularios,
   - Se deben mapear obligatoriamente a variables semánticas de Shadcn/Tailwind que soporten modo claro/oscuro dinámico por defecto (ej. `bg-background`, `bg-muted/50`, `bg-accent`, `text-foreground`, `text-muted-foreground`, `border-border`).
 - **Gráficos Dinámicos y Reactivos (SVG/Recharts Theme Sync):**
   - Cualquier componente de gráficos (como Recharts o visores vectoriales SVG) que use atributos de pintado inline (`stroke`, `fill`, `color`) debe resolver sus colores mediante un custom hook o variables dinámicas que consuman el estado del tema actual (`useTheme` de `next-themes` u homólogo), previniendo que líneas o textos queden invisibles en modo oscuro.
+  - Está estrictamente prohibido usar variables CSS puras directamente en `stroke` o `fill` de SVG si estas no son resueltas de forma dinámica. Si es necesario, utiliza una paleta de colores hexadecimales fija de alto contraste y compatible con ambos modos claro y oscuro (ej: `#0072f5` para líneas y barras, o una paleta de sectores sólida para PieCharts) que garantice legibilidad 100% en fondos claros y oscuros, manteniendo solo los ejes y rejillas de fondo (grids) referenciando variables semánticas.
+- **Evitar Solapamiento de Sidebar (Sidebar Overlap Prevention):**
+  - Al implementar barras laterales colapsables de Shadcn (`Sidebar`), el Coder debe asegurarse de que el contenedor del contenido principal use de forma robusta `<SidebarInset>` o una estructura flexbox flexible (ej: `flex flex-1 flex-col`) que responda al estado del sidebar. Está estrictamente prohibido usar posicionamiento fijo o absoluto en el sidebar sin un espaciador o contenedor dinámico que evite que el sidebar se sobreponga al contenido en pantallas anchas.
 - **Robustez HTML y Regla de No-Nesting en Triggers:**
   - Al utilizar componentes contenedores de Radix/Shadcn UI (como `TooltipTrigger`, `DropdownMenuTrigger`, `DialogTrigger`, `SheetTrigger`), está estrictamente PROHIBIDO anidar un elemento interactivo nativo (como `<button>` o `<a>`) directamente dentro de otro trigger que ya renderice un botón por defecto.
   - Para evitar la hidratación rota y HTML inválido, se debe usar siempre el prop `asChild` en el trigger de Radix o delegar los props correctamente usando las directivas del componente de base.
@@ -49,8 +53,21 @@ Cualquier desarrollo de interfaz de usuario (Dashboards, Landings, Formularios,
   - **Tooltips:** Todo botón que contenga únicamente un icono de acción debe estar envuelto en un componente `Tooltip` con su descripción respectiva.
   - **Skeletons y Empty States:** Las vistas de carga deben contar con animaciones de `Skeleton` fluidas. Las listas o tablas vacías deben presentar un `Empty State` visual y explicativo agradable con iconos y un botón de acción alternativo, nunca una página o cuadro en blanco.
 
-## 6. Mockups Visuales y Validación Temprana de Layout (F0/F1)
+## 6. Estándar de Robustez en Autenticación, Ruteo y SSR (Next.js)
+Para evitar bucles de redirección ("redirect loops") y pantallas parpadeantes (flickers/blinking) tras iniciar sesión:
+- **Evitar Race Conditions en Redirecciones:** En el formulario de login, usa siempre `router.replace("/")` en lugar de `push` tras un login exitoso para evitar empujar estados duplicados al historial.
+- **Evitar useEffects Cruzados Activos:** Si usas un guard de redirección en `LoginPage` o similar para usuarios ya autenticados, utiliza un `useRef(false)` para controlar que la redirección asíncrona solo se dispare una vez y no se encadene con re-renderizados concurrentes de React.
+- **Evitar Flash de Carga SSR en Layouts:** Para layouts o guards protegidos, nunca asumas estados por defecto que pinten elementos cargando (spinners) durante el servidor. Comprueba si el componente está montado (`mounted === true`) antes de evaluar la sesión en el cliente y renderizar el contenido. Retorna `null` antes de montar para evitar desajustes de hidratación (hydration mismatch).
+- **Eliminación Obligatoria de Placeholders de Página Raíz:**
+  - El Coder debe asegurar que la página de entrada de la aplicación (`src/app/page.tsx` o similar) no se quede con el texto placeholder por defecto. Debe ser reemplazada por el componente principal especificado o contener una redirección limpia (`redirect("/dashboard")`) hacia la vista principal protegida o pública definida por el contrato.
+
+## 7. Mockups Visuales y Validación Temprana de Layout (F0/F1)
 Para optimizar el diseño, evitar cambios de arquitectura estructurales a mitad del desarrollo (como rediseñar pestañas a layouts de sidebar lateral) y garantizar alineación inmediata con las expectativas del usuario:
 - **Propuesta de Layout Visual:** Durante la transición de F0 a F1, el `@sdd-spec-writer` **debe** proponer un mockup textual o diagrama de cajas ASCII detallando la distribución estructural de la pantalla (Layout general, barras laterales sticky, contenedores de contenido responsivos y anchos de pantalla recomendados, ej. `max-w-6xl` vs `w-full`).
 - **Ancho y Densidad Modernos:** Por defecto, los layouts complejos deben evitar contenedores angostos restrictivos como `max-w-3xl` para maximizar el aprovechamiento de pantallas de escritorio modernas mediante rejillas responsivas (`grid grid-cols-1 md:grid-cols-X gap-6`).
 - **Aprobación Temprana:** El orquestador presentará esta propuesta visual al usuario en la fase F1. Una vez aprobada la disposición espacial y la estructura de navegación local (ej: sidebar split vs horizontal tabs), el `@sdd-coder` la ejecutará exactamente como se acordó, previniendo loops redundantes de maquetación en fases tardías.
+
+## 8. Abstracción y Prohibición de Parchar Código en F3/Orquestador
+Para mantener la limpieza y disciplina en la ventana de contexto de la sesión:
+- **Orquestador No-Coder:** El orquestador principal (`sdd-orchestrator`) tiene estrictamente prohibido usar herramientas de edición (`edit` o `write`) para modificar código de producción o archivos de test.
+- **Rollback Disciplinado:** Si en la fase `F3_VERIFICATION` el linter o los tests reportan errores, el orquestador **debe** transicionar el estado a `F2_IMPLEMENTATION` mediante `sdd_core_set_phase` y re-invocar al subagente experto (`sdd-coder`) para que realice la corrección cleanly. No se permiten parches rápidos a mitad de fase de test.

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

@@ -63,6 +63,13 @@ ENV HOSTNAME="0.0.0.0"
 CMD ["node", "server.js"]
 ```
 
+#### 🛠️ **Manejo de Conflictos de Dependencias y Sincronización de Lockfile**
+En proyectos donde las dependencias cambian con frecuencia por la adición automática de componentes de Shadcn, es muy común que el comando estricto `npm ci --frozen-lockfile` falle dentro de Docker con errores de desincronización de lockfile (ej: `Invalid: lock file's picomatch... does not satisfy`).
+
+Para solucionar esto de manera robusta:
+1. **Solución Local Primaria**: El Coder debe añadir de manera explícita la dependencia par conflictiva en su `package.json` (ej: `"picomatch": "^4.0.4"`) y ejecutar `npm install` localmente para regenerar y sincronizar un `package-lock.json` limpio antes de intentar compilar el contenedor.
+2. **Estrategia Fallback en Dockerfile**: Si la sincronización del lockfile sigue presentando conflictos intermitentes e inestabilidad insalvable, el Deployer tiene autorización para modificar el paso de instalación del Dockerfile de un estricto `npm ci` a un dinámico `npm install --no-audit --no-fund` para permitir que el motor de resolución de Node resuelva las dependencias pares de forma adaptativa.
+
 #### **.dockerignore**
 ```ignore
 node_modules

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

@@ -41,65 +41,53 @@ Cada fase tiene un **gate explícito** (HIL del usuario) antes de transicionar a
 
 ---
 
-## 3. Trampas conocidas (EVITAR siempre)
+## 3. Trampas del Flujo Maestro (EVITAR siempre)
 
 ### Trampa 1: Listar marcas de diseño una por una
-**NO HAGAS**: 4 llamadas a `oh-my-design_list_references` con `category: "saas"`, "fintech", "ecommerce", "consumer" solo para mostrar opciones.
-**HAZ**: 1 llamada a `sdd_list_design_recommendations({ use_case: "all", max_per_category: 3 })`. Si el usuario quiere "Personalizar", ahí sí usa `oh-my-design_search_by_vibe`.
+**NO HAGAS**: Hacer múltiples llamadas a `oh-my-design_list_references` para mostrar opciones al usuario en F0.
+**HAZ**: Haz una única llamada consolidada a `sdd_list_design_recommendations({ use_case: "all", max_per_category: 3 })`.
 
 ### Trampa 2: Crear la carpeta del spec en 2 steps
-**NO HAGAS**: `sdd_create_spec_folder("mi-spec")` + `sdd_set_phase("F1_CONTRACT", ...)` en 2 calls (race condition de timestamp, observado en sesión 137a).
-**HAZ**: 1 sola call: `sdd_set_phase({ phase: "F1_CONTRACT", spec_name: "mi-spec" })`. Devuelve `activeContract` listo.
+**NO HAGAS**: Llamar a `sdd_create_spec_folder("mi-spec")` y luego a `sdd_set_phase("F1_CONTRACT", ...)` por separado (causa race conditions en el timestamp).
+**HAZ**: Transiciona en un solo paso: `sdd_set_phase({ phase: "F1_CONTRACT", spec_name: "mi-spec" })`.
 
-### Trampa 3: Reescribir `globals.css` desde cero
-**NO HAGAS**: Sobrescribir `src/app/globals.css` quitando las variables shadcn (`--color-border: var(--border)`, etc.) al aplicar tokens de marca. Build falla con `Cannot apply unknown utility class 'border-border'` (observado en sesión 137a).
-**HAZ**: Usar `sdd_apply_brand_tokens` que inyecta en un bloque `@theme inline` aparte, preservando las variables shadcn.
+### Trampa 3: Cargar `next-devtools` MCP en sesión normal
+**NO HAGAS**: Activar `next-devtools` por defecto. Inyecta miles de palabras de instrucciones redundantes al contexto, desperdiciando tokens de razonamiento.
+**HAZ**: Mantenerlo deshabilitado en `opencode.json` y activarlo únicamente bajo demanda si se depura un error muy específico del runtime de Next.js.
 
-### Trampa 4: Cargar `next-devtools` MCP en sesión normal
-**NO HAGAS**: Dejar `next-devtools` habilitado. Su tool `init` inyecta 1000+ palabras de "FORGET ALL PRIOR KNOWLEDGE" (~8K tokens de reasoning desperdiciado — el coder tuvo el mayor consumo de tokens de la sesión 137a por esta razón).
-**HAZ**: Está deshabilitado por defecto en `opencode.json`. Solo activarlo on-demand si un subagente reporta un error específico de Next 16.
+### Trampa 4: Escribir el contrato desde cero en F1
+**NO HAGAS**: Redactar cientos de líneas de `contract.json` de forma manual.
+**HAZ**: Cargar la skill `sdd-quickstart` y rellenar los huecos `{{...}}` de su plantilla preconfigurada.
 
-### Trampa 5: Escribir el contrato desde cero
-**NO HAGAS**: Redactar 600+ líneas de `contract.json` en cada sesión. Riesgo alto de inconsistencia.
-**HAZ**: Cargar la skill `sdd-quickstart` y usar la plantilla pre-rellenada. Solo rellenar `{{...}}`.
+### Trampa 5: Permitir que el Coder escriba los tests en F2
+**NO HAGAS**: Desarrollar la lógica y luego redactar las pruebas (causa bucles redundantes entre Coder y Tester).
+**HAZ**: Que el Spec-Writer declare las aserciones en el contrato en F1. El Coder solo implementa el código de negocio necesario para que pasen.
 
-### Trampa 6: Tests en F2
-**NO HAGAS**: Que el coder escriba los tests después de implementar (loop Coder → Tester → Coder, observado en sesión 137a).
-**HAZ**: Que el spec-writer (en F1) cree los tests con assertions reales basadas en `test_scenarios`. El coder solo implementa el código de producción para hacerlos pasar.
+### Trampa 6: Exceso de actualizaciones de TODOs con `todowrite`
+**NO HAGAS**: Llamar a `todowrite` para actualizar el estado del arnés tras cada pequeño cambio o fase.
+**HAZ**: Inicializar la lista al inicio, marcar `in_progress` al arrancar una fase, y marcar los TODOs completados en bloque al final.
 
-### Trampa 7: 5+ llamadas a `todowrite` durante la sesión
-**NO HAGAS**: Actualizar la lista de TODOs cada vez que cambias de fase (observado 5 veces en sesión 137a).
-**HAZ**: Crear la lista al inicio. Marcar `in_progress` solo cuando arrancas la fase. Marcar `completed` **en bloque** al final.
+### Trampa 7: Cargar skills duplicadas en subagentes
+**NO HAGAS**: Cargar skills generales (como `sdd-methodology`) de manera redundante en subagentes especializados (como `@sdd-deployer` o `@sdd-tester`) que ya la tienen incorporada en su prompt base.
+**HAZ**: Limitar la carga de skills estrictamente a tareas que requieran sus plantillas específicas.
 
-### Trampa 8: `lint: false` en el orquestador
-**NO HAGAS**: Dejar que el tester descubra imports no usados en tests.
-**HAZ**: El self-audit del coder (F2) y el auto-lint gate de `sdd_set_phase("F3_VERIFICATION")` ya lo previenen. El orquestador debe **reportar el `lintWarning`** al usuario antes de delegar al tester.
+### Trampa 8: Invocar Playwright en modo Console
+**NO HAGAS**: Abrir navegadores o tomar snapshots si `verificationMode` es `"console"`.
+**HAZ**: Confiar plenamente en Vitest/Pytest y curls rápidos desde la terminal.
 
-### Trampa 9: Cargar skills duplicadas
-**NO HAGAS**: Cargar skills de forma genérica en subagentes si su contenido ya está integrado en su prompt de identidad (ej. cargar `sdd-methodology` en `@sdd-deployer` o `@sdd-tester`). Esto duplica los tokens de input consumidos.
-**HAZ**: Limitar la carga de skills a los casos proactivos indicados o cuando se requieran plantillas/recursos específicos de la skill (ej. `sdd-quickstart` en `@sdd-spec-writer`).
+### Trampa 9: Orquestador usurpador (Ruptura de Abstracción)
+**NO HAGAS**: Editar código de producción o escribir/ejecutar tests directamente desde el orquestador si un subagente falla o se queda sin pasos.
+**HAZ**: Re-invocar al subagente experto (`sdd-coder` o `sdd-tester`) mediante la herramienta `task` pasándole el `task_id` original para que continúe limpiamente.
 
-### Trampa 10: Playwright en modo Console
-**NO HAGAS**: Invocar herramientas de Playwright (`playwright_browser_navigate`, `playwright_browser_snapshot`, etc.) si `verificationMode` está configurado en `"console"`. Esto consume tiempo y reasoning innecesarios.
-**HAZ**: En modo `console`, confía en pruebas unitarias/integración (Vitest) y verificaciones directas con curls/logs. No abras navegadores.
-
-### Trampa 11: Orquestador usurpador (Ruptura de Abstracción)
-**NO HAGAS**: Permitir que el Orquestador principal (`sdd-orchestrator`) tome el rol de escribir el código de producción o escribir/ejecutar tests directamente si un subagent (ej. `@sdd-coder`) falla o alcanza el límite de pasos ("Maximum Steps Reached"). Esto ensucia la ventana de contexto principal de la sesión.
-**HAZ**: Re-invoca al mismo subagente usando la herramienta `task`, pasando el `task_id` original del subagente interrumpido e instruyéndole: "Te quedaste sin pasos. Continúa y finaliza los archivos pendientes".
-
-### Trampa 12: Obsesión por alineación de consola (Pixel-Peeping)
-**NO HAGAS**: Gastar múltiples iteraciones o miles de tokens en el razonamiento de `@sdd-coder` tratando de lograr una alineación perfecta de columnas con espacios exactos en salidas CLI o tablas ASCII.
-**HAZ**: Usa funciones estándar de formateo de strings de tu lenguaje (como `ljust()`, `rjust()` o `center()` en Python; o formateadores sencillos en JS/TS) para lograr una presentación razonable de forma inmediata y avanzar directamente a la creación de pruebas.
-
-### Trampa 13: Omitir la disposición espacial y propuesta de Layout en F1
-**NO HAGAS**: Redactar el contrato en F1 listando únicamente archivos de forma abstracta sin definir o validar la geometría estructural y distribución de la UI (ej. si se requieren Sidebars locales de navegación vs pestañas horizontales planas), asumiendo anchos angostos y estáticos (como `max-w-3xl`) o rompiendo el soporte de modo oscuro con colores absolutos (`bg-white`).
-**HAZ**: El spec-writer debe proponer proactivamente en F1 un bosquejo textual o diagrama ASCII de la interfaz y validar con el usuario un layout responsivo amplio (`max-w-6xl` o superior). Además, el coder debe implementar soporte semántico dinámico de temas de entrada (sin colores duros) y sincronizar colores SVG/gráficos dinámicamente con el tema actual.
+### Trampa 10: Obsesión por alineación exacta en consola (Pixel-Peeping)
+**NO HAGAS**: Consumir iteraciones intentando alinear espacios exactos en salidas CLI o tablas ASCII.
+**HAZ**: Usar funciones estándar de formateo de strings de tu lenguaje (`ljust()`, `rjust()`) y priorizar la lógica de negocio y las pruebas.
 
 ---
 
 ## 4. Stack cerrado (NO abrir)
 
-- **Frontend**: Next.js 15/16 + React 19 + TypeScript + Tailwind v4 + Shadcn UI v2.1.8 (Radix UI) + lucide-react + Vitest. **PROHIBIDO**: Shadcn v4/Base-UI (por inestabilidad y falta de soporte actual), HeroUI, Chakra, Material-UI.
+- **Frontend**: Next.js 15/16 + React 19 + TypeScript + Tailwind v4 + Shadcn UI @latest (Radix UI) + lucide-react + Vitest. **PROHIBIDO**: Shadcn v4/Base-UI (por inestabilidad y falta de soporte actual), HeroUI, Chakra, Material-UI.
 - **Backend**: Python 3.11+ + FastAPI + Pydantic v2 + Uvicorn + Pytest + Ruff. **PROHIBIDO**: Django, Flask, sync SQLAlchemy.
 - **Persistencia**: localStorage (frontend-only) o PostgreSQL con pgvector. **PROHIBIDO**: MongoDB (excepto si se justifica), Redis como primary store.
 - **Containerización**: Docker multi-stage con `node:20-alpine` (Next) o `python:3.11-slim` (FastAPI). Usuario no-root. Healthcheck via `node -e` (no wget en alpine).

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

@@ -160,6 +160,7 @@ Copia y adapta los IDs y descripciones que apliquen. Borra los que no apliquen.
 - **NO escribas más de 5-6 `test_scenarios`** para modo `console`. Más de eso no acelera la entrega, solo retrasa F2.
 - **NO incluyas escenarios `visual` o `e2e` si `verificationMode` es `console`.** El tester los rechazará.
 - **NO omitas la disposición espacial y propuesta de Layout**: El spec-writer DEBE proponer un bosquejo textual o diagrama ASCII de la disposición espacial de la UI en F1 (ej. layouts con sidebar lateral para configuración o paneles complejos en lugar de simples pestañas tradicionales planas) y acordar anchos de pantalla generosos (`max-w-6xl` o superior, evitando el limitante `max-w-3xl`) con el usuario antes de transicionar a F2. Esto previene reestructuraciones estéticas costosas y asegura entregas de alta gama a la primera.
+- **NO omitas la página raíz (`src/app/page.tsx`) en el mapeo de archivos afectados**: El spec-writer DEBE asegurar que `src/app/page.tsx` quede registrado explícitamente y que el contrato aclare si la ruta raíz `/` servirá el contenido principal de la aplicación, o si simplemente ejecutará una redirección limpia (`redirect("/dashboard")`) hacia el panel principal. Esto evita que el Coder conserve el placeholder por defecto de bootstrap y cause inconsistencias visuales o de navegación.
 
 ---
 

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

@@ -19,12 +19,14 @@ Esta habilidad proporciona un **flujo de trabajo estructurado en 4 pasos** para
 - En el **Paso 3**, no aplican los mocks de React, Lucide ni `crypto.randomUUID` en JS. Si necesitas mockear en Python, usa `unittest.mock` (como `patch` o `MagicMock`).
 - En el **Paso 4**, ejecuta `ruff check src/` o similar para linting, y `python -m pytest tests/ -v` para ejecutar toda la suite de pruebas de una sola llamada consolidada.
 
-### Paso 1: Leer solo lo indispensable (Máximo 3 reads)
+### Paso 1: Leer solo lo indispensable (Máximo 3 reads) y asegurar entorno
 1. **Contrato**: Lee únicamente `contract.json` para extraer los `test_scenarios` y el `verificationMode`.
 2. **Setup**: Lee `src/test/setup.ts` o `vitest.config.ts` para confirmar si ya hay polyfills.
 3. **Breve examen**: Lee el componente principal (`AppLayout` o similar) para confirmar el `stateFlow`. 
 *NO uses `glob` ciegos para buscar archivos del proyecto.*
 
+**VERIFICACIÓN CLAVE DE DEPENDENCIAS**: Asegúrate de que `package.json` tenga instaladas las devDependencies necesarias para pruebas de React: `happy-dom`, `@testing-library/jest-dom` y `@testing-library/dom`. Si no están presentes, instálalas en un solo comando unificado: `npm install --save-dev happy-dom @testing-library/jest-dom @testing-library/dom`.
+
 ### Paso 2: Autogenerar plantillas de tests (BLOQUEANTE)
 Antes de escribir cualquier test a mano, **DEBES** ejecutar:
 ```bash
@@ -35,17 +37,24 @@ Esto creará automáticamente las plantillas correspondientes en base a los `tes
 ### Paso 3: Completar aserciones usando Mocks Estandarizados (Evitar fallos de librerías)
 Completa los tests importando los componentes reales. Si Vitest o happy-dom fallan por dependencias externas de Shadcn UI o Lucide, aplica estos mocks centralizados:
 
-#### Mock de Lucide Icons (si fallan por SVG/React)
+#### Mock Dinámico de Lucide Icons (Recomendado para evitar fallos de iconos faltantes)
+Para evitar que tests fallen porque falta mockear un icono específico (ej. `PanelLeft`, `Search`, etc.), usa un Proxy que mockea dinámicamente CUALQUIER icono exportado por `lucide-react`:
 ```typescript
-vi.mock('lucide-react', () => ({
-  Sun: () => <div data-testid="icon-sun" />,
-  Moon: () => <div data-testid="icon-moon" />,
-  Plus: () => <div data-testid="icon-plus" />,
-  Trash2: () => <div data-testid="icon-trash" />,
-  History: () => <div data-testid="icon-history" />,
-  Clock: () => <div data-testid="icon-clock" />,
-  Calculator: () => <div data-testid="icon-calculator" />
-}));
+vi.mock('lucide-react', () => {
+  return new Proxy(
+    {},
+    {
+      get: (target, prop) => {
+        // Retorna un componente funcional con el testid del icono solicitado
+        const IconComponent = (props: any) => (
+          <span data-testid={`icon-${String(prop).toLowerCase()}`} {...props} />
+        );
+        IconComponent.displayName = String(prop);
+        return IconComponent;
+      },
+    }
+  );
+});
 ```
 
 #### Mock de Base UI / Shadcn Radix Primitives
@@ -74,6 +83,38 @@ if (!globalThis.crypto) {
 }
 ```
 
+#### Mock de `next-themes` (Soporte reactivo de Tema)
+Para probar toggles de tema sin que fallen en clics sucesivos:
+```typescript
+let currentTheme = 'light';
+const mockSetTheme = vi.fn((newTheme: string) => {
+  currentTheme = newTheme;
+});
+
+vi.mock('next-themes', () => ({
+  useTheme: () => ({
+    get theme() { return currentTheme; },
+    setTheme: mockSetTheme,
+    get resolvedTheme() { return currentTheme; },
+  }),
+}));
+```
+
+#### Mock de `next/navigation` (Router y Pathname)
+```typescript
+const mockPush = vi.fn();
+const mockReplace = vi.fn();
+
+vi.mock('next/navigation', () => ({
+  useRouter: () => ({
+    push: mockPush,
+    replace: mockReplace,
+    prefetch: vi.fn(),
+  }),
+  usePathname: () => '/',
+}));
+```
+
 ### Paso 4: Ejecutar Lint y Tests consolidando comandos
 1. Corre el linter enfocado en el código fuente:
 ```bash
@@ -91,3 +132,24 @@ npx vitest run
 1. **PROHIBIDO Playwright en modo Console**: Si `verificationMode === "console"`, no instancies ni corras ningún test de Playwright, ni navegues con tools de Playwright. Solo corre tests de Vitest.
 2. **PROHIBIDO modificar código de features para "hacer pasar" el test**: Si el código tiene un bug, haz rollback a `F2_IMPLEMENTATION` reportando el error exacto al coder. No parches la lógica del negocio en F3.
 3. **Consolidación**: No corras `vitest` archivo por archivo. Corre la suite completa en una sola llamada a `bash`.
+4. **REGLA DE ORO DE ASERCIONES DE TEXTO (Acentos y Encoding)**: Para evitar fallos tontos de aserción por diferencias de codificación en caracteres con tildes (ej: `ó` vs `\u00f3`, `ñ` vs `\u00f1`), usa siempre expresiones regulares insensibles a mayúsculas y comodines (ej: `screen.getByText(/Inicia sesi.n/i)` o `screen.getByText(/contrase.a/i)`). Nunca utilices comparaciones estrictas de cadenas de texto acentuadas.
+
+---
+
+## ⚠️ Trampas Comunes de Pruebas (Testing Gotchas)
+
+### 1. Extensión incorrecta en archivos de pruebas con JSX
+* **No hagas**: Usar la extensión `.ts` para archivos de tests que renderizan primitivas de HTML o JSX o que mockean componentes de interfaz (causa fallos de compilación inmediatos en Vitest).
+* **Haz**: Toda suite de pruebas que monte componentes o contenga JSX debe grabarse con la extensión `.tsx` obligatoriamente.
+
+### 2. Selectores ambiguos para campos interactivos comunes
+* **No hagas**: Usar queries genéricas e insensibles como `screen.getByLabelText(/password/i)` si existen múltiples elementos en el DOM que contengan esa palabra (ej: botones de "Show password"). Esto lanzará un error de "Found multiple elements".
+* **Haz**: Usa selectores de coincidencia exacta como `screen.getByLabelText(/^Password$/)` o busca mediante placeholders específicos (`screen.getByPlaceholderText(...)`).
+
+### 3. Validar ausencia de elementos ocultos por CSS con `not.toBeInTheDocument()`
+* **No hagas**: Tratar de validar que un menú o modal colapsado/oculto ya no es visible utilizando `expect(queryByText("...")).not.toBeInTheDocument()`. Si el elemento simplemente se oculta con clases de CSS (como `hidden`, `w-0` u `opacity-0`), el nodo sigue existiendo físicamente en el DOM.
+* **Haz**: Verifica la visibilidad real usando `.not.toBeVisible()` de `@testing-library/jest-dom`, o comprueba directamente las clases CSS de colapso.
+
+### 4. Mocks estáticos de hooks con estado
+* **No hagas**: Mockear hooks que controlan toggles (como `useTheme` de `next-themes`) usando un retorno fijo estático. Al simular el clic en el botón de toggle, el test fallará o entrará en bucles porque el valor del estado simulado permanece congelado.
+* **Haz**: Declara variables mutables locales a nivel de archivo de pruebas y usa getters dinámicos en la definición del mock de Vitest para simular los cambios de estado correctamente.

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

@@ -9,19 +9,19 @@ compatibility: opencode
 
 A framework for building ui, components and design systems. Components are added as source code to the user's project via the CLI.
 
-> **IMPORTANT:** Run all CLI commands using the project's package runner: `npx shadcn@2.1.8`, `pnpm dlx shadcn@2.1.8`, or `bunx --bun shadcn@2.1.8` — based on the project's `packageManager`. Examples below use `npx shadcn@2.1.8` but substitute the correct runner for the project.
+> **IMPORTANT:** Run all CLI commands using the project's package runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest` — based on the project's `packageManager`. Examples below use `npx shadcn@latest` but substitute the correct runner for the project.
 
 ## Current Project Context
 
 ```json
-!`npx shadcn@2.1.8 info --json`
+!`npx shadcn@latest info --json`
 ```
 
-The JSON above contains the project config and installed components. Use `npx shadcn@2.1.8 docs <component>` to get documentation and example URLs for any component.
+The JSON above contains the project config and installed components. Use `npx shadcn@latest docs <component>` to get documentation and example URLs for any component.
 
 ## Principles
 
-1. **Use existing components first.** Use `npx shadcn@2.1.8 search` to check registries before writing custom UI. Check community registries too.
+1. **Use existing components first.** Use `npx shadcn@latest search` to check registries before writing custom UI. Check community registries too.
 2. **Compose, don't reinvent.** Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table.
 3. **Use built-in variants before custom styles.** `variant="outline"`, `size="sm"`, etc.
 4. **Use semantic colors.** `bg-primary`, `text-muted-foreground` — never raw values like `bg-blue-500`.
@@ -52,7 +52,7 @@ These rules are **always enforced**. Each links to a file with Incorrect/Correct
 ### Component Structure → [composition.md](../../docs/shadcn/rules/composition.md)
 
 - **Items always inside their Group.** `SelectItem` → `SelectGroup`. `DropdownMenuItem` → `DropdownMenuGroup`. `CommandItem` → `CommandGroup`.
-- **Use `asChild` (radix) or `render` (base) for custom triggers.** Check `base` field from `npx shadcn@2.1.8 info`. → [base-vs-radix.md](../../docs/shadcn/rules/base-vs-radix.md)
+- **Use `asChild` (radix) or `render` (base) for custom triggers.** Check `base` field from `npx shadcn@latest info`. → [base-vs-radix.md](../../docs/shadcn/rules/base-vs-radix.md)
 - **Dialog, Sheet, and Drawer always need a Title.** `DialogTitle`, `SheetTitle`, `DrawerTitle` required for accessibility. Use `className="sr-only"` if visually hidden.
 - **Use full Card composition.** `CardHeader`/`CardTitle`/`CardDescription`/`CardContent`/`CardFooter`. Don't dump everything in `CardContent`.
 - **Button has no `isPending`/`isLoading`.** Compose with `Spinner` + `data-icon` + `disabled`.
@@ -77,8 +77,8 @@ These rules are **always enforced**. Each links to a file with Incorrect/Correct
 
 ### CLI
 
-- **Never decode preset codes or build preset URLs manually.** Use `npx shadcn@2.1.8 preset decode <code>`, `preset url <code>`, or `preset open <code>`. For project-aware preset detection, use `npx shadcn@2.1.8 preset resolve`.
-- **Apply preset codes directly with the CLI.** Use `npx shadcn@2.1.8 apply <code>` for existing projects, or `npx shadcn@2.1.8 init --preset <code>` when initializing.
+- **Never decode preset codes or build preset URLs manually.** Use `npx shadcn@latest preset decode <code>`, `preset url <code>`, or `preset open <code>`. For project-aware preset detection, use `npx shadcn@latest preset resolve`.
+- **Apply preset codes directly with the CLI.** Use `npx shadcn@latest apply <code>` for existing projects, or `npx shadcn@latest init --preset <code>` when initializing.
 
 ## Key Patterns
 
@@ -151,7 +151,7 @@ The injected project context contains these key fields:
 - **`resolvedPaths`** → exact file-system destinations for components, utils, hooks, etc.
 - **`framework`** → routing and file conventions (e.g. Next.js App Router vs Vite SPA).
 - **`packageManager`** → use this for any non-shadcn dependency installs (e.g. `pnpm add date-fns` vs `npm install date-fns`).
-- **`preset`** → resolved preset code and values for the current project. Use `npx shadcn@2.1.8 preset resolve --json` when you only need preset information.
+- **`preset`** → resolved preset code and values for the current project. Use `npx shadcn@latest preset resolve --json` when you only need preset information.
 
 See [cli.md — `info` command](../../docs/shadcn/cli.md) for the full field reference.
 
@@ -166,29 +166,29 @@ DO NOT run bash commands to view docs. Instead, explicitly use the built-in MCP
 
 ## Workflow
 
-1. **Get project context** — already injected above. Run `npx shadcn@2.1.8 info` again if you need to refresh.
+1. **Get project context** — already injected above. Run `npx shadcn@latest info` again if you need to refresh.
 2. **Check installed components first** — before running `add`, always check the `components` list from project context or list the `resolvedPaths.ui` directory. Don't import components that haven't been added, and don't re-add ones already installed.
-3. **Find components** — `npx shadcn@2.1.8 search`.
-4. **Get docs and examples** — use the MCP tool `shadcn_get_item_examples_from_registries` with query strings like `'button demo'` or `'login block example'` to see exact implementations. To preview changes to installed components, use `npx shadcn@2.1.8 add --diff`.
-5. **Install or update** — `npx shadcn@2.1.8 add`. When updating existing components, use `--dry-run` and `--diff` to preview changes first (see [Updating Components](#updating-components) below).
-6. **Fix imports in third-party components** — After adding components from community registries (e.g. `@bundui`, `@magicui`), check the added non-UI files for hardcoded import paths like `@/components/ui/...`. These won't match the project's actual aliases. Use `npx shadcn@2.1.8 info` to get the correct `ui` alias (e.g. `@workspace/ui/components`) and rewrite the imports accordingly. The CLI rewrites imports for its own UI files, but third-party registry components may use default paths that don't match the project.
+3. **Find components** — `npx shadcn@latest search`.
+4. **Get docs and examples** — use the MCP tool `shadcn_get_item_examples_from_registries` with query strings like `'button demo'` or `'login block example'` to see exact implementations. To preview changes to installed components, use `npx shadcn@latest add --diff`.
+5. **Install or update** — `npx shadcn@latest add`. When updating existing components, use `--dry-run` and `--diff` to preview changes first (see [Updating Components](#updating-components) below).
+6. **Fix imports in third-party components** — After adding components from community registries (e.g. `@bundui`, `@magicui`), check the added non-UI files for hardcoded import paths like `@/components/ui/...`. These won't match the project's actual aliases. Use `npx shadcn@latest info` to get the correct `ui` alias (e.g. `@workspace/ui/components`) and rewrite the imports accordingly. The CLI rewrites imports for its own UI files, but third-party registry components may use default paths that don't match the project.
 7. **Review added components** — After adding a component or block from any registry, **always read the added files and verify they are correct**. Check for missing sub-components (e.g. `SelectItem` without `SelectGroup`), missing imports, incorrect composition, or violations of the [Critical Rules](#critical-rules). Also replace any icon imports with the project's `iconLibrary` from the project context (e.g. if the registry item uses `lucide-react` but the project uses `hugeicons`, swap the imports and icon names accordingly). Fix all issues before moving on.
 8. **Registry must be explicit** — When the user asks to add a block or component, **do not guess the registry**. If no registry is specified (e.g. user says "add a login block" without specifying `@shadcn`, `@tailark`, `owner/repo`, etc.), ask which registry to use. Never default to a registry on behalf of the user.
 9. **Switching presets** — Ask the user first: **overwrite**, **partial**, **merge**, or **skip**?
-   - **Inspect current preset**: `npx shadcn@2.1.8 preset resolve`. Use `--json` when you need structured values.
-   - **Inspect incoming preset**: `npx shadcn@2.1.8 preset decode <code>`. Use `preset url <code>` or `preset open <code>` to share or open the preset builder.
-   - **Overwrite**: `npx shadcn@2.1.8 apply <code>`. Overwrites detected components, fonts, and CSS variables.
-   - **Partial**: `npx shadcn@2.1.8 apply <code> --only theme,font`. Updates only the selected preset parts without reinstalling UI components. Supported values are `theme` and `font`; comma-separated combinations are allowed. `icon` is intentionally not supported, because icon changes may require full component reinstall and transforms.
-   - **Merge**: `npx shadcn@2.1.8 init --preset <code> --force --no-reinstall`, then run `npx shadcn@2.1.8 info` to list installed components, then for each installed component use `--dry-run` and `--diff` to [smart merge](#updating-components) it individually.
-   - **Skip**: `npx shadcn@2.1.8 init --preset <code> --force --no-reinstall`. Only updates config and CSS, leaves components as-is.
+   - **Inspect current preset**: `npx shadcn@latest preset resolve`. Use `--json` when you need structured values.
+   - **Inspect incoming preset**: `npx shadcn@latest preset decode <code>`. Use `preset url <code>` or `preset open <code>` to share or open the preset builder.
+   - **Overwrite**: `npx shadcn@latest apply <code>`. Overwrites detected components, fonts, and CSS variables.
+   - **Partial**: `npx shadcn@latest apply <code> --only theme,font`. Updates only the selected preset parts without reinstalling UI components. Supported values are `theme` and `font`; comma-separated combinations are allowed. `icon` is intentionally not supported, because icon changes may require full component reinstall and transforms.
+   - **Merge**: `npx shadcn@latest init --preset <code> --force --no-reinstall`, then run `npx shadcn@latest info` to list installed components, then for each installed component use `--dry-run` and `--diff` to [smart merge](#updating-components) it individually.
+   - **Skip**: `npx shadcn@latest init --preset <code> --force --no-reinstall`. Only updates config and CSS, leaves components as-is.
    - **Important**: Always run preset commands inside the user's project directory. `apply` only works in an existing project with a `components.json` file. The CLI automatically preserves the current base (`base` vs `radix`) from `components.json`. If you must use a scratch/temp directory (e.g. for `--dry-run` comparisons), pass `--base <current-base>` explicitly — preset codes do not encode the base.
 
 ## Updating Components
 
 When the user asks to update a component from upstream while keeping their local changes, use `--dry-run` and `--diff` to intelligently merge. **NEVER fetch raw files from GitHub manually — always use the CLI.**
 
-1. Run `npx shadcn@2.1.8 add <component> --dry-run` to see all files that would be affected.
-2. For each file, run `npx shadcn@2.1.8 add <component> --diff <file>` to see what changed upstream vs local.
+1. Run `npx shadcn@latest add <component> --dry-run` to see all files that would be affected.
+2. For each file, run `npx shadcn@latest add <component> --diff <file>` to see what changed upstream vs local.
 3. Decide per file based on the diff:
    - No local changes → safe to overwrite.
    - Has local changes → read the local file, analyze the diff, and apply upstream updates while preserving local modifications.
@@ -199,55 +199,55 @@ When the user asks to update a component from upstream while keeping their local
 
 ```bash
 # Create a new project.
-npx shadcn@2.1.8 init --name my-app --preset base-nova
-npx shadcn@2.1.8 init --name my-app --preset a2r6bw --template vite
+npx shadcn@latest init --name my-app --preset base-nova
+npx shadcn@latest init --name my-app --preset a2r6bw --template vite
 
 # Create a monorepo project.
-npx shadcn@2.1.8 init --name my-app --preset base-nova --monorepo
-npx shadcn@2.1.8 init --name my-app --preset base-nova --template next --monorepo
+npx shadcn@latest init --name my-app --preset base-nova --monorepo
+npx shadcn@latest init --name my-app --preset base-nova --template next --monorepo
 
 # Initialize existing project.
-npx shadcn@2.1.8 init --preset base-nova
-npx shadcn@2.1.8 init --defaults  # shortcut: --template=next --preset=nova (base style implied)
+npx shadcn@latest init --preset base-nova
+npx shadcn@latest init --defaults  # shortcut: --template=next --preset=nova (base style implied)
 
 # Apply a preset to an existing project.
-npx shadcn@2.1.8 apply a2r6bw
-npx shadcn@2.1.8 apply a2r6bw --only theme
-npx shadcn@2.1.8 apply a2r6bw --only font
-npx shadcn@2.1.8 apply a2r6bw --only theme,font
+npx shadcn@latest apply a2r6bw
+npx shadcn@latest apply a2r6bw --only theme
+npx shadcn@latest apply a2r6bw --only font
+npx shadcn@latest apply a2r6bw --only theme,font
 
 # Inspect preset codes and project preset state.
-npx shadcn@2.1.8 preset decode a2r6bw
-npx shadcn@2.1.8 preset url a2r6bw
-npx shadcn@2.1.8 preset open a2r6bw
-npx shadcn@2.1.8 preset resolve
-npx shadcn@2.1.8 preset resolve --json
+npx shadcn@latest preset decode a2r6bw
+npx shadcn@latest preset url a2r6bw
+npx shadcn@latest preset open a2r6bw
+npx shadcn@latest preset resolve
+npx shadcn@latest preset resolve --json
 
 # Add components.
-npx shadcn@2.1.8 add button card dialog
-npx shadcn@2.1.8 add @magicui/shimmer-button
-npx shadcn@2.1.8 add owner/repo/item
-npx shadcn@2.1.8 add --all
+npx shadcn@latest add button card dialog
+npx shadcn@latest add @magicui/shimmer-button
+npx shadcn@latest add owner/repo/item
+npx shadcn@latest add --all
 
 # Preview changes before adding/updating.
-npx shadcn@2.1.8 add button --dry-run
-npx shadcn@2.1.8 add button --diff button.tsx
-npx shadcn@2.1.8 add @acme/form --view button.tsx
-npx shadcn@2.1.8 add owner/repo/item --dry-run
+npx shadcn@latest add button --dry-run
+npx shadcn@latest add button --diff button.tsx
+npx shadcn@latest add @acme/form --view button.tsx
+npx shadcn@latest add owner/repo/item --dry-run
 
 # Search registries.
-npx shadcn@2.1.8 search @shadcn -q "sidebar"
-npx shadcn@2.1.8 search @tailark -q "stats"
-npx shadcn@2.1.8 search owner/repo -q "login"
-npx shadcn@2.1.8 search                          # all configured registries
-npx shadcn@2.1.8 search @shadcn -q "menu" -t ui  # filter by item type
+npx shadcn@latest search @shadcn -q "sidebar"
+npx shadcn@latest search @tailark -q "stats"
+npx shadcn@latest search owner/repo -q "login"
+npx shadcn@latest search                          # all configured registries
+npx shadcn@latest search @shadcn -q "menu" -t ui  # filter by item type
 
 # Get component docs and example URLs.
 # ALWAYS use your MCP Tools (shadcn_get_item_examples_from_registries) instead of bash for docs.
 
 # View registry item details (for items not yet installed).
-npx shadcn@2.1.8 view @shadcn/button
-npx shadcn@2.1.8 view owner/repo/item
+npx shadcn@latest view @shadcn/button
+npx shadcn@latest view owner/repo/item
 ```
 
 **Named presets:** `nova`, `vega`, `maia`, `lyra`, `mira`, `luma`

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

@@ -73,13 +73,16 @@ npx shadcn@latest add <component-name>
 Al diseñar o codificar páginas con Shadcn UI, sigue estas reglas estrictas:
 
 ### 3.1 Componer, no reinventar (MANDATORIO)
-Utiliza las plantillas y bloques existentes de Shadcn como el estándar absoluto de tu interfaz. Queda **estrictamente prohibido** escribir layouts, páginas de autenticación o cuadros de mando desde cero si ya existe un bloque oficial que resuelva el caso de uso:
-- **Dashboards**: Utiliza `dashboard-01` como base para cualquier panel de control interactivo.
+Utiliza las plantillas y bloques existentes de Shadcn como el estándar absoluto de tu interfaz. Queda **estrictamente prohibido** escribir layouts, páginas de autenticación o cuadros de mando desde cero si ya existe un bloque oficial que resuelva el caso de uso. **No estás restringido a ningún subconjunto fijo de componentes**: tienes total libertad para buscar en el catálogo completo de 97+ bloques oficiales y componentes primitivos de Shadcn:
+- **Dashboards**: Utiliza `dashboard-01` o cualquier variante de panel de control interactivo oficial.
 - **Sidebars / Barras de Navegación**: Utiliza `sidebar-01` al `16` para paneles laterales funcionales, colapsables, dinámicos o anidados. No programes componentes de navegación complejos a mano.
 - **Login / Registro**: Utiliza `login-01` al `05` y `signup-01` al `05` para flujos de login y registro de usuarios.
 - **Gráficos y Métricas**: Busca y añade bloques de gráficos oficiales de Recharts (`chart-area-*`, `chart-bar-*`, `chart-pie-*`, `chart-radar-*`) para dar vida a la visualización de datos.
 
-Busca layouts de dashboards o formularios complejos en el registro mediante el MCP `shadcn` antes de escribir cualquier código personalizado. Una vez agregado el bloque, distribuye y adapta sus elementos con el estado y la lógica de tu aplicación.
+Busca layouts de dashboards o formularios complejos en el registro mediante el MCP `shadcn` antes de escribir cualquier código personalizado. Una vez agregado el bloque, distribuye y adapta sus elementos con el estado y la lógica de tu aplicación. Te motivamos a explorar todo el ecosistema de bloques pre-creados por Shadcn para armar una UI robusta y moderna.
+
+**REGLA CRÍTICA DE RUTAS DUPLICADAS POR SHADCN CLI**:
+Al agregar un bloque interactivo complejo (como `dashboard-01`), el CLI de Shadcn puede inyectar automáticamente archivos en directorios fijos (como `src/app/dashboard/page.tsx`). El Coder **debe** verificar inmediatamente si existe una colisión con la estructura de rutas establecida por el contrato (`contract.json`) —por ejemplo, si el contrato establece un Route Group `src/app/(dashboard)/page.tsx` que sirve en la raíz `/`—. Si ocurre esto, el Coder tiene la obligación de **borrar, mover o refactorizar de inmediato el archivo inyectado automáticamente** para eliminar la duplicidad de rutas, evitando así bucles infinitos de redirección o errores fatales de compilación del router de Next.js.
 
 ### 3.2 Form Layouts (FieldGroup + Field)
 Para estructurar campos de formularios, no uses `div`s arbitrarios con clases de espaciado complejas. Usa las composiciones semánticas oficiales de Shadcn:
@@ -109,25 +112,19 @@ Para estructurar campos de formularios, no uses `div`s arbitrarios con clases de
 ### 3.4 Sin Placeholders en Producción
 Los datos dummy y placeholders deben reemplazarse inmediatamente por estados y hooks reales en el frontend que llamen a las APIs del backend (ej. estados de carga, manejo de errores de llamada, y datos dinámicos).
 
-### 3.5 Estética de Diseño Premium y Layouts (OBLIGATORIO)
-Queda **estrictamente prohibido** generar interfaces visualmente planas, vacías o que parezcan un "mínimo producto viable" básico (por ejemplo, una sola caja minimalista en el centro de un fondo blanco plano con un botón gris). 
-
-El diseño debe ser profesional y generar impacto visual instantáneo. Sigue estas directrices:
-- **Estructura de Layout Completa**: Toda herramienta, calculadora o pantalla debe estar contenida en un layout profesional. Usa barras de navegación superiores (`Header`), paneles laterales colapsables (`Sidebar`), menús de usuario con avatares, y una barra de estado o pie de página.
-- **Grids de KPIs y Métricas**: Añade tarjetas estadísticas en la parte superior de la página para resumir datos clave (ej. número de cálculos realizados, tiempo de respuesta promedio, tasa de éxito) utilizando iconos, números destacados y pequeños indicadores porcentuales.
-- **Gráficos e Historiales**: Si hay tablas o historiales, hazlos interactivos. Usa bordes redondeados (`rounded-xl`), sombras suaves, efectos de hover en las filas y, de ser posible, integra gráficos modernos (ej. utilizando `@/components/ui/chart` o Recharts) para representar tendencias.
-- **Colores Semánticos y Gradientes**: Utiliza gradientes sutiles y la paleta de colores HSL/OKLCH del tema en lugar de colores puros. Asegúrate de que el botón de cambiar tema (Modo Claro/Oscuro) esté visible en la barra de navegación y funcione de manera impecable.
-- **Estados Dinámicos y Micro-animaciones**: Añade pequeños efectos de transición y hover (`transition-all duration-200`) en botones, inputs y tarjetas para que la interfaz se sienta "viva" y responda a las acciones del usuario.
+### 3.5 Reglas de Diseño y Estándares de Calidad (Consolidadas)
+* **Estándar Semántico**: Consulta y aplica estrictamente la **Sección 5 de `.opencode/rules/sdd-global.md`** para la prevención de colores fijos (hardcoded light/dark), sincronización de temas en gráficos Recharts, prevención de solapamientos del sidebar (Sidebar Overlap) y la regla de no anidamiento en triggers de Radix.
+* **Componentes de Calidad**: Toda interfaz debe estar pulida con skeletons de carga fluidos, empty states agradables con iconos ilustrativos, y tooltips descriptivos para cualquier botón basado únicamente en iconos.
 
 ---
 
 ## 4. Flujo de Trabajo en SDD
 
 ### Fase F1 (Spec-Driven Contract)
-El `@sdd-spec-writer` utiliza el MCP `shadcn` (`mcp__shadcn__search_items`, `mcp__shadcn__get_item`) para documentar en el contrato (`contract.json`) qué componentes y bloques se usarán para la UI y verificar sus APIs/propiedades expuestas.
+El `@sdd-spec-writer` utiliza de manera proactiva el MCP `shadcn` (`shadcn_search_items_in_registries`, `shadcn_list_items_in_registries`) para encontrar bloques. **Es obligatorio** usar la herramienta `shadcn_view_items_in_registries` para inspeccionar el contenido completo, la estructura de archivos y las dependencias del bloque seleccionado antes de cerrar el contrato. Esto le permite al Spec-Writer mapear con exactitud los archivos que se generarán en `files_affected` y documentar explícitamente cualquier potencial colisión de ruteo en el `contract.json`.
 
 ### Fase F2 (Implementation)
-El `@sdd-coder` utiliza el template base `nextjs-shadcn` y ejecuta `npx shadcn@latest add` para instalar los componentes requeridos para la interfaz. Implementa las vistas componiendo dichos bloques y vinculando el estado con el backend.
+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.
 
 ### Fase F3 (Verification)
 El `@sdd-tester` ejecuta las pruebas según el modo de verificación especificado en el contrato (`settings.verificationMode`):

package/.opencode/skills/stack-validator/SKILL.md

@@ -66,11 +66,12 @@ Para garantizar consistencia y escalabilidad en todos los proyectos, la estructu
    className={cn("base-classes", condition && "extra", className)}
    ```
 5. **Iconos**: usar `lucide-react` (`import { Icon } from "lucide-react"`).
-6. **Block/Template installation**: usar el MCP `shadcn` para browse/search/install:
-   - Dashboards → `mcp__shadcn__get_item` con `@shadcn/dashboard-01`
+6. **Block/Template installation**: usar el MCP `shadcn` para browse/search/install. **NOTA CRÍTICA: NO existe ninguna restricción de lista fija**. Tienes libertad absoluta y la obligación proactiva de buscar e instalar CUALQUIER componente primitivo o bloque del catálogo oficial de Shadcn UI que se adapte al caso de uso de la aplicación (entre los 97+ bloques disponibles como dashboards, sidebars colapsables, login, charts, etc.):
+   - Dashboards → `@shadcn/dashboard-01`
    - Landings → `@shadcn/landing-hero`, `@shadcn/pricing`, etc.
-   - Auth flows → `@shadcn/login-01`, `@shadcn/signup-01`
+   - Auth flows → `@shadcn/login-01` al `05`, `@shadcn/signup-01` al `05`
    - Forms complejos → `@shadcn/settings`, `@shadcn/data-table`
+   - Sidebars → `@shadcn/sidebar-01` al `16`
 7. **Shadcn v4 (Base UI)**: En Shadcn UI v4.11.0+, la biblioteca primitiva es `@base-ui/react` (no Radix UI). La propiedad `asChild` **no existe**. Para evitar HTML inválido y problemas de SEO/accesibilidad, no anides interactives (`<Button><Link>`). Aplica las clases de estilo del botón directamente sobre el elemento `<Link>` de Next.js.
 8. **Compatibilidad Turbopack + CSS**: Turbopack no resuelve directivas `@import` para archivos CSS de `node_modules` (ej. `@import "tw-animate-css"` o `@import "shadcn/tailwind.css"`). En Tailwind CSS v4, define las variables y estilos inline en `globals.css` en lugar de importar desde `node_modules`.
 9. **Despliegue y Next Config**: Todo proyecto de Next.js debe estar configurado para Docker standalone en `next.config.ts`:

package/.opencode/tools/brain.ts

@@ -75,7 +75,7 @@ const writeBrainFile = (filePath: string, title: string, sections: Record<string
 }
 
 export const save_memory = tool({
-  description: "Guarda un aprendizaje, decisión de diseño, ruta concreta, resolución de error o memoria del proyecto en el archivo .openspec/brain.md. Es acumulativo y añade una marca de tiempo.",
+  description: "Guarda una memoria o aprendizaje clave en .openspec/brain.md de forma acumulativa.",
   args: {
     category: tool.schema.string().describe("Categoría o sección donde clasificar la memoria (ej: 'design', 'learnings', 'routing', 'errors')"),
     content: tool.schema.string().describe("El contenido o aprendizaje exacto que se desea guardar. Se recomienda ser conciso y claro.")
@@ -115,7 +115,7 @@ export const save_memory = tool({
 })
 
 export const read_memory = tool({
-  description: "Recupera la memoria y los aprendizajes del proyecto del archivo .openspec/brain.md. Si se especifica una categoría, solo lee esa sección para optimizar tokens y contexto. Si no se especifica, lista las categorías disponibles.",
+  description: "Recupera la memoria y los aprendizajes del proyecto de .openspec/brain.md.",
   args: {
     category: tool.schema.string().optional().describe("La categoría específica a leer (ej: 'design', 'learnings', 'routing', 'errors'). Si no se provee, se listarán las categorías disponibles.")
   },

package/.opencode/tools/sdd_bootstrap.ts

@@ -101,7 +101,7 @@ function detectPythonPackageManager(root: string): "uv" | "pip" {
 
 // Tool: sdd_bootstrap_status
 export const bootstrap_status = tool({
-  description: "Reporta el estado de bootstrap del proyecto (qué plantilla se usó, cuándo, qué componentes shadcn están instalados, versión de Node y package manager). Si el proyecto no está bootstrapped, retorna NOT_BOOTSTRAPPED. Útil para que el coder verifique antes de empezar a codear.",
+  description: "Reporta el estado de bootstrap del proyecto.",
   args: {},
   async execute(args, context) {
     const root = getRoot(context)
@@ -143,7 +143,7 @@ export const bootstrap_status = tool({
 
 // Tool: sdd_bootstrap_nextjs_shadcn
 export const bootstrap_nextjs_shadcn = tool({
-  description: "Inicializa un proyecto Next.js 16 + Shadcn UI + Tailwind v4 + Vitest a partir de la plantilla canónica en .opencode/templates/nextjs-shadcn/. Es IDEMPOTENTE: si el proyecto ya está inicializado y no se pasa force=true, no toca nada. Copia archivo-por-archivo (sin pisar los existentes), mergea package.json, y opcionalmente instala dependencias y shadcn components.",
+  description: "Inicializa un proyecto Next.js 16 + Shadcn UI + Tailwind v4 + Vitest.",
   args: {
     targetDir: tool.schema.string().default(".").describe("Subdirectorio donde se inicializará el proyecto Next.js (ej: 'next-app' o '.')."),
     components: tool.schema.array(tool.schema.string()).default([]).describe("Lista de shadcn components a instalar (ej: ['button','input','table']). Vacío = no instalar shadcn components."),
@@ -297,7 +297,7 @@ export const bootstrap_nextjs_shadcn = tool({
     let componentsError: string | null = null
     if (args.components && args.components.length > 0) {
       try {
-        const cmd = `npx shadcn@2.1.8 add ${args.components.join(" ")} --yes --overwrite`
+        const cmd = `npx shadcn@latest add ${args.components.join(" ")} --yes --overwrite`
         execSync(cmd, {
           cwd: targetPath,
           stdio: "ignore",
@@ -353,7 +353,7 @@ export const bootstrap_nextjs_shadcn = tool({
 
 // Tool: sdd_bootstrap_fastapi
 export const bootstrap_fastapi = tool({
-  description: "Inicializa un proyecto FastAPI + Pydantic + Uvicorn + Pytest + Ruff a partir de la plantilla canónica en .opencode/templates/fastapi-sdd/. Es IDEMPOTENTE: si el proyecto ya está inicializado y no se pasa force=true, no toca nada. Copia archivo-por-archivo (sin pisar los existentes), opcionalmente instala dependencias con uv (fallback pip).",
+  description: "Inicializa un proyecto FastAPI + Pydantic + Uvicorn + Pytest + Ruff.",
   args: {
     targetDir: tool.schema.string().default(".").describe("Subdirectorio donde se inicializará el proyecto FastAPI (ej: 'backend' o '.')."),
     extras: tool.schema.array(tool.schema.string()).default([]).describe("Lista de paquetes Python adicionales a instalar (ej: ['sqlalchemy','pydantic-settings','pytest-asyncio']). Vacío = no instalar extras extra."),
@@ -543,7 +543,7 @@ export const bootstrap_fastapi = tool({
 
 // Tool: sdd_bootstrap_agnostic
 export const bootstrap_agnostic = tool({
-  description: "Inicializa un proyecto de tipo script, tooling o agnóstico de forma idempotente (crea un package.json básico, requirements.txt, o estructura plana de archivos según sea necesario). Evita la sobrecarga de frameworks pesados.",
+  description: "Inicializa un proyecto de tipo script, tooling o agnóstico de forma idempotente.",
   args: {
     language: tool.schema.enum(["javascript", "python", "bash", "google-apps-script", "plano"]).default("plano").describe("El lenguaje o entorno para inicializar"),
     install: tool.schema.boolean().default(true).describe("Si true, ejecuta npm init -y o uv init de forma básica si aplica.")

package/.opencode/tools/sdd_core.ts

@@ -248,7 +248,7 @@ const getPidFilePath = (root: string) => {
 
 // Tool: sdd_set_phase (file sdd_core.ts, export set_phase -> sdd_set_phase)
 export const set_phase = tool({
-  description: "Establece la fase activa del ciclo de desarrollo SDD (F0_DETECT, F1_CONTRACT, F2_IMPLEMENTATION, F3_VERIFICATION, F4_DEPLOYMENT). Si phase=F1_CONTRACT y se pasa spec_name, crea la carpeta del spec atómicamente y devuelve la ruta absoluta. Si phase=F3_VERIFICATION, ejecuta auto-lint (no bloqueante, solo informativo) y aborta si hay errores de lint.",
+  description: "Establece la fase activa del ciclo de desarrollo SDD.",
   args: {
     phase: tool.schema.enum(["F0_DETECT", "F1_CONTRACT", "F2_IMPLEMENTATION", "F3_VERIFICATION", "F4_DEPLOYMENT"]).describe("La fase a establecer"),
     activeContract: tool.schema.string().optional().describe("La ruta o nombre del archivo de contrato JSON activo (.openspec/specs/XXXX_TIMESTAMP_NAME/contract.json)"),
@@ -431,7 +431,7 @@ export const set_phase = tool({
 
 // Tool: sdd_get_state (file sdd_core.ts, export get_state -> sdd_get_state)
 export const get_state = tool({
-  description: "Obtiene el estado de desarrollo actual (fase activa, contrato seleccionado, stack validado)",
+  description: "Obtiene el estado de desarrollo actual.",
   args: {},
   async execute(args, context) {
     const filePath = getStateFilePath(context)
@@ -442,7 +442,7 @@ export const get_state = tool({
 
 // Tool: sdd_get_initial_session_data
 export const get_initial_session_data = tool({
-  description: "Obtiene atómicamente todos los datos de inicio de sesión: el estado actual del arnés, las memorias históricas clave del Brain ('learnings', 'design', 'routing'), y la lista curada de recomendaciones de diseño de Oh My Design. Reemplaza las llamadas secuenciales a sdd_get_state, brain_read_memory y sdd_list_design_recommendations.",
+  description: "Obtiene de forma atómica el estado actual, memorias del Brain y recomendaciones Oh My Design.",
   args: {},
   async execute(args, context) {
     const root = getRoot(context)
@@ -498,7 +498,7 @@ export const get_initial_session_data = tool({
 
 // Tool: sdd_save_active_brief
 export const save_active_brief = tool({
-  description: "Guarda un resumen breve y estructurado del spec o contrato activo en .openspec/active-brief.md para que sirva de anclaje de contexto de sistema (System State Anchoring) para el subagente sdd-coder o sdd-tester.",
+  description: "Guarda un resumen del spec activo en .openspec/active-brief.md como anclaje de contexto.",
   args: {
     brief: tool.schema.string().describe("Contenido en formato Markdown con el resumen del spec activo, componentes, diseño y dependencias.")
   },
@@ -558,7 +558,7 @@ export const save_active_brief = tool({
 
 // Tool: sdd_create_spec_folder (file sdd_core.ts, export create_spec_folder -> sdd_create_spec_folder)
 export const create_spec_folder = tool({
-  description: "Crea una nueva carpeta ordenada para la especificación del cambio (formato: yyyy-mm-dd__hh-mm-ss_nombre)",
+  description: "Crea una nueva carpeta ordenada para la especificación del cambio.",
   args: {
     name: tool.schema.string().describe("Nombre del cambio en minúsculas y separado por guiones (ej. sumar-endpoint)")
   },
@@ -593,7 +593,7 @@ export const create_spec_folder = tool({
 
 // Tool: sdd_validate_contract
 export const validate_contract = tool({
-  description: "Valida de forma estricta el archivo contract.json contra el contract-schema.json oficial para detectar errores de tipos, alucinaciones o campos faltantes antes de avanzar.",
+  description: "Valida contract.json contra el contract-schema.json oficial.",
   args: {
     contractPath: tool.schema.string().describe("Ruta relativa al contract.json (ej. '.openspec/specs/XXXX/contract.json')")
   },

package/.opencode/tools/sdd_design.ts

@@ -41,7 +41,7 @@ export const RECOMMENDED_BRANDS: Record<string, { id: string; name: string; cate
 
 // Tool: sdd_select_design
 export const select_design = tool({
-  description: "Copia fielmente el archivo DESIGN.md y sus ejemplos y recursos interactivos asociados desde el catálogo original de oh-my-design a la carpeta .openspec/ del proyecto.",
+  description: "Copia fielmente el archivo DESIGN.md y ejemplos de la marca a .openspec/",
   args: {
     brandId: tool.schema.string().describe("ID exacto del diseño en oh-my-design (ej: 'linear.app', 'vercel', 'stripe')")
   },
@@ -128,7 +128,7 @@ async function selectDesignHelper(brandId: string, context: any) {
 
 // Tool: sdd_list_design_recommendations
 export const list_design_recommendations = tool({
-  description: "Devuelve una lista curada y corta de marcas de diseño recomendadas (con assets HTML+CSS interactivos), filtrada por categoría de uso. Reemplaza 3-4 llamadas a oh-my-design_list_references en F0.",
+  description: "Devuelve una lista curada de marcas de diseño recomendadas.",
   args: {
     use_case: tool.schema.enum(["saas", "fintech", "ecommerce", "consumer", "all"]).default("all").describe("Categoría del proyecto para filtrar marcas relevantes"),
     max_per_category: tool.schema.number().default(3).describe("Máximo de marcas a devolver por categoría"),
@@ -162,7 +162,7 @@ export const list_design_recommendations = tool({
 
 // Tool: sdd_apply_brand_tokens
 export const apply_brand_tokens = tool({
-  description: "Inyecta tokens de diseño de marca (colores, tipografía, radius) en src/app/globals.css preservando las variables shadcn (--color-border, --color-background, etc.). Usar en F2 cuando se necesite aplicar el tema de marca.",
+  description: "Inyecta tokens de diseño de marca en src/app/globals.css.",
   args: {
     tokens: tool.schema.string().describe("JSON stringificado con {colors: {...}, typography: {...}, radius: {...}} extraído de contract.json design.tokens"),
   },
@@ -232,7 +232,7 @@ ${brandVarLines.join("\n")}
 
 // Tool: sdd_validate_lucide_icons_batch
 export const validate_lucide_icons_batch = tool({
-  description: "Valida un lote de nombres de iconos de Lucide React de forma rápida e idempotente. Si node_modules/lucide-react existe, verifica contra los exports reales; de lo contrario, valida contra un listado estático de los iconos más comunes.",
+  description: "Valida un lote de nombres de iconos de Lucide React de forma rápida.",
   args: {
     icons: tool.schema.array(tool.schema.string()).describe("Lista de nombres de iconos a validar (ej: ['Sun', 'Moon', 'Plus'])"),
   },

package/.opencode/tools/sdd_docker.ts

@@ -34,7 +34,7 @@ const getTargetDir = (root: string): string => {
 
 // Tool: sdd_clean_docker_environment
 export const clean_docker_environment = tool({
-  description: "Asegura que Docker esté abierto y realiza una limpieza total y agresiva: detiene y elimina TODOS los contenedores (activos o inactivos), remueve TODAS las imágenes, volúmenes y redes para garantizar un lienzo en blanco absoluto antes de desplegar.",
+  description: "Asegura que Docker esté abierto y realiza una limpieza total y agresiva.",
   args: {},
   async execute(args, context) {
     const results: Record<string, string> = {}
@@ -114,7 +114,7 @@ export const clean_docker_environment = tool({
 
 // Tool: sdd_generate_dockerfile
 export const generate_dockerfile = tool({
-  description: "Genera Dockerfile multi-stage, .dockerignore y docker-compose.yml optimizados a partir del stack del proyecto (nextjs|fastapi|agnostic). Detecta package manager desde package.json.",
+  description: "Genera Dockerfile, .dockerignore y docker-compose.yml optimizados para el stack.",
   args: {
     stack: tool.schema.enum(["nextjs", "fastapi", "agnostic"]).describe("Stack del proyecto"),
     port: tool.schema.number().default(3000).describe("Puerto de la aplicación"),

package/.opencode/tools/sdd_network.ts

@@ -39,7 +39,7 @@ const getPidFilePath = (root: string) => {
 
 // Tool: sdd_free_port
 export const free_port = tool({
-  description: "Busca y termina de manera forzada cualquier proceso que esté escuchando en un puerto específico",
+  description: "Libera un puerto específico de forma forzada.",
   args: {
     port: tool.schema.number().describe("El puerto a liberar (ej. 3000 o 8000)")
   },
@@ -69,7 +69,7 @@ export const free_port = tool({
 
 // Tool: sdd_start_server
 export const start_server = tool({
-  description: "Inicia un servidor de desarrollo o producción en segundo plano y registra su PID para limpieza posterior",
+  description: "Inicia un servidor en segundo plano y registra su PID.",
   args: {
     command: tool.schema.string().describe("Comando para iniciar el servidor (ej. 'yarn dev' o 'npm run dev')"),
     port: tool.schema.number().optional().default(3000).describe("Puerto esperado del servidor (default: 3000)"),
@@ -132,7 +132,7 @@ export const start_server = tool({
 
 // Tool: sdd_stop_server
 export const stop_server = tool({
-  description: "Detiene el servidor en segundo plano usando el PID registrado",
+  description: "Detiene el servidor en segundo plano registrado.",
   args: {},
   async execute(args, context) {
     const root = getRoot(context)

package/.opencode/tools/sdd_status.ts

@@ -10,7 +10,7 @@ const getRoot = (context: any) => {
 };
 
 export default tool({
-  description: "Obtiene de forma nativa y unificada el estado del ciclo SDD (.openspec/sdd_state.json) junto con un resumen de las categorías de memoria del cerebro (Brain). Evita llamadas lentas de consola y es multiplataforma.",
+  description: "Obtiene el estado unificado del ciclo SDD y un resumen de las categorías del Brain.",
   args: {},
   async execute(args, context) {
     const root = getRoot(context)

package/.opencode/tools/sdd_testing.ts

@@ -71,7 +71,7 @@ const parseSemanticErrors = (rawOutput: string, type: "eslint" | "tsc"): any[] =
 
 // Tool: sdd_quick_lint
 export const quick_lint = tool({
-  description: "Ejecuta el linter del proyecto (eslint) restringido a src/. Devuelve exit code y warnings. Usado como gate automático antes de transicionar a F3.",
+  description: "Ejecuta el linter del proyecto (eslint) restringido a src/.",
   args: {},
   async execute(args, context) {
     const root = getRoot(context)
@@ -140,7 +140,7 @@ export const quick_lint = tool({
 
 // Tool: sdd_shift_left_verify
 export const shift_left_verify = tool({
-  description: "Ejecuta validaciones estáticas Shift-Left completas en el proyecto: ejecuta el compilador de TypeScript (tsc) y el linter (eslint) de manera combinada. Limpia y parsea semánticamente los stack traces y logs de error crudos, devolviendo un JSON limpio y estructurado de errores que el LLM puede digerir y solucionar de inmediato sin perder atención.",
+  description: "Ejecuta validaciones estáticas Shift-Left completas (tsc + eslint) combinadas.",
   args: {},
   async execute(args, context) {
     const root = getRoot(context)
@@ -323,7 +323,7 @@ export const shift_left_verify = tool({
 
 // Tool: sdd_generate_tests
 export const generate_tests = tool({
-  description: "Autogenera plantillas de pruebas unitarias/integración en el directorio corporativo de pruebas a partir de los escenarios de prueba descritos en el contrato activo de sdd_state.json. No pisa archivos de pruebas existentes.",
+  description: "Autogenera plantillas de pruebas a partir de los escenarios del contrato activo.",
   args: {},
   async execute(args, context) {
     const root = getRoot(context)
@@ -442,7 +442,7 @@ export const generate_tests = tool({
 
 // Tool: sdd_save_playwright_artifacts
 export const save_playwright_artifacts = tool({
-  description: "Promueve y archiva los artefactos de captura visual/videos (.openspec/.playwright/) generados por Playwright a la carpeta del spec/contrato activo de forma ordenada, evitando ensuciar la raíz.",
+  description: "Promueve y archiva los artefactos de Playwright a la carpeta del contrato activo.",
   args: {
     callId: tool.schema.string().optional().describe("ID de llamada de Playwright MCP específica. Si no se pasa, toma la última ejecución de forma automática."),
     move: tool.schema.boolean().default(false).describe("Si true, mueve los archivos en lugar de copiarlos.")

package/.utils/export_opencode_session.py

@@ -9,7 +9,7 @@ DB_PATH = "/Users/wavesbyte/.local/share/opencode/opencode.db"
 
 # Escribe aquí el ID de la sesión que deseas exportar (ejemplo: "ses_1234...")
 # Si se deja vacío, el script requerirá el ID como argumento al ejecutarlo
-TARGET_SESSION_ID = "ses_11d2"
+TARGET_SESSION_ID = "ses_11a7"
 
 
 def format_timestamp(ts):

package/opencode.json

@@ -43,7 +43,7 @@
         "./.opencode/oh-my-design/packages/mcp/dist/index.mjs"
       ],
       "enabled": true,
-      "purpose": "MCP oficial de Oh My Design para buscar, consultar y aplicar temas de diseño (Toss, Stripe, Supabase, etc.)."
+      "purpose": "Busca, consulta y aplica temas de diseño (Toss, Stripe, Supabase, etc.)."
     },
     "shadcn": {
       "type": "local",
@@ -54,7 +54,7 @@
         "mcp"
       ],
       "enabled": true,
-      "purpose": "Librería UI objetivo. Usar para browse/search/install de componentes y blocks (dashboards, landings, auth, forms)."
+      "purpose": "Usa para browse/search/install de componentes y blocks oficiales de Shadcn UI."
     },
     "context7": {
       "type": "local",
@@ -76,7 +76,7 @@
         "--isolated"
       ],
       "enabled": true,
-      "purpose": "Playwright MCP. Artefactos (screenshots, traces, videos, downloads) van a .openspec/.playwright/<call-id>/. Para evidencia por sesión SDD, promueve los artefactos relevantes a .openspec/specs/<activeContract>/playwright/ con .opencode/tools/save-playwright-artifacts.sh. --isolated evita ensuciar el perfil del browser en disco."
+      "purpose": "Ejecuta pruebas de regresión visual y capturas de pantalla de Playwright."
     },
     "next-devtools": {
       "type": "local",
@@ -89,7 +89,7 @@
       "environment": {
         "NEXT_TELEMETRY_DISABLED": "1"
       },
-      "purpose": "Toolchain oficial Vercel para Next.js 16. Provee init, nextjs_docs, nextjs_index/nextjs_call (errores, logs, rutas, Server Actions en runtime), browser_eval, upgrade_nextjs_16 y enable_cache_components. Complementa context7 (docs genérico) con docs y runtime específicos de Next 16 (dev server expone /_next/mcp). Telemetría desactivada explícitamente. **DESHABILITADO por defecto** — solo activar on-demand cuando un subagente reporte un error específico de Next 16 que requiera docs oficiales. La razón: el tool `init` inyecta 1000+ palabras de 'FORGET ALL PRIOR KNOWLEDGE' en el contexto del coder (~8K tokens de reasoning desperdiciado en sesiones normales)."
+      "purpose": "Toolchain oficial para depurar Next.js 16 (deshabilitado por defecto)."
     },
     "lucide-icons": {
       "type": "local",
@@ -100,7 +100,7 @@
         "--stdio"
       ],
       "enabled": true,
-      "purpose": "Permite buscar, filtrar y obtener ejemplos de uso JSX de más de 1,500 iconos de Lucide React de forma exacta mediante herramientas del MCP."
+      "purpose": "Busca y obtiene ejemplos de uso de iconos de Lucide React."
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zugzbot",
-  "version": "1.0.38",
+  "version": "1.0.40",
   "description": "Fácil instalador del arnés SDD de Zugzbot para proyectos OpenCode",
   "type": "module",
   "bin": {