@neuroverseos/nv-sim 0.1.7 → 0.1.10

package/README.md

@@ -2,68 +2,141 @@
 
 **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
+## The Problem With Agentic Simulation Today
 
-Most simulation tools answer: *"What will happen?"*
+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:
+
+*Why did the agents do that?*
+
+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.
+
+Most multi-agent systems let agents do whatever emerges. NeuroVerse lets *you* decide what's allowed — and actually stops the rest.
+
+## How It Works (For Humans)
+
+You're a scientist. You have AI agents running experiments for you — testing hypotheses, searching literature, publishing findings. But they do dumb things. They publish claims with no evidence. They cite one paper and call it proof. They pile onto whatever the first agent found.
+
+You need to say: **"Here's what counts as good science in my lab."** And you need the system to actually enforce it.
+
+That's what NeuroVerse does.
+
+### Step 1: You describe what matters
+
+You open the app and fill in plain English:
 
-NV-SIM answers: *"What changes when I change the rules?"*
+**What should agents explore?**
+> "Protein mutations that improve binding affinity for SSTR2"
 
-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:
+**What should never be published?**
+> "Results based on a single data source. Claims with confidence below 70%."
 
-- **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)
+**What makes a result valuable?**
+> "Multiple independent lines of evidence converging on the same finding."
+
+**How should agents be rewarded or penalized?**
+> IF an agent publishes without peer validation → reduce its influence for 3 rounds
+> IF two agents independently converge on the same finding → boost that finding's priority
+
+**Anything else you want to try?**
+> "Reward agents that challenge the dominant consensus."
+
+### Step 2: The system translates your words into rules
+
+When you click "Build World," your plain English becomes enforceable logic. Before anything runs, you see exactly what will be enforced:
 
 ```
-Rule changed
-  → Behavior shifted
-    → Pattern emerged
-      → System outcome changed
+BLOCK       Results with confidence below 70%
+BLOCK       Results from a single source
+PRIORITIZE  Multi-source convergence
+PENALIZE    Publishing without validation → reduce influence, 3 rounds
+REWARD      Independent convergence → boost priority, 5 rounds
 ```
 
-That's the loop. Every time.
+You can remove rules, change them, add more. Nothing runs until you say so.
 
-## This Is a Runtime, Not Just a Simulator
+### Step 3: Run the experiment — and see what actually happens
 
-NV-SIM runs in two modes:
+The agents run. Some of them try to publish low-confidence findings. **Those get blocked.** Not flagged. Not warned. Blocked. The UI shows you exactly which rule stopped it and why.
 
-- **Simulate** — explore how systems behave under different rules
-- **Act** — govern real agents, real workflows, and real decisions
+Some agents independently arrive at the same mutation. **Those get boosted.** Their findings move to the top. Not because they gamed the system — because they met the standard you set.
 
-The interface is the same. The difference is where the behavior comes from.
+An agent that keeps publishing without validation? **Its influence drops.** It still participates, but its findings carry less weight. For three rounds.
 
+You can see all of this happening:
+- A green badge means rules are being enforced
+- A yellow badge means you're just previewing (the engine isn't connected)
+- Every blocked action shows the exact rule and condition
+- Every reward and penalty shows which agent, what happened, and for how long
+
+### Step 4: Change one rule. Run again.
+
+Remove the confidence threshold. What breaks? Do agents start publishing garbage? Does it matter?
+
+Add a rule that penalizes groupthink. Do agents start exploring more diverse hypotheses?
+
+**This is the experiment.** Not the simulation — the rules themselves. You're not testing what agents do. You're testing which rules produce the science you actually want.
+
+### What's different about this
+
+Other agent systems give you emergent behavior and hope for the best.
+
+NeuroVerse gives you a control surface:
+
+| You say | The system does |
+|---|---|
+| *"Block single-source claims"* | Blocks them. Every time. With evidence. |
+| *"Penalize publishing without review"* | Reduces the agent's influence. For exactly as long as you specified. |
+| *"Reward independent convergence"* | Boosts the finding's priority. The agents don't even know — it just rises. |
+
+The agents don't need to understand the rules. They just operate within them.
+
+### Running it
+
+```bash
+npm install
+npm run dev:full
 ```
-Simulate → internal swarm engine
-Act      → external systems (agents, APIs, frameworks like OpenClaw)
-```
 
-In both cases:
+Opens in your browser. Everything runs on your machine. No cloud. No accounts. No cost.
+
+> **If the governance engine isn't running, nothing is enforced.** The UI always tells you: green = real, yellow = preview.
+
+## What NV-SIM Gives You That Nothing Else Does
+
+NV-SIM doesn't predict outcomes. It shows you **why agents behaved the way they did** — and what happens when you change the rules.
+
+You change one constraint — block panic selling, cap leverage at 3x, close a shipping lane — and the system shows you:
+
+- **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"
 
 ```
-Action → Governance → Decision → Behavioral Shift → System Outcome
+Rule changed
+  → Agents shifted strategy
+    → New patterns emerged
+      → System outcome changed
+        → You know exactly why
 ```
 
-You're not switching tools. You're switching the source of reality.
+This is behavioral evidence, not metrics. You don't get a number — you get a story you can trace, verify, and share.
+
+### For researchers
+
+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 +151,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 +169,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 for governance accountability.
+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**.
 
-## Worlds — Where the Power Lives
+### Option 1: Start from a template
 
-Integration is one line. The world file controls everything.
+```bash
+npx @neuroverseos/nv-sim visualize    # Pick a template, adjust, run
+```
 
-The `world` you pass to `/api/evaluate` determines how actions are judged. Change the world, change the outcome.
+### Option 2: Write your rules, we build the world
+
+Create a text file with your rules in plain English:
 
 ```
-verdict = evaluate(actor="agent_1", action="panic_sell", world="trading")
-                                                          ^^^^^^^^
-                                                    this 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
 ```
 
-### Built-in Worlds
+Then generate a full governed world from it:
+
+```bash
+npx @neuroverseos/nv-sim world-from-doc my-rules.txt --output my-world.json
+```
+
+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
+```
+
+Load any saved world file directly into the runtime.
+
+## Two Template Worlds
+
+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. 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)
 
-| 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 |
+### `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 +398,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 +474,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 +553,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
+See [INTEGRATION.md](./INTEGRATION.md) for the full API contract, framework guides, and decision types.
 
-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
-```
-
-## 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 +586,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 +608,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 +649,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 +738,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 +757,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
         ↓