theus-cli-linux-x64 0.2.84

package/vendor/theus-arsenal/skills/modelos-fundacionales-en-dispositivo/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: modelos-fundacionales-en-dispositivo
+description: Framework FoundationModels de Apple para LLM en dispositivo — generación de texto,
+  generación guiada con @Generable, tool calling y streaming por snapshots en iOS 26+.
+---
+
+# FoundationModels: LLM en dispositivo (iOS 26)
+
+Patrones para integrar el modelo de lenguaje en dispositivo de Apple en apps usando el framework FoundationModels. Cubre generación de texto, salida estructurada con `@Generable`, tool calling personalizado y streaming por snapshots — todo ejecutado en el dispositivo, con privacidad y soporte offline.
+
+## Cuándo usarla
+
+- Construir funcionalidades de IA con Apple Intelligence en dispositivo
+- Generar o resumir texto sin dependencia de la nube
+- Extraer datos estructurados de lenguaje natural
+- Implementar tool calling personalizado para acciones de IA específicas del dominio
+- Hacer streaming de respuestas estructuradas para UI en tiempo real
+- Necesidad de IA que preserve la privacidad (ningún dato sale del dispositivo)
+
+## Patrón base — comprobación de disponibilidad
+
+Comprueba siempre la disponibilidad del modelo antes de crear una sesión:
+
+```swift
+struct GenerativeView: View {
+    private var model = SystemLanguageModel.default
+
+    var body: some View {
+        switch model.availability {
+        case .available:
+            ContentView()
+        case .unavailable(.deviceNotEligible):
+            Text("Dispositivo no compatible con Apple Intelligence")
+        case .unavailable(.appleIntelligenceNotEnabled):
+            Text("Activa Apple Intelligence en Ajustes")
+        case .unavailable(.modelNotReady):
+            Text("El modelo se está descargando o no está listo")
+        case .unavailable(let other):
+            Text("Modelo no disponible: \(other)")
+        }
+    }
+}
+```
+
+## Patrón base — sesión básica
+
+```swift
+// Turno único: crea una sesión nueva cada vez
+let session = LanguageModelSession()
+let response = try await session.respond(to: "¿Cuál es un buen mes para visitar París?")
+print(response.content)
+
+// Multi-turno: reutiliza la sesión para mantener el contexto de la conversación
+let session = LanguageModelSession(instructions: """
+    Eres un asistente de cocina.
+    Sugiere recetas según los ingredientes disponibles.
+    Mantén las sugerencias breves y prácticas.
+    """)
+
+let first = try await session.respond(to: "Tengo pollo y arroz")
+let followUp = try await session.respond(to: "¿Y una opción vegetariana?")
+```
+
+Puntos clave para las instrucciones:
+- Define el rol del modelo ("Eres un mentor")
+- Especifica qué hacer ("Ayuda a extraer eventos de calendario")
+- Fija preferencias de estilo ("Responde lo más breve posible")
+- Añade medidas de seguridad ("Responde 'No puedo ayudar con eso' ante peticiones peligrosas")
+
+## Patrón base — generación guiada con @Generable
+
+Genera tipos Swift estructurados en lugar de strings crudos:
+
+### 1. Define un tipo Generable
+
+```swift
+@Generable(description: "Información básica de perfil de un gato")
+struct CatProfile {
+    var name: String
+
+    @Guide(description: "La edad del gato", .range(0...20))
+    var age: Int
+
+    @Guide(description: "Un perfil de una frase sobre la personalidad del gato")
+    var profile: String
+}
+```
+
+### 2. Solicita salida estructurada
+
+```swift
+let response = try await session.respond(
+    to: "Genera un gato rescatado adorable",
+    generating: CatProfile.self
+)
+
+// Accede a los campos estructurados directamente
+print("Nombre: \(response.content.name)")
+print("Edad: \(response.content.age)")
+print("Perfil: \(response.content.profile)")
+```
+
+### Restricciones de @Guide soportadas
+
+- `.range(0...20)` — rango numérico
+- `.count(3)` — número de elementos de un array
+- `description:` — guía semántica para la generación
+
+## Patrón base — tool calling
+
+Permite que el modelo invoque código propio para tareas del dominio:
+
+### 1. Define una Tool
+
+```swift
+struct RecipeSearchTool: Tool {
+    let name = "recipe_search"
+    let description = "Busca recetas que coincidan con un término y devuelve una lista de resultados."
+
+    @Generable
+    struct Arguments {
+        var searchTerm: String
+        var numberOfResults: Int
+    }
+
+    func call(arguments: Arguments) async throws -> ToolOutput {
+        let recipes = await searchRecipes(
+            term: arguments.searchTerm,
+            limit: arguments.numberOfResults
+        )
+        return .string(recipes.map { "- \($0.name): \($0.description)" }.joined(separator: "\n"))
+    }
+}
+```
+
+### 2. Crea la sesión con tools
+
+```swift
+let session = LanguageModelSession(tools: [RecipeSearchTool()])
+let response = try await session.respond(to: "Encuéntrame recetas de pasta")
+```
+
+### 3. Maneja errores de las tools
+
+```swift
+do {
+    let answer = try await session.respond(to: "Busca una receta de sopa de tomate.")
+} catch let error as LanguageModelSession.ToolCallError {
+    print(error.tool.name)
+    if case .databaseIsEmpty = error.underlyingError as? RecipeSearchToolError {
+        // Manejar el error específico de la tool
+    }
+}
+```
+
+## Patrón base — streaming por snapshots
+
+Haz streaming de respuestas estructuradas para UI en tiempo real con los tipos `PartiallyGenerated`:
+
+```swift
+@Generable
+struct TripIdeas {
+    @Guide(description: "Ideas para próximos viajes")
+    var ideas: [String]
+}
+
+let stream = session.streamResponse(
+    to: "¿Qué ideas de viaje emocionantes se te ocurren?",
+    generating: TripIdeas.self
+)
+
+for try await partial in stream {
+    // partial: TripIdeas.PartiallyGenerated (todas las propiedades Optional)
+    print(partial)
+}
+```
+
+### Integración con SwiftUI
+
+```swift
+@State private var partialResult: TripIdeas.PartiallyGenerated?
+@State private var errorMessage: String?
+
+var body: some View {
+    List {
+        ForEach(partialResult?.ideas ?? [], id: \.self) { idea in
+            Text(idea)
+        }
+    }
+    .overlay {
+        if let errorMessage { Text(errorMessage).foregroundStyle(.red) }
+    }
+    .task {
+        do {
+            let stream = session.streamResponse(to: prompt, generating: TripIdeas.self)
+            for try await partial in stream {
+                partialResult = partial
+            }
+        } catch {
+            errorMessage = error.localizedDescription
+        }
+    }
+}
+```
+
+## Decisiones de diseño clave
+
+| Decisión | Razón |
+|----------|-------|
+| Ejecución en dispositivo | Privacidad — ningún dato sale del dispositivo; funciona offline |
+| Límite de 4 096 tokens | Restricción del modelo en dispositivo; trocea datos grandes entre sesiones |
+| Streaming por snapshots (no deltas) | Amigable con la salida estructurada; cada snapshot es un estado parcial completo |
+| Macro `@Generable` | Seguridad en compilación para generación estructurada; autogenera el tipo `PartiallyGenerated` |
+| Una petición por sesión | `isResponding` impide peticiones concurrentes; crea varias sesiones si hace falta |
+| `response.content` (no `.output`) | API correcta — accede siempre a los resultados vía la propiedad `.content` |
+
+## Buenas prácticas
+
+- **Comprueba siempre `model.availability`** antes de crear una sesión — maneja todos los casos de no disponibilidad
+- **Usa `instructions`** para guiar el comportamiento del modelo — tienen prioridad sobre los prompts
+- **Comprueba `isResponding`** antes de enviar una nueva petición — las sesiones atienden una petición a la vez
+- **Accede a `response.content`** para los resultados — no a `.output`
+- **Trocea las entradas grandes** — el límite de 4 096 tokens aplica a instrucciones + prompt + salida combinados
+- **Usa `@Generable`** para salida estructurada — garantías más fuertes que parsear strings crudos
+- **Usa `GenerationOptions(temperature:)`** para ajustar la creatividad (más alto = más creativo)
+- **Monitorea con Instruments** — usa Instruments de Xcode para perfilar el rendimiento de las peticiones
+
+## Antipatrones a evitar
+
+- Crear sesiones sin comprobar antes `model.availability`
+- Enviar entradas que exceden la ventana de contexto de 4 096 tokens
+- Intentar peticiones concurrentes en una misma sesión
+- Usar `.output` en lugar de `.content` para acceder a la respuesta
+- Parsear respuestas de string crudo cuando la salida estructurada con `@Generable` funcionaría
+- Meter lógica multi-paso compleja en un solo prompt — divide en prompts enfocados
+- Asumir que el modelo siempre está disponible — la elegibilidad del dispositivo y los ajustes varían
+
+## Cuándo aplica
+
+- Generación de texto en dispositivo para apps sensibles a la privacidad
+- Extracción de datos estructurados de la entrada del usuario (formularios, comandos en lenguaje natural)
+- Funcionalidades asistidas por IA que deben funcionar offline
+- UI de streaming que muestra progresivamente el contenido generado
+- Acciones de IA del dominio vía tool calling (búsqueda, cómputo, consulta)

package/vendor/theus-arsenal/skills/modo-seguro/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: modo-seguro
+description: Usa esta skill para prevenir operaciones destructivas al trabajar sobre sistemas en producción o al ejecutar agentes de forma autónoma.
+---
+
+# Modo seguro — Prevención de operaciones destructivas
+
+## Cuándo usarla
+
+- Al trabajar sobre sistemas en producción
+- Cuando los agentes corren de forma autónoma (modo totalmente automático)
+- Cuando quieres restringir las ediciones a un directorio específico
+- Durante operaciones sensibles (migraciones, despliegues, cambios de datos)
+
+## Cómo funciona
+
+Tres modos de protección:
+
+### Modo 1: Modo cuidadoso
+
+Intercepta comandos destructivos antes de su ejecución y advierte:
+
+```
+Patrones vigilados:
+- rm -rf (especialmente /, ~ o la raíz del proyecto)
+- git push --force
+- git reset --hard
+- git checkout . (descartar todos los cambios)
+- DROP TABLE / DROP DATABASE
+- docker system prune
+- kubectl delete
+- chmod 777
+- sudo rm
+- npm publish (publicaciones accidentales)
+- Cualquier comando con --no-verify
+```
+
+Cuando lo detecta: el hook bloquea el comando y el motivo (en stderr) explica qué hace el comando y sugiere una alternativa más segura.
+
+### Modo 2: Modo congelado
+
+Bloquea las ediciones de archivos a un árbol de directorios específico:
+
+```
+/modo-seguro congelar src/components/
+```
+
+Cualquier Write/Edit fuera de `src/components/` se bloquea con una explicación. Útil cuando quieres que un agente se concentre en un área sin tocar código no relacionado.
+
+### Modo 3: Modo guardián (cuidadoso + congelado combinados)
+
+Ambas protecciones activas. Seguridad máxima para agentes autónomos.
+
+```
+/modo-seguro guardian --dir src/api/ --allow-read-all
+```
+
+Los agentes pueden leer cualquier cosa, pero solo escribir en `src/api/`. Los comandos destructivos se bloquean en todas partes.
+
+### Desbloquear
+
+```
+/modo-seguro off
+```
+
+## Implementación
+
+La aplicación de las reglas la hace el hook `scripts/hooks/modo-seguro.js`, registrado en `hooks/hooks.json` como PreToolUse con matcher `Bash|Write|Edit`. En cada llamada, el hook lee el archivo de estado; si `mode` es `off` o el archivo no existe, permite todo. Con `cuidadoso` bloquea los patrones destructivos listados arriba; con `congelado` bloquea Write/Edit fuera del directorio configurado; con `guardian` aplica ambas protecciones. Un bloqueo se comunica con exit 2 y el motivo en stderr, para que el modelo reciba el porqué como feedback; el mensaje va en español, y cada acción bloqueada queda registrada en `~/.theus/arsenal/modo-seguro.log`.
+
+El estado del modo activo se guarda en `~/.theus/arsenal/modo-seguro.json`:
+
+```json
+{
+  "mode": "guardian",
+  "dir": "src/api/",
+  "allowReadAll": true,
+  "updatedAt": "2026-07-16T00:00:00Z"
+}
+```
+
+## Integración
+
+- Actívalo por defecto en sesiones autónomas donde los permisos están en modo automático
+- Combínalo con la skill `verificacion-factual`: el modo seguro bloquea lo destructivo; la compuerta factual exige evidencia antes de editar
+- El hook registra todas las acciones bloqueadas en `~/.theus/arsenal/modo-seguro.log`
+- El comando `/modo-seguro` activa/desactiva los modos y consulta el estado actual