docs(contrib): streamline contributor workflow and add issue-first approach (#5)

CHANGES
- Add mandatory issue-first workflow to CONTRIBUTING.md (no issue, no PR)
- Streamline development setup with concise sections and clear structure
- Enhance quality tools section with complete file tree for templates and prompts
- Create README-dockerhub.md for Docker Hub with full GitHub links
- Apply ruff formatting to src/build_index.py for code consistency
- Update README.md contributing link to use "follow" instead of "see"

IMPACT
- Contributors must create issues before PRs, ensuring structured development
- Reduced contributor friction with clearer, more organized documentation
- Docker Hub users get comprehensive guidance with proper GitHub references

TECHNICAL NOTES
- Issue-first approach enforces best practices and improves project management
- Dockerhub README maintains feature parity while adapting for external hosting
- Code formatting maintains consistency across Python files

Author: KemingHe

CONTRIBUTING.md

@@ -2,11 +2,19 @@
 
 > Updated on 2025-07-23 by @KemingHe
 
-Thank you for your interest in contributing! This document provides development setup instructions and guidelines.
+Thank you for your interest in contributing! This guide covers development workflow and setup.
 
-## 🛠️ Development Setup
+## 🔄 Contribution Workflow
+
+**Issue-first approach**: No issue, no PR. No PR, no merge.
+
+1. **Raise issue** - Bug report or feature request
+2. **Get assigned** - Wait for maintainer assignment  
+3. **Create PR** - Link to assigned issue
+4. **Review & approval** - Address feedback
+5. **Merge** - Maintainer merges approved PR
 
-**Transport**: Stdio only (MCP standard for local tools).
+## 🛠️ Development Setup
 
 ### Local Development
 
@@ -16,19 +24,19 @@ git clone <repo-url>
 cd python-dep-manager-companion-mcp-server
 uv sync
 
-# Run server locally
+# Run server locally  
 uv run --with fastmcp --with tantivy fastmcp run src/mcp_server.py
 
 # Build Docker image
 docker build -t py-dep-man-companion .
 ```
 
-### Local Testing with MCP Client
+### Local Testing
 
-For testing the server locally during development, add this configuration to your VSCode/Cursor `mcp.json`:
+Add to your VSCode/Cursor's `mcp.json` for testing:
 
->[!IMPORTANT]
-> Replace `/path/to/your/python-dependency-manager-companion-mcp-server` with the absolute path to your local repository.
+> [!IMPORTANT]
+> Replace `/path/to/your/repo` with your local repository path.
 
 ```json
 {
@@ -37,47 +45,38 @@ For testing the server locally during development, add this configuration to you
       "py-dep-man-companion-native": {
         "command": "uv",
         "args": [
-          "run",
-          "--directory",
-          "/path/to/your/python-dependency-manager-companion-mcp-server",
-          "--with",
-          "fastmcp>=2.10.5",
-          "--with",
-          "tantivy>=0.24.0",
-          "fastmcp",
-          "run",
-          "src/mcp_server.py"
+          "run", "--directory", "/path/to/your/repo",
+          "--with", "fastmcp>=2.10.5", "--with", "tantivy>=0.24.0",
+          "fastmcp", "run", "src/mcp_server.py"
         ]
       }
     }
   }
 }
 ```
 
-## 📝 Development Guidelines
-
-- Follow existing code style and structure
-- Test your changes locally using the native configuration above
-- Update documentation when adding new features
-- Submit pull requests with clear descriptions of changes
+## 📝 Development Standards
 
-### Git Workflow & Branching
+### Git Workflow
 
-- **Branching pattern**: `type/feature-or-bug-scope/GitHubUsername`
+- **Branching**: `type/feature-or-bug-scope/GitHubUsername`
 - **Types**: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
+- **Commits**: Use `prompts/prompt-commit-msg-gen.md` for consistency
+
+### Quality Tools
 
-### Prompts for AI-Assisted Development
+Available templates and prompts for consistent contributions:
 
 > [!TIP]
-> This project includes AI prompts and GitHub templates for consistent, high-quality contributions:
+> Use these tools for consistent, high-quality contributions that reduce review cycles.
 
 ```plaintext
 .github/
 ├── ISSUE_TEMPLATE/
 │   ├── bug-report.md             # Bug report template
 │   └── feature-request.md        # Feature request template
 └── PULL_REQUEST_TEMPLATE/
-    └── pull_request_template.md  # PR template with checklist
+    └── pull_request_template.md
 
 prompts/
 ├── prompt-commit-msg-gen.md      # Generate uniform commit messages
@@ -86,12 +85,12 @@ prompts/
 └── prompt-readme-gen.md          # Maintain documentation standards
 ```
 
-## 🔄 Automated Updates
+## 🤖 Automated Systems
 
-This repository includes automated workflows that:
+The repository auto-updates weekly (Tuesday 6pm ET):
 
-1. Update documentation weekly from official sources
-2. Rebuild search indexes automatically
-3. Publish multi-architecture Docker images
+1. Syncs official documentation
+2. Rebuilds search indexes
+3. Publishes Docker images
 
-See [.github/workflows/README.md](.github/workflows/README.md) for workflow details.
+See [.github/workflows/README.md](.github/workflows/README.md) for technical details.

README-dockerhub.md

@@ -0,0 +1,72 @@
+# Python Dependency Manager Companion MCP Server
+
+> README updated on 2025-07-23 by [@KemingHe](https://github.com/KemingHe)
+
+Official docs from `pip`, `poetry`, `uv`, and `conda` + automated weekly updates = zero maintenance overhead for developers using VSCode/Cursor with AI assistants. [[Demo]](https://www.loom.com/share/a80f6041dc374c07b95b2397ee4e8ca1?sid=1209cdce-7239-447e-8b20-49eae454cc9a)
+
+## 🚀 Quick Start for Agentic IDEs
+
+**1. Pull latest Docker image**:
+
+```shell
+docker pull keminghe/py-dep-man-companion:latest
+```
+
+**2. Add to your IDE's `mcp.json`**:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "python-deps": {
+        "command": "docker",
+        "args": ["run", "-i", "--rm", "keminghe/py-dep-man-companion:latest"]
+      }
+    }
+  }
+}
+```
+
+**3. Query official docs directly in your AI chat** - guaranteed fresh from weekly automated updates.
+
+## 🔄 Auto-Update Architecture
+
+```plaintext
+┌───────────────────────────┐
+│  ⏰ Every Tuesday 6pm ET  │
+└─────────────┬─────────────┘
+              ▼
+┌───────────────────────────┐
+│  📚 Sync Official Docs    │
+└─────────────┬─────────────┘
+              ▼
+┌───────────────────────────┐
+│  🔍 Rebuild Search Index  │
+└─────────────┬─────────────┘
+              ▼
+┌───────────────────────────┐
+│  🐳 Publish Latest Image  │
+└───────────────────────────┘
+```
+
+**Zero maintenance**: Documentation automatically synced weekly from official sources. Docker `:latest` tag guarantees you always get current docs without manual updates.
+
+## 🤝 Contributing
+
+**Use as template**: [[Create from template]](https://github.com/new?template_name=python-dependency-manager-companion-mcp-server&template_owner=KemingHe) for your own MCP server projects.
+
+**Contribute back**: Fork and follow [CONTRIBUTING.md](https://github.com/KemingHe/python-dependency-manager-companion-mcp-server/blob/main/CONTRIBUTING.md) for development setup.
+
+## 🗺️ Roadmap
+
+- [ ] Add support for `pipenv`, `pdm`, `pixi`
+- [ ] Add comprehensive tests with 100% coverage  
+- [ ] Add indexing support for PDF and CSV files
+
+## 📄 License
+
+This project is licensed under the [MIT License](https://github.com/KemingHe/python-dependency-manager-companion-mcp-server/blob/main/LICENSE) - a permissive license that allows free use, modification, and distribution with attribution.
+
+## 📞 Support
+
+Open a [GitHub issue](https://github.com/KemingHe/python-dependency-manager-companion-mcp-server/issues) for bug reports and feature requests.

README.md

@@ -33,7 +33,7 @@ docker pull keminghe/py-dep-man-companion:latest
 
 **Use as template**: [[Create from template]](https://github.com/new?template_name=python-dependency-manager-companion-mcp-server&template_owner=KemingHe) for your own MCP server projects.
 
-**Contribute back**: Fork and see [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup.
+**Contribute back**: Fork and follow [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup.
 
 ## 🔄 Auto-Update Architecture
 

src/build_index.py

@@ -110,7 +110,7 @@ def find_markdown_files(assets_dir: Path) -> list[tuple[Path, str, Dict[str, Any
 def read_file_content(file_path: Path) -> str:
     """
     Read file content with multiple encoding fallbacks.
-    
+
     Note: This function is called only with paths from find_markdown_files(),
     which uses glob() to find files within the controlled ASSETS_DIR structure.
     The paths are generated by filesystem iteration, not user input.
@@ -120,16 +120,16 @@ def read_file_content(file_path: Path) -> str:
         if not file_path.exists() or not file_path.is_file():
             logger.warning(f"File does not exist or is not a regular file: {file_path}")
             return ""
-        
+
         # Simple safety check: ensure resolved path is still within assets
         if not file_path.resolve().is_relative_to(ASSETS_DIR.resolve()):
             logger.error(f"File path outside assets directory: {file_path}")
             return ""
-            
+
     except (OSError, ValueError) as e:
         logger.warning(f"Path validation failed for {file_path}: {e}")
         return ""
-    
+
     encodings = ["utf-8", "utf-8-sig", "latin1", "cp1252"]
 
     for encoding in encodings: