docs: README rewrite, per-language READMEs, hello-world example

AGENTS.md

@@ -51,7 +51,7 @@ src/
   output/
   **/*.test.ts   # unit tests colocated next to source
 tests/           # shared helpers/fixtures + optional *.integration.test.ts
-examples/roundtrip/
+examples/hello-world/
 scripts/
   evidenceLocal.ts
 .github/workflows/

CODE-STYLE.md

@@ -150,24 +150,27 @@ Agent Session Pack is CLI-only.
 - `--json` never prompts and never emits ANSI.
 - Long flags are preferred. Only obvious short aliases like `-h` and `-v` are allowed.
 - Durations accept `7d`, `2w`, `30d`, and `12h`.
-- `--provider` is repeatable.
+- `--provider` takes one provider id: `codex`, `claude`, `kiro`, `grok`, `kimi`, `opencode`, `gemini`, `cursor`, or `devin`. Use `--all-providers` for every provider.
 
-Commands:
+Commands (`<id>` is a provider id):
 
 ```bash
 agent-session-pack guide [--json]
-agent-session-pack check [--provider codex|claude|kiro|cursor|devin] [--json]
-agent-session-pack init [--apply] [--json]
-agent-session-pack scan [--provider codex|claude|kiro|cursor|devin] [--json]
-agent-session-pack pack [--all-providers|--provider codex|claude|kiro|cursor|devin] [--older-than 7d|--max] [--dry-run|--apply] [--yes] [--json]
-agent-session-pack unpack [--all-providers|--provider codex|claude|kiro|cursor|devin] [--apply] [--yes] [--json]
-agent-session-pack savings [--provider codex|claude|kiro|cursor|devin] [--json]
-agent-session-pack list [--provider codex|claude|kiro|cursor|devin] [--json]
-agent-session-pack restore <selector> [--to original|<path>] [--json]
-agent-session-pack pin <selector>
-agent-session-pack unpin <selector>
+agent-session-pack check [--provider <id>] [--json]
+agent-session-pack savings [--provider <id>] [--json]
+agent-session-pack scan [--provider <id>] [--json]
 agent-session-pack doctor [--json]
-agent-session-pack prune [--quarantine] [--dry-run|--apply]
+agent-session-pack init [--apply] [--json]
+agent-session-pack pack [--all-providers|--provider <id>] [--older-than 7d|--max] [--dry-run|--apply] [--yes] [--json]
+agent-session-pack unpack [--all-providers|--provider <id>] [--apply] [--yes] [--json]
+agent-session-pack restore <selector> [--provider <id>] [--to original] [--json]
+agent-session-pack open <session> [--provider <id>] [--json]
+agent-session-pack list [--provider <id>] [--json]
+agent-session-pack lifecycle enable|disable|status [--json]
+agent-session-pack maintain [--dry-run|--apply] [--yes] [--json]
+agent-session-pack preflight --provider <id> [--json]
+agent-session-pack watch [--provider <id>] [--poll-ms 750] [--json]
+agent-session-pack ensure-restored <session> [--provider <id>] [--json]
 ```
 
 Local package scripts should cover the common human paths:

README.es.md

@@ -0,0 +1,137 @@
+<p align="center">
+  <a href="https://github.com/YosefHayim/agent-session-pack"><img src="https://raw.githubusercontent.com/YosefHayim/agent-session-pack/main/assets/hero.png" alt="Agent Session Pack: comprime el historial local de sesiones de agentes de programación con IA en un archivo zstd verificado y lo restaura byte a byte" width="820" /></a>
+</p>
+
+<p align="center">
+  <strong>Almacenamiento en frío para sesiones locales de agentes de programación con IA. Reduce en disco el historial de Codex, Claude Code, Kiro, Grok, Kimi, OpenCode y Gemini CLI, y recupera cada byte al restaurar.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/agent-session-pack"><img src="https://img.shields.io/npm/v/agent-session-pack?logo=npm&color=cb3837" alt="versión en npm" /></a>
+  <a href="https://www.npmjs.com/package/agent-session-pack"><img src="https://img.shields.io/npm/dm/agent-session-pack?logo=npm&color=cb3837" alt="descargas mensuales en npm" /></a>
+  <a href="https://github.com/YosefHayim/agent-session-pack/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/YosefHayim/agent-session-pack/ci.yml?branch=main&logo=github&label=CI" alt="estado de CI" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/agent-session-pack?color=blue" alt="licencia MIT" /></a>
+  <img src="https://img.shields.io/node/v/agent-session-pack?logo=node.js&color=339933" alt="versión de Node.js requerida" />
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> · <a href="README.ja.md">日本語</a> · <a href="README.he.md">עברית</a> · <strong>Español</strong> · <a href="README.zh-CN.md">简体中文</a>
+</p>
+
+---
+
+**Agent Session Pack** es una CLI de [Node.js](https://nodejs.org/en) para desarrolladores y agentes de programación cuyo historial local de sesiones ha crecido demasiado. Encuentra los almacenes de sesiones de Codex, Claude Code, Kiro, Grok, Kimi Code, OpenCode, Gemini CLI, Cursor y Devin, demuestra la compresión sin pérdida con [Zstandard](https://facebook.github.io/zstd/) sobre copias y empaqueta las sesiones frías en una bóveda local solo cuando se lo pides. Antes de borrar un archivo original, siempre restaura el archivo comprimido y compara los hashes SHA-256.
+
+Sin demonio, sin sincronización en la nube, sin resúmenes. Tus sesiones nunca salen de tu máquina.
+
+> La documentación completa está en inglés en [README.md](README.md).
+
+## Características
+
+- **9 agentes de programación** - Codex, Claude Code, Kiro, Grok, Kimi Code, OpenCode y Gemini CLI se empaquetan y restauran; Cursor y Devin son solo de respaldo.
+- **Prueba antes de cambiar** - `check` copia una sesión por agente, la comprime, la restaura y compara hashes. Los archivos reales no se tocan.
+- **Restauración byte a byte** - cada archivo comprimido se restaura y se verifica con SHA-256 antes de borrar el original.
+- **Simulación por defecto** - nada se borra sin `--apply`, y `--apply` pide confirmación salvo que pases `--yes`.
+- **Filtro de sesiones frías** - `--older-than 7d` (o `12h`, `1d`, `2w`, `30d`) protege tu trabajo activo.
+- **Pensado para agentes** - `guide --json` muestra el mapa de comandos seguros y los comandos principales tienen salida `--json` estable.
+
+## Agentes compatibles
+
+| Agente | Modo | Almacén de sesiones |
+| --- | --- | --- |
+| Codex | Archivo | `~/.codex/sessions` |
+| Claude Code | Archivo | `~/.claude/projects` |
+| Kiro | Archivo | `~/.kiro/sessions` |
+| Grok | Archivo | `~/.grok/sessions` (carpetas completas) |
+| Kimi Code | Archivo | `~/.kimi-code/sessions` (carpetas completas) |
+| OpenCode | Archivo | `~/.local/share/opencode`, `~/.opencode` |
+| Gemini CLI | Archivo | `~/.gemini`, `~/.gemini/tmp` |
+| Cursor | Solo respaldo | `~/Library/Application Support/Cursor` |
+| Devin | Solo respaldo | `~/.local/share/devin/cli` (solo lee metadatos de `sessions.db`) |
+
+## Resultados
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/YosefHayim/agent-session-pack/main/assets/benchmarks.svg" alt="Tamaño de las sesiones antes y después de empaquetar en una máquina" width="820" />
+</p>
+
+| Agente | Antes | Después | Ahorro |
+| --- | ---: | ---: | ---: |
+| Codex | 2.22 GB | 782 MB | **65.6%** |
+| Claude Code | 2.10 GB | 457 MB | **78.7%** |
+| Kiro | 1.95 GB | 190 MB | **90.5%** |
+| Cursor (copia de respaldo) | 7.27 GB | 957 MB | **87.1%** |
+| **Total** | **13.5 GB** | **2.3 GB** | **~83%** |
+
+Son datos reales de una sola máquina, no un benchmark universal. Mide los tuyos con `npx --yes agent-session-pack check` (solo trabaja con copias).
+
+## Inicio rápido
+
+Requisitos: [Node.js](https://nodejs.org/en) 20 o superior, [`zstd`](https://facebook.github.io/zstd/) en tu `PATH` y `sqlite3` solo si usas Devin.
+
+```bash
+# 1. Demuestra el ahorro sobre copias (no toca los archivos reales)
+npx --yes agent-session-pack check
+
+# 2. Previsualiza qué se empaquetaría
+npx --yes agent-session-pack pack --all-providers --older-than 7d --dry-run
+
+# 3. Empaqueta las sesiones frías (borra originales solo tras verificar)
+npx --yes agent-session-pack pack --all-providers --older-than 7d --apply
+
+# 4. Restaura cuando lo necesites
+npx --yes agent-session-pack unpack --all-providers --apply
+npx --yes agent-session-pack restore SESSION_ID_OR_NAME
+```
+
+Ejecuta `npx --yes agent-session-pack` sin argumentos para abrir un menú guiado en la terminal.
+
+## Modelo de seguridad
+
+- `check` y `savings` solo trabajan con copias.
+- `pack --all-providers` es una simulación salvo que añadas `--apply`.
+- `pack --apply` pide confirmación en la terminal salvo que añadas `--yes`.
+- `pack --max --apply` se rechaza.
+- Al aplicar: escribe el archivo, lo restaura, compara SHA-256, escribe un manifiesto y solo entonces borra el original.
+- `unpack --apply` omite los archivos vivos que cambiaron en lugar de sobrescribirlos.
+- Cursor y Devin son solo de respaldo: sus almacenes nativos nunca se modifican.
+
+## Ciclo de vida: restauración automática al abrir
+
+El ciclo de vida está desactivado hasta que lo actives. `lifecycle enable` instala envoltorios para los agentes, y una sesión empaquetada se restaura sola cuando la abres. `maintain --apply` vuelve a empaquetar las sesiones que se enfriaron otra vez. Más detalles en el [README en inglés](README.md#lifecycle-auto-restore-on-launch).
+
+## Preguntas frecuentes
+
+<details>
+<summary><strong>¿Es compactación o resumen del contexto?</strong></summary>
+
+No. Nunca resume, reescribe ni recorta una conversación. Usa compresión sin pérdida y verifica la restauración byte a byte.
+</details>
+
+<details>
+<summary><strong>¿Lee credenciales o sube sesiones?</strong></summary>
+
+No. Escanea almacenes locales y escribe archivos locales. Para Devin lee metadatos de la base SQLite local y nunca lee credenciales.
+</details>
+
+<details>
+<summary><strong>¿En qué se diferencia de borrar sesiones antiguas?</strong></summary>
+
+Borrar no tiene vuelta atrás. Agent Session Pack escribe un archivo, demuestra que restaura exactamente los bytes originales, escribe un manifiesto y solo entonces borra el original.
+</details>
+
+## Licencia
+
+MIT - consulta [LICENSE](LICENSE).
+
+---
+
+<div align="center">
+
+<a href="https://www.buymeacoffee.com/yosefhayim" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="48" /></a>
+
+<br /><br />
+
+**[Apoya este proyecto](https://www.buymeacoffee.com/yosefhayim)** · Creado por [Yosef Hayim Sabag](https://github.com/YosefHayim)
+
+</div>

README.he.md

@@ -0,0 +1,145 @@
+<div dir="rtl">
+
+<p align="center">
+  <a href="https://github.com/YosefHayim/agent-session-pack"><img src="https://raw.githubusercontent.com/YosefHayim/agent-session-pack/main/assets/hero.png" alt="Agent Session Pack: דחיסת היסטוריית סשנים מקומית של סוכני קוד לארכיון zstd מאומת ושחזור מדויק ברמת הבייט" width="820" /></a>
+</p>
+
+<p align="center">
+  <strong>אחסון קר לסשנים מקומיים של סוכני קוד מבוססי AI. מקטין את נפח ההיסטוריה של Codex, Claude Code, Kiro, Grok, Kimi, OpenCode ו־Gemini CLI בדיסק, ומחזיר כל בייט בשחזור.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/agent-session-pack"><img src="https://img.shields.io/npm/v/agent-session-pack?logo=npm&color=cb3837" alt="גרסת npm" /></a>
+  <a href="https://www.npmjs.com/package/agent-session-pack"><img src="https://img.shields.io/npm/dm/agent-session-pack?logo=npm&color=cb3837" alt="הורדות npm בחודש" /></a>
+  <a href="https://github.com/YosefHayim/agent-session-pack/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/YosefHayim/agent-session-pack/ci.yml?branch=main&logo=github&label=CI" alt="סטטוס CI" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/agent-session-pack?color=blue" alt="רישיון MIT" /></a>
+  <img src="https://img.shields.io/node/v/agent-session-pack?logo=node.js&color=339933" alt="גרסת Node.js נדרשת" />
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> · <a href="README.ja.md">日本語</a> · <strong>עברית</strong> · <a href="README.es.md">Español</a> · <a href="README.zh-CN.md">简体中文</a>
+</p>
+
+---
+
+**Agent Session Pack** הוא כלי CLI מבוסס [Node.js](https://nodejs.org/en) למפתחים ולסוכני קוד שהיסטוריית הסשנים המקומית שלהם גדלה. הכלי מוצא את תיקיות הסשנים של Codex, Claude Code, Kiro, Grok, Kimi Code, OpenCode, Gemini CLI, Cursor ו־Devin, מוכיח דחיסה ללא אובדן עם [Zstandard](https://facebook.github.io/zstd/) על עותקים, ואורז סשנים קרים לכספת מקומית רק כשמבקשים ממנו. לפני שקובץ מקורי נמחק, הארכיון משוחזר ו־hash מסוג SHA-256 מושווה.
+
+בלי שירות רקע, בלי סנכרון לענן, בלי סיכומים. הסשנים לא יוצאים מהמחשב.
+
+> התיעוד המלא נמצא ב־[README.md](README.md) באנגלית.
+
+## יכולות
+
+- **9 סוכני קוד** - Codex, Claude Code, Kiro, Grok, Kimi Code, OpenCode ו־Gemini CLI נארזים ומשוחזרים. Cursor ו־Devin במצב גיבוי בלבד.
+- **הוכחה לפני שינוי** - `check` מעתיק סשן אחד לכל סוכן, דוחס, משחזר ומשווה hash. הקבצים האמיתיים לא נוגעים.
+- **שחזור מדויק ברמת הבייט** - כל ארכיון משוחזר ונבדק ב־SHA-256 לפני מחיקת המקור.
+- **הרצת ניסיון כברירת מחדל** - שום דבר לא נמחק בלי `--apply`, ו־`--apply` מבקש אישור אלא אם מעבירים `--yes`.
+- **סינון סשנים קרים** - `--older-than 7d` (או `12h`, `1d`, `2w`, `30d`) שומר על העבודה הפעילה.
+- **מותאם לסוכנים** - `guide --json` מדפיס מפת פקודות בטוחה, ולפקודות העיקריות יש פלט `--json` יציב.
+
+## סוכנים נתמכים
+
+| סוכן | מצב | תיקיית סשנים |
+| --- | --- | --- |
+| Codex | ארכיון | `~/.codex/sessions` |
+| Claude Code | ארכיון | `~/.claude/projects` |
+| Kiro | ארכיון | `~/.kiro/sessions` |
+| Grok | ארכיון | `~/.grok/sessions` (תיקיות שלמות) |
+| Kimi Code | ארכיון | `~/.kimi-code/sessions` (תיקיות שלמות) |
+| OpenCode | ארכיון | `~/.local/share/opencode`, `~/.opencode` |
+| Gemini CLI | ארכיון | `~/.gemini`, `~/.gemini/tmp` |
+| Cursor | גיבוי בלבד | `~/Library/Application Support/Cursor` |
+| Devin | גיבוי בלבד | `~/.local/share/devin/cli` (קורא רק מטא־דאטה מ־`sessions.db`) |
+
+## מדדים
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/YosefHayim/agent-session-pack/main/assets/benchmarks.svg" alt="נפח הסשנים לפני ואחרי אריזה במחשב אחד" width="820" />
+</p>
+
+| סוכן | לפני | אחרי | חיסכון |
+| --- | ---: | ---: | ---: |
+| Codex | 2.22 GB | 782 MB | **65.6%** |
+| Claude Code | 2.10 GB | 457 MB | **78.7%** |
+| Kiro | 1.95 GB | 190 MB | **90.5%** |
+| Cursor (עותק גיבוי) | 7.27 GB | 957 MB | **87.1%** |
+| **סך הכול** | **13.5 GB** | **2.3 GB** | **כ־83%** |
+
+אלה נתונים אמיתיים ממחשב אחד, לא מדד כללי. כדי למדוד אצלכם הריצו `npx --yes agent-session-pack check` (עובד על עותקים בלבד).
+
+## התחלה מהירה
+
+דרישות: [Node.js](https://nodejs.org/en) 20 ומעלה, [`zstd`](https://facebook.github.io/zstd/) ב־`PATH`, ו־`sqlite3` רק אם משתמשים ב־Devin.
+
+</div>
+
+```bash
+# 1. Prove savings on copies (real files untouched)
+npx --yes agent-session-pack check
+
+# 2. Preview what would be packed
+npx --yes agent-session-pack pack --all-providers --older-than 7d --dry-run
+
+# 3. Pack cold sessions (originals removed only after verification)
+npx --yes agent-session-pack pack --all-providers --older-than 7d --apply
+
+# 4. Restore when needed
+npx --yes agent-session-pack unpack --all-providers --apply
+npx --yes agent-session-pack restore SESSION_ID_OR_NAME
+```
+
+<div dir="rtl">
+
+הרצה של `npx --yes agent-session-pack` בלי ארגומנטים פותחת תפריט מודרך בטרמינל.
+
+## מודל הבטיחות
+
+- `check` ו־`savings` עובדים על עותקים בלבד.
+- `pack --all-providers` הוא הרצת ניסיון אלא אם מוסיפים `--apply`.
+- `pack --apply` מבקש אישור בטרמינל אלא אם מוסיפים `--yes`.
+- `pack --max --apply` נדחה.
+- בהחלה: כתיבת ארכיון, שחזור, השוואת SHA-256, כתיבת מניפסט, ורק אז מחיקת המקור.
+- `unpack --apply` מדלג על קבצים חיים ששונו במקום לדרוס אותם.
+- Cursor ו־Devin במצב גיבוי בלבד: התיקיות המקוריות שלהם לא משתנות.
+
+## מחזור חיים: שחזור אוטומטי בפתיחה
+
+מחזור החיים כבוי עד שמפעילים אותו. `lifecycle enable` מתקין עטיפות לסוכנים, וסשן ארוז משוחזר אוטומטית כשפותחים אותו. `maintain --apply` אורז מחדש סשנים שהתקררו שוב. פרטים מלאים ב־[README באנגלית](README.md#lifecycle-auto-restore-on-launch).
+
+## שאלות נפוצות
+
+<details>
+<summary><strong>האם זה סיכום או דחיסת הקשר?</strong></summary>
+
+לא. הכלי לא מסכם, לא משכתב ולא חותך שיחות. הוא משתמש בדחיסה ללא אובדן ומוודא שחזור מדויק ברמת הבייט.
+</details>
+
+<details>
+<summary><strong>האם הכלי קורא פרטי התחברות או מעלה סשנים?</strong></summary>
+
+לא. הוא סורק תיקיות מקומיות וכותב ארכיונים מקומיים בלבד. עבור Devin הוא קורא מטא־דאטה ממסד SQLite מקומי ולא קורא פרטי התחברות.
+</details>
+
+<details>
+<summary><strong>במה זה שונה ממחיקת קבצי סשנים ישנים?</strong></summary>
+
+מחיקה היא חד־כיוונית. Agent Session Pack כותב ארכיון, מוכיח שהוא משחזר את הבייטים המקוריים במדויק, כותב מניפסט, ורק אז מוחק את המקור.
+</details>
+
+## רישיון
+
+MIT - ראו [LICENSE](LICENSE).
+
+---
+
+<div align="center">
+
+<a href="https://www.buymeacoffee.com/yosefhayim" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="48" /></a>
+
+<br /><br />
+
+**[לתמיכה בפרויקט](https://www.buymeacoffee.com/yosefhayim)** · נוצר על ידי [Yosef Hayim Sabag](https://github.com/YosefHayim)
+
+</div>
+
+</div>