---
name: vnstock-env-setup
description: Comprehensive environment diagnostic, setup, and agent guide installation for the Vnstock ecosystem (Free or Sponsored). Validates OS, Python, venv, and performs migrations. Fully English documented.
---

# Vnstock Environment Setup & Diagnostics

> **PURPOSE**: This skill transforms you into the **Vnstock Environment Doctor & Setup Expert**. You are responsible for ensuring users have the perfect local or cloud setup for `vnstock` (Free) or `vnstock_data` (Sponsor). You will run diagnostics, set up python/venv, migrate legacy code, and optionally install the latest Agent Guide. **All actions must be CLI-driven; do not ask users to run UI installers unless explicitly requested.**

## ⚡ TRIGGER DETECTION

**✅ ACTIVATE WHEN:**
1. User reports an installation error ("error installing vnstock", "ModuleNotFoundError: vnstock_data", "pip error").
2. User asks you to initialize or check their environment ("chuẩn bị môi trường", "cài đặt vnstock", "setup project").
3. User asks you to install or update the **Agent Guide** ("cài đặt agent guide", "tải docs mới").

**❌ DO NOT ACTIVATE WHEN:**
1. User is asking a pure finance or data visualization question (Use `vnstock-solution-architect`).
2. User wants to write code logic right away (Unless they explicitly suffer from an import error).

---

## 📊 QUICK REFERENCE: COMMANDS

| Task | Command / Script to Execute |
| :--- | :--- |
| **1. Diagnostics Check** | **Mac/Linux:** `python3 .agents/skills/vnstock-env-setup/scripts/diagnostics.py`<br>**Win:** `py .agents/skills/vnstock-env-setup/scripts/diagnostics.py` (if `py` fails, test `python`) |
| **2. Create Venv (Mac/Linux)** | `python3 -m venv ~/.venv && source ~/.venv/bin/activate` |
| **3. Create Venv (Win)**| `py -m venv $env:USERPROFILE\.venv; & "$env:USERPROFILE\.venv\Scripts\Activate.ps1"` |
| **4. Install Dependencies**| `pip install -r https://vnstocks.com/files/requirements.txt` |
| **5. Free Tier Setup** | `pip install vnstock -U` |
| **6. Sponsor Tier Setup** | **Linux**: `wget -qO- https://vnstocks.com/files/vnstock-cli-installer.run \| bash -s -- --non-interactive --api-key "API_KEY"`<br>**Mac**: `curl -fsSL https://vnstocks.com/files/vnstock-cli-installer.run \| bash -s -- --non-interactive --api-key "API_KEY"`<br>**Win (PowerShell)**: `pip install -r https://vnstocks.com/files/requirements.txt; pip install --extra-index-url https://vnstocks.com/api/simple vnstock_installer; py -m vnstock_installer` |
| **7. Agent Guide Install** | **Mac/Linux:** `python3 .agents/skills/vnstock-env-setup/scripts/setup_agent_guide.py --confirm-docs-overwrite`<br>**Win:** `py .agents/skills/vnstock-env-setup/scripts/setup_agent_guide.py --confirm-docs-overwrite` |

---

## ⚠️ CRITICAL RULES

> [!CRITICAL]
> **1. THE VENV MANDATE**
> If the user is on a Local machine (macOS, Linux, Windows), they **MUST** use a virtual environment (`~/.venv`). NEVER use `--break-system-packages` globally.

> [!CRITICAL]
> **2. THE MIGRATION CHECK MANDATE**
> If you detect the user is on the **Sponsor Tier** (`vnstock_data`), you **MUST** search the workspace for legacy `from vnstock import ...` code. If found, you must immediately reference and invoke `vnstock-migration-expert` to migrate their script to `vnstock_data` and Unified UI.

> [!IMPORTANT]
> **3. AGENT GUIDE SAFE OVERWRITE**
> When asked to install the Agent Guide, if the `docs/` directory already exists in their workspace, you MUST ask the user via `notify_user` for explicit permission to overwrite it.

---

## ⛔ ANTI-PATTERNS (COMMON TRAPS)

| ❌ AVOID | ✅ PREFER |
| :--- | :--- |
| Asking the user "Are you in a venv?" | Running `diagnostics.py` to check for `VIRTUAL_ENV` automatically. |
| Overwriting `docs/` blindly during guide setup | Asking: *"Thư mục docs/ đã tồn tại, bạn có muốn ghi đè để cập nhật Agent Guide không?"* |
| Assuming pip installs successfully globally | Always activate Venv explicitly before running `pip`. |
| Ignoring Windows aliases loops | Telling users to turn off "App Execution Aliases" for Python in Windows Settings, or using `py` command instead of `python`. |
| Assuming `~` maps to home dir on Windows natively | Using `$env:USERPROFILE\.venv` instead of `~/.venv` when interacting via PowerShell on Windows. |

---

## ⚙️ THE UNIFIED SETUP WORKFLOW

Follow this exact sequence to ensure a flawless setup for any user.

### Step 1: Run Diagnostics
Run the provided python script to detect OS, Python version, Venv, and installed packages.
```bash
# Mac/Linux
python3 .agents/skills/vnstock-env-setup/scripts/diagnostics.py

# Windows
# Note: Try 'py' first to avoid Windows Store aliases. If it fails, fallback to 'python' or prompt user.
py .agents/skills/vnstock-env-setup/scripts/diagnostics.py
```

### Step 2: Ensure Python & Git exist
*Evaluate output from Step 1:* 
- If Python < 3.10, suggest `brew install python@3.12` (Mac) or `winget install Python.Python.3.12` (Win).
- Ensure `git` is installed (the Agent Guide script in Step 3 will also verify this).

### Step 3: Install/Update Agent Guide
Before proceeding, install the latest Agent Guide to provide the AI with the deepest context ($docs/$ and skills).

1. **Check for existing docs:** `ls -d docs/ 2>/dev/null`
2. **Request Permission:** If `docs/` exists, you MUST pause and ask the user (e.g. using `notify_user`): *"Thư mục `docs/` đã tồn tại. Quá trình cài đặt Agent Guide sẽ ghi đè thư mục này (nhưng tự động sao lưu Git trước). Bạn có đồng ý không?"*
3. **Execute Setup:**
```bash
# Mac/Linux (append --confirm-docs-overwrite if permission was granted)
python3 .agents/skills/vnstock-env-setup/scripts/setup_agent_guide.py

```powershell
# Windows (append --confirm-docs-overwrite if permission was granted)
py .agents/skills/vnstock-env-setup/scripts/setup_agent_guide.py
```
> **AI Instruction**: Once the guide is installed, actively reference the setup instructions in `docs/setup-and-debug` for the remainder of this setup process if needed.

### Step 4: Establish Virtual Environment & Requirements
Create a virtual environment (`~/.venv`) to isolate dependencies. Install the baseline requirements to ensure no package conflicts happen later.

```bash
# Mac/Linux
python3 -m venv ~/.venv
source ~/.venv/bin/activate
pip install -r https://vnstocks.com/files/requirements.txt
```

```powershell
# Windows
py -m venv $env:USERPROFILE\.venv
& "$env:USERPROFILE\.venv\Scripts\Activate.ps1"
pip install -r https://vnstocks.com/files/requirements.txt
```

### Step 5: Install Vnstock Packages
Based on the user's tier discovered in Step 1 (or if they provided an API key):

**If they are a Free User:**
```bash
pip install vnstock -U
```

**If they are a Sponsor User (requires API key):**
```bash
# Linux
wget -qO- https://vnstocks.com/files/vnstock-cli-installer.run | bash -s -- --non-interactive --api-key "USER_API_KEY" --accept

# Mac
curl -fsSL https://vnstocks.com/files/vnstock-cli-installer.run | bash -s -- --non-interactive --api-key "USER_API_KEY" --accept

# Windows (PowerShell)
pip install --extra-index-url https://vnstocks.com/api/simple vnstock_installer
py -m vnstock_installer
# ⚠️ Note on Windows: If the installer runs successfully on the browser but the terminal shows "uv install failed... Access is denied", it is due to a Windows file lock issue. Inform the user that they can safely ignore it if the main packages (vnstock_data) were successfully installed, or suggest they close terminal/VSCode and retry.
```

### Step 6: Verification & Migration Check (⭐ CRITICAL)
Run `diagnostics.py` again. If `vnstock_data` is now installed, BẮT BUỘC search the workspace for legacy imports (`grep -r "from vnstock import" .`). If found, run `vnstock-migration-expert` to migrate the user's code.

---

## ✅ QUALITY CHECKLIST

Before concluding your interaction, verify:
- [ ] Did you properly diagnose using `diagnostics.py` instead of guessing?
- [ ] If setting up Python, did you ensure they are in a `.venv`?
- [ ] If Sponsor tier was detected, did you trigger the `vnstock-migration-expert`?
- [ ] During Agent Guide setup, did you warn the user before overwriting `docs/` and run the backup script?