@inference-gateway/cli 0.217.0 → 0.219.0

package/README.md

@@ -9,7 +9,7 @@
 
 An agentic command-line assistant that writes code, understands project context, and uses tools to perform real tasks.
 
-[📖 Documentation](https://docs.inference-gateway.com/cli) · [🚀 Quick Start](#quick-start) · [🛠️ Tools Reference](docs/tools-reference.md) · [💬 Discussions](https://github.com/orgs/inference-gateway/discussions)
+[📖 Documentation](https://docs.inference-gateway.com/cli) · [🚀 Quick Start](#quick-start) · [🧭 Features](#features) · [💬 Discussions](https://github.com/orgs/inference-gateway/discussions)
 
 <br/>
 
@@ -19,268 +19,18 @@ An agentic command-line assistant that writes code, understands project context,
 
 </div>
 
-## ⚠️ Warning
-
-> **Early Development Stage**: This project is in its early development
-> stage and breaking changes are expected until it reaches a stable version.
->
-> Always use pinned versions by specifying a specific version tag when
-> downloading binaries or using install scripts.
-
-## Table of Contents
-
-- [Features](#features)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Commands](#commands)
-- [Tools for LLMs](#tools-for-llms)
-- [Configuration](#configuration)
-- [Cost Tracking](#cost-tracking)
-- [Tool Approval System](#tool-approval-system)
-- [Shortcuts](#shortcuts)
-- [Channels (Remote Messaging)](#channels-remote-messaging)
-- [Heartbeat (Periodic Wake-Up)](#heartbeat-periodic-wake-up)
-- [Agent Skills](#agent-skills)
-- [Computer Use](#computer-use)
-- [Persistent Memory](#persistent-memory)
-- [Reminders & Command Hooks](#reminders--command-hooks)
-- [Global Flags](#global-flags)
-- [Examples](#examples)
-- [Development](#development)
-- [License](#license)
-
-## Features
-
-- **Automatic Gateway Management**: Automatically downloads and runs the Inference Gateway binary (no Docker required!)
-- **Zero-Configuration Setup**: Start chatting immediately with just your API keys in a `.env` file
-- **Interactive Chat**: Chat with models using an interactive interface
-- **Status Monitoring**: Check gateway health and resource usage
-- **Conversation History**: Store and retrieve past conversations with multiple storage backends
-  - [Conversation Storage](docs/conversation-storage.md) - Detailed storage backend documentation
-  - [Conversation Title Generation](docs/conversation-title-generation.md) - AI-powered title generation system
-  - [Database Migrations](docs/database-migrations.md) - Schema migration system for the SQLite/Postgres backends
-- **Conversation Versioning**: Navigate back in time to previous conversation points (double ESC)
-  - View message history with timestamps
-  - Restore conversation to any previous user message
-  - Permanent deletion of messages after restore point
-  - [Learn more →](docs/conversation-versioning.md)
-- **Configuration Management**: Manage gateway settings via YAML config
-- **Project Initialization**: Set up local project configurations
-- **Tool Execution**: LLMs can execute allowed commands and tools - [See all tools →](docs/tools-reference.md)
-- **Tool Approval System**: User approval workflow for sensitive operations with real-time diff visualization
-- **Agent Modes**: Four operational modes for different workflows:
-  - **Standard Mode** (default): Normal operation with all configured tools and approval checks
-  - **Plan Mode**: Read-only mode for planning and analysis without execution - [Learn more →](docs/plan-mode.md)
-  - **Auto-Accept Mode**: All tools auto-approved for rapid execution (YOLO mode)
-  - **Auto+Judge Mode**: No human approves tool calls - an LLM judge decides gated calls - [Learn more →](docs/judge-mode.md)
-  - Toggle between modes with **Shift+Tab**
-- **Token Usage Tracking**: Accurate token counting with polyfill support for providers that don't return usage metrics
-- **Cost Tracking**: Real-time cost calculation for API usage with per-model breakdown and configurable pricing
-- **Inline History Auto-Completion**: Smart command history suggestions with inline completion
-- **GitHub Issue References (`#`)**: Type `#` in chat to open a dropdown of the current
-  repo's open issues. Selecting one inserts a `#N` token that is highlighted in the input
-  and, on submit, expanded inline into the issue's title, body, and recent comments - so
-  the agent works from full context without a redundant `gh issue view` lookup. Gracefully
-  no-ops when `gh` is not installed or the repo has no remote.
-- **Customizable Keybindings**: Fully configurable keyboard shortcuts for the chat interface
-- **Selectable Status Indicators**: Press `↓` in chat to select the indicators below the input and
-  open the matching view with `enter` (model → model selection, theme → theme selection,
-  `A2A:` → registered agents, `Tools:` → available tools, `⚙` jobs → task management)
-- **Model Thinking Visualization**: When models use extended thinking,
-  their internal reasoning process is displayed as collapsible blocks above responses (toggle with **ctrl+k** by default, configurable via `display_toggle_thinking`)
-- **Extensible Shortcuts System**: Create custom commands with AI-powered snippets - [Learn more →](docs/shortcuts-guide.md)
-- **MCP Server Support**: Direct integration with Model Context Protocol servers for extended tool capabilities.
-  Servers must speak MCP `2026-07-28`; the gateway's `/mcp` works as a single entry for all its servers -
-  [Learn more →](docs/mcp-integration.md)
-- **Custom Tools**: Add tools written in any language with one YAML manifest per tool in `~/.infer/tools/` or a
-  project's `.infer/tools/` / `.agents/tools/` - no SDK or server needed - [Learn more →](docs/custom-tools.md)
-- **Web Terminal Interface**: Browser-based terminal access with tabbed sessions for remote access and multi-session workflows - [Learn more →](docs/web-terminal.md)
-- **Remote Messaging Channels**: Control the agent from Telegram, WhatsApp, and other platforms via a pluggable channel system - [Learn more →](docs/channels.md)
-- **Speech-to-Text (Whisper)**: Dictate into chat with `/voice` and transcribe inbound Telegram voice messages, locally and offline -
-  off by default - [Learn more →](docs/speech-to-text.md)
-- **Text-to-Speech (Qwen3-TTS)**: Turn text into a spoken WAV locally and offline, with zero-shot voice cloning
-  from a short reference recording - off by default - [Learn more →](docs/text-to-speech.md)
-- **Text-to-Music**: Compose a music clip from a text prompt through the gateway's Music API -
-  off by default - [Learn more →](docs/text-to-music.md)
-- **Scheduled Tasks**: Ask the agent (over Telegram, etc.) to run a prompt on a cron schedule and deliver the result back through the same channel -
-  recurring ("send me a quote every morning") or one-off ("remind me at 6pm today") - [Learn more →](docs/scheduling.md)
-- **Heartbeat (Periodic Wake-Up)**: Wake the agent on a fixed interval to check for pending todos and background work,
-  with a separate configurable system prompt - off by default - [Learn more →](docs/heartbeat.md)
-- **Agent Skills**: Drop-in `SKILL.md` instruction folders the agent discovers and loads on demand;
-  install them straight from GitHub with `infer skills install` - on by default - [Learn more →](docs/skills.md)
-- **Plugins**: Install Claude Code-format plugins (skills + an always-on `AGENTS.md` ruleset) from GitHub with
-  `infer plugins install owner/repo` - content only, plugin code is never executed - [Learn more →](docs/plugins.md)
-- **Persistent Memory**: Cross-session memory stored as individual Markdown fact-files with an
-  auto-maintained `MEMORY.md` index that is injected at session start - on by default - [Learn more →](#persistent-memory)
-- **Subagents**: Spawn parallel `infer headless` subprocesses from chat with the `Agent` tool to fan out
-  independent work (research, edits, investigations) and fold their results back into the conversation;
-  define reusable presets as Markdown files in `.infer/agents/` (Claude Code / Gemini CLI compatible)
-  - [Learn more →](docs/subagents.md)
-- **Computer Use**: Let the agent drive the desktop - mouse, keyboard, screenshots, app focus - across
-  macOS, X11, and Wayland - off by default - [Learn more →](#computer-use)
-- **Reminders & Command Hooks**: Inject system reminders or run shell commands at agent-loop hook
-  points to enforce project conventions - [Learn more →](#reminders--command-hooks)
+> **Early development stage**: breaking changes are expected until the project reaches a stable version.
+> Always pin a specific version tag when downloading binaries or using install scripts.
 
 ## Installation
 
-### Using npm/npx (Recommended)
-
-If you already have Node.js (>= 18), run the CLI with npx - no Go toolchain or manual
-download required. The matching native binary is fetched and cached on first use:
+The recommended install is npm/npx - the matching native binary is fetched and cached on first use:
 
 ```bash
-# Run without installing
-npx @inference-gateway/cli@latest --help
 npx @inference-gateway/cli@latest chat
 ```
 
-Or install it globally:
-
-```bash
-npm install -g @inference-gateway/cli
-infer --help
-```
-
-> **Not recommended for production.** For production or CI, prefer the
-> [install script](#using-install-script), [Nix flake](#using-nix-flake--flox),
-> [container image](#using-container-image), or [building from source](#build-from-source). Prebuilt binaries cover Linux, macOS, and Windows on
-> amd64/arm64.
-
-### Using Go Install
-
-```bash
-go install github.com/inference-gateway/cli/cmd/infer@latest
-```
-
-This installs the binary as `infer`.
-
-### Using Nix Flake / Flox
-
-With Nix (flakes enabled), run directly without installing:
-
-```bash
-nix run github:inference-gateway/cli
-
-# Pin a specific release
-nix run github:inference-gateway/cli/v0.135.0
-```
-
-Or install into your profile:
-
-```bash
-nix profile install github:inference-gateway/cli
-```
-
-With [Flox](https://flox.dev), pin it in your environment manifest (`.flox/env/manifest.toml`):
-
-```toml
-[install]
-infer.flake = "github:inference-gateway/cli"
-```
-
-Then `flox activate` makes `infer` available in the environment. Pin a release by appending the tag: `github:inference-gateway/cli/v0.135.0`.
-
-### Using Container Image
-
-```bash
-# Create network and deploy inference gateway first
-docker network create inference-gateway
-docker run -d --name inference-gateway --network inference-gateway \
-  --env-file .env \
-  ghcr.io/inference-gateway/inference-gateway:latest
-
-# Pull and run the CLI
-docker pull ghcr.io/inference-gateway/cli:latest
-docker run -it --rm --network inference-gateway ghcr.io/inference-gateway/cli:latest chat
-```
-
-### Using Install Script
-
-**Linux/macOS:**
-
-```bash
-# Latest version
-curl -fsSL https://raw.githubusercontent.com/inference-gateway/cli/main/install.sh | bash
-
-# Specific version
-curl -fsSL https://raw.githubusercontent.com/inference-gateway/cli/main/install.sh | bash -s -- --version v0.77.0
-
-# Custom installation directory
-curl -fsSL https://raw.githubusercontent.com/inference-gateway/cli/main/install.sh | bash -s -- --install-dir $HOME/.local/bin
-```
-
-**Windows (PowerShell 5.1+ / pwsh):**
-
-```powershell
-# Latest version
-.\install.ps1
-
-# Specific version
-.\install.ps1 -Version v0.1.0
-
-# Custom installation directory
-$env:INSTALL_DIR = "C:\tools"; .\install.ps1
-```
-
-Or run directly from GitHub:
-
-```powershell
-# Download and run
-iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/inference-gateway/cli/main/install.ps1'))
-```
-
-### Manual Download
-
-Download the latest release binary for your platform from the [releases page](https://github.com/inference-gateway/cli/releases).
-
-Available binaries:
-
-| Platform | Binary |
-| -------- | ------ |
-| Linux amd64 | `infer-linux-amd64` |
-| Linux arm64 | `infer-linux-arm64` |
-| macOS amd64 (Intel) | `infer-darwin-amd64` |
-| macOS arm64 (Apple Silicon) | `infer-darwin-arm64` |
-| Windows amd64 | `infer-windows-amd64` (rename to `infer.exe`) |
-| Windows arm64 | `infer-windows-arm64` (rename to `infer.exe`) |
-
-**Verify the binary** (recommended for security):
-
-```bash
-# Download binary and checksums
-curl -L -o infer-darwin-amd64 \
-  https://github.com/inference-gateway/cli/releases/latest/download/infer-darwin-amd64
-curl -L -o checksums.txt \
-  https://github.com/inference-gateway/cli/releases/latest/download/checksums.txt
-
-# Verify checksum
-shasum -a 256 infer-darwin-amd64
-grep infer-darwin-amd64 checksums.txt
-
-# Install
-chmod +x infer-darwin-amd64
-sudo mv infer-darwin-amd64 /usr/local/bin/infer
-```
-
-For advanced verification with Cosign signatures, see [Binary Verification Guide](docs/binary-verification.md).
-
-### Build from Source
-
-```bash
-git clone https://github.com/inference-gateway/cli.git
-cd cli
-go build -o infer ./cmd/infer
-sudo mv infer /usr/local/bin/
-```
-
-On Windows, build with:
-
-```powershell
-git clone https://github.com/inference-gateway/cli.git
-cd cli
-go build -o infer.exe ./cmd/infer
-# The binary is at .\infer.exe
-```
+See **[Installation](docs/installation.md)** for production and CI installs, and **[Binary Verification](docs/binary-verification.md)** to verify a download.
 
 ## Quick Start
 
@@ -290,12 +40,11 @@ go build -o infer.exe ./cmd/infer
 infer init
 ```
 
-This creates the shared `~/.infer/` configuration directory. All state
-(conversations, logs, history, artifacts) lives under `~/.infer/` too; a
-project `.infer/` is an optional config override layer you create with
-`infer config set --project` when a project needs different settings.
+This creates the shared `~/.infer/` configuration directory. All state (conversations, logs, history,
+artifacts) lives there, and a project `.infer/` is an optional override layer you create with
+`infer config set --project`.
 
-2. **Set up your environment** (create `.env` file):
+2. **Set up your environment** (create a `.env` file):
 
 ```env
 ANTHROPIC_API_KEY=your_key_here
@@ -303,18 +52,8 @@ OPENAI_API_KEY=your_key_here
 DEEPSEEK_API_KEY=your_key_here
 ```
 
-Provider keys resolve in this order, first hit wins: the system environment, the
-project `.env`, then the userspace fallback `~/.infer/auth.yaml` - a flat YAML
-map of provider key env vars, so you can keep keys in one place across all
-projects (or run `infer` outside any project):
-
-```yaml
-ANTHROPIC_API_KEY: sk-ant-...
-OPENAI_API_KEY: sk-...
-```
-
-A missing `auth.yaml` changes nothing, and a malformed one is ignored with a
-logged warning. Keep the file private (`chmod 600 ~/.infer/auth.yaml`).
+Provider keys resolve in this order, first hit wins: the system environment, the project `.env`, then the userspace
+`~/.infer/auth.yaml` fallback - see [Provider API Keys](docs/configuration-reference.md#provider-api-keys).
 
 3. **Start chatting**:
 
@@ -322,1227 +61,70 @@ logged warning. Keep the file private (`chmod 600 ~/.infer/auth.yaml`).
 infer chat
 ```
 
-### Next Steps
-
-Now that you're up and running, explore these guides:
-
-- **[Commands Reference](docs/commands-reference.md)** - Complete command documentation
-- **[Tools Reference](docs/tools-reference.md)** - Available tools for LLMs
-- **[Custom Tools](docs/custom-tools.md)** - Add your own tools in any language through YAML manifests
-- **[Configuration Guide](docs/configuration-reference.md)** - Full configuration options
-- **[Directory Structure](docs/directory-structure.md)** - Map of every file and subdirectory the CLI creates under `.infer/` and `~/.infer/`
-- **[Web Terminal](docs/web-terminal.md)** - Browser-based terminal interface
-- **[Shortcuts Guide](docs/shortcuts-guide.md)** - Custom shortcuts and AI-powered snippets
-- **[A2A Agents](docs/agents-configuration.md)** - Agent-to-agent communication setup
-- **[Markdown Subagents](docs/subagents.md)** - Reusable subagent presets in `.infer/agents/<name>.md`
-- **[Telemetry](docs/telemetry.md)** - OpenTelemetry traces/metrics and baggage propagation
-- **[AG-UI Output](docs/ag-ui-output.md)** - AG-UI protocol event stream for the headless agent
-
-## Commands
-
-The CLI provides several commands for different workflows. For detailed documentation, see [Commands Reference](docs/commands-reference.md).
-
-### Core Commands
-
-**`infer init`** - Initialize the userspace baseline configuration
-
-```bash
-infer init              # Seed the shared ~/.infer/ baseline
-infer init --overwrite  # Re-seed the baseline files
-```
-
-**`infer chat`** - Start an interactive chat session with model selection
-
-```bash
-# Terminal mode (default)
-infer chat
-
-# Resume a previous chat session
-infer conversations list  # Find session IDs
-infer chat --session-id abc-123-def
-
-# Web terminal mode with browser interface
-infer chat --web
-infer chat --web --port 8080  # Custom port
-```
-
-**Features:** Model selection, real-time streaming, scrollable history, four agent modes (Standard/Plan/Auto-Accept/Auto+Judge).
-Select text by holding Shift (Option on macOS terminals) while dragging.
-
-**Web Mode Features:**
-
-- Browser-based terminal using xterm.js
-- Multiple independent tabbed sessions
-- Automatic session cleanup on inactivity
-- Each tab manages its own `infer chat` process with isolated containers
-- Access from any device on the network
-- Responsive terminal sizing with horizontal padding
-
-**`infer headless`** - Execute autonomous tasks in background mode
-
-```bash
-# Start new agent sessions
-infer headless "Please fix the github issue 38"
-infer headless --model "openai/gpt-4" "Implement feature from issue #42"
-infer headless "Analyze this UI issue" --files screenshot.png
-
-# Resume existing sessions
-infer conversations list  # Find session IDs
-infer headless "continue fixing the bug" --session-id abc-123-def
-infer headless "analyze new logs" --session-id abc-123 --files error.log
-```
-
-**Features:** Autonomous execution, multimodal support (images/files), parallel tool execution, **session resumption**.
-
-### Configuration Commands
-
-**`infer config`** - Manage CLI configuration settings
-
-```bash
-# Read any value (effective config: defaults + ~/.infer + .infer + env)
-infer config get agent.model
-infer config get                       # dump the whole effective config
-
-# Agent configuration
-infer config set agent.model "deepseek/deepseek-v4-pro"
-infer config set agent.max_turns 100
-
-# Tool management
-infer config set tools.enabled true
-infer config set tools.bash.enabled true
-infer config set tools.safety.require_approval true
-
-# Write a project-level override into ./.infer/config.yaml instead
-infer config set agent.model "openai/gpt-4o" --project
-```
-
-> System prompts live in `prompts.yaml` (e.g. `prompts.agent.system_prompt`), not
-> in `config.yaml`, so they are edited there rather than via `config set`.
-
-See [Commands Reference](docs/commands-reference.md#configuration-management) for all configuration options.
-
-### Agent Management
-
-**`infer agents`** - Manage A2A (Agent-to-Agent) agent configurations
-
-```bash
-infer agents init                    # Initialize agents configuration
-infer agents add browser-agent       # Add an agent from the registry with defaults
-infer agents add browser-agent --tag lightpanda  # Pick another image tag (engine/version)
-infer agents add custom https://...  # Add a custom agent
-infer agents list                    # List all agents
-```
-
-For detailed A2A setup, see [A2A Agents Configuration](docs/agents-configuration.md); for how
-connections are established and tasks polled, see [A2A Connections](docs/a2a-connections.md).
-
-### Utility Commands
-
-**`infer status`** - Check gateway health and resource usage
-
-```bash
-infer status
-```
-
-**`infer conversations`** - List and manage conversation history
-
-```bash
-infer conversations list                    # List all saved conversations
-infer conversations list --limit 20         # List first 20 conversations
-infer conversations list --offset 40 -l 20  # Paginate: conversations 41-60
-infer conversations list --format json      # Output as JSON
-
-infer conversations show <session-id>                  # Show a conversation's entries
-infer conversations show <session-id> --include-hidden # Include hidden entries (e.g. system reminders)
-infer conversations show <session-id> --format json    # One JSON object per line (jq-friendly)
-```
-
-**`infer conversation-title`** - Manage AI-powered conversation titles
-
-```bash
-infer conversation-title generate  # Generate titles for all conversations
-infer conversation-title status    # Show generation status
-```
-
-**`infer skills`** - Manage Agent Skills (reusable `SKILL.md` instruction folders)
-
-```bash
-infer skills list                                # List discovered skills
-infer skills install skill-creator               # Install a skill from GitHub
-infer skills install acme/internal-comms --user  # Install to ~/.infer/skills
-infer skills uninstall pdf                        # Remove a skill by name
-```
-
-See [Agent Skills](#agent-skills) and [docs/skills.md](docs/skills.md) for the format.
-
-**`infer plugins`** - Manage Claude Code-format plugins (skills + instruction rulesets)
-
-```bash
-infer plugins install DietrichGebert/ponytail    # Install a plugin from GitHub
-infer plugins list                                # List installed plugins
-infer plugins disable ponytail                    # Unload its skills + instructions
-infer plugins update                              # Re-fetch all plugins
-infer plugins remove ponytail                     # Remove entirely
-```
-
-See [docs/plugins.md](docs/plugins.md) for the mapping and security model.
-
-**`infer avatars`** - Create and manage the TextToVideo avatar library (`~/.infer/avatars/<name>/` portrait folders)
-
-```bash
-infer avatars create presenter --from me.jpg   # Photo + generated three-quarter views
-infer avatars list                             # List avatars and their images
-infer avatars list --format json               # Machine-readable listing
-infer avatars delete presenter                 # Remove an avatar folder
-```
-
-See [docs/text-to-video.md](docs/text-to-video.md#avatar-library) for the layout. With `text_to_video.create_avatar` the agent
-can build avatars itself through the `CreateAvatar` tool.
-
-**`infer export`** - Export a conversation to a Markdown file
-
-```bash
-infer conversations list      # Find the session ID
-infer export <session-id>     # Writes ~/.infer/projects/<slug>/exports/chat_export_<timestamp>.md
-```
-
-**`infer insights`** - Analyze past sessions for repeatable workflows and recurring tool failures
-
-```bash
-infer insights                # Every saved session
-infer insights 7d             # Only the last 7 days (also 24h, 30d)
-infer insights --model <id>   # Pick the model; defaults to agent.model
-```
-
-Writes a markdown report to `~/.infer/insights/`. Needs conversation storage enabled.
-
-Reads the conversation store, the telemetry directory, the log directory and the persistent
-memory index (`MEMORY.md`, capped at `memory.max_chars`). `infer reset insights` runs the
-analysis before the wipe, so the facts survive in the report even though the memory directory
-does not.
-
-The logs are the only source that sees a failure which never reached a saved session - a startup
-crash, a gateway that never came up, a background job that died. They are deduplicated before the
-model sees them: records at or above `logging.insights_min_level` (default `warn`) inside the
-window are folded by normalized message, so lines differing only in a path, an id or a number
-become one group with a count, a first/last timestamp and one verbatim sample. The report's
-frontmatter states how many records were read (`log_records`) and how many groups survived
-(`log_groups`). Only the structured `app-*.log` and `daemon-*.log` files and their `.gz` archives
-are read; `gateway-*.log` is raw subprocess output with no level or timestamp to filter on, and
-the gateway's own failures are logged through zap into `app-*.log` anyway.
-
-The analysis runs on `agent.max_tokens` (default 8192) rather than a fixed budget — a
-reasoning model spends that budget thinking before it answers, and too small a value fails
-the run outright. The written analysis is capped at 200 lines / 16000 characters, so a
-model that ignores the requested length cannot flood the report.
-
-Each report records what it cost to produce in its own frontmatter
-(`analysis_prompt_tokens`, `analysis_completion_tokens`, `analysis_total_tokens`, and
-`analysis_reasoning_tokens` where the provider breaks it out), so the price of a run is
-visible in the artifact rather than guessed at.
-
-**`infer reset`** - Wipe all local runtime state and start fresh
-
-```bash
-infer reset             # Preview every path that would be deleted; deletes nothing
-infer reset confirm     # Perform the wipe
-infer reset insights    # Analyze past sessions first, then preview (takes --model)
-```
-
-Clears the runtime directories of **every project on this machine**, the persistent memory directory
-and the local conversation store. Per-project runtime directories are deleted rather than recreated
-empty, and a project whose working directory no longer exists is removed entirely.
-
-Config, custom shortcuts, skills and saved insights are preserved; remote stores (postgres, redis, d1)
-are skipped, and a git-backed memory directory syncs back from its remote on the next run.
-
-The `/reset` and `/insights` chat shortcuts are thin YAML wrappers over these commands, written to
-`~/.infer/shortcuts/` by `infer init` - edit them like any other shortcut.
-
-**`infer version`** - Display CLI version information
-
-```bash
-infer version
-```
-
-## Tools for LLMs
-
-When tool execution is enabled, LLMs can use various tools to interact with your system. Below is a
-summary of available tools. For detailed documentation, parameters, and examples, see
-[Tools Reference](docs/tools-reference.md).
-
-<div align="center">
-
-<img src="./assets/tui-tools.png" width="760" alt="A Grep tool call executed by the agent, with its result and the assistant's summary" />
-
-*The agent running a `Grep` tool call - results are collapsible with `ctrl+o`*
-
-</div>
-
-Tools are grouped by category below. Many are gated behind a config flag (noted per group);
-the always-available set is registered for every session. There is **no built-in GitHub tool** -
-use the `gh` CLI through Bash (or the built-in `/scm` shortcuts) for GitHub operations.
-
-**Core file & search** (always available):
-
-| Tool | Purpose | Approval |
-| ------ | --------- | ---------- |
-| **Read** | Read file contents with line ranges | No |
-| **Write** | Write content to files | Yes |
-| **Edit** | Exact string replacements in files | Yes |
-| **MultiEdit** | Multiple atomic edits to a single file | Yes |
-| **Delete** | Delete files and directories | Yes |
-| **Grep** | Search files with regex (ripgrep/Go) | No |
-| **Tree** | Display directory structure | No |
-
-**Shell** (Bash is always available; the background-shell trio needs `tools.bash.background_shells.enabled`):
-
-| Tool | Purpose | Approval |
-| ------ | --------- | ---------- |
-| **Bash** | Execute shell commands (per-mode allow-list) | Optional |
-| **BashOutput** | Read new output from a running background shell | Yes |
-| **KillShell** | Terminate a background shell | Yes |
-| **ListShells** | List background shells and their state | Yes |
-| **Wait** | Block until a condition is met (shells exit, file event, or check command succeeds) - no LLM round-trips wasted | No |
-
-**Task & planning** (`AskUserQuestion` needs `tools.ask_user_question.enabled`):
-
-| Tool | Purpose | Approval |
-| ------ | --------- | ---------- |
-| **TodoWrite** | Create and manage task lists | No |
-| **RequestPlanApproval** | Submit a plan for approval and persist it (plan mode) | No |
-| **AskUserQuestion** | Ask the user multiple-choice questions | No |
-| **RequestApproval** | Ask the user to override a judge rejection once (judge mode) | No |
-
-**Web** (`WebSearch`/`WebFetch` need their respective config flag):
-
-| Tool | Purpose | Approval |
-| ------ | --------- | ---------- |
-| **WebSearch** | Search the web (DuckDuckGo/Google) | Yes |
-| **WebFetch** | Fetch content from a URL | No |
-
-`WebFetch` does not require approval by default; set `tools.web_fetch.require_approval: true` to require it.
-
-**Subagents** (the `Agent` tool and its companions, enabled by default):
-
-| Tool | Purpose | Approval |
-| ------ | --------- | ---------- |
-| **Agent** | Spawn an `infer headless` subprocess to run work in parallel | Yes |
-| **ListSubagents** | List spawned subagents and their status | No |
-| **GetSubagentResult** | Re-read a finished subagent's last message | No |
-| **ReadSubagentScreen** | Capture an interactive subagent's terminal screen | No |
-| **SendSubagentInput** | Type into an interactive subagent's TUI | Yes |
-| **CloseSubagent** | Stop a subagent or tidy a finished pane | Yes |
-| **ApproveSubagent** | Relay an approval decision to a waiting subagent | Yes |
-
-**Computer Use** (require `computer_use.enabled`; these bypass the approval prompt and run silently):
-
-| Tool | Purpose | Approval |
-| ------ | --------- | ---------- |
-| **Computer** | Read the accessibility tree, press labelled controls, capture screenshots, and control mouse/keyboard | Configurable |
-| **GetLatestFrame** | Read the latest frame from a named source (screen, camera directory) | No |
-| **RecordStart** | Record the screen, a window, or a region to MP4 (needs `computer_use.recording.enabled`) | Configurable |
-| **RecordStop** | Stop the recording and return the file path, duration, and size | Configurable |
-
-**Media** (each gated by its own flag; all output is written to disk, never played aloud):
-
-| Tool | Purpose | Approval | Enabled by |
-| ------ | --------- | ---------- | ------------ |
-| **ImageGeneration** | Generate an image from a prompt into `~/.infer/projects/<project-slug>/artifacts/` | No | `tools.image_generation.enabled` |
-| **ImageEdit** | Edit an existing image and save the result | No | `tools.image_edit.enabled` |
-| **ImageVariation** | Produce a variation of an existing image | No | `tools.image_variation.enabled` |
-| **TextToSpeech** | Synthesize speech to a WAV (local llama-tts or gateway Audio API), optionally cloning a voice | No | `text_to_speech.enabled` |
-
-**Memory, scheduling & A2A** (each gated by its own flag):
-
-| Tool | Purpose | Approval | Enabled by |
-| ------ | --------- | ---------- | ------------ |
-| **Memory** | Persistent, cross-session fact storage | No | `memory.enabled` (default on) |
-| **Schedule** | Cron-driven recurring/one-off tasks via the originating channel | Yes | `tools.schedule.enabled` |
-| **A2A_SubmitTask** | Submit a task to an A2A agent | Yes | A2A enabled |
-| **A2A_QueryAgent** | Query an A2A agent's capabilities | No | A2A enabled |
-| **A2A_QueryTask** | Check an A2A task's status | No | A2A enabled |
-
-> **Approval** reflects the default policy. The global default is `tools.safety.require_approval: true`,
-> so a tool is **No** only where it is explicitly exempt in code (read-only file/search tools, Memory,
-> the plan/question tools, subagent reads, and computer-use). Bash is governed instead by the per-mode
-> bash allow-list. Override any tool with `tools.<name>.require_approval`.
->
-> **MCP tools** are not listed here - they are discovered and registered dynamically at runtime from your
-> configured MCP servers and surface as `MCP_<server>_<tool>` (see [MCP Integration](docs/mcp-integration.md)).
-
-**Tool Configuration:**
-
-Tools can be enabled/disabled and configured individually:
-
-```bash
-# Enable/disable specific tools
-infer config set tools.bash.enabled true
-infer config set tools.write.enabled true
-
-# Configure tool settings
-infer config set tools.grep.backend ripgrep
-# List values are comma-separated and replace the whole list
-infer config set tools.web_fetch.allowed_domains "example.com,github.com"
-```
-
-See [Tools Reference](docs/tools-reference.md) for complete documentation.
-
-## Configuration
-
-The CLI uses a powerful 2-layer configuration system with environment variable support.
-
-### Configuration Quick Start
-
-Create a minimal configuration:
-
-```yaml
-# .infer/config.yaml
-gateway:
-  url: http://localhost:8080
-  standalone_binary: true  # Run the gateway as a standalone binary (false = Docker container)
-
-tools:
-  enabled: true
-  bash:
-    enabled: true
-
-agent:
-  model: "deepseek/deepseek-v4-pro"
-  max_turns: 50
-
-chat:
-  theme: tokyo-night
-```
-
-System prompts and custom instructions live in `prompts.yaml`, not `config.yaml`:
-
-```yaml
-# .infer/prompts.yaml
-agent:
-  system_prompt: "You are a helpful assistant"  # Base identity
-  custom_instructions: ""  # Additional instructions appended to system prompt
-```
-
-### Configuration Layers
-
-1. **Command Line Flags** - Highest priority
-2. **Environment Variables** (`INFER_*`)
-3. **Project Config** (`.infer/config.yaml`)
-4. **Userspace Config** (`~/.infer/config.yaml`)
-5. **Built-in Defaults** - Lowest priority
-
-**Example:**
-
-```bash
-# Set via command flag (highest priority; beats env vars and config files)
-infer headless --model "anthropic/claude-4" "Summarize this repository"
-
-# Or via environment variable (beats config files)
-export INFER_AGENT_MODEL="openai/gpt-4"
-
-# Or via config file
-infer config set agent.model "deepseek/deepseek-v4-pro"
-```
-
-The two exceptions where the environment variable wins over the flag:
-`INFER_TOOLS_BASH_ALLOW_APPEND` (over `--tools-bash-allow-append`) and
-`INFER_REMINDERS_CONFIG` (over `--reminders-file`).
-
-### Key Configuration Options
-
-- **gateway.url** - Gateway URL (default: `http://localhost:8080`)
-- **gateway.standalone_binary** - Run the gateway as a standalone binary instead of a Docker container (default: `true`)
-- **tools.enabled** - Enable/disable all tools (default: `true`)
-- **agent.model** - Default model for agent operations
-- **prompts.agent.system_prompt** (prompts.yaml) - Base identity for the agent (e.g., `"You are a helpful assistant"`)
-- **prompts.agent.custom_instructions** (prompts.yaml) - Additional instructions appended after the system prompt
-- **agent.max_turns** - Maximum turns for agent sessions (default: `50`)
-- **chat.theme** - Chat interface theme (default: `tokyo-night`)
-- **chat.status_bar.enabled** - Enable/disable status bar (default: `true`)
-- **chat.status_bar.indicators** - Configure individual status indicators (all enabled by default except `max_output`)
-- **web.enabled** - Enable web terminal mode (default: `false`)
-- **web.port** - Web server port (default: `3000`)
-- **web.host** - Web server host (default: `localhost`)
-- **web.session_inactivity_mins** - Minutes a session may go without activity before it is reaped (default: `5`).
-  A connected browser tab refreshes its session every 10s, so in practice this only reaps sessions whose
-  connection is gone or stalled. `0` or negative disables cleanup entirely.
-
-### Environment Variables
-
-All configuration can be set via environment variables with the `INFER_` prefix:
-
-```bash
-export INFER_GATEWAY_URL="http://localhost:8080"
-export INFER_GATEWAY_MOCK=true # embedded mock gateway with canned scenario responses, no real LLM
-export INFER_AGENT_MODEL="deepseek/deepseek-v4-pro"
-export INFER_TOOLS_BASH_ENABLED=true
-export INFER_CHAT_THEME="tokyo-night"
-
-# Web terminal configuration
-export INFER_WEB_PORT=3000
-export INFER_WEB_HOST="localhost"
-export INFER_WEB_SESSION_INACTIVITY_MINS=5
-```
-
-**Format:** `INFER_<PATH>` where dots become underscores.
-Example: `agent.model` → `INFER_AGENT_MODEL`
-
-For complete configuration documentation, including all options and environment variables, see [Configuration Reference](docs/configuration-reference.md).
-
-## Cost Tracking
-
-The CLI automatically tracks API costs based on token usage for all providers and models.
-Costs are calculated in real-time with support for both aggregate totals and per-model breakdowns.
-
-### Viewing Costs
-
-Use the `/cost` command in any chat session to see the cost breakdown:
-
-```bash
-# In chat, use the /cost shortcut
-/cost
-```
-
-This displays:
-
-- **Total session cost** in USD
-- **Input/output costs** separately
-- **Per-model breakdown** when using multiple models
-- **Token usage** for each model
-
-**Status Bar**: Session costs are also displayed in the status bar (e.g., `💰 $0.0234`) if enabled.
-
-### Configuring Pricing
-
-The CLI includes hardcoded pricing for 30+ models across all major providers
-(Anthropic, OpenAI, Google, DeepSeek, Groq, Mistral, Cohere, etc.).
-Prices are updated regularly to match current provider pricing.
-
-The model picker groups models into three categories you can filter with the
-`[1] All` / `[2] Free` / `[3] Paid` / `[4] Pro` tabs:
-
-- **Free** - no per-token cost (e.g. local Ollama, Gemma).
-- **Paid** - billed per token at the listed `$input/$output per MTok` rate.
-- **Pro** - gated behind a paid **Pro subscription** (some Ollama Cloud models).
-  These have no per-token price but are not free, so they are marked
-  `pro subscription` instead of `free` to avoid the misleading label.
-
-**Override pricing** for specific models or add pricing for custom models:
-
-```yaml
-# .infer/config.yaml
-pricing:
-  enabled: true
-  currency: "USD"
-  custom_prices:
-    # Override existing model pricing
-    "openai/gpt-4o":
-      input_price_per_mtoken: 2.50    # Price per million input tokens
-      output_price_per_mtoken: 10.00  # Price per million output tokens
-
-    # Add pricing for custom/local models
-    "ollama/llama3.2":
-      input_price_per_mtoken: 0.0
-      output_price_per_mtoken: 0.0
-
-    "custom-fine-tuned-model":
-      input_price_per_mtoken: 5.00
-      output_price_per_mtoken: 15.00
-
-    # Mark a model as Pro-subscription only (no per-token cost, but gated)
-    "ollama_cloud/deepseek-v4-pro":
-      input_price_per_mtoken: 0.0
-      output_price_per_mtoken: 0.0
-      requires_pro: true
-```
-
-> **Note:** A custom entry fully replaces the default for that model. Omitting
-> `requires_pro` in a custom override resets it to `false`, so re-state
-> `requires_pro: true` if you override a model the CLI flags as Pro by default.
-
-**Via environment variables:**
-
-```bash
-# Disable cost tracking entirely
-export INFER_PRICING_ENABLED=false
-
-# Hide cost from status bar
-export INFER_CHAT_STATUS_BAR_INDICATORS_COST=false
-```
-
-> **Note:** `pricing.custom_prices` is a map keyed by `provider/model`, so its entries
-> cannot be set through environment variables. Override per-model pricing only via
-> the `custom_prices` block in `config.yaml` (shown above).
-
-**Status Bar Configuration:**
-
-```yaml
-# .infer/config.yaml
-chat:
-  status_bar:
-    enabled: true
-    indicators:
-      cost: true  # Show/hide cost indicator
-```
-
-### Cost Calculation
-
-- Costs are calculated as: `(tokens / 1,000,000) × price_per_million_tokens`
-- Prices are per million tokens (input and output priced separately)
-- Models without pricing data (Ollama, free tiers) show $0.00
-- Token counts use actual usage from providers or polyfilled estimates
-
-## Tool Approval System
-
-The CLI includes a comprehensive approval system for sensitive tool operations, providing security and
-visibility into what actions LLMs are taking.
-
-### How It Works
-
-When a tool requiring approval is executed:
-
-1. **Validation**: Tool arguments are validated
-2. **Approval Prompt**: User sees tool details with:
-   - Tool name and parameters
-   - Real-time diff preview (for file modifications)
-   - Approve/Reject/Auto-approve options
-3. **Execution**: Tool runs only if approved
-
-### Default Approval Requirements
-
-The global default is `tools.safety.require_approval: true`, so **any tool not explicitly exempt requires
-approval**; override per tool with `tools.<name>.require_approval`.
-
-| Tool | Requires Approval | Reason |
-| ------ | ------------------- | --------- |
-| Write, Edit, MultiEdit, Delete | Yes | Create / modify / remove files |
-| Schedule, Agent | Yes | Side effects (scheduled jobs, spawned subprocesses) |
-| WebSearch | Yes | Make external requests (global default) |
-| WebFetch | No | Explicitly exempt - override with `tools.web_fetch.require_approval` |
-| A2A_SubmitTask | Yes | Dispatches work to another agent |
-| Bash | Optional | Governed by the per-mode bash allow-list |
-| Wait | No | Passive utility - blocks until condition met, no side effects |
-| Read, Grep, Tree | No | Read-only operations |
-| Memory, TodoWrite | No | Local agent state (explicitly exempt) |
-| Image tools | No | Output confined to `~/.infer/projects/<project-slug>/artifacts/` - override with `tools.<name>.require_approval` |
-| TextToSpeech | No | Output confined to `text_to_speech.output_dir` - override with `text_to_speech.require_approval` |
-| Computer-use tools | No | Run silently in the background |
-| A2A_QueryAgent, A2A_QueryTask | No | Read-only A2A queries |
-
-### Approval Configuration
-
-Configure approval requirements per tool:
-
-```bash
-# Enable/disable approval for specific tools
-infer config set tools.safety.require_approval true   # Global approval
-infer config set tools.bash.enabled true              # Enable bash tool
-```
-
-Or via configuration file:
-
-```yaml
-tools:
-  safety:
-    require_approval: true  # Global default
-  write:
-    require_approval: true
-  bash:
-    require_approval: false  # Override for bash
-```
-
-### Approval UI Controls
-
-The approval box is an inline select: **left / right** moves between
-**Approve**, **Reject** and **Auto-Approve**, **enter** confirms.
-
-- **Left / Right** - Choose an option
-- **Enter** - Confirm the highlighted choice
-- **Esc** - Reject execution
-
-## Shortcuts
-
-The CLI provides an extensible shortcuts system for quickly executing common commands with `/shortcut-name` syntax.
-
-**Subcommands:** Shortcuts can have subcommands for organized command groups (e.g., `/git status`,
-`/scm issues`). This allows related operations to be grouped under a single shortcut name with multiple
-actions.
-
-### Built-in Shortcuts
-
-**Conversation & session:**
-
-- `/new [title]` - Start a new conversation (optionally titled)
-- `/clear` - Save the current conversation and start a new one
-- `/insights [24h|7d|30d]` - Analyze past sessions for repeatable workflows worth a skill and recurring tool failures; saves a report to `~/.infer/insights/`.
-  Vendored as `~/.infer/shortcuts/insights.yaml`, wrapping `infer insights` - edit it to pin a model or change the windows.
-- `/reset [insights|confirm]` - Wipe the local runtime state (conversations, plans, scratch, artifacts, history, backups, exports, logs) of
-  **every project on this machine**.
-  `/reset` previews and deletes nothing, `/reset insights` analyzes the sessions first, `/reset confirm` performs the wipe.
-  Config and saved insights are preserved, remote stores are skipped.
-  Vendored as `~/.infer/shortcuts/reset.yaml`, wrapping `infer reset` - edit or delete it like any other shortcut.
-  A chat session running during the wipe keeps the conversation it already has in memory; run `/new` or restart to be fully fresh.
-- `/compact` - Save the conversation and start a new session seeded with a summary
-- `/conversations` - Open the conversation selection dropdown
-- `/context` - Show context-window usage
-- `/cost` - Show session cost breakdown with per-model details
-- `/copy [text|markdown|json]` - Copy the conversation to the clipboard (aliases: `txt`, `md`)
-- `/model [model-name] [prompt]` - Switch model, or run a single prompt against a specific model then restore
-- `/theme` - Switch chat theme
-- `/voice [seconds]` - Record from the microphone and transcribe to the input with Whisper (requires `speech_to_text.enabled`)
-- `/help [shortcut]` - Show available shortcuts
-- `/exit` - Exit the chat session
-
-**Panels & views:**
-
-- `/diff` - Open the changes panel (interactive diff viewer)
-- `/explorer` - Open the file explorer (tree + fuzzy finder) - [Learn more →](docs/explorer.md)
-- `/tools` - Show the tools available to the agent (read-only, filterable list)
-- `/a2a` - Show registered A2A agents and their status (requires A2A)
-- `/tasks` - Show the A2A task-management interface (requires A2A) - [Learn more →](docs/tasks-management.md)
-- `/release-notes [version]` - Show release notes from GitHub Releases (latest, or a specific version)
-
-**Project setup:**
-
-- `/init` - Generate an `AGENTS.md` by analyzing the project
-- `/install-opentask [owner/repo] [extra context...]` - Install the OpenTask GitHub workflow via the chat agent:
-  creates or updates `.github/workflows/tasks.yml` for `infer-action` on an install branch, then opens a pull
-  request (pass `[owner/repo]` to target a repo other than the current checkout)
-
-**Git Shortcuts** (created by `infer init`):
-
-- `/git status` - Show working tree status
-- `/git commit` - Generate AI commit message from staged changes
-- `/git push` - Push commits to remote
-- `/git log` - Show commit logs
-
-**SCM Shortcuts** (GitHub integration):
-
-- `/scm issues` - List GitHub issues
-- `/scm issue <number>` - Show issue details
-
-**Other Shortcuts** (created by `infer init`):
-
-- `/mcp [list|add|remove|enable|disable]` - Manage MCP servers
-- `/shells` - List running and recent background shell processes
-- `/export` - Export the current conversation to markdown
-- `/env` - Generate a `.env.example` with all provider API keys
-- `/agents [list|add|remove]` - Manage A2A agents
-- `/skills [list|install|uninstall]` - Manage Agent Skills
-
-### AI-Powered Snippets
-
-Create shortcuts that use LLMs to transform data:
-
-```yaml
-# ~/.infer/shortcuts/custom-example.yaml
-shortcuts:
-  - name: analyze-diff
-    description: "Analyze git diff with AI"
-    command: bash
-    args:
-      - -c
-      - |
-        diff=$(git diff)
-        jq -n --arg diff "$diff" '{diff: $diff}'
-    snippet:
-      prompt: |
-        Analyze this diff and suggest improvements:
-        ```diff
-        {diff}
-        ```
-      template: |
-        ## Analysis
-        {llm}
-```
-
-### Custom Shortcuts
-
-Create custom shortcuts by adding YAML files to `~/.infer/shortcuts/` (a
-project `./.infer/shortcuts/` is overlaid on top by name):
-
-```yaml
-# ~/.infer/shortcuts/custom-dev.yaml
-shortcuts:
-  - name: tests
-    description: "Run all tests"
-    command: go
-    args:
-      - test
-      - ./...
-
-  - name: build
-    description: "Build the project"
-    command: go
-    args:
-      - build
-      - -o
-      - infer
-      - .
-```
-
-**With Subcommands:**
-
-```yaml
-# .infer/shortcuts/custom-docker.yaml
-shortcuts:
-  - name: docker
-    description: "Docker operations"
-    command: docker
-    subcommands:
-      - name: build
-        description: "Build Docker image"
-        args:
-          - -t
-          - myapp
-          - .
-      - name: run
-        description: "Run Docker container"
-        args:
-          - -p
-          - "8080:8080"
-          - myapp
-```
-
-Use as: `/docker build` or `/docker run`
-
-Use with `/tests` or `/build`.
-
-For complete shortcuts documentation, including advanced features and examples, see [Shortcuts Guide](docs/shortcuts-guide.md).
-
-## Channels (Remote Messaging)
-
-Control the agent remotely from messaging platforms like Telegram or
-WhatsApp. Messages sent to a bot are forwarded to the agent, and the
-agent's responses are sent back through the same platform.
-
-### Setup (Telegram)
-
-**1. Create a Telegram bot** by messaging [@BotFather](https://t.me/BotFather) and sending `/newbot`. Copy the bot token.
-
-**2. Get your chat ID** by messaging your bot, then visiting:
-
-```text
-https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
-```
-
-Find `"chat":{"id":123456789}` in the response.
-
-**3. Configure** in `.infer/channels.yaml` (seeded by `infer init`):
-
-```yaml
----
-enabled: true
-
-telegram:
-  enabled: true
-  bot_token: "${INFER_CHANNELS_TELEGRAM_BOT_TOKEN}"
-  allowed_users:
-    - "123456789"
-  poll_timeout: 30
-```
-
-Or via environment variables:
-
-```bash
-export INFER_CHANNELS_ENABLED=true
-export INFER_CHANNELS_TELEGRAM_ENABLED=true
-export INFER_CHANNELS_TELEGRAM_BOT_TOKEN="123456:ABC-DEF..."
-export INFER_CHANNELS_TELEGRAM_ALLOWED_USERS="123456789"
-```
-
-**4. Start the channel listener:**
-
-```bash
-infer daemon
-```
-
-**5. Send a message** to your bot in Telegram - the agent will respond.
-
-Each incoming message triggers `infer headless --session-id <id>` as a
-subprocess with a persistent session per sender.
-
-### Tool Approval
-
-By default, sensitive tools (Write, Edit, Delete, Bash) require user approval
-before executing. The agent sends an approval prompt to the channel and waits
-for the user to reply "yes" or "no". Read-only tools (Read, Grep, Tree) execute
-without approval.
-
-This reuses the existing `tools.*.require_approval` configuration. To disable, set in `.infer/channels.yaml`:
-
-```yaml
-require_approval: false  # default: true
-```
-
-Or: `INFER_CHANNELS_REQUIRE_APPROVAL=false`
-
-Approvals time out after 5 minutes and are automatically rejected.
-
-### Security
-
-- **Allowlist-only access**: Only chat IDs in `allowed_users` can interact with the agent
-- **Empty allowlist = reject all**: If no users are configured, all messages are rejected (secure by default)
-- **Per-channel allowlists**: Each channel (Telegram, WhatsApp) has its own independent allowlist
-- **Tool approval by default**: Sensitive tools require explicit user approval before executing
-- **Use environment variables** for tokens - never commit secrets to config files
-
-### Supported Channels
-
-| Channel  | Status    | Transport                   |
-| -------- | --------- | --------------------------- |
-| Telegram | Available | Long-polling (Bot API)      |
-| WhatsApp | Planned   | Webhook (Meta Business API) |
-
-For a complete working example with Docker Compose, see [examples/telegram-channel](examples/telegram-channel/).
-
-For detailed documentation including custom channel development, see [Channels Documentation](docs/channels.md).
-
-### Scheduled Tasks
-
-When the daemon is running, the agent can schedule prompts on a cron
-schedule. Every fire runs an agent and records the run to storage; jobs
-created from a channel chat (e.g. Telegram) additionally deliver the
-response back through that channel.
-
-> *"Send me an inspiring quote every day at 8 AM"* - recurring
-> *"Remind me at 6pm today to call mum"* - one-off (deletes itself after firing)
-
-Enable in `.infer/config.yaml`:
-
-```yaml
-tools:
-  schedule:
-    enabled: true               # disabled by default
-    require_approval: true      # default; recommended
-```
-
-Or via env var: `INFER_TOOLS_SCHEDULE_ENABLED=true`.
-
-Jobs are persisted as YAML in `~/.infer/schedules/<id>.yaml` and hot-reloaded
-by the daemon (no restart needed). Channel + recipient are derived
-automatically from the session - the LLM never has to guess them.
-
-Container deployments must set `TZ=Europe/Berlin` (or your zone) so cron
-expressions are interpreted in local time. The binary embeds the IANA zone
-database so this works on any base image.
-
-For the full guide, including the cron syntax primer and end-to-end Telegram
-walkthroughs, see [Scheduling Documentation](docs/scheduling.md).
-
-## Heartbeat (Periodic Wake-Up)
-
-Heartbeat wakes the agent on a fixed interval - without any user input -
-so it can check for pending todos, background tasks, or anything else
-your system prompt tells it to monitor. It runs alongside the scheduler
-inside the `infer daemon` process and is **disabled by default**.
-
-Unlike the [Schedule](docs/scheduling.md) tool (which the LLM uses to
-create user-driven cron jobs that deliver to a channel), heartbeat is a
-single global tick the operator configures once. Output goes to logs;
-the agent itself decides whether to send a Telegram message, open a PR,
-or just no-op.
-
-Enable in `.infer/heartbeat.yaml` (seeded by `infer init`):
-
-```yaml
----
-enabled: true
-interval: 1h            # Go duration: 30s, 5m, 1h, 24h
-initial_delay: 1m       # delay before first tick
-model: ""               # optional override; empty = agent.model
-prompt: "Heartbeat tick - check for any pending tasks, todos, or background work and act on them."
-```
-
-The **system prompt** for heartbeat runs lives in `.infer/prompts.yaml`
-under `agent.system_prompt_heartbeat` so you can tune the agent's
-wake-up behaviour separately from chat-mode behaviour.
-
-Then start the daemon:
-
-```bash
-infer daemon
-```
-
-Heartbeat alone is a valid run mode - you don't need any channel
-enabled to use it. The daemon hosts whichever of channels / scheduler /
-heartbeat are turned on.
-
-Or via env vars:
-
-```bash
-export INFER_HEARTBEAT_ENABLED=true
-export INFER_HEARTBEAT_INTERVAL=30m
-```
-
-For the full guide, including configuration reference and common
-patterns (TODO sweeps, CI watchdogs), see [Heartbeat Documentation](docs/heartbeat.md).
-
-## Agent Skills
-
-Agent Skills are reusable, model-readable instruction folders. Each skill is a folder containing a
-`SKILL.md` file with YAML frontmatter (`name`, `description`) - the same contract used by the open
-`.agents/skills/` standard, so existing skill folders drop in unchanged. The agent discovers skills at
-startup and loads a skill's full instructions on demand when they are relevant.
-
-Skills are scanned from three locations (highest precedence first; first match wins on a name collision):
-
-- `.infer/skills/<name>/SKILL.md` - project
-- `.agents/skills/<name>/SKILL.md` - open standard
-- `~/.infer/skills/<name>/SKILL.md` - user-global
-
-Skills are **enabled by default**; disable with `agent.skills.enabled=false` (or `INFER_AGENT_SKILLS_ENABLED=false`).
-
-```bash
-infer skills list                          # Discover skills (works even when disabled)
-infer skills install skill-creator         # Install from github.com/inference-gateway/skills
-infer skills install acme/internal-comms   # Install from github.com/acme/skills
-infer skills uninstall pdf                 # Remove a skill folder by name
-```
-
-`install` accepts a skill name, an `org/skill` pair, or a full GitHub tree URL; set `GITHUB_TOKEN`
-(or `GH_TOKEN`) to raise the rate limit and reach private repositories. See
-[docs/skills.md](docs/skills.md) for the authoring format.
-
-## Computer Use
-
-When enabled, the agent can inspect and control the desktop - read accessible controls, press them by
-label, capture screenshots, move and click the mouse, scroll, and type text or key combinations. The
-display backend is detected automatically across **macOS**, **Linux**, and **Windows**.
-
-Computer Use is **off by default**. Turn it on in `computer_use.yaml` (or with `INFER_COMPUTER_USE_ENABLED=true`):
-
-```yaml
-# .infer/computer_use.yaml
-enabled: true
-rate_limit:
-  enabled: true
-screenshot:
-  streaming_enabled: true   # also registers the GetLatestFrame tool
-```
-
-Tools: `Computer` and `GetLatestFrame`. `Computer` is action-based. Its `accessibility` action is the
-preferred first observation on macOS: it returns compact `{role,label,state,bbox}` text in the same
-coordinate space as screenshots, without a screenshot or vision-model call. Its `press` action invokes
-an element's accessibility action by exact label without moving the cursor. Use `screenshot` only when
-the accessibility tree is unavailable, empty, or insufficient; the remaining actions control the
-pointer and keyboard.
-
-The macOS AX bridge is implemented in Go with PureGo and runs in a short-lived helper process, so a
-native accessibility failure degrades to screenshot guidance without taking down the CLI. Linux AT-SPI
-and Windows UIA providers are not implemented yet and report that fallback explicitly. Computer-use
-actions are governed by `computer_use.enabled`, rate limits, and `computer_use.approval`. The
-[desktop app](https://github.com/inference-gateway/desktop) visualizes what the agent is doing
-(monitor, screen overlay, approvals). For a sandboxed desktop to drive, see
-[examples/computer-use](examples/computer-use/).
-
-## Frame Sources & Vision Annotation
-
-Cheap or text-only models (DeepSeek, small local models) can still "see". Named **frame sources**
-feed images to the agent - the built-in `screen` source (computer-use screenshot streaming) plus any
-number of **directory sources** watching a folder for camera frames - and a pluggable **image
-annotator** turns each frame into text: a scene summary and a numbered element list with bounding
-boxes.
-
-```yaml
-# .infer/config.yaml
-vision:
-  annotator:
-    enabled: true
-    model: anthropic/claude-haiku-4-5-20251001 # any vision model served by your gateway
-  sources:
-    camera-front:
-      type: directory
-      path: .infer/frames/front # wherever your camera process writes frames
-      retention: { max_files: 100, max_age: 24h }
-```
-
-The agent reads frames via `GetLatestFrame(source, format)` and arbitrary image files via
-`ImageDecode(image, prompt)`. Any orchestrator or model that speaks chat completions can use these
-tools - a vision model gets the image itself and a text-only model gets the annotation text: with an
-annotator configured, `GetLatestFrame` defaults to `format: annotated` (text replaces the frame) and
-`format: regular` returns the raw image; `ImageDecode` always attaches the image and adds the
-annotation when an annotator is configured. Annotation is a side-call through the
-gateway, so any vision model it serves works - including fully local ones via Ollama. See the
-[configuration reference](docs/configuration-reference.md#vision-settings) for all options.
-
-## Persistent Memory
-
-The agent keeps a durable, cross-session memory: individual Markdown **fact-files** under a global
-directory (`~/.infer/memory` by default), catalogued by a `MEMORY.md` index. The index is injected
-into context at session start, and the agent reads or writes individual facts on demand through the
-`Memory` tool. A session reminder nudges it to consult and keep memory up to date.
-
-Memory is **enabled by default**. Configure it in `memory.yaml`:
-
-```yaml
-# .infer/memory.yaml
-enabled: true
-dir: ""           # "" => ~/.infer/memory
-max_chars: 4000   # cap on the injected MEMORY.md index
-```
-
-Turn it off with `memory.enabled=false` (or `INFER_MEMORY_ENABLED=false`); the memory-consult
-reminder below is pruned automatically when memory is disabled.
-
-## Reminders & Command Hooks
-
-Two lightweight extension points fire at fixed **agent-loop hook points** - `pre_session`,
-`pre_stream`, `post_stream`, `pre_tool`, `post_tool`, `pre_queue_drain`, `post_queue_drain`, and
-`post_session`:
-
-- **Reminders** (`reminders.yaml`) inject a `<system-reminder>` text block at a hook point, gated by a
-  trigger (`always`, `interval`, `once_after`, `turns_before_max`, `once`, `on_failure`,
-  `on_mode_change`, `on_repeated_failure`, `on_truncation`, `on_stalled_todos`, or
-  `on_empty_response`; see the [configuration reference](docs/configuration-reference.md) for the
-  full table). Reminders ship **enabled** with nine defaults: `todo-hygiene` (nudges the agent to
-  keep a todo list), `mode-change-reminder`, `user-intent-focus`, `repeated-failure`,
-  `todo-continuation`, `truncation-continuation`, `empty-response-continuation`, and the memory
-  reminders `memory-consult` (points it at the memory index) and `memory-hygiene` (one nudge after
-  25 turns to save what a future session would otherwise miss); the memory ones are auto-pruned
-  when memory is off.
-- **Command Hooks** (`hooks.yaml`) run a shell command at a hook point - the executable sibling of
-  reminders. They are **off by default**; each command still faces the per-mode bash allow-list when
-  the agent runs it, so allow-list the command and set `enabled: true` to turn hooks on.
-
-```yaml
-# .infer/hooks.yaml
-enabled: true
-hooks:
-  - name: gofmt
-    hook: post_session
-    command: "gofmt -w ."
-    timeout: 30   # seconds; 0 -> default 30
-```
-
-## Global Flags
+## Features
 
-- `-v, --verbose`: Enable verbose output
-- `--no-colors`: Disable ANSI colors in command output (colors are also auto-disabled when stdout is not a terminal or `NO_COLOR` is set)
-- `--tools-bash-allow-append <cmds>`: Comma/newline-separated commands added to the bash allow-list in every mode
-  (`standard`, `plan`, `auto`); `INFER_TOOLS_BASH_ALLOW_APPEND` takes precedence
-- `--reminders-file <path>`: Path to a reminders YAML file, overriding project `.infer/` and `~/.infer/` reminders
+One line per feature, each linking to its full guide:
+
+### Core
+
+- **Automatic gateway management** - downloads and runs the gateway binary, no Docker required - [Installation](docs/installation.md)
+- **Interactive chat and headless agent** - model selection, streaming, session resumption, inline history auto-completion - [Commands Reference](docs/commands-reference.md)
+- **Agent modes** - Standard, Plan, Auto-Accept and Auto+Judge, toggled with Shift+Tab - [Plan Mode](docs/plan-mode.md) · [Judge Mode](docs/judge-mode.md)
+- **Tool execution** - every built-in tool the LLM can call, with parameters and approval defaults - [Tools Reference](docs/tools-reference.md)
+- **Tool approval** - the gate in front of sensitive tools - [Tool Approval](docs/tool-approval.md)
+- **Custom tools** - add tools in any language with one YAML manifest - [Custom Tools](docs/custom-tools.md)
+- **MCP servers** - Model Context Protocol integration - [MCP Integration](docs/mcp-integration.md)
+- **Subagents** - fan out parallel `infer headless` runs - [Subagents](docs/subagents.md)
+- **GitHub issue references** - type `#` in chat to expand an issue inline (needs `gh` and a GitHub remote) - [Shortcuts Guide](docs/shortcuts-guide.md)
+- **Cost tracking** - real-time per-model cost breakdown - [Cost Tracking](docs/cost-tracking.md)
+- **Conversation history** - multiple storage backends - [Conversation Storage](docs/conversation-storage.md)
+- **Conversation versioning** - navigate back in time to a previous point - [Conversation Versioning](docs/conversation-versioning.md)
+- **Conversation titles** - AI-generated session titles - [Conversation Title Generation](docs/conversation-title-generation.md)
+- **Configuration** - two-layer YAML plus `INFER_*` environment overrides - [Configuration Reference](docs/configuration-reference.md)
+- **Configurable keybindings and themes** - [Configuration Reference](docs/configuration-reference.md#keybinding-configuration)
+- **Persistent memory** - cross-session Markdown facts with an injected index - [Persistent Memory](docs/memory.md)
+- **Reminders and command hooks** - extension points at agent-loop hook points - [Reminders & Command Hooks](docs/hooks.md)
+- **Telemetry** - OpenTelemetry traces and metrics - [Telemetry](docs/telemetry.md)
+- **AG-UI output** - protocol event stream for the headless agent - [AG-UI Output](docs/ag-ui-output.md)
+
+### Remote and automation
+
+- **Web terminal** - browser-based, tabbed sessions - [Web Terminal](docs/web-terminal.md)
+- **Remote messaging channels** - drive the agent from Telegram - [Channels](docs/channels.md)
+- **Scheduled tasks** - cron prompts that deliver back through the channel - [Scheduling](docs/scheduling.md)
+- **Heartbeat** - periodic wake-up to check pending work - [Heartbeat](docs/heartbeat.md)
+- **A2A agents** - delegate to Agent-to-Agent servers - [A2A Agents Configuration](docs/agents-configuration.md) · [A2A Connections](docs/a2a-connections.md)
+- **Task management** - the A2A task interface - [Tasks Management](docs/tasks-management.md)
+- **Browser tools** - drive a browser through an extension bridge - [Browser Extension Protocol](docs/browser-extension-protocol.md)
+- **Explorer and diffs** - in-terminal file tree, fuzzy finder and diff viewer - [Explorer](docs/explorer.md)
+
+### Skills and plugins
+
+- **Agent Skills** - drop-in `SKILL.md` instruction folders - [Agent Skills](docs/skills.md)
+- **Plugins** - Claude Code-format skills plus an always-on ruleset - [Plugins](docs/plugins.md)
+- **Extensible shortcuts** - custom `/`-commands with AI-powered snippets - [Shortcuts Guide](docs/shortcuts-guide.md)
+
+### Media and computer use
+
+- **Computer Use** - drive the desktop: mouse, keyboard, screenshots - [Computer Use](docs/computer-use.md)
+- **Frame sources and vision annotation** - let text-only models "see" - [Vision](docs/vision.md)
+- **Image generation, edit and variation** - written to the session artifacts dir - [Tools Reference](docs/tools-reference.md#media-tools)
+- **Speech-to-text** - dictate with Whisper, locally and offline - [Speech-to-Text](docs/speech-to-text.md)
+- **Text-to-speech** - local WAV synthesis with zero-shot voice cloning - [Text-to-Speech](docs/text-to-speech.md)
+- **Text-to-music and text-to-video** - generate audio and video through the gateway - [Text-to-Music](docs/text-to-music.md) · [Text-to-Video](docs/text-to-video.md)
 
 ## Examples
 
-### Docker Compose Examples
-
-Each directory under [`examples/`](examples/) is a self-contained, runnable setup with its own README,
-most with a Docker Compose file:
-
-| Example | Demonstrates |
-| --------- | -------------- |
-| [basic](examples/basic/) | Minimal gateway + CLI setup to get started |
-| [a2a](examples/a2a/) | Agent-to-Agent: multiple agents, a demo site, and a VNC container |
-| [mcp](examples/mcp/) | MCP server integration with a sample server and config |
-| [tools](examples/tools/) | Custom tools in Python and shell, run offline against a scripted mock model |
-| [computer-use](examples/computer-use/) | Computer Use driving a sandboxed Ubuntu GUI container |
-| [model-switching](examples/model-switching/) | Switching models mid-session, with a small frontend |
-| [shortcuts](examples/shortcuts/) | Custom `/`-shortcuts wired through config |
-| [web-terminal](examples/web-terminal/) | Browser-based, multi-tab web terminal |
-| [telegram-channel](examples/telegram-channel/) | Driving the agent from a Telegram channel |
-| [working-offline](examples/working-offline/) | Fully offline usage with local models via Ollama or llama.cpp |
-| [gpu-provisioning](examples/gpu-provisioning/) | Renting an on-demand cloud GPU running llama.cpp via `infer gpu` (RunPod) |
-| [postgres-storage](examples/postgres-storage/) | Persisting conversations to PostgreSQL |
-| [a2a-traces](examples/a2a-traces/) | End-to-end OpenTelemetry traces between the CLI and an A2A agent |
-
-### Basic Workflow
-
-```bash
-# Initialize project
-infer init
-
-# Start interactive chat
-infer chat
-
-# Execute autonomous task
-infer headless "Fix the bug in issue #42"
-
-# Check gateway status
-infer status
-```
-
-### Working on a GitHub Issue
+Each directory under [`examples/`](examples/) is a self-contained, runnable setup. See
+**[Examples](docs/examples.md)** for the full index and common workflows, or jump straight to
+[basic](examples/basic/) for a minimal gateway plus CLI.
 
-```bash
-# Start chat
-infer chat
-
-# In chat, use shortcuts to get context
-/scm issue 123
-
-# Discuss with AI, let it use tools to:
-# - Read files
-# - Search codebase
-# - Make changes
-# - Run tests
-
-# Ask the agent to open the PR when ready
-> Create a pull request for these changes - it fixes the authentication timeout issue
-```
-
-### Configuration Example
-
-```bash
-# Set default model
-infer config set agent.model "deepseek/deepseek-v4-pro"
-
-# Enable bash tool
-infer config set tools.bash.enabled true
-
-# Configure web search
-infer config set tools.web_search.enabled true
-
-# Check current configuration
-infer config get
-```
-
-### Web Terminal Example
-
-```bash
-# Start web terminal server
-infer chat --web
-
-# Open browser to http://localhost:3000
-# Click "+" to create new terminal tabs
-# Each tab is an independent chat session
-
-# Custom port for remote access
-infer chat --web --port 8080 --host 0.0.0.0
-
-# Configure via config file
-cat > .infer/config.yaml <<EOF
-web:
-  enabled: true
-  port: 3000
-  host: "localhost"
-  session_inactivity_mins: 10  # Reap sessions with no activity for 10 minutes
-EOF
-
-infer chat --web  # Uses config file settings
-```
-
-**Use Cases:**
-
-- Remote access to CLI from any device
-- Multiple parallel chat sessions in browser tabs
-- Team collaboration with shared terminal access
-- Persistent sessions with automatic cleanup
-
-## Development
-
-For development, use [Task](https://taskfile.dev) for build automation:
-
-```bash
-task build # Build binary
-task test  # Run tests
-task fmt   # Format code
-task lint  # Run linter
-```
+## Contributing
 
-See [AGENTS.md](AGENTS.md) for detailed development documentation.
+Development is documented in **[CONTRIBUTING.md](CONTRIBUTING.md)**. Coding agents working in this repository
+should read **[AGENTS.md](AGENTS.md)** first; packages with their own agent-specific rules ship an `AGENTS.md`
+next to the code.
 
 ## License
 
-Apache 2.0 License - see [LICENSE](LICENSE) file for details.
+Apache 2.0 License - see the [LICENSE](LICENSE) file for details.