docs(adopters): friction reduction — setup targets, contributing guide, README fixes

- Makefile: add 'make setup' (interactive config/.env) and 'make onboard' targets
- Makefile: add setup/onboard to .PHONY
- docs/CONTRIBUTING_ADOPTERS.md: first-PR guide (hardware profile, bug report, docs)
- README.md: Quick Start overhauled — setup.sh as step 0, fix admin/bessai, fix .env paths
- docs/tutorials/connecting_real_hardware.md: fix broken bounty_program.md link
- mkdocs.yml: add CONTRIBUTING_ADOPTERS.md to Para Adopters nav section

Author: BESS Solutions

Makefile

@@ -1,7 +1,7 @@
 # BESSAI Edge Gateway — Developer Makefile
 # Usage: make <target>   →   make help  for full list
 
-.PHONY: help dev install test test-cov test-compliance test-fast lint lint-fix type-check security audit \
+.PHONY: help dev install setup onboard test test-cov test-compliance test-fast lint lint-fix type-check security audit \
         all-checks simulate health up up-sim down logs build \
         gen-onnx export-cmg fetch-cmg evolve train-drl train-ppo \
         cert pilot compliance-report fleet \
@@ -33,6 +33,16 @@ dev: ## Install all dev dependencies + pre-commit hooks + security hooks
 install: ## Install runtime dependencies only
 	pip install -e "."
 
+setup: ## Interactive setup — generate config/.env for your site (5 questions)
+	@bash scripts/setup.sh
+
+onboard: setup ## Full onboarding: generate config/.env + activate PI hooks + verify Docker
+	@bash scripts/install_hooks.sh
+	@echo ""
+	@echo "✅ config/.env generated and PI hooks active."
+	@echo "📖 Next step: make up-sim   →  demo local con simulador"
+	@echo "📖 Full guide: docs/ONBOARDING_7DAYS.md"
+
 # ── Testing ────────────────────────────────────────────────────────────────────
 
 test: ## Run full test suite (compliance + edge)

README.md

@@ -170,28 +170,33 @@ graph LR
 
 ## ⚡ Quick Start
 
-### 1. Local (Python)
+### 0. Setup interactivo (recomendado)
 
 ```bash
 git clone https://github.com/bess-solutions/open-bess-edge.git
 cd open-bess-edge
-make dev                  # install all deps + pre-commit hooks
-cp .env.example .env      # edit with your BESS IP + credentials
-make simulate             # run with built-in hardware simulator
-make health               # verify all subsystems are up
+bash scripts/setup.sh   # 5 preguntas → genera config/.env listo
+```
+
+### 1. Local (Python)
+
+```bash
+make dev                  # instala dependencias + pre-commit hooks
+bash scripts/setup.sh     # genera config/.env
+make simulate             # arranca con simulador integrado
+make health               # verifica que todo está activo
 ```
 
 ### 2. Docker Compose (recommended)
 
 ```bash
 git clone https://github.com/bess-solutions/open-bess-edge.git
 cd open-bess-edge
-cp .env.example .env
-docker compose up -d                        # core gateway
-docker compose --profile monitoring up -d  # + Prometheus + Grafana
+bash scripts/setup.sh     # genera config/.env con parámetros de tu sitio
+docker compose -f infrastructure/docker/docker-compose.yml --profile simulator --profile monitoring up -d
 ```
 
-Grafana → http://localhost:3000 (admin / bessai)  
+Grafana → http://localhost:3000 (credenciales: ver `GF_SECURITY_ADMIN_PASSWORD` en `config/.env`)  
 Metrics → http://localhost:8000/metrics  
 Health  → http://localhost:8000/health
 

docs/CONTRIBUTING_ADOPTERS.md

@@ -0,0 +1,165 @@
+# 🤝 Cómo contribuir como Early Adopter
+
+> Esta guía está dirigida a usuarios que quieren contribuir con su primera mejora al proyecto — sin necesidad de ser expertos en el código interno.
+
+---
+
+## Contribuciones más valoradas por la comunidad
+
+| Tipo | Dificultad | Impacto |
+|------|-----------|---------|
+| ➕ Perfil JSON de nuevo hardware | ⭐ Baja | 🔴 Alto |
+| 🐛 Reportar bug con logs completos | ⭐ Baja | 🔴 Alto |
+| 📝 Mejorar documentación / traducción | ⭐ Baja | 🟡 Medio |
+| 🧪 Escribir test para un caso de borde | ⭐⭐ Media | 🟡 Medio |
+| ✨ Implementar feature de GOOD_FIRST_ISSUES | ⭐⭐ Media | 🔴 Alto |
+| 🏗️ Nuevo conector de mercado (CENACE, REE…) | ⭐⭐⭐ Alta | 🔴 Alto |
+
+---
+
+## Contribución 1 — Perfil de hardware (más común)
+
+Tienes un inversor que no está en `registry/`. En 30 minutos puedes aportarlo.
+
+### Paso 1 — Revisar el formato existente
+
+```bash
+cat registry/huawei_sun2000.json | python3 -m json.tool
+```
+
+La estructura es:
+```json
+{
+  "profile_id": "huawei_sun2000_v1",
+  "manufacturer": "Huawei",
+  "model": "SUN2000",
+  "protocol": "modbus_tcp",
+  "default_port": 502,
+  "default_slave_id": 0,
+  "registers": {
+    "soc_pct":   {"address": 37760, "type": "uint16", "scale": 0.1, "unit": "%"},
+    "power_kw":  {"address": 37113, "type": "int32",  "scale": 0.001, "unit": "kW"},
+    "temp_c":    {"address": 35182, "type": "int16",  "scale": 0.1, "unit": "°C"}
+  }
+}
+```
+
+### Paso 2 — Crear tu perfil
+
+```bash
+cp registry/huawei_sun2000.json registry/mi_inversor_modelo.json
+# Editar con los registros Modbus de tu fabricante
+```
+
+Los tres registros **obligatorios** son `soc_pct`, `power_kw` y `temp_c`. Los demás son opcionales.
+
+### Paso 3 — Validar el perfil
+
+```bash
+make validate-registry
+# Debe pasar sin errores antes de abrir el PR
+```
+
+### Paso 4 — Abrir el PR
+
+```bash
+git checkout -b feat/hardware-profile-FABRICANTE-MODELO
+git add registry/mi_inversor_modelo.json
+git commit -m "feat(registry): add FABRICANTE MODELO profile"
+git push origin feat/hardware-profile-FABRICANTE-MODELO
+```
+
+Luego ve a GitHub y abre el Pull Request. El team lo revisa en ≤ 3 días hábiles.
+
+> **TIP:** Menciona en el PR qué firmware version del inversor usaste para identificar los registros.
+
+---
+
+## Contribución 2 — Reportar un bug
+
+Usa el template de issue en GitHub:  
+→ [Nuevo issue → Bug Report](https://github.com/bess-solutions/open-bess-edge/issues/new?template=bug_report.yml)
+
+Los logs más útiles para el equipo:
+
+```bash
+# Logs del gateway (últimas 50 líneas)
+docker logs bessai-edge 2>&1 | tail -50
+
+# Estado de compliance
+curl http://localhost:8000/compliance/report | python3 -m json.tool
+
+# Versión exacta
+git log --oneline -1
+docker inspect bessai-edge | python3 -c "import sys,json; d=json.load(sys.stdin)[0]; print(d['Config']['Image'])"
+```
+
+---
+
+## Contribución 3 — Mejorar documentación
+
+La documentación está en `docs/` en formato Markdown. Para visualizarla localmente:
+
+```bash
+pip install mkdocs-material
+mkdocs serve   # → http://localhost:8001
+```
+
+Para traducir partes al inglés (el repo está en español/inglés mezclado):
+- Abre un PR con la traducción
+- El team la revisa y la integra
+
+---
+
+## Proceso de revisión — qué esperar
+
+```
+Tu PR abierto
+    │
+    ▼
+CI automático (~5 min)  ← lint, type-check, tests, security scan
+    │
+    ▼
+Revisión del team (~3 días hábiles)
+    │
+    ├── ✅ Aprobado → Merge a main
+    └── 💬 Cambios solicitados → Iterar
+```
+
+### Estándares de calidad obligatorios
+
+- `make lint` debe pasar sin errores
+- `make test` debe pasar (o documentar por qué el test no aplica)
+- Nuevos archivos Python deben tener type hints
+- Commits en formato [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `docs:`, etc.
+
+---
+
+## Primeros issues recomendados para newcomers
+
+Ver [GOOD_FIRST_ISSUES.md](GOOD_FIRST_ISSUES.md) para issues etiquetados con `good-first-issue`.
+
+Los más accesibles actualmente:
+- Agregar un perfil JSON de hardware faltante
+- Mejorar el mensaje de error cuando `MODBUS_HOST` no es accesible
+- Traducir secciones del `ADOPTER_HUB.md` al inglés
+
+---
+
+## Stack técnico de referencia
+
+| Capa | Tecnología |
+|------|-----------|
+| Runtime | Python 3.11+ / asyncio |
+| Protocolo industrial | pymodbus 3.x |
+| API REST | FastAPI + uvicorn |
+| Observabilidad | Prometheus + structlog + OpenTelemetry |
+| IA / ML | ONNX Runtime + scikit-learn |
+| Tests | pytest + pytest-asyncio |
+| Linter | ruff + mypy strict |
+| Contenedores | Docker multi-arch (amd64/arm64) |
+| CI | GitHub Actions |
+
+---
+
+*¿Tienes dudas? [Abre un issue](https://github.com/bess-solutions/open-bess-edge/issues/new?labels=question) o escríbenos a `ingenieria@bess-solutions.cl`.*

docs/tutorials/connecting_real_hardware.md

@@ -154,11 +154,13 @@ Deberías ver valores reales (no el rango simulado 20-95% SOC):
 
 ## Paso 7 — Hardware no soportado
 
-Si tu inversor no está entre los 4 perfiles:
+Si tu inversor no está entre los perfiles existentes:
 
-1. Abre un issue con el template [`hardware_support.yml`](https://github.com/bess-solutions/open-bess-edge/issues/new?template=hardware_support.yml)
-2. Adjunta el Modbus register map del fabricante
-3. Si tienes acceso al inversor, puedes contribuir el perfil JSON y recibir un **bounty** (ver [bounty_program.md](bounty_program.md))
+1. Revisa si ya hay un issue abierto: [buscar en issues con etiqueta `hardware`](https://github.com/bess-solutions/open-bess-edge/issues?q=label%3Ahardware)
+2. Si no existe, abre uno con la etiqueta `hardware` describiendo tu inversor y adjunta el mapa de registros Modbus del fabricante
+3. Si tienes acceso al inversor físico, puedes contribuir el perfil JSON directamente: ver guía [hardware_profile_contribution.md](hardware_profile_contribution.md)
+
+> Las contribuciones de perfiles de hardware son las más valoradas por la comunidad — se mencionan explícitamente en las release notes.
 
 ---
 

mkdocs.yml

@@ -72,6 +72,7 @@ nav:
     - Adopter Hub (empieza aquí): ADOPTER_HUB.md
     - Onboarding Día 0 → 7: ONBOARDING_7DAYS.md
     - FAQ Técnica: FAQ.md
+    - Contribuir (primer PR): CONTRIBUTING_ADOPTERS.md
     - Programa Early Adopters: early_adopters.md
     - Pilot Guide (Chile/CEN): PILOT_GUIDE.md
   - Getting Started: