docs: improve docs

Author: wislertt

CONTRIBUTING.md

@@ -37,21 +37,66 @@ I'm also open to feedback and suggestions for improving the project!
 
 ## Development Setup
 
+### Prerequisites
+
+- **Python 3.10+** - Modern Python runtime
+- **Poetry** - Dependency management ([install guide](https://python-poetry.org/docs/#installation))
+- **Make** - Build automation (usually pre-installed on Unix systems)
+- **Git** - Version control
+- **Graphviz** - Graph visualization ([install guide](https://graphviz.org/download/))
+
+## Development Workflow
+
+### 1. Fork and Setup
+
 ```bash
-git clone https://github.com/wisarootl/leetcode-py.git
+# Fork the repository on GitHub, then clone your fork
+git clone https://github.com/YOUR_USERNAME/leetcode-py.git
 cd leetcode-py
 poetry install
+
+# Add upstream remote
+git remote add upstream https://github.com/wisarootl/leetcode-py.git
+
+# Verify setup
+make test
+make lint
+```
+
+### 2. Create Feature Branch
+
+```bash
+git checkout -b your-feature-name
+```
+
+### 3. Make Changes and Test
+
+```bash
+# Test specific problem
+make p-test PROBLEM=problem_name
+
+# Test all
 make test
+
+# Lint your changes
+make lint
+
+# Generate/regenerate problems (if needed)
+make p-gen PROBLEM=problem_name
 ```
 
-## Pull Request Process
+### 4. Submit Pull Request
+
+```bash
+# Commit and push to your fork
+git add .
+git commit -m "feat: your descriptive commit message"
+git push origin your-feature-name
+
+# Then create a pull request on GitHub from your fork to the main repository
+```
 
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Run `make lint` and `make test`
-5. Ensure all GitHub Actions CI checks pass
-6. Submit a pull request with clear description
+**Ensure all GitHub Actions CI checks pass before requesting review.**
 
 ## Questions?
 

README.md

@@ -54,15 +54,14 @@ pip install leetcode-py-sdk
 lcpy gen -n 1                    # Generate Two Sum
 lcpy gen -t grind-75             # Generate all Grind 75 problems
 lcpy list -t grind-75            # List available problems
-lcpy scrape -n 1                 # Fetch problem data
 
 # Start practicing
 cd leetcode/two_sum
 python -m pytest test_solution.py  # Run tests
 # Edit solution.py, then rerun tests
 ```
 
-### Example
+### Bulk Generation Example
 
 ```bash
 lcpy gen --problem-tag grind-75 --output leetcode  # Generate all Grind 75 problems

docs/cli-usage.md

@@ -65,9 +65,23 @@ lcpy gen -s two-sum
 # Multiple problems by slug
 lcpy gen -s two-sum -s valid-palindrome
 
-# All problems with specific tag
+# All problems with specific tag (bulk generation)
 lcpy gen -t grind-75
 
+# Example: Generate all Grind 75 problems
+lcpy gen --problem-tag grind-75 --output leetcode
+```
+
+![Problem Generation](https://raw.githubusercontent.com/wisarootl/leetcode-py/main/docs/images/problems-generation.png)
+
+_Bulk generation output showing "Generated problem:" messages for all 75 Grind problems_
+
+![Problem Generation 2](https://raw.githubusercontent.com/wisarootl/leetcode-py/main/docs/images/problems-generation-2.png)
+
+_Generated folder structure showing all 75 problem directories after command execution_
+
+```bash
+
 # Filter by difficulty
 lcpy gen -t grind-75 -d Easy
 
@@ -151,6 +165,18 @@ problem_name/
 └── __init__.py         # Package marker
 ```
 
+![README Example](https://raw.githubusercontent.com/wisarootl/leetcode-py/main/docs/images/readme-example.png)
+
+_README format that mirrors LeetCode's problem description layout_
+
+![Solution Boilerplate](https://raw.githubusercontent.com/wisarootl/leetcode-py/main/docs/images/solution-boilerplate.png)
+
+_Solution boilerplate with type hints and TODO placeholder_
+
+![Test Example](https://raw.githubusercontent.com/wisarootl/leetcode-py/main/docs/images/test-example.png)
+
+_Comprehensive parametrized tests with 10+ test cases - executable and debuggable in local development environment_
+
 ## Tags
 
 Available tags for bulk operations:

docs/improvement-checklist.md

@@ -75,27 +75,25 @@ Each problem includes 10+ test cases covering edge cases (note: generated test c
 
 _Generated test_solution.py with parametrized tests and comprehensive test cases_
 
-## Test Enhancement Workflow
+## Test Enhancement & Verification
 
-### Enhancing Existing Problems
+### Enhancing and Verifying Test Cases
 
-Improve test coverage for existing problems:
+Improve test coverage and verify correctness for existing or newly generated problems:
+
+**1. Run the tests:**
 
 ```bash
-"Enhance test cases for two_sum problem"
-"Add more edge cases to binary_tree_inorder_traversal"
-"Fix test reproducibility for valid_palindrome"
+make p-test PROBLEM={problem_name}
 ```
 
-### Quality Assurance
-
-The assistant can identify problems needing more test cases and verify test case correctness and reproducibility:
+**2. Ask LLM to enhance or verify:**
 
 ```bash
+"Enhance test cases for {problem_name} problem"
+"Fix test reproducibility for {problem_name}"
 "Check which problems need more test cases"
 "Find problems with less than 12 test cases"
-"Verify test case correctness for house_robber"
-"Fix test reproducibility for binary_tree_inorder_traversal"
 ```
 
 ## Best Practices
@@ -107,11 +105,13 @@ The assistant can identify problems needing more test cases and verify test case
 - "Add problem 198. House Robber with grind tag"
 - "Create problem 70. Climbing Stairs for grind-75"
 - "Enhance test cases for two_sum problem"
+- "Verify and fix test cases for binary_search problem"
 
 **Avoid:**
 
 - Vague requests without problem numbers
 - Requests for non-existent problems
+- Assuming generated test cases are always correct
 
 ## Troubleshooting