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>

README.md

@@ -0,0 +1,112 @@
+# fit-boilerplate-wox
+
+**Boilerplate FactorIT** para construir soluciones agénticas sobre **IBM watsonx Orchestrate (ADK 2.x)** con una capa web encima.
+
+Este repositorio es el punto de partida canónico para cualquier solución estilo `cotemar-poc-n1` o `dun-casos-prueba`: trae estructura, plantillas, scripts, documentación y subagentes Claude pre-configurados para que vos arranques con un cliente nuevo en **minutos, no días**.
+
+---
+
+## ¿Qué hay acá?
+
+| Pieza | Para qué sirve |
+|---|---|
+| `wxo/` | Plantillas de agentes, conexiones, tools (Python/OpenAPI/MCP) y KBs |
+| `web/_default_fastapi_htmx/` | Capa web por defecto (FastAPI + HTMX + Jinja). Swap por React/Next/etc. si el caso lo pide |
+| `mocks/_example_mock/` | Ejemplo de mock externo (FastAPI con healthcheck correcto para Coolify/Traefik) |
+| `scripts/` | Deploy idempotente, undeploy, evals, smoke test, scaffolding de specialists |
+| `evals/` | Linter de buenas prácticas + scenarios + smoke tests + runner |
+| `docs/` | Cheatsheet ADK 2.x, best practices, deployment guide, runbook, known issues |
+| `.claude/agents/` | 7 subagentes Claude (architect, agent-author, tool-author, etc.) |
+| `.gitea/workflows/ci.yml` | CI con lint + evals |
+
+---
+
+## Quick start
+
+```bash
+# 1. Clonar
+git clone https://gitea.fitlabs.dev/farentsen/fit-boilerplate-wox.git mi-cliente
+cd mi-cliente
+rm -rf .git && git init
+
+# 2. Conversar con Claude usando el skill fit-wxo-bootstrap
+#    (instalalo primero en ~/.claude/skills/ — ver más abajo)
+#    El skill te pregunta qué construís, decide la topología, y dispara
+#    subagentes Claude en paralelo para escribir agentes/tools/runbooks/evals.
+
+# 3. Revisar lo que generó la skill, ajustar, y desplegar:
+./scripts/check-adk-version.sh
+./scripts/deploy-wxo.sh
+```
+
+---
+
+## Skill `fit-wxo-bootstrap`
+
+Bajo `skill/fit-wxo-bootstrap/` hay un skill bundle listo para instalar:
+
+```bash
+cp -r skill/fit-wxo-bootstrap ~/.claude/skills/
+```
+
+Reinicia Claude Code y el skill queda disponible. Invocalo con:
+
+> "Quiero arrancar una solución WxO nueva para [cliente/caso de uso]"
+
+La skill te lleva por las decisiones de arquitectura y delega la escritura a subagentes Claude que corren en paralelo.
+
+---
+
+## Filosofía del template
+
+1. **WxO es el motor multi-agéntico fijo. Todo lo demás es swap-able.**
+   El stack web (FastAPI+HTMX, Next, Remix, lo que sea) puede cambiar según el caso. WxO no.
+
+2. **Buenas prácticas se enforcean, no se sugieren.**
+   `evals/lint_wxo_yaml.py` falla el CI si:
+   - Algún agente tiene >10 tools
+   - El orchestrator declara tools de remediación (`reset_password`, `restart_service`, etc.)
+   - Un agente con `style: react` no tiene KB ni tools (sin propósito)
+   - Una tool no usa el decorator `@observable_tool`
+   - Falta el `_compat.py` inline
+   - Algún `docker-compose.yml` usa `wget --spider`
+   - Algún OpenAPI no tiene `description` per-operation
+   - Algún schema Pydantic de tool no tiene `@field_validator(mode="before")`
+
+3. **Cada tool es observable por defecto.**
+   El decorator `@observable_tool` emite trazas estructuradas (inputs, outputs, latency, side effects, observed state). El web layer las consume y las muestra en una vista timeline. Las evals las usan para validar que el agente llamó las tools correctas en el orden correcto.
+
+4. **Cuatro tipos de agente, no uno.** Procedural (con runbook KB), API-driven (sin KB, todos OpenAPI), MCP-driven (sin KB, herramientas vía MCP server), híbrido.
+
+5. **Dos modos de tool wrapper.**
+   - **Mock externo** (estilo cotemar): Python `@tool` que llama HTTP a un mock separado
+   - **Backend integrado** (estilo dun): tu propio backend FastAPI expone un OpenAPI filtrado que WxO importa directamente. Más rápido para producción real.
+
+---
+
+## Documentación
+
+| Doc | Propósito |
+|---|---|
+| [`docs/INDEX.md`](docs/INDEX.md) | Doc de docs — empezá acá |
+| [`docs/adk-2x-cheatsheet.md`](docs/adk-2x-cheatsheet.md) | Comandos ADK 2.x + YAML schemas + gotchas |
+| [`docs/wxo-best-practices.md`](docs/wxo-best-practices.md) | Las 30+ reglas codificadas, con el "por qué" |
+| [`docs/architecture-patterns.md`](docs/architecture-patterns.md) | Árbol de decisión: ¿1 agente o N? ¿KB o no? ¿OpenAPI o Python? |
+| [`docs/observability-pattern.md`](docs/observability-pattern.md) | El contrato `@observable_tool` + `write_audit` |
+| [`docs/tool-authoring-guide.md`](docs/tool-authoring-guide.md) | Python vs OpenAPI vs MCP — cuándo usar cuál |
+| [`docs/deployment-guide.md`](docs/deployment-guide.md) | Deploy genérico (parametrizable a cualquier tenant) |
+| [`docs/DEPLOY_TO_NEW_WOX.md`](docs/DEPLOY_TO_NEW_WOX.md) | Cold start playbook (provision → secrets → backend → wox → smoke test) |
+| [`docs/RUNBOOK.md`](docs/RUNBOOK.md) | Operación: URLs, monitoring, recovery, rotation, troubleshooting |
+| [`docs/known-issues.md`](docs/known-issues.md) | Errores reales con su fix (recursion_limit, llama bug, Coolify Traefik, etc.) |
+| [`docs/eval-strategy.md`](docs/eval-strategy.md) | 4 capas de eval: nativa, agente, runbook, web |
+| [`INSTRUCCIONES.md`](INSTRUCCIONES.md) | Quickstart de 5 pasos |
+
+---
+
+## Origen
+
+Destilado de dos PoCs reales de FIT México:
+- [`cotemar-poc-n1`](https://gitea.fitlabs.dev/farentsen/cotemar-poc-mesa-n1) — Mesa N1 multi-agente (1 orquestador + 3 specialists) con runbooks + KBs + mocks
+- [`dun-casos-prueba`](https://gitea.fitlabs.dev/farentsen/dun-casos-prueba) — QA Studio con OpenAPI integrado + audit_logs + webhook HMAC + meta-tool
+
+Cada lección aprendida en esos dos repos vive acá como código, plantilla o validador de CI.