megabuff 0.7.0 → 0.9.2

package/README.md

@@ -1,76 +1,107 @@
-# MegaBuff
+<h1 align="center">
+🤖 MegaBuff
+</h1>
+<div align="center">
 
-AI-powered prompt optimizer CLI with multi-provider support (OpenAI, Anthropic & Google Gemini). Improve your prompts with BYOK (Bring Your Own Key) and flexible input/output options.
+**Transform your AI prompts from good to great!** ✨
 
-## Installation
+AI-powered prompt optimizer with multi-provider support (OpenAI, Anthropic, Gemini, DeepSeek, xAI & more)
 
-Install MegaBuff globally:
+🔑 BYOK (Bring Your Own Key) • 🎨 16 Beautiful Themes • ⚡ Lightning Fast
+
+[![npm version](https://img.shields.io/npm/v/megabuff.svg?style=flat-square)](https://www.npmjs.com/package/megabuff)
+[![npm downloads](https://img.shields.io/npm/dm/megabuff.svg?style=flat-square)](https://www.npmjs.com/package/megabuff)
+[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL%203.0-blue.svg?style=flat-square)](https://opensource.org/licenses/AGPL-3.0)
+[![GitHub stars](https://img.shields.io/github/stars/thesupermegabuff/megabuff-cli.svg?style=flat-square)](https://github.com/thesupermegabuff/megabuff-cli/stargazers)
+[![GitHub issues](https://img.shields.io/github/issues/thesupermegabuff/megabuff-cli.svg?style=flat-square)](https://github.com/thesupermegabuff/megabuff-cli/issues)
+[![Node.js Version](https://img.shields.io/node/v/megabuff.svg?style=flat-square)](https://nodejs.org)
+
+<img width="690" src="media/github-media-banner.png" alt="MegaBuff Banner" width="100%">
+
+<br/>
+<br/>
+</div>
+
+---
+
+## 📦 Installation
+
+Get started in seconds:
 
 ```bash
 npm install -g megabuff
 megabuff optimize "Rewrite this prompt to be clearer"
 ```
 
-## Table of Contents
-
-- [Installation](#installation)
-- [Setup](#setup)
-  - [Getting Your OpenAI API Key (BYOK)](#getting-your-openai-api-key-byok)
-  - [Getting Your Anthropic API Key (BYOK)](#getting-your-anthropic-api-key-byok)
-  - [Configuring Your API Key](#configuring-your-api-key)
-    - [Option 1: Save to Config (Recommended)](#option-1-save-to-config-recommended)
-    - [Option 2: Environment Variable](#option-2-environment-variable)
-    - [Option 3: Pass as Flag](#option-3-pass-as-flag)
-  - [API Key Priority](#api-key-priority)
-- [Configuration Commands](#configuration-commands)
-- [Feature requests or contributing](#feature-requests--contributing)
-- [Development](#development)
-- [Build](#build)
-- [Install Globally](#install-globally)
-- [Usage](#usage)
-  - [1. Inline Argument (Quick & Simple)](#1-inline-argument-quick--simple)
-  - [2. File Input](#2-file-input)
-  - [3. Stdin Pipe](#3-stdin-pipe)
-  - [4. Interactive Mode](#4-interactive-mode)
-- [Output Options](#output-options)
-  - [Default: Print to stdout AND copy to clipboard](#default-print-to-stdout-and-copy-to-clipboard)
-  - [Disable clipboard copy](#disable-clipboard-copy)
-  - [Save to file](#save-to-file)
-  - [Interactive comparison view](#interactive-comparison-view)
-  - [Combine options](#combine-options)
-- [Examples](#examples)
-- [How It Works](#how-it-works)
-- [VS Code Integration: WIP](#vs-code-integration)
-  - [Option 1: VS Code Extension (Full Experience)](#option-1-vs-code-extension-full-experience)
-  - [Option 2: VS Code Tasks (Quick Setup)](#option-2-vs-code-tasks-quick-setup)
-  - [Option 3: Terminal Integration](#option-3-terminal-integration)
-- [Publishing to npm](#publishing-to-npm)
-  - [First-time Setup](#first-time-setup)
-  - [Publishing Steps](#publishing-steps)
-  - [Publishing Updates](#publishing-updates)
-  - [What Gets Published](#what-gets-published)
-  - [After Publishing](#after-publishing)
-
-Local installation:
+**That's it!** 🎉 You're ready to supercharge your prompts.
+
+---
+
+## ✨ Features
+
+- 🤖 **Multi-Provider Support** - OpenAI, Anthropic Claude, Google Gemini, & more
+- 🔑 **BYOK Model** - Bring your own API key, full control
+- 🎨 **16 Beautiful Themes** - Customize your CLI experience
+- ⚡ **Lightning Fast** - Optimize prompts in seconds
+- 📋 **Auto-Clipboard** - Results copied automatically
+- 🔄 **Flexible Input** - Inline, file, pipe, or interactive
+- 💾 **Multiple Output Formats** - Stdout, file, or interactive view
+- 🔒 **Secure Storage** - Keychain support for API keys
+- 🎯 **Smart Model Selection** - Auto-detects provider from model name
+- 📊 **Stats Tracking** - See word count changes and improvements
+- 🌈 **Beautiful Output** - Themed, formatted, fun to use!
+
+---
+
+## 📚 Table of Contents
+
+- [✨ Features](#-features)
+- [📦 Installation](#-installation)
+- [⚡ Quick Start](#-quick-start)
+- [🔐 Setup](#-setup)
+- [⚙️ Configuration Commands](#️-configuration-commands)
+- [🎨 Theme Commands](#-theme-commands)
+- [💡 Usage](#-usage)
+- [🎯 Examples](#-examples)
+- [🔧 How It Works](#-how-it-works)
+- [🆚 VS Code Integration](#-vs-code-integration)
+- [🤝 Contributing](#-contributing)
+- [📄 License](#-license)
+- [👨‍💻 Development](#-development)
+
+---
+
+## ⚡ Quick Start
+
+**New to MegaBuff?** Let's get you optimizing in under 60 seconds! ⏱️
 
 ```bash
-git clone https://github.com/thesupermegabuff/megabuff-cli.git
-cd megabuff-cli
-nvm use 22
-npm install
+# 1. Install globally
+npm install -g megabuff
+
+# 2. Set up your API key (choose your favorite provider)
+megabuff config token YOUR_API_KEY --provider openai
+
+# 3. Start optimizing!
+megabuff optimize "Write a function to validate emails"
 ```
 
-## Setup
+> 💡 **Pro Tip:** Try out different themes with `megabuff theme list`!
+
+---
 
-### Getting Your OpenAI API Key (BYOK)
+## 🔐 Setup
 
-MegaBuff uses a **BYOK (Bring Your Own Key)** model, meaning you use your own OpenAI API key. This gives you:
-- ✅ Direct control over your usage and costs
-- ✅ Pay-per-use pricing (typically pennies per optimization)
-- ✅ Full privacy - your prompts go directly to OpenAI
-- ✅ Ability to set your own usage limits
+### 🤖 Getting Your OpenAI API Key (BYOK)
 
-**Steps to get your OpenAI API Key:**
+MegaBuff uses a **BYOK (Bring Your Own Key)** model. Why is this awesome?
+
+- ✅ **Full Control** - You manage your usage and costs
+- ✅ **Super Cheap** - Typically just pennies per optimization 💰
+- ✅ **Privacy First** - Your prompts go directly to the provider 🔒
+- ✅ **Your Rules** - Set your own usage limits
+
+**Get your key in 4 easy steps:**
 
 1. **Create an OpenAI Account**
    - Sign up or log in at [platform.openai.com](https://platform.openai.com/)
@@ -93,11 +124,9 @@ MegaBuff uses a **BYOK (Bring Your Own Key)** model, meaning you use your own Op
    - Store it securely - you'll need to generate a new one if you lose it
    - The key starts with `sk-`
 
-### Getting Your Anthropic API Key (BYOK)
+### 🧠 Getting Your Anthropic API Key (BYOK)
 
-MegaBuff can also use **Anthropic (Claude)** if you provide your own Anthropic API key.
-
-**Steps to get your Anthropic API Key:**
+Want to use **Claude**? Follow these simple steps:
 
 1. **Create an Anthropic Console account**
    - Sign up / log in at `https://console.anthropic.com/`
@@ -114,11 +143,9 @@ MegaBuff can also use **Anthropic (Claude)** if you provide your own Anthropic A
    - Copy and store it somewhere secure
    - Anthropic keys typically start with `sk-ant-`
 
-### Getting Your Google Gemini API Key (BYOK)
-
-MegaBuff also supports **Google Gemini** with your own API key.
+### ✨ Getting Your Google Gemini API Key (BYOK)
 
-**Steps to get your Google Gemini API Key:**
+Ready to try **Gemini**? Here's how:
 
 1. **Go to Google AI Studio**
    - Visit [Google AI Studio](https://aistudio.google.com/app/apikey)
@@ -171,6 +198,8 @@ This saves your key for future use. You only need to do this once!
 export OPENAI_API_KEY="sk-your-api-key-here"
 export ANTHROPIC_API_KEY="sk-ant-your-api-key-here"
 export GOOGLE_API_KEY="your-google-api-key-here"
+export XAI_API_KEY="xai-your-api-key-here"
+export DEEPSEEK_API_KEY="sk-your-deepseek-key-here"
 ```
 
 Add to your shell profile (`.bashrc`, `.zshrc`, etc.) to persist across sessions.
@@ -187,15 +216,17 @@ megabuff optimize --provider google "your prompt" --api-key your-google-key-here
 
 The CLI checks for your token in this order (per provider):
 1. `--api-key` flag (highest priority)
-2. Provider env var (e.g. `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`)
+2. Provider env var (e.g. `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `XAI_API_KEY`, `DEEPSEEK_API_KEY`)
 3. System keychain (if configured)
 4. Config file at `~/.megabuff/config.json`
 
-## Configuration Commands
+---
 
-### Interactive Config Menu
+## ⚙️ Configuration Commands
 
-Run `megabuff config` for an interactive configuration menu:
+### 🎮 Interactive Config Menu
+
+The easiest way to configure everything:
 
 ```bash
 megabuff config
@@ -214,31 +245,38 @@ megabuff config
 #   5) Exit
 ```
 
-### Direct Commands
+### 🔧 Direct Commands
 
+**Token Management:**
 ```bash
-# Set API token for a provider
-megabuff config token sk-your-api-key-here --provider openai
-megabuff config token sk-ant-... --provider anthropic --keychain
+# 🔑 Set your API token
+megabuff config token sk-your-api-key --provider openai
+megabuff config token sk-ant-... --provider anthropic --keychain  # More secure!
 
-# Set default provider
+# 🗑️ Remove a token
+megabuff config remove --provider anthropic
+```
+
+**Provider & Model Selection:**
+```bash
+# 🤖 Set default provider
 megabuff config provider anthropic
-megabuff config provider  # show current provider
+megabuff config provider                  # Show current
 
-# Set model (automatically sets provider)
-megabuff config model claude-sonnet-4-5  # sets provider to anthropic
-megabuff config model gpt-4o             # sets provider to openai
-megabuff config model gemini-1.5-pro     # sets provider to google
-megabuff config model                     # show current model
+# 🎯 Set model (auto-selects provider!)
+megabuff config model claude-sonnet-4-5   # → Anthropic
+megabuff config model gpt-4o              # → OpenAI
+megabuff config model gemini-1.5-pro      # → Google
+megabuff config model                     # Show current
+```
 
-# Show all configuration
+**View Everything:**
+```bash
+# 📊 Show complete configuration
 megabuff config show
-
-# Remove a saved token
-megabuff config remove --provider anthropic
 ```
 
-### Available Models
+### 🤖 Available Models
 
 **OpenAI:**
 - `gpt-4o`
@@ -262,186 +300,196 @@ megabuff config remove --provider anthropic
 - `gemini-1.5-flash` (default for Google)
 - `gemini-1.0-pro`
 
-## Development
+---
 
-Test your CLI during development:
+## 🎨 Theme Commands
 
-```bash
-npm install
+**Make your CLI experience uniquely yours!** Choose from 16 stunning color themes. ✨
 
-# Using the dev script (recommended)
-npm run dev optimize "Write a function to sort arrays"
+### 👀 View Current Theme
 
-# Or using npx tsx directly
-npx tsx src/index.ts optimize "Your prompt here"
-
-# Or install locally as a global command
-npm link
-megabuff optimize "Your prompt here"
+```bash
+megabuff theme
 ```
 
-## Build
+Shows your active theme with a beautiful preview! 🌈
 
-Compile TypeScript to JavaScript:
+### 📋 List All Themes
 
 ```bash
-npm run build
+megabuff theme list
 ```
 
-This will create compiled files in the `dist/` folder.
+Browse all 16 themes with:
+- ⭐ Your active theme highlighted
+- Live color previews
+- Theme descriptions
 
-## Install Globally
-
-Install the CLI globally on your machine for testing:
+### 🎭 Change Theme
 
 ```bash
-npm link
+megabuff theme set dracula         # 🧛‍♂️ Dark & mysterious
+megabuff theme set cyberpunk       # 🌆 Neon future vibes
+megabuff theme set pastel-rainbow  # 🌈 Soft & dreamy
 ```
 
-## Usage
+Your choice is saved and applied to all commands instantly!
 
-The CLI supports multiple input methods:
+### 🔍 Preview Theme
 
-### 1. Inline Argument (Quick & Simple)
+Try before you apply:
 
 ```bash
-megabuff optimize "Write a function that validates email addresses"
+megabuff theme preview monokai
 ```
 
-### 2. File Input
-
-```bash
-megabuff optimize --file prompt.txt
-```
+See the full color palette in action before committing! 🎨
 
-### 3. Stdin Pipe
+### 🌟 Available Themes
 
-```bash
-echo "Explain quantum computing" | megabuff optimize
-cat prompt.txt | megabuff optimize
-```
+| Theme | Vibe | Description |
+|-------|------|-------------|
+| 🎯 **default** | Clean & Pro | Cyan and green palette |
+| 🎨 **material** | Modern | Google Material Design |
+| 🧛‍♂️ **dracula** | Dark & Gothic | Purple and pink accents |
+| ❄️ **nord** | Arctic | Cool bluish tones |
+| ☀️ **solarized** | Precision | Perfect balance |
+| 🎸 **monokai** | Vibrant | Monokai Pro inspired |
+| 🌆 **cyberpunk** | Futuristic | Neon city lights |
+| 🌅 **sunset** | Warm | Oranges & purples |
+| 🌈 **pastel-rainbow** | Dreamy | Soft rainbow hues |
+| 🍬 **bubblegum** | Sweet | All the pink vibes |
+| 🍭 **cotton-candy** | Fluffy | Pink meets blue |
+| 🦄 **unicorn** | Magical | Pastel paradise |
+| 🌊 **ocean** | Aquatic | Deep blue serenity |
+| 🌲 **forest** | Natural | Earthy greens |
+| 📺 **retro** | Nostalgic | 80s terminal style |
+| ⚡ **neon-dreams** | Electric | Vibrant neons |
 
-### 4. Interactive Mode
+**Every theme is optimized for readability and style!** 🎨✨
 
-```bash
-megabuff optimize
-# Then paste/type your prompt and press Ctrl+D when done
-```
+---
 
-## Output Options
+## 💡 Usage
 
-### Default: Print to stdout AND copy to clipboard
+**MegaBuff is flexible!** Use whichever input method works best for you:
 
-By default, the optimized prompt is:
-1. Printed to stdout (so you can pipe it)
-2. Automatically copied to your clipboard (works on macOS, Windows, and Linux)
+### 1️⃣ Inline (Fastest!)
 
 ```bash
-megabuff optimize "your prompt"
-# Result is both printed AND copied to clipboard
+megabuff optimize "Write a function that validates emails"
 ```
 
-### Disable clipboard copy
-
-If you don't want automatic clipboard copy:
+### 2️⃣ From a File
 
 ```bash
-megabuff optimize "your prompt" --no-copy
+megabuff optimize --file my-prompt.txt
 ```
 
-### Save to file
+### 3️⃣ Pipe It In
 
 ```bash
-megabuff optimize "your prompt" --output result.txt
-# Still copies to clipboard by default
+echo "Explain quantum computing" | megabuff optimize
+cat prompt.txt | megabuff optimize
 ```
 
-### Interactive comparison view
+### 4️⃣ Interactive Mode
 
 ```bash
-megabuff optimize "your prompt" --interactive
-# Shows before/after comparison AND copies to clipboard
+megabuff optimize
+# Type/paste your prompt, then Ctrl+D ✨
 ```
 
-### Combine options
+### 📤 Output Options
+
+**By default, MegaBuff does BOTH:**
+- ✅ Prints to stdout (for piping)
+- ✅ Copies to clipboard (instant paste!)
+
+**Customize the output:**
 
 ```bash
-# Save to file without clipboard
-megabuff optimize "your prompt" --output result.txt --no-copy
+# Don't copy to clipboard
+megabuff optimize "prompt" --no-copy
 
-# Interactive view without clipboard
-megabuff optimize "your prompt" --interactive --no-copy
+# Save to file (still copies by default)
+megabuff optimize "prompt" --output result.txt
 
-# Pipe to another command (clipboard still works)
-megabuff optimize "your prompt" | grep "specific"
+# Interactive before/after view
+megabuff optimize "prompt" --interactive
+
+# Save without clipboard
+megabuff optimize "prompt" -o result.txt --no-copy
 ```
 
-## Examples
+---
+
+## 🎯 Examples
+
+**Real-world use cases to get you started:**
 
 ```bash
-# Quick inline optimization with OpenAI (auto-copies to clipboard)
+# 🚀 Quick optimization
 megabuff optimize "Write code for user auth"
 
-# Use Anthropic (Claude) instead
-megabuff optimize --provider anthropic "Write code for user auth"
+# 🧠 Use Claude for better reasoning
+megabuff optimize --provider anthropic "Explain recursion"
 
-# Use Google Gemini
-megabuff optimize --provider google "Write code for user auth"
+# ✨ Try Gemini
+megabuff optimize --provider google "Design a database schema"
 
-# From file with interactive view (auto-copies)
-megabuff optimize --file my-prompt.txt --interactive
+# 📁 From a file with before/after comparison
+megabuff optimize --file prompt.txt --interactive
 
-# Pipe and save (auto-copies)
+# 🔄 Pipe and save
 cat input.txt | megabuff optimize --output optimized.txt
 
-# Disable clipboard copy
-megabuff optimize "Your prompt" --no-copy
+# 🎯 Use a specific model
+megabuff config model claude-sonnet-4-5
+megabuff optimize "Explain quantum computing"
 
-# Save to file without clipboard
-megabuff optimize --file prompt.txt --output result.txt --no-copy
+# 🎨 Make it pretty!
+megabuff theme set cyberpunk           # Set theme
+megabuff theme preview dracula         # Preview first
+megabuff theme list                    # See all options
 
-# Use specific API key (overrides config)
-megabuff optimize "Your prompt" --api-key sk-your-key-here
+# 🔧 Power user combos
+megabuff optimize --file long-prompt.txt --provider anthropic -o result.txt --interactive
+```
 
-# Set default provider to Anthropic, then optimize
-megabuff config provider anthropic
-megabuff optimize "Rewrite this prompt to be clearer"
+---
 
-# Set a specific model (auto-sets provider)
-megabuff config model claude-sonnet-4-5
-megabuff optimize "Explain quantum computing"
+## 🔧 How It Works
 
-# Or use Gemini model
-megabuff config model gemini-1.5-pro
-megabuff optimize "Explain quantum computing"
-```
+**The Magic Behind MegaBuff** ✨
 
-## How It Works
+MegaBuff uses state-of-the-art AI to transform your prompts:
 
-MegaBuff supports multiple AI providers to optimize your prompts:
+### 🎯 What Gets Optimized?
 
-**Providers:**
-- **OpenAI** (default): Uses GPT-4o-mini for fast, cost-effective optimization
-- **Anthropic**: Uses Claude Sonnet 4.5 for advanced reasoning and optimization
-- **Google Gemini**: Uses Gemini 1.5 Flash for efficient, high-quality optimization
+1. **Clarity** - Removes ambiguity and vague instructions
+2. **Context** - Adds missing details that improve results
+3. **Structure** - Organizes information logically
+4. **Format** - Specifies expected output clearly
+5. **Specificity** - Makes requests actionable and precise
 
-The optimization process:
-1. Identifies ambiguities or unclear instructions
-2. Adds relevant context that would improve results
-3. Structures the prompt for clarity
-4. Specifies expected output format if not present
-5. Makes the prompt more specific and actionable
+### 🤖 Choose Your AI
 
-**Model Selection:**
-- Set a specific model with `megabuff config model <model-name>`
-- Provider is automatically selected based on the model
-- Or explicitly choose provider with `--provider` flag
+| Provider | Best For | Default Model |
+|----------|----------|---------------|
+| 🤖 **OpenAI** | Fast & economical | GPT-4o-mini |
+| 🧠 **Anthropic** | Deep reasoning | Claude Sonnet 4.5 |
+| ✨ **Google** | Efficient & quality | Gemini 1.5 Flash |
 
-## VS Code Integration
+**Switch providers anytime** with `--provider` or set your favorite as default!
 
-MegaBuff integrates seamlessly with VS Code in multiple ways:
+---
 
-### Option 1: VS Code Extension (Full Experience)
+## 🆚 VS Code Integration
+
+**Use MegaBuff right inside VS Code!** 🎉
+
+### ⭐ Option 1: VS Code Extension (Full Experience)
 
 Install and develop the MegaBuff VS Code extension:
 
@@ -463,131 +511,174 @@ Then press `F5` to launch the extension in debug mode.
 
 See [megabuff-vscode/README.md](../megabuff-vscode/README.md) for more details.
 
-### Option 2: VS Code Tasks (Quick Setup)
+### 🚀 Option 2: VS Code Tasks (Quick Setup)
 
-Use the pre-configured tasks in `.vscode/tasks.json`:
+Pre-configured tasks for instant productivity:
 
-1. Select text in VS Code
-2. Press `Ctrl+Shift+P` → "Tasks: Run Task"
-3. Choose "MegaBuff: Optimize Selected Text"
+1. Select text
+2. `Ctrl+Shift+P` → "Tasks: Run Task"
+3. Pick a MegaBuff task
 
-Available tasks:
-- `MegaBuff: Optimize Selected Text`
-- `MegaBuff: Optimize Current File`
-- `MegaBuff: Optimize Selected (Interactive)`
-- `MegaBuff: Configure API Key`
+**Available Tasks:**
+- ✨ Optimize Selected Text
+- 📄 Optimize Current File
+- 🔍 Optimize (Interactive View)
+- ⚙️ Configure API Key
 
-### Option 3: Terminal Integration
+### 💻 Option 3: Terminal Integration
 
-Simply use the CLI in VS Code's integrated terminal:
+Just use the integrated terminal:
 
 ```bash
-# Select text, then in terminal:
 pbpaste | megabuff optimize  # macOS
 xclip -o | megabuff optimize  # Linux
 ```
 
-## Feature requests or contributing
+---
 
-Want a feature or want to contribute one? Please open an issue here:
+## 🤝 Contributing
 
-- [GitHub Issues](https://github.com/thesupermegabuff/megabuff-cli/issues)
+**We'd love your help making MegaBuff better!**
 
-## Publishing to npm
+Found a bug? Have an idea? Open an issue:
 
-### First-time Setup
+👉 [GitHub Issues](https://github.com/thesupermegabuff/megabuff-cli/issues)
 
-1. **Create an npm account** at [npmjs.com/signup](https://www.npmjs.com/signup) if you don't have one
+---
 
-2. **Login to npm** from your terminal:
-   ```bash
-   npm login
-   ```
+## 📄 License
 
-3. **Update package.json** with your information:
-   - Change `author` to your name and email
-   - Update `repository` URL with your GitHub username
-   - Update `bugs` and `homepage` URLs
+**MegaBuff is open source!** Licensed under **AGPL-3.0**
 
-4. **Check if the package name is available**:
-   ```bash
-   npm search megabuff
-   ```
-   The name `megabuff` should be available (or use an alternative if taken)
+**What this means:**
+- ✅ **Free to use** - For any purpose
+- ✅ **Free to modify** - Make it your own
+- ✅ **Free to share** - Spread the love
+- 🔓 **Open source required** - Derivative works must stay open
+- 🌐 **Service transparency** - If you run it as a service, share the code
 
-### Publishing Steps
+[Read the full license](LICENSE)
 
-1. **Make sure everything is committed**:
-   ```bash
-   git status
-   git add .
-   git commit -m "Prepare for publish"
-   ```
+---
 
-2. **Build the project**:
-   ```bash
-   npm version minor 
-   npm run build
-   ```
-   This compiles TypeScript to JavaScript in the `dist/` folder
+## 👨‍💻 Development
 
-3. **Test the package locally** (optional but recommended):
-   ```bash
-   npm pack
-   # This creates a .tgz file you can inspect
-   ```
+**Want to contribute or build from source?**
 
-4. **Publish to npm**:
-   ```bash
-   npm publish
-   ```
+### 🔧 Local Development
 
-   The `prepublishOnly` script will automatically run `npm run build` before publishing.
+```bash
+# Clone the repo
+git clone https://github.com/thesupermegabuff/megabuff-cli.git
+cd megabuff-cli
 
-### Publishing Updates
+# Install dependencies
+npm install
 
-When you make changes and want to publish a new version:
+# Run in dev mode
+npm run dev optimize "Your prompt"
 
-1. **Update the version** using semantic versioning:
-   ```bash
-   # For bug fixes (0.1.0 -> 0.1.1)
-   npm version patch
+# Or use tsx directly
+npx tsx src/index.ts optimize "Your prompt"
+```
 
-   # For new features (0.1.0 -> 0.2.0)
-   npm version minor
+### 📦 Build & Publish
+
+**Building the project:**
+
+```bash
+npm run build  # Compiles TypeScript to dist/
+```
 
-   # For breaking changes (0.1.0 -> 1.0.0)
-   npm version major
-   ```
+**Version and build:**
 
-2. **Publish the update**:
-   ```bash
-   npm publish
-   ```
+```bash
+npm version minor  # Bump version (patch/minor/major)
+npm run build      # Compile TypeScript
+```
 
-3. **Push the version tag to GitHub**:
-   ```bash
-   git push && git push --tags
-   ```
+This compiles TypeScript to JavaScript in the `dist/` folder.
 
-### What Gets Published
+**Test the package locally** (optional but recommended):
 
-The npm package includes:
-- ✅ `dist/` - Compiled JavaScript
-- ✅ `README.md` - Documentation
-- ✅ `package.json` - Package metadata
-- ✅ `LICENSE` - License file
-- ❌ `src/` - TypeScript source (excluded)
-- ❌ `node_modules/` - Dependencies (excluded)
-- ❌ Development files (excluded via .npmignore)
+```bash
+npm pack
+# This creates a .tgz file you can inspect
+```
 
-### After Publishing
+**Test locally with npm link:**
 
-Users can install your CLI globally with:
+```bash
+npm link  # Install as global command
+megabuff optimize "Test it out!"
+```
+
+**Publish to npm:**
+
+```bash
+npm publish
+```
+
+The `prepublishOnly` script will automatically run `npm run build` before publishing.
+
+---
+
+## 📚 Publishing to npm
+
+<details>
+<summary><b>📦 Publishing Guide (For Maintainers)</b></summary>
+
+### 🎯 First-time Setup
+
+1. Create an [npm account](https://www.npmjs.com/signup)
+2. Login: `npm login`
+3. Update `package.json` with your details
+4. Check name availability: `npm search megabuff`
+
+### 🚀 Publishing Process
+
+```bash
+# 1. Commit changes
+git add .
+git commit -m "Release preparation"
+
+# 2. Bump version (patch/minor/major)
+npm version minor
+
+# 3. Publish!
+npm publish
+
+# 4. Push tags
+git push && git push --tags
+```
+
+### 📦 What Gets Published
+
+- ✅ Compiled JavaScript (`dist/`)
+- ✅ Documentation
+- ✅ Package metadata
+- ❌ TypeScript source
+- ❌ Dev dependencies
+
+### 🎉 After Publishing
+
+Users install with:
 ```bash
 npm install -g megabuff
 ```
 
-Your package will be available at:
-- npm: `https://www.npmjs.com/package/megabuff`
-- Docs: `https://github.com/thesupermegabuff/megabuff-cli`
+Available at: [npmjs.com/package/megabuff](https://www.npmjs.com/package/megabuff)
+
+</details>
+
+---
+
+<div align="center">
+
+**Made with ❤️ by the MegaBuff Team**
+
+⭐ **Star us on [GitHub](https://github.com/thesupermegabuff/megabuff-cli)!**
+
+🐛 [Report Issues](https://github.com/thesupermegabuff/megabuff-cli/issues) • 💡 [Request Features](https://github.com/thesupermegabuff/megabuff-cli/issues)
+
+</div>