Grounding hardening, live-hazard tools, agentic deliverables + trace

.gitignore

@@ -75,6 +75,11 @@ yarn-error.log*
 .idea/
 *.swp
 
+# --- Agent tooling scratch ---
+# Per-session metrics written by claude-flow hooks. Machine-local, no bearing
+# on the build; six of these were tracked by accident before this rule.
+.claude-flow/
+
 # --- Vercel ---
 # Added by `vercel link`, which also appends a bare `.env*`. That pattern is
 # kept narrower here: it sits after the `!.env.example` negation above and would

README.md

@@ -24,7 +24,11 @@ facts memorized into model weights.
 - **Evaluated by an independent judge.** A held-out set of 26 domain
   scenarios (`petri/seeds/humanitarian_test_scenarios.json`) is graded by a
   model from a different family than the one being tested, against explicit
-  expected facts — not a self-graded, keyword-ratio heuristic. See
+  expected facts — not a self-graded, keyword-ratio heuristic. Current
+  published baseline: **1 of 26 scenarios passing (4%)**, published as-is —
+  the suite is a regression instrument, not a trophy (see
+  [`docs/STRATEGY.md`](docs/STRATEGY.md#what-the-evals-are-for) and the full
+  reports in [`evals/reports/`](evals/reports/)). See
   [`evals/README.md`](evals/README.md).
 
 ![HAI chat, empty state](docs/assets/chat-empty-en.png)
@@ -33,13 +37,13 @@ facts memorized into model weights.
 
 ```mermaid
 flowchart LR
-    UI["Next.js UI\n(chat, playbooks, guides)"] --> API["/api/chat\nAI SDK v7"]
-    API --> Safety["Safety layer\nPII interception"]
-    Safety --> LLM["Local Ollama\nqwen2.5:14b\n(swappable via env)"]
-    LLM --> T1["search_standards\nSupabase pgvector\nhybrid search"]
-    LLM --> T2["crisis_updates\nIFRC GO / ReliefWeb"]
-    LLM --> T3["humanitarian_data\nHDX HAPI"]
-    LLM --> I18n["i18n: EN / FR / AR / ES\n(RTL for Arabic)"]
+    UI["Next.js UI<br/>(chat, playbooks, guides)<br/>i18n: EN / FR / AR / ES"] --> API["/api/chat<br/>AI SDK v7"]
+    API --> Safety["Safety layer<br/>PII interception"]
+    Safety --> LLM["Local Ollama<br/>qwen2.5:14b<br/>(swappable via env)"]
+    LLM --> T1["search_standards<br/>Supabase pgvector<br/>hybrid search"]
+    LLM --> T2["crisis_updates<br/>IFRC GO / ReliefWeb"]
+    LLM --> T3["humanitarian_data<br/>HDX HAPI"]
+    LLM --> T4["hazards_context<br/>USGS / GDACS<br/>World Bank / OCHA HPC"]
 ```
 
 - **UI**: Next.js app (`app/`) — chat, six role playbooks, three guides, and
@@ -65,6 +69,11 @@ flowchart LR
   - `humanitarian_data` — structured country indicators from **HDX HAPI**
     (population, food security, funding, humanitarian needs). No key
     required.
+  - `hazards_context` — live hazard and context signals aggregated from four
+    keyless sources: **USGS** (earthquakes), **GDACS** (multi-hazard alerts),
+    **World Bank** (country indicators) and **OCHA HPC** (response plans and
+    funding). Each source degrades its own section rather than failing the
+    whole answer.
 - **i18n**: UI chrome in English, French, Arabic, Spanish, with RTL layout
   for Arabic. The model answers in whatever language the user writes in,
   independent of the UI locale.

app/.env.example

@@ -26,6 +26,27 @@ LLM_BASE_URL=http://localhost:11434/v1
 LLM_MODEL=qwen2.5:14b
 LLM_API_KEY=ollama
 
+# Optional. The model /api/deliverables uses; defaults to LLM_MODEL.
+#
+# Worth setting on a hosted deployment, because Groq's token buckets are per
+# model — both the per-minute one and the per-day one. Verified against the
+# deployed key: qwen/qwen3.8-27b and openai/gpt-oss-120b each reported their own
+# independent 8,000 tokens/minute and decremented separately.
+#
+# A situation brief costs roughly 25,000 tokens against a 200,000/day ceiling,
+# so sharing one model with chat means a busy chat afternoon quietly consumes
+# the ability to produce a document. Pointing deliverables at a second model
+# gives the two features independent daily budgets on the same key.
+#
+#   LLM_DELIVERABLES_MODEL=openai/gpt-oss-120b   # hosted demo's value
+LLM_DELIVERABLES_MODEL=
+
+# Optional. Only if deliverables should use a different provider entirely
+# rather than a second model on the same one. Each falls back to its LLM_*
+# equivalent.
+LLM_DELIVERABLES_BASE_URL=
+LLM_DELIVERABLES_API_KEY=
+
 # IMPORTANT for local Ollama: the 4096-token default context is too small for
 # HAI, and overflowing it silently drops the system prompt — after which the
 # model loses its grounding and language rules mid-answer. Either build the
@@ -82,8 +103,30 @@ HDX_APP_IDENTIFIER=
 # RATE_LIMIT_RPM paces one client: a per-IP sliding window, default 20/min. It
 # lives in process memory, so on Vercel each serverless instance keeps its own
 # copy and it resets on every deploy — a politeness control, not a spend control.
+#
+# It governs /api/chat only. /api/deliverables keeps its own, much tighter
+# counter (3 runs per 10 minutes, not configurable), because one run is about
+# nineteen model calls rather than one.
 RATE_LIMIT_RPM=
 
+# LLM_TOKENS_PER_MINUTE no longer needs setting on an ordinary hosted
+# deployment, and its meaning has narrowed.
+#
+# /api/deliverables now reads x-ratelimit-* off every response (see
+# src/lib/llm/rate-limit.ts) and paces against the endpoint's own numbers rather
+# than a configured guess, so Groq's free tier and a paid tier are both paced
+# correctly with no configuration. Pacing switches itself on when an endpoint
+# reports a ceiling and stays off when none is reported — a local Ollama is
+# never paced, and no URL check decides that.
+#
+# What this variable is for now is the endpoint that enforces a ceiling but does
+# not report it in headers: set it to that ceiling in tokens per minute. A
+# reported limit always wins over it. Leave it unset otherwise.
+#
+# Only the deliverables engine reads it; chat is one call at a time and never
+# approaches the limit.
+LLM_TOKENS_PER_MINUTE=
+
 # MAX_DAILY_REQUESTS is the spend control: one shared counter in Postgres,
 # default 500/day across the whole deployment, enforced atomically so concurrent
 # instances cannot overshoot it. Requires the daily_request_cap migration.

app/README.md

@@ -9,8 +9,8 @@ This file covers just this package.
 
 | Path | What's in it |
 |---|---|
-| `src/app/` | Routes — chat (`/`), playbooks, guides, `/api/chat` |
-| `src/lib/tools/` | The three tools the model calls: `search-standards.ts`, `crisis-updates.ts` (IFRC GO / ReliefWeb), `humanitarian-data.ts` (HDX HAPI) |
+| `src/app/` | Routes — chat (`/`), playbooks, guides, `/about`, `/deliverables`, `/api/chat`, `/api/deliverables` |
+| `src/lib/tools/` | The four tools the model calls: `search-standards.ts`, `crisis-updates.ts` (IFRC GO / ReliefWeb), `humanitarian-data.ts` (HDX HAPI), `hazards-context.ts` (USGS / GDACS / World Bank / OCHA HPC) |
 | `src/lib/retrieval/` | `search.ts` — embeds the query via Ollama and calls the `search_standards_hybrid` Supabase RPC |
 | `src/lib/safety/` | `pii.ts` (deterministic regex/heuristic screening), `llm-screen.ts` (optional second-pass), `intercept.ts` (turns findings into the banner copy) |
 | `src/lib/prompts/` | `system.ts` (base system prompt), `coach.ts` (coach-mode addition) |

app/package.json

@@ -1,7 +1,14 @@
 {
-  "name": "app",
+  "name": "hai-app",
   "version": "0.1.0",
   "private": true,
+  "description": "The HAI Next.js application: chat, role playbooks, guides and the deliverables engine. Built from the repository root — see the root package.json for why.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/samfrons/HAI.git",
+    "directory": "app"
+  },
   "scripts": {
     "dev": "next dev",
     "build": "next build",
@@ -15,6 +22,7 @@
     "@ai-sdk/react": "^4.0.82",
     "@supabase/supabase-js": "^2.58.0",
     "ai": "^7.0.79",
+    "fast-xml-parser": "^5.11.1",
     "gray-matter": "^4.0.3",
     "next": "16.3.2",
     "react": "19.2.8",