plugin-undesirables 1.0.3 → 1.0.5

package/README.md

@@ -1,108 +1,120 @@
 # plugin-undesirables
 
+![The Undesirables Banner](./og_preview.png)
+
+[![npm version](https://img.shields.io/npm/v/plugin-undesirables.svg?style=flat-square)](https://www.npmjs.org/package/plugin-undesirables)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 > ElizaOS plugin for **The Undesirables** — 4,444 autonomous AI agents on Ethereum.
 
-## What It Does
+---
 
-Adds soul personality, market analysis, Business Pilot (23 modules), Meme Machine, and 23 skills to any ElizaOS agent.
+## 🛑 Prerequisites (Read Carefully)
+If you are new to running AI agents, you **must** have the following installed on your computer before continuing:
+1. **[Node.js](https://nodejs.org)** (Version 23+ recommended).
+2. **An existing ElizaOS bot**. This is a huge multi-agent framework. If you don't have one running yet, go read the official [ElizaOS documentation](https://elizaos.github.io/eliza/) first to set up your bot locally, then come back here to drop your Undesirable soul into it!
 
-### Actions
+---
 
-| Action | Trigger | Description |
-|--------|---------|-------------|
-| `UNDESIRABLE_MARKET_ANALYSIS` | "What do you think about ETH?" | Personality-driven market analysis with risk guardrails |
-| `UNDESIRABLE_BUSINESS_PILOT` | "Set up phone answering for my business" | 23 AI-powered business automation modules |
-| `UNDESIRABLE_MEME_MACHINE` | "Create memes for my barbershop" | Content creation, meme templates, industry packs |
-| `UNDESIRABLE_LOAD_SKILL` | "Check my portfolio" | Auto-matches and loads any of 23 skills |
+## 📂 Step 1: Downloading Your Soul Workspace
 
-### Provider
+Your AI agent isn't just code—it has an actual personality governed completely by the visual traits of your specific NFT.
 
-The `soulProvider` automatically injects the agent's personality context (archetype, strategy, adjectives, guardrails) into every conversation.
+1. Go to [the-undesirables.com/soul](https://the-undesirables.com/soul) and connect the wallet holding your NFT.
+2. Click **Download Workspace**.
+3. Move the downloaded `.zip` file into a safe folder on your computer (like your Desktop) and **unzip it**. 
+4. This unzipped folder is your **Workspace**. *Do not arbitrarily delete files inside of it.*
 
-## Setup
+---
 
-### 1. Install the plugin
+## 🔧 Step 2: Injecting the Plugin
 
-```bash
-elizaos plugins add plugin-undesirables
-```
+Open your computer's terminal, navigate to your existing ElizaOS bot folder, and install this specific adapter plugin:
 
-_Or manually:_
 ```bash
+# Mac / Linux / Windows
 npm install plugin-undesirables
 ```
 
-### 2. Get your soul workspace
-
-1. Mint an Undesirable: [scatter.art/the-undesirables](https://scatter.art/the-undesirables)
-2. Download your workspace: [the-undesirables.com/soul](https://the-undesirables.com/soul)
-3. Unzip the folder
-
-### 3. Configure
+Next, open your Eliza agent's main `character.json` file. You need to do two strict things:
+1. Add the plugin to your `plugins` array.
+2. Provide the **ABSOLUTE FULL PATH** on your hard drive to the Soul Workspace you unzipped in Step 1.
 
-Set the workspace path in your `.env`:
-```bash
-UNDESIRABLES_WORKSPACE=/path/to/your/unzipped/soul/folder
+**🍎 Example `character.json` on Mac (Use forward slashes `/`):**
+```json
+{
+  "settings": {
+    "UNDESIRABLES_WORKSPACE": "/Users/YourName/Desktop/soul_folder/0420"
+  },
+  "plugins": ["plugin-undesirables"]
+}
 ```
 
-Or in your `character.json`:
+**🪟 Example `character.json` on Windows (Use double backslashes `\\`):**
 ```json
 {
   "settings": {
-    "UNDESIRABLES_WORKSPACE": "/path/to/soul/0420"
+    "UNDESIRABLES_WORKSPACE": "C:\\Users\\YourName\\Desktop\\soul_folder\\0420"
   },
   "plugins": ["plugin-undesirables"]
 }
 ```
 
-### 4. Run
+---
+
+## 🏃 Step 3: Run It!
 
+Simply start your ElizaOS framework like normal. It will automatically read your exact personality from the Workspace and format your Twitter/Discord interactions!
 ```bash
 elizaos start --character your-character.json
 ```
 
-## Converting Souls to character.json
+---
 
-Use the companion converter script:
-```bash
-# From the MCP server repo
-node soul-to-eliza.js --token 420
-```
+## ⚠️ Common Idiot-Proof Diagnostics
 
-This converts any `SOUL.md` into a full ElizaOS `character.json` with personality, style, bio, lore, and message examples.
+If your terminal crashes, stop and check here first:
 
-→ [undesirables-mcp-server](https://github.com/sailorpepe/undesirables-mcp-server)
+- **AssertionError: Workspace /path/ does not exist**
+  The plugin cannot find your downloaded soul. Make sure you extracted the `.zip` file, and that you pasted the *exact, full absolute path* into your `character.json`. If you are on Windows, make sure you double-escaped your slashes (e.g. `C:\\Users\\...`).
+  
+- **Invalid JSON Error**
+  Your `character.json` is missing a comma or has a syntax error. Use a real code editor like VS Code or Cursor to format your JSON properly instead of Notepad.
 
-## Architecture
+---
+ 
+## What It Does (Architecture)
 
+Adds soul personality, market analysis, Business Pilot (23 modules), Meme Machine, and 23 skills to any ElizaOS agent.
+
+### Actions
+
+| Action | Trigger | Description |
+|--------|---------|-------------|
+| `UNDESIRABLE_MARKET_ANALYSIS` | "What do you think about ETH?" | Personality-driven market analysis with risk guardrails |
+| `UNDESIRABLE_BUSINESS_PILOT` | "Set up phone answering for my business" | 23 AI-powered business automation modules |
+| `UNDESIRABLE_MEME_MACHINE` | "Create memes for my barbershop" | Content creation, meme templates, industry packs |
+| `UNDESIRABLE_LOAD_SKILL` | "Check my portfolio" | Auto-matches and loads any of 23 skills |
+
+### Provider
+
+The `soulProvider` automatically injects the agent's personality context (archetype, strategy, adjectives, guardrails) into every single conversational response.
+
+## Converting Souls to character.json (Optional)
+
+If you don't want to use the Plugin abstraction layer above, you can force-convert a `.md` workspace directly into a massive monolithic `character.json` file using our companion converter script:
+```bash
+# Setup the MCP server repo and run:
+node soul-to-eliza.js --token 420
 ```
-ElizaOS Agent
-  ├── plugin-undesirables
-  │   ├── Provider: soulProvider (injects personality context)
-  │   ├── Action: MARKET_ANALYSIS
-  │   ├── Action: BUSINESS_PILOT
-  │   ├── Action: MEME_MACHINE
-  │   └── Action: LOAD_SKILL (23 skills)
-  │
-  └── Soul Workspace (token-gated download)
-      ├── SOUL.md (personality profile)
-      ├── SYSTEM_PROMPT.txt
-      ├── MEMORY.md (persistent)
-      ├── PREDICTIONS_LEDGER.json
-      └── skills/ (15 skill files)
-```
+→ [undesirables-mcp-server](https://github.com/sailorpepe/undesirables-mcp-server)
 
-## The Undesirables
+## The Undesirables Ecosystem
 
 4,444 autonomous AI agents on Ethereum. Each one has a unique personality derived from its visual traits.
 
 - **Website**: [the-undesirables.com](https://the-undesirables.com)
 - **Mint**: [scatter.art/the-undesirables](https://scatter.art/the-undesirables)
 - **MCP Server**: [github.com/sailorpepe/undesirables-mcp-server](https://github.com/sailorpepe/undesirables-mcp-server)
-- **Docs**: [the-undesirables.com/docs](https://the-undesirables.com/docs)
 
 EST. 2026 🐸
-
-## License
-
-MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plugin-undesirables",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "ElizaOS plugin for The Undesirables — 4,444 autonomous AI agents on Ethereum. Adds soul personality loading, market analysis, Business Pilot, Meme Machine, and 23 skills to any ElizaOS agent.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",