docker-swarm 0.5.4 → 0.7.0

data/docs/glossary/glossary.md

@@ -0,0 +1,141 @@
+# Glosario — docker-swarm
+
+> meta: artefacto · RFC-009 · generado dev-enrich · anclado a `a4e3129` · cobertura: completo inicial (primitivas Docker + arquitectura interna); no se acrecienta sin tocar el flujo/concepto
+
+## 1. Resumen
+
+Términos de negocio que la gema `docker-swarm` materializa. Dos grupos: **primitivas Docker** (entidades del Engine API expuestas como modelos Ruby) y **conceptos arquitectónicos internos** (mecanismos que sostienen el ORM). Sólo términos de negocio con binding estable. Definiciones técnicas de columnas/atributos no van acá (sería Data Dictionary; n/a en gema sin DB).
+
+## 2. Términos
+
+### Service
+
+Servicio de Docker Swarm: definición declarativa de un conjunto de tasks que corren en el cluster. La gema lo expone como CRUD completo + `restart` + `logs`. Update atómico vía `Version.Index`.
+**Binding:** [`DockerSwarm::Service`](../../lib/docker_swarm/models/service.rb)
+
+### Node
+
+Miembro físico del cluster Swarm (manager o worker). Read-only desde el punto de vista de creación: los nodos se unen al swarm fuera de la gema; la gema sólo permite update (rol/disponibilidad) y destroy.
+**Binding:** [`DockerSwarm::Node`](../../lib/docker_swarm/models/node.rb)
+
+### Task
+
+Unidad de ejecución de un Service en un Node específico. Read-only: las tasks se generan automáticamente por el orquestador a partir del Spec del Service. La gema sólo permite listar/inspeccionar/obtener logs.
+**Binding:** [`DockerSwarm::Task`](../../lib/docker_swarm/models/task.rb)
+
+### Container
+
+Container Docker standalone (no Swarm). La gema expone start/stop/destroy/logs sobre containers existentes. Creación intencionalmente fuera de scope F1 — el caso de uso primario de la gema es Swarm.
+**Binding:** [`DockerSwarm::Container`](../../lib/docker_swarm/models/container.rb)
+
+### Image
+
+Imagen Docker (registry o local). La gema cubre listar, pull (`create`) y destroy. Build local no cubierto (no caso de uso de orquestación).
+**Binding:** [`DockerSwarm::Image`](../../lib/docker_swarm/models/image.rb)
+
+### Network
+
+Red Docker (overlay para Swarm, bridge para Container). CRUD completo. Update soporta conectar/desconectar containers.
+**Binding:** [`DockerSwarm::Network`](../../lib/docker_swarm/models/network.rb)
+
+### Volume
+
+Volumen Docker (named volume). CRUD sin update (Docker no soporta update de Volume). La respuesta del index viene envuelta en `{"Volumes": [...]}` — manejado vía `root_key`.
+**Binding:** [`DockerSwarm::Volume`](../../lib/docker_swarm/models/volume.rb)
+
+### Config
+
+Configuración inmutable distribuida en el cluster (archivos de configuración, manifests). CRUD sin update — Docker requiere recrear. Sólo Swarm.
+**Binding:** [`DockerSwarm::Config`](../../lib/docker_swarm/models/config.rb)
+
+### Secret
+
+Dato sensible distribuido en el cluster (passwords, tokens, certs). Misma semántica que Config pero el `Data` se filtra automáticamente en logs vía `LogHelper`. Sólo Swarm.
+**Binding:** [`DockerSwarm::Secret`](../../lib/docker_swarm/models/secret.rb)
+
+### Swarm
+
+Cluster Docker Swarm como entidad singleton. Sólo `show` (info del cluster: ID, Version, Spec, JoinTokens). No CRUD — el cluster se inicializa/disuelve fuera de la gema.
+**Binding:** [`DockerSwarm::Swarm`](../../lib/docker_swarm/models/swarm.rb)
+
+### System
+
+Daemon Docker como entidad singleton. Métodos estáticos: `info`, `version`, `up` (ping), `df` (disk usage). Útil para health checks y observabilidad.
+**Binding:** [`DockerSwarm::System`](../../lib/docker_swarm/models/system.rb)
+
+---
+
+### Base (ORM base)
+
+Clase base de todos los modelos. Hereda de `ActiveModel::Model`. Provee accessors dinámicos PascalCase, `find`, `all`, `where`, `reload`, `payload_for_docker`. Centraliza el patrón ORM contra Docker Engine API.
+**Binding:** [`DockerSwarm::Base`](../../lib/docker_swarm/base.rb)
+
+### Concern
+
+Mixin (`ActiveSupport::Concern`) que agrega capacidad CRUD/auxiliar a un modelo. La gema define cinco concerns ortogonales: cada modelo incluye los que aplican a su semántica Docker.
+
+| Concern | Símbolo | Aplica a |
+|---|---|---|
+| Creatable | [`DockerSwarm::Concerns::Creatable`](../../lib/docker_swarm/concerns/creatable.rb) | Service, Network, Volume, Config, Secret, Image |
+| Updatable | [`DockerSwarm::Concerns::Updatable`](../../lib/docker_swarm/concerns/updatable.rb) | Service, Node, Network |
+| Deletable | [`DockerSwarm::Concerns::Deletable`](../../lib/docker_swarm/concerns/deletable.rb) | Service, Node, Container, Network, Volume, Config, Secret, Image |
+| Loggable | [`DockerSwarm::Concerns::Loggable`](../../lib/docker_swarm/concerns/loggable.rb) | Service, Task, Container |
+| Inspectable | [`DockerSwarm::Concerns::Inspectable`](../../lib/docker_swarm/concerns/inspectable.rb) | Todos (vía Base) |
+
+### Middleware
+
+Capa Excon en el stack del cliente HTTP. Tres middlewares custom: serialización de body, parsing de respuesta con indifferent access, mapeo de status a excepción tipada.
+
+| Middleware | Símbolo | Rol |
+|---|---|---|
+| RequestEncoder | [`DockerSwarm::Middleware::RequestEncoder`](../../lib/docker_swarm/middleware/request_encoder.rb) | Serializa body (JSON / x-www-form / multipart) según Content-Type |
+| ResponseJSONParser | [`DockerSwarm::Middleware::ResponseJSONParser`](../../lib/docker_swarm/middleware/response_json_parser.rb) | Parsea JSON y aplica `with_indifferent_access` |
+| ErrorHandler | [`DockerSwarm::Middleware::ErrorHandler`](../../lib/docker_swarm/middleware/error_handler.rb) | Mapea 4xx/5xx → `DockerSwarm::Error::*` + log `business_error` |
+
+### Connection
+
+Wrapper sobre el cliente Excon. Memoiza la conexión, aplica timeouts/retries de configuración, clasifica errores idempotentes vs no-idempotentes (post-fix correctness), y emite logs KV.
+**Binding:** [`DockerSwarm::Connection`](../../lib/docker_swarm/connection.rb)
+
+### Dynamic Accessor
+
+Mecanismo por el cual los modelos exponen atributos no declarados. Docker Engine evoluciona y agrega campos: la gema usa `method_missing` + cache en `defined_attributes` (Set) para responder a cualquier campo PascalCase de la respuesta sin requerir update del código.
+**Binding:** [`DockerSwarm::Base#method_missing`](../../lib/docker_swarm/base.rb), [`DockerSwarm::Base.defined_attributes`](../../lib/docker_swarm/base.rb)
+
+### Spec deep_merge
+
+Estrategia de actualización parcial del campo `Spec` de un modelo. En vez de reemplazar Spec completo, `assign_attributes` hace `deep_merge` cuando la key es `Spec` y ambos valores son Hash. Razón: updates parciales no pierden campos anidados no tocados.
+**Binding:** [`DockerSwarm::Base#assign_attributes`](../../lib/docker_swarm/base.rb)
+
+### Version.Index
+
+Mecanismo de control de concurrencia optimista de Docker para updates atómicos. Cada Service/Node tiene `Version.Index` que incrementa en cada cambio. Update requiere enviar el index actual como query param; si no coincide, Docker rechaza (500). La gema lo extrae automáticamente en `Updatable#update`.
+**Binding:** [`DockerSwarm::Concerns::Updatable#update`](../../lib/docker_swarm/concerns/updatable.rb)
+
+### LogHelper
+
+Módulo de formateo de logs en KV (`key=value`) con masking automático de claves sensibles. La regex (`password|pass|passwd|secret|token|api_key|auth|\bdata\b`) reemplaza valores por `[FILTERED]`. `\bdata\b` evita falsos positivos en `metadata`/`database`.
+**Binding:** [`DockerSwarm::LogHelper`](../../lib/docker_swarm/log_helper.rb)
+
+### payload_for_docker
+
+Transformación interna que prepara un modelo para enviarlo al API: descarta atributos internos (`ID`/`Version`/`CreatedAt`/`UpdatedAt`), extrae el contenido de `Spec` al root y mergea otros campos top-level. Resultado: el payload que Docker espera para `create`/`update`.
+**Binding:** [`DockerSwarm::Base#payload_for_docker`](../../lib/docker_swarm/base.rb)
+
+## 3. Inferencias
+
+| Término | Inferencia | Confidence | Verificar |
+|---|---|---|---|
+| Container | "creación intencionalmente fuera de scope F1" | inferred | ¿se quiere documentar como decisión explícita o como gap a cubrir? |
+| Spec deep_merge | "razón: updates parciales no pierden campos" | declared | confirmado en CLAUDE.md decisión arquitectura |
+| Dynamic Accessor | "Docker evoluciona y agrega campos" | declared | confirmado en CLAUDE.md decisión arquitectura |
+
+## 4. Cobertura y fronteras
+
+- **Cobertura:** Completa para primitivas Docker (11) y conceptos arquitectónicos internos (9). Esta es una corrida inicial (sembrado autorizado, RFC-009).
+- **Frontera con Data Dictionary (RFC-002 §2.c r4):** la gema **no tiene capa de datos** (no DB, no `docs/data/`). Definiciones de columnas/atributos = `n/a`. Atributos PascalCase de Docker (`Spec`, `TaskTemplate`, etc.) son contrato de la API Docker, no del dominio de esta gema — no entran al glosario.
+- **Frontera con comportamiento:** flujos (create+reload, retry, error-mapping) viven en [`docs/behavior/behavior.md`](../behavior/behavior.md), no acá.
+- **Fuera de alcance:**
+  - Términos técnicos puros sin significado de negocio (ej: `instance_values`, `attr_accessor`) — son detalles de implementación, no contrato.
+  - Glossary del Docker Engine API (cómo funciona internamente Swarm, raft, gossip) — vive en docs de Docker, no se duplica acá.
+- **Cadencia:** incremental por PR a partir de acá; ausencia ≠ inexistencia (RFC-009).

data/lib/docker_swarm/base.rb

@@ -75,31 +75,23 @@ module DockerSwarm
 
     def assign_attributes(new_attributes)
       return if new_attributes.blank?
+      raise ArgumentError, "assign_attributes expects a Hash, got #{new_attributes.class}" unless new_attributes.is_a?(Hash)
 
-      attributes_to_assign = new_attributes.deep_dup
+      attributes_to_assign = new_attributes.deep_dup.with_indifferent_access
+      normalized_attributes = {}
 
-      if attributes_to_assign.is_a?(Hash)
-        attributes_to_assign = attributes_to_assign.with_indifferent_access
-        normalized_attributes = {}
+      attributes_to_assign.each do |key, value|
+        normalized_key = key.to_s == "Id" ? "ID" : key.to_s
+        _define_dynamic_accessor(normalized_key)
 
-        attributes_to_assign.each do |key, value|
-          normalized_key = key.to_s == "Id" ? "ID" : key.to_s
-          _define_dynamic_accessor(normalized_key)
-
-          if normalized_key == "Spec" && respond_to?(:Spec) && self.Spec.is_a?(Hash) && value.is_a?(Hash)
-            value = self.Spec.deep_merge(value)
-          end
-
-          normalized_attributes[normalized_key] = value
+        if normalized_key == "Spec" && respond_to?(:Spec) && self.Spec.is_a?(Hash) && value.is_a?(Hash)
+          value = self.Spec.deep_merge(value)
         end
 
-        super(normalized_attributes)
-      else
-        Array(attributes_to_assign).each do |item|
-          next unless item.is_a?(Hash)
-          item.each_key { |key| _define_dynamic_accessor(key) }
-        end
+        normalized_attributes[normalized_key] = value
       end
+
+      super(normalized_attributes)
     end
 
     def attributes

data/lib/docker_swarm/connection.rb

@@ -2,6 +2,10 @@
 
 module DockerSwarm
   class Connection
+    # HTTP methods safe to retry automatically. POST/PATCH are excluded because
+    # replaying after a partial failure can create duplicate resources.
+    IDEMPOTENT_METHODS = %i[get head put delete options].freeze
+
     attr_reader :socket_path, :logger
 
     def initialize(socket_path, logger)
@@ -16,14 +20,16 @@ module DockerSwarm
                 level: :debug,
                 data: options.merge(path: options[:path]))
 
-      # Combinar opciones por defecto de la gema con las de la petición
+      method = options[:method].to_s.downcase.to_sym
+      idempotent = IDEMPOTENT_METHODS.include?(method)
+
       request_options = {
-        idempotent: true,
+        idempotent: idempotent,
         retry_errors: [ Excon::Error::Socket, Excon::Error::Timeout ],
         read_timeout: DockerSwarm.configuration.read_timeout.to_f,
         write_timeout: DockerSwarm.configuration.write_timeout.to_f,
         connect_timeout: DockerSwarm.configuration.connect_timeout.to_f,
-        retries: DockerSwarm.configuration.max_retries.to_i
+        retries: idempotent ? DockerSwarm.configuration.max_retries.to_i : 0
       }.merge(options)
 
       response = client.request(request_options)
@@ -37,8 +43,8 @@ module DockerSwarm
       response.body
     rescue => e
       # Excon suele envolver excepciones de middleware en Excon::Error::Socket.
-      # Intentamos recuperar la causa original si es una de nuestras excepciones.
-      actual_error = (e.respond_to?(:cause) && e.cause&.class&.name&.include?("DockerSwarm::Error")) ? e.cause : e
+      # Recuperamos la causa original si es una excepción de DockerSwarm.
+      actual_error = e.cause.is_a?(::DockerSwarm::Error) ? e.cause : e
 
       log_event("request_failure",
                 level: :error,
@@ -48,9 +54,10 @@ module DockerSwarm
                   duration_s: calculate_duration(start_time)
                 ))
 
-      if actual_error.class.name.include?("DockerSwarm::Error")
+      case actual_error
+      when ::DockerSwarm::Error
         raise actual_error
-      elsif actual_error.is_a?(Excon::Error::Socket)
+      when Excon::Error::Socket
         raise ::DockerSwarm::Error::Communication, "Docker socket error: #{actual_error.message}"
       else
         raise actual_error

data/lib/docker_swarm/log_helper.rb

@@ -3,7 +3,9 @@
 module DockerSwarm
   # Helper module to centralize logging logic and formatting
   module LogHelper
-    SENSITIVE_KEYS = /password|token|api_key|auth|secret|data/i.freeze
+    # `data` se matchea con \b para que `Data` (Secret/Config) se filtre
+    # pero `metadata` u otras claves no caigan en falso positivo.
+    SENSITIVE_KEYS = /password|pass|passwd|secret|token|api_key|auth|\bdata\b/i.freeze
 
     # Formats a hash into a KV structured string with sensitive data masking
     # @param payload [Hash] The data to format

data/lib/docker_swarm/models/service.rb

@@ -8,5 +8,14 @@ module DockerSwarm
     include Concerns::Updatable
     include Concerns::Deletable
     include Concerns::Loggable
+
+    # Restarts the service by incrementing ForceUpdate, which causes
+    # Docker to recreate all tasks.
+    #
+    # @return [Boolean] true if the restart was triggered successfully
+    def restart
+      current = self.Spec&.dig("TaskTemplate", "ForceUpdate").to_i
+      update(Spec: { TaskTemplate: { ForceUpdate: current + 1 } })
+    end
   end
 end

data/lib/docker_swarm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DockerSwarm
-  VERSION = "0.5.4"
+  VERSION = "0.7.0"
 end

data/skill/SKILL.md

@@ -1,227 +1,174 @@
-# DockerSwarm Expert
-
-Skill de conocimiento completo sobre DockerSwarm. Consultame para cualquier pregunta sobre integración, arquitectura, API, errores y antipatrones.
-
-## Glosario
-
-**Base** — Clase ORM base que hereda de ActiveModel::Model. Provee accessors dinámicos PascalCase, `find`, `all`, `where`, `reload`, `payload_for_docker`. Todos los modelos heredan de ella.
-
-**Concern** — Mixin ActiveSupport::Concern que agrega comportamiento CRUD a un modelo: Creatable (POST), Updatable (POST con Version.Index), Deletable (DELETE), Loggable (logs streaming), Inspectable (#inspect legible). **Nota:** Los atributos dinámicos en Inspectable deben invocarse con `send(:ID)` para evitar `NameError` por interpretación como constante.
-
-**Middleware** — Capa Excon que procesa request/response: RequestEncoder (serialización body), ResponseJSONParser (parsing + indifferent access), ErrorHandler (status HTTP → excepción).
-
-**Deep Indifferent Access** — Toda respuesta JSON se convierte recursivamente a `HashWithIndifferentAccess`, permitiendo acceso por symbol o string en cualquier nivel de anidamiento.
-
-**Dynamic Accessor** — Cuando Docker devuelve un atributo nuevo (ej: `Spec`, `Status`), Base crea `attr_accessor` dinámicamente via `method_missing`. Se cachea en `defined_attributes` (Set) para no redefinir.
-
-**Version.Index** — Mecanismo de Docker para updates atómicos. Updatable extrae `Version["Index"]` y lo envía como query param para evitar race conditions.
-
-**LogHelper** — Módulo que formatea logs en KV (`key=value`) y enmascara campos sensibles matching `/password|token|api_key|auth|secret|data/i` → `[FILTERED]`.
-
-## Arquitectura
-
-### Responsabilidad core
-
-ORM ligero compatible con ActiveModel para Docker Engine API. Comunica via Excon sobre Unix socket (default) o TCP. Todos los requests pasan por una cadena de middlewares.
-
-### Mapa de componentes
-
-```
-┌──────────────┐     ┌──────────────┐     ┌──────────────┐
-│   Modelo     │────>│   Api        │────>│  Connection   │
-│  (Service,   │     │  (ENDPOINTS  │     │  (Excon +     │
-│   Node...)   │     │   + request) │     │   Timeouts)   │
-└──────────────┘     └──────────────┘     └──────────────┘
-                                                │
-                                                ▼
-                                    ┌───────────────────────┐
-                                    │   Middleware Stack     │
-                                    │  RequestEncoder       │
-                                    │  ResponseJSONParser   │
-                                    │  ErrorHandler         │
-                                    └───────────────────────┘
-```
-
-### Flujo en runtime
-
-1. Modelo invoca `Api.request(action:, arguments:, query_params:, payload:)`.
-2. Api formatea el path con `format()` y delega a `DockerSwarm.request`.
-3. Connection crea/reutiliza cliente Excon singleton con middlewares.
-4. RequestEncoder serializa body (JSON default, form-urlencoded, multipart).
-5. Excon envía al Docker daemon (socket o TCP).
-6. ResponseJSONParser parsea JSON y aplica `with_indifferent_access` recursivo.
-7. ErrorHandler mapea status 4xx/5xx a excepciones tipadas.
-8. Connection mide duración con `CLOCK_MONOTONIC` y loguea en KV.
-
-### Decisiones de diseño
-
-- **PascalCase fiel**: Los atributos mantienen el naming de Docker (`Spec`, `TaskTemplate`, `ContainerSpec`). No se transforman a snake_case.
-- **Spec merging**: `assign_attributes` hace `deep_merge` cuando el atributo es `Spec` para no perder campos anidados en updates.
-- **Singleton connection**: `@client ||= Excon.new(...)` — se reutiliza, se resetea al cambiar configuración.
-- **Retries en Excon**: `idempotent: true` + `retry_errors: [Socket, Timeout]` con `max_retries` configurable.
-
-## API Pública (resumen)
+---
+name: docker-swarm
+description: >-
+  ORM y cliente API Ruby para Docker Swarm. Expone las primitivas del Docker
+  Engine (Service, Node, Task, Container, Network, Volume, Config, Secret,
+  Swarm, System, Image) como modelos ActiveModel con CRUD, control de
+  concurrencia optimista (Version.Index), retries seguros por método HTTP,
+  logging KV con masking de secrets y jerarquía de errores tipada. ACTIVAR
+  cuando el caller necesita orquestar Docker desde Ruby — listar/crear/
+  actualizar/eliminar recursos del cluster, leer logs de services/tasks/
+  containers, hacer health-check del daemon (System.up/info/df), filtrar por
+  labels, o capturar errores tipados de Docker (Conflict/NotFound/
+  Communication). NO activar para builds de imágenes (no implementado), pull
+  con auth de registry privado (no implementado), o flujos que no son
+  Swarm (Docker Compose, raw containers).
+triggers:
+  - "DockerSwarm::"
+  - "docker-swarm gem"
+  - "Docker Engine API desde Ruby"
+  - "Service.create / Service.update / Service.restart"
+  - "Container.start / Container.stop"
+  - "logs de un servicio Docker"
+  - "Version.Index"
+---
+
+# docker-swarm — Skill
+
+## Qué es / cuándo usar
+
+Gema Ruby que provee ORM `ActiveModel`-compatible sobre Docker Engine API. Cliente HTTP `Excon` directo (Unix socket o TCP). Usá esta dep para orquestación programática de Docker Swarm: lifecycle de recursos, logs, health checks y observabilidad.
+
+No es:
+- Build/compose tool — no construye imágenes, no parsea `docker-compose.yml`.
+- Driver Kubernetes — sólo Swarm.
+
+## Contrato resumido (piso mínimo)
 
 ### Configuración
 
 ```ruby
 DockerSwarm.configure do |config|
-  config.socket_path     = "unix:///var/run/docker.sock"  # o http://host:port
+  config.socket_path     = "unix:///var/run/docker.sock"  # o "http://host:2375"
   config.logger          = Logger.new($stdout)
   config.log_level       = Logger::INFO
-  config.read_timeout    = 60.0    # segundos
+  config.read_timeout    = 60.0
   config.write_timeout   = 60.0
   config.connect_timeout = 10.0
   config.max_retries     = 3
 end
 ```
 
-### Operaciones comunes
-
-```ruby
-# Listar
-DockerSwarm::Service.all
-DockerSwarm::Service.all(label: ["app=web"])
-
-# Buscar
-service = DockerSwarm::Service.find("service_id")  # nil si no existe
-
-# Crear
-svc = DockerSwarm::Service.create(Name: "web", TaskTemplate: { ... })
-
-# Actualizar (maneja Version.Index automáticamente)
-service.update(Spec: { Replicas: 3 })
-
-# Eliminar (graceful con 404)
-service.destroy
-
-# Logs
-service.logs(stdout: 1, stderr: 1)
-
-# Sistema
-DockerSwarm::System.up       # ping
-DockerSwarm::System.info     # daemon info
-DockerSwarm::System.version  # versión Docker
-DockerSwarm::System.df       # disk usage
-DockerSwarm::Swarm.show      # info del cluster
-```
-
-Ver [API Detallada](references/api-detallada.md) para la referencia completa de todos los modelos.
+Defaults son razonables: en local sin TLS, no necesitás bloque `configure`.
 
-## FAQ
+### Símbolos públicos por modelo
 
-### Como conecto a un Docker remoto por TCP?
+| Modelo | Class methods | Instance methods | Notas |
+|---|---|---|---|
+| `Service` | `all(filters)`, `find(id)`, `where(filters)`, `create(attrs)` | `update(attrs)`, `restart`, `destroy`, `logs(query)`, `reload`, `persisted?`, `id` | CRUD completo + force-recreate de tasks |
+| `Node` | `all(filters)`, `find(id)`, `where(filters)` | `update(attrs)`, `destroy` | No `create` (los nodos se unen fuera de la gema) |
+| `Task` | `all(filters)`, `find(id)`, `where(filters)` | `logs(query)`, `reload` | Read-only (generados por orquestador) |
+| `Container` | `all(filters)`, `find(id)`, `where(filters)` | `start`, `stop`, `destroy`, `logs(query)` | **No `create`** (gap conocido, fuera F1) |
+| `Image` | `all(filters)`, `find(id)`, `create(attrs)` | `destroy` | `create` = pull. **No soporta `X-Registry-Auth`** (registries privados con auth no funcionan) |
+| `Network` | `all(filters)`, `find(id)`, `create(attrs)` | `update(attrs)`, `destroy` | CRUD completo |
+| `Volume` | `all(filters)`, `find(id)`, `create(attrs)` | `destroy` | No `update` (Docker no lo soporta). Respuesta wrapped vía `root_key = "Volumes"` |
+| `Config` | `all(filters)`, `find(id)`, `create(attrs)` | `destroy` | No `update` — recrear |
+| `Secret` | `all(filters)`, `find(id)`, `create(attrs)` | `destroy` | No `update`. `Data` se filtra en logs (LogHelper) |
+| `Swarm` | `.show` | — | Singleton, sólo info del cluster |
+| `System` | `.info`, `.version`, `.up`, `.df` | — | Singleton, health/observabilidad |
 
-```ruby
-DockerSwarm.configure do |config|
-  config.socket_path = "http://192.168.1.100:2375"
-end
-```
-Connection detecta si empieza con `unix://` (socket) o no (TCP) y configura Excon.
+Detalle por símbolo en [`docs/glossary/glossary.md`](docs/glossary/glossary.md). Secuencias de operación en [`docs/behavior/behavior.md`](docs/behavior/behavior.md).
 
-### Por qué los atributos son PascalCase y no snake_case?
-
-Docker Engine API usa PascalCase en todos sus JSON. La gema mantiene fidelidad 1:1 para evitar confusión al leer la documentación de Docker. Se accede igual: `service.Spec`, `node.Status`.
-
-### Como filtro recursos con labels?
+### Operaciones típicas
 
 ```ruby
-DockerSwarm::Service.all(label: ["env=production", "app=web"])
+# Listar con filtros (serializa como JSON en query param `filters`)
+DockerSwarm::Service.all(label: ["env=production"])
 DockerSwarm::Node.all(role: ["manager"])
-```
-Los filtros se serializan como JSON en el query param `filters` del Docker API.
+DockerSwarm::Container.all(status: ["running"])
 
-### Como manejo errores de conexión?
+# Lookup graceful (nil si 404)
+service = DockerSwarm::Service.find("svc-id")  # => Service | nil
 
-```ruby
-begin
-  DockerSwarm::System.up
-rescue DockerSwarm::Communication => e
-  # Socket caído o inalcanzable
-end
-```
-`Communication` envuelve errores de `Excon::Error::Socket`. Los retries se aplican automáticamente (`max_retries`).
+# Crear (auto-reload tras POST para hidratar Spec/Version completos)
+svc = DockerSwarm::Service.create(
+  Name: "web",
+  TaskTemplate: { ContainerSpec: { Image: "nginx:latest" } }
+)
 
-### Puedo usar validaciones de ActiveModel?
+# Update atómico (Version.Index extraído automáticamente)
+service.update(Mode: { Replicated: { Replicas: 3 } })
 
-Sí. Todos los modelos heredan de `ActiveModel::Model`. Podés agregar validaciones custom:
+# Force-recreate de tasks (equivalente a `docker service update --force`)
+service.restart
 
-```ruby
-service = DockerSwarm::Service.new(Name: "")
-service.valid?  # usa validaciones ActiveModel
-service.save    # retorna false si invalid?
-```
-
-## Antipatrones
-
-### Transformar atributos a snake_case
+# Destroy graceful (nil si 404)
+service.destroy
 
-```ruby
-# MAL
-service.task_template["container_spec"]
+# Logs raw
+service.logs(stdout: 1, stderr: 1)
 
-# BIEN
-service.TaskTemplate["ContainerSpec"]
+# Health check
+DockerSwarm::System.up        # => "OK" si daemon responde
 ```
-**Razón:** Docker API usa PascalCase. La gema mantiene fidelidad. Con indifferent access, podés usar strings o symbols, pero siempre PascalCase.
 
-### Reemplazar Spec en vez de mergear
+### Jerarquía de errores
+
+Todas heredan de `DockerSwarm::Error`. Tres formas de acceso equivalentes: `DockerSwarm::NotFound`, `DockerSwarm::Error::NotFound`, `DockerSwarm::Errors::NotFound`.
+
+| Excepción | Status | Cuándo |
+|---|---|---|
+| `BadRequest` | 400 | Payload malformado |
+| `Unauthorized` | 401 | TLS sin credenciales |
+| `Forbidden` | 403 | Permisos insuficientes (ej: swarm op en worker) |
+| `NotFound` | 404 | Recurso inexistente (capturado por `find`/`destroy`) |
+| `NotAcceptable` | 406 | Headers Accept incompatibles (raro) |
+| `RequestTimeout` | 408 | Daemon tardó (subí `read_timeout`) |
+| `Conflict` | 409 | Nombre duplicado o `Version.Index` stale |
+| `UnprocessableEntity` | 422 | Payload semánticamente inválido |
+| `TooManyRequests` | 429 | Rate limiting |
+| `InternalServerError` | 500 | Bug Docker o update sin `version` query param |
+| `BadGateway` | 502 | Proxy entre cliente y daemon falló |
+| `ServiceUnavailable` | 503 | Daemon reiniciando |
+| `GatewayTimeout` | 504 | Proxy timeout |
+| `Communication` | — | Socket caído / inalcanzable. `cause` mantiene el `Excon::Error` original |
+
+## Gotchas / breaking
+
+- **PascalCase fiel.** Los atributos NO se transforman: `service.Spec`, `service.TaskTemplate`, `service.Version` — no `snake_case`. Indifferent access soportado: `service.Spec[:Name]` ≡ `service.Spec["Name"]`.
+- **`Version.Index` obligatorio en updates** (Service/Node/Network). La gema lo extrae automático de `self.Version["Index"]`. Si construís el request por afuera (`DockerSwarm.request`), tenés que pasarlo vos.
+- **Retries automáticos sólo en métodos seguros** (GET/HEAD/PUT/DELETE/OPTIONS). POST/PATCH **no** reintentan para evitar duplicados — si el socket se cae durante un `create`, el caller decide qué hacer. Ver §3.5 de `docs/behavior/behavior.md`.
+- **`Spec` se mergea con `deep_merge` en updates**, no se reemplaza. Pasale sólo los campos que cambian: `service.update(Mode: {...})`, no `service.update(Spec: {...completo})`.
+- **`assign_attributes` muta antes de validar.** Si `update` falla por `valid?` o por el API, la instancia local quedó mutada. Hacé `reload` si necesitás estado limpio.
+- **`Container.create` no existe** en la gema (gap intencional F1). Si necesitás crear containers standalone, usá `DockerSwarm.request(method: :post, path: "containers/create", ...)` directo.
+- **Pull con registry privado no soportado.** `Image.create` no inyecta header `X-Registry-Auth`. Para registries privados, fallback a `DockerSwarm.request` con headers manuales.
+- **`destroy` es graceful con 404** (retorna `nil`), no con 409. Si el recurso está en uso, `Conflict` se propaga.
+- **Logs sensibles enmascarados** automáticamente: keys matching `password|pass|passwd|secret|token|api_key|auth|\bdata\b` → `[FILTERED]`. `\bdata\b` evita filtrar `metadata`/`database`.
+
+## Testing
+
+Mockear `DockerSwarm::Api.request`:
 
 ```ruby
-# MAL — pierde campos existentes del Spec
-service.update(Spec: { Mode: { Replicated: { Replicas: 5 } } })
+expect(DockerSwarm::Api).to receive(:request).with(
+  hash_including(action: DockerSwarm::Api::ENDPOINTS[:services][:show])
+).and_return({ "ID" => "svc-1", "Spec" => { "Name" => "web" }, "Version" => { "Index" => 1 } })
 
-# BIEN — mergear solo lo que cambia
-service.update(Mode: { Replicated: { Replicas: 5 } })
+service = DockerSwarm::Service.find("svc-1")
 ```
-**Razón:** `payload_for_docker` extrae contenido de Spec al root. Si pasás Spec completo, `assign_attributes` hace deep_merge, pero es más limpio pasar los campos directamente.
-
-### Ignorar Version.Index en updates
 
-```ruby
-# MAL — update manual sin version
-DockerSwarm.request(method: :post, path: "services/#{id}/update", body: payload)
-
-# BIEN — usar el modelo, maneja version automáticamente
-service.update(new_attrs)
-```
-**Razón:** Docker requiere `version` query param para updates atómicos. Updatable lo extrae de `self.Version["Index"]` automáticamente.
+Para `create`: mockear **dos** llamadas (POST + show de reload). Para errores: `and_raise(DockerSwarm::NotFound)` etc.
 
-### No capturar errores específicos
+## Integración (Rails)
 
 ```ruby
-# MAL
-begin
-  service.destroy
-rescue StandardError
-  # tragarse todo
-end
-
-# BIEN
-begin
-  service.destroy
-rescue DockerSwarm::NotFound
-  # ya fue eliminado, ok
-rescue DockerSwarm::Conflict => e
-  # servicio en uso
+# config/initializers/docker_swarm.rb
+DockerSwarm.configure do |config|
+  config.socket_path = ENV.fetch("DOCKER_URL", "unix:///var/run/docker.sock")
+  config.logger      = Rails.logger
+  config.log_level   = Rails.logger.level
 end
 ```
-**Razón:** La jerarquía de errores mapea cada status HTTP. Capturar errores específicos permite manejar cada caso.
-
-## Errores
 
-Los errores más comunes. Ver [Catálogo de Errores](references/errores.md) para la referencia completa.
+Logs salen en formato KV (`component=docker_swarm.connection event=request_success ...`) compatible con parsers estructurados.
 
-| Excepción | Status | Causa típica |
-|-----------|--------|--------------|
-| `NotFound` | 404 | Recurso eliminado o ID incorrecto |
-| `Conflict` | 409 | Nombre duplicado o recurso en uso |
-| `Communication` | — | Socket caído o inalcanzable |
-| `ServiceUnavailable` | 503 | Docker daemon reiniciando |
+## Índice de artefactos
 
-Todas heredan de `DockerSwarm::Error`. Se acceden como `DockerSwarm::NotFound` (alias) o `DockerSwarm::Error::NotFound`.
+- [`docs/glossary/glossary.md`](docs/glossary/glossary.md) — definición de términos (primitivas Docker + conceptos internos).
+- [`docs/behavior/behavior.md`](docs/behavior/behavior.md) — secuencias load-bearing (create+reload, update+Version, retry-policy, error-mapping, etc.).
+- `docs/data/` — `n/a` (gema sin DB).
+- `docs/api/`, `docs/interface/`, `docs/topology/` — F2 declaradas, **no implementadas**. El contrato resumido de arriba reside **transitoriamente** acá (RFC-008 §2 coexistencia transitoria con destino pendiente).
 
-## Referencias
+## Versionado del contrato
 
-- [API Detallada](references/api-detallada.md) — Referencia completa de modelos, concerns y métodos
-- [Catálogo de Errores](references/errores.md) — Todas las excepciones con causa y resolución
+Este SKILL.md viaja version-locked con el release de la gema (`gemspec.files` incluye `skill/**/*`). Para consumir desde otro proyecto: el agente lee `Gem.loaded_specs["docker-swarm"].gem_dir + "/skill/SKILL.md"`. Links relativos del paquete del release; no `HEAD`/branch.