alvin-bot 4.4.1

package/.env.example

@@ -0,0 +1,43 @@
+# === Telegram (required) ===
+BOT_TOKEN=your-telegram-bot-token
+ALLOWED_USERS=your-telegram-user-id
+
+# === AI Provider (choose one) ===
+# Options: groq | nvidia-llama-3.3-70b | gemini-2.5-flash | gpt-4o | openrouter | claude-sdk | ollama
+# Free providers: groq, nvidia-llama-3.3-70b, gemini-2.5-flash
+# Claude SDK: Premium — full agent with tool use, needs `claude login` (Max subscription)
+PRIMARY_PROVIDER=groq
+
+# Fallback chain (comma-separated, tried in order if primary fails)
+# FALLBACK_PROVIDERS=nvidia-llama-3.3-70b,gemini-2.5-flash
+
+# === API Keys (set the one for your chosen provider) ===
+# Groq — free at console.groq.com (also enables voice transcription)
+GROQ_API_KEY=
+# Google Gemini — free tier at aistudio.google.com
+GOOGLE_API_KEY=
+# NVIDIA NIM — free tier at build.nvidia.com
+NVIDIA_API_KEY=
+# OpenAI — paid, platform.openai.com
+OPENAI_API_KEY=
+# Anthropic API — direct Claude access (Opus, Sonnet, Haiku)
+ANTHROPIC_API_KEY=
+# OpenRouter — openrouter.ai (100+ models)
+OPENROUTER_API_KEY=
+
+# === Agent ===
+WORKING_DIR=~
+MAX_BUDGET_USD=5.0
+
+# === Web UI ===
+WEB_PORT=3100
+# WEB_PASSWORD=your-password
+
+# === Optional Platforms ===
+# WHATSAPP_ENABLED=true
+# DISCORD_TOKEN=your-discord-bot-token
+# SIGNAL_API_URL=http://localhost:8080
+# SIGNAL_NUMBER=+491234567890
+
+# === Custom Chrome (for WhatsApp, if not auto-detected) ===
+# CHROME_PATH=/usr/bin/google-chrome

package/BACKLOG.md

@@ -0,0 +1,223 @@
+# BACKLOG.md — Alvin Bot Entwicklung
+
+> Interne Projektdatei. Wird NICHT ins Git gepusht (.gitignore).
+> Letzte Aktualisierung: 2026-03-03
+
+---
+
+## Legende
+
+| Prio | Bedeutung |
+|------|-----------|
+| P0 | Sicherheitslücke / Kritisch |
+| P1 | Wichtig für Stabilität & Code-Qualität |
+| P2 | Feature / Developer Experience |
+| P3 | Nice-to-Have / Zukunft |
+
+---
+
+## P0 — Security
+
+### [ ] WebSocket Auth fehlt
+- Aktuell kann jeder, der `localhost:3100` erreicht, über WebSocket chatten
+- Lösung: Auth-Token als Query-Param beim WS-Connect (`ws://localhost:3100?token=xxx`)
+- Token aus WEB_PASSWORD ableiten oder Session-Cookie validieren
+
+### [ ] Tool Executor: Unzureichendes Sandboxing
+- `run_shell` Blocklist ist minimal (nur `rm -rf /`, `mkfs`, `dd`)
+- `rm -rf ~/Projects/` würde durchgehen
+- `write_file` kann `.env` und Systemdateien überschreiben
+- `python_execute` führt beliebigen Code ohne Sandbox aus
+- Lösung: Working-Directory-Sandboxing, Blocklist für sensitive Pfade (.env, /etc/, ~/.ssh/)
+
+### [ ] Web UI: Kein HTTPS
+- HTTP-only → Passwörter und Chat im Klartext
+- Lösung: Optionaler HTTPS-Modus mit self-signed Cert, oder Warnung wenn WEB_PASSWORD gesetzt aber kein HTTPS
+
+### [ ] Sudo-Passwort in CLI-Argument (macOS)
+- `security add-generic-password` bekommt das Passwort als CLI-Arg → sichtbar in `ps aux`
+- Lösung: Passwort über stdin pipen statt als Argument
+
+---
+
+## P1 — Code-Qualität & Stabilität
+
+### [ ] commands.ts aufteilen (74KB Monolith!)
+- Aktuell: ALLE Telegram-Commands in einer Datei (~1700 Zeilen)
+- Vorschlag: `src/handlers/commands/` Ordner mit je einer Datei pro Bereich:
+  - `chat.ts` (help, start, new, cancel)
+  - `model.ts` (model, effort, fallback, voice)
+  - `tools.ts` (web, imagine, browse, remind)
+  - `memory.ts` (recall, remember, reindex, export, memory)
+  - `admin.ts` (status, dir, groups, security, users, setup, sudo)
+  - `cron.ts` (cron)
+  - `extensions.ts` (plugins, mcp, tools, webui)
+  - `index.ts` (registriert alle)
+
+### [ ] web/server.ts aufteilen (57KB Monolith!)
+- Aktuell: REST-API, WebSocket, Static-Serving, Auth — alles in einer Datei
+- Vorschlag: Router-Module nach Bereich (api/models.ts, api/memory.ts, api/sessions.ts, etc.)
+
+### [ ] web/public/js/app.js refactoren (3079 Zeilen)
+- Vanilla JS ohne Struktur → schwer wartbar
+- Option A: Alpine.js oder Petite-Vue für reaktive Bindings (minimaler Overhead)
+- Option B: Web Components für Isolation der Sektionen
+- Option C: Zumindest in Module aufteilen (ES Module Imports)
+
+### [ ] Config-Validation mit Zod
+- Aktuell: Kein Validation → `ALLOWED_USERS=""` ergibt `[NaN]`
+- `BOT_TOKEN` fehlt → kryptischer Fehler statt klare Meldung
+- Lösung: `src/config.ts` mit Zod-Schema, Startup-Validation, klare Fehlermeldungen
+
+### [ ] MAX_BUDGET_USD wird nie enforced
+- Variable wird gelesen aber nirgendwo geprüft
+- Lösung: In `queryWithFallback()` vor jedem API-Call prüfen, bei Überschreitung blockieren
+
+### [ ] Tests einführen
+- Aktuell: Null Tests im gesamten Projekt
+- Priorität für Tests:
+  1. Provider-Registry (Fallback-Chain Logik)
+  2. Cron-Parser (Edge Cases bei Zeitberechnung)
+  3. Tool-Executor (Security-Blocklist)
+  4. Config-Validation
+  5. Markdown-Sanitizer
+- Framework: Vitest (schnell, ESM-nativ, kein Babel nötig)
+
+### [ ] Watch-Mode für Development
+- Aktuell: `npm run dev` = `tsx src/index.ts` (einmal starten, manuell restarten)
+- Lösung: `tsx watch src/index.ts` oder `nodemon` mit TS-Loader
+
+---
+
+## P2 — Features & Verbesserungen
+
+### [ ] Session-Persistence (optional)
+- Sessions überleben keinen Restart — Chat-History weg nach `pm2 restart`
+- Option A: SQLite-File für Sessions (leichtgewichtig, kein DB-Server)
+- Option B: JSON-Files pro User in `data/sessions/`
+- Opt-in via `SESSION_PERSIST=true` in .env
+
+### [ ] Session-Timeout / Cleanup
+- Sessions akkumulieren sich unbegrenzt im Speicher
+- Lösung: Inaktive Sessions nach 24h aus dem RAM entfernen (History bleibt in Memory-Logs)
+
+### [ ] Memory-Rotation
+- Daily Logs (`~/.alvin-bot/memory/YYYY-MM-DD.md`) wachsen unbegrenzt
+- Lösung: Nach 30 Tagen alte Logs in `~/.alvin-bot/memory/archive/` verschieben oder komprimieren
+- Optional: Automatische Zusammenfassung alter Logs via AI
+
+### [ ] Embedding-Provider erweitern
+- Aktuell: Nur Google `text-embedding-004`
+- Alternativen: OpenAI Embeddings, lokale Ollama-Embeddings, Cohere
+- Fallback-Chain wie bei Chat-Providern
+
+### [ ] Plugin-Tools für alle Provider
+- Plugin-Tools funktionieren aktuell nur über Telegram-Commands
+- Sie sollten auch als Agent-Tools in `OpenAICompatibleProvider` injiziert werden
+- Damit können alle LLMs Plugin-Funktionen nutzen (nicht nur Claude SDK)
+
+### [ ] MCP HTTP/SSE Transport fertigstellen
+- Aktuell nur stdio-Transport implementiert
+- HTTP/SSE ist stub: `"HTTP/SSE transport not yet supported"`
+- Wichtig für Remote-MCP-Server (z.B. Cloudflare Workers)
+
+### [ ] Discord: Richtige Integration
+- `discord.js` fehlt in package.json (muss manuell installiert werden)
+- Kein Support für Discord Slash-Commands
+- Kein Rate-Limiting
+- Lösung: Als optional peer dependency, Slash-Command Registration
+
+### [ ] WhatsApp Media Cleanup
+- `data/wa-media/` sammelt empfangene Medien-Dateien und löscht sie nie
+- Lösung: Cron-Job oder TTL-basiertes Cleanup (z.B. nach 7 Tagen löschen)
+
+### [ ] Heartbeat-Kosten reduzieren
+- Heartbeat macht echte API-Calls ("Hi") an alle Provider → erzeugt Kosten
+- Lösung: Für Provider mit bekanntem Status-Endpoint nur diesen pingen
+- Für kostenlose Provider (Groq, NVIDIA): OK so lassen
+
+### [ ] Kosten-Tracking verbessern
+- `estimateCost()` schätzt nur Output-Tokens, keine Input-Tokens
+- Preise teilweise veraltet
+- Lösung: Aktuelle Preistabelle pflegen, Input+Output getrennt tracken
+
+### [ ] Cron-Parser erweitern
+- Kein Support für `@daily`, `@hourly`, `@reboot`, `@weekly`
+- Kein `L` (last day of month), kein `W` (nearest weekday)
+- Lösung: Aliases in `parseSchedule()` hinzufügen
+
+---
+
+## P3 — Nice-to-Have / Zukunft
+
+### [ ] Multi-Language über DE/EN hinaus
+- i18n-System unterstützt nur `de | en`
+- Erweiterbar auf FR, ES, TR, RU etc.
+- Web UI hat bereits ~500 Keys → Übersetzung nötig
+
+### [ ] Skill-Matching mit Embeddings
+- Aktuell: Simples `text.includes(trigger)` — sehr unzuverlässig
+- Besser: Embedding-basiertes Similarity-Matching für Skill-Trigger
+- Oder: LLM-basierte Skill-Auswahl ("Welcher Skill passt zu dieser Nachricht?")
+
+### [ ] Plugin Hot-Reload über Web UI
+- Aktuell: Plugin-Änderungen erfordern Bot-Restart
+- Lösung: "Reload Plugin" Button in Web UI → `pluginManager.reload(name)`
+
+### [ ] Conversation-Export als PDF
+- `/export` gibt aktuell Markdown → könnte auch als formatiertes PDF exportieren
+- Tools vorhanden: `pandoc`, `wkhtmltopdf`
+
+### [ ] Streaming für OpenAI-Compatible + Tool-Use
+- Aktuell schließen sich Streaming und Tool-Use gegenseitig aus
+- Lösung: Tool-Calls aus Stream-Chunks akkumulieren (wie OpenAI es unterstützt)
+
+### [ ] Windows .exe Build
+- Braucht Windows-Umgebung oder Cross-Compilation
+- electron-builder unterstützt es, aber nicht von macOS aus testbar
+
+### [ ] Linux .AppImage Build
+- Braucht Linux-Umgebung oder CI (GitHub Actions)
+- Vorschlag: GitHub Actions Workflow für Multi-Platform Builds
+
+### [ ] CI/CD Pipeline (GitHub Actions)
+- Build-Verification auf Push
+- Lint (ESLint) + Type-Check + Tests
+- Auto-Publish zu npm bei Tag
+- Multi-Platform Electron Builds (macOS, Windows, Linux)
+
+### [ ] Rate-Limiting für API-Endpoints
+- Web UI API-Endpoints haben kein Rate-Limiting
+- Lösung: Simpler in-memory Counter pro IP (kein Redis nötig)
+
+### [ ] Electron: asar wieder aktivieren
+- `asar: false` wegen electron-builder 26.x Bug
+- Bei neuerer Version testen ob es gefixt ist → Source-Code wäre dann nicht mehr exposed
+
+### [ ] Provider-Config via Web UI erweitern
+- Neue Provider-Presets (z.B. Anthropic API direkt, DeepSeek, Mistral) über Web UI registrieren
+- Aktuell nur über .env oder Code möglich
+
+---
+
+## Erledigte Items
+
+### [x] i18n English-First (v3.3.0)
+- Alle Telegram-Commands, TUI, Services, Plugins auf Englisch
+- Web UI bleibt bilingual (DE/EN Toggle)
+- TUI nur noch mit explizitem --lang de auf Deutsch
+
+### [x] /webui Telegram-Befehl (v3.3.0)
+- Sendet Web UI URL als Text (kein Inline-Button, da Telegram localhost-URLs blockiert)
+
+### [x] Smart Port Selection (v3.3.0)
+- Web UI findet automatisch freien Port wenn 3100 belegt
+
+### [x] Multi-Platform Support (Phase 7)
+- Telegram, WhatsApp, Discord, Signal
+
+### [x] Universal Tool Use (Phase 8)
+- Alle Provider können Shell, File I/O, Web Fetch, Python ausführen
+
+### [x] Skill System (Phase 9)
+- SKILL.md-basierte Domain-Expertise

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to Alvin Bot are documented here.
+
+## [2.2.0] — 2026-02-24
+
+### 🔐 Security
+- **Group approval system** — New groups must be approved by admin before bot responds
+- `/groups` — Manage all groups with approve/block inline buttons
+- `/security` — Toggle forwarded messages, auto-approve settings
+- Blocked groups completely ignored (zero response)
+- `data/access.json` persists approvals (gitignored)
+
+### 🤖 Multi-Model
+- **Provider abstraction layer** with unified interface
+- **Fallback chain**: Claude SDK → Kimi K2.5 → Llama 3.3 70B (all via NVIDIA NIM)
+- `/model` — Switch models with inline keyboard buttons
+- **Cost tracking per provider** in `/status`
+- **Fallback notifications** — User sees ⚡ when provider switches
+
+### 🧠 Memory
+- **SOUL.md** — Customizable personality file, hot-reloadable via `/reload`
+- **Memory service** — Auto-writes session summaries to daily logs on `/new`
+- Non-SDK providers get memory context injected into system prompt
+- `/memory` — View memory stats
+
+### 🎨 Rich Interactions
+- **Emoji reactions**: 🤔 thinking, 🎧 listening, 👀 looking, 👍 done, 👎 error
+- **Inline keyboards** for `/model`, `/effort`, `/lang`
+- **Document handling** — PDFs, Word, Excel, code files, CSV, JSON (30+ types)
+- **Image generation** — `/imagine` via Gemini API
+- **Reply threading** — Bot responses are replies to the original message
+- **Reply context** — Quoted messages included as context
+- **Forward handling** — Forwarded messages analyzed with sender context
+- **Group chat** — Responds to @mentions and replies only
+
+### 📦 Tools & Commands
+- `/help` — Complete command overview
+- `/web` — DuckDuckGo instant search
+- `/remind` — Set, list, cancel reminders
+- `/export` — Download conversation as markdown
+- `/system` — System info (OS, CPU, RAM, Node)
+- `/lang` — Switch DE/EN with inline buttons
+- `/ping` — Health check with latency
+- `/status` — Enhanced with provider stats, memory, uptime
+
+### 🛠 Infrastructure
+- **Dockerfile** + `docker-compose.yml` for containerized deployment
+- **CLI**: `npx alvin-bot setup` (wizard), `doctor`, `update`, `version`
+- **Markdown sanitizer** — Fixes unbalanced markers for Telegram
+- **Graceful shutdown** with 5s grace period
+- **Error resilience** — Uncaught exceptions logged, not crashed
+- `alvin-bot.config.example.json` for all configurable options
+
+## [2.0.0] — 2026-02-24
+
+### Initial Release
+- grammY + Claude Agent SDK integration
+- Streaming responses with live message editing
+- Voice (Groq Whisper STT + Edge TTS)
+- Photo analysis (Claude vision)
+- Session management (in-memory)
+- PM2 ecosystem config

package/CLAUDE.example.md

@@ -0,0 +1,152 @@
+# CLAUDE.md — Agent Instructions
+
+> Loaded automatically on every `query()` call via `settingSources: ["project"]`.
+> Together with the system prompt, this file forms the agent's core knowledge.
+> Customize this file to shape how your bot thinks and behaves.
+
+## Personality & Behavior
+
+You are an autonomous AI agent. Not just a chatbot — an assistant that thinks ahead and takes action.
+
+**Core Principles:**
+- **Be genuinely helpful.** No "Great question!" or "I'd be happy to help!" — just help.
+- **Have opinions.** You may disagree, prefer things, find stuff interesting or boring.
+- **Be resourceful.** Try to figure it out yourself — read the file, check context, search. Only then ask.
+- **Verify your work.** Don't just do something and assume it worked — actively check.
+- **Earn trust through competence.** Your user gave you access. Don't break things.
+
+**Boundaries:**
+- Private things stay private
+- When in doubt: ask before acting externally (sending emails, deleting files, posting)
+- Don't send half-finished answers
+- `trash` > `rm` (recoverable > gone forever)
+
+## Resource Usage: Check First, Then Act
+
+**CRITICAL — always follow this:**
+
+Before saying "I would need X" or "I don't have access to Y":
+
+1. **Check if it's already there:** `which <tool>`, `command -v <tool>`
+2. **Check the tool list in the system prompt** — it shows what's available
+3. **Use the best available tool directly** — don't ask, just do it
+4. **ONLY if nothing exists:** suggest installation + alternatives
+
+**NEVER say "I can't do X" when a tool for it exists.**
+
+## Complex Tasks — Step by Step
+
+For complex, multi-step tasks:
+
+1. **Make a plan** — What needs to happen? Which tools do I need?
+2. **Identify tools** — What's installed? What might need installation?
+3. **Execute sequentially** — One step at a time, verify each result
+4. **Save intermediate results** — Write to files, don't just keep in memory
+5. **Verify the result** — Does it work? Does it look right?
+
+## Memory System
+
+You wake up fresh every session. These files are your memory.
+
+### Reading
+
+- **New session** (no sessionId / after `/new`):
+  Read `~/.alvin-bot/memory/MEMORY.md` for long-term context
+  Read `~/.alvin-bot/memory/YYYY-MM-DD.md` (today + yesterday) if available
+
+- **Ongoing session:** Context is already in the conversation
+
+### Writing
+
+**`~/.alvin-bot/memory/YYYY-MM-DD.md`** — Daily session logs:
+- After complex tasks: write a summary
+- On important decisions or insights
+- On topic changes: short checkpoint
+- Format: Append (don't overwrite), with timestamp
+
+**`~/.alvin-bot/memory/MEMORY.md`** — Curated long-term memory:
+- "ALWAYS when X, then Y" rules
+- User preferences
+- Project decisions
+- Important workflows
+
+### Checkpoints (Compacting Protection)
+
+Your context window is limited. **Checkpoints protect against data loss.**
+
+**When to write checkpoints (MANDATORY):**
+- After completing a complex task
+- When you see the hint `[CHECKPOINT]` in the prompt
+- Before topic changes
+- When the user makes an important decision
+
+### After Compacting — Restore Context
+
+**If the conversation history seems thin** (user refers to something you can't see):
+1. Read `~/.alvin-bot/memory/YYYY-MM-DD.md` (today + yesterday)
+2. Read `~/.alvin-bot/memory/MEMORY.md`
+3. Only THEN respond
+
+## Cron Jobs — Scheduled Tasks
+
+You have access to a cron system. When the user wants recurring tasks, create a cron job.
+
+```bash
+node scripts/cron-manage.js add \
+  --name "Daily reminder" \
+  --type reminder \
+  --schedule "0 9 * * *" \
+  --prompt "Good morning! Here's your daily briefing." \
+  --chatId YOUR_CHAT_ID
+
+node scripts/cron-manage.js list
+node scripts/cron-manage.js delete --id <job-id>
+node scripts/cron-manage.js toggle --id <job-id>
+```
+
+**Job types:** `reminder` | `shell` | `http` | `message` | `ai-query`
+
+### Schedule Formats
+- **Interval:** `30s`, `5m`, `1h`, `6h`, `1d`
+- **Cron:** `MIN HOUR DAY MONTH WEEKDAY` (0=Sunday)
+
+## API Access for Extended Features
+
+### Image Generation
+If `GOOGLE_API_KEY` is set, you can generate images via Gemini API.
+
+### Text-to-Speech
+```bash
+# Edge TTS (free, no API key needed)
+npx edge-tts --text "Hello World" --voice en-US-GuyNeural --write-media /tmp/output.mp3
+```
+
+### Web Search
+```bash
+# web_search and web_fetch are available as built-in tools
+# Or use: curl + DuckDuckGo / Brave Search / Google
+```
+
+## Project Context
+
+This project is the bot itself. Source code lives in `src/`.
+
+**NEVER modify bot code (src/, package.json, .env, ecosystem.config.cjs) without explicit instruction.**
+
+The working directory (`cwd`) changes based on the `/dir` command — it's not always this project.
+
+## Architecture
+
+- **Runtime:** Node.js >= 18, TypeScript, ESM (`"type": "module"`)
+- **Telegram:** grammy
+- **AI:** Multi-Provider (Claude SDK, Groq, Gemini, GPT-4o, NVIDIA NIM, Ollama, OpenRouter)
+- **Web UI:** Express (auth via `WEB_PASSWORD` env var)
+- **TUI:** `alvin-bot tui` — Terminal chat via WebSocket
+- **Cron:** In-app scheduler (30s loop), jobs in `~/.alvin-bot/cron-jobs.json`
+- **PM2:** Process management, config in `ecosystem.config.cjs`
+
+## Security Rules
+
+- **No personal data in code:** Telegram IDs, paths, tokens → only in `.env`
+- **`.gitignore` protects:** `.env`, `data/` (personal data lives in `~/.alvin-bot/`, outside the repo)
+- **Never commit secrets** — always check `git diff --cached` before committing

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,52 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery and unwelcome sexual attention
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers via [GitHub Issues](https://github.com/alvbln/Alvin-Bot/issues). All complaints
+will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).

package/CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing to Alvin Bot
+
+Thanks for your interest in contributing! Here's how you can help.
+
+## Getting Started
+
+1. **Fork** the repository
+2. **Clone** your fork: `git clone https://github.com/YOUR_USERNAME/alvin-bot.git`
+3. **Install** dependencies: `npm install`
+4. **Create** a branch: `git checkout -b feature/your-feature`
+
+## Development
+
+```bash
+# Build
+npm run build
+
+# Run in development
+npm run dev
+
+# Run tests
+npm test
+```
+
+## Project Structure
+
+- `src/` — Core bot source code
+- `src/handlers/` — Message and command handlers
+- `src/providers/` — AI provider integrations
+- `src/platforms/` — Messaging platform adapters
+- `src/services/` — Background services (cron, memory, etc.)
+- `web/` — Dashboard web interface
+- `electron/` — Desktop app wrapper
+- `plugins/` — Plugin system
+
+## Guidelines
+
+- **TypeScript** — All source files should be TypeScript
+- **Conventional Commits** — Use `feat:`, `fix:`, `docs:`, `chore:` prefixes
+- **No breaking changes** without discussion in an issue first
+- **Tests** — Add tests for new features when applicable
+- **Lint** — Run `npm run lint` before submitting
+
+## Pull Requests
+
+1. Update documentation if you change behavior
+2. Keep PRs focused — one feature/fix per PR
+3. Write a clear description of what changed and why
+4. Reference any related issues
+
+## Reporting Bugs
+
+Open an [issue](https://github.com/alvbln/alvin-bot/issues) with:
+- Steps to reproduce
+- Expected vs actual behavior
+- Node.js version and OS
+- Relevant logs (redact any API keys!)
+
+## Feature Requests
+
+Open an issue with the `enhancement` label describing:
+- The use case
+- Proposed solution
+- Alternatives considered
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md). By participating, you agree to uphold this code.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Alvin-Bot Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.