# Codex Suite · Guía de Control (cuándo / cómo / por qué)

> Corte: **8 de agosto de 2026**.  
> Complementa [CODEX-SUITE-MANUAL.md](CODEX-SUITE-MANUAL.md). Este documento es la referencia operativa de **todos** los apartados del panel Control.

## 0. Honestidad sobre la verificación

| Tipo de prueba | Qué cubre | Estado 8 ago |
|---|---|---|
| API smoke autenticado `tools/smoke-codex-control.mjs` | Lecturas/escrituras HTTP de las superficies Control (threads, catálogo, MCP install, plugins 409, seguridad, lab, vecinas, events window, settings, diagnostics, evidence, twin, contracts, deploy, persistence) | Revalidar tras cambios |
| Tests Node `npm test` | Contratos de UI, rutas, persistencia, installs | Revalidar con `npm test` |
| Clic UI exhaustivo de cada botón en navegador | Cada acción destructiva/confirmación de cada pestaña | **No ejecutado al 100%** en esta sesión; los menús existen y cargan datos vía las APIs anteriores |
| Apps Server live (plugins remotos con API key) | Install NVIDIA del catálogo OpenAI | **Limitación real**: exige ChatGPT; con API key → 409 claro |

Conclusión: **sé que las APIs de Control responden**; no afirmo haber pulsado manualmente cada botón de cada submenú. Para revalidar:

```powershell
cd C:\xampp\htdocs\cursor-mobile-bridge
node tools/smoke-codex-control.mjs c-xampp-htdocs-chatbot
npm test
```

---

## 1. Mapa del hub Control

Cuatro grupos → **diecisiete** pestañas:

| Grupo | Pestañas | Propósito en una frase |
|---|---|---|
| **Operar** | Acciones, Comandos /, Eventos | Actuar sobre el hilo actual sin salir del chat |
| **Proyecto** | Recursos, Proyecto, Catálogo, Complementos | Capacidades e integraciones del workspace |
| **Calidad** | Modelos, Misiones, Contratos, Staging, Gemelo | Evidencia, router FCC y gates antes de aceptar cambios |
| **Sistema** | Seguridad, Lab IA, Claves, Freemodel, Privado/Composer (flag), Vecinas, Ajustes, Pruebas | Host, fabric del `.16`, vault write-only, índice Composer operador, apps hermanas y diagnósticos |

---

## 2. Ficha por pestaña (cuándo / cómo / por qué)

### 2.1 Operar → Acciones

- **Cuándo:** quieres adjuntar rutas, cambiar permisos del próximo turno, compactar, renombrar o recuperar un turno atascado.
- **Cómo:** abre Control con un proyecto y conversación activos; las acciones sensibles piden confirmación.
- **Por qué:** concentra operaciones del hilo sin mezclarlas con configuración global.
- **Verificación:** runtime + checkpoints del thread en smoke; UI enlazada a `control.js` / `chat.js`.

### 2.2 Operar → Comandos /

- **Cuándo:** no recuerdas un slash (`/permissions`, `/compact`, etc.) o quieres descubrir equivalentes.
- **Cómo:** busca en el catálogo; al elegir, se inserta o ejecuta según soporte (`native` / `workflow` / `host`).
- **Por qué:** evita memorizar; documenta qué es real de App Server y qué es del host.
- **API:** `GET /api/codex/commands`.

### 2.3 Operar → Eventos

- **Cuándo:** un turno “parece parado”, hay aprobaciones o quieres auditar la secuencia.
- **Cómo:** mira el feed en vivo; combina con la franja de watchdog del compositor. Tras reconexión, el cliente envía `since` + `clientId`; si el lag es `stale`/`reset`, se recupera estado automáticamente.
- **Por qué:** transparencia operativa sin exponer razonamiento privado; el log durable (1.2) permite replay acotado.
- **APIs:** SSE `GET /api/codex/events`, `GET /api/codex/events/window`, `GET /api/codex/events/cursors`.

### 2.4 Proyecto → Recursos

- **Cuándo:** necesitas ver modelos, skills, MCP, plugins, hooks y perfiles que App Server anuncia **ahora**.
- **Cómo:** selecciona proyecto → Recursos → refrescar.
- **Por qué:** es la fuente de verdad de capacidades anunciadas; el Catálogo es descubrimiento externo.
- **API:** `GET /api/codex/capabilities?workspace=…`.

### 2.5 Proyecto → Proyecto (workspace)

- **Cuándo:** quieres áreas multi-carpeta, memoria del proyecto o `AGENTS.md`.
- **Cómo:** define áreas confinadas al path del workspace; guarda `AGENTS.md` con confirmación `SAVE_AGENTS`.
- **Por qué:** contexto persistente sin salir del sandbox del proyecto.

### 2.6 Proyecto → Catálogo

- **Cuándo:** descubrir MCP públicos (mcp.so remotos) o instalar plugins de marketplaces Codex.
- **Cómo MCP:** abrir ficha → si hay HTTPS del proveedor se rellena; instalar escribe `.codex/config.toml` del **proyecto**.
- **Cómo plugins:** con API key, el catálogo remoto OpenAI puede devolver **409 ChatGPT**; plugins en caché local se pueden habilitar.
- **Por qué:** instalación gobernada, sin inventar endpoints.
- **APIs:** `/api/codex/mcp-marketplace`, `/mcp/install`, `/plugins/detail`, `/plugins/install`.

### 2.7 Proyecto → Complementos

- **Cuándo:** quieres capacidades nativas de Codex Suite (calidad PHP/JS, deploy, secretos…) ligadas al stack detectado.
- **Cómo:** revisa puntuación → habilitar por workspace (no es VSIX).
- **Por qué:** recomendaciones por proyecto sin instalar extensiones IDE.
- **API:** `GET /api/codex/complements?workspace=…` (+ deploy en la misma área).

### 2.8 Calidad → Modelos

- **Cuándo:** elegir/probar modelos vía **FCC** (`127.0.0.1:8082`) o activar router automático del proyecto.
- **Cómo:** “Comprobar catálogos” (sin tokens) · “Probar proveedores/modelo” (consume cuota) · “Usar en conversaciones nuevas” escribe `fcc_local` en `config.toml` de Codex.
- **Por qué:** separar catálogo barato/local/remoto del proveedor `freemodel` por defecto.
- **Fuente de datos:** `C:\Users\Paterna\.fcc\.env` + `codex-model-catalog.json` + admin FCC `/admin`.
- **API:** `GET /api/codex/model-router`.

### 2.9 Calidad → Misiones

- **Cuándo:** revisar evidencias de turnos del proyecto (archivos, aprobaciones, fallos).
- **Cómo:** filtra por conversación actual si hace falta; abre una misión para la secuencia.
- **Por qué:** accountability sin dumps de prompts.
- **API:** `GET /api/codex/evidence?workspace=…`.

### 2.10 Calidad → Contratos

- **Cuándo:** fijar objetivo, criterios y pruebas obligatorias **de una conversación**.
- **Cómo:** requiere thread activo; confirma criterios; se inyecta en turnos siguientes.
- **Por qué:** reduce ambigüedad en trabajos largos.
- **API:** `/api/codex/threads/:id/contract`.

### 2.11 Calidad → Staging

- **Cuándo:** antes de aceptar cambios de un checkpoint, quieres preflight local no ejecutable.
- **Cómo:** necesita thread + checkpoint con archivos pendientes; confirmación exacta de la UI.
- **Por qué:** atrapa secretos/rutas raras antes del accept.
- **Nota:** depende de haber generado checkpoint tras un turno con cambios.

### 2.12 Calidad → Gemelo

- **Cuándo:** fotografiar el estado técnico/operativo del workspace para comparar después.
- **Cómo:** crear snapshot → seleccionar en el desplegable → ver diff vs anterior.
- **Por qué:** continuidad entre sesiones sin Git sano (el repo local aún no es recuperable por commits).
- **API:** `GET/POST /api/codex/workspace-twin`.

### 2.13 Sistema → Seguridad

- **Cuándo:** auditoría de solo lectura (hardening bridge, firewall, Defender, hallazgos del proyecto, Docker remoto).
- **Cómo:** “Actualizar diagnóstico”; no cambia configuración del equipo.
- **Por qué:** visibilidad de riesgo sin side-effects.
- **API:** `GET /api/codex/security?workspace=…`.

### 2.14 Sistema → Lab IA

- **Cuándo:** quieres ver si el fabric del servidor IA (`.16`) responde: Supervisor, Ollama, Qdrant, Baileys/Evolution y FCC local/remoto.
- **Cómo:** Control → Sistema → Lab IA → “Actualizar lab”. Solo lectura; estados `up|timeout|unreachable|unconfigured|degraded`.
- **Por qué:** Codex Suite debe consumir el lab como backend observable, sin absorber CaptaJaus/Ops.
- **API:** `GET /api/codex/lab/status`, `GET /api/codex/lab/wave16`, `GET /api/codex/lab/fcc-plane`.
- **Límite:** Evolution/Baileys/FCC Docker remoto pueden quedar `timeout`/`unconfigured` hasta despliegue operador; opcionales `LAB_*_HTTP_URL` y `FCC_REMOTE_BASE_URL`.

### 2.14a Sistema → Claves APIs

- **Cuándo:** guardar varias API keys con segunda contraseña, sin revelar secretos.
- **Cómo:** bootstrap/unlock → añadir alias/proveedor/secreto → activar (escribe `auth.json` para freemodel/openai) → auditoría sin valores.
- **Por qué:** vault profesional write-only; SEC-16 sigue retirado.
- **API:** `/api/codex/keys/*`.
- **Límite:** activar no recarga terminales ya iniciados; hace falta reinicio o protocolo propio.

### 2.14b Sistema → Privado / Composer (operador)

- **Cuándo:** diagnosticar overlap Composer↔`agent-transcripts` en esta máquina.
- **Cómo:** requiere `CODEX_COMPOSER_PRIVATE=1`. Control → Sistema → Privado / Composer.
- **Por qué:** metadatos SQLite de Cursor son privados; no se productizan. **Nunca** escribe `state.vscdb`.
- **API:** `GET /api/codex/private/composer-index?workspace=…`.
- **Límite:** chats Composer sin JSONL no son ejecutables; WAL puede fallar con Cursor abierto.

### 2.15 Sistema → Vecinas

- **Cuándo:** CaptaJaus, ALimpiezas, bridge, etc. comparten host y quieres inventario/preflight/rollback de catálogo.
- **Cómo:** inventario → preflight (env sin secretos) → verify → acciones con rollback.
- **Por qué:** reinicios del bridge no deben tumbar vecinas a ciegas.
- **API:** `/api/codex/neighbors/*`.

### 2.16 Sistema → Ajustes

- **Cuándo:** tema, densidad, permiso por defecto, proveedores públicos de `config.toml`, AGENTS.md, Policy Studio.
- **Cómo:** previsualizar diff Suite/TOML → Guardar; rollback solo Suite con confirmación `ROLLBACK_SETTINGS`.
- **Por qué:** preferencias de producto sin filtrar secretos; cambios auditables.
- **API:** `GET/PUT /api/codex/settings`, `/settings/schema|effective|preview|revisions|rollback|scopes`, `PUT /admin/config`.

### 2.16b Concurrencia / actividad background

- **Cuándo:** PWA y escritorio (o dos pestañas) revisan el mismo checkpoint, o cambias de proyecto con turns vivos en otro.
- **Cómo:** la UI envía `expectedRevision` al aceptar/rechazar; si otro cliente ya decidió o el disco cambió, verás aviso 409 y debes recargar la revisión. El banner de actividad background lista turns/aprobaciones de otros workspaces sin cancelarlos.
- **Por qué:** evita doble accept/reject silencioso y deja visible el trabajo en segundo plano.
- **API:** `GET /api/codex/activity/background?excludeWorkspace=…`, `POST .../checkpoints/:id/decision` con `expectedRevision`.

### 2.17 Sistema → Pruebas

- **Cuándo:** tras un deploy o sospecha de sesión/CORS/bootstrap.
- **Cómo:** ejecuta el paquete de diagnósticos del bridge (POST).
- **Por qué:** smoke interno sin depender del navegador del operador.
- **API:** `POST /api/codex/diagnostics`.

---

## 3. ¿Cómo sé qué modelo se está usando?

Hay **tres capas** (no las confundas):

| Capa | Dónde se mira | Qué significa |
|---|---|---|
| **Predeterminado Codex** | `C:\Users\Paterna\.codex\config.toml` → `model_provider` + `model` | Hoy verificado: `freemodel` / `gpt-5.6-sol` |
| **Selección del compositor** | Desplegable Modelo + motor (Codex / Cursor) | Vacío = automático/router o predeterminado |
| **Efectivo del turno** | Chip bajo la respuesta del asistente + barra `execution-status` | `Modelo: … · Proveedor: … · Selección: automática/manual` persistido en turn metadata |

FCC (`http://127.0.0.1:8082/admin`) lista el **proxy multi-proveedor** local. Su `MODEL=` en `.fcc/.env` es el default del propio FCC (hoy `nvidia_nim/...`), **no** sustituye automáticamente el `config.toml` de Codex hasta que pulses **Usar en conversaciones nuevas** (activa `fcc_local`).

Flujo típico:

1. Control → Modelos → comprobar/probar candidato FCC.  
2. Activar → se escribe proveedor `fcc_local` → `http://127.0.0.1:8082/v1`.  
3. Abrir **conversación nueva**.  
4. Enviar mensaje → en la respuesta ver `provider: fcc_local` y el slug efectivo.

---

## 4. Relación con herramientas del home del usuario

Carpetas relevantes del `dir` de `C:\Users\Paterna` (no migrar a ciegas):

| Carpeta | Rol respecto a Codex Suite / lab |
|---|---|
| `.codex` | Runtime Codex CLI (config, sessions, plugins cache) |
| `.fcc` | Proxy de modelos :8082 + catálogo + `.env` de proveedores |
| `.cursor` | IDE Cursor + transcripts |
| `.claude` / `.copilot` | Otros agentes; no son el control plane Codex Suite |
| `.serena` | MCP Serena (edición simbólica) |
| `.lmstudio` | Modelos locales vía LM Studio (`LM_STUDIO_BASE_URL`) |
| `.pm2` | Procesos Node de negocio local (captajaus, etc.) |

---

## 5. Mantenimiento de esta guía

Si se añade una pestaña a `CONTROL_GROUPS` en `static/codex-suite/modules/control.js`, actualizar:

1. Esta guía (sección 1–2).  
2. `tools/smoke-codex-control.mjs` con al menos un GET/POST.  
3. Una sección breve en el MANUAL.  
4. `CODEX-SUITE-STATUS.md` inventario.