fn_registry/.claude/commands/documentar.md

/documentar — Distribuir la conversacion en la documentacion del registry

Documenta la conversacion actual repartiendo el contenido en TODOS los .md que correspondan: artefactos del registry (funciones, tipos, apps, projects, analysis, vaults) y documentacion global del repo (docs/*, docs/adr/, CHANGELOG.md, dev/issues/*, .claude/rules/*, .claude/CLAUDE.md, sub-CLAUDEs, READMEs/SPECs en apps). Cierra con una entrada en /entrada_diario. El objetivo es que otro LLM (o yo en otra sesion) pueda continuar sin haber visto la conversacion: contexto, decisiones, gotchas, paths, IDs, comandos exactos, "lo siguiente que pega".

Uso

/documentar                       # documenta todo lo relevante de la sesion
/documentar shaders_lab fase 6    # acota a artefactos/temas concretos (opcional)

$ARGUMENTS es opcional: si va vacio, documenta toda la sesion. Si lleva texto, usalo como hilo conductor para decidir que es relevante.

---

Reglas duras

1. NUNCA escribir secretos en ningun .md ni en el diario:
   • Passwords, tokens, API keys, GPG keys, ssh private keys, valores reales de variables de entorno sensibles (REGISTRY_API_TOKEN, *_SECRET, *_PASSWORD, *_TOKEN, basicAuth en URLs).
   • Si el usuario lo pide explicitamente, OK. Por defecto, redactar como <token> / <password> o referenciar el origen (pass entry registry_api, ~/.fn_pc).
   • URLs publicas, hosts, puertos, paths, IDs, nombres de servicios, env var names (no values), licencias, hashes de commit cortos: SI se documentan.
2. NUNCA sobreescribir secciones existentes ni reordenar contenido previo. Solo append o seccion nueva con timestamp/fase si encaja.
3. SIEMPRE consultar registry.db con FTS5 para encontrar el .md correcto antes de editar (no asumir paths).
4. SIEMPRE cerrar invocando /entrada_diario con un resumen del bloque (a no ser que el usuario diga lo contrario).
5. Densidad util > prosa: comandos exactos, IDs del registry, paths relativos, error messages literales, flags de build, decisiones (con el "porque"), bugs encontrados (con el fix), proximos pasos. Sin fluff.

---

PASO 0 — Recopilar el material de la sesion

Antes de escribir nada, repasar la conversacion y juntar:

1. Artefactos tocados (creados, editados, ejecutados, mencionados):

   • Funciones / tipos del registry → IDs {name}_{lang}_{domain}.
   • Apps (apps/* o projects/*/apps/*).
   • Projects (projects/*).
   • Analyses (analysis/* o projects/*/analysis/*).
   • Vaults (projects/*/vaults/vault.yaml).
   • Reglas (.claude/rules/*.md), ADRs (docs/adr/*.md), templates (docs/templates/*).
   • Issues (dev/issues/*.md, dev/issues/completed/*.md).
   • Docs globales (docs/*.md: architecture, integrity, execution_standard, fn_operations, sync_setup, init-pipelines, testing, functions, types, fn-registry-system-complete).
   • CLAUDE.md raiz (.claude/CLAUDE.md) y sub-CLAUDEs (apps/*/.claude/CLAUDE.md, projects/*/apps/*/.claude/CLAUDE.md, analysis/*/.claude/CLAUDE.md, projects/*/analysis/*/.claude/CLAUDE.md).
   • Docs sueltas en apps (apps/*/SPEC.md, apps/*/README.md, apps/*/docs/*.md, cpp/DESIGN_SYSTEM.md).
   • CHANGELOG.md raiz.

2. Cambios concretos desde git:

   cd $HOME/fn_registry
   git status --short
   git diff --stat
   git log --since="6 hours ago" --oneline
   

   Cada path modificado mapea a un artefacto — convertir a su .md.

3. Material no codigo que vale la pena dejar registrado:

   • Decisiones de diseño y por que (anti-bitrot: el porque suele perderse).
   • Bugs encontrados + raiz + fix (no solo "fix").
   • Atajos / convenciones nuevas.
   • Pendientes y "lo siguiente que pega" para la proxima sesion.
   • Aprendizajes operativos (build flags, cross-compile gotchas, env requerido).

4. Filtrar secretos segun la regla dura #1.

Si el material es solo conversacion exploratoria sin artefactos tocados, ir directo a PASO 4 (solo diary).

---

PASO 1 — Mapear cada bloque de informacion a su .md

Para cada artefacto identificado, localizar su .md consultando registry.db:

cd $HOME/fn_registry

# Funcion / tipo
sqlite3 registry.db "SELECT id, file_path FROM functions WHERE id IN (SELECT id FROM functions_fts WHERE functions_fts MATCH 'name:NAME* OR description:NAME*');"
sqlite3 registry.db "SELECT id, file_path FROM types     WHERE id IN (SELECT id FROM types_fts     WHERE types_fts     MATCH 'name:NAME* OR description:NAME*');"

# App / project / analysis (los .md son nombres fijos)
sqlite3 registry.db "SELECT id, dir_path FROM apps      WHERE name = 'NAME';"  # → {dir_path}/app.md
sqlite3 registry.db "SELECT id, dir_path FROM projects  WHERE name = 'NAME';"  # → projects/NAME/project.md
sqlite3 registry.db "SELECT id, dir_path FROM analysis  WHERE name = 'NAME';"  # → {dir_path}/analysis.md
sqlite3 registry.db "SELECT id, name, path FROM vaults  WHERE name = 'NAME';"  # → vault.yaml entry

Si el .md aun no existe (artefacto recien creado en la sesion y todavia no indexado), el path se deduce de la convencion:

• Funcion: functions/{domain}/{name}.md, python/functions/{domain}/{name}.md, bash/functions/{domain}/{name}.md, frontend/functions/{domain}/{name}.md, cpp/functions/{domain}/{name}.md.
• Tipo: types/{domain}/{name}.md (codigo en functions/{domain}/{name}.go).
• App: apps/{name}/app.md o projects/{proyecto}/apps/{name}/app.md.
• Project: projects/{name}/project.md.
• Analysis: analysis/{name}/analysis.md o projects/{proyecto}/analysis/{name}/analysis.md.

Donde escribir dentro de cada .md

Tipo de .md	Seccion preferida para append
Funcion / tipo	## Notas al final. Si no existe, crearla. NO tocar el frontmatter salvo que el usuario pida cambiar metadata.
App (app.md)	## Estado actual con sub-fases si el app ya las usa (ej. ### Fase 7 — ... [done]). Si no, ## Notas. Tambien ## Lo siguiente que pega para futuros pasos.
Project (project.md)	## Notas o seccion del area afectada (## Apps, ## Operacion, ## Troubleshooting).
Analysis (analysis.md)	## Notas o ## Hallazgos (crearla si no existe).
Vault (vault.yaml)	Comentario al final del entry o crear vaults/{name}/README.md con notas operativas (NO meter datos sensibles).
Regla (.claude/rules/*)	Solo si el usuario explicitamente formaliza una regla nueva — entonces archivo nuevo + entrada en INDEX.md.
ADR (docs/adr/*)	Solo si la decision es arquitectural y persistente — archivo nuevo numerado.

Documentacion global / cross-cutting (NO saltarse)

Estos .md describen el sistema entero, no un artefacto concreto. Cuando un cambio impacta convenciones, comportamiento de agentes, decisiones, issues abiertos o features visibles al usuario, tambien se actualizan aqui:

Archivo / carpeta	Cuando tocarlo	Como
CHANGELOG.md (raiz)	Cambio visible al usuario o agentes: nueva funcion/pipeline/app, breaking change, fix relevante, rename, deprecate.	Append bajo seccion del dia (## YYYY-MM-DD) con ### Added/Changed/Fixed/Removed/Deprecated. NUNCA reescribir entradas previas. Si es trabajo en curso, usar ## [Unreleased].
docs/adr/NNNN-slug.md	Decision arquitectural persistente con alternativas descartadas (no es regla operativa, es historia del por que).	Archivo nuevo numerado siguiendo plantilla en docs/adr/README.md. Estado inicial: accepted o proposed.
docs/architecture.md	Cambia la arquitectura general (BDs, layers, flujo de datos, capas).	Append en seccion afectada o nueva subseccion. Mantener tablas y diagramas existentes.
docs/integrity.md	Nueva regla de integridad / referencia cruzada que el indexer valida.	Append a la lista de reglas. Reflejar tambien en codigo del indexer si toca.
docs/execution_standard.md	Cambia el estandar de ejecucion (fn run, despacho por lenguaje, env vars).	Append seccion. Sincronizar con .claude/CLAUDE.md si menciona los mismos comandos.
docs/sync_setup.md	Cambia el flujo de fn sync, env vars (FN_REGISTRY_API, REGISTRY_API_TOKEN), ~/.fn_pc, troubleshooting.	Append. Recordatorio: NO escribir el valor del token, solo el nombre.
docs/init-pipelines.md	Nuevo pipeline de scaffolding o cambio en uno existente.	Append seccion del pipeline.
docs/testing.md	Cambia convencion de tests, runners, layout de *_test.go/test_*.py.	Append seccion afectada.
docs/functions.md / docs/types.md	Cambia el schema de la tabla functions o types (columnas, FTS5, enums, params_schema).	Append. Sincronizar con .claude/CLAUDE.md schema rapido.
docs/fn_operations.md	Cambia el schema/comportamiento de operations.db o el bucle reactivo (entities, relations, executions, assertions).	Append seccion afectada.
docs/fn-registry-system-complete.md	Snapshot completo del sistema — solo si la sesion implico un rediseño grande. Normalmente NO se toca por sesion.	Si toca, append seccion con timestamp.
docs/templates/*.md	Cambia el frontmatter obligatorio de un tipo de artefacto (function/pipeline/component/type/app/project/analysis).	Editar la plantilla correspondiente. Tambien actualizar ejemplos en .claude/CLAUDE.md.
dev/issues/NNNN-*.md	Sesion trabajo en un issue: progreso, blockers, decisiones del scope.	Append ## Notas / Progreso con timestamp. NO mover de dev/issues/ a dev/issues/completed/ salvo que el issue cierre.
dev/issues/completed/NNNN-*.md	Issue completado en esta sesion.	Mover el archivo a completed/ (git mv) y actualizar la fila en dev/issues/README.md (estado completado, link a completed/...).
dev/issues/README.md	Issue creado, cambia estado, prioridad, dependencias.	Editar la fila correspondiente o anadir nueva al final de la tabla.
.claude/rules/*.md + INDEX.md	El usuario formaliza una nueva regla operativa.	Archivo nuevo + fila en INDEX.md. Numerar en el indice manteniendo orden.
.claude/CLAUDE.md (raiz)	Cambio en convenciones globales del proyecto, comandos fn nuevos, env vars, estructura de carpetas, schema BDs.	Append en seccion afectada. Sincronizar con docs/ si hay overlap.
Sub-CLAUDE (apps/*/.claude/CLAUDE.md, analysis/*/.claude/CLAUDE.md, projects/*/apps/*/.claude/CLAUDE.md)	Cambio especifico en como un agente debe trabajar dentro de esa app/analysis (no global).	Append. NO duplicar reglas que ya estan en CLAUDE.md raiz.
cpp/DESIGN_SYSTEM.md	Cambia tokens, layout, primitivas visuales del stack C++.	Append seccion afectada.
apps/*/SPEC.md, apps/*/README.md, apps/*/docs/*.md, apps/*/NEXT_STEPS_*.md	App tiene docs propias mas alla de app.md.	Append. Si el contenido encaja mejor en app.md, preferir app.md y mencionar el SPEC desde ahi.

Reglas de decision rapidas

• ¿Cambio visible / breaking / nueva feature? → CHANGELOG.md SI.
• ¿Decision con alternativas descartadas? → ADR SI. Una regla operativa "haz X" sin alternativas → .claude/rules/.
• ¿Cambia como un agente debe comportarse? → .claude/rules/ o .claude/CLAUDE.md (global) o sub-CLAUDE (local).
• ¿Cambia el schema de BDs o columnas? → docs/functions.md/docs/types.md/docs/fn_operations.md + .claude/CLAUDE.md schema rapido.
• ¿Trabajo en un issue? → dev/issues/NNNN-*.md + tabla en dev/issues/README.md.
• ¿Cross-cutting sin artefacto y sin encajar arriba? → solo diario (PASO 4).

---

PASO 2 — Escribir las actualizaciones

Para cada .md identificado:

1. Read el archivo para ver estructura actual y secciones.
2. Decidir si append a seccion existente o crear seccion nueva.
3. Usar Edit para append (preferible) o Write solo si es archivo nuevo.
4. Mantener el estilo del archivo (markdown, viñetas cortas, bloques de codigo con lenguaje).
5. No tocar el frontmatter salvo que el usuario haya cambiado metadata explicita (description, tags, uses_functions, version). Si se toca, re-indexar al final.

Plantilla de bloque para append en .md de artefacto

### {Fase / Tema corto} `[done|wip|notes]`

{1-3 lineas de contexto: que se hizo y por que.}

- Hecho: {cambio concreto, con path y/o ID si aplica}.
- Hecho: {cambio concreto}.
- Bug + fix: {sintoma → raiz → fix} (si procede).
- Decision: {opcion elegida vs alternativa} — porque {razon} (si procede).
- Pendiente: {algo que queda} (si procede).

{Comando(s) exacto(s) si la operacion vale la pena reproducir.}

Plantilla para ## Lo siguiente que pega (apps maduras)

- {Tarea proxima}: {contexto minimo, que tocar, criterio de hecho}.

---

PASO 3 — Reindexar si tocaste frontmatter o creaste artefacto

Si los cambios de la sesion incluyen creacion de funciones/tipos/apps/projects/analysis/vaults o modificacion de frontmatter:

cd $HOME/fn_registry && ./fn index

Y verificar:

./fn show {id_creado_o_modificado}

Si solo se editaron secciones de prosa (Notas, Estado actual, etc.) sin tocar frontmatter, el indexado igual recoge documentation/notes actualizados — re-indexar es barato y deja la BD coherente.

---

PASO 4 — Cerrar con entrada al diario

Invocar /entrada_diario con un resumen conciso de la sesion (3-6 viñetas, verbos en pasado para lo hecho, infinitivo para pendientes). Referenciar:

• IDs de artefactos tocados.
• Paths relativos clave.
• Hashes de commit cortos si la sesion termino con commits.
• ADRs / issues / proposals abiertos.

Ejemplo de invocacion:

/entrada_diario shaders_lab fase 6 — menubar reusable (View + Layouts) cableado, persistencia de layouts en shaders_lab.db

Si el usuario ya invoco /entrada_diario antes en esta sesion para este bloque, no duplicar: solo añadir lo que no estaba.

---

PASO 5 — Reportar al usuario

Resumen breve (formato texto, no tabla a no ser que sean muchos):

=== DOCUMENTADO ===

Artefactos (.md de registry):
  - apps/shaders_lab/app.md           (Fase 6 — menubar)
  - cpp/functions/core/app_menubar.md (notas de uso)
  - cpp/functions/core/layouts_menu.md (notas de cableado)

Globales:
  - CHANGELOG.md                      (Added: app_menubar, layouts_menu)
  - docs/adr/0002-menubar-arch.md     (nuevo ADR — decision menubar reusable)
  - dev/issues/README.md              (issue 0027 → completado)
  - dev/issues/completed/0027-...md   (movido)
  - .claude/rules/cpp_icons.md        (regla nueva, anadida a INDEX.md)

Diario:  docs/diary/2026-04-25.md  (## 18:30 — ...)

Re-indexado: si | no
Pendientes registrados: {N}
Secretos omitidos: {lista de tipos redactados, ej. "REGISTRY_API_TOKEN"}

---

Checklist final

• Cada artefacto tocado tiene su .md actualizado (append, no overwrite).
• Ningun secreto, password, token o key en los archivos.
• Comandos exactos, IDs y paths para que otro LLM reproduzca.
• Decisiones con su "porque", bugs con su raiz+fix.
• CHANGELOG.md actualizado si el cambio es visible al usuario / agentes.
• ADR creado (docs/adr/NNNN-*.md) si hay decision arquitectural con alternativas descartadas.
• dev/issues/*.md y dev/issues/README.md actualizados si la sesion toco issues.
• docs/{architecture,integrity,functions,types,fn_operations,execution_standard,sync_setup,init-pipelines,testing}.md actualizado si el cambio afecta lo que cada uno documenta.
• .claude/CLAUDE.md raiz actualizado si cambian convenciones / comandos / schema globales.
• .claude/rules/* + INDEX.md actualizado si el usuario formaliza una regla nueva.
• Sub-CLAUDE de la app/analysis afectada actualizado si cambia comportamiento agente local.
• /entrada_diario invocado con resumen de la sesion.
• ./fn index corrido si hubo creacion o cambio de frontmatter.
• Reporte final al usuario con la lista de archivos tocados (artefactos + globales).

$ARGUMENTS