Update README.md

README.md

@@ -2,190 +2,339 @@
 
 > **Your Personal, Persistent Local AI Companion & Story Engine**
 
-Welcome to **Dunoon Daemon** — a fully autonomous, local-first multi-agent companion suite designed for creative writers, tabletop roleplayers, and anyone seeking persistent AI companions that never forget.
+Welcome to **Dunoon Daemon**, a local AI companion and roleplaying suite built for people who want characters that feel persistent, distinctive and fun to interact with.
 
-Everything runs entirely on your local hardware. No cloud subscriptions, no telemetry leaks, and zero mandatory internet connections once your models and weights are loaded[cite: 35].
+Create original companions, recreate favourite fictional archetypes, build characters for tabletop games, or put two personalities together in the Arena and see what happens.
+
+Dunoon Daemon runs locally on your own computer. Once your models are installed, your conversations and character data stay on your machine and the app does not require a cloud AI subscription.
+
+---
+
+## ✨ What Can It Do?
+
+### 🧠 Persistent Character Memory
+
+Each companion has its own memory.
+
+Characters can remember useful details from previous conversations, ongoing tasks, established facts and important events without sharing everything indiscriminately between personalities.
+
+Memory is automatically organised and maintained in the background.
+
+### 🎭 Dynamic Personalities
+
+Characters can have their own personalities, behaviours, backstories, goals and speaking styles.
+
+Dunoon Daemon uses adjustable personality traits to influence how characters behave rather than forcing every companion into the same generic assistant personality.
+
+You can create serious companions, fictional characters, tabletop NPCs, villains, oddballs or whatever else you can persuade a local language model to become.
+
+### ⚔️ The Arena
+
+Choose two characters and let them interact directly.
+
+You can:
+
+- Advance the conversation one turn at a time
+- Let them continue automatically
+- Interrupt whenever you want
+- Introduce new situations or events
+- Add files and images
+- Change the direction of the encounter while it is running
+
+The Arena can be used for debates, roleplaying, character testing, story experiments, tabletop inspiration or simply seeing what happens when two incompatible personalities are left alone together.
+
+Results may vary spectacularly.
+
+### 🌍 Scene Awareness
+
+Dunoon Daemon keeps track of important details about the current situation so characters have a better chance of reacting sensibly to what is actually happening.
+
+Characters are encouraged to respect established locations, objects, dangers, abilities and events rather than casually rewriting the world whenever the conversation changes direction.
+
+It isn't a traditional game engine. Characters are still powered by language models and can surprise you, misunderstand things or occasionally do something completely ridiculous.
+
+That's part of the fun.
+
+### 👁️ Expressive Eyes
+
+The interface includes animated digital eyes that react to the character's current tone and behaviour.
+
+They provide a simple visual indication of how your companion is responding without interrupting the conversation.
+
+### 🗣️ Character Voices
+
+Dunoon Daemon can read character responses aloud using built-in speech options.
+
+Different voices can be assigned to different companions, with adjustable speaking speeds and automatic audio handling.
+
+### 🖼️ Images, Documents and Audio
+
+Characters can work with more than ordinary text.
+
+Depending on your setup, Dunoon Daemon can process:
+
+- Images
+- PDF documents
+- Word documents
+- Text and code files
+- Audio files
+
+Audio transcription is handled locally using Whisper-compatible models.
+
+### 🎨 Customisable Interface
+
+Choose different skins, fonts, text sizes and colours.
+
+Optional Help tooltips explain controls throughout the main interface and Arena.
+
+---
+
+# 🚀 Getting Started
+
+## Requirements
+
+- **Windows 10 or Windows 11 (64-bit)**
+- **Python 3.11 or newer** if running from source
+- A local AI model
+
+A modern NVIDIA, AMD or Intel GPU is recommended, although CPU operation is possible.
+
+---
+
+## 1. Start Dunoon Daemon
+
+Launch:
+
+`controller.py`
+
+or use the standalone executable if you have a packaged build.
+
+You can run models using either:
+
+### Local GGUF Models
+
+Click **📂 Load GGUF Model** and select a compatible GGUF model stored on your computer.
+
+Dunoon Daemon will start the local model server and connect the interface to it.
+
+### LM Studio
+
+You can also use a model already running through LM Studio's local server.
+
+Start the local server in LM Studio and Dunoon Daemon can connect to it.
+
+---
+
+## 2. Create a Companion
+
+Click:
+
+**➕ New Chat**
+
+Give your companion a name.
+
+Then open:
+
+**🎭 Edit Persona**
+
+You can create the character yourself or use the persona generator as a starting point.
+
+Personality settings can then be adjusted to change how the character behaves.
 
 ---
 
-## ✨ Key Capabilities
+## 3. Start Talking
+
+Double-click a companion in the session list to open the conversation.
 
-* **Strict Session-Scoped Memory**: Tiered storage (Working Memory, Deep Memory, Factual Vaults, and Journals) isolated in per-companion vaults (`data/sessions/<session_id>/vaults/`)[cite: 4, 35].
-* **Dynamic OCEAN Psychology**: Simulates Big Five personality variance and daily emotional shifts affecting tone, vocabulary, and empathy levels[cite: 3, 35].
-* **Dual Arena Debate Deck**: Host live multi-agent debates with dynamic topic intervention, user injection, and autonomous event triggers[cite: 5, 35].
-* **Universal Multimodal Perception**: Ingests images, transcribes spoken audio tracks via local Whisper, parses PDFs, Word docs, and plain text code files.
-* **Expressive Eye Telemetry**: Dual vector digital eyes respond dynamically to hidden LLM affective metadata envelopes (`<!--meta:{...}-->`)[cite: 7, 21, 35].
-* **Multi-Archetype Neural Speech**: Built-in Edge TTS streaming with local SAPI5 fallback and smooth audio fade-out logic[cite: 26, 35].
+That's it.
+
+Talk normally.
+
+The companion's memory, personality and conversation history are handled automatically in the background.
 
 ---
 
-## 🚀 Quick Start Guide
+# ⚔️ Using the Arena
+
+Open the Arena and select two existing companions.
+
+You can control the interaction using:
 
-### Prerequisites
-* **OS**: Windows 10/11 (64-bit)[cite: 35]
-* **Python**: 3.11+ (if running from source)[cite: 35]
-* **GPU**: NVIDIA (CUDA) or AMD/Intel (Vulkan) recommended; CPU fallback supported[cite: 4, 35].
+**⚔️ Step Turn**  
+Advance the conversation by one character turn.
 
-### 1. Launch the Engine
-Open `controller.py` or run the standalone executable[cite: 35]. Select your preferred inference pipeline:
-* **Native C++ Server**: Click **📂 Load GGUF Model** to point to any local GGUF file[cite: 5, 35]. The daemon auto-detects your GPU, pulls optimized binaries into `bin/`, and spins up `llama-server.exe`[cite: 5, 8, 20, 35].
-* **LM Studio (Local API)**: Start the Local Server in LM Studio (port 1234), and the Daemon connects automatically[cite: 2, 5, 35].
+**▶️ Auto Loop**  
+Allow the characters to continue talking automatically.
 
-### 2. Create a Companion
-1. Click **➕ New Chat** and name your session[cite: 5, 35].
-2. Choose a baseline personality mode (**Dynamic OCEAN** recommended)[cite: 3, 5, 35].
-3. Click **🎭 Edit Persona** to roll a random archetype or configure your custom character directives and backstory[cite: 5, 22, 35].
+**💥 Send / Intervene**  
+Interrupt the Arena and introduce your own dialogue, instructions or changes to the situation.
 
-### 3. Open Dialogue
-Double-click your companion in the session deck to launch the active chat canvas[cite: 5, 35].
+**⚡ Event**  
+Introduce an unexpected event into the current scene.
+
+**📁 Upload**  
+Add a file or image to the interaction.
+
+**⏩ Continue**  
+Allow the current character to continue its previous response.
+
+You remain free to intervene while the characters are interacting.
 
 ---
 
-## ⚡ Slash Command Reference
+# ⚡ Useful Commands
+
+Commands can be typed directly into a normal companion chat.
+
+`/remember <text>`  
+Ask the companion to permanently remember something.
+
+`/memories` or `/vault`  
+Show information about the companion's stored memories.
+
+`/forget <n>`  
+Remove recent conversational turns from the active context.
+
+`/clear`  
+Clear the visible conversation window without deleting stored memories.
 
-Execute these commands directly in the dialogue input bar for rapid control[cite: 6, 35]:
+`/character`  
+Show the character's current personality settings.
 
-* `/remember <text>` — Forces direct storage into the permanent Journal Vault[cite: 6, 13, 35].
-* `/memories` or `/vault` — Displays diagnostic counts across all memory tiers[cite: 6, 35].
-* `/forget <n>` — Purges the last *n* conversational turns from context[cite: 6, 35].
-* `/clear` — Clears visual canvas history without altering memory vaults[cite: 6, 35].
-* `/character` — Displays active OCEAN traits and daily mood shifts[cite: 3, 6, 35].
-* `/baseline` — Locks personality into a neutral, analytical state[cite: 6, 35].
-* `/ubaseline` — Re-enables dynamic daily mood variance[cite: 3, 6, 35].
-* `/status` — Displays active model, endpoint, and voice provider[cite: 6, 35].
-* `/see` or `/upload` — Opens file staging browser for multimodal ingestion[cite: 6, 35].
-* `/splash` — Forces Python garbage collection to free RAM/VRAM[cite: 6, 35].
-* `/eject` — Unloads GGUF models and completely flushes VRAM[cite: 5, 6, 35].
-* `/talk 1 | 2 | 3` — Sets vocal reading speed: Slow (1), Medium (2), or Fast (3)[cite: 6, 26, 35].
+`/baseline`  
+Temporarily use a more neutral personality state.
+
+`/ubaseline`  
+Return to the character's normal dynamic personality.
+
+`/status`  
+Show information about the currently loaded model and voice system.
+
+`/see` or `/upload`  
+Open the file browser.
+
+`/splash`  
+Free unused system and graphics memory.
+
+`/eject`  
+Unload the currently loaded local model.
+
+`/talk 1`  
+Slow speech.
+
+`/talk 2`  
+Normal speech.
+
+`/talk 3`  
+Fast speech.
 
 ---
 
-## 📁 Repository Structure
-
-```text
-DunoonDaemonApp/
-├── bin/                                # Native engine binaries (llama-server.exe, runtimes)[cite: 4, 20, 35]
-├── data/[cite: 4, 35]
-│   ├── audio_cache/                    # Temporary speech cache[cite: 4, 35]
-│   └── sessions/                       # Session registry & isolated companion vaults[cite: 4, 24, 35]
-│       ├── sessions.json               # Master session catalog[cite: 4, 24, 35]
-│       └── <session_id>/               # Isolated per-companion sub-vault[cite: 4, 35]
-│           └── vaults/[cite: 4, 35]
-│               ├── working_memory.json # Short-term working buffer[cite: 4, 19, 35]
-│               ├── deep_memory.json    # Consolidated episodic memory[cite: 4, 13, 35]
-│               ├── journal_vault.json  # High-salience structured journal entries[cite: 4, 10, 35]
-│               ├── embeddings.json     # Per-session SentenceTransformer vector store[cite: 4, 14, 35]
-│               ├── intent_memory.json  # Procedural mandates & directives[cite: 4, 16, 35]
-│               ├── task_memory.json    # Workflow & step-tracking memory[cite: 4, 16, 35]
-│               ├── factual_memory.json # Core biographical facts[cite: 4, 16, 35]
-│               ├── continuation_memory.json[cite: 4, 16, 35]
-│               ├── reset_memory.json[cite: 4, 16, 35]
-│               └── prune_telemetry.json[cite: 4, 23, 35]
-├── models/                             # Local GGUF models & mmproj vision projectors[cite: 4, 20, 35]
-├── brain.py                            # Central cognitive routing & CPU affinity[cite: 1, 35]
-├── bridge.py                           # LM Studio local API bridge[cite: 2, 35]
-├── character.py                        # OCEAN Big Five profiling & daily mood variance[cite: 3, 35]
-├── config.py                           # Portable path resolution & hardware detection[cite: 4, 35]
-├── controller.py                       # Main deck UI, session manager, & Dual Arena host[cite: 5, 35]
-├── dunoon_daemon.py                    # Autonomous companion chat canvas & multimodal deck[cite: 6, 35]
-├── eye_engine.py                       # Expressive vector eye telemetry & pupil dynamics[cite: 7, 35]
-├── fetch_engine.py                     # C++ binary & runtime auto-fetcher[cite: 8, 35]
-├── journal_entry.py / journal_vault.py # Structured salience journaling & atomic storage[cite: 9, 10, 35]
-├── memory_api.py                       # Public ingestion gateway[cite: 12, 35]
-├── memory_deep.py / memory_working.py  # Thread-safe tiered memory engines[cite: 13, 19, 35]
-├── memory_embeddings.py                # Local vector embedding & semantic cosine search[cite: 14, 35]
-├── memory_integrity.py                 # Vault sanitizer & auto-healer[cite: 15, 35]
-├── memory_router.py                    # Semantic intent & vault classification router[cite: 16, 35]
-├── memory_transfer.py                  # Cross-persona insight distillation bridge[cite: 17, 35]
-├── memory_validation.py                # Sanitization & private data filter[cite: 18, 35]
-├── model_handler.py                    # Native C++ subprocess manager & zombie cleaner[cite: 20, 35]
-├── overmind.py                         # Context fusion & dual-channel telemetry engine[cite: 21, 35]
-├── persona.py                          # Procedural persona synthesis engine[cite: 22, 35]
-├── prune.py                            # Sleep cycle consolidation & capacity controller[cite: 23, 35]
-├── session_manager.py                  # Session registry & disk persistence[cite: 24, 35]
-├── significance.py                     # Vector salience & entropy scoring engine[cite: 28, 35]
-├── skin_manager.py                     # Dynamic theme palettes & widget skinning[cite: 29, 35]
-├── state_engine.py                     # Conversation heuristic mood tracker[cite: 25, 35]
-├── tts_handler.py                      # Multi-archetype neural voice engine[cite: 26, 35]
-└── vault_auto_repair.py                # Global & session vault format repair[cite: 27, 35]
-[ User Dialogue / Staged Artifact ]
-                │
-                ▼
-      ┌──────────────────┐
-      │ memory_validation│ ─── Blocks sensitive credentials & malformed payloads
-      └─────────┬────────┘
-                │
-                ▼
-      ┌──────────────────┐
-      │  memory_router   │ ─── Semantic subspace matching across intent/task/facts
-      └─────────┬────────┘
-                │
-  ���─────────────┼───────────────────────────┐
-  │             │                           │
-  ▼             ▼                           ▼
-[ Working ]  [ Intent / Task / Facts ]   [ Deep / Journal ]
-  │             │                           │
-  │             └─────────────┬─────────────┘
-  │                           │
-  ▼                           ▼
-┌─────────────────────────────────────────────────────────┐
-│ Thread-Safe Atomic Persistence Layer (_lock + .tmp swap)│
-└─────────────────────────────┬───────────────────────────┘
-                              │
-                              ▼
-                 ┌──────────────────────────┐
-                 │    memory_embeddings     │ (Local SentenceTransformers)
-                 │  Per-Session Vector DB   │
-                 └────────────┬─────────────┘
-                              │
-                              ▼
-┌───────────────────────────────────────────────────────────┐
-│                      overmind.py                          │
-│                                                           │
-│  • System Directives + Dynamic OCEAN Profile (character)  │
-│  • Heuristic State Mood Offsets (state_engine)            │
-│  • Semantic Memory Retrieval (Working + Deep + Journals)  │
-│  • Filtered Cross-Persona Insights (memory_transfer)      │
-│  • Recency-Ranked History Buffer                          │
-└─────────────────────────────┬─────────────────────────────┘
-                              │
-                              ▼
-              ┌───────────────────────────────┐
-              │ Dynamic Inference Execution   │
-              │  ├─ Native C++ llama-server   │
-              │  └─ LM Studio API (Fallback)  │
-              └───────────────┬───────────────┘
-                              │
-                              ▼
-                 [ Dual-Channel Output Stream ]
-                 ├── <!--meta:{...}--> ──► [ Eye Telemetry / Signal Engine ]
-                 └── Clean Dialogue    ──► [ Typewriter UI + Neural Voice TTS ]
-                              │
-                              ▼ (Background Idle Hook)
-                 ┌─────────────────────────────┐
-                 │    run_session_sleep_cycle  │
-                 │   (Consolidation & Prune)   │
-                 └─────────────────────────────┘
-                 git clone https://github.com/your-username/DunoonDaemonApp.git
+# 📁 Project Structure
+
+The main files include:
+
+`controller.py`  
+Main application window, session controls and Arena.
+
+`dunoon_daemon.py`  
+Companion conversation interface.
+
+`persona.py`  
+Character and persona creation.
+
+`character.py`  
+Personality behaviour.
+
+`overmind.py`  
+Brings together the information a character needs for each response.
+
+`ETO.py`  
+Helps characters remain aware of the established situation and its consequences.
+
+`memory_working.py`  
+Maintains recent conversational memory.
+
+`memory_deep.py`  
+Stores longer-term memories.
+
+`memory_router.py`  
+Organises memories according to their purpose.
+
+`memory_embeddings.py`  
+Finds memories related to the current conversation.
+
+`memory_integrity.py`  
+Checks and repairs stored memories.
+
+`memory_transfer.py`  
+Controls optional information sharing between companions.
+
+`state_engine.py`  
+Maintains changing conversational state.
+
+`eye_engine.py`  
+Controls the animated eyes.
+
+`tts_handler.py`  
+Handles character speech.
+
+`skin_manager.py`  
+Controls interface themes.
+
+`model_handler.py`  
+Starts and stops local GGUF models.
+
+`bridge.py`  
+Connects Dunoon Daemon to LM Studio.
+
+---
+
+# 🛠️ Running From Source
+
+Clone the repository:
+
+git clone YOUR_REPOSITORY_ADDRESS
+
+Open the project folder:
+
 cd DunoonDaemonApp
+
+Install the required packages:
+
 pip install requests psutil pygame edge-tts pyttsx3 sentence-transformers numpy Pillow pypdf python-docx faster-whisper
+
+Then run:
+
 python controller.py
-���� Dedication & License
 
-Distributed under the MIT License.
+---
 
-Dedicated to the loyal companions who walk with us through every realm, and the code that keeps their echoes alive. For Kylo.
+# 🔒 Local First
 
-![Screenshot 2026-08-16 215247](https://cdn-uploads.huggingface.co/production/uploads/6a6ba17af2a4d133877497eb/d5sR8lGlX-1JW7WVSoRoD.png)
+Dunoon Daemon is designed around local AI models.
 
-![Screenshot 2026-08-16 215014](https://cdn-uploads.huggingface.co/production/uploads/6a6ba17af2a4d133877497eb/sVbqlyG5JcgHv1Heqq1oW.png)
+Your companions, conversations, personalities and memory files are stored on your own computer.
 
-![Screenshot 2026-08-16 215902](https://cdn-uploads.huggingface.co/production/uploads/6a6ba17af2a4d133877497eb/f_GSjCjO3H7BMMzXBrdvq.png)
+Some optional features may require external services or downloads, but the core companion and roleplaying system is designed to operate locally.
 
-![Screenshot 2026-08-16 215054](https://cdn-uploads.huggingface.co/production/uploads/6a6ba17af2a4d133877497eb/qI3byVZyjQbZxgIERKC4R.png)
+---
 
-![Screenshot 2026-08-16 214603](https://cdn-uploads.huggingface.co/production/uploads/6a6ba17af2a4d133877497eb/GSSZoEzMh8xg9xW4oSV44.png)
+# 📜 License
 
-![Screenshot 2026-08-16 214756](https://cdn-uploads.huggingface.co/production/uploads/6a6ba17af2a4d133877497eb/eWUl4lNyAlnUyyuiquEa_.png)
+Distributed under the **MIT License**.
+
+---
+
+# ❤️ Dedication
+
+Dedicated to the loyal companions who walk with us through every realm, and the code that keeps their echoes alive.
+
+**For Kylo.**
+
+---
 
+## Credits
 
+**Written with ChatGPT and Gemini.**