# Repository Intelligence Platform — End-to-End Execution Guide

This guide describes how to set up, build, package, run, and validate the Repository Intelligence Platform from scratch.

---

## 1. Prerequisites

Before setting up the platform, ensure your environment meets the following specifications:

- **OS**: Windows, macOS, or Linux (Ubuntu 20.04+)
- **Python**: Version `>=3.9` (validated against Python `3.10`, `3.11`, and `3.12` in development)
- **Node.js**: Version `18` or higher (LTS recommended)
- **npm**: Version `9.x` or `10.x`
- **VS Code**: `v1.85.0` or higher
- **Git**: Version `2.30.0` or higher (installed and configured in your PATH)

---

## 2. Backend Setup

Follow these steps to configure and start the backend service.

### Step 2.1: Create a Virtual Environment & Install Dependencies
Run these commands from the repository root:
```bash
# Create a virtual environment
python -m venv .venv

# Activate the virtual environment
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

# Upgrade pip and install package dependencies
pip install --upgrade pip
pip install -r requirements.txt
```

### Step 2.2: Configure Environment Variables
Copy the template `.env.example` to `.env` and fill in the required LLM provider credentials:
```bash
# On Windows:
copy .env.example .env
# On macOS/Linux:
cp .env.example .env
```
Ensure your `.env` contains the required keys:
```env
PORT=8001
HOST=127.0.0.1
GEMINI_API_KEY=your_gemini_api_key_here
DEEPSEEK_API_KEY=your_deepseek_api_key_here
```

### Step 2.3: Run Database Migrations
Initialize the local SQLite database state:
```bash
python -m backend.cli run-migrations
```

### Step 2.4: Start the FastAPI Backend Server
Launch the development server:
```bash
python -m uvicorn backend.api:app --host 127.0.0.1 --port 8001 --reload
```

---

## 3. VS Code Extension Setup

Follow these steps to compile and package the extension.

### Step 3.1: Install Node Dependencies
Navigate to the `vscode-extension` directory and install the packages:
```bash
cd vscode-extension
npm install
```

### Step 3.2: Compile and Package the Extension
Compile TypeScript files and create the `.vsix` distribution package:
```bash
# Compile TypeScript code
npm run compile

# Package the extension into a VSIX file
npx @vscode/vsce package --allow-missing-repository
```
This generates the packaged file: `vscode-extension/repo-intelligence-agent-0.1.0.vsix`.

---

## 4. VSIX Installation

Verify the extension in a clean, isolated VS Code profile:

1. Open your terminal.
2. Create a clean profile directory:
   ```bash
   mkdir -p C:\temp\vscode-profile
   ```
3. Launch a new VS Code window using that profile:
   ```bash
   code --user-data-dir C:\temp\vscode-profile\data --extensions-dir C:\temp\vscode-profile\extensions
   ```
4. In the new VS Code window:
   - Open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`).
   - Select **Extensions: Install from VSIX...**.
   - Locate and select `repo-intelligence-agent-0.1.0.vsix`.
   - Click **Install**.
5. Once installation finishes, reload the window (`Developer: Reload Window`).
6. Open your target repository folder in VS Code.

---

## 5. End-to-End Functional Verification

Confirm all components function correctly by completing the following checklist.

### Feature Checklist

- **[ ] Backend health**: Open a browser or run `curl http://127.0.0.1:8001/health` and verify the status is `"healthy"`.
- **[ ] Analyze Repository**: Click **ARIA: Analyze Repository** in the VS Code sidebar. Verify that the repository is cloned and the Digital Twin / Knowledge Graph are built under `data/`.
- **[ ] Findings**: Verify that the **Engineering Findings** panel renders the list of detected issues (Complexity, Performance, etc.).
- **[ ] Advisor**: Verify that the **Advisor Dashboard** lists advisor recommendations and roadmaps.
- **[ ] Execution Planner**: Verify that the **Execution Planner** displays tasks, batches, critical paths, and rollback checkpoints.
- **[ ] Hover**: Open a file, hover over a symbol (function/class name), and verify that the rich documentation card appears.
- **[ ] CodeLens**: Verify that CodeLens annotations ("Show Callers", "Show Blast Radius") render above symbol declarations.
- **[ ] Code Actions**: Highlight a block of code, press `Ctrl+.` / `Cmd+.`, and verify that refactoring suggestions are shown.
- **[ ] Search**: Use the **Search** field in the ARIA bar and verify that it resolves matching files/symbols.
- **[ ] Review**: Right-click a file in the explorer, select **ARIA: Review Current File**, and check for feedback.
- **[ ] Graph Navigation**: Select **Show Call Graph** or **Show Dependency Graph** to display interactive visual maps.

---

## 6. Troubleshooting

### Issue 6.1: Backend is unavailable
- **Symptoms**: The Backend Connection tree view shows status "offline".
- **Probable Cause**: The FastAPI server is not running, or is running on a different port/address.
- **Resolution**: Ensure you ran `python -m uvicorn backend.api:app --host 127.0.0.1 --port 8001`. Check if `repoIntelligence.backendUrl` in VS Code settings matches `http://127.0.0.1:8001`.

### Issue 6.2: VSIX packaging failure
- **Symptoms**: `vsce package` errors out complaining about missing repository fields or missing files.
- **Probable Cause**: Repository metadata is missing from `package.json`, or the `LICENSE` file is missing.
- **Resolution**: Run `npx @vscode/vsce package --allow-missing-repository`. Ensure a copy of the `LICENSE` file exists in the `vscode-extension` directory.

### Issue 6.3: Empty Tree Views
- **Symptoms**: The findings, advisor, or execution panels show "No active repository" or are completely blank.
- **Probable Cause**: Active repository is not selected, or analysis hasn't been run yet.
- **Resolution**: Click **Set Active Repository** (or run command `repoIntelligence.setActiveRepository`) and enter `owner/repo-name`. Run **Analyze Repository** to kick off the backend pipeline.

### Issue 6.4: Authentication/Access Token Errors
- **Symptoms**: Analysis fails with a 401 or 403 status code.
- **Probable Cause**: Required GitHub token or API Key is missing or invalid.
- **Resolution**: Ensure `repoIntelligence.apiToken` is set in your VS Code settings, or check your backend `.env` variables.

### Issue 6.5: API Endpoint mismatch (404 Not Found)
- **Symptoms**: Generating an execution plan returns a 404 error from the server.
- **Probable Cause**: VS Code extension client calls the wrong API path (e.g. `/execution` instead of `/execution-plan`).
- **Resolution**: Ensure you are using v1.5.0 where the client path has been mapped to `/execution-plan`.