docs(agent): add README (hoppscotch#5286)

This adds documentation for the Hoppscotch Agent package covering
 installation, configuration, and usage.

 Closes FE-942
 Closes hoppscotch#5284

 The agent package lacked user-facing documentation beyond the minimal
 Tauri template content. Users needed guidance for installation,
 registration, certificate management, proxy configuration, and
 troubleshooting.

Author: CuriousCorrelation

packages/hoppscotch-agent/README.md

@@ -1,16 +1,281 @@
-# Tauri + Vue + TypeScript
+<div align="center">
+   <img align="center" width="128px" src="public/icon.png" />
+   <h1 align="center"><b>Hoppscotch Agent</b></h1>
+   <h2 align="center">
+      <a href="https://github.com/hoppscotch/agent-releases">Download</a> |
+      <a href="https://docs.hoppscotch.io/documentation/clients/agent">Official Docs</a>
+   </h2>
+</div>
 
-This template should help get you started developing with Vue 3 and TypeScript in Vite. The template uses Vue 3 `<script setup>` SFCs, check out the [script setup docs](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup) to learn more.
+<br/>
 
-## Recommended IDE Setup
+#### Hoppscotch Agent is a cross-platform HTTP request relay for Hoppscotch built with [Tauri V2](https://v2.tauri.app/) that adds capabilities like custom headers, certificates, proxies, and local access typically restricted in browsers.
 
-- [VS Code](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) + [Tauri](https://marketplace.visualstudio.com/items?itemName=tauri-apps.tauri-vscode) + [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer)
+The agent runs as a local system service on port `9119`, acting as an intermediary between the Hoppscotch web application and target APIs. It establishes an encrypted communication channel authenticated via an OTP registration process.
 
-## Type Support For `.vue` Imports in TS
+## Installation
 
-Since TypeScript cannot handle type information for `.vue` imports, they are shimmed to be a generic Vue component type by default. In most cases this is fine if you don't really care about component prop types outside of templates. However, if you wish to get actual prop types in `.vue` imports (for example to get props validation when using manual `h(...)` calls), you can enable Volar's Take Over mode by following these steps:
+### Standard Installation
 
-1. Run `Extensions: Show Built-in Extensions` from VS Code's command palette, look for `TypeScript and JavaScript Language Features`, then right click and select `Disable (Workspace)`. By default, Take Over mode will enable itself if the default TypeScript extension is disabled.
-2. Reload the VS Code window by running `Developer: Reload Window` from the command palette.
+1. Download the latest version of Hoppscotch Agent from [releases](https://github.com/hoppscotch/agent-releases)
+2. Run the installer
+3. Follow the installation wizard to complete setup
+4. The agent automatically starts and appears in your system tray
 
-You can learn more about Take Over mode [here](https://github.com/johnsoncodehk/volar/discussions/471).
+### Portable Version
+
+The portable version runs without installation and does not include automatic updates.
+
+1. Download the portable version for your operating system
+2. Extract the archive to your desired location
+3. Run the executable directly
+4. The agent will start and appear in your system tray
+
+> [!Note]
+> The portable version uses a separate configuration (`tauri.portable.conf.json`) that disables bundling and updater functionality.
+
+## Getting Started
+
+### Registration
+
+1. Open Hoppscotch web app and navigate to **Settings** → **Interceptors**
+2. Select **Agent** from the available interceptors  
+3. Click **Register Agent** button
+4. The agent window displays a 6-digit verification code
+5. Enter the verification code in the OTP input field
+6. Click the confirm button to establish connection
+7. The agent displays a masked auth key hash when successfully registered
+
+### Usage
+
+Once registered, all HTTP requests made through Hoppscotch are processed by the agent. The agent provides:
+
+- CORS bypass by processing requests locally
+- Client certificate authentication for mutual TLS
+- HTTP Digest Authentication using challenge-response mechanisms  
+- Custom headers that browsers typically restrict
+- Proxy routing with authentication support
+- Local network and localhost access
+- SSL/TLS verification controls
+- And much more
+
+## Domain-Specific Configuration
+
+The agent (and `Native`) interceptor supports per-domain configuration overrides with a global default (`*`) domain:
+
+### Domain Management
+- **Global Defaults**: Base settings applied to all domains (domain: `*`)
+- **Domain Overrides**: Specific settings for individual domains (e.g., `api.example.com`)
+- **Domain Addition**: Add new domains through the domain management modal
+- **Domain Removal**: Remove custom domain configurations (global default cannot be removed)
+
+### SSL/TLS Security Settings
+
+For each domain, configure:
+
+- **Verify Host**: Enable/disable hostname verification during SSL handshake
+- **Verify Peer**: Enable/disable peer certificate verification
+- **CA Certificates**: Upload custom Certificate Authority certificates for domain validation
+- **Client Certificates**: Configure client certificates for mutual TLS authentication
+
+## Client Certificates
+
+The agent supports client certificate authentication for APIs requiring mutual TLS:
+
+### Certificate Formats
+- **.pem certificates**: Requires separate certificate (.crt/.cer/.pem) and private key (.key/.pem) files
+- **.pfx/.pkcs12 certificates**: Single file format with optional password protection
+
+### Configuration
+
+1. Access **Settings** → **Interceptors** → **Agent** in Hoppscotch
+2. Select the target domain from the domain selector
+3. Click **Client Certificates** button
+4. Choose certificate format (PEM or PFX tab)
+5. Upload certificate files:
+   - **PEM**: Upload certificate file and private key file separately  
+   - **PFX**: Upload .pfx/.pkcs12 file and enter password if required
+6. Configuration is automatically saved per domain
+
+### CA Certificates
+
+Custom Certificate Authority certificates can be added per domain:
+
+1. Navigate to the CA Certificates section for the target domain
+2. Click **Add Certificate File** 
+3. Upload the CA certificate file
+4. Toggle certificate inclusion on/off as needed
+5. Remove certificates using the trash icon
+
+## Proxy Configuration
+
+The agent supports HTTP/HTTPS proxy routing with authentication (including NTLM):
+
+### Proxy Settings
+- **Proxy URL**: HTTP/HTTPS proxy server address with port
+- **Proxy Authentication**: Username and password for proxy server authentication
+- **Per-Domain**: Each domain can have different proxy configurations
+
+### Configuration
+
+1. Select the target domain
+2. Toggle the **Proxy** switch to enable
+3. Enter the proxy URL (e.g., `http://proxy.example.com:8080`)
+4. Configure proxy authentication if required:
+   - Username field
+   - Password field (with show/hide toggle)
+
+## System Integration
+
+### System Tray
+The agent runs with system tray integration, providing access to:
+- **Show Registrations**: View active connections and registration status
+- **Clear Registrations**: Remove all registered instances  
+- **Maximize Window**: Show the agent interface window
+- **Quit**: Exit the agent application
+
+### Configuration Storage
+The agent stores configuration in platform-specific locations:
+
+- **Windows**: `%APPDATA%\io.hoppscotch.agent\`
+- **macOS**: `~/Library/Application Support/io.hoppscotch.agent/`  
+- **Linux**: `~/.config/io.hoppscotch.agent/`
+
+### Logging
+Logs are stored in platform-specific directories:
+
+- **Windows**: `%LOCALAPPDATA%\io.hoppscotch.agent\logs\`
+- **macOS**: `~/Library/Logs/io.hoppscotch.agent/`
+- **Linux**: `~/.local/share/io.hoppscotch.agent/logs/`
+
+### Auto-Start Configuration
+The standard installation includes auto-start functionality. The portable version does not include auto-start and must be launched manually.
+
+## Building from Source
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/) (v18 or later)
+- [pnpm](https://pnpm.io/) package manager
+- [Rust](https://rustup.rs/) (latest stable)
+- [Tauri CLI](https://tauri.app/v1/guides/getting-started/prerequisites)
+
+### Development
+
+```bash
+# Clone the repository  
+git clone https://github.com/hoppscotch/hoppscotch.git
+cd hoppscotch/packages/hoppscotch-agent
+
+# Install dependencies
+pnpm install
+
+# Start development server
+pnpm tauri dev
+```
+
+### Production Build
+
+```bash
+# Build standard version
+pnpm tauri build
+
+# Build portable version  
+pnpm tauri build --config src-tauri/tauri.portable.conf.json
+```
+
+The built applications will be available in `src-tauri/target/release/bundle/`
+
+### Build Variants
+
+Two build configurations are available:
+
+- **Standard** (`tauri.conf.json`): Includes installer, auto-updater, and auto-start functionality
+- **Portable** (`tauri.portable.conf.json`): Standalone executable without installation requirements
+
+## Network Configuration
+
+### Default Port
+The agent runs on port `9119` by default. Make sure this port is not blocked by firewalls.
+
+### Communication Protocol
+- **Encryption**: AES-256-GCM for all agent-to-web-app communication
+- **Authentication**: X25519 key exchange for secure channel establishment
+- **Registration**: One-time 6-digit OTP verification process
+
+## System Requirements
+
+### Windows
+- **OS Version**: Windows 10 1803+ or Windows 11
+- **Architecture**: x64
+- **Dependencies**: WebView2 Runtime (auto-installed for standard version)
+
+### macOS  
+- **OS Version**: macOS 10.15 (Catalina) or later
+- **Architecture**: Intel x64 or Apple Silicon (ARM64)
+
+### Linux
+- **Architecture**: x64
+- **Dependencies**: WebKit2GTK 2.44.0+ (usually pre-installed)
+- **Minimum**: Systems with GLIBC 2.38+
+
+## Troubleshooting
+
+### Agent Detection Issues
+1. **"Agent not detected" popup**: Verify the agent is running by checking the system tray for the Hoppscotch icon
+2. **Switching interceptors blocked**: If the "Agent not detected" popup prevents switching interceptors, restart your browser and stop the agent before changing interceptor settings
+3. **Port accessibility**: Check that no firewall is blocking port `9119`  
+4. **Browser compatibility**: Safari on macOS may have CORS issues with localhost:9119 due to access control checks, try Chrome/Firefox for agent registration
+
+### Registration Failures  
+1. **"Failed to initiate the registration"**: This error may occur due to browser security policies or extension conflicts
+2. **Missing OTP input field**: Verify the agent window is focused and displaying a 6-digit verification code
+3. **OTP expiration**: Registration codes have limited lifetime, restart the registration process if the code expires
+4. **Network connectivity**: Verify browser can reach localhost:9119/handshake
+5. **Version compatibility**: Some agent versions may be incompatible with specific Hoppscotch web app versions. For self-hosted setups, make sure Agent version in the release matches, see https://github.com/hoppscotch/hoppscotch/issues/4936#issuecomment-2756981053
+
+### Certificate Issues
+1. Verify certificate format is supported (.pem or .pfx/.pkcs12)
+2. Check certificate expiration dates
+3. Confirm private key matches certificate (for .pem files)
+4. Verify domain configuration matches target API hostname
+5. Confirm certificate password is correct (for .pfx/.pkcs12)
+6. Check CA certificate inclusion status (toggle on/off)
+
+### Request Processing Issues
+1. **Custom headers not applied**: Verify the agent is selected as interceptor, browsers may override headers like User-Agent when using default HTTP methods
+2. **CORS errors**: Confirm agent interceptor is active and requests are routing through localhost:9119
+3. **SSL/TLS verification**: Check verify host/peer settings for the target domain
+4. **Proxy routing**: Verify proxy URL format includes protocol (http:// or https://)
+
+### System-Specific Issues
+
+#### Windows
+1. Check WebView2 Runtime is installed (auto-installed with standard version)
+2. Check Windows Defender or antivirus exclusions for the agent executable
+3. Verify agent has network permissions through Windows Firewall
+
+#### macOS  
+1. Safari browser may block agent connections due to CORS policies, try Chrome or Firefox instead
+2. Check macOS Gatekeeper settings if agent fails to start
+3. Verify agent is allowed in System Preferences →  Security & Privacy
+
+#### Linux
+1. Check WebKit2GTK dependencies are installed
+2. Check systemd logs if agent fails to start as service
+3. Verify GLIBC version compatibility (requires 2.38+)
+
+### Portable Version Issues
+1. Manual WebView2 installation - may be required on older versions of Windows
+2. No auto-start capability - must launch manually after system restart  
+3. No automatic updates - download new versions manually
+4. Verify executable permissions on Unix-like systems
+5. Check that portable version is extracted to a writable directory
+
+### Log
+Check agent logs for detailed error information:
+- **Windows**: `%LOCALAPPDATA%\io.hoppscotch.agent\logs\`
+- **macOS**: `~/Library/Logs/io.hoppscotch.agent/`
+- **Linux**: `~/.local/share/io.hoppscotch.agent/logs/`
+
+Look for connection errors, certificate validation failures, or proxy authentication issues in the log files.