Merge pull request #3 from 1broseidon/claude/readme-github-tags-011CUqTezBNHUHHZonyPyfPM

Improve README and GitHub tags for discoverability

Author: 1broseidon

README.md

@@ -1,6 +1,6 @@
 # promptext
 
-Converts codebases to token-efficient formats for AI context windows.
+Convert your codebase into AI-ready prompts - a fast, token-efficient alternative to code2prompt for Claude, ChatGPT, and other LLMs.
 
 [![Go Report Card](https://goreportcard.com/badge/github.com/1broseidon/promptext?prx=v0.4.5)](https://goreportcard.com/report/github.com/1broseidon/promptext)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -15,14 +15,26 @@ AI assistants need code context. Sending entire repositories exceeds token limit
 
 promptext filters files, ranks by relevance, and serializes to token-efficient formats within specified budgets.
 
+## Why promptext?
+
+Unlike other tools like code2prompt, codebase-digest, or manual copy-pasting:
+- **Faster**: Written in Go, processes large codebases in seconds
+- **Smarter**: Relevance scoring automatically finds the most important files
+- **Token-aware**: Built-in tiktoken counting prevents LLM context overflow
+- **Format-flexible**: PTX, TOON, Markdown, or XML output for any AI assistant
+- **Budget-conscious**: Enforce token limits before sending to expensive API calls
+
 ## Features
 
-- **PTX format**: 25-30% token reduction vs JSON (TOON v1.3-based hybrid with multiline code blocks)
+- **PTX format**: promptext's hybrid TOON format - 25-30% token reduction with explicit paths and multiline code blocks
 - **Token budgeting**: Hard limits with relevance-based file selection
 - **Relevance scoring**: Keyword matching in paths (10×), directories (5×), imports (3×), content (1×)
 - **Standard exclusions**: `.gitignore` patterns, `node_modules/`, lock files, binaries
 - **Accurate counting**: tiktoken cl100k_base tokenizer (GPT-3.5/4, Claude compatible)
 - **Format options**: PTX (default), TOON-strict, Markdown, XML
+- **LLM-optimized**: Works with ChatGPT, Claude, GPT-4, Gemini, and any AI assistant
+- **Context window aware**: Respect token limits for Claude Haiku/Sonnet/Opus, GPT-3.5/4
+- **AI-friendly formatting**: Structured output for better AI code comprehension
 
 Format reference: [johannschopplich/toon](https://github.com/johannschopplich/toon)
 
@@ -59,84 +71,65 @@ prx --update
 
 promptext automatically checks for new releases once per day and notifies you when updates are available. Network failures are silently ignored to avoid disrupting normal operation.
 
-## Basic Usage
+## Use Cases
 
-```bash
-# Current directory to clipboard (PTX format)
-prx
+- **AI Code Review**: Feed entire projects to Claude/ChatGPT for comprehensive code analysis
+- **Context Engineering**: Build optimized prompts within LLM token limits for better AI responses
+- **AI Pair Programming**: Provide full codebase context to AI assistants like GitHub Copilot, Cursor, or Windsurf
+- **Documentation Generation**: Help AI understand your complete project structure for accurate docs
+- **Code Migration**: Give LLMs full legacy codebase context for refactoring suggestions
+- **Prompt Engineering**: Create consistent, repeatable AI prompts from code for development workflows
+- **Bug Investigation**: Let AI analyze related files together with proper context
+- **API Integration**: Generate structured code context for AI-powered development tools
 
-# Specific directory
-prx /path/to/project
+## Usage
 
-# Filter by extensions
-prx -e .go,.js,.ts
-
-# Summary only (file list, token counts)
-prx -i
+### Smart Context Building (The Power Features)
 
-# Output to file (format auto-detected from extension)
-prx -o context.ptx      # PTX format
-prx -o context.toon     # PTX format (backward compatibility)
-prx -o context.md       # Markdown
-prx -o project.xml      # XML
-
-# Explicit format specification
-prx -f ptx -o context.txt        # PTX: readable code blocks
-prx -f toon-strict -o small.txt  # TOON v1.3: maximum compression
-prx -f markdown -o context.md    # Standard Markdown
-prx -f xml -o project.xml        # XML structure
+```bash
+# Find authentication-related files within token budget
+prx -r "auth login OAuth session" --max-tokens 10000
 
-# Exclude patterns (comma-separated)
-prx -x "test/,vendor/" --verbose
+# Get database layer for Claude Haiku (8K limit)
+prx -r "database SQL postgres migration" --max-tokens 8000 -o db-context.ptx
 
-# Preview file selection without processing
-prx --dry-run -e .go
+# API routes for GPT-4 analysis
+prx -r "api routes handlers middleware" --max-tokens 15000
 
-# Suppress output (useful in scripts)
-prx -q -o output.ptx
+# Bug investigation: error handling code only
+prx -r "error exception handler logging" --max-tokens 5000 -e .go,.js
 ```
 
-## Advanced Usage
-
-### Relevance Filtering
+**How relevance scoring works:**
+- Filename match: 10 points
+- Directory path match: 5 points
+- Import statement match: 3 points
+- Content match: 1 point
 
-Rank files by keyword frequency:
+### Quick Commands
 
 ```bash
-# Authentication-related files
-prx --relevant "auth login OAuth session"
-
-# Database layer
-prx -r "database SQL postgres migration"
-
-# API endpoints
-prx -r "api routes handlers middleware"
-```
-
-**Scoring algorithm:**
-- Filename match: 10 points per occurrence
-- Directory path match: 5 points per occurrence
-- Import statement match: 3 points per occurrence
-- Content match: 1 point per occurrence
-
-Files ranked by total score. Ties broken by file size (smaller first).
-
-### Token Budget Control
+# Current directory to clipboard
+prx
 
-Enforce context window limits:
+# Specific directory with extension filter
+prx /path/to/project -e .go,.js,.ts
 
-```bash
-# Claude 3 Haiku limit
-prx --max-tokens 8000
+# Output to file (format auto-detected)
+prx -o context.ptx      # PTX (default)
+prx -o context.md       # Markdown
+prx -o project.xml      # XML
 
-# Combined relevance + budget
-prx -r "api routes handlers" --max-tokens 5000
+# Summary only (file list, token counts)
+prx -i
 
-# Cost optimization for iterative queries
-prx --max-tokens 3000 -o quick-context.ptx
+# Preview file selection
+prx --dry-run -r "auth"
 ```
 
-When budget exceeded, output shows inclusion/exclusion breakdown:
+### Token Budget Output
+
+When `--max-tokens` is set and exceeded, promptext shows exactly what was included and excluded:
 
 ```
 ╭───────────────────────────────────────────────╮
@@ -156,6 +149,8 @@ Files included in priority order until budget exhausted.
 
 ## Output Formats
 
+**About PTX**: PTX is a hybrid TOON format specifically created for promptext. It balances the extreme compression of TOON-strict with human readability by using explicit file paths as keys and preserving multiline code blocks. This gives you ~25-30% token savings without sacrificing clarity - perfect for AI assistants that need both efficiency and accurate file path context.
+
 | Format | Token Efficiency | File Path Clarity | Code Preservation | Use Case |
 |--------|-----------------|-------------------|-------------------|----------|
 | **PTX** (default) | 25-30% reduction | ✅ Explicit quoted paths | Multiline blocks preserved | Code analysis, debugging |