@4via6/relay 1.0.0 → 1.1.0

package/docs/features.md

@@ -24,13 +24,21 @@ Relay streams AI responses in real time. As the AI generates text, the Telegram
 
 ### Configuration
 
-Streaming is enabled by default. To disable it:
+Streaming is configured during `relay onboard`, or via CLI flag:
 
-```env
-STREAMING=false
+```bash
+relay --streaming-enabled=true
 ```
 
-When disabled, the bot waits for the complete response before sending a single message.
+Or set it in `.relay/config.json`:
+
+```json
+{
+  "streamingEnabled": true
+}
+```
+
+When disabled (default), the bot waits for the complete response before sending a single message.
 
 ---
 
@@ -68,12 +76,14 @@ Send voice notes to the bot and they'll be transcribed and processed as text inp
 
 ### Setup
 
-Configure at least one speech-to-text provider:
+Configure at least one speech-to-text provider during `relay onboard`, or set keys in `.relay/config.json`:
 
-```env
-GROQ_API_KEY=gsk_...          # Groq Whisper (fastest, has free tier)
-OPENAI_API_KEY=sk-...          # OpenAI Whisper
-ASSEMBLYAI_API_KEY=...         # AssemblyAI
+```json
+{
+  "groqApiKey": "gsk_...",
+  "openaiSttApiKey": "sk-...",
+  "assemblyaiApiKey": "..."
+}
 ```
 
 If multiple providers are configured, the cheapest available one is selected automatically.
@@ -194,25 +204,17 @@ Relay supports switching between AI models at runtime.
 
 ### Listing available models
 
-Use `/models` to see all configured models:
+Use `/models` to see all available models as an interactive inline keyboard. Models are grouped by provider, with capability badges shown next to each name. The currently active model is marked with a `✓` prefix.
 
-```
-Available Models
+Tap any model button to switch to it instantly — no need to type a command.
 
-anthropic
-  claude-sonnet-4-20250514  [reasoning] [active]
-  claude-opus-4-20250514  [reasoning]
-  claude-haiku-4-20250514
-
-openrouter
-  deepseek/deepseek-r1  [reasoning]
-```
+If there are more than 8 models, pagination buttons (`« Prev` / `Next »`) appear at the bottom.
 
 ### Capability badges
 
 - `[reasoning]` — The model supports extended thinking/reasoning
 - `[vision]` — The model accepts image input
-- `[active]` — Currently selected model
+- `✓` prefix — Currently selected model
 
 ### Switching models
 
@@ -236,8 +238,10 @@ Capabilities: reasoning, vision
 ### Provider behavior
 
 - **OpenCode**: Lists all models from all configured providers dynamically
-- **Claude**: Fetches available models dynamically from the Anthropic API (`GET /v1/models`)
-- **Codex**: Fetches available models dynamically from the OpenAI API (`GET /v1/models`)
+- **Claude**: Fetches available models dynamically from the Anthropic API — requires `ANTHROPIC_API_KEY` in the environment
+- **Codex**: Fetches available models dynamically from the OpenAI API — requires `CODEX_API_KEY` or `OPENAI_API_KEY` in the environment
+
+If the provider API key is not set or the API call fails, no models are listed.
 
 ---
 
@@ -247,14 +251,26 @@ Customize the AI's behavior with a system prompt file.
 
 ### Default behavior
 
-The bot loads a system prompt from `skill.md` in the project root. If the file doesn't exist, a built-in default prompt is used.
+The bot looks for a system prompt in this order:
+1. Explicit path from `systemPromptFile` in config
+2. `.relay/SKILL.md` if it exists
+3. `./SKILL.md` in the current directory (backward compatibility)
+4. Built-in default prompt
 
 ### Custom prompt file
 
-Set a custom path:
+Set a custom path in `.relay/config.json`:
 
-```env
-SYSTEM_PROMPT_FILE=prompts/my-prompt.md
+```json
+{
+  "systemPromptFile": "prompts/my-prompt.md"
+}
+```
+
+Or via CLI flag:
+
+```bash
+relay --system-prompt-file=prompts/my-prompt.md
 ```
 
 ### Hot reload
@@ -397,10 +413,18 @@ Relay automatically persists critical state to disk so it survives bot restarts
 
 ### Configuration
 
-Override the data directory:
+Override the data directory in `.relay/config.json`:
+
+```json
+{
+  "dataDir": "/path/to/custom/data"
+}
+```
+
+Or via CLI flag:
 
-```env
-RELAY_DATA_DIR=/path/to/custom/data
+```bash
+relay --data-dir=/path/to/custom/data
 ```
 
 Default: `.relay/` in the project root.
@@ -413,11 +437,21 @@ For production deployments, you can run Relay in webhook mode instead of long-po
 
 ### Setup
 
-```env
-BOT_MODE=webhook
-WEBHOOK_URL=https://your-server.com/bot
-WEBHOOK_PORT=3000
-WEBHOOK_SECRET=your-random-secret
+Configure webhook mode during `relay onboard`, or set it in `.relay/config.json`:
+
+```json
+{
+  "botMode": "webhook",
+  "webhookUrl": "https://your-server.com/bot",
+  "webhookPort": 3000,
+  "webhookSecret": "your-random-secret"
+}
+```
+
+Or via CLI flags:
+
+```bash
+relay --bot-mode=webhook --webhook-url=https://your-server.com/bot --webhook-port=3000
 ```
 
 ### Requirements
@@ -434,7 +468,7 @@ WEBHOOK_SECRET=your-random-secret
 
 ### Switching back to polling
 
-Set `BOT_MODE=polling` (or remove the variable). The bot will clear any stale webhook before starting long-polling.
+Set `botMode` to `polling` in your config (or remove it — polling is the default). The bot will clear any stale webhook before starting long-polling.
 
 ### Benefits over polling
 

package/docs/getting-started.md

@@ -13,43 +13,56 @@ This guide walks you through setting up Relay from scratch.
 
 ### From npm (recommended)
 
+Relay is published as [`@4via6/relay`](https://www.npmjs.com/package/@4via6/relay) on npm:
+
+```bash
+npm install -g @4via6/relay
+```
+
+Or run directly without installing:
+
 ```bash
-npm install -g relay
+npx @4via6/relay
 ```
 
 ### From source
 
 ```bash
-git clone https://github.com/Harsh-2002/relay.git
-cd relay
+git clone https://github.com/Harsh-2002/Relay.git
+cd Relay
 npm install
 npm run build
 ```
 
 ## Configuration
 
-Copy the example environment file and edit it:
+Run the interactive setup wizard:
 
 ```bash
-cp .env.example .env
+relay onboard
 ```
 
-Open `.env` and set the required values:
+The wizard will ask for:
+1. Your Telegram bot token
+2. Your Telegram user ID
+3. Your preferred AI provider (OpenCode, Claude Code, or Codex)
+4. Provider-specific settings
+5. Optional voice transcription (STT) keys
+6. Streaming and logging preferences
+
+Config is saved to `.relay/config.json`.
 
-```env
-# Required for all providers
-BOT_TOKEN=your-telegram-bot-token
-ALLOWED_USER_ID=your-telegram-user-id
+You can also pass settings as CLI flags:
 
-# Select your provider
-PROVIDER=opencode
+```bash
+relay --bot-token=xxx --allowed-user-id=123 --provider=opencode
 ```
 
-Then configure your chosen provider. See [Providers](providers.md) for detailed setup instructions.
+See [Configuration](configuration.md) for all available options.
 
 ## Running the Bot
 
-Start the bot:
+### Foreground (default)
 
 ```bash
 # If installed globally
@@ -59,15 +72,30 @@ relay
 npm start
 ```
 
-You should see output like:
+On first run with no config, the setup wizard starts automatically.
+
+### Background (daemon mode)
 
+Run the bot as a background service that survives terminal closure:
+
+```bash
+relay start                  # Start as background daemon
+relay status                 # Check if running (PID, uptime, memory)
+relay logs                   # Tail daemon logs (Ctrl+C to exit)
+relay restart                # Restart the daemon
+relay stop                   # Stop the daemon
 ```
-Initializing opencode provider...
-opencode provider ready.
-Starting Telegram bot (long polling)...
-Bot @YourBotName is running!
+
+pm2 is auto-installed on first `relay start`. CLI flags are forwarded — e.g. `relay start --provider=claude`.
+
+### Updating
+
+```bash
+relay update
 ```
 
+Auto-detects your install method (npm or git source) and updates to the latest version. Restarts the daemon automatically if it's running.
+
 ## First Steps
 
 1. Open your bot in Telegram
@@ -80,22 +108,27 @@ Bot @YourBotName is running!
 
 ```
 relay/
-  .env.example       -- Template for environment variables
-  package.json        -- Dependencies and scripts
+  .relay/               -- Config and persisted state (auto-created)
+    config.json         -- Your configuration
+    session.json        -- Active session state
+    SKILL.md            -- Custom system prompt (optional)
+  package.json          -- Dependencies and scripts
   src/
-    index.ts          -- Entry point
-    bot.ts            -- Bot setup and middleware
-    auth.ts           -- User authentication
-    session.ts        -- Session state management
-    providers/        -- Provider implementations
-    commands/         -- Telegram command handlers
-    utils/            -- Shared utilities
-  docs/               -- This documentation
+    cli.ts              -- CLI entry point (onboard, --help, --version)
+    index.ts            -- Bot startup
+    bot.ts              -- Bot setup and middleware
+    auth.ts             -- User authentication
+    session.ts          -- Session state management
+    config/             -- Config schema, loader, setup wizard
+    providers/          -- Provider implementations
+    commands/           -- Telegram command handlers
+    utils/              -- Shared utilities (logger, store, stream, etc.)
+  docs/                 -- This documentation
 ```
 
 ## Next Steps
 
-- [Configuration Reference](configuration.md) -- All environment variables
+- [Configuration Reference](configuration.md) -- All config options and CLI flags
 - [Provider Setup](providers.md) -- Detailed provider configuration
 - [Commands](commands.md) -- Full command reference
 - [Features](features.md) -- File attachments, streaming, MCP, voice

package/docs/providers.md

@@ -1,6 +1,6 @@
 # Provider Setup
 
-Relay supports three coding agent backends. Each provider connects the bot to a different AI coding tool. Set `PROVIDER` in your `.env` file to choose one.
+Relay supports three coding agent backends. Each provider connects the bot to a different AI coding tool. Select your provider during `relay onboard` or pass `--provider=<name>`.
 
 ## OpenCode
 
@@ -16,24 +16,11 @@ There are two modes of operation:
 
 #### Mode 1: Start (recommended)
 
-Relay spawns and manages the OpenCode server automatically.
-
-```env
-PROVIDER=opencode
-OPENCODE_MODE=start
-OPENCODE_HOSTNAME=127.0.0.1
-OPENCODE_PORT=4096
-```
+Relay spawns and manages the OpenCode server automatically. This is the default.
 
 #### Mode 2: Connect
 
-Connect to an already-running OpenCode server. Use this when the server is running on a different machine or managed separately.
-
-```env
-PROVIDER=opencode
-OPENCODE_MODE=connect
-OPENCODE_URL=http://localhost:4096
-```
+Connect to an already-running OpenCode server. Use this when the server is running on a different machine or managed separately. Pass `--opencode-mode=connect --opencode-url=http://your-server:4096`.
 
 If you connect to a remote server over HTTP, the bot will show a warning. Use HTTPS for production deployments.
 
@@ -88,17 +75,15 @@ npm install @anthropic-ai/claude-code
 
 ### Configuration
 
-```env
-PROVIDER=claude
-ANTHROPIC_API_KEY=sk-ant-api03-...
-CLAUDE_MODEL=sonnet
-CLAUDE_PERMISSION_MODE=acceptEdits
-CLAUDE_CWD=/path/to/your/project
+Select Claude during `relay onboard`, or pass:
+
+```bash
+relay --provider=claude --claude-model=sonnet
 ```
 
 ### API Key
 
-Get your API key from the [Anthropic Console](https://console.anthropic.com/). The key must have access to the Claude Code API.
+Your `ANTHROPIC_API_KEY` must be set in the environment where Claude Code runs — this is the coding agent's responsibility, not Relay's. Get your API key from the [Anthropic Console](https://console.anthropic.com/).
 
 ### Models
 
@@ -165,14 +150,15 @@ npm install @openai/codex
 
 ### Configuration
 
-```env
-PROVIDER=codex
-CODEX_API_KEY=sk-...
-CODEX_MODEL=o3
-CODEX_CWD=/path/to/your/project
+Select Codex during `relay onboard`, or pass:
+
+```bash
+relay --provider=codex --codex-model=o3
 ```
 
-You can use either `CODEX_API_KEY` or `OPENAI_API_KEY`. If both are set, `CODEX_API_KEY` takes priority.
+### API Key
+
+Your `CODEX_API_KEY` or `OPENAI_API_KEY` must be set in the environment where Codex runs — this is the coding agent's responsibility, not Relay's.
 
 ### Models
 
@@ -227,10 +213,10 @@ Set `CODEX_CWD` to the project directory. Defaults to the directory where Relay
 
 ## Switching Providers
 
-To switch providers, update the `PROVIDER` variable in `.env` and restart the bot:
+To switch providers, run `relay onboard` and select a different provider, or pass `--provider=<name>`:
 
-```env
-PROVIDER=claude  # or opencode, codex
+```bash
+relay --provider=claude
 ```
 
 Sessions are provider-specific and not shared between providers. Switching providers starts fresh.