# /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:
   ```bash
   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`:

```bash
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

```markdown

### {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)

```markdown
- {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:

```bash
cd $HOME/fn_registry && ./fn index
```

Y verificar:

```bash
./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
