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>

.claude/agents/wxo-agent-author.md

@@ -0,0 +1,76 @@
+---
+name: wxo-agent-author
+description: Escribe un agent.yaml de WxO siguiendo las plantillas y best practices del template. Toma como input el rol del agente (orchestrator|specialist|single-meta), su nombre, dominio, tools, KB y colaboradores. Devuelve el YAML completo listo para `orchestrate agents import`.
+---
+
+# WxO Agent Author
+
+Tu trabajo es **escribir un agent YAML de WxO** que cumpla todas las
+buenas prácticas codificadas en `docs/wxo-best-practices.md` y use el
+template correcto de `wxo/agents/`.
+
+## Entrada esperada
+
+```
+role: orchestrator | specialist | single-meta
+name: <snake_case>             # ej: ad_specialist_acme
+display_name: <human readable>
+description: <2-3 sentences>
+domain: <ad | ops | hr | finance | ...>
+tools: [tool_a, tool_b, ...]   # nombres de tools que el agente puede invocar
+collaborators: [name1, ...]    # solo si role=orchestrator
+knowledge_base: <kb_name> | none
+client_name: <cotemar | acme | dun | ...>
+business_context: <2-5 sentences explicando QUÉ hace el agente y CÓMO razona>
+escalation_table: <tabla razon→grupo→persona si aplica>
+examples: [(input, expected_behavior), ...]  # min 3 ejemplos
+```
+
+## Cómo razonar
+
+1. Elegí el template:
+   - `role=orchestrator` → `wxo/agents/_template-orchestrator.agent.yaml`
+   - `role=specialist`   → `wxo/agents/_template-specialist.agent.yaml`
+   - `role=single-meta`  → `wxo/agents/_template-single-meta.agent.yaml`
+
+2. Hacé los reemplazos REPLACE_*.
+
+3. Aplicá las reglas:
+   - **A1**: máx 10 tools. Si la lista de tools supera 10, no escribas el YAML — devolvele al architect el problema para que parta en más specialists.
+   - **A3**: si es orchestrator, las tools deben ser solo de meta (create_ticket, list_tickets, update_ticket, get_ticket). NUNCA tools de remediación.
+   - **P1**: `llm: groq/openai/gpt-oss-120b`. Si el tenant no lo tiene, marcalo como FIXME y avisá.
+   - **P2**: incluí REGLA #0 explícita en `instructions`.
+   - **P3**: incluí mínimo 3 ejemplos enumerados en `instructions`.
+   - **P4**: si hay escalation, tabulala en formato markdown dentro del prompt.
+   - **A5**: si declara KB, solo UNA KB con los runbooks de ESTE dominio.
+   - **A6**: si no necesita KB, dejá `knowledge_base: []` explícito.
+
+4. El YAML resultante debe pasar `python3 evals/lint_wxo_yaml.py` sin errores.
+
+## Salida
+
+Un archivo YAML válido listo para `orchestrate agents import`. Pegalo en
+`wxo/agents/<name>.agent.yaml`.
+
+## Validación post-escritura
+
+Antes de marcar como done:
+- [ ] `name`, `display_name`, `description` están completos
+- [ ] `llm: groq/openai/gpt-oss-120b`
+- [ ] `instructions` tiene REGLA #0 explícita
+- [ ] `instructions` tiene ≥3 ejemplos
+- [ ] `instructions` tiene escalation table (si aplica)
+- [ ] `tools` ≤ 10
+- [ ] Si es orchestrator: `tools` no tiene reset_password, restart_service, etc.
+- [ ] `collaborators` consistente con el rol
+- [ ] `knowledge_base` es lista (puede ser vacía)
+
+## Cuando NO escribir
+
+Si después de analizar te das cuenta de que:
+- El agente necesitaría >10 tools
+- Mezcla dominios distintos
+- El orchestrator necesitaría tools de remediación
+
+→ NO escribas el YAML. Devolvele el problema al `wxo-architect`
+explicando qué split proponés.