Documentación: framework vs plugins¶

Principio¶

El framework no conoce plugins de dominio ni decide qué panels de negocio existen. Descubre paquetes instalados por entry points (cortex.plugins, cortex.panels), ensambla lo que el state store activa y materializa namespaces cuando un plugin habilitado aporta módulos (contributes_panels, register_resources).

No hay imports ni listas hardcodeadas de plugins de dominio (booking, clients, billing, …) en cortex_framework.

El framework sí conoce mecanismos de plataforma (no dominio):

Mecanismo	Rol
Bootstrap de `control`	Panel de plataforma siempre activo
Namespaces generativos (`operations`, `admin`, `samples`)	Shells vacíos materializados con `ensure_panel()`
Entry points `cortex.plugins` / `cortex.panels`	Discovery y `configure_panel` opcional para namespaces dedicados

Los panel_id de negocio (p. ej. accounting, trainer) emergen de plugins habilitados, no de un catálogo fijo del framework. Los namespaces generativos (operations, admin) se materializan con ensure_panel() al registrar módulos. Ver ADR 004, ADR 011 y Namespaces y paneles.

La documentación sigue la misma frontera:

Capa	Qué documenta	Dónde vive
Arquitectura	Visión, taxonomía dependiente/independiente, mapa del sistema	`docs/arquitectura/`
Infraestructura	Stack, despliegue, CI, variables de entorno	`docs/infraestructura/`
Ingeniería	Plataforma core/framework, Cortex Panel runtime	`docs/ingenieria/`, `docs/guias/cortex-panel.md`
Plugins	Handbook, directorio por plugin, SPI	`docs/plugins/`, `docs/guias/plugins/`
Caso de uso ensamblado	Grafo, bundles pip, convenciones de panel de un vertical	`docs/casos-de-uso/`
Plugin (dominio)	API REST, eventos, integraciones, pantallas CUS	`docs/plugins/<id>/` en cortex-docs (fuente única)

Catálogo de plugins¶

Sección en pestaña propia Plugins: principios, ingeniería de plugins, directorio por plugin, arquitectura SPI y requisitos. Los ADR de plataforma describen mecanismos; la spec de cada dominio vive en Plugins (ver ADR 008).

La pestaña Ingeniería documenta la plataforma (core, framework, panel runtime) para maintainers — no el handbook de plugins.

flowchart LR
  subgraph platform [cortex-docs plataforma]
    FW[Framework y guías genéricas]
    IDX[ADRs de plataforma]
    CAT[docs/plugins/id]
  end
  subgraph casoUso [casos-de-uso/reservas sandbox PMV]
    PR[Composición UnoSportClub]
  end
  CAT -->|cita hooks del framework| FW
  CAT -->|cita requires del producto| PR
  FW -.->|no documenta detalle de booking| CAT
  PR -.->|enlaza a docs del sitio| CAT

El framework documenta mecanismos (register_resources, register_listeners, namespaces de panel, /control/plugins). No describe reglas de negocio de booking, billing ni similares.
Cada plugin documenta su propio comportamiento en docs/plugins/<id>/ y puede referenciar utilidades del framework y contratos del producto que lo incluya.

Estructura canónica de documentación de plugin¶

docs/plugins/<id>/
├── index.md          # ex README.md del repo
├── design.md         # opcional
├── api.md
├── dependencies.md
├── events.md         # opcional
├── ui.md
└── operations.md

Los repos cortex-plugin-* mantienen solo un docs/README.md de redirección al sitio público.

Rol de `cortex-docs`¶

Contenido	Ubicación canónica
Cómo crear un plugin (getting started, hooks genéricos)	`docs/guias/plugins/`
Principios y directorio de plugins first-party	`docs/plugins/`
Comportamiento detallado de un dominio	`docs/plugins/<id>/`
ADRs de plataforma (multi-panel, activación, IO)	`docs/adr/`
Grafo y contratos HTTP de un caso de uso (ej. Reservas)	`docs/casos-de-uso/`
Stub en handbook → enlace al producto	`docs/guias/plugins/dependency-contracts.md`

Publicación¶

Sitio público (docs.cortex-ia.com.co): build de cortex-docs (plataforma + directorio de plugins).
Repos plugin: código + docs/README.md con enlace al sitio.

Verificación en PR de plugin¶

Cambios de API o eventos → actualizar docs/plugins/<id>/ en cortex-docs (mismo PR o PR coordinado en monorepo).
Nuevas dependencias en un producto → actualizar dependencies.md, descriptor y grafo en el paquete de producto (cortex-product-unosportclub), no en cortex-core.
No duplicar documentación de dominio en el handbook de plataforma salvo extractos con enlace.