ValueCell-ai · hazeone · Nov 20, 2025 · Nov 20, 2025 · Nov 20, 2025 · Nov 20, 2025
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -43,7 +43,7 @@ We welcome code contributions! See the [Development Setup](#development-setup) s
 
 > Multi-agent system architecture: [CORE_ARCHITECTURE](../docs/CORE_ARCHITECTURE.md)  
 > Configuration documentation: [CONFIGURATION_GUIDE](../docs/CONFIGURATION_GUIDE.md)  
-> Agent development guide: [CONTRIBUTING_AN_AGENT](../docs/CONTRIBUTING_AN_AGENT.md)
+> Agent development guide: [CONTRIBUTING_AN_AGENT](../docs/CONTRIBUTE_AN_AGENT.md)
 
 
 ## Development Setup
@@ -63,15 +63,18 @@ We welcome code contributions! See the [Development Setup](#development-setup) s
    cd valuecell
    ```
 
-2. **Configure environment variables**
+2. **First run**
 
    ```bash
-   cp .env.example .env
-   # Edit .env with your API keys
+   sh start.sh # MacOS, Linux
+   .\start.ps1 # Windows
    ```
+3. **Configuration**
+   The project will automatically create a config file (.env) in your system ValueCell directory.
+   You can configure your API key via the GUI settings tab.
+   Refer to [Configuration Guide](../docs/CONFIGURATION_GUIDE.md) for details.
 
-Refer to [Configuration Guide](../docs/CONFIGURATION_GUIDE.md) for details.
-
+### Development Run
 **Install backend dependencies:**
 
 ```bash
@@ -92,7 +95,7 @@ cd frontend
 bun install
 ```
 
-### Backend and Agents
+### Backend
 
 For detailed information on building and contributing agents, see the [Agent Development Guide](../docs/CONTRIBUTING_AN_AGENT.md).
 
@@ -105,15 +108,6 @@ cd python
 python -m valuecell.server.main
 ```
 
-**Run the Research Agent:**
-
-```bash
-cd python
-python -m valuecell.agents.research_agent
-```
-
-> [!TIP]
-> Set your environment first. At minimum, configure `OPENROUTER_API_KEY` (or `GOOGLE_API_KEY`) and `SEC_EMAIL`. See [Configuration Guide](../docs/CONFIGURATION_GUIDE.md).
 
 ### Code Style
 
@@ -128,26 +122,6 @@ This section shows how to run the backend locally and build new agents.
 - Core contracts: `valuecell.core.types` define response events and data shapes.
 - Streaming helpers: `valuecell.core.agent.responses.streaming` for emitting events.
 
-#### Launch backend
-
-Run the API server (from the `python/` folder):
-
-```bash
-cd python
-python -m valuecell.server.main
-```
-
-Run the built‑in Research Agent as a standalone service:
-
-```bash
-cd python
-python -m valuecell.agents.research_agent
-```
-
-> [!TIP]
-> Set your environment first. At minimum, configure `OPENROUTER_API_KEY` (or `GOOGLE_API_KEY`) and `SEC_EMAIL`. See `docs/CONFIGURATION_GUIDE.md`.
-> Optional: set `AGENT_DEBUG_MODE=true` to trace model behavior locally.
-
 #### Create a new Agent
 
 1. Subclass `BaseAgent` and implement `stream()`
@@ -326,6 +300,7 @@ We use **Biome** for linting and formatting.
 ```bash
 cd frontend
 bun run check:fix  # Auto-fix all issues
+bun run format:fix # Auto lint code
 ```
 
 **Key style rules:**

diff --git a/docs/CONTRIBUTE_AN_AGENT.md b/docs/CONTRIBUTE_AN_AGENT.md
@@ -14,7 +14,7 @@ The AI will read through this documentation and generate all necessary files:
 
 - Agent module (`core.py`, `__main__.py`, `__init__.py`)
 - Configuration files (YAML and JSON)
-- Launch script registration
+- Agent card registration (JSON)
 
 This is the fastest way to get started and learn the agent structure hands-on!
 
@@ -23,7 +23,7 @@ This is the fastest way to get started and learn the agent structure hands-on!
 - [Architecture Overview](#architecture-overview)
 - [Create a New Agent](#create-a-new-agent)
 - [Add an Agent Configuration](#add-an-agent-configuration-required)
-- [Register Agent in Launch Script](#register-agent-in-launch-script)
+- [Run Your Agent](#run-your-agent)
 - [Use Models and Tools](#use-models-and-tools-inside-an-agent)
 - [Event System](#event-system-contracts)
 - [Launch Backend](#launch-backend)
@@ -127,7 +127,7 @@ if __name__ == "__main__":
 > Always place the wrap and serve logic in `__main__.py`. This pattern enables:
 >
 > - Consistent agent launching via `uv run -m valuecell.agents.your_agent`
-> - Integration with the ValueCell launch script
+> - Automatic discovery by the ValueCell backend server
 > - Standardized transport and event emission
 
 Run your agent:
@@ -243,50 +243,46 @@ The `name` must match your agent class name (e.g., `HelloAgent`). The `url` deci
 > - Change the `url` port if it's occupied. The wrapper reads host/port from this URL when serving
 > - If you see "No agent configuration found … in agent cards", check the `name` and the JSON location
 
-## Register Agent in Launch Script
+## Run Your Agent
 
-To enable your agent to be launched via the project's launch script, register it in `python/scripts/launch.py`.
+### Local Development
 
-### Add Agent to Launch Script
+For local web development, simply start the backend server which will automatically load all agents:
 
-Open `python/scripts/launch.py` and add your agent:
+```bash
+# Start the full stack (frontend + backend with all agents)
+bash start.sh
 
-```python
-# Define agent name constant
-HELLO_AGENT_NAME = "HelloAgent"
-
-# Add to AGENTS list
-AGENTS = [
-    RESEARCH_AGENT_NAME,
-    AUTO_TRADING_AGENT_NAME,
-    HELLO_AGENT_NAME,  # Add your agent here
-]
-
-# Add launch command mapping
-MAP_NAME_COMMAND[HELLO_AGENT_NAME] = (
-    f"uv run --env-file {ENV_PATH_STR} -m valuecell.agents.hello_agent"
-)
+# Or start backend only
+bash start.sh --no-frontend
 ```
 
-Now you can launch your agent using the project's start script. The `start.sh` (or `start.ps1` on Windows) script automatically invokes `launch.py`:
+The backend will automatically discover and initialize your agent based on the agent card configuration.
 
-```bash
-# Launch all registered agents including yours
-bash start.sh
+### Direct Agent Execution
+
+You can also run your agent directly using Python module syntax:
 
-# Or manually run the launch script
+```bash
 cd python
-python scripts/launch.py
+uv run python -m valuecell.agents.hello_agent
 ```
 
-The launch script will:
+### Client Application
 
-- Start your agent as a background service
-- Create log files in `logs/{timestamp}/HelloAgent.log`
-- Display the agent's URL for monitoring
+For the packaged client application (Tauri):
+1. The agent will be automatically included in the build
+2. No additional registration is required
+3. Test using workflow builds: `.github/workflows/mac_build.yml`
 
-> [!NOTE]
-> The current launch script implementation will be optimized in future releases with automatic agent discovery and registration. For now, manual registration is required.
+> [!TIP]
+> Environment variables are loaded from system application directory:
+> - **macOS**: `~/Library/Application Support/ValueCell/.env`
+> - **Linux**: `~/.config/valuecell/.env`
+> - **Windows**: `%APPDATA%\ValueCell\.env`
+> 
+> The `.env` file will be auto-created from `.env.example` on first run if it doesn't exist.
+> Both local development and packaged client use the same location.
 
 ## Use Models and Tools Inside an Agent
 

diff --git a/docs/OKX_SETUP.md b/docs/OKX_SETUP.md