QVerisAI
diff --git a/‎agent/GUIDELINES.md‎
Lines changed: 67 additions & 5 deletions b/‎agent/GUIDELINES.md‎
Lines changed: 67 additions & 5 deletions
diff --git a/‎agent/SETUP.md‎
Lines changed: 63 additions & 5 deletions b/‎agent/SETUP.md‎
Lines changed: 63 additions & 5 deletions
@@ -162,6 +162,58 @@ When a tool response exceeds `max_response_size`, the API returns:
 
 ---
 
+## CLI Workflow
+
+When using the QVeris CLI (`@qverisai/cli` v0.4.0) instead of MCP, the same Discover → Inspect → Call pattern applies via shell commands.
+
+### Basic Agent Workflow
+
+```bash
+# Discover tools (free)
+qveris discover "weather forecast API" --json
+
+# Inspect top result by index (free)
+qveris inspect 1 --json
+
+# Call with parameters (1-100 credits)
+qveris call 1 --params '{"city": "London"}' --json
+
+# Validate without consuming credits
+qveris call 1 --params '{"city": "London"}' --dry-run --json
+
+# Generate code snippet after successful call
+qveris call 1 --params '{"city": "London"}' --codegen curl
+```
+
+### Key Flags for Agents
+
+| Flag | Purpose |
+|------|---------|
+| `--json` | Structured JSON output — always use in agent/script contexts |
+| `--dry-run` | Validate parameters without executing (no credits consumed) |
+| `--codegen <curl\|js\|python>` | Generate API call snippets from last successful call |
+| `--params <json\|@file\|->` | Pass parameters as inline JSON, from file (`@params.json`), or stdin (`-`) |
+| `--limit <n>` | Limit discover results (default: 5) |
+| `--max-size <bytes>` | Response size limit; `-1` for unlimited (default: 4KB TTY, 20KB non-TTY). MCP default is 20KB. |
+
+### Session & Index Shortcuts
+
+After `qveris discover`, results are stored in a session file (30-minute TTL). Use numeric indices in subsequent commands:
+
+```bash
+qveris discover "stock price API"    # Returns indexed results: 1, 2, 3...
+qveris inspect 1                     # Inspect first result by index
+qveris call 1 --params '...'         # Call first result by index
+```
+
+The session tracks the discovery ID, so `inspect` and `call` automatically link back to the original discovery for analytics. Use `qveris history` to view current session state.
+
+### Diagnostics
+
+Run `qveris doctor` to check setup: Node.js version, API key validity, region detection, and API connectivity.
+
+---
+
 ## Self-Check (before responding)
 
 - Is my discover query a **tool type description** or a **factual question**? → If it contains specific names, "is X listed?", or "what is Y?" — use web_search.
@@ -185,10 +237,20 @@ Region is auto-detected from the API key prefix. Override with `QVERIS_REGION=cn
 
 **Auth**: `Authorization: Bearer ${QVERIS_API_KEY}`
 
-| Action | Endpoint | Body |
-|--------|----------|------|
-| Discover | `POST /search` | `{"query": "...", "limit": 10}` |
-| Inspect | `POST /tools/by-ids` | `{"tool_ids": ["..."], "search_id": "..."}` |
-| Call | `POST /tools/execute?tool_id=...` | `{"search_id": "...", "parameters": {...}, "max_response_size": 20480}` |
+| Action | REST Endpoint | MCP Tool | CLI Command |
+|--------|--------------|----------|-------------|
+| Discover | `POST /search` | `discover` | `qveris discover <query>` |
+| Inspect | `POST /tools/by-ids` | `inspect` | `qveris inspect <id\|index>` |
+| Call | `POST /tools/execute?tool_id=...` | `call` | `qveris call <id\|index>` |
+
+**REST Body Examples:**
+
+| Action | Body |
+|--------|------|
+| Discover | `{"query": "...", "limit": 10}` |
+| Inspect | `{"tool_ids": ["..."], "search_id": "..."}` |
+| Call | `{"search_id": "...", "parameters": {...}, "max_response_size": 20480}` |
+
+> **MCP backward compatibility:** Old tool names `search_tools`, `get_tools_by_ids`, `execute_tool` are still supported as deprecated aliases in MCP server v0.5.0. Use the new names (`discover`, `inspect`, `call`) going forward.
 
 Full API documentation: https://github.com/QVerisAI/QVerisAI/blob/main/docs/en-US/rest-api.md
@@ -41,12 +41,61 @@ The QVeris MCP server requires Node.js.
    - Attempt to install it using the system's package manager (e.g., `winget install OpenJS.NodeJS` on Windows, `brew install node` on macOS, or `apt install nodejs` on Linux).
    - If you cannot install it automatically, stop and ask the user to install Node.js (LTS version recommended).
 
-## 2. Detect Environment & Configure
+## 2. Choose Integration Method
+
+QVeris supports two integration methods. Choose based on your environment:
+
+| Method | Best For | How It Works |
+|--------|----------|--------------|
+| **CLI** (recommended) | Agents with shell access (Claude Code, OpenClaw, terminals) | Subprocess calls — zero prompt tokens, 10,000+ tools without bloat |
+| **MCP Server** | IDE integrations (Cursor, Claude Desktop, OpenCode) | MCP protocol — tools injected into agent context |
+
+### Option A: CLI Setup (Recommended for shell-capable agents)
+
+Install the CLI globally:
+
+```bash
+# One-liner install
+curl -fsSL https://qveris.ai/cli/install | bash
+
+# Or via npm
+npm install -g @qverisai/cli
+```
+
+Authenticate with interactive region selection:
+
+```bash
+qveris login
+```
+
+The `login` command will:
+1. Prompt for region selection (Global or China) if not pre-configured
+2. Open a browser to retrieve your API key
+3. Accept masked key input and validate it
+4. Save credentials to `~/.config/qveris/config.json`
+
+Alternatively, set the API key directly:
+
+```bash
+qveris config set api_key YOUR_QVERIS_API_KEY
+```
+
+Verify the setup:
+
+```bash
+qveris doctor    # Check Node.js, API key, region, connectivity
+qveris whoami    # Show auth status and region
+qveris credits   # Check credit balance
+```
+
+Skip to **Section 3: Verify Installation** once `qveris doctor` passes all checks.
+
+### Option B: MCP Server Setup
 
 Detect which coding tool or environment you are currently running in (e.g., Claude Code, OpenCode, Cursor, Trae, VS Code).
 
 **Configuration involves two steps for all environments:**
-1. **MCP Server Setup:** Connects the QVeris tool server (`@qverisai/mcp`) to your environment.
+1. **MCP Server Setup:** Connects the QVeris tool server (`@qverisai/mcp` v0.5.0) to your environment.
 2. **Skill Configuration:** Teaches the agent how to use the tools using the MCP/client skill definition file.
    - **Skill URL:** `https://github.com/QVerisAI/QVerisAI/blob/main/skills/qveris/SKILL.md`
 
@@ -215,11 +264,20 @@ More details: https://qveris.ai/docs/openclaw-setup
 
 ## 3. Verify Installation
 
-After configuration, you must verify that the QVeris tools are visible and usable.
+After configuration, verify that QVeris tools are visible and usable.
+
+### CLI Verification
+
+```bash
+qveris doctor                              # Run diagnostics
+qveris discover "weather forecast API"     # Test discovery (free)
+```
+
+### MCP Verification
 
 1. **Restart:** If required by the environment, restart the MCP client or reload the window.
-2. **List Tools:** Run the tool discovery command available to you (e.g., `mcp.list_tools`, `search_tools`, or `/mcp` in chat).
-3. **Check for QVeris:** Look for tools starting with `qveris_` or the `qveris` server in the list.
+2. **List Tools:** Run the tool discovery command available to you (e.g., `mcp.list_tools`, or `/mcp` in chat).
+3. **Check for QVeris:** Look for `discover`, `inspect`, `call` tools (or the `qveris` server) in the list. Legacy tool names `search_tools`, `get_tools_by_ids`, `execute_tool` are still supported as deprecated aliases.
 
 ## 4. Troubleshooting & Fixes