@itradingai/aiwiki 0.2.21 → 0.2.22

package/docs/FAQ.md

@@ -1,100 +1,124 @@
 # AIWiki FAQ
 
-## AIWiki 是什么？
+## What is AIWiki?
 
-AIWiki 是一个开源的 Agent-first 本地 LLM-wiki CLI。宿主 Agent 负责读取和理解内容，AIWiki 负责把结果稳定写成本地 Markdown 知识库。
+AIWiki is a local Markdown knowledge base for AI assistants. Your assistant reads and understands sources; AIWiki writes structured, traceable, reusable Markdown knowledge files.
 
-## AIWiki 是网页爬虫吗？
+## Is AIWiki a web crawler?
 
-不是。网页读取主要交给宿主 Agent，AIWiki 专注于校验结构化输入、写本地文件、生成 Wiki Entry、提供 context 和 lint。
+No. Web reading belongs to the host assistant. AIWiki receives content the assistant already read and turns it into a local knowledge base.
 
-## AIWiki 会自动高质量总结吗？
+## Does AIWiki call an LLM?
 
-不会。AIWiki CLI 本身不调用 LLM。高质量 Wiki Entry 来自宿主 Agent 在 payload 中提供的 `analysis` 或 `wiki_entry`。
+No. AIWiki CLI does not call an LLM. High-quality summaries and analysis come from the host assistant through `analysis` or `wiki_entry` fields.
 
-## 为什么会生成 05-wiki？
+## Why does installation fail?
 
-因为 AIWiki 的目标不是只保存资料，而是让资料进入可查询、可维护的 Wiki 知识层。成功入库会生成 `05-wiki/source-knowledge/<slug>.md`。
+Check Node.js first:
 
-## Wiki Entry 的两种质量模式是什么？
+```bash
+node --version
+```
+
+AIWiki requires Node.js 20 or newer. If `node` is missing or older than 20, upgrade Node.js before running `npm install -g @itradingai/aiwiki@latest`.
 
-- `agent_enriched` / `enriched`：宿主 Agent 提供了总结、核心观点、知识点等分析结果。
-- `deterministic_fallback` / `scaffold`：AIWiki 只生成标题、来源、正文预览、反链和待补全区。
+## Why does AIWiki create `05-wiki`?
 
-## 05-wiki 是否代表我的观点？
+Because the goal is not just to save source material. AIWiki creates reusable Wiki Entries that assistants can query later.
 
-不一定。外部资料生成的 Wiki Entry 默认代表外部资料的结构化整理，不代表用户个人观点。
+## What are the two Wiki Entry quality modes?
 
-## 一定要用 Obsidian 吗？
+- `agent_enriched` / `enriched`: the assistant provided analysis or wiki content.
+- `deterministic_fallback` / `scaffold`: AIWiki created a traceable shell from source content only.
 
-不一定。AIWiki 生成的是标准 Markdown 和 frontmatter，Obsidian 只是最适合它的审阅界面之一。
+## Does a Wiki Entry represent my personal opinion?
 
-## 一定要装 Dataview 吗？
+Not by default. External sources use `source_role: input` and `represents_user_view: false`. Use `source_role: output` and `represents_user_view: true` only for your own published writing, scripts, talks, newsletters, or similar authored output.
 
-不一定。没有 Dataview，也可以用 Obsidian 原生的 Properties、Backlinks、Search 和 Graph View。
+## Do I need Obsidian?
 
-## 宿主 Agent 和 AIWiki 各负责什么？
+No. AIWiki writes plain Markdown and frontmatter. Obsidian is a useful viewing surface, not a requirement.
 
-- 宿主 Agent 负责读取网页、正文或附件，并尽量生成 `analysis` / `wiki_entry`
-- AIWiki 负责校验 payload、写本地知识库、生成 Wiki Entry、输出处理记录
-- 用户负责提供链接或正文，并在需要时让 Agent 继续查询或补全
+## Do I need Dataview?
 
-## 为什么要先让 Agent 学会 AIWiki？
+No. Dataview is optional. AIWiki does not install Dataview and does not edit `.obsidian`.
 
-因为大多数用户不想每次手动跑命令。更顺的方式是：把链接发给宿主 Agent，Agent 自动把内容交给 AIWiki，AIWiki 再把结果写进本地知识库。
+## Why should I sync the assistant first?
 
-## 我能不能把它当成一个通用爬虫用？
+Because the intended workflow is assistant-driven. You send a source or question to the assistant; the assistant calls AIWiki commands. Without sync, the assistant may fall back to generic file search and skip AIWiki's ingest, query, status, and lint surfaces.
 
-不建议。AIWiki 的边界不是“抓全网”，而是“把宿主 Agent 已经读到的内容稳定沉淀下来”。
+## Where should I start?
 
-## 我从哪里开始最好？
+Ask your assistant to run the Quick Start prompt in the main [README](../README.md). Then read the [Usage Guide](USAGE.md).
 
-先跑：
+## What should my first 10-minute trial include?
+
+Use one temporary knowledge base, one source, one query, and one health check:
+
+```bash
+aiwiki setup --path <workspace> --yes
+aiwiki doctor --path <workspace>
+aiwiki ingest-file --file <file> --path <workspace>
+aiwiki query "<topic>" --path <workspace>
+aiwiki context "<topic>" --path <workspace>
+aiwiki lint --json --path <workspace>
+```
+
+If the source is a URL, your assistant should read the URL and then call `aiwiki ingest-agent`; AIWiki does not crawl the URL itself.
+
+## Why is my assistant still reading files directly?
+
+Usually the assistant has not loaded the AIWiki skill, or the workspace root is missing AIWiki guidance. Run:
 
 ```bash
-npx @itradingai/aiwiki@latest setup
 aiwiki agent sync --yes
-aiwiki agent check --json
 aiwiki agent sync --path <workspace> --yes
 aiwiki agent check --path <workspace> --json
 ```
 
-然后去看：
+Then restart or reload the assistant if needed.
 
-- [USAGE.md](USAGE.md)
-- [SHOWCASE.md](SHOWCASE.md)
-- [AGENT_HANDOFF.md](AGENT_HANDOFF.md)
+## How do I query the knowledge base?
 
-## 有没有可以直接看的样例？
+Ask your assistant:
 
-有。`examples/demo-run/` 记录输入、命令和 CLI 输出；`examples/obsidian-vault-sample/` 是已经生成好的样例知识库。它展示了核心产物优先，以及可选增强目录只在有内容时出现。
+```text
+What does AIWiki know about <topic>?
+```
 
-## 怎么从知识库里查询？
+The assistant should call:
 
-让宿主 Agent 调用：
+```bash
+aiwiki context "<topic>"
+```
+
+For human terminal output:
 
 ```bash
-aiwiki context "主题"
+aiwiki query "<topic>"
 ```
 
-## 怎么检查知识库结构？
+## How do I check the workspace?
 
-运行：
+Ask your assistant to run:
 
 ```bash
-aiwiki lint
+aiwiki lint --json
 ```
 
-如果只是清理旧版本留下的空可选增强目录，可以让 Agent 先运行 `aiwiki lint --json`，确认只有 safe fix 后再运行 `aiwiki lint --fix-empty-dirs --json`。
+`aiwiki doctor --path <workspace>` checks whether the workspace is ready and reports actionable setup problems.
 
-## 为什么我的 Agent 还是在直接翻文件？
-
-通常是它没有加载 AIWiki skill，或者知识库根目录缺少 AIWiki 的 `AGENTS.md` 指导。先运行：
+When safe fixes are allowed:
 
 ```bash
-aiwiki agent sync --yes
-aiwiki agent sync --path <workspace> --yes
-aiwiki agent check --path <workspace> --json
+aiwiki lint --fix-empty-dirs --json
+aiwiki lint --json
 ```
 
-之后再让 Agent 处理 AIWiki 任务。它应该优先调用 `aiwiki lint --json`、`aiwiki status`、`aiwiki query`、`aiwiki context`、`aiwiki ingest-file` 或 `aiwiki ingest-agent`。只有这些命令不够用时，才退回到通用文件搜索。
+## How do I send useful trial feedback?
+
+Use [TRIAL_FEEDBACK_TEMPLATE.md](TRIAL_FEEDBACK_TEMPLATE.md). Focus on whether setup worked, whether the assistant called AIWiki commands, whether generated files were easy to inspect, whether query/context helped, and what real scenario you wanted to use.
+
+## What is out of scope?
+
+AIWiki is not a web crawler, WeChat reader, browser extension, built-in LLM, vector database, RAG replacement, Obsidian plugin, default manual review queue, multi-knowledge-base manager, RSS tool, or scheduled collection system.

package/docs/FAQ.zh-CN.md

@@ -0,0 +1,103 @@
+# AIWiki 常见问题
+
+## AIWiki 是什么？
+
+AIWiki 是给 AI 助手使用的本地 Markdown 知识库。AI 助手负责读取和理解资料；AIWiki 负责写入结构化、可追踪、可复用的 Markdown 知识文件。
+
+## AIWiki 是网页爬虫吗？
+
+不是。网页读取属于宿主 AI 助手。AIWiki 接收助手已经读到的内容，并把它变成本地知识库。
+
+## AIWiki 会调用 LLM 吗？
+
+不会。AIWiki CLI 本身不调用 LLM。高质量总结和分析来自宿主助手提供的 `analysis` 或 `wiki_entry`。
+
+## 为什么安装失败？
+
+先检查 Node.js：
+
+```bash
+node --version
+```
+
+AIWiki 需要 Node.js 20 或更新版本。如果没有 `node` 命令，或版本低于 20，请先升级 Node.js，再运行 `npm install -g @itradingai/aiwiki@latest`。
+
+## 为什么会生成 `05-wiki`？
+
+因为 AIWiki 的目标不是只保存资料，而是创建以后能被助手查询和复用的 Wiki Entry。
+
+## Wiki Entry 的两种质量模式是什么？
+
+- `agent_enriched` / `enriched`：助手提供了分析或 Wiki 内容。
+- `deterministic_fallback` / `scaffold`：AIWiki 只根据来源内容生成可追踪脚手架。
+
+## Wiki Entry 代表我的观点吗？
+
+默认不代表。外部资料使用 `source_role: input` 和 `represents_user_view: false`。只有导入自己的已发布文章、演讲稿、公众号文章等个人输出时，才使用 `source_role: output` 和 `represents_user_view: true`。
+
+## 一定要用 Obsidian 吗？
+
+不一定。AIWiki 写的是普通 Markdown 和 frontmatter。Obsidian 只是好用的查看界面。
+
+## 一定要安装 Dataview 吗？
+
+不需要。Dataview 是可选增强。AIWiki 不会安装 Dataview，也不会修改 `.obsidian`。
+
+## 为什么要先同步助手？
+
+因为 AIWiki 的主路径是助手驱动。你把资料或问题交给助手，助手调用 AIWiki 命令。如果没有同步，助手可能只会直接翻文件，绕过 AIWiki 的入库、查询、状态和 lint 能力。
+
+## 从哪里开始？
+
+先把主 [README](../README.zh-CN.md) 里的 Quick Start 提示词复制给 AI 助手，再阅读 [使用指南](USAGE.zh-CN.md)。
+
+## 为什么我的助手还是直接翻文件？
+
+通常是助手没有加载 AIWiki skill，或者知识库根目录缺少 AIWiki 指导。运行：
+
+```bash
+aiwiki agent sync --yes
+aiwiki agent sync --path <workspace> --yes
+aiwiki agent check --path <workspace> --json
+```
+
+必要时重启或重新加载助手。
+
+## 怎么查询知识库？
+
+对 AI 助手说：
+
+```text
+AIWiki 里关于 <主题> 有什么？
+```
+
+助手应该调用：
+
+```bash
+aiwiki context "<主题>"
+```
+
+人在终端里查询可以用：
+
+```bash
+aiwiki query "<主题>"
+```
+
+## 怎么检查知识库？
+
+让助手运行：
+
+```bash
+aiwiki lint --json
+```
+
+允许安全修复时：
+
+```bash
+aiwiki lint --fix-empty-dirs --json
+aiwiki lint --json
+```
+
+## 哪些能力不在范围内？
+
+AIWiki 不是网页爬虫、微信读取器、浏览器插件、内置 LLM、向量数据库、RAG 替代品、Obsidian 插件、默认人工审核队列、多知识库管理器、RSS 工具或定时采集系统。

package/docs/README.md

@@ -1,36 +1,47 @@
 # AIWiki Docs
 
-AIWiki 是一个 Agent-first 的本地知识库工具，用来把宿主 Agent 已经读取到的文章、网页正文或本地文本写入当前配置的知识库。
+AIWiki is a local Markdown knowledge base for AI assistants.
 
-- 用户使用说明：[USAGE.md](USAGE.md)
-- Agent 对接协议：[AGENT_HANDOFF.md](AGENT_HANDOFF.md)
-- Obsidian + Dataview 方案：[OBSIDIAN_DATAVIEW_PLAN.md](OBSIDIAN_DATAVIEW_PLAN.md)
-- 架构图：[architecture.svg](architecture.svg)
-- 示例展示：[SHOWCASE.md](SHOWCASE.md)
-- 常见问题：[FAQ.md](FAQ.md)
-- 路线图：[ROADMAP.md](ROADMAP.md)
-- 开发记录：[development-log.md](development-log.md)
+This docs folder keeps the public guides short and task-oriented. The main README is the product entry point; these files explain daily use, assistant handoff, examples, release checks, and roadmap boundaries.
 
-## Examples
+## Start Here
 
-- `../examples/demo-run/` records the input files, commands, and CLI outputs from a regenerated demo.
-- `../examples/obsidian-vault-sample/` is a sample vault showing the current core-first artifact contract.
+- [Main README](../README.md)
+- [Chinese README](../README.zh-CN.md)
+- [Usage Guide](USAGE.md)
+- [FAQ](FAQ.md)
+- [Agent Handoff](AGENT_HANDOFF.md)
+- [Showcase](SHOWCASE.md)
+- [Trial Feedback Template](TRIAL_FEEDBACK_TEMPLATE.md)
+- [Roadmap](ROADMAP.md)
+- [Release Notes](RELEASE.md)
 
-## Quick Start
+## Chinese Docs
 
-```bash
-npx @itradingai/aiwiki@latest setup
-aiwiki agent sync --yes
-aiwiki agent check --json
-aiwiki doctor
-```
+- [Chinese Docs Home](README.zh-CN.md)
+- [Chinese Usage Guide](USAGE.zh-CN.md)
+- [Chinese Agent Handoff](AGENT_HANDOFF.zh-CN.md)
+- [Chinese FAQ](FAQ.zh-CN.md)
+- [Chinese Showcase](SHOWCASE.zh-CN.md)
+- [Chinese Roadmap](ROADMAP.zh-CN.md)
+- [Chinese Release Notes](RELEASE.zh-CN.md)
+
+## Examples
+
+- [`../examples/demo-run/`](../examples/demo-run/) records input files, CLI commands, and outputs from a regenerated run.
+- [`../examples/obsidian-vault-sample/`](../examples/obsidian-vault-sample/) is a sample Markdown vault showing the current core-first artifact contract.
 
-优先运行 `aiwiki agent sync --yes`，让 CLI 幂等同步本机 Codex、QClaw、OpenClaw、Claude Code 等宿主 Agent 对接文件。其他宿主 Agent 可使用 `aiwiki prompt agent` 输出通用协议，再安装成 skill 或粘贴到项目/会话说明里。之后把链接发给宿主 Agent：
+## Core Workflow
 
 ```text
-入库 https://example.com/article
+AI assistant reads a source
+  -> AIWiki writes local Markdown artifacts
+  -> assistant retrieves context with aiwiki context
+  -> aiwiki lint checks structure and consistency
 ```
 
-## 重要边界
+For public trials, keep the first loop to one source and one question: setup, ingest, inspect the run artifacts, query/context reuse, lint/doctor, and a short feedback note.
+
+## Important Boundaries
 
-CLI 不保证网页抓取成功。网页读取属于宿主 Agent。
+AIWiki does not fetch webpages, call an LLM, install Obsidian plugins, run vector search, or manage multiple knowledge bases. The host assistant reads sources; AIWiki validates, writes, links, queries, and checks the local Markdown knowledge base.

package/docs/README.zh-CN.md

@@ -0,0 +1,34 @@
+# AIWiki 中文文档
+
+AIWiki 是给 AI 助手使用的本地 Markdown 知识库。
+
+主 README 面向 GitHub / npm 的英文入口；中文用户可以从这里进入完整说明。
+
+## 从这里开始
+
+- [中文 README](../README.zh-CN.md)
+- [English README](../README.md)
+- [使用指南](USAGE.zh-CN.md)
+- [常见问题](FAQ.zh-CN.md)
+- [Agent 接入说明](AGENT_HANDOFF.zh-CN.md)
+- [案例展示](SHOWCASE.zh-CN.md)
+- [路线图](ROADMAP.zh-CN.md)
+- [发布说明](RELEASE.zh-CN.md)
+
+## 示例
+
+- [`../examples/demo-run/`](../examples/demo-run/)：记录输入、命令和 CLI 输出。
+- [`../examples/obsidian-vault-sample/`](../examples/obsidian-vault-sample/)：已经生成好的样例知识库。
+
+## 核心流程
+
+```text
+AI 助手读取资料
+  -> AIWiki 写入本地 Markdown 知识文件
+  -> 助手用 aiwiki context 取回上下文
+  -> aiwiki lint 检查结构和一致性
+```
+
+## 重要边界
+
+AIWiki 不抓网页、不调用 LLM、不自动安装 Obsidian 插件、不做向量检索、不管理多个知识库。宿主 AI 助手负责读取和理解资料；AIWiki 负责写入、链接、查询和检查本地 Markdown 知识库。

package/docs/RELEASE.md

@@ -1,54 +1,84 @@
-# AIWiki 发布检查
+# AIWiki Release Notes
 
-发布前先确认本地工作区只包含本次发布需要的改动：
+This document describes the release gate for maintainers.
+
+AIWiki release work must prove the package locally, on the remote test server, through GitHub, and after npm publication.
+
+## Local Checks
+
+Start from a clean, intentional worktree:
 
 ```bash
 git status --short --branch
+npm test
 npm run release:check
 ```
 
-`release:check` 会执行测试、构建、`npm pack --dry-run`、CLI 版本一致性检查，以及一次临时知识库入库检查。
+When package contents, docs, examples, or skill files changed, inspect:
+
+```bash
+npm pack --dry-run
+```
 
-## 版本号
+The package should contain CLI runtime files, user documentation, examples, and packaged skill files only.
 
-版本号以 `package.json` 为唯一来源。CLI 的 `aiwiki --version` 会运行时读取 `package.json`，不要在源码里另写一份版本常量。
+## Version
 
-升级版本：
+`package.json` is the version source. `aiwiki --version` reads it at runtime.
+
+Patch bump by default:
 
 ```bash
 npm version patch --no-git-tag-version
 ```
 
-## npm 发布
+## Pre-delivery Remote Test
+
+Before pushing to GitHub or publishing to npm, build the exact local tarball and test it on the remote server.
+
+Standard order:
+
+```text
+local verification
+  -> version bump
+  -> local commit
+  -> npm pack
+  -> install local tarball on remote test server
+  -> run task-specific CLI smoke
+  -> GitHub push
+  -> GitHub Actions publish workflow
+  -> npm registry verification
+  -> post-publish remote sanity
+```
 
-发布前必须先让同一个本地 tarball 在测试服务器通过 smoke test。顺序是：本地验证、版本号、提交、本地 `npm pack`、测试服务器安装 tarball 并跑 CLI smoke，然后才能 `git push` 和 `npm publish`。
+If the remote smoke fails, do not push and do not publish. Fix locally, rebuild, repack, and rerun the remote smoke.
 
-AIWiki 使用 npm Trusted Publishing。npm 发布应由 GitHub Actions 的 `.github/workflows/publish.yml` 完成，不依赖本机 `npm login`、OTP 或长期 `NPM_TOKEN`。
+## Publishing
 
-远程测试和 GitHub push 都通过后，触发发布 workflow：
+AIWiki uses npm Trusted Publishing. Publication should be done through GitHub Actions:
 
 ```bash
 gh workflow run publish.yml --repo iTradingAI/aiwiki
 gh run watch --repo iTradingAI/aiwiki
 ```
 
-如需查看最近一次发布任务：
+Check recent publish runs:
 
 ```bash
 gh run list --workflow publish.yml --repo iTradingAI/aiwiki --limit 5
 ```
 
-发布后验证：
+Verify the registry:
 
 ```bash
 npm view @itradingai/aiwiki version
 npm view @itradingai/aiwiki versions --json
 ```
 
-如果 workflow 提示 Trusted Publishing / OIDC 权限问题，检查 npm 包设置里的 Trusted Publisher 是否指向 `iTradingAI/aiwiki` 和 workflow 文件名 `publish.yml`，并确认 workflow 顶层包含 `permissions: id-token: write`。
+If Trusted Publishing fails, verify the npm Trusted Publisher settings, repository name, workflow filename, and `id-token: write` permission.
 
-## 包体积
+## Package Images
 
-npm 包只应包含 CLI 运行和用户文档所需文件。README 中的图片使用 GitHub raw 链接展示，`docs/assets/` 不进入 npm 包。
+The README uses GitHub raw URLs for public images so GitHub and npm can render them without bundling `docs/assets/` into the npm package.
 
-如果 `npm pack --dry-run` 输出里出现 `docs/assets/`，说明包内容配置回退了，需要先修复 `package.json.files`。
+If `npm pack --dry-run` includes unexpected assets or private planning files, fix `package.json.files` before publishing.

package/docs/RELEASE.zh-CN.md

@@ -0,0 +1,84 @@
+# AIWiki 发布说明
+
+这份文档给维护者使用。
+
+AIWiki 发布必须证明：本地通过、测试服务器通过、GitHub 推送通过、npm 发布后也通过。
+
+## 本地检查
+
+先确认工作区只包含本次发布需要的改动：
+
+```bash
+git status --short --branch
+npm test
+npm run release:check
+```
+
+如果包内容、文档、示例或 skill 有变化，检查：
+
+```bash
+npm pack --dry-run
+```
+
+npm 包只应包含 CLI 运行文件、用户文档、示例和 packaged skill。
+
+## 版本
+
+`package.json` 是版本来源。`aiwiki --version` 运行时读取它。
+
+默认 patch bump：
+
+```bash
+npm version patch --no-git-tag-version
+```
+
+## 发布前远端测试
+
+推 GitHub 或发布 npm 之前，必须把同一个本地 tarball 放到测试服务器安装并跑 smoke。
+
+标准顺序：
+
+```text
+本地验证
+  -> 版本号
+  -> 本地提交
+  -> npm pack
+  -> 测试服务器安装本地 tarball
+  -> 跑任务对应 CLI smoke
+  -> GitHub push
+  -> GitHub Actions 发布 workflow
+  -> npm registry 验证
+  -> 发布后远端 sanity
+```
+
+如果远端 smoke 失败，不推 GitHub，不发布 npm。先本地修复，重新构建、打包、远端验证。
+
+## 发布
+
+AIWiki 使用 npm Trusted Publishing。发布应通过 GitHub Actions 完成：
+
+```bash
+gh workflow run publish.yml --repo iTradingAI/aiwiki
+gh run watch --repo iTradingAI/aiwiki
+```
+
+查看最近发布任务：
+
+```bash
+gh run list --workflow publish.yml --repo iTradingAI/aiwiki --limit 5
+```
+
+验证 npm：
+
+```bash
+npm view @itradingai/aiwiki version
+npm view @itradingai/aiwiki versions --json
+```
+
+如果 Trusted Publishing 失败，检查 npm Trusted Publisher、仓库名、workflow 文件名和 `id-token: write` 权限。
+
+## README 图片
+
+README 使用 GitHub raw 图片链接，让 GitHub 和 npm 都能显示图片，同时避免把 `docs/assets/` 打进 npm 包。
+
+如果 `npm pack --dry-run` 出现意外资产或内部规划文件，先修复 `package.json.files`。

package/docs/ROADMAP.md

@@ -1,43 +1,65 @@
 # AIWiki Roadmap
 
-AIWiki 对外只有一个项目，所以这里写的是能力路线，不是版本分层。
+AIWiki has one public base product: a local Markdown knowledge base for AI assistants.
 
-公开试用和长期运营的完整路线图见：
+The roadmap keeps the base CLI focused. Advanced automation, crawling, multi-knowledge-base workflows, vector search, and team controls belong outside the base scope unless explicitly planned later.
 
-- [AIWiki 长期运营路线图](./20260607-aiwiki-long-term-operating-roadmap.md)
+## Current Focus
 
-## 1. 更稳的入库体验
+### 1. First-use success
 
-- 更顺的 setup 引导
-- 更清晰的 doctor 检查
-- 更稳定的 Agent handoff
-- 更完整的 Obsidian 审阅入口
-- 更容易追查失败原因
-- 更稳定的公开样例，让新用户先看到真实生成的核心产物
+- clearer assistant-first installation prompt
+- safer `agent sync` and workspace guidance
+- better `agent check` diagnostics
+- a clean path from setup to first ingest to first query
 
-## 2. 更完整的内容处理能力
+### 2. Reusable local knowledge
 
-- 更好用的资料卡
-- 更清楚的 Claim / Evidence 建议
-- 更顺手的选题候选
-- 更稳定的大纲生成
-- 更好复用的模板和输出结构
+- clearer Wiki Entry quality signals
+- better query/context explanations
+- more examples showing writing, research, decision, and review workflows
+- stronger distinction between external sources and user-authored output
 
-## 3. 更适合团队和自动化部署
+### 3. Workspace health
 
-- 更多宿主 Agent 接入方式
-- 更适合团队协作的知识库目录
-- 更完善的部署说明
-- 更清楚的诊断和支持入口
-- 更好的服务化落地方式
+- practical lint output for humans and assistants
+- safe automatic fixes only when the fix is narrow and reversible
+- better status and doctor guidance
+- fewer empty optional artifacts in new workspaces
 
-## 4. 服务层能力
+### 4. Public trial assets
 
-公开软件还是 AIWiki 本身。后续如果要做商业化，重点会放在：
+- short use cases users can complete in 5-10 minutes
+- example vaults that match the current CLI behavior
+- WeChat group feedback templates
+- a queue policy that separates user pain from feature creep
 
-- 部署服务
-- 陪跑服务
-- 团队集成服务
-- 技术支持服务
+## Not in the Base Queue
 
-这些都属于服务层，不是把 AIWiki 拆成多个软件版本。
+The base AIWiki CLI is not currently planning:
+
+- web crawling
+- WeChat Official Account reading
+- browser plugins
+- vector search
+- RAG-over-wiki
+- multiple knowledge bases
+- RBAC
+- RSS or scheduled collection
+- default manual review workflow
+- automatic Dataview or Obsidian plugin installation
+
+These may become separate service-layer, integration, or Pro-adjacent projects, but they should not blur the base README promise.
+
+## Operating Principle
+
+AIWiki should stay boring in the right places:
+
+```text
+assistant reads
+AIWiki writes
+Markdown stays local
+context can be reused later
+```
+
+The product gets better when the first ingest, first query, and first maintenance pass become more reliable.