diff --git a/README.md b/README.md
index ed50194..70915f0 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,15 @@
 
 HomeAgent 插件开发 SDK，用于构建与 HomeAgent 平台交互的智能插件。
 
+> 📖 **完整文档**：<https://sdk.homeagent.jianfgit.xyz/>
+>
+> 快速开始 / API 参考 / 指南 / 示例插件都在那里，**本 README 只是速览**，
+> 接口细节以文档站为准。直接进入：[快速开始](https://sdk.homeagent.jianfgit.xyz/guide/getting-started/)
+> · [API 参考](https://sdk.homeagent.jianfgit.xyz/api/) · [能力边界](https://sdk.homeagent.jianfgit.xyz/guide/capability-boundary/)
+>
+> 面向 agent 的纯文本入口：[`llms.txt`](https://sdk.homeagent.jianfgit.xyz/llms.txt)
+> （含全部 API 的 [`llms-full.txt`](https://sdk.homeagent.jianfgit.xyz/llms-full.txt)）。
+
 ## 版本与兼容性
 
 当前：**SDK 1.3.0**（需内核 **1.3.0+**）。
@@ -337,15 +346,23 @@ func New(name string, sett SettingsAPI, regTool ToolRegistrar, regStage StageReg
 ## hmapdev 工具链
 
 `hmapdev` 提供插件开发全流程支持，最终产出 `.hmap` 插件包（工具名即来自该包格式）。
-预编译二进制作为 **release 附件**分发（linux/darwin/windows × amd64/arm64），从
-[Releases](https://gitcode.com/JianFeeeee/homeagent-sdk/releases) 下载后加入 PATH 即可：
+预编译二进制作为 **release 附件**分发（linux/darwin/windows × amd64/arm64），
+下载后加入 PATH 即可：
+
+> ⚠️ **二进制的实际分发地址目前是 gitcode**（两个仓的 release 附件不同步）：
+> `hmapdev_linux_amd64` 等 5 个平台二进制 + `SHA256SUMS` 在
+> <https://gitcode.com/JianFeeeee/homeagent-sdk/releases>。
+> GitHub 侧（<https://github.com/JianFeeeee/homeagentsdk/releases>）从
+> 下一个 SDK 版本（v1.4.0）起才会同步发布 —— 因为 SDK 仓**移仓后还没发过版**。
+> 源码与文档一律以 GitHub 为准，**只有二进制暂时还得到 gitcode 取**。
 
 > 改名说明：工具链原名 `plugindev`，自 1.2.0 起更名 `hmapdev`。
 > SDK 存储目录同时由 `~/.homeagent/plugindev/sdk` 迁到 `~/.homeagent/hmapdev/sdk`
 > （旧目录会被自动沿用，不会丢已装版本）。
 
 ```bash
-# 从 release 附件下载（以最新 SDK 发布 / linux amd64 为例）
+# 从 release 附件下载（以 linux amd64 为例，<版本> 如 v1.3.0）
+# 当前实际分发地址是 gitcode（见下方说明）：
 curl -Lo hmapdev https://gitcode.com/JianFeeeee/homeagent-sdk/releases/download/<版本>/hmapdev_linux_amd64
 chmod +x hmapdev
 
@@ -956,6 +973,19 @@ curl -X POST http://127.0.0.1:9876/plugins \
 
 或通过 WebUI 插件管理页面上传，也可手动将 `.hmap` 放入插件目录后重启平台。
 
+## 文档
+
+- 文档站：**<https://sdk.homeagent.jianfgit.xyz/>**
+- 快速开始：[环境与工具链](https://sdk.homeagent.jianfgit.xyz/guide/getting-started/) · [第一个 Go 插件](https://sdk.homeagent.jianfgit.xyz/guide/first-plugin/) · [第一个 Lua 插件](https://sdk.homeagent.jianfgit.xyz/guide/first-lua-plugin/)
+- API 参考：[总览](https://sdk.homeagent.jianfgit.xyz/api/) · [工具](https://sdk.homeagent.jianfgit.xyz/api/tools/) · [阶段钩子](https://sdk.homeagent.jianfgit.xyz/api/stages/) · [记忆](https://sdk.homeagent.jianfgit.xyz/api/memory/) · [输入/输出通道](https://sdk.homeagent.jianfgit.xyz/api/channels/)
+- 指南：[能力边界（哪些 API 外部可用）](https://sdk.homeagent.jianfgit.xyz/guide/capability-boundary/) · [工具并发声明](https://sdk.homeagent.jianfgit.xyz/guide/parallel-tool-declaration/) · [流式多 tool_call](https://sdk.homeagent.jianfgit.xyz/guide/stream-tool-call-index/) · [场景记忆](https://sdk.homeagent.jianfgit.xyz/guide/scene-memory/) · [打包与发布](https://sdk.homeagent.jianfgit.xyz/guide/packaging/)
+- 版本与兼容：<https://sdk.homeagent.jianfgit.xyz/versions/>
+- 核心仓（内核 / 记忆 / 调度）：<https://github.com/JianFeeeee/HomeAgent>
+- 介绍站：<https://introduce.homeagent.jianfgit.xyz/>
+
+> 文档站为自托管（国内直连，不必挂代理）。构建与部署见核心仓的
+> `deploy-sdk-site.sh`（`--check` 只比对、`--rollback` 回滚）。
+
 ## 许可
 
 SDK 以 **MIT** 发布，全文见 [LICENSE](LICENSE)。
diff --git a/README_EN.md b/README_EN.md
index 32f9bd9..bd5e3d4 100644
--- a/README_EN.md
+++ b/README_EN.md
@@ -2,6 +2,16 @@
 
 Plugin development SDK for building intelligent plugins that interact with the HomeAgent platform.
 
+> 📖 **Full documentation**: <https://sdk.homeagent.jianfgit.xyz/>
+>
+> Quick start / API reference / guides / example plugins all live there. **This README is a
+> summary only** — the docs site is authoritative for interface details.
+> Jump to: [Getting started](https://sdk.homeagent.jianfgit.xyz/guide/getting-started/)
+> · [API reference](https://sdk.homeagent.jianfgit.xyz/api/) · [Capability boundary](https://sdk.homeagent.jianfgit.xyz/guide/capability-boundary/)
+>
+> Agent-friendly plain-text entry points: [`llms.txt`](https://sdk.homeagent.jianfgit.xyz/llms.txt)
+> and [`llms-full.txt`](https://sdk.homeagent.jianfgit.xyz/llms-full.txt) (the whole docs in one file).
+
 ## Version and Compatibility
 
 Current: **SDK 1.3.0** (requires kernel **1.3.0+**).
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
index d2c27d7..a45f39a 100644
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -13,13 +13,19 @@
 从源码构建：
 
 ```bash
-git clone https://gitcode.com/JianFeeeee/homeagent-sdk
-cd homeagent-sdk/tools/hmapdev
+git clone https://github.com/JianFeeeee/homeagentsdk
+cd homeagentsdk/tools/hmapdev
 go build -o hmapdev
 # 把 hmapdev 放进 PATH，或直接用 ./hmapdev
 ```
 
-也可以从 SDK 的 release 附件下载预编译二进制（`hmapdev_linux_amd64` 等）。
+也可以从 SDK 的 release 附件下载预编译二进制（`hmapdev_linux_amd64` 等，
+共 5 个平台：linux/darwin/windows × amd64/arm64）。
+
+> 仓已迁到 GitHub；gitcode 仅作国内镜像（源码同步，**release 附件暂时仍在那里**）：
+> `https://gitcode.com/JianFeeeee/homeagent-sdk/releases`。
+> Go 模块路径仍是 `gitcode.com/JianFeeeee/homeagent-sdk` —— 这是有意保留的，
+> 改模块路径会让现有插件的 `go.mod` 全面失效。
 
 ## SDK 版本管理
 
diff --git a/mkdocs.yml b/mkdocs.yml
index bff39eb..2061db8 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -92,9 +92,17 @@ markdown_extensions:
 extra:
   generator: false
   social:
+    # 主仓已迁到 GitHub；gitcode 保留为国内镜像（源码同步）。
+    # 两个链接都放，是因为国内直连 gitcode 更快，而海外/权威源看 GitHub。
     - icon: fontawesome/solid/code
+      link: https://github.com/JianFeeeee/homeagentsdk
+      name: SDK 源码（GitHub）
+    - icon: fontawesome/solid/code-branch
       link: https://gitcode.com/JianFeeeee/homeagent-sdk
-      name: SDK 源码
+      name: gitcode 镜像（国内）
+    - icon: fontawesome/solid/house
+      link: https://introduce.homeagent.jianfgit.xyz/
+      name: HomeAgent 介绍站
   # 自定义检索端点在 docs/javascripts/api-search.js 里注册，
   # 索引文件由 gensite 产出：docs/assets/api-index.json