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

⚠️ 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)

⚙️ 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.

# 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:

# Mac/Linux (append --confirm-docs-overwrite if permission was granted)
python3 .agents/skills/vnstock-env-setup/scripts/setup_agent_guide.py

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.

Mac/Linux

python3 -m venv ~/.venv

source ~/.venv/bin/activate

pip install -r https://vnstocks.com/files/requirements.txt

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:**

pip install vnstock -U

**If they are a Sponsor User (requires API key):**

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?