velune-cli 0.9.0__tar.gz → 0.9.2__tar.gz

velune_cli-0.9.2/.gitignore

@@ -0,0 +1,112 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Testing & Coverage
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.tox/
+.hypothesis/
+
+# Type checking & Linting
+.mypy_cache/
+.ruff_cache/
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv/
+
+# IDE / Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+*.sublime-project
+*.sublime-workspace
+
+# Claude Code / AI tooling internals
+.claude/
+
+# Velune runtime/cache
+.velune/
+
+# Dev container
+.devcontainer/
+
+# Benchmarks
+.benchmarks/
+
+# Scripts (local utility scripts)
+scripts/*.sh
+scripts/*.ts
+
+# Project-specific
+examples/
+
+# Secrets & credentials — never commit these
+.env
+.env.*
+*.env
+secrets/
+credentials/
+*.pem
+*.key
+*.p12
+*.pfx
+*.cer
+*.crt
+config/local.py
+config/local.json
+local_settings.py
+
+# OS & system artifacts
+*.log
+*.tmp
+*.temp
+tmp/
+temp/
+
+# Distribution / packaging internals
+*.whl
+RECORD
+installer/
+
+# Profiling
+*.prof
+*.lprof
+
+# Jupyter (if any notebooks are local-only)
+.ipynb_checkpoints/
+
+# Node (if any frontend tooling)
+node_modules/
+package-lock.json
+yarn.lock

{velune_cli-0.9.0 → velune_cli-0.9.2}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: velune-cli
-Version: 0.9.0
+Version: 0.9.2
 Summary: Local-first multi-model AI developer CLI — council-based agents, persistent memory, repository cognition
 Project-URL: Homepage, https://github.com/Surya-Hariharan/Velune-CLI
 Project-URL: Repository, https://github.com/Surya-Hariharan/Velune-CLI
+Project-URL: Documentation, https://github.com/Surya-Hariharan/Velune-CLI/tree/main/docs
 Project-URL: Issues, https://github.com/Surya-Hariharan/Velune-CLI/issues
-Project-URL: Changelog, https://github.com/Surya-Hariharan/Velune-CLI/blob/main/CHANGELOG.md
+Project-URL: Changelog, https://github.com/Surya-Hariharan/Velune-CLI/blob/main/docs/CHANGELOG.md
 Author-email: Surya HA <suryahariharan2006@gmail.com>
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -218,65 +219,77 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development
 Classifier: Topic :: Terminals
+Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: aiosqlite>=0.19.0
 Requires-Dist: anthropic>=0.18.0
-Requires-Dist: gitpython>=3.1.40
 Requires-Dist: httpx>=0.26.0
 Requires-Dist: keyring>=24.0.0
-Requires-Dist: lancedb>=0.5.0
 Requires-Dist: mcp>=1.0.0
 Requires-Dist: networkx>=3.2.0
 Requires-Dist: numpy>=1.24.0
 Requires-Dist: openai>=1.10.0
-Requires-Dist: opentelemetry-api>=1.22.0
-Requires-Dist: opentelemetry-exporter-otlp>=1.22.0
-Requires-Dist: opentelemetry-sdk>=1.22.0
 Requires-Dist: orjson>=3.9.0
 Requires-Dist: pathspec>=0.12.0
 Requires-Dist: platformdirs>=4.2.0
 Requires-Dist: prompt-toolkit>=3.0.0
 Requires-Dist: psutil>=5.9.0
-Requires-Dist: pyarrow>=14.0.0
-Requires-Dist: pydantic-settings>=2.1.0
+Requires-Dist: pydantic-settings>=2.14.2
 Requires-Dist: pydantic>=2.5.0
-Requires-Dist: qdrant-client>=1.7.0
 Requires-Dist: rank-bm25>=0.2.2
 Requires-Dist: rich>=13.7.0
 Requires-Dist: structlog>=24.0.0
 Requires-Dist: tiktoken>=0.5.0
 Requires-Dist: toml>=0.10.2
-Requires-Dist: tree-sitter-go>=0.21.0
-Requires-Dist: tree-sitter-python>=0.21.0
-Requires-Dist: tree-sitter-rust>=0.21.0
-Requires-Dist: tree-sitter-typescript>=0.21.0
-Requires-Dist: tree-sitter>=0.21.0
 Requires-Dist: typer>=0.9.0
 Provides-Extra: all
+Requires-Dist: docker>=7.0.0; extra == 'all'
 Requires-Dist: gguf>=0.6.0; extra == 'all'
-Requires-Dist: llama-cpp-python>=0.2.0; extra == 'all'
+Requires-Dist: gitpython>=3.1.40; extra == 'all'
+Requires-Dist: lancedb>=0.5.0; extra == 'all'
+Requires-Dist: opentelemetry-api>=1.22.0; extra == 'all'
+Requires-Dist: opentelemetry-exporter-otlp>=1.22.0; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.22.0; extra == 'all'
+Requires-Dist: pyarrow>=14.0.0; extra == 'all'
+Requires-Dist: qdrant-client>=1.7.0; extra == 'all'
+Requires-Dist: tree-sitter-go>=0.21.0; extra == 'all'
+Requires-Dist: tree-sitter-python>=0.21.0; extra == 'all'
+Requires-Dist: tree-sitter-rust>=0.21.0; extra == 'all'
+Requires-Dist: tree-sitter-typescript>=0.21.0; extra == 'all'
+Requires-Dist: tree-sitter>=0.21.0; extra == 'all'
 Provides-Extra: dev
-Requires-Dist: black>=23.12.0; extra == 'dev'
+Requires-Dist: bandit[toml]>=1.7.0; extra == 'dev'
 Requires-Dist: build>=1.0.0; extra == 'dev'
-Requires-Dist: coverage>=7.0.0; extra == 'dev'
-Requires-Dist: mypy>=1.8.0; extra == 'dev'
 Requires-Dist: pip-audit>=2.6.0; extra == 'dev'
 Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
 Requires-Dist: pyright>=1.1.350; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
-Requires-Dist: pytest-benchmark>=4.0.0; extra == 'dev'
-Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
-Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
-Requires-Dist: pytest-timeout>=2.2.0; extra == 'dev'
-Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.1.0; extra == 'dev'
 Requires-Dist: twine>=4.0.0; extra == 'dev'
-Requires-Dist: types-toml>=0.10.0; extra == 'dev'
+Provides-Extra: docker
+Requires-Dist: docker>=7.0.0; extra == 'docker'
 Provides-Extra: gguf
 Requires-Dist: gguf>=0.6.0; extra == 'gguf'
-Requires-Dist: llama-cpp-python>=0.2.0; extra == 'gguf'
+Provides-Extra: git
+Requires-Dist: gitpython>=3.1.40; extra == 'git'
+Provides-Extra: parsing
+Requires-Dist: tree-sitter-go>=0.21.0; extra == 'parsing'
+Requires-Dist: tree-sitter-python>=0.21.0; extra == 'parsing'
+Requires-Dist: tree-sitter-rust>=0.21.0; extra == 'parsing'
+Requires-Dist: tree-sitter-typescript>=0.21.0; extra == 'parsing'
+Requires-Dist: tree-sitter>=0.21.0; extra == 'parsing'
+Provides-Extra: rag
+Requires-Dist: lancedb>=0.5.0; extra == 'rag'
+Requires-Dist: pyarrow>=14.0.0; extra == 'rag'
+Requires-Dist: qdrant-client>=1.7.0; extra == 'rag'
+Provides-Extra: telemetry
+Requires-Dist: opentelemetry-api>=1.22.0; extra == 'telemetry'
+Requires-Dist: opentelemetry-exporter-otlp>=1.22.0; extra == 'telemetry'
+Requires-Dist: opentelemetry-sdk>=1.22.0; extra == 'telemetry'
 Description-Content-Type: text/markdown
 
 # Velune
@@ -285,7 +298,7 @@ Description-Content-Type: text/markdown
 > persistent memory, repository cognition.
 > No cloud required. No quota. No lock-in.
 
-[![PyPI](https://img.shields.io/pypi/v/velune)](https://pypi.org/project/velune/)
+[![PyPI](https://img.shields.io/pypi/v/velune-cli)](https://pypi.org/project/velune-cli/)
 [![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://python.org)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-green)](LICENSE)
 [![CI](https://img.shields.io/github/actions/workflow/status/Surya-Hariharan/Velune-CLI/ci.yml?branch=main&label=CI)](https://github.com/Surya-Hariharan/Velune-CLI/actions/workflows/ci.yml)
@@ -320,7 +333,7 @@ curl -fsSL https://ollama.com/install.sh | sh
 ollama pull qwen2.5-coder:7b
 
 # 3. Install Velune
-pip install velune
+pip install velune-cli
 
 # 4. Initialize in your project
 cd your-project
@@ -333,7 +346,7 @@ velune
 ### Option B — Cloud free tier (Groq, fastest, no GPU needed)
 
 ```bash
-pip install velune
+pip install velune-cli
 velune init --provider groq
 velune setup        # enter your free Groq key
 velune
@@ -341,6 +354,34 @@ velune
 
 Get a free Groq key at <https://console.groq.com/keys> — no credit card.
 
+### Installing the `velune` command
+
+```bash
+pip install velune-cli
+velune --version
+```
+
+If your shell reports **`velune: command not found`** (or, on Windows,
+*"'velune' is not recognized…"*), the install succeeded but your Python
+scripts directory is not on `PATH`. Two reliable fixes:
+
+- **Recommended — install with [pipx](https://pipx.pypa.io/)** (isolated env, auto-managed PATH):
+
+  ```bash
+  pipx install velune-cli
+  ```
+
+- **Or run it as a module** (always works, no PATH changes needed):
+
+  ```bash
+  python -m velune --version
+  python -m velune            # start the REPL
+  ```
+
+On Windows, a plain `pip install` puts the launcher in a per-user
+`…\PythonXX\Scripts` folder; re-running the Python installer with **“Add
+Python to PATH”** checked (or using `pipx`) resolves it permanently.
+
 ---
 
 ## Hardware requirements
@@ -374,15 +415,23 @@ Velune features a modern, clean terminal interface designed for productivity:
 
 ## Providers
 
-| Provider              | Type  | Cost           | Models                               | Setup                            |
-|-----------------------|-------|----------------|--------------------------------------|----------------------------------|
-| Ollama                | Local | Free           | Any pulled model                     | Install Ollama, pull a model     |
-| Groq                  | Cloud | Free tier      | Llama 3.3 70B, Mixtral, Gemma2       | `velune setup` → enter key       |
-| OpenRouter            | Cloud | Pay-per-token  | 100+ models                          | `velune setup` → enter key       |
-| OpenAI                | Cloud | Pay-per-token  | GPT-4o, GPT-4o Mini                  | `velune setup` → enter key       |
-| Anthropic             | Cloud | Pay-per-token  | Claude Opus, Sonnet, Haiku           | `velune setup` → enter key       |
-| xAI (Grok)            | Cloud | Pay-per-token  | Grok 2, Grok 2 Mini                  | `velune setup` → enter key       |
-| Google Gemini         | Cloud | Free quota     | Gemini 2.0 Flash, 1.5 Pro/Flash      | `velune setup` → enter key       |
+| Provider     | Type  | Cost          | Models                                        | Setup                        |
+|--------------|-------|---------------|-----------------------------------------------|------------------------------|
+| Ollama       | Local | Free          | Any pulled model                              | Install Ollama, pull a model |
+| LM Studio    | Local | Free          | Any GGUF / MLX model                          | Launch LM Studio server      |
+| Groq         | Cloud | Free tier     | Llama 3.3 70B, Mixtral, Gemma2                | `velune setup` → enter key   |
+| OpenRouter   | Cloud | Pay-per-token | 100+ models                                   | `velune setup` → enter key   |
+| OpenAI       | Cloud | Pay-per-token | GPT-4o, GPT-4o Mini                           | `velune setup` → enter key   |
+| Anthropic    | Cloud | Pay-per-token | Claude Opus, Sonnet, Haiku                    | `velune setup` → enter key   |
+| xAI (Grok)   | Cloud | Pay-per-token | Grok 2, Grok 2 Mini                           | `velune setup` → enter key   |
+| Google       | Cloud | Free quota    | Gemini 2.0 Flash, 1.5 Pro/Flash               | `velune setup` → enter key   |
+| Together AI  | Cloud | Pay-per-token | Llama 3.3 70B, Qwen 2.5 Coder, DeepSeek R1    | `velune setup` → enter key   |
+| Fireworks AI | Cloud | Pay-per-token | DeepSeek R1, Qwen 2.5 Coder, Mixtral 8x22B    | `velune setup` → enter key   |
+| Mistral      | Cloud | Pay-per-token | Mistral Large, Codestral, Mixtral             | `velune setup` → enter key   |
+| DeepSeek     | Cloud | Pay-per-token | DeepSeek R1, DeepSeek Coder                   | `velune setup` → enter key   |
+| Cohere       | Cloud | Pay-per-token | Command R+, Command R                         | `velune setup` → enter key   |
+| NVIDIA NIM   | Cloud | Pay-per-token | Llama, Mistral, and other NIM models          | `velune setup` → enter key   |
+| HuggingFace  | Cloud | Free/paid     | Open models via Inference API                 | `velune setup` → enter key   |
 
 Keys are stored in your OS keyring — never in files, never in git.
 
@@ -390,40 +439,122 @@ Keys are stored in your OS keyring — never in files, never in git.
 
 ## Commands
 
-### CLI (before the REPL starts)
+### CLI (terminal, before the REPL)
 
 ```bash
-velune              # Start the persistent REPL session
-velune init         # Initialize Velune in a project
-velune setup        # Configure API keys securely (stored in OS keyring)
-velune doctor       # Check hardware, providers, dependencies
-velune models scan  # Discover all available local and cloud models
+# Core
+velune                    # Start the interactive REPL session
+velune chat               # Same as above (explicit form)
+velune run "<task>"       # Run a task non-interactively and exit
+velune ask "<question>"   # Ask a one-shot question and exit
+velune init               # Initialize Velune in a project directory
+
+# Workspace & sessions
+velune workspace init     # Index the current workspace
+velune workspace status   # Show index freshness and file counts
+velune workspace graph    # Render the workspace dependency graph
+velune workspace list     # List all known workspaces
+velune session list       # List saved chat sessions
+velune session delete <id>  # Delete a saved session
+
+# Setup & models
+velune setup              # Configure API keys (stored in OS keyring)
+velune models scan        # Discover all available local and cloud models
+velune models list        # List discovered models
+velune provider list      # Show all configured providers and their status
+velune provider add       # Add a new provider interactively
+velune config show        # Print effective velune.toml settings
+velune config set <k> <v> # Write a setting to velune.toml
+
+# Analytics & monitoring
+velune usage              # Token usage and estimated cost for recent sessions
+velune quota              # Check provider rate-limit and quota status
+velune health             # Check provider reachability and response time
+
+# Diagnostics
+velune doctor             # Run full environment health check
+velune logs               # View recent execution event log
+velune logs live          # Follow new events as they are written
+velune status             # Index freshness and workspace health snapshot
+velune pipeline "<query>" # Trace a retrieval query through the search pipeline
+velune daemon start       # Start the background Velune service
+velune daemon stop        # Stop the background service
+velune mcp serve          # Expose Velune's tool council as an MCP server
+velune mcp connect <url> <name>  # Connect to an external MCP server and list tools
+velune memory inspect     # Show memory tier sizes and record counts
+velune memory clear       # Clear all memory tiers for the current workspace
 ```
 
 ### Inside the REPL
 
 ```text
-/run <task>              Execute a task through the council
-/model                   Switch active model (arrow-key picker)
-/models                  List all available models
-/optimus                 Speed mode — instant tier, smallest model
-/godly                   Max power — full council, largest model
-/normal                  Return to balanced mode
-/mode                    Show current mode settings
-/memory                  Inspect memory tiers
-/session save            Save current session
-/session list            List saved sessions
-/session resume <id>     Resume a session
-/usage                   Token count and cost for this session
-/context                 Context window usage indicator
-/diff                    Show pending file changes
-/doctor                  Run health checks
-/help                    Show all commands
-/clear                   Clear screen and context
+─── Session ───────────────────────────────────────────────────────────────────
+/help                    Show all commands and their aliases
 /exit                    Exit Velune
+/clear                   Clear the terminal screen (context is preserved)
+/new [title]             Start a new conversation (project memory persists)
+/project [name|path]     Switch or manage project workspaces
+
+─── Council / Execution ───────────────────────────────────────────────────────
+/run <task>              Execute a task through the Reasoning Council
+/run --bg <task>         Submit task to background — prompt returns immediately
+/council <task>          Force full council tier regardless of task complexity
+/jobs                    List all background jobs (ID, status, phase, elapsed)
+/jobs cancel <id>        Cancel a running background job
+/dashboard               Live progress dashboard (jobs + alerts + provider health)
+
+─── Models ────────────────────────────────────────────────────────────────────
+/model [model-id]        Switch active model (arrow-key picker if no arg)
+/models                  List all available models
+/pull [model-id]         Download an Ollama model with live progress
+/delete <model-id>       Delete a locally installed Ollama model
+/councilmodel            Assign specific models to Planner / Coder / Reviewer roles
+/bench [run]             View or run empirical model capability benchmarks
+
+─── Session Modes ─────────────────────────────────────────────────────────────
+/optimus                 Speed mode — instant tier, smallest model, 4k context
+/godly                   Max power — full council, largest model, 128k context
+/normal                  Return to balanced mode (auto-tier, 16k context)
+/mode                    Show current mode settings and active council tier
+
+─── Memory & Context ──────────────────────────────────────────────────────────
+/memory [clear|stats]    Inspect or clear memory tiers
+/session                 Interactive session picker (list / resume / save / export)
+/context                 Show context window usage for the current conversation
+/graph                   Render a tree of knowledge graph entities
+
+─── Diffs & Editing ───────────────────────────────────────────────────────────
+/diff                    Show uncommitted file changes from the last council run
+/undo                    Revert the last Velune-generated git commit (keeps changes staged)
+/hunk                    Toggle hunk-by-hunk review mode for edits
+/approve [safe|ask|block] Set tool/command approval gate
+
+─── Git Integration ───────────────────────────────────────────────────────────
+/push [--force]          Push current branch to remote origin
+/pr <title>              Create a pull request / merge request on GitHub or GitLab
+/issue <number>          Fetch a GitHub/GitLab issue and inject it as context
+/sandbox [docker|status] Show or switch sandbox type (subprocess or Docker)
+
+─── Code Intelligence ─────────────────────────────────────────────────────────
+/lint [file]             Lint a Python file and display diagnostic output
+/refactor <file>         Detect code smells and suggest refactoring targets
+/typify <file>           Suggest type hints for unannotated functions
+
+─── MCP & Plugins ─────────────────────────────────────────────────────────────
+/mcp [servers|tools|resources|connect|disconnect]  Inspect MCP servers and tools
+/plugin [list|enable|disable|reload|show]          Manage declarative plugins
+
+─── Diagnostics ───────────────────────────────────────────────────────────────
+/doctor                  Run environment health checks
+/config                  Show current configuration settings
+/stats                   Session statistics: tokens, cost, turns, uptime
+/history                 Show REPL command execution history
+/hooks                   List active lifecycle hooks and their configuration
 ```
 
-Tab-completion is active for all `/` commands and for model IDs (type `/model` then space to trigger).
+Tab-completion is active for all `/` commands and for model IDs (type `/model` then Space to trigger).
+
+The status bar shows `⚙ N bg` for active background jobs and `⚠ N` for unread proactive alerts. Alerts drain automatically after each prompt and are printed as Rich panels above the input line.
 
 ---
 
@@ -432,17 +563,35 @@ Tab-completion is active for all `/` commands and for model IDs (type `/model` t
 ```text
 velune/
 ├── cli/              REPL, slash commands, banner, autocomplete, session manager
-├── providers/        Ollama, Groq, OpenAI, Anthropic, xAI, Google, OpenRouter
-├── cognition/        Council: Planner + Coder + Reviewer + Challenger + Synthesizer
+│   ├── commands/     Typer subcommands (workspace, session, models, doctor, mcp, …)
+│   ├── display/      Live dashboards and council pipeline view
+│   └── rendering/    Rich error panels and markdown streaming
+├── providers/        15 provider adapters (Ollama, Groq, OpenAI, Anthropic, Mistral, …)
+│   ├── adapters/     Per-provider inference + streaming implementations
+│   └── discovery/    Model catalog discovery for each provider
+├── cognition/        Council: Planner → Coder → Reviewer → Challenger → Synthesizer
+│   └── council/      DebateSession, CouncilRunner, per-role agents, tier classifier
 ├── memory/           5-tier: working → episodic → semantic → graph → lineage
-├── repository/       AST indexing, dependency graph, .veluneignore
-├── execution/        Sandbox, diff preview, rollback, cancellation
+├── proactive/        Alert store + watcher (CognitiveBus event subscriptions)
+├── repository/       AST indexing, import graph, blast-radius estimator, .veluneignore
+├── retrieval/        Hybrid retrieval: BM25 + vector + graph, cross-encoder reranker
+├── execution/        Managed execution (allowlist + limits), diff preview, rollback
+│   └── edit_formats/ Diff format parsers (unified, search-replace, XML, JSON)
+├── analysis/         Code intelligence: linting, code-smell detection, type inference
+├── integrations/     GitHub and GitLab REST clients (push, PR, issues)
+├── hooks/            Lifecycle hook dispatcher and executor (pre/post tool events)
+├── observability/    Context reports, execution trace log, workspace dependency graph
+├── mcp/              MCP server + client; stdio / SSE / HTTP / WebSocket transports
 ├── hardware/         Hardware detection, tier classification, GPU probe
 ├── telemetry/        Token tracking, cost estimation, latency profiling
 ├── models/           Model registry, capability scoring, specializations
-├── context/          Context window tracking, extractive compression
+├── context/          Context window tracking, token counting, extractive compression
+├── orchestration/    ContextOrchestrationEngine — wires intent → council → output
+├── core/             Loop detector, retry policy, task/job registry, error types
 ├── kernel/           Bootstrap, lifecycle coordinator, service container
-└── plugins/          Plugin loader & hook registry (experimental; unsandboxed, off by default)
+├── daemon/           Background Velune service (server + IPC transport)
+├── tools/            File-system, git, web-fetch, and terminal tool implementations
+└── plugins/          Declarative plugin loader, SKILL.md injection, hook wiring
 ```
 
 ---
@@ -453,7 +602,7 @@ Velune maintains five memory tiers across sessions:
 
 1. **Working** — current conversation turns (in-process, TTL-evicted)
 2. **Episodic** — session history (SQLite, persisted to `~/.velune/`)
-3. **Semantic** — vector search over past interactions (local Qdrant)
+3. **Semantic** — vector search over past interactions (local LanceDB and Qdrant)
 4. **Graph** — repository structure and symbol relationships
 5. **Lineage** — decision history, what was tried and why
 
@@ -477,19 +626,66 @@ Switch modes at any time mid-session. The prompt badge updates immediately.
 
 ## MCP integration
 
-Velune exposes an MCP server so that Claude Desktop and VS Code can call
-Velune's local model council as a tool — giving cloud-based editors access
-to local hardware without sending your code to a third party.
+Velune works as both an MCP **server** and an MCP **client**:
+
+- **Server** (`velune mcp serve`) — exposes Velune's local tool council over
+  stdio so Claude Desktop, VS Code, and other MCP-capable editors can call
+  Velune's models without sending your code to a third party.
+- **Client** (`velune mcp connect <url> <name>`) — connects to any external MCP
+  server, lists its tools, and makes them available inside the REPL via `/mcp`.
+- **Transports** — stdio, SSE, HTTP, and WebSocket (`ws://` / `wss://`) are all
+  supported. Servers can also be declared in `.mcp.json` and loaded automatically.
 
-See [`docs/mcp.md`](docs/mcp.md) for configuration examples and the full tool reference.
+Outbound connections to external MCP servers are trust-gated — see
+[MCP trust gating](docs/SECURITY.md#mcp-trust-gating) in the security policy.
 
 ---
 
 ## Windows
 
-Velune runs on Windows via WSL2. Native Windows support is planned.
+Velune runs natively on Windows (supporting native command execution sandboxing, local Ollama integration, and keyring credentials). It can also run via WSL2 if preferred.
+
+---
+
+## Project docs
+
+| Doc | What's inside |
+| --- | --- |
+| [docs/SECURITY.md](docs/SECURITY.md) | Security posture, trust boundaries, reporting |
+| [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) | Dev setup and contribution workflow |
+| [docs/CHANGELOG.md](docs/CHANGELOG.md) | Full version history |
+
+---
+
+## Optional extras
+
+The default install is intentionally lean and pure-python-friendly so it
+resolves fast and cleanly on every platform. Heavy or feature-specific
+dependencies live in extras — every feature that needs one **degrades
+gracefully** when it is absent (e.g. semantic search becomes a no-op, but
+lexical search and chat keep working).
+
+| Extra | Installs | Enables |
+| --- | --- | --- |
+| `[rag]` | `lancedb`, `pyarrow`, `qdrant-client` | Semantic memory + vector retrieval (large compiled wheels) |
+| `[parsing]` | `tree-sitter` + grammars | Tree-sitter source parsing for deep repository cognition |
+| `[telemetry]` | `opentelemetry-*` | Export spans/metrics to an OTLP collector |
+| `[git]` | `gitpython` | Git provider tools (push / PR / issue) and richer git context |
+| `[gguf]` | `gguf` | GGUF file metadata reading — safe, no transitive risk |
+| `[docker]` | `docker` | Docker sandbox for isolated code execution |
+| `[all]` | everything above | Full-featured install |
+| `[dev]` | Test/lint tools | For contributors |
+
+```bash
+pip install velune-cli            # lean base (Ollama, cloud providers, chat, lexical search)
+pip install 'velune-cli[rag]'     # + semantic memory & vector retrieval
+pip install 'velune-cli[all]'     # + every optional feature
+```
 
-See [WINDOWS.md](WINDOWS.md) for the complete WSL2 setup guide.
+> The former `[llamacpp]` extra has been **permanently removed**:
+> `llama-cpp-python` pulls in `diskcache ≤ 5.6.3` (unsafe pickle
+> deserialization, no patched version). Install `llama-cpp-python` manually,
+> in a trusted single-user environment only, if you accept that risk.
 
 ---
 
@@ -506,8 +702,8 @@ pytest tests/ -q
 ```
 
 Report security issues via
-[GitHub Security Advisories](https://github.com/Surya-Hariharan/Velune-CLI/security/advisories/new) —
-not public issues.
+[GitHub Security Advisories](https://github.com/Surya-Hariharan/Velune-CLI/security/advisories/new)
+— not public issues.
 
 ---