# Repository Guidelines

 ## Project Structure & Module Organization
 - `RoslynBridge/` – VSIX source (C#). Key folders: `Server/` (HTTP host), `Services/` (Roslyn queries, refactorings), `Models/`, `Constants/`.
 - Build artifacts: `RoslynBridge/bin/` and `RoslynBridge/obj/`.
 - Claude skills: `.claude/skills/roslyn-api/SKILL.md` (HTTP query reference for local discovery/testing).

 ## Build, Test, and Development Commands
 - **IMPORTANT**: This VSIX project MUST be built with MSBuild, NOT `dotnet build`. Using `dotnet build` will fail with missing namespace errors.
- Build (CLI): `msbuild RoslynBridge.sln /p:Configuration=Debug` or with full path:
  ```powershell
  & 'C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe' RoslynBridge.sln /t:Restore /t:Build /p:Configuration=Debug
  ```
 - Build (VS): Open `RoslynBridge.sln`, set `RoslynBridge` as startup, press F5 to launch the Experimental Instance.
 - Health check (server running in VS):
   - PowerShell: `$b=@{queryType='getprojects'}|ConvertTo-Json; Invoke-RestMethod -Uri 'http://localhost:59123/query' -Method Post -Body $b -ContentType 'application/json'`
   - curl (Windows): `curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"getprojects\"}"`

 ## Coding Style & Naming Conventions
 - Language: C# (net48 VSIX). Use 4‑space indentation; braces on new lines.
 - Naming: `PascalCase` for types/methods; `camelCase` for locals; private fields as `_camelCase`.
 - Prefer `async`/`await`, avoid blocking the UI thread; use `JoinableTaskFactory` when switching.
 - Keep nullable annotations consistent with project settings.
 - Run Format Document and Organize Usings before commits.

 ## Testing Guidelines
 - No unit test project yet. Validate via HTTP endpoints (see SKILL.md): `getprojects`, `getdiagnostics`, `getsolutionoverview`, `getsymbol`, etc.
 - Expected response shape: `{ success, message, data, error }` (JSON).
 - Lines are 1‑based; columns 0‑based. File paths in JSON require escaped backslashes.

 ## Commit & Pull Request Guidelines
 - Commits: concise, imperative subject (e.g., "Add diagnostics endpoint"), with short body explaining rationale and scope.
 - PRs: include description, linked issues, sample requests/responses, and screenshots when UI/VS behavior is affected.
 - Checklist: builds clean, `getdiagnostics` shows no new errors, code formatted, usings organized.

 ## Security & Configuration Tips
 - Server binds to `http://localhost:59123/` and accepts only POST; CORS is permissive for local tooling. Do not expose externally.
 - Endpoints: `/query` (main), `/health` route exists but still requires POST.
 - Adjust port/paths in `RoslynBridge/Constants/ServerConstants.cs` if needed.

## Agent Script Usage: rb.ps1 (for AI agents)

This section is for the agent only. Use `rb.ps1` to minimize tokens and speed up local Roslyn queries.

- Location: `rb.ps1` (repo root). Invoke with PowerShell.
- Auto-detects endpoints: prefers Web API (`http://localhost:5001`), falls back to VS plugin (`http://localhost:59123`).
- Output defaults to compact JSON. Use `-Raw` to emit raw response strings, `-Pretty` only for debugging.
- Override detection with `-BaseUrl http://localhost:5001` if needed; `-NoDetect` forces Web API pathing.

Examples (run from repo root):

```powershell
# Health and discovery
powershell -NoProfile -Command .\rb.ps1 health
powershell -NoProfile -Command .\rb.ps1 projects -Raw
powershell -NoProfile -Command .\rb.ps1 overview

# File-specific queries (use full paths from `projects`)
powershell -NoProfile -Command .\rb.ps1 diagnostics -FilePath C:/full/path/File.cs
powershell -NoProfile -Command .\rb.ps1 symbol -FilePath C:/full/path/File.cs -Line 12 -Column 4
powershell -NoProfile -Command .\rb.ps1 references -FilePath C:/full/path/File.cs -Line 12 -Column 4 -Raw

# Symbol search
powershell -NoProfile -Command .\rb.ps1 search -SymbolName Service -Kind class

# Project operations
powershell -NoProfile -Command .\rb.ps1 build -ProjectName MyProject
powershell -NoProfile -Command .\rb.ps1 package-add -ProjectName MyProject -PackageName Newtonsoft.Json -Version 13.0.3

# History (Web API only)
powershell -NoProfile -Command .\rb.ps1 history-recent -Count 10
powershell -NoProfile -Command .\rb.ps1 history-stats

# Compact solution overview summary (uses API-level summary)
powershell -NoProfile -Command .\rb.ps1 solution-overview -Format yaml -Top 5

```

Key behaviors and assumptions:
- Lines are 1-based; columns 0-based.
- Forward slashes `/` are accepted in file paths.
- Prefer `-Raw` to minimize token usage when chaining outputs.
- If Web API is down, commands transparently fall back to the plugin when possible. History endpoints require Web API.
- If auto-detection is ambiguous, set `-BaseUrl` explicitly.

Policy (agent-only):
- Do NOT call `curl`, `Invoke-RestMethod`, or `Invoke-WebRequest` directly to Roslyn Bridge.
- Always invoke `rb.ps1` for all Roslyn-related queries and operations.
- Prefer `-Raw` output and parse only what’s needed to reduce tokens.
- Keep timeouts short unless debugging (`-TimeoutSec` can be raised temporarily).
- Avoid pretty output unless explicitly needed (`-Pretty`).