From b009cd3027fae698142348e27481d179d8e53f1b Mon Sep 17 00:00:00 2001
From: who96 <825265100@qq.com>
Date: Thu, 26 Mar 2026 08:49:09 +0800
Subject: [PATCH 1/2] docs: clarify dashboard install and fallback startup

---
 README.md          | 16 ++++++++++++++++
 README_CN.md       | 16 ++++++++++++++++
 frontend/README.md | 12 ++++++++++++
 3 files changed, 44 insertions(+)

diff --git a/README.md b/README.md
index 7d9ea13..3303948 100644
--- a/README.md
+++ b/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
diff --git a/README_CN.md b/README_CN.md
index eca8642..c82b712 100644
--- a/README_CN.md
+++ b/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        # 仅首次需要
diff --git a/frontend/README.md b/frontend/README.md
index bd6051e..4028da5 100644
--- a/frontend/README.md
+++ b/frontend/README.md
@@ -30,6 +30,13 @@ VITE_API_BASE_URL=/api/v1
 npm install
 ```
 
+After the package is installed, verify both backend entry points from the same activated Python environment:
+
+```bash
+openspace-mcp --help
+openspace-dashboard --help
+```
+
 3. **Start the backend** (in a separate terminal)
 
 ```bash
@@ -41,6 +48,8 @@ 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**
 
@@ -58,6 +67,9 @@ Once `.env` is configured and dependencies are installed, you only need:
 # 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

From efd020317c0d4b6552f5c06cd13ae7deea70957b Mon Sep 17 00:00:00 2001
From: who96 <825265100@qq.com>
Date: Thu, 26 Mar 2026 09:20:05 +0800
Subject: [PATCH 2/2] docs: apply PR1 dashboard install review fixes

---
 frontend/README.md | 23 +++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/frontend/README.md b/frontend/README.md
index 4028da5..5544437 100644
--- a/frontend/README.md
+++ b/frontend/README.md
@@ -30,14 +30,28 @@ VITE_API_BASE_URL=/api/v1
 npm install
 ```
 
-After the package is installed, verify both backend entry points from the same activated Python environment:
+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
 ```
 
-3. **Start the backend** (in a separate terminal)
+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
@@ -51,9 +65,10 @@ python -m openspace.dashboard_server --host 127.0.0.1 --port 7788
 >
 > 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
 ```
 
@@ -61,7 +76,7 @@ The dev server will be available at `http://127.0.0.1:3888` (or whatever `VITE_P
 
 ## 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