@itradingai/aiwiki 0.2.22 → 0.2.23

package/README.md

@@ -28,7 +28,7 @@ Use it to build a local AI knowledge base that can be queried, checked, maintain
 
 Ask your AI assistant to install and configure AIWiki.
 
-Choose a local folder for your knowledge base. Examples:
+1. Choose a local folder for your knowledge base.
 
 ```text
 Windows: D:\AIWiki
@@ -36,7 +36,9 @@ macOS/Linux: ~/AIWiki
 Project test: ./aiwiki-test
 ```
 
-Copy this prompt into Codex, Claude Code, QClaw, OpenClaw, or another local coding assistant:
+2. Copy this prompt into Codex, Claude Code, QClaw, OpenClaw, or another local coding assistant.
+
+Before sending it, replace every `<replace-with-my-aiwiki-path>` with your own local folder path, such as `D:\AIWiki` or `~/AIWiki`. Do not leave the placeholder in the commands.
 
 ```text
 Please install and configure AIWiki for me.
@@ -48,6 +50,8 @@ Use this knowledge base path:
 
 <replace-with-my-aiwiki-path>
 
+Replace every `<replace-with-my-aiwiki-path>` below with my own local folder path before running commands. If I left the placeholder unchanged, stop and ask me for the real path.
+
 Run these commands:
 
 npm install -g @itradingai/aiwiki@latest
@@ -68,37 +72,13 @@ Then tell me:
 5. what I should do next
 ```
 
-AIWiki has two integration layers:
-
-- `aiwiki agent sync --yes` syncs AIWiki instructions into supported local assistant environments.
-- `aiwiki agent sync --path "<workspace>" --yes` writes workspace-level guidance so assistants entering the knowledge base know to use AIWiki commands first.
-
-After syncing, restart or reload your assistant if needed.
-
-### Expected result
+3. Restart or reload your assistant if needed.
 
-After setup, your assistant should be able to confirm:
-
-- `aiwiki` is installed and reports a version
-- the knowledge base path exists and passes `aiwiki doctor`
-- assistant integration is `installed`, `updated`, or `current`
-- workspace guidance was written by `aiwiki agent sync --path`
-- `aiwiki status` reports the workspace state and next action
+If assistant sync fails, open an [Agent Integration issue](https://github.com/iTradingAI/aiwiki/issues/new?template=agent_integration.md) and include the output of `aiwiki agent check --json` and `aiwiki doctor --path "<workspace>"`.
 
 ## First Use
 
-### 10-minute public trial path
-
-Use this path when you are trying AIWiki for the first time:
-
-1. Run the Quick Start prompt above with a temporary knowledge base path.
-2. Send one article, file, or note to your assistant and ask it to ingest the source into AIWiki.
-3. Ask one question about the ingested topic so the assistant calls `aiwiki context`.
-4. Run `aiwiki query "<topic>"` when you want a direct terminal view.
-5. Ask the assistant to check the workspace with `aiwiki lint --json` and `aiwiki doctor`.
-6. Share feedback with the short template in [`docs/TRIAL_FEEDBACK_TEMPLATE.md`](docs/TRIAL_FEEDBACK_TEMPLATE.md).
-
-The point of the first trial is not to build a large archive. It is to confirm that one source can move from reading, to traceable Markdown files, to later reuse.
+Trying AIWiki for the first time? Use the short trial route in the [Usage Guide](docs/USAGE.md#3-ingest-a-source).
 
 ### Ingest a source
 
@@ -152,13 +132,6 @@ The assistant should call:
 aiwiki lint --json
 ```
 
-When only safe fixes are reported and you allow cleanup, the assistant may run:
-
-```bash
-aiwiki lint --fix-empty-dirs --json
-aiwiki lint --json
-```
-
 ## What AIWiki Creates
 
 A successful ingest creates a traceable knowledge package:
@@ -181,15 +154,6 @@ Optional files may also be created when the assistant provides enough structured
 
 The Wiki Entry is the main reusable knowledge surface. The raw record and source card preserve traceability, so you can always go back from a summary to the source.
 
-A successful first run should leave you with:
-
-- a new folder under `09-runs/`
-- `payload.json` and `processing-summary.md` inside that run folder
-- a Source Card under `03-sources/article-cards/`
-- a reusable Wiki Entry under `05-wiki/source-knowledge/`
-- `aiwiki query "<topic>"` or `aiwiki context "<topic>"` returning a relevant match
-- `aiwiki lint --json` returning structure feedback instead of requiring manual file inspection first
-
 See:
 
 - [`examples/demo-run/`](examples/demo-run/)
@@ -209,9 +173,10 @@ Instead of saving links and losing context, you get Markdown files that your ass
 
 ## Practical Scenarios
 
-- **Save research while reading**: send an article to your assistant and let AIWiki create a source card, Wiki Entry, and processing record.
-- **Prepare future writing**: turn useful ideas into reusable concepts, claims, topics, and outline material when the assistant provides enough structure.
-- **Ask across your own archive**: ask what AIWiki knows about a topic and let the assistant retrieve local context before answering.
+- **Build a personal research wiki** from articles, PDFs, files, and notes.
+- **Turn useful reading into reusable ideas** such as concepts, claims, topics, and outlines.
+- **Give Codex, Claude Code, or QClaw a stable local knowledge layer** it can query before answering.
+- **Keep summaries traceable** with raw records, source cards, Wiki Entries, and run records.
 
 ## How It Works
 
@@ -256,43 +221,40 @@ The goal is simple: make what your assistant reads useful again later.
 
 ## Agent Integration
 
-AIWiki is built for assistant-driven workflows.
-
-Supported local assistant targets may include:
+AIWiki is built for assistant-driven workflows. `aiwiki agent sync --yes` syncs packaged AIWiki instructions into supported local assistant environments, and `aiwiki agent sync --path "<workspace>" --yes` writes workspace guidance so assistants entering the knowledge base use AIWiki commands first.
 
-- Codex
-- Claude Code
-- QClaw
-- OpenClaw
+See [Agent Handoff](docs/AGENT_HANDOFF.md) for the full command-first contract.
 
-Your assistant should run:
+## Obsidian and Dataview
 
-```bash
-aiwiki agent sync --yes
-aiwiki agent sync --path "<workspace>" --yes
-aiwiki agent check --json
-aiwiki agent check --path "<workspace>" --json
-```
+AIWiki writes plain Markdown and frontmatter.
 
-For unsupported hosts, ask AIWiki to print the generic assistant protocol:
+Obsidian is optional but useful as a viewing surface. Dataview is an optional dashboard enhancement.
 
-```bash
-aiwiki prompt agent
-```
+AIWiki does not require Obsidian, does not auto-install Dataview, and does not edit `.obsidian`.
 
-`npm install` does not silently modify assistant configuration. Sync is explicit, idempotent, and backs up changed installed skill files before overwrite.
+Review Queue is not the main workflow. AIWiki creates Wiki entries first, then uses lint and assistant workflows to keep the workspace clean.
 
-After syncing, restart or reload the assistant if needed.
+## Security and Privacy
 
-## Obsidian and Dataview
+- AIWiki writes local Markdown and JSON files.
+- AIWiki does not upload your knowledge base.
+- AIWiki does not include a built-in LLM.
+- AIWiki does not crawl the web by itself.
+- `npm install` does not modify assistant configuration.
+- Agent integration is explicit through `aiwiki agent sync`.
 
-AIWiki writes plain Markdown and frontmatter.
+## Current Status
 
-Obsidian is optional but useful as a viewing surface. Dataview is an optional dashboard enhancement.
+AIWiki currently focuses on:
 
-AIWiki does not require Obsidian, does not auto-install Dataview, and does not edit `.obsidian`.
+- one local AIWiki knowledge base
+- local Markdown and frontmatter retrieval
+- assistant-driven ingest
+- Source Cards and Wiki Entries
+- `context`, `query`, `lint`, `status`, and `doctor` workflows
 
-Review Queue is not the main workflow. AIWiki creates Wiki entries first, then uses lint and assistant workflows to keep the workspace clean.
+Semantic search, vector indexing, browser clipping, RSS collection, and enterprise permissions are intentionally out of scope for now.
 
 ## Boundaries
 
@@ -317,9 +279,10 @@ AIWiki is developed by iTradingAI.
 
 For Chinese users, scan the QR codes below to join the WeChat group or follow the official account.
 
-| WeChat Group | Official Account |
-| --- | --- |
-| ![Join WeChat group](https://raw.githubusercontent.com/iTradingAI/aiwiki/main/docs/assets/join-group.png) | ![WeChat official account](https://raw.githubusercontent.com/iTradingAI/aiwiki/main/docs/assets/wechat-official-account.png) |
+<p>
+  <img src="https://raw.githubusercontent.com/iTradingAI/aiwiki/main/docs/assets/join-group.png" alt="Join WeChat group" width="220" />
+  <img src="https://raw.githubusercontent.com/iTradingAI/aiwiki/main/docs/assets/wechat-official-account.png" alt="WeChat official account" width="220" />
+</p>
 
 ## Documentation
 

package/README.zh-CN.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/iTradingAI/aiwiki/main/docs/assets/aiwiki-hero.png" alt="AIWiki" width="100%" />
+  <img src="https://raw.githubusercontent.com/iTradingAI/aiwiki/main/docs/assets/aiwiki-hero.zh-CN.png" alt="AIWiki" width="100%" />
 </p>
 
 <p align="center">
@@ -24,7 +24,7 @@ AIWiki 是给 AI 助手使用的本地 Markdown 知识库。
 
 ## 快速开始
 
-先选一个本地文件夹作为 AIWiki 知识库。示例：
+1. 先选一个本地文件夹作为 AIWiki 知识库。示例：
 
 ```text
 Windows: D:\AIWiki
@@ -32,7 +32,9 @@ macOS/Linux: ~/AIWiki
 项目内测试: ./aiwiki-test
 ```
 
-把下面这段复制给 Codex、Claude Code、QClaw、OpenClaw 或其他本地 AI 编程助手：
+2. 把下面这段复制给 Codex、Claude Code、QClaw、OpenClaw 或其他本地 AI 编程助手：
+
+发送前，请把所有 `<替换成我的 AIWiki 知识库路径>` 替换成你自己的本地文件夹路径，例如 `D:\AIWiki` 或 `~/AIWiki`。不要把这个占位符原样留在命令里。
 
 ```text
 请帮我安装并配置 AIWiki。
@@ -44,6 +46,8 @@ macOS/Linux: ~/AIWiki
 
 <替换成我的 AIWiki 知识库路径>
 
+运行命令前，请把下面所有 `<替换成我的 AIWiki 知识库路径>` 替换成我的真实本地文件夹路径。如果我没有替换，占位符仍然原样存在，请停止并向我询问真实路径。
+
 请运行这些命令：
 
 npm install -g @itradingai/aiwiki@latest
@@ -64,25 +68,14 @@ aiwiki status --path "<替换成我的 AIWiki 知识库路径>"
 5. 下一步应该怎么用
 ```
 
-AIWiki 有两层接入：
-
-- `aiwiki agent sync --yes`：把 AIWiki 的 skill / command 同步到本机支持的 AI 助手环境。
-- `aiwiki agent sync --path "<workspace>" --yes`：在知识库根目录写入指导，让以后进入这个目录的 Agent 也知道要优先使用 `aiwiki` 命令。
-
-同步后，如果助手没有立刻识别 AIWiki，需要重启或重新加载助手。
+3. 如有需要，重启或重新加载你的 AI 助手。
 
-### 安装成功后应该看到什么
-
-完成后，AI 助手应该能确认：
-
-- `aiwiki` 已安装，并能输出版本号
-- 知识库路径已经创建，并通过 `aiwiki doctor`
-- Agent 接入状态是 `installed`、`updated` 或 `current`
-- `aiwiki agent sync --path` 已经写入知识库根指导
-- `aiwiki status` 能返回当前知识库状态和下一步动作
+如果 Agent 同步失败，可以提交 [Agent Integration issue](https://github.com/iTradingAI/aiwiki/issues/new?template=agent_integration.md)，并附上 `aiwiki agent check --json` 和 `aiwiki doctor --path "<workspace>"` 的输出。
 
 ## 第一次使用
 
+第一次试用 AIWiki，建议先按 [使用指南](docs/USAGE.zh-CN.md#3-入库资料) 里的短路径跑一遍。
+
 ### 入库资料
 
 对 AI 助手说：
@@ -135,12 +128,7 @@ aiwiki query "<主题>"
 aiwiki lint --json
 ```
 
-如果只包含安全修复，并且你允许整理，可以继续调用：
-
-```bash
-aiwiki lint --fix-empty-dirs --json
-aiwiki lint --json
-```
+如果你想让助手进一步整理知识库，可以参考 [使用指南](docs/USAGE.zh-CN.md) 里的检查流程。
 
 ## AIWiki 会生成什么
 
@@ -183,9 +171,10 @@ AIWiki 的作用是让 AI 助手把读过的资料整理成本地 Markdown 知
 
 ## 典型场景
 
-- **阅读时顺手沉淀资料**：把文章发给 AI 助手，让 AIWiki 生成资料卡、Wiki 条目和处理记录。
-- **为后续写作做准备**：当助手提供了足够结构化内容时，把观点、概念、选题和大纲素材一起沉淀下来。
-- **从自己的资料库里追问**：围绕某个主题提问，让助手先从 AIWiki 取回本地上下文，再组织回答。
+- **建立个人研究 Wiki**：把文章、PDF、文件和笔记沉淀成本地 Markdown 知识库。
+- **把有价值的阅读变成可复用想法**：沉淀概念、观点、选题、大纲和后续创作素材。
+- **给 Codex、Claude Code 或 QClaw 一个稳定的本地知识层**：让助手回答前先查自己的 AIWiki。
+- **保留可追溯的知识链路**：Raw、Source Card、Wiki Entry 和运行记录都能回查。
 
 ## 工作原理
 
@@ -226,39 +215,38 @@ AIWiki 不是简单拼接两套方法。
 
 ## Agent 接入
 
-AIWiki 面向 AI 助手驱动的工作流。
+AIWiki 面向 AI 助手驱动的工作流。`aiwiki agent sync --yes` 会把 AIWiki 的说明同步到支持的本地助手环境；`aiwiki agent sync --path "<workspace>" --yes` 会在知识库根目录写入指导，让进入该目录的助手优先使用 AIWiki 命令。
 
-目前支持自动同步的本地助手目标包括：
+完整的命令优先协作约定见 [Agent 接入说明](docs/AGENT_HANDOFF.zh-CN.md)。
 
-- Codex
-- Claude Code
-- QClaw
-- OpenClaw
+## Obsidian / Dataview
 
-让 AI 助手运行：
+AIWiki 写的是普通 Markdown 和 frontmatter。
 
-```bash
-aiwiki agent sync --yes
-aiwiki agent sync --path "<workspace>" --yes
-aiwiki agent check --json
-aiwiki agent check --path "<workspace>" --json
-```
+Obsidian 是推荐查看界面，但不是硬依赖。Dataview 是可选 dashboard 增强。
 
-不支持自动写入的宿主，可以输出通用协议：
+AIWiki 不会自动安装 Dataview，也不会修改 `.obsidian`。
 
-```bash
-aiwiki prompt agent
-```
+## 安全和隐私
 
-`npm install` 不会偷偷修改 AI 助手配置。同步是显式动作，可重复执行，并会在覆盖已变化的 skill 前创建备份。
+- AIWiki 写入本地 Markdown 和 JSON 文件。
+- AIWiki 不会上传你的知识库。
+- AIWiki 不内置 LLM。
+- AIWiki 不会自行爬取网页。
+- `npm install` 不会修改 AI 助手配置。
+- Agent 接入需要显式运行 `aiwiki agent sync`。
 
-## Obsidian / Dataview
+## 当前状态
 
-AIWiki 写的是普通 Markdown 和 frontmatter。
+AIWiki 当前聚焦于：
 
-Obsidian 是推荐查看界面，但不是硬依赖。Dataview 是可选 dashboard 增强。
+- 单个本地 AIWiki 知识库
+- 本地 Markdown 和 frontmatter 检索
+- AI 助手驱动的入库流程
+- Source Card 和 Wiki Entry
+- `context`、`query`、`lint`、`status`、`doctor` 等工作流
 
-AIWiki 不会自动安装 Dataview，也不会修改 `.obsidian`。
+语义搜索、向量索引、浏览器剪藏、RSS 采集和企业权限管理目前都不在当前范围内。
 
 ## 设计边界
 
@@ -283,9 +271,10 @@ AIWiki 由 iTradingAI 开源维护。
 
 中文用户可以扫码加入交流群，或关注公众号获取更新、案例和使用讨论。
 
-| 微信交流群 | 公众号 |
-| --- | --- |
-| ![加入微信群](https://raw.githubusercontent.com/iTradingAI/aiwiki/main/docs/assets/join-group.png) | ![微信公众号](https://raw.githubusercontent.com/iTradingAI/aiwiki/main/docs/assets/wechat-official-account.png) |
+<p>
+  <img src="https://raw.githubusercontent.com/iTradingAI/aiwiki/main/docs/assets/join-group.png" alt="加入微信群" width="220" />
+  <img src="https://raw.githubusercontent.com/iTradingAI/aiwiki/main/docs/assets/wechat-official-account.png" alt="微信公众号" width="220" />
+</p>
 
 ## 文档
 

package/docs/USAGE.md

@@ -17,6 +17,8 @@ AIWiki does not fetch webpages and does not call an LLM. The host assistant read
 
 Copy this prompt into your assistant:
 
+Before sending it, replace every `<replace-with-my-aiwiki-path>` with your own local folder path, such as `D:\AIWiki` or `~/AIWiki`. Do not leave the placeholder in the commands.
+
 ```text
 Please install and configure AIWiki for me.
 
@@ -27,6 +29,8 @@ Use this knowledge base path:
 
 <replace-with-my-aiwiki-path>
 
+Replace every `<replace-with-my-aiwiki-path>` below with my own local folder path before running commands. If I left the placeholder unchanged, stop and ask me for the real path.
+
 Run these commands:
 
 npm install -g @itradingai/aiwiki@latest

package/docs/USAGE.zh-CN.md

@@ -17,6 +17,8 @@ AIWiki 不抓网页，也不调用 LLM。宿主 AI 助手负责读取和理解
 
 复制这段给你的 AI 助手：
 
+发送前，请把所有 `<替换成我的 AIWiki 知识库路径>` 替换成你自己的本地文件夹路径，例如 `D:\AIWiki` 或 `~/AIWiki`。不要把这个占位符原样留在命令里。
+
 ```text
 请帮我安装并配置 AIWiki。
 
@@ -27,6 +29,8 @@ AIWiki 不抓网页，也不调用 LLM。宿主 AI 助手负责读取和理解
 
 <替换成我的 AIWiki 知识库路径>
 
+运行命令前，请把下面所有 `<替换成我的 AIWiki 知识库路径>` 替换成我的真实本地文件夹路径。如果我没有替换，占位符仍然原样存在，请停止并向我询问真实路径。
+
 请运行这些命令：
 
 npm install -g @itradingai/aiwiki@latest

package/docs/development-log.md

@@ -2,6 +2,71 @@
 
 This log records queue-driven AIWiki development milestones that should remain visible to future maintainers, not only in automation chat history.
 
+## 2026-06-11 - Repository trust and README P0/P1 polish
+
+Status: implemented and locally verified. Demo GIF recording is intentionally deferred until the P0/P1 documentation and repository trust pass is complete.
+
+### Goal
+
+Close the high-priority public-facing issues identified after the README rewrite:
+
+- keep GitHub About, npm metadata, and README positioning aligned;
+- make README shorter and push detailed procedures into docs;
+- document security and privacy boundaries;
+- add CI coverage for build, test, and package inspection;
+- make Agent sync failure reporting easier;
+- keep WeChat community entry visible without overwhelming the README.
+
+### Implemented
+
+- Compressed the English and Chinese README quick-start flows around the assistant-driven install prompt.
+- Moved detailed first-use, lint, and trial-route guidance toward the usage guides.
+- Added Agent sync failure issue guidance with `agent check` and `doctor` evidence.
+- Added Security and Privacy and Current Status sections in both README files.
+- Refined practical scenarios around research, reusable ideas, assistant context, and traceability.
+- Reduced community QR display size while keeping the WeChat group and official account visible.
+- Clarified that `<replace-with-my-aiwiki-path>` and `<替换成我的 AIWiki 知识库路径>` are placeholders users must replace with their own local folder path before running commands.
+- Added `.github/workflows/ci.yml` to run build, tests, and `npm pack --dry-run` on Node 20, 22, and 24.
+- Fixed the npm test runner command so CI does not depend on shell glob expansion or newer Node test-runner glob behavior.
+
+### Verification
+
+- Local README/doc link check: passed, `broken links: 0`.
+- `npm run release:check`: passed, 61 tests.
+- `npm pack --dry-run --json`: passed for `@itradingai/aiwiki@0.2.22`, 90 files, package size approximately 106 kB.
+- Pack inspection confirmed `docs/assets`, `aiwiki-hero`, `aiwiki-logo`, `join-group`, and `wechat-official-account` are still excluded from the npm tarball.
+- GitHub About description was updated to match npm/README positioning.
+- Initial CI run exposed Node 20 incompatibility in the quoted test glob; the test helper was added, and the follow-up GitHub Actions CI run passed on Node 20, 22, and 24.
+
+## 2026-06-11 - README hero and logo asset refresh
+
+Status: implemented and locally verified. This pass targets GitHub raw image delivery only; no npm publication.
+
+### Goal
+
+Replace the older README hero visual with gpt-image-2 generated brand assets that better match the current AIWiki positioning:
+
+- golden angular AIWiki logo with a four-point star in the center;
+- clear source inputs: Web link, PDF, and Notes;
+- assistant-driven reading and understanding;
+- AIWiki writing structured Markdown;
+- local Markdown knowledge vault and later `aiwiki context` retrieval;
+- separate English and Chinese README hero images.
+
+### Implemented
+
+- Replaced `docs/assets/aiwiki-hero.png` with the English gpt-image-2 generated hero.
+- Added `docs/assets/aiwiki-hero.zh-CN.png` as the Chinese gpt-image-2 generated hero.
+- Added `docs/assets/aiwiki-logo.png` cropped from the gpt-image-2 generated English hero for future brand reuse.
+- Updated `README.zh-CN.md` to use the Chinese raw GitHub hero URL: `docs/assets/aiwiki-hero.zh-CN.png`.
+- Kept README images out of the npm package; README files reference GitHub raw URLs instead.
+
+### Verification
+
+- Local README/doc link check: passed, `broken links: 0`.
+- `npm run release:check`: passed, 61 tests.
+- `npm pack --dry-run`: passed for `@itradingai/aiwiki@0.2.22`; confirmed `docs/assets`, `aiwiki-hero`, `aiwiki-logo`, `join-group`, and `wechat-official-account` were not included in the npm tarball.
+
 ## 2026-06-11 - Public trial path and feedback loop
 
 Status: implemented and locally verified. Pre-delivery remote tarball smoke, GitHub push, Trusted Publishing, registry verification, and post-publish remote sanity are required before queue completion.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itradingai/aiwiki",
-  "version": "0.2.22",
+  "version": "0.2.23",
   "type": "module",
   "description": "Local Markdown knowledge base for AI assistants. Save what your AI reads, ask it later, and keep everything local.",
   "license": "MIT",
@@ -67,7 +67,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --test \"dist/tests/*.test.js\"",
+    "test": "npm run build && node scripts/run-tests.mjs",
     "check": "npm run test",
     "release:check": "npm test && node scripts/release-check.mjs",
     "prepack": "npm run build"