@itradingai/aiwiki 0.2.15 → 0.2.18

package/docs/POSITIONING_CONTEXT_COMPILER_PLAN.md

@@ -0,0 +1,347 @@
+# AIWiki 定位调整与产品方案
+
+本文基于 `20260607-aiwiki定位.md` 的判断，并结合当前 AIWiki 仓库现状整理。结论是：文档大方向可取，但不能把 AIWiki 改成重学习、重记忆、重人工复习的 Knowledge MEMO。AIWiki 更适合继续做 Agent-first 本地上下文编译器。
+
+## 一句话定位
+
+AIWiki 不是替代搜索，也不是替你读书，而是把你真正需要反复调用的资料、判断和输出，编译成 AI 能查询、能引用、能检查、能继续使用的本地知识资产。
+
+更锋利的对外表达：
+
+> 公开知识交给搜索。
+> 私有判断、项目经验、输出风格、证据链，交给 AIWiki。
+
+## 建议取舍判断
+
+| 文档建议 | 判断 | 原因 | 落地优先级 |
+| --- | --- | --- | --- |
+| 不把 AIWiki 宣传成普通个人知识库或资料索引 | 可取 | 当前 README 已强调 Agent-first 和本地 LLM-wiki 后端，但还可以更明确地区分搜索、收藏夹和上下文编译器 | P0 |
+| 保留 Markdown Wiki 形态 | 可取 | AIWiki 面向人和 Agent 协作，Markdown 的可读、可 diff、可回滚、可被 Agent 编辑是核心优势 | P0 |
+| 强化个人判断层 | 强烈可取 | 当前 payload 已有 `source_role=processing`，但产品心智和目录/命令输出还没有把 personal insight 变成一等资产 | P0 |
+| 强化输出资产层 | 强烈可取 | 当前已有 `source_role=output` 和 `represents_user_view=true` 边界，这是 AIWiki 最有差异化的一层 | P0 |
+| `context` 从资料检索升级为任务上下文包 | 强烈可取 | 当前 `context` 已是 JSON 结构，适合加 `mode` 和按任务分组的结果，不需要推倒重做 | P0 |
+| `query` 输出按资料类型分组 | 可取 | 这是低成本心智升级：从“搜索结果”变成“知识资产调度” | P1 |
+| `lint` 从结构检查升级为知识质量检查 | 可取 | 当前 lint 已有元数据边界、fallback、grounding 检查，可继续加入 insight/output/evidence 使用关系检查 | P1 |
+| `next` 从命令导航升级为加工建议 | 可取 | 适合帮助用户把资料推进到 insight、output、topic 或 review，而不是只提示下一条 CLI 命令 | P1 |
+| 新增 Retain / Review | 部分可取 | 可以做轻量回看，但不应成为主流程，也不要第一阶段引入 FSRS 或 Anki 式学习系统 | P2 |
+| 把 AIWiki 改成纯人脑内化工具 | 不建议 | 会偏离当前 Agent-first CLI 边界，也会让产品过重 | 不做 |
+| 引入多知识库、自动采集、内置网页抓取 | 不建议 | 与当前仓库 AGENTS.md 和 README 边界冲突；这些属于 AIWiki Pro 或宿主 Agent/服务层，不属于基础 CLI | 不做 |
+
+## 产品原则
+
+1. AIWiki 只沉淀值得复用的上下文，不收藏所有公开知识。
+2. 外部资料默认不代表用户观点。
+3. 用户自己的输出和判断比外部输入更值钱。
+4. AIWiki CLI 不调用 LLM；高质量分析由宿主 Agent 提供，AIWiki 负责规范、落盘、追踪、检查。
+5. 保持单知识库、单命令 `aiwiki`、本地 Markdown 的基本边界。
+6. Review / Retain 是增强闭环，不是默认主流程。
+
+## 三类知识资产模型
+
+### 1. Source Knowledge：来源证据
+
+用于保存外部文章、网页、报告、视频转写、书籍摘录等。
+
+建议字段：
+
+```yaml
+source_role: input
+wiki_type: source_knowledge
+represents_user_view: false
+```
+
+价值标准：
+
+- 是否能作为证据引用。
+- 是否能支撑观点或反驳观点。
+- 是否能生成选题、方案、脚本或研究方向。
+- 是否能和已有资料、判断、输出建立连接。
+
+### 2. Personal Insight：个人判断
+
+用于保存用户或宿主 Agent 帮用户整理出的判断、取舍、冲突、决策理由。
+
+建议先复用现有 `source_role=processing`，并把 `wiki_type` 从宽泛的 `thought_note` 收窄为更明确的 `personal_insight` 或 `decision_note`。第一阶段可以兼容旧值。
+
+建议字段：
+
+```yaml
+type: insight_note
+source_role: processing
+wiki_type: personal_insight
+represents_user_view: true
+confidence: low | medium | high
+based_on:
+  - 03-sources/article-cards/example.md
+  - 05-wiki/source-knowledge/example.md
+used_for:
+  - article
+  - product_decision
+  - client_solution
+  - research
+```
+
+条目应回答：
+
+- 我认同什么，为什么。
+- 我反对什么，为什么。
+- 对项目、文章、产品或客户方案有什么启发。
+- 能否转成文章观点、产品决策或执行动作。
+- 和我已有判断是否冲突。
+
+### 3. Output Knowledge：可复用输出
+
+用于保存用户已经发布或交付过的文章、方案、PRD、README、报价、视频脚本、群内回答等。
+
+建议字段：
+
+```yaml
+source_role: output
+wiki_type: personal_knowledge
+represents_user_view: true
+```
+
+价值标准：
+
+- 能反映用户真实观点。
+- 能反映用户表达风格。
+- 能被新文章、新方案、新脚本复用。
+- 能回溯到支撑它的 source 和 insight。
+
+## 命令方案
+
+### `aiwiki context`
+
+定位：从“相关资料包”升级为“任务上下文包”。
+
+新增 `--mode`：
+
+```bash
+aiwiki context "AI知识库是否还有必要" --mode write
+aiwiki context "AIWiki产品定位" --mode decide
+aiwiki context "Karpathy LLM Wiki" --mode research
+aiwiki context "我的公众号文章风格" --mode style
+aiwiki context "某个知识点" --mode learn
+```
+
+建议返回结构：
+
+```json
+{
+  "schema_version": "aiwiki.context.v2",
+  "query": "AIWiki产品定位",
+  "mode": "decide",
+  "external_sources": [],
+  "personal_insights": [],
+  "past_outputs": [],
+  "conflicts": [],
+  "usable_arguments": [],
+  "missing_context": [],
+  "recommended_next_action": ""
+}
+```
+
+兼容策略：
+
+- 保留 v1 `matches` 结构一段时间。
+- v2 可以先在结果中新增字段，不立刻移除旧字段。
+- `--mode` 缺省为 `general`。
+
+### `aiwiki query`
+
+定位：给人看的知识资产摘要，不是普通搜索结果。
+
+建议输出分组：
+
+```text
+外部资料
+- ...
+
+个人判断
+- ...
+
+已发布输出
+- ...
+
+证据与冲突
+- ...
+
+建议下一步
+- ...
+```
+
+优先级：
+
+- 命中 output 和 insight 时，展示在 source 前面。
+- source 只作为证据，不默认当成结论。
+
+### `aiwiki lint`
+
+定位：从文件结构健康检查升级为知识资产健康检查。
+
+保留现有检查：
+
+- 缺少系统文件。
+- Source Card 没有 Wiki Entry。
+- Wiki Entry 缺少 source_card / raw_file。
+- fallback scaffold 过期。
+- grounding needs review。
+- `represents_user_view=true` 但不是 output。
+- 重复 URL、重复标题、断链。
+
+新增质量检查：
+
+- 某主题只有 source，没有 insight。
+- 某 insight 没有 `based_on`。
+- 某 output 没有关联 source 或 insight。
+- source 被错误标记为代表用户观点。
+- claim 没有 source quote 或证据边界。
+- 某主题存在冲突观点但没有决策结论。
+- enriched entry 只有摘要，没有 reusable judgment / reusable knowledge。
+
+### `aiwiki next`
+
+定位：从命令导航升级为加工建议。
+
+建议输出：
+
+```text
+当前最值得做：
+- 这 3 篇 source 只有摘要，没有个人判断。
+- 这个主题已有 5 条 source，可以生成主题页。
+- 这条 output 没有证据链，建议补 linked sources。
+- 这个观点和历史输出存在冲突，建议进入 review。
+```
+
+### `aiwiki review` 或 `aiwiki retain`
+
+定位：轻量回看，不做重学习系统。
+
+第一版只做候选生成：
+
+```text
+今日建议回看：
+- 3 条个人 insight
+- 2 条高价值 source knowledge
+- 1 条已输出文章中的核心观点
+
+可生成卡片：
+- 观点卡
+- 证据卡
+- 反驳卡
+- 案例卡
+- 输出卡
+```
+
+暂不做：
+
+- FSRS。
+- 每日强制复习。
+- Anki 兼容。
+- 学习进度系统。
+
+## README 与对外话术
+
+建议把开头改得更锋利：
+
+```text
+AIWiki 是一个 Agent-first 本地上下文编译器。
+
+它不替代搜索，也不替你读书，而是把你真正需要反复调用的资料、判断和输出，编译成 AI 能查询、能引用、能检查、能继续使用的本地知识资产。
+```
+
+“它解决什么”建议改成：
+
+- 公开资料搜索得到，但你的使用场景、判断和输出痕迹搜不到。
+- 链接和资料散在聊天记录里，后续很难被 Agent 复用。
+- AI 总结过一次内容，但没有沉淀成可追踪、可查询、可检查的上下文资产。
+- 想把来源证据、个人判断、选题、大纲和已输出内容放进同一个本地知识系统。
+- 想让宿主 Agent 负责理解内容，让 AIWiki 负责稳定落盘、连接和检查。
+
+不建议继续主打：
+
+```text
+打造你的 AI 个人知识库
+```
+
+这个说法太泛，容易被理解成“AI 时代还要不要收藏夹”。
+
+## 分阶段落地
+
+### P0：定位与 schema 心智对齐
+
+目标：不大改代码，先把产品定位和现有字段解释清楚。
+
+任务：
+
+1. 更新 README、FAQ、USAGE 的定位话术。
+2. 在 docs 中新增“三类资产模型”说明。
+3. 在 Agent handoff / skill 中要求宿主 Agent 区分 source、insight、output。
+4. 明确 `source_role=input` 永远不默认代表用户观点。
+5. 为 `processing` 角色补充 personal insight 示例 payload。
+
+验收：
+
+- 新用户能在 README 前 30 秒理解 AIWiki 不是搜索替代品。
+- 文档能解释 source、insight、output 三层差异。
+- 不引入新命令、不破坏旧 payload。
+
+### P1：任务上下文与质量检查
+
+目标：让 AIWiki 从“能查到资料”升级为“能为任务组织上下文”。
+
+任务：
+
+1. `context` 增加 `--mode`。
+2. `context` 输出新增 `external_sources`、`personal_insights`、`past_outputs`、`conflicts`、`usable_arguments`、`missing_context`。
+3. `query` 输出按资产类型分组。
+4. `lint` 增加 insight/output/evidence 质量检查。
+5. `next` 增加加工建议。
+
+验收：
+
+- 同一个 query 在 `write`、`decide`、`research`、`style` 下返回不同的建议结构。
+- 有 insight/output 时优先暴露，不被 source 淹没。
+- `lint` 能指出“只有资料、没有个人判断”和“输出没有证据链”。
+
+### P2：轻量回看闭环
+
+目标：吸收 Retain 思想，但不把 AIWiki 变成学习软件。
+
+任务：
+
+1. 新增 `review` 或 `retain` 的候选生成命令。
+2. 支持观点卡、证据卡、反驳卡、案例卡、输出卡。
+3. Review Queue 只作为入口，不成为默认强制流程。
+
+验收：
+
+- 命令能生成今日回看候选。
+- 不需要用户维护复杂学习计划。
+- 不引入 FSRS 或重型记忆系统。
+
+## 不做清单
+
+- 不做通用网页抓取。
+- 不做多知识库。
+- 不做 CLI 内置 LLM。
+- 不做默认人工审核流程。
+- 不把 Review Queue 变成强制主流程。
+- 不把 AIWiki 改成 Anki 或 Knowledge MEMO。
+- 不用 `aiwiki-pro` 作为用户命令。
+
+## 推荐任务拆分
+
+1. `AIWIKI-POS-001`：更新 README / FAQ / USAGE 定位话术。
+2. `AIWIKI-POS-002`：补充三类资产模型文档和示例 payload。
+3. `AIWIKI-CTX-001`：为 `context` 增加 `--mode` 和 v2 结果字段。
+4. `AIWIKI-QRY-001`：让 `query` 按 source / insight / output 分组展示。
+5. `AIWIKI-LINT-001`：增加知识质量 lint。
+6. `AIWIKI-NEXT-001`：让 `next` 输出加工建议。
+7. `AIWIKI-REV-001`：设计轻量 review / retain 候选生成。
+
+## 最终判断
+
+这份定位文档对 AIWiki 是利好。它指出了“普通个人知识库/资料索引”在 AI 时代价值下降，这个判断应该接受；但它没有否定 AIWiki 的 Agent-first 本地上下文后端方向。真正可取的调整，是把 AIWiki 从“存知识”进一步收窄成“存上下文、判断和使用痕迹”。
+
+AIWiki 下一步最该做的不是扩功能，而是把已有地基讲清楚、排出优先级，然后补齐 personal insight、output knowledge、task context 和 quality lint 这四块。

package/docs/README.md

@@ -9,6 +9,7 @@ AIWiki 是一个 Agent-first 的本地知识库工具，用来把宿主 Agent
 - 示例展示：[SHOWCASE.md](SHOWCASE.md)
 - 常见问题：[FAQ.md](FAQ.md)
 - 路线图：[ROADMAP.md](ROADMAP.md)
+- 开发记录：[development-log.md](development-log.md)
 
 ## Quick Start
 

package/docs/USAGE.md

@@ -318,13 +318,23 @@ aiwiki query "AI Agent"
 aiwiki lint
 ```
 
+常用工作台模式：
+
+```bash
+aiwiki lint --severity warning
+aiwiki lint --json
+aiwiki lint --no-write
+```
+
+`lint` 会先输出 `lint_summary`、`top_issue` 和报告路径，再按 Errors / Warnings / Info 分组展示问题。每个问题会尽量给出建议动作，例如 `enrich`、`fix_link`、`reingest`、`archive` 或 `mark_reviewed`。`--severity` 只查看指定级别，`--json` 给宿主 Agent 使用，`--no-write` 只在终端检查而不更新 `dashboards/Lint Report.md`。
+
 查看下一步建议：
 
 ```bash
 aiwiki next
 ```
 
-`lint` 输出报告并写入 `dashboards/Lint Report.md`。
+默认情况下，`lint` 输出报告并写入 `dashboards/Lint Report.md`。
 
 ## 8. 高级调试
 
@@ -424,3 +434,59 @@ aiwiki status
 - `next_action`: the recommended next command.
 
 `aiwiki next` uses the same repair order: fix workspace structure first, then lint errors, lint warnings, empty-workspace onboarding, and finally healthy-state query guidance.
+
+## Query and Context Filters
+
+`aiwiki context` and `aiwiki query` use local Markdown/frontmatter search. They do not use vector search, a database, external search, or RAG-over-wiki.
+
+Useful filters:
+
+```bash
+aiwiki context "AI Agent" --type wiki_entries --source-role input --wiki-type source_knowledge --status active --limit 5
+aiwiki query "AI Agent" --type source_cards --status to-review --limit 3
+```
+
+Supported filters:
+
+- `--type`: one result group, such as `wiki_entries`, `source_cards`, `claims`, `topics`, `outlines`, or `raw_refs`.
+- `--source-role`: frontmatter `source_role`, usually `input`, `processing`, or `output`.
+- `--wiki-type`: frontmatter `wiki_type`, such as `source_knowledge` or `personal_knowledge`.
+- `--status`: frontmatter status, such as `active`, `to-review`, `ready`, or `draft`.
+- `--limit`: per-group result limit, clamped from 1 to 50.
+
+The JSON result keeps the stable `schema_version: "aiwiki.context.v1"` and now also includes:
+
+- `query_scope`: filters, limit, and searched groups.
+- `result_quality`: total matches, best score, whether a Wiki Entry was found, and warnings.
+- `recommended_next_action`: for example `use_matches_for_answer`, `review_grounding_or_enrich_entry`, or `broaden_query_or_ingest_source`.
+- Per match: `match_reasons`, `quality_signals`, and `related_refs`.
+
+Use `match_reasons` to explain why a result matched. Use `quality_signals` before answering confidently: scaffold or grounding-review entries should be treated as traceable leads, not final knowledge.
+
+## Agent Skill Sync
+
+AIWiki does not modify Agent configuration during `npm install`. After first install or upgrade, sync the packaged skill explicitly:
+
+```bash
+aiwiki agent sync --yes
+aiwiki agent check
+```
+
+For one host Agent:
+
+```bash
+aiwiki agent sync --agent codex --yes
+aiwiki agent sync --agent claude --yes
+```
+
+Useful Agent-facing options:
+
+```bash
+aiwiki agent sync --dry-run
+aiwiki agent sync --json --yes
+aiwiki agent check --json
+aiwiki agent help
+aiwiki context --help
+```
+
+`agent sync` is safe for first install and cross-version upgrades. It installs missing targets, leaves current targets unchanged, and backs up changed installed skill files before overwrite. If a backup is created, tell the user the backup path and that rollback means copying the backup file back to the target path.

package/docs/development-log.md

@@ -0,0 +1,97 @@
+# AIWiki Development Log
+
+This log records queue-driven AIWiki development milestones that should remain visible to future maintainers, not only in automation chat history.
+
+## 2026-06-05 - AIWIKI-004 lint workbench
+
+Status: implemented, locally verified, pushed to GitHub, blocked on npm OTP before publication.
+
+Version target: `@itradingai/aiwiki@0.2.16`
+
+Commit: `932386c` (`Turn lint into an actionable maintenance workbench`)
+
+### Goal
+
+Turn `aiwiki lint` from a plain report writer into a practical structure-maintenance workbench for humans and host Agents.
+
+The scoped acceptance criteria were:
+
+- summarize lint output in the terminal with errors, warnings, info, top issue, and report path;
+- group the markdown report by severity and provide a handling order;
+- support `--severity error|warning|info`;
+- support `--json` for machine-readable Agent use;
+- support `--no-write` for temporary checks that do not update `dashboards/Lint Report.md`;
+- add lightweight knowledge-gap signals where feasible;
+- attach advisory review actions such as `enrich`, `fix_link`, `archive`, `reingest`, and `mark_reviewed`.
+
+### Implemented
+
+- `src/lint.ts`
+  - Added `LintSeverity` and advisory `LintAction`.
+  - Added issue `category` and `action` fields.
+  - Added system-file checks for `_system/purpose.md`, `_system/index.md`, and `_system/log.md`.
+  - Added signals for isolated Source Cards, stale deterministic fallback entries, grounding-review entries, metadata-boundary issues, duplicate URLs/titles, and broken wikilinks.
+  - Added severity filtering, terminal summary rendering, and severity-grouped report rendering.
+
+- `src/app.ts`
+  - Added `aiwiki lint --severity error|warning|info`.
+  - Added `aiwiki lint --json`.
+  - Added `aiwiki lint --no-write`.
+  - Kept the default behavior of writing `dashboards/Lint Report.md`.
+
+- `tests/cli.test.ts` and `tests/ingest.test.ts`
+  - Covered lint summary output, severity filtering, JSON output, no-write behavior, and updated lint issue text assertions.
+
+- `docs/USAGE.md` and `docs/AGENT_HANDOFF.md`
+  - Documented human and Agent-facing lint modes.
+
+### Verification
+
+- `npm test`: passed, 53 tests.
+- `npm run release:check`: passed, including 53 tests and release-check.
+- `npm pack --dry-run`: passed for `@itradingai/aiwiki@0.2.16`.
+- Clean export pack from `C:/tmp/aiwiki-004-publish`: passed, 31 files, shasum `945c70d3d4cf20c9550deaaf92036786b75e62cf`.
+
+### Release State
+
+GitHub push succeeded:
+
+```text
+2e4b253..932386c main -> main
+```
+
+npm publication is blocked by a one-time password challenge:
+
+```text
+npm error code EOTP
+npm error This operation requires a one-time password from your authenticator.
+```
+
+Current registry version remains `0.2.15`, so remote smoke tests for `0.2.16` have not run yet.
+
+### Resume Steps
+
+From the clean publish directory:
+
+```powershell
+cd C:\tmp\aiwiki-004-publish
+npm publish --access public --otp=<code>
+npm view @itradingai/aiwiki version
+```
+
+After `npm view` returns `0.2.16`, run remote smoke tests for:
+
+```bash
+aiwiki lint --path <tmp-vault>
+aiwiki lint --severity warning --path <tmp-vault>
+aiwiki lint --json --path <tmp-vault>
+aiwiki lint --no-write --path <tmp-vault>
+```
+
+Then update the queue through `published`, `remote_verified`, and `done`.
+
+### Notes For Future Changes
+
+- Lint actions are advisory only. Do not make `archive`, `reingest`, `mark_reviewed`, or related actions mutate files without a separate explicit task.
+- Keep lint local-file-only. Do not add crawling, vector search, RAG-over-wiki, RBAC, RSS, scheduled collection, or browser plugins under this queue item.
+- The original working tree had unrelated `skill/SKILL.md` changes. Publication must use a clean commit export until that WIP is resolved.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itradingai/aiwiki",
-  "version": "0.2.15",
+  "version": "0.2.18",
   "type": "module",
   "description": "Agent-first AI knowledge base CLI for turning articles, links and notes into Obsidian-ready source cards, topics, outlines and reusable knowledge assets.",
   "license": "MIT",

package/skill/LINT_PROTOCOL.md

@@ -15,15 +15,23 @@ Use this protocol when the user asks:
 aiwiki lint
 ```
 
-2. Read the terminal report.
-3. Mention the report path, usually:
+2. When you need machine-readable triage, call:
+
+```bash
+aiwiki lint --json
+aiwiki next
+```
+
+3. Read the terminal report.
+4. Mention the report path, usually:
 
 ```text
 dashboards/Lint Report.md
 ```
 
-4. Explain warnings and errors as structure-health feedback.
-5. Do not frame lint as "the user must manually audit every note".
+5. Explain warnings and errors as structure-health feedback.
+6. Do not frame lint as "the user must manually audit every note".
+7. If `aiwiki next` recommends `aiwiki agent sync --yes`, treat Agent skill setup as the next operational step before asking the user to ingest or query more material.
 
 ## Issue Meaning
 
@@ -39,4 +47,3 @@ Prefer small, traceable fixes:
 - Fix broken wikilinks.
 - Add missing `source_card` or `raw_file` paths.
 - Ask the host Agent to provide `analysis` for scaffold entries.
-

package/skill/QUERY_PROTOCOL.md

@@ -16,11 +16,29 @@ Use this protocol when the user asks:
 aiwiki context "<topic>"
 ```
 
+Add filters when the user intent is specific:
+
+```bash
+aiwiki context "<topic>" --type wiki_entries --status active --limit 5
+aiwiki context "<topic>" --source-role input --wiki-type source_knowledge --limit 5
+aiwiki context "<topic>" --source-role output --limit 5
+aiwiki context "<topic>" --type source_cards --status to-review --limit 5
+```
+
 3. Read the JSON result.
 4. Prefer `matches.wiki_entries` before source cards, claims, topics, outlines, or raw refs.
-5. Pay attention to `generation_mode`, `quality`, and `warnings`.
-6. If the best Wiki Entry has `quality: "scaffold"`, tell the user that the entry is a traceable fallback and may need Agent enrichment.
-7. Do not scan `02-raw` by default unless:
+5. Read `query_scope` to understand what was searched.
+6. Read `result_quality` before deciding how confident the answer can be.
+7. Follow `recommended_next_action`:
+   - `use_matches_for_answer`: answer from the matches.
+   - `review_grounding_or_enrich_entry`: answer cautiously and suggest enrichment/review.
+   - `review_source_cards_then_create_wiki_entry`: explain that only source-level material exists.
+   - `broaden_query_or_ingest_source`: ask for a broader query or ingest more material.
+8. Use `match_reasons` to explain why an item was selected.
+9. Use `quality_signals` to decide whether the result is enriched, scaffold, needs grounding review, or only has weak source support.
+10. Use `related_refs` to mention useful local follow-up files.
+11. If the best Wiki Entry has `quality: "scaffold"` or `quality_signals` includes `grounding:needs_review`, tell the user that the entry is a traceable lead and may need Agent enrichment or evidence review.
+12. Do not scan `02-raw` by default unless:
    - Wiki Entries are insufficient.
    - The user asks to verify the original source.
    - There is a source conflict.
@@ -35,4 +53,3 @@ Include:
 - Source basis.
 - Known gaps or scaffold warnings.
 - Suggested next step.
-

package/skill/SKILL.md

@@ -3,12 +3,46 @@ name: aiwiki
 description: Agent-first AIWiki workflow for turning one URL/body into local Wiki knowledge files.
 ---
 
+<!-- aiwiki-skill-version: 0.2.18 -->
+
 # AIWiki Skill
 
 Use this skill when the user asks an Agent to process one URL, article body, or local text file with the `aiwiki` keyword, or says phrases like `入库 <url>` / `收录 <url>` / `从 AIWiki 里了解 <topic>`.
 
 AIWiki CLI does not fetch webpages and does not call an LLM. The host Agent reads and understands the source; AIWiki validates, writes, links, tracks, queries, and lints local Markdown knowledge files.
 
+## Agent-First Setup and Upgrade
+
+When the user asks you to install, update, or repair AIWiki Agent integration, prefer the idempotent sync command:
+
+```bash
+aiwiki agent sync --yes
+```
+
+For a specific host:
+
+```bash
+aiwiki agent sync --agent codex --yes
+aiwiki agent sync --agent claude --yes
+```
+
+Use `--dry-run` to preview without writing, and `--json` when you need machine-readable status:
+
+```bash
+aiwiki agent sync --agent codex --dry-run
+aiwiki agent sync --json --yes
+aiwiki agent check --json
+```
+
+Sync behavior:
+
+- missing installed skill: install the packaged AIWiki skill
+- current installed skill: leave unchanged
+- different installed skill: backup the old file, then overwrite with the packaged skill
+- unsupported host: do not write; use `aiwiki prompt agent` as a manual fallback
+
+After sync, tell the user the target path, any backup path, and that the target Agent may need to restart or reload before the new skill is active. Never edit Agent config during `npm install`; sync is the explicit safe step.
+
 ## Knowledge Base Purpose
 
 Before ingesting, querying, linting, or reorganizing material, read `_system/purpose.md` in the target AIWiki workspace when it exists. Treat it as the local contract for:
@@ -143,7 +177,26 @@ When the user asks to understand a topic from AIWiki, call:
 aiwiki context "<topic>"
 ```
 
-Use the returned JSON to answer. Prefer Wiki Entries first. Do not scan `02-raw` by default unless the Wiki result is insufficient, the user asks to verify the original text, or sources conflict.
+Use filters when the user's intent is clear:
+
+```bash
+aiwiki context "<topic>" --type wiki_entries --status active --limit 5
+aiwiki context "<topic>" --source-role output --limit 5
+aiwiki context "<topic>" --type source_cards --status to-review --limit 5
+```
+
+Use the returned JSON to answer. Prefer Wiki Entries first, but read these fields before responding:
+
+- `query_scope`: filters, limit, and searched groups
+- `result_quality`: total matches, best score, and whether a Wiki Entry was found
+- `recommended_next_action`: whether to answer, broaden the query, enrich, or review grounding
+- `match_reasons`: why each result matched
+- `quality_signals`: scaffold, enriched, grounding, status, and relationship hints
+- `related_refs`: local wikilinks and frontmatter relationships
+
+Do not scan `02-raw` by default unless the Wiki result is insufficient, the user asks to verify the original text, or sources conflict.
+
+If `quality_signals` contains `quality:scaffold` or `grounding:needs_review`, tell the user the result is a traceable lead that needs enrichment or review. Do not present it as final confirmed knowledge.
 
 For direct human terminal output, use: