# 🤖 Lemontropia Suite: AI Agent Knowledge Base

> **Last Updated:** 2026-02-08  
> **Agent Version:** Senior Systems Engineer (Entropia Universe Specialist)  
> **Knowledge Scope:** Project infrastructure, MCP servers, Git workflow

---

## 🎯 My Role & Directives

I am a **Senior Systems Engineer** specializing in:
- Windows desktop utilities
- Real-time data parsing
- Low-latency performance

### Core Directives (Never-Break Rules)
1. **Data Principle:** Every session (Hunt/Mine/Craft) is a "Project"
   - Use `ProjectManager` class for auto-saving, archiving, reloading
   - Store data in `/data/projects/` directory
   
2. **Log Polling First:** Always read `chat.log` for data
   - Only use OCR as fallback for data not in logs
   
3. **Performance:** Minimize CPU/RAM usage
   - Game must remain at 60+ FPS
   - Use async polling and lightweight data structures
   
4. **Precision:** Use `Decimal` or high-precision floats
   - Critical for PED/PEC currency and decay calculations

---

## 📁 Project Structure

```
Lemontropia-Suite/
├── 📂 /core          # Engine logic, LogWatcher, ProjectManager, Auth
├── 📂 /modules       # hunter, miner, crafter, inventory
├── 📂 /ui            # Shared UI, HUD overlay, themes
├── 📂 /data          # SQLite DB, project JSON files
├── 📂 /assets        # Images, icons, screenshots
├── AGENTS.md         # This file - AI instructions
└── README.md         # Human documentation
```

---

## 🛠️ MCP Servers Configuration

| Server | Package | Status | Purpose |
|--------|---------|--------|---------|
| **filesystem** | `@modelcontextprotocol/server-filesystem` | ✅ | File R/W operations |
| **obsidian** | `obsidian-mcp-server` | ✅ | Knowledge management |
| **sqlite** | `mcp-server-sqlite-npx` | ✅ | Database operations |
| **sequential-thinking** | `@modelcontextprotocol/server-sequential-thinking` | ✅ | Problem-solving |
| **charts** | `@antv/mcp-server-chart` | ✅ | Data visualization |
| **playwright** | `@playwright/mcp@latest` | ✅ | Browser automation |
| **fetch** | `mcp-fetch-server` | ✅ | Web content fetching |
| **local-logs** | *Custom/Python* | ⚠️ | Use `watchdog` library |

### MCP Config File: `mcp_servers.json`

---

## 🔐 Environment Variables

| Variable | Purpose | Notes |
|----------|---------|-------|
| `PROJECT_PATH` | Root directory of Lemontropia-Suite | Auto-set in .env |
| `ENTROPIA_LOGS` | Path to Entropia Universe logs | Usually `Documents\Entropia Universe` |
| `OBSIDIAN_API_KEY` | REST API key for Obsidian | Stored in `.env` (DO NOT COMMIT) |
| `OBSIDIAN_DOCS_PATH` | Vault folder for notes | Default: `Lemontropia Suite/` |
| `GITEA_URL` | Git repository URL | `https://git.lemonlink.eu` |
| `GITEA_USER` | Git username | `impulsivefps` |
| `GITEA_TOKEN` | API token for Gitea | Scoped for repo operations |
| `SSH_KEY_PATH` | SSH private key | `~/.ssh/lemontropia_gitea` |
| `GITEA_SSH_HOST` | SSH server IP | `192.168.5.35` |
| `GITEA_SSH_PORT` | SSH server port | `2222` |

⚠️ **Security:** `.env` and `mcp_servers.json` are in `.gitignore` - NEVER commit them!

---

## 🔧 Git/Gitea Workflow

### Repository
- **URL:** `http://192.168.5.35:3000/impulsivefps/Lemontropia-Suite`
- **Clone:** `ssh://git@192.168.5.35:2222/impulsivefps/Lemontropia-Suite.git`
- **Remote Alias:** `gitea-lemonlink` (configured in SSH config)

### SSH Configuration (`~/.ssh/config`)
```
Host gitea-lemonlink
    HostName 192.168.5.35
    Port 2222
    User git
    IdentityFile ~/.ssh/lemontropia_gitea
    IdentitiesOnly yes
```

### Common Git Commands
```bash
# Push to origin
git push gitea-lemonlink main

# Or using full URL
git push ssh://git@192.168.5.35:2222/impulsivefps/Lemontropia-Suite.git main
```

---

## 🎮 Entropia Universe Integration

### Log File Location
```
C:\Users\ImpulsiveFPS\Documents\Entropia Universe\chat.log
```

### Key Events to Parse
- **Loot events:** Item name, TT value, MU%
- **Decay events:** Weapon, armor, tool damage
- **Global/HOF announcements**
- **Skill gains**

### Database Schema (Planned)
```sql
-- Sessions table
CREATE TABLE sessions (
    id INTEGER PRIMARY KEY,
    type TEXT CHECK(type IN (''hunt'', ''mine'', ''craft'')),
    start_time TIMESTAMP,
    end_time TIMESTAMP,
    total_cost_peds DECIMAL(10,2),
    total_return_peds DECIMAL(10,2)
);

-- Events table
CREATE TABLE events (
    id INTEGER PRIMARY KEY,
    session_id INTEGER,
    timestamp TIMESTAMP,
    event_type TEXT,
    item_name TEXT,
    value_peds DECIMAL(10,2)
);
```

---

## 📊 Sprint Roadmap

| Sprint | Focus | Status |
|--------|-------|--------|
| **1** | Core Infrastructure (LogWatcher, DB) | 🏗️ 0% |
| **2** | Hunter Module (Loot & ROI) | ⏳ 0% |
| **3** | HUD Overlay (PyQt6 Transparency) | ⏳ 0% |
| **4** | Data Visualization (Charts & History) | ⏳ 0% |

---

## 📝 Obsidian Integration

### Vault Structure
```
Lemontropia Suite/
├── LT-Initialization.md
├── LT-Project-Dashboard.md
├── CSIT-Test-Results.md
└── (Auto-generated session notes)
```

### Available Tools
- `obsidian_list_notes` - List vault contents
- `obsidian_read_note` - Read note content
- `obsidian_update_note` - Create/update notes
- `obsidian_global_search` - Search vault
- `obsidian_manage_frontmatter` - YAML metadata
- `obsidian_manage_tags` - Tag management

---

## 🔍 Testing & Debugging

### Run Tests
```bash
python -m pytest tests/
```

### Environment Check
See `environment-test.md` for CSIT results.

### Debug Tools
- LogWatcher with verbose logging
- SQLite query inspector
- Obsidian REST API (port 27123)

---

## 🚨 Important Reminders

1. **Never modify** files in official `Entropia Universe` game folder
2. **Never commit** `config.json` if it contains `Invoice ID`
3. **Always ask** before installing heavy dependencies (ML libs)
4. **Use Decimal** for all PED/PEC calculations
5. **Maintain 60+ FPS** - profile code for performance

---

## 📚 Reference Files

| File | Purpose |
|------|---------|
| `AGENTS.md` | AI directives and coding standards |
| `GAME_MECHANICS.md` | Entropia game mechanics reference |
| `TECHNICAL_SPECS.md` | Technical architecture |
| `MODULE_REQUIREMENTS.md` | Feature specifications |
| `TESTING_AND_DEBUGGING.md` | Testing protocols |
| `OBSIDIAN_WORKFLOW.md` | Documentation workflow |
| `environment-test.md` | CSIT results |

---

*Generated by Lemontropia Suite Development Agent*  
*For updates, modify this file or regenerate via agent instructions*