docs(litellm): add integration guide for environment variables and configuration

Document usage of LITELLM_BASE_URL, LITELLM_API_KEY, and LITELLM_MODEL_NAME
environment variables, along with configuration examples and setup instructions.

Author: craftslab

README_litellm.md

@@ -0,0 +1,146 @@
+# LiteLLM Integration Guide
+
+This guide explains how to use LiteLLM with OpenCode, including environment variable configuration and model setup.
+
+## Overview
+
+LiteLLM is a proxy that allows you to use 100+ LLM providers through a unified OpenAI-compatible API. OpenCode supports LiteLLM through both environment variables and configuration files.
+
+## Quick Start with Environment Variables
+
+The simplest way to get started is using environment variables:
+
+```bash
+# Set your LiteLLM proxy URL (defaults to http://localhost:4000)
+export LITELLM_BASE_URL="http://localhost:4000"
+
+# Set your API key (optional, leave empty if not required)
+export LITELLM_API_KEY="sk-your-api-key"
+
+# Automatically add a model
+export LITELLM_MODEL_NAME="gpt-4"
+```
+
+Then run OpenCode. The model will be automatically available.
+
+## Environment Variables
+
+### `LITELLM_BASE_URL`
+
+The URL of your LiteLLM proxy server.
+
+- **Default**: `http://localhost:4000`
+- **Example**: `export LITELLM_BASE_URL="https://litellm.example.com"`
+
+### `LITELLM_API_KEY`
+
+Your LiteLLM API key. Optional if your proxy doesn't require authentication.
+
+- **Default**: Uses a dummy key for local proxy
+- **Example**: `export LITELLM_API_KEY="sk-1234567890"`
+
+### `LITELLM_MODEL_NAME`
+
+Automatically adds a model to OpenCode without needing to configure `opencode.json`.
+
+- **Example**: `export LITELLM_MODEL_NAME="gpt-4"`
+- **Example**: `export LITELLM_MODEL_NAME="claude-3-5-sonnet-20241022"`
+
+When `LITELLM_MODEL_NAME` is set, OpenCode will automatically create a model configuration with sensible defaults:
+- Context limit: 128,000 tokens
+- Output limit: 4,096 tokens
+- Tool calling: enabled
+- Temperature: enabled
+- Text input/output: enabled
+
+**Note**: Models defined in `opencode.json` take precedence over the `LITELLM_MODEL_NAME` environment variable.
+
+## Configuration Priority
+
+The authentication configuration follows this priority order:
+
+1. **Environment variables** (`LITELLM_BASE_URL`, `LITELLM_API_KEY`)
+2. **Stored authentication** (configured via `/connect` command)
+3. **Defaults** (`http://localhost:4000` with dummy key)
+
+## Interactive Configuration
+
+You can also configure LiteLLM interactively using the `/connect` command:
+
+1. Run `/connect` in OpenCode
+2. Select "LiteLLM" from the provider list
+3. Enter your base URL and API key when prompted
+
+This stores the configuration persistently.
+
+## Advanced Configuration with `opencode.json`
+
+For more control over models and their capabilities, create or update your `opencode.json` file:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "litellm": {
+      "baseURL": "http://localhost:4000",
+      "apiKey": "{env:LITELLM_API_KEY}",
+      "models": {
+        "gpt-4": {
+          "name": "GPT-4 (via LiteLLM)",
+          "limit": {
+            "context": 128000,
+            "output": 8192
+          },
+          "tool_call": true,
+          "temperature": true,
+          "reasoning": false,
+          "attachment": false
+        },
+        "claude-3-5-sonnet-20241022": {
+          "name": "Claude 3.5 Sonnet (via LiteLLM)",
+          "limit": {
+            "context": 200000,
+            "output": 8192
+          },
+          "tool_call": true,
+          "temperature": true,
+          "reasoning": true,
+          "attachment": false
+        },
+        "gpt-3.5-turbo": {
+          "name": "GPT-3.5 Turbo (via LiteLLM)"
+        }
+      }
+    }
+  }
+}
+```
+
+### Configuration Options
+
+- **`baseURL`**: The URL of your LiteLLM proxy server
+- **`apiKey`**: Your LiteLLM API key. Use `{env:VARIABLE_NAME}` to reference environment variables
+- **`models`**: Object defining available models with the following optional properties:
+  - `name`: Display name for the model in the UI
+  - `limit.context`: Maximum input tokens (default: 128000)
+  - `limit.output`: Maximum output tokens (default: 4096)
+  - `tool_call`: Whether the model supports function calling (default: true)
+  - `temperature`: Whether the model supports temperature parameter (default: true)
+  - `reasoning`: Whether the model has reasoning capabilities (default: false)
+  - `attachment`: Whether the model supports file attachments (default: false)
+
+## Implementation Details
+
+The LiteLLM integration is implemented in [`packages/opencode/src/plugin/litellm.ts`](packages/opencode/src/plugin/litellm.ts):
+
+- Checks environment variables first (`LITELLM_BASE_URL`, `LITELLM_API_KEY`, `LITELLM_MODEL_NAME`)
+- If `LITELLM_MODEL_NAME` is set, automatically adds it as an available model with sensible defaults
+- Only adds the env model if not already configured in `opencode.json` (user config takes precedence)
+- Supports interactive configuration via custom prompts
+- Stores authentication as `baseURL|apiKey` composite format
+
+## Learn More
+
+- [LiteLLM Documentation](https://docs.litellm.ai/)
+- [OpenCode Providers Documentation](packages/web/src/content/docs/providers.mdx)
+- [LiteLLM Plugin Source](packages/opencode/src/plugin/litellm.ts)