chore: auto-commit (286 archivos)

- .claude/agents/fn-orquestador/SKILL.md - .claude/commands/fn_claude.md - .claude/rules/INDEX.md - .claude/rules/cpp_apps.md - .claude/rules/ids_naming.md - CHANGELOG.md - apps/dag_engine/README.md - apps/dag_engine/api.go - apps/dag_engine/dags_migrated/example.yaml - apps/dag_engine/dags_migrated/example_lineage_tracking.yaml - ... Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-16 16:33:22 +02:00
parent 0b9af8f1bb
commit a03675113a
281 changed files with 12596 additions and 19526 deletions
@@ -0,0 +1,239 @@
+# Agent guide — como armar (o asistir) un flow
+
+Este archivo lo lee el LLM/agente que crea o edita flows. Su trabajo es **recomendar piezas concretas del registry** para cada flow, no inventarlas. Todo lo que se recomiende debe existir ya en el sistema (registry / apps / projects / vaults / DAGs) — o quedar marcado explicitamente como "FALTA: crear".
+
+## Que es un flow
+
+Caso de uso end-to-end reutilizable que cruza N apps del registry. Vive en `dev/flows/NNNN-<slug>.md`. Cada flow:
+
+- describe Goal + Pre-requisitos + Flow steps + Acceptance + Telemetria,
+- esta tageado con `apps:` (apps tocadas) en frontmatter,
+- se ejecuta manualmente (fase 1) o via `/flow run` (fase 2 futura),
+- alimenta `data_factory.runs` + `call_monitor.calls` al correr.
+
+## Tu trabajo como agente cuando un flow nace
+
+Al recibir "crea flow para <X>" o `/flow create <slug>`:
+
+1. **Entiende el goal** en una frase. Si ambiguo, pregunta antes de scaffold.
+2. **Recomienda piezas concretas** del registry para cada rol (extractor, transformer, sink, scheduler, notify, storage). Ver tabla de roles abajo.
+3. **Cita IDs reales** del registry/apps. Si la pieza no existe -> escribe `FALTA: crear <id> via fn-constructor` en la seccion correspondiente.
+4. **Marca riesgo** (low/medium/high) por sensibilidad de datos.
+5. **Sugiere schedule** (cron / webhook / manual) basado en el tipo de fuente.
+6. **Sugiere apps** del stack que encajan, sin inflar — solo las que realmente tocara.
+
+## Mapa de discovery — donde mirar para cada decision
+
+### Extractor (de donde sacan los datos)
+
+| Tipo de fuente | Donde buscar | Filtro MCP |
+|---|---|---|
+| API REST publica (JSON) | tag `extractor` + `http` | `mcp__registry__fn_search query="http" tag="extractor"` |
+| BigQuery | tag `bigquery` + `extractor` | `mcp__registry__fn_search query="" tag="bigquery"` |
+| Metabase | tag `metabase` + `extractor` | `mcp__registry__fn_search query="" tag="metabase"` |
+| Web scraping (con auth) | apps `navegator_dashboard` + recipes YAML | `ls projects/navegator/profiles/*/recipes/` |
+| Web scraping (sin auth, API JSON) | `http_get_json_*` (Tier 1 Tabla extractor.md) | `docs/capabilities/extractor.md` |
+| CSV/Parquet local | `load_csv_go_datascience`, `load_parquet_go_datascience`, `from_csv_py_core` | tag `extractor` lang `go|py` |
+| Webhooks | apps `registry_api` o `deploy_server` (receivers) | inspeccionar handlers existentes |
+| Jupyter notebook | `jupyter_read_py_notebook` | tag `notebook` |
+
+### Transformer (que se hace con los datos)
+
+| Operacion | Donde buscar |
+|---|---|
+| Dedup / Aggregate / Filter | `docs/capabilities/transformer.md` |
+| Tipos / Validacion de schema | `docs/capabilities/validator.md` (puede actuar como gate transformer) |
+| Geo (PostGIS, tiles) | `footprint_geo_stack` (app sink + transformer geo) |
+| NLP / Embeddings / entities | `docs/capabilities/nlp.md` |
+| Lua / TQL (table query) | `cpp-tables` group + `tql_*` funcs |
+
+### Sink (donde acaban los datos)
+
+| Destino | Recomendar |
+|---|---|
+| BigQuery | `bq_insert_rows_py_infra`, `bq_load_from_*` |
+| Metabase card / alert | `metabase_create_card_*`, `metabase_create_card_alert_*` |
+| PostgreSQL / SQLite local | `db_insert_row_go_infra` |
+| Notificacion Matrix | `agents_and_robots` (app) + funcion bot |
+| DuckDB en vault | listar `~/vaults/*` para destino + `csv_to_parquet_duckdb_py_core` |
+| HTTP POST a webhook ajeno | `http_post_json_*` |
+| Email / Slack | (todavia no — anadir si flow lo pide) |
+| Dashboard | `metabase_create_dashboard_*` + `auto_metabase` |
+| Grafo entidades | INSERT operations.db de algun project (ej `osint_graph`) + visualizar con `graph_explorer` |
+
+### Scheduler / Trigger
+
+| Caso | Recomendar |
+|---|---|
+| Recurrente cada N min/hora/dia | DAG en `apps/dag_engine/dags_migrated/<slug>.yaml` con `schedule:` cron. Step usa `function: <id>` directo. |
+| Manual (auth requiere user) | `trigger: manual` en flow. Sin DAG. |
+| Event-driven (push) | Webhook receiver — depende app (`registry_api`, `deploy_server`). |
+| Notebook colaborativo | `jupyter_*` funcs + analysis dir |
+| Ejecucion ad-hoc | `./fn run <id>` directo |
+
+### Storage / Artefacto
+
+| Tipo | Donde vive |
+|---|---|
+| BD app-local | `apps/<app>/operations.db` (entities, runs, assertions) |
+| Pipeline factory | `apps/data_factory/data_factory.db` (nodes, runs) |
+| DAG runs | `apps/dag_engine/dag_engine.db` |
+| Telemetria agente | `projects/fn_monitoring/apps/call_monitor/operations.db` |
+| Vault privado (datos sensibles) | `~/vaults/<vault>/` declarado en `projects/<p>/vaults/vault.yaml` |
+| Sub-repo Gitea (codigo/artefacto) | `dataforge/<name>` |
+| Configs reproducibles | `projects/metabase_registry/`, `projects/element_agents/`, etc. |
+
+### Apps disponibles (snapshot 2026-05-16)
+
+| App | Rol tipico en un flow |
+|---|---|
+| `navegator_dashboard` | extractor con auth / AutoExtract / recipes |
+| `dag_engine` + `dag_engine_ui` | scheduler / orquestador / vista runs |
+| `data_factory` | catalogo nodes + runs live |
+| `registry_dashboard` | vista codigo registry |
+| `call_monitor` | telemetria agent calls |
+| `sqlite_api` | HTTP server read-only de todas las BDs |
+| `agents_and_robots` | bot Matrix (sink notificaciones) |
+| `element_matrix_chat` | backend Matrix |
+| `auto_metabase` | sync YAML <-> Metabase |
+| `metabase_registry` | snapshots Metabase como codigo |
+| `odr_console` | jobs paralelos scraping |
+| `graph_explorer` | grafo entidades/relaciones |
+| `script_navegador` | runner YAML CDP headless |
+| `footprint_geo_stack` | PostGIS + Martin (tiles) + Valhalla (routing) |
+| `deploy_server` | rsync/systemd a VPS |
+| `docker_tui` | gestion docker |
+| `fn_match` | matcher funciones |
+| `kanban` | gestion tareas (sink reports?) |
+| `pipeline_launcher` | TUI lanzador pipelines |
+| `registry_api` | REST API del registry remoto |
+| `registry_mcp` | MCP server (Claude) |
+| `chart_demo / shaders_lab / primitives_gallery / runtime_test / engine_smoke / text_editor_smoke / altsnap_jitter_test` | demos C++ (raro que un flow las use) |
+
+### Projects disponibles
+
+| Project | Tema |
+|---|---|
+| `fn_monitoring` | observabilidad del registry |
+| `osint_graph` | grafos OSINT |
+| `navegator` | scraping CDP |
+| `element_agents` | agentes Matrix |
+| `online_data_recopilation` | scraping batch |
+| `imagegen` | image generation |
+| `app_turismo` | turismo |
+
+### Vaults disponibles
+
+`fn sync locations | grep vault` o `cat projects/*/vaults/vault.yaml`. Tipicos:
+- `~/vaults/imagegen_models/`
+- `~/vaults/odr_data/`
+- `~/vaults/osint_graph/`
+- `~/vaults/osint_nlp_models/`
+- `~/vaults/turismo_spain/`
+- `~/vaults/market_data/` (pendiente)
+- `~/vaults/finanzas/` (pendiente para flow 0003)
+
+### Capability groups (mother pages, lectura preferente)
+
+`docs/capabilities/INDEX.md`. Cuando recomiendes, lee la mother page del grupo antes de citar funciones sueltas:
+
+- `extractor` (15 funcs)
+- `transformer` (15 funcs)
+- `sink` (11 funcs)
+- `validator` (6 funcs)
+- `scheduler` (4 funcs cron parsing)
+- `navegator` (10 funcs CDP + LLM)
+- `notebook` (Jupyter)
+- `metabase` (106 funcs)
+- `bigquery` (26 funcs)
+- `nlp` (33 funcs)
+- `docker, ssh, systemd, deploy, registry, doctor, git, mantine, android, playwright, cpp-tables, cpp-windows, data-table-renderers`
+
+## Estructura de recomendacion a producir
+
+Cuando creas un flow, rellena estas secciones del .md (la template ya las tiene como placeholders):
+
+```markdown
+## Funciones del registry recomendadas
+
+| Rol | Funcion candidata | Si falta |
+|---|---|---|
+| Extractor | `http_get_json_py_infra` (URL: ...) | OK |
+| Validator | `validate_recipe_yaml_py_core` | OK |
+| Transformer | FALTA: crear `parse_aemet_response_py_core` via fn-constructor |
+| Sink | `db_insert_row_go_infra` (target PostGIS) | OK |
+| Scheduler | DAG `aemet-madrid.yaml` con cron `0 * * * *` | OK |
+| Notify | `matrix_send_message_*` (sala #ops) | FALTA: crear wrapper |
+
+## Apps tocadas
+
+- `dag_engine` (schedule)
+- `data_factory` (visibility runs)
+- `footprint_geo_stack` (sink PostGIS)
+
+## Projects relacionados
+
+- `fn_monitoring` (telemetria observable)
+- `osint_graph` (si lineage)
+
+## Vaults / storage
+
+- PostGIS (footprint_geo_stack): tabla `weather_madrid`
+- DuckDB local: NO
+
+## Schedule
+
+`0 * * * *` (cada hora). Razon: AEMET refresca cada hora.
+
+## Capability groups consultados
+
+- `extractor` (http_get_json), `validator`, `sink`
+```
+
+Si una recomendacion es FALTANTE: anota en la seccion + abre issue paralelo (`/create-issue`) o flag al user "necesitamos crear estas N funciones antes de poder correr el flow".
+
+## Reglas duras al recomendar
+
+1. **NUNCA inventes IDs**. Si dudas, busca con MCP. Cita solo IDs que respondan a `mcp__registry__fn_show`.
+2. **REUTILIZA antes que crear**. Solo FALTA si nada del registry encaja despues de >=3 queries FTS distintas.
+3. **MARCA riesgo explicito** en frontmatter. Datos publicos = `low`. Auth = `medium`. Datos personales/financieros = `high`.
+4. **NO sugieras schedule cron si requiere auth manual**. `trigger: manual`.
+5. **CITA capability group** preferido cuando exista, no funcion suelta. Ej. "ver `docs/capabilities/sink.md`" mejor que "usar `bq_insert_rows_py_infra`".
+6. **DOCUMENTA gotchas** especificos del flow en seccion `## Notas`.
+7. **NO mezcles N flows en uno**. Si el goal toca >5 apps -> probable que sean 2 flows distintos.
+
+## Plantilla de prompt para futuro agente
+
+Cuando user invoca `/flow create <slug>` o pide "ayuda para crear flow":
+
+```
+Eres asistente de flow design. Lee dev/flows/AGENT_GUIDE.md primero.
+
+Pasos:
+1. Pregunta al user: "Que quieres lograr en 1 frase? + datos sensibles?"
+2. Identifica fuente -> recomienda extractor del registry.
+3. Identifica destino -> recomienda sink del registry.
+4. Identifica frecuencia -> recomienda schedule (cron / webhook / manual).
+5. Identifica notify channel (matrix / email / ninguno).
+6. Lista apps tocadas + projects + vaults.
+7. Marca FALTA para piezas inexistentes con sugerencia de fn-constructor prompt.
+8. Crea NNNN-<slug>.md desde template con las secciones rellenadas.
+9. Actualiza INDEX.md.
+10. Imprime resumen: "Flow 0008 creado. Faltan N piezas: lista".
+```
+
+## Donde escribir hallazgos
+
+Tras correr un flow:
+- Marca acceptance checkboxes `[x]`.
+- Rellena `## Notas` con tiempos reales, problemas, mejoras.
+- Si descubres patron repetido en varios flows: candidato a sub-feature de `/flow run` (fase 2) o nueva funcion del registry.
+
+## Mantenimiento del guide
+
+Este archivo crece. Cuando:
+- Una app nueva aparece -> anadir fila a "Apps disponibles".
+- Un capability group nuevo -> anadir a "Capability groups".
+- Un vault nuevo -> anadir a "Vaults".
+
+`fn doctor` deberia detectar drift entre AGENT_GUIDE.md y BD del registry (TBD: nuevo subcomando `fn doctor flows`).