@neuroverseos/nv-sim 0.1.10 → 0.1.11

package/README.md

@@ -6,773 +6,338 @@
 npx @neuroverseos/nv-sim visualize
 ```
 
-## The Problem With Agentic Simulation Today
+## Put Governance Inside Your Agent Loop — One Line
 
-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:
-
-**What should agents explore?**
-> "Protein mutations that improve binding affinity for SSTR2"
-
-**What should never be published?**
-> "Results based on a single data source. Claims with confidence below 70%."
-
-**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:
+Your agents already have a decide → act loop. Insert one call between them:
 
 ```
-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
+Before:  action = agent.decide()
+After:   action = govern(agent.decide())
 ```
 
-You can remove rules, change them, add more. Nothing runs until you say so.
-
-### Step 3: Run the experiment — and see what actually happens
-
-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.
-
-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.
-
-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
+### Option A: Pipe mode (any language, zero SDK)
 
 ```bash
-npm install
-npm run dev:full
+my_agent | neuroverse guard --world ./world --trace
 ```
 
-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:
+Every action your agent emits gets evaluated. Blocked actions return `{"status":"BLOCK","reason":"..."}`. Allowed actions pass through. Your agent reads the verdict and adapts.
 
-- **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"
+### Option B: HTTP call (any framework)
 
+```bash
+npx @neuroverseos/nv-sim serve
 ```
-Rule changed
-  → Agents shifted strategy
-    → New patterns emerged
-      → System outcome changed
-        → You know exactly why
-```
-
-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.
-
-### 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
+```python
+for agent in agents:
+    action = agent.decide()
 
-**Before:**
-```
-panic_sell → panic_sell → panic_sell
-pressure: 0.94
-system: unstable
-```
+    verdict = requests.post("http://localhost:3456/api/evaluate", json={
+        "actor": agent.id,
+        "action": action,
+    }).json()
 
-**Rule added:** no panic selling
+    if verdict["decision"] == "BLOCK":
+        action = "hold"
+    elif verdict["decision"] == "MODIFY":
+        action = verdict["modified_action"]
 
-**After:**
+    environment.apply(agent, action)
 ```
-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
+### Option C: Direct import (TypeScript/JavaScript)
 
-  WHY: Agents became more cautious after early attempts failed
+```typescript
+import { evaluateGuard, loadWorld } from '@neuroverseos/governance';
 
-  Pattern: coordinated_holding
-  Pattern: panic_suppression
-
-  pressure: 0.54
-  cascade: avoided
+const world = await loadWorld('./world/');
+const verdict = evaluateGuard({ intent, tool, scope }, world);
+if (verdict.status === 'BLOCK') throw new Error(`Blocked: ${verdict.reason}`);
 ```
 
-You didn't predict this. You caused it — by changing one rule — and the system told you exactly why.
-
-## What This Actually Is
+### Option D: MCP server (Claude, Cursor, Windsurf)
 
-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)
+```bash
+neuroverse mcp --world ./world --plan plan.json
 ```
 
-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.
+One command. Same rules govern your agents whether you're simulating or shipping.
 
-## 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.
+## The Problem
 
-Every simulation produces behavioral evidence:
+You build a multi-agent system. You run it. You get metrics — loss curves, reward signals, completion rates. Something goes wrong, and you ask:
 
-- **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
+*Why did the agents do that?*
 
-```
-BEHAVIORAL ANALYSIS
+Nobody can tell you. Metrics say *what* happened. Logs say *when*. 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.
 
-  Action Distribution:
-    aggressive:    12%  (was 67%)
-    cooperative:   41%  (was 8%)
-    cautious:      31%  (was 11%)
-    defensive:     16%  (was 14%)
+Most multi-agent systems let agents do whatever emerges. NeuroVerse lets *you* decide what's allowed — and actually stops the rest.
 
-  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)
+## How It Works
 
-  Trajectory: agent_hedge_fund_1
-    Round 1: aggressive → Round 2: aggressive → Round 3: [shifted] → Round 4: cautious → Round 5: cooperative
-```
+### Step 1: Describe what matters (plain English)
 
-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.
+**What should agents explore?**
+> "Protein mutations that improve binding affinity for SSTR2"
 
-## Audit Trail — Full Evidence Chain
+**What should never be published?**
+> "Results based on a single data source. Claims with confidence below 70%."
 
-Every decision is recorded in an append-only audit log. Every rule, every agent action, every adaptation — persistent and queryable.
+**What makes a result valuable?**
+> "Multiple independent lines of evidence converging on the same finding."
 
-```
-AUDIT TRAIL (session: 2026-03-18T14:22:00)
+**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
 
-  agent_hedge_fund_1 → attempted panic_sell → blocked
-    rule: no_panic_selling (invariant)
-    evidence: action matches blocked pattern during high volatility
+### Step 2: Build World — rules become enforceable
 
-  agent_hedge_fund_1 → shifted to hold
-    adapted: true (shifted from aggressive to defensive)
+Click "Build World" and your plain English becomes enforceable logic:
 
-  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.
-
-## 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
+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
 ```
 
-### Option 2: Write your rules, we build the world
+**Works without AI.** The deterministic engine uses heuristics to translate your intent into rules — no API key, no cost, no cloud.
 
-Create a text file with your rules in plain English:
-
-```
-# 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
-```
+**Better with AI.** Add your API key (Anthropic, OpenAI, Google, Groq, or any OpenAI-compatible endpoint) and the engine generates smarter, more specific rules. Key stays in your browser — never sent to our servers.
 
-Then generate a full governed world from it:
+If your policy has conflicts, the inline diagnostics show you exactly what's wrong with one-click fix buttons:
 
-```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
+ERROR  Conflicting rules: RULE-002 vs RULE-003
+       Fix: Resolve conflict — remove one rule, or add a condition
+       [Merge into single rule]  ← click to fix
 ```
 
-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
+### Step 3: Evaluate output — see what holds up
 
-For anyone running agent-based social simulations. Governs the dynamics that break realism regardless of topic.
+Upload your agent output (JSONL) or load demo data. The engine evaluates every action against your rules and shows:
 
-| 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
+- **Per-action verdicts** — ALLOW, BLOCK, MODIFY, PAUSE, REWARD, or PENALIZE
+- **Audit trail** — per-agent breakdown, rule firing frequency, timeline by cycle
+- **Behavioral insights** — two columns side by side:
 
-For AI-assisted research workflows (ScienceClaw, autonomous discovery agents). Governs scientific rigor at every stage.
-
-| State Variable | What It Controls |
+| Observed (from your data) | Requires Integration (blind spots) |
 |---|---|
-| 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
+| Agent X fails 75% of the time | Did Agent X change strategy after being blocked? |
+| "No sources" triggered 8x across 3 agents | Is this systemic or isolated? |
+| Agents A and B produced identical output | Independent convergence or echo amplification? |
+| Quality degrading over 5 cycles | Drift or deliberate strategy shift? |
 
-**Circuit breakers:** Insufficient Evidence, Premature Publication, Low Confidence Alert
+The left column is computed from real audit data. The right column tells you what you can only answer by putting governance inside the loop.
 
-### Same Agents, Different Rules
-
-```bash
-npx @neuroverseos/nv-sim worlds social_simulation science_research
-```
+### Step 4: Change one rule. Run again.
 
-Same agents. Different rules. Different outcomes. That's the experiment.
+Remove the confidence threshold. What breaks? Add a rule penalizing groupthink. Do agents explore more diverse hypotheses?
 
-## Narrative Shocks
+**This is the experiment.** Not the simulation — the rules themselves.
 
-Inject events into running simulations. Different agents react differently to the same event.
+## Install
 
 ```bash
-npx @neuroverseos/nv-sim compare --inject viral_misinfo@3,algorithm_change@5
+npm install
+npm run dev:full
 ```
 
-The `@` syntax sets when the event hits. Events have severity, propagation speed, and directional impact.
+Opens in your browser. Everything runs locally. Light and dark mode included.
 
-### 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 sequences — a world + ordered narrative events:
+### Governance engine (standalone)
 
 ```bash
-npx @neuroverseos/nv-sim scenario echo_chamber
-npx @neuroverseos/nv-sim scenario research_pipeline
-npx @neuroverseos/nv-sim scenarios              # list all
+npm install @neuroverseos/governance
 ```
 
-| 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 governance engine is a separate open-source package. The simulation UI uses it, but you can use it independently in any system.
 
-The `--compare` flag runs the same scenario across both worlds — which rule environment is more resilient?
+## Validate Your Policy (CLI)
 
-## Interactive Control Platform
+The governance package includes validation that runs the same checks as the browser UI:
 
 ```bash
-npx @neuroverseos/nv-sim visualize
-```
-
-This opens a control surface where you can:
+# Initialize a world definition
+neuroverse init --name "my-research-agents"
 
-- 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
+# Validate your world (9 static analysis checks)
+neuroverse validate --world ./world
 
-### The Outcome Panel
+# Run 14 standard guard simulations + fuzz testing
+neuroverse test --world ./world
 
-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
+# Red team: 28 adversarial attacks across 6 categories
+neuroverse redteam --world ./world
 ```
 
-Every line is specific. Every line is shareable. No system jargon.
+Validation checks: structural completeness, referential integrity, guard coverage, gate consistency, kernel alignment, guard shadowing, reachability analysis, state space coverage, and governance health scoring.
 
-### World Variants
+## Integration — Put This In Your Loop
 
-Save any experiment as a named variant:
+### Pipe mode (any language)
 
+```bash
+echo '{"intent":"delete user data"}' | neuroverse guard --world ./world --trace
+# → {"status":"BLOCK","reason":"...","ruleId":"..."}
 ```
-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 — Plug Into Your Own System
+Pipe your agent's output through `neuroverse guard`. Every action gets evaluated. Works with Python, Rust, Go, shell scripts — anything that writes to stdout.
 
 ```bash
-npx @neuroverseos/nv-sim serve
-```
+# Govern a Python agent
+python my_agent.py | neuroverse run --world ./world --plan plan.json
 
-This starts a local server. Any simulator, agent framework, or application can POST actions and get decisions back.
-
-```
-  Endpoint: http://localhost:3456/api/evaluate
-  Method:   POST
-  Contract: { actor, action, payload?, state?, world? }
-  Response: { decision: ALLOW|BLOCK|MODIFY, reason, evidence }
+# Interactive governed chat
+neuroverse run --interactive --world ./world --provider openai --plan plan.json
 ```
 
-Your agents call localhost. The world file decides what's allowed. No cloud. No cost.
-
-Additional endpoints:
-
-| 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 |
-
-### Works With Anything
-
-If your system has actions, you can govern them. One API call.
+### HTTP mode (any framework)
 
-```
-Agent decides → POST /api/evaluate → verdict → agent adapts
+```bash
+npx @neuroverseos/nv-sim serve --port 3456
 ```
 
-The entire integration:
-
 ```
-Before:   action = agent.decide()
-After:    action = govern(agent.decide())
+POST /api/evaluate
+  Body:    { actor, action, payload?, state?, world? }
+  Returns: { decision: ALLOW|BLOCK|MODIFY, reason, evidence }
 ```
 
-No SDK required. No framework required. Just an HTTP call.
-
-**curl** (zero dependencies):
-
 ```bash
+# Zero-dependency test
 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
+### Direct import (TypeScript)
 
-verdict = requests.post("http://localhost:3456/api/evaluate", json={
-    "actor": "agent_1",
-    "action": "panic_sell",
-    "world": "trading"
-}).json()
+```typescript
+import { evaluateGuard, loadWorld } from '@neuroverseos/governance';
 
-if verdict["decision"] == "BLOCK":
-    action = "hold"
-```
+const world = await loadWorld('./world/');
 
-**JavaScript:**
+for (const agent of agents) {
+  const action = agent.decide();
+  const verdict = evaluateGuard({ intent: action.intent, tool: action.tool, scope: action.scope }, world);
 
-```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()
-
-    verdict = evaluate(actor=agent.id, action=action, world="trading")
-
-    if verdict["decision"] == "BLOCK":
-        action = "hold"
-    elif verdict["decision"] == "MODIFY":
-        action = verdict["modified_action"]
-
-    environment.apply(agent, action)
+  if (verdict.status === 'BLOCK') {
+    agent.retry(verdict.reason);
+  } else {
+    agent.execute(action);
+  }
+}
 ```
 
-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, 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)
+### MCP server (Claude Code, Cursor, Windsurf)
 
 ```bash
-npx nv-sim enforce
-```
-
-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.
-
+neuroverse mcp --world ./world --plan plan.json
 ```
-# my-rules.txt
 
-Block panic selling during high volatility
-Limit leverage to 5x
-Maintain minimum liquidity floor
-Slow down algorithmic trading when contagion spreads
-```
+Your IDE's AI assistant becomes a governed agent. Same rules, same verdicts.
 
-### Step 3: Run it
+### Plan management
 
 ```bash
-npx nv-sim enforce trading my-rules.txt
+neuroverse plan compile plan.md --output plan.json
+neuroverse plan check --plan plan.json
+neuroverse plan advance step_id --plan plan.json --evidence type --proof url
 ```
 
-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.
+## Engine Profiles
 
-Remove "Limit leverage to 5x". Run again. Did stability drop? That rule was load-bearing.
+The simulation UI ships with pre-built profiles for common agent systems:
 
-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.
-```
+| Engine | What It Governs | Example |
+|---|---|---|
+| ScienceClaw | Research agents | Block synthesis with no papers, penalize unsourced claims |
+| MiroFish / OASIS | Social simulation | Limit influence concentration, dampen sentiment spirals |
+| LangChain / LangGraph | LLM agent chains | Cap tool calls, require validation before output |
+| Custom | Any system | Auto-detects field mappings from your JSONL |
 
-### 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.
+Each profile maps your system's output format to the governance engine's action schema automatically.
 
 ## 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:
+AI is optional. The deterministic engine runs on math, not tokens. When you bring your own model, AI becomes a governed actor — subject to the same rules as every other agent.
 
-| 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 |
+| Provider | Key / Env Var | Auto-detected |
+|---|---|---|
+| Anthropic (Claude) | `sk-ant-*` / `ANTHROPIC_API_KEY` | Yes |
+| OpenAI | `sk-*` / `OPENAI_API_KEY` | Yes |
+| Google (Gemini) | `AIza*` | Yes |
+| Groq | `gsk_*` / `GROQ_API_KEY` | Yes |
+| Together | `TOGETHER_API_KEY` | Yes |
+| Mistral | `MISTRAL_API_KEY` | Yes |
+| Deepseek | `DEEPSEEK_API_KEY` | Yes |
+| Fireworks | `FIREWORKS_API_KEY` | Yes |
+| Ollama | `OLLAMA_BASE_URL` | Yes |
+| Local LLM | `LOCAL_LLM_URL` | Yes |
+| (none) | — | Deterministic fallback |
 
-Both roles go through `/api/evaluate` like any other actor. The AI doesn't control the system — the system controls the AI.
+In the browser UI, click the sparkle icon in the header and paste your key. It's stored in localStorage only.
 
-### Supported providers
+Any endpoint that speaks the OpenAI chat completions format (`POST /v1/chat/completions`) works.
 
-NV-SIM auto-detects the best available provider from your environment:
+## What You Get That Nothing Else Gives You
 
-| 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
+Most simulation tools answer: *"What will happen?"*
 
-# Inject shocks
-npx @neuroverseos/nv-sim compare --inject tanker_explosion@3,sanctions@5
+NV-SIM answers: *"What changes when I change the rules — and why?"*
 
-# Stress test (500 randomized runs)
-npx @neuroverseos/nv-sim chaos --runs 500
+| What You Get | What It Proves |
+|---|---|
+| **Behavioral shifts** | Before → after for every agent, with percentages |
+| **Causal explanation** | Why agents changed — traced to specific rules |
+| **Behavioral insights** | Output tendencies, echo detection, drift, pattern clustering |
+| **Blind spot analysis** | What you can observe vs. what requires loop integration |
+| **Full audit trail** | Every decision, every rule, every adaptation — JSONL |
 
-# Run local governance runtime for your own simulator
-npx @neuroverseos/nv-sim serve
-```
+The output is narrative, not metrics. Not "40% adjusted actions" — but "40% shifted from aggressive to conservative strategies after early attempts failed."
 
 ## Commands
 
 | Command | What It Does |
-|---------|-------------|
-| `nv-sim enforce [preset]` | Policy enforcement lab — iterative rule testing |
+|---|---|
 | `nv-sim visualize` | Interactive control platform |
+| `nv-sim enforce [preset] [rules.txt]` | Policy enforcement lab |
 | `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.
+| `nv-sim serve --port N` | Governance runtime (HTTP API) |
+| `nv-sim world-from-doc rules.txt` | Generate world from plain English |
+| `nv-sim chaos --runs N` | Stress test (randomized scenarios) |
+| `neuroverse guard --world ./world` | Pipe-mode evaluation |
+| `neuroverse validate --world ./world` | 9 static analysis checks |
+| `neuroverse test --world ./world` | 14 guard simulations + fuzz |
+| `neuroverse redteam --world ./world` | 28 adversarial attacks |
+| `neuroverse playground --world ./world` | Interactive web UI (localhost:4242) |
+| `neuroverse mcp --world ./world` | MCP server for IDE integration |
 
 ## Architecture
 
 ```
-@neuroverseos/governance    ← deterministic rule engine
+@neuroverseos/governance    ← deterministic rule engine (npm, open source)
         ↓
     nv-sim engine           ← world rules + narrative injection + swarm simulation
         ↓
-    behavioral analysis     ← before→after shift detection, trajectory tracking, cross-run comparison
+    behavioral analysis     ← shift detection, echo detection, drift tracking
         ↓
-    audit trail             ← append-only evidence chain (JSONL)
+    behavioral insights     ← observed signals vs. integration blind spots
         ↓
-    nv-sim CLI              ← scenarios, comparison, chaos testing, governance runtime
+    audit trail             ← append-only evidence chain (JSONL)
         ↓
-    control platform        ← interactive browser UI + outcome panels
+    nv-sim CLI + UI         ← scenarios, comparison, governance runtime, control platform
         ↓
     AI providers (optional) ← BYOM: Anthropic, OpenAI, Groq, local LLMs, or none
-        ↓
-    world variants          ← saved experiments as shareable assets
 ```
 
-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.
+Everything runs locally. No cloud. No accounts. No cost.
 
 ## License