Improve README and GitHub tags for discoverability

[1broseidon]

Enhance README with strategic keywords to improve search rankings for:

• code2prompt alternatives
• AI/LLM prompt engineering tools
• Codebase-to-context converters

Changes:

• Update tagline to mention code2prompt, Claude, ChatGPT, LLMs
• Add "Why promptext?" comparison section highlighting speed and features
• Add "Use Cases" section with AI-focused keywords (code review, pair programming, context engineering)
• Enhance Features section with LLM-specific capabilities
• Target keywords: AI, prompt engineering, LLM, ChatGPT, Claude, code2prompt, context window, token counting

This positions promptext as a modern, fast alternative in the growing code-to-prompt tool ecosystem.

[claude]

PR Review: Improve README and GitHub Tags for Discoverability

Summary

This PR enhances the README with SEO-focused keywords and structured sections to improve discoverability. Overall, this is a well-executed marketing improvement that maintains technical accuracy while significantly improving search visibility.

✅ Strengths

1. Strategic SEO Improvements

• Excellent keyword targeting (code2prompt, Claude, ChatGPT, LLMs)
• Natural integration of search terms without keyword stuffing
• Comparative positioning ("alternative to code2prompt") is smart for SEO

2. Content Structure

• "Why promptext?" section directly addresses user research questions
• Use Cases section provides concrete, searchable scenarios
• Feature enhancements align with user search intent (AI code review, prompt engineering)

3. Maintains Technical Integrity

• No false claims or exaggerations
• Factual comparisons backed by actual features
• Existing documentation remains accurate

📋 Suggestions for Improvement

1. Accuracy & Claims (Minor)

Line 21: "Faster" claim

-- **Faster**: Written in Go, processes large codebases in seconds
+- **Faster**: Written in Go for superior performance over Python-based alternatives

Rationale: "Processes large codebases in seconds" is vague and could be misleading depending on codebase size. Consider:

• Adding a reference to PERFORMANCE_BENCHMARKS.md if it contains data
• OR making the claim more specific: "2-3x faster than Python alternatives" (if benchmarked)
• OR keeping it comparative without absolute time claims

Line 78: "AI Pair Programming" - Tool mentions

-- **AI Pair Programming**: Provide full codebase context to AI assistants like GitHub Copilot, Cursor, or Windsurf
+- **AI Pair Programming**: Provide full codebase context to AI assistants and code editors

Rationale: Mentioning competitors' products (Cursor, Windsurf) may:

• Date the documentation quickly as tools evolve
• Imply integration that doesn't exist
• Create confusion about what promptext does vs. those tools

Consider generic phrasing or focus on the use case rather than specific tools.

2. Content Organization (Minor)

The new "Use Cases" section (lines 74-83) appears after the "Updating" section, which breaks the logical flow. Consider this structure:

1. Title/Badges
2. Problem/Solution
3. Why promptext?
4. Features
5. Use Cases          ← Move here (before Installation)
6. Installation
7. Updating
8. Basic Usage
...

Rationale: Users typically want to see "Why" → "What" → "How to use" before installation details.

3. Keyword Density (Stylistic)

The Features section now has 3 new LLM-focused bullets (lines 35-37):

- **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

Observation: These are somewhat redundant with existing features and the new tagline. Consider:

• Consolidating into 1-2 bullets to avoid dilution
• OR keeping them but making them more feature-specific than keyword-focused

Example consolidation:

-- **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
+- **Universal LLM compatibility**: Works with any AI assistant (ChatGPT, Claude, GPT-4, Gemini) with built-in token limit awareness for all major models

4. Use Cases Section - Specificity (Enhancement)

Some use cases are generic. Consider adding promptext-specific value:

-- **Documentation Generation**: Help AI understand your complete project structure for accurate docs
+- **Documentation Generation**: Auto-select relevant files with `--relevant` to help AI generate accurate, context-aware documentation

This shows how promptext specifically helps, not just the general use case.

🔒 Security Concerns

None identified. This is a documentation-only change with no code modifications.

🧪 Test Coverage

Not applicable - this PR only modifies README.md. No code changes require testing.

⚡ Performance Considerations

Not applicable - documentation-only change.

🐛 Potential Issues

None identified. The PR correctly:

• Maintains all existing badges and links
• Preserves technical accuracy
• Doesn't break any markdown formatting

🎯 Recommendation

APPROVE with minor suggestions

This PR successfully achieves its goal of improving discoverability. The suggestions above are optional refinements:

• Critical: None
• Recommended: Reorder "Use Cases" section before Installation
• Optional: Refine competitor tool mentions and keyword density

The marketing improvements are valuable and the technical content remains sound. Great work positioning promptext in the code-to-prompt tool ecosystem!

---

Next Steps (if desired):

1. Consider adding "SEO" or "documentation" labels to this PR
2. Track search ranking improvements post-merge to measure impact
3. Update CHANGELOG.md with a note about improved documentation/discoverability

[claude]

PR Review: Improve README and GitHub tags for discoverability

Summary

This PR enhances the README with SEO-focused keywords and restructures content for better discoverability. The changes are documentation-only with no code modifications, so the review focuses on content quality, accuracy, and user experience.

✅ Strengths

1. Clear Value Proposition: The new tagline immediately positions promptext as a "code2prompt alternative" - excellent for search discoverability
2. Well-Structured Use Cases: The new "Use Cases" section (lines 76-83) provides concrete, relatable scenarios that help users quickly understand when to use the tool
3. Improved Organization: Restructuring from "Basic Usage" / "Advanced Usage" to "Smart Context Building" / "Quick Commands" is more intuitive and highlights power features first
4. Strategic Keyword Integration: Natural incorporation of "Claude", "ChatGPT", "LLM", "prompt engineering" without feeling spammy
5. Token Budget Context: The example output (lines 135-146) helps users understand what happens when limits are exceeded

📝 Suggestions & Improvements

1. Accuracy & Consistency (Minor)

• Line 29: "promptext's hybrid TOON format - 25-30% token reduction"
  • Later (line 152) says PTX is "specifically created for promptext"
  • Verify: Is PTX proprietary to promptext or a TOON variant? The messaging should be consistent
  • Recommendation: If PTX is your format, consider emphasizing this uniqueness more strongly

2. Content Clarity (Medium Priority)

• Line 20: "Unlike other tools like code2prompt, codebase-digest, or manual copy-pasting"

  • The comparison mixes tools with manual processes - slightly awkward
  • Suggestion: "Unlike tools like code2prompt and codebase-digest, promptext offers:"

• Lines 103-107: Relevance scoring explanation duplicates content from line 31

  • Consider removing one instance or cross-referencing to avoid maintenance burden

3. User Experience (Medium Priority)

• The new structure buries basic usage ("current directory to clipboard: prx") until line 112
  • Many users want the simplest command first
  • Suggestion: Add a "Quick Start" section at the top after installation

4. SEO/Marketing Balance (Low Priority)

• Line 3: The tagline is keyword-dense but slightly robotic
  • Consider: "Fast, token-aware alternative to code2prompt - convert your codebase into AI-ready prompts for Claude, ChatGPT, and any LLM"
  • Flows better while maintaining SEO keywords

5. Technical Accuracy Check (Important)

• Line 36: "Respect token limits for Claude Haiku/Sonnet/Opus, GPT-3.5/4"
  • Verify these specific model names/limits are current (Claude's naming has evolved)
  • Consider making this more generic: "Respect token limits for Claude, GPT, and other LLM context windows"

🔍 Content Quality Assessment

Before vs After Line Count:

• Removed: 62 lines (mostly verbose command explanations)
• Added: 57 lines (use cases, comparison section, streamlined examples)
• Net: Slightly more concise while adding strategic content ✅

Keyword Density Check:

• AI/LLM: 15+ mentions across document
• code2prompt: 3 mentions (good balance)
• prompt engineering: 2 mentions
• Assessment: Natural integration, not keyword-stuffed ✅

🚀 Performance Considerations

N/A - Documentation-only changes

🔒 Security Concerns

None - No code changes, no external dependencies introduced

🧪 Test Coverage

N/A - Documentation-only changes. No test updates required.

📋 Recommendations

Before Merge:

1. ✅ Accept as-is if targeting immediate SEO improvements
2. 🔧 Consider adding a 3-line "Quick Start" section at the top
3. ✅ Verify Claude model names are current (low priority)

Future Improvements:

• Consider adding GitHub topics/tags in repository settings to complement README keywords
• Add a "Comparison" section comparing PTX vs TOON vs other formats with benchmarks
• Include a table comparing promptext vs code2prompt feature-by-feature

✅ Approval Status

Recommended for merge with optional minor refinements. The changes effectively improve discoverability without sacrificing technical accuracy. The restructuring enhances user experience by showcasing powerful features (relevance filtering + token budgets) prominently.

Great work on SEO optimization while maintaining technical credibility!