chore: snapshot WIP previo + flow 0008 + 7 sub-issues (0112-0119)

Snapshot de WIP acumulado de sesiones previas antes de merge wave 1 del flow 0008 (kanban_cpp + agent_runner_api + DoD schema). Incluye: - dev/flows/0008-kanban-cpp-and-agent-workflows.md - dev/issues/0112-0119*.md (7 sub-issues) - WIP previo en cmd/fn/doctor.go, registry/*, modules/, cpp/, etc. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-18 18:17:08 +02:00
parent ddb5366884
commit b9716a7cd6
119 changed files with 14929 additions and 3084 deletions
@@ -0,0 +1,131 @@
+---
+id: "0107f"
+title: "modules/README.md (catalogo) + docs/MODULES_API.md (contrato publico por modulo)"
+status: pendiente
+type: docs
+domain:
+  - meta
+  - cpp-stack
+  - docs
+scope: registry
+priority: alta
+depends: []
+blocks: []
+related:
+  - "0107"
+created: 2026-05-17
+updated: 2026-05-17
+tags: [modules, docs, api, contract]
+---
+
+# 0107f — Docs API publica de modulos
+
+Parte del issue principal [0107](0107-modules-standardization.md).
+
+## Objetivo
+
+Resolver "no hay un sitio canonico que diga como usar un modulo". Dos archivos:
+
+1. `modules/README.md` — catalogo (tabla con nombre, version, descripcion 1-linea, link a contrato).
+2. `docs/MODULES_API.md` — contrato canonico publico de cada modulo (template + ejemplos).
+
+## Estructura `modules/README.md`
+
+```markdown
+# Modulos C++ del registry
+
+Bundles versionados de funciones del registry expuestos como static libs.
+Apps opt-in via `app.md::uses_modules` + `target_link_libraries(... fn_module_<X>)`.
+
+| Modulo | Version | Static lib | Header | Entry | Descripcion | Contrato |
+|---|---|---|---|---|---|---|
+| framework_cpp | 1.1.0 | fn_framework | cpp/framework/app_base.h | fn::run_app(cfg, render) | Shell ImGui (GLFW+OpenGL+ImGui+ImPlot+themas+layouts+logger) | [framework_cpp](../docs/MODULES_API.md#framework_cpp) |
+| data_table_cpp | 2.0.0 | fn_module_data_table | modules/data_table/data_table.h | data_table::render(...) | Tabla completa TQL+viz+drill+AI+button events | [data_table_cpp](../docs/MODULES_API.md#data_table_cpp) |
+
+## Como anadir un modulo
+
+Ver [docs/MODULES_API.md#cycle](../docs/MODULES_API.md#ciclo-de-vida-de-un-modulo) y `.claude/rules/cpp_apps.md`.
+```
+
+## Estructura `docs/MODULES_API.md`
+
+```markdown
+# Modules API
+
+Contrato publico canonico de cada modulo C++ del registry. Una app DEBE
+poder integrar un modulo leyendo solo esta pagina (sin abrir el .cpp).
+
+## Template por modulo
+
+### <module_name>
+
+**Static lib target:** `<cmake_target>`
+**Header path:** `<include>`
+**Namespace:** `<namespace>`
+**Entry function:** `<signature>`
+**State struct:** `<type>` (lifecycle: <lifecycle notes>)
+**Public types:** lista de tipos publicos consumidos (TableInput, TableEvent, etc.)
+**Dependencias transitivas:** lista de libs externas (lua54, imgui, etc.)
+**Min ImGui version:** <X.Y>
+**Thread safety:** <main thread only | safe to call from any thread>
+
+#### Opt-in en una app
+
+1. `app.md`: anadir `uses_modules: [{name: <id>, min_version: "X.Y"}]`.
+2. `CMakeLists.txt`: `target_link_libraries(<app> PRIVATE <cmake_target>)`.
+3. Header: `#include "<header_path>"`.
+4. Reservar `<state>` persistente entre frames.
+5. Llamar `<entry>` cada frame.
+
+#### Ejemplo minimo
+
+```cpp
+[bloque de codigo lanzable]
+```
+
+#### Eventos / callbacks
+
+[Tabla de eventos publicos si aplica]
+
+#### Gotchas
+
+[Lista de gotchas conocidos]
+
+#### Version policy
+
+Semver. Major = breaking ABI/API de la entry function o State publico.
+Minor = additive (nuevo evento, nuevo renderer opcional). Patch = bugfix.
+
+---
+
+## framework_cpp
+
+[Aplicar template]
+
+## data_table_cpp
+
+[Aplicar template]
+
+## Ciclo de vida de un modulo
+
+1. Crear `modules/<name>/` con `module.md`, `CMakeLists.txt`, `<name>.cpp`, `<name>.h`.
+2. `module.md::members` lista funciones del registry que el modulo bundla.
+3. `module.md::version` SemVer estricto.
+4. `CMakeLists.txt` define static lib `fn_module_<name>` con sus deps.
+5. Anadir entrada en `modules/README.md`.
+6. Anadir seccion en `docs/MODULES_API.md` siguiendo el template.
+7. `fn index` registra el modulo.
+8. Cada bump de version: `/version modules/<name> <major|minor|patch> "<reason>"` (ver `.claude/commands/version.md`).
+```
+
+## Tareas
+
+- [ ] **6.1** Crear `modules/README.md` con tabla canonica.
+- [ ] **6.2** Crear `docs/MODULES_API.md` con template + secciones para los 2 modulos actuales.
+- [ ] **6.3** Anadir referencia desde `.claude/rules/cpp_apps.md` a `docs/MODULES_API.md`.
+- [ ] **6.4** Anadir referencia desde `cpp/PATTERNS.md` a `docs/MODULES_API.md`.
+- [ ] **6.5** Anadir referencia desde `.claude/CLAUDE.md` en la seccion "Estructura" listando `modules/` y enlazando docs.
+
+## Riesgos
+
+- Doc drift: facil que `module.md` y `MODULES_API.md` se desincronicen. Mitigacion: `fn doctor modules` (0107a) verifica que cada modulo registrado tiene seccion en `MODULES_API.md`. Si no, warning.