diff --git a/docs/reference/device-pod.md b/docs/reference/device-pod.md
index b13b27f6..7968c4f1 100644
--- a/docs/reference/device-pod.md
+++ b/docs/reference/device-pod.md
@@ -30,12 +30,37 @@ device-pod -> cloud-api -> gateway -> cmd -> skill/downloader -> debug probe ->
 
 `debugInterface` 只暴露设备语义能力，例如 `debug.probe`、`debug.download`、`debug.reset`。不得把它退化成任意 shell 执行入口。
 
+`debugInterface` 不承载源码编译、工程发现或工具链定义；这些属于
+`projectWorkspace`。`debugInterface` 可以消费 `projectWorkspace` 产生的
+artifact，例如 `.hex`、`.bin` 或 `.elf`，并负责把该 artifact 下载、校验、
+复位或附着调试到 `deviceTarget`。
+
 ### `projectWorkspace`
 
 `projectWorkspace` 是设备对应的源码、工程文件和编译工具链上下文，例如 Keil 工程、target 名称、构建脚本和 workspace root。它描述如何从源码生成可下载产物，也为 debug/download job 提供工程路径和工具链边界。
 
 `projectWorkspace` 可以和 `debugInterface` 位于同一台用户 PC，也可以只通过 gateway 暴露受控 CLI。HWLAB 不直接读取 secret、kubeconfig、DB URL 或完整源码内容；探测必须有界。
 
+工程源码的编译和工具链归属 `projectWorkspace`，包括：
+
+- 源码根目录、工程文件和 target 名称；
+- build profile、编译参数和工具链入口；
+- build、clean、artifact list 等工程动作；
+- `.hex`、`.bin`、`.elf` 等下载产物的位置和元数据。
+
+因此 build 失败应归类为 workspace/toolchain blocker；download、reset 或
+probe attach 失败才归类为 debug/probe/target blocker。
+
+典型流程为：
+
+```text
+projectWorkspace.build
+-> artifact
+-> debugInterface.download
+-> debugInterface.reset
+-> ioInterface.status/sample/uart
+```
+
 ### `ioInterface`
 
 `ioInterface` 是设备的实时或近实时 I/O 观测与控制接口，代表 UART、AI、AO、DI、DO、状态采样、日志抓取等能力。典型实现包括 DAPLink 自带串口、独立串口工具、USB/WiFi/厂商协议上位机或 `device-host-cli`。
@@ -76,6 +101,7 @@ GET /health
 GET /v1/profile
 GET /v1/status
 GET /v1/capabilities
+GET /v1/workspace/status
 GET /v1/debug/status
 GET /v1/io/status
 ```
@@ -83,6 +109,7 @@ GET /v1/io/status
 异步 API 用于下载、复位、采样等动作；每个 HTTP 调用必须短，长耗时由 job 轮询表达：
 
 ```text
+POST /v1/workspace/jobs
 POST /v1/debug/jobs
 POST /v1/io/jobs
 GET /v1/jobs/{jobId}
@@ -93,8 +120,11 @@ POST /v1/jobs/{jobId}/cancel
 第一版可接受的 intent 示例：
 
 ```text
+workspace.detect
+workspace.build
+workspace.clean
+workspace.artifact.list
 debug.probe
-debug.build
 debug.download
 debug.reset
 io.status.read