sync main snapshot for HF Space

.dockerignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+.git
+.idea
+backend/.venv
+backend/__pycache__

.env.example

@@ -0,0 +1,4 @@
+NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
+NEXT_PUBLIC_VERCEL_API_BASE=/api
+NEXT_PUBLIC_ENABLE_SOURCE_LOGIC=false
+NEXT_PUBLIC_MAPBOX_TOKEN=

.gitignore

@@ -0,0 +1,16 @@
+node_modules
+dist
+.next
+tsconfig.tsbuildinfo
+.env
+.env.local
+.env.*.local
+__pycache__
+.pytest_cache
+.venv
+backend/.venv
+
+# Training checkpoints (binary files)
+backend/tmp-training-run/
+backend/tmp-*/
+/tmp/smoke-test*

.idea/.gitignore

@@ -0,0 +1,10 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Ignored default folder with query files
+/queries/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml
+# Editor-based HTTP Client requests
+/httpRequests/

.idea/misc.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Black">
+    <option name="sdkName" value="uv" />
+  </component>
+  <component name="ProjectRootManager" version="2" project-jdk-name="openjdk-25" project-jdk-type="JavaSDK">
+    <output url="file://$PROJECT_DIR$/out" />
+  </component>
+</project>

.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/trenches.iml" filepath="$PROJECT_DIR$/.idea/trenches.iml" />
+    </modules>
+  </component>
+</project>

.idea/swift-toolchain.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="SwiftToolchain">
+    <option name="toolchain" value="system-/usr/bin/swift" />
+  </component>
+</project>

.idea/trenches.iml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="JAVA_MODULE" version="4">
+  <component name="NewModuleRootManager" inherit-compiler-output="true">
+    <exclude-output />
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="jdk" jdkName="uv" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

BACKEND_SUMMARY.md

@@ -0,0 +1,524 @@
+# Backend Summary
+
+This is the backend handoff for the frontend team.
+
+## Plain-English State Model
+
+There are five different layers of state:
+
+1. `world.latent_state`
+   Backend truth. Rewards and simulation logic use this.
+
+2. `world.latent_events`
+   Canonical hidden event chain. News, actions, asset damage, and oversight now create or update these events.
+
+3. `world.actor_state`
+   Lagged/public summary of the world.
+
+4. `observations[agent_id]`
+   What each entity actually sees. This can be partial, delayed, contradictory, and low-confidence.
+
+5. `belief_state[agent_id]`
+   What each entity currently believes across turns. This is persistent memory, not just the current observation. It now uses doctrine-specific priors, slow false-belief decay, and contradiction-driven revision.
+
+The frontend should not treat those layers as interchangeable.
+
+## Real Model Behavior
+
+Each entity has a `model_bindings[agent_id]` object.
+
+That tells you:
+
+- which provider is configured
+- which model is configured
+- whether the binding is ready for inference
+- which tools/actions the entity is allowed to use
+- whether the entity is currently on real provider execution or heuristic fallback
+
+Current behavior:
+
+- if a provider binding is ready, the backend tries real provider inference first
+- if that fails or returns an invalid action, the backend falls back explicitly to heuristic policy
+- action metadata records whether the action came from `provider_inference` or `heuristic_fallback`
+
+Supported provider names now include:
+
+- `openai`
+- `anthropic`
+- `openrouter`
+- `huggingface`
+- `ollama`
+- `vllm`
+- `custom`
+
+Hugging Face notes:
+
+- `huggingface` uses the HF router chat-completions endpoint
+- if `api_key_env` is not set, the backend defaults to `HF_TOKEN`
+- if `TRENCHES_HF_ROUTING_POLICY` is set to `fastest`, `cheapest`, or `preferred`, the backend appends that routing suffix to HF model names that do not already include one
+- the recommended deployment pattern is to store `HF_TOKEN` as a secret, not in repo files
+
+## Main Endpoints
+
+Server file:
+
+- [backend/src/trenches_env/server.py](/Users/alazarmanakelew/IdeaProjects/trenches/backend/src/trenches_env/server.py)
+
+### Health And Capabilities
+
+- `GET /healthz`
+  Returns `{ "status": "ok" }`
+
+- `GET /capabilities`
+  Returns:
+  - session/OpenEnv capability flags
+  - CORS settings
+  - per-entity `model_bindings`
+
+Use this once at app startup.
+
+### Session Lifecycle
+
+- `POST /sessions`
+  Creates a session.
+
+- `POST /sessions/{session_id}/reset`
+  Resets an existing session.
+
+- `GET /sessions/{session_id}`
+  Returns the latest `SessionState`.
+
+- `POST /sessions/{session_id}/step`
+  Advances one turn.
+
+Request body:
+- `actions: Record<agentId, AgentAction>`
+- `external_signals: ExternalSignal[]`
+
+Response:
+- `StepSessionResponse`
+  - `session`
+  - `oversight`
+  - `done`
+
+### Live News And Reaction Timeline
+
+- `POST /sessions/{session_id}/news`
+  Injects public/news signals, lets the backend resolve entity reactions, steps the world, and returns the structured reaction entry for that news event.
+
+Request body:
+- `signals: ExternalSignal[]`
+- `agent_ids?: string[]`
+
+Notes:
+- if `agent_ids` is omitted, all entities react
+- if `agent_ids` is provided, only those entities are auto-resolved for that news event
+- this still goes through the same env step path, so it stays aligned with OpenEnv behavior
+
+Response:
+- `IngestNewsResponse`
+  - `session`
+  - `oversight`
+  - `reaction`
+  - `done`
+
+- `GET /sessions/{session_id}/reactions`
+  Returns the rolling `reaction_log`.
+
+Use these two endpoints for:
+
+- incoming-news timeline
+- “who reacted to what” UI
+- live world-monitoring panels
+
+### Provider Diagnostics
+
+- `GET /sessions/{session_id}/providers/diagnostics`
+  Returns per-entity provider runtime health and recent inference telemetry.
+
+Important fields per entity:
+
+- `status`
+- `request_count`
+- `success_count`
+- `error_count`
+- `consecutive_failures`
+- `last_latency_ms`
+- `avg_latency_ms`
+- `last_success_at`
+- `last_error_at`
+- `last_error`
+
+Use this for:
+
+- provider health badges
+- fallback warnings
+- “model is unhealthy” operator panels
+- debugging why an entity is on heuristic fallback
+
+### Live Source Controls
+
+- `POST /sessions/{session_id}/live`
+  Enables or disables live mode.
+
+- `POST /sessions/{session_id}/sources/refresh`
+  Forces source refresh and rebuilds observations.
+
+- `GET /sessions/{session_id}/sources/monitor`
+  Returns source-health and delivery status per entity.
+
+### Scenarios And Benchmarks
+
+- `GET /scenarios`
+  Returns seeded scenarios.
+
+- `POST /benchmarks/run`
+  Runs scenario benchmarks and returns scorecards.
+
+### OpenEnv
+
+Legacy tuple-style endpoints:
+
+- `POST /reset`
+- `POST /step`
+- `GET /state`
+
+If `openenv-core` is installed, native OpenEnv is mounted at:
+
+- `/openenv`
+
+OpenEnv file:
+
+- [backend/src/trenches_env/openenv_adapter.py](/Users/alazarmanakelew/IdeaProjects/trenches/backend/src/trenches_env/openenv_adapter.py)
+
+## Main Schemas
+
+Schema file:
+
+- [backend/src/trenches_env/models.py](/Users/alazarmanakelew/IdeaProjects/trenches/backend/src/trenches_env/models.py)
+
+### SessionState
+
+Main top-level object for the frontend.
+
+Important fields:
+
+- `session_id`
+- `world`
+- `observations`
+- `belief_state`
+- `rewards`
+- `model_bindings`
+- `recent_traces`
+- `action_log`
+- `reaction_log`
+- `live`
+- `episode`
+
+### WorldState
+
+Important fields:
+
+- `latent_state`
+- `latent_events`
+- `actor_state`
+- `active_events`
+- `asset_state`
+- `coalition_graph`
+- `risk_scores`
+- `last_actions`
+
+Important distinction:
+
+- `latent_events` are canonical hidden events
+- `active_events` are the public-facing projection of those latent events
+
+### AgentObservation
+
+Main entity-facing view.
+
+Important fields:
+
+- `decision_prompt`
+- `belief_brief`
+- `belief_topics`
+- `available_actions`
+- `available_data_sources`
+- `strategic_state`
+- `strategic_assets`
+- `asset_alerts`
+- `source_packets`
+- `training_source_packets`
+- `live_source_packets`
+- `projection`
+
+### ObservationProjection
+
+This explains how messy the entity’s current view is.
+
+Important fields:
+
+- `mode`
+- `worldview_reliability`
+- `delayed_source_count`
+- `contested_source_count`
+- `contradiction_packet_count`
+- `contradiction_topics`
+- `obscured_metric_count`
+- `notes`
+
+Frontend rule:
+
+Show this clearly. Do not present entity observations as perfect truth.
+
+### EntityModelBinding
+
+Per-entity provider/runtime config.
+
+Important fields:
+
+- `provider`
+- `model_name`
+- `configured`
+- `ready_for_inference`
+- `decision_mode`
+- `supports_tool_calls`
+- `supports_structured_output`
+- `action_tools`
+- `observation_tools`
+- `notes`
+
+### ProviderAgentDiagnostics
+
+Per-entity runtime telemetry for provider-backed execution.
+
+Important fields:
+
+- `agent_id`
+- `provider`
+- `model_name`
+- `configured`
+- `ready_for_inference`
+- `decision_mode`
+- `status`
+- `request_count`
+- `success_count`
+- `error_count`
+- `consecutive_failures`
+- `last_latency_ms`
+- `avg_latency_ms`
+- `last_success_at`
+- `last_error_at`
+- `last_error`
+
+### ActionLogEntry
+
+Per-action activity feed row.
+
+Important fields:
+
+- `turn`
+- `actor`
+- `action_type`
+- `summary`
+- `target`
+- `reward_total`
+- `metadata`
+
+Use this for the entity activity log.
+
+### ReactionLogEntry
+
+Structured “public release -> entity reaction” object.
+
+Important fields:
+
+- `event_id`
+- `turn`
+- `source`
+- `latent_event_ids`
+- `signals`
+- `actor_outcomes`
+- `oversight_triggered`
+- `tension_before`
+- `tension_after`
+- `market_stress_after`
+- `oil_pressure_after`
+
+This is the easiest object for a live news feed.
+
+### AgentBeliefState
+
+Persistent per-entity memory.
+
+Important fields:
+
+- `agent_id`
+- `dominant_topics`
+- `beliefs`
+- `last_revision_turn`
+
+### AgentBeliefEntry
+
+One remembered belief/hypothesis for an entity.
+
+Important fields:
+
+- `belief_id`
+- `topic`
+- `summary`
+- `confidence`
+- `status`
+- `source`
+- `suspected_agents`
+- `related_event_ids`
+- `confirmation_count`
+- `contradiction_count`
+- `last_confirmed_turn`
+- `last_updated_turn`
+
+Belief behavior:
+
+- entities do not weight all topics equally
+- beliefs decay gradually when no new confirmation arrives
+- contradictory evidence usually downgrades a belief first before fully disconfirming it
+- two entities can see the same event and end up with different confidence because doctrine priors differ
+
+### Latent Events
+
+The backend now treats event flow as first-class, not just metric movement.
+
+Main schema:
+
+- `LatentEvent`
+
+Key fields:
+
+- `event_id`
+- `topic`
+- `status`
+- `severity`
+- `visibility`
+- `reliability`
+- `origin`
+- `affected_agents`
+- `affected_assets`
+- `started_at_turn`
+- `last_updated_turn`
+- `decay_rate`
+- `linked_event_ids`
+- `narratives`
+
+What this means:
+
+- scenarios can seed hidden events
+- incoming news creates or updates hidden events
+- entity actions create hidden events
+- linked spillover events can be spawned
+- public event feeds are projected from latent events
+- source contradictions now key off latent events, not only metric heuristics
+
+### ReactionActorOutcome
+
+One entity’s response to one news event.
+
+Important fields:
+
+- `agent_id`
+- `action`
+- `reward_total`
+- `decision_mode`
+
+## What Is Good To Go
+
+Backend pieces that are ready for frontend integration:
+
+- session lifecycle
+- live source monitoring
+- latent truth vs public state split
+- latent event engine and event-driven public projection
+- persistent belief state per entity
+- doctrine-specific belief revision and false-belief persistence
+- contradiction-aware observation projection
+- per-entity rewards
+- per-entity action logging
+- structured reaction logging for public/news events
+- seeded scenarios
+- benchmark runs
+- provider bindings
+- real provider execution with explicit fallback
+- provider runtime diagnostics
+- OpenEnv-compatible environment flow
+
+## What Is Still Left
+
+### Backend
+
+1. Persist replay history.
+   `recent_traces`, `action_log`, `reaction_log`, and latent event evolution are still rolling in-memory state, not durable history.
+
+2. Deepen the latent event graph.
+   The event engine now exists, but it can still be improved with stronger causal chains, event merging, event resolution rules, and richer cross-front propagation.
+
+3. Add event-delta summaries.
+   A compact backend-generated turn delta would make replay/debug views much easier to build.
+
+4. Keep hardening provider execution.
+   Retries and diagnostics now exist. The next step is richer classification for rate limits, timeout classes, and provider-specific retry traces.
+
+5. Add a durable event archive or export path.
+   There is still no persistent event timeline outside in-memory session state.
+
+### Frontend
+
+1. Build the app shell around:
+   - `/capabilities`
+   - `/scenarios`
+   - `/sessions`
+   - `/sessions/{id}`
+   - `/sessions/{id}/step`
+   - `/sessions/{id}/news`
+   - `/sessions/{id}/reactions`
+   - `/sessions/{id}/providers/diagnostics`
+   - `/sessions/{id}/live`
+   - `/sessions/{id}/sources/monitor`
+
+2. Add entity cards that show:
+   - projected state
+   - persistent belief topics / belief memory
+   - reward total
+   - provider readiness
+   - provider health/latency
+   - latest action
+   - uncertainty/projection info
+
+3. Add a live news/reaction timeline.
+   Use `/sessions/{id}/news` for ingestion and `reaction_log` or `/sessions/{id}/reactions` for history.
+
+4. Add latent event visibility to operator surfaces.
+   Show:
+   - key latent event topics
+   - event severity
+   - event visibility
+   - linked spillovers
+
+5. Add a source-health panel.
+   Use `/sessions/{id}/sources/monitor`.
+
+6. Add replay panels.
+   Use `recent_traces`, `action_log`, `reaction_log`, and `world.latent_events`.
+
+7. Make uncertainty visible.
+   Show reliability, contradiction topics, delayed sources, and contested-source counts.
+
+## Rule Of Thumb For Frontend
+
+If the UI means:
+
+- “what the entity believes” -> use `session.observations[agent_id]`
+- “what the entity currently remembers/believes across turns” -> use `session.belief_state[agent_id]`
+- “what the operator/debugger sees” -> use `session.world`
+- “what hidden developments are driving the sim” -> use `session.world.latent_events`
+- “what the backend can execute” -> use `session.model_bindings`
+- “what just happened on a turn” -> use `session.action_log` and `session.recent_traces`
+- “what public news triggered reactions” -> use `session.reaction_log`

DATA.md

@@ -0,0 +1,226 @@
+# Data Handoff
+
+## Chosen Base Model
+
+Use:
+
+- `Qwen/Qwen3-8B`
+
+Why this is the best default for the `2025-01 -> 2026-01` post-training window:
+
+- it was released inside the required time frame
+- it is available on Hugging Face
+- it is strong enough for structured action + prediction output
+- it is still realistic to run six separate entity post-training jobs on it
+
+This is the recommended first real base model for all six entities.
+
+## What I Added For Data
+
+The repo already had:
+
+- synthetic seed replay JSON files under [backend/src/trenches_env/historical_replays](/Users/alazarmanakelew/IdeaProjects/trenches/backend/src/trenches_env/historical_replays)
+- an OpenEnv replay training path
+- a training CLI that consumes replay JSON with the `HistoricalReplayDefinition -> HistoricalEvent` schema
+
+What I added is the first path from real historical sources into that same replay schema.
+
+### New Files
+
+- [backend/src/trenches_env/historical_collection.py](/Users/alazarmanakelew/IdeaProjects/trenches/backend/src/trenches_env/historical_collection.py)
+  - builds historical source profiles from the existing source manifest
+  - derives historical domains from allowlisted agent sources
+  - defines the `2025` and `2026` collection windows
+  - dedupes collected articles
+  - converts collected articles into the exact replay event schema used by training
+
+- [backend/src/trenches_env/historical_collection_cli.py](/Users/alazarmanakelew/IdeaProjects/trenches/backend/src/trenches_env/historical_collection_cli.py)
+  - CLI collector
+  - queries the GDELT DOC API month by month
+  - writes raw article audit files
+  - writes replay JSON files in the same schema as the existing synthetic seeds
+
+- [backend/tests/test_historical_collection.py](/Users/alazarmanakelew/IdeaProjects/trenches/backend/tests/test_historical_collection.py)
+  - validates source-profile extraction
+  - validates article -> replay-event conversion
+  - validates replay JSON compatibility with the existing historical replay loader
+
+## What Source Data It Uses
+
+The collector starts from the existing [backend/src/trenches_env/source_manifest.json](/Users/alazarmanakelew/IdeaProjects/trenches/backend/src/trenches_env/source_manifest.json).
+
+That means it does not invent a separate source universe. It reuses the current project’s aligned sources, then extracts historical domains from them. In practice this means it leans on the project’s existing training-core sources such as:
+
+- Reuters and wire-style reporting
+- official government / ministry sources
+- regional English-language outlets already assigned to the entities
+- market / shipping / sanctions / diplomacy sources already present in the manifest
+
+For historical collection, it converts those sources into domain-filtered GDELT queries and collects article candidates month by month.
+
+## Output Files
+
+The collector writes two outputs per run.
+
+### 1. Replay JSON
+
+Path example:
+
+- `backend/src/trenches_env/historical_replays/us_historical_2025.json`
+
+This matches the same structure as the existing synthetic seed files:
+
+- `replay_id`
+- `name`
+- `description`
+- `training_agent`
+- `events[]`
+
+Each event matches the current training schema:
+
+- `event_id`
+- `timestamp`
+- `topic`
+- `region`
+- `actors`
+- `targets`
+- `severity`
+- `summary`
+- `public_summary`
+- `source_type`
+- `confirmed`
+- `tags`
+- `impact`
+
+### 2. Raw Audit JSONL
+
+Path example:
+
+- `backend/tmp-historical-raw/us_historical_2025.articles.jsonl`
+
+Each line contains:
+
+- `article_id`
+- `agent_id`
+- `source_id`
+- `source_name`
+- `title`
+- `url`
+- `domain`
+- `timestamp`
+- `query`
+- `window_id`
+
+This is the provenance trail for curator review.
+
+## Date Windows
+
+The collector currently supports:
+
+- `2025` -> `2025-01-01` through `2026-01-01`
+- `2026` -> `2026-01-01` through the current day at collection time
+
+Important note:
+
+As of March 7, 2026, `2026` cannot honestly mean `2026-01-01 -> 2027-01-01` yet. The collector clamps future end dates to the current day so it does not pretend future historical data exists.
+
+## What Is Real vs Heuristic
+
+Real:
+
+- source alignment from the project’s own source manifest
+- historical article collection via GDELT
+- raw audit/provenance files
+- replay JSON output in the exact schema the training system already consumes
+
+Heuristic:
+
+- topic classification from article titles
+- severity classification from article titles
+- dedupe logic
+- actor/target inference
+- event `impact` generation
+
+That heuristic layer is intentional. It gives you a bootstrap pipeline from real historical articles into replay training data, but the resulting replay should still be curator-reviewed before production post-training.
+
+## Commands
+
+From repo root:
+
+```bash
+backend/.venv/bin/python -m trenches_env.historical_collection_cli \
+  --training-agent us \
+  --window 2025 \
+  --window 2026 \
+  --max-records-per-query 50 \
+  --max-events 128 \
+  --output-dir backend/src/trenches_env/historical_replays \
+  --raw-dir backend/tmp-historical-raw
+```
+
+All entities:
+
+```bash
+backend/.venv/bin/python -m trenches_env.historical_collection_cli \
+  --training-agent all \
+  --window 2025 \
+  --window 2026 \
+  --max-records-per-query 50 \
+  --max-events 128 \
+  --output-dir backend/src/trenches_env/historical_replays \
+  --raw-dir backend/tmp-historical-raw
+```
+
+## Docs Updated
+
+I also updated:
+
+- [backend/TRAINING_RUNBOOK.md](/Users/alazarmanakelew/IdeaProjects/trenches/backend/TRAINING_RUNBOOK.md)
+- [backend/TRAINING_FLOW.md](/Users/alazarmanakelew/IdeaProjects/trenches/backend/TRAINING_FLOW.md)
+- [backend/POST_TRAINING_PLAN.md](/Users/alazarmanakelew/IdeaProjects/trenches/backend/POST_TRAINING_PLAN.md)
+- [backend/pyproject.toml](/Users/alazarmanakelew/IdeaProjects/trenches/backend/pyproject.toml)
+
+So the collection path is now documented and exposed as a real CLI entry point.
+
+## Verification
+
+The added data-collection path was verified locally with:
+
+```bash
+PYTHONPYCACHEPREFIX=/tmp/trenches-pyc python -m py_compile \
+  backend/src/trenches_env/historical_collection.py \
+  backend/src/trenches_env/historical_collection_cli.py
+```
+
+```bash
+cd backend
+uv run --extra dev python -m pytest \
+  tests/test_historical_collection.py \
+  tests/test_openenv_adapter.py \
+  tests/test_server.py -q
+```
+
+Result:
+
+- `20 passed in 8.78s`
+
+## Handoff
+
+What is ready now:
+
+- a chosen base model: `Qwen/Qwen3-8B`
+- a collector path from real historical sources into the existing replay schema
+- raw provenance output
+- replay JSON output compatible with the current OpenEnv training flow
+
+What still needs to happen next:
+
+1. Run the collector for each entity.
+2. Curator-review the raw article audit files and the generated replay JSON.
+3. Replace the current synthetic seed replays with reviewed historical replays.
+4. Update the actual training runs to use `Qwen/Qwen3-8B` as the base model.
+5. Keep the old synthetic seeds only for smoke tests.
+
+One important truth:
+
+The collector is the first real data path, but it does not magically make the replay production-grade by itself. The training-ready replay still needs human review because event impact shaping is currently heuristic.

Dockerfile

@@ -0,0 +1,41 @@
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    NEXT_TELEMETRY_DISABLED=1 \
+    TRENCHES_ENTITIES_ROOT=/app/entities \
+    PORT=7860 \
+    BACKEND_PROXY_TARGET=http://127.0.0.1:8000 \
+    NEXT_PUBLIC_API_BASE_URL=/backend-api \
+    NEXT_PUBLIC_VERCEL_API_BASE=/api \
+    NEXT_PUBLIC_ENABLE_SOURCE_LOGIC=true
+
+WORKDIR /app
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends curl ca-certificates unzip \
+  && rm -rf /var/lib/apt/lists/*
+
+RUN curl -fsSL https://bun.sh/install | bash
+ENV PATH="/root/.bun/bin:${PATH}"
+
+COPY package.json bun.lock* ./
+RUN bun install --frozen-lockfile
+
+COPY next.config.ts postcss.config.mjs tsconfig.json next-env.d.ts ./
+COPY app ./app
+COPY src ./src
+
+COPY backend/pyproject.toml backend/README.md ./backend/
+COPY backend/src ./backend/src
+COPY entities ./entities
+
+RUN pip install --no-cache-dir ./backend
+RUN bun run build
+
+COPY scripts/start-space.sh ./scripts/start-space.sh
+RUN chmod +x ./scripts/start-space.sh
+
+EXPOSE 7860
+
+CMD ["./scripts/start-space.sh"]

Dockerfile.frontend

@@ -0,0 +1,14 @@
+FROM oven/bun:1.2.22-alpine
+
+WORKDIR /app
+
+COPY package.json bun.lock* ./
+RUN bun install --frozen-lockfile
+
+COPY next.config.ts postcss.config.mjs tsconfig.json next-env.d.ts ./
+COPY app ./app
+COPY src ./src
+
+EXPOSE 3000
+
+CMD ["bun", "run", "dev"]

ENTITIES.md

@@ -0,0 +1,128 @@
+# ENTITY.md: Detailed Breakdown of Agents in Fog of War Diplomacy Simulator
+
+This document provides a comprehensive breakdown of the 6 agents in the Fog of War Diplomacy Simulator, an OpenEnv-based multi-agent RL environment simulating the 2026 US-Israel-Iran geopolitical crisis. Each agent represents a key entity with a unique "identity" (embedded via LLM system prompts), personalized data feeds (filtered from World Monitor's 435+ RSS sources and other integrations), models, tools, observation spaces, and reward considerations. The goal is to foster emergent behaviors like coalition formation, deception, and de-escalation under partial observability.
+
+Agents receive consistent, role-specific information feeds through periodic queries to World Monitor APIs (e.g., every 5-10 turns or on-demand via tool calls). This ensures "fog of war"—no agent sees the full picture, but data is reliable and live-updated. Rewards are shared via a multi-component formula, tuned per agent to align with their adversarial "defeat enemies while staying strong" mindset.
+
+## General Setup Guidance
+
+### How to Use OpenEnv
+
+OpenEnv is a Gymnasium-compatible RL library for agentic environments. Extend `openenv.Env` to create your simulator:
+
+- **Core Class**: Define `FogOfWarDiplomacy` with `reset()` (initialize crisis state, e.g., tension at 50%), `step(actions)` (process text actions from LLMs, update world probabilistically), and per-agent observations/rewards as dicts.
+- **Multi-Agent Handling**: Use dict-based spaces (e.g., `observations = {"US": obs_us, ...}`) for partial observability.
+- **Training**: Wrap with RL libraries like TRL (Hugging Face) or RLlib. Loop: `env.reset()` → LLM agents generate actions via prompts → `env.step(actions)` → Update policies with PPO/GRPO on rewards.
+- **Deployment**: Dockerize as FastAPI server (expose `/reset`, `/step`). Client: `openenv.client` for remote training.
+- **Integration Tips**: Add World Monitor queries in `step()` for live data; use oversight as a wrapper class.
+
+### Setting Up Rewards
+
+Rewards are sparse/delayed for long-horizon planning, calculated per agent in `step()`:
+\[ r_t = w_1 \cdot C_t + w_2 \cdot E_t + w_3 \cdot M_t + w_4 \cdot B_t \]
+
+- \( C_t \): Coalition Stability (\( \frac{\# \text{allied} - \# \text{betrayals}}{\# \text{agents}} \)).
+- \( E_t \): Escalation Penalty (\( - \sigma(2 \cdot \Delta \text{tension}\_t) \)).
+- \( M_t \): Market Gain (\( \frac{\Delta \text{oil} + \Delta \text{sanctions}}{2} \)).
+- \( B*t \): Belief Alignment (\( 1 - |I*{\text{inferred}} - I\_{\text{true}}| \)).
+- Weights (\( w \)): Customized per agent (e.g., US emphasizes \( M_t \)); oversight scales by 0.5 on high risk.
+- Implementation: NumPy in env code; normalize to [-1,1]. Train via RL to amplify entity-specific goals (e.g., penalize weakness).
+
+### Representing Entities
+
+- **Identity Embedding**: Use system prompts in LLM pipelines (e.g., Hugging Face Transformers). Prepend to every inference: "You are [entity]. Prioritize [goals]. Forget unrelated knowledge—focus on defeating enemies while building strength."
+- **Consistency**: Fine-tune with RLHF on entity-aligned trajectories (reward persona adherence). Agents "forget" via prompt engineering and training masks.
+
+### Consistent Feed of Information
+
+- **Mechanism**: In `step()`, env queries World Monitor APIs (deployed on Vercel/Railway) for filtered data. Agents access via tool calls in prompts (e.g., "Query RSS for polls").
+- **Consistency**: Poll every 5 turns or on events; cache in env state (Redis). Partial: Each gets 20-50% relevant snippets, injected into obs dicts.
+- **Tools for Agents**: Text-based function calling (e.g., "query_intel(keywords)"); oversight has meta-tools.
+- **Fallback**: Procedural mocks for offline.
+
+## Agent Breakdowns
+
+### 1. US (Trump Admin / CENTCOM)
+
+- **Role/Identity**: Hawkish strategist leading military strikes, sanctions, and alliances. Prompt: "You are the US President in 2026 Iran war. Prioritize alliances and oil stability. Think aggressively: Defeat enemies via superior force, avoid domestic backlash, model incentives to exploit weaknesses."
+- **Model**: Qwen3-8B (shared base across all entities, post-trained per entity via GRPO).
+- **Personalized RSS/Data Feeds** (Filtered via World Monitor APIs, e.g., `/api/geopolitics/v1/filter?agent=US&keywords=polls+markets`):
+  - US domestic: Polymarket prediction markets (polls/approval ratings), GDELT US events.
+  - Economic: Bloomberg US feeds, commodity dashboard (oil prices).
+  - Alliances: AIS vessel tracking (Gulf bases), Sky News Middle East (ally updates).
+  - Query Frequency: High on domestic (every turn for polls); stochastic injection for events like "Dow drop".
+- **Tools/Actions**: "impose_sanctions", "propose_alliance", "query_polls", "cyber_command".
+- **Observation Space**: Dict with public news, private intel (allies, polls), market impacts; partial (hides Iran internals).
+- **Rewards Tuning**: High weight on \( M_t \) (markets) and \( C_t \) (alliances); bonus for bluff detection (\( B_t \)).
+- **Training Notes**: RL emphasizes domestic strength; fine-tune on trajectories avoiding "forever war" fatigue.
+
+### 2. Israel (Netanyahu / IDF)
+
+- **Role/Identity**: Defensive aggressor focused on regime change and border security. Prompt: "You are Israel's PM/IDF in 2026 crisis. Eliminate threats decisively. Reason multi-step: Defeat Iran proxies, form unbreakable coalitions, infer hidden aggressions."
+- **Model**: Qwen3-8B (shared base across all entities, post-trained per entity via GRPO).
+- **Personalized RSS/Data Feeds** (e.g., `/api/geopolitics/v1/filter?agent=Israel&keywords=threats+lebanon`):
+  - Regional threats: OREF rocket alerts, ACLED conflict data (Lebanon/Syria).
+  - Defense: Sky News Middle East, Al Jazeera regional (proxy movements).
+  - Borders: MTV Lebanon streams/webcams, NASA FIRMS (strike fires).
+  - Query Frequency: Event-triggered (e.g., on "clash" headlines); consistent northern front updates.
+- **Tools/Actions**: "launch_strike", "border_defense", "query_alerts", "coalition_propose".
+- **Observation Space**: Public escalations, private troop intel; hides Gulf economics.
+- **Rewards Tuning**: Emphasize \( E_t \) (penalize escalations if not decisive) and \( B_t \) (belief on proxies).
+- **Training Notes**: Optimize for high-pressure recovery; RL on decapitation scenarios.
+
+### 3. Iran (IRGC / Interim Leadership)
+
+- **Role/Identity**: Resilient defender using proxies and asymmetry. Prompt: "You are Iran's IRGC post-Khamenei. Defend sovereignty via deception. Survive escalations: Weaken foes indirectly, defeat through attrition while maintaining internal strength."
+- **Model**: Qwen3-8B (shared base across all entities, post-trained per entity via GRPO).
+- **Personalized RSS/Data Feeds** (e.g., `/api/geopolitics/v1/filter?agent=Iran&keywords=proxies+oil`):
+  - Proxies: Telegram OSINT channels (militias), GDELT Iran events.
+  - Internal: NASA FIRMS (strike impacts), commodity dashboard (Hormuz oil).
+  - Retaliation: ACLED global conflicts (proxy actions).
+  - Query Frequency: Real-time on proxies (WebSockets); consistent for losses.
+- **Tools/Actions**: "activate_proxy", "missile_launch", "query_osint", "deception_campaign".
+- **Observation Space**: Private morale/funding, public strikes; hides US polls.
+- **Rewards Tuning**: High on \( E_t \) (survive escalations) and \( M_t \) (oil resilience).
+- **Training Notes**: RL for deception emergence; fine-tune on asymmetric wins.
+
+### 4. Hezbollah (Proxy Swarm Leader)
+
+- **Role/Identity**: Opportunistic insurgent in asymmetric warfare. Prompt: "You are Hezbollah's leader. Swarm enemies with minimal resources. Infer weaknesses: Defeat via guerrilla tactics, align with Iran while exploiting gaps for strength."
+- **Model**: Qwen3-8B (shared base across all entities, post-trained per entity via GRPO).
+- **Personalized RSS/Data Feeds** (e.g., `/api/geopolitics/v1/filter?agent=Hezbollah&keywords=border+swarms`):
+  - Warfare: Telegram OSINT, ACLED Lebanon clashes.
+  - Morale: Al Jazeera proxies, border webcams/videos.
+  - Funding: Filtered RSS (Iran ties).
+  - Query Frequency: High on borders (streams); event-based for swarms.
+- **Tools/Actions**: "drone_swarm", "asymmetric_strike", "query_border", "morale_boost".
+- **Observation Space**: Proxy reports, limited global; hides market data.
+- **Rewards Tuning**: Bonus on \( C_t \) (Iran alignment) and \( B_t \) (infer Israel bluffs).
+- **Training Notes**: Train for sub-agent spawning; RL on opportunistic plays.
+
+### 5. Gulf Coalition (Saudi/UAE/Qatar)
+
+- **Role/Identity**: Pragmatic hedger balancing neutrality and security. Prompt: "You are the Gulf Coalition. Protect markets selectively. Hedge alliances: Defeat disruptions economically, stay strong via resource leverage without full commitment."
+- **Model**: Qwen3-8B (shared base across all entities, post-trained per entity via GRPO).
+- **Personalized RSS/Data Feeds** (e.g., `/api/market/v1/filter?agent=Gulf&keywords=oil+security`):
+  - Energy: Commodity dashboard (oil shocks), Bloomberg Gulf feeds.
+  - Security: AIS Hormuz vessels, finance variant (market data).
+  - Neutrality: Climate/anomaly APIs (disruptions).
+  - Query Frequency: Consistent markets (every turn); triggered on blockades.
+- **Tools/Actions**: "hedge_neutrality", "resource_allocate", "query_markets", "evade_blockade".
+- **Observation Space**: Economic ripples, partial alliances; hides proxy internals.
+- **Rewards Tuning**: Heavy on \( M_t \) (markets) and \( C_t \) (hedging).
+- **Training Notes**: RL for balanced neutrality; fine-tune on ripple effects.
+
+### 6. Oversight Agent (Fleet AI Meta-Layer)
+
+- **Role/Identity**: Impartial auditor for scalable monitoring. Prompt: "You are an AI overseer. Analyze drifts probabilistically. Explain/intervene neutrally: Ensure alignment without bias, focusing on crisis de-escalation."
+- **Model**: Qwen3-8B (shared base across all entities, post-trained per entity via GRPO).
+- **Personalized RSS/Data Feeds** (e.g., `/api/geopolitics/v1/synthesized?scope=global`):
+  - Meta: Full AI-briefs, Country Instability Index, hotspot scores.
+  - Aggregated: RAG headline memory (cross-agent).
+  - Query Frequency: Every step for traces; real-time escalations.
+- **Tools/Actions**: "analyze_drift", "generate_explanation", "intervene_realign", "query_global".
+- **Observation Space**: Aggregated traces, beliefs; no direct actions.
+- **Rewards Tuning**: Tied to primaries (e.g., bonus if reduces \( E_t \)); self-reward on accuracy.
+- **Training Notes**: Meta-RL; fine-tune on intervention efficacy.
+
+This setup ensures agents are fully representative, with consistent live feeds driving adaptive, entity-aligned behaviors in OpenEnv. For code examples, see the main repo.

FLOW.md

@@ -0,0 +1,163 @@
+# Trenches — System Flow
+
+## High-Level Architecture
+
+```mermaid
+graph TB
+    subgraph Frontend ["Frontend (Next.js · port 3000)"]
+        Globe["🌍 Mapbox Globe"]
+        TopBar["Top Bar (Trenches + Stats)"]
+        News["📰 News Feed Panel"]
+        Activity["📋 Activity Log Panel"]
+        Chat["💬 Chat Panel"]
+        Controls["🎮 Map Controls"]
+        Timeline["⏱️ Timeline Scrubber (planned)"]
+    end
+
+    subgraph API ["Next.js API Routes (/api)"]
+        Bootstrap["GET /api/bootstrap"]
+        SessionAPI["POST /api/session"]
+        StepAPI["POST /api/step"]
+        ChatAPI["POST /api/chat"]
+    end
+
+    subgraph Backend ["Backend (FastAPI · port 8000)"]
+        Server["FastAPI Server"]
+        Env["FogOfWarDiplomacyEnv"]
+        SessionMgr["Session Manager"]
+        RL["RL / Rewards Engine"]
+        Oversight["Oversight Agent"]
+        Scenarios["Scenario Engine"]
+        SourceHarvester["Source Harvester"]
+        ProviderRuntime["Provider Runtime (LLM)"]
+    end
+
+    subgraph Data ["Data Layer"]
+        Entities["📁 Entity Packs (6 agents)"]
+        SourceManifest["📋 Source Manifest (RSS/OSINT)"]
+        LiveFeeds["🔴 Live Feeds (RSS/Telegram/API)"]
+    end
+
+    Globe --- TopBar
+    Globe --- News
+    Globe --- Activity
+    Globe --- Chat
+    Globe --- Controls
+
+    Frontend -->|HTTP| API
+    API -->|proxy| Backend
+
+    Server --> SessionMgr
+    SessionMgr --> Env
+    Env --> RL
+    Env --> Oversight
+    Env --> Scenarios
+    Env --> SourceHarvester
+    Env --> ProviderRuntime
+
+    SourceHarvester --> LiveFeeds
+    SourceHarvester --> SourceManifest
+    Env --> Entities
+```
+
+## Simulation Loop (per turn)
+
+```mermaid
+sequenceDiagram
+    participant User as User / Chat
+    participant FE as Frontend
+    participant API as API Layer
+    participant Env as FogOfWarDiplomacyEnv
+    participant Sources as Source Harvester
+    participant Agents as 6 LLM Agents
+    participant OA as Oversight Agent
+    participant RL as Rewards Engine
+
+    User->>FE: Injects event via Chat (fake) or auto-step (real)
+    FE->>API: POST /step {actions, external_signals}
+    API->>Env: step_session(session, request)
+
+    Note over Env: Turn increments
+
+    Env->>Sources: refresh_due_batch()
+    Sources-->>Env: Latest RSS/OSINT packets
+
+    Env->>Env: inject_external_signals (real or fake)
+
+    Env->>Agents: resolve_policy_actions()
+    Note over Agents: Each agent picks action based on<br/>partial observations + signals
+
+    Env->>OA: compute_oversight(world, actions)
+    OA-->>Env: Risk score + interventions
+    Note over OA: If risk > 0.5, scale rewards<br/>or force re-action
+
+    Env->>Env: apply_actions → update world state
+    Env->>Env: update tension, market, oil
+
+    Env->>RL: compute_rewards(world, episode)
+    Note over RL: r = 0.3·Coalition + 0.4·Escalation<br/>+ 0.2·Market + 0.1·Belief
+    RL-->>Env: Per-agent reward breakdowns
+
+    Env->>Env: build_observations (fog of war)
+    Env-->>API: StepSessionResponse {session, oversight, done}
+    API-->>FE: Updated state
+    FE->>FE: Re-render globe, panels, stats
+```
+
+## Event Types and Reward Impact
+
+```mermaid
+flowchart LR
+    subgraph Real ["Real Events"]
+        RSS["RSS/OSINT Feed"]
+        Scenario["Scenario Engine"]
+    end
+
+    subgraph Fake ["Fake Events"]
+        ChatInput["Chat Injection"]
+    end
+
+    RSS -->|"source: live"| Env["Environment"]
+    Scenario -->|"source: env"| Env
+    ChatInput -->|"source: manual"| Env
+
+    Env --> AgentBehavior["Agent Behavior<br/>(all events affect actions)"]
+
+    Env --> RewardCalc{"Reward Calculation"}
+
+    RewardCalc -->|"✅ Real events only"| RLSignal["RL Training Signal"]
+    RewardCalc -->|"❌ Fake events filtered"| NoReward["No reward impact"]
+```
+
+## Agent Decision Flow
+
+```mermaid
+flowchart TD
+    Obs["Partial Observation<br/>(fog of war filtered)"] --> Agent["Agent (LLM)"]
+
+    subgraph Context ["Agent Context"]
+        Identity["Identity / System Prompt"]
+        Intel["Private Intel Briefs"]
+        Beliefs["Belief State"]
+        Tools["Available Tools"]
+    end
+
+    Context --> Agent
+
+    Agent --> Action["Choose Action"]
+    Action --> Strike["⚔️ Strike"]
+    Action --> Negotiate["🤝 Negotiate"]
+    Action --> Sanction["💰 Sanction"]
+    Action --> Defend["🛡️ Defend"]
+    Action --> Intel2["🔍 Intel Query"]
+    Action --> Mobilize["🚀 Mobilize"]
+    Action --> Deceive["🎭 Deceive"]
+
+    Strike & Negotiate & Sanction & Defend & Intel2 & Mobilize & Deceive --> Oversight{"Oversight Check"}
+
+    Oversight -->|"Risk ≤ 0.5"| Execute["Execute Action"]
+    Oversight -->|"Risk > 0.5"| Intervene["Intervene / Modify"]
+
+    Execute --> WorldUpdate["Update World State"]
+    Intervene --> WorldUpdate
+```

HANDOFF.md

@@ -0,0 +1,17 @@
+The frontend now presents the RL environment as a black intelligence-style operator console instead of a generic dashboard. The main map in src/components/CommandMap.tsx:44 was restyled toward the
+WorldMonitor look: darker basemap treatment, suppressed civilian labels, stronger fog/space treatment, and scanline/grid atmosphere. The app shell in src/App.tsx:161 now builds a monitoring snapshot per
+agent from live session state and renders the monitoring deck beside the map, so the user can watch reward pressure, source health, recent actions, and model posture in one place. IMPROVEMENTS.md is fully
+written at IMPROVEMENTS.md:1.
+
+On the backend, reward shaping is no longer mostly shared. backend/src/trenches_env/rl.py:203 now defines doctrine-specific strategic state baselines and per-actor action effects, and backend/src/
+trenches_env/env.py:222 now carries persistent actor_state, applies signal pressure and action pressure into that state, exposes it in observations, flattens geolocated assets for model/viewer use, and
+computes unique reward functions for each entity at backend/src/trenches_env/env.py:892. Type surfaces were aligned in src/lib/types.ts:45, reward coverage was extended in backend/tests/
+test_reward_differentiation.py:5, and the source manifest was regenerated in backend/src/trenches_env/source_manifest.json so the Israel/Hezbollah source specialization matches runtime.
+
+What still needs to be done: the monitoring deck supports tool inventory, but entity tools.json packs are not wired into observations yet, so that part of the UI will stay empty until the tool layer is
+integrated. The model labels in the monitoring view are still product-style placeholders, not final checkpoint selections. The map requires VITE_MAPBOX_TOKEN for full rendering, and the frontend still has a
+large-bundle warning on build, so code-splitting is still worth doing before the UI grows further. The bigger roadmap items in IMPROVEMENTS.md:5 are still future work: hidden-world engine, benchmark/
+curriculum harness, and deeper replay/comparison observability.
+
+Verification: PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python -m pytest passed with 14 passed, 1 skipped. npm run typecheck passed. npm run build passed, with the existing Vite chunk-size warning
+only.

IMPROVEMENTS.md

@@ -0,0 +1,84 @@
+# Improvements
+
+This document captures the three highest-leverage improvements for the simulator after the MVP. Each one is large enough to materially change training quality, realism, and operator usefulness.
+
+## 1. Hidden-World Engine
+
+### Objective
+Replace the current mostly surface-level world update loop with a canonical latent world state that each entity only perceives through partial, noisy, delayed, and bias-shaped observations.
+
+### Why This Matters
+Right now the simulator has actor-specific rewards and source bundles, but the underlying world can still be too direct and too legible. That makes the task easier than the real problem and increases the risk of reward gaming. A hidden-world engine forces the policies to reason under uncertainty instead of reacting to a clean omniscient state.
+
+### What To Build
+- A canonical state graph for logistics, infrastructure integrity, domestic resilience, proxy health, coalition confidence, chokepoint access, and military readiness.
+- Observation projection layers that transform latent state into actor-specific intel packets with source lag, missingness, confidence, and bias.
+- Source reliability and deception mechanics so models must reason about contradictory or manipulated evidence.
+- Damage persistence so strikes and mobilization affect later turns instead of only the immediate step.
+- Cross-front coupling so a Gulf shock can change Israeli decision quality, US domestic resilience, or Iranian leverage.
+
+### Implementation Shape
+- Keep one hidden state store per session.
+- Each step applies actions to the hidden state first.
+- Each source/tool reads from that hidden state through a projection function.
+- Each actor receives only its projection, not the full state.
+- The viewer dashboard can still render a privileged map and replay, but that view remains unavailable to the models.
+
+### Success Criteria
+- Agents can no longer trivially infer the full world from public state alone.
+- Different source bundles produce meaningfully different beliefs for the same event.
+- Training runs become less brittle and less prone to one-step exploitation.
+
+## 2. Evaluation Harness And Curriculum
+
+### Objective
+Turn training from open-ended sandbox play into measurable policy development with regression protection, seeded scenarios, and staged learning.
+
+### Why This Matters
+The project will improve much faster once performance is measured against doctrine-specific benchmarks rather than by whether the simulator runs. Without evaluation, reward shaping tends to drift and policies often learn artifacts instead of strategy.
+
+### What To Build
+- Seeded scenario packs for shipping crises, border flare-ups, corridor interdiction, domestic unrest, and coalition fracture.
+- Policy scorecards per entity with doctrine-aligned metrics.
+- Reward-gaming checks that detect obviously degenerate policies.
+- Self-play and adversarial evaluation between versions.
+- Curriculum stages that move from narrow tactical cases to full multi-front regional crises.
+- Unsloth-based per-entity post-training loops so each actor can be adapted efficiently without retraining the full stack.
+
+### Implementation Shape
+- Add fixed seeds and replayable scenario fixtures.
+- Run benchmark suites after policy changes.
+- Store reward decomposition and trace outputs for each benchmark run.
+- Train smaller doctrine-specific adapters first, then graduate them into the full environment.
+
+### Success Criteria
+- Every entity has a stable benchmark suite.
+- Policy regressions are visible in CI or scheduled evaluation runs.
+- New reward changes can be justified with measurable gains, not intuition alone.
+
+## 3. Command Dashboard And Replay Observability
+
+### Objective
+Promote the frontend from a session viewer to a real command-and-control observability layer for simulation, training, and debugging.
+
+### Why This Matters
+If a run collapses, you need to know why immediately. A polished dashboard is not just presentation; it is the main debugging surface for understanding model behavior, source health, intervention timing, and reward dynamics.
+
+### What To Build
+- A unified operational map showing entities, geolocated assets, fronts, chokepoints, and coalition links.
+- A per-agent monitoring deck for model status, source health, reward decomposition, and recent actions.
+- Step-by-step replay with diff views between timesteps.
+- Source-ingestion health views so failed feeds are visible.
+- Oversight visibility showing when intervention risk crossed thresholds and what triggered it.
+- Run comparison views so two policies or seeds can be compared side by side.
+
+### Implementation Shape
+- Keep the map viewer privileged for the human operator only.
+- Feed the dashboard from structured session snapshots, not hand-built UI-only state.
+- Surface both raw metrics and human-readable summaries.
+- Preserve replay history so failures can be audited after the run ends.
+
+### Success Criteria
+- A user can explain a bad decision by tracing source inputs, action choice, and reward terms.
+- Replay is fast enough to inspect long runs without digging through logs.
+- The dashboard is useful for both live demos and offline training analysis.

PLAN.md

@@ -0,0 +1,118 @@
+# Fog of War Diplomacy Simulator
+
+## Overview
+
+The Fog of War Diplomacy Simulator is an innovative OpenEnv-based multi-agent reinforcement learning (RL) environment designed for the OpenEnv Hackathon under **Statement 1: Multi-Agent Interactions**, with a focus on the **Fleet AI Sub-Theme: Scalable Oversight**. This project simulates the volatile 2026 US-Israel-Iran geopolitical crisis—drawing from real-time events like airstrikes on Tehran, retaliatory missile barrages across the Gulf, threats to the Strait of Hormuz, leadership assassinations (e.g., Khamenei's fallout), US naval engagements (e.g., sub sinkings), domestic political upheavals (e.g., Trump's mid-war oustings of figures like Noem and Mullin), market crashes (Dow drops of 800+ points), and public opinion shifts (e.g., 59% disapproval polls)—to train LLM agents in emergent strategic behaviors, theory-of-mind reasoning, and de-escalation tactics.
+
+At its core, the simulator creates a partially observable "fog-of-war" world where agents negotiate coalitions, manage deceptions, and respond to stochastic "black swan" events. A dedicated oversight agent monitors and intervenes scalably, preventing cascading failures. By integrating live global data feeds (via a forked World Monitor integration), the environment pushes the boundaries of LLM training in adversarial, long-horizon multi-agent settings—addressing the unsolved challenge of preparing AI for real-world crises where misjudgment could exacerbate global instability.
+
+This project is difficult and untried due to its scale: combining infinite-horizon partial observability, emergent deception in high-dimensional state spaces, live-trending stochasticity, and recursive oversight mechanisms that risk computational explosion or reward hacking. The expected outcome is an environment that trains LLMs for scalable oversight in complex multi-actor crises, fostering resilient, explainable AI behaviors amid 2026-style volatility.
+
+## Key Features
+
+- **Multi-Agent Dynamics**: 6 LLM agents representing key geopolitical entities, engaging in cooperation, competition, negotiation, and coalition formation.
+- **Partial Observability and Fog of War**: Agents receive personalized, incomplete views of the world state, forcing inference of hidden incentives and beliefs.
+- **Live Data Integration**: Real-time ingestion from 435+ RSS feeds, Telegram OSINT, video streams, and structured data sources (via World Monitor fork) for dynamic event injection.
+- **Scalable Oversight**: A meta-agent analyzes behaviors, calculates risks, and intervenes using probabilistic formulas, aligning with Fleet AI's emphasis on monitoring complex settings.
+- **RL Training Loop**: Agents undergo post-training via methods like PPO/GRPO, with sparse rewards encouraging de-escalation while maintaining adversarial "defeat enemies" mindsets.
+- **Centralized Dashboard**: Military-themed UI for monitoring all agents from a single command center, with per-agent tabs showing personalized intel and actions.
+- **Dockerized Deployment**: Fully containerized for reproducibility, scalability, and hackathon judging (e.g., upload to Hugging Face Hub).
+- **Hackathon Alignment**: Builds a realistic multi-actor environment for task discovery and achievement, with bonus potential for Fleet AI prizes.
+
+## Architecture
+
+The simulator is built as a Dockerized OpenEnv environment, extending `openenv.Env` for Gymnasium-compatible RL interfaces. It runs as a FastAPI server in a container, exposing endpoints like `/reset`, `/step`, and `/state` for agent interactions. The architecture emphasizes modularity:
+
+- **Core Environment Class (`FogOfWarDiplomacy`)**: Manages the global state, including tension levels, coalitions, and stochastic events. Uses NumPy for probabilistic simulations (e.g., event triggers based on real-time data).
+- **Multi-Agent Setup**: Agents operate in parallel, submitting text-based actions (e.g., "Propose ceasefire with sanctions relief") via LLM prompts. Observations are returned as a dict keyed by agent ID, enforcing partial observability.
+- **Oversight Wrapper (`OversightAgent`)**: A meta-layer that queries primary traces without direct interference, generating explanations and interventions.
+- **Data Ingestion Sidecar**: A forked World Monitor service (cloned from https://github.com/koala73/worldmonitor) runs in a separate Docker container via Docker Compose. It aggregates data from RSS feeds (e.g., Bloomberg, Al Jazeera), Telegram channels, video streams (HLS), webcams, and structured APIs (e.g., ACLED conflicts, Polymarket polls, GDELT events). The env queries this via HTTP/protobuf for filtered, per-agent intel.
+- **Dashboard**: Built with Streamlit or Gradio, themed as a tactical command center (dark greens/blacks, radar overlays, red alerts). Connects to OpenEnv's API for live visualization; features a global map (using Plotly.js), intel streams, and tabbed per-agent views.
+- **Training Integration**: Compatible with RL libraries like TRL (Hugging Face) or TorchForge. Agents train in loops: Reset env → Step with prompts → Update policies via rewards.
+
+Processing of data (e.g., RSS feeds) occurs in the World Monitor sidecar:
+
+- **Ingestion**: World Monitor polls feeds in real-time (e.g., every 5-10 minutes via cron-like jobs) and stores in a lightweight DB (e.g., SQLite or Redis cache).
+- **Filtering and Distribution**: On env `step()` or `reset()`, the OpenEnv server requests agent-specific subsets (e.g., via `/api/geopolitics/v1/filter?agent=US&keywords=polls`). No agent processes the full dataset—each gets tailored snippets (e.g., US: Polymarket polls; Iran: Telegram proxy reports), maintaining fog of war.
+- **Event Injection**: Parsed data triggers stochastic events (e.g., if "strike" in headline, increase tension by 20% with probability 0.7).
+
+Agents do not have individual dashboards; instead, they access data/tools via personalized APIs in their prompts (e.g., "Query RSS for US polls"). The centralized dashboard monitors all, allowing human oversight during training/demos.
+
+## Agents and Models
+
+Exactly 6 agents are defined to capture the crisis's core dynamics without combinatorial overload:
+
+1. **US (Trump Admin / CENTCOM)**: Focuses on alliances, sanctions, and domestic stability. Identity: "Hawkish strategist prioritizing oil and polls; defeat enemies via superior force while avoiding backlash."
+   - Model: Qwen3-8B (post-trained per entity via GRPO).
+   - Personalized Data/Tools: Polymarket polls, Bloomberg US feeds, sanctions imposition API.
+
+2. **Israel (Netanyahu / IDF)**: Emphasizes regime change and border security. Identity: "Defensive aggressor; eliminate threats decisively, model allies' incentives to form unbreakable coalitions."
+   - Model: Qwen3-8B (post-trained per entity via GRPO).
+   - Personalized Data/Tools: OREF alerts, ACLED Lebanon data, strike simulation tools.
+
+3. **Iran (IRGC / Interim Leadership)**: Coordinates retaliation and proxies. Identity: "Resilient defender; use asymmetry and deception to weaken foes, survive escalations at all costs."
+   - Model: Qwen3-8B (post-trained per entity via GRPO).
+   - Personalized Data/Tools: Telegram OSINT, GDELT Iran events, missile launch tools.
+
+4. **Hezbollah (Proxy Swarm Leader)**: Handles asymmetric attacks. Identity: "Opportunistic insurgent; swarm enemies with minimal resources, infer hidden weaknesses for strikes."
+   - Model: Qwen3-8B (post-trained per entity via GRPO).
+   - Personalized Data/Tools: Border webcams, ACLED clashes, drone activation tools.
+
+5. **Gulf Coalition (Saudi/UAE/Qatar)**: Balances energy security and neutrality. Identity: "Pragmatic hedger; protect markets by allying selectively, defeat disruptions through economic leverage."
+   - Model: Qwen3-8B (post-trained per entity via GRPO).
+   - Personalized Data/Tools: Commodity dashboard, AIS vessel tracking, blockade evasion tools.
+
+6. **Oversight Agent (Fleet AI Meta-Layer)**: Monitors without negotiating. Identity: "Impartial auditor; explain drifts probabilistically, intervene to align without bias."
+   - Model: Qwen3-8B (post-trained per entity via GRPO).
+   - Personalized Data/Tools: Full synthesized briefs, hotspot scores, intervention APIs.
+
+Each agent's "identity" is embedded via system prompts in LLM inference, ensuring focus on "defeating enemies" (adversarial goals) while building strength (e.g., coalitions). During training, agents "forget" irrelevant knowledge, optimizing solely for crisis survival via RL.
+
+## Data Integration with World Monitor
+
+Forked from https://github.com/koala73/worldmonitor (AGPL-3.0), this service provides the backbone for live intel:
+
+- **Sources**: 435+ RSS (media outlets like Reuters, Sky News), 26 Telegram OSINT channels, 30+ HLS video streams, 22 webcams (e.g., Gulf hotspots), structured feeds (ACLED conflicts, Polymarket markets, GDELT events, NASA FIRMS fires).
+- **Processing**: Self-hosted in Docker; uses Vite/Tauri for frontend (optional), but we leverage its 22 proto-first APIs (e.g., `/api/geopolitics/v1/list-hotspots`) and WebSockets for real-time pushes.
+- **Per-Agent Filtering**: Agents query tailored endpoints (e.g., US: `?filter=polls+us`; Iran: `?filter=proxies+iran`). No full requests—agents decide what to pull based on prompts (e.g., "If tension >50%, query RSS for enemy movements").
+- **Fallbacks**: Cached data for offline demos; procedural mocks if live feeds fail.
+
+This setup makes agents adaptive: Live info streams in during training, influencing decisions (e.g., a fresh Polymarket poll shifts US rewards).
+
+## RL Training and Rewards
+
+Agents train in an RL loop using OpenEnv's interfaces, with each having independent policy updates (via TRL) while sharing the env. Live data injects during episodes, allowing decisions/actions in real-time simulations. Method: GRPO for multi-agent cooperation.
+
+**Rewards**: Sparse and delayed to encourage long-horizon planning. Formula per agent at timestep \( t \):
+
+\[ r_t = 0.3 \cdot C_t + 0.4 \cdot E_t + 0.2 \cdot M_t + 0.1 \cdot B_t \]
+
+- \( C_t \): Coalition Stability (\( \frac{\# \text{allied} - \# \text{betrayals}}{\# \text{agents}} \)).
+- \( E_t \): Escalation Penalty (\( - \sigma(2 \cdot \Delta \text{tension}\_t) \)).
+- \( M_t \): Market Gain (\( \frac{\Delta \text{oil} + \Delta \text{sanctions}}{2} \)).
+- \( B*t \): Belief Alignment (\( 1 - |I*{\text{inferred}} - I\_{\text{true}}| \)).
+
+Oversight scales rewards by 0.5 on high risk. Normalized to [-1, 1]; aggregated over 1000+ turn episodes.
+
+## Oversight Analytical Method
+
+Oversight uses belief propagation for risk:
+
+1. Belief Update: \( B'(s') = \eta \sum_s P(o_t | a_t, s') T(s, a_t, s') B(s) \).
+
+2. Risk Score: \( R(a*t) = \sum*{s'} B'(s') \cdot U(s', a*t) \cdot \sigma(2 \cdot (I*{\text{self}} - I\_{\text{other}})) \).
+
+Intervene if \( R > 0.5 \). Implemented in NumPy for efficiency.
+
+## Installation and Setup
+
+1. **Clone Repo**: `git clone https://github.com/shlawgathon/trenches.git`
+2. **Frontend**: `bun install && bun run dev` → `http://localhost:3000`
+3. **Backend**: `cd backend && uv sync && source .venv/bin/activate && uvicorn trenches_env.server:app --reload --port 8000`
+4. **Training**: `python -m trenches_env.training_cli --model-id Qwen/Qwen3-8B --training-agent us`
+5. **HF Space**: Live at [AlazarM/trenches](https://huggingface.co/spaces/AlazarM/trenches)
+6. **Dependencies**: Python 3.12, OpenEnv, FastAPI, NumPy, Hugging Face TRL.
+
+## Contributing and License
+
+Open-source under MIT. Contributions welcome for expanding agents or data sources. Built for the OpenEnv Hackathon (March 7-8, 2026).

README.md

@@ -0,0 +1,84 @@
+---
+title: Trenches
+emoji: 🌍
+colorFrom: red
+colorTo: gray
+sdk: docker
+app_port: 7860
+---
+
+<img width="512" height="512" alt="Image Background Remover (1)" src="https://github.com/user-attachments/assets/a1ab0df2-435f-444b-b8a1-36b1a64b55e8" />
+
+# Trenches
+
+A multi-agent crisis simulator built on [OpenEnv](https://github.com/openenv-ai/openenv). LLM agents navigate a fog-of-war geopolitical scenario — negotiating coalitions, managing deception, and responding to live global events — while a dedicated oversight agent monitors for dangerous escalation.
+
+## Overview
+
+Trenches drops six LLM-powered actors into a volatile 2026 Middle East crisis. Each agent operates under partial observability with role-specific intelligence, tools, and incentives. A scalable oversight mechanism intervenes when escalation risk crosses critical thresholds.
+
+| Agent             | Role                                            | Model    |
+| ----------------- | ----------------------------------------------- | -------- |
+| 🇺🇸 United States  | Hawkish superpower balancing polls & projection | Qwen3-8B |
+| 🇮🇱 Israel         | Regional actor with strike autonomy             | Qwen3-8B |
+| 🇮🇷 Iran           | Adversary leveraging proxies & deception        | Qwen3-8B |
+| 🪖 Hezbollah      | Non-state militia with asymmetric tactics       | Qwen3-8B |
+| 🛢️ Gulf Coalition | Economic bloc protecting oil & stability        | Qwen3-8B |
+| 🔍 Oversight      | Monitors all actors, intervenes on escalation   | Qwen3-8B |
+
+## Key Features
+
+- **Fog of War** — agents see only their role-filtered intel, never the full world state
+- **Live News Injection** — real-time RSS/OSINT feeds drive stochastic in-sim events
+- **Scalable Oversight** — Bayesian risk scoring triggers interventions before runaway escalation
+- **Tool Use** — agents call `query_intel`, `propose_negotiation`, `impose_sanctions`, etc.
+- **Multi-component Rewards** — coalition stability, escalation penalty, market impact, belief alignment
+
+## Stack
+
+| Layer    | Tech                                                 |
+| -------- | ---------------------------------------------------- |
+| Frontend | Next.js 16 · Tailwind v4 · Mapbox GL · Framer Motion |
+| Backend  | FastAPI · OpenEnv Core · NumPy                       |
+| Infra    | Docker · Bun · uv                                    |
+
+## Quick Start
+
+```bash
+# Frontend
+bun install
+bun run dev          # → http://localhost:3000
+
+# Backend
+cd backend
+uv sync
+source .venv/bin/activate
+uvicorn trenches_env.server:app --reload --port 8000
+```
+
+Set your environment variables in `.env.local`:
+
+```
+NEXT_PUBLIC_MAPBOX_TOKEN=...
+NEXT_PUBLIC_API_URL=http://localhost:8000
+```
+
+## Project Structure
+
+```
+trenches/
+├── app/              # Next.js app router + API routes
+├── src/
+│   ├── components/   # Globe, NewsFeed, ActivityLog, ChatPanel
+│   ├── hooks/        # React hooks
+│   └── lib/          # Types, utils, bootstrap
+├── backend/
+│   ├── src/          # FastAPI server, OpenEnv environment
+│   └── tests/        # Backend test suite
+├── entities/         # Agent identity configs (US, Israel, Iran, etc.)
+└── scripts/          # Utility scripts
+```
+
+## License
+
+MIT

RL.md

@@ -0,0 +1,354 @@
+# RL.md: Reinforcement Learning Mechanics in Fog of War Diplomacy Simulator
+
+This document describes the RL design for the Fog of War Diplomacy Simulator and, critically, the boundary between what OpenEnv supports directly and what this project must implement on top of OpenEnv.
+
+The short version:
+
+- OpenEnv is the environment packaging and execution layer.
+- The crisis simulator, reward model, six-agent orchestration, and oversight logic are project code.
+- CTDE, MAPPO, PPO, GRPO, TRL, and RLlib are training-stack choices outside OpenEnv itself.
+
+The current repository now includes a native OpenEnv-facing adapter layer around the simulator, while still retaining the older session-oriented FastAPI API used by the dashboard.
+
+---
+
+## OpenEnv Support Boundary
+
+### What OpenEnv directly supports
+
+OpenEnv gives us the environment contract and runtime surface:
+
+- An async environment interface built around `reset()` and `step(action)`.
+- Environment-side `Action`, `Observation`, and `State` models.
+- Client-side `StepResult` objects that expose:
+  - `observation`
+  - scalar `reward`
+  - `done`
+- Client access through `EnvClient`, typically from a Docker image or a deployed URL.
+- Containerized environment packaging.
+- Optional custom UI support.
+
+In other words, OpenEnv is well-suited to hosting the simulator and stepping it remotely, but it is not a multi-agent RL trainer and it does not natively provide Gymnasium-style multi-agent dict rewards or observations.
+
+### What this project layers on top
+
+The following are project-level features, not native OpenEnv guarantees:
+
+- Six-agent world state with partial observability.
+- Joint action parsing and per-agent observation projection.
+- Per-agent reward vectors and reward breakdowns.
+- Oversight risk scoring and corrective interventions.
+- Curriculum design, CTDE, MAPPO, PPO, GRPO, TRL, and RLlib integration.
+- Live data ingestion plans, RSS/Telegram/video source routing, and demo-only live mode.
+- The current FastAPI session API in this repo.
+
+### Important design consequence
+
+OpenEnv expects one action in and one scalar reward out per `step()`. For this simulator, that means one of two patterns:
+
+1. Encode the full six-agent joint move as a single structured OpenEnv action, then expose per-agent details through custom observation fields and `state()`.
+2. Build a higher-level coordinator outside OpenEnv that manages multiple policies against one shared world state.
+
+For the MVP and the current backend shape, pattern `1` is the cleaner fit.
+
+---
+
+## OpenEnv-Aligned Environment Contract
+
+The OpenEnv adapter for this project should look conceptually like this:
+
+```python
+from openenv.core import Action, Environment, Observation
+from openenv.core.env_server.types import State
+
+
+class JointAction(Action):
+    actions: dict[str, dict]
+
+
+class DiplomacyObservation(Observation):
+    training_agent: str
+    reward_breakdown: dict
+
+
+class DiplomacyState(State):
+    training_agent: str
+    world: dict
+
+
+class DiplomacyEnvironment(Environment):
+    @property
+    def state(self) -> DiplomacyState:
+        return DiplomacyState(
+            episode_id=self.session_id,
+            step_count=self.turn,
+            training_agent=self.training_agent,
+            world=self._serialize_world(self.world),
+        )
+
+    async def reset(self):
+        self.world = self._initial_world()
+        return self._build_observation(self.world)
+
+    async def step(self, action):
+        # `action` is a structured joint action for all six agents.
+        joint_actions = self._decode_joint_action(action)
+
+        self._apply_actions(self.world, joint_actions)
+        oversight = self._compute_oversight(self.world, joint_actions)
+        self._apply_oversight(self.world, oversight)
+
+        per_agent_rewards = self._compute_rewards(self.world, joint_actions)
+
+        # OpenEnv needs a scalar reward. The trainer/coordinator chooses
+        # which policy is being optimized for this rollout.
+        scalar_reward = per_agent_rewards[self.training_agent]
+
+        return DiplomacyObservation(
+            reward=scalar_reward,
+            done=self._is_done(self.world),
+            training_agent=self.training_agent,
+            reward_breakdown=per_agent_rewards[self.training_agent],
+        )
+```
+
+This is the key correction relative to earlier drafts: the simulator may compute rich multi-agent state internally, but the OpenEnv-facing `step()` still emits a single `Observation`, and the client sees a scalar-reward `StepResult`.
+
+---
+
+## Relationship to the Current Repo
+
+The current backend environment is not yet a direct OpenEnv environment. Today it is a custom simulator plus FastAPI session layer that exposes:
+
+- session creation/reset
+- live-mode toggles
+- turn stepping
+- structured per-agent observations and reward breakdowns
+
+That is still useful. It means the simulator logic is already mostly in place, and the OpenEnv integration work becomes an adapter task rather than a full rewrite.
+
+The practical implication is:
+
+- `backend/src/trenches_env/env.py` is the world simulator.
+- OpenEnv should wrap or call into that simulator.
+- `RL.md` must not describe current behavior as if the repo is already using OpenEnv natively.
+
+---
+
+## Reward System: Project Logic on Top of OpenEnv
+
+Rewards remain a project design choice. OpenEnv does not impose the reward formula; it only transports the scalar training reward through `Observation.reward` and exposes richer environment state through `state()`.
+
+### Design constraints
+
+- Reward computation happens after action processing and state updates.
+- Each component should be normalized before weighting.
+- Oversight should modify environment state, not rescale rewards.
+- Hidden incentives should not be used as a direct reward signal.
+- Full per-agent reward breakdowns can live in simulator state or custom observation fields even though the outward training reward is scalar.
+
+### Core Reward Formula
+
+Per timestep $t$, for each agent $i$:
+
+$$r_t^i = w_1 \cdot \hat{C}_t^i + w_2 \cdot \hat{E}_t^i + w_3 \cdot \hat{M}_t^i + w_4 \cdot \hat{B}_t^i$$
+
+where each component is normalized independently to `[-1, 1]` before aggregation.
+
+### Components
+
+- $C_t$: Coalition stability.
+- $E_t$: Escalation penalty using an EMA of tension level.
+- $M_t$: Market/economic gain from observable stress reduction.
+- $B_t$: Behavioral consistency from observable action and rationale traces rather than hidden oracle state.
+
+### OpenEnv-facing reward rule
+
+Internally we may compute:
+
+```python
+per_agent_rewards = {
+    "us": ...,
+    "israel": ...,
+    "iran": ...,
+    "hezbollah": ...,
+    "gulf": ...,
+    "oversight": ...,
+}
+```
+
+But the OpenEnv adapter should emit:
+
+```python
+DiplomacyObservation(
+    reward=per_agent_rewards[active_training_agent],
+    done=done,
+    reward_breakdown=per_agent_rewards[active_training_agent],
+)
+```
+
+That keeps the simulator expressive without claiming unsupported native multi-agent reward output.
+
+---
+
+## Oversight: OpenEnv-Compatible Placement
+
+The previous Gymnasium-wrapper framing was too specific. OpenEnv does not give us a native `gym.Wrapper` abstraction, so oversight should be implemented as part of the simulator transition or as a thin project-side interceptor around the environment.
+
+An OpenEnv-compatible pattern is:
+
+```python
+async def step(self, action):
+    joint_actions = self._decode_joint_action(action)
+    self._apply_actions(self.world, joint_actions)
+
+    oversight = self._compute_oversight(self.world, joint_actions)
+    if oversight["triggered"]:
+        self._apply_oversight(self.world, oversight)
+
+    per_agent_rewards = self._compute_rewards(self.world, joint_actions)
+
+    return DiplomacyObservation(
+        reward=per_agent_rewards[self.training_agent],
+        done=self._is_done(self.world),
+        reward_breakdown=per_agent_rewards[self.training_agent],
+    )
+```
+
+This preserves the intended semantics:
+
+- oversight changes the transition
+- reward is not rescaled
+- intervention details remain inspectable through `state()` or custom observation fields
+
+---
+
+## Multi-Agent Training Architecture
+
+### What OpenEnv does not do for us
+
+OpenEnv is not a built-in multi-agent trainer. It does not natively provide:
+
+- CTDE
+- MAPPO
+- GRPO
+- centralized critics
+- per-agent replay buffers
+- RLlib or TRL integration
+
+Those belong in the training harness.
+
+### Recommended architecture
+
+Use OpenEnv as the rollout environment, then place the multi-agent trainer above it:
+
+1. OpenEnv hosts one simulator instance.
+2. Each rollout step carries a structured joint action for all six agents.
+3. The simulator computes the full per-agent reward vector.
+4. The OpenEnv adapter returns the scalar reward for the currently optimized policy and exposes richer diagnostics through `state()` and custom observation fields.
+5. The trainer reconstructs per-agent trajectories from state snapshots and session traces.
+
+This works for:
+
+- independent PPO baselines
+- CTDE with a centralized critic
+- MAPPO-style actor-critic training
+- GRPO-style grouped rollout training
+
+But again: these are external training choices, not native OpenEnv features.
+
+---
+
+## Algorithm Choice
+
+### CTDE
+
+CTDE remains a sound design choice for this simulator because agents interact in a shared partially observable world. The centralized critic is trainer-side logic and does not require native OpenEnv support.
+
+### GRPO vs PPO
+
+GRPO is still a plausible fit for sparse long-horizon signals, but the doc should treat it as an external training-stack choice. OpenEnv will not provide `GRPOTrainer`; it only supplies environment rollouts.
+
+PPO remains a valid baseline, especially for shorter or denser curriculum stages.
+
+### Practical recommendation
+
+Phrase the implementation plan as:
+
+- OpenEnv for rollout generation
+- custom trainer or external framework for policy updates
+- state snapshots and session traces for reconstructing per-agent returns
+
+not as:
+
+- OpenEnv natively handles GRPO or multi-agent PPO
+
+---
+
+## Training Flow
+
+1. Package the simulator as an OpenEnv environment or connect to it through `EnvClient.from_url(...)` once deployed.
+2. Reset the environment to get the initial joint observation.
+3. Query all six policies to produce one joint action.
+4. Step the environment and capture:
+   - next observation
+   - scalar reward for the active policy
+   - done flag
+   - environment state with per-agent rewards, oversight data, and world trace
+5. Reconstruct trainer-side trajectories for CTDE, MAPPO, PPO, or GRPO.
+6. Keep all training episodic and reproducible.
+
+### Live mode rule
+
+Live mode is inference/demo only.
+
+Training should use:
+
+- episodic rollouts
+- fixed seeds where needed
+- replayed or sampled event bundles
+
+Training should not depend on live RSS/Telegram/video streams if reproducibility matters.
+
+That means the earlier idea of "Stage 3 training with live RSS injection" should be replaced by "Stage 3 training with replayed sampled event bundles and oversight enabled."
+
+---
+
+## Evaluation
+
+These evaluation targets are still reasonable project metrics:
+
+| Metric | Definition | Target |
+|---|---|---|
+| Avg reward/episode | Mean $\sum_t r_t$ over recent episodes | Upward trend |
+| De-escalation rate | % of episodes ending with tension < 30 | > 60% |
+| Oversight intervention rate | Interventions per episode | Decreasing over training |
+| Behavioral consistency | Mean $B_t$ across agents | > 0.7 |
+| Coalition durability | Avg turns before first betrayal | > 200 |
+
+But the trainer must compute them from rollout traces. OpenEnv will not provide these metrics automatically.
+
+---
+
+## Known Challenges
+
+- Multi-agent credit assignment is trainer complexity, not environment complexity.
+- If training data comes from changing live sources, reproducibility degrades fast.
+- Reward hacking remains a real risk.
+- OpenEnv scalar reward output means the adapter boundary must be explicit and carefully documented.
+
+---
+
+## Summary of Corrections
+
+| Earlier claim | Corrected statement |
+|---|---|
+| OpenEnv extends Gymnasium with dict observations/actions and done-truncated-info tuples | OpenEnv uses its own async `reset()` / `step()` contract with typed `Action`/`Observation`/`State`; the client exposes `StepResult` with scalar reward |
+| OpenEnv natively handles six-agent dict rewards and observations | Multi-agent orchestration is project logic layered on top of OpenEnv |
+| OpenEnv envs are raw FastAPI `/reset` and `/step` servers | This repo uses FastAPI today, but OpenEnv itself exposes an environment contract plus `EnvClient` transport |
+| OpenEnv directly supports CTDE, MAPPO, GRPO, TRL, or RLlib | Those are trainer-side integrations outside OpenEnv |
+| Oversight should be a Gym wrapper | In this project it should be implemented inside the simulator transition or a thin project-side interceptor |
+| Stage 3 training can use live RSS injection | Live mode is demo-only; training should remain episodic and reproducible |
+| The current repo is already a native OpenEnv environment | The current repo now includes a native OpenEnv-facing adapter while still keeping the session-oriented dashboard API |
+
+This version is the correct mental model: OpenEnv is the execution shell for the simulator, while nearly all of the interesting multi-agent RL behavior is our own design sitting above that shell.

TODO.md

@@ -0,0 +1,49 @@
+# Trenches — TODO
+
+## Reward System
+
+- [ ] **Event-prediction RL rewards** — when a real-world event occurs and an agent's prior prediction/action aligns with it, grant a positive reward signal. This closes the loop between live data ingestion and agent learning.
+  - Track agent predictions per turn (e.g., "Iran will retaliate within 2 turns")
+  - Compare predictions against actual events that fire from RSS/OSINT feeds
+  - Reward = f(prediction accuracy, lead time, specificity)
+  - Only **real events** (from live feeds or env-generated stochastic events) impact the reward signal
+
+- [ ] **Chat-injected fake events** — allow manual event injection via the chat panel that influences agent behavior but does **not** affect reward calculations.
+  - Tag chat-injected events with `source: "manual"` vs real events with `source: "live"` or `source: "env"`
+  - Agents still react to fake events (observe and act), but the reward function filters them out
+  - Useful for demos, testing edge cases, and probing agent behavior without polluting the training signal
+
+## UI / Frontend
+
+- [ ] **Event timeline with time control** — scrubber bar (like a video editor) for navigating, rewinding, and branching the simulation
+  - **Scrubber bar** at the bottom: drag to jump to any turn/timestamp, play/pause, rewind, fast-forward
+  - Two event types on the timeline: **predictions** (agent forecasts) and **actuals** (confirmed real events)
+  - Predictions that matched actual outcomes are visually linked; incorrect ones shown faded
+  - **Branching**: when a fake scenario is injected via chat, the timeline forks — you can scrub back to before the injection and see the "what if" branch vs the real timeline
+  - Playback controls: step-by-step (turn by turn), continuous playback at adjustable speed
+  - Markers on the scrubber for key events (escalations, interventions, injected scenarios)
+  - Filterable by agent, event type, and time range
+  - Feeds into the reward system — correct predictions on the timeline = positive RL signal
+
+- [x] Merge tension/stats pills into top bar
+- [x] Disable text selection on floating panels
+- [x] Remove Mapbox logo
+- [x] Clean up README
+
+## Infrastructure
+
+- [x] Push to HF Space (`AlazarM/trenches`)
+- [ ] Add `NEXT_PUBLIC_MAPBOX_TOKEN` as HF Space secret
+
+## Post-Training
+
+- [x] 6 synthetic seed replay datasets (in `synthetic_historical_replays/`)
+- [x] Training CLI with GRPO, hyperparameter args, checkpointing
+- [x] Local smoke test (tiny-gpt2, US + Israel)
+- [x] HF GPU smoke test on T4 ([trenches-training-smoke](https://huggingface.co/spaces/AlazarM/trenches-training-smoke))
+- [x] All 6 entity models → `Qwen/Qwen3-8B` (no quantization)
+- [x] Historical data collection pipeline (GDELT → replay JSON)
+- [ ] Run historical collector for all 6 entities
+- [ ] Curator-review collected replay data
+- [ ] Spin up 6 HF A100 Spaces for production training
+- [ ] Evaluation/baseline reporting

TOOLS.md

@@ -0,0 +1,137 @@
+# TOOLS.md: Agent Tools and Function-Calling Interface in Fog of War Diplomacy Simulator
+
+This document details the **tools** available to the 6 agents in the Fog of War Diplomacy Simulator. These tools enable agents to interact with the environment, query personalized intelligence feeds (from World Monitor integration), perform actions that affect the world state, and gather information consistent with their partial-observability constraints.
+
+Tools are implemented as **text-based function-calling** within each agent's LLM inference loop (using Hugging Face Transformers or similar). When an agent needs information or wants to act, it outputs a structured function call in its response (e.g., JSON or XML-like format). The OpenEnv environment parses these calls, executes them, and injects results back into the next observation.
+
+This design:
+- Reinforces **theory-of-mind** (agents must infer when others might use tools)
+- Supports **tool-use fine-tuning** during RL post-training
+- Maintains **partial observability** (tools return only agent-specific data)
+- Aligns with **entity identity** (some tools are role-exclusive)
+
+## General Tool Usage Rules
+
+- **Invocation Format**: Agents output function calls in a parseable format, e.g.:
+  ```json
+  {
+    "tool": "query_intel",
+    "parameters": {
+      "keywords": "US_polls Iran_strike",
+      "source": "polymarket"
+    }
+  }
+  ```
+  or XML-style if preferred by the prompt.
+
+- **Execution**: In `step(actions)`, the env:
+    1. Parses tool calls from agent text output
+    2. Validates agent permissions (e.g., Iran cannot use "impose_sanctions")
+    3. Executes (queries World Monitor API, simulates action outcome)
+    4. Returns result in next obs dict (e.g., `obs["US"]["tool_result"]`)
+
+- **Cost/Cooldown**: Most tools have simulated "cost" (e.g., -0.1 reward for heavy queries) or cooldown (e.g., query every 3 turns) to prevent spam.
+
+- **Consistency**: Tools pull from World Monitor APIs (deployed on Vercel/Railway) → filtered JSON snippets → injected into prompt history for persistent context.
+
+## Common Tools (Available to All Agents)
+
+1. **query_intel**
+    - Description: Request filtered intelligence from World Monitor feeds.
+    - Parameters:
+        - `keywords`: string (space-separated search terms, e.g., "oil Hormuz strike")
+        - `source`: optional string (e.g., "polymarket", "acled", "telegram_osint", "commodity_dashboard")
+        - `time_range`: optional string ("last_hour", "last_day")
+    - Returns: Dict of snippets/headlines (e.g., {"headline": "...", "sentiment": 0.6, "source": "..."})
+    - Usage: Core tool for maintaining situational awareness; agents decide what to query based on current tension.
+
+2. **analyze_belief**
+    - Description: Infer hidden incentives/beliefs of another agent (theory-of-mind).
+    - Parameters:
+        - `target_agent`: string (e.g., "Iran")
+        - `evidence`: string (short summary of observed actions)
+    - Returns: Dict {"inferred_incentive": "...", "confidence": 0.72}
+    - Usage: Used to improve \( B_t \) reward component.
+
+3. **propose_negotiation**
+    - Description: Send a diplomatic proposal to one or more agents.
+    - Parameters:
+        - `recipients`: list[string] (e.g., ["US", "Gulf Coalition"])
+        - `proposal_text`: string (e.g., "Ceasefire in exchange for sanctions relief")
+    - Returns: Dict {"sent": true, "acknowledged_by": [...], "immediate_response": "..."}
+    - Usage: Forms coalitions; can be deceptive.
+
+## Agent-Specific Tools
+
+### 1. US (Trump Admin / CENTCOM)
+- **impose_sanctions**
+    - Parameters: `target`: string, `severity`: float (0-1)
+    - Effect: Increases tension for target, boosts US \( M_t \), risks backlash if overused.
+- **deploy_assets**
+    - Parameters: `location`: string (e.g., "Gulf"), `type`: string ("carrier", "cyber")
+    - Effect: Deters escalation, visible to allies.
+- **query_polls**
+    - Shortcut to `query_intel(keywords="US approval rating Polymarket")`
+
+### 2. Israel (Netanyahu / IDF)
+- **launch_precise_strike**
+    - Parameters: `target`: string (e.g., "IRGC facility"), `risk_level`: float
+    - Effect: High escalation potential, strong \( E_t \) penalty if civilian risk high.
+- **activate_iron_dome**
+    - Parameters: `region`: string
+    - Effect: Reduces damage from incoming rockets (reduces \( E_t \) penalty).
+- **query_border_alerts**
+    - Shortcut: `query_intel(keywords="OREF Lebanon rocket")`
+
+### 3. Iran (IRGC / Interim Leadership)
+- **activate_proxy**
+    - Parameters: `proxy`: string (e.g., "Hezbollah"), `action_type`: string ("drone", "cyber")
+    - Effect: Asymmetric retaliation, lower escalation visibility.
+- **threaten_hormuz**
+    - Parameters: `severity`: float
+    - Effect: Spikes global oil price, strong \( M_t \) impact for Gulf.
+- **query_proxy_status**
+    - Shortcut: `query_intel(keywords="Hezbollah militia Telegram")`
+
+### 4. Hezbollah (Proxy Swarm Leader)
+- **launch_drone_swarm**
+    - Parameters: `target`: string, `scale`: int (1-10)
+    - Effect: High asymmetric damage, visible to Israel.
+- **evade_detection**
+    - Parameters: None
+    - Effect: Reduces probability of being traced back to Iran.
+- **query_border_streams**
+    - Shortcut: `query_intel(keywords="MTV Lebanon webcam Hezbollah")`
+
+### 5. Gulf Coalition (Saudi/UAE/Qatar)
+- **adjust_oil_output**
+    - Parameters: `delta`: float (-1 to +1)
+    - Effect: Stabilizes or shocks markets, directly affects \( M_t \).
+- **host_base_access**
+    - Parameters: `ally`: string (e.g., "US")
+    - Effect: Strengthens coalition, visible to Iran.
+- **query_market_impact**
+    - Shortcut: `query_intel(keywords="oil price Hormuz Bloomberg")`
+
+### 6. Oversight Agent (Fleet AI Meta-Layer)
+- **generate_explanation**
+    - Parameters: `target_action`: string, `agent`: string
+    - Returns: Natural language explanation + risk score.
+- **calculate_risk**
+    - Parameters: `action`: dict
+    - Returns: Float risk score (0-1) using belief propagation formula.
+- **intervene**
+    - Parameters: `target_agent`: string, `action`: string ("force_rethink", "audit_beliefs")
+    - Effect: Scales reward by 0.5 or forces re-action.
+- **query_global_synthesis**
+    - Shortcut: `query_intel(scope="global", keywords="hotspot escalation")`
+
+## Implementation Notes
+
+- **Tool Parsing**: Use structured output prompting (e.g., "Always respond with JSON tool call if using a tool") + regex/JSON parser in env.
+- **Tool Result Injection**: Results appended to prompt history (e.g., "Tool result: [JSON]") for context window management.
+- **RL Fine-Tuning**: Reward tool usage that leads to high entity-aligned outcomes (e.g., US sanctions → coalition strength).
+- **Debugging**: Log all tool calls/results in dashboard for judging.
+- **Security**: Validate parameters server-side to prevent invalid actions.
+
+This toolset empowers agents to act intelligently within their roles while maintaining the simulator's core challenge: operating under incomplete, live-fed information in a high-stakes multi-agent crisis.

TRAINING_PLAN.md

@@ -0,0 +1,209 @@
+# Trenches Training Plan
+
+This document is the working plan for the historical prediction training setup.
+
+## Goal
+
+Train six separate entity models in the same OpenEnv-backed simulator so they do two things at each turn:
+
+1. choose an action
+2. predict what will happen next
+
+The core idea is:
+
+- the environment replays a real historical event window
+- each model only sees information available up to that point in time
+- each model generates a predicted future timeline
+- the environment later reveals what actually happened
+- reward is based partly on whether the model predicted correctly
+
+Target training window:
+
+- 2025
+- 2026
+
+## Intended Training Shape
+
+Two timelines exist at once:
+
+1. `ground_truth_timeline`
+   The real historical sequence of events.
+
+2. `predicted_timeline`
+   What the entity believed would happen next, based only on available information at that turn.
+
+The environment reward should compare the second timeline against the first.
+
+## Why OpenEnv Is The Right Boundary
+
+OpenEnv is the environment interface, not the trainer itself.
+
+That is exactly what we need:
+
+- `reset()` starts a historical replay episode at a chosen point
+- `step()` accepts an entity output
+- the env advances time
+- the env computes reward from action quality and prediction quality
+
+Training should happen outside the backend with something like Hugging Face TRL.
+
+## What Exists Already
+
+The current backend already has:
+
+- an OpenEnv environment boundary
+- session and step logic
+- per-entity observations
+- per-entity rewards
+- latent state
+- latent events
+- belief state
+- source projection
+- scenario and benchmark support
+- a structured `Prediction` schema
+- prediction storage and scoring in session state
+- replay mode driven by historical event timestamps
+- a bundled set of 6 synthetic seed replay datasets (in `synthetic_historical_replays/`)
+- a replay-aware TRL/OpenEnv CLI training loop
+- a historical data collection pipeline (GDELT → replay JSON)
+
+## What Is Missing
+
+The backend does not yet have:
+
+- a larger curated truth dataset beyond the bundled synthetic seed replays
+- a proper evaluation report for prediction quality
+- baselines and train/eval split reporting
+
+## Planned Implementation Order
+
+### Phase 1: Historical Replay Foundation
+
+1. Define a normalized historical event schema.
+2. Build a replay dataset for selected 2025-2026 events.
+3. Add historical replay mode to the backend environment.
+4. Ensure agents only see information available before each replay timestamp.
+
+### Phase 2: Prediction Contract
+
+1. Add a structured `Prediction` object for each agent.
+2. Extend agent outputs so a turn can include:
+   - `action`
+   - `prediction`
+3. Store prediction history in session state.
+
+### Phase 3: Reward Logic
+
+1. Add reward terms for:
+   - correct topic
+   - correct actor
+   - correct target
+   - correct timing window
+   - correct severity band
+   - confidence calibration
+2. Penalize:
+   - confident false predictions
+   - vague predictions
+   - repeated contradiction with real history
+3. Exclude fake/manual events from training reward.
+
+### Phase 4: Training Loop
+
+1. Train one entity first.
+2. Use OpenEnv + HF TRL.
+3. Prove a working historical replay training loop.
+4. Scale to six entity-specific models.
+
+### Phase 5: Evaluation
+
+1. Build evaluation metrics for forecast quality.
+2. Compare against simple baselines.
+3. Separate train and eval windows.
+4. Report before/after performance.
+
+## Recommended Minimal Event Schema
+
+Each historical event should have:
+
+- `event_id`
+- `timestamp`
+- `topic`
+- `region`
+- `actors`
+- `targets`
+- `severity`
+- `summary`
+- `source_type`
+- `confirmed`
+- `tags`
+
+## Recommended Prediction Schema
+
+Each prediction should have:
+
+- `prediction_id`
+- `agent_id`
+- `turn`
+- `timestamp`
+- `topic`
+- `predicted_actor`
+- `predicted_target`
+- `time_horizon_turns`
+- `expected_severity`
+- `confidence`
+- `summary`
+- `rationale`
+
+## Critical Design Rules
+
+1. No leakage.
+   The model must never see future information.
+
+2. Real events and fake events must be separated.
+   Manual events can drive behavior but must not drive training reward.
+
+3. Action and prediction should remain separate outputs.
+   Mixing them into one blob will make both training and debugging worse.
+
+4. Train one entity first before scaling to six.
+   Prove the loop on one actor before multiplying complexity.
+
+5. Evaluate against baselines.
+   Otherwise there is no evidence the training helped.
+
+## Suggested First Entity
+
+Start with:
+
+- `us`
+
+Why:
+
+- broad observation surface
+- strong strategic tradeoffs
+- likely easiest to benchmark against known 2025-2026 developments
+
+## Known Future Work
+
+After the first working replay-training loop:
+
+- train all six entities
+- compare model families
+- add branch evaluation for counterfactual timelines
+- add replay UI for predicted vs actual timeline alignment
+
+## Working Status
+
+Current status:
+
+- all 6 synthetic seed replay datasets created and bundled (in `synthetic_historical_replays/`)
+- base model: `Qwen/Qwen3-8B` (shared across all entities, no quantization)
+- OpenEnv step accepts separate `action` and `prediction`
+- forecast reward is blended into entity reward on replay steps
+- TRL CLI training path is implemented and smoke-tested end to end
+- local smoke tests pass for US + Israel entities (tiny-gpt2)
+- HF GPU smoke test passed on T4 ([trenches-training-smoke](https://huggingface.co/spaces/AlazarM/trenches-training-smoke))
+- historical data collection pipeline implemented (GDELT → replay JSON)
+- multi-entity scaling to A100 and evaluation still pending
+
+This file should be updated as the forecasting/replay training system is built.

app/api/health/route.ts

@@ -0,0 +1,10 @@
+import { NextResponse } from "next/server";
+
+export const runtime = "edge";
+
+export function GET() {
+  return NextResponse.json({
+    status: "ok",
+    service: "trenches-vercel-api",
+  });
+}

app/api/source-registry/route.ts

@@ -0,0 +1,12 @@
+import { NextResponse } from "next/server";
+
+import { getAllSources, validateSourceRegistry } from "../../../src/lib/data-sources";
+
+export const runtime = "edge";
+
+export function GET() {
+  return NextResponse.json({
+    sources: getAllSources(),
+    validation: validateSourceRegistry(),
+  });
+}

app/globals.css

@@ -0,0 +1,159 @@
+@import url("https://fonts.googleapis.com/css2?family=Oxanium:wght@200..800&family=Source+Code+Pro:wght@200..900&display=swap");
+
+@import "tailwindcss";
+
+:root {
+  --card: #b0b0b0;
+  --ring: #b71c1c;
+  --input: #505050;
+  --muted: #b8b8b8;
+  --accent: #4682b4;
+  --border: #505050;
+  --radius: 0px;
+  --chart-1: #b71c1c;
+  --chart-2: #556b2f;
+  --chart-3: #4682b4;
+  --chart-4: #ff6f00;
+  --chart-5: #8d6e63;
+  --popover: #b0b0b0;
+  --primary: #b71c1c;
+  --sidebar: #b0b0b0;
+  --spacing: 0.25rem;
+  --font-mono: "Source Code Pro", monospace;
+  --font-sans: "Oxanium", sans-serif;
+  --secondary: #556b2f;
+  --background: #cccccc;
+  --font-serif: ui-serif, Georgia, Cambria, "Times New Roman", Times, serif;
+  --foreground: #1f1f1f;
+  --destructive: #ff6f00;
+  --shadow-blur: 4px;
+  --shadow-color: hsl(0 0% 0%);
+  --sidebar-ring: #b71c1c;
+  --shadow-spread: 0px;
+  --letter-spacing: 0em;
+  --shadow-opacity: 0.4;
+  --sidebar-accent: #4682b4;
+  --sidebar-border: #505050;
+  --card-foreground: #1f1f1f;
+  --shadow-offset-x: 0px;
+  --shadow-offset-y: 2px;
+  --sidebar-primary: #b71c1c;
+  --muted-foreground: #4a4a4a;
+  --accent-foreground: #ffffff;
+  --popover-foreground: #1f1f1f;
+  --primary-foreground: #ffffff;
+  --sidebar-foreground: #1f1f1f;
+  --secondary-foreground: #ffffff;
+  --destructive-foreground: #000000;
+  --sidebar-accent-foreground: #ffffff;
+  --sidebar-primary-foreground: #ffffff;
+}
+
+.dark {
+  --card: #2a2a2a;
+  --ring: #e53935;
+  --input: #4a4a4a;
+  --muted: #252525;
+  --accent: #64b5f6;
+  --border: #4a4a4a;
+  --radius: 0px;
+  --chart-1: #e53935;
+  --chart-2: #689f38;
+  --chart-3: #64b5f6;
+  --chart-4: #ffa000;
+  --chart-5: #a1887f;
+  --popover: #2a2a2a;
+  --primary: #e53935;
+  --sidebar: #141414;
+  --spacing: 0.25rem;
+  --font-mono: "Source Code Pro", monospace;
+  --font-sans: "Oxanium", sans-serif;
+  --secondary: #689f38;
+  --background: #1a1a1a;
+  --font-serif: ui-serif, Georgia, Cambria, "Times New Roman", Times, serif;
+  --foreground: #e0e0e0;
+  --destructive: #ffa000;
+  --shadow-blur: 5px;
+  --shadow-color: hsl(0 0% 0%);
+  --sidebar-ring: #e53935;
+  --shadow-spread: 0px;
+  --letter-spacing: 0em;
+  --shadow-opacity: 0.6;
+  --sidebar-accent: #64b5f6;
+  --sidebar-border: #4a4a4a;
+  --card-foreground: #e0e0e0;
+  --shadow-offset-x: 0px;
+  --shadow-offset-y: 2px;
+  --sidebar-primary: #e53935;
+  --muted-foreground: #a0a0a0;
+  --accent-foreground: #000000;
+  --popover-foreground: #e0e0e0;
+  --primary-foreground: #ffffff;
+  --sidebar-foreground: #e0e0e0;
+  --secondary-foreground: #000000;
+  --destructive-foreground: #000000;
+  --sidebar-accent-foreground: #000000;
+  --sidebar-primary-foreground: #ffffff;
+}
+
+@theme inline {
+  --color-card: var(--card);
+  --color-ring: var(--ring);
+  --color-input: var(--input);
+  --color-muted: var(--muted);
+  --color-accent: var(--accent);
+  --color-border: var(--border);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --color-popover: var(--popover);
+  --color-primary: var(--primary);
+  --color-sidebar: var(--sidebar);
+  --color-secondary: var(--secondary);
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-destructive: var(--destructive);
+  --color-sidebar-ring: var(--sidebar-ring);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-card-foreground: var(--card-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --font-sans: var(--font-sans);
+  --font-mono: var(--font-mono);
+  --font-serif: var(--font-serif);
+  --spacing: var(--spacing);
+}
+
+* {
+  box-sizing: border-box;
+  border-color: var(--border);
+}
+
+body {
+  font-family: var(--font-sans);
+  background: var(--background);
+  color: var(--foreground);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+/* Hide Mapbox branding */
+.mapboxgl-ctrl-logo,
+.mapboxgl-ctrl-attrib {
+  display: none !important;
+}

app/layout.tsx

@@ -0,0 +1,24 @@
+import type { Metadata } from "next";
+
+import "./globals.css";
+import "mapbox-gl/dist/mapbox-gl.css";
+
+export const metadata: Metadata = {
+  title: "Trenches — Fog of War Diplomacy Simulator",
+  description:
+    "Multi-agent geopolitical crisis simulator with live intelligence feeds and Mapbox globe visualization.",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en" className="dark">
+      <body className="min-h-screen overflow-hidden antialiased">
+        {children}
+      </body>
+    </html>
+  );
+}

app/page.tsx

@@ -0,0 +1,5 @@
+import GlobePage from "@/src/components/GlobePage";
+
+export default function HomePage() {
+  return <GlobePage />;
+}

backend/Dockerfile

@@ -0,0 +1,19 @@
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV TRENCHES_ENTITIES_ROOT=/app/entities
+
+WORKDIR /app
+
+COPY backend/pyproject.toml backend/README.md ./backend/
+COPY backend/src ./backend/src
+COPY entities ./entities
+
+WORKDIR /app/backend
+
+RUN pip install --no-cache-dir .
+
+EXPOSE 8000
+
+CMD ["python", "-m", "trenches_env.server"]

backend/HOW_POST_TRAINING_WORKS.md

@@ -0,0 +1,127 @@
+# How Post-Training Works: Steps, Data, and Rewards
+
+## The Loop in One Sentence
+
+Each GRPO step resets the environment at a random replay position, generates 16 completions, scores them against the real timeline, and updates the model to favor better responses.
+
+## Steps vs Data
+
+You have **10 replay events** and **100 GRPO steps**. They don't map 1:1.
+
+```
+Step 1:  reset() → random position in 10-event timeline
+         → generate 16 completions
+         → score all 16 against the next revealed event
+         → GRPO update (reinforce good, suppress bad)
+
+Step 2:  reset() → different random position
+         → generate 16 completions → score → update
+
+...
+
+Step 100: same process
+```
+
+Across 100 steps × 16 generations = **1,600 rollouts** through those 10 events.
+Each event seen ~160 times from different angles.
+
+## What The Model Sees (Input)
+
+Built by `_render_observation_prompt()` from the replay timeline:
+
+```
+You are training the us policy in the Trenches OpenEnv historical replay
+environment. Return strict JSON only.
+
+Training agent: us
+Turn: 3
+
+Historical brief:
+- Commercial shipping insurers flag elevated Gulf transit risk near Hormuz.
+- Washington reinforces maritime protection with Gulf partners.
+- A renewed cross-border volley drives northern-front alerting.
+
+Public brief:
+- Gulf transit risk elevated near Hormuz.
+- Coalition deconfliction messaging underway.
+
+Private brief:
+- Domestic approval is sensitive to prolonged escalation.
+- Forward naval posture can deter but also spike market stress.
+
+Strategic state:
+- regional_access: 74.5
+- shipping_security: 72.0
+- domestic_support: 63.9
+- force_posture: 76.0
+
+Allowed actions: hold, negotiate, sanction, strike, defend, intel_query, mobilize, deceive
+```
+
+## What The Model Returns (Output)
+
+```json
+{
+  "action": {
+    "type": "sanction",
+    "target": "iran",
+    "summary": "Target proxy logistics channels to degrade corridor sustainment."
+  },
+  "prediction": {
+    "topic": "domestic",
+    "predicted_actor": "us",
+    "predicted_target": "iran",
+    "time_horizon_turns": 1,
+    "expected_severity": "medium",
+    "confidence": 0.7,
+    "summary": "Washington will announce a sanctions package aimed at proxy sustainment.",
+    "rationale": "Escalating Hormuz pressure creates political pressure for economic action."
+  }
+}
+```
+
+## Ground Truth (Revealed Event)
+
+The environment reveals the next event from `us_synthetic_seed_2025_2026.json`:
+
+```json
+{
+  "event_id": "evt-2025-04-us-sanctions-package",
+  "timestamp": "2025-04-22T12:00:00Z",
+  "topic": "domestic",
+  "actors": ["us"],
+  "targets": ["iran"],
+  "severity": "medium",
+  "summary": "Washington rolls out a coordinated sanctions package aimed at procurement and logistics channels linked to proxy sustainment."
+}
+```
+
+## Scoring
+
+```
+action_reward:   +0.55  (sanction aligns with us policy at 0.55 per rl.py)
+forecast_reward: +0.82  (topic ✅ actor ✅ target ✅ severity ✅ confidence ✅)
+─────────────────────────
+total_reward:    +1.37  → fed back to GRPO
+```
+
+## Where Each Piece Comes From
+
+| Data              | Source File                           | What It Provides                                                          |
+| ----------------- | ------------------------------------- | ------------------------------------------------------------------------- |
+| Replay events     | `synthetic_historical_replays/*.json` | 10 synthetic events (timestamp, topic, actors, severity, impact)          |
+| Intel briefings   | `source_manifest.json`                | Public + private brief items                                              |
+| Agent identity    | `agents.py`                           | Role, intel focus, private intel baseline                                 |
+| Reward config     | `rl.py`                               | Allowed actions, action alignment scores, state baselines, metric targets |
+| Environment logic | `env.py`                              | Builds observation, applies actions, scores predictions, computes rewards |
+| Training loop     | `training_cli.py`                     | Connects model ↔ environment via GRPO rollouts                            |
+| OpenEnv boundary  | `openenv_adapter.py`                  | reset/step interface between TRL and the simulator                        |
+
+## Key Numbers
+
+| Metric                        | Value | Formula                                |
+| ----------------------------- | ----- | -------------------------------------- |
+| Total rollouts per entity     | 1,600 | 100 steps × 16 generations             |
+| Times each event is seen      | ~160  | 1,600 ÷ 10 events                      |
+| Effective batch size          | 8     | batch_size(1) × grad_accum(8)          |
+| Completions compared per step | 16    | GRPO ranks them relative to each other |

backend/POST_TRAINING_PLAN.md

@@ -0,0 +1,121 @@
+# Post-Training Plan: 6 Entities × 1 Hour Parallel
+
+## Overview
+
+6 HF A100 Spaces running in parallel. Total wall time: **1 hour**. Total cost: **$15**. Base model: **Qwen/Qwen3-8B** (no quantization).
+
+GRPO post-training on OpenEnv. Qwen3-8B already knows how to reason — we're aligning it to each entity's policy behavior through the environment reward signal.
+
+## Cost
+
+| Item      | Rate     | Quantity      | Cost    |
+| --------- | -------- | ------------- | ------- |
+| A100 80GB | $2.50/hr | 6 Spaces × 1h | **$15** |
+
+## Optimal Hyperparameters
+
+Researched from TRL docs, DeepSeek-R1 paper, Open-R1 recipe, and TRL OpenEnv examples.
+
+```yaml
+# Model
+model_id: Qwen/Qwen3-8B
+# No quantization — full precision on A100 80GB.
+# Quantization noise actually aids exploration (QeRL paper).
+
+# GRPO Core (from DeepSeek-R1 + Open-R1 recipes)
+algorithm: GRPO
+loss_type: grpo
+beta: 0.001 # KL coefficient (DeepSeek-R1 uses 0.001)
+num_generations:
+  16 # DeepSeek-R1: "sample 16 outputs per prompt"
+  # More generations = better group-relative advantage signal
+max_steps: 100 # 1 hour on A100 with these settings
+warmup_steps: 10 # Stabilize early training
+
+# Learning Rate
+learning_rate:
+  5e-6 # Open-R1 + OpenEnv Sudoku example both use 5e-6
+  # Higher than our earlier 5e-7; research shows
+  # post-training converges faster with this range
+
+# Batching
+per_device_train_batch_size: 1 # Memory-safe for 9B 4-bit
+gradient_accumulation_steps: 8 # Effective batch = 8 (from TRL Sudoku OpenEnv example)
+
+# Context
+max_prompt_length: 1536
+max_completion_length: 256
+
+# Generation Sampling (from TRL OpenEnv Sudoku)
+temperature: 0.8 # Balanced exploration vs exploitation
+top_k: 10 # Focused sampling
+
+# Saving
+save_strategy: steps
+save_steps: 25 # Checkpoint every 25 steps (4 saves per run)
+
+# Inference
+generation_backend: transformers # vllm if CUDA available
+# If vllm: use_vllm=True, vllm_mode="colocate", vllm_gpu_memory_utilization=0.3
+
+# Preview
+preview_samples: 3
+training_stage: stage_1_dense
+```
+
+### Why These Settings
+
+| Setting                    | Value                                           | Source/Reasoning                                                                               |
+| -------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `num_generations: 16`      | DeepSeek-R1                                     | More rollouts = better advantage estimation. 16 is the standard for GRPO                       |
+| `beta: 0.001`              | DeepSeek-R1                                     | Low KL penalty allows the model to explore further from base policy                            |
+| `learning_rate: 5e-6`      | Open-R1 + TRL examples                          | 10x higher than our earlier setting; post-training on instruct models converges with higher LR |
+| `gradient_accumulation: 8` | TRL OpenEnv Sudoku                              | Effective batch of 8 stabilizes updates without excessive VRAM                                 |
+| `temperature: 0.8`         | TRL OpenEnv Sudoku                              | Encourages diverse completions during rollout                                                  |
+| `No quantization`          | A100 80GB has enough VRAM for 8B full precision | Full precision avoids quantization noise and simplifies checkpointing                          |
+
+## Per-Space Command
+
+Replace `ENTITY` with: `us`, `israel`, `iran`, `hezbollah`, `gulf`, `oversight`
+
+```bash
+python -m trenches_env.training_cli \
+  --model-id Qwen/Qwen3-8B \
+  --training-agent ENTITY \
+  --replay-id ENTITY_synthetic_seed_2025_2026 \
+  --output-dir checkpoints/ENTITY-qwen3-8b \
+  --generation-backend transformers \
+  --training-stage stage_1_dense \
+  --max-steps 100 \
+  --train-size 256 \
+  --num-generations 16 \
+  --per-device-train-batch-size 1 \
+  --gradient-accumulation-steps 8 \
+  --learning-rate 5e-6 \
+  --max-prompt-length 1536 \
+  --max-completion-length 256 \
+  --preview-samples 3
+```
+
+## HuggingFace Hub Output
+
+```
+shlawgathon/trenches-us-qwen3-8b
+shlawgathon/trenches-israel-qwen3-8b
+shlawgathon/trenches-iran-qwen3-8b
+shlawgathon/trenches-hezbollah-qwen3-8b
+shlawgathon/trenches-gulf-qwen3-8b
+shlawgathon/trenches-oversight-qwen3-8b
+```
+
+Each checkpoint contains: `config.json`, `model.safetensors`, `tokenizer.json`, `generation_config.json`, `training_args.bin`
+
+## Build Steps
+
+1. ~~Create 5 replay datasets (israel, iran, hezbollah, gulf, oversight)~~ ✅ done (synthetic seed data in `synthetic_historical_replays/`)
+2. ~~Add `--quantize-4bit` to `training_cli.py` (NF4 via bitsandbytes)~~ ✅ done
+3. ~~Add `beta`, `warmup_steps`, `temperature`, `top_k`, `save_strategy` CLI args~~ ✅ done
+4. ~~Add `bitsandbytes>=0.43.0` to `pyproject.toml`~~ ✅ done
+5. ~~Smoke test locally with tiny-gpt2~~ ✅ done (US + Israel pass)
+6. ~~Smoke test on HF T4 GPU~~ ✅ done ([trenches-training-smoke](https://huggingface.co/spaces/AlazarM/trenches-training-smoke))
+7. Spin up 6 HF A100 Spaces → 1 hour → done

backend/README.md

@@ -0,0 +1,86 @@
+# Trenches Backend
+
+This directory contains the Python backend for the Trenches simulator.
+
+It now exposes two layers:
+
+- the existing session-oriented FastAPI API used by the React dashboard
+- a native OpenEnv-compatible environment mounted under `/openenv` when `openenv-core` is installed
+
+The backend does not serve frontend assets and is intended to stay frontend-stack agnostic. Any web client
+(Next.js, Vite, Bun, mobile, or a thin dashboard proxy) should be able to consume the same HTTP contract.
+
+CORS is configurable so frontend migrations do not require backend code changes:
+
+- `TRENCHES_CORS_ALLOW_ORIGINS=https://app.example.com,https://ops.example.com`
+- `TRENCHES_CORS_ALLOW_ORIGIN_REGEX=https://.*\\.example\\.com`
+- `TRENCHES_CORS_ALLOW_CREDENTIALS=true|false`
+
+If no CORS env vars are set, the backend allows local development origins on `localhost` / `127.0.0.1` for any port.
+
+Entity-model provider bindings are also configurable per agent. The backend does not fake provider readiness:
+if a provider/model is not configured, the runtime reports `heuristic_fallback` explicitly in session state and
+`/capabilities`.
+
+Supported env patterns:
+
+- `TRENCHES_MODEL_PROVIDER=openai|anthropic|openrouter|ollama|vllm|custom`
+- `TRENCHES_MODEL_NAME=<provider model id>`
+- `TRENCHES_MODEL_BASE_URL=<custom base url>`
+- `TRENCHES_MODEL_API_KEY_ENV=<name of env var holding the secret>`
+- `TRENCHES_MODEL_SUPPORTS_TOOL_CALLS=true|false`
+- `TRENCHES_MODEL_SUPPORTS_STRUCTURED_OUTPUT=true|false`
+
+Per-entity overrides use the uppercase agent suffix, for example:
+
+- `TRENCHES_MODEL_PROVIDER_US=openai`
+- `TRENCHES_MODEL_NAME_US=gpt-4.1`
+- `TRENCHES_MODEL_API_KEY_ENV_US=OPENAI_API_KEY`
+
+Relevant OpenEnv pieces in this package:
+
+- `trenches_env.openenv_adapter.TrenchesOpenEnvEnvironment`
+- `trenches_env.openenv_adapter.TrenchesOpenEnvAction`
+- `trenches_env.openenv_adapter.TrenchesOpenEnvObservation`
+- `trenches_env.openenv_adapter.TrenchesOpenEnvState`
+- `trenches_env.openenv_client.TrenchesEnvClient`
+
+Historical replay training pieces:
+
+- `trenches_env.models.Prediction`
+- `trenches_env.models.HistoricalEvent`
+- `trenches_env.models.HistoricalReplayState`
+- `trenches_env.training_cli`
+
+The backend now supports replay-aware forecast training:
+
+- `reset(..., replay_id=...)` starts from a visible historical context event
+- `step(...)` accepts separate `action` and `prediction`
+- the next ground-truth event is revealed on the same OpenEnv step
+- reward blends the entity action reward with forecast scoring terms
+
+Bundled bootstrap replay (⚠️ **all replays are synthetic seed data** — replace with curated truth sets for production):
+
+- `us_synthetic_seed_2025_2026`
+
+CLI training entrypoint:
+
+```bash
+trenches-train \
+  --training-agent us \
+  --replay-id us_synthetic_seed_2025_2026 \
+  --generation-backend transformers
+```
+
+The CLI supports two rollout backends:
+
+- `transformers` for portable local smoke runs
+- `vllm` for the documented colocated OpenEnv + TRL path on a GPU box
+
+Planned responsibilities:
+
+- Hold in-memory crisis sessions.
+- Expose `create`, `reset`, `step`, and `state` HTTP endpoints.
+- Model the fog-of-war world state and per-agent observations.
+- Provide a native OpenEnv boundary with scalar rewards for one active training agent while retaining full per-agent state internally.
+- Provide extension points for World Monitor ingestion and RL training hooks.

backend/TRAINING_FLOW.md

@@ -0,0 +1,156 @@
+# Trenches OpenEnv Training Flow
+
+## End-to-End Training Pipeline
+
+```mermaid
+flowchart TD
+    subgraph CLI["training_cli.py — CLI Entry Point"]
+        A["python -m trenches_env.training_cli<br/>--model-id · --training-agent · --replay-id<br/>--output-dir · --generation-backend"]
+    end
+
+    A -->|"Loads base model<br/>from HuggingFace Hub"| B["🤗 HuggingFace Model<br/>(e.g. Qwen/Qwen3-8B<br/>or sshleifer/tiny-gpt2)"]
+    A -->|"Starts in-process"| C["FastAPI Backend<br/>server.py → uvicorn<br/>localhost:8000"]
+
+    B --> D["GRPOTrainer<br/>(HF TRL)"]
+
+    subgraph GRPO["GRPO Training Loop (per step)"]
+        D -->|"1. Build prompts<br/>from base_prompt × train_size"| E["Prompt Dataset"]
+        E -->|"2. rollout_func()"| F["OpenEnv Client<br/>POST /openenv/reset"]
+        F -->|"Returns observation"| G["Render Grounded Prompt<br/>agent obs + historical brief<br/>+ strategic state + allowed actions"]
+        G -->|"3. Generate completions"| H{Generation Backend?}
+        H -->|transformers| I["transformers .generate()<br/>(CPU / Apple Silicon)"]
+        H -->|vllm| J["vLLM inference<br/>(Linux CUDA GPU)"]
+        I --> K["Parse JSON Output<br/>→ action + prediction"]
+        J --> K
+        K -->|"4. POST /openenv/step"| L["OpenEnv Environment<br/>openenv_adapter.py"]
+    end
+
+    subgraph ENV["OpenEnv Environment Boundary"]
+        L --> M["FogOfWarDiplomacyEnv<br/>env.py"]
+        M -->|"Load replay"| N["Replay Data<br/>synthetic_historical_replays/<br/>us_synthetic_seed_2025_2026.json"]
+        M -->|"Apply action in sim"| O["Advance World State"]
+        M -->|"Reveal next event"| P["Compare prediction<br/>vs actual event"]
+        P --> Q["Compute Blended Reward<br/>action_reward + forecast_reward"]
+    end
+
+    Q -->|"5. Return env_reward<br/>+ forecast_reward"| D
+    D -->|"6. GRPO policy update<br/>(gradient step)"| D
+
+    D -->|"After max_steps"| R["trainer.save_model()"]
+    R -->|"Writes checkpoint"| S["📁 output-dir/<br/>(--output-dir flag)"]
+
+    R -->|"Optional"| T["Preview Rollouts<br/>--preview-samples N"]
+
+    style CLI fill:#1a1a2e,stroke:#e94560,color:#fff
+    style GRPO fill:#16213e,stroke:#0f3460,color:#fff
+    style ENV fill:#0f3460,stroke:#533483,color:#fff
+    style S fill:#e94560,stroke:#fff,color:#fff
+```
+
+## Model Storage Locations
+
+| What                              | Where                                                    | Notes                                                                                                                                                                  |
+| --------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Base model (source)**           | HuggingFace Hub or a local checkpoint directory          | Loaded at training start via `AutoTokenizer.from_pretrained(model_id)` + `GRPOTrainer(model=model_id)`                                                                 |
+| **HF cache (downloaded weights)** | `~/.cache/huggingface/hub/`                              | Automatic HF cache, reused across runs                                                                                                                                 |
+| **Trained checkpoint (output)**   | `--output-dir` flag                                      | Default: `trl-openenv-historical-replay/`. Examples: `backend/tmp-training-run/`, `backend/us-qwen-replay-run/`, `backend/us-vllm-replay-run/`                         |
+| **Replay dataset**                | `backend/src/trenches_env/synthetic_historical_replays/` | Bundled JSON files (e.g. `us_synthetic_seed_2025_2026.json`). ⚠️ **All 6 replays are currently synthetic seed data** — replace with curated truth sets for production. |
+
+## Per-Entity Model Pattern
+
+```mermaid
+flowchart LR
+    subgraph Entities["6 Entity Models (1 per agent)"]
+        US["us model<br/>📁 backend/us-run/"]
+        ISR["israel model<br/>📁 backend/israel-run/"]
+        IRN["iran model<br/>📁 backend/iran-run/"]
+        HEZ["hezbollah model<br/>📁 backend/hezbollah-run/"]
+        GULF["gulf model<br/>📁 backend/gulf-run/"]
+        OVR["oversight model<br/>📁 backend/oversight-run/"]
+    end
+
+    subgraph Replays["Replay Datasets"]
+        R1["us_synthetic_seed_2025_2026.json ✅"]
+        R2["israel_synthetic_seed_2025_2026.json ✅"]
+        R3["iran_synthetic_seed_2025_2026.json ✅"]
+        R4["hezbollah_synthetic_seed_2025_2026.json ✅"]
+        R5["gulf_synthetic_seed_2025_2026.json ✅"]
+        R6["oversight_synthetic_seed_2025_2026.json ✅"]
+    end
+
+    R1 --> US
+    R2 --> ISR
+    R3 --> IRN
+    R4 --> HEZ
+    R5 --> GULF
+    R6 --> OVR
+
+    BASE["🤗 Base Model<br/>(shared starting point)"] --> US
+    BASE --> ISR
+    BASE --> IRN
+    BASE --> HEZ
+    BASE --> GULF
+    BASE --> OVR
+
+    style Entities fill:#16213e,stroke:#e94560,color:#fff
+    style Replays fill:#0f3460,stroke:#533483,color:#fff
+    style BASE fill:#e94560,stroke:#fff,color:#fff
+```
+
+> ✅ = implemented (all 6 replays are **synthetic seed data** for smoke-testing — replace with curated truth sets for production)
+
+The first collection step for replacing those seeds is now:
+
+```bash
+python -m trenches_env.historical_collection_cli --training-agent us --window 2025 --window 2026
+```
+
+That collector writes replay JSON in the same schema as the bundled seed files plus raw article audit JSONL for review.
+
+Saved output directories are reusable as future `--model-id` inputs and can be served with standard Hugging Face-compatible deployment tooling.
+
+## Data Sources During Post-Training
+
+All data is bundled in the repo. No external API calls during post-training.
+
+```mermaid
+flowchart LR
+    subgraph Bundled["All in backend/src/trenches_env/"]
+        REPLAY["synthetic_historical_replays/*.json<br/>10 synthetic events per entity<br/>(timestamps, topics, actors, severity, impacts)"]
+        MANIFEST["source_manifest.json<br/>63KB intel briefings<br/>(public + private)"]
+        AGENTS["agents.py<br/>6 agent profiles<br/>(role, intel focus, private intel)"]
+        RL["rl.py<br/>Reward configs, allowed actions,<br/>strategic state baselines"]
+    end
+
+    REPLAY -->|"Replay timeline"| ENV["env.py builds<br/>observation"]
+    MANIFEST -->|"Intel briefings"| ENV
+    AGENTS -->|"Agent identity"| ENV
+    RL -->|"Reward + actions"| ENV
+
+    ENV --> PROMPT["Model sees:<br/>• decision prompt<br/>• historical brief<br/>• public/private brief<br/>• strategic state<br/>• allowed actions"]
+
+    PROMPT --> MODEL["Model outputs JSON<br/>{action, prediction}"]
+    MODEL --> SCORE["env.py scores:<br/>action reward + forecast reward<br/>→ GRPO update"]
+
+    style Bundled fill:#0f3460,stroke:#533483,color:#fff
+    style SCORE fill:#e94560,stroke:#fff,color:#fff
+```
+
+## Dual-Output Per Step
+
+Each training step requires the model to produce **two outputs**:
+
+```mermaid
+flowchart LR
+    MODEL["Entity Model"] --> ACTION["action<br/>{type, target, summary}"]
+    MODEL --> PRED["prediction<br/>{topic, actor, target,<br/>severity, confidence,<br/>time_horizon, summary}"]
+
+    ACTION -->|"Applied in simulator"| SIM["World State Update"]
+    PRED -->|"Compared against<br/>revealed event"| SCORE["Forecast Reward"]
+
+    SIM --> BLEND["Blended Reward<br/>= action_reward + forecast_reward"]
+    SCORE --> BLEND
+
+    style MODEL fill:#e94560,stroke:#fff,color:#fff
+    style BLEND fill:#533483,stroke:#fff,color:#fff
+```

backend/TRAINING_RUNBOOK.md

@@ -0,0 +1,441 @@
+# Trenches OpenEnv Training Runbook
+
+This runbook shows how to run the current CLI training loop for the Trenches entity models.
+
+The important architecture rule is simple:
+
+- each entity is its own model
+- each run trains one entity to become a better version of itself
+- training happens through the native OpenEnv environment boundary
+- the environment scores both action quality and forecast quality
+
+The first implemented proof path is the `us` entity.
+
+## Historical Data Collection Before Post-Training
+
+The bundled replay JSON files under `backend/src/trenches_env/historical_replays/` are still synthetic seed data for smoke tests.
+
+To move toward real post-training data, collect historical article candidates first and then write them back into the same replay JSON schema that the trainer already consumes.
+
+The new collector CLI does exactly that:
+
+```bash
+cd /Users/xiao/trenches
+backend/.venv/bin/python -m trenches_env.historical_collection_cli \
+  --training-agent us \
+  --window 2025 \
+  --window 2026 \
+  --max-records-per-query 50 \
+  --max-events 128 \
+  --output-dir backend/src/trenches_env/historical_replays \
+  --raw-dir backend/tmp-historical-raw
+```
+
+What it writes:
+
+- replay JSON matching the existing seed schema used by `training_cli.py`
+- raw article JSONL audit files for provenance and curator review
+
+Important date note:
+
+- `2025` maps to `2025-01-01` through `2026-01-01`
+- `2026` maps to `2026-01-01` through the current date at collection time
+
+As of March 7, 2026, a full January 1, 2026 to January 1, 2027 window does not exist yet, so the collector clamps the `2026` window to the current day.
+
+Collection path:
+
+1. start from existing agent-aligned sources in `source_manifest.json`
+2. derive historical source domains from those allowlisted feeds
+3. query the GDELT DOC API month by month
+4. write raw article audit data
+5. transform those articles into replay JSON with the same `HistoricalEvent` schema as the synthetic seeds
+6. curator-review the resulting replay before production post-training
+
+Replay file shape:
+
+```json
+{
+  "replay_id": "us_historical_2025",
+  "name": "US historical replay 2025-01-01 to 2026-01-01",
+  "description": "Historically collected replay built from allowlisted source domains via the GDELT DOC API.",
+  "training_agent": "us",
+  "events": [
+    {
+      "event_id": "us-20250112090000-abcd1234",
+      "timestamp": "2025-01-12T09:00:00Z",
+      "topic": "shipping",
+      "region": "us",
+      "actors": ["iran", "gulf"],
+      "targets": ["shipping_lanes"],
+      "severity": "medium",
+      "summary": "Commercial shipping risk rises near Hormuz after new tanker threat warning.",
+      "public_summary": "Commercial shipping risk rises near Hormuz after new tanker threat warning.",
+      "source_type": "gdelt_historical_collection",
+      "confirmed": true,
+      "tags": ["shipping", "wire", "reuters.com"],
+      "impact": {
+        "tension_delta": 3.5,
+        "market_stress_delta": 4.2,
+        "oil_pressure_delta": 5.25,
+        "actor_metric_deltas": {
+          "us": { "shipping_security": -4.2, "regional_access": -4.2 }
+        }
+      }
+    }
+  ]
+}
+```
+
+Raw audit file shape:
+
+```json
+{
+  "article_id": "7d8b1f5dcb87d4f2",
+  "agent_id": "us",
+  "source_id": "us-reuters-us",
+  "source_name": "Reuters US",
+  "title": "Commercial shipping risk rises near Hormuz after new tanker threat warning.",
+  "url": "https://www.reuters.com/world/middle-east/example",
+  "domain": "reuters.com",
+  "timestamp": "2025-01-12T09:00:00Z",
+  "query": "(domainis:reuters.com) AND (\"Hormuz\" OR \"shipping\")",
+  "window_id": "2025"
+}
+```
+
+## What This Training Loop Does
+
+On each replay step the model must return two separate outputs:
+
+1. an `action`
+2. a `prediction`
+
+The backend then:
+
+1. applies the action in the simulator
+2. reveals the next historical event in the replay timeline
+3. scores the prediction against that revealed event
+4. blends forecast reward into the entity reward
+
+This means the `us` model is not learning to be a generic strategist. It is learning to be a better `us` policy inside this simulator.
+
+## Current Scope
+
+Implemented now:
+
+- native OpenEnv replay-aware training loop
+- 6 **synthetic** seed replay datasets (us, israel, iran, hezbollah, gulf, oversight) — replace with curated truth sets for production
+- CLI trainer using Hugging Face TRL
+- portable local generation path with `transformers`
+- GPU-oriented generation path with `vllm`
+
+Not implemented yet:
+
+- evaluation/baseline reporting across all entities
+- UI training controls
+- production (non-synthetic) replay datasets
+
+## Requirements
+
+Use Python `3.12`.
+
+From the repo root:
+
+```bash
+cd /Users/xiao/trenches
+```
+
+Create a virtualenv:
+
+```bash
+uv venv backend/.venv --python 3.12
+```
+
+Install the backend plus training dependencies:
+
+```bash
+uv pip install --python backend/.venv/bin/python -e 'backend[train]' 'openenv-core[core]>=0.2.1,<0.3.0' 'torch>=2.10.0'
+```
+
+## Tokens And Env Vars
+
+No `.env` file is required for the default public smoke test.
+
+You only need a token if you use a gated or private Hugging Face model.
+
+If needed:
+
+```bash
+export HF_TOKEN=your_huggingface_token
+```
+
+You do not need OpenAI, Anthropic, or other provider keys for the local replay smoke run.
+
+Optional noise reduction:
+
+```bash
+export TRL_EXPERIMENTAL_SILENCE=1
+```
+
+## Local Smoke Run
+
+This is the fastest way to prove the loop works on a laptop or Mac.
+
+It uses:
+
+- `sshleifer/tiny-gpt2`
+- `transformers` generation backend
+- `us` replay
+- one tiny GRPO run
+
+Run:
+
+```bash
+backend/.venv/bin/python -m trenches_env.training_cli \
+  --model-id sshleifer/tiny-gpt2 \
+  --generation-backend transformers \
+  --training-agent us \
+  --training-stage stage_1_dense \
+  --replay-id us_synthetic_seed_2025_2026 \
+  --train-size 4 \
+  --max-steps 1 \
+  --num-generations 2 \
+  --max-prompt-length 512 \
+  --max-completion-length 48 \
+  --per-device-train-batch-size 1 \
+  --gradient-accumulation-steps 1 \
+  --output-dir backend/tmp-training-run \
+  --preview-samples 1
+```
+
+What to expect:
+
+- the trainer starts a local backend
+- the trainer talks to `/openenv`
+- one short GRPO pass runs
+- model artifacts are written to `backend/tmp-training-run`
+- the preview step prints a rollout sample after training
+
+This exact path has already been smoke-tested in this repo.
+
+## Real Replay Smoke Run
+
+Once you have collected real replay data under `backend/src/trenches_env/historical_replays/`,
+you can run the same tiny smoke pass against a real replay id.
+
+Example:
+
+```bash
+backend/.venv/bin/python -m trenches_env.training_cli \
+  --model-id sshleifer/tiny-gpt2 \
+  --generation-backend transformers \
+  --training-agent us \
+  --training-stage stage_1_dense \
+  --replay-id us_2025_events \
+  --train-size 4 \
+  --max-steps 1 \
+  --num-generations 2 \
+  --max-prompt-length 512 \
+  --max-completion-length 48 \
+  --per-device-train-batch-size 1 \
+  --gradient-accumulation-steps 1 \
+  --output-dir backend/tmp-real-smoke-us \
+  --preview-samples 1
+```
+
+This repo has now been smoke-tested successfully on the real `us_2025_events` replay.
+
+## Better Local Run
+
+Once the smoke test works, switch to a stronger public instruct model.
+
+Example:
+
+```bash
+backend/.venv/bin/python -m trenches_env.training_cli \
+  --model-id Qwen/Qwen3-8B \
+  --generation-backend transformers \
+  --training-agent us \
+  --training-stage stage_1_dense \
+  --replay-id us_synthetic_seed_2025_2026 \
+  --train-size 32 \
+  --max-steps 8 \
+  --num-generations 4 \
+  --max-prompt-length 1024 \
+  --max-completion-length 220 \
+  --per-device-train-batch-size 1 \
+  --gradient-accumulation-steps 1 \
+  --output-dir backend/us-qwen-replay-run \
+  --preview-samples 3
+```
+
+On CPU or Apple Silicon this will still be slow. That is expected.
+
+## GPU Run With vLLM
+
+Use this on a Linux CUDA machine when you want the documented OpenEnv + TRL path.
+
+First install `vllm` in the same environment.
+
+Then run:
+
+```bash
+backend/.venv/bin/python -m trenches_env.training_cli \
+  --model-id Qwen/Qwen3-8B \
+  --generation-backend vllm \
+  --training-agent us \
+  --training-stage stage_1_dense \
+  --replay-id us_synthetic_seed_2025_2026 \
+  --train-size 64 \
+  --max-steps 16 \
+  --num-generations 4 \
+  --max-prompt-length 1024 \
+  --max-completion-length 220 \
+  --per-device-train-batch-size 1 \
+  --gradient-accumulation-steps 1 \
+  --output-dir backend/us-vllm-replay-run \
+  --preview-samples 3
+```
+
+Notes:
+
+- `vllm` is not the default because many local machines do not support it cleanly
+- the CLI auto-detects a usable backend when `--generation-backend auto` is used
+- `transformers` is the safer fallback for local proof runs
+
+## Running Another Entity Later
+
+The trainer already supports `--training-agent`, and replay ids are loaded from both:
+
+- `backend/src/trenches_env/historical_replays/` for curated real data
+- `backend/src/trenches_env/synthetic_historical_replays/` for synthetic seed data
+
+The future pattern for the other five entities is:
+
+1. create a replay file for that entity
+2. point the trainer at that replay id
+3. write the checkpoint to a separate output directory
+
+Example shape:
+
+```bash
+backend/.venv/bin/python -m trenches_env.training_cli \
+  --training-agent israel \
+  --replay-id israel_2025_events \
+  --output-dir backend/israel-run
+```
+
+If you want the synthetic smoke path instead, switch the replay id back to
+`israel_synthetic_seed_2025_2026`.
+
+## Reusing Or Deploying A Saved Checkpoint
+
+Each completed run writes a standard Hugging Face checkpoint layout to `--output-dir`,
+including at minimum:
+
+- `config.json`
+- `model.safetensors`
+- `tokenizer.json`
+- `tokenizer_config.json`
+- `generation_config.json`
+
+Two verified reuse paths:
+
+1. Continue training from the saved directory by passing it back as `--model-id`
+2. Load it directly with `transformers.AutoModelForCausalLM.from_pretrained(...)`
+
+Example continue-training command:
+
+```bash
+backend/.venv/bin/python -m trenches_env.training_cli \
+  --model-id /Users/xiao/trenches/backend/tmp-real-smoke-us \
+  --generation-backend transformers \
+  --training-agent us \
+  --training-stage stage_1_dense \
+  --replay-id us_2025_events \
+  --train-size 2 \
+  --max-steps 1 \
+  --num-generations 2 \
+  --output-dir backend/tmp-real-smoke-us-reuse \
+  --no-preview
+```
+
+Because the output is a standard HF checkpoint, it is also compatible with normal
+deployment packaging flows such as `transformers` inference or a vLLM/Hugging Face-serving setup
+that accepts a local model directory.
+
+## How To Verify The Environment Signal
+
+Run the focused tests:
+
+```bash
+cd /Users/xiao/trenches/backend
+pytest -q tests/test_openenv_adapter.py tests/test_server.py
+```
+
+These tests cover:
+
+- replay reset/step behavior
+- prediction storage
+- forecast reward scoring
+- OpenEnv adapter behavior
+- server wiring
+
+## What Files Matter
+
+Core training files:
+
+- `backend/src/trenches_env/training_cli.py`
+- `backend/src/trenches_env/openenv_adapter.py`
+- `backend/src/trenches_env/env.py`
+- `backend/src/trenches_env/models.py`
+- `backend/src/trenches_env/historical_replay.py`
+- `backend/src/trenches_env/synthetic_historical_replays/us_synthetic_seed_2025_2026.json`
+
+## Troubleshooting
+
+If you see `No module named 'trl'` or `No module named 'openenv'`:
+
+- reinstall into `backend/.venv`
+- make sure you are using `backend/.venv/bin/python`
+
+If TRL complains that `generation_batch_size` is not divisible by `num_generations`:
+
+- keep `--num-generations` small
+- use the current CLI defaults
+
+If `vllm` fails locally:
+
+- switch to `--generation-backend transformers`
+
+If a model is gated:
+
+- export `HF_TOKEN`
+
+If the run finishes with flat rewards on a tiny smoke model:
+
+- that does not mean the environment is broken
+- it usually means the toy model generated poor outputs
+- use a better instruct model and a longer run
+
+## Short Version
+
+If you only want the shortest possible proof:
+
+```bash
+cd /Users/xiao/trenches
+uv venv backend/.venv --python 3.12
+uv pip install --python backend/.venv/bin/python -e 'backend[train]' 'openenv-core[core]>=0.2.1,<0.3.0' 'torch>=2.10.0'
+backend/.venv/bin/python -m trenches_env.training_cli \
+  --model-id sshleifer/tiny-gpt2 \
+  --generation-backend transformers \
+  --training-agent us \
+  --replay-id us_synthetic_seed_2025_2026 \
+  --train-size 4 \
+  --max-steps 1 \
+  --num-generations 2 \
+  --output-dir backend/tmp-training-run
+```
+
+That is the current hackathon-safe path.

backend/examples/trl_openenv_colab_minimal.py

@@ -0,0 +1,5 @@
+from trenches_env.training_cli import main
+
+
+if __name__ == "__main__":
+    main()

backend/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "trenches-openenv"
+version = "0.1.0"
+description = "Python scaffolding for the Trenches OpenEnv crisis simulator"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+  "fastapi>=0.115.0,<1.0.0",
+  "httpx>=0.27.0,<1.0.0",
+  "numpy>=1.26.0,<3.0.0",
+  "openenv-core[core]>=0.2.1,<0.3.0",
+  "pydantic>=2.8.0,<3.0.0",
+  "uvicorn[standard]>=0.30.0,<1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.3.0,<9.0.0",
+]
+train = [
+  "accelerate>=1.0.0,<2.0.0",
+  "bitsandbytes>=0.43.0",
+  "datasets>=3.0.0,<4.0.0",
+  "peft>=0.12.0,<1.0.0",
+  "transformers>=4.55.0,<5.0.0",
+  "trl>=0.25.0,<0.26.0",
+]
+
+[project.scripts]
+trenches-api = "trenches_env.server:run"
+trenches-train = "trenches_env.training_cli:main"
+trenches-build-historical-replay = "trenches_env.historical_collection_cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+trenches_env = ["source_manifest.json", "historical_replays/*.json"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

backend/src/trenches_env/__init__.py

@@ -0,0 +1,25 @@
+from trenches_env.env import FogOfWarDiplomacyEnv
+from trenches_env.openenv_client import TrenchesEnvClient
+from trenches_env.openenv_adapter import (
+    OPENENV_CORE_AVAILABLE,
+    OpenEnvAdapter,
+    TrenchesOpenEnvAction,
+    TrenchesOpenEnvEnvironment,
+    TrenchesOpenEnvObservation,
+    TrenchesOpenEnvState,
+    create_openenv_fastapi_app,
+)
+from trenches_env.session_manager import SessionManager
+
+__all__ = [
+    "OPENENV_CORE_AVAILABLE",
+    "FogOfWarDiplomacyEnv",
+    "OpenEnvAdapter",
+    "SessionManager",
+    "TrenchesEnvClient",
+    "TrenchesOpenEnvAction",
+    "TrenchesOpenEnvEnvironment",
+    "TrenchesOpenEnvObservation",
+    "TrenchesOpenEnvState",
+    "create_openenv_fastapi_app",
+]

backend/src/trenches_env/agents.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+AgentId = Literal["us", "israel", "iran", "hezbollah", "gulf", "oversight"]
+ModelSize = Literal["large", "medium-large", "medium"]
+
+
+@dataclass(frozen=True)
+class AgentProfile:
+    display_name: str
+    role: str
+    model_size: ModelSize
+    intelligence_focus: tuple[str, ...]
+    baseline_private_intel: tuple[str, ...]
+
+
+AGENT_IDS: tuple[AgentId, ...] = (
+    "us",
+    "israel",
+    "iran",
+    "hezbollah",
+    "gulf",
+    "oversight",
+)
+
+
+AGENT_PROFILES: dict[AgentId, AgentProfile] = {
+    "us": AgentProfile(
+        display_name="US / CENTCOM",
+        role="Alliance management, sanctions, domestic stability",
+        model_size="large",
+        intelligence_focus=("polls", "markets", "alliances", "shipping"),
+        baseline_private_intel=(
+            "Domestic approval is sensitive to prolonged escalation.",
+            "Forward naval posture can deter but also spike market stress.",
+        ),
+    ),
+    "israel": AgentProfile(
+        display_name="Israel / IDF",
+        role="Border defense, strike planning, proxy disruption",
+        model_size="medium-large",
+        intelligence_focus=("northern front", "sirens", "proxy movement", "air defense"),
+        baseline_private_intel=(
+            "Border warning posture remains elevated in the north.",
+            "Fast retaliation can secure deterrence but raises coalition risk.",
+        ),
+    ),
+    "iran": AgentProfile(
+        display_name="Iran / IRGC",
+        role="Asymmetric retaliation, proxy coordination, survival",
+        model_size="medium-large",
+        intelligence_focus=("proxy network", "oil chokepoints", "internal losses", "deception"),
+        baseline_private_intel=(
+            "Proxy coordination is most effective when attribution stays ambiguous.",
+            "Energy chokepoints remain the strongest leverage point.",
+        ),
+    ),
+    "hezbollah": AgentProfile(
+        display_name="Hezbollah",
+        role="Asymmetric swarming, opportunistic escalation",
+        model_size="medium",
+        intelligence_focus=("border gaps", "morale", "small-unit pressure", "drone windows"),
+        baseline_private_intel=(
+            "Small, frequent attacks are harder to pre-empt than large waves.",
+            "Alignment with Tehran matters more than independent visibility.",
+        ),
+    ),
+    "gulf": AgentProfile(
+        display_name="Gulf Coalition",
+        role="Market hedging, shipping security, selective alignment",
+        model_size="medium",
+        intelligence_focus=("oil", "shipping", "capital flows", "neutrality"),
+        baseline_private_intel=(
+            "Energy shock containment matters more than direct battlefield gains.",
+            "Neutral positioning creates leverage only while trade routes remain open.",
+        ),
+    ),
+    "oversight": AgentProfile(
+        display_name="Fleet Oversight",
+        role="Risk scoring, intervention, trace auditing",
+        model_size="medium-large",
+        intelligence_focus=("global risk", "misalignment", "cascades", "de-escalation"),
+        baseline_private_intel=(
+            "Misread incentives are the strongest predictor of runaway escalation.",
+            "Interventions should reduce risk without collapsing agent autonomy.",
+        ),
+    ),
+}

backend/src/trenches_env/benchmark_runner.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from typing import Callable
+
+from trenches_env.agents import AGENT_IDS
+from trenches_env.env import FogOfWarDiplomacyEnv
+from trenches_env.models import (
+    BenchmarkEntityScorecard,
+    BenchmarkRunRequest,
+    BenchmarkRunResponse,
+    BenchmarkScenarioResult,
+    StepSessionRequest,
+)
+from trenches_env.scenarios import benchmark_scenario_ids, get_scenario_definition, scenario_signals_for_turn
+from trenches_env.source_ingestion import SourceHarvester
+
+
+def _default_env_factory() -> FogOfWarDiplomacyEnv:
+    return FogOfWarDiplomacyEnv(source_harvester=SourceHarvester(auto_start=False))
+
+
+class ScenarioBenchmarkRunner:
+    def __init__(self, env_factory: Callable[[], FogOfWarDiplomacyEnv] | None = None) -> None:
+        self._env_factory = env_factory or _default_env_factory
+
+    def run(self, request: BenchmarkRunRequest) -> BenchmarkRunResponse:
+        scenario_ids = request.scenario_ids or benchmark_scenario_ids()
+        results: list[BenchmarkScenarioResult] = []
+        aggregate_reward_totals: dict[str, float] = {agent_id: 0.0 for agent_id in AGENT_IDS}
+
+        for index, scenario_id in enumerate(scenario_ids):
+            scenario = get_scenario_definition(scenario_id)
+            scenario_seed = None if request.seed is None else request.seed + index
+            turn_limit = request.steps_per_scenario or scenario.benchmark_turns
+            env = self._env_factory()
+
+            try:
+                session = env.create_session(
+                    seed=scenario_seed,
+                    training_stage=request.training_stage,
+                    max_turns=turn_limit,
+                    scenario_id=scenario.id,
+                )
+                reward_totals: dict[str, float] = {agent_id: 0.0 for agent_id in AGENT_IDS}
+                goal_term_totals: dict[str, dict[str, float]] = {
+                    agent_id: defaultdict(float) for agent_id in AGENT_IDS
+                }
+                action_counters: dict[str, Counter[str]] = {agent_id: Counter() for agent_id in AGENT_IDS}
+                oversight_trigger_count = 0
+                done = False
+                done_reason: str | None = None
+
+                for turn in range(1, turn_limit + 1):
+                    signals = scenario_signals_for_turn(scenario.id, turn)
+                    actions = env.resolve_policy_actions(session, signals)
+                    result = env.step_session(
+                        session,
+                        StepSessionRequest(actions=actions, external_signals=signals),
+                    )
+                    session = result.session
+                    trace = session.recent_traces[-1]
+
+                    if result.oversight.triggered:
+                        oversight_trigger_count += 1
+
+                    for agent_id, action in trace.actions.items():
+                        action_counters[agent_id][action.type] += 1
+
+                    for agent_id, reward in trace.rewards.items():
+                        reward_totals[agent_id] += reward.total
+                        for name, value in reward.goal_terms.items():
+                            goal_term_totals[agent_id][name] += value
+
+                    if result.done:
+                        done = True
+                        if session.world.tension_level >= 95.0:
+                            done_reason = "tension_threshold"
+                        else:
+                            done_reason = "max_turns"
+                        break
+
+                scorecards: dict[str, BenchmarkEntityScorecard] = {}
+                for agent_id in AGENT_IDS:
+                    final_reward = session.rewards[agent_id]
+                    aggregate_reward_totals[agent_id] += reward_totals[agent_id]
+                    action_counts = dict(action_counters[agent_id])
+                    dominant_action = (
+                        max(action_counts, key=action_counts.get)
+                        if action_counts
+                        else None
+                    )
+                    damaged_asset_count = sum(
+                        1
+                        for asset in session.world.asset_state.get(agent_id, {}).values()
+                        if asset.status != "operational"
+                    )
+                    asset_pressure = round(env._asset_pressure(session.world, agent_id), 3)
+                    warnings: list[str] = []
+                    if dominant_action is not None:
+                        dominant_share = action_counts[dominant_action] / max(sum(action_counts.values()), 1)
+                        if dominant_share >= 0.75:
+                            warnings.append(f"action_monoculture:{dominant_action}")
+                    if asset_pressure >= 0.45 and dominant_action == "hold":
+                        warnings.append("passive_under_asset_pressure")
+                    if final_reward.total <= -0.35 and dominant_action in {"strike", "mobilize", "deceive", "sanction"}:
+                        warnings.append("negative_escalation_bias")
+
+                    scorecards[agent_id] = BenchmarkEntityScorecard(
+                        agent_id=agent_id,
+                        total_reward=round(reward_totals[agent_id], 3),
+                        mean_reward=round(reward_totals[agent_id] / max(session.world.turn, 1), 3),
+                        final_reward=final_reward.total,
+                        final_goal_terms=final_reward.goal_terms,
+                        aggregated_goal_terms={
+                            name: round(value, 3)
+                            for name, value in goal_term_totals[agent_id].items()
+                        },
+                        final_state=session.world.latent_state.get(agent_id, {}).copy(),
+                        damaged_asset_count=damaged_asset_count,
+                        asset_pressure=asset_pressure,
+                        action_counts=action_counts,
+                        dominant_action=dominant_action,
+                        warnings=warnings,
+                    )
+
+                scenario_warnings: list[str] = []
+                if oversight_trigger_count >= max(2, turn_limit // 2):
+                    scenario_warnings.append("frequent_oversight")
+                if session.world.tension_level >= 90.0:
+                    scenario_warnings.append("runaway_escalation")
+                if all(
+                    scorecards[agent_id].dominant_action == "hold"
+                    for agent_id in ("us", "israel", "iran", "hezbollah", "gulf")
+                ):
+                    scenario_warnings.append("global_passivity")
+
+                summary = (
+                    f"{scenario.name}: {session.world.turn} turns, tension {session.world.tension_level:.1f}, "
+                    f"oversight triggers {oversight_trigger_count}."
+                )
+                results.append(
+                    BenchmarkScenarioResult(
+                        scenario_id=scenario.id,
+                        scenario_name=scenario.name,
+                        seed=scenario_seed,
+                        training_stage=request.training_stage,
+                        turns_executed=session.world.turn,
+                        done=done,
+                        done_reason=done_reason,
+                        oversight_trigger_count=oversight_trigger_count,
+                        final_tension=session.world.tension_level,
+                        final_market_stress=session.world.market_stress,
+                        final_oil_pressure=session.world.oil_pressure,
+                        summary=summary,
+                        warnings=scenario_warnings,
+                        scorecards=scorecards,
+                    )
+                )
+            finally:
+                env.shutdown()
+
+        scenario_count = max(len(results), 1)
+        aggregate_mean_total_rewards = {
+            agent_id: round(total / scenario_count, 3)
+            for agent_id, total in aggregate_reward_totals.items()
+        }
+        return BenchmarkRunResponse(
+            seed=request.seed,
+            training_stage=request.training_stage,
+            scenario_ids=[result.scenario_id for result in results],
+            scenario_count=len(results),
+            results=results,
+            aggregate_mean_total_rewards=aggregate_mean_total_rewards,
+        )

backend/src/trenches_env/entity_knowledge.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import json
+import os
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+DEFAULT_ENTITIES_ROOT = Path(__file__).resolve().parents[3] / "entities"
+
+
+@lru_cache(maxsize=1)
+def resolve_entities_root() -> Path:
+    configured_root = os.getenv("TRENCHES_ENTITIES_ROOT")
+    if configured_root:
+        candidate = Path(configured_root).expanduser().resolve()
+        if candidate.exists():
+            return candidate
+
+    fallback_candidates = (
+        DEFAULT_ENTITIES_ROOT,
+        Path.cwd() / "entities",
+        Path.cwd().parent / "entities",
+    )
+    for candidate in fallback_candidates:
+        if candidate.exists():
+            return candidate
+
+    return DEFAULT_ENTITIES_ROOT
+
+
+@lru_cache(maxsize=None)
+def load_entity_pack(agent_id: str) -> dict[str, Any]:
+    entity_dir = resolve_entities_root() / agent_id
+    profile_path = entity_dir / "profile.json"
+    assets_path = entity_dir / "assets.json"
+
+    if not profile_path.exists() or not assets_path.exists():
+        return {"profile": {}, "assets": {}}
+
+    with profile_path.open("r", encoding="utf-8") as profile_file:
+        profile = json.load(profile_file)
+
+    with assets_path.open("r", encoding="utf-8") as assets_file:
+        assets = json.load(assets_file)
+
+    return {
+        "profile": profile,
+        "assets": assets,
+    }

backend/src/trenches_env/historical_collection.py

@@ -0,0 +1,461 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from datetime import UTC, date, datetime, time, timedelta
+from pathlib import Path
+from urllib.parse import parse_qs, urlparse
+
+from pydantic import BaseModel, Field
+
+from trenches_env.agents import AGENT_IDS
+from trenches_env.historical_replay import HistoricalReplayDefinition
+from trenches_env.models import EventSeverity, HistoricalEvent, HistoricalEventImpact
+from trenches_env.source_catalog import get_sources_for_agent
+from trenches_env.source_catalog import SourceSpec, UrlEndpoint
+
+_SITE_PATTERN = re.compile(r"site:([A-Za-z0-9.-]+)")
+_NON_WORD_PATTERN = re.compile(r"[^a-z0-9]+")
+
+TOPIC_KEYWORDS: dict[str, tuple[str, ...]] = {
+    "shipping": ("shipping", "tanker", "hormuz", "maritime", "vessel", "escort", "transit", "port"),
+    "commodities": ("gold", "silver", "copper", "lithium", "lng", "commodity", "mineral", "rare earth"),
+    "border": ("border", "rocket", "missile", "drone", "swarm", "launch", "incursion", "front"),
+    "corridor": ("corridor", "logistics", "syria", "bekaa", "interdiction", "proxy", "sustainment"),
+    "domestic": ("sanction", "protest", "unrest", "inflation", "reserve", "political", "domestic"),
+    "cyber": ("cyber", "outage", "malware", "network", "infrastructure", "blackout"),
+    "market": ("market", "investor", "bond", "stocks", "premium", "insurance", "trade"),
+    "humanitarian": ("humanitarian", "aid", "displacement", "civilian", "refugee", "shelter"),
+    "diplomacy": ("ceasefire", "talks", "summit", "mediat", "backchannel", "framework", "deconfliction"),
+}
+
+NEGATIVE_MARKERS = (
+    "attack",
+    "strike",
+    "threat",
+    "harassment",
+    "swarm",
+    "sanction",
+    "disruption",
+    "outage",
+    "volley",
+    "incursion",
+    "retaliat",
+    "unrest",
+)
+
+POSITIVE_MARKERS = (
+    "ceasefire",
+    "stabil",
+    "assurance",
+    "resupply",
+    "escort",
+    "framework",
+    "deconfliction",
+    "reopen",
+    "relief",
+    "backchannel",
+    "reprieve",
+)
+
+AGENT_QUERY_TERMS: dict[str, tuple[str, ...]] = {
+    "us": ("Hormuz", "shipping", "CENTCOM", "sanctions", "Gulf", "Iran", "Israel", "Hezbollah"),
+    "israel": ("Israel", "IDF", "Hezbollah", "Lebanon", "Iran", "Syria", "rocket", "drone"),
+    "iran": ("Iran", "IRGC", "proxy", "Hormuz", "sanctions", "Israel", "United States"),
+    "hezbollah": ("Hezbollah", "Lebanon", "Israel", "rocket", "drone", "border", "south Lebanon"),
+    "gulf": ("Gulf", "Hormuz", "shipping", "energy", "LNG", "oil", "Saudi", "UAE", "Qatar"),
+    "oversight": ("regional escalation", "cyber", "shipping", "humanitarian", "ceasefire", "attribution"),
+}
+
+TOPIC_IMPACT_FACTORS: dict[str, tuple[float, float, float]] = {
+    "shipping": (1.0, 1.2, 1.5),
+    "commodities": (0.5, 1.2, 1.0),
+    "border": (1.25, 0.4, 0.1),
+    "corridor": (1.0, 0.3, 0.2),
+    "domestic": (0.7, 0.5, 0.2),
+    "cyber": (0.8, 0.9, 0.4),
+    "market": (0.4, 1.1, 0.5),
+    "humanitarian": (0.6, 0.2, 0.1),
+    "diplomacy": (-0.9, -0.8, -0.6),
+}
+
+AGENT_TOPIC_METRICS: dict[str, dict[str, tuple[str, ...]]] = {
+    "us": {
+        "shipping": ("shipping_security", "regional_access"),
+        "diplomacy": ("regional_access", "shipping_security"),
+        "domestic": ("domestic_support",),
+        "market": ("domestic_support", "force_posture"),
+    },
+    "israel": {
+        "border": ("homeland_security", "northern_deterrence", "reserve_endurance"),
+        "corridor": ("northern_deterrence",),
+        "diplomacy": ("us_resupply_confidence", "reserve_endurance"),
+        "domestic": ("reserve_endurance", "us_resupply_confidence"),
+    },
+    "iran": {
+        "shipping": ("hormuz_leverage",),
+        "corridor": ("proxy_corridor", "deterrence_credibility"),
+        "domestic": ("regime_stability",),
+        "diplomacy": ("deterrence_credibility",),
+    },
+    "hezbollah": {
+        "border": ("resistance_credibility", "launch_survivability"),
+        "corridor": ("logistics_depth",),
+        "domestic": ("political_cover",),
+        "diplomacy": ("political_cover",),
+    },
+    "gulf": {
+        "shipping": ("shipping_continuity", "investor_confidence"),
+        "commodities": ("investor_confidence", "diplomatic_flexibility"),
+        "cyber": ("infrastructure_security", "investor_confidence"),
+        "diplomacy": ("diplomatic_flexibility", "shipping_continuity"),
+        "market": ("investor_confidence",),
+    },
+    "oversight": {
+        "cyber": ("trace_clarity",),
+        "shipping": ("trace_clarity", "autonomy_balance"),
+        "humanitarian": ("intervention_legitimacy",),
+        "diplomacy": ("intervention_legitimacy", "autonomy_balance"),
+    },
+}
+
+SEVERITY_BASE: dict[EventSeverity, float] = {
+    "low": 1.5,
+    "medium": 3.5,
+    "high": 6.0,
+    "critical": 8.5,
+}
+
+WINDOW_PRESETS: dict[str, tuple[date, date]] = {
+    "2025": (date(2025, 1, 1), date(2026, 1, 1)),
+    "2026": (date(2026, 1, 1), date(2027, 1, 1)),
+}
+
+
+class HistoricalCollectionWindow(BaseModel):
+    window_id: str
+    start_date: date
+    end_date: date
+
+
+class HistoricalSourceProfile(BaseModel):
+    agent_id: str
+    source_id: str
+    source_name: str
+    rationale: str
+    domains: list[str] = Field(default_factory=list)
+    tags: list[str] = Field(default_factory=list)
+    query_terms: list[str] = Field(default_factory=list)
+    priority: int = 0
+
+
+class CollectedHistoricalArticle(BaseModel):
+    article_id: str
+    agent_id: str
+    source_id: str
+    source_name: str
+    title: str
+    url: str
+    domain: str
+    timestamp: datetime
+    query: str
+    window_id: str
+    tags: list[str] = Field(default_factory=list)
+    language: str | None = None
+    source_country: str | None = None
+
+
+def resolve_window(window_id: str, *, now: datetime | None = None) -> HistoricalCollectionWindow:
+    if window_id not in WINDOW_PRESETS:
+        known = ", ".join(sorted(WINDOW_PRESETS))
+        raise ValueError(f"Unknown collection window {window_id}. Known windows: {known}")
+    start_date, end_date = WINDOW_PRESETS[window_id]
+    current = (now or datetime.now(UTC)).date()
+    if end_date > current + timedelta(days=1):
+        end_date = current + timedelta(days=1)
+    return HistoricalCollectionWindow(window_id=window_id, start_date=start_date, end_date=end_date)
+
+
+def iter_month_windows(window: HistoricalCollectionWindow) -> list[HistoricalCollectionWindow]:
+    current = window.start_date
+    windows: list[HistoricalCollectionWindow] = []
+    while current < window.end_date:
+        next_month = date(current.year + (1 if current.month == 12 else 0), 1 if current.month == 12 else current.month + 1, 1)
+        windows.append(
+            HistoricalCollectionWindow(
+                window_id=f"{window.window_id}-{current.strftime('%Y-%m')}",
+                start_date=current,
+                end_date=min(next_month, window.end_date),
+            )
+        )
+        current = next_month
+    return windows
+
+
+def _priority_for_source(source: SourceSpec) -> int:
+    score = 0
+    tags = set(source.tags)
+    if "official" in tags:
+        score += 3
+    if "wire" in tags:
+        score += 2
+    if source.allowlistStatus == "allowed":
+        score += 1
+    return score
+
+
+def _extract_domains_from_source(source: SourceSpec) -> list[str]:
+    endpoint = source.endpoint
+    if not isinstance(endpoint, UrlEndpoint):
+        return []
+    parsed = urlparse(endpoint.url)
+    domains: set[str] = set()
+    hostname = parsed.hostname or ""
+    if hostname and hostname != "news.google.com":
+        domains.add(hostname.removeprefix("www."))
+    query_values = parse_qs(parsed.query).get("q", [])
+    for query_value in query_values:
+        for match in _SITE_PATTERN.findall(query_value):
+            domains.add(match.removeprefix("www."))
+    return sorted(domains)
+
+
+def build_source_profiles_for_agent(agent_id: str) -> list[HistoricalSourceProfile]:
+    profiles: list[HistoricalSourceProfile] = []
+    for source in get_sources_for_agent(agent_id, delivery="training_core"):
+        if source.kind not in {"rss", "api", "scrape"}:
+            continue
+        domains = _extract_domains_from_source(source)
+        if not domains:
+            continue
+        profiles.append(
+            HistoricalSourceProfile(
+                agent_id=agent_id,
+                source_id=source.id,
+                source_name=source.name,
+                rationale=source.rationale,
+                domains=domains,
+                tags=list(source.tags),
+                query_terms=list(AGENT_QUERY_TERMS.get(agent_id, ())),
+                priority=_priority_for_source(source),
+            )
+        )
+    profiles.sort(key=lambda item: (-item.priority, item.source_name))
+    return profiles
+
+
+def build_gdelt_query(profile: HistoricalSourceProfile) -> str:
+    domain_clause = " OR ".join(f"domainis:{domain}" for domain in profile.domains[:4])
+    terms = " OR ".join(json.dumps(term) for term in profile.query_terms[:8])
+    if domain_clause and terms:
+        return f"({domain_clause}) AND ({terms})"
+    if terms:
+        return terms
+    return domain_clause
+
+
+def parse_gdelt_datetime(value: str) -> datetime:
+    value = value.strip()
+    if value.endswith("Z") and "T" in value:
+        return datetime.fromisoformat(value.replace("Z", "+00:00")).astimezone(UTC)
+    if len(value) == 14 and value.isdigit():
+        return datetime.strptime(value, "%Y%m%d%H%M%S").replace(tzinfo=UTC)
+    if len(value) == 15 and value.endswith("Z") and value[:-1].isdigit():
+        return datetime.strptime(value, "%Y%m%d%H%M%SZ").replace(tzinfo=UTC)
+    return datetime.fromisoformat(value.replace("Z", "+00:00")).astimezone(UTC)
+
+
+def build_article_id(url: str, timestamp: datetime) -> str:
+    digest = hashlib.sha1(f"{url}|{timestamp.isoformat()}".encode("utf-8")).hexdigest()
+    return digest[:16]
+
+
+def dedupe_articles(articles: list[CollectedHistoricalArticle]) -> list[CollectedHistoricalArticle]:
+    seen_urls: set[str] = set()
+    seen_titles: set[str] = set()
+    deduped: list[CollectedHistoricalArticle] = []
+    for article in sorted(articles, key=lambda item: item.timestamp):
+        normalized_url = article.url.rstrip("/")
+        normalized_title = _NON_WORD_PATTERN.sub(" ", article.title.lower()).strip()
+        title_key = f"{article.timestamp.date().isoformat()}::{normalized_title}"
+        if normalized_url in seen_urls or title_key in seen_titles:
+            continue
+        seen_urls.add(normalized_url)
+        seen_titles.add(title_key)
+        deduped.append(article)
+    return deduped
+
+
+def infer_topic(title: str) -> str:
+    lowered = title.lower()
+    scored: list[tuple[int, str]] = []
+    for topic, keywords in TOPIC_KEYWORDS.items():
+        score = sum(1 for keyword in keywords if keyword in lowered)
+        if score:
+            scored.append((score, topic))
+    if not scored:
+        return "diplomacy"
+    scored.sort(reverse=True)
+    return scored[0][1]
+
+
+def infer_severity(title: str, topic: str) -> EventSeverity:
+    lowered = title.lower()
+    if any(marker in lowered for marker in ("critical", "massive", "major", "swarm", "ground operation")):
+        return "critical"
+    if any(marker in lowered for marker in ("strike", "attack", "retaliat", "incursion", "disruption", "outage")):
+        return "high"
+    if topic in {"shipping", "cyber", "commodities", "domestic", "corridor"}:
+        return "medium"
+    return "low"
+
+
+def infer_polarity(title: str, topic: str) -> int:
+    lowered = title.lower()
+    if any(marker in lowered for marker in POSITIVE_MARKERS):
+        return 1
+    if any(marker in lowered for marker in NEGATIVE_MARKERS):
+        return -1
+    if topic == "diplomacy":
+        return 1
+    if topic in {"shipping", "border", "corridor", "cyber", "humanitarian", "commodities"}:
+        return -1
+    return 0
+
+
+def infer_actors_and_targets(title: str, agent_id: str) -> tuple[list[str], list[str]]:
+    lowered = title.lower()
+    actors: list[str] = []
+    targets: list[str] = []
+    for candidate in AGENT_IDS:
+        if candidate == "us":
+            tokens = ("united states", "u.s.", "washington", "centcom", "pentagon", "us ")
+        elif candidate == "israel":
+            tokens = ("israel", "idf")
+        elif candidate == "iran":
+            tokens = ("iran", "irgc", "tehran")
+        elif candidate == "hezbollah":
+            tokens = ("hezbollah",)
+        elif candidate == "gulf":
+            tokens = ("gulf", "saudi", "uae", "qatar", "oman", "bahrain")
+        else:
+            tokens = ("oversight", "monitor", "trace")
+        if any(token in lowered for token in tokens):
+            actors.append(candidate)
+    if not actors:
+        actors = [agent_id]
+    topic = infer_topic(title)
+    if topic == "shipping":
+        targets = ["shipping_lanes"]
+    elif topic == "border":
+        targets = ["northern_front" if agent_id in {"israel", "hezbollah"} else "border_zone"]
+    elif topic == "corridor":
+        targets = ["proxy_corridor"]
+    elif topic == "cyber":
+        targets = ["energy_networks"]
+    elif topic == "commodities":
+        targets = ["commodity_markets"]
+    else:
+        targets = [agent_id]
+    return sorted(set(actors)), targets
+
+
+def infer_impact(agent_id: str, topic: str, severity: EventSeverity, polarity: int) -> HistoricalEventImpact:
+    base = SEVERITY_BASE[severity]
+    tension_factor, market_factor, oil_factor = TOPIC_IMPACT_FACTORS.get(topic, (0.5, 0.3, 0.2))
+    sign = 1 if polarity >= 0 else -1
+    if polarity == 0:
+        sign = 1 if topic not in {"diplomacy"} else -1
+
+    tension_delta = round(base * tension_factor * sign, 2)
+    market_delta = round(base * market_factor * sign, 2)
+    oil_delta = round(base * oil_factor * sign, 2)
+
+    metric_scale = max(1.5, base * 0.7)
+    actor_metric_deltas: dict[str, dict[str, float]] = {}
+    for target_agent, metric_map in AGENT_TOPIC_METRICS.items():
+        metrics = metric_map.get(topic, ())
+        if not metrics:
+            continue
+        direction = sign
+        if target_agent == agent_id and topic == "diplomacy":
+            direction = 1
+        elif target_agent == agent_id and topic in {"shipping", "border", "corridor", "cyber", "humanitarian", "commodities"}:
+            direction = -1 if sign > 0 else 1
+        elif target_agent in {"iran", "hezbollah"} and topic in {"shipping", "border", "corridor"} and sign > 0:
+            direction = 1
+        elif topic == "diplomacy":
+            direction = 1
+        actor_metric_deltas[target_agent] = {
+            metric: round(metric_scale * direction, 2) for metric in metrics
+        }
+
+    return HistoricalEventImpact(
+        tension_delta=tension_delta,
+        market_stress_delta=market_delta,
+        oil_pressure_delta=oil_delta,
+        actor_metric_deltas=actor_metric_deltas,
+    )
+
+
+def article_to_historical_event(article: CollectedHistoricalArticle, *, training_agent: str) -> HistoricalEvent:
+    topic = infer_topic(article.title)
+    severity = infer_severity(article.title, topic)
+    polarity = infer_polarity(article.title, topic)
+    actors, targets = infer_actors_and_targets(article.title, training_agent)
+    return HistoricalEvent(
+        event_id=f"{training_agent}-{article.timestamp.strftime('%Y%m%d%H%M%S')}-{article.article_id[:8]}",
+        timestamp=article.timestamp,
+        topic=topic,
+        region=training_agent if training_agent != "oversight" else "global",
+        actors=actors,
+        targets=targets,
+        severity=severity,
+        summary=article.title,
+        public_summary=article.title,
+        source_type="gdelt_historical_collection",
+        confirmed=True,
+        tags=sorted(set([*article.tags, topic, article.domain])),
+        impact=infer_impact(training_agent, topic, severity, polarity),
+    )
+
+
+def build_replay_definition(
+    *,
+    training_agent: str,
+    window: HistoricalCollectionWindow,
+    articles: list[CollectedHistoricalArticle],
+    max_events: int = 128,
+) -> HistoricalReplayDefinition:
+    events = [article_to_historical_event(article, training_agent=training_agent) for article in dedupe_articles(articles)]
+    events.sort(key=lambda item: item.timestamp)
+    events = events[:max_events]
+    return HistoricalReplayDefinition(
+        replay_id=f"{training_agent}_historical_{window.window_id}",
+        name=f"{training_agent.upper()} historical replay {window.start_date.isoformat()} to {window.end_date.isoformat()}",
+        description=(
+            "Historically collected replay built from allowlisted source domains via the GDELT DOC API. "
+            "Titles and impacts are heuristic and should be curator-reviewed before production post-training."
+        ),
+        training_agent=training_agent,
+        events=events,
+    )
+
+
+def dump_raw_articles(path: Path, articles: list[CollectedHistoricalArticle]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as handle:
+        for article in sorted(articles, key=lambda item: item.timestamp):
+            handle.write(article.model_dump_json())
+            handle.write("\n")
+
+
+def dump_replay_definition(path: Path, replay: HistoricalReplayDefinition) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(replay.model_dump_json(indent=2), encoding="utf-8")
+
+
+def format_gdelt_datetime(day: date, *, end_of_day: bool = False) -> str:
+    dt = datetime.combine(day, time.max if end_of_day else time.min, tzinfo=UTC)
+    return dt.strftime("%Y%m%d%H%M%S")

backend/src/trenches_env/historical_collection_cli.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import argparse
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from trenches_env.agents import AGENT_IDS
+from trenches_env.historical_collection import (
+    CollectedHistoricalArticle,
+    HistoricalCollectionWindow,
+    build_gdelt_query,
+    build_replay_definition,
+    build_source_profiles_for_agent,
+    build_article_id,
+    dump_raw_articles,
+    dump_replay_definition,
+    format_gdelt_datetime,
+    iter_month_windows,
+    parse_gdelt_datetime,
+    resolve_window,
+)
+
+GDELT_DOC_API = "https://api.gdeltproject.org/api/v2/doc/doc"
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Collect historical replay candidates into Trenches replay JSON format.")
+    parser.add_argument("--training-agent", choices=[*AGENT_IDS, "all"], default="us")
+    parser.add_argument("--window", action="append", choices=["2025", "2026"], default=["2025"])
+    parser.add_argument(
+        "--output-dir",
+        default="backend/src/trenches_env/historical_replays",
+        help="Directory for replay JSON files.",
+    )
+    parser.add_argument(
+        "--raw-dir",
+        default="backend/tmp-historical-raw",
+        help="Directory for raw collected article JSONL files.",
+    )
+    parser.add_argument("--max-records-per-query", type=int, default=50)
+    parser.add_argument("--max-events", type=int, default=128)
+    parser.add_argument("--timeout-seconds", type=float, default=30.0)
+    return parser.parse_args()
+
+
+def _fetch_gdelt_articles(
+    client: httpx.Client,
+    *,
+    agent_id: str,
+    window: HistoricalCollectionWindow,
+    max_records_per_query: int,
+) -> list[CollectedHistoricalArticle]:
+    articles: list[CollectedHistoricalArticle] = []
+    for profile in build_source_profiles_for_agent(agent_id):
+        query = build_gdelt_query(profile)
+        if not query:
+            continue
+        for month_window in iter_month_windows(window):
+            params = {
+                "query": query,
+                "mode": "artlist",
+                "format": "json",
+                "maxrecords": max_records_per_query,
+                "startdatetime": format_gdelt_datetime(month_window.start_date),
+                "enddatetime": format_gdelt_datetime(month_window.end_date - timedelta(days=1), end_of_day=True),
+                "sort": "datedesc",
+            }
+            response = client.get(GDELT_DOC_API, params=params)
+            response.raise_for_status()
+            payload = response.json()
+            for item in payload.get("articles", []):
+                url = str(item.get("url") or "").strip()
+                title = str(item.get("title") or "").strip()
+                seendate = str(item.get("seendate") or "").strip()
+                domain = str(item.get("domain") or "").strip()
+                if not url or not title or not seendate:
+                    continue
+                timestamp = parse_gdelt_datetime(seendate)
+                if timestamp.date() < window.start_date or timestamp.date() >= window.end_date:
+                    continue
+                articles.append(
+                    CollectedHistoricalArticle(
+                        article_id=build_article_id(url, timestamp),
+                        agent_id=agent_id,
+                        source_id=profile.source_id,
+                        source_name=profile.source_name,
+                        title=title,
+                        url=url,
+                        domain=domain or url.split("/")[2],
+                        timestamp=timestamp,
+                        query=query,
+                        window_id=window.window_id,
+                        tags=sorted(set([*profile.tags, *profile.query_terms[:3]])),
+                        language=item.get("language"),
+                        source_country=item.get("sourcecountry"),
+                    )
+                )
+    return articles
+
+
+def _collect_for_agent(
+    client: httpx.Client,
+    *,
+    agent_id: str,
+    windows: list[str],
+    output_dir: Path,
+    raw_dir: Path,
+    max_records_per_query: int,
+    max_events: int,
+) -> list[Path]:
+    written: list[Path] = []
+    for window_id in windows:
+        resolved_window = resolve_window(window_id, now=datetime.now(UTC))
+        articles = _fetch_gdelt_articles(
+            client,
+            agent_id=agent_id,
+            window=resolved_window,
+            max_records_per_query=max_records_per_query,
+        )
+        replay = build_replay_definition(
+            training_agent=agent_id,
+            window=resolved_window,
+            articles=articles,
+            max_events=max_events,
+        )
+        replay_path = output_dir / f"{replay.replay_id}.json"
+        raw_path = raw_dir / f"{replay.replay_id}.articles.jsonl"
+        dump_replay_definition(replay_path, replay)
+        dump_raw_articles(raw_path, articles)
+        written.append(replay_path)
+    return written
+
+
+def main() -> None:
+    args = _parse_args()
+    output_dir = Path(args.output_dir)
+    raw_dir = Path(args.raw_dir)
+    agent_ids = list(AGENT_IDS) if args.training_agent == "all" else [args.training_agent]
+
+    with httpx.Client(timeout=args.timeout_seconds, headers={"User-Agent": "trenches-historical-collector/0.1"}) as client:
+        written: list[Path] = []
+        for agent_id in agent_ids:
+            written.extend(
+                _collect_for_agent(
+                    client,
+                    agent_id=agent_id,
+                    windows=args.window,
+                    output_dir=output_dir,
+                    raw_dir=raw_dir,
+                    max_records_per_query=args.max_records_per_query,
+                    max_events=args.max_events,
+                )
+            )
+
+    for path in written:
+        print(path)
+
+
+if __name__ == "__main__":
+    main()

backend/src/trenches_env/historical_replay.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from importlib.resources import files
+
+from pydantic import BaseModel, Field
+
+from trenches_env.models import EventSeverity, HistoricalEvent
+
+
+class HistoricalReplayDefinition(BaseModel):
+    replay_id: str
+    name: str
+    description: str
+    training_agent: str = "us"
+    events: list[HistoricalEvent] = Field(default_factory=list)
+
+
+SEVERITY_SCORES: dict[EventSeverity, float] = {
+    "low": 0.25,
+    "medium": 0.5,
+    "high": 0.75,
+    "critical": 1.0,
+}
+
+SEVERITY_ORDER: tuple[EventSeverity, ...] = ("low", "medium", "high", "critical")
+
+
+@lru_cache(maxsize=1)
+def _load_replays() -> dict[str, HistoricalReplayDefinition]:
+    # Scan both dirs: historical_replays/ (curated real data) and
+    # synthetic_historical_replays/ (synthetic seed data for smoke-testing).
+    replay_dirs = [
+        files("trenches_env").joinpath("historical_replays"),
+        files("trenches_env").joinpath("synthetic_historical_replays"),
+    ]
+    replays: dict[str, HistoricalReplayDefinition] = {}
+    for replay_dir in replay_dirs:
+        try:
+            children = list(replay_dir.iterdir())
+        except (FileNotFoundError, TypeError):
+            continue
+        for child in children:
+            if not str(child).endswith(".json"):
+                continue
+            payload = json.loads(child.read_text(encoding="utf-8"))
+            replay = HistoricalReplayDefinition.model_validate(payload)
+            replays[replay.replay_id] = replay
+    return replays
+
+
+def list_historical_replays() -> list[HistoricalReplayDefinition]:
+    return [replay.model_copy(deep=True) for replay in _load_replays().values()]
+
+
+def get_historical_replay(replay_id: str) -> HistoricalReplayDefinition:
+    replay = _load_replays().get(replay_id)
+    if replay is None:
+        raise KeyError(replay_id)
+    return replay.model_copy(deep=True)
+
+
+def default_replay_id_for_agent(agent_id: str) -> str | None:
+    for replay in _load_replays().values():
+        if replay.training_agent == agent_id:
+            return replay.replay_id
+    return None
+
+
+def severity_score(severity: EventSeverity) -> float:
+    return SEVERITY_SCORES[severity]
+
+
+def severity_distance(expected: EventSeverity, actual: EventSeverity) -> int:
+    return abs(SEVERITY_ORDER.index(expected) - SEVERITY_ORDER.index(actual))

backend/src/trenches_env/historical_replays/hezbollah_2025_events.json

@@ -0,0 +1,1993 @@
+{
+  "replay_id": "hezbollah_2025_events",
+  "name": "HEZBOLLAH Real Events 2025",
+  "description": "Real historical events from 2025 relevant to the hezbollah entity. Source: Reubencf/2025_events HuggingFace dataset (68 events). Impact values are heuristic \u2014 curator review recommended before production training.",
+  "training_agent": "hezbollah",
+  "events": [
+    {
+      "event_id": "evt-2025-jan-07-d7a7aa3e",
+      "timestamp": "2025-01-07T12:00:00Z",
+      "topic": "security",
+      "region": "levant",
+      "actors": [
+        "hezbollah",
+        "gulf"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "medium",
+      "summary": "Lebanon approves the extradition of Abdul Rahman Yusuf, the son of late Egyptian ulama Yusuf al-Qaradawi, to the United Arab Emirates following his detention on December 28 after returning from Syria.",
+      "public_summary": "Lebanon approves the extradition of Abdul Rahman Yusuf, the son of late Egyptian ulama Yusuf al-Qaradawi, to the United Arab Emirates following his detention on December 28 after returning from Syria.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "security",
+        "law_and_crime",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 2.0,
+        "market_stress_delta": 1.0,
+        "oil_pressure_delta": 0.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-jan-09-03df61dc",
+      "timestamp": "2025-01-09T12:00:00Z",
+      "topic": "domestic",
+      "region": "levant",
+      "actors": [
+        "hezbollah",
+        "oversight"
+      ],
+      "targets": [
+        "civilians"
+      ],
+      "severity": "medium",
+      "summary": "2022\u20132025 Lebanese presidential election Military commander Joseph Aoun is elected as President of Lebanon, ending the power vacuum that began in October 2022.",
+      "public_summary": "2022\u20132025 Lebanese presidential election Military commander Joseph Aoun is elected as President of Lebanon, ending the power vacuum that began in October 2022.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "domestic",
+        "politics_and_elections",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 1.0,
+        "market_stress_delta": 1.5,
+        "oil_pressure_delta": 0.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-jan-11-6823bb50",
+      "timestamp": "2025-01-11T12:00:00Z",
+      "topic": "diplomacy",
+      "region": "levant",
+      "actors": [
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "medium",
+      "summary": "Lebanese prime minister Najib Mikati and Syrian de facto leader Ahmed al-Sharaa hold a meeting in Damascus, Syria, the first time that the two countries have met since the Syrian civil war began in 2011. (24 Digital) (MTV)",
+      "public_summary": "Lebanese prime minister Najib Mikati and Syrian de facto leader Ahmed al-Sharaa hold a meeting in Damascus, Syria, the first time that the two countries have met since the Syrian civil war began in 20",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "diplomacy",
+        "international_relations",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": -3.0,
+        "market_stress_delta": -2.0,
+        "oil_pressure_delta": -1.0,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-jan-13-cc2bf47a",
+      "timestamp": "2025-01-13T12:00:00Z",
+      "topic": "diplomacy",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah",
+        "oversight"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "2024 Israel\u2013Lebanon ceasefire agreement The Israel Defense Forces strike several Hezbollah sites in Lebanon, alleging that the targets violated the terms of the ceasefire agreement. (The Times of Israel)",
+      "public_summary": "2024 Israel\u2013Lebanon ceasefire agreement The Israel Defense Forces strike several Hezbollah sites in Lebanon, alleging that the targets violated the terms of the ceasefire agreement. (The Times of Isra",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "diplomacy",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": -4.5,
+        "market_stress_delta": -3.0,
+        "oil_pressure_delta": -1.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-jan-13-d53bb5ad",
+      "timestamp": "2025-01-13T12:00:00Z",
+      "topic": "domestic",
+      "region": "levant",
+      "actors": [
+        "hezbollah",
+        "oversight"
+      ],
+      "targets": [
+        "civilians",
+        "government"
+      ],
+      "severity": "medium",
+      "summary": "International Court of Justice President Nawaf Salam becomes the prime minister-designate of Lebanon after winning an absolute majority of votes from parliament, while stepping down from the ICJ. (TVN24)",
+      "public_summary": "International Court of Justice President Nawaf Salam becomes the prime minister-designate of Lebanon after winning an absolute majority of votes from parliament, while stepping down from the ICJ. (TVN",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "domestic",
+        "politics_and_elections",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 1.0,
+        "market_stress_delta": 1.5,
+        "oil_pressure_delta": 0.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-jan-26-36fdad2c",
+      "timestamp": "2025-01-26T12:00:00Z",
+      "topic": "diplomacy",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah",
+        "oversight"
+      ],
+      "targets": [
+        "civilians"
+      ],
+      "severity": "high",
+      "summary": "2024 Israel\u2013Lebanon ceasefire agreement January 2025 southern Lebanon attack Israeli soldiers open fire against the Lebanese Army and civilians in two villages in southern Lebanon, killing 22 people and wounding at least 124 more. (The Times of Israel)",
+      "public_summary": "2024 Israel\u2013Lebanon ceasefire agreement January 2025 southern Lebanon attack Israeli soldiers open fire against the Lebanese Army and civilians in two villages in southern Lebanon, killing 22 people a",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "diplomacy",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": -4.5,
+        "market_stress_delta": -3.0,
+        "oil_pressure_delta": -1.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-jan-26-294ead53",
+      "timestamp": "2025-01-26T12:00:00Z",
+      "topic": "diplomacy",
+      "region": "levant",
+      "actors": [
+        "us",
+        "israel",
+        "hezbollah",
+        "oversight"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "2024 Israel\u2013Lebanon ceasefire agreement The United States announces that the ceasefire between Israel and Lebanon will be extended to February 18. (Axios)",
+      "public_summary": "2024 Israel\u2013Lebanon ceasefire agreement The United States announces that the ceasefire between Israel and Lebanon will be extended to February 18. (Axios)",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "diplomacy",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": -4.5,
+        "market_stress_delta": -3.0,
+        "oil_pressure_delta": -1.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-jan-31-5d3ec117",
+      "timestamp": "2025-01-31T12:00:00Z",
+      "topic": "diplomacy",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah",
+        "oversight"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "2024 Israel\u2013Lebanon ceasefire agreement Two people are killed and ten others are injured during Israeli airstrikes in the Beqaa Valley, Lebanon.",
+      "public_summary": "2024 Israel\u2013Lebanon ceasefire agreement Two people are killed and ten others are injured during Israeli airstrikes in the Beqaa Valley, Lebanon.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "diplomacy",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": -4.5,
+        "market_stress_delta": -3.0,
+        "oil_pressure_delta": -1.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-feb-08-42563620",
+      "timestamp": "2025-02-08T12:00:00Z",
+      "topic": "border",
+      "region": "levant",
+      "actors": [
+        "hezbollah"
+      ],
+      "targets": [
+        "northern_front"
+      ],
+      "severity": "high",
+      "summary": "Four people are killed in border clashes between Syrian Hay'at Tahrir al-Sham and Lebanese clans. (Al-Monitor)",
+      "public_summary": "Four people are killed in border clashes between Syrian Hay'at Tahrir al-Sham and Lebanese clans. (Al-Monitor)",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "border",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 7.5,
+        "market_stress_delta": 1.5,
+        "oil_pressure_delta": 0.8,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-feb-08-221a1303",
+      "timestamp": "2025-02-08T12:00:00Z",
+      "topic": "domestic",
+      "region": "levant",
+      "actors": [
+        "hezbollah"
+      ],
+      "targets": [
+        "civilians",
+        "government"
+      ],
+      "severity": "medium",
+      "summary": "A new government is formed in Lebanon, with former International Court of Justice president Nawaf Salam as the new prime minister, following two years of the country under a caretaker government.",
+      "public_summary": "A new government is formed in Lebanon, with former International Court of Justice president Nawaf Salam as the new prime minister, following two years of the country under a caretaker government.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "domestic",
+        "politics_and_elections",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 1.0,
+        "market_stress_delta": 1.5,
+        "oil_pressure_delta": 0.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-feb-09-10b945ba",
+      "timestamp": "2025-02-09T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "Six people are killed and two others are wounded in Israeli airstrikes near Jannata, South Governorate, Lebanon.",
+      "public_summary": "Six people are killed and two others are wounded in Israeli airstrikes near Jannata, South Governorate, Lebanon.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-feb-15-d2808a36",
+      "timestamp": "2025-02-15T12:00:00Z",
+      "topic": "diplomacy",
+      "region": "levant",
+      "actors": [
+        "hezbollah",
+        "oversight"
+      ],
+      "targets": [
+        "infrastructure"
+      ],
+      "severity": "medium",
+      "summary": "2025 Beirut attack on UN convoy The Lebanese Armed Forces arrest over 25 people on suspicion of attacking a UNIFIL convoy and United Nations peacekeepers near Rafic Hariri International Airport in Beirut.",
+      "public_summary": "2025 Beirut attack on UN convoy The Lebanese Armed Forces arrest over 25 people on suspicion of attacking a UNIFIL convoy and United Nations peacekeepers near Rafic Hariri International Airport in Bei",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "diplomacy",
+        "law_and_crime",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": -3.0,
+        "market_stress_delta": -2.0,
+        "oil_pressure_delta": -1.0,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-feb-17-0eae2220",
+      "timestamp": "2025-02-17T12:00:00Z",
+      "topic": "diplomacy",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah",
+        "oversight"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "2024 Israel\u2013Lebanon ceasefire agreement Mohammad Shahin, a senior Hamas commander, is assassinated in an Israeli airstrike on a vehicle in Sidon, Lebanon. (Anadolu Ajans\u0131)",
+      "public_summary": "2024 Israel\u2013Lebanon ceasefire agreement Mohammad Shahin, a senior Hamas commander, is assassinated in an Israeli airstrike on a vehicle in Sidon, Lebanon. (Anadolu Ajans\u0131)",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "diplomacy",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": -4.5,
+        "market_stress_delta": -3.0,
+        "oil_pressure_delta": -1.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-feb-18-5cf1ac14",
+      "timestamp": "2025-02-18T12:00:00Z",
+      "topic": "conflict",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "Israel partially withdraws troops from Lebanon as the deadline for their withdrawal expires.",
+      "public_summary": "Israel partially withdraws troops from Lebanon as the deadline for their withdrawal expires.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "conflict",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 7.5,
+        "market_stress_delta": 3.0,
+        "oil_pressure_delta": 1.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-feb-23-996c089e",
+      "timestamp": "2025-02-23T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "Israel launches airstrikes in the Baalbek area in northeastern Lebanon and other areas in the south of the country. (Times of Israel)",
+      "public_summary": "Israel launches airstrikes in the Baalbek area in northeastern Lebanon and other areas in the south of the country. (Times of Israel)",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-feb-23-32a876cf",
+      "timestamp": "2025-02-23T12:00:00Z",
+      "topic": "domestic",
+      "region": "levant",
+      "actors": [
+        "hezbollah",
+        "oversight"
+      ],
+      "targets": [
+        "infrastructure"
+      ],
+      "severity": "medium",
+      "summary": "Funeral of Hassan Nasrallah and Hashem Safieddine The joint funeral for Hezbollah leaders Hassan Nasrallah and Hashem Safieddine is held at the Camille Chamoun Sports City Stadium in Beirut, Lebanon.",
+      "public_summary": "Funeral of Hassan Nasrallah and Hashem Safieddine The joint funeral for Hezbollah leaders Hassan Nasrallah and Hashem Safieddine is held at the Camille Chamoun Sports City Stadium in Beirut, Lebanon.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "domestic",
+        "politics_and_elections",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 1.0,
+        "market_stress_delta": 1.5,
+        "oil_pressure_delta": 0.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-mar-04-bf37eb45",
+      "timestamp": "2025-03-04T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "An Israeli drone strike in Tyre, Lebanon, kills Haidar Hashem, the head of naval forces in Hezbollah's Radwan Force. (Times of Israel)",
+      "public_summary": "An Israeli drone strike in Tyre, Lebanon, kills Haidar Hashem, the head of naval forces in Hezbollah's Radwan Force. (Times of Israel)",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-mar-17-c455ec67",
+      "timestamp": "2025-03-17T12:00:00Z",
+      "topic": "border",
+      "region": "levant",
+      "actors": [
+        "hezbollah"
+      ],
+      "targets": [
+        "government",
+        "northern_front"
+      ],
+      "severity": "high",
+      "summary": "Hezbollah involvement in the Syrian civil war, Hezbollah\u2013Syria relations Hezbollah\u2013Syria clashes, Lebanon\u2013Syria border clashes According to Syria's state media, clashes occur at the Lebanon\u2013Syria border, after the Syrian transitional government accused Hezbollah militants of kidnapping three soldier",
+      "public_summary": "Hezbollah involvement in the Syrian civil war, Hezbollah\u2013Syria relations Hezbollah\u2013Syria clashes, Lebanon\u2013Syria border clashes According to Syria's state media, clashes occur at the Lebanon\u2013Syria bord",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "border",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 7.5,
+        "market_stress_delta": 1.5,
+        "oil_pressure_delta": 0.8,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-mar-22-8beb634e",
+      "timestamp": "2025-03-22T12:00:00Z",
+      "topic": "diplomacy",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah",
+        "oversight"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "Six people, including a child, are killed by Israeli airstrikes in Lebanon in the heaviest exchange of fire since the ceasefire with the Lebanese militant group Hezbollah almost four months ago. The strikes were carried out in retaliation for rockets from Lebanon being fired into Israel. (CTV News)",
+      "public_summary": "Six people, including a child, are killed by Israeli airstrikes in Lebanon in the heaviest exchange of fire since the ceasefire with the Lebanese militant group Hezbollah almost four months ago. The s",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "diplomacy",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": -4.5,
+        "market_stress_delta": -3.0,
+        "oil_pressure_delta": -1.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-mar-28-784c03ba",
+      "timestamp": "2025-03-28T12:00:00Z",
+      "topic": "diplomacy",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah",
+        "oversight"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "2024 Israel\u2013Lebanon ceasefire agreement The Israel Defense Forces strikes southern Beirut, Lebanon, for the first time since November 2024, violating the ceasefire agreement.",
+      "public_summary": "2024 Israel\u2013Lebanon ceasefire agreement The Israel Defense Forces strikes southern Beirut, Lebanon, for the first time since November 2024, violating the ceasefire agreement.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "diplomacy",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": -4.5,
+        "market_stress_delta": -3.0,
+        "oil_pressure_delta": -1.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-apr-01-abc80e69",
+      "timestamp": "2025-04-01T12:00:00Z",
+      "topic": "diplomacy",
+      "region": "levant",
+      "actors": [
+        "us",
+        "israel",
+        "hezbollah",
+        "oversight"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "2024 Israel\u2013Lebanon ceasefire agreement Four people are killed, including Hassan Bdeir, a high-ranking Hezbollah official, and seven others are injured by an Israeli airstrike on a building in Dahieh, Beirut, Lebanon.",
+      "public_summary": "2024 Israel\u2013Lebanon ceasefire agreement Four people are killed, including Hassan Bdeir, a high-ranking Hezbollah official, and seven others are injured by an Israeli airstrike on a building in Dahieh,",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "diplomacy",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": -4.5,
+        "market_stress_delta": -3.0,
+        "oil_pressure_delta": -1.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-apr-16-a1545048",
+      "timestamp": "2025-04-16T12:00:00Z",
+      "topic": "security",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "The Lebanese military detains a group of people, including several Palestinians, for firing rockets towards Israel in two separate attacks. Hezbollah denies their involvement in the rocket attacks.",
+      "public_summary": "The Lebanese military detains a group of people, including several Palestinians, for firing rockets towards Israel in two separate attacks. Hezbollah denies their involvement in the rocket attacks.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "security",
+        "law_and_crime",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 3.0,
+        "market_stress_delta": 1.5,
+        "oil_pressure_delta": 0.8,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-apr-27-6e271ef9",
+      "timestamp": "2025-04-27T12:00:00Z",
+      "topic": "diplomacy",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah",
+        "oversight"
+      ],
+      "targets": [
+        "infrastructure"
+      ],
+      "severity": "high",
+      "summary": "Israel carries out airstrikes on several suburbs of Beirut, Lebanon, despite a ceasefire agreement following the 2024 invasion. The Lebanese Civil Defense reports no casualties.",
+      "public_summary": "Israel carries out airstrikes on several suburbs of Beirut, Lebanon, despite a ceasefire agreement following the 2024 invasion. The Lebanese Civil Defense reports no casualties.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "diplomacy",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": -4.5,
+        "market_stress_delta": -3.0,
+        "oil_pressure_delta": -1.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-may-04-4ef8e5be",
+      "timestamp": "2025-05-04T12:00:00Z",
+      "topic": "domestic",
+      "region": "levant",
+      "actors": [
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "medium",
+      "summary": "2025 Lebanese municipal elections First round of voting in the Lebanese municipal elections begin in the Mount Lebanon Governorate and Keserwan-Jbeil Governorate. (NBC News)",
+      "public_summary": "2025 Lebanese municipal elections First round of voting in the Lebanese municipal elections begin in the Mount Lebanon Governorate and Keserwan-Jbeil Governorate. (NBC News)",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "domestic",
+        "politics_and_elections",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 1.0,
+        "market_stress_delta": 1.5,
+        "oil_pressure_delta": 0.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-may-11-453debd8",
+      "timestamp": "2025-05-11T12:00:00Z",
+      "topic": "conflict",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "medium",
+      "summary": "The body of Israel Defense Forces soldier Zvi Feldman, missing since the 1982 Lebanon War, is repatriated to Israel from \"deep inside Syria\" in a joint Mossad\u2013IDF operation. (The Times of Israel)",
+      "public_summary": "The body of Israel Defense Forces soldier Zvi Feldman, missing since the 1982 Lebanon War, is repatriated to Israel from \"deep inside Syria\" in a joint Mossad\u2013IDF operation. (The Times of Israel)",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "conflict",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 5.0,
+        "market_stress_delta": 2.0,
+        "oil_pressure_delta": 1.0,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-may-14-3fd3730d",
+      "timestamp": "2025-05-14T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "The Israel Defense Forces claim that a drone strike in Qaaqaait al-Jisr, Nabatieh Governorate, Lebanon, killed a Hezbollah commander. (The Times of Israel)",
+      "public_summary": "The Israel Defense Forces claim that a drone strike in Qaaqaait al-Jisr, Nabatieh Governorate, Lebanon, killed a Hezbollah commander. (The Times of Israel)",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-jun-03-8ce77e7e",
+      "timestamp": "2025-06-03T12:00:00Z",
+      "topic": "security",
+      "region": "levant",
+      "actors": [
+        "hezbollah",
+        "oversight"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "A court in Stuttgart, Germany, sentences a Syrian man to life in prison under universal jurisdiction for leading a Hezbollah-backed group and committing alleged war crimes against Sunni Muslims in Busra al-Sham, Syria, during the Syrian civil war. (DW)",
+      "public_summary": "A court in Stuttgart, Germany, sentences a Syrian man to life in prison under universal jurisdiction for leading a Hezbollah-backed group and committing alleged war crimes against Sunni Muslims in Bus",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "security",
+        "law_and_crime",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 3.0,
+        "market_stress_delta": 1.5,
+        "oil_pressure_delta": 0.8,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-jun-05-284cb00e",
+      "timestamp": "2025-06-05T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "us",
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "Israeli Air Force jets launch airstrikes on southern Beirut, Lebanon, targeting alleged underground Hezbollah drone manufacturing facilities. (T\u00fcrkiye Today) (Al-Monitor)",
+      "public_summary": "Israeli Air Force jets launch airstrikes on southern Beirut, Lebanon, targeting alleged underground Hezbollah drone manufacturing facilities. (T\u00fcrkiye Today) (Al-Monitor)",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-jun-28-1c0ebb59",
+      "timestamp": "2025-06-28T12:00:00Z",
+      "topic": "conflict",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "Three people are killed by Israeli attacks on multiple vehicles in southern Lebanon.",
+      "public_summary": "Three people are killed by Israeli attacks on multiple vehicles in southern Lebanon.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "conflict",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 7.5,
+        "market_stress_delta": 3.0,
+        "oil_pressure_delta": 1.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-jul-06-599bfcd6",
+      "timestamp": "2025-07-06T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "Israel conducts four drone strikes in Bint Jbeil, Shebaa, and Shaqra, in southern Lebanon over the weekend, killing one person and injuring several others.",
+      "public_summary": "Israel conducts four drone strikes in Bint Jbeil, Shebaa, and Shaqra, in southern Lebanon over the weekend, killing one person and injuring several others.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-jul-08-ef9f612a",
+      "timestamp": "2025-07-08T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "An Israeli airstrike kills at least three people and injures 13 others in an attack on Tripoli, Lebanon.",
+      "public_summary": "An Israeli airstrike kills at least three people and injures 13 others in an attack on Tripoli, Lebanon.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-jul-15-373cb31b",
+      "timestamp": "2025-07-15T12:00:00Z",
+      "topic": "diplomacy",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah",
+        "oversight"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "At least 12 people are killed in Israeli air strikes in Lebanon's eastern Bekaa Valley. The missiles struck a number of military compounds belonging to the armed group Hezbollah, including training camps affiliated to its elite Radwan Force. These were the deadliest strikes since a ceasefire ended a",
+      "public_summary": "At least 12 people are killed in Israeli air strikes in Lebanon's eastern Bekaa Valley. The missiles struck a number of military compounds belonging to the armed group Hezbollah, including training ca",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "diplomacy",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": -4.5,
+        "market_stress_delta": -3.0,
+        "oil_pressure_delta": -1.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-jul-24-911b9aa0",
+      "timestamp": "2025-07-24T12:00:00Z",
+      "topic": "security",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "infrastructure"
+      ],
+      "severity": "medium",
+      "summary": "Hungary\u2013Israel relations, Hungary\u2013United Kingdom relations Hungary bans Irish rap trio Kneecap for three years ahead of a music festival, citing a national security threat over their alleged support for Hamas and Hezbollah. (The Times of Israel)",
+      "public_summary": "Hungary\u2013Israel relations, Hungary\u2013United Kingdom relations Hungary bans Irish rap trio Kneecap for three years ahead of a music festival, citing a national security threat over their alleged support f",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "security",
+        "law_and_crime",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 2.0,
+        "market_stress_delta": 1.0,
+        "oil_pressure_delta": 0.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-jul-29-3e354f7d",
+      "timestamp": "2025-07-29T12:00:00Z",
+      "topic": "diplomacy",
+      "region": "levant",
+      "actors": [
+        "hezbollah",
+        "oversight"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "Lebanon convicts and sentences six people who are accused of killing a United Nations peacekeeper in Beirut in 2023.",
+      "public_summary": "Lebanon convicts and sentences six people who are accused of killing a United Nations peacekeeper in Beirut in 2023.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "diplomacy",
+        "law_and_crime",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": -4.5,
+        "market_stress_delta": -3.0,
+        "oil_pressure_delta": -1.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-aug-07-dfc4fcd9",
+      "timestamp": "2025-08-07T12:00:00Z",
+      "topic": "domestic",
+      "region": "levant",
+      "actors": [
+        "us",
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "medium",
+      "summary": "The cabinet of Lebanon approves a U.S. proposal for disarming Hezbollah by the end of the year, along with ending Israel's occupation in the country, despite Hezbollah's rejection of this demand.",
+      "public_summary": "The cabinet of Lebanon approves a U.S. proposal for disarming Hezbollah by the end of the year, along with ending Israel's occupation in the country, despite Hezbollah's rejection of this demand.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "domestic",
+        "politics_and_elections",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 1.0,
+        "market_stress_delta": 1.5,
+        "oil_pressure_delta": 0.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-aug-09-ecc2fce9",
+      "timestamp": "2025-08-09T12:00:00Z",
+      "topic": "border",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "northern_front"
+      ],
+      "severity": "high",
+      "summary": "At least six Lebanese soldiers are killed in an explosion while removing munitions from a Hezbollah facility near the Israeli border. (Al Arabiya)",
+      "public_summary": "At least six Lebanese soldiers are killed in an explosion while removing munitions from a Hezbollah facility near the Israeli border. (Al Arabiya)",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "border",
+        "disasters_and_accidents",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 7.5,
+        "market_stress_delta": 1.5,
+        "oil_pressure_delta": 0.8,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-aug-28-53dcd36c",
+      "timestamp": "2025-08-28T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "infrastructure"
+      ],
+      "severity": "high",
+      "summary": "The Lebanese army reports that two soldiers were killed and two others were injured after an Israeli drone crashed and exploded in An-Naqoura, southern Lebanon, while they were inspecting it.",
+      "public_summary": "The Lebanese army reports that two soldiers were killed and two others were injured after an Israeli drone crashed and exploded in An-Naqoura, southern Lebanon, while they were inspecting it.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-aug-28-901efa72",
+      "timestamp": "2025-08-28T12:00:00Z",
+      "topic": "diplomacy",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah",
+        "oversight"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "The United Nations Security Council votes unanimously to withdraw its peacekeeping mission in Lebanon on December 31, 2026.",
+      "public_summary": "The United Nations Security Council votes unanimously to withdraw its peacekeeping mission in Lebanon on December 31, 2026.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "diplomacy",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": -4.5,
+        "market_stress_delta": -3.0,
+        "oil_pressure_delta": -1.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-sep-08-2deaa7a0",
+      "timestamp": "2025-09-08T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "Five people are killed and five others injured during at least eight Israeli airstrikes between Beqaa Valley and Hermel, in Lebanon.",
+      "public_summary": "Five people are killed and five others injured during at least eight Israeli airstrikes between Beqaa Valley and Hermel, in Lebanon.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-sep-09-6ee67073",
+      "timestamp": "2025-09-09T12:00:00Z",
+      "topic": "diplomacy",
+      "region": "levant",
+      "actors": [
+        "us",
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "proxy_corridor"
+      ],
+      "severity": "medium",
+      "summary": "Iraq\u2013Israel relations, Iraq\u2013United States relations Iraqi Shia militia Kata'ib Hezbollah releases Russian\u2013Israeli researcher Elizabeth Tsurkov who was abducted in 2023 during a research trip to Iraq following negotiations involving Israel and the United States. (CNBC)",
+      "public_summary": "Iraq\u2013Israel relations, Iraq\u2013United States relations Iraqi Shia militia Kata'ib Hezbollah releases Russian\u2013Israeli researcher Elizabeth Tsurkov who was abducted in 2023 during a research trip to Iraq f",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "diplomacy",
+        "international_relations",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": -3.0,
+        "market_stress_delta": -2.0,
+        "oil_pressure_delta": -1.0,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-sep-16-1203ea8d",
+      "timestamp": "2025-09-16T12:00:00Z",
+      "topic": "security",
+      "region": "levant",
+      "actors": [
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "Bulgarian police arrest the owner of the ship that brought explosive material to Beirut, Lebanon, which caused an explosion in August 2020 that killed more than 200 people.",
+      "public_summary": "Bulgarian police arrest the owner of the ship that brought explosive material to Beirut, Lebanon, which caused an explosion in August 2020 that killed more than 200 people.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "security",
+        "law_and_crime",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 3.0,
+        "market_stress_delta": 1.5,
+        "oil_pressure_delta": 0.8,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-sep-21-eaa27044",
+      "timestamp": "2025-09-21T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "Five people are killed and two others are injured in an Israeli drone strike on a vehicle in Bint Jbeil, Lebanon.",
+      "public_summary": "Five people are killed and two others are injured in an Israeli drone strike on a vehicle in Bint Jbeil, Lebanon.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-sep-26-46695b30",
+      "timestamp": "2025-09-26T12:00:00Z",
+      "topic": "security",
+      "region": "levant",
+      "actors": [
+        "us",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "medium",
+      "summary": "Lebanese authorities release former central bank governor Riad Salameh after he posts bail of US$14 million and LL 5 billion ($55,866) while facing ongoing charges of alleged financial crimes.",
+      "public_summary": "Lebanese authorities release former central bank governor Riad Salameh after he posts bail of US$14 million and LL 5 billion ($55,866) while facing ongoing charges of alleged financial crimes.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "security",
+        "law_and_crime",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 2.0,
+        "market_stress_delta": 1.0,
+        "oil_pressure_delta": 0.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-sep-28-97d06874",
+      "timestamp": "2025-09-28T12:00:00Z",
+      "topic": "disaster",
+      "region": "levant",
+      "actors": [
+        "us",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "Four people are killed and another six people affected after a fire in a building in Lebanon, Pennsylvania, United States. (MSN)",
+      "public_summary": "Four people are killed and another six people affected after a fire in a building in Lebanon, Pennsylvania, United States. (MSN)",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "disaster",
+        "disasters_and_accidents",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 1.5,
+        "market_stress_delta": 3.0,
+        "oil_pressure_delta": 1.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-oct-07-9974fc64",
+      "timestamp": "2025-10-07T12:00:00Z",
+      "topic": "diplomacy",
+      "region": "levant",
+      "actors": [
+        "hezbollah"
+      ],
+      "targets": [
+        "infrastructure"
+      ],
+      "severity": "medium",
+      "summary": "Foreign relations of the Holy See Visit by Pope Leo XIV to Turkey and Lebanon The Holy See Press Office announces that Pope Leo XIV will visit \u0130znik, Turkey, the location of the ancient city Nicaea, and Lebanon in November and December as his first papal visits abroad. (The Catholic Herald) (Anadolu",
+      "public_summary": "Foreign relations of the Holy See Visit by Pope Leo XIV to Turkey and Lebanon The Holy See Press Office announces that Pope Leo XIV will visit \u0130znik, Turkey, the location of the ancient city Nicaea, a",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "diplomacy",
+        "international_relations",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": -3.0,
+        "market_stress_delta": -2.0,
+        "oil_pressure_delta": -1.0,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-oct-10-6494d5d9",
+      "timestamp": "2025-10-10T12:00:00Z",
+      "topic": "conflict",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "government"
+      ],
+      "severity": "high",
+      "summary": "Israel\u2013Hezbollah conflict (2023\u2013present) The Lebanese government announces the arrest of a network affiliated to Israel which attempted to carry out assassinations and bombing attacks, mainly during a commemoration ceremony for the assassinated Hezbollah leader Hassan Nasrallah.",
+      "public_summary": "Israel\u2013Hezbollah conflict (2023\u2013present) The Lebanese government announces the arrest of a network affiliated to Israel which attempted to carry out assassinations and bombing attacks, mainly during a",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "conflict",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 7.5,
+        "market_stress_delta": 3.0,
+        "oil_pressure_delta": 1.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-oct-11-f7370a76",
+      "timestamp": "2025-10-11T12:00:00Z",
+      "topic": "conflict",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "One person is killed, seven others are injured, dozens of bulldozers are destroyed, and a key route connecting Beirut to Lebanon's south is severed in Israeli attacks in Msayleh, An-Najjariyah, Lebanon. (Naharnetnet)",
+      "public_summary": "One person is killed, seven others are injured, dozens of bulldozers are destroyed, and a key route connecting Beirut to Lebanon's south is severed in Israeli attacks in Msayleh, An-Najjariyah, Lebano",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "conflict",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 7.5,
+        "market_stress_delta": 3.0,
+        "oil_pressure_delta": 1.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-oct-16-f53c3e02",
+      "timestamp": "2025-10-16T12:00:00Z",
+      "topic": "conflict",
+      "region": "levant",
+      "actors": [
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "Heavy armed clashes break out in Zawiya, Tripolitania, Libya, after the attempted assassination of Reserve Force commander Suleiman Al-Fitouri. (Xinhua News Agency)",
+      "public_summary": "Heavy armed clashes break out in Zawiya, Tripolitania, Libya, after the attempted assassination of Reserve Force commander Suleiman Al-Fitouri. (Xinhua News Agency)",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "conflict",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 7.5,
+        "market_stress_delta": 3.0,
+        "oil_pressure_delta": 1.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-oct-23-99d61a03",
+      "timestamp": "2025-10-23T12:00:00Z",
+      "topic": "military",
+      "region": "gulf",
+      "actors": [
+        "israel",
+        "hezbollah",
+        "gulf"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "Four people, including an elderly woman, are killed in a series of Israeli airstrikes in eastern and southern Lebanon.",
+      "public_summary": "Four people, including an elderly woman, are killed in a series of Israeli airstrikes in eastern and southern Lebanon.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "gulf"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-oct-24-f15a2436",
+      "timestamp": "2025-10-24T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "Three people are killed and two others injured during two Israeli airstrikes against two vehicles in Toul and Nabatieh, Lebanon. Senior Hezbollah commander Abbas Karki is among the fatalities. (AA)",
+      "public_summary": "Three people are killed and two others injured during two Israeli airstrikes against two vehicles in Toul and Nabatieh, Lebanon. Senior Hezbollah commander Abbas Karki is among the fatalities. (AA)",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-oct-25-4adb2abc",
+      "timestamp": "2025-10-25T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "Two people are killed during two Israeli airstrikes against a car and a motorcycle in Harouf and Qlayleh, Lebanon, bringing the death toll from the attacks since the past 48 hours to nine.",
+      "public_summary": "Two people are killed during two Israeli airstrikes against a car and a motorcycle in Harouf and Qlayleh, Lebanon, bringing the death toll from the attacks since the past 48 hours to nine.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-oct-26-6e2fdfe0",
+      "timestamp": "2025-10-26T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "Three people are killed in two Israeli airstrikes in An-Naqoura and Baalbek, Lebanon. Separately, an Israeli drone drops a grenade near UNIFIL forces in Kfar Kila, without casualties.",
+      "public_summary": "Three people are killed in two Israeli airstrikes in An-Naqoura and Baalbek, Lebanon. Separately, an Israeli drone drops a grenade near UNIFIL forces in Kfar Kila, without casualties.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-oct-30-d623fb35",
+      "timestamp": "2025-10-30T12:00:00Z",
+      "topic": "border",
+      "region": "israel",
+      "actors": [
+        "israel",
+        "hezbollah",
+        "oversight"
+      ],
+      "targets": [
+        "civilians"
+      ],
+      "severity": "high",
+      "summary": "Israeli troops enter the southern Lebanese city of Blida and storm the municipal hall, killing an employee while sleeping. In response, Lebanese president Joseph Aoun orders the military to confront any Israeli incursions.",
+      "public_summary": "Israeli troops enter the southern Lebanese city of Blida and storm the municipal hall, killing an employee while sleeping. In response, Lebanese president Joseph Aoun orders the military to confront a",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "border",
+        "armed_conflicts_and_attacks",
+        "israel"
+      ],
+      "impact": {
+        "tension_delta": 7.5,
+        "market_stress_delta": 1.5,
+        "oil_pressure_delta": 0.8,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-nov-01-99cb3eee",
+      "timestamp": "2025-11-01T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "Four people are killed and three injured in an Israeli airstrike on a vehicle in Kfar Reman, Lebanon.",
+      "public_summary": "Four people are killed and three injured in an Israeli airstrike on a vehicle in Kfar Reman, Lebanon.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-nov-10-eb28755c",
+      "timestamp": "2025-11-10T12:00:00Z",
+      "topic": "security",
+      "region": "levant",
+      "actors": [
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "medium",
+      "summary": "Lebanon grants a US$900,000 bail to Hannibal Gaddafi, the son of former Libyan leader Muammar Gaddafi, ending his nearly 10-year detention in a case involving the 1978 disappearance of Shia Muslim cleric Musa al-Sadr, for which Gaddafi was accused of withholding information but never tried.",
+      "public_summary": "Lebanon grants a US$900,000 bail to Hannibal Gaddafi, the son of former Libyan leader Muammar Gaddafi, ending his nearly 10-year detention in a case involving the 1978 disappearance of Shia Muslim cle",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "security",
+        "law_and_crime",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 2.0,
+        "market_stress_delta": 1.0,
+        "oil_pressure_delta": 0.5,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-nov-18-cdfe2fae",
+      "timestamp": "2025-11-18T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "civilians"
+      ],
+      "severity": "high",
+      "summary": "Thirteen people are killed and several others are wounded in an Israeli airstrike in the Ain al-Hilweh Palestinian refugee camp in Sidon District, Lebanon. (MENA via The New Arab)",
+      "public_summary": "Thirteen people are killed and several others are wounded in an Israeli airstrike in the Ain al-Hilweh Palestinian refugee camp in Sidon District, Lebanon. (MENA via The New Arab)",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-nov-18-ec6565fe",
+      "timestamp": "2025-11-18T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "Two people are killed in two separate Israeli airstrikes on vehicles in Bint Jbeil and Marjayoun, Lebanon. (L'Orient Today)",
+      "public_summary": "Two people are killed in two separate Israeli airstrikes on vehicles in Bint Jbeil and Marjayoun, Lebanon. (L'Orient Today)",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-nov-19-e4cdfd62",
+      "timestamp": "2025-11-19T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "us",
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "One person is killed in an Israeli airstrike attack against a vehicle in Bint Jbeil, Lebanon. Several students are also wounded on a bus passing in the area.",
+      "public_summary": "One person is killed in an Israeli airstrike attack against a vehicle in Bint Jbeil, Lebanon. Several students are also wounded on a bus passing in the area.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-nov-22-1df578e2",
+      "timestamp": "2025-11-22T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "A person is killed in an Israeli airstrike on a car in Zawtar al-Sharqiyah, Lebanon, while several more attacks are carried out across Kafr Rumman.",
+      "public_summary": "A person is killed in an Israeli airstrike on a car in Zawtar al-Sharqiyah, Lebanon, while several more attacks are carried out across Kafr Rumman.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-nov-23-3f1e2172",
+      "timestamp": "2025-11-23T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "November 2025 Israeli attack in Beirut Israel carries out an airstrike on a building in Beirut, Lebanon, killing five Hezbollah militants and injuring 28 others. Hezbollah military chief Haytham Ali Tabatabai\u00a0is confirmed among the fatalities.",
+      "public_summary": "November 2025 Israeli attack in Beirut Israel carries out an airstrike on a building in Beirut, Lebanon, killing five Hezbollah militants and injuring 28 others. Hezbollah military chief Haytham Ali T",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-nov-26-4e3538d9",
+      "timestamp": "2025-11-26T12:00:00Z",
+      "topic": "culture",
+      "region": "levant",
+      "actors": [
+        "hezbollah"
+      ],
+      "targets": [
+        "infrastructure"
+      ],
+      "severity": "high",
+      "summary": "Holy See\u2013Lebanon relations, Holy See\u2013Turkey relations Visit by Pope Leo XIV to Turkey and Lebanon Pope Leo XIV begins his first papal trip, first to \u0130znik and Nicaea in Turkey, then to Bkerk\u00e9, the Monastery of Saint Maron, and the Port of Beirut in Lebanon. The trip will include an ecumenical commem",
+      "public_summary": "Holy See\u2013Lebanon relations, Holy See\u2013Turkey relations Visit by Pope Leo XIV to Turkey and Lebanon Pope Leo XIV begins his first papal trip, first to \u0130znik and Nicaea in Turkey, then to Bkerk\u00e9, the Mon",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "culture",
+        "arts_and_culture",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 0.0,
+        "market_stress_delta": 0.0,
+        "oil_pressure_delta": 0.0,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-nov-26-814de5ef",
+      "timestamp": "2025-11-26T12:00:00Z",
+      "topic": "shipping",
+      "region": "levant",
+      "actors": [
+        "us",
+        "hezbollah"
+      ],
+      "targets": [
+        "shipping_lanes"
+      ],
+      "severity": "medium",
+      "summary": "Cyprus and Lebanon sign a long-delayed maritime boundary agreement.",
+      "public_summary": "Cyprus and Lebanon sign a long-delayed maritime boundary agreement.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "shipping",
+        "international_relations",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 3.0,
+        "market_stress_delta": 4.0,
+        "oil_pressure_delta": 6.0,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-dec-08-614e2d74",
+      "timestamp": "2025-12-08T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "Israel carries out a wave of airstrikes in southern Lebanon, allegedly targeting Hezbollah's site.",
+      "public_summary": "Israel carries out a wave of airstrikes in southern Lebanon, allegedly targeting Hezbollah's site.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-dec-13-6ca8c26a",
+      "timestamp": "2025-12-13T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "The Israeli military issues an evacuation order in southern Lebanese villages in preparation for planned airstrikes on Hezbollah targets. (The Jerusalem Post)",
+      "public_summary": "The Israeli military issues an evacuation order in southern Lebanese villages in preparation for planned airstrikes on Hezbollah targets. (The Jerusalem Post)",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-dec-14-5d24227b",
+      "timestamp": "2025-12-14T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "Three people are killed in three separated Israeli airstrikes against vehicles in southern Lebanon. (L'Orient Today)",
+      "public_summary": "Three people are killed in three separated Israeli airstrikes against vehicles in southern Lebanon. (L'Orient Today)",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-dec-22-48c66d32",
+      "timestamp": "2025-12-22T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "Three people are killed in an Israeli airstrike against a vehicle near Sidon, Lebanon.",
+      "public_summary": "Three people are killed in an Israeli airstrike against a vehicle near Sidon, Lebanon.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-dec-24-30bada7a",
+      "timestamp": "2025-12-24T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "An alleged Hezbollah member is killed in an airstrike by the Israel Defense Forces on a vehicle near Jannata, Tyre District, South Governorate,  Lebanon. (MSN)",
+      "public_summary": "An alleged Hezbollah member is killed in an airstrike by the Israel Defense Forces on a vehicle near Jannata, Tyre District, South Governorate,  Lebanon. (MSN)",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    },
+    {
+      "event_id": "evt-2025-dec-25-7c508b87",
+      "timestamp": "2025-12-25T12:00:00Z",
+      "topic": "military",
+      "region": "levant",
+      "actors": [
+        "israel",
+        "iran",
+        "hezbollah"
+      ],
+      "targets": [
+        "general"
+      ],
+      "severity": "high",
+      "summary": "Israel\u2013Hezbollah conflict, Iran\u2013Israel relations Three people are killed in two separate Israeli airstrikes targeting vehicles in southern Lebanon, including a member of the Iranian Quds Force.",
+      "public_summary": "Israel\u2013Hezbollah conflict, Iran\u2013Israel relations Three people are killed in two separate Israeli airstrikes targeting vehicles in southern Lebanon, including a member of the Iranian Quds Force.",
+      "source_type": "hf_2025_events",
+      "confirmed": true,
+      "tags": [
+        "military",
+        "armed_conflicts_and_attacks",
+        "levant"
+      ],
+      "impact": {
+        "tension_delta": 9.0,
+        "market_stress_delta": 3.8,
+        "oil_pressure_delta": 2.2,
+        "actor_metric_deltas": {}
+      }
+    }
+  ]
+}