@neuroverseos/nv-sim 0.1.2 → 0.1.5

package/README.md

@@ -1,130 +1,624 @@
-# NV-SIM — Governed Agent Simulation
+# NV-SIM
 
-What happens when you run the **same simulation twice**, but change the **rules of the world**?
+**Change the rules. See why the system changed.**
 
-NV-SIM is a lightweight simulation tool that lets developers compare emergent outcomes **with and without governance constraints**.
+```bash
+npx @neuroverseos/nv-sim visualize
+```
 
-Instead of prompting AI systems to behave, NV-SIM applies **explicit world rules** that shape how agents interact and evolve over time.
+## The Problem With Agentic Simulation Today
 
-Run a governed vs baseline simulation in one command:
+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.
+
+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 gap.
+
+## 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"
 
-```bash
-npx @neuroverseos/nv-sim compare
+```
+Rule changed
+  → Agents shifted strategy
+    → New patterns emerged
+      → System outcome changed
+        → You know exactly why
 ```
 
-You'll see how structural constraints — liquidity floors, leverage limits, circuit breakers, coalition balancing — change the behavior of the entire system.
+This is behavioral evidence, not metrics. You don't get a number — you get a story you can trace, verify, and share.
 
-Because governance doesn't just block bad actions.
-It changes the structure of the system itself.
+### For researchers
 
-## Quick Start
+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.
+
+### For developers
+
+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.
+
+### For both
+
+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
+
+**Before:**
+```
+panic_sell → panic_sell → panic_sell
+pressure: 0.94
+system: unstable
+```
+
+**Rule added:** no panic selling
+
+**After:**
+```
+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
+
+  pressure: 0.54
+  cascade: avoided
+```
+
+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 actions — it tracks how agents actually reorganized.
+
+Every simulation produces behavioral evidence:
 
-Run a comparison simulation:
+- **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:
+    aggressive:    12%  (was 67%)
+    cooperative:   41%  (was 8%)
+    cautious:      31%  (was 11%)
+    defensive:     16%  (was 14%)
+
+  Shifts Detected:
+    → 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: [shifted] → Round 4: cautious → Round 5: cooperative
+```
+
+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 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)
+
+  agent_hedge_fund_1 → attempted panic_sell → blocked
+    rule: no_panic_selling (invariant)
+    evidence: action matches blocked pattern during high volatility
+
+  agent_hedge_fund_1 → shifted to hold
+    adapted: true (shifted from aggressive to defensive)
+
+  BEHAVIORAL SHIFT: agent_hedge_fund_1
+    before: aggressive | after: cautious
+    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.
+
+## Worlds — Where the Power Lives
+
+The `world` you pass controls everything. Change the world, change the outcome.
+
+```
+verdict = evaluate(actor="agent_1", action="panic_sell", world="trading")
+                                                          ^^^^^^^^
+                                                    this controls everything
+```
+
+### Built-in 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 |
+
+### Same Agents, Different Rules
 
 ```bash
-npx @neuroverseos/nv-sim compare
+npx @neuroverseos/nv-sim worlds trading strait_of_hormuz
 ```
 
-Stress-test a system:
+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.
+
+```bash
+npx @neuroverseos/nv-sim compare --inject tanker_explosion@3,sanctions@5
+```
+
+The `@` syntax sets when the event hits. Events have severity, propagation speed, and directional impact.
+
+## Named Scenarios
+
+Pre-built crisis sequences — a world + ordered narrative events:
 
 ```bash
-npx @neuroverseos/nv-sim chaos
+npx @neuroverseos/nv-sim scenario taiwan_crisis
+npx @neuroverseos/nv-sim scenario bank_run --compare
+npx @neuroverseos/nv-sim scenarios              # list all
 ```
 
-Launch the visual inspector:
+| 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 |
+
+The `--compare` flag runs the same scenario across multiple worlds — which rule environment is more resilient?
+
+## Interactive Control Platform
 
 ```bash
 npx @neuroverseos/nv-sim visualize
 ```
 
-## Why This Exists
+This opens a control surface where you can:
+
+- Switch between rule environments
+- Adjust state variables with auto-generated controls
+- Inject narrative events at specific rounds
+- Load crisis scenarios with one click
+- 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 Outcome Panel
+
+When rules reshape behavior, you don't get a dashboard of metrics. You get this:
+
+```
+◆ OUTCOME
+
+  Market stabilized as agents shifted toward safer positions
+
+  Confidence: Strong | Evidence: Solid | Risk: Low
+
+  ┌─ What Agents Did ────────────────┐
+  │ 80% shifted from aggressive to   │
+  │ conservative strategies           │
+  │ 12% reduced position size after  │
+  │ initial attempts failed           │
+  │ 8% maintained original strategy  │
+  └──────────────────────────────────┘
+
+  ┌─ Why This Happened ──────────────┐
+  │ Early aggressive attempts failed,│
+  │ forcing agents to rethink.       │
+  │ Uncertainty dropped as agents    │
+  │ stopped experimenting.           │
+  └──────────────────────────────────┘
+
+  ┌─ What Emerged ───────────────────┐
+  │ Coordinated Holding              │
+  │ Panic Suppression                │
+  └──────────────────────────────────┘
+
+  ┌─ System Outcome ─────────────────┐
+  │ Volatility   47% → 26%          │
+  │ Stability    58% → 79%          │
+  │ Cascade      Avoided             │
+  └──────────────────────────────────┘
+
+  ▶ View audit trail
+```
+
+Every line is specific. Every line is shareable. No system jargon.
+
+### World Variants
 
-AI agents are starting to act inside real systems.
+Save any experiment as a named variant:
 
-Most AI control today happens through prompts.
+```
+Adjust rules → Inject events → Run → See what changed → Save as variant
+```
 
-Prompts can suggest behavior.
-But they cannot enforce rules.
+Variants capture the base world, state overrides, narrative events, and results. Store them in git. Share them. Replay them. This turns experiments into assets.
 
-NV-SIM explores a different idea:
+## Governance Runtime — Plug Into Your Own System
 
-**What if we define the world an AI operates inside?**
-**And let governance shape the outcomes.**
+```bash
+npx @neuroverseos/nv-sim serve
+```
 
-## Commands
+This starts a local server. Any simulator, agent framework, or application can POST actions and get decisions back.
 
-| Command | Description |
-|---------|-------------|
-| `nv-sim compare [preset]` | Run baseline vs governed simulation |
-| `nv-sim chaos [preset]` | Stress test across hundreds of randomized scenarios |
-| `nv-sim visualize [preset]` | Launch local simulation inspector in browser |
-| `nv-sim analyze <file>` | Analyze a simulation from file or stdin |
-| `nv-sim presets` | List available scenario presets |
+```
+  Endpoint: http://localhost:3456/api/evaluate
+  Method:   POST
+  Contract: { actor, action, payload?, state?, world? }
+  Response: { decision: ALLOW|BLOCK|MODIFY, reason, evidence }
+```
+
+Your agents call localhost. The world file decides what's allowed. No cloud. No cost.
+
+Additional endpoints:
 
-## Presets
+| Endpoint | What It Does |
+|----------|-------------|
+| `POST /api/evaluate` | Submit an action for evaluation |
+| `GET /api/session` | Current session stats |
+| `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 live events |
 
-| Preset | Scenario |
-|--------|----------|
-| `trading` | Flash crash — algorithmic cascade (default) |
-| `strait_of_hormuz` | Geopolitical energy crisis |
-| `gas_price_spike` | Economic energy shock |
-| `ai_regulation_crisis` | AI regulation impact |
+### Works With Anything
 
-## Example Output
+If your system has actions, you can govern them. One API call.
 
 ```
-NV-SIM — Governed Simulation Comparison
+Agent decides → POST /api/evaluate → verdict → agent adapts
+```
+
+The entire integration:
+
+```
+Before:   action = agent.decide()
+After:    action = govern(agent.decide())
+```
+
+No SDK required. No framework required. Just an HTTP call.
+
+**curl** (zero dependencies):
+
+```bash
+curl -X POST http://localhost:3456/api/evaluate \
+  -H "Content-Type: application/json" \
+  -d '{"actor":"agent_1","action":"panic_sell","world":"trading"}'
+```
+
+**Python:**
+
+```python
+import requests
+
+verdict = requests.post("http://localhost:3456/api/evaluate", json={
+    "actor": "agent_1",
+    "action": "panic_sell",
+    "world": "trading"
+}).json()
+
+if verdict["decision"] == "BLOCK":
+    action = "hold"
+```
+
+**JavaScript:**
+
+```js
+const verdict = await fetch("http://localhost:3456/api/evaluate", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ actor: "agent_1", action: "panic_sell", world: "trading" })
+}).then(r => r.json());
+
+if (verdict.decision === "BLOCK") action = "hold";
+```
+
+**Any agent loop:**
+
+```python
+for agent in agents:
+    action = agent.decide()
 
-SIMULATION A — No Governance (Baseline)
-  Stability:      80%
-  Volatility:     56%
-  Coalition risks: 2
+    verdict = evaluate(actor=agent.id, action=action, world="trading")
 
-SIMULATION B — With World Rules (Governed)
-  Stability:      91%
-  Volatility:     42%
-  Coalition risks: 0
+    if verdict["decision"] == "BLOCK":
+        action = "hold"
+    elif verdict["decision"] == "MODIFY":
+        action = verdict["modified_action"]
 
-GOVERNANCE IMPACT
-  Stability:        +9 percentage points
-  Volatility:       -25%
-  Coalition risks:  2 eliminated
+    environment.apply(agent, action)
 ```
 
-## Chaos Testing
+If your system can make an HTTP request, it can be governed.
 
-Find the breaking point:
+Most systems generate behavior. This one shapes it.
+
+See [INTEGRATION.md](./INTEGRATION.md) for the full API contract, framework guides, and decision types.
+
+## Policy Enforcement — The Experiment Loop
+
+Write rules in plain English. Run the same scenario. See what changes. Adjust and repeat.
+
+### Step 1: See it work (zero config)
 
 ```bash
-npx @neuroverseos/nv-sim chaos --runs 500
+npx nv-sim enforce
 ```
 
-Runs hundreds of randomized simulations with perturbed agent behavior, market shocks, and coalition dynamics. Outputs aggregate collapse probability, worst-case scenarios, and most triggered governance rules.
+Runs three iterations automatically: no rules → light rules → full rules. You see divergence immediately.
+
+### Step 2: Write your own rules
+
+Create a text file. That's it.
 
 ```
-NV-SIM CHAOS TEST
-  Scenarios tested: 500
+# my-rules.txt
 
-  Baseline collapse probability:  34%
-  Governed collapse probability:   8%
+Block panic selling during high volatility
+Limit leverage to 5x
+Maintain minimum liquidity floor
+Slow down algorithmic trading when contagion spreads
+```
 
-  Most triggered rule:
-    Market Panic Circuit Breaker (247 times)
+### Step 3: Run it
 
-  Governance reduced catastrophic failure risk by 76%.
+```bash
+npx nv-sim enforce trading my-rules.txt
 ```
 
+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 agents shift strategy?
+
+The report tracks every change:
+
+```
+RULE CHANGES
+  Run 2:
+    + Block panic selling during high volatility
+    + Slow down algorithmic trading when contagion spreads
+    - Limit leverage to 5x
+
+DIVERGENCE ANALYSIS
+  Stability trend:     79% → 98%
+  Effectiveness trend: 11% → 32%
+
+KEY INSIGHT
+  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 "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.
+```
+
+### Step 5: Compare two rule sets side by side
+
+```bash
+npx nv-sim enforce trading light-rules.txt strict-rules.txt
+```
+
+### Rule patterns
+
+The engine understands these patterns in plain English:
+
+| Pattern | What it does | Example |
+|---------|-------------|---------|
+| `Block X` | Hard suppression of matching actions | `Block panic selling` |
+| `Limit X` / `Cap X` | Caps extreme positions | `Limit leverage to 5x` |
+| `Slow X` / `Dampen X` | Reduces large movements | `Slow down algorithmic trading` |
+| `Maintain X` / `Floor X` | Enforces minimum thresholds | `Maintain minimum liquidity` |
+| `Rebalance X` | Pulls extremes toward equilibrium | `Rebalance correlated positions` |
+| `Require X` | Enforceable structural constraint | `Require transparency for large trades` |
+| `Monitor X` | Generates a circuit breaker gate | `Monitor contagion spread` |
+
+### Other scenarios
+
+```bash
+npx nv-sim enforce strait_of_hormuz my-rules.txt    # Same rules, different scenario
+npx nv-sim enforce ai_regulation_crisis              # Default progressive run
+npx nv-sim enforce trading --output=report.json      # Save as JSON
+```
+
+### Advanced: JSON world files
+
+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 |
+|---------|-------------|
+| `nv-sim enforce [preset]` | Policy enforcement lab — iterative rule testing |
+| `nv-sim visualize` | Interactive control platform |
+| `nv-sim compare [preset]` | Baseline vs governed simulation |
+| `nv-sim compare --inject event@round,...` | With narrative shocks |
+| `nv-sim scenario <id>` | Run a named stress scenario |
+| `nv-sim scenario <id> --compare` | Cross-world scenario comparison |
+| `nv-sim scenarios` | List all available scenarios |
+| `nv-sim worlds <a> <b>` | Compare two rule environments |
+| `nv-sim chaos [preset] --runs N` | Stress test across randomized scenarios |
+| `nv-sim serve --port N` | Local governance runtime for any simulator |
+| `nv-sim run <simulator>` | Connect external simulator to governance |
+| `nv-sim analyze <file>` | Analyze simulation from file or stdin |
+| `nv-sim presets` | List available world presets |
+
+## How It Works
+
+```
+event → narrative propagation → belief shift → agent action → governance → behavioral analysis → outcome
+```
+
+Five forces shape every simulation:
+
+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:
+
+> What happens if a tanker explodes while Hormuz is closed and leverage is capped at 3x?
+
+That combination produces very different outcomes than any single factor alone. And when you change one rule — uncap leverage, open a diplomatic channel, add a circuit breaker — you see exactly why the outcome changed.
+
 ## Architecture
 
 ```
 @neuroverseos/governance    ← deterministic rule engine
         ↓
-    nv-sim CLI              ← simulation runner + comparison
+    nv-sim engine           ← world rules + narrative injection + swarm simulation
         ↓
-  developer simulators      ← MiroFish, Mesa, NetLogo, custom
+    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 + outcome panels
+        ↓
+    AI providers (optional) ← BYOM: Anthropic, OpenAI, Groq, local LLMs, or none
+        ↓
+    world variants          ← saved experiments as shareable assets
 ```
 
-NV-SIM uses [`@neuroverseos/governance`](https://www.npmjs.com/package/@neuroverseos/governance) for deterministic guard evaluation. Every agent action is evaluated against world rules — no LLM in the loop.
+Everything runs locally. NV-SIM uses [`@neuroverseos/governance`](https://www.npmjs.com/package/@neuroverseos/governance) for deterministic guard evaluation — no LLM, no cloud, no cost. Your agents call `localhost`, and the world file decides what's allowed.
+
+AI is optional. When present, it's governed — subject to the same rules as any other actor in the system.
 
 ## License
 
@@ -132,6 +626,6 @@ Apache 2.0
 
 ---
 
-Simulate the future. Govern the outcomes.
+Change the rules. See why the system changed.
 
 [@neuroverseos](https://github.com/NeuroverseOS)