@ngocsangairvds/vsaf 3.2.14 → 3.2.15

package/tools/vds-scripts/lsp_orchestrator/README.md

@@ -1,616 +0,0 @@
-# VDS LSP Orchestrator
-
-A standalone orchestrator for Language Server Protocol (LSP) operations in Python projects. Provides CLI access to code intelligence, diagnostics, refactoring, and type checking without requiring an editor.
-
-**Status**: Production Ready ✅ | All LSP features working natively without AST fallback
-
-## Documentation
-
-<!-- documentation_framework: diátxis -->
-<!-- docs_index: docs/index.md -->
-
-This documentation follows the [Diátaxis framework](https://diataxis.fr/) with four distinct types:
-
-### 📚 Tutorials (Learning)
-Lessons where you learn by doing.
-- [Quick Start Tutorial](docs/tutorials/00-quick-start.md) - Your first experience (10 min)
-
-### 📖 How-to Guides (Tasks)
-Step-by-step directions to solve specific problems.
-- [Type Check Code](docs/how-to-guides/type-check-code.md)
-- [Navigate Code](docs/how-to-guides/navigate-code.md)
-- [Use Daemon Mode](docs/how-to-guides/use-daemon-mode.md)
-- [Automate with JSON](docs/how-to-guides/automate-with-json.md)
-- [Parallel Processing](docs/how-to-guides/parallel-processing.md) - Speed up batch operations (Phase 10)
-- [Docker Mode](docs/how-to-guides/docker-mode.md) - Isolated environment setup (Phase 11)
-- [WSL2 Optimization](docs/how-to-guides/wsl2-optimization.md) - Windows performance tips (Phase 11)
-- [Project Tool Detection](docs/how-to-guides/project-tool-detection.md) - Auto-detect project tools (Phase 12)
-
-### 📋 Reference (Information)
-Austere technical descriptions.
-- [Command Reference](docs/reference/commands.md) - Complete CLI documentation
-- [Configuration Reference](docs/reference/configuration.md) - Config files and env vars
-
-### 💡 Explanation (Understanding)
-Discursive context and background.
-- [About LSP Response Matching](docs/explanation/lsp-response-matching.md)
-- [About Daemon Architecture](docs/explanation/daemon-architecture.md)
-
-**[← Documentation Index](docs/index.md)** | **[For LLMs →](docs/FOR_LLMS.md)**
-
----
-
-### Legacy Documents
-
-The following have been reorganized into the Diátaxis structure:
-- [SETUP.md](SETUP.md) → See [How-to Guides](docs/how-to-guides/)
-- [COMMANDS.md](COMMANDS.md) → See [Command Reference](docs/reference/commands.md)
-- [ARCHITECTURE.md](ARCHITECTURE.md) → See [Explanation](docs/explanation/)
-
-## Features
-
-### Code Intelligence (LSP Native)
-- **Navigation**: Go to definition, find references, call hierarchy (callers/callees)
-- **Symbol Search**: Workspace-wide symbol search with fuzzy matching
-- **Language Services**: Hover, completion, rename, signature help, inlay hints, semantic tokens
-- **Document Info**: Document symbols, document highlight
-
-### Diagnostics & Refactoring
-- **Type Checking**: Integration with `basedpyright` (bundled; falls back to system)
-- **Code Quality**: Aggregated diagnostics from basedpyright and ruff
-- **Code Actions**: Automated quick fixes and refactoring
-- **Formatting**: Ruff LSP formatting and organize imports
-- **Batch Operations**: Format, organize imports, fix-all across multiple files
-
-### Performance
-- **Daemon Mode**: Persistent LSP server for instant responses (<100ms)
-- **Document Caching**: No re-parsing needed for repeated operations
-- **Smart Timeouts**: Configurable timeouts with retry logic
-
-### Additional Features
-- **Notebooks**: `.ipynb` diagnostics supported (Ruff CLI fallback when notebook sync isn't available)
-- **JSON Output**: Structured JSON output for all commands (automation-friendly)
-- **Health Checks**: Monitor LSP server status and diagnostics
-- **Document Links**: Find all clickable links in documents (URLs, imports, file references)
-- **Import Suggestions**: Auto-import suggestions for undefined symbols (BasedPyright)
-- **Type Ignore Comments**: Add `# type: ignore` comments to suppress diagnostics
-
-### Performance Enhancements (Phase 10)
-- **Parallel Processing**: Multi-core batch operations with `--parallel` flag
-- **Configurable Jobs**: Control parallelism with `--jobs N` flag
-- **Concurrent Clients**: Daemon supports multiple simultaneous clients (`--max-clients`)
-- **Hot Reload**: Configuration changes without daemon restart (`--hot-reload`)
-
-### Platform Support (Phase 11)
-- **Docker Mode**: Isolated, reproducible environment with `--docker` flag
-- **WSL2 Optimization**: Automatic filesystem optimization for WSL2 (`--wsl-optimize`)
-- **Windows Support**: Full Windows support with proper path handling
-
-### Project Tool Detection (Phase 12)
-- **Auto-Detection**: Automatically detects package managers, type checkers, formatters, linters, and test runners
-- **Mypy Support**: Full mypy integration as an alternative to BasedPyright
-- **Smart Defaults**: Priority-based detection using lock files, config sections, and dependencies
-- **detect-tools Command**: Show detected project tools in table or JSON format
-
-## Installation
-
-This package is part of the `vds-scripts` monorepo and is typically installed via `uv` in the `vds-cli` context.
-
-```bash
-uv sync
-```
-
-## Quick Start
-
-### Direct Mode (Simple)
-
-```bash
-# Hover information
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp hover src/app.py:10:5
-
-# Go to definition
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp goto --file "src/app.py:10:5" my_function
-
-# Find references
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp refs --file "src/app.py:10:5" my_function
-
-# Document symbols
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp doc-symbols src/app.py
-```
-
-### Daemon Mode (Recommended for Development)
-
-```bash
-# Start daemon (keeps LSP server running)
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp daemon start
-
-# Check daemon status
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp daemon status
-
-# Use LSP features (instant through daemon)
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp hover src/app.py:10:5
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp goto --file "src/app.py:10:5" symbol_name
-
-# Stop daemon when done
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp daemon stop
-```
-
-## Usage
-
-### Via vds-cli (Recommended)
-
-```bash
-# Symbol search
-vds lsp symbol "Agent"
-vds lsp symbol "Agent" --match regex --limit 25
-
-# Type checking
-vds lsp type-check src/
-
-# Diagnostics
-vds lsp diagnostics src/
-vds lsp --json-only diagnostics src/
-vds lsp --include "**/core/**" --exclude "**/tests/**" diagnostics .
-vds lsp diagnostics src/ --severity error --code E501 --file "**/api/**"
-vds lsp diagnostics src/ --fixable --max-fixable 25
-vds lsp diagnostics src/ --watch --interval 2
-
-# Refactoring
-vds lsp fix-errors src/ --apply --yes
-vds lsp fix-errors src/ --apply --yes --kinds quickfix
-vds lsp fix-errors src/ --apply --yes --kinds source.organizeImports --confirm-annotations
-vds lsp fix-errors src/ --patch-file /tmp/vds-lsp.patch
-vds lsp rollback .vds-lsp/backups/20260202-120000
-
-# Formatting
-vds lsp format src/app.py
-vds lsp organize-imports src/app.py --apply --yes
-vds lsp fix-all src/app.py --apply --yes
-
-# Language services
-vds lsp hover src/app.py:10:5
-vds lsp completion src/app.py:10:5
-vds lsp rename src/app.py:10:5 NewName --apply --yes
-vds lsp signature-help src/app.py:10:5
-vds lsp inlay-hints src/app.py
-vds lsp semantic-tokens src/app.py
-
-# Navigation
-vds lsp refs MyClass --context 2
-vds lsp callers my_function --max-depth 2 --show-path --include-external
-vds lsp callees my_function --max-depth 2 --show-path --include-external
-
-# Document links (Phase 9)
-vds lsp doc-links src/app.py
-
-# Import suggestions (Phase 9)
-vds lsp suggest-imports src/app.py:10:5
-vds lsp suggest-imports src/app.py:10:5 --apply --yes
-
-# Type ignore comments (Phase 9)
-vds lsp ignore-comment src/app.py:10:5
-vds lsp ignore-comment src/app.py:10:5 --error-code reportOptionalMemberAccess --apply --yes
-
-# Health check
-vds lsp health
-```
-
-### Standalone
-
-```bash
-# Symbol search
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp symbol "Agent"
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp symbol "Agent" --match exact --limit 20
-
-# Type checking
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp type-check .
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp --lsp-server basedpyright-langserver diagnostics src/
-
-# Call hierarchy
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp callers my_function --max-depth 2 --show-path --include-external
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp callees my_function --max-depth 2 --show-path --include-external
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp callers my_function --format mermaid --output reports/callers.mmd
-
-# Code actions
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp code-actions src/app.py:10:5 --index 1 --apply --yes
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp code-actions src/app.py:10:5 --index 1 --patch-file /tmp/vds-lsp-action.patch
-
-# Refactoring
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp fix-errors src/ --apply --yes --kinds quickfix
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp format src/app.py --apply --yes
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp organize-imports src/app.py --apply --yes
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp fix-all src/app.py --apply --yes
-
-# Batch operations
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp batch-format . --apply --atomic
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp batch-organize-imports . --apply --atomic
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp batch-fix-all . --apply --atomic
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp batch-format . --include "src/vds_lsp_orchestrator" --exclude "tests"
-
-# Parallel batch operations (Phase 10)
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp batch-format . --apply --parallel --jobs 8
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp batch-organize-imports . --apply --no-parallel
-
-# Document links (Phase 9)
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp doc-links src/app.py
-
-# Import suggestions (Phase 9)
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp suggest-imports src/app.py:10:5
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp suggest-imports src/app.py:10:5 --apply --yes
-
-# Type ignore comments (Phase 9)
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp ignore-comment src/app.py:10:5
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp ignore-comment src/app.py:10:5 --error-code reportOptionalMemberAccess --apply --yes
-
-# Health check
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp health
-```
-
-## Daemon Mode
-
-Daemon mode keeps the LSP server running between CLI invocations for instant responses.
-
-### Starting the Daemon
-
-```bash
-# Start with default settings
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp daemon start
-
-# Start with custom idle timeout (seconds)
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp daemon start --idle-timeout 600
-
-# Phase 10: Configure concurrent clients
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp daemon start --max-clients 20
-
-# Phase 10: Disable hot reload
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp daemon start --no-hot-reload
-```
-
-### Daemon Status
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp daemon status
-```
-
-Output:
-```
-┏━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-┃ Property  ┃ Value                                                            ┃
-┡━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
-│ Running   │ Yes                                                              │
-│ PID       │ 56158                                                            │
-│ Socket    │ /tmp/vds-lsp-daemon/vds-lsp-f1a67163077cb984.sock                │
-│ Uptime    │ 0:05:23                                                          │
-│ Clients   │ 1                                                                │
-│ Workspace │ /path/to/workspace                                               │
-└───────────┴───────────────────────────────────────────────────────────────────┘
-```
-
-### Stopping the Daemon
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp daemon stop
-```
-
-### Performance Comparison
-
-| Mode | First Request | Subsequent Requests |
-|------|--------------|---------------------|
-| Direct (no daemon) | ~1-3s (server startup) | ~1s (new server per command) |
-| Daemon mode | ~1s (server startup) | <100ms (instant from cache) |
-
-## Configuration
-
-### Configuration Files
-
-1. **`.vds-lsp/config.json`** - VDS-specific settings
-2. **`pyproject.toml`** - `[tool.vds-lsp]` and `[tool.basedpyright]` sections
-3. **Environment variables** - Runtime overrides
-
-### Example Configuration
-
-**`.vds-lsp/config.json`**:
-```json
-{
-  "timeout": 60,
-  "enable_ruff_lsp": true,
-  "basedpyright": {
-    "analysis": {
-      "diagnosticMode": "openFilesOnly",
-      "typeCheckingMode": "standard",
-      "useLibraryCodeForTypes": false,
-      "autoSearchPaths": true
-    }
-  }
-}
-```
-
-**`pyproject.toml`**:
-```toml
-[tool.vds-lsp]
-enable_ruff_lsp = true
-
-[tool.basedpyright]
-include = ["src"]
-exclude = ["tests", "migrations"]
-typeCheckingMode = "standard"
-```
-
-### Environment Variables
-
-| Variable | Purpose | Default |
-|----------|---------|---------|
-| `VDS_LSP_SERVER` | LSP server command override | Auto-detect |
-| `VDS_LSP_TIMEOUT` | Request timeout in seconds | 10 |
-| `VDS_LSP_CACHE_DIR` | Cache directory | `.vds-lsp/cache` |
-| `VDS_LSP_LOG_LEVEL` | Logging level | `INFO` |
-| `VDS_LSP_ENABLE_RUFF_LSP` | Enable Ruff LSP | Auto-detect |
-| `VDS_LSP_RUFF_SERVER` | Ruff server command | `ruff server` |
-| `VDS_LSP_FIXES_ALLOW_UNSAFE` | Allow unsafe code actions | `false` |
-| `VDS_LSP_ENABLE_LANGUAGE_SERVICES` | Enable language services | `true` |
-| `VDS_LSP_NOTEBOOK_SUPPORT` | Enable notebook support | `true` |
-| `VDS_LSP_DAEMON_IDLE_TIMEOUT` | Daemon auto-shutdown timeout | `300` |
-| `VDS_LSP_DOCKER_MODE` | Enable Docker mode (Phase 11) | `false` |
-| `VDS_LSP_DOCKER_IMAGE` | Docker image to use (Phase 11) | `vds-lsp-orchestrator:latest` |
-| `VDS_LSP_WSL_OPTIMIZE` | Enable WSL2 optimization (Phase 11) | Auto-detect |
-
-## Correct CLI Format for goToDefinition
-
-**Wrong**: `./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp goto "path:line:col"` (treats path as symbol name, falls back to AST)
-
-**Correct**: `./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp goto --file "path:line:col" symbol_name` (uses LSP for definition)
-
-**Examples**:
-```bash
-# Find definition of 'stop' method
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp goto --file "src/vds_lsp_orchestrator/lsp_client.py:100:20" stop
-
-# Short form
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp goto -f "src/vds_lsp_orchestrator/lsp_client.py:100:20" stop
-```
-
-## Development
-
-```bash
-# Run tests
-uv run pytest
-
-# Format code
-uv run ruff format .
-
-# Type check
-uv run ruff check .
-```
-
-## Verification
-
-All LSP features have been verified working natively without AST fallback:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp diagnostics src/
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp hover src/app.py:10:5
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp goto --file "src/app.py:10:5" my_function
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp code-actions src/app.py:10:5
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp fix-errors src/ --apply --yes --kinds quickfix
-```
-
-## Additional Documentation
-
-| Document | Description |
-|----------|-------------|
-| **[SETUP.md](SETUP.md)** | Installation and setup guide |
-| **[COMMANDS.md](COMMANDS.md)** | Complete command reference with all options |
-| **[ARCHITECTURE.md](ARCHITECTURE.md)** | Technical architecture and internal design |
-| **[LSP_ISSUES_AND_FINDINGS.md](LSP_ISSUES_AND_FINDINGS.md)** | Research findings and implementation history |
-| **[Agent Docs](../docs/agents/README.md)** | WHO-owned VDS agent documentation |
-
----
-
-## Quick Command Reference
-
-### Most Common Commands
-
-```bash
-# Type checking
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp type-check src/
-
-# Diagnostics
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp diagnostics src/
-
-# Fix errors automatically
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp fix-errors src/ --apply --yes
-
-# Go to definition
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp goto --file "src/app.py:10:5" my_function
-
-# Find references
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp refs --file "src/app.py:10:5" my_function
-
-# Hover info
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp hover src/app.py:10:5
-
-# Format code
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp format src/app.py --apply
-
-# Organize imports
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp organize-imports src/app.py --apply
-
-# Daemon mode (recommended for development)
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp daemon start
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp daemon status
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp daemon stop
-```
-
-### JSON Output (for scripting)
-
-Add `--json-only` flag to any command for structured JSON output:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp --json-only type-check src/
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp --json-only symbol "DaemonManager"
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp --json-only diagnostics src/
-```
-
----
-
-## All Available Commands
-
-| Category | Commands |
-|----------|----------|
-| **Navigation** | `symbol`, `goto`, `refs`, `implementations`, `highlight`, `callers`, `callees`, `doc-links` |
-| **Language Services** | `hover`, `completion`, `rename`, `signature-help`, `inlay-hints`, `semantic-tokens`, `suggest-imports` |
-| **Diagnostics** | `diagnostics`, `type-check`, `fix-errors`, `code-actions`, `ignore-comment` |
-| **Refactoring** | `format`, `organize-imports`, `fix-all` |
-| **Batch Operations** | `batch-format`, `batch-organize-imports`, `batch-fix-all` |
-| **Utility** | `doc-symbols`, `index-workspace`, `health`, `rollback` |
-| **Daemon** | `daemon start`, `daemon stop`, `daemon restart`, `daemon status` |
-
-See **[COMMANDS.md](COMMANDS.md)** for detailed documentation of each command.
-
----
-
-## Docker Mode
-
-Docker mode provides an isolated, reproducible environment for LSP operations. This is useful for CI/CD pipelines or when you want to ensure consistent behavior across different machines.
-
-### Using Docker Mode
-
-```bash
-# Enable Docker mode for a single command
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp --docker type-check src/
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp --docker diagnostics src/
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp --docker hover src/app.py:10:5
-```
-
-### Building the Docker Image
-
-```bash
-# Build the image
-cd WHO-project/vds-scripts/lsp_orchestrator
-docker build -t vds-lsp-orchestrator:latest .
-```
-
-### Using docker-compose (Recommended)
-
-```bash
-# Start the LSP server container
-cd WHO-project/vds-scripts/lsp_orchestrator
-docker-compose up -d vds-lsp
-
-# Run commands through the container
-docker-compose run --rm vds-lsp-cmd type-check /workspace/src/
-docker-compose run --rm vds-lsp-cmd diagnostics /workspace/src/
-
-# Stop the container
-docker-compose down
-```
-
-### Docker Configuration
-
-Docker mode can be configured via environment variables or `.vds-lsp/config.json`:
-
-**Environment Variables**:
-- `VDS_LSP_DOCKER_MODE=true` - Enable Docker mode
-- `VDS_LSP_DOCKER_IMAGE=vds-lsp-orchestrator:latest` - Docker image to use
-- `VDS_LSP_DOCKER_WORKSPACE=/path/to/workspace` - Workspace mount point
-
-**Configuration File** (`.vds-lsp/config.json`):
-```json
-{
-  "docker_mode": true,
-  "docker_image": "vds-lsp-orchestrator:latest",
-  "docker_workspace": "/path/to/workspace"
-}
-```
-
-### Benefits of Docker Mode
-
-- **Isolation**: LSP server runs in an isolated container
-- **Reproducibility**: Same environment across different machines
-- **CI/CD**: Easy integration into CI/CD pipelines
-- **No Dependencies**: No need to install Python or LSP servers on the host
-
-### Limitations
-
-- Workspace must be accessible from the container (via volume mount)
-- Container must have access to the same files as the host
-- Slight performance overhead compared to native mode
-
----
-
-## Features
-
-### Code Intelligence (LSP Native)
-
-All features work through LSP - no AST fallback needed:
-
-- **Navigation**: Go to definition, find references, call hierarchy (callers/callees)
-- **Symbol Search**: Workspace-wide symbol search with fuzzy/exact/regex matching
-- **Language Services**: Hover, completion, rename, signature help, inlay hints, semantic tokens
-- **Document Info**: Document symbols, document highlight
-
-### Diagnostics & Refactoring
-
-- **Type Checking**: Integration with BasedPyright (bundled, falls back to system)
-- **Code Quality**: Aggregated diagnostics from BasedPyright and Ruff
-- **Code Actions**: Automated quick fixes and refactoring
-- **Formatting**: Ruff LSP formatting and organize imports
-- **Batch Operations**: Format, organize imports, fix-all across multiple files
-
-### Performance
-
-- **Daemon Mode**: Persistent LSP server for instant responses (<100ms)
-- **Document Caching**: No re-parsing needed for repeated operations
-- **Smart Timeouts**: Configurable timeouts with retry logic
-
-### Additional Features
-
-- **Notebooks**: `.ipynb` diagnostics supported (Ruff CLI fallback)
-- **JSON Output**: Structured JSON output for all commands (automation-friendly)
-- **Health Checks**: Monitor LSP server status and diagnostics
-
-## Project Tool Detection
-
-The VDS LSP Orchestrator automatically detects your project's tools and configuration:
-
-### Auto-Detection
-
-- **Package Manager**: UV, Poetry, PDM, Hatch, Pipenv, pip
-- **Type Checker**: mypy, basedpyright, pyright
-- **Formatter**: ruff, black
-- **Linter**: ruff, pylint, flake8
-- **Test Runner**: pytest, unittest
-
-### detect-tools Command
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp detect-tools          # Show detected tools (table format)
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp detect-tools --json   # JSON output for scripts
-```
-
-### Type Checker Selection
-
-```bash
-# Auto-detect (default)
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp type-check src/
-
-# Explicit type checker
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp type-check src/ --type-checker mypy
-./scripts/worktree_uv.sh run --project vds_cli vds-cli lsp type-check src/ --type-checker basedpyright
-
-# Configuration file
-echo '{"typeChecker": "mypy"}' > .vds-lsp/config.json
-
-# Environment variable
-export VDS_LSP_TYPE_CHECKER=mypy
-```
-
-### Detection Priority
-
-Auto-detection uses a priority-based approach:
-1. Lock files (fastest, highest confidence) - `uv.lock`, `poetry.lock`, etc.
-2. Config sections - `[tool.uv]`, `[tool.mypy]`, `[tool.ruff]`
-3. Dependencies - Check `project.dependencies` in pyproject.toml
-4. Commands - Check if tool is available in PATH
-
-See [Project Tool Detection Guide](docs/how-to-guides/project-tool-detection.md) for detailed information.