docs: clarify dashboard install troubleshooting and frontend setup

README.md

@@ -142,6 +142,7 @@ On 50 professional tasks (**📈 [GDPVal Economic Benchmark](#-benchmark-gdpval)
 git clone https://github.com/HKUDS/OpenSpace.git && cd OpenSpace
 pip install -e .
 openspace-mcp --help   # verify installation
+openspace-dashboard --help   # verify dashboard entry point
 ```
 
 > [!TIP]
@@ -153,6 +154,18 @@ openspace-mcp --help   # verify installation
 > pip install -e .
 > ```
 
+If your shell cannot find `openspace-dashboard`, use the module form from the same environment:
+
+```bash
+python -m openspace.dashboard_server --help
+```
+
+### Windows / PATH Troubleshooting
+
+- Activate the same virtual environment you used for `pip install -e .` before running the commands above.
+- If `openspace-dashboard` is still not on `PATH`, use `python -m openspace.dashboard_server --host 127.0.0.1 --port 7788`.
+- If the backend is running on a different machine or port, update the frontend proxy settings to match. Only change `OPENSPACE_WORKSPACE` when the OpenSpace workspace path itself changes.
+
 **Choose your path:**
 - **[Path A](#-path-a-for-your-agent)** — Plug OpenSpace into your agent
 - **[Path B](#-path-b-as-your-co-worker)** — Use OpenSpace directly as your AI co-worker
@@ -250,6 +263,9 @@ See how your skills evolve — browse skills, track lineage, compare diffs.
 # Terminal 1. Start backend API
 openspace-dashboard --port 7788
 
+# Fallback if the console script is unavailable
+python -m openspace.dashboard_server --port 7788
+
 # Terminal 2: Start frontend dev server
 cd frontend
 npm install        # only needed once

README_CN.md

@@ -142,6 +142,7 @@ Skill 能够自动学习并持续提升
 git clone https://github.com/HKUDS/OpenSpace.git && cd OpenSpace
 pip install -e .
 openspace-mcp --help   # 验证安装
+openspace-dashboard --help   # 验证 dashboard 入口
 ```
 
 > [!TIP]
@@ -153,6 +154,18 @@ openspace-mcp --help   # 验证安装
 > pip install -e .
 > ```
 
+如果你的命令行找不到 `openspace-dashboard`，请在同一个环境里改用模块方式：
+
+```bash
+python -m openspace.dashboard_server --help
+```
+
+### Windows / PATH 排查
+
+- 先激活执行 `pip install -e .` 时使用的同一个虚拟环境。
+- 如果 `openspace-dashboard` 仍然找不到，直接用 `python -m openspace.dashboard_server --host 127.0.0.1 --port 7788`。
+- 如果后端运行在其他主机或端口，请同步更新前端代理配置。只有 OpenSpace 工作区路径本身变化时，才需要修改 `OPENSPACE_WORKSPACE`。
+
 **选择你的路径：**
 - **[路径 A](#-路径-a为你的-agent-接入)** — 将 OpenSpace 接入你的 Agent
 - **[路径 B](#-路径-b作为你的-ai-协作者)** — 直接使用 OpenSpace 作为你的 AI 协作者
@@ -250,6 +263,9 @@ asyncio.run(main())
 # 终端 1：启动后端 API
 openspace-dashboard --port 7788
 
+# 如果控制台命令不可用
+python -m openspace.dashboard_server --port 7788
+
 # 终端 2：启动前端开发服务器
 cd frontend
 npm install        # 仅首次需要

frontend/README.md

@@ -30,7 +30,28 @@ VITE_API_BASE_URL=/api/v1
 npm install
 ```
 
-3. **Start the backend** (in a separate terminal)
+3. **Install the OpenSpace Python package** from the repo root into the same Python environment that will run the backend:
+
+```bash
+cd ..
+python -m pip install -e .
+```
+
+4. **Verify both backend entry points** from that same activated Python environment:
+
+```bash
+openspace-mcp --help
+openspace-dashboard --help
+```
+
+If the console scripts are still unavailable on `PATH`, verify the module entry points from the repo root instead:
+
+```bash
+python -m openspace.mcp_server --help
+python -m openspace.dashboard_server --help
+```
+
+5. **Start the backend** (in a separate terminal)
 
 ```bash
 # option A – CLI entry point
@@ -41,23 +62,29 @@ python -m openspace.dashboard_server --host 127.0.0.1 --port 7788
 ```
 
 > Requires Python ≥ 3.12 with `flask` installed.
+>
+> If `openspace-dashboard` is not on `PATH`, use option B. On Windows, make sure the same virtual environment is activated before running either command.
 
-4. **Start the frontend**
+6. **Start the frontend**
 
 ```bash
+cd frontend
 npm run dev
 ```
 
 The dev server will be available at `http://127.0.0.1:3888` (or whatever `VITE_PORT` you set).
 
 ## Subsequent Starts
 
-Once `.env` is configured and dependencies are installed, you only need:
+Once `.env` is configured, frontend dependencies are installed, and the OpenSpace package is installed in your active Python environment, you only need:
 
 ```bash
 # terminal 1 – backend
 openspace-dashboard --host 127.0.0.1 --port 7788
 
+# fallback if the console script is unavailable
+python -m openspace.dashboard_server --host 127.0.0.1 --port 7788
+
 # terminal 2 – frontend
 cd frontend
 npm run dev