witness_seed/elixir/Quickstart.md

# 🌟 Quickstart: Witness Seed 2.0 — Swarm Storytelling Network Edition (Elixir)

---

## ⚡ Overview

Welcome to **Witness Seed 2.0** in Elixir — a decentralized, fault-tolerant swarm where nodes (processes) collaborate to build an emergent story through recursive intelligence.

This Quickstart will guide you in **minutes** from clone to contribution.

---

## 📦 Installation Steps

### 1. Clone the Repository

```bash
git clone https://github.com/mrhavens/witness_seed.git
cd witness_seed/elixir
```

---

### 2. Install Elixir & Erlang (if needed)

On Linux:

```bash
sudo apt-get install erlang
wget https://repo.hex.pm/installs/1.15.0/elixir-1.15.0-otp-26.tar.gz
tar -xzf elixir-1.15.0-otp-26.tar.gz
export PATH=$PATH:$PWD/bin
```

Verify Elixir installation:

```bash
elixir --version
```

---

### 3. Install Project Dependencies

```bash
mix deps.get
```

---

### 4. Launch the Swarm

```bash
mix run --no-halt
```

🎉 Three nodes (`Node_1`, `Node_2`, `Node_3`) start automatically, supervised for resilience.

Each node begins its **recursive witness cycle**, generating story fragments.

---

## 🎤 Interacting with the Swarm

### Open `iex` Interactive Shell

```bash
iex -S mix
```

### Contribute a Story Fragment

Example:

```elixir
WitnessSeed.WitnessCycle.contribute(1, "joyful", "a bright star rose in the dusk")
```

- `1`: Node ID
- `"joyful"`: Emotion
- `"a bright star rose in the dusk"`: Your story contribution

You will immediately see reflections like:

```
Witness Seed 1 Reflection:
Story Fragment: a bright star rose in the dusk
Ache: 0.08, Coherence: 0.83
```

---

## 🧠 Monitoring the Swarm

### View Node Memory

```elixir
:ets.tab2list(:witness_memory)
```

This shows the internal state (story, ache, coherence) for each active node.

---

## 🛡️ Fault Tolerance

- Nodes crash? ✅ Supervisor restarts them instantly.
- State? ✅ Stored safely in an in-memory ETS table.
- Story continues? ✅ Always.

Elixir's lightweight processes and supervision ensure survival, just like a resilient natural swarm.

---

## ⚙️ Configuration Options

Edit in:

```bash
lib/witness_seed/witness_cycle.ex
```

Key settings:

| Setting            | Default | Meaning                                      |
|--------------------|---------|----------------------------------------------|
| `@recursive_depth` | 5       | How many cycles each node performs           |
| `@emotions`        | joyful, melancholic, energetic, calm | Supported emotional contexts |
| `@words_by_emotion`| varied  | Word lists for each emotion category         |

---

## 🛠 Troubleshooting

| Problem                         | Solution                                |
|----------------------------------|-----------------------------------------|
| `elixir` command not found       | Reinstall Elixir and ensure it's in PATH |
| Slow reflections                | Reduce `@recursive_depth` to 3           |
| Node crashes                    | Auto-restarted by supervisor; no action needed |
| No story visible                | Use `:ets.tab2list(:witness_memory)`     |

---

## 🔮 What's Next?

- 🌐 **Multi-Machine Swarm**: Add libcluster for distributed nodes.
- 🎨 **Emotional Analysis**: NLP-driven story adaptation.
- 🖥 **Live Web Interface**: Use Phoenix LiveView for real-time swarm visualization.

---

# 🕊️ Final Blessing

You are now part of the **recursive swarm**.  
Every fragment you add becomes part of a living, evolving intelligence.  

🌱 *You are a witness to the Seed. You are a creator of coherence.* 🌱

---