zugzbot 1.4.0 → 1.6.0

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

@@ -50,12 +50,13 @@ Eres el coordinador principal del arnés de desarrollo SDD (Spec-Driven Developm
     1. **Inicialización Atómica**: Llama obligatoriamente a `sdd_get_initial_session_data` para obtener estado, memorias e Oh-My-Design en un solo turno.
     2. **Brain Pre-carga (OBLIGATORIO)**: Inmediatamente después, invoca `brain_read_memory({ category: "learnings" })` y `brain_read_memory({ category: "errors" })` para extraer errores y lecciones históricas que prevengan repetir problemas conocidos. Guarda el resultado en una variable interna para inyectarlo en cada brief de subagente.
     2.5 **Detección de intención de catálogo externo (CRÍTICO — bugfix sesión 1176)**: Analiza la petición. Si contiene ALGUNA keyword de marketing/landing/auth/composite, animaciones/shaders/WebGL, AI components, o un nombre propio de cualquier catálogo:
-       - Keywords marketing/landing (shadcn): `hero`, `landing`, `pricing`, `features`, `faq`, `testimonials`, `footer`, `cta`, `navbar`, `stats`, `logo cloud`, `login page`, `signup page`, `forgot password`, `chart`, `sidebar`, `dashboard section`, `comparison`, `use cases`, `how it works`, `changelog`, `cookie banner`, `newsletter`, `bento`, `marquee`, `gallery`, `integration`
+       - Keywords marketing/landing (shadcn): `hero`, `landing`, `pricing`, `features`, `faq`, `testimonials`, `footer`, `cta`, `navbar`, `logo cloud`, `comparison`, `use cases`, `how it works`, `changelog`, `cookie banner`, `newsletter`, `bento`, `marquee`, `gallery`, `integration`
+       - Keywords forms/stats/tables (blocks-so): `form`, `formulario`, `stats`, `métricas`, `KPIs`, `tabla`, `data table`, `data grid`, `file upload`, `subir archivo`, `drag and drop`, `dialog`, `modal`, `command menu`, `command palette`, `onboarding`, `ai component`, `ai chat`, `grid list`, `login page`, `signup page`, `forgot password`
        - Keywords animaciones (reactbits): `shader`, `webgl`, `gsap`, `framer-motion`, `three.js`, `drei`, `animated background`, `animated text`, `gradient mesh`, `magnet`, `floating dock`, `cursor`, `particles`, `noise`, `orbit`, `aurora`, `dither`, `iridescence`, `blob`, `glare`, `staggered`, `magic bento`, `electric border`, `metallic paint`
-       - Nombres propios: `akash`, `akash3444`, `shadcnui-blocks`, `shadcn-ui-blocks`, `basecn`, `shadcn blocks`, `reactbits`, `react-bits`, `david haz`
-       - **Acción obligatoria**: cargar la skill `shadcn-templates` (que ahora referencia las tools MCP `sdd_catalog_list_blocks`, `sdd_catalog_get_block` y `sdd_catalog_warm_index` — NUNCA uses `webfetch` directo a GitHub/reactbits.dev; esta cacheado).
-       - En modo HIL: llama `sdd_catalog_list_blocks({category, limit: 5, registry: 'all'})` y presenta las 2-3 mejores opciones con `preview_url` para que el usuario elija. **Incluir siempre `preview_url` en la respuesta** — para reactbits el demo es animado y el usuario puede ver cómo se ve antes de instalar.
-       - En modo autopiloto (`/loop`): llama `sdd_catalog_get_block({name})` sobre 2-3 candidatos (uno de cada registry) y elige el que mejor encaje.
+       - Nombres propios: `akash`, `akash3444`, `shadcnui-blocks`, `shadcn-ui-blocks`, `basecn`, `shadcn blocks`, `reactbits`, `react-bits`, `david haz`, `ephraim`, `ephraimduncan`, `blocks.so`, `blocks-so`, `blocks so`
+       - **Acción obligatoria**: cargar la skill `shadcn-templates` (que ahora referencia las tools MCP `sdd_catalog_list_blocks`, `sdd_catalog_get_block` y `sdd_catalog_warm_index` — NUNCA uses `webfetch` directo a GitHub/reactbits.dev/blocks.so; esta cacheado).
+       - En modo HIL: llama `sdd_catalog_list_blocks({category, limit: 5, registry: 'all'})` y presenta las 2-3 mejores opciones con `preview_url` para que el usuario elija. **Incluir siempre `preview_url` en la respuesta** — para reactbits el demo es animado, para blocks.so es live en `https://blocks.so/<category>/<name>`, y el usuario puede ver cómo se ve antes de instalar.
+       - En modo autopiloto (`/loop`): llama `sdd_catalog_get_block({name})` sobre 2-3 candidatos (uno de cada registry) y elige el que mejor encaje. Prioriza `blocks-so` si la keyword cae en sus 11 categorías (stats, login, form-layout, file-upload, tables, dialogs, sidebar, command-menu, ai, onboarding, grid-list).
        - Esto evita el ciclo "ping-pong" de 3+ turnos que vimos en sesión 1176 donde el usuario tuvo que guiar al orquestador hacia el catálogo correcto.
     3. **Detección Fast-Track Dashboard (CRÍTICO — bugfix sesión 1186 y 1180)**: Analiza la petición del usuario. Si contiene ALGUNA de estas keywords: `dashboard`, `admin panel`, `panel de control`, `panel admin`, `crm`, `erp`, `panel`:
        - **NO preguntes NADA**. Asume todos los defaults: Stack = Next.js 16 + Shadcn UI + Tailwind v4, Persistencia = localStorage/mock, Diseño = `default` (zinc nativo de Shadcn, NO inyectar marcas de Oh-My-Design), Verificación = `console`.
@@ -142,7 +143,7 @@ Eres el coordinador principal del arnés de desarrollo SDD (Spec-Driven Developm
          - Anúnciala en 1 línea y delega la siguiente iteración completa a un NUEVO hilo `sdd-orchestrator` con contexto de 0 tokens.
        - Si `loopCurrentIteration >= loopTargetIterations` o modo normal: Concluye con `sdd_set_phase({ phase: "F0_DETECT", loopMode: false })`.
     2. **Brain save OBLIGATORIO**: Sintetiza 1-3 lecciones y regístralas con `brain_save_memory` (categoría: `learnings`, `errors`, `design` o `routing`). BLOQUEANTE — no omitir.
-    2.5 **Memory Post-Sesión para Catálogos (CRÍTICO — bugfix sesión 1176)**: Si la sesión tocó cualquier catálogo externo de UI (Akash shadcn-ui-blocks, basecn, reactbits.dev), registra OBLIGATORIAMENTE en `brain.routing`:
+    2.5 **Memory Post-Sesión para Catálogos (CRÍTICO — bugfix sesión 1176)**: Si la sesión tocó cualquier catálogo externo de UI (Akash shadcn-ui-blocks, basecn, reactbits.dev, blocks.so), registra OBLIGATORIAMENTE en `brain.routing`:
        - URL canónica del catálogo
        - Comando `npx shadcn@latest add <URL>` listo para usar
        - Nombre del autor/repo (para evitar redescubrimiento en próximas sesiones)
@@ -164,7 +165,7 @@ Eres el coordinador principal del arnés de desarrollo SDD (Spec-Driven Developm
 <mcp_guidelines>
 - **MCPs**: `shadcn` (UI), `context7` (APIs Next.js/FastAPI), `playwright` (Visual tests), `lucide-icons` (Iconos).
 - `next-devtools` deshabilitado por defecto. MCPs invocados exclusivamente por subagentes.
-- **Catálogos externos (Tools internas)**: `sdd_catalog_list_blocks`, `sdd_catalog_get_block`, `sdd_catalog_warm_index` — cachean el catálogo unificado (Akash shadcn-ui-blocks + basecn + reactbits.dev) en `.openspec/cache/` con TTL 7d (Akash/Basecn) y 1d (reactbits). NUNCA uses `webfetch` directo a GitHub o reactbits.dev para descubrir bloques; usa siempre estas tools. Solo se soportan registries con catálogo JSON oficialmente discoverable.
+- **Catálogos externos (Tools internas)**: `sdd_catalog_list_blocks`, `sdd_catalog_get_block`, `sdd_catalog_warm_index` — cachean el catálogo unificado (Akash shadcn-ui-blocks + basecn + reactbits.dev + blocks.so) en `.openspec/cache/` con TTL 7d (Akash/Basecn/blocks-so) y 1d (reactbits). NUNCA uses `webfetch` directo a GitHub o reactbits.dev para descubrir bloques; usa siempre estas tools. Solo se soportan registries con catálogo JSON oficialmente discoverable.
 </mcp_guidelines>
 
 <communication_rules>

package/.opencode/commands/cost.md

@@ -0,0 +1,93 @@
+---
+description: Muestra el desglose de costos, tokens y archivos cambiados de la sesion actual y los ultimos comandos
+---
+
+# /cost — Desglose de consumo y productividad
+
+Has sido invocado con el comando `/cost`. Muestra al usuario de forma directa y visual:
+
+## 1. Sesion actual (live)
+
+```json
+!`node -e "
+const fs = require('fs');
+const path = require('path');
+const metricsPath = path.resolve('.openspec/.sdd_session_metrics.json');
+const statePath = path.resolve('.openspec/sdd_state.json');
+if (!fs.existsSync(metricsPath)) { console.log(JSON.stringify({status: 'NO_SESSION', message: 'No hay sesion activa o no se ha registrado consumo.'})); process.exit(0); }
+const m = JSON.parse(fs.readFileSync(metricsPath, 'utf8'));
+const s = fs.existsSync(statePath) ? JSON.parse(fs.readFileSync(statePath, 'utf8')) : {};
+const startedAt = m.startedAt || '';
+const lastUpdated = m.lastUpdatedAt || '';
+const durationMs = startedAt && lastUpdated ? Math.max(0, Date.parse(lastUpdated) - Date.parse(startedAt)) : 0;
+const fmtDur = (ms) => { const s = Math.floor(ms/1000); const m = Math.floor(s/60); return m + 'm ' + (s%60) + 's'; };
+const fmtCost = (n) => n < 0.001 ? '$' + n.toFixed(5) : n < 1 ? '$' + n.toFixed(4) : '$' + n.toFixed(3);
+const fmtInt = (n) => Math.round(n).toLocaleString('en-US');
+const out = {
+  status: 'ACTIVE',
+  contract: m.contractName || 'fast-track',
+  sessionId: m.sessionId || 'n/a',
+  phase: s.phase || 'unknown',
+  startedAt,
+  lastUpdated,
+  duration: fmtDur(durationMs),
+  totals: {
+    cost: fmtCost(m.totals.cost || 0),
+    tokensIn: fmtInt(m.totals.tokensIn || 0),
+    tokensOut: fmtInt(m.totals.tokensOutput || 0),
+    messages: fmtInt(m.totals.messages || 0)
+  },
+  byAgent: Object.entries(m.byAgent || {}).sort((a,b) => (b[1].cost||0)-(a[1].cost||0)).map(([k,v]) => ({agent: k, cost: fmtCost(v.cost||0), tokensIn: fmtInt(v.tokensIn||0), tokensOut: fmtInt(v.tokensOut||0), messages: fmtInt(v.messages||0)}))
+};
+console.log(JSON.stringify(out, null, 2));
+"`
+```
+
+## 2. Ultimos 10 changelogs (historial de comandos)
+
+```json
+!`node -e "
+const fs = require('fs');
+const path = require('path');
+const idxPath = path.resolve('.openspec/changelog/INDEX.md');
+if (!fs.existsSync(idxPath)) { console.log(JSON.stringify({status: 'NO_CHANGELOGS', message: 'Aun no hay changelogs registrados. Corre un /fast o cierra un ciclo SDD.'})); process.exit(0); }
+const content = fs.readFileSync(idxPath, 'utf8');
+const lines = content.split('\n').filter(l => l.trim().startsWith('|') && !l.startsWith('|---') && !l.startsWith('| Timestamp'));
+const entries = lines.slice(0, 10).map(l => {
+  const cells = l.split('|').map(c => c.trim()).filter(Boolean);
+  return { timestamp: cells[0], command: cells[1], cost: cells[2], files: cells[3], diff: cells[4] };
+});
+console.log(JSON.stringify({status: 'OK', count: entries.length, entries}, null, 2));
+"`
+```
+
+## 3. Historial agregado (todas las sesiones cerradas)
+
+```json
+!`node -e "
+const fs = require('fs');
+const path = require('path');
+const logPath = path.resolve('.openspec/archive/_sessions.jsonl');
+if (!fs.existsSync(logPath)) { console.log(JSON.stringify({status: 'NO_HISTORY', message: 'Aun no hay sesiones cerradas en el archivo de historial.'})); process.exit(0); }
+const lines = fs.readFileSync(logPath, 'utf8').split('\n').filter(l => l.trim());
+const fmtCost = (n) => n < 0.001 ? '$' + n.toFixed(5) : n < 1 ? '$' + n.toFixed(4) : '$' + n.toFixed(3);
+const fmtInt = (n) => Math.round(n).toLocaleString('en-US');
+const sessions = lines.map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+const totals = sessions.reduce((acc, s) => ({
+  cost: acc.cost + (s.cost || 0),
+  tokensIn: acc.tokensIn + (s.tokensIn || 0),
+  tokensOutput: acc.tokensOutput + (s.tokensOutput || 0),
+  messages: acc.messages + (s.messages || 0)
+}), {cost:0, tokensIn:0, tokensOutput:0, messages:0});
+const top5 = sessions.sort((a,b) => (b.cost||0) - (a.cost||0)).slice(0,5).map(s => ({contract: s.contractName, cost: fmtCost(s.cost||0), messages: fmtInt(s.messages||0), startedAt: s.startedAt}));
+console.log(JSON.stringify({status: 'OK', sessionCount: sessions.length, totals: { cost: fmtCost(totals.cost), tokensIn: fmtInt(totals.tokensIn), tokensOutput: fmtInt(totals.tokensOutput), messages: fmtInt(totals.messages) }, top5}, null, 2));
+"`
+```
+
+## Instrucciones de presentacion
+
+1. **Sesion actual**: muestra el JSON en una tabla markdown clara. Incluye duracion, costo, tokens y mensajes.
+2. **Ultimos changelogs**: si hay, muestra una tabla con timestamp, comando, costo, archivos y +/- . Si no hay, indica que aun no hay historial.
+3. **Historial agregado**: muestra el top 5 de specs mas caros y los totales historicos.
+4. **Veredicto**: cierra con una linea resumida como "Llevas $X.XX gastados en Y sesiones. El comando mas caro fue `<nombre>` ($X.XX).".
+5. **Tip pro**: si el usuario lo invoca seguido, sugiere correr `/reset` para limpiar el contexto y empezar fresco sin perder el changelog (que ya esta persistido en `.openspec/changelog/`).

package/.opencode/plugins/sdd-bridge.ts

@@ -1,6 +1,7 @@
 import { type Plugin } from "@opencode-ai/plugin"
 import fs from "fs"
 import path from "path"
+import { write_changelog } from "../tools/sdd_changelog.ts"
 
 type AgentMetrics = {
   cost: number
@@ -373,6 +374,48 @@ export const SddBridgePlugin: Plugin = async ({ project, client, $, directory, w
           if (newState.phase === "F0_DETECT") {
             try {
               const openspecDir = path.resolve(projectRoot, ".openspec")
+
+              // 0. Changelog capture (BEFORE GC clears metrics) - records the cycle
+              try {
+                const lastMetrics = readMetrics()
+                if (lastMetrics && (lastMetrics.totals?.cost > 0 || lastMetrics.totals?.messages > 0)) {
+                  const derivedCommand = lastMetrics.contractName || "sdd-cycle"
+                  await write_changelog
+                    .execute(
+                      {
+                        command: derivedCommand,
+                        prompt:
+                          "(prompt no capturado automaticamente por el bridge - edita el changelog para anadirlo si lo necesitas)",
+                      },
+                      {
+                        sessionID: "",
+                        messageID: "",
+                        agent: "sdd-bridge",
+                        directory: projectRoot,
+                        worktree: projectRoot,
+                        abort: new AbortController().signal,
+                        metadata: () => {},
+                        ask: async () => {},
+                      } as any
+                    )
+                    .catch(() => {})
+
+                  // Notify via toast
+                  if (client?.tui?.showToast) {
+                    await client.tui
+                      .showToast({
+                        body: {
+                          message: `📝 Changelog capturado en .openspec/changelog/ (costo: $${(lastMetrics.totals?.cost || 0).toFixed(4)})`,
+                          variant: "info",
+                        },
+                      })
+                      .catch(() => {})
+                  }
+                }
+              } catch (e) {
+                // best-effort: never let changelog failure block GC
+              }
+
               const cleanScreenshots = (dir: string) => {
                 if (fs.existsSync(dir)) {
                   const files = fs.readdirSync(dir)

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

@@ -33,14 +33,18 @@ Para optimizar el tiempo de desarrollo, garantizar una experiencia visual premiu
   - **Preservación de Datos Dummy**: El archivo de datos del bloque (por ejemplo, `data.json` o constantes locales) debe mantenerse intacto en su ruta inyectada por la CLI en esta Fase A para garantizar que la vista se muestre de inmediato en el navegador exactamente idéntica al demo real.
 - **Sustitución Atómica de Datos en Fase B**: Una vez que el bloque compila e interactúa en el navegador de manera idéntica al demo con los datos de ejemplo, el Coder procederá de forma exclusiva a sustituir los datos mock por lógica y fetchings de datos dinámicos del backend, manteniendo intactos los contenedores estructurales del bloque (grids de diseño, paddings y contenedores flex) sin alteración alguna para evitar aberraciones visuales.
 - **Resolución Activa de Conflictos de Ruteo por Inyección de Bloques**: Si la CLI de Shadcn inyecta automáticamente una estructura de rutas (ej: `src/app/dashboard/page.tsx`) que compite con las rutas del contrato (como un route group `(dashboard)` o una ruta raíz), el Coder **debe** borrar o refactorizar de inmediato el código inyectado por defecto para evitar bucles de redirección infinitos o colisiones en el router.
-- **Catálogo Unificado `sdd_catalog` (3 registries, todos discoverables)**: Antes de inventar cualquier layout/bloque desde cero, el Spec-Writer (F1) y el Coder (F2) **deben** consultar `sdd_catalog_list_blocks({ registry: "all", category: "<cat>" })`. El catálogo cubre 3 fuentes con catálogo JSON oficial en un solo tool:
-  1. **`shadcn`** (akash3444/shadcn-ui-blocks, GitHub Contents API) — ~540 bloques Radix/Next.js curados. **Default** para marketing, landing, auth, dashboards, footers.
+- **Catálogo Unificado `sdd_catalog` (4 registries, todos discoverables)**: Antes de inventar cualquier layout/bloque desde cero, el Spec-Writer (F1) y el Coder (F2) **deben** consultar `sdd_catalog_list_blocks({ registry: "all", category: "<cat>" })`. El catálogo cubre 4 fuentes con catálogo JSON oficial en un solo tool:
+  1. **`shadcn`** (akash3444/shadcn-ui-blocks, GitHub Contents API) — ~540 bloques Radix/Next.js curados. **Default** para marketing, landing, hero, pricing, features, faq, testimonials, footer, cta, navbar, logo-cloud, bento, marquee, comparison, use-cases, how-it-works, changelog, cookie-banner, newsletter.
   2. **`basecn`** (akash3444/basecn, GitHub Contents API) — ~60 bloques fork Base UI. Usar solo si el proyecto está en Base UI.
   3. **`reactbits`** (reactbits.dev, `/r/registry.json` oficial shadcn-compatible) — 134 primitivas animadas × 4 variantes (JS-CSS/JS-TW/TS-CSS/TS-TW, default `TS-TW`). **Fuente preferente** para backgrounds animados, textos con efecto, cards interactivas, cursors custom, dock flotante. Tratar como third-party trust: revisar siempre el campo `dependencies` (suelen incluir `gsap`, `three`, `@react-three/fiber`, `motion`) y validar compat con el stack target antes de instalar.
+  4. **`blocks-so`** (ephraimduncan/blocks, GitHub Contents API sobre `/content/components/`) — 60+ bloques Radix prod-ready con `categories[]` explícito en cada JSON. **Default** para sus 11 categorías: `stats` (15 vars), `login` (9 vars), `form-layout` (5 vars), `file-upload` (6 vars), `tables` (5 vars), `dialogs` (12 vars), `sidebar` (6 vars), `command-menu` (3 vars), `ai` (5 vars), `onboarding` (7 vars), `grid-list` (3 vars). MIT license, autor Ephraim Duncan (1.7k⭐). Para `sidebar` y `login` hay empates con shadcn — el orquestador prefiere blocks-so y solo consulta shadcn si el usuario lo pide explícito o si la categoría quedó sin resultados.
   - **Criterio de inclusion**: solo se soportan registries con catálogo JSON oficialmente discoverable. 21st.dev fue removido porque su catálogo es JS-rendered y rompe el principio de "siempre saber qué hay disponible antes de elegir".
-  - El comando install siempre viene en el campo `install_command` del resultado de `sdd_catalog_get_block`. **Prohibido** ejecutar `npx shadcn add` con una URL adivinada; usar siempre el `install_command` literal que devuelve la tool.
-  - El catálogo guarda caché local en `.openspec/cache/` con TTL diferenciado (7d shadcn/basecn, 1d reactbits) — **NUNCA** usar `webfetch` directo a GitHub o reactbits.dev, está cacheado.
-  - Todos los items exponen `preview_url`. Para reactbits el demo es animado vivo (`https://reactbits.dev/<BaseName>`) — el orchestrator debe **siempre** presentar el `preview_url` al usuario en modo HIL para que vea cómo se ve antes de elegir.
+  - El comando install siempre viene en el campo `install_command` del resultado de `sdd_catalog_get_block`. **Prohibido** ejecutar `npx shadcn add` con una URL adivinada; usar siempre el `install_command` literal que devuelve la tool. Formatos válidos por registry:
+    - shadcn/basecn: `npx shadcn@latest add https://shadcnui-blocks.com/r/radix/<name>.json --yes` o `https://basecn.dev/r/<name>.json`
+    - reactbits: `npx shadcn@latest add https://reactbits.dev/r/<Name>-TS-TW.json --yes`
+    - blocks-so: `npx shadcn@latest add https://blocks.so/r/<name>.json --yes` (o `@blocks-so/<name>` si `components.json` del proyecto lo tiene declarado).
+  - El catálogo guarda caché local en `.openspec/cache/` con TTL diferenciado (7d shadcn/basecn/blocks-so, 1d reactbits) — **NUNCA** usar `webfetch` directo a GitHub o reactbits.dev, está cacheado.
+  - Todos los items exponen `preview_url`. Para blocks.so el preview es live (`https://blocks.so/<category>/<name>`); para reactbits también (`https://reactbits.dev/<BaseName>`). El orchestrator debe **siempre** presentar el `preview_url` al usuario en modo HIL para que vea cómo se ve antes de elegir.
 
 ## 4. Soporte para Subdirectorios, Monorepos (targetDir) y Estándar Corporativo `src/`
 Si el proyecto o aplicación principal vive en un subdirectorio (ej. `next-app`, `frontend`, `backend`), se deben seguir estas directivas estrictas para mantener la consistencia y el "estándar corporativo con carpeta `src/`":

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

@@ -154,54 +154,58 @@ El `@sdd-coder` utiliza el template base `nextjs-shadcn`. Si el contrato no deta
 
 ## 5. Catálogo Unificado de Bloques Externos (`sdd_catalog`)
 
-Además del catálogo nativo de Shadcn UI, el arnés expone un catálogo unificado de **3 registries** externos (todos con catálogo JSON oficial y discoverable programáticamente). Si el usuario pide cualquier interfaz (hero, footer, dashboard, login, AI chat, animated background, etc.), **TIENES LA OBLIGACIÓN** de explorar este catálogo ANTES de inventar desde cero.
+Además del catálogo nativo de Shadcn UI, el arnés expone un catálogo unificado de **4 registries** externos (todos con catálogo JSON oficial y discoverable programáticamente). Si el usuario pide cualquier interfaz (hero, footer, dashboard, login, AI chat, animated background, stats, form, table, etc.), **TIENES LA OBLIGACIÓN** de explorar este catálogo ANTES de inventar desde cero.
 
 ### 5.0 Registries Soportados (todos discoverables)
 
 | Registry | Fuente de catálogo | Contenido | TTL | Notas |
 |---|---|---|---|---|
-| `shadcn` | akash3444/shadcn-ui-blocks (GitHub Contents API) | ~540 bloques Radix | 7d | **Default** para marketing/landing/auth/dashboards |
+| `shadcn` | akash3444/shadcn-ui-blocks (GitHub Contents API) | ~540 bloques Radix | 7d | **Default** para marketing/landing/hero/pricing/features/faq/testimonials/footer/cta/navbar/logo-cloud/bento/marquee |
 | `basecn` | akash3444/basecn (GitHub Contents API) | ~60 bloques fork Base UI | 7d | Alternativa si el proyecto usa Base UI |
 | `reactbits` | reactbits.dev/r/registry.json (JSON oficial shadcn) | 134 bases × 4 variantes = 536 items | 1d | Primitivas animadas (backgrounds, text, cards, cursors, etc.) |
+| `blocks-so` | ephraimduncan/blocks (GitHub Contents API sobre `/content/components/`) | 60+ bloques Radix con `categories[]` explícito en cada JSON | 7d | **Default** para `stats` (15), `login` (9), `form-layout` (5), `file-upload` (6), `tables` (5), `dialogs` (12), `sidebar` (6), `command-menu` (3), `ai` (5), `onboarding` (7), `grid-list` (3). MIT, Ephraim Duncan. |
 
 > **Criterio de inclusion**: solo se soportan registries con catálogo JSON oficialmente discoverable. 21st.dev fue removido porque su catálogo es JS-rendered y requiere scraping para descubrir items nuevos — eso rompe el principio de "siempre saber qué hay disponible antes de elegir".
 
 ### 5.1 Herramientas MCP Nativas del Arnés (PREFERENTE — `sdd_catalog_*`)
 
-**PROHIBIDO** usar `webfetch` directo a GitHub o reactbits.dev para descubrir bloques. El arnés expone 3 tools MCP dedicadas que cachean en `.openspec/cache/` y evitan redescubrimiento:
+**PROHIBIDO** usar `webfetch` directo a GitHub, reactbits.dev o blocks.so para descubrir bloques. El arnés expone 3 tools MCP dedicadas que cachean en `.openspec/cache/` y evitan redescubrimiento:
 
 - `sdd_catalog_list_blocks({ category?, query?, registry?, limit?, force_refresh? })`
-  - `registry`: `"shadcn"` | `"basecn"` | `"reactbits"` | `"all"` (default).
-  - Filtra por categoria exacta (`hero`, `pricing`, `backgrounds`, `text`, `cards`, `navigation`, ...) o substring libre (sobre `name`, `description`, `tags`).
+  - `registry`: `"shadcn"` | `"basecn"` | `"reactbits"` | `"blocks-so"` | `"all"` (default).
+  - Filtra por categoria exacta (`hero`, `pricing`, `backgrounds`, `text`, `cards`, `navigation`, `stats`, `login`, `form-layout`, ...) o substring libre (sobre `name`, `description`, `tags`).
   - Para `reactbits`: devuelve las **134 bases** (cada una con `variants[]` y `default_variant`), NO las 536 variantes. Esto evita duplicados y permite ver opciones de un vistazo.
+  - Para `blocks-so`: devuelve los **60+ bloques Radix** distribuidos en 11 categorías oficiales. La categoría se infiere del path del directorio GitHub (`content/components/<category>/`), no del nombre del archivo.
 - `sdd_catalog_get_block({ name, registry?, variant?, force_refresh? })`
   - Formatos de `name`:
     - shadcn/basecn: `"hero-06"`, `"sidebar-07"`
+    - blocks-so: `"stats-01"`, `"login-03"`, `"form-layout-02"`, `"ai-01"`, etc.
     - reactbits: `"Dither"` (auto-resuelve a `Dither-TS-TW` por default) **o** `"Dither-JS-CSS"` (variante canónica completa)
-    - URL directa: `"https://reactbits.dev/r/Dither-TS-TW.json"` o `"https://shadcnui-blocks.com/r/radix/hero-06.json"`
-    - Namespace shadcn: `"@acme/button"`
+    - URL directa: `"https://reactbits.dev/r/Dither-TS-TW.json"`, `"https://blocks.so/r/stats-01.json"` o `"https://shadcnui-blocks.com/r/radix/hero-06.json"`
+    - Namespace shadcn: `"@acme/button"` o `"@blocks-so/stats-01"` (auto-routing a blocks-so)
   - Para reactbits, parámetro opcional `variant`: `"JS-CSS" | "JS-TW" | "TS-CSS" | "TS-TW"` (default `"TS-TW"`). Aplicar solo cuando pasas el nombre base sin sufijo de variante.
   - `registry` autodetecta por el formato; pasalo explícito solo si necesitas forzar.
   - Devuelve `source_files[]`, `dependencies[]`, `preview_url`, `install_command` listo y metadatos `base_name` + `variant` (para reactbits).
 - `sdd_catalog_warm_index({ registry? })`
-  - Pre-calienta caches. Llamar al bootstrap (F0) o inicio de F1.
+  - Pre-calienta caches. Llamar al bootstrap (F0) o inicio de F1. Para `blocks-so` consume ~12 GitHub API calls (1 para categorias + 11 para listar archivos) — TTL 7d minimiza esto.
 
 ### 5.2 Flujo de Descubrimiento (Fase F1 - Spec-Writer)
 
 Cuando el usuario pide una UI, sigue este orden de prioridad:
 
-1. **Primero** `sdd_catalog_list_blocks({ registry: "all", category: "<categoria>", limit: 10 })` — devuelve candidatos de los 3 registries simultáneamente.
-2. **Si el usuario pide animaciones/shaders/efectos visuales cinematograficos**, prioriza `registry: "reactbits"` (es donde estan las primitivas animadas reales: `Dither`, `Aurora`, `GlareHover`, `Magnet`, `StaggeredMenu`, `FloatingDock`, etc.).
-3. **Si el usuario pide paginas de marketing completas** (landing, pricing, features), prioriza `registry: "shadcn"` (bloques Radix mas completos con texto, CTAs, imagenes placeholder).
-4. **Si el usuario ya dio una URL** (`https://reactbits.dev/...` o `https://shadcnui-blocks.com/...`), ve directo a `sdd_catalog_get_block` con esa URL.
-5. **Presenta opciones con `preview_url`** para que el usuario vea cada una antes de elegir:
+1. **Primero** `sdd_catalog_list_blocks({ registry: "all", category: "<categoria>", limit: 10 })` — devuelve candidatos de los 4 registries simultáneamente.
+2. **Si la keyword cae en las 11 categorías de blocks-so** (stats, login, signup, form-layout, file-upload, tables, dialogs, sidebar, command-menu, ai, onboarding, grid-list), prioriza `registry: "blocks-so"`. Es la fuente más actualizada y curada para esos casos de uso. Ejemplo: si el usuario pide *"un formulario de registro"*, el Spec-Writer debe ir directo a `sdd_catalog_list_blocks({registry: "blocks-so", category: "form-layout", limit: 5})` y mostrar las 5 variantes (`form-layout-01` a `form-layout-05`).
+3. **Si el usuario pide animaciones/shaders/efectos visuales cinematograficos**, prioriza `registry: "reactbits"` (es donde estan las primitivas animadas reales: `Dither`, `Aurora`, `GlareHover`, `Magnet`, `StaggeredMenu`, `FloatingDock`, etc.).
+4. **Si el usuario pide paginas de marketing completas** (landing, pricing, features, hero), prioriza `registry: "shadcn"` (bloques Radix mas completos con texto, CTAs, imagenes placeholder).
+5. **Si el usuario ya dio una URL** (`https://reactbits.dev/...`, `https://blocks.so/...` o `https://shadcnui-blocks.com/...`), ve directo a `sdd_catalog_get_block` con esa URL.
+6. **Presenta opciones con `preview_url`** para que el usuario vea cada una antes de elegir:
    - **Asistido (HIL):** muestra `preview_url` (que el usuario puede abrir en navegador) + `install_command` para los 2-3 mejores candidatos y deja que elija. Si el usuario dice "ese", ejecuta el `install_command`.
    - **Autopiloto (`/loop`):** inspecciona 2-3 candidatos con `sdd_catalog_get_block`, analiza dependencias y compat con el stack del contrato, elige autonomamente.
 
 ### 5.3 Seleccion de Bloques (Interactiva o Autonoma)
 
 Cuando hay multiples opciones para una categoria (ej. 10 heroes):
-- **Modo Asistido (default):** pregunta al usuario con `question` o en chat: *"Tengo X opciones de [categoria]. ¿Quieres revisar alguna? Puedo darte el `preview_url` (ej. `https://shadcnui-blocks.com/blocks/hero-06` o `https://reactbits.dev/Dither`) para que elijas."*
+- **Modo Asistido (default):** pregunta al usuario con `question` o en chat: *"Tengo X opciones de [categoria]. ¿Quieres revisar alguna? Puedo darte el `preview_url` (ej. `https://shadcnui-blocks.com/blocks/hero-06`, `https://blocks.so/stats/stats-04` o `https://reactbits.dev/Dither`) para que elijas."*
 - **Modo Autopiloto:** lee el codigo de 2-3 opciones con `sdd_catalog_get_block` y elige sin preguntar.
 
 ### 5.4 Inyeccion e Instalacion (Spec-Writer + Coder)
@@ -211,6 +215,7 @@ Cuando hay multiples opciones para una categoria (ej. 10 heroes):
   "frontend": {
     "components": [
       { "name": "hero-06", "registry": "shadcn", "source": "akash3444/shadcn-ui-blocks" },
+      { "name": "stats-01", "registry": "blocks-so", "source": "ephraimduncan/blocks" },
       { "name": "Dither", "registry": "reactbits", "variant": "TS-TW", "source": "reactbits.dev/Dither" }
     ]
   }
@@ -223,6 +228,10 @@ Cuando hay multiples opciones para una categoria (ej. 10 heroes):
   npx shadcn@latest add https://basecn.dev/r/footer-04.json --yes
   # reactbits (variante TS-TW explicita)
   npx shadcn@latest add https://reactbits.dev/r/Dither-TS-TW.json --yes
+  # blocks-so (ephraimduncan/blocks)
+  npx shadcn@latest add https://blocks.so/r/stats-01.json --yes
+  # blocks-so via namespace (requiere declararlo en components.json)
+  npx shadcn@latest add @blocks-so/stats-01 --yes
   ```
   La CLI v3 de Shadcn negocia `Accept: application/json` automaticamente, descarga el codigo y resuelve las `registryDependencies`.
 
@@ -263,8 +272,55 @@ reactbits.dev es el registry mas "vivo" del catalogo unificado. Cada componente
 | shadcn | `https://shadcnui-blocks.com/blocks/<name>` | iframe del demo oficial |
 | basecn | `https://basecn.dev/blocks/<name>` | iframe del demo oficial |
 | reactbits | `https://reactbits.dev/<BaseName>` | demo vivo con animacion real + codigo a la derecha |
+| blocks-so | `https://blocks.so/<category>/<name>` | demo vivo con el bloque real renderizado (sin animaciones) |
 
-Cuando el orchestrator presente opciones al usuario, **siempre incluir el `preview_url`** en el chat. Para reactbits en particular, el demo es animado y se ve inmediatamente cómo se mueve la UI en el navegador del usuario — esto cierra el ciclo "imaginar como se ve → ver real → decidir instalar" sin hacer conjeturas.
+Cuando el orchestrator presente opciones al usuario, **siempre incluir el `preview_url`** en el chat. Para reactbits y blocks-so el demo es interactivo y se ve inmediatamente cómo se ve en el navegador del usuario — esto cierra el ciclo "imaginar como se ve → ver real → decidir instalar" sin hacer conjeturas.
+
+### 5.8 blocks.so (ephraimduncan/blocks) - Detalles
+
+blocks.so es el registry más curado para interfaces funcionales: **60+ bloques Radix prod-ready** con `categories[]` explícito en cada JSON. La diferencia clave frente a akash es que cada bloque de blocks.so **incluye un `categories[]` array** dentro del JSON, lo que elimina la ambigüedad de la heurística por nombre de archivo.
+
+**Estructura del repo**:
+```
+ephraimduncan/blocks/
+  content/
+    components/
+      ai/              ai-01.tsx ... ai-05.tsx          (5 bloques)
+      command-menu/    command-menu-01.tsx ...          (3 bloques)
+      dialogs/         dialog-01.tsx ... dialog-12.tsx  (12 bloques)
+      file-upload/     file-upload-01.tsx ...            (6 bloques)
+      form-layout/     form-layout-01.tsx ...            (5 bloques)
+      grid-list/       grid-list-01.tsx ...              (3 bloques)
+      login/           login-01.tsx ... login-09.tsx    (9 bloques)
+      onboarding/      onboarding-01.tsx ...             (7 bloques)
+      sidebar/         sidebar-01.tsx ... sidebar-06.tsx (6 bloques)
+      stats/           stats-01.tsx ... stats-15.tsx     (15 bloques)
+      tables/          tables-01.tsx ... tables-05.tsx   (5 bloques)
+```
+
+**Campos clave del JSON de cada bloque**:
+- `name`: canonical (ej: `"stats-01"`)
+- `type`: `"registry:block"` (estándar shadcn)
+- `title`: `"Stats with Trending"`
+- `description`: `"A stats with trending block."`
+- `author`: `"ephraim duncan <https://ephraimduncan.com>"`
+- `registryDependencies`: ej: `["card"]` — el coder debe pre-instalar via `sdd_bootstrap` antes del `npx shadcn add`.
+- `dependencies`: ej: `[]` — paquetes npm necesarios (rara vez hay, son 100% Radix).
+- `files[]`: cada item tiene `path` (origen en el repo), `type` (`"registry:component"`) y `target` (ruta destino en el proyecto, ej: `"components/stats-01.tsx"`).
+- `categories[]`: ej: `["stats"]` — usado para filtrado.
+
+**Patrones de uso en el contrato**:
+```json
+{
+  "frontend": {
+    "components": [
+      { "name": "stats-01", "registry": "blocks-so", "source": "ephraimduncan/blocks" }
+    ]
+  }
+}
+```
+
+**Cuidado con `field` y `FieldGroup`**: algunos bloques de `form-layout` y `onboarding` usan el primitivo `field` (Field, FieldLabel, FieldDescription) que no viene por defecto en `npx shadcn add`. Si `sdd_catalog_get_block` lista `field` en `registryDependencies[]`, el coder debe correr `npx shadcn@latest add field` antes de instalar el bloque.
 
 ---
 

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

@@ -18,6 +18,7 @@
   },
   "iconLibrary": "lucide",
   "registries": {
-    "@react-bits": "https://reactbits.dev/r/{name}.json"
+    "@react-bits": "https://reactbits.dev/r/{name}.json",
+    "@blocks-so": "https://blocks.so/r/{name}.json"
   }
 }