# INICIO-AQUI.md — Punto de entrada para nuevos desarrollos frontend
## La guía única que consolida todo el stack cognitivo y técnico de frontend-ai

**Para:** cualquier desarrollador de frontend o agente autónomo que empiece a trabajar en este proyecto  
**Tiempo estimado de lectura:** 10 minutos  
**Tiempo estimado antes de escribir código:** completar el §PASO 1

---

## Mapa del proyecto

```
ibanking-ai-api/
│
├── AGENT.md                   ← SE CARGA AUTOMÁTICAMENTE en cada sesión de IA
│                                (system prompt de frontend — NO EDITAR sin consenso)
│
├── INICIO-AQUI.md             ← ESTE ARCHIVO — leerlo primero
│
├── docker-compose.yml         ← NUEVO: Servidor WireMock local para APIs downstream
├── setup.sh                   ← NUEVO: Script de inicialización para Linux/Mac
├── setup.ps1                  ← NUEVO: Script de inicialización para Windows
├── .env.local.template        ← NUEVO: Plantilla de variables de entorno locales
│
├── mocks/                     ← NUEVO: Mappings JSON de WireMock para simulación local
│   └── mappings/
│       ├── auth-me.json
│       ├── cuentas.json
│       └── transferencias.json
│
├── standards/                 ← Referencia operacional durante la implementación
│   ├── README.md
│   ├── 01-log-tracing.md      ← Server & client logging, enrutador POST /api/logs
│   ├── 02-security-tracing.md ← Middleware de sesión, cookies HTTP-only, cifrado Kong
│   ├── 03-headers-contract.md ← Propagación de traceId (sessionReference) y cookies JWT
│   ├── 04-configmap-management.md ← Gestión de .env.local, NEXT_PUBLIC_ y server private keys
│   └── 05-client-insumos.md   ← ⭐ COMPLETAR CON EL DISEÑADOR/CLIENTE antes de empezar
│
├── docs/                      ← Guías de referencia y visión del proyecto
│   ├── guia-4-implemented-pattern.md  ← Los patrones clave de Next.js App Router y Zustand
│   ├── guia-4.5-skills-proposal.md    ← Skills instalables y directrices del agente
│   ├── guia-prompting-v4.md           ← Plantilla del prompt para generar UI robusta y segura
│   └── guia-v5-advanced-ai-architecture.md ← Integración avanzada con Engram Cloud + Graphify
│
├── .agents/                   ← Skills congeladas comunitarias para excelencia operativa
│   ├── README.md
│   └── skills/
│       ├── test-driven-development/SKILL.md
│       ├── systematic-debugging/SKILL.md
│       ├── code-review-excellence/SKILL.md
│       ├── documentation-writer/SKILL.md
│       └── security-best-practices/SKILL.md
```

---

## PASO 1 — Antes de abrir el editor (obligatorio)

### 1.1 Ejecutar el script de Setup Automatizado (Onboarding)
Ejecuta el script correspondiente a tu sistema operativo en la raíz del proyecto para inicializar el entorno, instalar dependencias de IA (Graphify, Engram) y crear tu archivo de configuración `.env.local` automáticamente:

```bash
# Para desarrolladores en macOS / Linux:
chmod +x setup.sh && ./setup.sh

# Para desarrolladores en Windows (PowerShell):
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process; .\setup.ps1
```

### 1.2 Levantar el Entorno de Mocks (Docker)
Para interactuar localmente con datos simulados y no quedar bloqueado por caídas de red o fallos en el backend:
```bash
docker-compose up -d
```
Esto levantará el servidor **WireMock** en `http://localhost:8080` simulando de forma automática las respuestas del backend (Auth, Cuentas, y Transferencias).

### 1.3 Completar los insumos de pantalla y flujos
Abrir `standards/05-client-insumos.md` y completar las secciones de la interfaz de usuario con el cliente o equipo de producto:

* §1 Contrato de APIs e Integraciones (endpoints del backend Spring Boot)
* §2 Estructura y Comportamiento de la UI (Mockups, layouts y estados visuales)
* §3 Gestión de Estado en Cliente (variables a registrar en Zustand)
* §4 Niveles de Autenticación y Seguridad (páginas protegidas por middleware)
* §5 Trazabilidad y Eventos Críticos (qué logs registrar)

### 1.4 Verificar presencia de Skills locales
Los skills comunitarios están congelados y listos en `.agents/skills/`:
* `test-driven-development/SKILL.md` (tdd estricto en frontend con Vitest/Testing Library)
* `systematic-debugging/SKILL.md` (diagnóstico paso a paso de estado e hidratación React)
* `code-review-excellence/SKILL.md` (checklist de accesibilidad, seguridad y rendimiento)
* `documentation-writer/SKILL.md` (documentación de Props y flujo de Zustand)
* `security-best-practices/SKILL.md` (sanitización, cookies y seguridad Kong en client)

### 1.5 Generar y actualizar el Knowledge Graph con Graphify
Para optimizar las búsquedas de código y componentes del agente:
```bash
# Registrar mcpServer local de Graphify (según se detalla en README.md)
# Actualizar el grafo tras cambios estructurales:
graphify update .
```

---

## PASO 2 — El prompt de implementación de componentes

Plantilla de prompt rápido para inyectar al agente:
```
Implementa una pantalla/componente en Next.js siguiendo AGENT.md y docs/guia-4-implemented-pattern.md.

Reglas del Frontend Seguro:
- NO uses cookies ni secrets en el código del cliente.
- Utiliza Server Components por defecto. Usa 'use client' solo si hay interactividad.
- Centraliza estados globales en el store de Zustand en lib/auth/client/useAuthStore.ts.
- Registra logs críticos llamando al logger del cliente (client-logger) o servidor.

### Contexto de la Pantalla:
- Nombre: [ej. Dashboard / Perfil / Historial]
- Ruta: [ej. /dashboard o /api/user]
- Componentes UI requeridos: [ej. daisyUI tables, custom buttons]

### Insumos de la UI:
[pegar especificación de standards/05-client-insumos.md]
```

---

## PASO 3 — Control de versiones y convencionalismo de commits

```bash
# Crear rama
git checkout -b feat/pantalla-<nombre-flujo>-agented

# Commit estructurado (Conventional Commit sin atribución AI)
git commit -m "feat(ui): [FRONTEND-SECURE] implementar pantalla de <nombre-flujo>

Pattern: Server-First, Zustand State
Skills: security-best-practices, code-review-excellence
Standards: standards/05-client-insumos.md completado"
```

---

## PASO 4 — Checklist pre-PR (ejecutar desde el agente)

```
Haz una revisión completa con code-review-excellence
comparando la implementación contra el checklist de AGENT.md.
Reporta cualquier violación antes de continuar.
```

---

## Referencia rápida — Los 5 pilares del Frontend Banesco

| # | Pilar | Solución Clave |
|---|---|---|
| 1 | **Server-First** | Server Components por defecto para fetching seguro y veloz |
| 2 | **Cookies Protegidas** | Cookies HTTP-only administradas server-side para JWT |
| 3 | **Gobernanza de Estado** | Stores Zustand puros y reactivos sin excesivos Contexts |
| 4 | **Logs Enrutados** | Centralización de logs del cliente mediante `/api/logs` a `logs/app.log` |
| 5 | **Cifrado Perimetral** | Encriptación Kong en datos confidenciales que viajan al cliente |

---

## ¿Cuándo consultar cada guía?

| Situación | Dónde ir |
|---|---|
| Primera vez en el proyecto | **Este archivo** |
| Definir campos de UI e integraciones | `standards/05-client-insumos.md` |
| Implementar logs en el cliente o servidor | `standards/01-log-tracing.md` |
| Autenticar rutas o encriptar datos | `standards/02-security-tracing.md` |
| Revisar el flujo de cookies y traceId | `standards/03-headers-contract.md` |
| Configurar archivos .env o variables públicas | `standards/04-configmap-management.md` |
| Entender patrones de Server/Client Components | `docs/guia-4-implemented-pattern.md` |
| Ver la propuesta de Skills y tooling | `docs/guia-4.5-skills-proposal.md` |
| Plantilla de prompt interactivo de UI | `docs/guia-prompting-v4.md` |
| Activar Engram Cloud y Graphify | `docs/guia-v5-advanced-ai-architecture.md` |