# Kit y sistemas

Qué vive en el kit, qué vive en cada sistema y cómo se mantienen sincronizados.

## Dos tipos de repo

| Repo | Contiene | Ejemplo |
| --- | --- | --- |
| **Kit** (`design-system-agentic-first-kit`) | El motor: interfaz, CLI `ds`, scripts de sync y publicación, plantilla, skills y esta metodología. No nombra ningún producto. | Uno solo, compartido. |
| **Sistema** (`<producto>-design-system`) | El contenido de un producto: `system.json`, `DESIGN.md`, fichas, CSS experimental, instantánea de producción y huellas. | Uno por producto. |
| **Producción** | El código real del producto. El sistema lo lee; no lo modifica. | El repo de cada producto. |

```
kit ──(dependencia npm)──▶ sistema ──(lee por ruta, ds sync)──▶ producción
```

Es el patrón de Docusaurus, Storybook o Starlight: el motor se instala; el contenido es tuyo. Así cada sistema recibe las mejoras del kit subiendo de versión, sin mezclar cambios a mano.

## Por qué el sistema no vive dentro del repo de producción

Es una opción válida (lo hacen equipos con un monorepo), pero con un solo entorno de despliegue cualquier cambio en producción sale a producción. Separados:

- documentar no arriesga el producto;
- el sistema tiene su propio historial y su propio ritmo;
- el enlace se mantiene igual de estricto: las huellas detectan cualquier cambio de producción.

Cuando el producto tenga staging y CI, se añade a su CI un `ds check` que avise si un cambio de producción deja una ficha desajustada (ver «Git, GitHub y entornos»).

## Desarrollar el kit con datos reales

La interfaz se pule mejor con contenido real. Para eso se enlaza el kit en local desde el repo del sistema:

```bash
cd producto-design-system
npx ds enlazar ../design-system-agentic-first-kit   # el kit necesita su propio npm install
npx ds dev
npx ds desenlazar                                   # vuelve a la versión fijada en package.json
```

`ds enlazar` crea el enlace solo en ese repo (no usa `npm link`, que necesita permisos sobre la carpeta global de npm). Un `npm install` en el sistema también deshace el enlace.

Con el kit enlazado, `ds dev` ejecuta el motor desde la carpeta del kit: cada cambio en la interfaz se ve al momento con los datos del sistema. Los cambios se commitean **en el kit**, nunca en el sistema.

Sin enlazar, `ds` copia el motor a `.ds/kit` (ignorado por git) y lo ejecuta desde ahí.

## Actualizar un sistema

```bash
npm install github:USUARIO/design-system-agentic-first-kit#vX.Y.Z
npx ds skills     # actualiza las skills
npx ds sync && npx ds check
```

La skill `actualizar-kit` lo hace y resume el changelog.

## Versiones del kit

- **Parche**: arreglos de interfaz sin cambios en el contenido.
- **Menor**: funciones nuevas compatibles (una sección, un campo opcional).
- **Mayor**: cambios que obligan a tocar fichas o `system.json`. Van con una guía de migración en `CHANGELOG.md`.