Merge pull request #1546 from codeX-james/docs/sync-issues-1514-1517

docs: sync translations, document planned flags, add capability_summary verification

Author: ritik4ever

docs/CONTRACT_DEPLOYMENT_CHECKLIST.md

@@ -244,6 +244,14 @@ Use this for testing with real Stellar testnet infrastructure.
     --id $CONTRACT_ID \
     --network testnet
   ```
+- [ ] Verify `capability_summary` output matches the expected capability set for this release (see [Capability Summary Verification](#capability-summary-verification)):
+  ```bash
+  soroban contract invoke \
+    --id $CONTRACT_ID \
+    --source deployer \
+    --network testnet \
+    -- capability_summary
+  ```
 
 ### Initialize
 
@@ -372,6 +380,14 @@ Use this for pre-production testing on testnet.
   ```bash
   export STAGING_CONTRACT_ID=C...
   ```
+- [ ] Verify `capability_summary` output matches the expected capability set for this release (see [Capability Summary Verification](#capability-summary-verification)):
+  ```bash
+  soroban contract invoke \
+    --id $STAGING_CONTRACT_ID \
+    --source staging-deployer \
+    --network testnet \
+    -- capability_summary
+  ```
 
 ### Initialize
 
@@ -506,6 +522,14 @@ Use this for mainnet deployment. **This is irreversible and uses real XLM.**
     --id $PROD_CONTRACT_ID \
     --network mainnet
   ```
+- [ ] Verify `capability_summary` output matches the expected capability set for this release (see [Capability Summary Verification](#capability-summary-verification)) — **do not proceed to Initialize if this fails**:
+  ```bash
+  soroban contract invoke \
+    --id $PROD_CONTRACT_ID \
+    --source prod-deployer \
+    --network mainnet \
+    -- capability_summary
+  ```
 
 ### Initialize
 
@@ -570,6 +594,38 @@ Use this for mainnet deployment. **This is irreversible and uses real XLM.**
 
 ---
 
+## Capability Summary Verification
+
+Every deployment (testnet, staging, and production) must be verified post-deploy by calling the read-only `capability_summary` contract method (`contracts/CONTRACT_ABI.md`) before initialization or traffic cutover. This is the single cheapest way to confirm the deployed WASM matches the intended release — a stale or mismatched deploy is caught here before it reaches `initialize` or the auto-rebalancer.
+
+An automated equivalent of this check is planned for the contract-deploy pipeline (`deployment/contract-deploy.sh`), which would fail the deployment job automatically if `capability_summary` doesn't match expectations after `soroban contract deploy`. Until that automation lands, the manual checklist step above is required for every environment.
+
+### Expected capability set (current release)
+
+| Field                        | Expected value                                                       |
+| ----------------------------- | ---------------------------------------------------------------------- |
+| `version`                     | `1` (`CONTRACT_VERSION`, `contracts/src/types.rs`)                     |
+| `schema_version`              | `1` (`CONTRACT_EVENT_SCHEMA_VERSION`, `contracts/src/types.rs`)        |
+| `capability_flags`            | `7` (`PerPortfolioSteward \| DifferentiatedPricing \| EmergencyStop`)  |
+| `min_rebalance_threshold`     | `1`                                                                    |
+| `max_rebalance_threshold`     | `50`                                                                   |
+| `min_slippage_tolerance_bps`  | `10`                                                                   |
+| `max_slippage_tolerance_bps`  | `500`                                                                  |
+| `max_portfolio_assets`        | `10`                                                                   |
+
+> These values are sourced from `contracts/src/types.rs` and `contracts/src/lib.rs` (`capabilities()`). Update this table whenever a contract release changes `CONTRACT_VERSION`, `CONTRACT_EVENT_SCHEMA_VERSION`, adds a `CapabilityFlag` variant, or changes any of the min/max constants.
+
+### Escalation path on verification failure
+
+If `capability_summary` does not match the expected values above:
+
+1. **Do not** proceed to `initialize` or cut over traffic to the new contract ID.
+2. Re-check that the deployed WASM matches the intended release commit (`soroban contract info --wasm <path>` hash vs. the release's recorded hash from `make hash`).
+3. If the mismatch is unexplained, halt the deployment and escalate to the team in the deployment channel/wiki (see [Documentation](#documentation) steps) before retrying.
+4. Once resolved, redeploy and re-verify `capability_summary` before continuing.
+
+---
+
 ## Rollback Procedure
 
 If production deployment fails or needs to be reverted:

docs/FEATURE_FLAGS.md

@@ -32,6 +32,17 @@ Public copies of the main booleans are exposed on `GET /api/v1/system/status` un
 | `VITE_ENABLE_API_DEBUG_LOGS` | Verbose API logging via `frontend/src/utils/debug.ts`. |
 | `API_CONFIG.USE_BROWSER_PRICES` | **Code flag** in `frontend/src/config/api.ts` (currently `true`): GET `/prices` uses `browserPriceService` in the browser instead of the backend envelope. |
 
+## Planned Flags (Not Yet Implemented)
+
+The following flags do not exist in code yet — no environment variable is currently read for them. They are documented here ahead of implementation so the naming and rollout plan are agreed before the toggles are wired up. Update this section (move entries into [Backend](#backend-node--api)) once each flag lands in `backend/src/config/featureFlags.ts`.
+
+| Planned variable | Default (non‑prod) | Default (production) | Effect once implemented |
+|----------|-------------------|----------------------|--------|
+| `ENABLE_DCA_STRATEGY` | `false` | `false` | Would gate DCA (dollar-cost averaging) rebalance strategy support described conceptually in [`docs/REBALANCING_STRATEGIES.md`](REBALANCING_STRATEGIES.md). No DCA strategy code exists yet — the flag is a placeholder for the eventual rollout. |
+| `ENABLE_BULK_IMPORT` | `true` | `false` | Would gate the portfolio bulk import endpoint (`POST /api/v1/portfolio/import`, implemented in `backend/src/api/portfolioImportRoutes.ts` / `backend/src/services/portfolioImportService.ts`). Today this endpoint is **always enabled** and reads no feature flag; this entry documents the intended flag name for adding a kill switch. |
+
+**Local toggling (once implemented):** set the variable in `backend/.env` (or `config/feature-flags.staging.json` via `FEATURE_FLAGS_FILE`, see [File-Based Overrides](#file-based-overrides-staging--local)) the same way as any other backend boolean flag, then restart the backend.
+
 ## Safe combinations
 
 **Local development**

docs/README.es.md

@@ -1,5 +1,8 @@
 # Stellar Portfolio Rebalancer — README (Español)
 
+[![GitHub Repo](https://img.shields.io/badge/repo-Stellar%20Portfolio%20Rebalancer-blue?style=flat-square)](https://github.com/ritik4ever/stellar-portfolio-rebalancer)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 > **Nota:** Esta traducción puede estar una versión por detrás del README en inglés. Consulte el [README principal](../README.md) para obtener la información más actualizada.
 
 [English](../README.md) | [Português](README.pt.md) | **Español**
@@ -26,6 +29,54 @@ Ayuda a los usuarios a mantener una asignación óptima de activos mediante reba
 
 ---
 
+## Hoja de Ruta del Proyecto
+
+Vea hacia dónde se dirige Stellar Portfolio Rebalancer.
+
+| **Ahora** (Sprint Actual)          | **Próximamente** (1-2 meses) | **Más Adelante** (3-6+ meses) |
+| :---------------------------------- | :----------------------------- | :------------------------------ |
+| Algoritmo de rebalanceo principal   | Panel de control de cartera    | Aplicación móvil                |
+| Integración de oráculo Reflector    | Informes históricos            | Estrategias personalizadas      |
+| Estabilidad de conexión de billetera| Sistema de notificaciones      | Integración DeFi                |
+| Corrección de errores               | Soporte multi-activo           | Optimización fiscal             |
+
+**[Ver hoja de ruta detallada →](ROADMAP.md)**
+
+---
+
+## Arquitectura
+
+```text
+stellar-portfolio-rebalancer/
+├── contracts/     # Contratos inteligentes Soroban
+├── frontend/      # Frontend React + TypeScript
+├── backend/       # API Node.js + Express
+├── deployment/    # Archivos de despliegue Docker
+└── docs/          # Documentación (incluyendo ADRs)
+```
+
+### Términos Clave
+
+Los nuevos contribuidores deben leer el glosario antes de profundizar en la configuración o el trabajo con el contrato.
+
+- **Portfolio (Cartera)**: El objeto de asignación gestionado por el usuario, identificado por `portfolio_id`.
+- **Target Allocation, Rebalance Threshold y Slippage Tolerance**: Los principales parámetros del contrato para el rebalanceo automatizado.
+- **Reflector Oracle**: La fuente de precios que usa el contrato para decidir sobre desviación (drift) y rebalanceo.
+- **Cooldown Period y Emergency Stop**: Controles de seguridad integrados para los rebalanceos.
+
+📘 **Acceso al Glosario:** Consulte [docs/GLOSSARY.md](GLOSSARY.md) para el glosario central y enlaces cruzados a la documentación de contrato, API y despliegue.
+
+### Stack Tecnológico
+
+| Capa                | Tecnología                          |
+| -------------------- | ------------------------------------ |
+| Contratos Inteligentes | Rust + Soroban                     |
+| Frontend             | React + TypeScript + Tailwind CSS    |
+| Backend              | Node.js + Express + TypeScript       |
+| Datos de Precios     | Reflector + CoinGecko API            |
+
+---
+
 ## Inicio Rápido
 
 ### Requisitos Previos
@@ -68,6 +119,47 @@ cp frontend/.env.example frontend/.env
 
 Referencia completa del entorno del backend: [`docs/ENVIRONMENT.md`](ENVIRONMENT.md)
 
+**Versionado de la API:** El cliente HTTP del frontend apunta a `/api/v1/*` para las rutas de recursos de forma predeterminada (`VITE_API_VERSION=v1` en `frontend/.env.example`). La autenticación JWT sigue usando `/api/auth/*`. Consulte [API.md](API.md) para detalles completos de versionado.
+
+**Ejemplos de Cliente API:** Consulte el ejemplo de cliente API en Python (o el archivo de ejemplos correspondiente) para ver integraciones de referencia.
+
+### Configuración de la Base de Datos
+
+Las migraciones de PostgreSQL están disponibles para entornos configurados con `DATABASE_URL` o las variables `PGHOST` / `PGDATABASE` / `PGUSER`.
+
+```bash
+cd backend
+npm run db:migrate                 # Aplicar migraciones
+npm run db:migrate -- --dry-run    # Previsualizar migraciones
+```
+
+**Desarrollo local:** Para el desarrollo local con SQLite, deje las variables de PostgreSQL sin definir y use `DB_PATH` en su lugar. La ruta predeterminada es `backend/data/portfolio.db`. El backend crea el archivo de la base de datos y su directorio padre automáticamente al iniciar. Los clones nuevos no deben incluir archivos `.db`, `.db-wal` o `.db-shm` preconstruidos.
+
+**Siembra de demo:** Los datos de demostración de SQLite solo aparecen cuando la siembra de demo está habilitada mediante `ENABLE_DEMO_DB_SEED` o el Modo Demo. De lo contrario, la base de datos local inicia vacía y se inicializa a partir del esquema y las fuentes de semillas registradas en el repositorio.
+
+### Notificaciones por Correo (Opcional)
+
+Ejemplo de configuración con Gmail:
+
+```env
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_SECURE=false
+SMTP_USER=your-email@gmail.com
+SMTP_PASS=your-app-password
+SMTP_FROM=your-email@gmail.com
+```
+
+También se admiten otros proveedores como SendGrid, Mailgun y AWS SES.
+
+Prueba de notificaciones:
+
+```bash
+curl -X POST http://localhost:3001/api/v1/notifications/subscribe \
+  -H "Content-Type: application/json" \
+  -d '{"userId": "YOUR_STELLAR_ADDRESS", "eventType": "rebalance"}'
+```
+
 ### Desarrollo
 
 Inicie los servidores de desarrollo:
@@ -85,14 +177,79 @@ npm run dev
 - Frontend: http://localhost:3000
 - Backend API: http://localhost:3001
 
-### Uso
+### Despliegue del Contrato Inteligente
+
+```bash
+cd contracts
+
+# Construir el contrato
+soroban contract build
+
+# Desplegar en testnet
+soroban contract deploy \
+  --wasm target/wasm32-unknown-unknown/release/portfolio_rebalancer.wasm \
+  --source deployer \
+  --network testnet
+
+# Inicializar el contrato
+soroban contract invoke \
+  --id YOUR_CONTRACT_ID \
+  --source deployer \
+  --network testnet \
+  -- initialize \
+  --admin YOUR_ADMIN_ADDRESS \
+  --reflector_address CDSWUUXGPWDZG76ISK6SUCVPZJMD5YUV66J2FXFXFGDX25XKZJIEITAO
+```
+
+Ejemplo de dirección de contrato: `CCQ4LISQJFTZJKQDRJHRLXQ2UML45GVXUECN5NGSQKAT55JKAK2JAX7I`
+
+Para un checklist completo por entorno (local, testnet, staging, producción), vea [Contract Deployment Checklist](CONTRACT_DEPLOYMENT_CHECKLIST.md).
+
+### Verificación del Hash WASM
+
+Antes de desplegar, puede calcular y auditar el hash SHA-256 canónico del contrato WASM compilado para garantizar la reproducibilidad y la seguridad:
+
+```bash
+cd contracts
+make hash
+```
+
+Este target genera el hash tanto del WASM de release como del WASM optimizado (si está disponible). El mismo cálculo de hash se ejecuta automáticamente en las compilaciones de release/PR para simplificar las auditorías de despliegue.
+
+**Recursos para desarrolladores:**
+
+- Referencia de la interfaz del contrato (funciones, errores, notas de tipos): [contracts/CONTRACT_ABI.md](../contracts/CONTRACT_ABI.md)
+- Comandos y ejemplos comunes de invocación de Soroban: [docs/soroban-cookbook.md](soroban-cookbook.md)
+- Matriz de compatibilidad y capacidades del frontend (mapeo de degradación): [docs/CONTRACT_CAPABILITY_MATRIX.md](CONTRACT_CAPABILITY_MATRIX.md)
+
+---
+
+## Uso
+
+📸 ¿Nuevo en la plataforma? Consulte nuestro [Recorrido Visual de la Demo](DEMO_WALKTHROUGH.md) con capturas de pantalla paso a paso y explicaciones detalladas.
+
+### Flujo Rápido
 
 1. Conecte su billetera Stellar
 2. Cree una cartera y establezca las asignaciones objetivo (la suma debe ser 100%, máximo 10 activos por cartera)
 3. Configure los umbrales de rebalanceo (1–50%)
 4. Active/desactive el rebalanceo automático
 5. Envíe la transacción
 
+**Detección de Volatilidad:** Pausa el rebalanceo durante condiciones de mercado extremas.
+
+**Límites de Concentración:** Evita la sobreasignación a un único activo.
+
+**Circuit Breakers:** Múltiples verificaciones de seguridad antes de ejecutar operaciones.
+
+### Notificaciones
+
+Notificaciones por correo electrónico y webhook para eventos de rebalanceo.
+
+Tipos de evento: rebalanceo, circuit breaker, movimiento de precio, cambios de riesgo.
+
+Configurable por usuario.
+
 ---
 
 ## Referencia de la API
@@ -115,6 +272,9 @@ GET /api/v1/portfolio/:id
 # Ejecutar rebalanceo
 POST /api/v1/portfolio/:id/rebalance
 
+# Simulación de rebalanceo (plan de solo lectura, sin escrituras en BD ni llamada al contrato)
+POST /api/v1/portfolio/:id/rebalance/dry-run
+
 # Estado del rebalanceo
 GET /api/v1/portfolio/:id/rebalance-status
 ```
@@ -135,6 +295,14 @@ GET /api/v1/prices
 GET /api/v1/portfolio/:id/rebalance-plan
 ```
 
+### Integración con Stellar DEX
+
+Operaciones reales ejecutadas en la testnet de Stellar usando `@stellar/stellar-sdk`.
+
+Ejecución con conciencia de slippage, ejecuciones parciales y reversión (rollback) automatizada.
+
+El historial de rebalanceos registra los resultados y las métricas explícitas de slippage.
+
 ---
 
 ## Pruebas
@@ -148,6 +316,19 @@ cd backend && npm test
 
 # Smart contracts
 cd contracts && cargo test
+
+# Benchmarks de gas de smart contracts
+cd contracts && make bench
+```
+
+---
+
+## Despliegue con Docker
+
+```bash
+docker compose -f deployment/docker-compose.yml config
+docker compose -f deployment/docker-compose.yml build frontend backend
+docker compose -f deployment/docker-compose.yml up --build -d
 ```
 
 ---
@@ -165,10 +346,37 @@ Pasos rápidos:
 2. Cree una rama de funcionalidad: `git checkout -b feature/funcionalidad-increible`
 3. Siga la configuración en [docs/CONTRIBUTING.md](CONTRIBUTING.md)
 4. Asegúrese de que las pruebas pasen: `cd backend && npm test && cd ../frontend && npm test`
-5. Abra un Pull Request
+5. Abra un Pull Request bien documentado
+
+---
+
+## Solución de Problemas
+
+### Problemas con la Billetera
+
+¿Tiene problemas para conectar su billetera Stellar? Consulte las [Preguntas Frecuentes de Solución de Problemas de Billetera](WALLET_TROUBLESHOOTING.md) para soluciones paso a paso de:
+
+- Errores de "la billetera no está instalada"
+- Tiempos de espera y rechazos de conexión
+- Fallos en la firma de transacciones
+- Discrepancia de red entre la billetera y la aplicación
+- Peculiaridades específicas de cada billetera (Freighter, Rabet, xBull)
+
+### Problemas Comunes de Configuración
+
+Consulte CONTRIBUTING.md §10 "Common setup failures" para problemas de backend, base de datos y entorno.
 
 ---
 
 ## Licencia
 
 Este proyecto está licenciado bajo la [Licencia MIT](https://opensource.org/licenses/MIT).
+
+## Agradecimientos
+
+- Stellar Development Foundation
+- Reflector Protocol
+- Soroban
+- Integraciones de billeteras de la comunidad
+
+Construido con ❤️ para el ecosistema Stellar.