From 5b3555143459f92873568a9345c701adbbe136d3 Mon Sep 17 00:00:00 2001
From: red chen <redredchen01@gmail.com>
Date: Fri, 17 Jul 2026 16:45:10 +0800
Subject: [PATCH] Release v0.3.11: position repo as Grok plugin with clearer
 install

Document plugin-first packaging (manifest, commands, skills, hooks) and
have install.sh build the CLI, install the tmux dashboard, and register
the plugin so clone-and-setup matches how the project is shipped.
---
 .grok-plugin/marketplace.json  |   6 +-
 CHANGELOG.md                   |  12 ++
 CONTRIBUTING.md                |  18 ++-
 README.en.md                   | 108 +++++++++++++----
 README.md                      | 214 +++++++++++++++++++++++++--------
 commands/setup.md              |  30 +++--
 hooks/hooks.json               |   2 +-
 package.json                   |   7 +-
 plugin.json                    |   4 +-
 scripts/install.sh             |  44 +++++--
 skills/grok-build-hud/SKILL.md |  12 +-
 11 files changed, 344 insertions(+), 113 deletions(-)

diff --git a/.grok-plugin/marketplace.json b/.grok-plugin/marketplace.json
index 8200c1c..c495ddb 100644
--- a/.grok-plugin/marketplace.json
+++ b/.grok-plugin/marketplace.json
@@ -1,12 +1,12 @@
 {
   "name": "grok-build-hud-local",
-  "description": "Local marketplace entry for grok-build-hud",
-  "owner": { "name": "sooneocean" },
+  "description": "Local marketplace entry for the grok-build-hud Grok plugin",
+  "owner": { "name": "Redredchen01" },
   "plugins": [
     {
       "name": "grok-build-hud",
       "source": { "type": "local", "path": ".." },
-      "description": "Claude-HUD-style live status HUD for Grok Build",
+      "description": "Grok Build live multi-line status strip (context, quota, tokens, tools) — same-window tmux HUD",
       "category": "monitoring"
     }
   ]
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f681ebe..ebbe7a0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.3.11
+
+### Docs / packaging
+- **Plugin-first positioning**: README / README.en present this as a **Grok plugin**
+  (manifest + commands + skills + hooks) with CLI/tmux as the runtime, not an
+  optional add-on.
+- **Install**: `scripts/install.sh` now registers the plugin via
+  `grok plugin install . --trust` + `enable` after building the dashboard.
+- Clarified plugin-only vs full HUD (dashboard) install paths; FAQ and
+  CONTRIBUTING / skill / setup command docs aligned.
+- Bump package + `plugin.json` to 0.3.11; marketplace description cleaned.
+
 ## 0.3.10
 
 ### Docs / repo
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 81ee074..61c9e60 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,6 +2,10 @@
 
 > English notes: keep commit messages in English. Primary docs are Chinese ([README.md](./README.md)); English summary: [README.en.md](./README.en.md).
 
+## 定位
+
+本仓库以 **Grok 插件** 形式交付（`plugin.json` + `commands/` + `skills/` + `hooks/`），运行时依赖 Node CLI + 同窗口 tmux 状态条。改文档时保持「插件优先」表述。
+
 ## 环境
 
 ```bash
@@ -9,18 +13,23 @@ git clone http://172.238.15.154:3000/Redredchen01/grok-hud.git
 cd grok-hud
 npm install
 npm test
+npm run plugin:validate   # 需本机 grok CLI
 ```
 
 ## 目录结构
 
 | 路径 | 作用 |
 |------|------|
+| `plugin.json` | Grok 插件清单 |
+| `.grok-plugin/` | 本地 marketplace 元数据 |
+| `commands/` | 会话斜杠命令 |
+| `skills/` | Agent skill |
+| `hooks/` | Session hooks |
 | `src/` | TypeScript 源码（session、billing、status、tmux、theme、CLI） |
 | `bin/` | 入口：`grok-build-hud`、`grok-hud`、`grok-hud-run`、hook |
 | `tests/` | Node 内置测试 (`node --test`) |
 | `fixtures/` | 测试用 session / billing 样例 |
-| `commands/` / `skills/` | Grok 插件表面 |
-| `scripts/install.sh` | 一键安装 |
+| `scripts/install.sh` | 一键：CLI + dashboard + 插件注册 |
 | `README.md` | **中文主文档** |
 | `README.en.md` | 英文简版 |
 
@@ -30,12 +39,13 @@ npm test
 - 配额接口离线 / 未登录时**优雅降级**（渲染路径不抛错）  
 - HUD 保持**同窗口**（tmux status），默认不另开 Terminal  
 - 改解析 / 渲染逻辑请补测试  
+- hooks 依赖 `dist/`：改 hook 路径前确认 `npm run build`  
 - **Commit message 用英文**；用户文档以中文为主  
 
 ## 提交前
 
 ```bash
 npm test
+# 若改了 plugin.json / commands / skills / hooks：
+npm run plugin:validate
 ```
-
-全部测试通过后再 push。
diff --git a/README.en.md b/README.en.md
index 40213f8..fe19ce6 100644
--- a/README.en.md
+++ b/README.en.md
@@ -1,8 +1,8 @@
-# grok-hud
+# grok-build-hud
 
-**Live multi-line status strip for [Grok Build](https://x.ai/cli)**
+**Live multi-line status strip for [Grok Build](https://x.ai/cli) — shipped as a Grok plugin**
 
-> 中文文档（主 README）：[README.md](./README.md)
+> Primary docs (Chinese): [README.md](./README.md)
 
 Always-on strip at the bottom of the **same Terminal tab** (tmux status — not a second window):
 
@@ -22,19 +22,34 @@ ctx ██████░░░░ 50% (252k/500k) · i … o … c 99% · use 2
 | Multi-terminal | Independent session per tab |
 | Language | Default **简体中文**; English / 繁體 available |
 
-Repo: http://172.238.15.154:3000/Redredchen01/grok-hud
+Repo: http://172.238.15.154:3000/Redredchen01/grok-hud  
+Plugin id: `grok-build-hud` · version in [`plugin.json`](./plugin.json)
+
+---
+
+## What it is
+
+| Layer | Role |
+|-------|------|
+| **Delivery** | **Grok plugin** (`plugin.json` + `commands/` + `skills/` + `hooks/`) |
+| **Runtime** | Node CLI + **same-window tmux status strip** |
+| **Skill** | Bundled agent skill for in-session discovery |
+
+One line: a bottom status bar for Grok Build — context, quota, tokens, tools, todos.
 
 ---
 
 ## Requirements
 
-- Node.js 18+
+- Grok Build CLI + `grok login`
+- Node.js 18+ and npm
 - tmux (`brew install tmux` on macOS)
-- Grok Build signed in (`grok login`)
 
 ---
 
-## Install
+## Install (recommended)
+
+One script: **build CLI → install tmux HUD → register as Grok plugin**.
 
 ```bash
 git clone http://172.238.15.154:3000/Redredchen01/grok-hud.git
@@ -42,21 +57,17 @@ cd grok-hud
 bash scripts/install.sh
 ```
 
-Or:
+Then:
 
 ```bash
-npm install && npm run build && npm link
-npm run install-local
+grok                 # Grok + bottom HUD (same tab)
+grok-hud status
+grok-hud settings
 ```
 
-Optional plugin:
+Reload hooks in Grok: `/hooks` then `r` if needed.
 
-```bash
-grok plugin install . --trust
-grok plugin enable grok-build-hud
-```
-
-PATH (if commands missing):
+### PATH (if commands missing)
 
 ```bash
 export PATH="$(npm prefix -g)/bin:$HOME/.local/bin:$PATH"
@@ -64,20 +75,67 @@ export PATH="$(npm prefix -g)/bin:$HOME/.local/bin:$PATH"
 
 ---
 
+## Install pieces
+
+### CLI + same-window strip only
+
+```bash
+npm install && npm run build && npm link
+npm run install-local
+```
+
+### Register as Grok plugin (slash commands + skill + hooks)
+
+Build first (`dist/` is required by hooks):
+
+```bash
+npm install && npm run build
+grok plugin install . --trust
+grok plugin enable grok-build-hud
+grok plugin validate .
+```
+
+> Plugin-only install gives `/hud` etc. and scrollback annotations, **not** the multi-line tmux bar. Use `install.sh` for the full experience.
+
+### Update
+
+```bash
+git pull && bash scripts/install.sh
+# or: grok plugin update grok-build-hud
+```
+
+---
+
 ## Daily use
 
 ```bash
-grok                          # Grok + bottom HUD (same tab)
+grok                          # Grok + bottom HUD
 GROK_NO_HUD=1 grok -p "hi"    # bare CLI
 grok-hud status
 grok-hud settings             # language / preset / rows
-grok-hud lang en              # English labels
-grok-hud lang zh              # 简体中文 (default)
-grok-build-hud --theme auto   # follow Grok theme
+grok-hud lang en|zh|tw
+grok-build-hud --preset full|essential|minimal
+grok-build-hud --theme auto
 grok-hud stop
 ```
 
-Each Terminal tab gets an **independent** Grok session (unique tmux name).
+In-session (plugin enabled): `/hud` `/status` `/quota` `/preset` `/settings` `/setup` `/watch`
+
+Each Terminal tab gets an **independent** Grok session.
+
+---
+
+## Plugin layout
+
+```text
+plugin.json              # manifest
+.grok-plugin/            # local marketplace metadata
+commands/                # slash commands
+skills/grok-build-hud/   # agent skill
+hooks/hooks.json         # session hooks
+bin/ + src/              # CLI + HUD runtime
+scripts/install.sh       # one-shot installer
+```
 
 ---
 
@@ -93,11 +151,13 @@ Each Terminal tab gets an **independent** Grok session (unique tmux name).
 
 `language`: `zh-Hans` (default) / `en` / `zh-Hant`
 
+Theme always tracks Grok `/theme` unless `GROK_HUD_LOCK=1`.
+
 ---
 
 ## How it works
 
-Reads local `~/.grok/sessions/**`, uses existing Grok auth for billing, writes status files under `~/.grok/hud/`, displays via same-window tmux. Does **not** upload your code.
+Reads local `~/.grok/sessions/**`, uses existing Grok auth for billing, writes under `~/.grok/hud/`, displays via same-window tmux. Does **not** upload your code.
 
 ---
 
@@ -106,6 +166,7 @@ Reads local `~/.grok/sessions/**`, uses existing Grok auth for billing, writes s
 ```bash
 grok-build-hud --uninstall-dashboard
 grok-build-hud --uninstall-hooks
+grok plugin uninstall grok-build-hud
 npm unlink -g grok-build-hud
 ```
 
@@ -116,6 +177,7 @@ npm unlink -g grok-build-hud
 ```bash
 npm install
 npm test
+npm run plugin:validate
 ```
 
 Primary documentation is **Chinese** ([README.md](./README.md)). Commit messages in English.
diff --git a/README.md b/README.md
index 62dba77..b41691e 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
-# grok-hud
+# grok-build-hud
 
-**[Grok Build](https://x.ai/cli) 实时多行状态条**
+**Grok Build 官方插件格式的实时状态条**
 
 > English: [README.en.md](./README.en.md)
 
@@ -22,23 +22,39 @@ Grok 4.5 · AI FILM SPACE/0717 · ●
 | 多终端 | 每个标签页**独立** session，互不串线 |
 | 语言 | 默认**简体中文**，可切英文 / 繁體 |
 
-仓库：http://172.238.15.154:3000/Redredchen01/grok-hud
+仓库：http://172.238.15.154:3000/Redredchen01/grok-hud  
+插件名：`grok-build-hud` · 版本见 [`plugin.json`](./plugin.json)
+
+---
+
+## 这是什么
+
+| 层级 | 说明 |
+|------|------|
+| **交付形态** | **Grok 插件**（`plugin.json` + `commands/` + `skills/` + `hooks/`） |
+| **运行时** | Node CLI（`grok-hud` / `grok-build-hud`）+ **同窗口 tmux 状态条** |
+| **Skill** | 插件内附带，方便会话里被 agent 识别与调用 |
+
+**一句话：** 给 Grok Build 用的底部状态栏——上下文、配额、token、工具与待办，一眼看到。
 
 ---
 
 ## 目录
 
 1. [依赖](#依赖)
-2. [安装](#安装)
-3. [日常使用](#日常使用)
-4. [设定（语言 / 预设）](#设定语言--预设)
-5. [状态条说明](#状态条说明)
-6. [配置](#配置)
-7. [主题](#主题)
-8. [工作原理](#工作原理)
-9. [卸载](#卸载)
-10. [常见问题](#常见问题)
-11. [开发](#开发)
+2. [安装（推荐一键）](#安装推荐一键)
+3. [安装拆解](#安装拆解)
+4. [日常使用](#日常使用)
+5. [会话内斜杠命令](#会话内斜杠命令)
+6. [设定（语言 / 预设）](#设定语言--预设)
+7. [状态条说明](#状态条说明)
+8. [配置](#配置)
+9. [主题](#主题)
+10. [插件结构](#插件结构)
+11. [工作原理](#工作原理)
+12. [卸载](#卸载)
+13. [常见问题](#常见问题)
+14. [开发](#开发)
 
 ---
 
@@ -46,16 +62,17 @@ Grok 4.5 · AI FILM SPACE/0717 · ●
 
 | 依赖 | 说明 |
 |------|------|
+| **Grok Build** | 已安装 CLI，并 `grok login` |
 | **Node.js 18+** | `node -v` |
-| **tmux** | macOS：`brew install tmux` |
-| **Grok Build** | 已登录：`grok login` |
-| 终端 | Terminal / iTerm 等（在 tmux 内运行即可） |
+| **npm** | 随 Node 安装 |
+| **tmux** | 同窗口 HUD 必需；macOS：`brew install tmux` |
+| 终端 | Terminal / iTerm 等 |
 
 ---
 
-## 安装
+## 安装（推荐一键）
 
-### 方式 A：从 Gitea 克隆（推荐）
+从 Gitea 克隆后执行安装脚本：**编译 CLI → 装 tmux 状态条 → 注册为 Grok 插件**。
 
 ```bash
 git clone http://172.238.15.154:3000/Redredchen01/grok-hud.git
@@ -63,28 +80,23 @@ cd grok-hud
 bash scripts/install.sh
 ```
 
-会自动：`npm install` → 编译 → `npm link` → 装 dashboard / hooks → 主题跟随 → 预设 full → 语言中文。
+脚本会依次：
 
-### 方式 B：已有源码目录
+1. `npm install` + `npm run build`
+2. `npm link`（`grok-hud` / `grok-build-hud` 进 PATH）
+3. `--install-dashboard`（hooks + tmux 多行状态条 + `grok` wrapper）
+4. 主题跟随 + 预设 `full`
+5. `grok plugin install . --trust` 并 `enable`（若本机有 `grok`）
+
+完成后：
 
 ```bash
-cd /path/to/grok-hud
-bash scripts/install.sh
-# 或：
-npm install && npm run build && npm link
-npm run install-local
+grok                 # 同窗口底部出现状态条
+grok-hud status      # 打印一次完整状态
+grok-hud settings    # 语言 / 预设 / 行数
 ```
 
-### 方式 C：作为 Grok 插件（可选）
-
-```bash
-cd /path/to/grok-hud
-npm install && npm run build
-grok plugin install . --trust
-grok plugin enable grok-build-hud
-```
-
-在 Grok 内执行 `/hooks` 后按 `r` 重载 hooks。
+在 Grok 内执行 `/hooks` 后按 `r` 重载 hooks（若提示未加载）。
 
 ### 命令找不到时
 
@@ -94,13 +106,52 @@ grok plugin enable grok-build-hud
 export PATH="$(npm prefix -g)/bin:$HOME/.local/bin:$PATH"
 ```
 
-然后：
+然后 `source ~/.zshrc`，再 `which grok-hud`。
+
+---
+
+## 安装拆解
+
+只想分步做时：
+
+### 1）仅 CLI + 同窗口状态条（无心功能）
 
 ```bash
-source ~/.zshrc
-which grok-hud
+cd /path/to/grok-hud
+npm install && npm run build && npm link
+npm run install-local
+# 等价于：--install-dashboard + --theme auto + --preset full
 ```
 
+### 2）注册为 Grok 插件（斜杠命令 + skill + session hooks）
+
+须先完成编译（插件 hooks 依赖 `dist/`）：
+
+```bash
+cd /path/to/grok-hud
+npm install && npm run build
+grok plugin install . --trust
+grok plugin enable grok-build-hud
+```
+
+校验：
+
+```bash
+grok plugin validate .
+grok plugin details grok-build-hud
+```
+
+### 3）从本机已有源码目录更新
+
+```bash
+cd /path/to/grok-hud
+git pull
+bash scripts/install.sh
+# 或：grok plugin update grok-build-hud
+```
+
+> **注意：** 只装插件、不跑 `install-dashboard` 时，会话里会有 `/hud` 等命令与 scrollback 注解，但**不会**出现底部多行 tmux 状态条。完整体验请用一键 `install.sh`。
+
 ---
 
 ## 日常使用
@@ -126,6 +177,33 @@ grok-hud-run
 
 ---
 
+## 会话内斜杠命令
+
+插件启用后，在 Grok 会话中可用：
+
+| 命令 | 作用 |
+|------|------|
+| `/hud` | 状态条相关说明 |
+| `/status` | 打印当前状态 |
+| `/quota` | 配额相关 |
+| `/preset` | 切换 full / essential / minimal |
+| `/settings` | 语言、预设、行数 |
+| `/setup` | 安装 / 修复 dashboard |
+| `/watch` | 保持 HUD 实时更新说明 |
+
+也可在 shell：
+
+```bash
+grok-hud status
+grok-hud settings
+grok-hud lang zh|en|tw
+grok-build-hud --preset full|essential|minimal
+grok-build-hud --theme auto
+grok-hud stop
+```
+
+---
+
 ## 设定（语言 / 预设）
 
 ```bash
@@ -138,15 +216,6 @@ grok-hud lang en    # English
 grok-hud lang tw    # 繁體中文
 ```
 
-| 命令 | 作用 |
-|------|------|
-| `grok-hud status` | 打印当前完整状态一次 |
-| `grok-hud stop` | 停后台刷新 |
-| `grok-build-hud --preset full` | 三行全开（默认） |
-| `grok-build-hud --preset essential` | 两行 |
-| `grok-build-hud --preset minimal` | 一行 |
-| `grok-build-hud --theme auto` | 跟随 Grok 主题（推荐） |
-
 改完配置后若条未变，在 tmux 内：
 
 ```bash
@@ -166,8 +235,7 @@ tmux source-file ~/.grok/hud/tmux.conf && tmux refresh-client -S
 中文标签：`窗 / 额 / 入 / 出 / 缓 / 思 / 轮 / 具`  
 英文标签：`ctx / use / i / o / c / r / t / ⚙`  
 
-宽度会随窗口自适应：窄窗自动减行、丢次要字段，避免挤出屏外。
-
+宽度会随窗口自适应：窄窗自动减行、丢次要字段，避免挤出屏外。  
 会话开启时约每秒刷新。
 
 ---
@@ -187,6 +255,7 @@ tmux source-file ~/.grok/hud/tmux.conf && tmux refresh-client -S
 - `language`：`zh-Hans`（默认）/ `en` / `zh-Hant`
 - `bold: true` — 粗体数值
 - `barWidth: 14` — 进度条宽度  
+
 字号由 Terminal 字体决定，状态栏无法单独放大。
 
 ---
@@ -211,6 +280,37 @@ grok-build-hud --theme auto
 
 ---
 
+## 插件结构
+
+本仓库按 Grok 插件清单组织，可直接 `grok plugin install .`：
+
+```text
+grok-hud/                      # Gitea 仓库目录名
+├── plugin.json                # 插件清单（name / commands / skills / hooks）
+├── .grok-plugin/
+│   └── marketplace.json       # 本地 marketplace 元数据
+├── commands/                  # 会话斜杠命令（/hud /status /settings …）
+├── skills/
+│   └── grok-build-hud/        # Agent 可触发的 skill 说明
+├── hooks/
+│   └── hooks.json             # SessionStart / PostToolUse 等注解
+├── bin/                       # CLI 入口
+├── src/                       # TypeScript 源码
+├── scripts/install.sh         # 一键：CLI + dashboard + 插件
+├── README.md                  # 中文主文档（本文件）
+└── README.en.md
+```
+
+| 组件 | 路径 | 作用 |
+|------|------|------|
+| Manifest | `plugin.json` | 插件名、版本、组件入口 |
+| Commands | `commands/*.md` | Grok 内 `/…` 命令 |
+| Skills | `skills/*/SKILL.md` | 会话技能描述 |
+| Hooks | `hooks/hooks.json` | 会话生命周期注解 |
+| CLI / HUD | `bin/` + `src/` | 真正画状态条与查配额 |
+
+---
+
 ## 工作原理
 
 1. 读本机 `~/.grok/sessions/**`（signals / updates / summary）  
@@ -225,9 +325,15 @@ grok-build-hud --theme auto
 ## 卸载
 
 ```bash
+# 状态条 + shell hooks
 grok-build-hud --uninstall-dashboard
 grok-build-hud --uninstall-hooks
-npm unlink -g grok-build-hud   # 若用过 npm link
+
+# Grok 插件
+grok plugin uninstall grok-build-hud
+
+# CLI（若用过 npm link）
+npm unlink -g grok-build-hud
 ```
 
 可选删除：`~/.grok/hud/`、`~/.grok/hooks/grok-build-hud.json`。
@@ -239,12 +345,15 @@ npm unlink -g grok-build-hud   # 若用过 npm link
 | 现象 | 处理 |
 |------|------|
 | `command not found` | 检查 PATH；或 `node bin/grok-hud.js status` |
-| 底部没有状态条 | 用 `grok` 启动；已装 tmux；执行 `--install-dashboard` |
+| 底部没有状态条 | 用 `grok` 启动；已装 tmux；执行 `bash scripts/install.sh` 或 `--install-dashboard` |
+| 只有斜杠命令没有底栏 | 只装了插件；请再跑 dashboard 安装 |
+| 插件未出现 | `grok plugin list`；`grok plugin enable grok-build-hud`；`/hooks` → `r` |
 | 配额显示 `—` | 先 `grok login`，再 `grok-hud status` |
 | 颜色不对 | `grok-build-hud --theme auto`，与 Grok 主题一致 |
 | 状态不更新 | `grok-hud stop` 后重新 `grok` |
-| 多终端串会话 | 更新到新版；每标签独立 `grok`，勿共用旧 `grok-hud` tmux 名 |
+| 多终端串会话 | 更新到新版；每标签独立 `grok` |
 | 字太小 | 放大 Terminal 字体；保持 `bold` / `barWidth` |
+| `build missing` | `npm install && npm run build` 后再装插件 |
 
 ---
 
@@ -254,6 +363,7 @@ npm unlink -g grok-build-hud   # 若用过 npm link
 npm install
 npm test          # 编译 + 单元测试
 npm run build
+npm run plugin:validate   # 需本机有 grok CLI
 ```
 
 - Commit message 用英文  
diff --git a/commands/setup.md b/commands/setup.md
index 416c91f..e3f2c66 100644
--- a/commands/setup.md
+++ b/commands/setup.md
@@ -4,22 +4,37 @@ description: Install grok-build-hud dashboard + same-window multi-line status
 
 # grok-build-hud setup
 
-One-time setup (from the plugin / repo root):
+本仓库是 **Grok 插件**（`plugin.json`）。完整体验 = 插件 + 同窗口 tmux 状态条。
+
+## 推荐：一键安装
+
+在插件 / 仓库根目录：
+
+```bash
+bash scripts/install.sh
+```
+
+会：编译 → `npm link` → `--install-dashboard` → `grok plugin install . --trust`。
+
+## 分步
 
 ```bash
 npm install && npm run build
-# Preferred: full same-window HUD (tmux multi-line strip)
+npm link
 node bin/grok-build-hud.js --install-dashboard
 node bin/grok-build-hud.js --theme auto
 node bin/grok-build-hud.js --preset full
+grok plugin install . --trust
+grok plugin enable grok-build-hud
 ```
 
-Or: `bash scripts/install.sh` / `npm run install-local`.
+或：`npm run install-local`（仅 CLI + dashboard，不含插件注册）。
 
 ## Start Grok with HUD (same Terminal tab)
 
 ```bash
-grok-hud-run
+grok
+# 兼容：grok-hud-run
 ```
 
 You should see **2–3 rows** at the bottom (context + usage bars), not a second window.
@@ -32,14 +47,9 @@ node bin/grok-build-hud.js --install-hooks
 
 Reload in Grok: `/hooks` then press `r`.
 
-Example annotation:
-
-```text
-[hud] ctx 30% 154k/500k │ turns 3 │ tools 78 │ live │ project
-```
-
 ## Verify
 
 ```bash
 grok-hud status
+grok plugin details grok-build-hud
 ```
diff --git a/hooks/hooks.json b/hooks/hooks.json
index 16d88b6..4cb6ebb 100644
--- a/hooks/hooks.json
+++ b/hooks/hooks.json
@@ -1,5 +1,5 @@
 {
-  "description": "Live context/tool HUD annotations while you use Grok Build",
+  "description": "grok-build-hud: live context/quota/token annotations in Grok Build scrollback",
   "hooks": {
     "SessionStart": [
       {
diff --git a/package.json b/package.json
index b2502b9..7699178 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "grok-build-hud",
-  "version": "0.3.10",
-  "description": "Grok Build 实时多行状态条：上下文、配额、入出缓存 token、工具与待办；同窗口 tmux、主题跟随、中英文 UI",
+  "version": "0.3.11",
+  "description": "Grok Build 插件：同窗口实时状态条（上下文、配额、token、工具与待办）；plugin + CLI + tmux HUD",
   "type": "module",
   "main": "dist/src/index.js",
   "bin": {
@@ -41,6 +41,7 @@
     "grok",
     "xai",
     "grok-build",
+    "plugin",
     "hud",
     "statusline",
     "tmux",
@@ -49,7 +50,7 @@
     "quota",
     "tokens"
   ],
-  "author": "dex",
+  "author": "Redredchen01",
   "license": "MIT",
   "repository": {
     "type": "git",
diff --git a/plugin.json b/plugin.json
index dd6f8c6..4fca86f 100644
--- a/plugin.json
+++ b/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "grok-build-hud",
-  "version": "0.3.10",
-  "description": "Grok Build 实时状态条：上下文、配额、token、工具、待办（同窗口 tmux）",
+  "version": "0.3.11",
+  "description": "Grok Build 插件：同窗口实时状态条（上下文、配额、入出缓存 token、工具与待办）；tmux 多行 HUD + 会话斜杠命令",
   "author": {
     "name": "Redredchen01"
   },
diff --git a/scripts/install.sh b/scripts/install.sh
index bfb5154..324d3fd 100755
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
-# One-shot installer for grok-build-hud (run from repo root or via: npm run setup)
+# One-shot installer: CLI + same-window HUD + Grok plugin registration
+# Run from repo root: bash scripts/install.sh  |  npm run setup
 set -euo pipefail
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 cd "$ROOT"
@@ -28,31 +29,54 @@ if [[ "$NODE_MAJOR" -lt 18 ]]; then
   exit 1
 fi
 
-echo "==> 安装依赖"
+echo "==> [1/5] 安装依赖"
 npm install
 
-echo "==> 编译"
+echo "==> [2/5] 编译 (hooks / CLI 需要 dist/)"
 npm run build
 
-echo "==> 链接 CLI 到 PATH (npm link)"
+echo "==> [3/5] 链接 CLI 到 PATH (npm link)"
 npm link
 
-echo "==> 安装 dashboard（hooks + tmux + shims）"
+echo "==> [4/5] 安装 dashboard（tmux 多行状态条 + grok wrapper）"
 node bin/grok-build-hud.js --install-dashboard
 node bin/grok-build-hud.js --theme auto
 node bin/grok-build-hud.js --preset full
 
+echo "==> [5/5] 注册为 Grok 插件 (commands / skills / hooks)"
+if command -v grok >/dev/null 2>&1; then
+  # Prefer enable after install; re-run is ok for updates
+  if grok plugin install . --trust 2>&1; then
+    grok plugin enable grok-build-hud 2>/dev/null || true
+    echo "    插件已安装: grok-build-hud"
+    if grok plugin validate . >/dev/null 2>&1; then
+      echo "    plugin validate: ok"
+    else
+      echo "    warn: plugin validate 未通过（可稍后手动: grok plugin validate .）" >&2
+    fi
+  else
+    echo "    warn: grok plugin install 失败 — 可稍后手动:" >&2
+    echo "      cd \"$ROOT\" && grok plugin install . --trust && grok plugin enable grok-build-hud" >&2
+  fi
+else
+  echo "    warn: 未找到 grok CLI，跳过插件注册" >&2
+  echo "    安装 Grok Build 后执行:" >&2
+  echo "      cd \"$ROOT\" && grok plugin install . --trust && grok plugin enable grok-build-hud" >&2
+fi
+
 echo ""
-VER="$(node -e "import('node:fs').then(fs=>console.log(JSON.parse(fs.readFileSync('package.json','utf8')).version))" 2>/dev/null || echo 0.3.0)"
-echo "完成。grok-build-hud v${VER}"
+VER="$(node -e "import('node:fs').then(fs=>console.log(JSON.parse(fs.readFileSync('package.json','utf8')).version))" 2>/dev/null || echo "?")"
+echo "完成。grok-build-hud v${VER}（Grok 插件 + 同窗口 HUD）"
 echo ""
 echo "  启动 Grok + 底部 HUD：  grok"
 echo "  看当前状态一次：        grok-hud status"
 echo "  设定（语言/预设）：     grok-hud settings"
+echo "  会话斜杠命令：          /hud /status /settings /setup …"
 echo "  主题跟随 Grok：         grok-build-hud --theme auto"
 echo "  停止后台刷新：          grok-hud stop"
+echo "  插件详情：              grok plugin details grok-build-hud"
 echo ""
-echo "文档（中文）：README.md"
-echo "English:      README.en.md"
-echo "若提示 command not found，把下面加入 PATH 后重开终端："
+echo "若 hooks 未生效：在 Grok 内 /hooks 后按 r 重载"
+echo "文档（中文）：README.md  ·  English: README.en.md"
+echo "若 command not found，把下面加入 PATH 后重开终端："
 echo "  export PATH=\"\$(npm prefix -g)/bin:\$HOME/.local/bin:\$PATH\""
diff --git a/skills/grok-build-hud/SKILL.md b/skills/grok-build-hud/SKILL.md
index fe24db1..616ee87 100644
--- a/skills/grok-build-hud/SKILL.md
+++ b/skills/grok-build-hud/SKILL.md
@@ -5,7 +5,7 @@ description: Grok Build 实时状态条（同窗口多行：上下文、配额
 
 # grok-build-hud
 
-**Grok Build** 同窗口实时状态条（tmux）：上下文、配额、入/出/缓存 token、工具与待办。读本机会话文件与已有登录查配额，不另开窗口。
+**Grok Build 插件**：同窗口实时状态条（tmux）——上下文、配额、入/出/缓存 token、工具与待办。读本机会话文件与已有登录查配额，不另开窗口。
 
 ## What it shows
 
@@ -20,14 +20,16 @@ Data sources (local):
 - `summary.json` — title, effort, model
 - Grok auth → `cli-chat-proxy` billing for quota
 
-## Install once
+## Install once (plugin + HUD)
 
 ```bash
-cd /path/to/grok-build-hud
+git clone http://172.238.15.154:3000/Redredchen01/grok-hud.git
+cd grok-hud
 bash scripts/install.sh
-# or: npm run install-local
 ```
 
+One-shot: build CLI → install tmux dashboard → `grok plugin install . --trust`.
+
 ## Daily
 
 ```bash
@@ -40,7 +42,7 @@ grok-build-hud --theme auto       # follow Grok [ui].theme
 grok-hud stop                     # stop dashboard daemon
 ```
 
-## In-session slash commands (if plugin enabled)
+## In-session slash commands (plugin enabled)
 
 - `/hud` `/status` `/quota` `/preset` `/setup` `/watch` `/settings` — see `commands/`