docs: surface plugin upgrade flow

Author: Gewu Contributors

CHANGELOG.md

@@ -12,7 +12,10 @@
 
 ## 未发布
 
-暂无。
+### 新增
+
+- 将已安装用户的升级命令提升到 README 和 3 分钟上手指南
+- 明确区分远端仓库更新、Git 市场刷新和新任务重新载入三个阶段
 
 ## 1.1.0-rc.2 — 2026-07-25
 

CHANGELOG_EN.md

@@ -12,7 +12,10 @@ Gewu does not yet have a GitHub Release. The versions below describe repository
 
 ## Unreleased
 
-None.
+### Added
+
+- Promotes the upgrade command for existing users into the README and 3-minute guide
+- Separates remote repository updates, Git marketplace refresh, and new-task reload as three distinct stages
 
 ## 1.1.0-rc.2 — 2026-07-25
 

README.md

@@ -149,6 +149,16 @@ codex plugin add gewu@gewu
 
 > 目前这是由 GitHub 仓库直接提供的公开市场版本，尚未提交到 OpenAI 的通用插件目录。添加市场表示信任 `wuxie888/gewu` 这个第三方 Git 来源，不代表经过 OpenAI 目录审核。格物当前是纯 Skill 插件，不含 App、MCP Server、Hook、远程服务、账号登录或数据上传；源码、插件清单和提交历史都可在本仓库审阅。
 
+### 已经安装：更新格物
+
+GitHub 市场版本不会因为仓库出现新提交就保证立即更新本机缓存。刷新格物市场：
+
+```bash
+codex plugin marketplace upgrade gewu
+```
+
+市场刷新会重新同步已经安装的格物插件。完成后请新建一个任务，让 Agent 载入新版 Skill。不要重复运行 `codex plugin marketplace add wuxie888/gewu`；`add` 用于第一次添加市场，不是升级。
+
 ### 通用 Skill 接入
 
 1. 把 `skills/gewu/` 复制到目标 Agent 配置的 Skills 或 Instructions 目录

README_EN.md

@@ -151,6 +151,16 @@ Start a new task after installation so the agent reloads the plugin. In Codex, i
 
 > This is a public GitHub-backed marketplace build, not yet a listing in OpenAI's universal plugin directory. Adding it means trusting the third-party Git source `wuxie888/gewu`; it does not imply OpenAI directory review. Gewu is currently a Skill-only plugin with no App, MCP server, hook, remote service, account login, or data upload. Its source, manifest, and commit history are reviewable in this repository.
 
+### Already installed: update Gewu
+
+A new repository commit does not guarantee that a GitHub-backed marketplace immediately replaces the installed cache. Refresh the Gewu marketplace:
+
+```bash
+codex plugin marketplace upgrade gewu
+```
+
+Refreshing the marketplace resynchronizes the installed Gewu plugin. Start a new task afterward so the agent loads the updated Skill. Do not rerun `codex plugin marketplace add wuxie888/gewu`; `add` is for first-time marketplace setup, not upgrades.
+
 ### Generic Skill integration
 
 1. Copy `skills/gewu/` into the target agent's configured Skills or Instructions directory

docs/GETTING_STARTED.md

@@ -67,6 +67,16 @@ codex plugin add gewu@gewu
 
 发送之前，确认编辑框中已经出现 `$gewu` 或已选中的格物 Skill。仅仅得到一段像调查报告的回答，并不能证明插件已经被加载。
 
+### 已经安装过格物
+
+仓库发布新版本后，不要假设本机插件会立即自动更新。刷新 Git 市场并重新同步已安装插件：
+
+```bash
+codex plugin marketplace upgrade gewu
+```
+
+刷新后新建任务。`codex plugin marketplace add wuxie888/gewu` 只用于第一次添加市场，不是升级命令。
+
 ## 完成第一次调查
 
 复制下面这句话，把最后的链接换成你真正想调查的对象：

docs/GETTING_STARTED_EN.md

@@ -67,6 +67,16 @@ Invoke Gewu explicitly:
 
 Before sending, confirm that `$gewu` or the selected Gewu Skill appears in the composer. A response that merely looks like a research report does not prove that the plugin was loaded.
 
+### If Gewu is already installed
+
+Do not assume that a new repository release immediately updates the installed plugin. Refresh the Git marketplace and resynchronize installed plugins:
+
+```bash
+codex plugin marketplace upgrade gewu
+```
+
+Start a new task after the refresh. `codex plugin marketplace add wuxie888/gewu` is only for first-time marketplace setup, not upgrades.
+
 ## Complete your first investigation
 
 Copy this prompt and replace the final URL: