feat: introduce Telegram Bot for Green Goods

- Added a new Telegram Bot package to facilitate user interactions with Green Goods, allowing users to join gardens, submit work, and approve submissions via Telegram.
- Implemented core functionalities including custodial wallet management, natural language submission, and voice-to-text capabilities using OpenAI Whisper.
- Established a structured architecture with a focus on ease of use and low-bandwidth accessibility, utilizing Telegraf for bot logic and better-sqlite3 for session management.
- Included comprehensive documentation outlining the bot's features, architecture, and setup instructions.

Author: Oba-One

docs/developer/architecture/telegram-bot.md

@@ -0,0 +1,71 @@
+# Telegram Bot
+
+The **Telegram Bot** package (`packages/telegram`) provides a conversational interface for Green Goods, enabling users to join gardens, submit work, and approve submissions directly from Telegram.
+
+## Overview
+
+The bot is designed to be a "Bot-First" alternative to the web client, focusing on ease of use and low-bandwidth accessibility. It leverages AI for natural language understanding and voice processing.
+
+### Key Features
+
+*   **Custodial Wallet Management**: Automatically generates and manages wallets for users (MVP).
+*   **Natural Language Submission**: Users can describe their work in plain text.
+*   **Voice-to-Text**: Supports voice notes for work submission using OpenAI Whisper (via `@xenova/transformers`).
+*   **Operator Approvals**: Operators receive notifications and can approve work with a single command.
+
+## Architecture
+
+The bot is built with **Telegraf** and runs as a standalone Node.js process.
+
+### Tech Stack
+
+*   **Framework**: [Telegraf](https://telegraf.js.org/)
+*   **Database**: `better-sqlite3` (local SQLite for sessions and user data)
+*   **AI/ML**: `@xenova/transformers` (local inference for STT)
+*   **Blockchain**: `viem` (interaction with EAS and Green Goods contracts)
+
+### Data Flow
+
+1.  **User Input**: Text or Voice message received via Telegram Webhook/Polling.
+2.  **Processing**:
+    *   **Voice**: Transcribed to text using Whisper.
+    *   **Text**: Parsed (currently Regex/Logic, planned LLM) to extract work details.
+3.  **Session**: Draft work stored in SQLite session.
+4.  **Confirmation**: User confirms details via Inline Keyboard.
+5.  **Submission**:
+    *   Bot creates a `WorkDraft`.
+    *   Bot signs and submits transaction to EAS using the user's local custodial wallet.
+    *   **Pending State**: If approval is needed, work is stored as "pending" and operator is notified.
+6.  **Approval**: Operator sends `/approve <id>`, bot submits on-chain attestation.
+
+## Directory Structure
+
+```
+packages/telegram/
+├── src/
+│   ├── services/
+│   │   ├── ai.ts       # STT and NLU logic
+│   │   └── storage.ts  # SQLite database wrapper
+│   ├── bot.ts          # Main bot logic and command handlers
+│   └── index.ts        # Entry point
+├── bot.db              # Local database (gitignored)
+└── package.json
+```
+
+## Setup & Configuration
+
+The bot requires a Telegram Bot Token from [@BotFather](https://t.me/BotFather).
+
+### Environment Variables
+
+| Variable | Description |
+| :--- | :--- |
+| `TELEGRAM_BOT_TOKEN` | API Token from BotFather |
+| `DB_PATH` | Path to SQLite DB (default: `bot.db`) |
+
+### Running Locally
+
+```bash
+# From root
+bun run dev:telegram
+```

package.json

@@ -20,15 +20,15 @@
     "setup": "node scripts/setup.js",
     "prepare": "husky",
 
-    "dev": "trap 'bunx pm2 delete all' EXIT; bunx pm2 start ecosystem.config.js && bunx pm2 logs --raw",
-    "dev:stop": "bunx pm2 delete all",
+    "dev": "trap 'npx pm2 delete all' EXIT; npx pm2 start ecosystem.config.js && npx pm2 logs --raw",
+    "dev:stop": "npx pm2 delete all",
     "dev:client": "cd packages/client && bun run dev",
     "dev:admin": "cd packages/admin && bun run dev",
     "dev:indexer": "cd packages/indexer && bun run dev",
     "dev:contracts": "cd packages/contracts && bun run dev",
 
-    "format": "bunx @biomejs/biome format --write .",
-    "format:check": "bunx @biomejs/biome format .",
+    "format": "npx @biomejs/biome format --write .",
+    "format:check": "npx @biomejs/biome format .",
     "lint": "bun oxlint packages/client/src packages/admin/src packages/shared/src packages/indexer/src packages/contracts/script",
     "test": "bun run test:client && bun run test:admin && bun run test:indexer && bun run test:contracts",
 
@@ -75,10 +75,10 @@
   },
   "lint-staged": {
     "*.{js,jsx,ts,tsx,json}": [
-      "bunx @biomejs/biome format --write"
+      "npx @biomejs/biome format --write"
     ],
     "*.sol": [
-      "cd packages/contracts && bun run format"
+      "npx forge fmt"
     ]
   },
   "workspaces": [

packages/telegram/AGENTS.md

@@ -0,0 +1,29 @@
+# Green Goods — Telegram Bot Agent Guide
+
+Context for AI agents working on the `packages/telegram` directory.
+
+## Core Responsibilities
+
+-   **Bot Interface**: Primary interface for users to join gardens, submit work, and approve work via Telegram.
+-   **Custodial Wallet Management**: Manages local wallets for users (MVP).
+-   **AI Integration**: Handles STT (Speech-to-Text) and NLU (Natural Language Understanding) for conversational flows.
+
+## Key Patterns
+
+-   **Telegraf**: Uses `telegraf` framework for bot logic.
+-   **Session Management**: Uses `better-sqlite3` for persistent session state and pending work storage.
+-   **Shared Logic**: Imports business logic (submission, encoding) from `@green-goods/shared`.
+-   **Environment**: Loads environment variables from the root `.env` file.
+
+## Development Rules
+
+1.  **Statelessness**: Avoid in-memory state for critical flows; persist to SQLite.
+2.  **Type Safety**: Use shared types from `@green-goods/shared` where possible.
+3.  **Error Handling**: Gracefully handle AI model failures (fallback to regex/text).
+4.  **Security**: Treat private keys in `bot.db` with extreme caution (MVP only).
+
+## Common Tasks
+
+-   **Adding Commands**: Register new commands in `bot.ts`.
+-   **Updating AI**: Modify `services/ai.ts` for model updates or logic changes.
+-   **Schema Changes**: Update `services/storage.ts` and run migrations (if any) manually for now.

packages/telegram/data/bot.db

@@ -0,0 +1,29 @@
+{
+  "name": "@green-goods/telegram",
+  "version": "0.0.0",
+  "private": true,
+  "main": "src/index.ts",
+  "scripts": {
+    "dev": "bun --watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "lint": "oxlint src"
+  },
+  "dependencies": {
+    "@green-goods/shared": "workspace:*",
+    "@xenova/transformers": "^2.17.1",
+    "dotenv": "^16.4.5",
+    "fluent-ffmpeg": "^2.1.2",
+    "sharp": "^0.34.5",
+    "telegraf": "^4.16.3",
+    "viem": "^2.9.16",
+    "wavefile": "^11.0.0"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "@types/fluent-ffmpeg": "^2.1.24",
+    "@types/node": "^20.12.7",
+    "tsx": "^4.7.2",
+    "typescript": "^5.4.5"
+  }
+}