Add CONTRIBUTING, CODEOWNERS, PR/issue templates for better onboarding

.eslintrc.json

@@ -0,0 +1,18 @@
+{
+  "env": {
+    "node": true,
+    "es2021": true
+  },
+  "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 12,
+    "sourceType": "module"
+  },
+  "plugins": ["@typescript-eslint"],
+  "rules": {
+    "semi": ["error", "always"],
+    "quotes": ["error", "single"],
+    "@typescript-eslint/no-unused-vars": "warn"
+  }
+}

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @Yusasive

.github/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contributing to Eremos
+
+Thank you for your interest in contributing! Here’s how to get started:
+
+## Getting Started
+
+- Fork the repository and clone your fork.
+- Install dependencies: `npm install`
+- Run the project: `npm run dev`
+
+## How to Contribute
+
+- Propose improvements (code, docs, structure, tooling).
+- Open a clean pull request with a clear description.
+- Follow code style guidelines (see below).
+
+## Code Style
+
+- Use TypeScript for all source files.
+- Run `npm run lint` and `npm run format` before submitting.
+
+## Need Help?
+
+Open an issue or join discussions!

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,14 @@
+# Issue Template
+
+## Description
+
+Describe the issue or suggestion.
+
+## Steps to Reproduce
+
+1.
+2.
+
+## Expected Behavior
+
+## Additional Context

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,25 @@
+---
+name: Bug Report
+about: Create a report to help us improve
+labels: bug
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+
+1. Go to '...'
+2. Click on '...'
+3. Scroll down to '...'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature Request
+about: Suggest an idea for this project
+labels: enhancement
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is.
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+# Pull Request
+
+## Description
+
+Please describe your changes and why they are useful.
+
+## Checklist
+
+- [ ] I have tested my changes
+- [ ] I have updated documentation if needed
+- [ ] My code follows the style guidelines

.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: Node.js CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18.x]
+    steps:
+      - uses: actions/checkout@v3
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm install
+      - run: npm run lint
+      - run: npm run format
+      - run: npm test

.gitignore

@@ -1,6 +1,7 @@
 node_modules
 dist
 .env
+.env.local
 
 # macOS system file
 .DS_Store

.nycrc

@@ -0,0 +1,7 @@
+{
+  "extends": "@istanbuljs/nyc-config-typescript",
+  "all": true,
+  "reporter": ["text", "lcov"],
+  "include": ["agents/**/*.ts", "utils/**/*.ts", "types/**/*.ts"],
+  "exclude": ["**/*.test.ts", "scripts/**", "docs/**"]
+}

.prettierrc

@@ -0,0 +1,6 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2
+}

CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+- Initial improvements: README overhaul, dev tooling, docs navigation, templates, CI/CD setup.

FAQ.md

@@ -0,0 +1,22 @@
+# Frequently Asked Questions (FAQ)
+
+**Q: What is Eremos?**
+A: Eremos is a modular agent framework for monitoring blockchain activity and emitting early signals.
+
+**Q: How do I run an agent?**
+A: Use `npm run dev` after installing dependencies. See the README for details.
+
+**Q: Can I add my own agent?**
+A: Yes! Use `agents/example.ts` as a template and follow the contributing guide.
+
+**Q: What chains are supported?**
+A: Currently, Eremos supports RPC-based chains. Multi-chain support is planned (see ROADMAP).
+
+**Q: How do I report bugs or request features?**
+A: Use the issue templates provided in the .github folder.
+
+**Q: Where can I find documentation?**
+A: See the `docs/` folder and the README for navigation.
+
+**Q: Who maintains Eremos?**
+A: The Eremos Core team. See the README for contact links.

README.md

@@ -15,25 +15,23 @@ Designed for devs who want low-noise, early signals embedded into their workflow
 </p>
 
 **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)
 
 ---
 
 ## Features
 
-- **Modular Agents** - Scoped logic for detecting wallet activity, contract spawns, and anomalies  
-- **Signal Emission** - Structured signals for logging, alerting, or downstream use  
-- **Swarm Design** - Each agent operates independently with shared utilities  
-- **Extensible Core** - Plug in watchers, inference layers, or custom triggers  
+- **Modular Agents** - Scoped logic for detecting wallet activity, contract spawns, and anomalies
+- **Signal Emission** - Structured signals for logging, alerting, or downstream use
+- **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.*
-
+- _+ More to come._
 
 ---
 
@@ -64,6 +62,7 @@ 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)
@@ -101,10 +100,10 @@ npm run dev
 
 ## Key Folders
 
-- `/agents` - Agent templates + logic  
-- `/utils` - Shared signal/logging utilities  
-- `/types` - TypeScript interfaces + definitions  
-- `/scripts` - Bootstrap and dev scripts  
+- `/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
 
 ---
@@ -130,3 +129,19 @@ MIT © Eremos LLC
 - **Whitepaper:** [v1.0 PDF](docs/whitepaper.pdf)
 
 _Maintained by the Eremos Core team 💛._
+
+---
+
+## Code Coverage
+
+Code coverage is tracked using [nyc](https://github.com/istanbuljs/nyc).
+
+To run coverage:
+
+```bash
+npm run coverage
+```
+
+Coverage reports are output in the terminal and as an lcov file for badge integration.
+
+---

ROADMAP.md

@@ -0,0 +1,22 @@
+# Eremos Roadmap
+
+## Q3 2025
+
+- Launch Agent-001 (active agent)
+- Add more agent templates
+- Improve signal confidence scoring
+- Expand documentation and onboarding
+
+## Q4 2025
+
+- Add web-based dashboard for agent monitoring
+- Integrate more chain layers and triggers
+- Community-driven agent submissions
+
+## 2026
+
+- Multi-chain support
+- Advanced analytics and reporting
+- Open API for third-party integrations
+
+_Contributions and suggestions welcome!_

SECURITY.md

@@ -0,0 +1,8 @@
+# Security Policy
+
+If you discover a vulnerability in Eremos, please report it by opening a private issue or emailing the maintainers.
+
+- Do not disclose security issues publicly until they are resolved.
+- We aim to respond to security reports within 48 hours.
+
+Thank you for helping keep Eremos safe!

agents/README.md

@@ -0,0 +1,11 @@
+# Agents Folder
+
+This folder contains agent templates and logic for Eremos.
+
+- `example.ts`: Template agent for custom development
+- `theron.ts`: Passive, pattern-sensitive agent
+- `harvester.ts`, `observer.ts`, `launchtracker.ts`, `skieró.ts`: Specialized agents for different monitoring tasks
+
+To create your own agent, copy `example.ts` and modify its logic and metadata.
+
+See the main README and docs for more details.

docs/README.md

@@ -0,0 +1,11 @@
+# Eremos Documentation
+
+Welcome to the Eremos docs! Use the links below to navigate key topics:
+
+- [Project Overview](architecture.md)
+- [Agents](agents.md)
+- [Signals](signals.md)
+- [Metrics](metrics.md)
+- [Memory](memory.md)
+- [Deployment](deployment.md)
+- [Contributing](contributing.md)

docs/SUMMARY.md

@@ -0,0 +1,12 @@
+# Documentation Summary
+
+- [Agents](agents.md)
+- [Architecture](architecture.md)
+- [Contributing](contributing.md)
+- [Deployment](deployment.md)
+- [Events](events.md)
+- [Memory](memory.md)
+- [Metrics](metrics.md)
+- [Runtime](runtime.md)
+- [Signals](signals.md)
+- [Throttle](throttle.md)

docs/architecture.md

@@ -3,6 +3,7 @@
 Eremos is a swarm-style agent framework for passive blockchain observation.
 
 Each agent:
+
 - Has a role (`observer`, `memory`, `trigger`, `+ more to come`)
 - Watches a specific event type
 - Emits structured signals
@@ -12,3 +13,16 @@ Shared utilities and types define common structure across agents.
 Signals are deterministic and lightweight — not reactive.
 
 > Agent communication and orchestration are coming soon.
+
+# Architecture
+
+![Architecture Diagram](architecture-diagram.png)
+
+This diagram illustrates the modular agent framework of Eremos, showing how agents interact with blockchain data, utilities, and the signal emission system.
+
+- **Agents**: Monitor blockchain events and emit signals
+- **Utils**: Provide shared logic for parsing, logging, metrics, and more
+- **Types**: Define interfaces and data structures
+- **Scripts**: Bootstrap and manage agent execution
+
+For more details, see the main README and docs.

docs/badges.md

@@ -0,0 +1,7 @@
+# Badges & Shields
+
+Add these to your main README for extra clarity:
+
+- ![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+- ![Node.js CI](https://github.com/Yusasive/Eremos/actions/workflows/node.js.yml/badge.svg)
+- ![npm version](https://img.shields.io/npm/v/eremos-core)