paramsx 2.1.0__tar.gz → 2.2.1__tar.gz

paramsx-2.2.1/CHANGELOG.md

@@ -0,0 +1,123 @@
+# Changelog
+
+## 2.2.1
+
+Solo comandos de terminal y documentación: no cambia nada de la lectura, la carga ni la
+construcción de rutas. Si ya tienes la 2.2.0 funcionando, actualizar no te obliga a tocar
+tu configuración.
+
+### Añadido
+
+- **`paramsx --version`** (y `-v`), y la versión también en la cabecera de `paramsx --help`. La versión pasa a vivir en `paramsx/__init__.py` y `setup.py` la lee de ahí, para que el paquete y el comando no puedan decir cosas distintas.
+- **`paramsx configure` sobre una configuración que ya existe ya no se queda en "no se sobrescribirá".** Sigue sin tocar el fichero, pero ahora te dice qué opciones nuevas no tienes y con qué valor por defecto se rellenan, si usas el nombre antiguo `abac`, y si la configuración es válida.
+- **`paramsx configure --ejemplo`**: además de lo anterior, deja la plantilla de esta versión en `~/.xsoft/paramsx_config.ejemplo.py`, al lado de la tuya, para comparar. ParamsX no la lee: es solo referencia. Escribir en tu configuración es lo único que no se puede deshacer, así que va en un comando aparte y en otro fichero.
+- Mensaje de primer arranque más claro cuando todavía no hay configuración, explicando qué hace `paramsx configure` y dónde va el fichero.
+
+### Cambiado
+
+- **`paramsx --help` al día.** La opción 2 ya explica que eliges entre los ficheros que tengas en el directorio; el ejemplo de `mixto` usa el entorno en mayúscula como el resto de la documentación; `fichero_por_ruta` enseña el nombre real (`parameters_dev__API_STA__max.py`); y se documentan `profile_name`, `region_name` y `entornos`, que no aparecían aunque son obligatorios.
+- **El README muestra el contenido literal de `paramsx_config.py`**, con sus comentarios y tablas, en vez de una versión resumida: es exactamente lo que te crea `paramsx configure`, así que no pueden desincronizarse. Y una tabla con todos los comandos disponibles.
+
+## 2.2.0
+
+### Añadido
+
+- **Perfiles de naming libres.** `min` y `max` dejan de estar cableados en el código: ahora son entradas de un diccionario `naming` en `~/.xsoft/paramsx_config.py` que puedes redefinir, ampliar y renombrar. Cada perfil declara tres cosas:
+  - `posicion_entorno`: `inicio` (`/rds` → `/dev/rds`), `final` (`/API/STA` → `/API/STA/DEV`), `mixto` (`/API/*/STA` → `/API/dev/STA`) o `ninguno` (`/api/sta/auth` → `/api/sta/auth`).
+  - `case_entorno`: `lower`, `upper` o `capitalize`.
+  - `case_ruta`: `lower`, `upper`, `capitalize` o `ninguno`; a qué case se fuerza la ruta al crear un parámetro nuevo. Con `ninguno` se respeta lo que escribas.
+- **Marcador `*` para colocar el entorno donde quieras** (perfiles `mixto`). Sirve para acotar la lectura a un subárbol concreto: `/API/MULTIAPI/*/stan_ai` lee solo `/API/MULTIAPI/DEV/stan_ai` en vez de todo lo que cuelga de `/API/MULTIAPI/DEV`. El `*` debe ser un segmento entero y aparecer exactamente una vez.
+- **`posicion_entorno: "ninguno"`**, para cuentas que separan los entornos por cuenta de AWS y no meten el entorno en la ruta. Antes esas cuentas no podían usar ParamsX: toda ruta recibía un segmento de entorno sí o sí.
+- **`fichero_por_ruta`**: con `True`, el fichero exportado incluye la ruta y el perfil en su nombre (`parameters_dev__API_STA__max.py`), así leer una segunda ruta del mismo entorno no machaca la que estabas editando. Con `False` (por defecto) se mantiene el nombre de siempre. En los dos modos ParamsX **pide confirmación antes de sobrescribir** un fichero de una lectura anterior, porque volver a leer la misma ruta también se lleva por delante lo que tuvieras editado.
+- **La carga (opción 2) lista los ficheros que hay en el directorio**, en vez de pedir ruta y entorno y fallar si no existe el fichero correspondiente. Se ofrecen los que conservan su backup al lado, se lean con `fichero_por_ruta` o sin él, e incluso los de una ruta que ya hayas quitado de tu `parameter_list`.
+- **`convencion_nuevos`**: qué perfil usan los parámetros creados con la opción 4. Si no lo declaras, se usa el primer perfil de `naming`.
+- **Validación de la configuración al arrancar**, para que un naming mal declarado se vea como un error y no como una lista de parámetros vacía: perfil inexistente, `posicion_entorno`/`case_entorno`/`case_ruta` con valores inválidos, perfil `mixto` sin `*`, `*` en un perfil que no es `mixto`, más de un `*`, `*` pegado a un segmento, y aviso si dos entradas resuelven a la misma ruta.
+
+### Cambiado
+
+- **`abac` pasa a llamarse `tags_activas`.** Es el mismo interruptor de siempre (gestionar y validar tags), con un nombre que dice lo que hace en vez de por qué lo queremos nosotros. **El nombre viejo se sigue aceptando**, así que las configuraciones de la 2.0 y la 2.1 funcionan sin tocar nada.
+- **La opción 4 (crear parámetro) ya no está cableada a `min`.** Antes forzaba toda la ruta a minúscula y exigía que el primer segmento fuera el entorno, así que quien nombra sus parámetros en mayúscula no podía crearlos con la herramienta. Ahora se escribe la ruta **sin el entorno**, igual que en `parameter_list`, y ParamsX aplica el perfil de `convencion_nuevos`, respeta el case según `case_ruta` y enseña la ruta resultante en AWS para confirmarla antes de seguir.
+
+### Corregido
+
+- **La convención `max` ponía el entorno en el medio de la ruta.** Con rutas de más de un segmento el entorno se insertaba tras el primer segmento (`/API/MULTIAPI` + `dev` → `/API/DEV/MULTIAPI`), cuando en `max` el entorno va **siempre al final**: `/API/MULTIAPI` + `dev` → `/API/MULTIAPI/DEV`. Con esa inserción en medio, ninguna ruta `max` de más de un segmento resolvía a una ruta real, así que no se veían los parámetros. Las rutas de un solo segmento (`/EMAIL` → `/EMAIL/DEV`) no cambian: ahí el resultado ya era correcto.
+- La documentación de la 2.0.0 (README, plantilla de configuración y `paramsx --help`) describía esa inserción en medio como el comportamiento esperado de `max`, con el ejemplo `/API/STA` → `/API/DEV/STA`. Corregida: el ejemplo correcto es `/API/STA` → `/API/STA/DEV`.
+
+### Actualizar desde la 2.1.0
+
+No hay que tocar nada: sin `naming` en tu fichero se usan los perfiles de la plantilla, donde `min` y `max` significan lo mismo que antes, y `abac` se sigue leyendo como `tags_activas`. Todo lo nuevo (`*`, `ninguno`, `fichero_por_ruta`, `convencion_nuevos`) es opcional. Si quieres usarlo, la forma más rápida de ver la plantilla nueva entera es `paramsx --help` o el README.
+
+## 2.1.0
+
+### Añadido
+
+- **Flag `obligatorias_vacias`** en `~/.xsoft/paramsx_config.py`. Solo tiene efecto con `abac = True`:
+  - `False` (valor por defecto, comportamiento de la 2.0.0): validación bloqueante. Si a un parámetro le falta cualquiera de las tags obligatorias no se sube ni su valor ni sus tags, y al crear un parámetro no se puede dejar una tag en blanco.
+  - `True`: se permite dejar vacías las tags obligatorias. El parámetro se sube igualmente y **las tags sin valor no se crean en AWS**: nunca se suben etiquetas vacías. En la creación puedes saltar una tag pulsando Enter y el resumen previo lista cuáles quedan vacías.
+- El informe de carga incluye un bloque `Tags obligatorias vacías` con el parámetro y las tags afectadas, para dejar constancia sin bloquear.
+
+No hay que tocar nada en la configuración para actualizar desde la 2.0.0: si no defines `obligatorias_vacias`, se asume `False` y todo sigue igual.
+
+### Nota
+
+Vaciar una tag **que ya tenía valor en AWS** sigue significando borrarla del parámetro, en los dos modos. Es la forma de eliminar una tag. Lo que cambia con `obligatorias_vacias = True` es que una tag en blanco que nunca existió simplemente no se crea, en vez de bloquear la subida.
+
+## 2.0.0
+
+### ⚠ Breaking change: hay que actualizar `~/.xsoft/paramsx_config.py` a mano
+
+`parameter_list` **ya no es una lista de strings**: cada entrada es ahora un diccionario que declara su convención de naming. El formato antiguo no es compatible y ParamsX se niega a arrancar mostrando cómo migrarlo.
+
+Antes (1.x):
+
+```python
+    "entornos": ["DEV", "PROD"],
+    "parameter_list": [
+        "/params1/xx",
+        "/params2/xx",
+    ]
+```
+
+Ahora (2.0.0):
+
+```python
+    "entornos": ['dev', 'pre', 'prod'],   # SIEMPRE en minúscula, lista canónica única
+    "parameter_list": [
+        {"path": "/common", "convencion": "min"},
+        {"path": "/rds", "convencion": "min"},
+        {"path": "/EMAIL", "convencion": "max"},
+        {"path": "/API/STA", "convencion": "max"},
+    ]
+```
+
+Además:
+- `entornos` se escribe **siempre en minúscula**. El entorno en mayúscula de las rutas `max` se deriva con `.upper()` de esa misma lista.
+- Ya **no existe** `entornos_old`.
+- Los ficheros temporales pasan a llamarse `parameters_dev.py` (antes `parameters_DEV.py`) al usar entornos en minúscula.
+
+### Añadido
+
+- **Doble convención de naming en `parameter_list`.** Cada ruta declara `"convencion": "min"` o `"max"`:
+  - `min` (convención nueva): el entorno en minúscula se añade **al principio**. `/rds` + `dev` → `/dev/rds`.
+  - `max` (convención legacy): el entorno en mayúscula se inserta **tras el primer segmento**. `/API/STA` + `dev` → `/API/DEV/STA`; `/EMAIL` + `dev` → `/EMAIL/DEV`. (Esto era un bug, corregido en la 2.2.0: el entorno va al final, `/API/STA/DEV`.)
+- **Opción 4 del menú: "Crear nuevo parámetro".** Pide ruta (siempre en convención `min`, forzada a minúscula), valor (texto plano o JSON, validado) y las tags obligatorias. Se crea con `Overwrite=False` para no machacar nada. No se puede crear un parámetro con la convención `max`.
+- **Aviso de correlación de naming en RDS.** Al crear un parámetro de RDS se comprueba que exista su contraparte (`/{entorno}/common/rds/{nombre-servicio}` ↔ `/{entorno}/rds/{nombre-servicio}/...`) y se avisa si falta. Es un aviso, no bloquea.
+- **Flag `abac` y tags obligatorias.** Con `abac = True`, el fichero exportado incluye un campo por tag (`tagApplication`, `tagEnvironment`, `tagOwner`, `tagProject`, `tagProduct`, `tagService`, `tagComponent`, `tagManagedBy`) con su valor actual en AWS. Estas 8 tags sostienen el control de acceso ABAC vía IAM de toda la cuenta. La lista vive en `tags_obligatorias`, en el propio fichero de configuración, para poder ampliarla sin tocar código. Con `abac = False` no aparecen tags en el fichero y no se valida nada (comportamiento 1.x).
+- **Validación bloqueante por parámetro.** Al cargar con `abac = True`, si a un parámetro le falta cualquiera de las tags obligatorias no se sube ni su valor ni sus tags, y se indica qué falta y en qué `parameter_name`. El resto del lote se sube con normalidad. Cuando la carga queda a medias los ficheros no se borran y el backup se resincroniza con lo ya aplicado, así que la segunda pasada solo sube lo pendiente.
+- **Round-trip de tags en la edición.** Los diffs de tags se detectan igual que los de valores (Nuevos / Modificados / Eliminados) y se aplican con `add_tags_to_resource` / `remove_tags_from_resource` en la misma pasada que el valor, sin borrar ni recrear el parámetro. Vaciar el campo de una tag la borra en AWS. Los backups automáticos incluyen las tags.
+
+### Cambiado
+
+- **Errores de permisos legibles.** `AccessDeniedException` se captura de forma específica y se muestra como `⚠ No tienes permisos para leer: /dev/rds — pídele a un admin que te dé acceso, o acota la ruta en tu parameter_list...`, sin traza de boto3. Cualquier otro error de AWS (ruta inexistente, throttling...) se propaga con su traza normal en lugar de quedar oculto tras un `except Exception`.
+- Los cambios que solo afectan a tags ya no generan una versión nueva del valor del parámetro.
+- Las pantallas de resultado son informes con scroll en vez de un mensaje centrado de 3 segundos.
+- Las tags de sistema (`aws:*`) no se exportan ni se modifican. Las tags existentes que no estén en la lista obligatoria se conservan.
+- `paramsx configure` copia la plantilla que trae el paquete, así que el fichero generado y la documentación no se pueden desincronizar.
+- La configuración se valida antes de entrar en la interfaz curses, con los errores impresos en la terminal.
+- `paramsx --help` documenta las opciones del menú y las claves de configuración.
+
+### Corregido
+
+- El menú de backup ya no muta `parameter_list` para añadir y quitar sus dos opciones extra.
+- El backup "Total parámetros listados" ya no se interrumpe cuando una ruta no tiene parámetros en algún entorno o no es accesible: continúa con el resto y avisa al final.
+- Los mensajes largos ya no rompen la pantalla: se ajustan al ancho del terminal.

{paramsx-2.1.0/paramsx.egg-info → paramsx-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paramsx
-Version: 2.1.0
+Version: 2.2.1
 Summary: Librería para gestionar y respaldar parámetros de AWS SSM de manera sencilla y eficiente.
 Home-page: https://github.com/pistatxos/paramsx
 Author: Mariox
@@ -81,7 +81,8 @@ la ruta en tu parameter_list a algo más específico (ej. /dev/rds/<sub-ruta>).
 
 2. Comparar y actualizar parámetros
 - Una vez finalizados los ajustes en los parámetros descargados, selecciona esta opción.
-- El programa pedirá el entorno correspondiente y realizará una comparación detallada, tanto de valores como de tags:
+- El programa te muestra **los ficheros que tienes en el directorio** listos para cargar (los que conservan su backup al lado) y eliges cuál. No te pregunta por rutas ni entornos: el fichero ya sabe de dónde salió.
+- Con el elegido hace una comparación detallada, tanto de valores como de tags:
     - Nuevos: Parámetros que serán añadidos.
     - Modificados: Parámetros existentes cuyo valor y/o tags serán actualizados.
     - Eliminados: Parámetros que serán borrados de AWS.
@@ -96,10 +97,10 @@ Esto te permitirá mantener respaldos seguros o realizar migraciones/reorganizac
 
 4. Crear nuevo parámetro
 - Crea un parámetro desde cero sin salir de la herramienta. Te pedirá, en este orden:
-    - La ruta completa, **siempre en convención `min`** (entorno primero y todo en minúscula: se fuerza automáticamente).
+    - La ruta **sin el entorno**, igual que la declaras en `parameter_list`: el perfil de naming se encarga de colocarlo. Verás en pantalla la ruta resultante en AWS antes de seguir.
     - El valor: texto plano o JSON en una línea (por ejemplo `{"host": "x", "user": "y", "pass": "z"}`), que se valida antes de continuar.
-    - Las tags obligatorias, si tienes `abac = True`.
-- No se puede crear un parámetro nuevo con la convención `max`: esa convención existe solo para seguir leyendo y editando los paths legacy.
+    - Las tags obligatorias, si tienes `tags_activas = True`.
+- El perfil que se usa es el que declares en `convencion_nuevos`. Si tu perfil es de tipo `mixto`, escribe el `*` en la ruta para indicar dónde va el entorno.
 - Antes de subirlo verás una pantalla de confirmación con la ruta, el valor y las tags. El parámetro se crea con `Overwrite=False`, así que nunca machaca uno existente.
 - Tras crearlo aparecerá la próxima vez que leas la ruta correspondiente de tu `parameter_list`.
 
@@ -127,73 +128,146 @@ Este comando creará automáticamente una carpeta de configuración en tu direct
 
 Dentro de esta carpeta, encontrarás el archivo paramsx_config.py. Este archivo contiene la configuración inicial que debes ajustar según tu entorno.
 
+Si ya tenías configuración de una versión anterior, `paramsx configure` **no la sobrescribe**: te dice qué opciones nuevas no tienes y con qué valor por defecto se están rellenando, y si la configuración es válida. Con `paramsx configure --ejemplo` además deja la plantilla de esta versión en `paramsx_config.ejemplo.py`, al lado de la tuya, para que compares sin tocar nada.
+
 Ejemplo del contenido de paramsx_config.py:
 
 ```python
 ## Configuraciones ParamsX
 
+# --- Perfiles de naming -------------------------------------------------------------
+# Un perfil dice CÓMO se construye la ruta real en AWS a partir de la ruta que declaras
+# en 'parameter_list' y del entorno que eliges en el menú. Los nombres son tuyos: define
+# solo los que uses y llámalos como quieras. Un perfil tiene tres campos:
+#
+#   campo             | valores                                  | qué decide
+#   ------------------+------------------------------------------+---------------------------
+#   posicion_entorno  | inicio | final | mixto | ninguno          | dónde va el entorno
+#   case_entorno      | lower | upper | capitalize                | cómo se escribe el entorno
+#   case_ruta         | lower | upper | capitalize | ninguno      | case de la ruta AL CREAR
+#
+# posicion_entorno -> dónde se coloca el entorno (ejemplos con el entorno 'dev'):
+#
+#   valor    | ruta declarada  | ruta real en AWS
+#   ---------+-----------------+--------------------------------------------------------
+#   inicio   | /rds            | /dev/rds
+#   final    | /API/STA        | /API/STA/DEV
+#   mixto    | /API/*/STA      | /API/DEV/STA    el '*' marca el sitio; uno y como segmento
+#   ninguno  | /api/sta/auth   | /api/sta/auth   una cuenta AWS por entorno; case_entorno da igual
+#
+# case_entorno -> cómo se escribe ese entorno en la ruta:
+#
+#   valor       | 'dev' se escribe | ruta real de /API/STA con posicion_entorno=final
+#   ------------+------------------+------------------------------------------------
+#   lower       | dev              | /API/STA/dev
+#   upper       | DEV              | /API/STA/DEV
+#   capitalize  | Dev              | /API/STA/Dev
+#
+# case_ruta -> a qué case se fuerza la ruta que TÚ escribes al CREAR un parámetro
+# (opción 4 del menú). No afecta a leer ni a editar: lo que ya existe en AWS se
+# respeta siempre tal cual esté.
+#
+#   valor       | si escribes /API/MULTIAPI/Token, se crea
+#   ------------+-----------------------------------------
+#   lower       | /api/multiapi/token
+#   upper       | /API/MULTIAPI/TOKEN
+#   capitalize  | /Api/Multiapi/Token
+#   ninguno     | /API/MULTIAPI/Token
+#
+# Combina los tres campos como necesites: no hay una lista cerrada de perfiles. En el
+# README tienes más ejemplos.
+
+naming = {
+    "min": {"posicion_entorno": "inicio", "case_entorno": "lower", "case_ruta": "lower"},
+    "max": {"posicion_entorno": "final", "case_entorno": "upper", "case_ruta": "ninguno"},
+    "mixto_max": {"posicion_entorno": "mixto", "case_entorno": "upper", "case_ruta": "ninguno"},
+    # Crea los tuyos combinando los valores de la tabla, por ejemplo:
+    # "sin_entorno": {"posicion_entorno": "ninguno", "case_entorno": "lower", "case_ruta": "ninguno"},
+}
+
 configuraciones = {
     "profile_name": "default",           # Cambiar por el nombre de tu perfil en ~/.aws/credentials
     "region_name": "eu-south-2",         # Cambiar por tu región de AWS
     "entornos": ['dev', 'pre', 'prod'],  # SIEMPRE en minúscula, es la lista canónica única
     "parameter_list": [
-        {"path": "/common", "convencion": "min"},
-        {"path": "/rds", "convencion": "min"},
-        {"path": "/api", "convencion": "min"},
-        {"path": "/EMAIL", "convencion": "max"},
-        {"path": "/API/STA", "convencion": "max"},
+        {"path": "/common", "convencion": "min"},      # -> /dev/common
+        {"path": "/rds", "convencion": "min"},         # -> /dev/rds
+        {"path": "/EMAIL", "convencion": "max"},       # -> /EMAIL/DEV
+        {"path": "/API/STA", "convencion": "max"},     # -> /API/STA/DEV
+        # Con 'mixto' acotas por debajo del entorno: esto lee solo stan_ai, en vez de
+        # todo lo que cuelga de /API/MULTIAPI/DEV
+        {"path": "/API/MULTIAPI/*/stan_ai", "convencion": "mixto_max"},  # -> /API/MULTIAPI/DEV/stan_ai
     ]
 }
 
-abac = True
-
+# Perfil de naming que se usa al crear un parámetro nuevo (opción 4 del menú).
+# Si no lo defines, se usa el primer perfil de 'naming'.
+convencion_nuevos = "min"
+
+# ¿El nombre del fichero exportado incluye la ruta leída?
+#   False -> parameters_dev.py            (comportamiento de siempre)
+#   True  -> parameters_dev__API_STA__max.py  (uno por entrada y entorno: lleva el
+#            entorno, la ruta y el perfil, porque dos entradas pueden compartir ruta)
+# Ponlo en True si sueles leer varias rutas del mismo entorno y no quieres que la
+# segunda lectura te machaque el fichero de la primera.
+fichero_por_ruta = False
+
+
+## Configuraciones Tags
+
+# Gestionar las tags de los parámetros: leerlas de AWS, exponerlas en el fichero
+# exportado para editarlas y validar las obligatorias al cargar.
+#   True  -> las tags viajan en el fichero y se validan.
+#   False -> no aparecen tags en el fichero y no se valida nada.
+# En cuentas cuyo control de acceso va por tags (ABAC vía IAM) esto debe estar en True.
+tags_activas = True
+
+# Solo aplica si tags_activas = True.
+#   False -> validación bloqueante: si a un parámetro le falta alguna tag obligatoria
+#            no se sube (ni su valor ni sus tags).
+#   True  -> se permiten vacías: el parámetro se sube igualmente y las tags sin valor
+#            simplemente NO se crean en AWS (no se suben como etiquetas vacías).
 obligatorias_vacias = False
 
+# Tags que se exigen en cada parámetro cuando tags_activas = True. La lista es libre:
+# estas 8 son las que sostienen el control de acceso ABAC vía IAM de nuestra cuenta.
 tags_obligatorias = [
-    "Application", "Environment", "Owner", "Project",
-    "Product", "Service", "Component", "ManagedBy",
+    "Application",
+    "Environment",
+    "Owner",
+    "Project",
+    "Product",
+    "Service",
+    "Component",
+    "ManagedBy",
 ]
 ```
 Nota: Si el archivo paramsx_config.py ya existe, no será sobrescrito durante la instalación para proteger las configuraciones personalizadas.
 
-### La doble convención de naming: `min` y `max`
+### Los perfiles de naming
 
-Durante la transición a la convención nueva conviven dos formas de construir la ruta. Cada entrada de `parameter_list` declara la suya, y **la diferencia no es solo el case: también cambia la posición donde se inserta el entorno**.
+Cada organización nombra sus parámetros a su manera, así que ParamsX no impone ninguna convención: **tú defines los perfiles que uses en el diccionario `naming` y les pones el nombre que quieras**. Cada entrada de `parameter_list` declara con qué perfil se construye su ruta completa. Los tres campos de un perfil y sus valores están explicados en el propio fichero de configuración, ahí arriba.
 
-| convencion | Qué hace | Ejemplo con entorno `dev` |
-|---|---|---|
-| `min` | Convención nueva. Añade el entorno en **minúscula al principio** de la ruta. | `/rds` → `/dev/rds` |
-| `max` | Convención legacy. Inserta el entorno en **mayúscula tras el primer segmento**. | `/API/STA` → `/API/DEV/STA` |
-| `max` | Con un solo segmento queda al final. | `/EMAIL` → `/EMAIL/DEV` |
+**No hay una lista cerrada de perfiles.** Los tres campos se combinan libremente, así que la plantilla no intenta traértelos todos: define los dos o tres que use tu organización y olvídate del resto. `min` y `max` vienen predefinidos porque son los que ParamsX traía antes de que los perfiles fueran configurables.
 
-Ya **no existe** la lista `entornos_old`: el entorno en mayúscula de las rutas `max` se deriva con `.upper()` de la misma lista canónica `entornos`, que se escribe siempre en minúscula.
+**Para qué sirve el `*`.** Además de colocar el entorno donde quieras, acota la lectura a un solo subárbol: con `/API/MULTIAPI/*/stan_ai` lees únicamente `/API/MULTIAPI/DEV/stan_ai`, en vez de todo lo que cuelga de `/API/MULTIAPI/DEV`. Debe ser un segmento entero, aparecer **exactamente una vez** y solo se admite en perfiles `mixto`: si el perfil y la ruta no cuentan la misma historia, ParamsX te lo dice al arrancar en vez de leer una ruta inexistente y devolverte una lista vacía.
 
-Ejemplo completo de una `parameter_list` migrada, mezclando rutas nuevas y legacy:
+**Los entornos.** Ya no existe la lista `entornos_old`: el entorno sale siempre de la lista canónica `entornos` (en minúscula), aplicándole el `case_entorno` del perfil. Si en tus rutas se llama `staging` en vez de `pre`, ponlo así en `entornos`.
 
-```python
-    "parameter_list": [
-        {"path": "/common", "convencion": "min"},
-        {"path": "/rds", "convencion": "min"},
-        {"path": "/api", "convencion": "min"},
-        {"path": "/INFRA", "convencion": "max"},
-        {"path": "/API/STA", "convencion": "max"},
-        {"path": "/API/p15", "convencion": "max"},
-        {"path": "/API/MULTIAPI", "convencion": "max"},
-        {"path": "/APP/Alertas", "convencion": "max"},
-        {"path": "/API/ALERTAS", "convencion": "max"},
-        {"path": "/APP/Eter", "convencion": "max"},
-        {"path": "/API/GIS", "convencion": "max"},
-        {"path": "/API/PANGEA", "convencion": "max"},
-        {"path": "/BUCKETS", "convencion": "max"},
-        {"path": "/EMAIL", "convencion": "max"},
-        {"path": "/INFERENCIAS/TASA_DMI", "convencion": "max"},
-        {"path": "/IP", "convencion": "max"},
-        {"path": "/TASA", "convencion": "max"},
-        {"path": "/CEE/CEXGEN", "convencion": "max"},
-    ]
-```
+Y ParamsX **no renombra ni fuerza el case de los parámetros que ya existen**: los lee y edita tal cual estén. El `case_ruta` del perfil solo entra en juego al crear parámetros nuevos.
+
+### Un fichero por ruta: `fichero_por_ruta`
 
-Sobre mayúsculas y minúsculas: ParamsX **no renombra ni fuerza el case de los parámetros que ya existen**, los lee y edita tal cual estén según la convención que hayas indicado para esa ruta. Los parámetros **nuevos** que crea la herramienta (opción 4) van siempre en convención `min`.
+Al leer una ruta se generan `parameters_{entorno}.py` y su backup. Ese nombre depende solo del entorno, así que si lees una segunda ruta del mismo entorno **machacas el fichero de la primera**. Por defecto ParamsX te avisa y te pide confirmación antes de sobrescribir.
+
+Si trabajas a menudo con varias rutas del mismo entorno, pon `fichero_por_ruta = True`: cada entrada pasa a tener su propio fichero y dejan de pisarse. Al cargar los verás todos en la lista y eliges cuál aplicar.
+
+En el nombre van el entorno, la ruta y el perfil, porque dos entradas pueden compartir la ruta declarada y apuntar a sitios distintos:
+
+| Entrada | Fichero |
+|---|---|
+| `{"path": "/API/STA", "convencion": "max"}` | `parameters_dev__API_STA__max.py` |
+| `{"path": "/API/*/STA", "convencion": "mixto_max"}` | `parameters_dev__API_env_STA__mixto_max.py` |
 
 ### Cómo acotar tu parameter_list (recomendación)
 
@@ -204,22 +278,24 @@ Sobre mayúsculas y minúsculas: ParamsX **no renombra ni fuerza el case de los
 
 Si configuras una ruta más amplia que tus permisos, no pasa nada grave: ParamsX te avisará con un mensaje claro de acceso denegado en vez de una traza de boto3. Pero afinar la ruta te ahorra el error.
 
-### Tags obligatorias y el flag `abac`
+### Tags obligatorias y el flag `tags_activas`
 
-El control de acceso a los valores privados de la cuenta va por **tags IAM** (condición `aws:ResourceTag/${TagKey}` sobre `GetParameter`), no por restricción de path — la única excepción es `/{entorno}/common/*`, que se concede por prefijo de ruta. Por eso estas 8 tags son el mínimo no negociable: son las que sostienen todo el modelo ABAC de la cuenta AWS.
+En nuestra cuenta, el control de acceso a los valores privados va por **tags IAM** (condición `aws:ResourceTag/${TagKey}` sobre `GetParameter`), no por restricción de path — la única excepción es `/{entorno}/common/*`, que se concede por prefijo de ruta. Por eso estas 8 tags son ahí el mínimo no negociable: son las que sostienen todo el modelo ABAC.
 
 ```
 Application, Environment, Owner, Project, Product, Service, Component, ManagedBy
 ```
 
-La lista vive en `tags_obligatorias`, dentro de tu propio `paramsx_config.py`, para poder ampliarla sin tocar código.
+La lista vive en `tags_obligatorias`, dentro de tu propio `paramsx_config.py`: es libre, pon las que use tu organización.
 
-El flag `abac` decide si ParamsX gestiona tags:
+El flag `tags_activas` decide si ParamsX gestiona tags:
 
-- **`abac = True`**: al leer parámetros, el fichero exportado incluye un campo por tag con su valor actual en AWS (vacío si el parámetro es legacy y no la tiene). Al cargar, es **obligatorio** que las 8 tengan valor.
-- **`abac = False`**: las tags no aparecen en el fichero exportado en absoluto y no se valida nada (comportamiento de la 1.x).
+- **`tags_activas = True`**: al leer parámetros, el fichero exportado incluye un campo por tag con su valor actual en AWS (vacío si el parámetro es legacy y no la tiene). Al cargar, es **obligatorio** que todas tengan valor.
+- **`tags_activas = False`**: las tags no aparecen en el fichero exportado en absoluto y no se valida nada (comportamiento de la 1.x).
 
-Formato del fichero exportado con `abac = True`:
+Este flag se llamaba `abac` en la 2.0 y la 2.1. El nombre viejo se sigue aceptando, así que no tienes que tocar tu configuración, pero `tags_activas` describe lo que hace de verdad: activar la gestión de tags. Que esas tags sostengan un modelo ABAC es el motivo por el que tú las quieres, no lo que hace el flag.
+
+Formato del fichero exportado con `tags_activas = True`:
 
 ```python
 parametros = [
@@ -241,7 +317,7 @@ Este formato con tags **solo existe en el fichero temporal que genera ParamsX**:
 
 #### `obligatorias_vacias`: cuando alguna tag tiene que ir vacía
 
-En la práctica hay parámetros a los que no les aplica alguna de las 8 tags. Ese caso se controla con `obligatorias_vacias`, y solo tiene efecto si `abac = True`:
+En la práctica hay parámetros a los que no les aplica alguna de las 8 tags. Ese caso se controla con `obligatorias_vacias`, y solo tiene efecto si `tags_activas = True`:
 
 | `obligatorias_vacias` | Comportamiento |
 |---|---|
@@ -250,14 +326,14 @@ En la práctica hay parámetros a los que no les aplica alguna de las 8 tags. Es
 
 Ojo con la diferencia entre "vacía" y "borrada": con `obligatorias_vacias = True`, una tag que se deja en blanco y **nunca existió** simplemente no se crea; pero si esa tag **ya tenía valor en AWS** y la vacías en el fichero, se interpreta como que quieres borrarla y se elimina del parámetro. Es la forma de quitar una tag.
 
-Detalles del comportamiento con `abac = True`:
+Detalles del comportamiento con `tags_activas = True`:
 
-- La validación es **por parámetro**, no global: con `obligatorias_vacias = False`, si a uno le falta cualquiera de las 8 tags no se sube ni su valor ni sus tags, y verás un error indicando qué tags faltan y a qué `parameter_name`. El resto de parámetros del fichero que estén completos se suben con normalidad.
+- La validación es **por parámetro**, no global: con `obligatorias_vacias = False`, si a uno le falta cualquiera de las tags obligatorias no se sube ni su valor ni sus tags, y verás un error indicando qué tags faltan y a qué `parameter_name`. El resto de parámetros del fichero que estén completos se suben con normalidad.
 - Cuando una carga queda a medias, los ficheros `parameters_{entorno}.py` y su backup **no se borran**, para que corrijas lo que falta y vuelvas a cargar. El backup se resincroniza con lo ya aplicado, así que la segunda pasada solo sube lo que quedó pendiente.
 - Si el parámetro ya existe y le faltan tags (creado antes de esta versión), se rellenan en este mismo flujo de edición, sin borrar ni recrear el parámetro.
 - Los cambios de tags se aplican con `add_tags_to_resource` / `remove_tags_from_resource` en la misma pasada que el valor. Vaciar el campo de una tag en el fichero equivale a borrarla en AWS.
 - Las tags de sistema (`aws:*`) no se exportan ni se tocan. Las tags que ya existan en AWS y no estén en la lista obligatoria se conservan y se pueden editar.
-- No hay forma de saltarse la validación por parámetro salvo relajarla explícitamente en tu configuración con `obligatorias_vacias = True`, o desactivar las tags por completo con `abac = False`.
+- No hay forma de saltarse la validación por parámetro salvo relajarla explícitamente en tu configuración con `obligatorias_vacias = True`, o desactivar las tags por completo con `tags_activas = False`.
 
 #### Configuración manual del PATH
 En algunos sistemas (especialmente en entornos corporativos como Windows), el PATH puede no configurarse automáticamente durante la instalación. Si ocurre esto, sigue los pasos según tu sistema operativo:
@@ -280,7 +356,17 @@ En algunos sistemas (especialmente en entornos corporativos como Windows), el PA
 ```source ~/.zshrc    # Para zsh```
 
 Una vez instalado, verifica que el comando paramsx esté disponible ejecutando:
-```paramsx --help```
+```paramsx --version```
+
+Comandos disponibles:
+
+| Comando | Qué hace |
+|---|---|
+| `paramsx` | Abre el menú interactivo (necesita configuración). |
+| `paramsx configure` | Crea la configuración la primera vez; si ya existe, la revisa sin tocarla. |
+| `paramsx configure --ejemplo` | Además deja la plantilla de esta versión al lado, para comparar. |
+| `paramsx --version` | Versión instalada. |
+| `paramsx --help` | Ayuda, con el resumen de todas las opciones de configuración. |
 
 
 ## Modo de empleo
@@ -297,13 +383,13 @@ El programa mostrará un menú donde Podrás:
 - Crear un parámetro nuevo.
 
 ### Leer Parámetros:
-1. Selecciona la opción "Leer parámetros" en el menú. La lista muestra cada ruta con su convención, por ejemplo `/rds  [min]` o `/API/STA  [max]`.
+1. Selecciona la opción "Leer parámetros" en el menú. La lista muestra cada ruta con su perfil de naming, por ejemplo `/rds  [min]` o `/API/STA  [max]`.
 2. Elige el prefijo y el entorno que deseas consultar.
 3. Los parámetros serán descargados y guardados en archivos como:
     - parameters_dev.py
     - parameters_dev_backup.py
     ```Importante: Los archivos se generarán en la misma ruta desde donde ejecutes el comando paramsx```
-4. Edita el archivo parameters_{entorno}.py con tu software favorito. Con `abac = True` cada parámetro trae además sus 8 campos de tag para rellenar.
+4. Edita el archivo parameters_{entorno}.py con tu software favorito. Con `tags_activas = True` cada parámetro trae además un campo por cada tag obligatoria para rellenar.
 
 ### Cargar Parámetros:
 1. Modifica los archivos generados (parameters_dev.py).
@@ -318,9 +404,9 @@ El programa mostrará un menú donde Podrás:
 
 ### Crear un parámetro nuevo:
 1. Selecciona la opción "Crear nuevo parámetro" y elige el entorno.
-2. Escribe la ruta completa en convención `min` (`/dev/...`): se fuerza a minúscula y se valida que el primer segmento sea el entorno.
+2. Escribe la ruta **sin el entorno**, como en tu `parameter_list`: ParamsX le aplica el perfil de `convencion_nuevos` y te enseña la ruta resultante en AWS para que la confirmes.
 3. Escribe el valor: texto plano o JSON en una línea.
-4. Rellena las tags obligatorias (si `abac = True`). `Environment` viene precargada con el entorno elegido. Con `obligatorias_vacias = True` puedes dejar alguna en blanco pulsando Enter: esas no se crearán en AWS.
+4. Rellena las tags obligatorias (si `tags_activas = True`). `Environment` viene precargada con el entorno elegido. Con `obligatorias_vacias = True` puedes dejar alguna en blanco pulsando Enter: esas no se crearán en AWS.
 5. Confirma en la pantalla de resumen. Si es un parámetro de RDS y falta su contraparte (común o privado), verás el aviso de correlación de naming ahí mismo.
 
 ### Backup Parámetros: