docs: improved README, CONTRIBUTING, and pull request template

.env.example

@@ -0,0 +1,4 @@
+# RunPod API Key for development and testing
+# Copy this file to .env and add your actual API key
+# Get your API key from: https://www.runpod.io/console/user/settings
+RUNPOD_API_KEY=your_api_key_here

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,92 @@
+## Description
+
+Brief description of what this PR adds or fixes.
+
+## Type of Change
+
+- [ ] New example
+- [ ] Bug fix
+- [ ] Enhancement to existing example
+- [ ] Documentation update
+- [ ] Other (please describe):
+
+## Example Category
+
+If adding a new example, which category does it belong to?
+
+- [ ] 01 - Getting Started
+- [ ] 02 - ML Inference
+- [ ] 03 - Advanced Workers
+- [ ] 04 - Scaling & Performance
+- [ ] 05 - Data Workflows
+- [ ] 06 - Real World Applications
+- [ ] misc - Miscellaneous
+
+## Checklist
+
+### Functionality
+- [ ] Example runs successfully with `flash run`
+- [ ] All endpoints return correct responses
+- [ ] Tested locally
+- [ ] Error handling implemented
+
+### Code Quality
+- [ ] Code follows project style guidelines
+- [ ] Type hints added for function signatures
+- [ ] Async functions used where appropriate
+- [ ] No hardcoded credentials
+- [ ] Proper logging (not print statements)
+
+### Documentation
+- [ ] README.md included with all required sections
+- [ ] Code comments added for complex logic
+- [ ] API endpoints documented
+- [ ] Deployment instructions included
+- [ ] `.env.example` file provided
+
+### Dependencies
+- [ ] All dependencies listed in `requirements.txt`
+- [ ] Dependencies are pinned to specific versions
+- [ ] `pyproject.toml` included with project metadata
+
+### Testing
+- [ ] Manually tested all endpoints
+- [ ] Unit tests added (if applicable)
+- [ ] No syntax errors (`python -m py_compile`)
+- [ ] Linting passes (if configured)
+
+### Security
+- [ ] No secrets or API keys committed
+- [ ] Input validation implemented
+- [ ] Security best practices followed
+
+## What This Example Demonstrates
+
+List the key concepts or patterns this example demonstrates:
+
+1.
+2.
+3.
+
+## Testing Instructions
+
+How should reviewers test this example?
+
+```bash
+# Steps to test
+cd path/to/example
+pip install -r requirements.txt
+# Add your test steps here
+```
+
+## Screenshots/Output (if applicable)
+
+Add screenshots or example output if relevant.
+
+## Additional Context
+
+Any additional information reviewers should know about this PR.
+
+## Related Issues
+
+Closes #(issue number)

.gitignore

@@ -205,3 +205,4 @@ cython_debug/
 marimo/_static/
 marimo/_lsp/
 __marimo__/
+*.pkl

.vscode/launch.json

@@ -0,0 +1,22 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Python Debugger: Current File",
+      "type": "debugpy",
+      "request": "launch",
+      "program": "${file}",
+      "console": "integratedTerminal",
+      "python": "${workspaceFolder}/.venv/bin/python",
+      "cwd": "${workspaceFolder}",
+      "envFile": "${workspaceFolder}/.env",
+      "env": {
+        "PYTHONPATH": "${workspaceFolder}"
+      },
+      "justMyCode": false
+    }
+  ]
+}

CONTRIBUTING.md

@@ -173,7 +173,7 @@ if __name__ == "__main__":
     import uvicorn
     import os
 
-    port = int(os.getenv("PORT", 8000))
+    port = int(os.getenv("PORT", 8888))
     uvicorn.run(app, host="0.0.0.0", port=port)
 ```
 
@@ -295,17 +295,51 @@ Test your example thoroughly:
 flash run
 
 # Test health endpoint
-curl http://localhost:8000/health
+curl http://localhost:8888/health
 
 # Test your endpoints
-curl -X POST http://localhost:8000/your/endpoint \
+curl -X POST http://localhost:8888/your/endpoint \
   -H "Content-Type: application/json" \
   -d '{"test": "data"}'
 
 # Check API docs
-open http://localhost:8000/docs
+open http://localhost:8888/docs
 ```
 
+### VS Code Debugging
+
+The repository includes VS Code debug configurations for endpoint development:
+
+**Setup:**
+
+1. Copy the root `.env.example` to `.env`:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Add your RunPod API key to `.env`:
+   ```bash
+   RUNPOD_API_KEY=your_actual_api_key_here
+   ```
+
+3. Ensure you have the Python extension installed in VS Code
+
+**Debugging:**
+
+Two debug configurations are available:
+
+- **Python Debugger: Current File** - Debug any Python file
+- **Flash Worker: Debug Endpoint** - Debug worker endpoint files with async support
+
+To debug an endpoint:
+1. Open any `endpoint.py` file (e.g., `01_getting_started/01_hello_world/workers/gpu/endpoint.py`)
+2. Set breakpoints in your worker functions
+3. Press F5 or select "Debug: Start Debugging"
+4. Choose the appropriate debug configuration
+5. The debugger will execute the `if __name__ == "__main__"` test block
+
+The `.env` file is automatically loaded, so your `RUNPOD_API_KEY` is available during debugging.
+
 ### Unit Tests (Recommended)
 
 Add tests for your worker functions:

README.md

@@ -23,21 +23,24 @@ cd flash-examples
 # Install dependencies (works with uv, pip, poetry, conda, or pipenv)
 make dev
 
-# Navigate to an example
-cd 01_getting_started/01_hello_world
+# Set your API key (choose one method):
 
-# Install example dependencies
-pip install -r requirements.txt
+# Option A: Export in shell (recommended for trying multiple examples)
+export RUNPOD_API_KEY=your_key_here
 
-# Set your API key
-echo "RUNPOD_API_KEY=your_key_here" > .env
+# Option B: Create .env file per example (if you prefer per-example config)
+# cd 01_getting_started/01_hello_world
+# echo "RUNPOD_API_KEY=your_key_here" > .env
 
-# Run locally
+# Try any example
+cd 01_getting_started/01_hello_world
 flash run
 
-# Visit http://localhost:8000/docs
+# Visit http://localhost:8888/docs
 ```
 
+**Note**: After running `make dev`, all example dependencies are installed. You can navigate to any example directory and run `flash run` immediately. The exported API key persists in your shell session across all examples.
+
 **Alternative Setup Methods:**
 - **With Makefile**: `make dev` (auto-detects your package manager)
 - **With uv**: `uv sync && uv pip install -e .`
@@ -115,12 +118,34 @@ Flash is FastAPI-centric for building production applications, while Modal focus
 
 ```bash
 flash init              # Create new Flash project
-flash run              # Run development server (default: localhost:8000)
+flash run              # Run development server (default: localhost:8888)
 flash build            # Build application for deployment
 flash deploy new <env> # Create deployment environment
 flash deploy send <env># Deploy to Runpod
 ```
 
+## Testing Your Application
+
+After running `flash run`, you can test your API in two ways:
+
+**Option A: Using the Interactive UI**
+
+Visit **http://localhost:8888/docs** to use FastAPI's built-in Swagger UI where you can:
+- See all available endpoints
+- Test requests directly in your browser
+- View request/response schemas
+
+**Option B: Using curl**
+
+Test endpoints from the command line:
+```bash
+curl -X POST http://localhost:8888/endpoint \
+  -H "Content-Type: application/json" \
+  -d '{"key": "value"}'
+```
+
+See individual example READMEs for specific endpoint examples.
+
 ## Example Structure
 
 Each example follows this structure: