Create README.md

README.md

@@ -0,0 +1,746 @@
+# 🤖 AI Codebase Assistant — Complete Documentation
+
+> An AI-powered developer tool that ingests any local code repository, answers questions about it using RAG (Retrieval-Augmented Generation), detects bugs, measures complexity, generates docs, proposes new files, and integrates with the GitHub MCP API — all from an interactive CLI.
+
+---
+
+## Table of Contents
+
+1. [Project Overview](#1-project-overview)
+2. [Repository Structure](#2-repository-structure)
+3. [Architecture & Flow](#3-architecture--flow)
+4. [Component Deep-Dive](#4-component-deep-dive)
+5. [Setup & Installation](#5-setup--installation)
+6. [Configuration (.env)](#6-configuration-env)
+7. [Running the CLI](#7-running-the-cli)
+8. [CLI Features — All 9 Options](#8-cli-features--all-9-options)
+9. [REST API](#9-rest-api)
+10. [Key Design Decisions & Bug Fixes](#10-key-design-decisions--bug-fixes)
+11. [Extending the Project](#11-extending-the-project)
+
+---
+
+## 1. Project Overview
+
+The **AI Codebase Assistant** is a local developer tool that:
+
+- 📂 **Ingests** any code repository (Python, JS, TS, Java, Go, Markdown)
+- 🔍 **Answers questions** about the code using RAG + LLM
+- 🐛 **Detects bugs** via LLM-powered code review
+- 📊 **Measures cyclomatic complexity** using Radon
+- 📝 **Explains functions** in plain English
+- 📄 **Generates module docs and READMEs** automatically
+- 🛠️ **Proposes & creates new files** using AI, saved to your chosen directory
+- 🔗 **Lists 44 GitHub MCP tools** via the GitHub Copilot MCP API
+
+**LLM Providers supported:**
+| Provider | Model | Notes |
+|---|---|---|
+| Groq | `llama-3.3-70b-versatile` | Free tier, recommended |
+| Gemini | Configurable | Paid, stricter quota |
+
+**Embedding:** Google Gemini Embedding API (`models/gemini-embedding-001`)  
+**Vector Store:** ChromaDB (local persistent)
+
+---
+
+## 2. Repository Structure
+
+```
+Codebase Assistant/
+│
+├── cli.py                     # ← Main entry point (interactive CLI)
+├── app.py                     # ← FastAPI REST server (optional)
+├── config.py                  # ← All settings via pydantic-settings + .env
+├── llm.py                     # ← LLM abstraction (Gemini / Groq) + prompt templates
+├── mcp_client.py              # ← GitHub MCP async context-manager client
+├── requirements.txt           # ← All Python dependencies
+├── .env                       # ← API keys and configuration (not committed)
+│
+├── rag/                       # ── RAG Pipeline ──────────────────────────────
+│   ├── repository_loader.py   #   Walk directory, read files → CodeDocument
+│   ├── splitter.py            #   Split CodeDocuments into chunks with metadata
+│   ├── embedding.py           #   Embed chunks/queries via Gemini Embeddings
+│   ├── retriever.py           #   ChromaDB vector store: build / load / query
+│   └── rag_chain.py           #   Orchestrate retrieve → build context → LLM
+│
+├── services/                  # ── Feature Services ──────────────────────────
+│   ├── code_analysis.py       #   Bug detection, complexity, function explainer
+│   ├── documentation.py       #   Module docs, README generator
+│   └── file_creator.py        #   AI file proposal + local disk write
+│
+├── api/                       # ── REST API (FastAPI) ────────────────────────
+│   └── routes.py              #   All HTTP endpoints (mirrors CLI features)
+│
+└── vector_db/                 # ── ChromaDB Storage (auto-created) ───────────
+    └── chroma.sqlite3         #   Persisted vector embeddings
+```
+
+---
+
+## 3. Architecture & Flow
+
+### 3.1 Full System Architecture
+
+```mermaid
+graph TB
+    subgraph USER["User Interface"]
+        CLI["cli.py\n(Interactive CLI)"]
+        API["app.py\n(FastAPI REST API)"]
+    end
+
+    subgraph RAG["RAG Pipeline"]
+        RL["repository_loader.py\nWalk & read files"]
+        SP["splitter.py\nChunk by language"]
+        EM["embedding.py\nGemini Embeddings"]
+        RT["retriever.py\nChromaDB"]
+        RC["rag_chain.py\nOrchestrator"]
+    end
+
+    subgraph SERVICES["Feature Services"]
+        CA["code_analysis.py\nBugs · Complexity · Explain"]
+        DOC["documentation.py\nModule Docs · README"]
+        FC["file_creator.py\nAI File Creator"]
+    end
+
+    subgraph EXTERNAL["External APIs"]
+        GROQ["Groq API\nllama-3.3-70b"]
+        GEM["Gemini API\nEmbeddings"]
+        MCP["GitHub MCP\n44 tools"]
+    end
+
+    LLM["llm.py\nLLM Abstraction Layer"]
+    CFG["config.py\n.env Settings"]
+    DB[("vector_db/\nChromaDB")]
+
+    CLI --> RAG
+    CLI --> SERVICES
+    API --> RAG
+    API --> SERVICES
+
+    RL --> SP --> EM --> RT
+    RT --> DB
+    RC --> RT
+    RC --> LLM
+
+    CA --> LLM
+    DOC --> LLM
+    FC --> LLM
+
+    LLM --> GROQ
+    LLM --> GEM
+    EM --> GEM
+    CLI --> MCP
+
+    CFG -.->|settings| RAG
+    CFG -.->|settings| LLM
+    CFG -.->|settings| SERVICES
+```
+
+### 3.2 Ingest Flow (Step-by-step)
+
+```mermaid
+flowchart LR
+    A["User provides\nrepo path"] --> B["repository_loader.py\nwalk directories\nskip: .git venv __pycache__"]
+    B --> C["Filter by\nallowed extensions\n.py .js .ts .java .go .md"]
+    C --> D["Read each file\n→ CodeDocument\n(content, path, language, size)"]
+    D --> E["splitter.py\nLanguage-aware chunking\nRecursiveCharacterTextSplitter"]
+    E --> F["Each chunk gets\nmetadata: file_path\nlanguage · start_line · end_line"]
+    F --> G["embedding.py\nGemini embed_documents\n→ float vectors"]
+    G --> H["retriever.py\nDelete old collection\nCreate fresh ChromaDB\ncollection.add(...)"]
+    H --> I["✓ Vector store ready"]
+```
+
+### 3.3 RAG Query Flow
+
+```mermaid
+flowchart LR
+    Q["User question"] --> E["embed_query\n(Gemini)"]
+    E --> S["ChromaDB\ncollection.query\ntop-k chunks"]
+    S --> C["build_context\nformat chunks\nwith file/line headers"]
+    C --> P["build_prompt\nqa template\ncontext + question"]
+    P --> L["LLM\n(Groq / Gemini)"]
+    L --> A["Answer + Sources\n(file_path, line range)"]
+```
+
+### 3.4 CLI Menu Flow
+
+```mermaid
+flowchart TD
+    START([Start cli.py]) --> REPO["▶ Enter repo path"]
+    REPO --> INGEST["Ingest Repository\nload → split → embed → store"]
+    INGEST --> MENU["Show Menu\nOptions 1–9"]
+
+    MENU --> O1["1 Ask a question\n→ RAG Query"]
+    MENU --> O2["2 Detect bugs\n→ LLM code review"]
+    MENU --> O3["3 Cyclomatic complexity\n→ Radon"]
+    MENU --> O4["4 Explain function\n→ AST + LLM"]
+    MENU --> O5["5 Module docs\n→ LLM"]
+    MENU --> O6["6 Generate README\n→ LLM"]
+    MENU --> O7["7 Propose & create file\n→ LLM + local write"]
+    MENU --> O8["8 List GitHub MCP tools\n→ GitHub Copilot MCP"]
+    MENU --> O9["9 Re-ingest repo\n→ new repo path"]
+    MENU --> O0["0 Exit"]
+
+    O1 & O2 & O3 & O4 & O5 & O6 & O7 & O8 & O9 --> MENU
+    O0 --> END([Goodbye!])
+```
+
+---
+
+## 4. Component Deep-Dive
+
+### 4.1 `config.py` — Settings
+
+All configuration lives in one `pydantic-settings` class loaded from `.env`:
+
+| Setting | Default | Description |
+|---|---|---|
+| `llm_provider` | `"groq"` | `"groq"` or `"gemini"` |
+| `groq_api_key` | `""` | From `.env` |
+| `groq_model` | `"llama-3.3-70b-versatile"` | Free Groq model |
+| `gemini_api_key` | `""` | From `.env` |
+| `embedding_model` | `"models/gemini-embedding-001"` | Always Gemini for embeddings |
+| `vector_db_path` | `"./vector_db"` | ChromaDB storage directory |
+| `chunk_size` | `1200` | Characters per chunk |
+| `chunk_overlap` | `100` | Overlap between chunks |
+| `allowed_extensions` | `[.py .js .ts .go .java .md]` | File types to load |
+| `max_file_size_kb` | `1042` | Skip files larger than this |
+| `github_mcp_url` | GitHub Copilot MCP endpoint | For option 8 |
+| `github_mcp_token` | `""` | GitHub PAT from `.env` |
+
+### 4.2 `rag/repository_loader.py` — File Ingestion
+
+```
+load_repository(root_path)
+  └── os.walk(root_path)
+        ├── Skip: .git, node_modules, __pycache__, venv, .venv, dist, build
+        ├── should_include(fpath) → checks extension + file size
+        └── read_file_with_metadata(fpath) → CodeDocument(content, file_path, language, size_bytes)
+```
+
+**Supported languages detected by extension:**
+
+| Extension | Language |
+|---|---|
+| `.py` | python |
+| `.js` | javascript |
+| `.ts` | typescript |
+| `.java` | java |
+| `.go` | go |
+| `.md` | markdown |
+
+### 4.3 `rag/splitter.py` — Chunking
+
+Uses **LangChain's `RecursiveCharacterTextSplitter`** with language-aware splitting:
+- For Python/JS/TS/Java/Go — uses syntax-aware boundaries (functions, classes)
+- For Markdown/unknown — falls back to generic character splitting
+- Each chunk carries: `content`, `file_path`, `language`, `chunk_index`, `start_line`, `end_line`
+
+### 4.4 `rag/embedding.py` — Embeddings
+
+- Uses `GoogleGenerativeAIEmbeddings` (`models/gemini-embedding-001`)
+- `embed_document(chunks)` — batch embeds all chunks, mutates dicts in-place
+- `embed_query(query)` — single query vector for similarity search
+
+### 4.5 `rag/retriever.py` — Vector Store
+
+> **Critical fix applied:** collection is deleted and recreated on every ingest to prevent stale data from previous repos bleeding through.
+
+```python
+build_vector_store(chunks)     # delete → create → add (fresh each ingest)
+load_vector_store()            # get_or_create for reading
+retrieve_relevant_chunks(q, k) # embed query → cosine similarity → top-k
+```
+
+### 4.6 `rag/rag_chain.py` — Orchestration
+
+```python
+run_rag_query(query, k=5)
+  1. retrieve_relevant_chunks(query, k)
+  2. build_context(chunks)         # format with file/line headers
+  3. build_prompt(query, context)  # fill qa template
+  4. llm.generate(prompt)
+  5. return { answer, sources }
+```
+
+### 4.7 `llm.py` — LLM Abstraction
+
+Abstract `BaseLLM` with two concrete providers:
+
+| Class | Provider | API |
+|---|---|---|
+| `GeminiLLM` | Google Gemini | `google-genai` SDK |
+| `GroqLLM` | Groq | `groq` SDK, chat completions |
+
+**Prompt templates (`build_prompt`):**
+
+| `task_type` | Used by |
+|---|---|
+| `"qa"` | RAG query, function explain, module docs, README |
+| `"bug_finding"` | Bug detection (returns JSON) |
+| `"docstring"` | Docstring generation |
+| `"file_creation"` | AI file proposal |
+
+### 4.8 `mcp_client.py` — GitHub MCP Client
+
+Async context-manager pattern using `AsyncExitStack` to keep all `anyio` cancel scopes in the **same task**:
+
+```python
+async with get_github_mcp_client() as client:
+    tools = await client.list_tools()
+    result = await client.call_tool("create_branch", {...})
+```
+
+Available GitHub MCP tools (44 total) include: `search_code`, `list_issues`, `create_pull_request`, `get_file_contents`, `push_files`, `create_branch`, `fork_repository`, `search_repositories`, and many more.
+
+### 4.9 `services/code_analysis.py`
+
+| Function | How it works |
+|---|---|
+| `explain_function(file, name)` | Python `ast` extracts the function source → RAG context → LLM |
+| `detect_bugs(file)` | Read file → `bug_finding` prompt → LLM returns JSON list |
+| `analyze_complexity(file)` | `radon.cc_visit` → cyclomatic complexity + rank A–F |
+
+### 4.10 `services/file_creator.py`
+
+```
+propose_new_file(description, context_query)
+  ├── RAG retrieve relevant context
+  ├── build_prompt(description, context, "file_creation")
+  ├── LLM generates complete file content
+  └── infer_file_path(description) → LLM suggests relative path
+
+apply_approved_file(proposal, confirmed, base_dir)
+  ├── Strip leading / or \ from LLM path
+  ├── os.path.join(base_dir, relative_path)
+  ├── os.makedirs(parent_dirs, exist_ok=True)
+  └── open(abs_path, "w").write(content)
+```
+
+---
+
+## 5. Setup & Installation
+
+### Prerequisites
+
+| Requirement | Version |
+|---|---|
+| Python | 3.11+ |
+| pip | Latest |
+| Internet | For API calls |
+
+### Step 1 — Clone / Download the project
+
+```bash
+git clone <your-repo-url>
+cd "Codebase Assistant"
+```
+
+### Step 2 — Create a virtual environment
+
+```bash
+# Windows (PowerShell)
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+
+# macOS / Linux
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+### Step 3 — Install dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+> [!TIP]
+> If you hit permission issues on Windows, use:
+> `pip install -r requirements.txt --user`
+
+### Step 4 — Create your `.env` file
+
+Create a file named `.env` in the project root:
+
+```env
+# Choose your LLM provider: "groq" (free) or "gemini"
+LLM_PROVIDER=groq
+
+# Groq — free at https://console.groq.com
+GROQ_API_KEY=gsk_your_key_here
+
+# Gemini — get at https://aistudio.google.com
+GEMINI_API_KEY=your_gemini_key_here
+
+# GitHub PAT for MCP tools — create at https://github.com/settings/tokens
+# Required scopes: repo, read:org
+GITHUB_MCP_TOKEN=github_pat_your_token_here
+```
+
+> [!IMPORTANT]
+> `GEMINI_API_KEY` is **always required** regardless of LLM provider, because embeddings always use Gemini.
+
+### Step 5 — Run the CLI
+
+```bash
+.venv\Scripts\python.exe cli.py     # Windows
+python cli.py                        # macOS / Linux
+```
+
+---
+
+## 6. Configuration (.env)
+
+```env
+# ─── LLM Provider ────────────────────────────────────────
+LLM_PROVIDER=groq          # "groq" | "gemini"
+
+# ─── Groq (recommended — free tier) ─────────────────────
+GROQ_API_KEY=gsk_...
+GROQ_MODEL=llama-3.3-70b-versatile
+
+# ─── Gemini ──────────────────────────────────────────────
+GEMINI_API_KEY=...
+LLM_MODEL=gemini-1.5-flash        # only used if LLM_PROVIDER=gemini
+EMBEDDING_MODEL=models/gemini-embedding-001
+
+# ─── RAG / Vector DB ─────────────────────────────────────
+VECTOR_DB_PATH=./vector_db
+CHUNK_SIZE=1200
+CHUNK_OVERLAP=100
+
+# ─── File loader ─────────────────────────────────────────
+# comma-separated extensions
+ALLOWED_EXTENSIONS=[".py",".js",".ts",".go",".java",".md"]
+MAX_FILE_SIZE_KB=1042
+
+# ─── GitHub MCP ──────────────────────────────────────────
+GITHUB_MCP_URL=https://api.githubcopilot.com/mcp/
+GITHUB_MCP_TOKEN=github_pat_...
+```
+
+---
+
+## 7. Running the CLI
+
+```
+╔══════════════════════════════════════════╗
+║       AI  Codebase  Assistant  CLI       ║
+╚══════════════════════════════════════════╝
+
+▶ Enter the path to the repository you want to analyse: D:\MyProject
+
+── Ingesting Repository ──────────────────────
+  Loading files from: D:\MyProject
+  ✓  Loaded 12 files
+  ✓  Split into 47 chunks
+  Embedding chunks (this may take a moment)...
+  ✓  Embedded 47 chunks
+  ✓  Vector store ready (ChromaDB)
+
+── What would you like to do? ────────────────
+   1  Ask a question about the codebase
+   2  Detect bugs in a file
+   3  Cyclomatic complexity analysis
+   4  Explain a function
+   5  Generate module documentation
+   6  Generate README for a repository
+   7  Propose & create a new file (AI)
+   8  List GitHub MCP tools
+   9  Re-ingest a repository
+    0  Exit
+
+▶ Choose an option [0–9]:
+```
+
+---
+
+## 8. CLI Features — All 9 Options
+
+### Option 1 — Ask a Question (RAG Query)
+
+```
+▶ Your question: How does the authentication work?
+▶ Number of source chunks to retrieve? [default: 5] 3
+
+── Answer ────────────────────────────────────
+The authentication uses JWT tokens ...
+
+── Sources ───────────────────────────────────
+  • src/auth/middleware.py  lines 12–45
+  • src/auth/tokens.py  lines 1–30
+```
+
+**Pipeline:** Embed question → ChromaDB similarity search → Build context → LLM → Answer + cited sources
+
+---
+
+### Option 2 — Detect Bugs
+
+```
+▶ File path to analyse: src/payment.py
+
+── Found 2 issue(s) ──────────────────────────
+  [HIGH] Line 34: SQL query uses string concatenation
+    → Use parameterized queries to prevent SQL injection
+
+  [MEDIUM] Line 67: Exception swallowed silently
+    → Log or re-raise the exception
+```
+
+**Pipeline:** Read file → `bug_finding` prompt → LLM returns JSON → parsed and displayed
+
+---
+
+### Option 3 — Cyclomatic Complexity
+
+```
+▶ File path to analyse: src/processor.py
+
+── 4 function(s) ─────────────────────────────
+  [A]  process_order              complexity=2  ██
+  [B]  validate_cart              complexity=5  █████
+  [C]  apply_discounts            complexity=8  ████████
+  [F]  handle_edge_cases          complexity=18 ██████████████████
+```
+
+**Rank scale:** A (1–5, simple) → F (26+, untestable)
+
+---
+
+### Option 4 — Explain a Function
+
+```
+▶ File path: src/utils.py
+▶ Function name: parse_date_range
+
+── Explanation ───────────────────────────────
+parse_date_range takes a string like "2024-01-01:2024-12-31"
+and returns a tuple of (start_date, end_date) as datetime objects ...
+```
+
+**Pipeline:** Python `ast` module extracts exact function source → RAG retrieves usages → LLM explains
+
+---
+
+### Option 5 — Generate Module Documentation
+
+```
+▶ File path: src/database.py
+
+── Documentation ─────────────────────────────
+## database.py
+
+### Overview
+This module provides the database connection layer ...
+
+### Functions
+- `connect(url)` — Establishes a connection ...
+- `execute(query, params)` — Runs a parameterized query ...
+```
+
+---
+
+### Option 6 — Generate README
+
+```
+▶ Repository root path: D:\MyProject
+
+── README Preview ────────────────────────────
+# MyProject
+
+## Overview
+A FastAPI application that ...
+
+▶ Save to README.md in that directory? [y/N] y
+  ✓  Saved to D:\MyProject\README.md
+```
+
+---
+
+### Option 7 — Propose & Create a New File
+
+```
+▶ Describe the file you want to create: Rectangle area calculator in JavaScript
+▶ Optional context query (or press Enter to skip):
+
+── Proposed File ─────────────────────────────
+  Path:  /src/geometry/rectangle.js
+
+  class Rectangle { ...full generated code... }
+
+▶ Write this file to disk? [y/N] y
+▶ Save under which directory? [default: D:\MyProject]
+
+  ✓  File written: D:\MyProject\src\geometry\rectangle.js
+```
+
+**Pipeline:** RAG context (optional) → `file_creation` prompt → LLM generates code → user confirms → write to `base_dir/relative_path`
+
+---
+
+### Option 8 — List GitHub MCP Tools
+
+```
+── List GitHub MCP Tools ─────────────────────
+  44 tools available:
+    • create_branch                   Create a new branch in a GitHub repository
+    • create_pull_request             Create a new pull request ...
+    • search_code                     Fast and precise code search ...
+    • list_issues                     List issues in a GitHub repository ...
+    ...
+```
+
+**Connection:** Uses `streamable_http_client` → `ClientSession` → GitHub Copilot MCP endpoint
+
+---
+
+### Option 9 — Re-ingest a Repository
+
+```
+▶ New repository path to ingest: D:\AnotherProject
+── Ingesting Repository ──────────────────────
+  ✓  Loaded 8 files ...
+```
+
+Wipes the ChromaDB collection and ingests the new repo fresh. All subsequent queries answer from the new repo only.
+
+---
+
+## 9. REST API
+
+Start the FastAPI server:
+
+```bash
+.venv\Scripts\python.exe -m uvicorn app:app --reload --port 8000
+```
+
+Open docs at: `http://localhost:8000/docs`
+
+### Endpoints
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/health` | Health check |
+| `POST` | `/api/query` | RAG question answering |
+| `POST` | `/api/analyze/bugs?file_path=...` | Bug detection |
+| `POST` | `/api/analyze/complexity?file_path=...` | Cyclomatic complexity |
+| `POST` | `/api/analyze/explain` | Explain a function |
+| `POST` | `/api/docs/module?file_path=...` | Module documentation |
+| `POST` | `/api/docs/readme?root_path=...` | README generation |
+| `POST` | `/api/files/propose` | Propose a new file |
+| `POST` | `/api/files/approve` | Write approved file to disk |
+
+### Example — Query
+
+```bash
+curl -X POST http://localhost:8000/api/query \
+  -H "Content-Type: application/json" \
+  -d '{"query": "How does authentication work?", "k": 5}'
+```
+
+```json
+{
+  "answer": "Authentication is handled by ...",
+  "sources": [
+    {"file_path": "src/auth.py", "start_line": 10, "end_line": 45}
+  ]
+}
+```
+
+---
+
+## 10. Key Design Decisions & Bug Fixes
+
+### Bug Fix 1 — Collection Isolation (retriever.py)
+
+**Problem:** ChromaDB used `upsert` on a shared `"codebase"` collection — stale chunks from previously ingested repos leaked into new queries.
+
+**Fix:** On every ingest, `delete_collection` + `create_collection` ensures a clean slate:
+
+```python
+# Before (bug)
+collection = client.get_or_create_collection("codebase")
+collection.upsert(...)
+
+# After (fix)
+client.delete_collection("codebase")   # wipe old repo
+collection = client.create_collection("codebase")
+collection.add(...)
+```
+
+---
+
+### Bug Fix 2 — GitHub MCP Cancel Scope (mcp_client.py)
+
+**Problem:** Manually calling `__aenter__`/`__aexit__` on `anyio`-backed context managers across tasks causes `RuntimeError: Attempted to exit cancel scope in a different task`.
+
+**Fix:** Use `AsyncExitStack` to nest all context managers inside a single `async with`:
+
+```python
+async with get_github_mcp_client() as client:
+    tools = await client.list_tools()
+```
+
+---
+
+### Bug Fix 3 — Wrong Unpack Count (mcp_client.py)
+
+**Problem:** `streamable_http_client` yields 2 values, not 3. Unpacking 3 caused `ValueError: not enough values to unpack`.
+
+```python
+# Before (bug)
+read, write, _ = await ctx.__aenter__()
+
+# After (fix)
+read, write = await stack.enter_async_context(streamable_http_client(...))
+```
+
+---
+
+### Bug Fix 4 — File Save Path (file_creator.py)
+
+**Problem:** Generated files saved to the current working directory regardless of user input.
+
+**Fix:** 
+- Strip leading `/\` from LLM path to make it always relative
+- Accept `base_dir` defaulting to `_current_repo` (the ingested repo path)
+- Create all parent directories automatically
+
+---
+
+## 11. Extending the Project
+
+### Add a new LLM provider
+
+1. Add a new class in `llm.py` extending `BaseLLM`
+2. Add the provider name to `get_llm_client()` factory
+3. Add matching settings in `config.py`
+
+### Add support for new file types
+
+1. Add extension → language in `LANGUAGE_BY_EXT` in `repository_loader.py`
+2. Add extension to `allowed_extensions` in `config.py`
+3. If LangChain has a `Language` enum for it, add to `LANGUAGE_MAP` in `splitter.py`
+
+### Use a GitHub MCP tool in a feature
+
+```python
+async with get_github_mcp_client() as client:
+    result = await client.call_tool("create_branch", {
+        "owner": "myuser",
+        "repo": "myrepo",
+        "branch": "feature/new-branch",
+        "from_branch": "main"
+    })
+```
+
+### Add a new CLI option
+
+1. Write a `feature_xxx()` function in `cli.py`
+2. Add `("Label", feature_xxx)` to the `MENU` list
+3. Add a matching FastAPI endpoint in `api/routes.py`
+
+---
+