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`.

```json
{
  "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`.

```json
{
  "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:

```json
{
  "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](referencia-entorno) para excepciones y valores concretos.