From 103cba2a42c0e0a3d94ad5d656dec1155a4fd0b8 Mon Sep 17 00:00:00 2001
From: Egutierrez <egutierrez@dead.dd>
Date: Mon, 6 Apr 2026 00:35:40 +0200
Subject: [PATCH] docs: documenta params_schema en CLAUDE.md y templates
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Actualiza schema rápido, ejemplo FTS5, sección de añadir funciones y los tres
templates (function, pipeline, component) con los campos params/output obligatorios.
---
 .claude/CLAUDE.md           | 16 ++++++++++++++--
 docs/templates/component.md |  1 +
 docs/templates/function.md  |  6 ++++++
 docs/templates/pipeline.md  |  8 ++++++++
 4 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
index a5500ea8..c9cb4eeb 100644
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -28,6 +28,9 @@ sqlite3 registry.db "SELECT id, kind, purity, description FROM functions WHERE i
 # FTS5 en tipos
 sqlite3 registry.db "SELECT id, algebraic, description FROM types WHERE id IN (SELECT id FROM types_fts WHERE types_fts MATCH 'name:result OR description:result') ORDER BY name;"
 
+# FTS5 por semantica de params (composabilidad)
+sqlite3 registry.db "SELECT id, json_extract(params_schema, '$.output') FROM functions WHERE id IN (SELECT id FROM functions_fts WHERE functions_fts MATCH 'params_schema:retornos');"
+
 # Por dominio
 sqlite3 registry.db "SELECT id, purity, signature FROM functions WHERE domain = 'finance' ORDER BY name;"
 
@@ -51,7 +54,8 @@ sqlite3 registry.db ".schema"
 
 ### Schema rapido
 
-**functions** — columnas: `id, name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, example, tested, tests, test_file_path, file_path, created_at, updated_at, props, emits, has_state, framework, variant, notes, documentation, code, content_hash, source_repo, source_license, source_file`
+**functions** — columnas: `id, name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, example, tested, tests, test_file_path, file_path, created_at, updated_at, props, emits, has_state, framework, variant, notes, documentation, code, content_hash, source_repo, source_license, source_file, params_schema`
+- `params_schema`: JSON con semántica de inputs/outputs. Formato: `{"params":[{"name":"x","desc":"..."}],"output":"..."}`. Buscable via FTS5.
 - Enums: `kind`(function|pipeline|component) `purity`(pure|impure) `lang`(go|py|bash|ps)
 - Dominios: core, infra, finance, datascience, cybersecurity, shell, tui, pipelines, browser
 
@@ -63,7 +67,7 @@ sqlite3 registry.db ".schema"
 - FK: `function_id` → `functions.id`
 
 **FTS5 (columnas buscables):**
-- `functions_fts`: id, name, description, tags, signature, domain, example, notes, documentation, code
+- `functions_fts`: id, name, description, tags, signature, domain, example, notes, documentation, code, params_schema
 - `types_fts`: id, name, description, tags, domain, examples, notes, documentation, code
 - `unit_tests_fts`: id, name, code, function_id, lang
 
@@ -112,6 +116,7 @@ fn search -k function -p pure -d core "slice"
 fn list [-d domain] [-k kind]
 fn show <id>
 fn add -k function                  # Template
+fn check params                     # Lista funciones sin params_schema
 
 # Ejecutar funciones y pipelines (fn run)
 fn run <id_or_name> [args...]       # Ejecuta por ID o nombre
@@ -177,6 +182,13 @@ Entornos usados automaticamente:
 
 Frontmatter del .md — ver template completo en `docs/templates/` o con `fn add -k function`.
 
+Campos `params` y `output` (obligatorios en frontmatter):
+- `params`: lista de `{name, desc}` con descripción semántica de cada parámetro (qué representa, unidades, rango)
+- `output`: descripción semántica de lo que retorna la función
+- Para componentes: solo `output` (ya tienen `props`)
+- Se indexan como JSON en `params_schema` y son buscables via FTS5
+- `fn check params` lista funciones sin documentar
+
 Reglas de integridad (el indexer las valida):
 - Pipeline → siempre impuro + uses_functions no vacio
 - Pure → returns_optional: false + error_type: ""
diff --git a/docs/templates/component.md b/docs/templates/component.md
index b1d97ec8..222d7fbf 100644
--- a/docs/templates/component.md
+++ b/docs/templates/component.md
@@ -14,6 +14,7 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [react]
+output: "tabla HTML interactiva con los datos renderizados según las columnas"
 tested: false
 tests: []
 test_file_path: ""
diff --git a/docs/templates/function.md b/docs/templates/function.md
index 394c37d3..12c5a1f8 100644
--- a/docs/templates/function.md
+++ b/docs/templates/function.md
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: xs
+    desc: "slice de elementos a filtrar"
+  - name: pred
+    desc: "predicado que evalúa cada elemento, true = incluir"
+output: "nuevo slice con los elementos que cumplen el predicado"
 tested: false
 tests: []
 test_file_path: ""
diff --git a/docs/templates/pipeline.md b/docs/templates/pipeline.md
index 3a2f689a..82669c94 100644
--- a/docs/templates/pipeline.md
+++ b/docs/templates/pipeline.md
@@ -14,6 +14,14 @@ returns: [ohlcv_go_finance]
 returns_optional: false
 error_type: "error_go_core"
 imports: []
+params:
+  - name: ctx
+    desc: "contexto de ejecución con timeout/cancelación"
+  - name: symbol
+    desc: "par de trading (ej: BTCUSDT)"
+  - name: interval
+    desc: "duración de cada vela (ej: 5m, 1h)"
+output: "slice de velas OHLCV agregadas, o error si falla el fetch"
 tested: false
 tests: []
 test_file_path: ""