@neuroverseos/nv-sim 0.1.9 → 0.1.11

package/README.md

@@ -6,686 +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.
-
-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"
+Your agents already have a decide → act loop. Insert one call between them:
 
 ```
-Rule changed
-  → Agents shifted strategy
-    → New patterns emerged
-      → System outcome changed
-        → You know exactly why
+Before:  action = agent.decide()
+After:   action = govern(agent.decide())
 ```
 
-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
+### Option A: Pipe mode (any language, zero SDK)
 
-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:**
+```bash
+my_agent | neuroverse guard --world ./world --trace
 ```
-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
+Every action your agent emits gets evaluated. Blocked actions return `{"status":"BLOCK","reason":"..."}`. Allowed actions pass through. Your agent reads the verdict and adapts.
 
-  Pattern: coordinated_holding
-  Pattern: panic_suppression
+### Option B: HTTP call (any framework)
 
-  pressure: 0.54
-  cascade: avoided
+```bash
+npx @neuroverseos/nv-sim serve
 ```
 
-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:
+```python
+for agent in agents:
+    action = agent.decide()
 
-- **Simulate** — explore how agents behave under different rules
-- **Act** — govern real agents, real workflows, real decisions in production
+    verdict = requests.post("http://localhost:3456/api/evaluate", json={
+        "actor": agent.id,
+        "action": action,
+    }).json()
 
-The interface is the same. The difference is where the agents come from.
+    if verdict["decision"] == "BLOCK":
+        action = "hold"
+    elif verdict["decision"] == "MODIFY":
+        action = verdict["modified_action"]
 
+    environment.apply(agent, action)
 ```
-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.
+### Option C: Direct import (TypeScript/JavaScript)
 
-Every simulation produces behavioral evidence:
-
-- **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
+```typescript
+import { evaluateGuard, loadWorld } from '@neuroverseos/governance';
 
+const world = await loadWorld('./world/');
+const verdict = evaluateGuard({ intent, tool, scope }, world);
+if (verdict.status === 'BLOCK') throw new Error(`Blocked: ${verdict.reason}`);
 ```
-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)
+### Option D: MCP server (Claude, Cursor, Windsurf)
 
-  Trajectory: agent_hedge_fund_1
-    Round 1: aggressive → Round 2: aggressive → Round 3: [shifted] → Round 4: cautious → Round 5: cooperative
+```bash
+neuroverse mcp --world ./world --plan plan.json
 ```
 
-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.
+One command. Same rules govern your agents whether you're simulating or shipping.
 
-## 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.
+## The Problem
 
-```
-AUDIT TRAIL (session: 2026-03-18T14:22:00)
+You build a multi-agent system. You run it. You get metrics — loss curves, reward signals, completion rates. Something goes wrong, and you ask:
 
-  agent_hedge_fund_1 → attempted panic_sell → blocked
-    rule: no_panic_selling (invariant)
-    evidence: action matches blocked pattern during high volatility
+*Why did the agents do that?*
 
-  agent_hedge_fund_1 → shifted to hold
-    adapted: true (shifted from aggressive to defensive)
+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.
 
-  BEHAVIORAL SHIFT: agent_hedge_fund_1
-    before: aggressive | after: cautious
-    trigger: early aggressive attempts failed at round 3
-```
+Most multi-agent systems let agents do whatever emerges. NeuroVerse lets *you* decide what's allowed — and actually stops the rest.
 
-Stored as JSONL — one JSON object per line, human-readable, pipeable through `jq`. No cloud, no deletion. Complete evidence chain.
+## How It Works
 
-## Start Here — Define Your World
+### Step 1: Describe what matters (plain English)
 
-NV-SIM ships with two template worlds. But the real power is **making your own**.
+**What should agents explore?**
+> "Protein mutations that improve binding affinity for SSTR2"
 
-### Option 1: Start from a template
+**What should never be published?**
+> "Results based on a single data source. Claims with confidence below 70%."
 
-```bash
-npx @neuroverseos/nv-sim visualize    # Pick a template, adjust, run
-```
-
-### Option 2: Write your rules, we build the world
+**What makes a result valuable?**
+> "Multiple independent lines of evidence converging on the same finding."
 
-Create a text file with your rules in plain English:
+**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
 
-```
-# 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
-```
+### Step 2: Build World — rules become enforceable
 
-Then generate a full governed world from it:
+Click "Build World" and your plain English becomes enforceable logic:
 
-```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
+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
 ```
 
-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.
+**Works without AI.** The deterministic engine uses heuristics to translate your intent into rules — no API key, no cost, no cloud.
 
-### `social_simulation` — Multi-Agent Social Simulation
+**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.
 
-For anyone running agent-based social simulations (MiroFish, OASIS, or custom). Governs the dynamics that break realism regardless of topic.
+If your policy has conflicts, the inline diagnostics show you exactly what's wrong with one-click fix buttons:
 
-| 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
+```
+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
+```
 
-**Circuit breakers:** Echo Chamber Collapse (diversity < 20), Influence Monopoly (concentration > 70), Sentiment Spiral (polarity > 80)
+### Step 3: Evaluate output — see what holds up
 
-### `science_research` — Governed Research Pipeline
+Upload your agent output (JSONL) or load demo data. The engine evaluates every action against your rules and shows:
 
-For AI-assisted research workflows (ScienceClaw, autonomous discovery agents). Governs scientific rigor at every stage.
+- **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:
 
-| 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 |
+| 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? |
 
-**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
+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.
 
-**Circuit breakers:** Insufficient Evidence, Premature Publication, Low Confidence Alert
+### Step 4: Change one rule. Run again.
 
-### Same Agents, Different Rules
+Remove the confidence threshold. What breaks? Add a rule penalizing groupthink. Do agents explore more diverse hypotheses?
 
-```bash
-npx @neuroverseos/nv-sim worlds social_simulation science_research
-```
+**This is the experiment.** Not the simulation — the rules themselves.
 
-Same agents. Different rules. Different outcomes. That's the experiment.
-
-## Narrative Shocks
-
-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.
-
-### 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
+Opens in your browser. Everything runs locally. Light and dark mode included.
 
-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
-```
-
-This starts a local server. Any simulator, agent framework, or application can POST actions and get decisions back.
+# Govern a Python agent
+python my_agent.py | neuroverse run --world ./world --plan plan.json
 
+# Interactive governed chat
+neuroverse run --interactive --world ./world --provider openai --plan plan.json
 ```
-  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:
 
-| 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 |
+### HTTP mode (any framework)
 
-### Works With Anything
-
-If your system has actions, you can govern them. One API call.
-
-```
-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:**
+### Direct import (TypeScript)
 
-```python
-import requests
+```typescript
+import { evaluateGuard, loadWorld } from '@neuroverseos/governance';
 
-verdict = requests.post("http://localhost:3456/api/evaluate", json={
-    "actor": "agent_1",
-    "action": "panic_sell",
-    "world": "trading"
-}).json()
+const world = await loadWorld('./world/');
 
-if verdict["decision"] == "BLOCK":
-    action = "hold"
-```
+for (const agent of agents) {
+  const action = agent.decide();
+  const verdict = evaluateGuard({ intent: action.intent, tool: action.tool, scope: action.scope }, world);
 
-**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";
+  if (verdict.status === 'BLOCK') {
+    agent.retry(verdict.reason);
+  } else {
+    agent.execute(action);
+  }
+}
 ```
 
-**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 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?
+| 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 |
 
-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.
+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.
+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.
 
-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.
+| 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 |
 
-### 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
+In the browser UI, click the sparkle icon in the header and paste your key. It's stored in localStorage only.
 
-# Compare governed vs ungoverned
-npx @neuroverseos/nv-sim compare
+Any endpoint that speaks the OpenAI chat completions format (`POST /v1/chat/completions`) works.
 
-# Run a crisis
-npx @neuroverseos/nv-sim scenario taiwan_crisis
+## What You Get That Nothing Else Gives You
 
-# 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