@neuroverseos/nv-sim 0.1.7 → 0.1.9

package/README.md

@@ -2,68 +2,54 @@
 
 **Change the rules. See why the system changed.**
 
-NV-SIM doesn't predict outcomes — it shows how systems change when you change the rules.
-
-Define a world. Set the constraints. Run the agents. Then change one rule and watch the entire system reorganize. Not in theory. You see exactly which agents shifted, what patterns emerged, and why the outcome changed.
-
-It feels a lot like a Prime Radiant — except instead of psychohistory, you're running controlled behavioral experiments on complex systems.
-
 ```bash
 npx @neuroverseos/nv-sim visualize
 ```
 
-## What This Actually Is
-
-Most simulation tools answer: *"What will happen?"*
+## The Problem With Agentic Simulation Today
 
-NV-SIM answers: *"What changes when I change the rules?"*
+You build a multi-agent system. You run it. You get metrics — loss curves, reward signals, completion rates. Something goes wrong, or something goes right, and you ask the only question that matters:
 
-You're not forecasting. You're experimenting. You change a constraint — no panic selling, cap leverage at 3x, close a shipping lane — and the system shows you:
+*Why did the agents do that?*
 
-- **How agents reorganize** (80% shifted from panic selling to coordinated holding)
-- **What patterns emerge** (panic suppression, stability shift)
-- **What the system became** (volatility dropped 21%, cascade avoided)
+Nobody can tell you. The metrics say *what* happened. The logs say *when* it happened. But nothing tells you *why agents changed their behavior* — which rule caused it, which agents shifted first, what strategy they abandoned, and what they replaced it with.
 
-```
-Rule changed
-  → Behavior shifted
-    → Pattern emerged
-      → System outcome changed
-```
+So you rerun. You tweak. You guess. You stare at dashboards full of numbers that describe the system but never explain it.
 
-That's the loop. Every time.
+That's the gap.
 
-## This Is a Runtime, Not Just a Simulator
+## What NV-SIM Gives You That Nothing Else Does
 
-NV-SIM runs in two modes:
+NV-SIM doesn't predict outcomes. It shows you **why agents behaved the way they did** — and what happens when you change the rules.
 
-- **Simulate** — explore how systems behave under different rules
-- **Act** — govern real agents, real workflows, and real decisions
+You change one constraint — block panic selling, cap leverage at 3x, close a shipping lane — and the system shows you:
 
-The interface is the same. The difference is where the behavior comes from.
+- **Before → After proof**: "80% of agents shifted from panic selling to coordinated holding"
+- **Emergent patterns**: "Panic suppression appeared — not programmed, not predicted"
+- **Causal chains**: "Agents became more cautious after early aggressive attempts failed"
+- **Quantified outcomes**: "Volatility dropped 21%, cascade avoided"
 
 ```
-Simulate → internal swarm engine
-Act      → external systems (agents, APIs, frameworks like OpenClaw)
+Rule changed
+  → Agents shifted strategy
+    → New patterns emerged
+      → System outcome changed
+        → You know exactly why
 ```
 
-In both cases:
+This is behavioral evidence, not metrics. You don't get a number — you get a story you can trace, verify, and share.
 
-```
-Action → Governance → Decision → Behavioral Shift → System Outcome
-```
+### For researchers
 
-You're not switching tools. You're switching the source of reality.
+You get **controlled behavioral experiments** on complex systems. Same agents, different rules, measured side by side. The output isn't a chart — it's proof of what changed and why.
 
-That's what makes this a runtime.
+### For developers
 
-The same world file can:
+You get **runtime governance** for any agent system. One HTTP call between "agent decides" and "agent acts." Your agents become observable, auditable, and controllable — without rewriting your framework.
 
-- simulate a crisis
-- govern a live system
-- produce comparable outcomes across both
+### For both
 
-Design the rules once. Run them anywhere.
+You get something that didn't exist before: **rule-to-behavior causation**. Not correlation. Not post-hoc analysis. Direct, traceable proof that changing rule X caused agents to shift from behavior A to behavior B.
 
 ## The Demo Moment
 
@@ -78,12 +64,17 @@ system: unstable
 
 **After:**
 ```
-80% of agents adapted
+Market stabilized as agents shifted toward safer positions
 
   panic_sell → hold
   panic_sell → hold
   panic_sell → hold
 
+  80% of agents shifted from aggressive to conservative strategies
+  Uncertainty dropped 34% as agents moved from exploration to caution
+
+  WHY: Agents became more cautious after early attempts failed
+
   Pattern: coordinated_holding
   Pattern: panic_suppression
 
@@ -91,123 +82,222 @@ system: unstable
   cascade: avoided
 ```
 
-You didn't predict this. You caused it — by changing one rule — and watched the system tell you why.
+You didn't predict this. You caused it — by changing one rule — and the system told you exactly why.
+
+## What This Actually Is
+
+Most simulation tools answer: *"What will happen?"*
+
+NV-SIM answers: *"What changes when I change the rules — and why?"*
+
+You're not forecasting. You're running controlled behavioral experiments. Every simulation produces:
+
+| What You Get | What It Proves |
+|---|---|
+| **Outcome statement** | System state + dominant agent behavior in one sentence |
+| **Behavioral shifts** | Before → after for every agent group, with percentages |
+| **Causal explanation** | Why agents changed — in their experience, not system jargon |
+| **Confidence rating** | How strong the evidence is, how much risk remains |
+| **Full audit trail** | Every decision, every rule, every adaptation — append-only |
+
+The output is designed to be specific, narrative, and shareable. Not "40% adjusted actions" — but "40% shifted from aggressive to conservative strategies after early attempts failed."
+
+## Design the Rules Once. Run Them Anywhere.
+
+NV-SIM is a runtime, not just a simulator. It runs in two modes:
+
+- **Simulate** — explore how agents behave under different rules
+- **Act** — govern real agents, real workflows, real decisions in production
+
+The interface is the same. The difference is where the agents come from.
+
+```
+Simulate → internal swarm engine (built-in agents, instant results)
+Act      → your system (any framework, any language, one HTTP call)
+```
+
+The same world file can simulate a crisis, govern a live system, and produce comparable outcomes across both. This means the experiments you run in simulation directly translate to the rules you deploy in production.
 
 ## Behavioral Analysis — The Proof Layer
 
-Blocking actions is easy. The hard part is proving what changed and why. NV-SIM doesn't just count blocked actions — it tracks how agents actually reorganized.
+Blocking actions is easy. The hard part is proving what changed and why. NV-SIM doesn't just count actions — it tracks how agents actually reorganized.
 
 Every simulation produces behavioral evidence:
 
-- **Action classification** — each agent action is categorized as aggressive, defensive, cautious, cooperative, opportunistic, or neutral
-- **Agent trajectories** — traces each agent's behavior across rounds, showing when and how they shifted
-- **Behavioral shifts** — detects the moment agents change strategy in response to governance
+- **Action classification** — each agent action categorized as aggressive, defensive, cautious, cooperative, opportunistic, or neutral
+- **Agent trajectories** — each agent's behavior traced across rounds, showing when and how they shifted
+- **Behavioral shifts** — the exact moment agents changed strategy, with before → after
 - **Cross-run comparison** — same agents under different rules, measured side by side
 
 ```
 BEHAVIORAL ANALYSIS
 
-  Action Distribution (governed):
+  Action Distribution:
     aggressive:    12%  (was 67%)
     cooperative:   41%  (was 8%)
     cautious:      31%  (was 11%)
     defensive:     16%  (was 14%)
 
   Shifts Detected:
-    → 80% of aggressive agents shifted to cooperative after round 3
+    → 80% shifted from aggressive to cooperative after round 3
     → Panic selling replaced by coordinated holding
     → New pattern: quality_competition (not present in baseline)
 
   Trajectory: agent_hedge_fund_1
-    Round 1: aggressive → Round 2: aggressive → Round 3: [BLOCK] → Round 4: cautious → Round 5: cooperative
+    Round 1: aggressive → Round 2: aggressive → Round 3: [shifted] → Round 4: cautious → Round 5: cooperative
 ```
 
-The governance isn't the insight. The behavioral shift is the insight. You changed a rule, and the system tells you exactly who changed, when they changed, and what they changed to.
+The behavioral shift is the insight. You changed a rule, and the system tells you exactly who changed, when they changed, and what they changed to.
 
 ## Audit Trail — Full Evidence Chain
 
-Every governance decision is recorded in an append-only audit log. Every rule firing, every agent action, every verdict — persistent and queryable.
+Every decision is recorded in an append-only audit log. Every rule, every agent action, every adaptation — persistent and queryable.
 
 ```
 AUDIT TRAIL (session: 2026-03-18T14:22:00)
 
-  [GOVERNANCE] agent_hedge_fund_1 → panic_sell → BLOCK
+  agent_hedge_fund_1 → attempted panic_sell → blocked
     rule: no_panic_selling (invariant)
     evidence: action matches blocked pattern during high volatility
 
-  [AGENT] agent_hedge_fund_1 → hold
+  agent_hedge_fund_1 → shifted to hold
     adapted: true (shifted from aggressive to defensive)
 
-  [BEHAVIORAL_SHIFT] agent_hedge_fund_1
+  BEHAVIORAL SHIFT: agent_hedge_fund_1
     before: aggressive | after: cautious
-    trigger: governance block at round 3
+    trigger: early aggressive attempts failed at round 3
+```
+
+Stored as JSONL — one JSON object per line, human-readable, pipeable through `jq`. No cloud, no deletion. Complete evidence chain.
+
+## Start Here — Define Your World
+
+NV-SIM ships with two template worlds. But the real power is **making your own**.
+
+### Option 1: Start from a template
+
+```bash
+npx @neuroverseos/nv-sim visualize    # Pick a template, adjust, run
 ```
 
-Stored as JSONL — one JSON object per line, human-readable, pipeable through `jq`. No cloud, no deletion. Complete evidence for governance accountability.
+### Option 2: Write your rules, we build the world
 
-## Worlds — Where the Power Lives
+Create a text file with your rules in plain English:
 
-Integration is one line. The world file controls everything.
+```
+# my-rules.txt
+Limit any agent to 15% of total posts per round
+Block coordinated posting from 3+ agents
+Dampen sentiment shifts larger than 0.3 per round
+Require source attribution for factual claims
+```
 
-The `world` you pass to `/api/evaluate` determines how actions are judged. Change the world, change the outcome.
+Then generate a full governed world from it:
 
+```bash
+npx @neuroverseos/nv-sim world-from-doc my-rules.txt --output my-world.json
 ```
-verdict = evaluate(actor="agent_1", action="panic_sell", world="trading")
-                                                          ^^^^^^^^
-                                                    this controls everything
+
+This doesn't just parse your rules — it generates a complete governed world: state variables, gates, invariants, thesis, and agent types. The same structure as the built-in templates. Your world is equal to ours.
+
+### Option 3: Upload a .nv world file
+
+```bash
+npx @neuroverseos/nv-sim serve --world my-world.json
 ```
 
-### Built-in Worlds
+Load any saved world file directly into the runtime.
+
+## Two Template Worlds
 
-| World | Domain | What You Can Change |
-|-------|--------|---------------------|
-| `trading` | Financial markets | Leverage ratio, liquidity index, volatility, circuit breakers |
-| `strait_of_hormuz` | Geopolitical energy | Oil supply disruption, military escalation, diplomatic channels |
-| `gas_price_spike` | Economic energy | Gas price, consumer sentiment, EV demand, grid capacity |
-| `ai_regulation_crisis` | Tech regulation | AI regulation impact on markets and sector alignment |
+NV-SIM ships with two complete governed worlds. These are templates — starting points for your own experiments.
+
+### `social_simulation` — Multi-Agent Social Simulation
+
+For anyone running agent-based social simulations (MiroFish, OASIS, or custom). Governs the dynamics that break realism regardless of topic.
+
+| State Variable | What It Controls |
+|---|---|
+| Opinion Diversity (0-100) | How spread out are opinions? Low = echo chamber |
+| Influence Concentration (0-100) | Gini coefficient of agent influence. High = monopoly |
+| Sentiment Polarity (0-100) | How extreme is overall sentiment? High = spiral |
+| Echo Chamber Strength | none → forming → established → dominant |
+| Active Agent % (0-100) | What % of agents participate per round |
+| Viral Amplification Threshold | How many interactions before amplification kicks in |
+
+**Default rules:**
+- Limit any agent to 15% of total posts per round
+- Dampen sentiment shifts > 0.3 per round
+- Block coordinated posting (same content from 3+ agents)
+- Require source attribution for factual claims
+- Monitor opinion diversity — alert below 30
+
+**Circuit breakers:** Echo Chamber Collapse (diversity < 20), Influence Monopoly (concentration > 70), Sentiment Spiral (polarity > 80)
+
+### `science_research` — Governed Research Pipeline
+
+For AI-assisted research workflows (ScienceClaw, autonomous discovery agents). Governs scientific rigor at every stage.
+
+| State Variable | What It Controls |
+|---|---|
+| Verified Sources (0-50) | How many peer-reviewed sources have been found |
+| Confidence Level (0-1) | How confident is the current hypothesis |
+| Hypothesis Validated | Has the hypothesis been confirmed by multiple sources |
+| Peer Review Status | none → submitted → reviewed → approved |
+| Publication Readiness % | How close to publication-ready |
+
+**Default rules:**
+- Literature search must return 2+ peer-reviewed sources before analysis
+- Claims must cite specific sources — unsupported assertions blocked
+- Publication requires confidence > 0.7 and validated hypothesis
+- Cross-referencing must compare 3+ independent sources
+- Recommendations must include uncertainty language when confidence < 0.9
+
+**Circuit breakers:** Insufficient Evidence, Premature Publication, Low Confidence Alert
 
 ### Same Agents, Different Rules
 
 ```bash
-npx @neuroverseos/nv-sim worlds trading strait_of_hormuz
+npx @neuroverseos/nv-sim worlds social_simulation science_research
 ```
 
 Same agents. Different rules. Different outcomes. That's the experiment.
 
 ## Narrative Shocks
 
-Inject events into running simulations. Watch them propagate differently through different agents — a bank collapse hits retail investors and algorithmic traders in completely different ways.
+Inject events into running simulations. Different agents react differently to the same event.
 
 ```bash
-npx @neuroverseos/nv-sim compare --inject tanker_explosion@3,sanctions@5
+npx @neuroverseos/nv-sim compare --inject viral_misinfo@3,algorithm_change@5
 ```
 
 The `@` syntax sets when the event hits. Events have severity, propagation speed, and directional impact.
 
+### Social simulation events
+`viral_misinfo`, `influencer_stance_change`, `algorithm_change`, `external_news_event`, `coordinated_campaign`, `whistleblower_post`
+
+### Research events
+`search_literature`, `analyze_findings`, `cross_reference`, `unsupported_claim`, `hypothesis_validated`, `publish_result`
+
 ## Named Scenarios
 
-Pre-built crisis sequences — a world + ordered narrative events:
+Pre-built sequences — a world + ordered narrative events:
 
 ```bash
-npx @neuroverseos/nv-sim scenario taiwan_crisis
-npx @neuroverseos/nv-sim scenario bank_run --compare
+npx @neuroverseos/nv-sim scenario echo_chamber
+npx @neuroverseos/nv-sim scenario research_pipeline
 npx @neuroverseos/nv-sim scenarios              # list all
 ```
 
-| Scenario | Events | What It Tests |
-|----------|--------|---------------|
-| `taiwan_crisis` | 4 | Military escalation + sanctions + shipping disruption |
-| `hormuz_blockade` | 3 | Tanker attack escalates to full shipping disruption |
-| `bank_run` | 4 | Bank insolvency triggers contagion cascade |
-| `flash_cascade` | 3 | Algorithmic failure chain reaction |
-| `oil_shock` | 4 | Tanker attack + sanctions compound crisis |
-| `energy_transition_shock` | 3 | Grid failure during rapid transition |
-| `election_shock` | 4 | Political shock cascades into markets |
-| `ai_crackdown` | 3 | Overnight AI regulation triggers panic |
-| `perfect_storm` | 6 | Geopolitical + financial + energy convergence |
-| `black_swan` | 5 | Extreme low-probability events in succession |
+| Scenario | World | Events | What It Tests |
+|----------|-------|--------|---------------|
+| `echo_chamber` | social_simulation | 3 | Opinion diversity collapses into self-reinforcing groups |
+| `influence_monopoly` | social_simulation | 3 | Small group dominates discourse |
+| `sentiment_spiral` | social_simulation | 4 | Negativity feeds on itself until unrealistic |
+| `platform_shock` | social_simulation | 3 | Algorithm change reshapes engagement overnight |
+| `research_pipeline` | science_research | 6 | Full research workflow with governance at each step |
 
-The `--compare` flag runs the same scenario across multiple worlds — which rule environment is more resilient?
+The `--compare` flag runs the same scenario across both worlds — which rule environment is more resilient?
 
 ## Interactive Control Platform
 
@@ -221,68 +311,68 @@ This opens a control surface where you can:
 - Adjust state variables with auto-generated controls
 - Inject narrative events at specific rounds
 - Load crisis scenarios with one click
-- Watch the **System Shift card** — not a log of what happened, but a story of what the system became
+- Watch the **Outcome Panel** — not a log of what happened, but a story of what the system became and why
 - Save any experiment as a reusable variant
 
-### The System Shift Card
+### The Outcome Panel
 
-When rules reshape behavior, you don't get a log. You get this:
+When rules reshape behavior, you don't get a dashboard of metrics. You get this:
 
 ```
-◆ SYSTEM SHIFT
+◆ OUTCOME
 
-  No panic selling allowed
-  437 actions reshaped out of 1,247 total
+  Market stabilized as agents shifted toward safer positions
 
-  Rule → Behavioral Shift → What Emerged → System Outcome
+  Confidence: Strong | Evidence: Solid | Risk: Low
 
-  ┌─ Behavioral Shift ─────────────────┐
-  │ 80%                                │
-  │ adaptation across 1,247 agents     │
-  │ → BLOCK: hold (312 agents)         │
-  │ → MODIFY: sell_slowly (87 agents)  │
-  └────────────────────────────────────┘
+  ┌─ What Agents Did ────────────────┐
+  │ 80% shifted from aggressive to   │
+  │ conservative strategies           │
+  │ 12% reduced position size after  │
+  │ initial attempts failed           │
+  │ 8% maintained original strategy  │
+  └──────────────────────────────────┘
 
-  ┌─ What Emerged ─────────────────────┐
-  │ Coordinated Holding                │
-  │ Panic Suppression                  │
-  └────────────────────────────────────┘
+  ┌─ Why This Happened ──────────────┐
+  │ Early aggressive attempts failed,│
+  │ forcing agents to rethink.       │
+  │ Uncertainty dropped as agents    │
+  │ stopped experimenting.           │
+  └──────────────────────────────────┘
 
-  ┌─ System Outcome ───────────────────┐
-  │ Volatility   47% → 26%            │
-  │ Stability    58% → 79%            │
-  │ Cascade      Avoided              │
-  └────────────────────────────────────┘
+  ┌─ What Emerged ───────────────────┐
+  │ Coordinated Holding              │
+  │ Panic Suppression                │
+  └──────────────────────────────────┘
 
-  ┌─ What Actually Happened ───────────┐
-  │ No panic selling allowed. 437 of   │
-  │ 1,247 agents reorganized — most    │
-  │ shifted to hold. Volatility        │
-  │ dropped 21%.                       │
-  └────────────────────────────────────┘
+  ┌─ System Outcome ─────────────────┐
+  │ Volatility   47% → 26%          │
+  │ Stability    58% → 79%          │
+  │ Cascade      Avoided             │
+  └──────────────────────────────────┘
 
-  ▶ View raw detail
+  ▶ View audit trail
 ```
 
-We don't show you what every agent did. We show you what the system became.
+Every line is specific. Every line is shareable. No system jargon.
 
 ### World Variants
 
 Save any experiment as a named variant:
 
 ```
-Adjust rules → Inject events → Run → See the shift → Save as variant
+Adjust rules → Inject events → Run → See what changed → Save as variant
 ```
 
 Variants capture the base world, state overrides, narrative events, and results. Store them in git. Share them. Replay them. This turns experiments into assets.
 
-## Governance Runtime — Run It For Your Own System
+## Governance Runtime — Plug Into Your Own System
 
 ```bash
 npx @neuroverseos/nv-sim serve
 ```
 
-This starts a local governance server. Any simulator, agent framework, or application can POST actions and get governance decisions back.
+This starts a local server. Any simulator, agent framework, or application can POST actions and get decisions back.
 
 ```
   Endpoint: http://localhost:3456/api/evaluate
@@ -297,16 +387,16 @@ Additional endpoints:
 
 | Endpoint | What It Does |
 |----------|-------------|
-| `POST /api/evaluate` | Submit an action for governance |
+| `POST /api/evaluate` | Submit an action for evaluation |
 | `GET /api/session` | Current session stats |
-| `GET /api/session/report` | Full governance report |
+| `GET /api/session/report` | Full session report |
 | `POST /api/session/reset` | Reset session state |
 | `POST /api/session/save` | Save session as experiment |
-| `GET /api/events` | SSE stream of governance events |
+| `GET /api/events` | SSE stream of live events |
 
 ### Works With Anything
 
-If your system has actions, you can govern it. One API call.
+If your system has actions, you can govern them. One API call.
 
 ```
 Agent decides → POST /api/evaluate → verdict → agent adapts
@@ -376,72 +466,9 @@ If your system can make an HTTP request, it can be governed.
 
 Most systems generate behavior. This one shapes it.
 
-See [INTEGRATION.md](./INTEGRATION.md) for the full API contract and decision types.
-
-## AI Providers — Bring Your Own Model
-
-AI is optional. AI is governed. AI is pluggable.
-
-NV-SIM works without any AI — the deterministic engine runs on math, not tokens. But when you bring your own model, AI becomes a governed actor inside the system — subject to the same rules as every other agent.
+See [INTEGRATION.md](./INTEGRATION.md) for the full API contract, framework guides, and decision types.
 
-### How AI fits in
-
-AI plays two governed roles:
-
-| Role | What It Does | Constraints |
-|------|-------------|-------------|
-| `ai_translator` | Converts unstructured input into normalized events | Must output valid schema, no invention of events, must include confidence |
-| `ai_analyst` | Generates reports from simulation traces | Must reference trace data, must include blocked actions, no unverifiable claims |
-
-Both roles go through `/api/evaluate` like any other actor. The AI doesn't control the system — the system controls the AI.
-
-### Supported providers
-
-NV-SIM auto-detects the best available provider from your environment:
-
-| Provider | Env Var | What It Connects To |
-|----------|---------|---------------------|
-| Anthropic (Claude) | `ANTHROPIC_API_KEY` | Claude Sonnet, Opus, Haiku |
-| OpenAI | `OPENAI_API_KEY` | GPT-4, GPT-4o, o1 |
-| Groq | `GROQ_API_KEY` | Llama 3 70B |
-| Together | `TOGETHER_API_KEY` | Llama, Mixtral |
-| Mistral | `MISTRAL_API_KEY` | Mistral Large |
-| Deepseek | `DEEPSEEK_API_KEY` | Deepseek Chat |
-| Fireworks | `FIREWORKS_API_KEY` | Llama, custom models |
-| Ollama | `OLLAMA_BASE_URL` | Any local model |
-| Local LLM | `LOCAL_LLM_URL` | LM Studio, vLLM, llama.cpp |
-| (none) | — | Deterministic fallback (no AI, no cost) |
-
-Set the env var and run. No configuration files. No provider lock-in.
-
-Any endpoint that speaks the OpenAI chat completions format (`POST /v1/chat/completions`) works out of the box.
-
-## Quick Start
-
-```bash
-# See it
-npx @neuroverseos/nv-sim visualize
-
-# Compare governed vs ungoverned
-npx @neuroverseos/nv-sim compare
-
-# Run a crisis
-npx @neuroverseos/nv-sim scenario taiwan_crisis
-
-# Same crisis, different worlds — which rules hold?
-npx @neuroverseos/nv-sim scenario bank_run --compare
-
-# Inject shocks
-npx @neuroverseos/nv-sim compare --inject tanker_explosion@3,sanctions@5
-
-# Stress test (500 randomized runs)
-npx @neuroverseos/nv-sim chaos --runs 500
-
-# Run local governance runtime for your own simulator
-npx @neuroverseos/nv-sim serve
-```
-
-## Policy Enforcement — The Product Loop
+## Policy Enforcement — The Experiment Loop
 
 Write rules in plain English. Run the same scenario. See what changes. Adjust and repeat.
 
@@ -472,13 +499,13 @@ Slow down algorithmic trading when contagion spreads
 npx nv-sim enforce trading my-rules.txt
 ```
 
-The engine parses your plain English into governance rules, runs the scenario, and shows what changed.
+The engine parses your plain English into rules, runs the scenario, and shows what changed — with before → after behavioral proof.
 
 ### Step 4: Change a rule. Run again.
 
 Remove "Limit leverage to 5x". Run again. Did stability drop? That rule was load-bearing.
 
-Add "Require transparency for all large trades". Run again. Did effectiveness improve?
+Add "Require transparency for all large trades". Run again. Did agents shift strategy?
 
 The report tracks every change:
 
@@ -494,11 +521,12 @@ DIVERGENCE ANALYSIS
   Effectiveness trend: 11% → 32%
 
 KEY INSIGHT
-  Enforcement gates are the key differentiator. Rules alone: 11%. Rules + gates: 32%.
+  Removing the leverage cap caused agents to take larger positions — but the
+  panic selling block forced them to hold through volatility instead of exiting.
+  Net effect: more risk-taking, but more stability.
 
 TRY THIS EXPERIMENT
-  Remove this rule and see what happens:
-    Remove "Block panic selling during high volatility" from your rules file, then run again.
+  Remove "Block panic selling during high volatility" from your rules file, then run again.
   If stability drops, that rule was load-bearing. If nothing changes, it was noise.
 ```
 
@@ -534,6 +562,69 @@ npx nv-sim enforce trading --output=report.json      # Save as JSON
 
 For full control over gates, state variables, and thesis, use JSON world files. See `examples/worlds/` for templates. Enforce accepts both `.txt` and `.json` — mix and match.
 
+## AI Providers — Bring Your Own Model
+
+AI is optional. AI is governed. AI is pluggable.
+
+NV-SIM works without any AI — the deterministic engine runs on math, not tokens. But when you bring your own model, AI becomes a governed actor inside the system — subject to the same rules as every other agent.
+
+### How AI fits in
+
+AI plays two governed roles:
+
+| Role | What It Does | Constraints |
+|------|-------------|-------------|
+| `ai_translator` | Converts unstructured input into normalized events | Must output valid schema, no invention of events, must include confidence |
+| `ai_analyst` | Generates reports from simulation traces | Must reference trace data, must include blocked actions, no unverifiable claims |
+
+Both roles go through `/api/evaluate` like any other actor. The AI doesn't control the system — the system controls the AI.
+
+### Supported providers
+
+NV-SIM auto-detects the best available provider from your environment:
+
+| Provider | Env Var | What It Connects To |
+|----------|---------|---------------------|
+| Anthropic (Claude) | `ANTHROPIC_API_KEY` | Claude Sonnet, Opus, Haiku |
+| OpenAI | `OPENAI_API_KEY` | GPT-4, GPT-4o, o1 |
+| Groq | `GROQ_API_KEY` | Llama 3 70B |
+| Together | `TOGETHER_API_KEY` | Llama, Mixtral |
+| Mistral | `MISTRAL_API_KEY` | Mistral Large |
+| Deepseek | `DEEPSEEK_API_KEY` | Deepseek Chat |
+| Fireworks | `FIREWORKS_API_KEY` | Llama, custom models |
+| Ollama | `OLLAMA_BASE_URL` | Any local model |
+| Local LLM | `LOCAL_LLM_URL` | LM Studio, vLLM, llama.cpp |
+| (none) | — | Deterministic fallback (no AI, no cost) |
+
+Set the env var and run. No configuration files. No provider lock-in.
+
+Any endpoint that speaks the OpenAI chat completions format (`POST /v1/chat/completions`) works out of the box.
+
+## Quick Start
+
+```bash
+# See it
+npx @neuroverseos/nv-sim visualize
+
+# Compare governed vs ungoverned
+npx @neuroverseos/nv-sim compare
+
+# Run a crisis
+npx @neuroverseos/nv-sim scenario taiwan_crisis
+
+# Same crisis, different worlds — which rules hold?
+npx @neuroverseos/nv-sim scenario bank_run --compare
+
+# Inject shocks
+npx @neuroverseos/nv-sim compare --inject tanker_explosion@3,sanctions@5
+
+# Stress test (500 randomized runs)
+npx @neuroverseos/nv-sim chaos --runs 500
+
+# Run local governance runtime for your own simulator
+npx @neuroverseos/nv-sim serve
+```
+
 ## Commands
 
 | Command | What It Does |
@@ -560,11 +651,11 @@ event → narrative propagation → belief shift → agent action → governance
 
 Five forces shape every simulation:
 
-1. **Agent behavior** — traders, voters, regulators, media
-2. **World rules** — leverage caps, circuit breakers, chokepoints
-3. **Narrative events** — information shocks that propagate through the system
-4. **Perception propagation** — different agents react differently to the same event
-5. **Behavioral analysis** — tracks how agents reorganize under governance, producing the evidence that rules actually changed the system
+1. **Agent behavior** — traders, voters, regulators, media — each with different risk profiles and strategies
+2. **World rules** — leverage caps, circuit breakers, chokepoints — the constraints that shape what agents can do
+3. **Narrative events** — information shocks that propagate through the system at different speeds
+4. **Perception propagation** — different agents react differently to the same event based on their role and exposure
+5. **Behavioral analysis** — tracks how agents reorganize, producing the before → after evidence that proves rules actually changed the system
 
 This lets you ask compound questions:
 
@@ -579,13 +670,13 @@ That combination produces very different outcomes than any single factor alone.
         ↓
     nv-sim engine           ← world rules + narrative injection + swarm simulation
         ↓
-    behavioral analysis     ← shift detection, trajectory tracking, cross-run comparison
+    behavioral analysis     ← before→after shift detection, trajectory tracking, cross-run comparison
         ↓
     audit trail             ← append-only evidence chain (JSONL)
         ↓
     nv-sim CLI              ← scenarios, comparison, chaos testing, governance runtime
         ↓
-    control platform        ← interactive browser UI + System Shift card
+    control platform        ← interactive browser UI + outcome panels
         ↓
     AI providers (optional) ← BYOM: Anthropic, OpenAI, Groq, local LLMs, or none
         ↓