shilo-cli 0.6.0 → 0.8.0

package/README.md

@@ -1,243 +1,319 @@
-# shilo-cli
-
-CLI para subir carpetas locales a repositorios de [Shilo](https://www.shilo.city),
-con una experiencia tipo git: `shilo login` una vez y después `shilo push`.
-
-> **Estado:** Fase 5 (colaboración asíncrona). Disponibles `login`, `whoami`, `logout`,
-> `init`, `push`, `pull`, `status`, `log`, `diff`.
-> Ciclo completo: `shilo status` → `shilo pull` → trabajar local → `shilo push`.
-
-## Requisitos
-
-- Node.js **>= 18** (usa `fetch` y `crypto` nativos; sin dependencias de runtime).
-
-## Instalación (local, durante desarrollo)
-
-```bash
-cd cli
-npm link          # expone el comando `shilo` global
-# o, sin link:
-node bin/shilo.js <comando>
-```
-
-## Uso
-
-```bash
-shilo login                 # pregunta email y contraseña (oculta)
-shilo login --email you@example.com
-shilo whoami                # muestra la sesión activa
-shilo logout                # borra las credenciales locales
-```
-
-### Subir una carpeta (flujo tipo git)
-
-```bash
-cd mi-carpeta
-shilo init --project <uuid>       # ata la carpeta al repo (escribe .shilo.json)
-shilo push                        # sube: crea/actualiza + commit
-shilo push -m "mi mensaje"        # con mensaje de commit
-shilo push --dry-run              # muestra qué haría sin subir
-shilo push --card ABC-123         # agrega "[card: ABC-123]" al mensaje del commit
-shilo push --yes                  # sin pedir confirmación
-shilo push --verbose              # lista archivo por archivo en vez de resumir
-shilo push --concurrency 4        # requests en paralelo (1-32, default 8)
-shilo push ./otra-carpeta --project <uuid>   # sin init, proyecto explícito
-```
-
-Sólo se suben archivos de **texto**; binarios, oversize (>25 MB) y nombres con
-caracteres no permitidos se saltan con aviso. Los archivos sin cambios no se
-re-suben.
-
-Los nombres aceptan **espacios, acentos y Unicode** (`Notas Metrónomo.txt`, `日本語.md`):
-sólo se rechaza lo que rompe una ruta o no es portable — `/ \ : * ? " < > |`, bytes de
-control, `.`/`..`, nombres de dispositivo de Windows (`CON`, `NUL`, `COM1`…) y el punto
-final. Los nombres se normalizan a NFC, igual que el backend, para que el mismo archivo
-subido desde macOS y desde Windows sea uno solo.
-
-La subida va **por lotes** (hasta 100 archivos o 4 MB por request) y **cada lote se
-commitea apenas termina**: si el push se corta a la mitad, lo ya escrito queda en el
-historial en vez de quedar suelto en storage. Contra un servidor viejo que no conoce el
-endpoint de lotes, el CLI avisa y sigue archivo por archivo.
-
-#### Qué se ignora
-
-`push` respeta **`.gitignore` y `.shiloignore`**, incluidos los de subcarpetas (una
-regla de `src/.gitignore` sólo alcanza a `src/`). `.shiloignore` se lee último, así que
-podés re-incluir con `!` algo que git ignora. Por defecto ya se saltean `.git/`,
-`node_modules/`, `.shilo/`, `.vercel/`, `.DS_Store` y `Thumbs.db`.
-
-También se poda cualquier carpeta que **tenga forma de repo git** (`HEAD` + `objects/`
-+ `refs/`), aunque no se llame `.git`: un `.git-ORIGINAL-BACKUP/` trae todo el
-historial, incluidos secretos de commits ya borrados del árbol de trabajo.
-
-> **Limitación conocida:** la negación `!` se evalúa por regla, no por directorio. Como
-> en git, `!` no puede re-incluir un archivo si su carpeta padre ya está excluida
-> (`dist/` + `!dist/keep.txt` no funciona); excluí el contenido en vez de la carpeta
-> (`dist/*` + `!dist/keep.txt`).
-
-Lo salteado se reporta **agrupado por motivo** (binario, ilegible, symlink, nombre
-inválido, profundidad) con unos pocos ejemplos; si una carpeta concentra muchos
-descartes, el CLI sugiere la línea de `.shiloignore` que la cubre. Con `--verbose` ves
-la lista completa.
-
-#### Escaneo de secretos
-
-Antes de tocar la red, `push` revisa nombres sospechosos (`.env`, `id_rsa`,
-`*.pem`, credenciales de service account…) y los primeros 8 KB de cada archivo
-buscando patrones de claves (AWS, JWT de Supabase, tokens de GitHub, claves privadas
-PEM…). Si encuentra algo, **no sube nada** y sale con código 1, indicando archivo y
-línea — nunca el valor detectado. Salidas: agregarlo a `.shiloignore`, sacar el
-secreto, o `--allow-secrets` si es un falso positivo.
-
-#### Índice local
-
-`push` guarda un índice en `.shilo/index.json` (tamaño + mtime + hash de lo último
-subido). Los archivos que no cambiaron se resuelven sin bajar el contenido remoto,
-que es lo que hace rápido el segundo push de una carpeta grande. Se puede ignorar con
-`--no-index` para recomparar todo contra el servidor. Agregá `.shilo/` a tu
-`.gitignore` (el CLI ya no lo sube).
-
-En `--dry-run` (y antes de la confirmación interactiva) cada archivo modificado
-muestra **quién lo tocó por última vez y cuándo**, y se avisa explícitamente si vas
-a pisar el trabajo de otra persona. Con token de acceso personal el autor se muestra
-igual, pero no se puede marcar cuál sos vos (el PAT no expone tu id de usuario).
-
-### ¿Estoy desactualizado? (status)
-
-```bash
-shilo status            # compara local vs remoto SIN bajar contenido
-shilo status --short    # sólo rutas
-shilo status --json     # para scripts
-```
-
-Es el comando barato: usa sólo listados de carpeta (una request por carpeta, cero
-descargas de contenido) y compara por **ruta + tamaño**. Informa qué tiene el remoto
-que vos no (con autor y fecha del último commit de cada archivo), qué tenés local sin
-subir, y marca aparte los archivos que cambiaron **de los dos lados** — el caso
-peligroso. **Exit code 2** = estás atrasado respecto del remoto, útil en scripts.
-
-Compensación consciente: dos archivos del mismo tamaño se reportan como iguales
-aunque difieran byte a byte. `shilo diff` y `shilo push` sí comparan contenido.
-
-La comparación con "desde la última vez que sincronicé" se apoya en `lastSync`, que
-`push` y los `pull` completos escriben en `.shilo.json`. Si nunca sincronizaste desde
-esta carpeta, no hay línea de base y los cambios remotos se reportan igual.
-
-### Historial (log)
-
-```bash
-shilo log                       # últimos commits del proyecto
-shilo log src/app.js            # sólo los commits que tocaron ese archivo
-shilo log -n 50 --files         # más commits, listando archivos de cada uno
-shilo log --json
-```
-
-La paginación es **por commit**, no por archivo: si un archivo no aparece, subí `-n`.
-
-### Diferencias (diff)
-
-```bash
-shilo diff                # resumen de todo lo que difiere (sólo metadata)
-shilo diff src/app.js     # diff de contenido línea a línea
-shilo diff src/app.js --context 6
-shilo diff --stat
-```
-
-El diff usa el remoto como base (`---`) y tu copia local como destino (`+++`), o sea
-que las líneas `+` son lo que un `push` agregaría. **Exit code 1** = hay diferencias.
-
-### Bajar un proyecto (pull)
-
-```bash
-shilo pull ./mi-carpeta --project <uuid>   # baja el repo a una carpeta local
-shilo pull --dry-run                        # muestra qué cambiaría localmente, sin bajar nada
-shilo pull --yes                            # sin pedir confirmación
-shilo pull --force                          # sobrescribe también los archivos que difieren
-```
-
-`pull` recorre el árbol remoto (carpeta por carpeta), baja los archivos de texto
-y deja `.shilo.json` listo para un `push` posterior sin `--project`.
-
-Protección del trabajo local sin guardar: **no pisa** un archivo local que difiera del
-remoto salvo con `--force`. Sin `--force` no aborta el pull entero — baja lo que es
-seguro, deja afuera los conflictivos y sale con código 1 para que decidas (mirá
-`shilo diff <archivo>`). Los archivos que sólo existen localmente nunca se tocan: el
-pull no borra. `--dry-run` muestra el impacto sobre tu disco (nuevo / sobrescribe /
-se conserva), no el árbol remoto crudo.
-
-También bloquea nombres que intenten escribir fuera de la carpeta destino (path
-traversal) y saltea binarios con aviso (volverían corruptos). Espejo de `push`:
-`--project` pisa a `.shilo.json`. Con `shilo init --pull` se ata y baja en un solo paso.
-
-### Servidor alternativo
-
-```bash
-shilo login --base-url https://mi-shilo.vercel.app
-```
-
-## Credenciales
-
-Se guardan en `~/.shilo/config.json` (override con `SHILO_CONFIG_DIR`), **cifradas**
-con AES-256-CBC y con permisos `0600`.
-
-- Por defecto la clave de cifrado se deriva de la máquina (hostname + usuario).
-  Esto es **ofuscación en reposo**, no secreto fuerte.
-- Para cifrado fuerte, exportá `SHILO_ENCRYPTION_KEY` (una passphrase propia) antes
-  de `shilo login`; necesitarás la misma variable para futuras ejecuciones.
-
-Se almacena el JWT, el refresh token, la expiración y el email; **no** se guarda la
-contraseña.
-
-### Tokens de acceso personal (PAT)
-
-Un token pasado como `--token abc123` queda en el historial del shell y en la lista de
-procesos (`ps` lo muestra a cualquier usuario de la máquina). El CLI lo acepta —es la
-forma que se copia desde la web— pero avisa. Alternativas:
-
-```bash
-cat pat.txt | shilo login --token -     # lee el token de stdin
-SHILO_TOKEN=<pat> shilo init --project <uuid>   # variable de entorno (lo natural en CI)
-```
-
-## Variables de entorno
-
-| Variable                | Efecto                                                        |
-| ----------------------- | ------------------------------------------------------------- |
-| `SHILO_CONFIG_DIR`      | Directorio de config (default `~/.shilo`).                    |
-| `SHILO_ENCRYPTION_KEY`  | Passphrase para cifrar credenciales (recomendado).            |
-| `SHILO_TOKEN`           | Token de acceso personal (evita pasarlo por `--token`).       |
-| `SHILO_CONCURRENCY`     | Requests en paralelo del push (1-32, default 8).              |
-| `NO_COLOR`              | Desactiva colores ANSI.                                       |
-
-## Roadmap
-
-- **Fase 1 — auth** *(hecho)*: `login`, `whoami`, `logout` + config cifrada.
-- **Fase 2 — motor** *(hecho)*: cliente de archivos (`list`/`getMeta`/`create`/`write`/
-  `ensurePath`/`commit`) + recorrido de árbol (`.shiloignore`) + detección de binarios.
-- **Fase 3 — push** *(hecho)*: `shilo init` + `shilo push` (crea/actualiza + commit,
-  detección de cambios, `.shiloignore`, `--dry-run`).
-- **Fase 4 — pull** *(hecho)*: `shilo pull` (recorrido del árbol remoto con pool,
-  guarda anti path-traversal, salto de binarios, colisiones, binding `.shilo.json`,
-  `--dry-run`). Cierra el ciclo `pull → trabajar local → push`.
-- **Fase 5 — colaboración asíncrona** *(hecho)*: `status` (comparación barata local vs
-  remoto + exit code 2), `log` (historial por proyecto o archivo), `diff` (comparación
-  de contenido + exit code 1), atribución de autor en `push --dry-run`, `pull` que
-  resuelve conflictos por archivo en vez de abortar, `lastSync` en `.shilo.json` y
-  `push --card <id>` para cruzar commits con un tablero externo (Metrónomo).
-- **Fase 6 — robustez del push** *(hecho)*: `.gitignore` (incluidos los anidados),
-  poda de repos git por forma, escaneo de secretos con corte del push, preflight
-  100 % offline antes de tocar la red, planificación con un recorrido del árbol
-  remoto (una request por carpeta en vez de una por archivo), índice local
-  `.shilo/index.json`, lectura perezosa del contenido, reintentos con backoff ante
-  429/5xx, concurrencia adaptativa, barra de progreso y confirmación real en
-  `init --push`.
-
-## Exit codes
-
-| Comando  | Código | Significado                                  |
-| -------- | ------ | -------------------------------------------- |
-| `status` | 2      | El remoto tiene cambios que no tenés.        |
-| `diff`   | 1      | Hay diferencias entre local y remoto.        |
-| `pull`   | 1      | Quedaron conflictos sin bajar (o fallas).    |
-| `push`   | 1      | Se detectaron posibles secretos (nada subido). |
-| cualquiera | 1    | Error.                                       |
+# shilo-cli
+
+CLI para subir carpetas locales a repositorios de [Shilo](https://www.shilo.city),
+con una experiencia tipo git: `shilo login` una vez y después `shilo push`.
+
+> **Estado:** Fase 5 (colaboración asíncrona). Disponibles `login`, `whoami`, `logout`,
+> `init`, `push`, `pull`, `status`, `log`, `diff`.
+> Ciclo completo: `shilo status` → `shilo pull` → trabajar local → `shilo push`.
+
+## Requisitos
+
+- Node.js **>= 18** (usa `fetch` y `crypto` nativos; sin dependencias de runtime).
+
+## Instalación (local, durante desarrollo)
+
+```bash
+cd cli
+npm link          # expone el comando `shilo` global
+# o, sin link:
+node bin/shilo.js <comando>
+```
+
+## Uso
+
+```bash
+shilo login                 # pregunta email y contraseña (oculta)
+shilo login --email you@example.com
+shilo whoami                # muestra la sesión activa
+shilo logout                # borra las credenciales locales
+```
+
+### Subir una carpeta (flujo tipo git)
+
+```bash
+cd mi-carpeta
+shilo init --project <uuid>       # ata la carpeta al repo (escribe .shilo.json)
+shilo push                        # sube: crea/actualiza + commit
+shilo push -m "mi mensaje"        # con mensaje de commit
+shilo push --dry-run              # muestra qué haría sin subir
+shilo push --card ABC-123         # agrega "[card: ABC-123]" al mensaje del commit
+shilo push --agent claude-code --model claude-opus-5   # lo escribió un agente, y queda anotado
+shilo push --agent claude-code --prompt-file pedido.md # guarda además el pedido que lo originó
+shilo push --yes                  # sin pedir confirmación
+shilo push --verbose              # lista archivo por archivo en vez de resumir
+shilo push --concurrency 4        # requests en paralelo (1-32, default 8)
+shilo push ./otra-carpeta --project <uuid>   # sin init, proyecto explícito
+```
+
+Sólo se suben archivos de **texto**; binarios, oversize (>25 MB) y nombres con
+caracteres no permitidos se saltan con aviso. Los archivos sin cambios no se
+re-suben.
+
+Los nombres aceptan **espacios, acentos y Unicode** (`Notas Metrónomo.txt`, `日本語.md`):
+sólo se rechaza lo que rompe una ruta o no es portable — `/ \ : * ? " < > |`, bytes de
+control, `.`/`..`, nombres de dispositivo de Windows (`CON`, `NUL`, `COM1`…) y el punto
+final. Los nombres se normalizan a NFC, igual que el backend, para que el mismo archivo
+subido desde macOS y desde Windows sea uno solo.
+
+Guardar es **proponer**: el push manda todo lo que cambió como una propuesta que parte
+de la versión que esta carpeta vio por última vez (`base` en `.shilo.json`, que
+`pull` y `push` van anotando). El servidor la aplica solo si combina limpio con la
+versión actual. Si otra persona cambió alguno de los **mismos archivos** desde esa
+base, la propuesta **queda abierta y no se pisa nada**: el CLI dice qué archivos son,
+tus cambios quedan guardados en esa propuesta para que el dueño decida, y vos podés
+traer la versión actual con `shilo pull`, ajustar y volver a `push`. Un push nuevo
+reemplaza tus propuestas abiertas anteriores.
+
+El texto viaja inline (hasta 500 archivos o 4 MB por propuesta; más que eso son varias
+propuestas de la misma base); los binarios y los textos de más de 1 MB se suben por URL
+firmada y entran por su identificador de contenido. Contra un servidor anterior a las
+propuestas, el CLI avisa y cae al camino viejo (escribir + commit), que sí puede pisar.
+
+#### Subir sólo una parte (`--only`)
+
+```bash
+shilo push --only Documentacion/decisiones.md --only LEEME.md -m "decisiones de la semana"
+shilo push --only Documentacion/            # un prefijo de carpeta también vale
+```
+
+`--only` es repetible y recorta **qué se sube**, no qué se revisa: los ignores y el
+escaneo de secretos corren igual sobre toda la carpeta. Como el push nunca borra
+archivos remotos, subir un subconjunto es seguro por construcción.
+
+Un selector que **no matchea nada es un error** (código 1) y no sube nada: nunca vas a
+pedir dos archivos y terminar subiendo el repo entero. Al final, el resumen dice
+cuántos archivos con cambios locales quedaron fuera, para que "una pieza = una tarjeta"
+no se convierta en trabajo olvidado. El índice local no se poda con la selección: el
+push completo siguiente sigue siendo rápido.
+
+#### Qué se ignora
+
+`push` respeta **`.gitignore` y `.shiloignore`**, incluidos los de subcarpetas (una
+regla de `src/.gitignore` sólo alcanza a `src/`). `.shiloignore` se lee último, así que
+podés re-incluir con `!` algo que git ignora. Por defecto ya se saltean `.git/`,
+`node_modules/`, `.shilo/`, `.vercel/`, `.DS_Store` y `Thumbs.db`.
+
+También se poda cualquier carpeta que **tenga forma de repo git** (`HEAD` + `objects/`
++ `refs/`), aunque no se llame `.git`: un `.git-ORIGINAL-BACKUP/` trae todo el
+historial, incluidos secretos de commits ya borrados del árbol de trabajo.
+
+> **Limitación conocida:** la negación `!` se evalúa por regla, no por directorio. Como
+> en git, `!` no puede re-incluir un archivo si su carpeta padre ya está excluida
+> (`dist/` + `!dist/keep.txt` no funciona); excluí el contenido en vez de la carpeta
+> (`dist/*` + `!dist/keep.txt`).
+
+Lo salteado se reporta **agrupado por motivo** (binario, ilegible, symlink, nombre
+inválido, profundidad) con unos pocos ejemplos; si una carpeta concentra muchos
+descartes, el CLI sugiere la línea de `.shiloignore` que la cubre. Con `--verbose` ves
+la lista completa.
+
+#### Escaneo de secretos
+
+Antes de tocar la red, `push` revisa nombres sospechosos (`.env`, `id_rsa`,
+`*.pem`, credenciales de service account…) y los primeros 8 KB de cada archivo
+buscando patrones de claves (AWS, JWT de Supabase, tokens de GitHub, claves privadas
+PEM…). Si encuentra algo, **no sube nada** y sale con código 1, indicando archivo y
+línea — nunca el valor detectado. Salidas: agregarlo a `.shiloignore`, sacar el
+secreto, o `--allow-secrets` si es un falso positivo.
+
+#### Índice local
+
+`push` guarda un índice en `.shilo/index.json` (tamaño + mtime + hash de lo último
+subido). Los archivos que no cambiaron se resuelven sin bajar el contenido remoto,
+que es lo que hace rápido el segundo push de una carpeta grande. Se puede ignorar con
+`--no-index` para recomparar todo contra el servidor. Agregá `.shilo/` a tu
+`.gitignore` (el CLI ya no lo sube).
+
+`--dry-run` lista qué se crearía y qué se actualizaría, sin tocar la red más que para
+leer el árbol. Ya no hace falta adivinar si vas a pisar a alguien: eso lo decide el
+servidor con la base exacta, y si pasa, no pisa.
+
+### ¿Estoy desactualizado? (status)
+
+```bash
+shilo status                 # compara local vs remoto SIN bajar contenido
+shilo status --short         # sólo rutas
+shilo status --show-ignored  # lista los archivos del remoto ignorados localmente
+shilo status --json          # para scripts
+```
+
+Es el comando barato: usa sólo listados de carpeta (una request por carpeta, cero
+descargas de contenido) y compara por **ruta + tamaño**. Informa qué tiene el remoto
+que vos no (con autor y fecha del último commit de cada archivo), qué tenés local sin
+subir, y marca aparte los archivos que cambiaron **de los dos lados** — el caso
+peligroso. **Exit code 2** = estás atrasado respecto del remoto, útil en scripts.
+
+**Los ignores valen en los dos sentidos.** Un archivo que existe en el remoto pero
+está ignorado localmente (un `.env.ejemplo`, un `settings.local.json` que alguien subió
+desde otra máquina) **no cuenta como "atrás"**: se informa en una línea aparte —con
+`--show-ignored` para verlos, y en el campo `ignoredRemote` del `--json`— pero no
+enciende el exit code 2. Antes quedaba en "faltan localmente" para siempre y la señal
+que debería frenarte era ruido permanente.
+
+Compensación consciente: dos archivos del mismo tamaño se reportan como iguales
+aunque difieran byte a byte. `shilo diff` y `shilo push` sí comparan contenido.
+
+La comparación con "desde la última vez que sincronicé" se apoya en `lastSync`, que
+`push` y los `pull` completos escriben en `.shilo.json`. Si nunca sincronizaste desde
+esta carpeta, no hay línea de base y los cambios remotos se reportan igual.
+
+### Historial (log)
+
+```bash
+shilo log                       # últimos commits del proyecto
+shilo log src/app.js            # sólo los commits que tocaron ese archivo
+shilo log -n 50 --files         # más commits, listando archivos de cada uno
+shilo log --json
+```
+
+La paginación es **por commit**, no por archivo: si un archivo no aparece, subí `-n`.
+
+### Diferencias (diff)
+
+```bash
+shilo diff                # resumen de todo lo que difiere (sólo metadata)
+shilo diff src/app.js     # diff de contenido línea a línea
+shilo diff src/app.js --context 6
+shilo diff --stat
+```
+
+El diff usa el remoto como base (`---`) y tu copia local como destino (`+++`), o sea
+que las líneas `+` son lo que un `push` agregaría. **Exit code 1** = hay diferencias.
+
+### Bajar un proyecto (pull)
+
+```bash
+shilo pull ./mi-carpeta --project <uuid>   # baja el repo a una carpeta local
+shilo pull --dry-run                        # muestra qué cambiaría localmente, sin bajar nada
+shilo pull --yes                            # sin pedir confirmación
+shilo pull --force                          # sobrescribe también los archivos que difieren
+shilo pull --include-ignored                # baja también lo ignorado localmente
+```
+
+`pull` recorre el árbol remoto (carpeta por carpeta), baja los archivos de texto
+y deja `.shilo.json` listo para un `push` posterior sin `--project`.
+
+Protección del trabajo local sin guardar: **no pisa** un archivo local que difiera del
+remoto salvo con `--force`. Sin `--force` no aborta el pull entero — baja lo que es
+seguro, deja afuera los conflictivos y sale con código 1 para que decidas (mirá
+`shilo diff <archivo>`). Los archivos que sólo existen localmente nunca se tocan: el
+pull no borra. `--dry-run` muestra el impacto sobre tu disco (nuevo / sobrescribe /
+se conserva), no el árbol remoto crudo.
+
+**Respaldo automático con `--force`.** Antes de pisar un archivo local que difería, el
+pull guarda tu versión en `.shilo/respaldo/<fecha-ISO>/<ruta>` y te dice la carpeta al
+terminar. Va dentro de `.shilo/` —ignorado por defecto— y no como un `<archivo>.local`
+al lado, que el push siguiente subiría: cambiaríamos "perder trabajo" por "publicar tu
+versión en conflicto". Al ir por fecha, dos pulls seguidos no se pisan entre sí.
+
+**Lo ignorado localmente no se baja.** Si `.env.*` está en tu `.shiloignore`, que
+alguien haya subido un `.env.ejemplo` desde otra máquina no lo hace aparecer acá: se
+cuenta aparte como "ignorados (no se bajan)", y con `--include-ignored` se bajan igual.
+Esto también arregla el conteo, que antes prometía más archivos de los que escribía.
+
+También bloquea nombres que intenten escribir fuera de la carpeta destino (path
+traversal) y saltea binarios con aviso (volverían corruptos). Espejo de `push`:
+`--project` pisa a `.shilo.json`. Con `shilo init --pull` se ata y baja en un solo paso.
+
+### Exportar a Git (export)
+
+```bash
+shilo export ../mi-repo --project <uuid>   # la historia entera, como repositorio Git
+shilo export ../mi-repo                     # otra vez: trae sólo lo nuevo
+git -C ../mi-repo push <remoto> main
+git -C ../mi-repo push <remoto> +refs/notes/shilo
+```
+
+Escribe todos los puntos de guardado de `main` como commits de Git, con su autor y
+su fecha, y la procedencia (agente, tarjeta, propuesta) al pie de cada mensaje y
+completa en `refs/notes/shilo`. Es de sólo lectura para el proyecto. Necesita `git`
+en el PATH; un proyecto público se exporta sin sesión.
+
+- **La primera vez**, la carpeta tiene que estar vacía o no existir. Después, repetir
+  el comando sobre la misma carpeta baja sólo los archivos nuevos
+  (`.git/shilo/mapa` recuerda lo exportado) y exige que lo viejo dé los mismos SHA-1.
+- **Determinístico:** el mismo proyecto da los mismos SHA-1 en cualquier máquina. Los
+  commits firman con el nombre congelado de cada persona y
+  `<usuario>@users.noreply.shilo.city`, nunca con su correo real.
+- **No pisa trabajo ajeno:** si `main` tiene commits que no salieron de Shilo, o hay
+  cambios sin guardar, se niega y no toca nada.
+- **Git no guarda carpetas vacías:** quedan afuera y el informe las lista.
+- La ref de notas se rehace entera en cada exportación: por eso el `+` en su push.
+
+### Servidor alternativo
+
+```bash
+shilo login --base-url https://mi-shilo.vercel.app
+```
+
+## Credenciales
+
+Se guardan en `~/.shilo/config.json` (override con `SHILO_CONFIG_DIR`), **cifradas**
+con AES-256-CBC y con permisos `0600`.
+
+- Por defecto la clave de cifrado se deriva de la máquina (hostname + usuario).
+  Esto es **ofuscación en reposo**, no secreto fuerte.
+- Para cifrado fuerte, exportá `SHILO_ENCRYPTION_KEY` (una passphrase propia) antes
+  de `shilo login`; necesitarás la misma variable para futuras ejecuciones.
+
+Se almacena el JWT, el refresh token, la expiración y el email; **no** se guarda la
+contraseña.
+
+### Tokens de acceso personal (PAT)
+
+Un token pasado como `--token abc123` queda en el historial del shell y en la lista de
+procesos (`ps` lo muestra a cualquier usuario de la máquina). El CLI lo acepta —es la
+forma que se copia desde la web— pero avisa. Alternativas:
+
+```bash
+cat pat.txt | shilo login --token -     # lee el token de stdin
+SHILO_TOKEN=<pat> shilo init --project <uuid>   # variable de entorno (lo natural en CI)
+```
+
+## Variables de entorno
+
+| Variable                | Efecto                                                        |
+| ----------------------- | ------------------------------------------------------------- |
+| `SHILO_CONFIG_DIR`      | Directorio de config (default `~/.shilo`).                    |
+| `SHILO_ENCRYPTION_KEY`  | Passphrase para cifrar credenciales (recomendado).            |
+| `SHILO_TOKEN`           | Token de acceso personal (evita pasarlo por `--token`).       |
+| `SHILO_CONCURRENCY`     | Requests en paralelo del push (1-32, default 8).              |
+| `NO_COLOR`              | Desactiva colores ANSI.                                       |
+
+## Roadmap
+
+- **Fase 1 — auth** *(hecho)*: `login`, `whoami`, `logout` + config cifrada.
+- **Fase 2 — motor** *(hecho)*: cliente de archivos (`list`/`getMeta`/`create`/`write`/
+  `ensurePath`/`commit`) + recorrido de árbol (`.shiloignore`) + detección de binarios.
+- **Fase 3 — push** *(hecho)*: `shilo init` + `shilo push` (crea/actualiza + commit,
+  detección de cambios, `.shiloignore`, `--dry-run`).
+- **Fase 4 — pull** *(hecho)*: `shilo pull` (recorrido del árbol remoto con pool,
+  guarda anti path-traversal, salto de binarios, colisiones, binding `.shilo.json`,
+  `--dry-run`). Cierra el ciclo `pull → trabajar local → push`.
+- **Fase 5 — colaboración asíncrona** *(hecho)*: `status` (comparación barata local vs
+  remoto + exit code 2), `log` (historial por proyecto o archivo), `diff` (comparación
+  de contenido + exit code 1), atribución de autor en `push --dry-run`, `pull` que
+  resuelve conflictos por archivo en vez de abortar, `lastSync` en `.shilo.json` y
+  `push --card <id>` para cruzar commits con un tablero externo (Metrónomo).
+- **Fase 6 — robustez del push** *(hecho)*: `.gitignore` (incluidos los anidados),
+  poda de repos git por forma, escaneo de secretos con corte del push, preflight
+  100 % offline antes de tocar la red, planificación con un recorrido del árbol
+  remoto (una request por carpeta en vez de una por archivo), índice local
+  `.shilo/index.json`, lectura perezosa del contenido, reintentos con backoff ante
+  429/5xx, concurrencia adaptativa, barra de progreso y confirmación real en
+  `init --push`.
+- **Fase 7 — propuestas** *(hecho)*: `push` deja de escribir archivo por archivo y
+  manda una propuesta con la base exacta; el servidor la combina con la versión actual
+  y nunca pisa un archivo que otra persona cambió. `base` en `.shilo.json`,
+  `registerBlob` para binarios, camino viejo sólo como reserva.
+
+## Exit codes
+
+| Comando  | Código | Significado                                  |
+| -------- | ------ | -------------------------------------------- |
+| `status` | 2      | El remoto tiene cambios que no tenés.        |
+| `diff`   | 1      | Hay diferencias entre local y remoto.        |
+| `pull`   | 1      | Quedaron conflictos sin bajar (o fallas).    |
+| `push`   | 1      | Se detectaron posibles secretos (nada subido). |
+| cualquiera | 1    | Error.                                       |