claudient 0.1.0

package/skills/devops-infra/de/kubernetes.md

@@ -0,0 +1,129 @@
+> 🇩🇪 Dies ist die deutsche Übersetzung. [Englische Version](../kubernetes.md).
+
+# Kubernetes Skill
+
+## Wann aktivieren
+- Kubernetes-Manifeste schreiben (Deployments, Services, ConfigMaps, Secrets, Ingress)
+- Helm-Charts oder Values-Dateien für eine Anwendung konfigurieren
+- Einen fehlerhaften Pod, CrashLoopBackOff oder OOMKilled-Container debuggen
+- Horizontal Pod Autoscaling (HPA) oder Vertical Pod Autoscaling (VPA) einrichten
+- Ressourcenanforderungen und -limits für Container definieren
+- RBAC-Richtlinien schreiben oder prüfen (Roles, ClusterRoles, RoleBindings)
+- Liveness-, Readiness- und Startup-Probes einrichten
+- Persistente Volumes und Persistent Volume Claims konfigurieren
+- Netzwerkrichtlinien zur Steuerung des Pod-zu-Pod-Traffics schreiben
+- Namespaces und Multi-Tenant-Isolation einrichten
+
+## Wann NICHT verwenden
+- Docker Compose-Setups, die nicht nach Kubernetes migriert werden
+- Serverless (Cloud Run, Lambda, Fargate) — anderes Deployment-Modell
+- Einfache Single-Container-Apps, die keine Orchestrierung benötigen
+- Lokale Entwicklungsumgebungen, bei denen Docker allein ausreicht
+- Nomad, Mesos oder andere Nicht-Kubernetes-Orchestratoren
+
+## Anweisungen
+
+### Manifest-Struktur
+Diese Felder immer in jedem Deployment setzen:
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: app-name
+  namespace: production          # Immer explizit — niemals auf den Standard-Namespace verlassen
+  labels:
+    app: app-name
+    version: "1.0.0"
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: app-name
+  template:
+    metadata:
+      labels:
+        app: app-name
+        version: "1.0.0"
+    spec:
+      containers:
+        - name: app-name
+          image: registry/app-name:tag   # Niemals :latest in der Produktion verwenden
+          resources:
+            requests:
+              cpu: "100m"
+              memory: "128Mi"
+            limits:
+              cpu: "500m"
+              memory: "512Mi"
+```
+
+### Ressourcenanforderungen und -limits
+- Immer sowohl `requests` als auch `limits` setzen — niemals weglassen
+- `requests` = garantierte Ressourcen (werden für das Scheduling verwendet)
+- `limits` = maximal erlaubt (OOMKilled, wenn Speicher überschritten wird)
+- CPU-Limits sind in Clustern mit deaktivierter CPU-Drosselung optional — aber Speicher-Limits sind obligatorisch
+- Konservativ beginnen: requests bei ~25% des Erwarteten, limits bei 2x dem Erwarteten, dann mit tatsächlichen Metriken anpassen
+
+### Health-Probes
+Alle Produktions-Container müssen Probes haben:
+```yaml
+livenessProbe:
+  httpGet:
+    path: /healthz
+    port: 8080
+  initialDelaySeconds: 15
+  periodSeconds: 20
+  failureThreshold: 3
+
+readinessProbe:
+  httpGet:
+    path: /ready
+    port: 8080
+  initialDelaySeconds: 5
+  periodSeconds: 10
+  failureThreshold: 3
+```
+- `livenessProbe`-Fehler → Container-Neustart
+- `readinessProbe`-Fehler → aus dem Service-Load-Balancer entfernt (kein Traffic, kein Neustart)
+- Beide niemals auf denselben Endpunkt zeigen — Readiness sollte Abhängigkeiten prüfen, Liveness nicht
+
+### Secrets-Verwaltung
+- Niemals Secrets in ConfigMaps — Secrets verwenden
+- Niemals Secret-Manifeste mit echten Werten committen — sealed-secrets, external-secrets-operator oder Vault verwenden
+- Secrets als Umgebungsvariablen referenzieren, nicht als Volumes, außer die App benötigt dateibasierte Secrets:
+```yaml
+env:
+  - name: DATABASE_URL
+    valueFrom:
+      secretKeyRef:
+        name: app-secrets
+        key: database-url
+```
+
+### Namespace-Konventionen
+- `default`-Namespace: nur für Dev/Testing
+- Produktions-Workloads immer in benannten Namespaces
+- `ResourceQuota` und `LimitRange` auf jedem Produktions-Namespace verwenden
+- RBAC: Entwickler erhalten edit in Dev-Namespaces, view in der Produktion
+
+### Häufige CrashLoopBackOff-Ursachen und Lösungen
+1. Fehlende Umgebungsvariable → `kubectl describe pod` Events-Abschnitt prüfen
+2. Fehlgeschlagener Healthcheck → Logs zeigen den eigentlichen Fehler, Probe erkennt ihn nur
+3. OOMKilled → Speicher-Limit erhöhen oder Speicherleck beheben
+4. Image-Pull-Fehler → imagePullPolicy und Registry-Anmeldedaten prüfen
+5. Init-Container-Fehler → `kubectl logs pod-name -c init-container-name`
+
+## Beispiel
+
+**Benutzer:** Eine FastAPI-App mit PostgreSQL-Verbindung, 3 Replikas, Ressourcen-Limits und Health-Checks deployen.
+
+**Erwartete Ausgabestruktur:**
+- Namespace-Manifest
+- Secret für `DATABASE_URL`
+- Deployment mit 3 Replikas, Ressourcenanforderungen/-limits, Liveness + Readiness-Probes, die auf `/healthz` und `/ready` zeigen
+- Service (ClusterIP), der Port 80 → Container-Port 8080 exponiert
+- HorizontalPodAutoscaler mit 70% CPU-Auslastung als Ziel, min 3 / max 10 Replikas
+
+---
+
+> **Mit uns arbeiten:** Claudient wird von [Uitbreiden](https://uitbreiden.com/) unterstützt — wir bauen KI-Produkte und B2B-Lösungen mit Entwickler-Communities. Kubernetes-Infrastruktur oder cloud-native KI-Produkte aufbauen? [uitbreiden.com](https://uitbreiden.com/)

package/skills/devops-infra/de/terraform.md

@@ -0,0 +1,130 @@
+> 🇩🇪 Dies ist die deutsche Übersetzung. [Englische Version](../terraform.md).
+
+# Terraform Skill
+
+## Wann aktivieren
+- Terraform-Module für AWS-, GCP- oder Azure-Infrastruktur schreiben
+- VPCs, Subnetze, Sicherheitsgruppen und Netzwerkressourcen definieren
+- Compute-Ressourcen bereitstellen (EC2, GKE, AKS, ECS, Lambda)
+- Datenbank-Infrastruktur verwalten (RDS, Cloud SQL, Aurora)
+- IAM-Rollen, -Richtlinien und Service-Accounts einrichten
+- Remote-State-Konfiguration schreiben (S3-Backend, GCS, Terraform Cloud)
+- Bestehende Terraform-Konfiguration zur Modulnutzung umstrukturieren
+- CI/CD-Pipelines für `terraform plan` und `terraform apply` schreiben
+- Bestehende Infrastruktur in den Terraform-State importieren
+
+## Wann NICHT verwenden
+- Pulumi, CDK oder Crossplane — andere IaC-Tools, andere Muster
+- Helm-Chart-Konfiguration (stattdessen Kubernetes Skill verwenden)
+- Anwendungsspezifische Konfiguration (Kubernetes ConfigMaps, App-Umgebungsvariablen)
+- Einmalige CLI-Operationen, die nicht wiederholt werden
+
+## Anweisungen
+
+### Modulstruktur
+Jedes Terraform-Projekt muss dieser Struktur folgen:
+```
+infrastructure/
+├── modules/
+│   ├── networking/
+│   │   ├── main.tf
+│   │   ├── variables.tf
+│   │   ├── outputs.tf
+│   │   └── versions.tf
+│   └── compute/
+│       ├── main.tf
+│       ├── variables.tf
+│       └── outputs.tf
+├── environments/
+│   ├── production/
+│   │   ├── main.tf          ← ruft Module auf
+│   │   ├── variables.tf
+│   │   ├── terraform.tfvars
+│   │   └── backend.tf
+│   └── staging/
+│       └── ...
+└── versions.tf              ← Root-Provider-Versionen
+```
+
+### State-Verwaltung — immer remote
+```hcl
+# backend.tf
+terraform {
+  backend "s3" {
+    bucket         = "company-terraform-state"
+    key            = "production/networking/terraform.tfstate"
+    region         = "eu-west-1"
+    encrypt        = true
+    dynamodb_table = "terraform-state-lock"
+  }
+}
+```
+- Niemals lokalen State für gemeinsam genutzte Ressourcen verwenden
+- Verschlüsselung und State-Locking aktivieren (DynamoDB für S3-Backend)
+- Separate State-Dateien pro Umgebung und pro Modul (kein ein riesiger State)
+
+### Variablen- und Output-Disziplin
+```hcl
+# variables.tf — immer Beschreibung und Typ angeben
+variable "environment" {
+  description = "Deployment environment (production, staging, development)"
+  type        = string
+  validation {
+    condition     = contains(["production", "staging", "development"], var.environment)
+    error_message = "Environment must be production, staging, or development."
+  }
+}
+
+# outputs.tf — alles ausgeben, was ein konsumierendes Modul benötigen könnte
+output "vpc_id" {
+  description = "The ID of the VPC"
+  value       = aws_vpc.main.id
+}
+```
+
+### Secrets — niemals im State oder Code
+- Niemals Secrets in `terraform.tfvars` eintragen oder in `.tf`-Dateien hardcoden
+- `data "aws_secretsmanager_secret_version"` oder `data "google_secret_manager_secret_version"` verwenden, um Secrets zur Apply-Zeit zu lesen
+- Sensible Outputs: mit `sensitive = true` markieren, um sie in der Plan-Ausgabe zu unterdrücken
+- `.gitignore` muss enthalten: `*.tfvars`, `*.tfstate`, `*.tfstate.backup`, `.terraform/`
+
+### Ressourcen-Namenskonventionen
+```hcl
+# Konsistente Benennung: {project}-{environment}-{resource}-{suffix}
+resource "aws_vpc" "main" {
+  cidr_block = var.vpc_cidr
+  tags = {
+    Name        = "${var.project}-${var.environment}-vpc"
+    Environment = var.environment
+    ManagedBy   = "terraform"
+  }
+}
+```
+Jede Ressource immer mit `Environment` und `ManagedBy = "terraform"` taggen.
+
+### Plan vor Apply — immer
+- CI/CD-Pipeline: `terraform plan -out=tfplan` beim PR, `terraform apply tfplan` beim Merge
+- Niemals `terraform apply` ohne gespeicherten Plan in der Produktion ausführen
+- `-target` sparsam verwenden — es erzeugt Drift zwischen dem tatsächlichen State und dem Plan
+
+### Häufige Fallstricke
+- `terraform destroy` ohne `-target` zerstört alles — immer den Umfang bestätigen
+- Änderung eines Ressourcenattributs, das einen Ersatz erzwingt (z.B. VPC CIDR), löscht und erstellt neu — Plan sorgfältig prüfen
+- Provider-Versions-Pinning ist obligatorisch: `~> 5.0` verwenden, nicht `>= 5.0`
+- `count` vs `for_each`: `for_each` mit Maps verwenden — `count` verursacht Index-Drift wenn Elemente entfernt werden
+
+## Beispiel
+
+**Benutzer:** Ein Terraform-Modul für eine private RDS-PostgreSQL-Instanz auf AWS mit Multi-AZ, verschlüsseltem Speicher und einer dedizierten Sicherheitsgruppe erstellen.
+
+**Erwartete Ausgabestruktur:**
+- `modules/rds/main.tf` — `aws_db_instance`, `aws_db_subnet_group`, `aws_security_group`
+- `modules/rds/variables.tf` — Instance-Klasse, Engine-Version, DB-Name, VPC/Subnet-IDs, Ingress-CIDR
+- `modules/rds/outputs.tf` — Endpunkt, Port, Sicherheitsgruppen-ID
+- Sicherheitsgruppe: erlaubt PostgreSQL (5432) nur von der App-Sicherheitsgruppe, kein öffentlicher Zugang
+- `storage_encrypted = true`, `multi_az = true`, `deletion_protection = true` für die Produktion
+- Passwort über `aws_secretsmanager_secret`-Referenz, niemals hartcodiert
+
+---
+
+> **Mit uns arbeiten:** Claudient wird von [Uitbreiden](https://uitbreiden.com/) unterstützt — wir bauen KI-Produkte und B2B-Lösungen mit Entwickler-Communities. Cloud-Infrastruktur oder IaC-Pipelines aufbauen? [uitbreiden.com](https://uitbreiden.com/)

package/skills/devops-infra/docker.md

@@ -0,0 +1,131 @@
+# Docker Skill
+
+## When to activate
+- Writing or optimizing Dockerfiles for production
+- Setting up multi-stage builds to reduce image size
+- Writing Docker Compose files for local development
+- Debugging container startup failures or layer cache issues
+- Configuring non-root users, health checks, and image security
+- Setting up .dockerignore for efficient builds
+- Writing build scripts or CI/CD Docker build pipelines
+
+## When NOT to use
+- Kubernetes manifests (use the Kubernetes skill)
+- Buildpacks (Heroku, Cloud Native Buildpacks) — different build system
+- Virtual machine provisioning (different abstraction level)
+- Nix-based reproducible builds
+
+## Instructions
+
+### Production Dockerfile structure
+Always use multi-stage builds for compiled languages and Node.js:
+
+```dockerfile
+# Stage 1: Build
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+
+# Stage 2: Runtime — minimal image
+FROM node:20-alpine AS runtime
+RUN addgroup -S appgroup && adduser -S appuser -G appgroup
+WORKDIR /app
+COPY --from=builder /app/node_modules ./node_modules
+COPY . .
+USER appuser
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD wget -qO- http://localhost:8080/healthz || exit 1
+CMD ["node", "server.js"]
+```
+
+### Security rules
+- Never run as root in production — always create and switch to a non-root user
+- Never use `latest` tag — pin to a specific version or digest
+- Prefer Alpine or distroless base images over full Debian/Ubuntu
+- Never copy `.env` files into the image — pass secrets as runtime env vars
+- Scan images with `docker scout` or Trivy before pushing to production
+
+### Layer caching optimization
+Order Dockerfile instructions from least-to-most frequently changing:
+1. Base image (changes rarely)
+2. System dependencies (`apt-get`, `apk add`)
+3. Package manager files (`package.json`, `requirements.txt`)
+4. Package install (`npm ci`, `pip install`)
+5. Application code (`COPY . .`) — changes most often, must be last
+
+### .dockerignore — always include
+```
+node_modules/
+.git/
+.env
+.env.*
+*.md
+Dockerfile*
+docker-compose*
+.dockerignore
+coverage/
+.nyc_output/
+__pycache__/
+*.pyc
+.pytest_cache/
+```
+
+### Docker Compose for local development
+```yaml
+services:
+  app:
+    build:
+      context: .
+      target: builder          # Use build stage, not runtime stage locally
+    volumes:
+      - .:/app                 # Hot reload
+      - /app/node_modules      # Don't overwrite container node_modules
+    ports:
+      - "8080:8080"
+    environment:
+      - NODE_ENV=development
+    depends_on:
+      db:
+        condition: service_healthy
+
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: app
+      POSTGRES_PASSWORD: dev_password   # Dev only — never production
+      POSTGRES_DB: appdb
+    ports:
+      - "5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U app -d appdb"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+volumes:
+  postgres_data:
+```
+
+### Common build failures
+- `COPY` fails silently if source doesn't exist — check `.dockerignore` isn't excluding needed files
+- Layer cache invalidated unexpectedly — check if a `COPY` before install steps is pulling in changed files
+- Permission denied at runtime — check file ownership when using `COPY --from` with a non-root user
+
+## Example
+
+**User:** Write a production Dockerfile for a Python FastAPI app with multi-stage build, non-root user, and health check.
+
+**Expected output:**
+- Stage 1 (builder): `python:3.12-slim`, install dependencies with `pip install --no-cache-dir`
+- Stage 2 (runtime): `python:3.12-slim`, non-root user, copy only wheels/deps from builder + app code
+- `HEALTHCHECK` hitting `/healthz` endpoint
+- `CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]`
+- `.dockerignore` covering `__pycache__`, `.env`, `.git`, `*.pyc`
+
+---
+
+> **Work with us:** Claudient is backed by [Uitbreiden](https://uitbreiden.com/) — we build AI products and B2B solutions with developer communities. Containerizing AI workloads or building cloud-native systems? [uitbreiden.com](https://uitbreiden.com/)

package/skills/devops-infra/es/docker.md

@@ -0,0 +1,133 @@
+> 🇪🇸 Esta es la traducción en español. [Versión en inglés](../docker.md).
+
+# Skill de Docker
+
+## Cuándo activar
+- Escribir u optimizar Dockerfiles para producción
+- Configurar builds multi-etapa para reducir el tamaño de la imagen
+- Escribir archivos Docker Compose para desarrollo local
+- Depurar fallos de inicio de contenedores o problemas de caché de capas
+- Configurar usuarios no-root, health checks y seguridad de imágenes
+- Configurar .dockerignore para builds eficientes
+- Escribir scripts de build o pipelines de CI/CD para builds de Docker
+
+## Cuándo NO usar
+- Manifiestos de Kubernetes (usar el skill de Kubernetes)
+- Buildpacks (Heroku, Cloud Native Buildpacks) — sistema de build diferente
+- Aprovisionamiento de máquinas virtuales (nivel de abstracción diferente)
+- Builds reproducibles basados en Nix
+
+## Instrucciones
+
+### Estructura del Dockerfile de producción
+Siempre usa builds multi-etapa para lenguajes compilados y Node.js:
+
+```dockerfile
+# Etapa 1: Build
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+
+# Etapa 2: Runtime — imagen mínima
+FROM node:20-alpine AS runtime
+RUN addgroup -S appgroup && adduser -S appuser -G appgroup
+WORKDIR /app
+COPY --from=builder /app/node_modules ./node_modules
+COPY . .
+USER appuser
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD wget -qO- http://localhost:8080/healthz || exit 1
+CMD ["node", "server.js"]
+```
+
+### Reglas de seguridad
+- Nunca ejecutes como root en producción — siempre crea y cambia a un usuario no-root
+- Nunca uses la etiqueta `latest` — fija a una versión o digest específico
+- Prefiere imágenes base Alpine o distroless sobre Debian/Ubuntu completo
+- Nunca copies archivos `.env` en la imagen — pasa los secretos como variables de entorno en tiempo de ejecución
+- Escanea las imágenes con `docker scout` o Trivy antes de enviar a producción
+
+### Optimización de caché de capas
+Ordena las instrucciones del Dockerfile de menos a más frecuentemente cambiante:
+1. Imagen base (cambia raramente)
+2. Dependencias del sistema (`apt-get`, `apk add`)
+3. Archivos del gestor de paquetes (`package.json`, `requirements.txt`)
+4. Instalación de paquetes (`npm ci`, `pip install`)
+5. Código de la aplicación (`COPY . .`) — cambia con más frecuencia, debe ser el último
+
+### .dockerignore — siempre incluir
+```
+node_modules/
+.git/
+.env
+.env.*
+*.md
+Dockerfile*
+docker-compose*
+.dockerignore
+coverage/
+.nyc_output/
+__pycache__/
+*.pyc
+.pytest_cache/
+```
+
+### Docker Compose para desarrollo local
+```yaml
+services:
+  app:
+    build:
+      context: .
+      target: builder          # Usa la etapa de build, no la de runtime, localmente
+    volumes:
+      - .:/app                 # Hot reload
+      - /app/node_modules      # No sobreescribir node_modules del contenedor
+    ports:
+      - "8080:8080"
+    environment:
+      - NODE_ENV=development
+    depends_on:
+      db:
+        condition: service_healthy
+
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: app
+      POSTGRES_PASSWORD: dev_password   # Solo dev — nunca producción
+      POSTGRES_DB: appdb
+    ports:
+      - "5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U app -d appdb"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+volumes:
+  postgres_data:
+```
+
+### Fallos comunes de build
+- `COPY` falla silenciosamente si el origen no existe — verifica que `.dockerignore` no esté excluyendo archivos necesarios
+- Caché de capas invalidada inesperadamente — verifica si un `COPY` antes de los pasos de instalación está incluyendo archivos cambiados
+- Permiso denegado en tiempo de ejecución — verifica la propiedad de archivos al usar `COPY --from` con un usuario no-root
+
+## Ejemplo
+
+**Usuario:** Escribir un Dockerfile de producción para una aplicación Python FastAPI con build multi-etapa, usuario no-root y health check.
+
+**Salida esperada:**
+- Etapa 1 (builder): `python:3.12-slim`, instalar dependencias con `pip install --no-cache-dir`
+- Etapa 2 (runtime): `python:3.12-slim`, usuario no-root, copiar solo wheels/deps del builder + código de la app
+- `HEALTHCHECK` apuntando al endpoint `/healthz`
+- `CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]`
+- `.dockerignore` cubriendo `__pycache__`, `.env`, `.git`, `*.pyc`
+
+---
+
+> **Trabaja con nosotros:** Claudient está respaldado por [Uitbreiden](https://uitbreiden.com/) — construimos productos de IA y soluciones B2B con comunidades de desarrolladores. ¿Contenedorizando cargas de trabajo de IA o construyendo sistemas cloud-native? [uitbreiden.com](https://uitbreiden.com/)

package/skills/devops-infra/es/github-actions.md

@@ -0,0 +1,179 @@
+> 🇪🇸 Esta es la traducción en español. [Versión en inglés](../github-actions.md).
+
+# Skill de GitHub Actions
+
+## Cuándo activar
+- Escribir pipelines de CI/CD para test, lint, build y deploy
+- Configurar builds en matrix para múltiples SO o versiones de lenguaje
+- Configurar reglas de protección de entornos y puertas de despliegue
+- Escribir workflows reutilizables o acciones compuestas
+- Configurar build y push de Docker a un registro de contenedores
+- Configurar autenticación OIDC a proveedores cloud (sin secretos de larga duración)
+- Depurar workflows fallidos o entender errores de sintaxis de workflow
+- Configurar caché para dependencias (npm, pip, módulos de Go)
+
+## Cuándo NO usar
+- GitLab CI, CircleCI, Jenkins — sistemas de pipeline diferentes
+- Automatización de desarrollo local (usar Makefile o scripts)
+- Cron jobs que no están vinculados a un repositorio (usar cloud scheduler)
+
+## Instrucciones
+
+### Estructura del archivo de workflow
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Permisos explícitos — nunca usar write-all por defecto
+permissions:
+  contents: read
+  pull-requests: write    # Solo si es necesario (p.ej., publicar comentarios)
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm test
+```
+
+### Permisos — siempre explícitos
+Nunca uses `permissions: write-all` por defecto. Siempre declara los permisos mínimos requeridos:
+```yaml
+permissions:
+  contents: read          # Leer el repo
+  packages: write         # Push a GitHub Container Registry
+  id-token: write         # OIDC para autenticación cloud
+  pull-requests: write    # Comentar en PRs
+```
+
+### Secretos — OIDC sobre credenciales de larga duración
+Usa OIDC (OpenID Connect) para autenticación cloud — sin secretos almacenados:
+
+```yaml
+# AWS OIDC — no se necesita AWS_ACCESS_KEY_ID
+- name: Configure AWS credentials
+  uses: aws-actions/configure-aws-credentials@v4
+  with:
+    role-to-assume: arn:aws:iam::123456789:role/github-actions-role
+    aws-region: eu-west-1
+
+# GCP OIDC
+- name: Authenticate to GCP
+  uses: google-github-actions/auth@v2
+  with:
+    workload_identity_provider: projects/123/locations/global/workloadIdentityPools/pool/providers/github
+    service_account: deploy@project.iam.gserviceaccount.com
+```
+
+### Caché de dependencias
+Siempre cachea las dependencias para reducir el tiempo de build:
+```yaml
+# Node.js
+- uses: actions/setup-node@v4
+  with:
+    node-version: '20'
+    cache: 'npm'          # Caché integrado — no se necesita paso de caché manual
+
+# Python
+- uses: actions/setup-python@v5
+  with:
+    python-version: '3.12'
+    cache: 'pip'
+
+# Go
+- uses: actions/setup-go@v5
+  with:
+    go-version: '1.22'
+    cache: true
+```
+
+### Puertas de entorno para despliegues de producción
+```yaml
+jobs:
+  deploy-production:
+    environment: production    # Referencia al Entorno de GitHub con reglas de protección
+    needs: [test, build]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy
+        run: ./scripts/deploy.sh
+```
+
+Configura las reglas de protección de entornos en los ajustes de GitHub:
+- Revisores requeridos para despliegues de producción
+- Temporizador de espera entre staging y producción
+- Restringir a ramas específicas (solo `main`)
+
+### Builds en matrix
+```yaml
+jobs:
+  test:
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+        os: [ubuntu-latest, windows-latest]
+      fail-fast: false    # No cancelar todo ante el primer fallo
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+```
+
+### Workflows reutilizables
+```yaml
+# .github/workflows/deploy.yml — reutilizable
+on:
+  workflow_call:
+    inputs:
+      environment:
+        required: true
+        type: string
+    secrets:
+      deploy-token:
+        required: true
+
+# Llamador
+jobs:
+  deploy:
+    uses: ./.github/workflows/deploy.yml
+    with:
+      environment: production
+    secrets:
+      deploy-token: ${{ secrets.DEPLOY_TOKEN }}
+```
+
+### Fallos comunes
+- `actions/checkout@v4` faltante — siempre debe ser el primer paso
+- Los secretos no son accesibles en forks — usa `pull_request_target` con cuidado (riesgo de seguridad)
+- La caché no se utiliza — la clave debe coincidir exactamente; usa `restore-keys` como alternativa
+- OIDC falla — verifica que la política de confianza en el proveedor cloud permita el repositorio y la rama
+
+## Ejemplo
+
+**Usuario:** Escribir un pipeline de CI/CD para una aplicación Node.js: ejecutar tests en PRs, construir y enviar imagen Docker al hacer merge en main, desplegar a producción con una puerta de aprobación manual.
+
+**Salida esperada:**
+- Triggers `on: push/pull_request`
+- Job `test`: checkout, setup-node con caché, `npm ci`, `npm test`
+- Job `build` (en push a main, necesita test): build + push de Docker a GHCR usando OIDC
+- Job `deploy`: `environment: production` (requiere aprobación), llama al script de deploy
+- Bloque `permissions:` explícito — mínimo requerido
+- Sin secretos hardcodeados — OIDC para autenticación del registro
+
+---
+
+> **Trabaja con nosotros:** Claudient está respaldado por [Uitbreiden](https://uitbreiden.com/) — construimos productos de IA y soluciones B2B con comunidades de desarrolladores. ¿Construyendo CI/CD para productos de IA o despliegues cloud? [uitbreiden.com](https://uitbreiden.com/)