🚀 feat(kb): 升级技能项目侧对齐检查 + 升级指南与官网入口

.Knowledge/topics/kb-routing-summary.md

@@ -27,6 +27,7 @@ confidence: manual
 
 - 写法规范（软 30 字 / 硬 40 字、职责 + 用户会问的核心名词、`includeAny` 单概念词优先、落盘前模拟问句自测）以 `f2s-topic-authoring`「初筛召回规范」为准，本 topic 不复述。
 - 存量修复走 `f2s-kb-upgrade` 完整流程步骤 3a.7 / 3a.8：`kb build --fix-topics` 补占位头部 → `kb check --strict` 报 summary warning → agent 逐个 Read 正文补写语义摘要 → `kb build` 同步进 `rule.summary`。
+- `f2s-kb-upgrade` 步骤 -1 的 A 分支（包侧均为最新）**不得直接停止**：须先做项目侧对齐检查（manifest `version`/`pkgRev` 对比包 Template Version + `kb check --strict`），未对齐视同 Template 更新转完整流程；否则刚升完包的老项目会被误判「无事可做」跳过 summary 补写。
 
 ## 边界
 

README.en.md

@@ -26,7 +26,14 @@
 Flow2Spec adds a spec-driven workflow layer to AI coding agents. It creates a small, routable `.Knowledge/` knowledge base, installs agent-specific `f2s-*` skills, and keeps optional local task state separate from product knowledge. A new session can load the facts relevant to a request instead of rediscovering the repository.
 
 ```bash
-npx @double-coding/flow2spec@latest init
+# Recommended: install globally, then initialize
+# (keeps the `flow2spec` command available for kb maintenance and upgrades)
+npm install -g @double-coding/flow2spec
+flow2spec init
+
+# One-off trial without installing (always resolves the latest version):
+# npx @double-coding/flow2spec@latest init
+
 # Native DeepSeek Harness plugin:
 # https://github.com/double-coding-lab/Flow2Spec-DeepSeek-Harness
 # Project-level adapter without the plugin:

README.md

@@ -26,7 +26,14 @@
 Flow2Spec adds a spec-driven workflow layer to AI coding agents. It creates a small, routable `.Knowledge/` knowledge base, installs agent-specific `f2s-*` skills, and keeps optional local task state separate from product knowledge. A new session can load the facts relevant to a request instead of rediscovering the repository.
 
 ```bash
-npx @double-coding/flow2spec@latest init
+# Recommended: install globally, then initialize
+# (keeps the `flow2spec` command available for kb maintenance and upgrades)
+npm install -g @double-coding/flow2spec
+flow2spec init
+
+# One-off trial without installing (always resolves the latest version):
+# npx @double-coding/flow2spec@latest init
+
 # Native DeepSeek Harness plugin:
 # https://github.com/double-coding-lab/Flow2Spec-DeepSeek-Harness
 # Project-level adapter without the plugin:

README.zh-CN.md

@@ -26,7 +26,13 @@
 Flow2Spec 是给 AI 编码工具使用的 Spec-driven 工作流层。它会在项目里建立小而可路由的 `.Knowledge/` 知识库，安装面向 agent 的 `f2s-*` 技能，并把可选的本地任务状态和产品知识分开保存。新的会话可以按需求加载相关事实，而不是重新翻完整个仓库。
 
 ```bash
-npx @double-coding/flow2spec@latest init
+# 推荐：全局安装后初始化（保留 flow2spec 命令，便于后续知识库维护与升级）
+npm install -g @double-coding/flow2spec
+flow2spec init
+
+# 免安装一次性体验（始终解析最新版）：
+# npx @double-coding/flow2spec@latest init
+
 # DeepSeek Harness 原生插件：
 # https://github.com/double-coding-lab/Flow2Spec-DeepSeek-Harness
 # 未装插件时的项目级适配：

docs/Flow2Spec基础介绍.md

@@ -422,7 +422,8 @@ Flow2Spec 提供三个互补命令，按触发方式与粒度区分：
 **5 分钟快速体验**：
 
 ```Plain Text
-npx @double-coding/flow2spec@latest init
+npm install -g @double-coding/flow2spec
+flow2spec init
 
 ```
 
@@ -459,7 +460,8 @@ Flow2Spec 做的事，是把项目知识整理成可路由、可依赖、可验
 - 文档和代码开始不同步。
 
 ```Plain Text
-npx @double-coding/flow2spec@latest init
+npm install -g @double-coding/flow2spec
+flow2spec init
 ```
 
 开源地址：`https://github.com/double-coding-lab/Flow2Spec`

docs/en/Flow2Spec-Introduction.md

@@ -438,7 +438,8 @@ In short: **single Q&A → distill (auto), new module bulk import → add, perio
 **5-minute quick start**:
 
 ```Plain Text
-npx @double-coding/flow2spec@latest init
+npm install -g @double-coding/flow2spec
+flow2spec init
 
 ```
 
@@ -475,7 +476,8 @@ If your project already has these problems, try it in one repository first:
 - documentation and code have started to drift apart.
 
 ```Plain Text
-npx @double-coding/flow2spec@latest init
+npm install -g @double-coding/flow2spec
+flow2spec init
 ```
 
 Repository: `https://github.com/double-coding-lab/Flow2Spec`

docs/en/upgrade-guide.md

@@ -0,0 +1,120 @@
+# Flow2Spec Upgrade Guide (CLI 3.6.1 / Core 3.7.1 / Template 3.6.1)
+
+> Highlight of this release: **routing-summary recall anchors**. Every routing rule in `manifest-routing.json` now carries a `summary` semantic digest (synced automatically from topic frontmatter), which greatly improves knowledge-base hit rates for natural phrasings such as "where are the prototypes" or "which folder holds the flowcharts". `kb check` gains summary quality validation accordingly.
+
+## Version matrix
+
+| Dimension | Latest | Notes |
+| --- | --- | --- |
+| CLI (`@double-coding/flow2spec`) | 3.6.1 | `kb check` prints warning details |
+| Core (`@double-coding/flow2spec-core`) | 3.7.1 | summary sync engine + quality validation; upgrade-skill project-side alignment check |
+| Template Version | 3.6.1 | templates carry topic-layer changes (projectRev 3) |
+| Qoder plugin | 3.7.1 | self-built (`npm run build:qoder-plugin`), named after the Core version |
+
+---
+
+## New users (first-time setup)
+
+### Option 1: CLI (Codex / Cursor / Claude / DSH)
+
+```bash
+npm install -g @double-coding/flow2spec
+flow2spec init <codex|cursor|claude|dsh>   # multi-select, follow the prompts
+```
+
+Installing the CLI automatically brings the latest compatible Core (`^3.6.0` → 3.7.1); no separate install is needed. After init you are on the latest knowledge-base templates with summary-based first-pass recall built in — nothing extra to do.
+
+### Option 2: Qoder plugin (self-built install)
+
+The Qoder plugin marketplace hosts official plugins only; build the Flow2Spec plugin yourself and install it locally:
+
+1. Clone the repository and build the plugin package:
+
+   ```bash
+   git clone https://github.com/double-coding-lab/Flow2Spec.git
+   cd Flow2Spec && npm install && npm run build:qoder-plugin
+   # produces output/flow2spec-3.7.1.zip
+   ```
+
+2. In Qoder's plugin management, choose local install and import the zip;
+3. On first use in a project, run `flow2spec init plugin` as prompted (plugin mode: initializes only the knowledge base and config, writes no client directories).
+
+Then tell the agent things like "f2s-kb-build / f2s-kb-add" to start building the knowledge base.
+
+---
+
+## Existing users (projects with `.Knowledge`)
+
+Template 3.5.0 → 3.6.x **includes topic-layer changes** (projectRev 2 → 3), so updating the packages alone is not enough — run one knowledge-base upgrade. Three steps:
+
+### Step 1: Update the packages
+
+Check current versions and available updates:
+
+```bash
+flow2spec version
+flow2spec update --check
+```
+
+Two cases depending on your current CLI:
+
+- **CLI is already 3.6.x**: run `flow2spec update --core` to get Core 3.7.1 (inside the `^3.6.0` range); if your CLI is below 3.6.1, also run `flow2spec update --cli` (its `kb check` prints warning details, handy for watching step 2 progress).
+- **CLI below 3.6.0**: reinstall the latest:
+
+  ```bash
+  npm install -g @double-coding/flow2spec@latest
+  ```
+
+**Qoder plugin users**: pull the latest code and rebuild the plugin package (`npm run build:qoder-plugin`, producing `output/flow2spec-3.7.1.zip`), then re-import it in Qoder's plugin management; no global npm package needed.
+
+### Step 2: Knowledge-base upgrade (the key step — let the agent do it)
+
+In your project session, tell the agent:
+
+```text
+f2s-kb-upgrade
+```
+
+The agent runs the full flow. The parts relevant to this release:
+
+1. Runs `flow2spec init` to align the routing manifest and templates (**incremental — it never overwrites your accumulated business knowledge**);
+2. `kb build --fix-topics` fills in frontmatter skeletons for existing topics;
+3. **Summary rewrite (new in this release)**: `kb check --strict` lists every missing/placeholder topic summary; the agent reads each topic body, writes a one-line semantic summary per the authoring rules, then `kb build` syncs it into the routing manifest — only after this step does your existing knowledge base gain the first-pass recall boost;
+4. Writes back `projectRev` and prints an upgrade summary.
+
+No manual edits to any `.Knowledge` file are needed.
+
+### Step 3: Verify
+
+```bash
+flow2spec version          # CLI 3.6.1 / Core 3.7.1 / Template 3.6.1
+flow2spec kb check --strict   # expect: knowledge check: ok, no summary warnings
+```
+
+Then try one natural question (e.g. "where do the prototypes / requirement docs of this project live") and confirm the agent hits the right topic.
+
+---
+
+## FAQ
+
+**Q: Will the upgrade overwrite the knowledge base I already wrote?**
+No. The init run by `f2s-kb-upgrade` is incremental and only updates template-owned routing structure and rules; your business content in `stock-docs` / `req-docs` / topic bodies is untouched. `--reset-knowledge` is used only when you explicitly ask for an overwrite reset.
+
+**Q: Can I just update the packages and skip `f2s-kb-upgrade`?**
+The engine capabilities (summary sync, validation) take effect, but your existing topics have no summaries, so first-pass recall does not improve — and `kb check` will keep reporting placeholder/missing warnings. Run the upgrade soon after updating the packages.
+
+**Q: My project is still on the very old V1 layout (no `.Knowledge/manifest-routing.json` shards)?**
+V1 auto-migration has been removed from the package. First do a one-time migration with the historical `@double-coding/flow2spec@3.4.x` (or move things into the `.Knowledge` shape manually), then run `f2s-kb-upgrade` on the latest version.
+
+**Q: I told the agent `f2s-kb-upgrade` and it just replied "everything is up to date" and did nothing?**
+A known misjudgment in older skills (Template ≤ 3.6.0): they only compared "installed packages vs npm" and never checked "project knowledge base vs package templates" — an old project right after a package upgrade hits exactly this. Fixed since Template 3.6.1 (a project-side alignment check is now mandatory before stopping). If you hit it during the first upgrade of an old project, just be more explicit:
+
+```text
+f2s-kb-upgrade, force the full flow: run flow2spec init first, then kb build --fix-topics and kb check --strict, and rewrite summaries per 3a.8
+```
+
+**Q: After upgrading, git shows lots of changes under `.cursor/` and `.codex/` — is that normal?**
+Yes. Those are real updates to rule and skill bodies in the new templates (including the wholesale removal of `f2s-kb-migrate`), not empty diffs; use `git diff -w` to verify. The upgrade only touches `.Knowledge/`, the agent config roots (`.cursor/` `.codex/` etc.), `AGENTS.md`, and `flow2spec.config.json` — **never your business source code**; commit the upgrade changes separately from business changes. Also, the manifest `version` is the Template Version (3.6.1 after upgrading) and will not equal the Core version — that is expected.
+
+**Q: After upgrading, my commit is blocked by `kb check` reporting routing drift?**
+The manifest and topics are out of sync (usually after hand-editing the manifest). Ask the agent to run `flow2spec kb build` once (idempotent) and it self-heals.

docs/升级指南.md

@@ -0,0 +1,120 @@
+# Flow2Spec 升级指南（CLI 3.6.1 / Core 3.7.1 / Template 3.6.1）
+
+> 本次版本核心能力：**路由初筛 summary 召回锚**。`manifest-routing.json` 的每条路由规则新增 `summary` 语义摘要（由 topic frontmatter 自动同步），大幅提升自然问法（如「原型放在哪」「流程图在哪个目录」）的知识库命中率；`kb check` 同步新增 summary 质量校验。
+
+## 版本对照
+
+| 维度 | 最新版本 | 说明 |
+| --- | --- | --- |
+| CLI（`@double-coding/flow2spec`） | 3.6.1 | `kb check` 输出 warning 明细 |
+| Core（`@double-coding/flow2spec-core`） | 3.7.1 | summary 同步引擎 + 质量校验；升级技能项目侧对齐检查 |
+| Template Version | 3.6.1 | 模板含主题层变更（projectRev 3） |
+| Qoder 插件 | 3.7.1 | 自行构建（`npm run build:qoder-plugin`），随 Core 版本号命名 |
+
+---
+
+## 新用户（首次接入）
+
+### 方式一：CLI（Codex / Cursor / Claude / DSH）
+
+```bash
+npm install -g @double-coding/flow2spec
+flow2spec init <codex|cursor|claude|dsh>   # 可多选，按提示回答
+```
+
+安装 CLI 会自动带上兼容的最新 Core（`^3.6.0` → 3.7.1），无需单独安装。init 完成后即为最新知识库模板，天然具备 summary 初筛能力，无需额外操作。
+
+### 方式二：Qoder 插件（自行构建安装）
+
+Qoder 插件市场为官方插件，Flow2Spec 插件需自行构建后本地安装：
+
+1. 克隆仓库并构建插件包：
+
+   ```bash
+   git clone https://github.com/double-coding-lab/Flow2Spec.git
+   cd Flow2Spec && npm install && npm run build:qoder-plugin
+   # 产出 output/flow2spec-3.7.1.zip
+   ```
+
+2. 在 Qoder 插件管理中选择本地安装，导入该 zip；
+3. 首次在项目中使用时按提示执行 `flow2spec init plugin`（插件模式：仅初始化知识库与配置，不写任何客户端目录）。
+
+初始化后按需对 agent 说「f2s-kb-build / f2s-kb-add」等开始沉淀知识库。
+
+---
+
+## 老用户（已有 `.Knowledge` 项目）
+
+本次 Template 3.5.0 → 3.6.0 **包含主题层变更**（projectRev 2 → 3），因此不能只更新包，需要走一次知识库升级。分三步：
+
+### 第 1 步：更新包
+
+先看当前版本与可用更新：
+
+```bash
+flow2spec version
+flow2spec update --check
+```
+
+按当前 CLI 版本分两种情况：
+
+- **CLI 已是 3.6.x**：执行 `flow2spec update --core` 更新 Core 到 3.7.1（在 `^3.6.0` 兼容范围内）；若 CLI 低于 3.6.1，建议再 `flow2spec update --cli` 升到 3.6.1（`kb check` 可打印 warning 明细，便于第 2 步观察补写进度）。
+- **CLI 低于 3.6.0**：直接重装最新：
+
+  ```bash
+  npm install -g @double-coding/flow2spec@latest
+  ```
+
+**Qoder 插件用户**：拉取最新代码重新构建插件包（`npm run build:qoder-plugin`，产出 `output/flow2spec-3.7.1.zip`），在 Qoder 插件管理中重新导入即可，无需操作 npm 全局包。
+
+### 第 2 步：知识库升级（关键，交给 agent 做）
+
+在项目会话中对 agent 说：
+
+```text
+f2s-kb-upgrade
+```
+
+agent 会代跑完整流程，其中与本次版本直接相关的是：
+
+1. 代跑 `flow2spec init` 对齐路由清单与模板（**增量落盘，不覆盖你已沉淀的业务知识**）；
+2. `kb build --fix-topics` 为存量 topic 补齐 frontmatter 骨架；
+3. **summary 补写（本版新增）**：`kb check --strict` 会列出所有缺失 / 占位的 topic 摘要，agent 逐个阅读 topic 正文、按创作规范补写一句话语义摘要，再 `kb build` 同步进路由清单——这一步完成后，你的存量知识库才真正获得初筛召回增强；
+4. 回写 `projectRev`，输出升级摘要。
+
+全程无需手动改任何 `.Knowledge` 文件。
+
+### 第 3 步：验证
+
+```bash
+flow2spec version          # CLI 3.6.1 / Core 3.7.1 / Template 3.6.1
+flow2spec kb check --strict   # 期望：knowledge check: ok，无 summary warning
+```
+
+再用一句自然问法试试路由（例如问「这个项目的原型 / 需求文档放在哪」），确认 agent 能命中对应 topic。
+
+---
+
+## 常见问题
+
+**Q：升级会覆盖我已经写好的知识库吗？**
+不会。`f2s-kb-upgrade` 代跑的 init 是增量对齐，只更新模板承载的路由结构与规则；`stock-docs` / `req-docs` / topic 正文的业务内容不受影响。只有明确要求「覆盖重置」时才会带 `--reset-knowledge`。
+
+**Q：不跑 `f2s-kb-upgrade`，只更新包行不行？**
+引擎能力（summary 同步、校验）会生效，但你的存量 topic 没有摘要，初筛命中率不会提升；且首次 `kb check` 会持续报占位 / 缺失 warning。建议升级包后尽快跑一次。
+
+**Q：我的项目还是很老的 V1 布局（无 `.Knowledge/manifest-routing.json` 分片结构）怎么办？**
+V1 自动迁移已随包移除。先用历史版本 `@double-coding/flow2spec@3.4.x` 完成一次性迁移（或手动迁入 `.Knowledge` 形态），再回到最新版本跑 `f2s-kb-upgrade`。
+
+**Q：对 agent 说 `f2s-kb-upgrade`，它回复「版本均为最新」就停了，什么都没做？**
+这是旧版技能（Template ≤ 3.6.0）的已知误判：它只比对了「本机包 vs npm」，没检查「项目知识库 vs 包模板」——刚升完包的老项目恰好命中。Template 3.6.1 起已修复（停止前强制项目侧对齐检查）。老项目首次升级时若遇到，说得更明确即可绕过：
+
+```text
+f2s-kb-upgrade，强制走完整流程：先代跑 flow2spec init，再 kb build --fix-topics 和 kb check --strict，按 3a.8 补写 summary
+```
+
+**Q：升级后 git 里 `.cursor/`、`.codex/` 出现大量文件变化，正常吗？**
+正常。这些是新模板的规则与技能正文真实更新（含已移除的 `f2s-kb-migrate` 整文件删除），不是空改动；可用 `git diff -w` 验证实质变更占比。升级只会动 `.Knowledge/`、各 agent 配置根（`.cursor/` `.codex/` 等）、`AGENTS.md`、`flow2spec.config.json`，**不碰业务源码**；建议把升级改动与业务改动分开提交。另外 manifest 的 `version` 是 Template Version（升级后为 3.6.1），不会等于 Core 版本号，属正常现象。
+
+**Q：升级后提交代码被 `kb check` 拦住报 routing drift？**
+说明 manifest 与 topic 不同步（常见于手改过 manifest）。让 agent 跑一次 `flow2spec kb build`（幂等）即可自愈。

packages/cli/README.md

@@ -26,7 +26,14 @@
 Flow2Spec adds a spec-driven workflow layer to AI coding agents. It creates a small, routable `.Knowledge/` knowledge base, installs agent-specific `f2s-*` skills, and keeps optional local task state separate from product knowledge. A new session can load the facts relevant to a request instead of rediscovering the repository.
 
 ```bash
-npx @double-coding/flow2spec@latest init
+# Recommended: install globally, then initialize
+# (keeps the `flow2spec` command available for kb maintenance and upgrades)
+npm install -g @double-coding/flow2spec
+flow2spec init
+
+# One-off trial without installing (always resolves the latest version):
+# npx @double-coding/flow2spec@latest init
+
 # Native DeepSeek Harness plugin:
 # https://github.com/double-coding-lab/Flow2Spec-DeepSeek-Harness
 # Project-level adapter without the plugin:

packages/core/README.md

@@ -27,4 +27,4 @@ const versions = getVersions();
 - `update.check()` 复用 `.Knowledge/update-check.json` 的每日缓存，分别返回 Core 与 Template 更新状态；网络不可用时返回 `unavailable`，不会阻断宿主。
 - `capabilities.json` 的 `protocolVersion` 用于插件启动时执行能力兼容校验。
 
-包通过 `index.d.ts` 导出完整公共契约类型。普通 CLI 用户继续使用 `npx @double-coding/flow2spec init`，无需直接调用这些 API。
+包通过 `index.d.ts` 导出完整公共契约类型。普通 CLI 用户继续使用 `flow2spec init`（全局安装 `@double-coding/flow2spec` 后），无需直接调用这些 API。

packages/core/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@double-coding/flow2spec-core",
-  "version": "3.7.0",
-  "templateVersion": "3.6.0",
+  "version": "3.7.1",
+  "templateVersion": "3.6.1",
   "description": "Flow2Spec Core APIs, knowledge engine, project initialization and shared resources",
   "homepage": "https://github.com/double-coding-lab/Flow2Spec#readme",
   "repository": {

packages/core/templates/en-US/knowledge/manifest-routing.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.6.0",
+  "version": "3.6.1",
   "projectRev": 3,
   "knowledgeRoot": ".Knowledge",
   "matcherKey": "matcherId",