diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f1d27ba..78d51bf 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -6,50 +6,97 @@ 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
+### 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
```
-## Code Standards
+### 2. Create Feature Branch
+
+```bash
+git checkout -b your-feature-name
+```
-- 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
+### 3. Make Changes and Test
-## Pull Request Process
+```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
+```
+
+### 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. Submit a pull request with clear description
+**Ensure all GitHub Actions CI checks pass before requesting review.**
## Questions?
diff --git a/README.md b/README.md
index d64ae6f..58fb42b 100644
--- a/README.md
+++ b/README.md
@@ -4,44 +4,56 @@
[](https://sonarcloud.io/summary/new_code?id=wisarootl_leetcode-py)
[](https://sonarcloud.io/summary/new_code?id=wisarootl_leetcode-py)
[](https://codecov.io/gh/wisarootl/leetcode-py)
-[](https://github.com/wisarootl/zerv/actions/workflows/ci-test.yml)
-[](https://github.com/wisarootl/zerv/actions/workflows/cd.yml)
+[](https://github.com/wisarootl/leetcode-py/actions/workflows/ci-test.yml)
+[](https://github.com/wisarootl/leetcode-py/actions/workflows/cd.yml)
+[](https://pepy.tech/projects/leetcode-py-sdk)
+[](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.
+## Table of Contents
+
+- [What's Included](#whats-included)
+- [Quick Start](#quick-start)
+- [Problem Structure](#problem-structure)
+- [Key Features](#key-features)
+- [Usage Patterns](#usage-patterns)
+- [Development Setup](#development-setup)
+- [Helper Classes](#helper-classes)
+- [Commands](#commands)
+- [Architecture](#architecture)
+- [Quality Metrics](#quality-metrics)
+
**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
+## ๐ฏ 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
+## ๐ Quick Start
### System Requirements
-- **Python 3.13+** - Modern Python runtime with latest type system features
-- **Poetry** - Dependency management and packaging
-- **Make** - Build automation (development workflows)
-- **Git** - Version control system
-- **Graphviz** - Graph visualization library (for data structure rendering)
+- **Python 3.10+** - Python runtime
+- **Graphviz** - Graph visualization library ([install guide](https://graphviz.org/download/))
```bash
# Install the package
-pip install leetcode-py
+pip install leetcode-py-sdk
# Generate problems anywhere
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
@@ -49,7 +61,7 @@ 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
@@ -63,7 +75,7 @@ _Bulk generation output showing "Generated problem:" messages for all 75 Grind p
_Generated folder structure showing all 75 problem directories after command execution_
-## ๐ Problem Structure
+## ๐ Problem Structure
Each problem follows a consistent, production-ready template:
@@ -93,7 +105,7 @@ _Comprehensive parametrized tests with 10+ test cases - executable and debuggabl
_Beautiful colorful test output with loguru integration for enhanced debugging and test result visualization_
-## โจ Key Features
+## โจ Key Features
### Production-Grade Development Environment
@@ -143,33 +155,23 @@ _Simple arrow-based list representation for console output and test debugging_
_Interactive multi-cell playground with rich data structure visualization for each problem_
-## ๐ Usage Patterns
+## ๐ Usage Patterns
### CLI Usage (Global Installation)
-Perfect for quick problem generation anywhere:
-
-```bash
-# Generate specific problems
-lcpy gen -n 1 -n 125 -n 206 # Multiple problems by number
-lcpy gen -s two-sum -s valid-palindrome # Multiple problems by slug
-
-# Bulk generation
-lcpy gen -t grind-75 # All Grind 75 problems
-lcpy gen -t grind-75 -d Easy # Only Easy problems from Grind 75
+Perfect for quick problem generation anywhere. See the ๐ **[Complete CLI Usage Guide](https://github.com/wisarootl/leetcode-py/blob/main/docs/cli-usage.md)** for detailed documentation with all options and examples.
-# Explore available problems
-lcpy list # All problems
-lcpy list -t grind-75 # Filter by tag
-lcpy list -d Medium # Filter by difficulty
+## ๐ ๏ธ Development Setup
-# Fetch problem data
-lcpy scrape -n 1 > two_sum.json # Save problem data
-```
+For working within this repository to generate additional LeetCode problems using LLM assistance:
-## ๐ ๏ธ Development Setup
+### Development Requirements
-For working within this repository to generate additional LeetCode problems using LLM assistance:
+- **Python 3.10+** - Modern Python runtime with latest type system features
+- **Poetry** - Dependency management and packaging
+- **Make** - Build automation (development workflows)
+- **Git** - Version control system
+- **Graphviz** - Graph visualization library ([install guide](https://graphviz.org/download/))
```bash
# Clone repository for development
diff --git a/docs/cli-usage.md b/docs/cli-usage.md
index 811beb5..ca91ff3 100644
--- a/docs/cli-usage.md
+++ b/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
+```
+
+
+
+_Bulk generation output showing "Generated problem:" messages for all 75 Grind problems_
+
+
+
+_Generated folder structure showing all 75 problem directories after command execution_
+
+```bash
+
# Filter by difficulty
lcpy gen -t grind-75 -d Easy
@@ -151,15 +165,24 @@ problem_name/
โโโ __init__.py # Package marker
```
+
+
+_README format that mirrors LeetCode's problem description layout_
+
+
+
+_Solution boilerplate with type hints and TODO placeholder_
+
+
+
+_Comprehensive parametrized tests with 10+ test cases - executable and debuggable in local development environment_
+
## Tags
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
diff --git a/docs/llm-assisted-problem-creation.md b/docs/llm-assisted-problem-creation.md
index f4d770f..bb97d3b 100644
--- a/docs/llm-assisted-problem-creation.md
+++ b/docs/llm-assisted-problem-creation.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