docs: Update README with containerless local development workflow

[manavgup]

Summary

Major update to README.md to reflect our new containerless local development paradigm.

Changes

1. Quick Start Reorganization

• Option 1: Local Development (⚡ Fastest - Recommended)

  • Step-by-step guide for containerless development
  • Clear venv activation instructions
  • Benefits and when to use

• Option 2: Production Mode (🐳 Docker)

  • For production-like testing
  • Uses pre-built GHCR images or local builds

• Option 3: GitHub Codespaces (☁️ Cloud)

  • For quick experimentation and onboarding

2. Development Workflow

• Recommended Daily Workflow: Morning setup → dev cycle → cleanup
• Essential Commands Table: With 'When to Use' guidance
• Testing & Quality: Local pytest commands + Makefile targets
• Container Development: Only when needed for production testing

3. Enhanced Troubleshooting

• 🐍 Virtual Environment Issues:

  • How to fix make venv problems
  • Fixing wrong tool versions (Ruff 0.5.7 vs 0.14.0)
  • Poetry installation issues

• 🐳 Docker Issues: Infrastructure service troubleshooting

• 📦 Dependency Issues: Import errors and missing modules

• Reference: Points to IMMEDIATE_FIX.md

4. Added Documentation

• IMMEDIATE_FIX.md: Quick guide for Ruff version mismatch
• Issue templates for future improvements:
  • makefile-streamline.md
  • optimize-cicd-builds.md

Philosophy

Develop locally without containers (maximum speed)
Deploy with containers (production readiness)

Related Issues

Addresses documentation needs after recent PR merges:

• fix: Remove 4 unused dependencies from production image #333, feat: Add document upload endpoint and improve error handling #341, feat: Implement real file upload in collection creation modal #342, feat: Add production deployment and improve local development #343, docs: Update documentation with latest accomplishments and features #344 (all recently merged)

Prepares for future improvements:

• Makefile streamlining (1,702 lines → ~500 lines)
• CI/CD optimization (build containers weekly, not per PR)

[github-actions]

🚀 Development Environment Options

This repository supports Dev Containers for a consistent development environment.

Option 1: GitHub Codespaces (Recommended)

Create a cloud-based development environment:

1. Click the green Code button above
2. Select the Codespaces tab
3. Click Create codespace on docs/update-readme-local-dev
4. Wait 2-3 minutes for environment setup
5. Start coding with all tools pre-configured!

Option 2: VS Code Dev Containers (Local)

Use Dev Containers on your local machine:

1. Install Docker Desktop
2. Install VS Code
3. Install the Dev Containers extension
4. Clone this PR branch locally
5. Open in VS Code and click "Reopen in Container" when prompted

Option 3: Traditional Local Setup

Set up the development environment manually:

# Clone the repository
git clone https://github.com/manavgup/rag_modulo.git
cd rag_modulo
git checkout docs/update-readme-local-dev

# Initialize development environment
make dev-init
make dev-build
make dev-up
make dev-validate

Available Commands

Once in your development environment:

make help           # Show all available commands
make dev-validate   # Validate environment setup
make test-atomic    # Run atomic tests
make test-unit      # Run unit tests
make lint          # Run linting

Services Available

When running make dev-up:

• Backend API: http://localhost:8000
• Frontend: http://localhost:3000
• MLflow: http://localhost:5001

---

This automated message helps reviewers quickly set up the development environment.

[claude]

PR Review: Documentation Update for Containerless Development

Overall Assessment

Verdict: Approve with minor suggestions

This PR significantly improves the developer experience by clearly documenting the containerless local development workflow.

Strengths

1. Excellent Documentation Structure - Clear separation of three development modes
2. Philosophy Clarity - "Develop locally without containers, deploy with containers" is excellent
3. Troubleshooting Section - IMMEDIATE_FIX.md addresses real issues
4. Future Planning - Issue templates show clear roadmap

Critical Issues (Must Fix Before Merge)

1. Directory Name Inconsistency (CRITICAL)

Lines 84, 98, 227 in README.md: References to frontend/ directory

Issue: According to CLAUDE.md, the frontend is in webui/ not frontend/

Fix: Change all frontend/ to webui/ throughout README.md

2. Hardcoded Personal Path

IMMEDIATE_FIX.md line 14: cd /Users/mg/mg-work/manav/work/ai-experiments/rag_modulo

Fix: Replace with generic instruction or remove personal path

3. Wrong Branch Reference

IMMEDIATE_FIX.md line 40: git push origin pr-02-backend-upload-error-handling

Fix: Use generic placeholder like <your-branch-name>

Code Quality Scores

• Documentation Quality: 9/10
• Best Practices Alignment: 9/10
• Maintainability: 8/10

Security

No security concerns - documentation only changes.

Recommendations

Before Merge (Critical):

1. Fix all frontend/ to webui/ directory references
2. Remove hardcoded personal path
3. Fix branch name reference

Nice to Have (Follow-up):

4. Add quick reference card for common commands
5. Simplify issue templates (currently 272+ lines)
6. Test instructions with fresh clone

Final Recommendation

APPROVE with requested changes

Fix items 1-3 before merge. This is excellent work that will significantly improve developer onboarding.

---

Reviewed by: Claude Code
Review Date: 2025-10-09

[claude]

Pull Request Review - Critical Issues Found

Thank you for this comprehensive documentation update! This PR significantly improves the developer onboarding experience. However, I found several critical issues that need fixing before merge.

---

CRITICAL: Missing Makefile Target

Problem: README recommends 'make run-infra' (lines 87, 224, 251) but this target does not exist in the Makefile.

Reality: The actual target is 'local-dev-infra' (found at Makefile:327)

Fix Required: Replace all 'make run-infra' with 'make local-dev-infra' at these locations:

• Line 87
• Line 154
• Line 224
• Line 251

---

Other Issues

1. Missing IMMEDIATE_FIX.md: Line 764 references IMMEDIATE_FIX.md but this file is not included in the PR. Either include it or remove the reference.

2. Directory naming inconsistency: README uses 'frontend' directory but CLAUDE.md says 'webui/'. The actual directory is 'frontend/' (verified). Update CLAUDE.md to match.

3. Codespaces instructions: Step 4 references the non-existent 'make run-infra' target. Update to use correct command.

---

Strengths

• Excellent developer experience focus with clear progression from local to Docker to cloud
• Comprehensive troubleshooting sections with collapsible details
• Clear command reference tables with When to Use guidance
• Good alignment with project philosophy
• Proper use of markdown formatting and visual hierarchy

---

Verified Commands

Testing commands are accurate (verified in Makefile):

• make test-unit-fast exists (Makefile:899)
• make test-integration exists (Makefile:903)
• make quick-check exists (Makefile:1446)

---

Recommendation

Overall Assessment: 4/5 stars

Status: Request Changes

The documentation is excellent overall, but the broken 'make run-infra' command will cause immediate confusion for new developers. Once this critical issue is fixed, this will be ready to merge.

Great work on improving the developer documentation! The containerless workflow is a significant improvement to development velocity.