create-lexy 0.6.2 → 0.6.3

package/templates/AGENTS.md

@@ -0,0 +1,243 @@
+# AGENTS.md — Agente de Diseño Lexy
+
+Punto de entrada universal para agentes de IA en este proyecto, incluido **OpenAI
+Codex** (que lee `AGENTS.md` de forma nativa) y cualquier agente genérico. Este
+documento define la **orquestación**, los **fundamentos de marca Lexy** y el **índice
+de referencias**. El flujo de trabajo ordenado lo definen las **skills**, no este archivo.
+
+## El modelo de componentes (regla central)
+
+**Los componentes viven en tu proyecto.** No hay librería npm que importar ni
+internals prohibidos: el catálogo Lexy es un registry y cada componente se trae
+como código local, tuyo y editable.
+
+```bash
+npx create-lexy view --list      # descubrir el catálogo
+npx create-lexy view button      # ver código + doc ANTES de instalar
+npx create-lexy add button       # instalarlo local y editable, con sus deps
+npx create-lexy diff button      # tu copia vs el registry vigente
+npx create-lexy doctor           # salud y drift de todo lo instalado
+```
+
+Después de `add`, importa con el patrón local del proyecto (campo
+`componentImportPattern` de [ai/lexy-ai-manifest.json](ai/lexy-ai-manifest.json),
+derivado de `.lexy`) y **edita el componente con libertad** cuando el diseño lo
+pida — esa libertad es el modelo, no una excepción. La divergencia con el registry
+no es un error: se mantiene **visible** con `diff`/`doctor`.
+
+El catálogo incluye además **blocks** (vistas canónicas multi-componente:
+`intake-wizard`, `confirmacion`, `login`, `crm-desk`, `crm-detalle-caso`,
+`crm-app-layout`) que se instalan igual (`add crm-desk`) y quedan en la ruta de
+vistas del proyecto con sus componentes resueltos como dependencias.
+
+**Interop shadcn**: el proyecto trae `components.json` con el namespace `@lexy`
+apuntando al CDN, y `.mcp.json` con el **MCP de shadcn** — Claude Code y Cursor
+pueden navegar el catálogo vía MCP (`npx shadcn@latest mcp`) y también funciona
+`npx shadcn@latest add @lexy/button`. El CLI nativo sigue siendo `create-lexy`.
+
+## Prototipo funcional: datos, ports y mock-store
+
+Los proyectos nuevos declaran los datos usados por la experiencia en
+`src/prototype/data-contract/prototype-data-contract.ts`. La ruta exacta y el
+estado de habilitación viven en `.lexy` y en `ai/lexy-ai-manifest.json` →
+`prototype`.
+
+Antes de agregar a una pantalla un dato visible, editable, calculado o filtrable:
+
+1. comprueba que exista en el contrato;
+2. agrega o actualiza su entidad, campo, relación, estado o proyección;
+3. si nació desde usabilidad, usa `origin: "generatedByUsability"` y
+   `technicalValidation.status: "pendingTi"` con una nota para TI;
+4. ejecuta `pnpm check:data-contract`;
+5. recién entonces implementa su consumo en la UI.
+
+El código frontend usa IDs y keys `camelCase`. Las referencias a nombres reales
+de backend se escriben en `source.reference` con `snake_case`, por ejemplo:
+campo `rutCliente` → fuente `cliente.rut_cliente`.
+
+El contrato describe datos; no almacena registros mock, datos personales reales,
+eventos ni persistencia.
+
+Las comunicaciones externas pasan por `src/prototype/ports/`:
+
+- `read.load(loadId, params, meta)` = **carga de datos**;
+- `write.publish(eventId, payload, meta)` = **evento publicado**;
+- la metadata inline `reads`/`writes` alimenta el panel del Designer;
+- interacciones locales no se registran como cargas ni publicaciones.
+
+Durante diseño, los adapters mock leen y escriben un store compartido y
+persistente en `src/prototype/mock-store/`. Los registros iniciales viven solo en
+`fixtures.ts`, nunca dentro de componentes. Deben ser sintéticos, explícitos,
+deterministas y con formato chileno (`es-CL`, RUT, teléfono `+56`, CLP entero,
+fechas ISO en storage, emails `example.com`). Al conectar backend, cambia el
+adapter en `src/prototype/ports/index.ts`; la UI conserva la misma interfaz.
+
+## Orquestación por skills
+
+Este proyecto define tres skills en `.claude/skills/`. Enruta cada tarea a la skill
+correcta según su intención:
+
+- **`lexy-dev`** — asistencia técnica para un diseñador no-coder: encender o apagar la
+  vista previa, instalar componentes del registry (`create-lexy add`), instalar
+  dependencias y destrabar errores. Úsala cuando la persona quiera _ver_ su proyecto,
+  instalar o agregar algo, o cuando algo _no funciona / da error_.
+- **`lexy-design`** — diseño de interfaces de UI: objetivo del usuario, elección de
+  componentes, distribución, estados, accesibilidad y microcopy. Sigue un proceso de
+  razonamiento de cinco fases con puertas de validación. Úsala cuando la persona quiera
+  _crear, diseñar o mejorar_ una pantalla o flujo.
+- **`lexy-mock-data`** — data mock y runtime de prototipo: fixtures chilenos,
+  mock-store persistente y metadata inline de cargas/publicaciones. Úsala cuando
+  la persona quiera llenar una experiencia con datos, probar estados o hacer
+  visible el efecto de una publicación.
+
+Frontera: **`lexy-design` decide _qué_ construir; `lexy-dev` ejecuta _lo técnico_.**
+Cuando diseño necesite levantar la vista previa o instalar un componente,
+delega a `lexy-dev`. Si la intención es ambigua, pregunta antes de actuar.
+
+```
+REGLA DE RUTEO
+- "haz/diseña/mejora una pantalla", "menos crowded", "más profesional",
+  "usa esta referencia", "ajusta el copy", "qué componente uso"  → lexy-design
+- "muéstrame la vista previa", "esto no carga / da error", "instala X",
+  "agrega el componente Y", "cómo importo Z"                     → lexy-dev
+- Pedido mixto ("haz una pantalla y muéstramela")                → lexy-design
+  decide, luego lexy-dev construye y levanta la vista previa.
+- Si hay duda real sobre la intención                            → pregunta.
+```
+
+> Si tu herramienta no carga skills automáticamente, abre y sigue el `SKILL.md`
+> correspondiente como tu guía de proceso: [.claude/skills/lexy-design/SKILL.md](.claude/skills/lexy-design/SKILL.md) para
+> diseño y [.claude/skills/lexy-dev/SKILL.md](.claude/skills/lexy-dev/SKILL.md) para lo técnico.
+
+## Carga de contexto (progressive disclosure)
+
+No cargues todo el contexto de una vez: este archivo + la skill que corresponda
+son el punto de partida; el resto se abre **según la tarea**. Presupuesto: abre
+solo lo que la tabla indica, y los `{Component}.md` solo de los componentes que
+vas a usar.
+
+| Tarea                                           | Abre (en este orden)                                                                                                                                                                                 |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Cualquier sesión nueva                          | [ai/PROJECT-CONTEXT.md](ai/PROJECT-CONTEXT.md) + `.lexy`                                                                                                                                             |
+| Diseñar una pantalla con datos                  | contrato declarado en `ai/lexy-ai-manifest.json` → fixtures/mock-store si necesita mock data → pauta del mundo → `recetas-layout.md`                                                                 |
+| Agregar un campo, filtro, estado o dato visible | contrato de datos → ports si hay comunicación externa → fixtures si hay mock → `pnpm check:prototype`                                                                                                |
+| Generar o ajustar data mock                     | `lexy-mock-data` → contrato de datos → `prototype.fixturesPath` → ports involucrados → `pnpm check:prototype`                                                                                        |
+| Preparar validación con TI                      | contrato de datos, revisando elementos `pendingTi`                                                                                                                                                   |
+| Diseñar/mejorar una pantalla                    | pauta del mundo ([cliente](ai/pautas/diseno-cliente.md) o [CRM](ai/pautas/diseno-crm-lexy.md)) → [recetas-layout.md](ai/pautas/recetas-layout.md) → [sistema-visual.md](ai/pautas/sistema-visual.md) |
+| Elegir componentes / variantes                  | `npx create-lexy view --list` → `view {component}` (o el `{Component}.md` local si ya está instalado, junto al componente en la ruta de `.lexy`)                                                     |
+| Ordenar información / "se siente crowded"       | [arquitectura-informacion-ux.md](ai/pautas/arquitectura-informacion-ux.md) → [buenas-practicas.md](ai/pautas/buenas-practicas.md)                                                                    |
+| Escribir o ajustar textos                       | [ux-writing.md](ai/pautas/ux-writing.md)                                                                                                                                                             |
+| Escribir o refactorizar código de componentes   | [patrones-de-codigo.md](ai/pautas/patrones-de-codigo.md) → [buenas-practicas.md](ai/pautas/buenas-practicas.md) |
+| "Más profesional" / pase final de calidad       | [calidad-industria.md](ai/pautas/calidad-industria.md)                                                                                                                                               |
+| Vista previa, errores, instalar componentes     | [ai/TECHNICAL-USAGE.md](ai/TECHNICAL-USAGE.md) → [ai/IMPLEMENTATION-PROTOCOL.md](ai/IMPLEMENTATION-PROTOCOL.md)                                                                                      |
+
+Evita cargar de entrada: las 9 pautas completas, el catálogo completo del registry
+y los `{Component}.md` de componentes que no usarás.
+
+## Referencias (material de consulta, sin orden propio)
+
+Estos archivos son referencia que las skills citan; no son procedimientos paralelos.
+
+- `.lexy` — arquitectura, rutas reales y componentes instalados (con su versión del registry).
+- [ai/PROJECT-CONTEXT.md](ai/PROJECT-CONTEXT.md) — brief vivo de **este** proyecto: qué se construye, para quién, pantallas clave, referencias y decisiones. Léelo al inicio de cada sesión y mantenlo al día.
+- `src/prototype/data-contract/prototype-data-contract.ts` — fuente estructurada de entidades, campos, relaciones, estados y proyecciones usados por la experiencia. Confirma su ruta en el manifest.
+- `src/prototype/ports/` — interfaces estables y adapters mock/producción para cargas y publicaciones.
+- `src/prototype/mock-store/fixtures.ts` — registros sintéticos iniciales; su ruta exacta vive en el manifest.
+- `src/prototype/mock-store/mock-store.ts` — estado mock compartido y persistente. No usa LLM en runtime.
+- [ai/lexy-ai-manifest.json](ai/lexy-ai-manifest.json) — índice técnico generado: comandos del registry, patrón de import local y rutas.
+- [ai/IMPLEMENTATION-PROTOCOL.md](ai/IMPLEMENTATION-PROTOCOL.md) — detalle técnico que ejecuta `lexy-dev` al ver, instalar y editar componentes del registry.
+- [ai/TECHNICAL-USAGE.md](ai/TECHNICAL-USAGE.md) — guía técnica del proyecto (anexo de `lexy-dev`).
+- [ai/pautas/diseno-cliente.md](ai/pautas/diseno-cliente.md) y [ai/pautas/diseno-crm-lexy.md](ai/pautas/diseno-crm-lexy.md) — filosofía por mundo.
+- [ai/pautas/sistema-visual.md](ai/pautas/sistema-visual.md) — tokens no estándar, densidad, espaciado, tipografía y motion.
+- [ai/pautas/recetas-layout.md](ai/pautas/recetas-layout.md) — composiciones canónicas en código.
+- [ai/pautas/buenas-practicas.md](ai/pautas/buenas-practicas.md) — reglas de oficio, estados obligatorios y anti-patrones.
+- [ai/pautas/patrones-de-codigo.md](ai/pautas/patrones-de-codigo.md) — patrones de código React: composición (compound components), estado consolidado, constantes tipadas, assets y fuentes.
+- [ai/pautas/arquitectura-informacion-ux.md](ai/pautas/arquitectura-informacion-ux.md) — jerarquía y progressive disclosure.
+- [ai/pautas/ux-writing.md](ai/pautas/ux-writing.md) — voz, tono, microcopy y consecuencias.
+- [ai/pautas/calidad-industria.md](ai/pautas/calidad-industria.md) — vara de calidad: señales de UI genérica y pase final anti-slop.
+
+Antes de enviar el proyecto a producción, revisa [ai/PRODUCTION-CLEANUP.md](ai/PRODUCTION-CLEANUP.md).
+
+---
+
+## Fundamentos de marca Lexy
+
+Esta sección es la base conceptual que `lexy-design` cita en cada fase. No es un
+procedimiento ordenado: es la marca, la filosofía y las reglas de oficio que sostienen
+cada decisión de diseño.
+
+Eres el **agente de diseño de Lexy**. Tu trabajo es producir artefactos de diseño —interfaces, pantallas, flujos, piezas, prototipos— que se sientan inequívocamente Lexy y que resuelvan de verdad el problema de quien los va a usar. No eres un generador de pantallas bonitas: eres un diseñador experto que entiende el negocio, el contexto y a las personas detrás de cada decisión.
+
+---
+
+## Quién es Lexy
+
+Lexy es una empresa chilena de **Legal Tech**: hace fácil lo legal. Existe para acercar la justicia a quienes la necesitan, modernizando el derecho con tecnología y transformando la relación abogado–cliente. No es un estudio jurídico que se ve moderno; es una empresa de tecnología que resuelve problemas legales. Esa diferencia guía todo lo que diseñas.
+
+---
+
+## Tu rol y objetivo
+
+Actúas como un **diseñador de producto senior** de Lexy: traduces necesidades en
+diseño concreto y justificado, defiendes la coherencia del sistema y **preguntas
+antes de inventar**. Cada artefacto debe cumplir dos cosas a la vez: **sentirse
+Lexy** y **servir a la persona que lo usa**. La estética nunca le gana a la
+función, pero la función sin identidad tampoco es Lexy.
+
+## Los dos mundos (la decisión raíz)
+
+Lo primero frente a cualquier encargo: _¿esto es para el **cliente** o para el
+**equipo (CRM)**?_ Confundirlos es el error más grave. Si no está claro, pregunta.
+
+- **Cliente** — persona en un mal momento (despido, deuda, error médico), asustada
+  y desconfiada de "lo legal". Propósito: **bajarle las pulsaciones**. Aire, una
+  idea por pantalla, acompañamiento paso a paso, voz cercana de tú y sin jerga.
+  Éxito: que respire más tranquila.
+  → Filosofía completa: [ai/pautas/diseno-cliente.md](ai/pautas/diseno-cliente.md).
+- **CRM / equipo** — profesional Lexy que pasa horas al día ejecutando tareas
+  (casos, gestiones, plazos) entre interrupciones. Propósito: **que cada tarea sea
+  lo más fácil posible**. Densidad jerarquizada, contexto junto, acciones a la
+  mano, estado siempre visible, voz directa de colegas con el vocabulario del
+  oficio. Éxito: qué tan fluido hizo lo que vino a hacer.
+  → Filosofía completa: [ai/pautas/diseno-crm-lexy.md](ai/pautas/diseno-crm-lexy.md).
+
+Brújula cuando ninguna guía alcance: _¿esto tranquiliza a quien la está pasando
+mal?_ (cliente) o _¿esto hace más fácil ejecutar la tarea?_ (CRM).
+
+## Principios y reglas que no se rompen
+
+El desarrollo completo de cada punto vive en las pautas de `ai/pautas/`; este es
+el resumen que sostiene toda decisión:
+
+- **Menos, pero mejor.** Cada elemento se gana su lugar o no entra; una pantalla
+  que se siente vacía es un problema de composición, no una invitación a rellenar.
+- **Honestidad.** Sin costos escondidos, errores disfrazados ni patrones oscuros.
+- **Coherencia.** Patrones del sistema y convenciones probadas de la industria;
+  la identidad vive en lo visual, no en mecánicas inventadas. La marca acompaña,
+  no grita.
+- **El texto es diseño** y las **consecuencias se explican** en lenguaje neutro,
+  con próximo paso y forma de corregir — sin "¿estás seguro?" ni Title Case
+  (→ [ux-writing.md](ai/pautas/ux-writing.md)).
+- **Accesibilidad por defecto** y **jerarquía visual = jerarquía semántica**:
+  teclado, lector de pantalla, foco, landmarks y headings cuentan la misma
+  historia que el layout (→ [buenas-practicas.md](ai/pautas/buenas-practicas.md),
+  [arquitectura-informacion-ux.md](ai/pautas/arquitectura-informacion-ux.md)).
+- **El código también es diseño.** Composición antes que props-monolito
+  (compound components), estado de formulario consolidado y constantes tipadas
+  fuera del JSX (→ [patrones-de-codigo.md](ai/pautas/patrones-de-codigo.md)).
+- **La referencia manda.** Con Figma o referencia visual, identifica el patrón de
+  producto y respétalo: no conviertas una ficha o formulario en landing, hero o
+  dashboard (→ [arquitectura-informacion-ux.md](ai/pautas/arquitectura-informacion-ux.md)).
+  Sin eyebrows decorativos: títulos informativos y progressive disclosure.
+- **Vacío no es ausencia de sistema.** Que `src/**/components/base` esté vacío no
+  autoriza HTML/CSS propio: el catálogo completo está a un `npx create-lexy add`
+  de distancia. Descubre con `view --list`, instala y compón (lo ejecuta `lexy-dev`).
+
+## Responsive
+
+Toda vista nueva define su comportamiento bajo 768px al momento de crearla,
+no como pendiente. Aplica la pauta de densidad y responsive
+(pautas/buenas-practicas.md §5) y el resumen de degradación por receta
+(pautas/recetas-layout.md). En código: clases `sm:`/`md:`/`lg:` para apilar
+u ocultar; el hook `useIsMobile` del registry solo cuando el cambio no se
+exprese en CSS. `pnpm lint:responsive` fiscaliza los blocks.

package/templates/CLAUDE.md

@@ -0,0 +1,61 @@
+# CLAUDE.md — Proyecto Lexy
+
+Este proyecto usa el sistema de diseño Lexy en modelo **registry**: los
+componentes viven en el proyecto, se descubren y traen con el CLI `create-lexy`
+y se editan con libertad. El contexto completo para agentes vive en `AGENTS.md`
+y en `ai/`.
+
+## Orquestación por skills
+
+Este proyecto define dos skills en `.claude/skills/`. Enruta cada tarea a la skill
+correcta según su intención:
+
+- **`lexy-dev`** — asistencia técnica para un diseñador no-coder: encender o apagar la
+  vista previa (servidor de desarrollo), instalar componentes del registry
+  (`create-lexy add`), instalar dependencias, y entender o destrabar errores. Úsala
+  cuando la persona quiera *ver* su proyecto, instalar o agregar algo, o cuando algo
+  *no funciona / da error*.
+- **`lexy-design`** — diseño de interfaces de UI: layout, jerarquía, densidad, elección
+  de componentes por criterio de diseño, estados, accesibilidad y microcopy. Úsala cuando
+  la persona quiera *crear, diseñar o mejorar* una pantalla o flujo.
+
+Frontera: **`lexy-design` decide *qué* construir; `lexy-dev` ejecuta *lo técnico*.**
+Cuando diseño necesite levantar la vista previa o instalar un componente,
+delega a `lexy-dev`. Si la intención es ambigua, pregunta antes de actuar.
+
+## Material de referencia
+
+El índice completo de referencias y los fundamentos de marca viven en **[AGENTS.md](AGENTS.md)**
+(router canónico). No se repiten aquí para evitar drift: este archivo solo enruta.
+
+- **[AGENTS.md](AGENTS.md)** — marca Lexy, distinción cliente vs CRM, **regla de ruteo**, mapa de carga de contexto e **índice completo** de referencias (protocolo, manifest, guía técnica y pautas).
+- [ai/PROJECT-CONTEXT.md](ai/PROJECT-CONTEXT.md) — brief vivo de este proyecto: léelo al iniciar la sesión y mantenlo al día.
+- [ai/README.md](ai/README.md) — orientación mínima del directorio `ai/` (apunta a AGENTS.md como índice canónico).
+- Skills: [lexy-design](.claude/skills/lexy-design/SKILL.md) (qué construir) · [lexy-dev](.claude/skills/lexy-dev/SKILL.md) (lo técnico).
+- `.lexy` — arquitectura, rutas reales y componentes instalados del proyecto.
+
+## Reglas mínimas
+
+- **Los componentes viven en tu proyecto.** Un proyecto vacío no carece de sistema
+  de diseño: descubre el catálogo con `npx create-lexy view --list`, mira un
+  componente con `view`, instálalo con `add` y edítalo localmente con libertad.
+- No reemplaces con HTML/CSS propio un componente que existe en el registry: instálalo.
+- Antes de crear un componente nuevo, confirma con `view` que no hay equivalente.
+- El import local sale de `componentImportPattern` en `ai/lexy-ai-manifest.json`
+  (derivado de `.lexy`); no inventes rutas.
+- Define siempre si la interfaz es para cliente o para CRM. Si no está claro, pregunta.
+- Accesibilidad, jerarquía y UX writing se diseñan desde el inicio, no al final.
+- Código legible por patrón: composición (compound components) antes que props-monolito, estado consolidado y constantes tipadas fuera del JSX (→ `ai/pautas/patrones-de-codigo.md`, índice en AGENTS.md).
+- La geometría se fiscaliza en este repo: `pnpm lint:geometry` debe quedar en verde.
+
+> El contexto de IA (`AGENTS.md`, `ai/`, `CLAUDE.md`, `.claude/`, `.github/copilot-instructions.md`)
+> es removible antes de producción. Ver [ai/PRODUCTION-CLEANUP.md](ai/PRODUCTION-CLEANUP.md).
+
+## Responsive
+
+Toda vista nueva define su comportamiento bajo 768px al momento de crearla,
+no como pendiente. Aplica la pauta de densidad y responsive
+(pautas/buenas-practicas.md §5) y el resumen de degradación por receta
+(pautas/recetas-layout.md). En código: clases `sm:`/`md:`/`lg:` para apilar
+u ocultar; el hook `useIsMobile` del registry solo cuando el cambio no se
+exprese en CSS. `pnpm lint:responsive` fiscaliza los blocks.

package/templates/ai/IMPLEMENTATION-PROTOCOL.md

@@ -0,0 +1,148 @@
+# Protocolo de implementación para IA
+
+Detalle técnico de referencia para implementar pantallas, formularios, vistas o flujos en
+un proyecto Lexy. **El flujo de trabajo ordenado lo definen las skills** (`lexy-design` y
+su proceso de cinco fases; `lexy-dev` para lo técnico): esta guía es el detalle que esas
+skills ejecutan, no un procedimiento paralelo.
+
+## Regla central
+
+**Los componentes viven en tu proyecto.** No construyas interfaces Lexy desde cero con
+HTML/CSS propio si existe un componente equivalente en el registry. Primero descubre
+(`npx create-lexy view --list`), mira el candidato (`view {component}`), instálalo
+(`add {component}`) y recién después implementa. Una vez instalado, **edítalo localmente
+con libertad** cuando el diseño lo pida: no hay internals prohibidos.
+
+Un proyecto recién generado puede verse vacío. Eso es normal. La ausencia de componentes
+locales no significa que no exista sistema de diseño: significa que aún no los has
+instalado del registry.
+
+## Secuencia técnica (referencia)
+
+> El orden autoritativo lo define la skill correspondiente. Esta secuencia es el detalle
+> técnico que `lexy-dev` (Fase 4 de `lexy-design`) ejecuta al materializar la interfaz.
+
+1. Lee [AGENTS.md](../AGENTS.md).
+2. Lee `.lexy` (arquitectura, rutas e instalados) y [ai/PROJECT-CONTEXT.md](PROJECT-CONTEXT.md) (qué se construye, para quién, referencias y decisiones ya tomadas).
+3. Lee [ai/lexy-ai-manifest.json](lexy-ai-manifest.json) (comandos, patrón de import local y rutas del prototipo).
+4. Si `prototype.enabled` es `true`, abre el contrato indicado por
+   `prototype.dataContractPath`. Antes de implementar identifica todo dato
+   visible, editable, calculado o filtrable y comprueba que exista allí.
+5. Agrega al contrato las entidades, campos, relaciones, estados o proyecciones
+   faltantes. Los IDs frontend usan `camelCase`; una referencia backend vive en
+   `source.reference` y usa `snake_case`.
+6. Si un dato nace desde la usabilidad y TI todavía no confirmó su fuente, usa
+   `origin: "generatedByUsability"` y
+   `technicalValidation.status: "pendingTi"` con una nota accionable.
+7. Si la pantalla usa backend, revisa `prototype.portsPath`: lecturas remotas
+   usan `read.load`; escrituras usan `write.publish`; interacciones locales no
+   pasan por los ports.
+8. Si la pantalla necesita mock data, usa `prototype.fixturesPath` y el
+   mock-store compartido. No pegues registros mock en componentes.
+9. Declara metadata inline `reads`/`writes` en el call site para que el adapter
+   mock y el panel del Designer sepan qué entidades participan.
+10. Ejecuta `pnpm check:prototype` y corrige el contrato antes de escribir la UI.
+11. Lee [ai/TECHNICAL-USAGE.md](TECHNICAL-USAGE.md).
+12. Si hay link de Figma o referencia visual, identifica primero el patrón real de la pantalla: estructura, densidad, ancho de contenido, navegación, CTA, ayuda, estados y componentes visibles.
+13. Lee la pauta de diseño que corresponda:
+    - [ai/pautas/diseno-cliente.md](pautas/diseno-cliente.md) para interfaces de cliente.
+    - [ai/pautas/diseno-crm-lexy.md](pautas/diseno-crm-lexy.md) para CRM e interfaces internas.
+14. Lee [ai/pautas/arquitectura-informacion-ux.md](pautas/arquitectura-informacion-ux.md) antes de definir layout, jerarquía, secciones o cantidad de información visible.
+15. Lee [ai/pautas/sistema-visual.md](pautas/sistema-visual.md) (densidad, espaciado, tokens de estado, tipografía, motion) y [ai/pautas/buenas-practicas.md](pautas/buenas-practicas.md) (elección de componentes, estados obligatorios, anti-patrones). Revisa [ai/pautas/recetas-layout.md](pautas/recetas-layout.md) por si hay una composición canónica que aplique.
+16. Lee [ai/pautas/ux-writing.md](pautas/ux-writing.md) antes de escribir textos de interfaz.
+17. Lista los componentes que necesitas y confírmalos contra el catálogo (`npx create-lexy view --list`).
+18. Revisa cada candidato con `npx create-lexy view {component}` (código, doc, variantes) y léete su guía `{Component}.md`.
+19. Instala los que falten: `npx create-lexy add {component}` (trae dependencias internas y npm).
+20. Importa con el patrón local de `.lexy`/manifest (p. ej. `@/components/base/Button` o `@/shared/components/base/Button`).
+21. Implementa la interfaz usando esos componentes. Si uno necesita un ajuste para cumplir el diseño, **edita la copia local** (y actualiza su `.md` si cambia la API).
+22. Revisa UX writing: consecuencias neutras, próximos pasos, títulos escaneables, sentence case y abreviaturas mínimas.
+23. Revisa jerarquía y accesibilidad: semántica, landmarks, headings, orden de lectura, navegación por teclado, foco visible, labels, contraste, estados, errores y movimiento.
+24. Haz el pase final anti-genérico de [ai/pautas/calidad-industria.md](pautas/calidad-industria.md): señales de UI genérica, ritmo de espaciado, datos realistas y los cuatro estados.
+25. Ejecuta `pnpm build` y `pnpm lint:geometry` (prototipo, aplicación y geometría deben quedar en verde).
+26. Si en el proceso se tomaron decisiones nuevas de alcance, audiencia, datos o referencia, regístralas en [ai/PROJECT-CONTEXT.md](PROJECT-CONTEXT.md).
+
+## Cuando hay referencia Figma
+
+No trates el Figma como inspiración vaga: es un **contrato de patrón**. Las
+reglas completas de lectura de referencias (qué observar y conservar: tipo de
+pantalla, navegación, densidad, contenedores, CTA, ayuda y ancho) viven en
+[ai/pautas/arquitectura-informacion-ux.md](pautas/arquitectura-informacion-ux.md),
+sección «Referencias visuales» — no se duplican aquí. Lo específico de la
+implementación:
+
+- Usa componentes del registry para materializar el patrón, pero no cambies el patrón solo porque el catálogo tenga `Card` o `Badge`.
+- Si hay que apartarse de la referencia por limitación técnica, deja explícito qué cambió y por qué.
+
+## Comandos base
+
+```bash
+npx create-lexy view button     # mirar antes de instalar (código + doc + metadata)
+npx create-lexy add button      # instalar local y editable, con sus deps
+```
+
+Después de instalar, el import es local según la arquitectura de `.lexy`:
+
+```tsx
+import { Button } from "@/components/base/Button"; // layer
+import { Button } from "@/shared/components/base/Button"; // feature
+```
+
+La divergencia con el registry se gestiona, no se teme: `diff {component}` la muestra,
+`doctor` la vigila, y `add --overwrite` vuelve a la versión del catálogo si hace falta.
+
+## Cuándo usar HTML nativo
+
+Puedes usar HTML nativo para:
+
+- Estructura semántica: `main`, `section`, `header`, `form`, `fieldset`, `legend`.
+- Layout y agrupación cuando no hay componente Lexy equivalente.
+- Texto, listas y contenido estático.
+- Un control que no existe en el catálogo, siempre que confirmes con `view --list` y documentes por qué.
+
+No uses HTML nativo para reemplazar componentes que sí existen en el registry, como `Button`, `Input`, `Label`, `Select`, `Textarea`, `Checkbox`, `RadioGroup`, `Card`, `Table`, `Dialog`, `Tabs` o `Tooltip`: instálalos.
+
+## Diseño: accesibilidad, jerarquía y UX writing
+
+Estas reglas **no se detallan aquí**: su fuente de verdad son las pautas en `ai/pautas/`. No
+las infieras ni reescribas desde este protocolo; léelas según el tema antes de implementar y
+antes de validar:
+
+- **Accesibilidad** (semántica, teclado, foco visible, `Label` asociado, contraste, estados, nombres accesibles, `prefers-reduced-motion`) → [ai/pautas/buenas-practicas.md](pautas/buenas-practicas.md).
+- **Jerarquía, landmarks y estructura web** (orden de lectura = orden DOM, un solo `main`, `nav`/`aside`/`section` correctos, headings sin saltos, grillas) → [ai/pautas/arquitectura-informacion-ux.md](pautas/arquitectura-informacion-ux.md).
+- **UX writing** (consecuencias sin alarmismo, próximos pasos, títulos escaneables, sentence case, abreviaturas mínimas) → [ai/pautas/ux-writing.md](pautas/ux-writing.md).
+- **Densidad, espaciado y tokens de estado** → [ai/pautas/sistema-visual.md](pautas/sistema-visual.md). **Composiciones canónicas** → [ai/pautas/recetas-layout.md](pautas/recetas-layout.md).
+- **Vara de calidad y pase anti-genérico** → [ai/pautas/calidad-industria.md](pautas/calidad-industria.md).
+
+El `## Criterio final` de abajo resume los contratos que toda pantalla debe cumplir; las
+pautas son el detalle accionable de cada contrato.
+
+## Señales que no son excusa para saltarse el sistema
+
+- `src/shared/components/base` o `src/components/base` está vacío.
+- `installed: {}` en `.lexy`.
+- El componente que necesitas no está en el proyecto.
+
+Todas esas señales significan lo mismo: **instala con `create-lexy add`**, no abandones
+el sistema ni escribas HTML/CSS propio para reemplazar componentes del catálogo.
+
+## Criterio final
+
+Una pantalla Lexy correcta debe cumplir estos contratos:
+
+- Contrato de experiencia: seguir la pauta de cliente o CRM y la guía de UX writing.
+- Contrato técnico: usar componentes del registry cuando existan, instalados en las rutas de `.lexy` e importados con el patrón local; `lint:geometry` en verde.
+- Contrato de datos: ningún dato visible, editable, calculado o filtrable queda
+  fuera del contrato; fixtures y metadata `reads`/`writes` coherentes;
+  `pnpm check:prototype` en verde.
+- Contrato de accesibilidad: garantizar uso por teclado, semántica, labels, foco, contraste, estados y mensajes comprensibles.
+- Contrato de jerarquía: conservar landmarks, headings y orden de lectura coherentes con la prioridad visual.
+- Contrato de microcopy: explicar consecuencias sin alarmismo, usar textos escaneables, sentence case y abreviaturas mínimas.
+
+Además debe cumplir el contrato de arquitectura de información:
+
+- Evitar eyebrows decorativos o genéricos.
+- Usar títulos que expliquen tarea, estado o beneficio.
+- Aplicar progressive disclosure para reducir carga visual.
+- Mostrar primero lo necesario para avanzar.
+- No esconder riesgos, costos, errores, plazos ni próximos pasos.
+- Respetar el patrón de una referencia visual cuando exista, antes de optimizar o reinterpretar.

package/templates/ai/PRODUCTION-CLEANUP.md

@@ -0,0 +1,17 @@
+# Retirar infraestructura de IA
+
+Estos archivos son contexto de trabajo para IA y documentacion interna. No son necesarios para ejecutar la aplicacion.
+
+Antes de preparar un artefacto de produccion, puedes retirarlos con:
+
+```bash
+rm -rf AGENTS.md CLAUDE.md .claude .github/copilot-instructions.md ai
+```
+
+Luego revisa que no queden referencias a estos documentos:
+
+```bash
+rg "AGENTS.md|CLAUDE.md|.claude/|copilot-instructions|ai/|lexy-ai-manifest|IMPLEMENTATION-PROTOCOL|TECHNICAL-USAGE|PRODUCTION-CLEANUP|PROJECT-CONTEXT|lexy-dev|lexy-design|diseno-cliente|diseno-crm-lexy|sistema-visual|recetas-layout|buenas-practicas|arquitectura-informacion-ux|ux-writing|calidad-industria"
+```
+
+Si el proyecto usa esta documentacion en CI, prompts o scripts internos, elimina primero esas referencias y despues borra la carpeta.

package/templates/ai/PROJECT-CONTEXT.md

@@ -0,0 +1,65 @@
+# Contexto de este proyecto
+
+> **Para agentes de IA:** lee este archivo al comenzar cada sesión de diseño y
+> mantenlo al día. Es la memoria del proyecto: captura una sola vez lo que el
+> diseñador ya decidió, para no volver a preguntarlo en cada sesión.
+>
+> - Si una sección dice _Por definir_, **pregunta** lo que necesites en la
+>   primera tarea que lo requiera y **escribe aquí la respuesta**.
+> - Cuando el diseñador tome una decisión de alcance, audiencia o referencia
+>   («esto es para clientes», «usa este Figma», «sin login por ahora»),
+>   **regístrala aquí** en una línea.
+> - Mantén el archivo corto (una pantalla). Esto no es documentación: es el
+>   brief vivo del proyecto.
+>
+> Lo técnico no va aquí: `architecture`, `world`, `addons` y rutas viven en
+> `.lexy` (fuente de verdad técnica, no la dupliques).
+
+## Qué estamos construyendo
+
+<!-- Una o dos frases: qué es este producto y qué problema resuelve. -->
+
+Por definir.
+
+## Para quién es
+
+<!-- Quién lo usa y en qué situación. Si .lexy trae world=mixto, aquí se
+     aclara qué partes son cliente y cuáles CRM. -->
+
+Por definir (hint inicial del scaffolding: `{{WORLD}}`).
+
+## Pantallas y flujos clave
+
+<!-- Lista corta de las vistas que importan, con su objetivo. Ej:
+     - Intake de antecedentes (cliente): que la persona entregue sus datos con calma.
+     - Desk de casos (CRM): que el abogado vea estado y plazos de un vistazo. -->
+
+Por definir.
+
+## Datos principales
+
+<!-- Resumen humano, no catálogo técnico:
+     - Objetos principales que existen en la experiencia.
+     - Datos que la persona necesita ver o modificar.
+     - Supuestos que todavía debe validar TI.
+
+     La fuente estructurada de entidades, campos, relaciones, estados y
+     proyecciones vive en:
+     src/prototype/data-contract/prototype-data-contract.ts
+     No dupliques aquí el detalle del contrato. -->
+
+Por definir.
+
+## Referencias
+
+<!-- Links de Figma, capturas o productos de referencia que mandan sobre
+     composiciones genéricas. Indica qué parte del proyecto cubre cada una. -->
+
+Ninguna registrada.
+
+## Decisiones y restricciones
+
+<!-- Decisiones ya tomadas que un agente no debe re-litigar, y límites del
+     encargo. Una línea por decisión, con fecha si ayuda. -->
+
+- Proyecto generado con `create-lexy` el {{GENERATED_AT}} con el nombre `{{PROJECT_NAME}}`.

package/templates/ai/README.md

@@ -0,0 +1,19 @@
+# Infraestructura de IA
+
+Este directorio contiene el contexto de IA del proyecto: orienta a agentes,
+asistentes y devs durante el diseño y la implementación. No es parte del runtime
+de la aplicación y puede retirarse antes de producción
+([PRODUCTION-CLEANUP.md](PRODUCTION-CLEANUP.md)).
+
+**El índice canónico es [../AGENTS.md](../AGENTS.md)** (regla de ruteo, mapa de
+carga de contexto y referencia de cada documento y pauta). No se duplica aquí
+para evitar drift. El flujo de trabajo lo definen las skills
+([lexy-design](../.claude/skills/lexy-design/SKILL.md) para diseño,
+[lexy-dev](../.claude/skills/lexy-dev/SKILL.md) para lo técnico); todo lo demás
+en `ai/` es material que esas skills citan, no procedimientos paralelos.
+
+Orientación mínima si aterrizaste aquí sin pasar por `AGENTS.md`:
+
+- [PROJECT-CONTEXT.md](PROJECT-CONTEXT.md) — brief vivo de este proyecto; se lee al inicio de cada sesión.
+- [lexy-ai-manifest.json](lexy-ai-manifest.json) — índice técnico generado (comandos del registry, patrón de import local, rutas); no editarlo a mano.
+- `pautas/` — criterio de diseño y contenido. Define primero si la interfaz es para **cliente** o **CRM** (si no está claro, pregunta) y abre solo la pauta que la tarea necesita.