scaffold: kind+Tilt cluster, api/ui/docs stubs, green at nvi.local.ar

README.md

@@ -0,0 +1,61 @@
+# nvi
+
+Text-to-SQL analytics agent over the BIRD `financial` warehouse (PKDD'99 Czech bank).
+Three-layer Plan / Analyses / Tools architecture, purpose-built runtime, soleprint-ui frontend, Langfuse observability via the sibling `lng` cluster.
+
+## Quick start
+
+Prerequisites: the `lng` Langfuse cluster reachable from this host, and the
+soleprint-ui framework propagated into `ui/framework` (handled by `spr`).
+Set `LANGFUSE_HOST` and the Langfuse keys in `.env` (see `.env.example`).
+
+Two equivalent paths — pick one.
+
+### Primary: kind + Tilt
+
+```bash
+make kind               # create kind-nvi cluster
+make tilt-up            # build images, bring up postgres, api, ui, docs, gateway
+make seed               # load BIRD financial into postgres (runs inside the api pod)
+```
+
+`*.local.ar` resolves via dnsmasq; the system Caddy at
+`~/wdir/ppl/local/Caddyfile` proxies `nvi.local.ar` to the kind NodePort
+(`localhost:8060`). Reload after first install: `sudo systemctl reload caddy`.
+
+Then open `http://nvi.local.ar`.
+
+### Alternative: docker-compose
+
+For when you don't want a k8s cluster running.
+
+```bash
+make compose-up         # build + start (postgres, api, ui, docs)
+make compose-seed       # load BIRD financial (runs inside the api container)
+```
+
+Then open `http://localhost:8060` (ui) or `http://localhost:8000` (api).
+
+### IDE setup (optional)
+
+The app runs entirely in containers; `uv sync` on the host is only useful for
+editor/LSP support. Run `uv sync` yourself if you want a local `.venv`.
+
+## Layout
+
+```
+api/           FastAPI: Plan, Analyses, Tools, runtime
+ui/app/        Vue 3 + soleprint-ui frontend
+ui/framework/  soleprint-ui (managed by spr; gitignored)
+docs/          hand-built HTML + Graphviz SVGs, served via nginx
+seed/          BIRD financial loader
+evals/         BIRD golden-set runner
+ctrl/          Tiltfile, kind config, k8s manifests, Dockerfiles
+def/           external reference notes (gitignored)
+```
+
+## Why this shape
+
+See `docs/` (served at `http://docs.nvi.local.ar:8060` once Tilt is up) and the
+approved plan at
+`~/.claude/plans/context-ref-file-home-mariano-wdir-nvi-floating-dream.md`.