vnstock-env-setup

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 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" Mac: curl -fsSL https://vnstocks.com/files/vnstock-cli-installer.run | bash -s -- --non-interactive --api-key "API_KEY" 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 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.

# 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

```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.

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