# Orquestador

[![Verificar](https://github.com/programadores-obreros/orquestador/actions/workflows/verificar.yml/badge.svg)](https://github.com/programadores-obreros/orquestador/actions/workflows/verificar.yml)
[![Semillas](https://github.com/programadores-obreros/orquestador/actions/workflows/semillas.yml/badge.svg)](https://github.com/programadores-obreros/orquestador/actions/workflows/semillas.yml)
[![MIT](https://img.shields.io/badge/licencia-MIT-blue.svg)](./LICENSE)

**Declarás un circuito una vez. Te devuelve documentación técnica de electrónica
verificada** — esquema eléctrico, PDF, lista de materiales, placa, render 3D. Y
si el circuito tiene un defecto, no devuelve nada: un PDF prolijo de un circuito
mal conectado es peor que ningún PDF, porque le da autoridad de documento a un
error.

Dos paquetes MIT, uno arriba del otro:

| Paquete | Qué es | Para quién |
|---|---|---|
| [`@tecnialab/esquematizador`](./esquematizador) | La biblioteca. Netlist declarado → nueve artefactos, verificados con KiCad | Lo usás desde tu código |
| [`@tecnialab/motor`](./motor) | Un servidor MCP que expone lo anterior como cinco herramientas | Lo usa un agente de IA |

No hace falta instalar KiCad. Corre en Docker.

---

## Camino rápido

```bash
pnpm install
pnpm test          # 686 pruebas, sin Docker, ~13 s
pnpm verificar-pack  # genera 3 circuitos de verdad, con Docker, ~19 s
```

Lo segundo baja la imagen de KiCad (1,7 GB) la primera vez. Si sale así, anda
todo:

```
  ✓ led-indicador    9 artefactos
  ✓ pulsador         9 artefactos
  ✓ semaforo         9 artefactos
```

## Qué hace y qué NO

Te lo decimos en la portada para que no pierdas una tarde en descubrirlo.

**Sí:** circuitos de *placa controladora + periféricos*. Arduino, ESP32, Pico,
STM32, PIC — cualquier placa. Cada red se dibuja partiendo del pin de la placa,
que es el centro del plano.

**No:** emplazamiento analógico arbitrario. Si lo tuyo es un 555 astable o una
fuente conmutada, esta herramienta no es la tuya.

## Por qué existe

Un agente de IA que produce documentación de electrónica **no falla al ejecutar
el generador** — eso son seis segundos y una línea de comandos. Falla al
**escribir el netlist**: inventa un pin que no existe, nombra un símbolo que no
está en la biblioteca, conecta dos redes que no van.

Por eso la herramienta más valiosa del motor no es la que genera. Es
`verificar_netlist`, que caza el error en **43 ms y sin levantar Docker**.

| Herramienta | Cuesta | Devuelve |
|---|---|---|
| `semilla` | instantáneo | Un circuito que YA pasa, para adaptar. Vienen tres de ejemplo |
| `buscar_componente` | instantáneo | Símbolos y huellas que existen de verdad |
| `verificar_netlist` | **43 ms**, sin Docker | Los problemas del netlist, uno por uno |
| `documentar` | ~6 s | Veredicto + plano y placa **como imágenes** + rutas |
| `revisar` | 3 ms | Lo ya generado, sin volver a generarlo |

## Cómo se verifica lo que hay acá

Este proyecto encontró en una sola semana **seis defectos de la misma familia**:
algo que anda en la máquina de quien lo escribió y no anda afuera. Ninguno lo
encontró alguien razonando.

De ahí salieron doce reglas mecánicas — mutar cada test después de moverlo,
verificar que la mutación *entró* antes de leer el resultado, medir en un entorno
ajeno, correr la cosa entera y no sólo las partes.

**→ [`COMO-SE-VERIFICA.md`](./COMO-SE-VERIFICA.md)**

> Si una regla nueva necesita que alguien se acuerde de aplicarla, todavía no es
> una regla — es una intención.

## Requisitos

| | |
|---|---|
| Node | ≥ 23.6 para desarrollar; los paquetes publicados piden ≥ 20 |
| pnpm | 11.3 (sale de `packageManager`) |
| Docker | corriendo, para generar. **No** para las pruebas |

## Licencia

MIT — ver [`LICENSE`](./LICENSE).

Las bibliotecas de símbolos y huellas de KiCad que se recortan para las pruebas
conservan la suya; está detallado en [`NOTICE`](./NOTICE).