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>

mocks/_example_mock/Dockerfile

@@ -0,0 +1,16 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+COPY mocks/_example_mock/requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY mocks/_example_mock/app/ ./app/
+
+EXPOSE 8000
+
+# Healthcheck con `wget -qO-` (issue I-008)
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+  CMD wget -qO- http://localhost:8000/health || exit 1
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

mocks/_example_mock/app/main.py

@@ -0,0 +1,135 @@
+"""Mock de ejemplo. Replicá esta estructura para tu mock real.
+
+Patrones aplicados:
+- /health endpoint (Coolify/Traefik)
+- /admin/reset endpoint (para rehearsals)
+- Pydantic con coerción de tipos (issue I-003)
+- Custom auth header X-Orchestrate-Token (regla C2)
+- Logs estructurados como JSON
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from typing import Optional
+
+from fastapi import FastAPI, Header, HTTPException
+from pydantic import BaseModel, field_validator
+
+
+# ─── Helpers de coerción (issue I-003) ──────────────────────────────────────
+
+def _coerce_int(v):
+    if isinstance(v, str) and v.strip().lstrip("-").isdigit():
+        return int(v)
+    return v
+
+
+def _coerce_list(v):
+    if isinstance(v, str):
+        try:
+            return json.loads(v)
+        except Exception:
+            return [v]
+    return v
+
+
+# ─── Seed data ──────────────────────────────────────────────────────────────
+
+SEED = {
+    "users": [
+        {"username": "juan.perez", "email": "juan.perez@example.com", "active": True, "department": "Finanzas"},
+        {"username": "maria.lopez", "email": "maria.lopez@example.com", "active": True, "department": "Operaciones"},
+        {"username": "ana.torres", "email": "ana.torres@example.com", "active": False, "department": "RRHH"},
+    ],
+}
+
+state: dict = {}
+
+
+def _reset():
+    global state
+    state = {"users": [u.copy() for u in SEED["users"]]}
+
+
+_reset()
+
+
+# ─── Models ─────────────────────────────────────────────────────────────────
+
+class LookupInput(BaseModel):
+    username: str
+
+
+class ExecuteInput(BaseModel):
+    target_id: int
+    options: list[str] = []
+    notify: bool = True
+    _coerce_id = field_validator("target_id", mode="before")(_coerce_int)
+    _coerce_opts = field_validator("options", mode="before")(_coerce_list)
+
+
+# ─── App ────────────────────────────────────────────────────────────────────
+
+app = FastAPI(title="Example Mock")
+
+
+def _log(event: str, **kwargs):
+    """Structured log for Coolify aggregation."""
+    payload = {"ts": datetime.now(timezone.utc).isoformat(), "event": event, **kwargs}
+    print(json.dumps(payload), file=sys.stdout, flush=True)
+
+
+def _check_token(token: Optional[str]):
+    expected = os.environ.get("MOCK_API_TOKEN")
+    if expected and token != expected:
+        raise HTTPException(status_code=401, detail="bad token")
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok"}
+
+
+@app.post("/admin/reset")
+def admin_reset():
+    """Para rehearsals: vuelve al seed."""
+    _reset()
+    _log("admin.reset")
+    return {"reset": True}
+
+
+@app.post(
+    "/users/lookup",
+    description="Busca un usuario por username. Devuelve datos del usuario."
+)
+def lookup_user(
+    payload: LookupInput,
+    x_orchestrate_token: str | None = Header(default=None),
+):
+    """Lookup de usuario — para que el agente decida si actuar."""
+    _check_token(x_orchestrate_token)
+    user = next((u for u in state["users"] if u["username"] == payload.username), None)
+    if not user:
+        raise HTTPException(status_code=404, detail="user not found")
+    _log("tool.lookup_user", username=payload.username, found=True)
+    return user
+
+
+@app.post(
+    "/execute",
+    description="Ejecuta una acción sobre un target_id. Devuelve resultado."
+)
+def execute_action(
+    payload: ExecuteInput,
+    x_orchestrate_token: str | None = Header(default=None),
+):
+    _check_token(x_orchestrate_token)
+    _log("tool.execute", target_id=payload.target_id, options=payload.options)
+    return {
+        "ok": True,
+        "target_id": payload.target_id,
+        "completed_at": datetime.now(timezone.utc).isoformat(),
+    }

mocks/_example_mock/requirements.txt

@@ -0,0 +1,3 @@
+fastapi>=0.110.0
+uvicorn[standard]>=0.27.0
+pydantic>=2.5.0