fss-link 1.6.1 → 1.6.12

package/docs/CONFIGURATION.md

@@ -0,0 +1,200 @@
+# Configuration Guide
+
+## Provider Setup
+
+FSS Link supports multiple LLM providers. Configure via CLI flags, environment variables, or the persistent database.
+
+### Priority Order
+
+1. **CLI flags** (`--provider`, `--model`) — highest priority, per-session
+2. **Database config** — persistent, survives restarts
+3. **Environment variables** — traditional fallback
+
+### Ollama
+
+Local models via Ollama. Default port 11434.
+
+```bash
+# CLI
+fss-link --provider ollama --model qwen3:4b
+
+# Or set the context window for large conversations
+fss-link --provider ollama --model qwen3:4b
+# Then use /context 32768 inside the session
+```
+
+**Context window**: Defaults to 32,768 tokens. Use the `/context` command to set a custom value that persists to the database.
+
+### LM Studio
+
+Local models via LM Studio. Default port 1234.
+
+```bash
+fss-link --provider lm-studio --model your-model-name
+```
+
+**Context window**: Auto-detected by querying the LM Studio API. Falls back to 32,768 if unavailable.
+
+### vLLM / OpenAI-Compatible Endpoints
+
+Any server that implements the OpenAI API format (`/v1/chat/completions`, `/v1/models`).
+
+```bash
+export BOB_AI_BASE_URL="http://your-server:8000/v1"
+export BOB_AI_API_KEY="your-key"  # optional, use "none" if not required
+fss-link --provider bob-ai --model your-model-name
+```
+
+**Context window**: Auto-detected by querying `/v1/models` for `max_model_len` (vLLM) or `max_context_length`. Falls back to 131,072 if the endpoint doesn't report it.
+
+### OpenAI API
+
+```bash
+export OPENAI_API_KEY="sk-..."
+fss-link --provider openai-api-key --model gpt-4o
+```
+
+### Gemini API
+
+```bash
+export GEMINI_API_KEY="your-key"
+fss-link --provider gemini-api-key --model gemini-2.0-flash
+```
+
+---
+
+## Database Configuration
+
+FSS Link stores model configuration in a SQLite database at `~/.fss-link/config.db`. This is the persistent source of truth for model settings.
+
+<!-- bobai:image-card width="6" -->
+![Database Persistence System](./assets/batch_0003_database-persistence-system-a.png)
+### Persistent Model Settings
+Your model choice survives restarts. CLI flags override, environment fallback.
+<!-- /bobai:image-card -->
+
+### Switching Models via Database
+
+```bash
+# View current config
+sqlite3 ~/.fss-link/config.db "SELECT auth_type, model_name, endpoint_url, is_active FROM model_configs"
+
+# Switch active model
+sqlite3 ~/.fss-link/config.db "UPDATE model_configs SET is_active = 0"
+sqlite3 ~/.fss-link/config.db "UPDATE model_configs SET is_active = 1 WHERE auth_type = 'ollama' AND model_name = 'qwen3:4b'"
+
+# Change endpoint
+sqlite3 ~/.fss-link/config.db "UPDATE model_configs SET endpoint_url = 'http://your-server:1234/v1' WHERE auth_type = 'lm-studio'"
+```
+
+### Database Location
+
+- Linux/macOS: `~/.fss-link/config.db`
+- Data directory: `~/.fss-link/`
+- Todos: `~/.fss-link/todos/`
+
+---
+
+## Context Window Management
+
+The context window is the maximum number of tokens the model can process in a single conversation. FSS Link manages this automatically.
+
+### How Context is Resolved
+
+1. **Manual override** in `settings.json` (`chatCompression.contextWindow`)
+2. **LM Studio API query** (auto-detected from server)
+3. **Ollama `num_ctx`** from `/context` command or sampling params
+4. **OpenAI-compatible `/models` endpoint** (vLLM `max_model_len`)
+5. **Static lookup** for known models (Gemini variants)
+6. **Provider defaults**: Ollama 32k, LM Studio 32k, OpenAI-compat 128k
+
+### Compression
+
+When a conversation reaches 85% of the context window, FSS Link automatically compresses the older history into a summary. The most recent 30% is preserved in full.
+
+<!-- bobai:callout variant="info" -->
+> **How it works**: Older messages are summarized into condensed notes while recent context stays in full detail. Images are replaced with `[Image: type]` placeholders. Tool outputs over 25k chars get truncated.
+<!-- /bobai:callout -->
+
+<!-- bobai:image-card width="6" -->
+![Context Window Compression](./assets/batch_0004_context-window-compression-a.png)
+### Smart History Management
+Full detail on recent context, compressed summaries for older messages.
+<!-- /bobai:image-card -->
+
+- **Threshold**: 85% (configurable via `chatCompression.contextPercentageThreshold`)
+- **Images**: Stripped before compression (replaced with `[Image: type]` placeholders)
+- **Tool results**: Large results (>25k chars) are truncated before entering history
+
+### The `/context` Command
+
+Set the context window for Ollama models:
+
+```
+/context 32768    # Set to 32k
+/context 98304    # Set to 98k (if model supports it)
+/context 98k      # Shorthand
+```
+
+This persists to the database and affects both the display and compression behaviour.
+
+---
+
+## Settings File
+
+Optional `settings.json` in your project root or `~/.fss-link/settings.json`:
+
+```json
+{
+  "chatCompression": {
+    "contextWindow": 98304,
+    "contextPercentageThreshold": 0.7
+  }
+}
+```
+
+---
+
+## Approval Modes
+
+<!-- bobai:image-card width="6" -->
+![Approval Mode Switches](./assets/batch_0014_approval-mode-switches-a.png)
+### Control the Balance
+Choose how much automation vs oversight you want.
+<!-- /bobai:image-card -->
+
+| Mode | Flag | Behaviour |
+|------|------|-----------|
+| Default | (none) | Prompts for approval on all file edits and shell commands |
+| Auto-edit | `--approval-mode auto_edit` | Auto-approves file operations, prompts for shell commands |
+| YOLO | `--approval-mode yolo` or `-y` | Auto-approves everything |
+
+---
+
+## Folder Trust
+
+FSS Link tracks whether a folder is trusted for file operations. On first use in a new directory, it will ask if you trust the folder.
+
+<!-- bobai:image-card width="6" -->
+![Folder Trust System](./assets/batch_0015_folder-trust-system-a.png)
+### Security by Location
+Each folder gets a trust decision. Non-interactive mode requires trust or YOLO/auto-edit.
+<!-- /bobai:image-card -->
+
+```bash
+# Trust the current folder
+fss-link --trust-folder
+
+# Non-interactive mode requires trusted folder or auto_edit/yolo mode
+fss-link --approval-mode auto_edit -p "your prompt"
+```
+
+---
+
+## Debug Mode
+
+```bash
+fss-link --debug
+```
+
+Enables verbose logging including API calls, token counts, context resolution, and tool execution details. Set `FSS_DEBUG=1` in environment for additional debug output from subsystems.

package/docs/README.md

@@ -0,0 +1,192 @@
+# FSS Link
+
+An AI-powered coding assistant for the terminal. FSS Link connects to local and cloud language models to help you write, edit, debug, and understand code through natural conversation.
+
+<!-- bobai:image-card width="8" -->
+![FSS Link Terminal Interface](./assets/batch_0001_fss-link-terminal-interface.png)
+### Your AI Pair Programmer
+Type what you want in plain language. The agent reads your code, makes edits, runs commands, searches your codebase, and explains what's happening.
+<!-- /bobai:image-card -->
+
+## What It Does
+
+```
+$ fss-link
+> Read the main config file and explain what each section does
+> Fix the bug in the authentication middleware
+> Add unit tests for the user registration endpoint
+> Search the codebase for all API endpoint definitions
+```
+
+## Key Features
+
+<!-- bobai:badges -->
+Ollama, LM Studio, OpenAI, Gemini, vLLM
+<!-- /bobai:badges -->
+
+- **Multi-provider support** — Connect to any LLM (local or cloud)
+- **Local-first** — Works offline, no cloud dependency required
+- **File operations** — Read, write, edit with safety checks
+- **Shell execution** — Run commands with approval modes
+- **Semantic search** — RAG-powered codebase discovery
+- **Vision support** — Analyze images and screenshots
+- **Document parsing** — PDF, Excel, Word, email, CSV/JSON
+- **Web tools** — Fetch, search, scrape
+- **TTS integration** — Hands-free voice output
+- **Context compression** — Automatic history management
+- **Session resume** — Pick up where you left off
+- **MCP support** — Extend with custom tools
+
+<!-- bobai:image-card width="6" -->
+![Multi-Provider Connection Hub](./assets/batch_0002_multiprovider-connection-hub-a.png)
+### Connect Anywhere
+Local models via Ollama. Cloud providers (OpenAI, Gemini). Custom endpoints (vLLM, LM Studio).
+<!-- /bobai:image-card -->
+
+## Installation
+
+### From npm
+
+```bash
+npm install -g fss-link
+```
+
+### From Source
+
+```bash
+git clone https://github.com/FSScoding/fss-link.git
+cd fss-link
+npm install
+npm run bundle
+npm install -g .
+```
+
+**Note:** `npm run bundle` uses esbuild to bundle directly from TypeScript source. Do not run bare `tsc` — the root tsconfig has no `outDir` and will scatter compiled files next to source, causing stale code to be bundled. See issue #64.
+
+## Quick Start
+
+### With Ollama (Local)
+
+```bash
+# Start Ollama with a model
+ollama run qwen3:4b
+
+# Launch FSS Link
+fss-link --provider ollama --model qwen3:4b
+```
+
+### With LM Studio (Local)
+
+```bash
+# Start LM Studio server on port 1234
+fss-link --provider lm-studio --model your-model-name
+```
+
+### With vLLM or OpenAI-Compatible Endpoint
+
+```bash
+export BOB_AI_BASE_URL="http://your-server:8000/v1"
+fss-link --provider bob-ai --model your-model-name
+```
+
+### With OpenAI API
+
+```bash
+export OPENAI_API_KEY="sk-..."
+fss-link --provider openai-api-key --model gpt-4o
+```
+
+## Usage Modes
+
+### Interactive (default)
+
+```bash
+fss-link
+```
+
+Opens an interactive chat session. Type messages, use `@file.txt` to reference files, press Enter to send.
+
+### Non-Interactive
+
+```bash
+fss-link -p "explain what this project does"
+```
+
+Runs a single prompt and exits. Useful for scripts and automation.
+
+### YOLO Mode
+
+```bash
+fss-link --approval-mode yolo
+```
+
+Auto-approves all tool operations. Use with caution — the agent can modify files and run commands without asking.
+
+### Auto-Edit Mode
+
+```bash
+fss-link --approval-mode auto_edit
+```
+
+Auto-approves file edits but still prompts for shell commands.
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| Enter | Send message |
+| Shift+Enter | New line |
+| Up/Down | Navigate history (single-line) or move cursor (multiline) |
+| Ctrl+P / Ctrl+N | Navigate message history |
+| Ctrl+A / Ctrl+E | Home / End of line |
+| Ctrl+C | Clear current input |
+| Ctrl+L | Clear screen |
+| Ctrl+V | Paste clipboard image |
+| Escape (x2) | Clear input |
+| `!` | Toggle shell mode |
+
+## File References
+
+Reference files directly in your message with `@`:
+
+```
+> @src/config.ts explain this configuration
+> @package.json what dependencies do we have?
+> @screenshot.png what's shown in this image?
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `BOB_AI_BASE_URL` | OpenAI-compatible endpoint URL | — |
+| `BOB_AI_API_KEY` | API key for the endpoint | — |
+| `BOB_AI_MODEL` | Default model name | — |
+| `OPENAI_API_KEY` | OpenAI API key | — |
+| `OPENAI_BASE_URL` | OpenAI base URL override | — |
+| `GEMINI_API_KEY` | Google Gemini API key | — |
+| `FSS_TTS_URL` | TTS server endpoint | `http://localhost:11450` |
+| `FSS_RAG_URL` | RAG search server endpoint | `http://localhost:11440` |
+| `FSS_DEBUG` | Enable debug logging | — |
+
+## Testing
+
+**Do not run `npm test` from the project root.** It launches vitest across all workspaces in parallel (256+ test files) and will consume all available system memory. See [VITEST-SAFETY.md](../VITEST-SAFETY.md) for safe testing methods and emergency kill procedures.
+
+```bash
+# Safe: run individual test files
+npx vitest run packages/cli/src/config/database.test.ts
+
+# Safe: run one workspace
+npm run test --workspace=packages/cli
+```
+
+## Documentation
+
+- [Configuration Guide](CONFIGURATION.md) — providers, models, database, context settings
+- [Tools Reference](TOOLS.md) — all available tools and their parameters
+- [Tool Flow Diagrams](../fss-docs/tool-flow-diagrams/) — visual documentation with Mermaid diagrams
+
+## License
+
+Apache-2.0

package/docs/TOOLS.md

@@ -0,0 +1,268 @@
+# Tools Reference
+
+FSS Link provides the agent with a set of tools it can use to interact with your system. Each tool has parameters the agent controls and safety checks that protect your files.
+
+---
+
+## File Operations
+
+<!-- bobai:image-card width="6" -->
+![File Operations with Safety](./assets/batch_0005_file-operations-with-safety.png)
+### Safe by Default
+Diff previews before changes. Workspace boundaries. Confirmation prompts.
+<!-- /bobai:image-card -->
+
+### read_file
+
+Reads a file and returns its contents. Handles text files, images (with vision normalization), PDFs, and binary detection.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `absolute_path` | string | Full path to the file |
+| `offset` | integer | Start reading from this line (optional) |
+| `limit` | integer | Maximum lines to read (optional) |
+
+- Images are automatically resized and converted for the model's vision pipeline
+- Large files can be read in sections using `offset` and `limit`
+- File paths are shown as clickable terminal hyperlinks (OSC 8)
+
+### write_file
+
+Creates a new file or overwrites an existing one. Requires confirmation in default mode.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `file_path` | string | Full path to write |
+| `content` | string | File content |
+
+- Shows a diff preview before writing to existing files
+- Creates parent directories automatically
+- Workspace boundary checks prevent writing outside project
+
+### edit
+
+Makes targeted edits to existing files by replacing specific text. The most commonly used file tool.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `file_path` | string | Full path to the file |
+| `old_string` | string | Exact text to find and replace |
+| `new_string` | string | Replacement text |
+| `expected_replacements` | integer | Expected number of matches (optional, for safety) |
+
+- Shows a diff preview before applying
+- Fails safely if the target string isn't found or matches multiple times unexpectedly
+- Can create new files when `old_string` is empty
+
+---
+
+## Search & Discovery
+
+### glob
+
+Finds files matching a glob pattern. Respects `.gitignore`.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pattern` | string | Glob pattern (e.g., `**/*.ts`, `src/**/*.test.*`) |
+| `path` | string | Directory to search in (optional, defaults to workspace) |
+
+### grep
+
+Searches file contents using regular expressions. Returns matching lines with context.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pattern` | string | Regex pattern to search for |
+| `path` | string | File or directory to search (optional) |
+| `include` | string | File glob filter (e.g., `*.ts`) (optional) |
+
+### ls
+
+Lists directory contents with file metadata (size, type, permissions).
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `path` | string | Directory to list |
+
+### rag_search
+
+Semantic search over indexed codebases using the FSS-RAG system. Finds code by meaning, not just text matching.
+
+<!-- bobai:image-card width="6" -->
+![Semantic Search RAG System](./assets/batch_0006_semantic-search-rag-system.png)
+### Search by Meaning
+Find code by what it does, not just what it says. Requires FSS-RAG server.
+<!-- /bobai:image-card -->
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `query` | string | Natural language search query |
+| `collection` | string | Collection name (auto-detected from project directory) |
+| `topk` | integer | Number of results (default: 5, max: 20). Each result ~400 chars. |
+| `mode` | string | `semantic` (default), `keyword`, or `ast` |
+| `contextSize` | integer | Surrounding chunks per result (0-10). Higher = more context but larger response. |
+| `fileTypes` | array | File extension filters (e.g., `[".ts", ".py"]`) |
+| `pathPattern` | string | Glob pattern to restrict search paths |
+
+Requires the FSS-RAG server running at `FSS_RAG_URL` (default `localhost:11440`).
+
+---
+
+## Shell & System
+
+<!-- bobai:image-card width="6" -->
+![Shell Command Execution](./assets/batch_0011_shell-command-execution-a.png)
+### Controlled Execution
+Run commands with safety checks. Approval required by default.
+<!-- /bobai:image-card -->
+
+### run_shell_command
+
+Executes shell commands. Always requires confirmation unless in YOLO mode.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `command` | string | The shell command to execute |
+| `description` | string | What this command does (shown to user) |
+| `is_background` | boolean | Run in background (optional) |
+
+- Background commands are useful for dev servers, watchers, etc.
+- Output is captured and returned to the agent
+- Long-running commands have configurable timeouts
+
+---
+
+## Web Tools
+
+<!-- bobai:image-card width="6" -->
+![Web Research Tools](./assets/batch_0009_web-research-tools-a.png)
+### Browse and Search
+Fetch pages, search the web, scrape content into your conversation.
+<!-- /bobai:image-card -->
+
+### web_fetch
+
+Fetches a URL and returns its content. Handles HTML (extracted as readable text), JSON, and plain text.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | string | URL to fetch |
+
+### web_search
+
+Searches the web using a search engine API.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `query` | string | Search query |
+| `limit` | integer | Maximum results (optional) |
+
+Requires a search API key (Tavily or similar) configured via `--tavily-api-key` or environment variable.
+
+### fetch_image
+
+Downloads an image from a URL and saves it locally.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | string | Image URL |
+| `save_path` | string | Where to save the file (optional) |
+
+---
+
+## Document Parsing
+
+<!-- bobai:image-card width="6" -->
+![Document Parsing Suite](./assets/batch_0008_document-parsing-suite-a.png)
+### Multi-Format Support
+PDF, Excel, Word, email, CSV, JSON — one tool per format.
+<!-- /bobai:image-card -->
+
+### read_pdf, read_excel, read_word, read_email, read_data
+
+Specialized parsers for structured documents. These extract text, tables, metadata, and structure from common file formats.
+
+| Tool | Formats | What It Extracts |
+|------|---------|-----------------|
+| `read_pdf` | PDF | Text, page structure, metadata |
+| `read_excel` | XLSX, XLS, CSV | Sheets, cells, formulas, structure |
+| `read_word` | DOCX | Text, headings, tables, styles |
+| `read_email` | EML, MSG | Headers, body, attachments metadata |
+| `read_data` | CSV, JSON, YAML, XML, TOML | Parsed data with schema inference |
+
+---
+
+## Agent Utilities
+
+### workplan_update (formerly `todo_write`)
+
+Manages a structured work plan for the current session. Helps the agent track multi-step work.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `todos` | array | Array of `{id, content, status}` objects |
+
+Status values: `pending`, `in_progress`, `completed`.
+
+Usage guidelines:
+- Create the plan once, then proceed with other tools.
+- Update only after real progress (status changes) or when adding/removing tasks.
+- Avoid calling repeatedly without progress.
+
+### memory
+
+Reads and writes to the agent's persistent memory system. Stores user preferences, project context, and learned patterns across sessions.
+
+---
+
+## TTS (Text-to-Speech)
+
+<!-- bobai:image-card width="6" -->
+![Text-to-Speech Voice Output](./assets/batch_0010_texttospeech-voice-output-a.png)
+### Hands-Free Interaction
+Listen to responses with natural voices (Bella, Emma, George, Lewis, and more).
+<!-- /bobai:image-card -->
+
+### tts_speak
+
+Synthesizes speech from text using the FSS-TTS server.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `text` | string | Text to speak |
+| `voice` | string | Voice name (Bella, Emma, George, Lewis, Sarah, Michael, Adam, Isabella, Nicole) |
+
+Requires the FSS-TTS server running at `FSS_TTS_URL` (default `localhost:11450`).
+
+---
+
+## MCP (Model Context Protocol)
+
+<!-- bobai:image-card width="6" -->
+![MCP Extension System](./assets/batch_0012_mcp-extension-system-a.png)
+### Extensible Architecture
+Plug in MCP servers to add custom tools and capabilities.
+<!-- /bobai:image-card -->
+
+FSS Link supports MCP servers for extending its capabilities. Configure MCP servers in your project's settings or via the CLI:
+
+```bash
+fss-link mcp add <server-name> <command>
+fss-link mcp list
+fss-link mcp remove <server-name>
+```
+
+MCP tools appear alongside native tools and are used by the agent automatically when relevant.
+
+---
+
+## Tool Safety
+
+All file-modifying tools (edit, write_file) enforce:
+
+- **Workspace boundary checks** — can't write outside your project directory
+- **Diff previews** — see exactly what will change before approving
+- **Confirmation prompts** — unless in auto_edit or YOLO mode
+- **Tool result size limits** — outputs exceeding 25k characters are truncated to prevent context overflow
+- **Error messages include the failed path** — so the agent knows exactly what went wrong and doesn't retry blindly