@@ -28,7 +28,7 @@ mxbank schema                           # JSON Schema completo
 Si `mxbank` no está en el PATH: `uv tool install git+https://github.com/proteo5/mx-bank-statement-reader` (pide permiso antes de instalar), o desde un clon del repo: `uv run --project <ruta-del-repo> mxbank …`.
 
 - **PDF con contraseña** (código 11): pide al usuario que la ponga en una variable de entorno y usa `--password-env NOMBRE`. Nunca la pases como argumento ni la escribas en la conversación.
-- **Varios meses**: usa la misma llave de seudónimos en todas las ejecuciones (`--pseudonym-key-env NOMBRE`), para que la misma cuenta o contraparte tenga el mismo alias.
+- **Varios meses o importación**: usa **siempre la misma llave** (`--pseudonym-key-env NOMBRE`) para que la misma cuenta, contraparte, movimiento y plan a meses tengan el mismo alias e id en todas las ejecuciones. Sin llave, la CLI avisa en stderr y los ids no sirven fuera de esa ejecución.
 - `--include-concepts` agrega los conceptos de transferencias (redactados); úsalo solo si el usuario lo pide.
 
 | Código | Significado / qué hacer |
@@ -48,6 +48,11 @@ Si `mxbank` no está en el PATH: `uv tool install git+https://github.com/proteo5
 - `installment_plans[]`: compras a meses con `pending_balance` y `installment_number`/`installments_total`.
 - `original_currency` / `original_amount` / `exchange_rate`: compras en otra moneda.
 - `merchant`: nombre canónico cuando el comercio es conocido; si no, usa `description`.
+- `statement_id`, `transactions[].id`, `installment_plans[].id` (schema 1.1): identificadores HMAC estables.
+  - **Para no duplicar** al combinar estados que se enciman o reimportados, agrupa o deduplica por `transactions[].id`, nunca por fecha + monto: dos compras idénticas el mismo día tienen ids distintos y ambas son reales.
+  - Sigue una compra a meses entre estados con `installment_plans[].id`.
+  - Los ids solo son comparables si `privacy.pseudonym_scope == "key"` y se usó la misma llave; con `"run"` no los guardes ni los compares entre ejecuciones.
+  - No intentes deducir nada de un id: no contiene datos.
 
 ## Cómo calcular bien (lecciones de estados reales)
 
 
@@ -3,6 +3,18 @@
 Formato basado en [Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/); versionado [SemVer](https://semver.org/lang/es/).
 El esquema JSON de salida tiene su propia versión (`schema_version`).
 
+## [0.2.0] - 2026-10-10
+
+Esquema de salida **1.1** (cambio aditivo; los consumidores de 1.0 siguen funcionando).
+
+### Añadido
+
+- `statement_id` (raíz), `transactions[].id` e `installment_plans[].id`: identificadores estables calculados con HMAC-SHA256 y la llave de seudónimos, para importar o reimportar estados (incluso estados que se enciman) sin duplicar movimientos ni planes a meses.
+  - Con `--pseudonym-key-env` son iguales entre ejecuciones, PDFs y perfiles de privacidad; sin llave solo valen dentro de la ejecución, y la CLI lo advierte en stderr al procesar varios archivos o con `--ndjson`.
+  - Dos movimientos idénticos el mismo día se distinguen con un ordinal de ocurrencia dentro del estado.
+  - El escáner residual exime solo esos campos y solo con su formato exacto.
+- Documentación de cómo se calculan y cuándo son estables (docs/03 §7, docs/04), y cómo usarlos para no duplicar (docs/AGENT.md, skill `mxbank`).
+
 ## [0.1.0] - 2026-10-10
 
 Primera versión pública. Esquema de salida **1.0**.
@@ -25,4 +37,5 @@ Primera versión pública. Esquema de salida **1.0**.
 - Herramientas de desarrollo: volcado enmascarado de layouts (`tools/layout_dump.py`), métricas sobre PDFs reales sin exponer contenido (`tools/corpus_check.py`) y guardia de git contra PDFs y datos personales (`tools/check_no_pii.py`).
 - PDFs sintéticos con datos ficticios para las pruebas.
 
+[0.2.0]: https://github.com/proteo5/mx-bank-statement-reader/releases/tag/v0.2.0
 [0.1.0]: https://github.com/proteo5/mx-bank-statement-reader/releases/tag/v0.1.0
@@ -7,7 +7,7 @@
 
 <p align="center">
   <a href="https://github.com/proteo5/mx-bank-statement-reader/actions/workflows/ci.yml"><img src="https://github.com/proteo5/mx-bank-statement-reader/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
-  <img src="https://img.shields.io/badge/versión-0.1.0-blue" alt="Versión 0.1.0">
+  <img src="https://img.shields.io/badge/versión-0.2.0-blue" alt="Versión 0.2.0">
   <img src="https://img.shields.io/badge/python-3.12%2B-blue" alt="Python 3.12+">
   <img src="https://img.shields.io/badge/licencia-Apache%202.0-green" alt="Licencia Apache 2.0">
 </p>
@@ -121,8 +121,9 @@ Extracto real generado a partir del PDF **sintético** de las pruebas, con datos
 
 ```json
 {
-  "schema_version": "1.0",
+  "schema_version": "1.1",
   "ok": true,
+  "statement_id": "ST_5c0e9a41d27b8f36",
   "document": { "bank": "bbva", "product": "credit", "product_name": "TARJETA AZUL BBVA (CREDITO)", "currency": "MXN" },
   "account": { "account_ref": "ACC_92d5", "account_last4": "3210", "holder_type": "individual" },
   "period": { "start": "2026-08-15", "end": "2026-09-14", "days": 31 },
@@ -132,7 +133,7 @@ Extracto real generado a partir del PDF **sintético** de las pruebas, con datos
     "minimum_payment": "900.00", "no_interest_payment": "1965.00", "cat_percent": "75.3"
   },
   "transactions": [
-    { "date": "2026-08-18", "description": "AMAZON", "type": "card_purchase", "amount": "-1200.00",
+    { "id": "TX_8d41f0b27c9e3a65", "date": "2026-08-18", "description": "AMAZON", "type": "card_purchase", "amount": "-1200.00",
       "merchant": "AMAZON", "card_type": "digital" },
     { "date": "2026-08-20", "description": "NETFLIX", "type": "card_purchase", "amount": "-299.00",
       "original_currency": "USD", "original_amount": "15.00", "exchange_rate": "19.93" },
@@ -148,6 +149,7 @@ Extracto real generado a partir del PDF **sintético** de las pruebas, con datos
 
 - Montos como **texto decimal** (`"1200.00"`), para no perder precisión. `amount` negativo = salida de dinero.
 - Fechas ISO-8601. `null` significa que el dato no viene en el documento; nunca se inventa.
+- `statement_id`, `transactions[].id` e `installment_plans[].id` son **identificadores estables** (HMAC con tu llave): con la misma `--pseudonym-key-env` puedes reimportar estados, incluso los que se enciman, sin duplicar movimientos. Ver [docs/03 §7](docs/03-esquema-salida.md#7-identificadores-estables-schema-11).
 - El esquema completo se obtiene con `mxbank schema`; la semántica de cada campo está en [docs/03-esquema-salida.md](docs/03-esquema-salida.md).
 
 ## Privacidad
 
@@ -159,4 +159,4 @@ Conclusión de diseño: **procesamiento 100 % local, sin telemetría, sin red**,
 | **F2** | Tarjetas de crédito de los mismos bancos, lote/directorio, consolidado multi‑mes, categorización básica de movimientos. |
 | **F3** | Más bancos, OCR, servidor MCP que expone las mismas herramientas, empaquetado como binario único. |
 
-> **Estado en v0.1.0**: F0 y F1 completas salvo el modo `generic` (un banco no soportado se rechaza con código 20/21 en lugar de extraerse en modo de respaldo). De F2 ya están las tarjetas de crédito BBVA; consolidado y categorización siguen pendientes. Ver [02 §11](02-especificacion-tecnica.md#11-estado-de-implementación-v010).
+> **Estado en v0.1.0**: F0 y F1 completas salvo el modo `generic` (un banco no soportado se rechaza con código 20/21 en lugar de extraerse en modo de respaldo). De F2 ya están las tarjetas de crédito BBVA; consolidado y categorización siguen pendientes. Ver [02 §11](02-especificacion-tecnica.md#11-estado-de-implementación-v020).
@@ -238,7 +238,7 @@ Detalle completo en [04-privacidad-y-redaccion.md](04-privacidad-y-redaccion.md)
 - **Servidor MCP (F3)**: `mxbank mcp` expone `extract_statement`, `detect_statement`, `audit_text`, `get_schema` reutilizando el mismo núcleo. El servidor recibe rutas locales, no contenido.
 - La salida incluye `schema_version` y un bloque `privacy` para que la IA sepa qué fue omitido y no "invente" datos.
 
-## 11. Estado de implementación (v0.1.0)
+## 11. Estado de implementación (v0.2.0)
 
 | Componente | Estado |
 |---|---|
@@ -247,6 +247,7 @@ Detalle completo en [04-privacidad-y-redaccion.md](04-privacidad-y-redaccion.md)
 | BanCoppel cuenta de débito (layout 2025.1) | ✅ 1/1 estado real conciliado, totales y saldos por renglón correctos |
 | BBVA tarjeta de crédito (layout 2025.1) | ✅ 4/4 estados reales conciliados con el saldo de cargos regulares; bloque `credit`, planes a meses, tipo de cambio, parcialidades |
 | Redacción (estructural, diccionario, patrones), seudónimos HMAC, escáner residual fail‑closed | ✅ |
+| Identificadores estables `statement_id`, `transactions[].id`, `installment_plans[].id` (schema 1.1) | ✅ docs/03 §7 |
 | Perfiles `minimal` / `standard` / `strict` | ✅ (diferencias en §6 de docs/04) |
 | `--consolidate`, parser genérico (`generic`), generalización de fechas/montos, OCR, NER, servidor MCP, tarjetas de otros bancos | ⏳ |
 
 
@@ -1,9 +1,11 @@
-# 03 · Esquema de salida JSON (v1, borrador)
+# 03 · Esquema de salida JSON (schema 1.1)
 
 El JSON Schema formal se genera desde los modelos Pydantic (`src/mxbank/models/statement.py`) y se obtiene con `mxbank schema`; **ese es la referencia autoritativa**. Este documento describe la forma y la semántica.
 
 > Schema 1.0 (v0.1.0), además de lo que muestra el ejemplo: `transactions[].balance_operation`, `value_date`, `counterparty_account_ref`, `concept` (solo con `--include-concepts`); `summary.minimum_average_balance`, `fees_vat`; bloque `rates`; `validation.running_balance_checked`, `bank_totals_match`; `privacy.include_concepts`. También `credit` e `installment_plans` (con `start_date` en lugar de `date`) y en movimientos `original_currency`, `original_amount`, `exchange_rate`, `installment_number`, `installments_total`, `card_type`. Pendiente: `fees[]`.
 
+> **Schema 1.1** (cambio aditivo): `statement_id` en la raíz, `transactions[].id` e `installment_plans[].id`. Ver §7.
+
 ## 1. Principios
 
 - **Allowlist**: solo existen en la salida los campos definidos aquí. Cualquier campo nuevo requiere revisión de privacidad.
@@ -16,8 +18,9 @@ El JSON Schema formal se genera desde los modelos Pydantic (`src/mxbank/models/s
 
 ```json
 {
-  "schema_version": "1.0",
+  "schema_version": "1.1",
   "ok": true,
+  "statement_id": "ST_5c0e9a41d27b8f36",
   "source": {
     "file_name": "estado_2026_09.pdf",
     "file_sha256": "9f2c…",
@@ -58,6 +61,7 @@ El JSON Schema formal se genera desde los modelos Pydantic (`src/mxbank/models/s
   },
   "transactions": [
     {
+      "id": "TX_8d41f0b27c9e3a65",
       "index": 0,
       "date": "2026-08-15",
       "posting_date": "2026-08-15",
@@ -73,6 +77,7 @@ El JSON Schema formal se genera desde los modelos Pydantic (`src/mxbank/models/s
       "page": 2
     },
     {
+      "id": "TX_f20c6b9e41a7d385",
       "index": 1,
       "date": "2026-08-16",
       "posting_date": "2026-08-16",
@@ -136,6 +141,7 @@ El JSON Schema formal se genera desde los modelos Pydantic (`src/mxbank/models/s
 },
 "installment_plans": [
   {
+    "id": "PLAN_3e7a90c5b1f4d268",
     "description": "LIVERPOOL MSI",
     "original_amount": "12000.00",
     "monthly_amount": "1000.00",
@@ -152,6 +158,7 @@ El JSON Schema formal se genera desde los modelos Pydantic (`src/mxbank/models/s
 | Campo | Significado | Nota de privacidad |
 |---|---|---|
 | `account_ref` | Token estable del número de cuenta (HMAC) | Permite a la IA agrupar meses de la misma cuenta sin conocer el número. |
+| `statement_id`, `transactions[].id`, `installment_plans[].id` | Identificadores estables (HMAC), §7 | No contienen ni dejan derivar la cuenta, montos ni descripciones sin la llave. |
 | `account_last4` | Últimos 4 dígitos | Omitido en perfil `strict`. |
 | `counterparty_ref` | Token de la contraparte (`PERSONA_xxxx` / `EMPRESA_xxxx`) | Misma contraparte ⇒ mismo token dentro del ámbito (`run` o `key`). |
 | `merchant` | Comercio normalizado | Se conserva: es útil y no identifica al titular. |
@@ -167,3 +174,23 @@ El JSON Schema formal se genera desde los modelos Pydantic (`src/mxbank/models/s
 
 - `schema_version` sigue SemVer: cambios aditivos ⇒ menor; cambios que rompen ⇒ mayor.
 - `mxbank schema --version N` imprime cualquier versión soportada.
+
+## 7. Identificadores estables (schema 1.1)
+
+Sirven para que un importador (p. ej. una base de datos personal de solo agregado) pueda **reimportar** un estado o importar **estados que se enciman** sin duplicar nada: basta con insertar solo los `id` que aún no tiene.
+
+| Campo | Formato | Entradas del HMAC | Igual cuando… |
+|---|---|---|---|
+| `statement_id` (raíz) | `ST_<16 hex>` | banco, producto, número de cuenta, inicio y fin del periodo | es el mismo estado de cuenta (mismo periodo de la misma cuenta), aunque sea otro PDF o se descargue de nuevo |
+| `transactions[].id` | `TX_<16 hex>` | banco, producto, número de cuenta, `date`, `amount`, descripción **cruda** del banco normalizada (`text.norm`), ordinal de ocurrencia | es el mismo movimiento, aunque aparezca en dos estados que se enciman o en otra posición/página |
+| `installment_plans[].id` | `PLAN_<16 hex>` | banco, producto, número de cuenta, descripción cruda normalizada, `start_date`, `original_amount`, ordinal de ocurrencia | es la misma compra a meses, en todos los estados donde aparezca (cambian la parcialidad y el saldo, el id no) |
+
+Reglas:
+
+- **Estables solo con llave**: con `--pseudonym-key-env` (`privacy.pseudonym_scope: "key"`) y siempre la misma llave, los ids son iguales entre ejecuciones, PDFs y perfiles. **Sin llave** (`"run"`) la llave es aleatoria y los ids solo valen dentro de esa ejecución; la CLI lo advierte en stderr al procesar varios archivos o usar `--ndjson`.
+- **No dependen** de `--privacy`, `--include-concepts`, `index`, `page`, el orden de extracción, `type`, `merchant` ni del texto redactado: se calculan con los datos crudos antes de redactar.
+- **Duplicados legítimos** (dos compras idénticas el mismo día): el ordinal de ocurrencia (0, 1, …) entre movimientos con la misma fecha, monto y descripción **dentro del mismo estado** los distingue. Si un estado que se encima trae solo una de dos compras idénticas, se le asigna el ordinal 0.
+- **Sin periodo** (el parser no lo encontró), `statement_id` se calcula con el hash del PDF: solo es estable para ese archivo exacto.
+- **Sin número de cuenta**, los ids no distinguen entre cuentas distintas; la salida lo avisa en `validation.warnings`.
+- Formato: 16 hex (64 bits). Si dos ids chocaran dentro de una ejecución con datos distintos, el hash se alarga de 2 en 2.
+- El HMAC usa un separador de dominio versionado (`mxbank-id/v1`): si algún día cambian las entradas, cambiará el prefijo de dominio y se documentará como cambio de esquema.
@@ -65,6 +65,16 @@ Los números largos que **no** validan se tratan según perfil: en `strict` se e
 - Con `--pseudonym-key-env` (`pseudonym_scope: "key"`): tokens estables entre meses. La llave nunca se escribe en la salida ni en logs.
 - La longitud del hash crece automáticamente si hay colisiones dentro del documento.
 
+### Identificadores estables (`statement_id`, `transactions[].id`, `installment_plans[].id`)
+
+`id = PREFIJO + "_" + hex(HMAC-SHA256(llave, "mxbank-id/v1" | PREFIJO | banco | producto | número de cuenta | …))[:16]` (detalle de las entradas en [03 §7](03-esquema-salida.md#7-identificadores-estables-schema-11)).
+
+**Por qué HMAC y no un hash simple.** Las entradas son datos que un atacante puede conocer o adivinar: el número de cuenta tiene 10–11 dígitos, la fecha está acotada al periodo y el monto a unos cuantos miles de valores. Con un hash sin llave (`sha256(cuenta | fecha | monto | …)`) bastaría probar combinaciones hasta reproducir el id para **confirmar o recuperar el número de cuenta**, o para saber si alguien hizo un pago concreto. Con HMAC, sin la llave cada intento es indistinguible del azar, así que el id no deja derivar nada.
+
+- La llave es la misma de los seudónimos (`--pseudonym-key-env`). Guárdala como cualquier secreto: quien la tenga puede verificar suposiciones sobre los ids.
+- El número de cuenta entra **solo al HMAC**; nunca aparece en la salida.
+- El escáner residual exime estos campos **solo** si se llaman `id` o `statement_id` **y** su valor coincide exactamente con `^(TX|ST|PLAN)_[0-9a-f]{16,64}$`; cualquier otro contenido en esos campos, o ese formato en otro campo, se escanea normalmente.
+
 ## 6. Perfiles
 
 | Elemento | `minimal` | `standard` (default) | `strict` |
 
@@ -45,6 +45,17 @@ Opciones útiles de `extract`: `--privacy strict`, `--include-concepts`, `--pseu
 - `credit` (solo tarjetas): límite, disponible, fecha de corte, fecha límite de pago, pago mínimo, pago para no generar intereses, CAT y tasa.
 - `installment_plans[]` (solo tarjetas): compras a meses con su saldo pendiente.
 - `privacy`: qué se eliminó o seudonimizó (conteos, nunca valores).
+- `statement_id`, `transactions[].id`, `installment_plans[].id`: identificadores estables (schema 1.1). Ver abajo.
+
+## Importar sin duplicar
+
+Para guardar movimientos en una base propia (p. ej. SQLite de solo agregado) y poder reimportar estados o importar estados que se enciman:
+
+1. Usa **siempre la misma llave**: `--pseudonym-key-env MXBANK_KEY`. Confirma que `privacy.pseudonym_scope` sea `"key"`; si es `"run"`, los ids cambian en cada ejecución y **no deben guardarse**.
+2. Usa `transactions[].id` como llave primaria del movimiento e inserta solo los que no existan (`INSERT OR IGNORE`). El mismo movimiento conserva su id aunque venga en otro PDF, en otra página o con otro `--privacy`.
+3. Usa `statement_id` para saber si un estado ya se importó, e `installment_plans[].id` para seguir una compra a meses de un mes a otro: cambian la parcialidad y el saldo, no el id.
+4. Dos movimientos idénticos el mismo día tienen ids distintos: no los fusiones.
+5. Si cambias o pierdes la llave, los ids nuevos no coincidirán con los guardados. Trátala como un secreto y respáldala.
 
 ## Ejemplo de uso en un agente
 
 
@@ -1,6 +1,6 @@
 [project]
 name = "mx-bank-statement-reader"
-version = "0.1.0"
+version = "0.2.0"
 description = "CLI orientada a IA: estados de cuenta bancarios mexicanos (PDF) a JSON sin datos personales"
 readme = "README.md"
 license = "Apache-2.0"
 
@@ -192,7 +192,7 @@
   <section class="hero">
     <div class="wrap hero-grid">
       <div>
-        <span class="eyebrow">Código abierto · v0.1.0</span>
+        <span class="eyebrow">Código abierto · v0.2.0</span>
         <h1>Tus estados de cuenta, <span class="hl">listos para la IA</span>. Sin tus datos personales.</h1>
         <p class="lead">mxbank lee estados de cuenta de bancos mexicanos en PDF <b>en tu computadora</b>, extrae saldos y movimientos, elimina todo lo que te identifica y entrega un JSON que ya puedes compartir con cualquier asistente.</p>
         <div class="cta">