@iaforged/context-code 2.0.9 → 2.1.0

package/docs/MULTI_PROVIDER.md

@@ -1,201 +0,0 @@
-## Sistema multi-proveedor y multi-perfil
-
-Context Code ya funciona con una capa de proveedores mas flexible. La idea base es separar:
-
-- el `provider` como backend de inferencia
-- el `provider profile` como perfil guardado dentro de ese proveedor
-- el `agentName` como nombre operativo pensado para futuros subagentes
-
-### Provider profile
-
-Un `provider profile` es una configuracion persistida para un proveedor concreto. Sirve para guardar datos que quieres recordar por separado, por ejemplo:
-
-- base URL
-- ultimo modelo usado
-- credenciales o token, cuando el proveedor lo soporta
-
-El nombre del perfil es el identificador humano que ves en el comando. El `agentName` es el nombre tecnico que queda preparado para el futuro sistema de subagentes. Por ejemplo:
-
-```sh
-/provider ollama profile local
-```
-
-Puede guardar un perfil llamado `local` con un `agentName` del estilo `ollama-local`.
-
-### Comando `/provider`
-
-El comando `/provider` ahora sirve para cambiar de proveedor y tambien para activar un perfil concreto.
-
-```sh
-/provider
-/provider list
-/provider ollama
-/provider zai profile main
-/provider ollama profile local
-```
-
-Comportamiento de `/provider`:
-
-- `/provider` (sin argumentos) abre el selector interactivo de proveedores.
-- `/provider list` muestra una tabla detallada con todos tus proveedores, perfiles guardados, estado de conexión (Conectado/Desconectado) y perfiles activos.
-- `/provider <proveedor>` cambia al proveedor especificado.
-- `/provider <proveedor> profile <nombre>` activa (o crea) un perfil específico para ese proveedor.
-- `/provider <proveedor> <URL>` cambia la Base URL del proveedor (ej. `/provider ollama http://localhost:11434/v1`).
-- `/provider <proveedor> clear` restaura la URL por defecto del proveedor.
-
-Tambien existe `/profile` para inspeccionar y navegar perfiles ya guardados:
-
-```sh
-/profile
-/profile list
-/profile current
-/profile use ollama local
-/profile rename ollama local gpu-lab
-/profile model ollama gpu-lab llama3.2
-/profile model ollama gpu-lab clear
-/profile agent ollama gpu-lab ollama-lab
-/profile remove all
-/profile remove ollama gpu-lab
-```
-
-Comportamiento de `/profile`:
-
-- `/profile` o `/profile list` muestra todos los perfiles guardados por proveedor.
-- `/profile current` muestra el perfil activo.
-- `/profile use <proveedor> <perfil>` activa el perfil y restaura su ultimo modelo si existe.
-- `/profile rename <proveedor> <actual> <nuevo>` renombra el perfil.
-- `/profile model <proveedor> <perfil> <modelo>` corrige o fija el ultimo modelo guardado para ese perfil.
-- `/profile model <proveedor> <perfil> clear` limpia el modelo guardado.
-- `/profile agent <proveedor> <perfil> <agentName>` cambia el nombre tecnico del perfil para futuros subagentes.
-- `/profile remove <proveedor> <perfil>` elimina el perfil.
-- `/profile remove all` elimina todos los perfiles guardados de una sola vez.
-
-Notas importantes:
-
-- El nombre visible del perfil y el `agentName` no son lo mismo.
-- El nombre visible sirve para navegar con `/provider ... profile ...` o `/profile use ...`.
-- `agentName` queda reservado como identificador operativo para el futuro sistema de subagentes.
-- Al renombrar un perfil, sus credenciales por perfil tambien se mueven al nuevo identificador para no perder API keys u OAuth.
-- Al borrar un perfil, tambien se limpian sus credenciales scoped cuando existen.
-- `/profile remove all` limpia todos los perfiles y sus credenciales scoped asociadas, pero no toca los fallbacks legacy de compatibilidad.
-
-Comportamiento esperado:
-
-- `/provider` abre la seleccion de proveedor.
-- `/provider <proveedor>` cambia al proveedor activo.
-- `/provider <proveedor> profile <nombre>` selecciona o crea ese perfil y lo deja activo.
-- La configuracion de ese perfil se reutiliza la proxima vez que vuelvas al mismo proveedor o perfil.
-
-Despues de activar un perfil, puedes seguir ajustando sus valores con los comandos normales del proveedor:
-
-```sh
-/provider ollama http://localhost:11434/v1
-/provider ollama clear
-/provider list
-/model
-```
-
-### Soporte Multi-cuenta real
-
-Context Code permite gestionar múltiples cuentas del mismo proveedor (como varias cuentas de Claude o OpenAI) de forma independiente.
-
-```sh
-/login --profile personal
-/login --profile trabajo
-```
-
-- Al usar el flag `--profile` (o `-p`), las credenciales se guardan específicamente en ese perfil.
-- El sistema detecta automáticamente si el perfil ya existe o crea uno nuevo.
-- Puedes saltar entre cuentas fácilmente usando `/provider claude profile personal` o listarlas todas con `/provider list`.
-
-### Persistencia por perfil
-
-La persistencia queda separada por perfil cuando el proveedor lo soporta.
-
-- `base URL` queda guardada por perfil.
-- `ultimo modelo` queda guardado por perfil.
-- `credenciales` quedan guardadas por perfil cuando aplica, incluyendo OAuth y API keys.
-- Si no existe un perfil nuevo, el sistema intenta reutilizar o migrar la configuracion vieja para no romper instalaciones existentes.
-
-### SQLite autogenerable
-
-La metadata de proveedores y perfiles ahora se apoya en una base SQLite autogenerable:
-
-- archivo: `~/.context/provider-state.sqlite3`
-- se crea sola al arrancar si no existe
-- si hay configuracion legacy previa, puede migrarla con `/profile migrate`
-- en Windows/Linux, las credenciales de proveedores tambien se almacenan en esta misma DB
-- esas credenciales se guardan cifradas localmente antes de persistirse en `secure_storage`
-
-Que se guarda ahi:
-
-- perfiles por proveedor
-- perfil activo
-- proveedor activo
-- ultimo modelo por proveedor
-- estado runtime necesario para restaurar contexto rapido
-- API keys, tokens OAuth y credenciales scoped por perfil, mediante la tabla `secure_storage`
-- el contenido de `secure_storage.value` ya no queda en JSON legible; se cifra localmente antes de escribirse
-
-Migracion de credenciales:
-
-- si existe `~/.context/.credentials.json`, se importa automaticamente a SQLite la primera vez que se lee el storage seguro
-- si la importacion termina bien, el archivo legacy `.credentials.json` se elimina para evitar dos fuentes de verdad
-- en macOS se mantiene el flujo de keychain con fallback, segun el backend disponible
-
-Estado actual:
-
-- Windows/Linux ya trabajan en modo `SQLite-only` para providers, perfiles, modelos, base URLs y credenciales
-- `/status` y `/profile migrate` muestran si el runtime quedo completamente migrado
-- macOS sigue usando keychain/fallback por diseno; esa ruta queda fuera de esta migracion
-
-### Proveedores actuales
-
-Estos son los proveedores visibles hoy y su estado general:
-
-- `Claude (Anthropic)`: usa OAuth y ahora puede resolver sesion por perfil, manteniendo fallback al storage anterior.
-- `OpenAI / Codex`: usa OAuth por perfil con compatibilidad hacia atras.
-- `OpenRouter`: usa API key y endpoint configurable por perfil.
-- `Ollama Local`: ya trabaja con perfiles; no usa API key y guarda base URL y modelo por perfil.
-- `Ollama Cloud`: usa endpoint configurable y queda alineado con la capa de perfiles.
-- `Z.AI`: ya trabaja con perfiles; guarda API key, base URL y modelo por perfil.
-- `MiniMax`: usa API key y endpoint compatible con Anthropic por perfil.
-
-### Compatibilidad hacia atras
-
-La migracion esta pensada para no romper la configuracion anterior:
-
-- los valores anteriores pueden servir de base para crear el perfil por defecto durante la migracion inicial
-- `/profile migrate` limpia el remanente legacy cuando la DB ya quedo consistente
-- en Windows/Linux el objetivo final ya es `SQLite-only`
-
-### Notas de uso
-
-- `Ollama` esta pensado como backend local, con el default en `http://localhost:11434/v1`.
-- `Z.AI` requiere API key por perfil y es el primer proveedor no local con soporte real de perfiles.
-- `Claude`, `OpenAI`, `OpenRouter`, `MiniMax` y `Ollama Cloud` ya resuelven su estado desde la arquitectura nueva con fallback a la configuracion anterior.
-- El comando `/model` sigue existiendo y ahora debe entenderse junto con el perfil activo.
-
-## Datos guardados en SQLite
-
-La base se crea automaticamente en:
-
-```text
-~/.context/provider-state.sqlite3
-```
-
-Ademas de perfiles y credenciales de providers, ahi se guardan:
-
-- `provider_workspaces`: proveedores disponibles para equipos
-- `provider_agents`: agentes por proveedor/perfil
-- `provider_agent_capabilities`: capacidades declaradas de agentes
-- `teams`: equipos
-- `team_units`: equipos internos dentro de un team
-- `team_unit_members`: miembros de cada equipo interno
-- `orchestration_runs`: ejecuciones
-- `orchestration_tasks`: tareas
-- `orchestration_messages`: bitacora de decisiones y eventos
-- `orchestration_task_results`: resultados por tarea
-- `orchestration_team_reports`: reportes por equipo interno
-- `orchestration_run_reports`: reporte consolidado de una ejecucion
-- `secure_storage`: credenciales cifradas y configuracion sensible de providers, Telegram y WhatsApp en Windows/Linux