Archivos de configuración

Los archivos describen conexiones y extensiones. Las credenciales viven aparte; la casa decide qué configuración puede guardarse y activarse.

Perfiles de proveedor

El archivo predeterminado es .comal/providers.json. Puedes indicar otro con --providers-config o COMAL_PROVIDERS_CONFIG.

{
  "version": 1,
  "defaultProfile": "residente",
  "profiles": {
    "residente": { "provider": "openai", "baseURL": "http://llama.local:11438/" },
    "codex": { "authProvider": "codex", "effort": "auto" },
    "visual": {
      "provider": "openai",
      "baseURL": "https://ollama.com/v1",
      "model": "minimax-m3",
      "apiKeyEnv": "COMAL_OLLAMA_KEY",
      "capabilities": { "vision": true }
    }
  }
}

apiKeyEnv es el nombre de una variable, nunca el valor. capabilities admite booleanos para text, tools, thinking, vision, video y web_search dentro del soporte del adaptador. Los campos desconocidos se rechazan; una capacidad declarada no implementa por sí misma un transporte.

Servidores MCP

El archivo predeterminado es .mcp.json del workspace. Un servidor stdio declara command/args; los remotos pueden declarar url, type (http, streamable-http o sse) y autenticación mediante headersEnv.

{
  "mcpServers": {
    "remoto": { "url": "https://tu-servidor.example/mcp", "type": "http" }
  }
}

Es una URL ilustrativa: sustitúyela por tu servidor. Recargar configuración no amplía automáticamente la autorización para invocar herramientas.

Plugins y skills

Plugins: <directorio de estado>/plugins.json, o --plugin-config. Las rutas de módulo son relativas a ese JSON. Cargar código local requiere autorización explícita.

Skills: .comal/skills/NOMBRE/SKILL.md. El archivo compañero opcional skill.json solicita un alcance tipado:

{
  "allowed_tools": ["Read", "FileInfo"],
  "effort": "low",
  "context": "inline"
}

El effort debe estar anunciado por el modelo. context:"fork" usa un hijo explore con ese techo de herramientas. El host restaura controles y préstamos al terminar, fallar o abortar; después de una muerte de proceso los recupera antes de la siguiente inferencia. El scope también restringe dependencias anidadas; no concede permiso por nombrar una operación compuesta.

Se leen también skills legadas de .harness, con preferencia por .comal. /NOMBRE tarea aplica una skill del proyecto; su contenido no concede permisos.

Estado y compatibilidad

Workspaces nuevos guardan en .comal/. Si existe .harness/ y no existe .comal/, Comal reutiliza el estado anterior. Si hay ambos, gana .comal/; --state-dir .harness permite elegir el anterior.

La compatibilidad de nombres no renombra la carpeta ni mueve libros. Usa el mismo workspace y directorio de estado para reanudar un UUID. HARNESS_* sigue como alias de COMAL_*, que tiene prioridad. Consulta variables para excepciones y valores concretos.