diff --git a/docs/FrontendBuildGuide.md b/docs/FrontendBuildGuide.md
new file mode 100644
index 00000000..4d416899
--- /dev/null
+++ b/docs/FrontendBuildGuide.md
@@ -0,0 +1,254 @@
+# Frontend Build Guide
+
+## Overview
+
+The LightRAG project includes a React-based WebUI frontend. This guide explains how frontend building works in different scenarios.
+
+## Key Principle
+
+- **Git Repository**: Frontend build results are **NOT** included (kept clean)
+- **PyPI Package**: Frontend build results **ARE** included (ready to use)
+- **Build Tool**: Uses **Bun** (not npm/yarn)
+
+## Installation Scenarios
+
+### 1. End Users (From PyPI) ✨
+
+**Command:**
+```bash
+pip install lightrag-hku[api]
+```
+
+**What happens:**
+- Frontend is already built and included in the package
+- No additional steps needed
+- Web interface works immediately
+
+---
+
+### 2. Development Mode (Recommended for Contributors) 🔧
+
+**Command:**
+```bash
+# Clone the repository
+git clone https://github.com/HKUDS/LightRAG.git
+cd LightRAG
+
+# Install in editable mode (no frontend build required yet)
+pip install -e ".[api]"
+
+# Build frontend when needed (can be done anytime)
+cd lightrag_webui
+bun install
+bun run build
+cd ..
+```
+
+**Advantages:**
+- Install first, build later (flexible workflow)
+- Changes take effect immediately (symlink mode)
+- Frontend can be rebuilt anytime without reinstalling
+
+**How it works:**
+- Creates symlinks to source directory
+- Frontend build output goes to `lightrag/api/webui/`
+- Changes are immediately visible in installed package
+
+---
+
+### 3. Normal Installation (Testing Package Build) 📦
+
+**Command:**
+```bash
+# Clone the repository
+git clone https://github.com/HKUDS/LightRAG.git
+cd LightRAG
+
+# ⚠️ MUST build frontend FIRST
+cd lightrag_webui
+bun install
+bun run build
+cd ..
+
+# Now install
+pip install ".[api]"
+```
+
+**What happens:**
+- Frontend files are **copied** to site-packages
+- Post-build modifications won't affect installed package
+- Requires rebuild + reinstall to update
+
+**When to use:**
+- Testing complete installation process
+- Verifying package configuration
+- Simulating PyPI user experience
+
+---
+
+### 4. Creating Distribution Package 🚀
+
+**Command:**
+```bash
+# Build frontend first
+cd lightrag_webui
+bun install
+bun run build
+cd ..
+
+# Create distribution packages
+python -m build
+
+# Output: dist/lightrag_hku-*.whl and dist/lightrag_hku-*.tar.gz
+```
+
+**What happens:**
+- `setup.py` checks if frontend is built
+- If missing, installation fails with helpful error message
+- Generated package includes all frontend files
+
+---
+
+## GitHub Actions (Automated Release)
+
+When creating a release on GitHub:
+
+1. **Automatically builds frontend** using Bun
+2. **Verifies** build completed successfully
+3. **Creates Python package** with frontend included
+4. **Publishes to PyPI** using existing trusted publisher setup
+
+**No manual intervention required!**
+
+---
+
+## Error Handling
+
+### Error: WebUI Not Built (Normal Install)
+
+```
+╔══════════════════════════════════════════════════════════════════════════╗
+║                    ⚠️  ERROR: WebUI Not Built                            ║
+╚══════════════════════════════════════════════════════════════════════════╝
+
+For normal installation (pip install .), you must build the frontend first:
+
+    cd lightrag_webui
+    bun install
+    bun run build
+    cd ..
+
+Then run the installation again.
+
+💡 TIP: For development, use editable mode instead:
+   pip install -e ".[api]"
+```
+
+**Solution:**
+- Build the frontend first, then install
+- OR use development mode (`pip install -e ".[api]"`)
+
+### Info: Development Mode Without Frontend
+
+```
+╔══════════════════════════════════════════════════════════════════════════╗
+║  ℹ️  Development Mode - WebUI not built yet                             ║
+╚══════════════════════════════════════════════════════════════════════════╝
+
+You're installing in development mode. You can build the frontend later:
+
+    cd lightrag_webui
+    bun install
+    bun run build
+
+The changes will take effect immediately (symlink mode).
+```
+
+**This is informational only** - installation continues successfully.
+
+---
+
+## Quick Reference
+
+| Scenario | Command | Frontend Required | Can Build After |
+|----------|---------|-------------------|-----------------|
+| From PyPI | `pip install lightrag-hku[api]` | Included | No (already installed) |
+| Development | `pip install -e ".[api]"` | No | ✅ Yes (anytime) |
+| Normal Install | `pip install ".[api]"` | ✅ Yes (before) | No (must reinstall) |
+| Create Package | `python -m build` | ✅ Yes (before) | N/A |
+
+---
+
+## Bun Installation
+
+If you don't have Bun installed:
+
+```bash
+# macOS/Linux
+curl -fsSL https://bun.sh/install | bash
+
+# Windows
+powershell -c "irm bun.sh/install.ps1 | iex"
+```
+
+Official documentation: https://bun.sh
+
+---
+
+## File Structure
+
+```
+LightRAG/
+├── lightrag_webui/          # Frontend source code
+│   ├── src/                 # React components
+│   ├── package.json         # Dependencies
+│   └── vite.config.ts       # Build configuration
+│       └── outDir: ../lightrag/api/webui  # Build output
+│
+├── lightrag/
+│   └── api/
+│       └── webui/           # Frontend build output (gitignored)
+│           ├── .gitkeep     # Preserves directory structure
+│           ├── index.html   # Built files (after running bun run build)
+│           └── assets/      # Built assets
+│
+├── setup.py                 # Build checks
+├── pyproject.toml           # Package configuration
+└── .gitignore               # Excludes lightrag/api/webui/* (except .gitkeep)
+```
+
+---
+
+## Troubleshooting
+
+### Q: I installed in development mode but the web interface doesn't work
+
+**A:** Build the frontend:
+```bash
+cd lightrag_webui && bun run build
+```
+
+### Q: I built the frontend but it's not in my installed package
+
+**A:** You probably used `pip install .` after building. Either:
+- Use `pip install -e ".[api]"` for development
+- Or reinstall: `pip uninstall lightrag-hku && pip install ".[api]"`
+
+### Q: Where are the built frontend files?
+
+**A:** In `lightrag/api/webui/` after running `bun run build`
+
+### Q: Can I use npm or yarn instead of Bun?
+
+**A:** The project is configured for Bun. While npm/yarn might work, Bun is recommended per project standards.
+
+---
+
+## Summary
+
+✅ **PyPI users**: No action needed, frontend included
+✅ **Developers**: Use `pip install -e ".[api]"`, build frontend when needed
+✅ **CI/CD**: Automatic build in GitHub Actions
+✅ **Git**: Frontend build output never committed
+
+For questions or issues, please open a GitHub issue.
diff --git a/setup.py b/setup.py
index 655e2e9e..0a796ddb 100644
--- a/setup.py
+++ b/setup.py
@@ -1,6 +1,74 @@
-# Minimal setup.py for backward compatibility
-# Primary configuration is now in pyproject.toml
+"""Minimal setup.py for backward compatibility with frontend build check"""
 
+from pathlib import Path
 from setuptools import setup
+from setuptools.command.build_py import build_py
+import sys
 
-setup()
+
+def check_webui_exists():
+    """Check if WebUI has been built"""
+    webui_index = Path("lightrag/api/webui/index.html")
+    return webui_index.exists()
+
+
+class BuildPyCommand(build_py):
+    """Check WebUI build status before packaging/installation"""
+
+    def run(self):
+        # Check if running in development mode
+        is_develop = any(arg in sys.argv for arg in ["develop", "egg_info"])
+        is_editable = "--editable" in sys.argv or "-e" in sys.argv
+
+        if is_develop or is_editable:
+            # Development mode: friendly reminder
+            if not check_webui_exists():
+                print("""
+╔══════════════════════════════════════════════════════════════════════════╗
+║  ℹ️  Development Mode - WebUI not built yet                             ║
+╚══════════════════════════════════════════════════════════════════════════╝
+
+You're installing in development mode. You can build the frontend later:
+
+    cd lightrag_webui
+    bun install
+    bun run build
+
+The changes will take effect immediately (symlink mode).
+╚══════════════════════════════════════════════════════════════════════════╝
+""")
+        else:
+            # Normal installation/packaging mode: frontend build required
+            if not check_webui_exists():
+                print("""
+╔══════════════════════════════════════════════════════════════════════════╗
+║                    ⚠️  ERROR: WebUI Not Built                            ║
+╚══════════════════════════════════════════════════════════════════════════╝
+
+For normal installation (pip install .), you must build the frontend first:
+
+    cd lightrag_webui
+    bun install
+    bun run build
+    cd ..
+
+Then run the installation again.
+
+💡 TIP: For development, use editable mode instead:
+   pip install -e ".[api]"
+
+   This allows you to build the frontend after installation.
+
+╚══════════════════════════════════════════════════════════════════════════╝
+""")
+                sys.exit(1)
+
+        print("✅ Proceeding with package build...")
+        build_py.run(self)
+
+
+setup(
+    cmdclass={
+        "build_py": BuildPyCommand,
+    }
+)