feat: server-beacon skill-update path for non-Bash clients

.github/workflows/protocol-validate.yml

@@ -0,0 +1,84 @@
+name: protocol-validate
+
+# Validates that every example fixture under protocol/ conforms to
+# skill-meta-v1.schema.json. Catches the case where someone updates the schema
+# but forgets to update the fixtures (or vice versa). When @agentkey/mcp
+# eventually ships its vendored copy of the same schema, a second job here will
+# diff against it to detect drift in the other direction.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'protocol/**'
+      - '.github/workflows/protocol-validate.yml'
+  pull_request:
+    paths:
+      - 'protocol/**'
+      - '.github/workflows/protocol-validate.yml'
+
+jobs:
+  validate-fixtures:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Validate every example fixture against the schema
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          fixtures=(protocol/example-*.json)
+          if [ ${#fixtures[@]} -eq 0 ]; then
+            echo "::error::no fixtures found under protocol/example-*.json"
+            exit 1
+          fi
+          for f in "${fixtures[@]}"; do
+            echo "=== $f ==="
+            npx -y ajv-cli@5 validate \
+              --spec=draft2020 \
+              -s protocol/skill-meta-v1.schema.json \
+              -d "$f"
+          done
+
+      - name: Schema must reject known bad payloads (regression guard)
+        run: |
+          set -euo pipefail
+          tmp=$(mktemp -d)
+          # protocol_version must be 1
+          echo '{"protocol_version":2,"skill_version_latest":"1.0.0","client_detected":"claude","update_doc_url":"https://x"}' > "$tmp/bad-v2.json"
+          # update_command requires update_command_kind (dependentRequired)
+          echo '{"protocol_version":1,"skill_version_latest":"1.0.0","client_detected":"claude","update_doc_url":"https://x","update_command":"echo hi"}' > "$tmp/bad-no-kind.json"
+          # version string must not have a 'v' prefix
+          echo '{"protocol_version":1,"skill_version_latest":"v1.0.0","client_detected":"claude","update_doc_url":"https://x"}' > "$tmp/bad-vprefix.json"
+          # client_detected must be lowercase short identifier
+          echo '{"protocol_version":1,"skill_version_latest":"1.0.0","client_detected":"Claude Desktop","update_doc_url":"https://x"}' > "$tmp/bad-caps.json"
+
+          fail=0
+          for f in "$tmp"/bad-*.json; do
+            if npx -y ajv-cli@5 validate --spec=draft2020 -s protocol/skill-meta-v1.schema.json -d "$f" >/dev/null 2>&1; then
+              echo "::error::$f should have been rejected by the schema but wasn't"
+              fail=1
+            else
+              echo "✓ correctly rejected $(basename "$f")"
+            fi
+          done
+          exit $fail
+
+  spec-cross-references:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Spec doc references all fixtures
+        run: |
+          set -euo pipefail
+          # Every fixture file should be mentioned in the spec's "See also" block,
+          # so adding a new fixture without doc-cross-referencing it fails CI.
+          missing=0
+          for f in protocol/example-*.json; do
+            base=$(basename "$f")
+            if ! grep -q "$base" protocol/skill-meta-v1.md; then
+              echo "::error file=protocol/skill-meta-v1.md::fixture $base is not referenced in the spec"
+              missing=1
+            fi
+          done
+          exit $missing

README.md

@@ -144,13 +144,38 @@ Just top up. No auto-renewal, no hidden charges.
 <details>
 <summary><b>How do I update?</b></summary>
 
-**You don't have to — updates are automatic by default.** Your MCP config uses `npx -y @agentkey/mcp`, which re-resolves to the latest published version every time your agent restarts. In Claude Code plugin mode, AgentKey also checks GitHub Releases at runtime and applies a silent in-place update, notifying you:
+There are two pieces and they update differently:
 
-```
-Claude: AgentKey Skill updated to v1.1.0.
+- **MCP server** (`@agentkey/mcp` npm package): always up to date. Your MCP config runs it as `npx -y @agentkey/mcp`, which re-resolves to the latest published version every time your agent restarts. You never have to touch this.
+
+- **Skill files** (`SKILL.md` + helpers): how this updates depends on your client.
+
+### Claude Code
+
+Updates are automatic. On the first call of a session the skill runs a silent version check; if a new release is available it prompts you to upgrade and (with your consent) runs `npx skills update -g agentkey`.
+
+### Claude Desktop, Cursor, and other clients without an inline Bash tool
+
+The skill cannot run the inline check itself, but starting in v1.4.0 the **MCP server publishes the latest skill version via a dedicated metadata tool (`agentkey_skill_meta`)**. Your agent calls it once per session, compares against this skill's own version, and prompts you to upgrade with the exact command for your client. See [protocol/skill-meta-v1.md](./protocol/skill-meta-v1.md) for the protocol details.
+
+**One-time bootstrap on Desktop:** if you're stuck on a pre-1.4.0 skill in Claude Desktop, the metadata tool exists but your skill rule doesn't know how to read it. Bring yourself current once with:
+
+```bash
+# Replace <UUID1>/<UUID2> with the actual session folder under skills-plugin
+# (usually there's just one; pick the one that contains skills/agentkey/SKILL.md)
+DESKTOP_BASE="$HOME/Library/Application Support/Claude/local-agent-mode-sessions/skills-plugin"
+LATEST_REPO_ZIP=$(mktemp -d)/agentkey.tar.gz
+curl -fsSL https://github.com/chainbase-labs/agentkey/archive/refs/heads/main.tar.gz -o "$LATEST_REPO_ZIP"
+tar -xzf "$LATEST_REPO_ZIP" -C "$(dirname "$LATEST_REPO_ZIP")"
+find "$DESKTOP_BASE" -type d -path "*/skills/agentkey" 2>/dev/null | while read -r dst; do
+  cp -R "$(dirname "$LATEST_REPO_ZIP")"/agentkey-main/skills/agentkey/. "$dst/"
+done
+# Then fully quit and restart Claude Desktop.
 ```
 
-**If you'd rather force it manually:**
+After this one bootstrap, future versions will be discovered automatically via the metadata tool.
+
+### Force manual update (any client)
 
 ```bash
 # Refresh the skill content
@@ -160,6 +185,8 @@ npx skills update agentkey
 npx skills add chainbase-labs/agentkey@v1.0.0
 ```
 
+Note: `npx skills update` writes to `~/.agents/skills/agentkey` and `~/.claude/skills/agentkey`, which is where Claude Code reads from. **Claude Desktop reads from its own sandbox path** and is not touched by `npx skills update` — use the Desktop bootstrap command above for Desktop.
+
 Re-run `npx -y @agentkey/mcp --auth-login` only when you want to rotate your API key.
 
 </details>

docs/README_zh.md

@@ -144,13 +144,38 @@ Claude 与 ChatGPT 的原生联网与平台覆盖有限，往往触达不到推
 <details>
 <summary><b>怎么更新？</b></summary>
 
-**默认不用你管，AgentKey 会自己更新。** 你的 MCP 配置使用的是 `npx -y @agentkey/mcp`，每次 Agent 重启都会自动解析到最新发布版本。Claude Code 插件模式下还会在运行时自动检查 GitHub Release，发现新版本就静默更新并提示：
+AgentKey 有两部分，更新方式不同：
 
-```
-Claude: AgentKey Skill updated to v1.1.0.
+- **MCP server**（npm 包 `@agentkey/mcp`）：永远自动最新。你的 MCP 配置写的是 `npx -y @agentkey/mcp`，每次 Agent 重启都会重新解析到最新发布版。这部分完全不用你管。
+
+- **Skill 文件**（`SKILL.md` 加辅助脚本）：升级方式取决于你用的 client。
+
+### Claude Code
+
+完全自动。每次会话第一次调用 skill 时会静默跑版本检查；发现新版本会提示你升级，得到你确认后跑 `npx skills update -g agentkey`。
+
+### Claude Desktop / Cursor 等没有 inline Bash 工具的 client
+
+Skill 自己跑不了 inline 检查，但**从 v1.4.0 起 MCP server 通过专用 metadata tool（`agentkey_skill_meta`）发布最新 skill 版本号**。Agent 在每个会话里调一次，对比本地 skill 版本，发现差异就用你 client 对应的精确命令提示你升级。协议细节见 [protocol/skill-meta-v1.md](../protocol/skill-meta-v1.md)。
+
+**Desktop 一次性破冰升级**：如果你 Desktop 里的 skill 还停在 1.4.0 之前，metadata tool 存在但旧 skill 不懂怎么读。先手动同步一次到最新版：
+
+```bash
+# 把 <UUID1>/<UUID2> 替换成 skills-plugin 下实际的 session 目录
+# （通常就一个，找包含 skills/agentkey/SKILL.md 的那个）
+DESKTOP_BASE="$HOME/Library/Application Support/Claude/local-agent-mode-sessions/skills-plugin"
+LATEST_REPO_ZIP=$(mktemp -d)/agentkey.tar.gz
+curl -fsSL https://github.com/chainbase-labs/agentkey/archive/refs/heads/main.tar.gz -o "$LATEST_REPO_ZIP"
+tar -xzf "$LATEST_REPO_ZIP" -C "$(dirname "$LATEST_REPO_ZIP")"
+find "$DESKTOP_BASE" -type d -path "*/skills/agentkey" 2>/dev/null | while read -r dst; do
+  cp -R "$(dirname "$LATEST_REPO_ZIP")"/agentkey-main/skills/agentkey/. "$dst/"
+done
+# 然后完全退出并重启 Claude Desktop。
 ```
 
-**如果你想强制手动更新：**
+破冰之后，后续每次新版都会通过 metadata tool 自动告知，无需再手动操作。
+
+### 任意 client：强制手动更新
 
 ```bash
 # 拉最新版的 Skill 内容
@@ -160,6 +185,8 @@ npx skills update agentkey
 npx skills add chainbase-labs/agentkey@v1.0.0
 ```
 
+注意：`npx skills update` 只写 `~/.agents/skills/agentkey` 和 `~/.claude/skills/agentkey` 这两个目录，是 Claude Code 读取的位置。**Claude Desktop 读的是自己的 sandbox 路径**，`npx skills update` 碰不到——Desktop 升级要用上面的破冰命令。
+
 只有在需要换 API Key 时才需要再跑一次 `npx -y @agentkey/mcp --auth-login`。
 
 </details>