feat(docs): sync knowledge base from remote docs API

[Saul-Gomez-J]

Summary

• Añadir un cliente async (bot/docs_client.py) sobre httpx que consume la API pública de docs publicada por helmcode/nan: GET /api/docs/manifest.json y GET /api/docs/{slug}.md. Verifica sha256 y cachea en disco (DOCS_CACHE_DIR) como fallback si el remoto cae.
• Añadir load_documentation_from_remote() (bot/knowledge.py) que diff-ea por contentHash, solo re-chunks/embeds lo que cambió, elimina sources que ya no están en el manifest y cae a cache → local en cascada.
• Tarea de fondo en bot/base.py que refresca cada DOCS_REFRESH_INTERVAL (suelo 60s), reembedde lo nuevo y expone docs_last_sync + docs_last_sync_ok en /health. El comando !docs ya no lista bot/docs/knowledge/*.md, lista los sources rastreados en el vector store.
• Cold start en main.py bifurcado por DOCS_USE_REMOTE:
  • local (default) — comportamiento actual, sin llamadas remotas.
  • remote — solo remoto, con fallback a local si el remoto y la cache fallan.
  • shadow — sigue cargando local pero también busca el manifest remoto y loguea un diff por slug (local_only / remote_only / changed). Pensado para validar paridad antes del switch.

Por qué

Hasta ahora los .md de bot/docs/knowledge/ vivían en este repo, lo que obligaba a editar dos repos por cada cambio de documentación y dejaba al bot fuera de sync. Con esto, la web es la fuente única y el bot la reindexa por hash.

Notas para revisar

• La rama legacy (bot/docs/knowledge/*.md + load_documentation) se deja intacta: el deploy actual sigue funcionando con DOCS_USE_REMOTE=local. La limpieza de esos .md y de load_documentation será un follow-up cuando validemos remote en prod.
• DocsClient valida el slug con ^[a-z0-9][a-z0-9-]{0,63}$ antes de ir a disco para evitar path traversal en la cache.
• El diff shadow también hace fetch_body de cada entrada para sacar a la luz errores del remoto pronto (no solo el manifest).
• httpx>=0.27 añadido como dependencia nueva en pyproject.toml.

Test plan

• uv sync para resolver httpx.
• Smoke test con la web en local (http://localhost:4321) y DOCS_USE_REMOTE=remote: validar manifest, fetch_body por slug y que los hashes cuadran.
• Modo shadow en staging contra https://nan.builders: revisar los logs Shadow diff: local_only=… remote_only=… changed=… y que no haya fetch fallidos.
• /health devuelve docs_last_sync y docs_last_sync_ok=true después del primer refresh.
• !docs lista los slugs del store y no los archivos locales.
• Simular caída de la API (apagar la web) y comprobar que el fallback a cache funciona; borrar la cache y comprobar el fallback a local.

🤖 Generated with Claude Code

[barckcode]

Muy buen plumbing: cascada remote → cache → local, diff per-slug con re-embed selectivo, modo shadow, escrituras atómicas (tmp.replace(dst)), health endpoint con docs_last_sync_ok, fallback no fatal. La rama legacy intacta es lo correcto.

Tres blockers antes de mergear, y un par de mejoras nice-to-have.

Blockers

1. Enviar If-None-Match y manejar 304

DocsClient.fetch_manifest/fetch_body siempre bajan el body completo aunque haya cache local. Persistir el ETag junto al body cacheado y mandarlo en el siguiente fetch ahorra ancho de banda y aprovecha el shared cache de Cloudflare. Requiere el fix paralelo en helmcode/nan#4 (honrar If-None-Match en el endpoint).

2. El diff de shadow está comparando cosas distintas

main.py:34-37 hashea el .md local entero con frontmatter. El remoto hashea el body sin frontmatter (tras htmlToText, que también se va a eliminar con el cambio del endpoint en helmcode/nan#4). Resultado: el diff marca todo como changed siempre → el modo shadow pierde su valor como gate.

Hay que hashear el texto canónico que va al chunker en ambos lados (mismo algoritmo, mismo input). Después de los cambios de helmcode/nan#4 esto se simplifica porque ambos lados serán markdown plano del mismo origen.

3. Sin tests

Una PR que introduce un cliente HTTP nuevo, un loader con diff por hash, un background refresh y un modo shadow debe ir acompañada de tests. Mínimo:

• _strip_frontmatter: con frontmatter, sin frontmatter, frontmatter malformado.
• _SAFE_SLUG_RE: positivos (api, getting-started) y negativos (../etc/passwd, Foo, vacío, >64 chars).
• DocsClient.fetch_manifest/fetch_body: mock httpx → manifest válido, manifest con entry inválido (filtrado), body con hash mismatch → warning pero no aborta, fallback a cache cuando 5xx.
• load_documentation_from_remote: diff (unchanged skip, changed re-embed, removed cleanup), cascada remote → cache → local.

Nice-to-have (no bloqueantes)

• Race window en refresh: _refresh_docs_once muta store._chunks mientras on_message lee con store.search. Asyncio single-thread lo salva, pero hay varios await en medio del refresh. Un asyncio.Lock por refresh deja las invariantes claras.
• SQLite _conn: añadir check_same_thread=False por si más adelante algo toca otro thread.
• settings.docs_use_remote: str sin validar: DOCS_USE_REMOTE=Remote cae a local silenciosamente. Literal["local","remote","shadow"] con pydantic.
• DocsClient sin retry/backoff: un 5xx transitorio = 15 min sin sync. httpx.AsyncHTTPTransport(retries=3) lo cubre.
• Manifest.version podría usarse como short-circuit (si no cambió, no iteres entries), pero requiere que en helmcode/nan#4 ese version sea estable.
• Eliminar la doble serialización frontmatter (el endpoint lo añade, _strip_frontmatter lo quita) cuando se haga el cambio en helmcode/nan#4.