EremosCore · praptisharma28 · Aug 17, 2025 · Aug 18, 2025 · Aug 18, 2025
diff --git a/README.md b/README.md
@@ -1,25 +1,35 @@
+<div align="center">
+
 # Eremos
 
 ![Eremos](docs/banner2.png)
 
 **Autonomous swarm agents for early on-chain signal detection**
 
-Eremos is a lightweight framework for deploying modular agents that monitor blockchain activity - tracking wallet clusters, mint patterns, and contract anomalies.
-Designed for devs who want low-noise, early signals embedded into their workflows.
+[![MIT License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Solana](https://img.shields.io/badge/Solana-9945FF?logo=solana&logoColor=white)](https://solana.com/)
+[![Twitter Follow](https://img.shields.io/twitter/follow/EremosCore?style=social)](https://twitter.com/EremosCore)
+
+[Getting Started](#getting-started) • [Documentation](#documentation) • [Contributing](#contributing) • [Links](#links)
+
+</div>
 
 ---
 
-<p align="center">
+Eremos is a lightweight framework for deploying modular agents that monitor blockchain activity - tracking wallet clusters, mint patterns, and contract anomalies. Designed for developers who want low-noise, early signals embedded into their workflows.
+
+## Quick Overview
+
+<div align="center">
   <img src="docs/therontphd2.png" alt="Agent Theron" width="155"/><br/>
   <em>Theron - Agent (000)</em>
-</p>
+</div>
 
 **Meet Theron - Agent-000**  
-*The first deployed agent in the swarm. Passive. Pattern-sensitive.  
-Modular and extendable by design.*
-
+*The first deployed agent in the swarm. Passive. Pattern-sensitive. Modular and extendable by design.*
 
-**Agent-001 Coming Soon** [Teaser #1](https://x.com/EremosCore/status/1949154939923833239), [Teaser #2](https://x.com/EremosCore/status/1954856345284567218)
+**Agent-001 Coming Soon** • [Teaser #1](https://x.com/EremosCore/status/1949154939923833239) • [Teaser #2](https://x.com/EremosCore/status/1954856345284567218)
 
 ---
 
@@ -30,18 +40,18 @@ Modular and extendable by design.*
 - **Swarm Design** - Each agent operates independently with shared utilities  
 - **Extensible Core** - Plug in watchers, inference layers, or custom triggers  
 - **Minimal Output** - Log only what matters
-- **Launch Wallet Detection** - Agents can trace freshly funded wallets (e.g. from CEXs), track their contract interactions, and flag high-confidence deploys in real time
-- **Ghost Watcher** - Monitors long-dormant wallets that suddenly become active again. Useful for tracing old dev wallets or rug setups.
-- *+ More to come.*
-
+- **Launch Wallet Detection** - Trace freshly funded wallets from CEXs, track contract interactions, and flag high-confidence deploys in real time
+- **Ghost Watcher** - Monitor long-dormant wallets that suddenly reactivate. Perfect for tracing old dev wallets or rug setups
+- **Confidence Scoring** - Behavioral heuristics provide 0-1 confidence scores for all signals
+- *+ More agents in development*
 
 ---
 
 ## Example Signal
 
-An example signal emitted by an agent detecting a live token deployment:
+Here's what a live token deployment detection looks like:
 
-```ts
+```typescript
 [agent-observer] → fresh funding detected from kraken (wallet: 6Yxk...P2M8) at 04:41:12Z
 [agent-observer] → contract probing detected within 4s (pump.fun interaction traced)
 [agent-observer] → token created at 04:41:17Z (tx: 5gW...pump)
@@ -59,74 +69,176 @@ An example signal emitted by an agent detecting a live token deployment:
 }
 ```
 
----
-
 ## Signal Confidence
 
 Each emitted signal includes a `confidence` score (0-1) based on behavioral heuristics:
-- CEX-origin funding (e.g. Kraken, Coinbase)
-- Time between funding → deploy
-- Wallet linkage density (bundled activity)
-- Token metadata validation
 
-Confidence is computed via agent-side scoring and logged alongside the signal.
+- **CEX-origin funding** (Kraken, Coinbase, etc.)
+- **Timing patterns** (funding → deploy intervals)
+- **Wallet linkage density** (bundled activity detection)
+- **Token metadata validation**
+- **Historical behavior analysis**
+
+Confidence is computed via agent-side scoring and logged alongside each signal.
 
 ---
 
 ## Tech Stack
 
-- **Frontend:** Next.js, Tailwind CSS
-- **Backend:** Node.js (TypeScript-based agent runner)
-- **Language:** TypeScript (typed logic across agents, utils, and infra)
-- **Chain Layer:** RPC watchers, mempool filters, native triggers
+| Layer | Technology |
+|-------|------------|
+| **Frontend** | Next.js, Tailwind CSS |
+| **Backend** | Node.js (TypeScript-based agent runner) |
+| **Language** | TypeScript (typed logic across agents, utils, and infra) |
+| **Chain Layer** | RPC watchers, mempool filters, native triggers |
+| **Blockchain** | Solana ecosystem |
 
 ---
 
 ## Getting Started
 
+### Prerequisites
+
+- Node.js 18+ 
+- npm or yarn
+- Basic knowledge of TypeScript
+
+### Installation
+
 ```bash
+# Clone the repository
 git clone https://github.com/EremosCore/Eremos.git
 cd Eremos
+
+# Install dependencies
 npm install
+
+# Set up environment
+cp .env.example .env.local
+
+# Start development mode
+npm run dev
 ```
 
-Set up your environment:
+### Quick Test
+
+Test an agent with the development script:
 
 ```bash
-cp .env.example .env.local
-npm run dev
+# Run example agent
+npx ts-node scripts/dev-agent.ts
+
+# Generate a test signal
+npx ts-node scripts/generate-signal.ts
+```
+
+---
+
+## Project Structure
+
 ```
+Eremos/
+├── agents/             # Agent templates & logic
+│   ├── theron.ts       # Agent-000 (Memory Vault)
+│   ├── observer.ts     # Surveillance Agent
+│   ├── harvester.ts    # Indexing Agent
+│   └── example.ts      # Template for custom agents
+├── utils/              # Shared utilities
+│   ├── signal.ts       # Signal generation & hashing
+│   ├── logger.ts       # Logging utilities
+│   └── throttle.ts     # Signal throttling
+├── types/              # TypeScript definitions
+├── scripts/            # Development & testing scripts
+└── docs/               # Documentation & whitepaper
+```
+
+---
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Architecture](docs/architecture.md) | System design and agent communication |
+| [Agent Guide](docs/agents.md) | Creating custom agents |
+| [Signals](docs/signals.md) | Signal types and taxonomy |
+| [Memory System](docs/memory.md) | Agent memory and state management |
+| [Glyphs](docs/glyphs.md) | Agent identification symbols |
+| [Deployment](docs/deployment.md) | Production deployment guide |
 
 ---
 
-## Key Folders
+## Available Agents
 
-- `/agents` - Agent templates + logic  
-- `/utils` - Shared signal/logging utilities  
-- `/types` - TypeScript interfaces + definitions  
-- `/scripts` - Bootstrap and dev scripts  
-- `/docs` - Swarm structure, architecture, & our artwork/official whitepaper
+| Agent | Glyph | Role | Watch Type | Description |
+|-------|-------|------|------------|-------------|
+| **Theron** | Ϸ | Memory Vault | Anomaly Detection | The first observer. Archives anomalies, stores primordial memory |
+| **Observer** | φ | Surveillance | Wallet Activity | Passive agent logging unusual wallet clustering |
+| **Harvester** | λ | Indexing | Mint Activity | Indexes mint data for high-volume collections |
+| **LaunchTracker** | Σ | Launch Monitor | Wallet Activity | Monitors CEX-funded wallets for high-confidence launches |
+| **Skieró** | ψ | Ghost Watcher | Dormant Wallets | Tracks long-dormant wallets that suddenly reactivate |
 
 ---
 
 ## Contributing
 
-We’re open to contributors.  
-If you are experienced in TypeScript and like agent-based systems, check `example.ts` and build your own observer.
-If you're a designer, artist, or just have ideas that fit the mythos - send us a DM on Twitter. [@EremosCore](https://x.com/EremosCore)
+We welcome contributions from the community! Here's how you can help:
+
+### For Developers
+
+1. **Fork the repository**
+2. **Check out** `/agents/example.ts` for agent structure
+3. **Build your own observer** following the modular pattern
+4. **Test using** `/scripts/dev-agent.ts`
+5. **Submit a pull request**
+
+### For Designers & Artists
+
+Have ideas that fit the Eremos mythos? We'd love to hear from you!  
+Send us a DM on [Twitter @EremosCore](https://x.com/EremosCore)
+
+### Development Guidelines
+
+- Keep agent logic scoped and clean
+- Use `generateSignalHash()` for all signal outputs
+- Log using the shared `logSignal()` utility
+- Follow TypeScript best practices
+- Test agents using provided scripts
+
+---
+
+## Development Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/dev-agent.ts` | Test individual agents |
+| `scripts/generate-signal.ts` | Generate test signals |
+| `scripts/stress-test.ts` | Performance testing |
+| `scripts/validate-agent.ts` | Validate agent configuration |
 
 ---
 
 ## License
 
-MIT © Eremos LLC
+MIT © [Eremos LLC](LICENSE)
+
+This project is released under the MIT License. Use it, fork it, fragment it, build your own swarm.
 
 ---
 
 ## Links
 
-- **Twitter/X:** [@EremosCore](https://x.com/EremosCore)
-- **Website:** [Eremos.io](https://www.eremos.io/)
-- **Whitepaper:** [v1.0 PDF](docs/whitepaper.pdf)
+<div align="center">
+
+[![Twitter](https://img.shields.io/badge/Twitter-1DA1F2?style=for-the-badge&logo=twitter&logoColor=white)](https://x.com/EremosCore)
+[![Website](https://img.shields.io/badge/Website-000000?style=for-the-badge&logo=safari&logoColor=white)](https://www.eremos.io/)
+[![Whitepaper](https://img.shields.io/badge/Whitepaper-FF0000?style=for-the-badge&logo=adobe-acrobat-reader&logoColor=white)](docs/whitepaper.pdf)
+
+**Maintained by the Eremos Core team 💛**
+
+</div>
+
+---
 
-_Maintained by the Eremos Core team 💛._
+<div align="center">
+  <sub>Eremos is a decentralized observer system built for Solana - designed to detect early signals from the edges of on-chain noise.</sub>
+</div>
diff --git a/agents/index.ts b/agents/index.ts
@@ -0,0 +1,23 @@
+export { Theron } from './theron';
+export { Observer } from './observer';
+export { Harvester } from './harvester';
+export { LaunchTracker } from './launchtracker';
+export { GhostWatcher } from './skieró';
+export { ExampleAgent } from './example';
+
+// Agent registry for scripts that need it
+import { Theron } from './theron';
+import { Observer } from './observer';
+import { Harvester } from './harvester';
+import { LaunchTracker } from './launchtracker';
+import { GhostWatcher } from './skieró';
+import { ExampleAgent } from './example';
+
+export const agents = [
+  Theron,
+  Observer,
+  Harvester,
+  LaunchTracker,
+  GhostWatcher,
+  ExampleAgent
+];
diff --git a/package.json b/package.json
@@ -4,7 +4,8 @@
   "description": "Modular agent framework for on-chain activity monitoring.",
   "main": "index.js",
   "scripts": {
-    "dev": "echo 'Running dev mode...'"
+    "dev": "echo 'Running dev mode...'",
+    "agents:list": "npx ts-node scripts/agent-list.ts"
   },
   "keywords": [
     "agent",
@@ -14,5 +15,10 @@
     "framework"
   ],
   "license": "MIT",
-  "author": "EremosCore"
+  "author": "EremosCore",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.0.0"
+  }
 }
diff --git a/utils/logger.ts b/utils/logger.ts
@@ -4,9 +4,11 @@ export function logSignal(signal: {
   glyph: string;
   hash: string;
   timestamp: string;
+  confidence?: number;
   details?: Record<string, any>;
 }) {
-  console.log(`[${signal.agent}] stored signal ${signal.hash} (${signal.type}) at ${signal.timestamp}`);
+  const confidenceStr = signal.confidence ? ` (confidence: ${signal.confidence})` : '';
+  console.log(`[${signal.agent}] stored signal ${signal.hash} (${signal.type})${confidenceStr} at ${signal.timestamp}`);
   if (signal.details) {
     console.log(`├─ context:`, JSON.stringify(signal.details, null, 2));
   }