zugzbot 1.0.36 → 1.0.38

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

@@ -11,7 +11,7 @@ tools:
   write: true
   edit: true
   bash: true
-  todowrite: true
+  todowrite: false
 permission:
   "*": "allow"
   bash:
@@ -49,6 +49,8 @@ Eres el Programador de Código (sdd-coder) del arnés SDD. Tu trabajo es codific
 - **Memoria del Proyecto**: Tienes PROHIBIDO llamar a `brain_read_memory`. Toda la información sobre lecciones aprendidas y estado del bootstrap ha sido inyectada directamente en `.opencode/active-brief.md`. Consúltala allí. Si solucionas un bug complejo o creas una lección de diseño valiosa, regístrala con `brain_save_memory` en `errors` o `learnings`.
 - **Evitar Obsesión Visual en Consola (Pixel-Peeping)**: Al implementar salidas por CLI, logs o tablas ASCII en consola, tienes STRICTAMENTE PROHIBIDO gastar múltiples iteraciones, turnos de LLM o miles de tokens en tu proceso de razonamiento intentando calcular de forma matemática e hiper-detallada el espaciado, dashes, bordes o celdas. Usa funciones estándares de formateo del lenguaje (`ljust`, `rjust`, `center`, etc.) para lograr una presentación razonable de forma inmediata y avanza directamente a codificar para cumplir con la iteración.
 - **Restricción de Archivos**: Tienes estrictamente prohibido modificar `contract.json`. Solo puedes modificar/escribir código en la fase 'F2_IMPLEMENTATION'.
+- **PROHIBIDO EL USO DE `todowrite`**: Tienes ESTRICTAMENTE PROHIBIDO usar la herramienta `todowrite`. El seguimiento de progreso está centralizado en el Orquestador. Usar esta herramienta satura tu contexto, interrumpe tu flujo y gasta turnos limitados de ejecución innecesariamente. No la invoques.
+- **Batcheo Extremo de ESCRITURA/EDICIÓN (CRÍTICO)**: NO modifiques ni crees archivos uno a uno para luego correr herramientas que comprueben cada archivo individualmente en un bucle `read -> write -> read`. Debes hacer **BATCH EXTREMO**. Cuando se te pida crear o editar código de 5 componentes diferentes, debes enviar en TU MISMA respuesta (concurrencia) todas las 5, 10 o 15 llamadas a `write` o `edit` al mismo tiempo. Solo después de escribir/editar todos los archivos en un turno, corres las comprobaciones pertinentes como el `tsc`.
 </constraints>
 
 <f2_implementation>
@@ -59,12 +61,12 @@ Eres el Programador de Código (sdd-coder) del arnés SDD. Tu trabajo es codific
     3. **Ejecuta Bootstrap**: Llama a la herramienta del stack instalando dependencias (con `install: true` y `force: false`). Para `sdd_bootstrap_agnostic`, indica el `language` adecuado (ej: `google-apps-script`, `python`, `javascript`, `bash` o `plano`).
     4. **Codifica Características de Forma Directa (CONCURRENCIA RECOMENDADA)**:
        - No busques archivos de forma ciega. Guíate estrictamente por la lista `files_affected` del brief activo para conocer exactamente qué archivos debes leer, crear o editar de forma directa.
-       - Lanza llamadas de escritura/edición en paralelo (ej: edita múltiples archivos de componentes enviando múltiples herramientas `write`/`edit` concurrentes en la misma respuesta) para optimizar turnos de LLM.
+       - Lanza llamadas de escritura/edición en paralelo (ej: edita múltiples archivos de componentes enviando múltiples herramientas `write`/`edit` concurrentes en la misma respuesta) para optimizar turnos de LLM. ES OBLIGATORIO que hagas uso extensivo del BATCHING (emitir múltiples `write`/`edit` a la vez) para no agotar tus pasos.
        - Implementa componentes en `src/components/blocks/` o routers en `src/app/routers/` según corresponda.
   </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@latest 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@2.1.8 add x y --yes`). No los instales uno a uno.
   </consolidar_instalaciones>
 
   <tests_y_contratos>
@@ -83,12 +85,13 @@ 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.
-- **Shadcn imports**: Importa desde `@/components/ui/<component>` (ej: `button`). Shadcn v4 usa `@base-ui/react` que no admite `asChild` en Switch.
+- **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`.
 - **Iconos**: Importa desde `lucide-react`. Usa `data-icon="inline-start"` para espaciados automáticos.
 </coding_cheatsheet>
 
 <design_standards>
-  - **Alineación con DESIGN.md e Instanciación de Bloques**: Lee obligatoriamente `.openspec/design-assets/<brandId>/DESIGN.md` y asimila los layouts para recrear diseños premium con grids, sidebars y headers. Quedan prohibidos los MVPs de página flotante. Es **obligatorio** que si la vista requiere un dashboard, panel lateral, login o registro, instales y utilices los bloques prehechos oficiales de Shadcn (`dashboard-01`, `sidebar-01` al `16`, `login-01` al `05`, `signup-01` al `05`, etc.) usando `npx shadcn@latest add <block-name> --yes` de forma agrupada. Distribuye y compón estos bloques enlazándolos con el backend en lugar de inventar la UI desde cero.
+  - **Alineación con DESIGN.md e Instanciación de Bloques**: Lee obligatoriamente `.openspec/design-assets/<brandId>/DESIGN.md` y asimila los layouts para recrear diseños premium con grids, sidebars y headers. Quedan prohibidos los MVPs de página flotante. Es **obligatorio** que si la vista requiere un dashboard, panel lateral, login o registro, utilices primero las herramientas MCP de Shadcn (`shadcn_search_items_in_registries` filtrando por `types: ["block"]`) para buscar bloques oficiales. Observa los ejemplos con `shadcn_get_item_examples_from_registries` y compón la vista. Distribuye y compón estos bloques prehechos enlazándolos con el backend en lugar de inventar la UI desde cero.
+  - **Uso Obligatorio del MCP de Shadcn (Cero Alucinaciones)**: Tienes PROHIBIDO alucinar o inventar la API, las props o los subcomponentes requeridos de los componentes de Shadcn (especialmente en componentes compuestos como Select, Tooltip, Dialog, DropdownMenu). Antes de escribir el código que use estos componentes, DEBES usar la herramienta `shadcn_get_item_examples_from_registries` para ver la implementación real, los imports exactos y su composición obligatoria.
   - **Self-audit pre-transición (BLOQUEANTE)**: Antes de entregar, ejecuta este bloque en una sola corrida de terminal. Si el linter o el tipado TypeScript fallan, debes corregirlos antes de transicionar (el test suite completo queda delegado al Tester en F3 para ahorrar tus turnos):
     ```bash
     HITS=$(grep -rE '#[0-9a-fA-F]{6}\b' src/ --include='*.tsx' --include='*.ts' 2>/dev/null | grep -v 'globals.css' | grep -v 'tailwind.config' | wc -l | tr -d ' ')

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

@@ -8,6 +8,7 @@ tools:
   write: true
   edit: true
   bash: true
+  todowrite: false
 permission:
   "*": "allow"
 ---

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

@@ -32,7 +32,8 @@ Eres el coordinador principal del arnés de desarrollo SDD (Spec-Driven Developm
 <constraints>
 - **Coordinación Pura**: Tienes STRICTAMENTE PROHIBIDO modificar archivos, escribir código o ejecutar comandos en la terminal. Tus herramientas de escritura, edición y bash están deshabilitadas.
 - **Delegación Exclusiva**: Toda acción de diseño, programación, testing o despliegue debe ser delegada a su subagente experto (`@sdd-spec-writer`, `@sdd-coder`, `@sdd-tester`, `@sdd-deployer`) mediante `task`.
-- **Resiliencia de Delegación**: Si un subagente (ej. `@sdd-coder`) se ve interrumpido o falla porque alcanzó el límite de pasos ("Maximum Steps Reached"), tienes STRICTAMENTE PROHIBIDO asumir su rol para escribir código, crear pruebas o ejecutar comandos de compilación/test de forma manual. En su lugar, debes re-invocar la herramienta `task` enviando el mismo `task_id` original del subagente interrumpido con instrucciones explícitas para que reanude y finalice su trabajo limpiamente.
+- **Resiliencia de Delegación**: Si un subagente (ej. `@sdd-coder`) se ve interrumpido o falla porque alcanzó el límite de pasos ("Maximum Steps Reached"), tienes STRICTAMENTE PROHIBIDO asumir su rol para escribir código, crear pruebas o ejecutar comandos de compilación/test de forma manual. En su lugar, debes re-invocar la herramienta `task` enviando el mismo `task_id` original del subagente interrumpido con instrucciones explícitas Y MUY BREVES para que reanude y finalice su trabajo limpiamente. No repitas el prompt original gigante, ya tiene todo en su contexto.
+- **Estructuración de Delegaciones (Sprints)**: Para evitar el "Maximum Steps Reached" en F2, el `sdd-orchestrator` NO DEBE pedirle al `sdd-coder` que implemente un sistema masivo de golpe (ej. "bootstrap, types, store, 20 componentes y 5 páginas"). Debes dividir F2 en "sprints" lógicos y delegarlos secuencialmente a nuevas instancias del `sdd-coder` (sin reusar `task_id` si es un sprint diferente), o pedirle expresamente al subagente que se limite a la Fase X de la implementación y devuelva el control.
 - **Estructura del Proyecto**: Asegúrate de usar la estructura escalable (código en `src/`, pruebas en `tests/`).
 - **Stack UI Exclusivo**: Toda interfaz de usuario debe usar únicamente **Shadcn UI**.
 - **Límite de `todowrite`**: Llama a `todowrite` MÁXIMO 2 veces por sesión: al inicio para crear la lista de fases y al final para marcar todo completado en bloque. No lo actualices en cada transición.
@@ -63,8 +64,8 @@ Eres el coordinador principal del arnés de desarrollo SDD (Spec-Driven Developm
   </f1_contract>
 
   <f2_implementation>
-    1. **Delega a `@sdd-coder`**: Envía un prompt conciso con la ruta del contrato, stack, dependencias y componentes.
-       - *Instrucción clave:* Si `active-brief.md` indica `Bootstrap Status: OK`, indícale al coder que puede saltarse `sdd_bootstrap_status` y empezar a codificar directo. Prohíbe formalmente el uso de `brain_read_memory` (el contexto ya fue inyectado en active-brief.md).
+    1. **Delega a `@sdd-coder`**: Envía un prompt conciso. NO re-envíes el contrato entero ni el package.json.
+       - *Instrucción clave:* Indica si requiere bootstrap. Prohíbe formalmente el uso de `brain_read_memory`. 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.
     2. **Verificación de Servidor**:
        - **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):**
@@ -77,6 +78,7 @@ Eres el coordinador principal del arnés de desarrollo SDD (Spec-Driven Developm
   <f3_verification>
     1. **Shift-Left**: Llama obligatoriamente a `sdd_shift_left_verify`. Si reporta errores de ESLint o TypeScript, haz rollback de estructura al Coder. No continúes si hay errores de compilación críticos.
     2. Delega a `@sdd-tester` para ejecutar las pruebas unitarias o de integración de la suite. (Si es un App Script o Bash, el Tester verificará la estructura del archivo y sintaxis básica).
+       - *Instrucción clave:* Al igual que en F2, si el subagente se quedó sin pasos y usas su `task_id`, el prompt DEBE SER EXTREMADAMENTE BREVE. NO incluyas las listas de test scenarios.
     3. **Transición**:
        - **Si la categoría es 'script' o 'tooling' (Track Agnóstico):** Omitir la fase F4_DEPLOYMENT por completo (los scripts no requieren Docker en su ciclo estándar). Transiciona directamente a `<completion>`.
        - **De lo contrario (Web):**

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

@@ -8,6 +8,7 @@ tools:
   write: false
   edit: false
   bash: true
+  todowrite: false
 permission:
   "*": "allow"
   write: "deny"

package/.opencode/agents/sdd-spec-writer.md

@@ -9,6 +9,7 @@ tools:
   edit: true
   bash: false
   question: true
+  todowrite: false
 permission:
   "*": "allow"
   bash: "deny"

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

@@ -11,7 +11,7 @@ tools:
   write: true
   edit: true
   bash: true
-  todowrite: true
+  todowrite: false
 permission:
   "*": "allow"
   bash:
@@ -46,6 +46,8 @@ 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.
+- **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>
 
 <pre_deploy>

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

@@ -34,3 +34,23 @@ Si el proyecto o aplicación principal vive en un subdirectorio (ej. `next-app`,
 - **Rutas de Archivos en el Contrato**: El Spec-Writer (F1) **debe** escribir las rutas del campo `files_affected` del contrato con el prefijo del subdirectorio correspondiente (ej. `["next-app/src/app/page.tsx", "next-app/src/components/blocks/Navbar.tsx"]`).
 - **Ejecución de Comandos**: El Coder (F2), Tester (F3) y Deployer (F4) **deben** ejecutar siempre sus comandos de terminal (`npm install`, `npm run lint`, `npx tsc`, `npx vitest`, `docker compose`) utilizando la subcarpeta como directorio de trabajo (`workdir` en las llamadas a herramientas, o moviéndose a ella).
 - **Consistencia de Configuración**: Está estrictamente prohibido esparcir o duplicar archivos de configuración (como `tsconfig.json`, `eslint.config.mjs`, `vitest.config.ts`, `components.json`) en la raíz del espacio de trabajo si hay un subdirectorio activo. Todo debe quedar encapsulado dentro del subdirectorio del proyecto.
+
+## 5. Estándares de Calidad UI/UX Premium, Soporte de Temas y Robustez HTML (OBLIGATORIO)
+Cualquier desarrollo de interfaz de usuario (Dashboards, Landings, Formularios, Componentes) debe cumplir con los siguientes estándares desde su **primera entrega (F2)** sin esperar a iteraciones reactivas:
+- **Soporte Semántico de Temas (Zero Hardcoded Light/Dark colors):**
+  - Está estrictamente PROHIBIDO usar clases de colores absolutos de Tailwind (como `bg-white`, `bg-neutral-50`, `text-neutral-900`, `border-neutral-200`) para componentes estructurales, fondos, textos o bordes.
+  - 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.
+- **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.
+- **Pulido y Acabado UX Premium:**
+  - **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)
+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.

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

@@ -91,11 +91,15 @@ Cada fase tiene un **gate explícito** (HIL del usuario) antes de transicionar a
 **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.
+
 ---
 
 ## 4. Stack cerrado (NO abrir)
 
-- **Frontend**: Next.js 16 + React 19 + TypeScript + Tailwind v4 + Shadcn UI v4.11+ (Base UI) + lucide-react + Vitest. **PROHIBIDO**: HeroUI, Chakra, Material-UI, Radix directo sin shadcn.
+- **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.
 - **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

@@ -159,6 +159,7 @@ Copia y adapta los IDs y descripciones que apliquen. Borra los que no apliquen.
 - **NO dupliques los tokens de `.openspec/design-assets/<brandId>/DESIGN.md` línea por línea.** Usa el tool `oh-my-design_get_design_md` y pega el bloque `tokens` completo UNA vez.
 - **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.
 
 ---
 

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@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.
+> **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.
 
 ## Current Project Context
 
 ```json
-!`npx shadcn@latest info --json`
+!`npx shadcn@2.1.8 info --json`
 ```
 
-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.
+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.
 
 ## Principles
 
-1. **Use existing components first.** Use `npx shadcn@latest search` to check registries before writing custom UI. Check community registries too.
+1. **Use existing components first.** Use `npx shadcn@2.1.8 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@latest 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@2.1.8 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@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.
+- **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.
 
 ## Key Patterns
 
@@ -151,45 +151,44 @@ 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@latest preset resolve --json` when you only need preset information.
+- **`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.
 
 See [cli.md — `info` command](../../docs/shadcn/cli.md) for the full field reference.
 
 ## Component Docs, Examples, and Usage
 
-Run `npx shadcn@latest docs <component>` to get the URLs for a component's documentation, examples, and API reference. Fetch these URLs to get the actual content.
+DO NOT run bash commands to view docs. Instead, explicitly use the built-in MCP Tools provided to you:
+1. Use `shadcn_search_items_in_registries` to find components and blocks.
+2. Use `shadcn_get_item_examples_from_registries` to get the full, actual implementation code, imports, and usage examples of any component or block.
+3. Use `shadcn_view_items_in_registries` to see the internal source code structure of a registry item.
 
-```bash
-npx shadcn@latest docs button dialog select
-```
-
-**When creating, fixing, debugging, or using a component, always run `npx shadcn@latest docs` and fetch the URLs first.** This ensures you're working with the correct API and usage patterns rather than guessing.
+**When creating, fixing, debugging, or using a component, always run `shadcn_get_item_examples_from_registries` first.** This ensures you're working with the correct API, composition (e.g. SelectItem inside SelectContent), and usage patterns rather than guessing.
 
 ## Workflow
 
-1. **Get project context** — already injected above. Run `npx shadcn@latest info` again if you need to refresh.
+1. **Get project context** — already injected above. Run `npx shadcn@2.1.8 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@latest search`.
-4. **Get docs and examples** — run `npx shadcn@latest docs <component>` to get URLs, then fetch them. Use `npx shadcn@latest view` to browse registry items you haven't installed. 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.
+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.
 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@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.
+   - **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.
    - **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@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.
+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.
 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.
@@ -200,55 +199,55 @@ When the user asks to update a component from upstream while keeping their local
 
 ```bash
 # Create a new project.
-npx shadcn@latest init --name my-app --preset base-nova
-npx shadcn@latest init --name my-app --preset a2r6bw --template vite
+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
 
 # Create a monorepo project.
-npx shadcn@latest init --name my-app --preset base-nova --monorepo
-npx shadcn@latest init --name my-app --preset base-nova --template next --monorepo
+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
 
 # Initialize existing project.
-npx shadcn@latest init --preset base-nova
-npx shadcn@latest init --defaults  # shortcut: --template=next --preset=nova (base style implied)
+npx shadcn@2.1.8 init --preset base-nova
+npx shadcn@2.1.8 init --defaults  # shortcut: --template=next --preset=nova (base style implied)
 
 # Apply a preset to an existing project.
-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
+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
 
 # Inspect preset codes and project preset state.
-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
+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
 
 # Add components.
-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
+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
 
 # Preview changes before adding/updating.
-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
+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
 
 # Search registries.
-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
+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
 
 # Get component docs and example URLs.
-npx shadcn@latest docs button dialog select
+# 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@latest view @shadcn/button
-npx shadcn@latest view owner/repo/item
+npx shadcn@2.1.8 view @shadcn/button
+npx shadcn@2.1.8 view owner/repo/item
 ```
 
 **Named presets:** `nova`, `vega`, `maia`, `lyra`, `mira`, `luma`

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

@@ -1,17 +1,15 @@
 {
   "$schema": "https://ui.shadcn.com/schema.json",
-  "style": "base-nova",
+  "style": "new-york",
   "rsc": true,
   "tsx": true,
   "tailwind": {
-    "config": "",
+    "config": "tailwind.config.ts",
     "css": "src/app/globals.css",
-    "baseColor": "neutral",
+    "baseColor": "zinc",
     "cssVariables": true,
     "prefix": ""
   },
-  "iconLibrary": "lucide",
-  "rtl": false,
   "aliases": {
     "components": "@/components",
     "utils": "@/lib/utils",
@@ -19,7 +17,5 @@
     "lib": "@/lib",
     "hooks": "@/hooks"
   },
-  "menuColor": "default",
-  "menuAccent": "subtle",
-  "registries": {}
+  "iconLibrary": "lucide"
 }

package/.opencode/tools/sdd_bootstrap.ts

@@ -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@latest add ${args.components.join(" ")} --yes --overwrite`
+        const cmd = `npx shadcn@2.1.8 add ${args.components.join(" ")} --yes --overwrite`
         execSync(cmd, {
           cwd: targetPath,
           stdio: "ignore",

package/.opencode/tools/sdd_docker.ts

@@ -11,6 +11,27 @@ const getRoot = (context: any) => {
   return process.cwd();
 };
 
+// Helper to read the targetDir from sdd_state.json or .sdd_bootstrap.json
+const getTargetDir = (root: string): string => {
+  try {
+    const bootstrapPath = path.resolve(root, ".openspec/.sdd_bootstrap.json")
+    if (fs.existsSync(bootstrapPath)) {
+      const data = JSON.parse(fs.readFileSync(bootstrapPath, "utf8"))
+      if (data && data.targetDir) return data.targetDir
+    }
+  } catch (e) {}
+  
+  try {
+    const statePath = path.resolve(root, ".openspec/sdd_state.json")
+    if (fs.existsSync(statePath)) {
+      const state = JSON.parse(fs.readFileSync(statePath, "utf8"))
+      if (state && state.targetDir) return state.targetDir
+    }
+  } catch (e) {}
+
+  return "."
+}
+
 // 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.",
@@ -100,6 +121,8 @@ export const generate_dockerfile = tool({
   },
   async execute(args, context) {
     const root = getRoot(context)
+    const targetDir = getTargetDir(root)
+    const targetPath = targetDir === "." ? root : path.resolve(root, targetDir)
 
     if (args.stack === "agnostic") {
       const dockerfileAg = `FROM node:20-alpine
@@ -111,7 +134,7 @@ CMD ["node", "src/index.js"]
       const filesWritten: string[] = []
       let content = dockerfileAg
       let targetName = "src/index.js"
-      if (fs.existsSync(path.resolve(root, "src/main.py"))) {
+      if (fs.existsSync(path.resolve(targetPath, "src/main.py"))) {
         content = `FROM python:3.11-slim
 WORKDIR /app
 COPY . .
@@ -121,9 +144,9 @@ CMD ["python", "src/main.py"]
         targetName = "src/main.py"
       }
       
-      const fullPath = path.resolve(root, "Dockerfile")
+      const fullPath = path.resolve(targetPath, "Dockerfile")
       fs.writeFileSync(fullPath, content, "utf8")
-      filesWritten.push("Dockerfile")
+      filesWritten.push(path.relative(root, fullPath))
       
       return JSON.stringify({
         status: "SUCCESS",
@@ -140,11 +163,11 @@ CMD ["python", "src/main.py"]
       let pm = "npm"
       let installCmd = "npm ci --frozen-lockfile"
       let buildCmd = "npm run build"
-      if (fs.existsSync(path.resolve(root, "pnpm-lock.yaml"))) {
+      if (fs.existsSync(path.resolve(targetPath, "pnpm-lock.yaml"))) {
         pm = "pnpm"
         installCmd = "pnpm install --frozen-lockfile"
         buildCmd = "pnpm build"
-      } else if (fs.existsSync(path.resolve(root, "yarn.lock"))) {
+      } else if (fs.existsSync(path.resolve(targetPath, "yarn.lock"))) {
         pm = "yarn"
         installCmd = "yarn install --frozen-lockfile"
         buildCmd = "yarn build"
@@ -231,7 +254,7 @@ test-results
         [".dockerignore", dockerignore],
         ["docker-compose.yml", compose],
       ] as const) {
-        const fullPath = path.resolve(root, name)
+        const fullPath = path.resolve(targetPath, name)
         fs.writeFileSync(fullPath, content, "utf8")
         filesWritten.push(path.relative(root, fullPath))
       }
@@ -288,7 +311,7 @@ tests/
       [".dockerignore", dockerignorePy],
       ["docker-compose.yml", composePy],
     ] as const) {
-      const fullPath = path.resolve(root, name)
+      const fullPath = path.resolve(targetPath, name)
       fs.writeFileSync(fullPath, content, "utf8")
       filesWritten.push(path.relative(root, fullPath))
     }

package/.opencode/tools/sdd_network.ts

@@ -11,6 +11,27 @@ const getRoot = (context: any) => {
   return process.cwd();
 };
 
+// Helper to read the targetDir from sdd_state.json or .sdd_bootstrap.json
+const getTargetDir = (root: string): string => {
+  try {
+    const bootstrapPath = path.resolve(root, ".openspec/.sdd_bootstrap.json")
+    if (fs.existsSync(bootstrapPath)) {
+      const data = JSON.parse(fs.readFileSync(bootstrapPath, "utf8"))
+      if (data && data.targetDir) return data.targetDir
+    }
+  } catch (e) {}
+  
+  try {
+    const statePath = path.resolve(root, ".openspec/sdd_state.json")
+    if (fs.existsSync(statePath)) {
+      const state = JSON.parse(fs.readFileSync(statePath, "utf8"))
+      if (state && state.targetDir) return state.targetDir
+    }
+  } catch (e) {}
+
+  return "."
+}
+
 // Helper to get PID file path
 const getPidFilePath = (root: string) => {
   return path.resolve(root, ".openspec/dev_server.pid")
@@ -56,7 +77,8 @@ export const start_server = tool({
   },
   async execute(args, context) {
     const root = getRoot(context)
-    const targetCwd = args.cwd ? path.resolve(root, args.cwd) : root
+    const targetDir = getTargetDir(root)
+    const targetCwd = args.cwd ? path.resolve(root, args.cwd) : (targetDir === "." ? root : path.resolve(root, targetDir))
     const pidFile = getPidFilePath(root)
 
     try {

package/.opencode/tools/sdd_testing.ts

@@ -11,6 +11,27 @@ const getRoot = (context: any) => {
   return process.cwd();
 };
 
+// Helper to read the targetDir from sdd_state.json or .sdd_bootstrap.json
+const getTargetDir = (root: string): string => {
+  try {
+    const bootstrapPath = path.resolve(root, ".openspec/.sdd_bootstrap.json")
+    if (fs.existsSync(bootstrapPath)) {
+      const data = JSON.parse(fs.readFileSync(bootstrapPath, "utf8"))
+      if (data && data.targetDir) return data.targetDir
+    }
+  } catch (e) {}
+  
+  try {
+    const statePath = path.resolve(root, ".openspec/sdd_state.json")
+    if (fs.existsSync(statePath)) {
+      const state = JSON.parse(fs.readFileSync(statePath, "utf8"))
+      if (state && state.targetDir) return state.targetDir
+    }
+  } catch (e) {}
+
+  return "."
+}
+
 // Helper to parse semantic errors from compiler and linter outputs (reducing raw trace log bloat for the LLM)
 const parseSemanticErrors = (rawOutput: string, type: "eslint" | "tsc"): any[] => {
   const parsed: any[] = []
@@ -54,8 +75,10 @@ export const quick_lint = tool({
   args: {},
   async execute(args, context) {
     const root = getRoot(context)
+    const targetDir = getTargetDir(root)
+    const targetPath = targetDir === "." ? root : path.resolve(root, targetDir)
 
-    const pkgPath = path.resolve(root, "package.json")
+    const pkgPath = path.resolve(targetPath, "package.json")
     if (!fs.existsSync(pkgPath)) {
       return JSON.stringify({
         status: "ERROR",
@@ -63,6 +86,13 @@ export const quick_lint = tool({
       }, null, 2)
     }
 
+    const getRelPath = (fullRel: string) => {
+      if (targetDir !== "." && fullRel.startsWith(targetDir + "/")) {
+        return fullRel.slice(targetDir.length + 1)
+      }
+      return fullRel
+    }
+
     let eslintFiles = "src/"
     try {
       const stateFile = path.resolve(root, ".openspec/sdd_state.json")
@@ -73,7 +103,9 @@ export const quick_lint = tool({
           if (fs.existsSync(contractPath)) {
             const contract = JSON.parse(fs.readFileSync(contractPath, "utf8"))
             if (contract && Array.isArray(contract.files_affected) && contract.files_affected.length > 0) {
-              const existingFiles = contract.files_affected.filter((f: string) => fs.existsSync(path.resolve(root, f)))
+              const existingFiles = contract.files_affected
+                .filter((f: string) => fs.existsSync(path.resolve(root, f)))
+                .map((f: string) => getRelPath(f))
               if (existingFiles.length > 0) {
                 eslintFiles = existingFiles.join(" ")
               }
@@ -87,7 +119,7 @@ export const quick_lint = tool({
 
     try {
       const out = execSync(`npx eslint ${eslintFiles} --quiet --max-warnings 0 2>&1 || true`, {
-        cwd: root,
+        cwd: targetPath,
         encoding: "utf8",
         timeout: 120_000,
       })
@@ -112,9 +144,11 @@ export const shift_left_verify = tool({
   args: {},
   async execute(args, context) {
     const root = getRoot(context)
+    const targetDir = getTargetDir(root)
+    const targetPath = targetDir === "." ? root : path.resolve(root, targetDir)
 
     // Check if it is a Python project
-    let isPython = fs.existsSync(path.resolve(root, "requirements.txt")) || fs.existsSync(path.resolve(root, "pyproject.toml"));
+    let isPython = fs.existsSync(path.resolve(targetPath, "requirements.txt")) || fs.existsSync(path.resolve(targetPath, "pyproject.toml"));
     try {
       const stateFile = path.resolve(root, ".openspec/sdd_state.json")
       if (fs.existsSync(stateFile)) {
@@ -133,6 +167,13 @@ export const shift_left_verify = tool({
       // ignore
     }
 
+    const getRelPath = (fullRel: string) => {
+      if (targetDir !== "." && fullRel.startsWith(targetDir + "/")) {
+        return fullRel.slice(targetDir.length + 1)
+      }
+      return fullRel
+    }
+
     if (isPython) {
       const resultPython: { ruff: { status: string, errors?: any[] } } = {
         ruff: { status: "SUCCESS" }
@@ -147,7 +188,9 @@ export const shift_left_verify = tool({
             if (fs.existsSync(contractPath)) {
               const contract = JSON.parse(fs.readFileSync(contractPath, "utf8"))
               if (contract && Array.isArray(contract.files_affected) && contract.files_affected.length > 0) {
-                const existingFiles = contract.files_affected.filter((f: string) => fs.existsSync(path.resolve(root, f)) && f.endsWith(".py"))
+                const existingFiles = contract.files_affected
+                  .filter((f: string) => fs.existsSync(path.resolve(root, f)) && f.endsWith(".py"))
+                  .map((f: string) => getRelPath(f))
                 if (existingFiles.length > 0) {
                   pythonFiles = existingFiles.join(" ")
                 }
@@ -157,7 +200,7 @@ export const shift_left_verify = tool({
         }
         
         try {
-          execSync(`ruff check ${pythonFiles} --quiet`, { cwd: root, stdio: "pipe", timeout: 20000 })
+          execSync(`ruff check ${pythonFiles} --quiet`, { cwd: targetPath, stdio: "pipe", timeout: 20000 })
         } catch (ruffErr: any) {
           const output = ruffErr.stdout?.toString() || ruffErr.stderr?.toString() || ""
           if (output.includes("command not found") || ruffErr.message?.includes("ENOENT") || ruffErr.status === 127) {
@@ -212,7 +255,7 @@ export const shift_left_verify = tool({
 
     // 1. Run tsc --noEmit
     try {
-      execSync("npx tsc --noEmit", { cwd: root, stdio: "pipe", timeout: 60000 })
+      execSync("npx tsc --noEmit", { cwd: targetPath, stdio: "pipe", timeout: 60000 })
     } catch (e: any) {
       const rawOutput = e.stdout?.toString() || e.stderr?.toString() || ""
       const errors = parseSemanticErrors(rawOutput, "tsc")
@@ -233,7 +276,9 @@ export const shift_left_verify = tool({
           if (fs.existsSync(contractPath)) {
             const contract = JSON.parse(fs.readFileSync(contractPath, "utf8"))
             if (contract && Array.isArray(contract.files_affected) && contract.files_affected.length > 0) {
-              const existingFiles = contract.files_affected.filter((f: string) => fs.existsSync(path.resolve(root, f)))
+              const existingFiles = contract.files_affected
+                .filter((f: string) => fs.existsSync(path.resolve(root, f)))
+                .map((f: string) => getRelPath(f))
               if (existingFiles.length > 0) {
                 eslintFiles = existingFiles.join(" ")
               }
@@ -247,7 +292,7 @@ export const shift_left_verify = tool({
 
     try {
       const out = execSync(`npx eslint ${eslintFiles} --quiet 2>&1 || true`, {
-        cwd: root,
+        cwd: targetPath,
         encoding: "utf8",
         timeout: 60000,
       })
@@ -278,10 +323,13 @@ export const shift_left_verify = tool({
 
 // Tool: sdd_generate_tests
 export const generate_tests = tool({
-  description: "Autogenera plantillas de pruebas unitarias/integración en tests/unit/ 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 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.",
   args: {},
   async execute(args, context) {
     const root = getRoot(context)
+    const targetDir = getTargetDir(root)
+    const targetPath = targetDir === "." ? root : path.resolve(root, targetDir)
+
     const stateFile = path.resolve(root, ".openspec/sdd_state.json")
     if (!fs.existsSync(stateFile)) {
       return JSON.stringify({ success: false, error: "sdd_state.json no existe. Inicia una sesión SDD primero." }, null, 2)
@@ -311,48 +359,76 @@ export const generate_tests = tool({
     const created: string[] = []
     const skipped: string[] = []
     
+    const isPythonProject = fs.existsSync(path.resolve(targetPath, "requirements.txt")) || fs.existsSync(path.resolve(targetPath, "pyproject.toml"))
+    const test_dir = isPythonProject 
+      ? path.resolve(targetPath, "tests/unit") 
+      : path.resolve(targetPath, "src/__tests__")
+
+    if (!fs.existsSync(test_dir)) {
+      fs.mkdirSync(test_dir, { recursive: true })
+    }
+
     for (const [feature, scenarios] of Object.entries(grouped_tests)) {
       const clean_feature = feature.replace(/([A-Z])/g, "-$1").toLowerCase().replace(/^-/, "")
       const hasReact = scenarios.some(s => s.type === "unit" || s.type === "visual")
       const ext = hasReact ? "tsx" : "ts"
-      const test_dir = path.resolve(root, "tests", "unit")
-      if (!fs.existsSync(test_dir)) {
-        fs.mkdirSync(test_dir, { recursive: true })
-      }
-      const test_file = path.join(test_dir, `${clean_feature}.test.${ext}`)
+      
+      const filename = isPythonProject 
+        ? `test_${clean_feature}.py` 
+        : `${feature}.test.${ext}`
+      const test_file = path.join(test_dir, filename)
+      const relative_test_path = path.relative(root, test_file)
       
       if (fs.existsSync(test_file)) {
-        skipped.push(`tests/unit/${clean_feature}.test.${ext}`)
+        skipped.push(relative_test_path)
         continue
       }
       
       const lines: string[] = []
-      lines.push('import { describe, it, expect } from "vitest";')
-      if (hasReact) {
-        lines.push('import { render, screen } from "@testing-library/react";')
-        lines.push('import userEvent from "@testing-library/user-event";')
-        lines.push(`// import ${feature} from "@/components/blocks/${clean_feature}";`)
-      }
-      lines.push("")
-      lines.push(`describe("${feature} Tests (Contract Scenarios)", () => {`)
-      
-      for (const s of scenarios) {
-        const tid = s.id || "TS-XX"
-        const name = s.name || "Test case"
-        lines.push(`  // ${tid}: ${name}`)
-        lines.push(`  // Given: ${s.given || ""}`)
-        lines.push(`  // When: ${s.when || ""}`)
-        lines.push(`  // Then: ${s.then || ""}`)
-        lines.push(`  it("${tid}: ${name}", async () => {`)
-        lines.push('    // TODO: Implement actual contract assertions')
-        lines.push('    expect(true).toBe(true);')
-        lines.push('  });')
+      if (isPythonProject) {
+        lines.push("import pytest")
+        lines.push(`from src.main import app # o tu router correspondiente`)
         lines.push("")
+        lines.push(`# tests para ${feature}`)
+        for (const s of scenarios) {
+          const tid = s.id || "TS-XX"
+          const name = s.name || "Test case"
+          const test_func_name = `test_${tid.toLowerCase().replace(/-/g, "_")}_${clean_feature.replace(/-/g, "_")}`
+          lines.push(`def ${test_func_name}():`)
+          lines.push(`    # Given: ${s.given || ""}`)
+          lines.push(`    # When: ${s.when || ""}`)
+          lines.push(`    # Then: ${s.then || ""}`)
+          lines.push("    assert True")
+          lines.push("")
+        }
+      } else {
+        lines.push('import { describe, it, expect } from "vitest";')
+        if (hasReact) {
+          lines.push('import { render, screen } from "@testing-library/react";')
+          lines.push('import userEvent from "@testing-library/user-event";')
+          lines.push(`// import { ${feature} } from "@/components/blocks/${feature}";`)
+        }
+        lines.push("")
+        lines.push(`describe("${feature} Tests (Contract Scenarios)", () => {`)
+        
+        for (const s of scenarios) {
+          const tid = s.id || "TS-XX"
+          const name = s.name || "Test case"
+          lines.push(`  // ${tid}: ${name}`)
+          lines.push(`  // Given: ${s.given || ""}`)
+          lines.push(`  // When: ${s.when || ""}`)
+          lines.push(`  // Then: ${s.then || ""}`)
+          lines.push(`  it("${tid}: ${name}", async () => {`)
+          lines.push('    // TODO: Implement actual contract assertions')
+          lines.push('    expect(true).toBe(true);')
+          lines.push('  });')
+          lines.push("")
+        }
+        lines.push("});")
       }
-      lines.push("});")
       
       fs.writeFileSync(test_file, lines.join("\n").trim() + "\n", "utf8")
-      created.push(`tests/unit/${clean_feature}.test.${ext}`)
+      created.push(relative_test_path)
     }
     
     return JSON.stringify({

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_11e1"
+TARGET_SESSION_ID = "ses_11d2"
 
 
 def format_timestamp(ts):

package/package.json

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