feat: v0.2.0 — 技能解除索引门槛，主动检查并提示初始化

本插件存在的意义是让智能体自己发现 CodeGraph、主动引导用户建立索引，
而不是只在已索引仓库里被动待命。v0.1.x 把这个目的堵死了：

- SKILL.md frontmatter 以「仓库根有 .codegraph/ 目录时使用」作为激活门槛，
  却又在同一句结尾写「不存在时引导用户运行 /codegraph-init」——该分支永远
  执行不到，因为技能只在已索引时才激活。
- SessionStart 钩子同样在未索引时静默（is_indexed 为假即 return 0）。
- 结果：未索引仓库里两条通路都不触发，智能体完全不知道 CodeGraph 存在。

0.2.0 行为契约：
  已索引 → 用 codegraph_explore 回答，不退回 Read + grep
  未索引 → 主动告知用户并征得同意，同意后跑 codegraph init

钩子保持静默是被硬约束推导的：注入块须 verbatim 来自上游，而上游原文即
"If there is no .codegraph/ directory, skip CodeGraph entirely"。钩子若在
未索引时发「你该索引」的提示，等于自我否定刚注入的块，违反提示词同步纪律。

补齐 init 与 install 的边界（判据是作用域与可逆性，不是谁做决定）：
  init    → 项目内写 .codegraph/，可重建 → 主动检查+主动提示，可代跑
  install → 改用户全局 MCP 配置，跨项目 → 不代劳，仅引导

新增 TestSkillFrontmatter::test_description_not_gated_on_index_presence
回归守卫（已做红→绿双向验证，防止门槛被写回）。

验证：tests 35 passed + 71 subtests、scripts/tests 14 passed、
validate_portable_plugin PASS、sync-marketplaces Validated。

Author: loong10k

.agents/plugins/marketplace.json

@@ -9,20 +9,20 @@
       "source": {
         "source": "url",
         "url": "https://github.com/full-stack-plugins/codegraph-plugin.git",
-        "ref": "v0.1.7"
+        "ref": "v0.2.0"
       },
       "policy": {
         "installation": "AVAILABLE",
         "authentication": "ON_USE"
       },
       "category": "Developer Tools",
-      "version": "0.1.7",
+      "version": "0.2.0",
       "description": "Inject the official CodeGraph prompt at session start (only when a `.codegraph/` directory exists) and expose 21 of codegraph's 23 CLI commands as slash commands for Codex/ZCode/Kimi/Claude Code. Pure Python stdlib.",
-      "icon": "https://cdn.jsdelivr.net/gh/full-stack-plugins/codegraph-plugin@v0.1.7/assets/official-logo.png",
+      "icon": "https://cdn.jsdelivr.net/gh/full-stack-plugins/codegraph-plugin@v0.2.0/assets/official-logo.png",
       "interface": {
         "displayName": "CodeGraph",
         "shortDescription": "Discoverable codegraph — official prompt + 21 CLI commands",
-        "logo": "https://cdn.jsdelivr.net/gh/full-stack-plugins/codegraph-plugin@v0.1.7/assets/official-logo.png"
+        "logo": "https://cdn.jsdelivr.net/gh/full-stack-plugins/codegraph-plugin@v0.2.0/assets/official-logo.png"
       }
     }
   ]

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codegraph",
-  "version": "0.1.7+codex.20261009",
+  "version": "0.2.0+codex.20261009",
   "description": "Inject the official CodeGraph prompt at session start (only when a `.codegraph/` directory exists) and expose 21 of codegraph's 23 CLI commands as slash commands for Codex/ZCode/Kimi/Claude Code. Pure Python stdlib.",
   "author": {
     "name": "Full Stack Plugins",

.zcode-plugin/plugin.json

@@ -5,7 +5,7 @@
     "en": "CodeGraph",
     "zh-CN": "CodeGraph 代码智能"
   },
-  "version": "0.1.7",
+  "version": "0.2.0",
   "description": "Inject the official CodeGraph prompt at session start (only when a `.codegraph/` directory exists) and expose 21 of codegraph's 23 CLI commands as slash commands for Codex/ZCode/Kimi/Claude Code. Pure Python stdlib.",
   "description_i18n": {
     "en": "At SessionStart, when a `.codegraph/` directory exists, this plugin writes the official CodeGraph prompt block to `<cwd>/.claude/CLAUDE.md` or `<cwd>/AGENTS.md`, and injects the same block as SessionStart additionalContext. Exposes 21 of codegraph's 23 CLI commands as slash commands.",

AGENTS.md

@@ -12,7 +12,7 @@
 
 ## 版本
 
-- 当前: v0.1.7
+- 当前: v0.2.0
 - 同步自 codegraph v1.6.0 的 `instructions-template.ts`（0.1.7 重新核对：与上游逐字节一致，805 bytes，无文本漂移）
 - Codex 后缀: `<version>+codex.YYYYMMDD`
 
@@ -42,11 +42,30 @@ codegraph v1.6.0 共 23 个子命令，本插件以 21 个 slash 命令覆盖，
 
 `codegraph context`（v1.6.0 新增）在 0.1.7 补齐——v0.1.0 时期的「覆盖全部可见命令」表述在 v1.5.0 时成立，v1.6.0 加入 `context` 后即失效。
 
+## 发现性是本插件的目的（0.2.0 起）
+
+本插件存在的意义是**让智能体自己发现 CodeGraph 并主动引导用户建立索引**，不是只在已索引仓库里被动待命。因此：
+
+- `codegraph-helper` 的 frontmatter `description` **不得**以「仓库根有 `.codegraph/` 目录时使用」作为激活门槛。若这样写，未索引仓库里技能根本不触发，其「未索引则提示用户」分支永远执行不到——这是 v0.1.x 的一个真实缺陷，0.2.0 已解除。
+- 技能的行为契约：**先检查 → 已索引就用 CodeGraph 回答 / 未索引就主动提示并征得同意 → 同意后跑 `codegraph init`**。不得因为「索引是用户决策」就当没看见。
+- **SessionStart 钩子保持静默**：上游注入块原文写着 "If there is no `.codegraph/` directory, skip CodeGraph entirely — indexing is the user's decision."（见 `prompt.CODEGRAPH_INSTRUCTIONS_BLOCK`）。钩子若在未索引时发「你该去索引」的提示，等于自我否定刚 verbatim 注入的块，违反上方 L6。未索引场景由技能的「检查 + 提示」通路兜底。
+
+## `init` 与 `install` 的边界
+
+两者都是用户的决策，但性质不同，不可混为一谈：
+
+| 命令 | 副作用 | 插件立场 |
+|---|---|---|
+| `codegraph init` | 在仓库根写 `.codegraph/`，项目内、可重建 | **主动检查 + 主动提示**；征得同意后可代跑 |
+| `codegraph install` | 改用户全局 MCP 配置，跨项目、影响宿主 | **不代劳**，仅通过 `/codegraph-install` 引导 |
+
+判断标准是副作用的作用域与可逆性，不是「谁做决定」。
+
 ## 不做的事
 
 - 不暴露 `codegraph prompt-hook` / `codegraph serve --mcp`（codegraph 自家隐藏命令），也不暴露 `help` / `ui` / `web`
 - 不挂 PreToolUse/PostToolUse/UserPromptSubmit/Stop 钩子（避免与 codeguard-plugin 抢触发器）
-- 不自动跑 `codegraph install`（那是用户的一次性 wiring 决策，插件不能越权）
+- 不自动跑 `codegraph install`（MCP wiring 改的是用户全局配置，作用域跨项目，插件不能越权——与 `init` 的处理见上节）
 - 不读取或上传任何源代码到外部
 
 <!-- partme-agent-plugin-policy:v1 -->

README.md

@@ -21,13 +21,13 @@ Three things, and **only** these three:
    - The current session, via `SessionStart.additionalContext` JSON output.
    - `<cwd>/.claude/CLAUDE.md` if it exists; else `<cwd>/AGENTS.md`. Uses atomic, marker-fenced section replacement — byte-equal content is a no-op, so this is safe to run alongside `codegraph install`.
 2. **Exposes 21 of codegraph's 23 CLI commands** as slash commands in two formats: JSON (`commands/*.json`, declared in `kimi.plugin.json`) and Markdown (`kimi-commands/*.md`), including the four hidden-but-useful maintenance commands (`daemon`, `unlock`, `version`, `telemetry`).
-3. **Registers a discovery skill** (`codegraph-helper`) that conditions the agent to use the right CodeGraph MCP tool for the task at hand.
+3. **Registers a discovery skill** (`codegraph-helper`) that makes the agent **check whether the repo is indexed and, if not, proactively offer to index it**. The skill activates on code-structure questions *whether or not* `.codegraph/` exists: it checks first, then either answers via CodeGraph or tells the user 「this repo isn't indexed yet — want me to index it?」 and runs `codegraph init` once the user agrees.
 
 ## What this plugin does **not** do
 
 - It does **not** modify or replace the `codegraph` CLI. The upstream `colbymchenry/codegraph` (MIT) is the source of truth.
 - It does **not** install the `codegraph` CLI. Users run `npm i -g @colbymchenry/codegraph` (or the install script) themselves; the plugin just exposes `/codegraph-install` as a guided wrapper around `codegraph install` for MCP wiring.
-- It does **not** auto-run `codegraph init`. Indexing is the user's decision. The plugin only activates when `.codegraph/` already exists.
+- It does **not** run `codegraph init` **without asking**. Indexing writes a `.codegraph/` directory, so the agent must get consent first — but it *does* detect the missing index and prompt for it automatically, because that discovery is the whole point of this plugin. (The SessionStart hook itself stays silent in un-indexed repos, matching the upstream prompt's own "skip CodeGraph entirely" wording.)
 - It does **not** hook `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, or `Stop` — only `SessionStart`. This avoids collisions with codeguard-plugin and other plugins that own those events.
 
 ## Requirements

README.zh-CN.md

@@ -25,13 +25,13 @@
    - 当前会话，通过 `SessionStart.additionalContext` JSON 输出；
    - `<cwd>/.claude/CLAUDE.md`（如果存在）；否则 `<cwd>/AGENTS.md`。使用标记区间原子替换——字节级幂等，所以与 `codegraph install` 并存是安全的。
 2. **暴露 codegraph 23 个 CLI 命令中的 21 个**为 slash 命令，JSON（`commands/*.json`，由 `kimi.plugin.json` 声明）与 Markdown（`kimi-commands/*.md`）双格式，包括 4 个隐藏但实用的维护命令（`daemon` / `unlock` / `version` / `telemetry`）。
-3. **注册发现型技能**（`codegraph-helper`），让智能体根据用户问题选择合适的 CodeGraph MCP 工具。
+3. **注册发现型技能**（`codegraph-helper`），让智能体**主动检查仓库是否已索引，未索引则主动提示可以索引**。该技能在代码结构类问题上激活，**不论 `.codegraph/` 是否存在**：先检查，已索引就用 CodeGraph 回答；未索引就告诉用户「此仓库尚未索引，要现在索引吗」，用户同意后运行 `codegraph init`。
 
 ## 本插件**不**做什么
 
 - **不**修改或替换 `codegraph` CLI。上游 [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph)（MIT）是唯一权威。
 - **不**安装 `codegraph` CLI。用户自行 `npm i -g @colbymchenry/codegraph`（或 install.sh）；本插件仅提供 `/codegraph-install` 作为 `codegraph install` 的引导包装。
-- **不**自动跑 `codegraph init`。索引是用户的决策，本插件只在 `.codegraph/` 已存在时激活。
+- **不**在未征得同意前跑 `codegraph init`。索引会在仓库根写 `.codegraph/`，必须先拿到用户同意——但智能体**会主动检测缺失的索引并自动提示**，因为这正是本插件存在的意义。（SessionStart 钩子本身在未索引仓库仍保持静默，与上游提示词自带的 "skip CodeGraph entirely" 措辞一致。）
 - **不**挂 `PreToolUse` / `PostToolUse` / `UserPromptSubmit` / `Stop` 钩子——只挂 `SessionStart`。避免和 codeguard-plugin 等其他插件抢触发器。
 
 ## 前置条件

RELEASE-NOTES.md

@@ -13,6 +13,7 @@
 
 | Version | Date | Changes |
 |---|---|---|
+| 0.2.0 | 2026-10-09 | **Behaviour change** — the `codegraph-helper` skill no longer treats an existing index as its activation gate; it now activates on code-structure questions in any repo, checks for `.codegraph/` itself, and proactively offers to index when absent (running `codegraph init` only after user consent). Documented the `init` vs `install` boundary. Regression guard added |
 | 0.1.7 | 2026-10-09 | Fix MCP tool claims to match upstream `DEFAULT_MCP_TOOLS` (only `codegraph_explore` is listed to agents by default); drop the fabricated `codegraph affected` MCP alternative; add `/codegraph-context` (codegraph 1.6.0 command) for 21/23 coverage; re-sync prompt text against codegraph v1.6.0; fix `./codegraph/` path typo; align AGENTS.md wording with actual marketplace schema; add regression guard for non-default MCP tool claims |
 | 0.1.5 | 2026-09-23 | Fix format-attribution claims (JSON/Markdown neutral wording, ecosystem-verified); rename `KIMI_COMMANDS` test variable; document command-directory convention in AGENTS.md |
 | 0.1.4 | 2026-09-23 | Add bump-plugin CLI tests (untested-hotspot closure); description parity check for all 40 command files; README heading-structure parity test; marker-containment guard in `replace_or_append_marked_section` |

RELEASE-NOTES.zh-CN.md

@@ -11,6 +11,7 @@
 
 | Version | Date | Changes |
 |---|---|---|
+| 0.2.0 | 2026-10-09 | **行为变更** — `codegraph-helper` 技能不再把「已建立索引」当作激活门槛；改为在任意仓库的代码结构类问题上激活，自行检查 `.codegraph/`，未索引时主动提示并征得同意后执行 `codegraph init`。补齐 `init` 与 `install` 的边界说明。新增回归守卫 |
 | 0.1.7 | 2026-10-09 | 修正 MCP 工具声明以对齐上游 `DEFAULT_MCP_TOOLS`（默认只向 agent 列出 `codegraph_explore`）；删除捏造的 `codegraph affected` MCP 替代工具；新增 `/codegraph-context`（codegraph 1.6.0 命令）使覆盖达 21/23；提示词文本按 codegraph v1.6.0 重新核对；修复 `./codegraph/` 路径笔误；AGENTS.md 表述对齐市场仓真实 schema；新增非默认 MCP 工具声明回归守卫 |
 | 0.1.5 | 2026-09-23 | 修正格式归属表述（JSON/Markdown 中性措辞，生态对照验证）；`KIMI_COMMANDS` 测试变量改中性名；AGENTS.md 补命令目录约定说明 |
 | 0.1.4 | 2026-09-23 | 新增 bump-plugin CLI 测试（热点零测试闭环）；40 个命令文件 description 双侧检查；README 标题层级 parity 测试；`replace_or_append_marked_section` 标记包含校验 |

docs/codegraph-plugin-design.md

@@ -16,6 +16,28 @@ A plugin that activates on SessionStart ensures **all three** audiences get the
 - `additionalContext` injection reaches the main agent's runtime context.
 - Both audiences get the same byte-equal text.
 
+## 1b. Why does the skill check for an index instead of assuming one?
+
+**Question.** Should `codegraph-helper` just assume the repo is indexed and use CodeGraph?
+
+**Answer.** No — and in v0.1.x it actually made that assumption structurally. The skill's frontmatter read *"仓库根有 `.codegraph/` 目录时使用"*, which made index presence the **activation gate**. The same description then ended with *「`.codegraph/` 不存在时引导用户运行 `/codegraph-init`」* — a branch that could never execute, because the skill only activated when it was already indexed. The SessionStart hook was silent for the same reason (`if not is_indexed(cwd): return 0`).
+
+Net effect: in an un-indexed repo, **neither** path fired. The agent got no signal that CodeGraph existed, so "discoverability" reduced to discoverability-among-those-who-already-indexed — the one audience that needed it least.
+
+**0.2.0 contract.** The skill activates on code-structure questions **regardless of index state**, then branches:
+
+| `.codegraph/` | Agent behavior |
+|---|---|
+| present | Answer via `codegraph_explore` (or the CLI table). Never fall back to Read + grep. |
+| absent | Tell the user the repo isn't indexed, offer to index, run `codegraph init` **only after they agree**. |
+
+**Why the hook still stays silent when un-indexed.** The injected block must be verbatim from upstream, and upstream's own text says *"If there is no `.codegraph/` directory, skip CodeGraph entirely — indexing is the user's decision."* Emitting an "you should index this" hint from the hook would contradict the block it just injected verbatim, violating the plugin's own prompt-sync discipline. The skill's check-and-prompt path covers that case instead.
+
+**`init` vs `install`.** Both are "the user's decision", but the plugin treats them differently — and the discriminator is *scope and reversibility*, not *who decides*:
+
+- `codegraph init` → writes `.codegraph/` inside the project, rebuildable → **proactive check + proactive prompt**, may run it with consent.
+- `codegraph install` → rewrites the user's global MCP config, cross-project, affects the host itself → **never runs it for the user**, only guides via `/codegraph-install`.
+
 ## 2. Why inject at SessionStart, not on every prompt?
 
 **Question.** UserPromptSubmit fires every turn — wouldn't that be more reliable?

kimi.plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codegraph",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "description": "Inject the official CodeGraph prompt at session start (only when a `.codegraph/` directory exists) and expose 21 of codegraph's 23 CLI commands as slash commands for Codex/ZCode/Kimi/Claude Code. Pure Python stdlib.",
   "author": {
     "name": "Full Stack Plugins",