diff --git a/simulator/.env.example b/simulator/.env.example
new file mode 100644
index 00000000..7a87c038
--- /dev/null
+++ b/simulator/.env.example
@@ -0,0 +1,30 @@
+# ──────────────────────────────────────────────
+# MiroFish BMNR Simulator — Environment Config
+# ──────────────────────────────────────────────
+# Copy this to .env and fill in your values.
+# Only the provider you're using needs a key.
+
+# ── LLM PROVIDER ──
+# Options: anthropic, openai, gemini, openrouter, ollama, custom
+VITE_LLM_PROVIDER=anthropic
+
+# ── API KEYS (only needed for the provider you chose) ──
+VITE_ANTHROPIC_API_KEY=
+VITE_OPENAI_API_KEY=
+VITE_GEMINI_API_KEY=
+VITE_OPENROUTER_API_KEY=
+
+# ── MODEL OVERRIDE (optional — each provider has a sensible default) ──
+VITE_LLM_MODEL=
+
+# ── OLLAMA (local — no key needed) ──
+VITE_OLLAMA_BASE_URL=http://localhost:11434
+
+# ── CUSTOM PROVIDER (OpenAI-compatible endpoint) ──
+VITE_CUSTOM_BASE_URL=
+VITE_CUSTOM_API_KEY=
+
+# ── NOTE ──
+# When running inside claude.ai artifacts, no API key is needed —
+# the Anthropic API is available automatically.
+# API keys are only required when self-hosting via `npm run dev`.
diff --git a/simulator/.gitignore b/simulator/.gitignore
new file mode 100644
index 00000000..94362ebd
--- /dev/null
+++ b/simulator/.gitignore
@@ -0,0 +1,6 @@
+node_modules/
+dist/
+.env
+.env.local
+*.log
+.DS_Store
diff --git a/simulator/CONTRIBUTING.md b/simulator/CONTRIBUTING.md
new file mode 100644
index 00000000..561ea97a
--- /dev/null
+++ b/simulator/CONTRIBUTING.md
@@ -0,0 +1,43 @@
+# Contributing to MiroFish BMNR
+
+Thanks for your interest. Here's how to help.
+
+## High-Impact Contributions
+
+These directly improve simulation accuracy:
+
+### Agent Personas
+Edit `src/data/agents.js`. The `persona` field is a natural-language prompt sent to the LLM. The richer and more specific the persona, the better the agent reasons. Think of it like briefing a method actor — give them a backstory, investment philosophy, emotional triggers, and decision-making framework.
+
+### Stimuli
+Edit `src/data/stimuli.js`. Add market events that affect BMNR. Each stimulus needs an `id`, `name`, `cat` (category), `icon`, `impact` (-1 to 1), and `desc`.
+
+### Prompt Engineering
+Edit `src/engine/prompts.js`. This constructs the prompt sent to the LLM each round. Small changes here can dramatically change output quality. Test with multiple providers — what works for Claude may not work for GPT-4o.
+
+### LLM Providers
+Edit `src/providers/index.js`. Add new providers by implementing the `call(messages, options)` interface. Return `{ text, raw }`.
+
+## Development Setup
+
+```bash
+git clone https://github.com/mikema-rgb/BMNR-Mirofish.git
+cd BMNR-Mirofish
+cp .env.example .env
+npm install
+npm run dev
+```
+
+## Pull Request Guidelines
+
+- Keep PRs focused — one feature or fix per PR
+- Test with at least 2 LLM providers if changing prompts
+- Update README if adding new features
+- Add your agent / stimulus to the appropriate data file, not to App.jsx
+
+## Code Style
+
+- No build tooling beyond Vite
+- Functional React with hooks, no class components
+- Inline styles using the `T` design token object (Wedge system)
+- Keep App.jsx as a working monolith — it needs to run as a Claude artifact
diff --git a/simulator/LICENSE b/simulator/LICENSE
new file mode 100644
index 00000000..006063e9
--- /dev/null
+++ b/simulator/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MiroFish BMNR Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/simulator/README.md b/simulator/README.md
new file mode 100644
index 00000000..63d5984b
--- /dev/null
+++ b/simulator/README.md
@@ -0,0 +1,225 @@
+# MiroFish × BMNR Simulator
+
+**Agent-based stock simulator for BitMine (BMNR) powered by LLM swarm intelligence.**
+
+A fork of [MiroFish](https://github.com/666ghj/MiroFish) adapted for financial market simulation. Instead of predicting outcomes with formulas, 21 AI agents with distinct personas reason collectively about BMNR's future — and predictions emerge from their interactions.
+
+> **Not financial advice.** This is an educational simulation tool. Not affiliated with BitMine Immersion Technologies, Tom Lee, ARK Invest, or any entity mentioned. Agent personas are fictional archetypes.
+
+---
+
+## What It Does
+
+| Feature | Description |
+|---------|-------------|
+| **Live Market Data** | Fetches BMNR price, ETH price, mNAV, holdings from bitminetracker.io on every load |
+| **21 AI Agents** | ARK/Cathie, Tom Lee, short sellers, Reddit bulls, WSB degens, arb bots — each with detailed personas |
+| **LLM Reasoning** | Each quarter, agents reason via LLM about the market state — not programmed formulas |
+| **25 Market Stimuli** | Toggle events (ETH rally, SEC crackdown, MAVAN launch) with adjustable intensity |
+| **Flywheel Math** | Real ATM issuance mechanics: NAV calc → breakeven check → share issuance → ETH/share accretion |
+| **3 Scenarios** | Bear / Base / Bull with overlaid comparison charts |
+| **Multi-LLM** | Pluggable providers: Anthropic, OpenAI, Google Gemini, OpenRouter, Ollama (local), or custom |
+| **Formula Fallback** | Instant results via network-propagation math when LLM is unavailable |
+
+---
+
+## Quick Start
+
+### Option 1: Claude.ai Artifact (zero setup)
+
+Copy the contents of `src/App.jsx` into a Claude.ai artifact. It runs immediately — the Anthropic API is available inside artifacts with no API key.
+
+### Option 2: Self-Host
+
+```bash
+git clone https://github.com/mikema-rgb/BMNR-Mirofish.git
+cd BMNR-Mirofish
+cp .env.example .env # Edit with your API key
+npm install
+npm run dev # Opens at http://localhost:3000
+```
+
+### Option 3: Any LLM
+
+Edit `.env` to use your preferred provider:
+
+```env
+# OpenAI
+VITE_LLM_PROVIDER=openai
+VITE_OPENAI_API_KEY=sk-...
+
+# Google Gemini
+VITE_LLM_PROVIDER=gemini
+VITE_GEMINI_API_KEY=AIza...
+
+# Ollama (local, free, no key)
+VITE_LLM_PROVIDER=ollama
+VITE_OLLAMA_BASE_URL=http://localhost:11434
+
+# OpenRouter (100+ models)
+VITE_LLM_PROVIDER=openrouter
+VITE_OPENROUTER_API_KEY=sk-or-...
+
+# Any OpenAI-compatible endpoint
+VITE_LLM_PROVIDER=custom
+VITE_CUSTOM_BASE_URL=https://your-endpoint.com
+VITE_CUSTOM_API_KEY=your-key
+```
+
+---
+
+## Architecture
+
+```
+BMNR-Mirofish/
+├── src/
+│ ├── App.jsx # Main component (monolith — runs standalone)
+│ ├── main.jsx # React entry point
+│ ├── config/
+│ │ └── index.js # Simulation config, scenario metadata, fallback data
+│ ├── data/
+│ │ ├── agents.js # 21 agent personas (the core of MiroFish)
+│ │ └── stimuli.js # 25 market event definitions
+│ ├── engine/
+│ │ └── prompts.js # LLM prompt builder (fork this for other stocks)
+│ └── providers/
+│ └── index.js # LLM provider abstraction (Anthropic, OpenAI, etc.)
+├── .env.example # Environment config template
+├── package.json
+├── vite.config.js
+└── README.md
+```
+
+### How MiroFish Works (vs. Traditional Models)
+
+| | Traditional Monte Carlo | Formula Agent Model | **MiroFish LLM Agents** |
+|---|---|---|---|
+| How price moves | `price × exp(drift + vol × dW)` | Sentiment formulas drive returns | LLM reasons about what agents would do |
+| Agent behavior | None — just noise terms | Programmed bias + susceptibility | Natural language persona → LLM reasoning |
+| Emergent effects | None | Limited network propagation | Herding, contrarianism, cascade failures |
+| Stimulus response | Hardcoded impact numbers | Type-weighted sensitivity | LLM interprets event for each persona |
+| Surprise factor | None — deterministic given seed | Low — formulas are predictable | High — LLM reasoning can produce unexpected cascades |
+
+### The Simulation Loop
+
+Each quarter:
+
+1. **Agent Selection** — 8 core agents + 3 rotating guests are selected
+2. **Prompt Construction** — Market state, stimuli, prior quarter narrative, and agent personas are assembled into a prompt
+3. **LLM Call** — The prompt is sent to the configured LLM provider
+4. **Response Parsing** — JSON output is extracted with markdown fence stripping and brace-counting fallback
+5. **Market Update** — LLM-derived ETH price change and mNAV change are applied (clamped to ±50% per quarter)
+6. **Flywheel Engine** — If mNAV > breakeven, ATM shares are issued, ETH is purchased, ETH/share updates
+7. **State Propagation** — The quarter narrative feeds into the next round as context
+
+---
+
+## How to Extend
+
+### Add a New Agent
+
+Edit `src/data/agents.js`:
+
+```javascript
+{
+ id: "your_agent",
+ name: "Your Agent Name",
+ type: "Institutional", // or Retail, Quant, Macro, Analyst, etc.
+ icon: "🎯",
+ bias: 0.2, // -1 (bearish) to 1 (bullish) for formula fallback
+ influence: 0.5, // 0-1: how much they sway others
+ susceptibility: 0.3, // 0-1: how much they follow the herd
+ memory: 0.6, // 0-1: how much past rounds carry forward
+ persona: "You are... [detailed natural language persona]. You believe... You react to..."
+}
+```
+
+The persona is the most important field — write it like you're briefing a method actor.
+
+### Add a New Stimulus
+
+Edit `src/data/stimuli.js`:
+
+```javascript
+{
+ id: "your_event",
+ name: "Your Event Name",
+ cat: "ETH", // Category for filtering
+ icon: "⚡",
+ impact: 0.5, // -1 to 1 for formula fallback
+ desc: "Short description"
+}
+```
+
+### Add a New LLM Provider
+
+Edit `src/providers/index.js`:
+
+```javascript
+export const YourProvider = {
+ id: "your_provider",
+ name: "Your Provider",
+ models: ["model-1", "model-2"],
+ defaultModel: "model-1",
+ requiresKey: true,
+
+ async call(messages, { model, maxTokens, apiKey } = {}) {
+ // Make your API call here
+ // Return { text: string, raw: any }
+ const res = await fetch("https://your-api.com/v1/chat", { ... });
+ const data = await res.json();
+ return { text: data.output, raw: data };
+ }
+};
+
+// Register it:
+export const PROVIDERS = {
+ ...existingProviders,
+ your_provider: YourProvider,
+};
+```
+
+### Fork for Another Stock
+
+The simulator is designed to be adapted. To fork for a different stock:
+
+1. Replace agent personas in `src/data/agents.js` with archetypes relevant to your stock
+2. Replace stimuli in `src/data/stimuli.js` with events that affect your stock
+3. Update `src/config/index.js` with fallback market data for your stock
+4. Modify `src/engine/prompts.js` to reference your stock's specific dynamics (the flywheel mechanics are BMNR-specific — replace with whatever drives your stock's value)
+5. Update the live data fetcher in `src/App.jsx` to pull from relevant data sources
+
+---
+
+## Acknowledgments
+
+- **[MiroFish](https://github.com/666ghj/MiroFish)** — the original swarm intelligence engine by Shanda Group. This project adapts their agent-based simulation concept for financial markets.
+- **[OASIS](https://github.com/camel-ai/oasis)** — the underlying social simulation platform that powers MiroFish.
+- **[Wedge](https://wedge.so)** — the BMNR flywheel model and design system.
+- **[bitminetracker.io](https://bitminetracker.io)** — live BMNR market data.
+
+---
+
+## Contributing
+
+PRs welcome. The most impactful contributions:
+
+- **Better agent personas** — if you can write a more realistic persona for any of the 21 agents, that directly improves simulation quality
+- **New stimuli** — market events we haven't thought of
+- **New LLM providers** — expand the provider abstraction
+- **Prompt engineering** — improvements to `src/engine/prompts.js` that produce more realistic agent reasoning
+- **UI improvements** — better charts, mobile responsiveness, dark mode
+- **Other stocks** — fork and adapt for MSTR, COIN, or any other stock with similar dynamics
+
+---
+
+## License
+
+MIT — same as MiroFish.
+
+---
+
+
+ {mode === "llm" ? "Each agent's persona is sent to Claude with the full market context. The LLM reasons in-character about what that agent would think, feel, and do — producing emergent collective predictions rather than programmed outcomes. Click any agent row to see their reasoning." : "Agents update sentiment via network propagation formulas. Faster but less realistic — outcomes are pre-determined by equations, not emergent reasoning."}
+