@ronaldjdevfs/forge 1.0.2 → 1.1.0

package/README.md

@@ -46,7 +46,7 @@ Los proyectos backend degeneran en código acoplado porque la infraestructura t
 Detecta el stack tecnológico, ejecuta bootstrap de platform/shared/infra si no existen, determina el perfil activo, analiza ownership y prepara el proyecto. Crea `ARCHITECTURE.md` si no existe.
 
 ```
-Boot sequence: context → bootstrap → profile → armorer → graph → chain → inscribe
+Boot sequence: context → armorer → profile → graph → chain → inspect → architecture → execute → architecture
 ```
 
 ### `cast` — Crear feature
@@ -143,6 +143,99 @@ src/shared/
 └── utils/       # <util>.ts (formatDate, pagination)
 ```
 
+### `assay` — Ensayo multi-persona
+
+Evalúa la arquitectura desde 5 perspectivas distintas:
+
+| Persona | Enfoque |
+|---------|---------|
+| **Jeff Bezos** | Acoplamiento, escalabilidad, equipos autónomos (API mandate) |
+| **Martin Fowler** | Refactoring, deuda técnica, microservicios vs monolitos |
+| **Hacker** | Seguridad, performance, edge cases, vulnerabilidades |
+| **Alex (PM)** | Tiempo de entrega, complejidad, ROI técnico |
+| **Dra. Carter** | Dependencias cíclicas, violaciones de capas, salud estructural |
+
+```
+forge assay                    # Ensayo completo (5 personas)
+forge assay --persona=bezos    # Solo Bezos
+forge assay --persona=fowler   # Solo Fowler
+forge assay --save             # Persiste en .forge/assay/
+forge assay --json             # Salida JSON
+```
+
+### `nail / unnail` — Shortcuts de navegación
+
+Fija rutas del proyecto como atajos para acceso rápido:
+
+```
+nail src/features/auth        # Crea atajo "auth"
+nail src/platform/config      # Crea atajo "config"
+nail --list                   # Lista atajos
+unnail auth                   # Elimina atajo
+```
+
+### `forge state` — Estado persistente
+
+Muestra y guarda el estado post-auditoría:
+
+```
+forge state          # Último score, grade, violaciones
+forge state --show   # Estado detallado
+forge state --json   # Salida JSON
+forge state --history # Histórico de auditorías
+```
+
+### `forge hook` — Git pre-commit hook
+
+Instala un hook pre-commit que valida la arquitectura en cada commit:
+
+```
+forge hook install      # Instalar hook
+forge hook status       # Ver estado
+forge hook check        # Validar archivos staged
+forge hook uninstall    # Eliminar hook
+```
+
+### `forge rollback` — Restauración
+
+Restaura el proyecto a un punto anterior:
+
+```
+forge rollback                   # Último checkpoint
+forge rollback --list            # Lista checkpoints
+forge rollback --id <checkpoint> # Restaurar específico
+```
+
+### `forge update` — Actualización
+
+Verifica si hay una nueva versión de Forge disponible.
+
+### Inline Ignores
+
+Forge soporta excepciones línea por línea para reglas arquitectónicas:
+
+```ts
+// forge-ignore-next-line
+import { something } from "../infra/prisma";  // ← no se reporta
+
+// forge-ignore: R1
+import { PrismaClient } from "../../infra/prisma/client"; // ← solo R1 ignorada
+
+// forge-ignore: R1, R8
+import { crossFeature } from "../other-feature/domain/Entity"; // ← R1 y R8 ignoradas
+```
+
+Usar `quench --show-ignores` para listar todos los ignores en el código.
+
+### Flags adicionales
+
+| Flag | Comando | Descripción |
+|------|---------|-------------|
+| `--fix` | `quench` | Auto-corrige violaciones WARNING/INFO (missing @injectable(), tsconfig, naming, container.resolve) |
+| `--show-ignores` | `quench` | Muestra los inline ignores encontrados en el código |
+| `--persona=<id>` | `assay` | Filtra ensayo por una persona (bezos, fowler, hacker, pm, senior) |
+| `--save` | `assay` | Persiste ensayo en `.forge/assay/` |
+
 ---
 
 ## Modelo arquitectónico
@@ -224,7 +317,12 @@ Ver `reference/patterns.md` para el detalle completo.
 | `express-mongodb` | Express | MongoDB | Mongoose | tsyringe |
 | `express-postgres` | Express | PostgreSQL | raw pg | Manual |
 | `express-prisma` | Express | PostgreSQL | Prisma | tsyringe |
+| `express-drizzle` | Express | PostgreSQL | Drizzle | tsyringe |
+| `fastify-mongodb` | Fastify | MongoDB | Mongoose | Manual |
 | `fastify-postgres` | Fastify | PostgreSQL | Prisma | Manual |
+| `fastify-prisma` | Fastify | PostgreSQL | Prisma | Manual |
+| `nestjs-mongodb` | NestJS | MongoDB | Mongoose | NestJS DI |
+| `nestjs-postgres` | NestJS | PostgreSQL | Prisma | NestJS DI |
 | `nestjs-prisma` | NestJS | PostgreSQL | Prisma | NestJS DI |
 
 Cada perfil define estructura de directorios, setup de DI, routing, persistencia, testing y naming conventions.
@@ -251,17 +349,33 @@ Donde vive toda la inteligencia arquitectónica:
 | `scripts/profile.mjs` | Matchea stack contra perfiles conocidos o sintetiza uno genérico |
 | `scripts/graph.mjs` | Grafo completo: 6 tipos de nodo, 4 capas, 9 reglas (R1-R9), risk score, dependency health |
 | `scripts/chain.mjs` | Grafo multi-capa (platform, features, shared, infra) con orden topológico |
-| `scripts/detect.mjs` | 6 categorías de chequeo arquitectónico (110 pts) |
+| `scripts/detect.mjs` | Validación de reglas R1-R9 con inline ignores y `--fix` |
 | `scripts/inspect.mjs` | Orquesta auditoría completa con reporte coloreado |
 | `scripts/architecture.mjs` | Genera/actualiza `ARCHITECTURE.md` vivo |
 | `scripts/bootstrap.mjs` | Inicializa platform/shared/infra según perfil (interno) |
+| `scripts/formatter.mjs` | Output unificado: colores, JSON, scoreBar, formatCheck |
+| `scripts/registry/rules.mjs` | Registry de reglas R1-R9 + custom rules desacoplado |
+| `scripts/assay.mjs` | Ensayo multi-persona (Bezos, Fowler, Hacker, PM, Arquitecta) |
+| `scripts/posttool.mjs` | PostToolUse hook con `--reminder` y `--strict` |
+| `scripts/forge-config.mjs` | Persistencia de config, estado e histórico |
+| `scripts/forge-state.mjs` | CLI wrapper de estado post-auditoría |
+| `scripts/forge-signals.mjs` | Manejo de señales (SIGINT, SIGTERM) |
+| `scripts/forge-api.mjs` | Validación de contratos API |
+| `scripts/hook.mjs` | Gestión de git pre-commit hook |
+| `scripts/pin.mjs` | Shortcuts de navegación (`nail`/`unnail`) |
+| `scripts/rollback.mjs` | Restauración de puntos de guardado |
+| `scripts/rename.mjs` | Renombrado bulk de componentes |
+| `scripts/parse-imports.mjs` | Parsing de imports ESM |
+| `scripts/update.mjs` | Verificador de actualizaciones |
 | `reference/` | Documentación detallada de cada comando y principios |
 | `reference/patterns.md` | Convenciones de nomenclatura globales |
-| `profiles/` | Convenciones por stack tecnológico |
-| `templates/feature/` | Templates TypeScript para features |
-| `templates/platform/` | Templates para componentes de platform |
-| `templates/shared/` | Templates para shared (errors, contracts, types, utils) |
-| `templates/infra/` | Templates para infra (prisma, mongodb, redis, mail) |
+| `reference/assay.md` | Documentación del comando assay |
+| `reference/hooks.md` | Documentación del sistema de hooks |
+| `profiles/` | 10 perfiles tecnológicos detallados |
+| `templates/feature/` | 11 templates TypeScript para features |
+| `templates/platform/` | 6 templates para componentes de platform |
+| `templates/shared/` | 4 templates para shared (errors, contracts, types, utils) |
+| `templates/infra/` | 4 templates para infra (prisma, mongodb, redis, mail) |
 
 ---
 
@@ -297,7 +411,7 @@ forge install -g   # global
 
 ## Uso
 
-Una vez instalada, OpenCode carga automáticamente la skill `forge` al trabajar en el proyecto. Los comandos se invocan por lenguaje natural:
+Una vez instalada, OpenCode carga automáticamente la skill `forge` al trabajar en el proyecto. Usa `forge --help` para ver la lista completa de comandos. Los comandos también se invocan por lenguaje natural:
 
 | Lenguaje natural | Comando |
 |---|---|
@@ -311,6 +425,14 @@ Una vez instalada, OpenCode carga automáticamente la skill `forge` al trabajar
 | "cadena", "grafo", "acoplamiento" | `chain` |
 | "inscribir", "grabar", "ARCHITECTURE.md" | `inscribe` |
 | "fundir", "compartir", "mover a shared" | `smelt` |
+| "examinar", "calidad", "opinión", "critique" | `assay` |
+| "fijar", "pinar", "shortcut" | `nail` |
+| "desfijar", "despinar" | `unnail` |
+| "estado", "state", "último audit" | `forge state --show` |
+| "hook", "pre-commit", "githook" | `forge hook` |
+| "api", "contrato", "openapi", "swagger" | `forge api` |
+| "rollback", "restaurar", "deshacer" | `forge rollback` |
+| "actualizar", "update", "nueva versión" | `forge update` |
 
 ---
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@ronaldjdevfs/forge",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Forge — Architecture Operating System for backend systems. Arquitectura Hexagonal, DDD pragmático y vertical slices.",
   "type": "module",
   "bin": {
-    "forge": "./src/cli.js"
+    "forge": "src/cli.js"
   },
   "files": [
     "src/",

package/skills/forge/SKILL.md

@@ -100,6 +100,7 @@ inspect=$(node .opencode/skills/forge/scripts/inspect.mjs --json 2>/dev/null)
 
 | Lenguaje natural | Comando | Archivo |
 |---|---|---|
+| "ayuda", "help", "comandos", "lista", "--help" | `forge --help` | `reference/help.md` |
 | "inicializar", "setup", "empezar" | `forge` | `reference/forge.md` |
 | "crear feature", "nuevo dominio" | `cast` | `reference/cast.md` |
 | "inspeccionar", "diagnóstico", "evaluar" | `inspect` | `reference/inspect.md` |
@@ -112,6 +113,13 @@ inspect=$(node .opencode/skills/forge/scripts/inspect.mjs --json 2>/dev/null)
 | "grafo", "graph", "nodo", "violaciones", "risk score" | `graph` | `scripts/graph.mjs` |
 | "fundir", "compartir", "mover a shared" | `smelt` | `reference/smelt.md` |
 | "ownership", "huérfanos", "armorer" | `inspect` | (incluido en auditoría) |
+| "fijar", "pinar", "atajo", "shortcut" | `nail` | `scripts/pin.mjs` |
+| "desfijar", "despinar", "remover atajo" | `unnail` | `scripts/pin.mjs` |
+| "hook", "pre-commit", "githook", "validar commit" | `forge hook` | `reference/hooks.md` |
+| "api", "contrato", "openapi", "swagger", "graphql" | `forge api` | `scripts/forge-api.mjs` |
+| "rollback", "restaurar", "deshacer", "backup" | `forge rollback` | `scripts/rollback.mjs` |
+| "estado", "state", "último audit" | `forge state --show` | `scripts/forge-state.mjs` |
+| "examinar","calidad", "assay", "opinión", "personas", "critique", "evaluación cualitativa" | `assay` | `reference/assay.md` |
 
 ---
 
@@ -140,6 +148,23 @@ Para cada comando, Forge sigue este flujo:
 - Si `ARCHITECTURE.md` está desactualizado (fecha de auditoría > 7 días), sugerir `forge inscribe`.
 - Todos los resultados se muestran con severidades: `[CRITICAL]`, `[ERROR]`, `[WARNING]`, `[INFO]`, `[SUGGESTION]`.
 
+### Inline Ignores
+
+Forge soporta comentarios inline para excepcionar violaciones línea por línea:
+
+```ts
+// forge-ignore-next-line
+import { something } from "../infra/prisma";  // ← esta línea no se reporta
+
+// forge-ignore: R1
+import { PrismaClient } from "../../infra/prisma/client"; // ← solo R1 ignorada
+
+// forge-ignore: R1, R8
+import { crossFeature } from "../other-feature/domain/Entity"; // ← R1 y R8 ignoradas
+```
+
+---
+
 ## ARCHITECTURE.md
 
 Forge mantiene un archivo `ARCHITECTURE.md` en la raíz del proyecto con el contexto persistente. Contiene:
@@ -147,15 +172,15 @@ Forge mantiene un archivo `ARCHITECTURE.md` en la raíz del proyecto con el cont
 ```md
 # Architecture State
 
-Project Name: <name>
-Framework: <detectado>
-Runtime: <detectado>
-Database: <detectado>
-ORM: <detectado>
-DI Strategy: <detectado>
-Profile: <detectado>
-Architecture: hexagonal-feature (Platform + Features + Shared + Infra)
-Last Audit: <fecha> (score: <puntaje>)
+- Project Name: <name>
+- Framework: <detectado>
+- Runtime: <detectado>
+- Database: <detectado>
+- ORM: <detectado>
+- DI Strategy: <detectado>
+- Profile: <detectado>
+- Architecture: hexagonal-feature (Platform + Features + Shared + Infra)
+- Last Audit: <fecha> (score: <puntaje>)
 
 ## Platform
 - platform/config/
@@ -175,11 +200,11 @@ Last Audit: <fecha> (score: <puntaje>)
 ...
 
 ## Ownership
-Health: healthy | degraded | critical
-Score: 0-100
-Orphans: 0
-Duplicates: 0
-Misplaced: 0
+- Health: healthy | degraded | critical
+- Score: 0-100
+- Orphans: 0
+- Duplicates: 0
+- Misplaced: 0
 
 ## Architecture Graph
 ...
@@ -198,10 +223,56 @@ El agente DEBE leer este archivo al inicio de cada interacción y actualizarlo a
 |---|---|
 | `reference/principles.md` | Manifiesto y 12 principios inquebrantables |
 | `reference/patterns.md` | Convenciones de nomenclatura globales (PascalCase.artifact, kebab dirs, etc.) |
+| `reference/errors.md` | Manejo de errores tipados en dominio y aplicación |
+| `reference/di-strategies.md` | Estrategias de inyección de dependencias según tamaño |
+| `reference/testing-patterns.md` | Pirámide de tests, unit mocks, integration tests |
+| `reference/api-design.md` | REST / GraphQL, paginación, validación, contratos |
+| `reference/observability.md` | Logging, tracing, métricas, health checks |
+| `reference/data-patterns.md` | Repository, Unit of Work, CQRS, Event Sourcing |
+| `reference/security-patterns.md` | AuthN, AuthZ, RBAC, rate limiting, validación |
+| `reference/events.md` | Eventos de dominio, outbox pattern, sagas |
+| `reference/hooks.md` | Git pre-commit hook para validación arquitectónica |
+| `reference/help.md` | Lista completa de comandos y flags de Forge |
+| `reference/assay.md` | Ensayo arquitectónico multi-persona — interpretación cualitativa del audit |
 | `profiles/` | Perfiles tecnológicos detallados (Express, Fastify, NestJS, etc.) |
-| `scripts/` | Scripts de análisis: context, detect, inspect, chain, profile, graph, architecture, armorer, bootstrap |
+| `scripts/` | Scripts: context, detect, inspect, chain, profile, graph, architecture, armorer, bootstrap, forge-config, forge-signals, forge-state, forge-api, pin, update, rollback, hook, posttool, formatter, assay, registry/rules |
+| `scripts/registry/rules.mjs` | Anti-pattern rule registry (R1-R9 + custom rules desacopladas de detect.mjs) |
+| `scripts/formatter.mjs` | Output formatter unificado (JSON, tabla, severidad coloreada, scoreBar, formatCheck, formatViolation) |
+| `scripts/posttool.mjs` | PostToolUse hook — analiza archivos modificados tras escritura y reporta violaciones |
+| `scripts/assay.mjs` | Motor de ensayo arquitectónico multi-persona (Bezos, Fowler, Hacker, PM, Arquitecta Senior) |
 | `templates/feature/` | Templates de feature (entity, repository, uc, controller, routes, schema, mapper) |
 | `templates/platform/` | Templates de platform (config, server, database, logger, http, di) |
 | `templates/shared/` | Templates de shared (errors, contracts, types, utils) |
 | `templates/infra/` | Templates de infra (prisma, mongodb, redis, mail) |
 | `command/forge.md` | Definición del comando `/forge` para opencode |
+
+### Tests
+
+Forge incluye tests unitarios con `node:test` (sin dependencias externas).
+
+```bash
+node --test .opencode/skills/forge/tests/core.test.mjs
+```
+
+| Módulo | Tests | Descripción |
+|--------|-------|-------------|
+| `profile.mjs` | 8 | Detección de perfiles |
+| `graph.mjs` | 1 | Grafo vacío |
+| `armorer.mjs` | 1 | Ownership vacío |
+| `forge-config.mjs` | 2 | Load/save state |
+| `chain.mjs` | 1 | Grafo de dependencias vacío |
+| `formatter.mjs` | 4 | Output format, colores, JSON |
+| `registry/rules.mjs` | 4 | R1-R9, evaluación, custom rules |
+| `detect.mjs` (inline ignores) | 5 | parseInlineIgnores, isIgnored |
+| `posttool.mjs` | 1 | PostToolUse hook |
+| `assay.mjs` | 4 | Personas, generateAssay, opiniones |
+
+### Flags adicionales
+
+| Flag | Comando | Descripción |
+|------|---------|-------------|
+| `--fix` | `quench` | Auto-corrige violaciones WARNING/INFO (missing @injectable(), tsconfig, naming, container.resolve) |
+| `--show-ignores` | `quench` | Muestra los inline ignores encontrados en el código |
+| `--persona=<id>` | `assay` | Filtra ensayo por una persona (bezos, fowler, hacker, pm, senior) |
+| `--save` | `assay` | Persiste ensayo en `.forge/assay/` |
+| `--json` | `assay` | Salida JSON |

package/skills/forge/profiles/express-drizzle.md

@@ -0,0 +1,107 @@
+# Profile: Express + Drizzle ORM
+
+## Metadata
+
+```yaml
+framework: Express
+runtime: Node 20+
+database: PostgreSQL / MySQL / SQLite
+orm: Drizzle
+di_strategy: manual
+architecture: hexagonal-feature
+```
+
+## DI Strategy
+
+DI manual. Sin contenedor externo. Las dependencias se inyectan por constructor y se cablean en `app.ts`.
+
+```typescript
+// app.ts
+import express from "express";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+
+const app = express();
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const db = drizzle(pool);
+
+const creditRepo = new CreditRepository(db);
+const addCredit = new AddCredit(creditRepo);
+const creditController = new CreditController(addCredit);
+
+app.use("/credits", creditRoutes(creditController));
+app.listen(3000);
+```
+
+## Project Structure
+
+```
+├── src/
+│   ├── db/
+│   │   └── schema.ts          # Drizzle schema definitions
+│   ├── features/
+│   │   └── <domain>/
+│   │       ├── domain/
+│   │       ├── application/
+│   │       └── adapters/
+│   │           ├── in/http/
+│   │           └── out/persistence/
+│   ├── shared/
+│   ├── app.ts
+│   └── server.ts
+```
+
+## Persistence (Drizzle)
+
+### Schema definition
+
+```typescript
+// src/db/schema.ts
+import { pgTable, serial, text, timestamp, integer } from "drizzle-orm/pg-core";
+
+export const credits = pgTable("credits", {
+  id: serial("id").primaryKey(),
+  amount: integer("amount").notNull(),
+  userId: text("user_id").notNull(),
+  createdAt: timestamp("created_at").defaultNow(),
+});
+```
+
+### Repository
+
+```typescript
+import { eq } from "drizzle-orm";
+import { credits } from "@/db/schema.js";
+
+export class CreditRepository implements ICreditRepository {
+  constructor(private readonly db: DrizzleClient) {}
+
+  async create(data: CreditInput): Promise<Credit> {
+    const [record] = await this.db.insert(credits).values(data).returning();
+    return CreditMapper.toDomain(record);
+  }
+
+  async findById(id: number): Promise<Credit | null> {
+    const [record] = await this.db.select().from(credits).where(eq(credits.id, id));
+    return record ? CreditMapper.toDomain(record) : null;
+  }
+}
+```
+
+### Migrations
+
+```bash
+# Generate
+npx drizzle-kit generate
+
+# Apply
+npx drizzle-kit migrate
+```
+
+## Testing Strategy
+
+Unit: mocks de DrizzleClient. Integration: base de datos de test independiente.
+
+## Naming Conventions
+
+Las tablas en Drizzle siguen camelCase en el esquema, snake_case en PostgreSQL.

package/skills/forge/profiles/fastify-mongodb.md

@@ -0,0 +1,103 @@
+# Profile: Fastify + MongoDB + Mongoose
+
+## Metadata
+
+```yaml
+framework: Fastify
+runtime: Node 20+
+database: MongoDB
+orm: Mongoose
+di_strategy: manual
+architecture: hexagonal-feature
+```
+
+## DI Strategy
+
+DI manual. Sin contenedor. Cableado en `app.ts`.
+
+```typescript
+// app.ts
+import Fastify from "fastify";
+import mongoose from "mongoose";
+
+await mongoose.connect(process.env.MONGO_URI);
+
+const app = Fastify({ logger: true });
+const creditRepo = new CreditRepository(mongoose.connection);
+const addCredit = new AddCredit(creditRepo);
+const creditController = new CreditController(addCredit);
+
+app.register(creditRoutes(creditController));
+await app.listen({ port: 3000 });
+```
+
+## Project Structure
+
+```
+├── src/
+│   ├── features/
+│   │   └── <domain>/
+│   │       ├── domain/
+│   │       ├── application/
+│   │       └── adapters/
+│   │           ├── in/http/
+│   │           └── out/persistence/
+│   ├── shared/
+│   ├── infrastructure/
+│   │   ├── mongoose.ts          # Mongoose connection
+│   │   └── models/              # Mongoose schemas
+│   ├── app.ts
+│   └── server.ts
+```
+
+## Persistence (Mongoose)
+
+### Model schema
+
+```typescript
+// infrastructure/models/credit.model.ts
+import { Schema, model } from "mongoose";
+
+const creditSchema = new Schema({
+  amount: { type: Number, required: true },
+  userId: { type: String, required: true },
+}, { timestamps: true });
+
+export const CreditModel = model("Credit", creditSchema);
+```
+
+### Repository
+
+```typescript
+export class CreditRepository implements ICreditRepository {
+  async create(data: CreditInput): Promise<Credit> {
+    const doc = await CreditModel.create(data);
+    return CreditMapper.toDomain(doc.toObject());
+  }
+}
+```
+
+## Routes & Controllers
+
+Usar patrón Fastify plugin (ver `fastify-postgres`).
+
+## Testing Strategy
+
+```typescript
+import { MongoMemoryServer } from "mongodb-memory-server";
+
+let mongod: MongoMemoryServer;
+
+beforeAll(async () => {
+  mongod = await MongoMemoryServer.create();
+  await mongoose.connect(mongod.getUri());
+});
+afterAll(async () => {
+  await mongoose.disconnect();
+  await mongod.stop();
+});
+```
+
+## Naming Conventions
+
+Mismas que `express-mongodb`. Colecciones en snake_case, campos en camelCase.

package/skills/forge/profiles/fastify-prisma.md

@@ -0,0 +1,81 @@
+# Profile: Fastify + Prisma
+
+## Metadata
+
+```yaml
+framework: Fastify
+runtime: Node 20+
+database: Cualquier RDBMS (PostgreSQL, MySQL, SQLite)
+orm: Prisma
+di_strategy: manual
+architecture: hexagonal-feature
+```
+
+## DI Strategy
+
+DI manual. Sin contenedor externo. Cableado explícito en `app.ts`.
+
+```typescript
+// app.ts
+import Fastify from "fastify";
+import { PrismaClient } from "@prisma/client";
+
+const app = Fastify({ logger: true });
+const prisma = new PrismaClient();
+const creditRepo = new CreditRepository(prisma);
+const addCredit = new AddCredit(creditRepo);
+const creditController = new CreditController(addCredit);
+
+app.register(creditRoutes(creditController));
+await app.listen({ port: 3000 });
+```
+
+## Project Structure
+
+```
+├── prisma/
+│   └── schema.prisma
+├── src/
+│   ├── features/
+│   │   └── <domain>/
+│   │       ├── domain/
+│   │       ├── application/
+│   │       └── adapters/
+│   │           ├── in/http/
+│   │           └── out/persistence/
+│   ├── shared/
+│   ├── infrastructure/
+│   │   └── prisma.ts
+│   ├── app.ts
+│   └── server.ts
+```
+
+## Persistence
+
+Idéntico al perfil `express-prisma`: repositorios Prisma con `PrismaClient` singleton, transacciones con `$transaction()`.
+
+## Routes & Controllers
+
+Usar el patrón Fastify plugin como en `fastify-postgres`. Cada feature expone un plugin que recibe el controlador por parámetro.
+
+## Testing Strategy
+
+```typescript
+import Fastify from "fastify";
+
+const app = Fastify();
+const mockRepo = { create: vi.fn() };
+const useCase = new AddCredit(mockRepo);
+
+app.register(creditRoutes(new CreditController(useCase)));
+
+it("creates a credit", async () => {
+  mockRepo.create.mockResolvedValue({ id: "1" });
+  const res = await app.inject({ method: "POST", url: "/credits", payload: { amount: 100 } });
+  expect(res.statusCode).toBe(201);
+});
+```
+
+## Naming Conventions
+
+Mismas que `fastify-postgres`. Rutas en camelCase, servicios en PascalCase.