From 84ad5838ea6570197d7a4629dece156272f369f2 Mon Sep 17 00:00:00 2001
From: Santi Legaristi
Date: Fri, 13 Nov 2026 00:47:13 +0100
Subject: [PATCH 1/2] docs: lead the README with Terraform validation,
persistence as the engine
Refs #33
---
README.md | 142 ++++++++++++++++++++++++++++----------
docs/i18n/README.es.md | 142 ++++++++++++++++++++++++++++----------
docs/i18n/README.zh-CN.md | 138 ++++++++++++++++++++++++++----------
3 files changed, 310 insertions(+), 112 deletions(-)
diff --git a/README.md b/README.md
index 11e3162..85d66a6 100644
--- a/README.md
+++ b/README.md
@@ -5,11 +5,12 @@
-Your local AWS survives restarts.
+Test your Terraform on local AWS before it touches the real one.
- Persistent state for AWS Emulator.
- Reboot, come back days later, and terraform plan still says No changes.
+ keepstack gives the official AWS Emulator a memory.
+ Your local infrastructure survives restarts with the same IDs, and every pull request is applied on top of what
+ main already built. No AWS account, no tokens.
@@ -21,6 +22,7 @@
Quick start ·
+ Validate pull requests ·
How it works ·
Compatibility ·
Contributing
@@ -30,6 +32,33 @@
+## Two ways to use it
+
+
+
+| 💻 On your machine |
+🔁 In every pull request |
+
+
+|
+
+The official AWS Emulator, with a memory. Apply, reboot, come back days later: `terraform plan` still says
+*No changes*, with the same VPC IDs, ARNs and data. Add one resource and the plan shows exactly that one.
+
+**→ [Quick start](#quick-start)**
+
+ |
+
+
+One step in GitHub Actions applies the pull request on top of the environment `main` already built and comments the
+incremental plan and every problem on the PR: config errors, emulator gaps, non-idempotent resources.
+
+**→ [Validate pull requests](#validate-pull-requests)**
+
+ |
+
+
+
## The problem
AWS Emulator is AWS's official local emulator: fast and faithful, but **everything lives in memory**.
@@ -100,6 +129,74 @@ Try the full loop with [`examples/quickstart`](examples/quickstart/main.tf).
> Use **AWS CLI v2**: v1 ignores `AWS_ENDPOINT_URL` for some services (e.g. SQS) and would call real AWS.
> In Terraform, copy the `provider` block from the [quickstart example](examples/quickstart/main.tf).
+## Validate pull requests
+
+
+Add one step and every pull request that touches your infrastructure gets applied on the official AWS Emulator, with
+no AWS account and no tokens:
+
+```yaml
+# .github/workflows/infra.yml
+on:
+ push:
+ branches: [main]
+ pull_request:
+
+jobs:
+ validate:
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ pull-requests: write # for the PR comment
+ steps:
+ - uses: actions/checkout@v7
+ - uses: sanlega/keepstack@v0.3.0
+ with:
+ validate: infra/ # your Terraform directory
+ baseline: true # validate PRs on top of main's environment
+ shims: true
+ run: pytest tests/smoke # optional: check the resources really work
+```
+
+- **Job summary and a sticky PR comment** with the plan, the steps and every problem found.
+- **Inline annotations** on the `.tf` lines that fail.
+- **Baseline:** pushes to `main` save the resulting environment; pull requests restore it and are applied on top, so
+ the report shows the real incremental plan (replacements, destroys, `moved` blocks) instead of a greenfield apply.
+ Other local emulators start from an empty account on every run.
+
+The comment it leaves on the pull request (this one caught a replacement and a resource that is not idempotent):
+
+
+> ### keepstack validate: `infra` ❌ failed
+>
+> | Step | Result |
+> |---|---|
+> | init | ✅ ok |
+> | plan | ✅ ok |
+> | apply | ✅ ok |
+> | idempotency | ❌ failed |
+> | smoke | ✅ ok |
+>
+> **Plan:** 1 to add, 1 to change, 1 to replace, 0 to destroy
+>
+> > [!WARNING]
+> > Destructive changes:
+> > - `aws_sqs_queue.jobs` will be **replaced**
+>
+> | | Kind | Resource | Message |
+> |---|---|---|---|
+> | 🔁 | not idempotent | `aws_dynamodb_table.items` `main.tf:58` | plan is not empty after apply (update)
*Hint:* keepstack up --shims, or lifecycle { ignore_changes = [on_demand_throughput] } |
+>
+> Planned changes
+>
+> - `create` aws_subnet.b
+> - `replace` aws_sqs_queue.jobs
+> - `update` aws_dynamodb_table.items
+>
+>
+>
+> keepstack · 52.3 s · AWS Emulator, no AWS account used
+
## Everyday commands
| Command | What it does |
@@ -204,42 +301,10 @@ translations and your snapshots. It only answers on `127.0.0.1`.
## In GitHub Actions
-### Validate every pull request
-
-Add one step and every pull request that touches your infrastructure gets applied on the official AWS Emulator, with
-no AWS account and no tokens:
-
-```yaml
-# .github/workflows/infra.yml
-on:
- push:
- branches: [main]
- pull_request:
-
-jobs:
- validate:
- runs-on: ubuntu-latest
- permissions:
- contents: read
- pull-requests: write # for the PR comment
- steps:
- - uses: actions/checkout@v7
- - uses: sanlega/keepstack@v0.3.0
- with:
- validate: infra/ # your Terraform directory
- baseline: true # validate PRs on top of main's environment
- shims: true
- run: pytest tests/smoke # optional: check the resources really work
-```
-
-- **Job summary and a sticky PR comment** with the plan, the steps and every problem found.
-- **Inline annotations** on the `.tf` lines that fail.
-- **Baseline:** pushes to `main` save the resulting environment; pull requests restore it and are applied on top, so
- the report shows the real incremental plan (replacements, destroys, `moved` blocks) instead of a greenfield apply.
- Other local emulators start from an empty account on every run.
-
### Just a local AWS
+Pull-request validation is described [above](#validate-pull-requests).
+
Without `validate`, the action only starts keepstack and points the AWS CLI, SDKs and Terraform at it:
```yaml
@@ -272,10 +337,11 @@ needs a Linux runner (Docker with Linux containers) and installs Terraform if th
| | |
|---|---|
+| 🧪 **Validate pull requests** | `keepstack validate` applies your Terraform locally and tells config errors apart from emulator gaps and non-idempotent resources, with file and line. |
+| 🧱 **Incremental, like production** | Pull requests are applied on top of `main`'s environment, so replacements and destroys show up before they reach AWS. |
| 🔁 **Survives everything** | Ctrl+C, `docker kill`, Docker restarts, reboots. If the container dies, keepstack restores it on its own. |
| 🪪 **Stable IDs** | `vpc-…`, KMS UUIDs, Secrets Manager ARNs, Route 53 zone IDs… keep their original values across restarts. |
| 🔍 **Know before you apply** | `keepstack check` tells you what will break on the emulator before you run Terraform. |
-| 🧪 **Validate pull requests** | `keepstack validate` applies your Terraform locally and tells config errors apart from emulator gaps and non-idempotent resources. |
| 📸 **Snapshots** | Save, restore and share whole environments, Terraform state included. |
| 🩹 **Compatibility shims** | `--shims` works around known emulator bugs (e.g. `aws_security_group`), off by default. |
| ⚡ **Zero setup** | One command, no config. The emulator image builds itself (x86_64 and Apple silicon). |
diff --git a/docs/i18n/README.es.md b/docs/i18n/README.es.md
index cc632fd..548f2e4 100644
--- a/docs/i18n/README.es.md
+++ b/docs/i18n/README.es.md
@@ -5,11 +5,12 @@
-Tu AWS local sobrevive a los reinicios.
+Prueba tu Terraform en un AWS local antes de tocar el real.
- Estado persistente para AWS Emulator:
- reinicia, vuelve días después y terraform plan sigue diciendo No changes.
+ keepstack le da memoria al AWS Emulator oficial.
+ Tu infraestructura local sobrevive a los reinicios con los mismos IDs, y cada pull request se aplica sobre lo que
+ main ya construyó. Sin cuenta de AWS ni tokens.
@@ -21,6 +22,7 @@
Inicio rápido ·
+ Valida pull requests ·
Cómo funciona ·
Compatibilidad ·
Contribuir
@@ -32,6 +34,33 @@
+## Dos formas de usarlo
+
+
+
+| 💻 En tu máquina |
+🔁 En cada pull request |
+
+
+|
+
+El AWS Emulator oficial, con memoria. Aplica, reinicia, vuelve días después: `terraform plan` sigue diciendo
+*No changes*, con los mismos IDs de VPC, ARN y datos. Añade un recurso y el plan muestra exactamente ese.
+
+**→ [Inicio rápido](#inicio-rápido)**
+
+ |
+
+
+Un paso en GitHub Actions aplica el pull request sobre el entorno que `main` ya construyó y comenta en el PR el plan
+incremental y cada problema: errores de configuración, carencias del emulador, recursos no idempotentes.
+
+**→ [Valida pull requests](#valida-pull-requests)**
+
+ |
+
+
+
## El problema
AWS Emulator es el emulador local oficial de AWS: rápido y fiel, pero **todo vive en memoria**.
@@ -102,6 +131,74 @@ Prueba el ciclo completo con [`examples/quickstart`](../../examples/quickstart/m
> Usa **AWS CLI v2**: la v1 ignora `AWS_ENDPOINT_URL` en algunos servicios (p. ej. SQS) y llamaría a AWS de verdad.
> En Terraform, copia el bloque `provider` del [ejemplo quickstart](../../examples/quickstart/main.tf).
+## Valida pull requests
+
+
+Con un solo paso, cada pull request que toque tu infraestructura se aplica en el emulador oficial de AWS, sin cuenta de
+AWS ni tokens:
+
+```yaml
+# .github/workflows/infra.yml
+on:
+ push:
+ branches: [main]
+ pull_request:
+
+jobs:
+ validate:
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ pull-requests: write # para el comentario en el PR
+ steps:
+ - uses: actions/checkout@v7
+ - uses: sanlega/keepstack@v0.3.0
+ with:
+ validate: infra/ # tu directorio Terraform
+ baseline: true # valida los PR sobre el entorno de main
+ shims: true
+ run: pytest tests/smoke # opcional: comprueba que los recursos funcionan
+```
+
+- **Resumen del job y un comentario fijo en el PR** con el plan, los pasos y cada problema encontrado.
+- **Anotaciones en línea** sobre las líneas `.tf` que fallan.
+- **Baseline:** los push a `main` guardan el entorno resultante; los pull requests lo restauran y se aplican encima, así
+ que el informe muestra el plan incremental real (reemplazos, borrados, bloques `moved`) en vez de un apply desde cero.
+ Los demás emuladores locales empiezan con una cuenta vacía en cada ejecución.
+
+El comentario que deja en el pull request (este detectó un reemplazo y un recurso no idempotente):
+
+
+> ### keepstack validate: `infra` ❌ failed
+>
+> | Step | Result |
+> |---|---|
+> | init | ✅ ok |
+> | plan | ✅ ok |
+> | apply | ✅ ok |
+> | idempotency | ❌ failed |
+> | smoke | ✅ ok |
+>
+> **Plan:** 1 to add, 1 to change, 1 to replace, 0 to destroy
+>
+> > [!WARNING]
+> > Destructive changes:
+> > - `aws_sqs_queue.jobs` will be **replaced**
+>
+> | | Kind | Resource | Message |
+> |---|---|---|---|
+> | 🔁 | not idempotent | `aws_dynamodb_table.items` `main.tf:58` | plan is not empty after apply (update)
*Hint:* keepstack up --shims, or lifecycle { ignore_changes = [on_demand_throughput] } |
+>
+> Planned changes
+>
+> - `create` aws_subnet.b
+> - `replace` aws_sqs_queue.jobs
+> - `update` aws_dynamodb_table.items
+>
+>
+>
+> keepstack · 52.3 s · AWS Emulator, no AWS account used
+
## Comandos del día a día
| Comando | Qué hace |
@@ -206,42 +303,10 @@ de IDs y tus snapshots. Solo responde en `127.0.0.1`.
## En GitHub Actions
-### Valida cada pull request
-
-Con un solo paso, cada pull request que toque tu infraestructura se aplica en el emulador oficial de AWS, sin cuenta de
-AWS ni tokens:
-
-```yaml
-# .github/workflows/infra.yml
-on:
- push:
- branches: [main]
- pull_request:
-
-jobs:
- validate:
- runs-on: ubuntu-latest
- permissions:
- contents: read
- pull-requests: write # para el comentario en el PR
- steps:
- - uses: actions/checkout@v7
- - uses: sanlega/keepstack@v0.3.0
- with:
- validate: infra/ # tu directorio Terraform
- baseline: true # valida los PR sobre el entorno de main
- shims: true
- run: pytest tests/smoke # opcional: comprueba que los recursos funcionan
-```
-
-- **Resumen del job y un comentario fijo en el PR** con el plan, los pasos y cada problema encontrado.
-- **Anotaciones en línea** sobre las líneas `.tf` que fallan.
-- **Baseline:** los push a `main` guardan el entorno resultante; los pull requests lo restauran y se aplican encima, así
- que el informe muestra el plan incremental real (reemplazos, borrados, bloques `moved`) en vez de un apply desde cero.
- Los demás emuladores locales empiezan con una cuenta vacía en cada ejecución.
-
### Solo un AWS local
+La validación de pull requests está descrita [más arriba](#valida-pull-requests).
+
Sin `validate`, la acción solo arranca keepstack y apunta a él la AWS CLI, los SDK y Terraform:
```yaml
@@ -274,10 +339,11 @@ acción necesita un runner Linux (Docker con contenedores Linux) e instala Terra
| | |
|---|---|
+| 🧪 **Valida pull requests** | `keepstack validate` aplica tu Terraform en local y distingue errores de configuración, carencias del emulador y recursos no idempotentes, con fichero y línea. |
+| 🧱 **Incremental, como en producción** | Los pull requests se aplican sobre el entorno de `main`, así que los reemplazos y borrados aparecen antes de llegar a AWS. |
| 🔁 **Sobrevive a todo** | Ctrl+C, `docker kill`, reinicios de Docker, reinicios del equipo. Si el contenedor muere, keepstack lo restaura por su cuenta. |
| 🪪 **IDs estables** | `vpc-…`, UUID de KMS, ARN de Secrets Manager, IDs de zona de Route 53… conservan su valor original tras los reinicios. |
| 🔍 **Sabes antes de aplicar** | `keepstack check` te dice qué fallará en el emulador antes de ejecutar Terraform. |
-| 🧪 **Valida pull requests** | `keepstack validate` aplica tu Terraform en local y distingue errores de configuración, carencias del emulador y recursos no idempotentes. |
| 📸 **Snapshots** | Guarda, restaura y comparte entornos completos, estado de Terraform incluido. |
| 🩹 **Shims de compatibilidad** | `--shims` esquiva errores conocidos del emulador (p. ej. `aws_security_group`), desactivado por defecto. |
| ⚡ **Cero configuración** | Un solo comando, sin config. La imagen del emulador se construye sola (x86_64 y Apple silicon). |
diff --git a/docs/i18n/README.zh-CN.md b/docs/i18n/README.zh-CN.md
index f27e114..7d9c1c9 100644
--- a/docs/i18n/README.zh-CN.md
+++ b/docs/i18n/README.zh-CN.md
@@ -5,11 +5,12 @@
-你的本地 AWS,重启后依然保留。
+在 Terraform 触及真实 AWS 之前,先在本地 AWS 上测试。
- 为 AWS Emulator 提供持久化状态。
- 重启电脑,几天后再回来,terraform plan 仍然显示 No changes。
+ keepstack 让官方 AWS Emulator 拥有记忆。
+ 本地基础设施在重启后保留,ID 不变;每个拉取请求都在 main 已构建的环境之上执行 apply。
+ 无需 AWS 账号,无需令牌。
@@ -21,6 +22,7 @@
快速开始 ·
+ 验证拉取请求 ·
工作原理 ·
兼容性 ·
参与贡献
@@ -32,6 +34,33 @@
+## 两种用法
+
+
+
+| 💻 在你的电脑上 |
+🔁 在每个拉取请求中 |
+
+
+|
+
+拥有记忆的官方 AWS Emulator。执行 apply、重启电脑、几天后再回来:`terraform plan` 仍然显示 *No changes*,VPC ID、ARN
+和数据都不变。新增一个资源,plan 就只显示这一个。
+
+**→ [快速开始](#快速开始)**
+
+ |
+
+
+GitHub Actions 中的一个步骤会在 `main` 已构建的环境之上 apply 拉取请求,并在 PR 中评论增量 plan 和每个问题:配置错误、
+模拟器缺陷、非幂等资源。
+
+**→ [验证拉取请求](#验证拉取请求)**
+
+ |
+
+
+
## 问题所在
AWS Emulator 是 AWS 官方提供的本地模拟器,速度快、还原度高,但**所有数据都只保存在内存中**。
@@ -102,6 +131,72 @@ aws sts get-caller-identity # "Account": "000000000000" → 说明你连上
> 请使用 **AWS CLI v2**:v1 对部分服务(例如 SQS)会忽略 `AWS_ENDPOINT_URL`,请求会被发往真实的 AWS。
> 在 Terraform 中,请复制[快速开始示例](../../examples/quickstart/main.tf)里的 `provider` 配置块。
+## 验证拉取请求
+
+
+只需一个步骤,每个涉及基础设施的拉取请求都会在官方 AWS Emulator 上执行 apply,无需 AWS 账号或令牌:
+
+```yaml
+# .github/workflows/infra.yml
+on:
+ push:
+ branches: [main]
+ pull_request:
+
+jobs:
+ validate:
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ pull-requests: write # 用于 PR 评论
+ steps:
+ - uses: actions/checkout@v7
+ - uses: sanlega/keepstack@v0.3.0
+ with:
+ validate: infra/ # 你的 Terraform 目录
+ baseline: true # 在 main 的环境之上验证 PR
+ shims: true
+ run: pytest tests/smoke # 可选:检查资源是否真的可用
+```
+
+- **作业摘要和一条固定的 PR 评论**,包含 plan、各个步骤以及发现的每个问题。
+- 在出错的 `.tf` 行上显示**行内注释**。
+- **基线:** 推送到 `main` 时保存得到的环境;拉取请求会恢复它并在其之上执行 apply,因此报告显示的是真实的增量 plan
+ (替换、销毁、`moved` 块),而不是从零开始的 apply。其他本地模拟器每次运行都从空账号开始。
+
+它在拉取请求中留下的评论(这次发现了一次替换和一个非幂等资源):
+
+
+> ### keepstack validate: `infra` ❌ failed
+>
+> | Step | Result |
+> |---|---|
+> | init | ✅ ok |
+> | plan | ✅ ok |
+> | apply | ✅ ok |
+> | idempotency | ❌ failed |
+> | smoke | ✅ ok |
+>
+> **Plan:** 1 to add, 1 to change, 1 to replace, 0 to destroy
+>
+> > [!WARNING]
+> > Destructive changes:
+> > - `aws_sqs_queue.jobs` will be **replaced**
+>
+> | | Kind | Resource | Message |
+> |---|---|---|---|
+> | 🔁 | not idempotent | `aws_dynamodb_table.items` `main.tf:58` | plan is not empty after apply (update)
*Hint:* keepstack up --shims, or lifecycle { ignore_changes = [on_demand_throughput] } |
+>
+> Planned changes
+>
+> - `create` aws_subnet.b
+> - `replace` aws_sqs_queue.jobs
+> - `update` aws_dynamodb_table.items
+>
+>
+>
+> keepstack · 52.3 s · AWS Emulator, no AWS account used
+
## 常用命令
| 命令 | 作用 |
@@ -202,40 +297,10 @@ Terraform output(`TF_OUTPUT_`),退出码非零则验证失败。在
## 在 GitHub Actions 中使用
-### 验证每一个拉取请求
-
-只需一个步骤,每个涉及基础设施的拉取请求都会在官方 AWS Emulator 上执行 apply,无需 AWS 账号或令牌:
-
-```yaml
-# .github/workflows/infra.yml
-on:
- push:
- branches: [main]
- pull_request:
-
-jobs:
- validate:
- runs-on: ubuntu-latest
- permissions:
- contents: read
- pull-requests: write # 用于 PR 评论
- steps:
- - uses: actions/checkout@v7
- - uses: sanlega/keepstack@v0.3.0
- with:
- validate: infra/ # 你的 Terraform 目录
- baseline: true # 在 main 的环境之上验证 PR
- shims: true
- run: pytest tests/smoke # 可选:检查资源是否真的可用
-```
-
-- **作业摘要和一条固定的 PR 评论**,包含 plan、各个步骤以及发现的每个问题。
-- 在出错的 `.tf` 行上显示**行内注释**。
-- **基线:** 推送到 `main` 时保存得到的环境;拉取请求会恢复它并在其之上执行 apply,因此报告显示的是真实的增量 plan
- (替换、销毁、`moved` 块),而不是从零开始的 apply。其他本地模拟器每次运行都从空账号开始。
-
### 只需要一个本地 AWS
+拉取请求验证见[上文](#验证拉取请求)。
+
不设置 `validate` 时,该 action 只启动 keepstack,并让 AWS CLI、SDK 和 Terraform 指向它:
```yaml
@@ -268,10 +333,11 @@ Linux runner(支持 Linux 容器的 Docker),如果 runner 上没有 Terraf
| | |
|---|---|
+| 🧪 **验证拉取请求** | `keepstack validate` 在本地 apply 你的 Terraform,并区分配置错误、模拟器缺陷和非幂等资源,精确到文件和行号。 |
+| 🧱 **增量验证,与生产一致** | 拉取请求在 `main` 的环境之上 apply,替换和销毁在到达 AWS 之前就会显现。 |
| 🔁 **任何情况都不丢状态** | Ctrl+C、`docker kill`、Docker 重启、整机重启均可。容器挂掉时,keepstack 会自动将其恢复。 |
| 🪪 **ID 保持稳定** | `vpc-…`、KMS UUID、Secrets Manager ARN、Route 53 托管区域 ID 等,重启前后保持原值。 |
| 🔍 **应用前先知道** | `keepstack check` 在你运行 Terraform 之前就告诉你哪些东西会在模拟器上出问题。 |
-| 🧪 **验证拉取请求** | `keepstack validate` 在本地 apply 你的 Terraform,并区分配置错误、模拟器缺陷和非幂等资源。 |
| 📸 **快照** | 保存、恢复和分享整个环境,包含 Terraform 状态。 |
| 🩹 **兼容性补丁** | `--shims` 可绕过已知的模拟器缺陷(例如 `aws_security_group`),默认关闭。 |
| ⚡ **零配置** | 一条命令,无需配置。模拟器镜像会自动构建(x86_64 和 Apple silicon)。 |
From 80a9ab3bb8b51c3d3db42aedb746ead6d4c45e65 Mon Sep 17 00:00:00 2001
From: Santi Legaristi
Date: Fri, 13 Nov 2026 01:36:04 +0100
Subject: [PATCH 2/2] docs: crash safety in the feature table, changelog
Refs #33
---
CHANGELOG.md | 4 ++++
README.md | 2 +-
docs/i18n/README.es.md | 2 +-
docs/i18n/README.zh-CN.md | 2 +-
4 files changed, 7 insertions(+), 3 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b9929c4..f555fd5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,10 @@ All notable changes to this project are documented here. The format follows
- `scripts/chaos.py` and a nightly workflow: kill the emulator, keepstack, or everything at once in the middle of
`terraform apply` and require Terraform to converge. Documented in [how it works](docs/how-it-works.md#crash-safety).
+### Changed
+- README: leads with Terraform validation (locally and in every pull request), with persistence as the engine;
+ example of the pull request comment.
+
## [0.3.0] - 2026-11-13
keepstack becomes a pull-request validator for Terraform: apply every change on the official AWS Emulator, on top of
diff --git a/README.md b/README.md
index 85d66a6..2ff82f1 100644
--- a/README.md
+++ b/README.md
@@ -339,7 +339,7 @@ needs a Linux runner (Docker with Linux containers) and installs Terraform if th
|---|---|
| 🧪 **Validate pull requests** | `keepstack validate` applies your Terraform locally and tells config errors apart from emulator gaps and non-idempotent resources, with file and line. |
| 🧱 **Incremental, like production** | Pull requests are applied on top of `main`'s environment, so replacements and destroys show up before they reach AWS. |
-| 🔁 **Survives everything** | Ctrl+C, `docker kill`, Docker restarts, reboots. If the container dies, keepstack restores it on its own. |
+| 🔁 **Survives everything** | Ctrl+C, `docker kill`, Docker restarts, reboots, even a crash in the middle of `terraform apply`. Exercised every night by a [chaos suite](docs/how-it-works.md#crash-safety). |
| 🪪 **Stable IDs** | `vpc-…`, KMS UUIDs, Secrets Manager ARNs, Route 53 zone IDs… keep their original values across restarts. |
| 🔍 **Know before you apply** | `keepstack check` tells you what will break on the emulator before you run Terraform. |
| 📸 **Snapshots** | Save, restore and share whole environments, Terraform state included. |
diff --git a/docs/i18n/README.es.md b/docs/i18n/README.es.md
index 548f2e4..364ef6f 100644
--- a/docs/i18n/README.es.md
+++ b/docs/i18n/README.es.md
@@ -341,7 +341,7 @@ acción necesita un runner Linux (Docker con contenedores Linux) e instala Terra
|---|---|
| 🧪 **Valida pull requests** | `keepstack validate` aplica tu Terraform en local y distingue errores de configuración, carencias del emulador y recursos no idempotentes, con fichero y línea. |
| 🧱 **Incremental, como en producción** | Los pull requests se aplican sobre el entorno de `main`, así que los reemplazos y borrados aparecen antes de llegar a AWS. |
-| 🔁 **Sobrevive a todo** | Ctrl+C, `docker kill`, reinicios de Docker, reinicios del equipo. Si el contenedor muere, keepstack lo restaura por su cuenta. |
+| 🔁 **Sobrevive a todo** | Ctrl+C, `docker kill`, reinicios de Docker, reinicios del equipo, incluso un crash en mitad de un `terraform apply`. Lo comprueba cada noche una [suite de caos](../how-it-works.md#crash-safety). |
| 🪪 **IDs estables** | `vpc-…`, UUID de KMS, ARN de Secrets Manager, IDs de zona de Route 53… conservan su valor original tras los reinicios. |
| 🔍 **Sabes antes de aplicar** | `keepstack check` te dice qué fallará en el emulador antes de ejecutar Terraform. |
| 📸 **Snapshots** | Guarda, restaura y comparte entornos completos, estado de Terraform incluido. |
diff --git a/docs/i18n/README.zh-CN.md b/docs/i18n/README.zh-CN.md
index 7d9c1c9..b80220d 100644
--- a/docs/i18n/README.zh-CN.md
+++ b/docs/i18n/README.zh-CN.md
@@ -335,7 +335,7 @@ Linux runner(支持 Linux 容器的 Docker),如果 runner 上没有 Terraf
|---|---|
| 🧪 **验证拉取请求** | `keepstack validate` 在本地 apply 你的 Terraform,并区分配置错误、模拟器缺陷和非幂等资源,精确到文件和行号。 |
| 🧱 **增量验证,与生产一致** | 拉取请求在 `main` 的环境之上 apply,替换和销毁在到达 AWS 之前就会显现。 |
-| 🔁 **任何情况都不丢状态** | Ctrl+C、`docker kill`、Docker 重启、整机重启均可。容器挂掉时,keepstack 会自动将其恢复。 |
+| 🔁 **任何情况都不丢状态** | Ctrl+C、`docker kill`、Docker 重启、整机重启,甚至 `terraform apply` 进行到一半时崩溃。每晚由[混沌测试](../how-it-works.md#crash-safety)验证。 |
| 🪪 **ID 保持稳定** | `vpc-…`、KMS UUID、Secrets Manager ARN、Route 53 托管区域 ID 等,重启前后保持原值。 |
| 🔍 **应用前先知道** | `keepstack check` 在你运行 Terraform 之前就告诉你哪些东西会在模拟器上出问题。 |
| 📸 **快照** | 保存、恢复和分享整个环境,包含 Terraform 状态。 |