---
name: generate_capability_doc
kind: pipeline
lang: bash
domain: pipelines
version: "1.0.0"
purity: impure
signature: "generate_capability_doc(group: string, --registry: string?, --out: string?) -> void"
description: "Regenera la tabla de funciones de una pagina capability en docs/capabilities/<group>.md consultando registry.db. Preserva bloques curated (Ejemplo canonico, Fronteras, Prerequisitos, Notas). Si el archivo no existe lo crea con plantilla minima."
tags: ["capability-groups", "docs", "doctor", "generator", "pipeline"]
uses_functions:
  - audit_capability_groups_go_infra
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: []
params:
  - name: group
    desc: "slug del capability group (ej. notebook, metabase). Coincide con el tag canonico en frontmatter de funciones."
  - name: --registry
    desc: "path opcional a registry.db o a su directorio padre (default: walk-up desde cwd hasta encontrar registry.db)."
  - name: --out
    desc: "path opcional del archivo de salida (default: <root>/docs/capabilities/<group>.md)."
output: "path del archivo actualizado o creado + count de funciones a stdout. Exit 0 ok, exit 1 si error."
tested: false
tests: []
test_file_path: ""
file_path: "bash/functions/pipelines/generate_capability_doc.sh"
---

## Ejemplo

```bash
# Regenerar tabla de notebook (ya existe, preserva Ejemplo canonico / Fronteras)
./bash/functions/pipelines/generate_capability_doc.sh notebook
# → $HOME/fn_registry/docs/capabilities/notebook.md updated (5 functions)

# Crear pagina nueva para un grupo sin pagina todavia
./bash/functions/pipelines/generate_capability_doc.sh metabase
# → $HOME/fn_registry/docs/capabilities/metabase.md created (12 functions)

# Especificar registry y destino custom
./bash/functions/pipelines/generate_capability_doc.sh android \
    --registry /ruta/alternativa/registry.db \
    --out /tmp/android_cap.md
# → /tmp/android_cap.md created (8 functions)

# Grupo sin funciones todavia (avisa pero no falla)
./bash/functions/pipelines/generate_capability_doc.sh nuevo_grupo
# WARN: El grupo 'nuevo_grupo' no tiene funciones con ese tag en registry.db.
# → $HOME/fn_registry/docs/capabilities/nuevo_grupo.md created (0 functions)
```

## Comportamiento detallado

### Resolucion de root

Walk-up desde `cwd` buscando `registry.db`. Si se pasa `--registry`:
- Si es un archivo: toma el directorio padre.
- Si es un directorio: lo usa directamente.

### Tabla generada (SQL)

```sql
SELECT f.id, f.signature, f.description
FROM functions f, json_each(f.tags) j
WHERE j.value = '<group>'
ORDER BY f.id;
```

JOIN custom via `json_each` — usa `sqlite3` directo (excepcion autorizada para JOINs no expuestos por MCP).

### Formato de tabla

```markdown
| ID | Firma | Que hace |
|---|---|---|
| `<id>` | `<signature>` | <description> |
```

Los `|` dentro de signatures y descriptions se escapan como `\|`.

### Preservacion de bloques curated

Cuando el archivo ya existe:
- El bloque entre `## Funciones` y la siguiente `## ` se reemplaza.
- Todo lo anterior y posterior (Ejemplo canonico, Fronteras, Prerequisitos, Notas, etc.) se mantiene intacto.
- Implementado con `awk`: copia hasta `## Funciones`, imprime nueva tabla, salta contenido viejo hasta encontrar `^## `, reanuda copia.

### Archivo nuevo

Si `docs/capabilities/<group>.md` no existe, se crea con plantilla minima:
- Titulo `# Capability: <group>`.
- Placeholder de descripcion (editable a mano).
- Tabla generada.
- Secciones vacias: `## Ejemplo canonico`, `## Fronteras`.

## Codigos de salida

| Codigo | Significado |
|--------|-------------|
| 0 | Exito |
| 1 | Error: grupo no especificado, registry.db no encontrado, fallo SQL, awk vacio |

## Notas

- `uses_functions: []` — depende de `sqlite3` y `awk` del sistema, no de funciones del registry.
- El tag del grupo debe ser plano (ej. `notebook`, `metabase`), no `tag:notebook`.
- Enganchado en `docs/capabilities/INDEX.md` como el mecanismo de auto-generacion referenciado bajo `fn doctor capabilities --update`.
- Seguro para re-ejecucion: idempotente si el registry no cambia.