feat: v1 — boilerplate WxO + web

Boilerplate completo para construir soluciones agénticas sobre IBM
watsonx Orchestrate (ADK 2.x) con una capa web encima.

Destilado de cotemar-poc-n1 y dun-casos-prueba. Incluye:

- 11 docs (best practices, architecture patterns, ADK cheatsheet,
  observability, tool authoring, deployment, RUNBOOK, DEPLOY_TO_NEW_WOX,
  known-issues con 16 errores reales y fix, eval strategy, INDEX)
- 13 templates WxO (orchestrator/specialist/single-meta agents,
  3 connections, KB + runbook, observable_tool decorator, coercion
  helpers, Python tools, OpenAPI spec, backend filter endpoint, webhook
  validator HMAC, MCP connection)
- 6 scripts (deploy idempotente con fallback ADK, undeploy, reset,
  check-adk-version, new-specialist scaffold, eval-agents runner)
- 4 eval pieces (linter de best practices, runner, smoke-test, direct
  backend probe) + scenario templates
- 8 subagentes Claude (.claude/agents/) — wxo-architect, wxo-agent-author,
  wxo-tool-author, runbook-author, mock-builder, backend-tool-builder,
  eval-author, web-layer-builder
- Skill bundle fit-wxo-bootstrap/ (SKILL.md + 3 templates) listo para
  copiar a ~/.claude/skills/
- Web layer default FastAPI+HTMX con vista timeline observable + endpoint
  receptor de trazas
- Docker compose Coolify-ready (healthcheck wget -qO-, sin labels Traefik,
  network split internal:true)
- CI Gitea workflow con lint + smoke

Best practices enforced por evals/lint_wxo_yaml.py:
- A1: máx 10 tools por agente
- A3: orchestrator sin tools de remediación
- A6: agente sin propósito (react sin tools ni KB)
- T1: @observable_tool obligatorio, no @tool directo
- T3: _compat shim inline en tools.py
- D1: docker-compose sin wget --spider
- I-005: OpenAPI con description per-operation
- I-009: sin labels Traefik manuales

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/DEPLOY_TO_NEW_WOX.md

@@ -0,0 +1,218 @@
+# Deploy to a New WxO Tenant — Cold Start Playbook
+
+Cuando arrancás esta solución en un tenant WxO **completamente nuevo**
+(otro cliente, otro environment, fresh start), seguí este playbook
+literal. Es el camino más corto desde "tengo credenciales" a "demo
+funcionando".
+
+---
+
+## Step 0 — Pre-requisitos
+
+- [ ] IBM Cloud account del cliente con WxO instance provisionada
+- [ ] API key del tenant
+- [ ] Coolify (u otro host Docker) accesible
+- [ ] Dominio público con DNS apuntando al host
+- [ ] Acceso a Gitea/repo para clonar el código
+
+---
+
+## Step 1 — Provisionar el ADK localmente
+
+```bash
+python3.12 -m venv .venv-wxo
+source .venv-wxo/bin/activate
+pip install --upgrade "ibm-watsonx-orchestrate==2.1.0"
+orchestrate --version    # 2.1.x
+```
+
+Verificá que el modelo esté disponible:
+
+```bash
+orchestrate env add -n nuevo-tenant \
+  --iam-url https://iam.cloud.ibm.com/identity/token \
+  -u "$ORCHESTRATE_API_URL"
+orchestrate env activate nuevo-tenant
+
+orchestrate models list | grep gpt-oss-120b
+```
+
+Si no aparece `gpt-oss-120b`, editá los YAMLs en `wxo/agents/` y poné
+`meta-llama/llama-3-3-70b-instruct` (con la advertencia de I-002).
+
+---
+
+## Step 2 — Secretos
+
+Crear `.env` desde `.env.example`:
+
+```bash
+cp .env.example .env
+nano .env
+```
+
+Llenar:
+- `ORCHESTRATE_API_URL`
+- `ORCHESTRATE_API_KEY`
+- `WATSONX_API_KEY` (si vas a usar Plan A)
+- `PUBLIC_HOST`
+- (Coolify) `COOLIFY_API_URL`, `COOLIFY_API_TOKEN`
+
+---
+
+## Step 3 — Deploy del backend / mocks
+
+Si tu solución incluye un backend propio o mocks:
+
+```bash
+# Coolify: crear app desde el git repo, configurar env vars, deploy
+# O localmente:
+docker compose up -d --build
+```
+
+Verificá que el `PUBLIC_HOST/health` responde 200:
+
+```bash
+curl -sf "https://$PUBLIC_HOST/health"
+```
+
+Si da 503 → Traefik exclude por healthcheck. Issue I-008.
+Si da default cert → labels manuales en compose. Issue I-009.
+
+---
+
+## Step 4 — Deploy del stack WxO
+
+```bash
+PUBLIC_HOST=mi-cliente.fitlabs.dev ./scripts/deploy-wxo.sh
+```
+
+El script:
+1. Crea las connections (draft + live)
+2. Importa los tools
+3. Importa las KBs
+4. Importa los agentes en orden (specialists primero)
+5. Hace `deploy --env live` de cada uno
+6. Crea el canal webchat
+
+Si falla a mitad de camino:
+- Re-corré el script (es idempotente)
+- Si persiste, ver `docs/known-issues.md`
+
+---
+
+## Step 5 — Capturar IDs
+
+```bash
+orchestrate agents list
+```
+
+Buscá tu orchestrator en el env `live`, capturá:
+- `agent_id` (UUID)
+- `environment_id` (UUID)
+
+Ponelos en:
+- `web/.../templates/index.html` (o donde esté tu landing): `agentId` y `agentEnvironmentId`
+- `.env`: `WXO_AGENT_ID`
+- Coolify panel: `WXO_AGENT_ID` env var
+
+Commit + redeploy de la landing.
+
+---
+
+## Step 6 — Embed Security OFF (manual, UI)
+
+**Esto es manual. No hay API.**
+
+1. WxO Console → Settings
+2. Embed Security → **Off**
+3. Confirmar
+
+Sin esto, el widget de chat queda en "Cargando..." para siempre.
+Issue I-007.
+
+---
+
+## Step 7 — Smoke test
+
+```bash
+./evals/smoke-test.sh
+```
+
+Si pasa, validá manualmente:
+
+```bash
+# Abrir el chat
+open "https://$PUBLIC_HOST/"
+```
+
+Tirale al chat tu primer scenario. Verifica que:
+1. El agente responde
+2. El tool se llama (mirá `docker logs <web>` para ver las trazas)
+3. El resultado final aparece en la UI (kanban / control plane / lo que sea)
+
+---
+
+## Step 8 — Direct backend probe (diagnóstico)
+
+Si el chat funciona pero ves errores, ejecutá:
+
+```bash
+./evals/direct-backend-probe.sh
+```
+
+Esto llama tu backend directamente con curl + el token de WxO. Sirve
+para aislar:
+- **200 OK con error de lógica** → el backend está bien, el problema
+  está en la conversación con el agente
+- **401/403** → problema de auth / connection / credentials
+- **502/504** → problema de red entre WxO y tu backend (firewall, DNS,
+  Cloud Run cold start, etc.)
+
+---
+
+## Step 9 — Activar Plan A (webhook → Runs API)
+
+Si tu solución tiene auto-trigger desde un sistema externo:
+
+1. Capturá el `WXO_AGENT_ID` (paso 5)
+2. Asegurate que `WATSONX_API_KEY` está en `.env`
+3. Re-deployá el backend/mocks (`docker compose up -d --force-recreate`)
+4. Probá disparando un evento desde el sistema externo
+5. Mirá los logs: debería ver `→ POST /v1/orchestrate/runs ... 200`
+
+Issue I-011 si los env vars no se actualizan: `restart` no relee `.env`,
+usar `--force-recreate`.
+
+---
+
+## Step 10 — Set up monitoring básico
+
+- Coolify alerta por email si el container reinicia >3 veces en 5 min
+- Healthcheck endpoint custom si necesitás
+- Logs accesibles desde Coolify panel
+- `./evals/smoke-test.sh` corriendo nightly desde CI
+
+---
+
+## Checklist final
+
+- [ ] Step 0 — Pre-reqs listos
+- [ ] Step 1 — ADK provisionado + modelo disponible
+- [ ] Step 2 — `.env` completo
+- [ ] Step 3 — Backend/mocks responden 200 en /health
+- [ ] Step 4 — `./scripts/deploy-wxo.sh` sin errores
+- [ ] Step 5 — IDs capturados y propagados
+- [ ] Step 6 — Embed Security OFF
+- [ ] Step 7 — Smoke test pasa
+- [ ] Step 8 — Direct probe responde 200
+- [ ] Step 9 — (si aplica) Plan A funciona
+- [ ] Step 10 — Monitoring básico
+
+Cuando los 10 estén ✅, estás listo para demo.
+
+---
+
+## Si algo se rompió en producción
+
+Ver `docs/RUNBOOK.md` para recovery procedures.