bug_bunny 4.8.0 → 4.8.1

data/.agents/skills/yard/references/tipos.md

@@ -0,0 +1,144 @@
+# YARD — Catálogo completo de Type Specifications
+
+Los tipos se especifican entre corchetes `[Type]` en tags como `@param`, `@return`, `@yield`, etc.
+
+## Tipos básicos
+
+| Tipo | Descripción |
+|---|---|
+| `String` | Clase Ruby estándar |
+| `Integer` | Clase Ruby estándar |
+| `Float` | Clase Ruby estándar |
+| `Symbol` | Clase Ruby estándar |
+| `Boolean` | Convención YARD: `TrueClass` o `FalseClass` |
+| `nil` | Valor nil literal |
+| `void` | Sin valor de retorno significativo |
+| `self` | Retorna self (métodos encadenables) |
+| `true` | Literal true |
+| `false` | Literal false |
+
+## Union types (múltiples tipos)
+
+Separados por comas dentro de los corchetes:
+
+```
+[String, Symbol]           → String o Symbol
+[Integer, nil]             → Integer o nil
+[String, Symbol, nil]      → cualquiera de los tres
+[Boolean, nil]             → true, false o nil
+```
+
+## Parametrized types (generics)
+
+Sintaxis: `Collection<ElementType>`
+
+```
+[Array<String>]                    → array de strings
+[Array<String, Symbol>]            → array de strings y/o symbols
+[Set<Integer>]                     → set de integers
+[Hash<Symbol, String>]             → hash con keys symbol, values string
+[Hash<Symbol, Array<Integer>>]     → hash con values que son arrays de integers
+[Enumerator<User>]                 → enumerator de users
+```
+
+## Hash con estructura explícita
+
+Sintaxis: `Hash{KeyType => ValueType}`
+
+```
+[Hash{Symbol => String}]           → hash con keys symbol, values string
+[Hash{String => Object}]           → hash con keys string, values cualquiera
+[Hash{Symbol => Array<String>}]    → hash con values que son arrays de strings
+[Hash{String, Symbol => Integer}]  → keys string o symbol, values integer
+```
+
+## Duck types
+
+Prefijo `#` indica que el objeto responde a ese método:
+
+```
+[#read]                → cualquier objeto con método #read
+[#call]                → cualquier callable (Proc, Lambda, etc.)
+[#to_s]                → cualquier objeto convertible a string
+[#read, #close]        → debe responder a ambos métodos
+[#each]                → cualquier enumerable
+```
+
+## Order-dependent lists
+
+Sintaxis: `Collection(Type1, Type2, ...)` — exactamente esos tipos en ese orden:
+
+```
+[Array(String, Integer)]           → array de exactamente 2 elementos: [string, integer]
+[Array(String, Integer, Hash)]     → array de exactamente 3 elementos en ese orden
+```
+
+## Combinaciones comunes
+
+```
+[String, nil]                      → string nullable
+[Array<String>]                    → array de strings
+[Hash{Symbol => Object}]           → options hash
+[Boolean]                          → true/false
+[void]                             → sin retorno
+[self]                             → chainable
+[#read, #write]                    → IO-like
+[Integer, Float]                   → numeric
+[String, Symbol]                   → string-like identifier
+[Array<Hash{Symbol => String}>]    → array de hashes
+[Hash{Symbol => String, nil}]      → hash con values nullable
+```
+
+## Patrones por contexto
+
+### Métodos de búsqueda
+```ruby
+# @return [User, nil] el usuario o nil si no existe
+def find(id); end
+
+# @return [User] el usuario
+# @raise [RecordNotFound] si no existe
+def find!(id); end
+```
+
+### Métodos booleanos
+```ruby
+# @return [Boolean] true si el usuario es admin
+def admin?; end
+```
+
+### Métodos de mutación
+```ruby
+# @return [void]
+def save!; end
+
+# @return [self] para encadenar
+def where(conditions); end
+```
+
+### Métodos de colección
+```ruby
+# @return [Array<User>] lista de usuarios
+def all; end
+
+# @yield [user] itera sobre cada usuario
+# @yieldparam user [User]
+# @return [Enumerator<User>] si no se pasa bloque
+def each(&block); end
+```
+
+### Métodos con opciones
+```ruby
+# @param opts [Hash{Symbol => Object}] opciones
+# @option opts [Integer] :limit (10) máximo de resultados
+# @option opts [Integer] :offset (0) desde dónde empezar
+# @option opts [Symbol] :order (:asc) dirección del ordenamiento
+def search(query, **opts); end
+```
+
+### Callbacks y Procs
+```ruby
+# @param callback [Proc, #call] bloque a ejecutar
+# @param filter [Proc<User, Boolean>] filtro que recibe user y retorna boolean
+def on_create(callback); end
+```

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [4.8.1] - 2026-04-04
+
+### Mejoras internas
+* **Skills System:** Migración completa del sistema de documentación AI de `docs/` y `.claude/commands/` al nuevo estándar de skills. La documentación AI ahora se distribuye como `skill/SKILL.md` empaquetada en la gema, con 7 archivos de referencia detallados en `skill/references/`.
+* **CLAUDE.md simplificado:** Se eliminaron ~230 líneas de instrucciones hardcodeadas. `CLAUDE.md` ahora delega el conocimiento a las skills en `.agents/skills/` y `skill/`.
+* **Gemspec:** `documentation_uri` actualizado de `docs` a `skill/` para apuntar a la ubicación correcta de la documentación.
+* **Skills de desarrollo:** Se incorporan 7 skills locales en `.agents/skills/` (documentation-writer, gem-release, quality-code, sentry, skill-builder, skill-manager, yard) con `skills.yml` como manifiesto de dependencias.
+
 ## [4.8.0] - 2026-04-02
 
 ### ✨ AI Documentation Standard (v4.3)

data/CLAUDE.md

@@ -7,234 +7,31 @@ BugBunny es una gema Ruby que implementa una capa de enrutamiento RESTful sobre
 **Problema que resuelve:** Eliminar el acoplamiento directo entre microservicios via HTTP, usando RabbitMQ como bus de mensajes con la misma ergonomía de un framework web.
 
 ## Knowledge Base
-
-- **Docs AI:** `docs/ai/` — conocimiento estructurado para agentes
-- **Index:** `docs/ai/_index.md` — manifest con versión, audiencias y archivos
-- **Docs humanos:** `docs/_index.md` — manifest de toda la documentación (`howto/`, `concepts.md`)
-
-## Skills disponibles
-
-- `.agents/skills/rabbitmq-expert/` — arquitectura AMQP, exchanges, quorum queues, DLX, HA, clustering
-
----
-
-## Arquitectura
-
-```
-Publisher (Client/Resource)
-  └─ Producer → Session → Bunny → RabbitMQ Exchange
-                                        │
-                                   RabbitMQ Queue
-                                        │
-Consumer (subscribe loop)
-  └─ ConsumerMiddleware::Stack
-       └─ process_message
-            └─ Router → Controller → Action
-                              └─ reply (RPC)
-```
-
-### Componentes clave
-
-| Clase | Responsabilidad |
-|---|---|
-| `BugBunny::Session` | Wrapper de canal Bunny. Declara exchanges y queues. |
-| `BugBunny::Consumer` | Subscribe loop. Rutea mensajes a controladores via `BugBunny.routes`. |
-| `BugBunny::ConsumerMiddleware::Stack` | Pipeline de middlewares antes de `process_message`. |
-| `BugBunny::Producer` | Publica mensajes. Implementa RPC con `Concurrent::IVar`. |
-| `BugBunny::Client` | API de alto nivel para el publicador. Pool de conexiones. |
-| `BugBunny::Controller` | Base class tipo Rails. `around_action`, `before_action`, `render`. |
-| `BugBunny::Resource` | ActiveRecord-like sobre AMQP. `find`, `where`, `create`, etc. |
-| `BugBunny::Request` | Value object del mensaje saliente (path, method, params, headers). |
-| `BugBunny::Observability` | Mixin de logging estructurado. `safe_log`, `exception_metadata`. |
-| `BugBunny::Configuration` | Configuración global. Logger, timeouts, middleware hooks. |
-
-### Flujo RPC completo
-
-1. `Resource.find(id)` → `Client#request` → `Producer#rpc`
-2. Producer publica en exchange con `reply_to: 'amq.rabbitmq.reply-to'`
-3. `Concurrent::IVar` bloquea el thread principal (`future.value(timeout)`)
-4. Consumer recibe → middleware stack → controller → `reply(response)`
-5. Reply listener thread setea `future.set({ body:, headers: })`
-6. Thread principal: `on_rpc_reply&.call(headers)` → `parse_response(body)`
-
-## Hooks de extensión
-
-```ruby
-# Middleware antes de process_message (ej: tracing, auth)
-BugBunny.consumer_middlewares.use MyMiddleware
-
-# Headers a inyectar en el reply RPC (ej: trace context actualizado)
-config.rpc_reply_headers = -> { { 'X-Amzn-Trace-Id' => Tracer.header } }
-
-# Callback en el thread principal al recibir el reply (ej: hidratar tracer)
-config.on_rpc_reply = ->(headers) { Tracer.hydrate(headers['X-Amzn-Trace-Id']) }
-```
-
----
-
-## Dominio y Expertise
-
-Al trabajar en esta gema aplicá expertise en:
-
-- **Ruby idiomático**: módulos, mixins, metaprogramación, `class_attribute`, `Concurrent::*`
-- **RabbitMQ / AMQP**: exchanges (direct/topic/fanout), queues, bindings, `reply_to`, `correlation_id`, `properties.headers`, publisher confirms, manual ack
-- **Bunny**: la gema Ruby que wrappea AMQP. `channel`, `basic_consume`, `basic_publish`, `IVar`
-- **Rails patterns**: `ActiveModel`, `ActiveSupport`, `class_attribute`, `concerns`, `constantize`
-- **Rack**: `Rack::Utils.parse_nested_query`, `build_nested_query`
-
----
-
-## Observability — Estándar de Logging
-
-Esta gema implementa su propio patrón de observability via `BugBunny::Observability`.
-
-### Reglas fundamentales
-
-- **Formato**: `component=x event=clase.evento [key=value ...]` — todo en una línea
-- **Nunca** llamar al logger directamente. Siempre usar `safe_log`
-- **Nunca** `Kernel#warn`, `$stderr`, `puts`
-- **Niveles**: `ERROR`=excepción, `WARN`=inesperado+continuó, `INFO`=normal, `DEBUG`=detalle
-- `DEBUG` siempre en bloque: `logger.debug { "k=#{v}" }` — `safe_log` lo maneja internamente
-- Duraciones: `Process.clock_gettime(Process::CLOCK_MONOTONIC)`, nunca `Time.now`
-- Logger failures **nunca** interrumpen el flujo — `safe_log` tiene `rescue StandardError`
-
-### Uso en clases nuevas
-
-```ruby
-class BugBunny::MiClase
-  include BugBunny::Observability
-
-  def initialize
-    @logger = BugBunny.configuration.logger
-  end
-
-  def mi_metodo
-    start = monotonic_now
-    # ...
-    safe_log(:info, "mi_clase.mi_evento", campo: valor, duration_s: duration_s(start))
-  rescue StandardError => e
-    safe_log(:error, "mi_clase.error", **exception_metadata(e))
-  end
-end
-```
-
-### Naming de eventos
-
-Formato estricto: `"clase.evento"` (string, nunca symbol)
-
-| Evento | Nivel | Cuándo |
-|---|---|---|
-| `consumer.start` | INFO | Consumer inicia subscribe |
-| `consumer.bound` | INFO | Queue bindeada al exchange |
-| `consumer.message_received` | INFO | Mensaje recibido, antes del routing |
-| `consumer.route_matched` | DEBUG | Ruta encontrada |
-| `consumer.message_processed` | INFO | Procesamiento exitoso con duración |
-| `consumer.execution_error` | ERROR | Excepción en el procesamiento |
-| `producer.publish` | INFO | Mensaje publicado |
-| `producer.rpc_waiting` | DEBUG | Bloqueando esperando respuesta |
-| `producer.rpc_response_received` | DEBUG | Reply recibido (thread principal) |
-
-### Campos estándar
-
-```ruby
-safe_log(:error, "clase.error", **exception_metadata(e))
-# => error_class: "RuntimeError", error_message: "..."
-
-safe_log(:info, "clase.evento", duration_s: duration_s(start_time))
-# => duration_s: 0.001234
-
-# Valores sensibles se filtran automáticamente:
-# password, token, secret, api_key, auth → [FILTERED]
-```
-
----
-
-## Standards de Código
-
-### RuboCop
-
-Esta gema usa **rubocop-rails-omakase**. Todo código nuevo o modificado debe cumplir.
-
-```bash
-source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8
-bundle exec rubocop
-bundle exec rubocop -a   # autocorrect
-```
-
-**No corregir código existente no tocado.** Solo el código nuevo o modificado en el PR.
-
-### YARD
-
-Todo método público nuevo o modificado lleva documentación YARD:
-
-```ruby
-# Descripción breve.
-#
-# Descripción extendida si es necesario.
-#
-# @param name [Type] Descripción
-# @return [Type] Descripción
-# @raise [ErrorClass] Cuándo se lanza
-# @example
-#   resultado = mi_metodo(arg)
-def mi_metodo(name)
-```
-
-```bash
-bundle exec yard doc
-bundle exec yard stats --list-undoc
-```
-
-### RSpec
-
-Tests en `spec/`. Sin mocks de dependencias externas reales (RabbitMQ se mockea con doubles de Bunny).
-
-```bash
-source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8
-bundle exec rspec
-bundle exec rspec spec/bug_bunny/consumer_spec.rb   # archivo específico
-```
-
----
-
-## Entorno de Desarrollo
-
-### Ruby
-
-```bash
-source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8
-```
-
-Nunca usar `bundle exec ruby` con el Ruby del sistema (2.6). Siempre sourcear chruby primero.
-
-### Worktrees
-
-- **Main**: `/Users/gabriel/src/gems/bug_bunny` (rama `main`)
-- **Work**: `/Users/gabriel/src/gems/worktrees/current-5n3` (ramas de feature)
-- `main` está checkeado en otro worktree — no se puede hacer `git checkout main` desde el worktree de trabajo
-
-### Push a remoto
-
-SSH está roto en este entorno. Para push siempre:
-
-```bash
-git remote set-url origin https://github.com/gedera/bug_bunny.git
-git push origin main
-git remote set-url origin git@github.com:gedera/bug_bunny.git   # restaurar
-```
-
----
-
-## Release Workflow
-
-Usá el comando `/release` para el flujo completo. Manualmente:
-
-1. Determinar tipo: `patch`=bugfix, `minor`=feature nueva, `major`=breaking change
-2. Actualizar `lib/bug_bunny/version.rb`
-3. Agregar entrada al tope de `CHANGELOG.md`
-4. Commit con mensaje convencional
-5. Desde `/Users/gabriel/src/gems/bug_bunny`: `git merge --ff-only <branch>`
-6. Push via HTTPS + restaurar SSH
-7. `git tag vX.Y.Z && git push origin vX.Y.Z`
-
-**Nunca commitear ni pushear sin permiso explícito del usuario.**
+- Las skills en `.agents/skills/` incluyen conocimiento de dependencias.
+- Leer la skill de una dependencia ANTES de responder sobre ella.
+- Rebuild: `ruby .agents/skills/skill-manager/scripts/sync.rb`
+
+## Entorno
+- Versión de Ruby: leer `.ruby-version`
+- Versión de Rails y gemas: leer `Gemfile.lock`
+- Gestor de Ruby: chruby (no usar rvm ni rbenv)
+- Package manager: Bundler
+
+## RuboCop
+- Usamos rubocop-rails-omakase como base.
+- Correr `bundle exec rubocop -a` antes de commitear.
+- No deshabilitar cops sin justificación en el PR.
+
+## YARD
+- Documentación incremental: si tocás un método, documentalo con YARD.
+- Consultar la skill `yard` para tags y tipos correctos.
+- Verificar cobertura: `bundle exec yard stats --list-undoc`
+
+## Testing
+- Framework: RSpec
+- Correr: `bundle exec rspec`
+- Todo código nuevo debe tener tests.
+
+## Releases
+- Gemas: `/gem-release`
+- Servicios: `/service-release build` o `/service-release deploy`

data/lib/bug_bunny/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BugBunny
-  VERSION = '4.8.0'
+  VERSION = '4.8.1'
 end

data/skill/SKILL.md

@@ -0,0 +1,230 @@
+# BugBunny Expert
+
+Skill de conocimiento completo sobre BugBunny. Consultame para cualquier pregunta sobre integración, arquitectura, API, errores y antipatrones.
+
+---
+
+## Glosario
+
+**AMQP** — Advanced Message Queuing Protocol. Protocolo binario que implementa RabbitMQ.
+**Bunny** — Cliente Ruby para AMQP. BugBunny lo usa internamente para conexiones, canales y publicación.
+**Exchange** — Recibe mensajes del producer y los enruta a queues según reglas. Tipos: `direct` (match exacto), `topic` (wildcards), `fanout` (broadcast).
+**Queue** — Almacena mensajes hasta que un consumer los consume. Las queues durables sobreviven reinicios del broker.
+**Routing Key** — String que el producer adjunta al mensaje. El exchange lo usa para decidir a qué queues enrutar.
+**Binding** — Enlace entre un exchange y una queue, opcionalmente con un patrón de routing key.
+**Session** — `BugBunny::Session` envuelve canales de Bunny con thread-safety y double-checked locking.
+**RPC** — Patrón síncrono que usa la pseudo-cola `amq.rabbitmq.reply-to` para respuestas sin crear queues temporales.
+**Fire-and-Forget** — Patrón asíncrono donde el producer publica y continúa sin esperar respuesta. Retorna `{ 'status' => 202 }`.
+**Resource** — ORM tipo ActiveRecord que mapea operaciones CRUD a llamadas AMQP.
+**Consumer** — Worker bloqueante que despacha mensajes a controladores mediante un Router.
+**Connection Pool** — Pool de conexiones (`connection_pool` gem) que comparte sessions entre threads. Cada slot cachea su `Session` y `Producer`.
+
+---
+
+## Arquitectura: Flujo RPC
+
+```
+┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
+│ Resource  │────>│  Client  │────>│ Middleware│────>│ Producer │
+└──────────┘     └──────────┘     │  Stack   │     └────┬─────┘
+                                  └──────────┘          │
+                                                        ▼
+                                                  ┌──────────┐
+                                                  │ Exchange  │
+                                                  └────┬─────┘
+                                                       │
+                                                       ▼
+                                                  ┌──────────┐
+                                                  │  Queue   │
+                                                  └────┬─────┘
+                                                       │
+                                                       ▼
+┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
+│  Reply   │<────│Controller│<────│  Router  │<────│ Consumer │
+└──────────┘     └──────────┘     └──────────┘     └──────────┘
+```
+
+1. El `Client` pasa la petición por una pila de middlewares client-side.
+2. El `Producer` publica en el exchange con `correlation_id`, `reply_to` y el path en el header `type`.
+3. El hilo emisor se bloquea en un `Concurrent::IVar` esperando la respuesta.
+4. El `Consumer` recibe, ejecuta consumer middlewares, rutea al controller.
+5. El controller ejecuta callbacks y la acción, luego responde via `reply_to`.
+6. Se aplican ganchos de traza (`on_rpc_reply`) y se devuelve el objeto hidratado.
+
+---
+
+## Arquitectura: Componentes Clave
+
+| Clase | Responsabilidad |
+|---|---|
+| `BugBunny::Configuration` | Configuración global. Valida campos requeridos en `BugBunny.configure`. |
+| `BugBunny::Session` | Wrapper de canal Bunny. Declara exchanges y queues. Thread-safe con double-checked locking. |
+| `BugBunny::Producer` | Publica mensajes. Implementa RPC con `Concurrent::IVar` y direct reply-to. |
+| `BugBunny::Client` | API de alto nivel. Pool de conexiones y middleware stack (onion architecture). |
+| `BugBunny::Consumer` | Subscribe loop con health check. Rutea mensajes via `BugBunny.routes`. |
+| `BugBunny::ConsumerMiddleware::Stack` | Pipeline de middlewares antes de `process_message`. Thread-safe. |
+| `BugBunny::Controller` | Base class tipo Rails. `before_action`, `around_action`, `after_action`, `rescue_from`, `render`. |
+| `BugBunny::Resource` | ORM sobre AMQP. `find`, `where`, `create`, `save`, `destroy`. ActiveModel validations y callbacks. |
+| `BugBunny::Routing::RouteSet` | DSL de rutas: `resources`, `namespace`, `member`, `collection`. |
+| `BugBunny::Observability` | Mixin de logging estructurado. `safe_log` nunca lanza excepciones. Filtra keys sensibles. |
+| `BugBunny::Middleware::Stack` | Builder de middlewares client-side (onion architecture tipo Faraday). |
+| `BugBunny::Request` | Value object del mensaje saliente con metadata AMQP completa. |
+| `BugBunny::Railtie` | Integración Rails: autoload de `app/rabbit`, fork safety (Puma, Spring). |
+
+---
+
+## API: Configuración Global
+
+```ruby
+BugBunny.configure do |config|
+  # Conexión
+  config.host = 'localhost'          # default: '127.0.0.1'
+  config.port = 5672                 # default: 5672
+  config.username = 'guest'          # default: 'guest'
+  config.password = 'guest'          # default: 'guest'
+  config.vhost = '/'                 # default: '/'
+
+  # Resiliencia
+  config.automatically_recover = true
+  config.network_recovery_interval = 5
+  config.max_reconnect_attempts = nil  # nil = infinito
+  config.connection_timeout = 10
+  config.heartbeat = 15
+
+  # Performance
+  config.channel_prefetch = 1
+  config.rpc_timeout = 10
+
+  # Logging
+  config.logger = Rails.logger
+  config.log_tags = [:uuid]
+
+  # Propagación de trazas
+  config.rpc_reply_headers = -> { { 'X-Trace-Id' => Tracer.id } }
+  config.on_rpc_reply = ->(h) { Tracer.hydrate(h['X-Trace-Id']) }
+
+  # Infraestructura (cascade level 2)
+  config.exchange_options = { durable: true }
+  config.queue_options = { auto_delete: false }
+
+  # Health check
+  config.health_check_interval = 60
+  config.health_check_file = 'tmp/bb_health'
+
+  # Routing
+  config.controller_namespace = 'BugBunny::Controllers'
+end
+```
+
+La validación es automática tras el bloque; lanza `ConfigurationError` si faltan campos requeridos o los valores están fuera de rango.
+
+---
+
+## API: Routing DSL
+
+```ruby
+BugBunny.routes.draw do
+  resources :users
+  resources :orders, only: [:index, :show]
+  resources :products, except: [:destroy]
+
+  namespace :admin do
+    resources :reports
+    resources :nodes do
+      member do
+        put :drain           # PUT nodes/:id/drain
+      end
+      collection do
+        get :stats           # GET nodes/stats
+      end
+    end
+  end
+end
+```
+
+Genera rutas REST estándar (index, show, create, update, destroy) mapeadas a controladores. El `namespace` añade prefijo al path y busca controladores dentro del módulo correspondiente.
+
+---
+
+## API: RPC vs Fire-and-Forget
+
+**RPC síncrono** — Bloquea hasta respuesta. Usa `amq.rabbitmq.reply-to`. Timeout configurable.
+```ruby
+response = client.request('users/42', method: :get)
+# → { 'status' => 200, 'body' => { 'id' => 42, 'name' => 'John' } }
+```
+
+**Fire-and-Forget** — Publica y continúa. Sin confirmación.
+```ruby
+client.publish('events', method: :post, body: { type: 'order.placed' })
+# → { 'status' => 202, 'body' => nil }
+```
+
+---
+
+## FAQ
+
+### ¿Cómo se integra con Rails?
+`rails generate bug_bunny:install` genera el inicializador, crea `app/bug_bunny/controllers/` y actualiza `CLAUDE.md`. El pool se define en el inicializador y se asigna a `BugBunny::Resource.connection_pool`.
+
+### ¿Cómo funciona el Health Check?
+El consumer ejecuta un check periódico (default 60s) que verifica la conexión AMQP con un `queue.declare(passive: true)`. Si `health_check_file` está configurado, actualiza su mtime. En Kubernetes, usar un `livenessProbe` tipo `exec` que verifique recencia del archivo.
+
+### ¿Cómo funciona el Connection Pool?
+Cada slot del pool cachea su `Session` y `Producer` durante su vida útil. Esto evita recrear canales AMQP (costoso) y previene el error de doble `basic_consume`. Thread-safety garantizada por `ConnectionPool`.
+
+### ¿Cómo funciona la cascada de configuración?
+3 niveles: Gem defaults → Global config (`BugBunny.configure`) → Per-request (args en `client.request` o `Resource.with`). Se mergean con `merge`.
+
+### ¿Cómo funciona fork safety?
+`BugBunny::Railtie` registra hooks en `ActiveSupport::ForkTracker` (Rails 7.1+), `Puma.events.on_worker_boot` y `Spring.after_fork` para llamar `BugBunny.disconnect` y evitar sockets TCP heredados.
+
+---
+
+## Antipatrones
+
+### Consumer en Puma
+No ejecutar el `Consumer` dentro de hilos de Puma. Es un bucle bloqueante que saturará el servidor web. Usar un proceso worker dedicado o una tarea Rake separada.
+
+### Reasignación de Pool en Runtime
+No asignar `Resource.connection_pool` dentro de controllers o models durante una petición. Es un ajuste global que causa condiciones de carrera y fugas de conexiones.
+
+### Abuso de .with persistente
+No guardar el resultado de `Order.with(...)` en una variable para múltiples llamadas. Lanzará error tras la primera ejecución. Para múltiples llamadas, usar siempre la forma de bloque.
+
+### Registrar middleware durante call()
+No registrar consumer middlewares durante la ejecución de `call()`. El stack toma un snapshot al inicio; los registros concurrentes no afectan la ejecución actual.
+
+---
+
+## Errores Comunes
+
+### BugBunny::RequestTimeout (408)
+**Causa:** No hubo respuesta en `config.rpc_timeout` segundos.
+**Resolución:** Verificar que el worker esté activo y que el controlador remoto no lance excepciones silenciosas.
+
+### BugBunny::SecurityError
+**Causa:** El mensaje intenta ejecutar un controlador que no hereda de `BugBunny::Controller`.
+**Resolución:** Verificar la jerarquía de controladores y que `config.controller_namespace` coincida.
+
+### BugBunny::UnprocessableEntity (422)
+**Causa:** Fallo de validación en el servicio remoto.
+**Resolución:** `resource.save` devuelve `false`. Acceder a `resource.errors` o `rescue` con `e.error_messages`.
+
+### BugBunny::CommunicationError
+**Causa:** Fallo de conexión o reconexión agotada.
+**Resolución:** Verificar conectividad a RabbitMQ. Revisar `max_reconnect_attempts` y logs de reconexión.
+
+Ver catálogo completo en [Errores](references/errores.md).
+
+---
+
+## Referencias
+
+- [Routing](references/routing.md) — DSL de rutas, bindings, namespaces, member y collection
+- [Controllers](references/controller.md) — Acciones, callbacks, render, rescue_from y log tags
+- [Resources](references/resource.md) — CRUD sobre AMQP, .with, callbacks y change tracking
+- [Client y Middleware](references/client-middleware.md) — Client, Producer, middleware stack onion
+- [Consumer](references/consumer.md) — Subscribe loop, consumer middleware, health check
+- [Catálogo de Errores](references/errores.md) — Jerarquía completa de excepciones con resolución
+- [Testing](references/testing.md) — RSpec helpers, mocks, patrones de integración