docs: improve docs

Author: wislertt

CONTRIBUTING.md

@@ -6,26 +6,34 @@ Thank you for your interest in contributing! This repository welcomes contributi
 
 ### 1. Add New Problems
 
-Use an LLM assistant (Cursor, GitHub Copilot Chat, Amazon Q) with the rule files:
+For adding new LeetCode problems, please refer to the comprehensive guide:
 
-- Include `.amazonq/rules/problem-creation.md` in your LLM context
-- Ask: "Create LeetCode problem [number] ([name])"
+📖 **[LLM-Assisted Problem Creation Guide](docs/llm-assisted-problem-creation.md)**
 
-### 2. Enhance Test Cases
+This document provides detailed instructions for using LLM assistants to generate new problems with proper templates, test cases, and documentation.
 
-- Include `.amazonq/rules/test-quality-assurance.md` in your LLM context
-- Ask: "Enhance test cases for [problem_name] problem"
+**Acceptance Criteria:**
 
-### 3. Improve Helper Classes
+- All GitHub Actions CI checks must pass (includes linting, testing, security scanning, reproducibility verification, and minimum 10 test cases per problem)
+- Proper type hints and code formatting
+- Complete the solution (documentation is auto-generated)
 
-- Add new data structure helpers in `leetcode_py/data_structures/`
-- Follow existing patterns with generic types and visualization support
+### 2. Other Contributions
 
-### 4. Bug Fixes & Improvements
+All other contributions are welcome! This includes:
 
-- Fix issues in existing problems
-- Improve documentation
-- Enhance CI/CD workflows
+- Bug fixes and improvements
+- Documentation enhancements
+- Helper class improvements
+- CI/CD workflow enhancements
+- Test case enhancements
+- New data structure visualizations
+
+**For small changes:** Feel free to open a pull request directly.
+
+**For larger changes:** Please open an issue for discussion first.
+
+I'm also open to feedback and suggestions for improving the project!
 
 ## Development Setup
 
@@ -36,20 +44,14 @@ poetry install
 make test
 ```
 
-## Code Standards
-
-- Follow [PEP 8](https://peps.python.org/pep-0008/) Python style guide
-- Use modern type hints per [PEP 585](https://peps.python.org/pep-0585/)/[PEP 604](https://peps.python.org/pep-0604/): `list[str]`, `dict[str, int]`, `Type | None`
-- Automated linting enforced by CI (black, isort, ruff, mypy)
-- Minimum 12 test cases per problem
-
 ## Pull Request Process
 
 1. Fork the repository
 2. Create a feature branch
 3. Make your changes
 4. Run `make lint` and `make test`
-5. Submit a pull request with clear description
+5. Ensure all GitHub Actions CI checks pass
+6. Submit a pull request with clear description
 
 ## Questions?
 

README.md

@@ -6,22 +6,25 @@
 [![codecov](https://codecov.io/gh/wisarootl/leetcode-py/graph/badge.svg?token=TI97VUIA4Z)](https://codecov.io/gh/wisarootl/leetcode-py)
 [![tests](https://img.shields.io/github/actions/workflow/status/wisarootl/leetcode-py/ci-test.yml?branch=main&label=tests&logo=github)](https://github.com/wisarootl/zerv/actions/workflows/ci-test.yml)
 [![release](https://img.shields.io/github/actions/workflow/status/wisarootl/leetcode-py/cd.yml?branch=main&label=release&logo=github)](https://github.com/wisarootl/zerv/actions/workflows/cd.yml)
+[![downloads](https://static.pepy.tech/personalized-badge/leetcode-py-sdk?period=total&units=international_system&left_color=grey&right_color=brightgreen&left_text=pypi%20downloads)](https://pepy.tech/projects/leetcode-py-sdk)
+[![python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-brightgreen?logo=python)](https://pypi.org/project/leetcode-py-sdk/)
 
 A Python package to generate professional LeetCode practice environments. Features automated problem generation from LeetCode URLs, beautiful data structure visualizations (TreeNode, ListNode, GraphNode), and comprehensive testing with 10+ test cases per problem. Built with professional development practices including CI/CD, type hints, and quality gates.
 
 **What makes this different:**
 
-- 🤖 **[LLM-Assisted Workflow](https://github.com/wisarootl/leetcode-py#llm-assisted-problem-creation)**: Generate new problems instantly with AI assistance
+- 🤖 **[LLM-Assisted Workflow](https://github.com/wisarootl/leetcode-py/blob/main/docs/llm-assisted-problem-creation.md)**: Generate new problems instantly with AI assistance
 - 🎨 **Visual Debugging**: Interactive tree/graph rendering with Graphviz and anytree
 - 🧪 **Production Testing**: Comprehensive test suites with edge cases and reproducibility verification
 - 🚀 **Modern Python**: PEP 585/604 type hints, Poetry, and professional tooling
 - 📊 **Quality Assurance**: 95%+ test coverage, security scanning, automated linting
+- ⚡ **[Powerful CLI](https://github.com/wisarootl/leetcode-py/blob/main/docs/cli-usage.md)**: Generate problems anywhere with `lcpy` command
 
 ## 🎯 What's Included
 
 **Current**: All 75 problems from [Grind 75](https://www.techinterviewhandbook.org/grind75/) - the most essential coding interview questions curated by the creator of Blind 75.
 
-**Future**: Planned expansion to all free Grind problems for comprehensive interview preparation.
+**Future**: Planned expansion to all free Grind problems for comprehensive interview preparation. [Contributions welcome!](CONTRIBUTING.md)
 
 ## 🚀 Quick Start
 

docs/cli-usage.md

@@ -156,10 +156,7 @@ problem_name/
 Available tags for bulk operations:
 
 - `grind-75` - Essential 75 coding interview problems
-- `blind-75` - Original Blind 75 problems
-- `neetcode-150` - NeetCode 150 problems
-- `top-interview` - Top interview questions
-- `easy`, `medium`, `hard` - Difficulty-based tags
+- `grind` - Original Blind 75 problems
 
 ## Output Directory
 

docs/improvement-checklist.md

@@ -0,0 +1,133 @@
+# Documentation Improvement Checklist
+
+## High Priority Fixes
+
+### README.md Critical Issues
+
+- [ ] **Fix badge links**: Update tests and release badges from `wisarootl/zerv` to `wisarootl/leetcode-py`
+- [ ] **Python version consistency**: Change "Python 3.13+" to "Python 3.10+" to match badge
+- [ ] **Fix pip install command**: Update from `pip install leetcode-py` to `pip install leetcode-py-sdk`
+
+### Navigation & Structure
+
+- [ ] **Add Table of Contents**: Include TOC at top of README for better navigation
+- [ ] **Consolidate CLI sections**: Reduce redundancy between Quick Start, Usage Patterns, and CLI guide
+- [ ] **Reorganize sections**: Move Development Setup after CLI usage for better flow
+
+## Content Enhancements
+
+### README.md Improvements
+
+- [ ] **Add "Getting Started in 5 Minutes"**: Absolute minimum steps for new users
+- [ ] **Performance metrics**: Add statistics like "Generate 75 problems in under 30 seconds"
+- [ ] **User personas**: Different paths for beginner vs advanced developers
+- [ ] **Comparison table**: Compare with other LeetCode practice tools
+- [ ] **More concrete examples**: Show before/after of problem generation
+
+### CLI Usage Guide
+
+- [ ] **Add troubleshooting section**: Common CLI errors and solutions
+- [ ] **Performance tips**: Best practices for bulk operations
+- [ ] **Combine multiple options**: Examples of complex CLI combinations
+- [ ] **Error handling examples**: Show specific error messages and fixes
+
+### LLM-Assisted Problem Creation Guide
+
+- [ ] **Prerequisites checklist**: Clear setup requirements at top
+- [ ] **Test case verification**: Section on verifying generated test correctness
+- [ ] **More prompt examples**: Expand good vs bad prompt examples
+- [ ] **Integration examples**: Show how it fits into development workflow
+
+### CONTRIBUTING.md
+
+- [ ] **Examples of contribution types**: Clarify "small changes" vs "larger changes"
+- [ ] **Link to issue templates**: Reference different contribution types
+- [ ] **Development workflow**: More detailed setup and testing instructions
+
+## New Documentation
+
+### Missing Documentation Files
+
+- [ ] **API Reference** (`docs/api-reference.md`): Document helper classes with examples
+    - TreeNode methods and usage
+    - ListNode methods and usage
+    - GraphNode methods and usage
+    - DictTree methods and usage
+- [ ] **Troubleshooting Guide** (`docs/troubleshooting.md`): Common issues and solutions
+- [ ] **FAQ** (`docs/faq.md`): Frequently asked questions
+- [ ] **Performance Guide** (`docs/performance.md`): Optimization tips and benchmarks
+
+### Enhanced Examples
+
+- [ ] **Data structure examples**: Concrete usage of TreeNode, ListNode, etc.
+- [ ] **Integration examples**: How to use with existing projects
+- [ ] **Advanced usage**: Complex scenarios and edge cases
+
+## Visual & Media
+
+### Image Consistency
+
+- [ ] **Standardize screenshots**: Ensure consistent IDE theme across all images
+- [ ] **Update outdated images**: Verify all screenshots reflect current UI
+- [ ] **Add missing visuals**: More examples of CLI output and generated files
+
+### Links & References
+
+- [ ] **Verify all links**: Check internal and external links work
+- [ ] **Add more references**: Link to LeetCode, Grind 75, related tools
+- [ ] **Fix image accessibility**: Ensure all images load correctly
+
+## Technical Improvements
+
+### SEO & Discoverability
+
+- [ ] **Improve meta descriptions**: Better GitHub search results
+- [ ] **Add keywords**: More searchable terms in descriptions
+- [ ] **Tag optimization**: Better categorization and tagging
+
+### Code Quality
+
+- [ ] **Code example validation**: Ensure all code snippets work
+- [ ] **Import statement examples**: Show correct import patterns
+- [ ] **Error handling**: Better error message examples
+
+## Organization & Maintenance
+
+### File Structure
+
+- [ ] **Organize docs folder**: Better categorization of documentation
+- [ ] **Cross-references**: Better linking between related docs
+- [ ] **Version consistency**: Ensure all docs reflect current version
+
+### Content Maintenance
+
+- [ ] **Regular review schedule**: Plan for keeping docs updated
+- [ ] **User feedback integration**: Process for incorporating user suggestions
+- [ ] **Automated checks**: Validate links and code examples in CI
+
+## Implementation Priority
+
+### Phase 1 (Immediate)
+
+1. Fix badge links
+2. Update Python version consistency
+3. Fix pip install command
+4. Add Table of Contents
+
+### Phase 2 (Short-term)
+
+1. Create API reference
+2. Add troubleshooting guide
+3. Enhance CLI documentation
+4. Improve visual consistency
+
+### Phase 3 (Long-term)
+
+1. Create comprehensive FAQ
+2. Add performance guide
+3. Develop user persona paths
+4. Build comparison resources
+
+---
+
+**Note**: This checklist should be reviewed and updated regularly as the project evolves and user feedback is received.