# Instalar Firmín: instrucciones para agentes

Estas instrucciones son para un agente de IA (Claude Code, Codex, etc.) que
trabaja en la terminal del Mac de una persona que le ha pedido instalar Firmín.
Síguelas en orden y cuéntale a la persona qué haces en cada paso.

Firmín (https://firmin.gobierto.es) firma PDFs con un certificado digital del
llavero de macOS (PAdES-B-B, SHA-256), desde el Finder (clic derecho → Firmar
con Firmín), desde su ventana o desde la terminal con la orden `firmin`. Es
gratuita, de Gobierto, y no necesita Java ni AutoFirma.

## 1. Comprueba el Mac

```sh
sw_vers -productVersion        # hace falta macOS 13 o posterior
ls -d "/Applications/Firmín.app" 2>/dev/null && echo "Ya está instalada"
```

Si ya está instalada, no la reinstales: Firmín se actualiza sola. Pasa al paso 4.

## 2. Instala la app

Desde el DMG:

```sh
curl -fL -o /tmp/Firmin.dmg https://firmin.gobierto.es/descargas/Firmin.dmg
hdiutil attach -quiet -nobrowse -readonly -mountpoint /tmp/firmin-dmg /tmp/Firmin.dmg
ditto "/tmp/firmin-dmg/Firmín.app" "/Applications/Firmín.app"
hdiutil detach -quiet /tmp/firmin-dmg
rm /tmp/Firmin.dmg
```

La orden `firmin` (desde la versión 0.2) la enlaza la propia app en
`~/.local/bin/firmin` al abrirla desde Aplicaciones (paso 3), sin contraseña.
Si `firmin` no se encuentra después, es que `~/.local/bin` no está en el PATH:
usa la ruta completa, `"/Applications/Firmín.app/Contents/Helpers/firmin"`.

## 3. Ábrela una vez

```sh
open -a "Firmín"
```

La primera vez, Firmín registra sus extensiones del Finder y enseña una
bienvenida. Pide a la persona que la mire; puede cerrarla después.

**Si macOS dice que no puede comprobar la app** (Firmín todavía no está
notarizada por Apple): la persona tiene que ir a **Ajustes del Sistema →
Privacidad y seguridad** y pulsar **Abrir igualmente**. Eso no lo puedes hacer
tú. Si además `firmin` termina sin decir nada (código 137), es el mismo
bloqueo; con el permiso de la persona, y no antes, se quita con:

```sh
xattr -dr com.apple.quarantine "/Applications/Firmín.app"
```

## 4. Comprueba que funciona

```sh
pluginkit -m -i es.gobierto.Firmin.FinderMenu     # «+» delante: activa
firmin --version                                  # si está la orden firmin
firmin certs                                      # los certificados de firma
```

- Si la extensión no aparece o no tiene «+», que la persona la active en
  **Ajustes del Sistema → General → Ítems de inicio y extensiones →
  Extensiones de archivos del Finder**, o reinicia el Finder: `killall Finder`.
- Si `firmin certs` no lista ningún certificado, la persona tiene que
  instalar el suyo: doble clic sobre el `.p12` o `.pfx` (lo añade al llavero).
  El DNI electrónico y las tarjetas criptográficas todavía no funcionan.

Termina diciéndole a la persona que ya puede firmar: en el Finder, clic derecho
sobre un PDF → **Firmar con Firmín**.

## 5. Firmar por la persona (solo si te lo pide)

Sigue https://firmin.gobierto.es/cli.md: las órdenes, lo que devuelve cada una
en JSON y las reglas. En resumen: firma solo lo que te pide, pregunta qué
certificado si hay varios, enséñale la vista previa antes de firmar y, si
deniega el permiso de la clave (código 3), no lo reintentes.

```sh
firmin certs --json                                   # elige el certificado (huella SHA-1)
firmin detect contrato.pdf --cert <huella> --json     # dónde irá la firma visible
firmin preview contrato.pdf --cert <huella> -o /tmp/vista.png   # la página con la firma
firmin sign contrato.pdf --cert <huella> --json       # guarda contrato-firmado.pdf
```

## Desinstalar

Borra la app con `rm -rf "/Applications/Firmín.app"` y, si existe, el
enlace con `rm ~/.local/bin/firmin`.

Ayuda y contacto: https://firmin.gobierto.es/ayuda/ · abre@gobierto.es