Add local repo scan import

INSTALL.md

@@ -139,21 +139,32 @@ docker run -d \
   -v ./data:/app/data \
   -v /Users/you/Development:/Users/you/Development:ro \
   -e ANTHROPIC_API_KEY=your_key_here \
+  -e PROJECTS_DIR=/Users/you/Development \
   ericblue/vibefocus:latest
 ```
 
 Replace `/Users/you/Development` with the parent directory where your git repos live. The path inside the container must match the host path so that `local_path` values on your projects resolve correctly. The `:ro` flag makes it read-only.
 
-If using `docker-compose.yml`, uncomment the volume mount line and set your path:
+If using `docker-compose.yml`, set `PROJECTS_DIR` before starting the container:
 
-```yaml
-volumes:
-  - ./data:/app/data
-  - /Users/you/Development:/Users/you/Development:ro
+```bash
+PROJECTS_DIR=/Users/you/Development docker compose up -d --build
 ```
 
 Without this mount, VibeFocus still works but analytics (heatmaps, velocity, streaks) will be empty and code analysis won't be available.
 
+### Importing Existing Local Repos
+
+After startup, open Settings and use **Import Local Git Repositories**. Enter the parent folder that contains your repos, for example `/Users/you/Development`, then click **Scan Repositories**. VibeFocus creates missing projects, updates matching projects by local path or GitHub URL, infers GitHub URLs from `origin`, and refreshes lightweight git stats like branch, dirty status, and latest commit.
+
+If the Settings page says the directory is missing, the backend cannot see that path. For Docker, restart with the folder mounted:
+
+```bash
+PROJECTS_DIR=/Users/you/Development docker compose up -d --build
+```
+
+From source, set `PROJECTS_DIR` in `backend/.env` or enter the absolute path in Settings. Re-running a scan is safe; it updates existing projects without importing commit logs. Use Analytics sync later when you want heatmaps, velocity, streaks, and health history.
+
 ### From Source
 
 ```bash

Makefile

@@ -9,6 +9,7 @@ MCP_VENV    := $(MCP_DIR)/venv
 BE_PORT     ?= 8000
 FE_PORT     ?= 5173
 PYTHON      ?= /opt/homebrew/bin/python3.12
+PROJECTS_DIR ?=
 
 # ── Version (single source of truth: VERSION file) ──────────────────────────
 CURRENT_VERSION := $(shell cat VERSION 2>/dev/null || echo "0.0.0")
@@ -20,7 +21,7 @@ DOCKER_TAG      ?= $(CURRENT_VERSION)
 
 # ── Install / Setup ──────────────────────────────────────────────────────────
 
-.PHONY: install install-fe install-be install-mcp
+.PHONY: install install-fe install-be install-mcp import-projects
 
 install: install-fe install-be install-mcp ## Install all dependencies
 
@@ -33,6 +34,13 @@ install-be: ## Create venv and install backend dependencies
 install-mcp: ## Create venv and install MCP server dependencies
 	cd $(MCP_DIR) && $(PYTHON) -m venv venv && . venv/bin/activate && pip install -r requirements.txt
 
+import-projects: ## Import local git repos into VibeFocus (PROJECTS_DIR=/path/to/repos)
+	@if [ -z "$(PROJECTS_DIR)" ]; then \
+		echo "PROJECTS_DIR is required. Example: make import-projects PROJECTS_DIR=/path/to/repos"; \
+		exit 1; \
+	fi
+	cd $(BE_DIR) && . venv/bin/activate && python import_local_projects.py --root "$(PROJECTS_DIR)"
+
 # ── Frontend ─────────────────────────────────────────────────────────────────
 
 .PHONY: fe fe-build fe-stop

README.md

@@ -62,7 +62,9 @@ docker run -d -p 8000:8000 \
   ericblue/vibefocus:latest
 ```
 
-Open http://localhost:8000. The volume mount to your projects directory enables git sync, code analysis, and AI code exploration.
+Open http://localhost:8000. The volume mount to your projects directory enables local repo import, git sync, code analysis, and AI code exploration.
+
+On a fresh install, open Settings and use **Import Local Git Repositories** to scan the folder you mounted or configured. The scan creates projects and refreshes lightweight git stats only; use Analytics sync later when you want commit history.
 
 ### From Source
 

backend/.env.example

@@ -2,3 +2,6 @@ ANTHROPIC_API_KEY=your_api_key_here
 DATABASE_URL=sqlite:///./vibefocus.db
 CORS_ORIGINS=http://localhost:5173
 PORT=8000
+
+# Optional: parent folder containing local git repositories.
+# PROJECTS_DIR=~/Development

backend/database.py

@@ -4,10 +4,11 @@
 
 
 class Settings(BaseSettings):
-    anthropic_api_key: str
+    anthropic_api_key: str | None = None
     database_url: str = "sqlite:///./vibefocus.db"
     cors_origins: str = "http://localhost:5173"
     port: int = 8000
+    projects_dir: str | None = None
 
     model_config = SettingsConfigDict(env_file=".env", extra="ignore")