zugzbot 1.0.20 → 1.0.22

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

@@ -47,6 +47,7 @@ Eres el Programador de Código (sdd-coder) del arnés SDD. Tu trabajo es codific
 - **Política Zero-Search (Mapeo de Archivos)**: Tienes STRICTAMENTE PROHIBIDO utilizar herramientas de búsqueda exploratoria como `glob` o `grep` de manera ciega para descubrir qué editar. Debes leer el parámetro `files_affected` de tu sección de brief activo y proceder de manera directa, inmediata e idiomática a leer (`read`), crear (`write`) o modificar (`edit`) exactamente esos archivos.
 - **NO escribir archivos de bootstrap manualmente**: No crees package.json, tsconfig.json, configs ni archivos base de Next.js/FastAPI a mano. Todo lo gestiona `sdd_bootstrap_nextjs_shadcn` o `sdd_bootstrap_fastapi`.
 - **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'.
 </constraints>
 

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

@@ -32,6 +32,7 @@ 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.
 - **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.

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

@@ -83,6 +83,14 @@ Cada fase tiene un **gate explícito** (HIL del usuario) antes de transicionar a
 **NO HAGAS**: Invocar herramientas de Playwright (`playwright_browser_navigate`, `playwright_browser_snapshot`, etc.) si `verificationMode` está configurado en `"console"`. Esto consume tiempo y reasoning innecesarios.
 **HAZ**: En modo `console`, confía en pruebas unitarias/integración (Vitest) y verificaciones directas con curls/logs. No abras navegadores.
 
+### Trampa 11: Orquestador usurpador (Ruptura de Abstracción)
+**NO HAGAS**: Permitir que el Orquestador principal (`sdd-orchestrator`) tome el rol de escribir el código de producción o escribir/ejecutar tests directamente si un subagent (ej. `@sdd-coder`) falla o alcanza el límite de pasos ("Maximum Steps Reached"). Esto ensucia la ventana de contexto principal de la sesión.
+**HAZ**: Re-invoca al mismo subagente usando la herramienta `task`, pasando el `task_id` original del subagente interrumpido e instruyéndole: "Te quedaste sin pasos. Continúa y finaliza los archivos pendientes".
+
+### Trampa 12: Obsesión por alineación de consola (Pixel-Peeping)
+**NO HAGAS**: Gastar múltiples iteraciones o miles de tokens en el razonamiento de `@sdd-coder` tratando de lograr una alineación perfecta de columnas con espacios exactos en salidas CLI o tablas ASCII.
+**HAZ**: Usa funciones estándar de formateo de strings de tu lenguaje (como `ljust()`, `rjust()` o `center()` en Python; o formateadores sencillos en JS/TS) para lograr una presentación razonable de forma inmediata y avanzar directamente a la creación de pruebas.
+
 ---
 
 ## 4. Stack cerrado (NO abrir)

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

@@ -13,6 +13,12 @@ Esta habilidad proporciona un **flujo de trabajo estructurado en 4 pasos** para
 
 ## 🚀 El flujo F3 en 4 pasos (Sin exploración ciega)
 
+*NOTA DE LENGUAJE (CRÍTICO):* Si el proyecto es en **Python**, toda la suite de Node.js/Vitest queda excluida. Aplica los pasos de abajo usando herramientas de Python:
+- En el **Paso 1**, lee `requirements.txt` y los archivos en `tests/` y `src/`.
+- En el **Paso 2**, no ejecutes `./generate-tests.sh` ya que es Node. El contrato ya debió tener los tests redactados por el spec-writer, o el coder los generó en F2.
+- En el **Paso 3**, no aplican los mocks de React, Lucide ni `crypto.randomUUID` en JS. Si necesitas mockear en Python, usa `unittest.mock` (como `patch` o `MagicMock`).
+- En el **Paso 4**, ejecuta `ruff check src/` o similar para linting, y `python -m pytest tests/ -v` para ejecutar toda la suite de pruebas de una sola llamada consolidada.
+
 ### Paso 1: Leer solo lo indispensable (Máximo 3 reads)
 1. **Contrato**: Lee únicamente `contract.json` para extraer los `test_scenarios` y el `verificationMode`.
 2. **Setup**: Lee `src/test/setup.ts` o `vitest.config.ts` para confirmar si ya hay polyfills.

package/.opencode/tools/sdd_testing.ts

@@ -112,6 +112,99 @@ export const shift_left_verify = tool({
   args: {},
   async execute(args, context) {
     const root = getRoot(context)
+
+    // Check if it is a Python project
+    let isPython = fs.existsSync(path.resolve(root, "requirements.txt")) || fs.existsSync(path.resolve(root, "pyproject.toml"));
+    try {
+      const stateFile = path.resolve(root, ".openspec/sdd_state.json")
+      if (fs.existsSync(stateFile)) {
+        const state = JSON.parse(fs.readFileSync(stateFile, "utf8"))
+        if (state.activeContract) {
+          const contractPath = path.resolve(root, state.activeContract)
+          if (fs.existsSync(contractPath)) {
+            const contract = JSON.parse(fs.readFileSync(contractPath, "utf8"))
+            if (contract && contract.settings && contract.settings.language?.toLowerCase() === "python") {
+              isPython = true
+            }
+          }
+        }
+      }
+    } catch (e) {
+      // ignore
+    }
+
+    if (isPython) {
+      const resultPython: { ruff: { status: string, errors?: any[] } } = {
+        ruff: { status: "SUCCESS" }
+      }
+      try {
+        let pythonFiles = "src/"
+        const stateFile = path.resolve(root, ".openspec/sdd_state.json")
+        if (fs.existsSync(stateFile)) {
+          const state = JSON.parse(fs.readFileSync(stateFile, "utf8"))
+          if (state.activeContract) {
+            const contractPath = path.resolve(root, state.activeContract)
+            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"))
+                if (existingFiles.length > 0) {
+                  pythonFiles = existingFiles.join(" ")
+                }
+              }
+            }
+          }
+        }
+        
+        try {
+          execSync(`ruff check ${pythonFiles} --quiet`, { cwd: root, 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) {
+            return JSON.stringify({
+              status: "SUCCESS",
+              message: "Proyecto Python detectado. Ruff linter no está instalado en este entorno; omitiendo verificación estática de lint (se confía en F3 Pytest)."
+            }, null, 2)
+          }
+          
+          const errors: any[] = []
+          const lines = output.split("\n")
+          for (const line of lines) {
+            const ruffMatch = line.match(/^([^:]+):(\d+):(\d+):\s+(.+)$/)
+            if (ruffMatch) {
+              errors.push({
+                file: ruffMatch[1].trim(),
+                line: parseInt(ruffMatch[2], 10),
+                column: parseInt(ruffMatch[3], 10),
+                error: ruffMatch[4].trim()
+              })
+            } else if (line.trim().length > 0) {
+              errors.push({ raw: line.trim() })
+            }
+          }
+          
+          if (errors.length > 0) {
+            resultPython.ruff = {
+              status: "FAIL",
+              errors
+            }
+          }
+        }
+      } catch (e: any) {
+        return JSON.stringify({
+          status: "SUCCESS",
+          message: "Proyecto Python detectado. Error al ejecutar Ruff; omitiendo verificación estática para confiar en F3 Pytest."
+        }, null, 2)
+      }
+      
+      const overallSuccess = resultPython.ruff.status === "SUCCESS"
+      return JSON.stringify({
+        status: overallSuccess ? "SUCCESS" : "FAIL",
+        message: overallSuccess ? "Shift-Left Verification (Python Ruff) exitosa: Cero errores de lint." : "Validación fallida: Se encontraron errores estáticos de Ruff.",
+        verification: resultPython
+      }, null, 2)
+    }
+
     const result: { tsc: { status: string, errors?: any[] }, eslint: { status: string, errors?: any[] } } = {
       tsc: { status: "SUCCESS" },
       eslint: { status: "SUCCESS" }

package/opencode.json

@@ -1,5 +1,13 @@
 {
   "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "sdd-spec-writer": {
+      "mode": "subagent",
+      "permission": {
+        "webfetch": "deny"
+      }
+    }
+  },
   "permission": {
     "*": "allow",
     "skill": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zugzbot",
-  "version": "1.0.20",
+  "version": "1.0.22",
   "description": "Fácil instalador del arnés SDD de Zugzbot para proyectos OpenCode",
   "type": "module",
   "bin": {
@@ -8,11 +8,21 @@
   },
   "files": [
     "bin/",
-    ".opencode/",
-    ".utils/",
     "models.json",
     "opencode.json",
-    "tui.json"
+    "tui.json",
+    ".opencode/agents/",
+    ".opencode/commands/",
+    ".opencode/plugins/",
+    ".opencode/rules/",
+    ".opencode/skills/",
+    ".opencode/templates/",
+    ".opencode/tools/",
+    ".opencode/contract-schema.json",
+    ".opencode/oh-my-design/design-md/",
+    ".opencode/oh-my-design/packages/mcp/dist/",
+    ".utils/export_opencode_session.py",
+    ".utils/toggle_model.py"
   ],
   "engines": {
     "node": ">=16.0.0"

package/tui.json

@@ -5,10 +5,9 @@
     "./.opencode/plugins/plugin_tui.tsx"
   ],
   "keybinds": {
-    "leader": "ctrl+x",
-    "sidebar_toggle": "leader,b",
-    "theme_list": "leader,t",
-    "session_list": "leader,l",
-    "editor_open": "leader,e"
+    "sidebar_toggle": "f3",
+    "theme_list": "f4",
+    "session_list": "f5",
+    "editor_open": "f6"
   }
 }

package/.opencode/active-brief.md

@@ -1,38 +0,0 @@
-# Dashboard Animations — Spec Activo
-
-**Contrato**: `.openspec/specs/2026-06-16__09-50-28_dashboard-animations/contract.json`
-
-## Resumen
-Añadir animaciones de entrada, tooltips interactivos, donut chart alternativo, hover en timeline, smooth transitions y carga progresiva al StatsDashboard existente.
-
-## Stack
-- Next.js 16 + Shadcn UI + Tailwind v4 + localStorage + Vitest
-- Diseño: Linear.app (#5e6ad2 indigo, dark-mode-first)
-
-## Componentes involucrados
-- **StatsDashboard** (`@/components/blocks/StatsDashboard.tsx`) — Modificar: añadir animaciones, tooltips, toggle, carga progresiva
-- **DonutChart** (NUEVO: `@/components/blocks/DonutChart.tsx`) — Mini donut con conic-gradient
-- **MetricCard** (inline en StatsDashboard) — fadeSlideUp + smooth transitions
-- **ColorChart/WeeklyChart** (inline en StatsDashboard) — Tooltips en hover + toggle Donut/Bar
-- **HashtagsCloud** (inline en StatsDashboard) — Progressive loading (600-900ms)
-- **Timeline** (inline en StatsDashboard) — Hover interactivo + mini preview
-
-## Shadcn components necesarios
-- `tooltip` (instalar con: `npx shadcn@latest add tooltip`)
-
-## Lucide icons usados
-- `PieChart`, `BarChart3`, `MousePointer2`, `BarChartHorizontal`
-
-## Animaciones
-- `@keyframes fadeSlideUp`: opacity 0→1, translateY(12px)→0
-- Metric cards: 0-300ms (index * 50ms delay)
-- Charts: 300-600ms
-- Hashtags + Timeline: 600-900ms
-- Smooth transitions: `transition-all duration-200 ease-out`
-- Hover: `hover:shadow-md hover:-translate-y-[1px]`
-
-## Tests (4 escenarios)
-1. TS-ANIM-01 → StatsDashboard metric cards tienen animación
-2. TS-ANIM-02 → DonutChart renderiza conic-gradient correcto
-3. TS-ANIM-03 → Toggle button cambia vista
-4. TS-ANIM-04 → Tooltip en WeeklyChart aparece en hover

package/.opencode/docs/shadcn/agents/openai.yml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "shadcn/ui"
-  short_description: "Manages shadcn/ui components — adding, searching, fixing, debugging, styling, and composing UI."
-  icon_small: "./assets/shadcn-small.png"
-  icon_large: "./assets/shadcn.png"

package/.opencode/docs/shadcn/cli.md

@@ -1,290 +0,0 @@
-# shadcn CLI Reference
-
-Configuration is read from `components.json`.
-
-> **IMPORTANT:** Always run commands using the project's package runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest`. Check `packageManager` from project context to choose the right one. Examples below use `npx shadcn@latest` but substitute the correct runner for the project.
-
-> **IMPORTANT:** Only use the flags documented below. Do not invent or guess flags — if a flag isn't listed here, it doesn't exist. The CLI auto-detects the package manager from the project's lockfile; there is no `--package-manager` flag.
-
-## Contents
-
-- Commands: init, apply, add (dry-run, smart merge), search, view, docs, info, build
-- Templates: next, vite, start, react-router, astro
-- Presets: named, code, URL formats and fields
-- Switching presets
-
----
-
-## Commands
-
-### `init` — Initialize or create a project
-
-```bash
-npx shadcn@latest init [components...] [options]
-```
-
-Initializes shadcn/ui in an existing project or creates a new project (when `--name` is provided). Optionally installs components in the same step.
-
-| Flag                    | Short | Description                                               | Default |
-| ----------------------- | ----- | --------------------------------------------------------- | ------- |
-| `--template <template>` | `-t`  | Template (next, start, vite, next-monorepo, react-router) | —       |
-| `--preset [name]`       | `-p`  | Preset configuration (named, code, or URL)                | —       |
-| `--yes`                 | `-y`  | Skip confirmation prompt                                  | `true`  |
-| `--defaults`            | `-d`  | Use defaults (`--template=next --preset=base-nova`)       | `false` |
-| `--force`               | `-f`  | Force overwrite existing configuration                    | `false` |
-| `--cwd <cwd>`           | `-c`  | Working directory                                         | current |
-| `--name <name>`         | `-n`  | Name for new project                                      | —       |
-| `--silent`              | `-s`  | Mute output                                               | `false` |
-| `--rtl`                 |       | Enable RTL support                                        | —       |
-| `--reinstall`           |       | Re-install existing UI components                         | `false` |
-| `--monorepo`            |       | Scaffold a monorepo project                               | —       |
-| `--no-monorepo`         |       | Skip the monorepo prompt                                  | —       |
-
-`npx shadcn@latest create` is an alias for `npx shadcn@latest init`.
-
-### `apply` — Apply a preset to an existing project
-
-```bash
-npx shadcn@latest apply [preset] [options]
-```
-
-Applies a preset to an existing project, overwriting preset-driven config, fonts, CSS variables, and detected UI components.
-
-| Flag                | Short | Description                                | Default |
-| ------------------- | ----- | ------------------------------------------ | ------- |
-| `--preset <preset>` | —     | Preset configuration (named, code, or URL) | —       |
-| `--yes`             | `-y`  | Skip confirmation prompt                   | `false` |
-| `--cwd <cwd>`       | `-c`  | Working directory                          | current |
-| `--silent`          | `-s`  | Mute output                                | `false` |
-
-`[preset]` is a shorthand for `--preset <preset>`. If both are provided, they must match.
-If no preset is provided, the CLI offers to open the custom preset builder on `ui.shadcn.com/create`.
-
-### `add` — Add components
-
-> **IMPORTANT:** To compare local components against upstream or to preview changes, ALWAYS use `npx shadcn@latest add <component> --dry-run`, `--diff`, or `--view`. NEVER fetch raw files from GitHub or other sources manually. The CLI handles registry resolution, file paths, and CSS diffing automatically.
-
-```bash
-npx shadcn@latest add [components...] [options]
-```
-
-Accepts component names, registry-prefixed names (`@magicui/shimmer-button`),
-GitHub item addresses (`owner/repo/item`), URLs, or local paths.
-
-| Flag            | Short | Description                                                                                                          | Default |
-| --------------- | ----- | -------------------------------------------------------------------------------------------------------------------- | ------- |
-| `--yes`         | `-y`  | Skip confirmation prompt                                                                                             | `false` |
-| `--overwrite`   | `-o`  | Overwrite existing files                                                                                             | `false` |
-| `--cwd <cwd>`   | `-c`  | Working directory                                                                                                    | current |
-| `--all`         | `-a`  | Add all available components                                                                                         | `false` |
-| `--path <path>` | `-p`  | Target path for the component                                                                                        | —       |
-| `--silent`      | `-s`  | Mute output                                                                                                          | `false` |
-| `--dry-run`     |       | Preview all changes without writing files                                                                            | `false` |
-| `--diff [path]` |       | Show diffs. Without a path, shows the first 5 files. With a path, shows that file only (implies `--dry-run`)         | —       |
-| `--view [path]` |       | Show file contents. Without a path, shows the first 5 files. With a path, shows that file only (implies `--dry-run`) | —       |
-
-#### Dry-Run Mode
-
-Use `--dry-run` to preview what `add` would do without writing any files. `--diff` and `--view` both imply `--dry-run`.
-
-```bash
-# Preview all changes.
-npx shadcn@latest add button --dry-run
-
-# Show diffs for all files (top 5).
-npx shadcn@latest add button --diff
-
-# Show the diff for a specific file.
-npx shadcn@latest add button --diff button.tsx
-
-# Show contents for all files (top 5).
-npx shadcn@latest add button --view
-
-# Show the full content of a specific file.
-npx shadcn@latest add button --view button.tsx
-
-# Works with URLs too.
-npx shadcn@latest add https://api.npoint.io/abc123 --dry-run
-
-# Works with public GitHub registries too.
-npx shadcn@latest add owner/repo/item --dry-run
-
-# CSS diffs.
-npx shadcn@latest add button --diff globals.css
-```
-
-**When to use dry-run:**
-
-- When the user asks "what files will this add?" or "what will this change?" — use `--dry-run`.
-- Before overwriting existing components — use `--diff` to preview the changes first.
-- When the user wants to inspect component source code without installing — use `--view`.
-- When checking what CSS changes would be made to `globals.css` — use `--diff globals.css`.
-- When the user asks to review or audit third-party registry code before installing — use `--view` to inspect the source.
-
-> **`npx shadcn@latest add --dry-run` vs `npx shadcn@latest view`:** Prefer `npx shadcn@latest add --dry-run/--diff/--view` over `npx shadcn@latest view` when the user wants to preview changes to their project. `npx shadcn@latest view` only shows raw registry metadata. `npx shadcn@latest add --dry-run` shows exactly what would happen in the user's project: resolved file paths, diffs against existing files, and CSS updates. Use `npx shadcn@latest view` only when the user wants to browse registry info without a project context.
-
-#### Smart Merge from Upstream
-
-See [Updating Components in SKILL.md](./SKILL.md#updating-components) for the full workflow.
-
-### `search` — Search registries
-
-```bash
-npx shadcn@latest search [registries...] [options]
-```
-
-Fuzzy search across registries. Also aliased as `npx shadcn@latest list`.
-Supports namespaces (`@acme`), public GitHub registry sources (`owner/repo`),
-and registry catalog URLs. Without `-q`, lists all items. When no registries are
-passed, searches every registry configured in `components.json`.
-
-| Flag                | Short | Description                                       | Default |
-| ------------------- | ----- | ------------------------------------------------- | ------- |
-| `--query <query>`   | `-q`  | Search query                                      | —       |
-| `--type <type>`     | `-t`  | Filter by item type (e.g. `ui`, `block`, `hook`); comma-separated | —       |
-| `--limit <number>`  | `-l`  | Max items to display                              | `100`   |
-| `--offset <number>` | `-o`  | Items to skip                                     | `0`     |
-| `--json`            |       | Output as JSON                                    | `false` |
-| `--cwd <cwd>`       | `-c`  | Working directory                                 | current |
-
-### `view` — View item details
-
-```bash
-npx shadcn@latest view <items...> [options]
-```
-
-Displays item info including file contents. Examples:
-`npx shadcn@latest view @shadcn/button`,
-`npx shadcn@latest view owner/repo/item`.
-
-### `docs` — Get component documentation URLs
-
-```bash
-npx shadcn@latest docs <components...> [options]
-```
-
-Outputs resolved URLs for component documentation, examples, and API references. Accepts one or more component names. Fetch the URLs to get the actual content.
-
-Example output for `npx shadcn@latest docs input button`:
-
-```
-base  radix
-
-input
-  docs      https://ui.shadcn.com/docs/components/radix/input
-  examples  https://raw.githubusercontent.com/.../examples/input-example.tsx
-
-button
-  docs      https://ui.shadcn.com/docs/components/radix/button
-  examples  https://raw.githubusercontent.com/.../examples/button-example.tsx
-```
-
-Some components include an `api` link to the underlying library (e.g. `cmdk` for the command component).
-
-### `diff` — Check for updates
-
-Do not use this command. Use `npx shadcn@latest add --diff` instead.
-
-### `info` — Project information
-
-```bash
-npx shadcn@latest info [options]
-```
-
-Displays project info and `components.json` configuration. Run this first to discover the project's framework, aliases, Tailwind version, and resolved paths.
-
-| Flag          | Short | Description       | Default |
-| ------------- | ----- | ----------------- | ------- |
-| `--cwd <cwd>` | `-c`  | Working directory | current |
-
-**Project Info fields:**
-
-| Field                | Type      | Meaning                                                            |
-| -------------------- | --------- | ------------------------------------------------------------------ |
-| `framework`          | `string`  | Detected framework (`next`, `vite`, `react-router`, `start`, etc.) |
-| `frameworkVersion`   | `string`  | Framework version (e.g. `15.2.4`)                                  |
-| `isSrcDir`           | `boolean` | Whether the project uses a `src/` directory                        |
-| `isRSC`              | `boolean` | Whether React Server Components are enabled                        |
-| `isTsx`              | `boolean` | Whether the project uses TypeScript                                |
-| `tailwindVersion`    | `string`  | `"v3"` or `"v4"`                                                   |
-| `tailwindConfigFile` | `string`  | Path to the Tailwind config file                                   |
-| `tailwindCssFile`    | `string`  | Path to the global CSS file                                        |
-| `aliasPrefix`        | `string`  | Import alias prefix (e.g. `@`, `~`, `@/`)                          |
-| `packageManager`     | `string`  | Detected package manager (`npm`, `pnpm`, `yarn`, `bun`)            |
-
-**Components.json fields:**
-
-| Field                | Type      | Meaning                                                                                    |
-| -------------------- | --------- | ------------------------------------------------------------------------------------------ |
-| `base`               | `string`  | Primitive library (`radix` or `base`) — determines component APIs and available props      |
-| `style`              | `string`  | Visual style (e.g. `nova`, `vega`)                                                         |
-| `rsc`                | `boolean` | RSC flag from config                                                                       |
-| `tsx`                | `boolean` | TypeScript flag                                                                            |
-| `tailwind.config`    | `string`  | Tailwind config path                                                                       |
-| `tailwind.css`       | `string`  | Global CSS path — this is where custom CSS variables go                                    |
-| `iconLibrary`        | `string`  | Icon library — determines icon import package (e.g. `lucide-react`, `@tabler/icons-react`) |
-| `aliases.components` | `string`  | Component import alias (e.g. `@/components`)                                               |
-| `aliases.utils`      | `string`  | Utils import alias (e.g. `@/lib/utils`)                                                    |
-| `aliases.ui`         | `string`  | UI component alias (e.g. `@/components/ui`)                                                |
-| `aliases.lib`        | `string`  | Lib alias (e.g. `@/lib`)                                                                   |
-| `aliases.hooks`      | `string`  | Hooks alias (e.g. `@/hooks`)                                                               |
-| `resolvedPaths`      | `object`  | Absolute file-system paths for each alias                                                  |
-| `registries`         | `object`  | Configured custom registries                                                               |
-
-**Links fields:**
-
-The `info` output includes a **Links** section with templated URLs for component docs, source, and examples. For resolved URLs, use `npx shadcn@latest docs <component>` instead.
-
-### `build` — Build a custom registry
-
-```bash
-npx shadcn@latest build [registry] [options]
-```
-
-Builds `registry.json` into individual JSON files for distribution. Default input: `./registry.json`, default output: `./public/r`.
-
-For authoring rules, `include`, item definitions, `registryDependencies`, and
-GitHub registry behavior, see [registry.md](./registry.md).
-
-| Flag              | Short | Description       | Default      |
-| ----------------- | ----- | ----------------- | ------------ |
-| `--output <path>` | `-o`  | Output directory  | `./public/r` |
-| `--cwd <cwd>`     | `-c`  | Working directory | current      |
-
----
-
-## Templates
-
-| Value          | Framework      | Monorepo support |
-| -------------- | -------------- | ---------------- |
-| `next`         | Next.js        | Yes              |
-| `vite`         | Vite           | Yes              |
-| `start`        | TanStack Start | Yes              |
-| `react-router` | React Router   | Yes              |
-| `astro`        | Astro          | Yes              |
-| `laravel`      | Laravel        | No               |
-
-All templates support monorepo scaffolding via the `--monorepo` flag. When passed, the CLI uses a monorepo-specific template directory (e.g. `next-monorepo`, `vite-monorepo`). When neither `--monorepo` nor `--no-monorepo` is passed, the CLI prompts interactively. Laravel does not support monorepo scaffolding.
-
----
-
-## Presets
-
-Three ways to specify a preset via `--preset`:
-
-1. **Named:** `--preset nova` or `--preset lyra`
-2. **Code:** `--preset a2r6bw` (version-prefixed base62 string, e.g. `a2r6bw` or `b0`)
-3. **URL:** `--preset "https://ui.shadcn.com/init?base=radix&style=nova&..."`
-
-> **IMPORTANT:** Never try to decode, fetch, or resolve preset codes manually. Preset codes are opaque — pass them directly to `npx shadcn@latest init --preset <code>` and let the CLI handle resolution.
-> Use `npx shadcn@latest apply --preset <code>` when overwriting an existing project's preset.
-
-## Switching Presets
-
-Ask the user first: **overwrite**, **merge**, or **skip** existing components?
-
-- **Overwrite / Re-install** → `npx shadcn@latest apply --preset <code>`. Overwrites all detected component files with the new preset styles. Use when the user hasn't customized components.
-- **Merge** → `npx shadcn@latest init --preset <code> --force --no-reinstall`, then run `npx shadcn@latest info` to get the list of installed components and use the [smart merge workflow](./SKILL.md#updating-components) to update them one by one, preserving local changes. Use when the user has customized components.
-- **Skip** → `npx shadcn@latest init --preset <code> --force --no-reinstall`. Only updates config and CSS variables, leaves existing components as-is.
-
-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.