docs: README badges + ToC; add typecheck CI and PR template

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,31 @@
+## Summary
+
+Describe the change in 1-2 sentences.
+
+## Motivation
+
+Why is this change needed? What problem does it solve?
+
+## Changes
+
+- [ ] Feature / Enhancement
+- [ ] Bug fix
+- [ ] Docs / Readme
+- [ ] Tooling / CI
+
+### Details
+
+- What was added/changed?
+- Any breaking changes?
+
+## Testing
+
+- Steps to verify locally:
+  - npm run typecheck
+  - (add commands/screenshots/logs as needed)
+
+## Checklist
+
+- [ ] I ran `npm run typecheck` and it passed
+- [ ] I updated docs or comments where relevant
+- [ ] I scoped the PR to a single purpose

.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Use Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install
+        run: npm ci || npm i
+
+      - name: TypeScript typecheck
+        run: npm run typecheck

README.md

@@ -18,11 +18,31 @@ Designed for devs who want low-noise, early signals embedded into their workflow
 *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)
 
 ---
 
+<p align="center">
+  <a href="https://github.com/lucadavid075/Eremos/actions" target="_blank"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/lucadavid075/Eremos/ci.yml?branch=main&label=CI&logo=github" /></a>
+  <a href="https://github.com/lucadavid075/Eremos/Eremos/blob/main/LICENSE" target="_blank"><img alt="License" src="https://img.shields.io/badge/License-MIT-yellow.svg" /></a>
+  <a href="https://x.com/EremosCore" target="_blank"><img alt="Follow on X" src="https://img.shields.io/badge/Follow-@EremosCore-1DA1F2?logo=x" /></a>
+</p>
+
+## Table of Contents
+
+- [Features](#features)
+- [Example Signal](#example-signal)
+- [Signal Confidence](#signal-confidence)
+- [Tech Stack](#tech-stack)
+- [Getting Started](#getting-started)
+- [Key Folders](#key-folders)
+- [Docs](#docs)
+- [Contributing](#contributing)
+- [License](#license)
+- [Links](#links)
+
+---
+
 ## Features
 
 - **Modular Agents** - Scoped logic for detecting wallet activity, contract spawns, and anomalies  
@@ -34,7 +54,6 @@ Modular and extendable by design.*
 - **Ghost Watcher** - Monitors long-dormant wallets that suddenly become active again. Useful for tracing old dev wallets or rug setups.
 - *+ More to come.*
 
-
 ---
 
 ## Example Signal
@@ -85,15 +104,20 @@ Confidence is computed via agent-side scoring and logged alongside the signal.
 ## Getting Started
 
 ```bash
-git clone https://github.com/EremosCore/Eremos.git
+git clone https://github.com/lucadavid075/Eremos.git
 cd Eremos
 npm install
 ```
 
-Set up your environment:
+Run a quick type check:
+
+```bash
+npm run typecheck
+```
+
+Start a local dev loop (scaffold script placeholder):
 
 ```bash
-cp .env.example .env.local
 npm run dev
 ```
 
@@ -109,12 +133,29 @@ npm run dev
 
 ---
 
+## Docs
+
+- `docs/agents.md` — Agent structure and lifecycle
+- `docs/signals.md` — Signal format and hashing
+- `docs/events.md` — Event parsing
+- `docs/memory.md` — Memory and persistence
+- `docs/metrics.md` — Metrics and counters
+- `docs/architecture.md` — High-level architecture
+- `docs/deployment.md` — Deployment notes
+
+---
+
 ## 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)
 
+When opening a PR, please:
+- Keep edits focused and documented in the description
+- Run `npm run typecheck` and ensure it passes
+- Use our PR template (pre-filled when you open a PR)
+
 ---
 
 ## License

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...'",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "keywords": [
     "agent",
@@ -14,5 +15,13 @@
     "framework"
   ],
   "license": "MIT",
-  "author": "EremosCore"
+  "author": "EremosCore",
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "packageManager": "npm@10"
 }

tsconfig.json

@@ -5,7 +5,8 @@
     "strict": true,
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,
-    "skipLibCheck": true
+    "skipLibCheck": true,
+    "types": ["node"]
   },
   "include": ["./agents", "./types", "./utils"]
 }

utils/logger.ts

@@ -4,9 +4,13 @@ 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}`);
+  if (signal.confidence !== undefined) {
+    console.log(`├─ confidence: ${signal.confidence}`);
+  }
   if (signal.details) {
     console.log(`├─ context:`, JSON.stringify(signal.details, null, 2));
   }