docs(flows): DoD obligatorio con user-facing surface + abrir issues 0100-0103 (taxonomia, frontmatter migration, dev_console, work dashboard)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

modules/data_table/CMakeLists.txt

@@ -0,0 +1,54 @@
+# --- fn_module_data_table ---
+# Static lib bundling the data_table module: TQL pipeline + Lua engine +
+# viz_render + data_table.cpp entrypoint.
+#
+# Apps opt-in via:
+#   target_link_libraries(<app> PRIVATE fn_module_data_table)
+#
+# Header access:
+#   #include "data_table/data_table.h"
+#   #include "core/data_table_types.h"
+#
+# Replaces former fn_table_viz target (renamed 2026-05-16 as part of the
+# modules system rollout — issue 0097 modules).
+
+cmake_minimum_required(VERSION 3.16)
+
+# Module sources: the entrypoint lives here; members live in cpp/functions/.
+set(_FN_CPP_ROOT ${CMAKE_SOURCE_DIR}/../cpp)
+
+add_library(fn_module_data_table STATIC
+    ${CMAKE_CURRENT_SOURCE_DIR}/data_table.cpp
+    ${_FN_CPP_ROOT}/functions/core/compute_stage.cpp
+    ${_FN_CPP_ROOT}/functions/core/compute_pipeline.cpp
+    ${_FN_CPP_ROOT}/functions/core/tql_emit.cpp
+    ${_FN_CPP_ROOT}/functions/core/tql_helpers.cpp
+    ${_FN_CPP_ROOT}/functions/core/tql_apply.cpp
+    ${_FN_CPP_ROOT}/functions/core/tql_to_sql.cpp
+    ${_FN_CPP_ROOT}/functions/core/lua_engine.cpp
+    ${_FN_CPP_ROOT}/functions/core/join_tables.cpp
+    ${_FN_CPP_ROOT}/functions/core/auto_detect_type.cpp
+    ${_FN_CPP_ROOT}/functions/core/compute_column_stats.cpp
+    ${_FN_CPP_ROOT}/functions/core/llm_anthropic.cpp
+    ${_FN_CPP_ROOT}/functions/viz/viz_render.cpp
+)
+
+# PUBLIC: consumers `#include "data_table/data_table.h"` and "core/..." via cpp/functions.
+target_include_directories(fn_module_data_table PUBLIC
+    ${CMAKE_SOURCE_DIR}/../modules
+    ${_FN_CPP_ROOT}/functions
+)
+target_include_directories(fn_module_data_table PRIVATE
+    ${_FN_CPP_ROOT}/framework
+)
+
+target_compile_definitions(fn_module_data_table PUBLIC FN_LLM_ANTHROPIC=1)
+
+target_link_libraries(fn_module_data_table PUBLIC
+    imgui
+    implot
+    lua54
+)
+
+# fn::local_path() (Ask AI export path + TQL save/load) needs fn_framework.
+target_link_libraries(fn_module_data_table PRIVATE fn_framework)

modules/data_table/data_table.h

@@ -0,0 +1,58 @@
+#pragma once
+// data_table — render UI completa de tabla TQL.
+// Entry-point publica del stack data_table del registry.
+// Issue 0081-H. Promovido desde cpp/apps/primitives_gallery/playground/tables/data_table.h
+// Phase 2 (issue 0081-O, v1.2.0): Button renderer + event sink + tooltip + RightClick.
+//
+// Uso basico (back-compat, sin events):
+//   data_table::State st;  // persistir entre frames
+//   ImGui::Begin("Window"); ImGui::BeginChild("tbl", {-1,-1});
+//   data_table::render("my_table", {table1, table2}, st);
+//   ImGui::EndChild(); ImGui::End();
+//
+// Uso con events (Phase 2):
+//   std::vector<data_table::TableEvent> events;
+//   data_table::render("my_table", {table1, table2}, st, &events);
+//   for (auto& ev : events) {
+//       if (ev.kind == data_table::TableEventKind::ButtonClick &&
+//           ev.action_id == "cancel") { ... }
+//   }
+//
+// Requiere ImGui context + ImPlot context activos.
+// Namespace identico al playground para facilitar migracion (solo cambiar include path).
+
+#include "core/data_table_types.h"
+#include <vector>
+
+namespace data_table {
+
+// render — Render barra-de-chips + tabla + panels de visualizacion.
+// Mutates `st` en respuesta a la interaccion del usuario.
+//
+// `id`          — ID unico de ImGui para esta instancia (ej. "##my_table").
+// `tables`      — lista de TableInput. tables[0] es la main por defecto;
+//                 si State.main_source no-vacio se usa por nombre.
+//                 Tablas extra se exponen como joinables en la UI.
+// `st`          — estado mutable. Debe persistir entre frames (no stack-local).
+// `events_out`  — if non-null, populated with UI events (ButtonClick,
+//                 RowDoubleClick, RowRightClick) fired this frame. The caller
+//                 clears/reads the vector after each render call.
+//                 Pass nullptr to disable event collection (back-compat).
+// `show_chrome` — si false, oculta la barra de chips + breadcrumb por defecto.
+//                 El usuario puede reactivarla via el boton "Show UI".
+void render(const char* id,
+            const std::vector<TableInput>& tables,
+            State& st,
+            std::vector<TableEvent>* events_out,
+            bool show_chrome = true);
+
+// Overload for back-compat: same as render(..., nullptr, show_chrome).
+inline void render(const char* id,
+                   const std::vector<TableInput>& tables,
+                   State& st,
+                   bool show_chrome = true)
+{
+    render(id, tables, st, nullptr, show_chrome);
+}
+
+} // namespace data_table

modules/data_table/data_table.md

@@ -0,0 +1,210 @@
+---
+name: data_table
+kind: function
+lang: cpp
+domain: viz
+version: "1.4.0"
+purity: impure
+signature: "void data_table::render(const char* id, const std::vector<TableInput>& tables, State& st, std::vector<TableEvent>* events_out = nullptr, bool show_chrome = true)"
+description: "Render UI completa de tabla TQL: chips bar, tabla, viz panels, column-stats inline, drill, color rules, joins, TQL editor, Ask AI, Button renderer, event sink (ButtonClick/RowDoubleClick/RowRightClick), tooltip per-cell, column_specs persisted in TQL. Dots renderer para sparkline-like de status (v1.3.0). CategoricalChip (dot izquierda + text, siempre visible) y ColorScale (gradient N-color en fondo de celda) en v1.4.0. Entry-point publica del stack data_table. Muta State segun interaccion del usuario."
+tags: [tables, viz, ui, imgui, tql, cpp-tables]
+uses_functions:
+  - compute_stage_cpp_core
+  - compute_pipeline_cpp_core
+  - compute_column_stats_cpp_core
+  - auto_detect_type_cpp_core
+  - tql_emit_cpp_core
+  - tql_apply_cpp_core
+  - tql_helpers_cpp_core
+  - tql_to_sql_cpp_core
+  - lua_engine_cpp_core
+  - join_tables_cpp_core
+  - viz_render_cpp_viz
+uses_types:
+  - data_table_types_cpp_core
+  - ColumnSpec_cpp_core
+  - CellRenderer_cpp_core
+  - BadgeRule_cpp_core
+  - IconMapEntry_cpp_core
+  - TableInput_cpp_core
+  - State_cpp_core
+  - Stage_cpp_core
+  - StageOutput_cpp_core
+  - ViewMode_cpp_viz
+  - ViewConfig_cpp_viz
+  - VizPanel_cpp_viz
+  - Join_cpp_core
+  - Filter_cpp_core
+  - DrillStep_cpp_core
+  - DerivedColumn_cpp_core
+  - Aggregation_cpp_core
+  - SortClause_cpp_core
+  - ColumnType_cpp_core
+  - TableEvent_cpp_core
+  - TableEventKind_cpp_core
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports:
+  - imgui.h
+  - app_base.h
+  - core/data_table_types.h
+  - core/lua_engine.h
+  - core/tql_apply.h
+  - core/tql_emit.h
+  - core/tql_helpers.h
+  - core/tql_to_sql.h
+  - core/compute_stage.h
+  - core/compute_pipeline.h
+  - core/compute_column_stats.h
+  - core/auto_detect_type.h
+  - core/join_tables.h
+  - viz/viz_render.h
+tested: true
+tests:
+  - "back-compat: TableInput without column_specs does not crash"
+  - "Badge: TableInput with Badge column_spec compiles and links"
+  - "Progress: TableInput with Progress column_spec compiles and links"
+  - "Duration: TableInput with Duration column_spec compiles and links"
+  - "Icon: TableInput with Icon column_spec compiles and links"
+  - "Button: TableEvent struct constructible; render() with events_out links"
+  - "Tooltip: ColumnSpec with tooltip_on_hover=true compiles and links"
+  - "Back-compat: both render() signatures (with/without events_out) link"
+  - "Dots: ColumnSpec with CellRenderer::Dots + badges constructs correctly"
+  - "Dots TQL roundtrip: State::aux_column_specs accepts Dots spec"
+  - "TestCategoricalChipRule: chip rule with match='success' produces correct color"
+  - "TestColorScaleLerpTwoStops: t=0→first color, t=1→last color, t=0.5→midpoint"
+  - "TestColorScaleLerpThreeStops: t=0.25 lies between stop0 and stop1"
+  - "TestColorScaleOutOfRange: t<0 saturates at first; t>1 saturates at last"
+test_file_path: "cpp/tests/test_column_specs.cpp"
+file_path: "modules/data_table/data_table.cpp"
+params:
+  - name: id
+    desc: "ID unico ImGui para esta instancia, ej. '##orders_table'. Debe ser estable entre frames."
+  - name: tables
+    desc: "Lista de TableInput materializadas en memoria. tables[0] es la main por defecto; si State.main_source no-vacio se usa por nombre. Tablas extra se exponen como joinables en la UI de joins."
+  - name: st
+    desc: "Estado mutable completo: pipeline de stages, joins, viz config, ui tweaks, aux_column_specs (Phase 2). Debe persistir entre frames — no declarar en el stack del frame."
+  - name: events_out
+    desc: "Puntero a vector de TableEvent. Si non-null, se puebla con eventos de este frame (ButtonClick, RowDoubleClick, RowRightClick). El caller limpia/lee el vector despues de cada render. Pasar nullptr para desactivar (back-compat)."
+  - name: show_chrome
+    desc: "Si false, oculta chips bar + breadcrumb por defecto. El usuario puede reactivar con el boton 'Show UI'. El State persiste el override del usuario entre frames."
+output: "void. Muta st en respuesta a la interaccion del usuario (filtros, breakouts, sorts, drill, joins, viz mode). Los cambios son visibles en st al retornar. Events emitted via events_out."
+---
+
+## Ejemplo
+
+```cpp
+#include "viz/data_table.h"
+#include "core/data_table_types.h"
+
+// --- Setup (una vez) ---
+data_table::TableInput t;
+t.name = "orders";
+t.rows = num_rows;
+t.cols = num_cols;
+t.cells = cells_ptr;          // row-major flat array, owner externo
+t.headers = {"id", "amount", "status", "actions"};
+t.types   = {data_table::ColumnType::Int,
+             data_table::ColumnType::Float,
+             data_table::ColumnType::String,
+             data_table::ColumnType::String};
+
+// Phase 2: declarative renderers + tooltip
+t.column_specs.resize(4);
+t.column_specs[2].renderer = data_table::CellRenderer::Badge;
+t.column_specs[2].badges   = {{"paid","#22c55e","Paid"},{"pending","#f59e0b",""}};
+t.column_specs[2].tooltip         = "auto";
+t.column_specs[2].tooltip_on_hover = true;
+t.column_specs[3].renderer     = data_table::CellRenderer::Button;
+t.column_specs[3].button_action = "cancel_order";
+t.column_specs[3].button_label  = "Cancel";
+
+data_table::State st;          // persiste entre frames
+std::vector<data_table::TableEvent> events;
+
+// --- Render (cada frame) ---
+ImGui::Begin("Orders");
+ImGui::BeginChild("##tbl", ImVec2(-1, -1));
+events.clear();
+data_table::render("##orders", {t}, st, &events);
+ImGui::EndChild();
+ImGui::End();
+
+// --- Process events ---
+for (const auto& ev : events) {
+    if (ev.kind == data_table::TableEventKind::ButtonClick &&
+        ev.action_id == "cancel_order") {
+        cancel_order(ev.row);   // app handles the action
+    }
+    if (ev.kind == data_table::TableEventKind::RowDoubleClick) {
+        open_order_detail(ev.row);
+    }
+}
+```
+
+## Cuando usarla
+
+Cuando una app necesita tabla con filtros + agregaciones + viz + joins sobre datos en memoria. Reemplaza `ImGui::BeginTable` inline + toda la logica TQL manual. Sustituye directamente el include del playground (`tables/data_table.h`) cambiando solo el path a `viz/data_table.h`.
+
+Usar `CategoricalChip` cuando quieras un indicador visual (dot de color) siempre visible a la izquierda del texto de la celda, para columnas categoricas (estado, tipo, severidad). Mas discreto que Badge y sin hover-only. Usar `ColorScale` cuando la columna sea numerica continua y quieras dar contexto visual de "alto/bajo/medio" con un fondo tintado proporcional al valor — util para latencias, scores, porcentajes, metricas.
+
+## Gotchas
+
+- **ImGui + ImPlot context activos**: `render()` llama a APIs de ambas librerias. Llamar fuera de un frame activo causa UB.
+- **State no stack-local**: `State` contiene el historial de drill, pipeline de stages, cache de stats y buffers de UI. Declarar en el stack del frame reset todo el estado del usuario en cada frame.
+- **Drill-down propaga en State**: `st.active_stage` y `st.stages` se mutan por click en charts. El caller puede leer `st` tras `render()` para reaccionar.
+- **Thread-safety**: `render()` usa `static thread_local` para buffers intermedios. Llamar solo desde el main thread de ImGui.
+- **TableInput owner externo**: `cells` es un puntero raw al array del caller. Los datos deben sobrevivir durante toda la llamada a `render()`. No pasar puntero a vector que puede reallocarse.
+- **events_out no se limpia**: `render()` solo hace `push_back`. El caller debe llamar `events.clear()` antes de cada frame o acumulara eventos de frames anteriores.
+- **Button + celda vacia**: si el cell value es vacio, el boton NO se dibuja. La app controla cuando mostrar el boton poniendo un value no vacio (ej. "1" o el ID de la fila).
+- **RowRightClick emite evento Y abre popup interno**: la tabla de stages (stage>0) sigue abriendo su popup de drill. En el raw table (stage 0), se emite el evento pero el popup de drill antiguo tambien puede abrirse via `U.open_cell_popup`. El caller puede ignorar el popup interno y gestionar su propio menu al detectar `RowRightClick`.
+- **CategoricalChip sin regla coincidente → sin dot**: si ninguna `ChipRule.match` coincide con el valor de la celda, solo se renderiza el texto. Definir una regla de fallback explicita si se necesita dot para valores no mapeados.
+- **ColorScale clampa fuera de rango**: valores por debajo de `range_min` se tratan como t=0 (primer stop) y valores por encima de `range_max` como t=1 (ultimo stop). Definir `range_min`/`range_max` sensatos para que el gradiente sea informativo; valores muy alejados de la mayoria hacen que todo el gradiente aparezca en un extremo.
+- **aux_column_specs merge**: si `TableInput.column_specs` esta vacio pero `State.aux_column_specs[0]` no, `render()` los aplica automaticamente. Si el caller pasa column_specs no vacios, ganan sobre los del State.
+- **Ask AI modal (llm_anthropic)**: el boton "Ask AI" usa un stub interno de `llm_anthropic` que retorna error por defecto. Para activar la feature real, compilar con `-DFN_LLM_ANTHROPIC=1` y proveer `infra/llm_anthropic.h` en el include path. Pendiente Wave 4: promover al registry.
+- **FN_TQL_DUCKDB**: modo SQL del Ask AI requiere compilar con `-DFN_TQL_DUCKDB=1` y la libreria DuckDB disponible.
+
+## Notas
+
+No hay tests unitarios directos: `render()` requiere ImGui + ImPlot context activos (imposible sin ventana GL). Cobertura via:
+1. `cpp/apps/primitives_gallery/playground/tables/` — playground original con self_test.cpp y e2e_run.sh.
+2. Wave 4: migration self-tests en las apps que migren desde el playground.
+
+**Estado Wave 3.5 (issue 0081-I):**
+- Todos los includes del playground (`data_table_logic.h`, `tql.h`, `tql_to_sql.h`) eliminados. `data_table.cpp` compila sin el playground en el include path.
+- `tql::apply` firma extendida ya en `tql_apply_cpp_core` (wave anterior). Resuelto.
+- `tql_to_sql` promovido a `core/tql_to_sql.h`. Resuelto.
+- `data_table_logic` helpers (row_to_tsv, drill, view_mode, etc.) declarados como `static` en `data_table.cpp`. No son API pública.
+- `State::ensure_stage0/raw/active` implementados en `compute_stage.cpp`.
+- `ColStats` struct: usa el de `compute_column_stats_cpp_core`. Unificado.
+
+**Deuda tecnica restante (Wave 4):**
+- `llm_anthropic` (Ask AI modal, issue 0080): stub interno activo. Promover a `cpp/functions/infra/llm_anthropic` para activar feature real.
+- `FN_TQL_DUCKDB`: modo SQL del Ask AI sin soporte en stub. Requiere DuckDB + flag de compilacion.
+- `column_specs` TQL roundtrip (Phase 2): actualmente caller-managed. No persisten en TQL emit/apply. Planificado en issue 0081-O.
+
+## Capability growth log
+
+v1.1.0 (2026-05-15) — declarative CellRenderer (Badge/Progress/Duration/Icon) via TableInput.column_specs sidecar. Back-compat preservado: apps existentes sin column_specs siguen funcionando sin cambios.
+
+v1.2.0 (2026-05-15) — Button renderer + event sink (ButtonClick/RowDoubleClick/RowRightClick) + tooltip per cell + column_specs persisted in TQL (aux_column_specs roundtrip). Back-compat preserved: events_out=nullptr by default; existing render() callers unchanged.
+
+v1.3.0 (2026-05-15) — Dots renderer for inline status timelines (sparkline-like). Reuses badges for color mapping. dots_max/dots_separator/dots_show_count/dots_glyph_size fields. TQL roundtrip. dag_engine_ui canonical use case (10-col antipattern -> 6-col fix).
+
+v1.3.1 (2026-05-15) — Dots renderer now draws filled circles via ImDrawList instead of Unicode glyph. Font-independent: works regardless of TTF glyph coverage. Closes "dots show as ?" bug in dag_engine_ui.
+
+v1.3.2 (2026-05-15) — Hover dimming: row uses muted alpha (0.05 vs default 0.31); hovered cell gets a subtle overlay (~9% white) via ImDrawList. Badge no longer SpanAllColumns. Closes "table-wide bright highlight on hover".
+
+v1.3.3 (2026-05-15) — Selectable bg disabled for Text/empty cells (was duplicating with manual overlay → gray double-hover). Explicit ImVec2 size on Selectable so empty cells get a hit area (fixes drag-select skipping empties). Single uniform hover layer across all cell renderers.
+
+v1.3.4 (2026-05-15) — Row height tightened: GetTextLineHeight() (no spacing) replaces GetTextLineHeightWithSpacing() in Selectable size + manual overlay rect. Removes inflated row vertical padding introduced in v1.3.3.
+
+v1.3.5 (2026-05-15) — Cell hover paints via TableSetBgColor (covers entire cell bg including CellPadding) instead of manual AddRectFilled inside content area. Hit-test expanded by CellPadding for proper edge-to-edge coverage. Closes "hover has gap between cell borders".
+
+v1.3.6 (2026-05-15) — Selection (drag-range) also paints via TableSetBgColor — same edge-to-edge coverage as hover. Header/HeaderHovered/HeaderActive colors set to fully transparent so Selectable doesn't paint anything; all cell bg states (hover, selected, selected+hover) go through TableSetBgColor uniformly.
+
+v1.4.0 (2026-05-16) — new renderers: `CategoricalChip` (dot izquierda + text, always visible, replaces hover-only color-on-text for categorical) + `ColorScale` (continuous N-color LERP gradient for numeric cells, configurable `range_min`/`range_max`/`range_stops`/`range_alpha`). New types: `ChipRule{match,color}` + `ColorStop{position,color}` in `data_table_types.h`. TQL roundtrip (emit+apply) for both renderers. 4 headless tests added to `test_column_specs.cpp`.
+
+---
+Promovido desde `cpp/apps/primitives_gallery/playground/tables/data_table.{h,cpp}` — issue 0081-H.

modules/data_table/module.md

@@ -0,0 +1,57 @@
+---
+name: data_table
+version: 1.4.0
+lang: cpp
+description: "Reusable C++ ImGui module to render a full TQL-aware data table: chips bar, table grid, viz panels, column-stats inline, drill, color rules, joins, TQL editor, Ask AI, Button renderer, event sink, tooltip per-cell. Bundles compute pipeline + TQL stack + Lua engine + viz_render."
+members:
+  - data_table_cpp_viz
+  - compute_stage_cpp_core
+  - compute_pipeline_cpp_core
+  - compute_column_stats_cpp_core
+  - tql_emit_cpp_core
+  - tql_helpers_cpp_core
+  - tql_apply_cpp_core
+  - tql_to_sql_cpp_core
+  - lua_engine_cpp_core
+  - join_tables_cpp_core
+  - auto_detect_type_cpp_core
+  - llm_anthropic_cpp_core
+  - viz_render_cpp_viz
+tags: [tables, viz, ui, imgui, tql, cpp]
+dir_path: modules/data_table
+---
+
+## Documentation
+
+C++ ImGui module to render a full data table with TQL pipeline, viz panels, joins, color rules, declarative cell renderers (Badge, Progress, Duration, Icon, Button, Dots, CategoricalChip, ColorScale), drill, Ask AI and event sink.
+
+Entry-point: `data_table::render(id, tables, state, events_out, show_chrome)`.
+
+### Opt-in en una app
+
+1. `app.md`: anadir `uses_modules: [data_table_cpp]`.
+2. `CMakeLists.txt`: `target_link_libraries(<app> PRIVATE fn_module_data_table)`.
+3. Header: `#include "data_table/data_table.h"` y `#include "core/data_table_types.h"`.
+4. Reservar `data_table::State` persistente entre frames y llamar `data_table::render(...)` cada frame.
+
+### Funciones miembro
+
+Cada ID en `members` es una funcion del registry que el modulo bundla en su static lib. Cuando una app declara `uses_modules: [data_table_cpp]`, automaticamente "usa" estas funciones a traves del modulo — no hace falta listarlas otra vez en `uses_functions`.
+
+### Version policy
+
+Semver. Bumps de version se documentan en `## Capability growth log`. Cambios en API publica (`data_table.h`) = major. Adicion de funcionalidad opt-in = minor. Bugfix = patch.
+
+## Capability growth log
+
+- v1.4.0 (2026-05-16) — CategoricalChip (dot izquierda + text) + ColorScale (gradient N-color en fondo de celda)
+- v1.3.1 (anterior) — Dots renderer via ImDrawList (font-independent)
+- v1.3.0 — Dots renderer para sparkline-like de status timelines
+- v1.2.0 — Joins, drill, color rules, tooltip per-cell, Button event sink
+- v1.0.0 — Initial table + TQL pipeline + chips bar
+
+## Notes
+
+- El modulo se compila como static lib `fn_module_data_table` (cmake target). Static lib bundla todos los miembros — apps consumidoras solo enlazan UN target.
+- Replaces former `fn_table_viz` target (2026-05-16).
+- Requiere `fn_framework` (para `fn::local_path()` usado en Ask AI export).

modules/framework/module.md

@@ -0,0 +1,52 @@
+---
+name: framework
+version: 1.0.0
+lang: cpp
+description: "Core C++ ImGui app shell: fn::run_app, AppConfig, GLFW + OpenGL + ImGui + ImPlot bootstrap, theming (Mantine dark + indigo), settings/about/menubar/layouts UI, Tabler icons, logging, viewports & AltSnap-safe sizemove, local_files dir, embedded layout storage."
+members:
+  - tokens_cpp_core
+  - icon_font_cpp_core
+  - app_settings_cpp_core
+  - app_about_cpp_core
+  - fps_overlay_cpp_core
+  - panel_menu_cpp_core
+  - layouts_menu_cpp_core
+  - app_menubar_cpp_core
+  - logger_cpp_core
+  - log_window_cpp_core
+  - gl_loader_cpp_gfx
+  - layout_storage_cpp_core
+  - selectable_text_cpp_core
+tags: [framework, imgui, cpp, core]
+dir_path: cpp/framework
+---
+
+## Documentation
+
+Foundational C++ ImGui app shell shared by every desktop app in the registry. Apps opt-in transparently — every C++ app already links `fn_framework` via the `add_imgui_app` macro. The framework provides:
+
+- `fn::run_app(cfg, render_fn)`: GLFW + OpenGL3 + ImGui + ImPlot setup, multi-viewport, docking, AltSnap-safe sizemove, icon attach, layouts persistence, log window, settings window, about window, menubar.
+- `fn::local_path(name)`: scoped writable path under `<exe_dir>/local_files/`.
+- Design tokens (Mantine dark + indigo accent).
+- Tabler icons (TI_* macros).
+- `fn::framework_version()` / `fn::framework_description()` (post 1.0.0).
+
+Apps NEVER list these members in their own `uses_functions` — they come transitively via `fn_framework`. Audited via [[cpp_apps]] rule.
+
+### Version policy
+
+Semver. Major = breaking ABI/API of public `fn::run_app` or `AppConfig`. Minor = additive (new optional config field, new helper). Patch = bugfix.
+
+### Boundaries
+
+Framework does NOT include modules like `data_table`. Apps that want tables opt-in via `uses_modules: [data_table_cpp]` and `target_link_libraries(<app> PRIVATE fn_module_data_table)`. The framework is intentionally small.
+
+## Capability growth log
+
+- v1.0.0 (2026-05-16) — Initial framing as a versioned module. Members above are the bundled units of `fn_framework` static lib. Pre-1.0.0 history lives in git.
+
+## Notes
+
+- Static lib target: `fn_framework` (defined in `cpp/CMakeLists.txt`).
+- Generated header `cpp/framework/version_generated.h` (gitignored) exposes `FN_FRAMEWORK_VERSION` constant.
+- About panel of every app reads `fn::framework_version()` at runtime.