@biaoo/tiangong-wiki 0.2.0 → 0.2.2

package/README.md

@@ -24,6 +24,21 @@
 npm install -g @biaoo/tiangong-wiki
 ```
 
+## Update
+
+Upgrade the npm package itself:
+
+```bash
+npm install -g @biaoo/tiangong-wiki@latest
+```
+
+Refresh workspace-local managed skills after upgrading the CLI or when upstream skill content changes:
+
+```bash
+tiangong-wiki skill status
+tiangong-wiki skill update --all
+```
+
 <details>
 <summary><strong>Use as an AI Agent Skill</strong></summary>
 
@@ -41,17 +56,36 @@ Or let the setup wizard handle everything:
 tiangong-wiki setup
 ```
 
+To manage workspace-local skills from arbitrary repo/path sources after setup:
+
+```bash
+tiangong-wiki skill add ../my-skills --skill notes
+tiangong-wiki skill status
+tiangong-wiki skill update notes
+tiangong-wiki skill update --all
+```
+
 </details>
 
 ## Quick Start
 
 ```bash
+cd /path/to/your/workspace                           # run commands from the workspace root
 tiangong-wiki setup                                   # interactive config wizard
 tiangong-wiki doctor                                  # verify configuration
 tiangong-wiki init                                    # initialize workspace
 tiangong-wiki sync                                    # index Markdown pages
 ```
 
+`tiangong-wiki setup` creates a workspace-local `.wiki.env` and records it as your default workspace config. Command resolution now follows this order:
+
+1. `--env-file <path>`
+2. `WIKI_ENV_FILE`
+3. The nearest `.wiki.env` found by walking upward from your current directory
+4. The global default workspace config written by `tiangong-wiki setup`
+
+That means commands still work best from inside a workspace, but they can also run from outside the workspace after setup, or target a specific workspace explicitly with `--env-file`.
+
 ```bash
 tiangong-wiki find --type concept --status active     # structured query
 tiangong-wiki fts "Bayesian"                          # full-text search
@@ -60,16 +94,17 @@ tiangong-wiki graph bayes-theorem --depth 2           # graph traversal
 ```
 
 ```bash
-tiangong-wiki daemon run                              # start dashboard & HTTP API
+tiangong-wiki daemon start                            # start the daemon in the background
 tiangong-wiki dashboard                               # open dashboard in browser
+# or: tiangong-wiki daemon run                        # run the daemon in the foreground for debugging
 ```
 
-> Environment variables are managed via `.wiki.env` (created by `tiangong-wiki setup`). See [references/env.md](./references/env.md) for the full reference.
+> Environment variables are managed via `.wiki.env` (created by `tiangong-wiki setup`). The CLI prefers the nearest local `.wiki.env`, then falls back to the global default workspace config. See [references/troubleshooting.md](./references/troubleshooting.md) for the full reference.
 
 ## CLI
 
 ```
-Setup         setup · doctor · check-config
+Setup         setup · skill · doctor · check-config
 Indexing      init · sync
 Query         find · fts · search · graph
 Inspect       list · page-info · stat · lint
@@ -84,53 +119,7 @@ See [references/cli-interface.md](./references/cli-interface.md) for the full co
 
 ## Architecture
 
-```
-┌──────────────────────────────────────────────────────────┐
-│                     Vault (raw input)                     │
-│           PDFs, docs, notes, bookmarks, clippings         │
-└────────────────────────┬─────────────────────────────────┘
-                         │ vault diff / vault queue
-                         ▼
-┌──────────────────────────────────────────────────────────┐
-│              Agentic Workflow (Codex SDK)                 │
-│                                                          │
-│  ┌─────────┐  read    ┌────────────┐  discover  ┌─────┐ │
-│  │ Parser  │ ──────►  │ tiangong-wiki-skill │ ────────►  │ LLM │ │
-│  │ Skills  │  source  │ find / fts │  + decide  │     │ │
-│  └─────────┘          └────────────┘            └─────┘ │
-│  pdf · docx · pptx                                       │
-│                                                          │
-│  → skip / create page / update page / propose only       │
-└────────────────────────┬─────────────────────────────────┘
-                         │ write pages
-                         ▼
-┌──────────────────────────────────────────────────────────┐
-│                    Markdown Pages (SSOT)                  │
-│                    wiki/pages/**/*.md                     │
-└────────────────────────┬─────────────────────────────────┘
-                         │ tiangong-wiki sync
-                         ▼
-┌──────────────────────────────────────────────────────────┐
-│                   SQLite Index (index.db)                 │
-│                                                          │
-│  pages          structured metadata (dynamic columns)    │
-│  pages_fts      FTS5 full-text search                    │
-│  vec_pages      sqlite-vec vector embeddings             │
-│  edges          knowledge graph (source → target)        │
-└──┬───────────┬───────────┬───────────┬───────────────────┘
-   │           │           │           │
-   ▼           ▼           ▼           ▼
-  find        fts       search       graph
-   │           │           │           │
-   └───────────┴───────────┴───────────┘
-                     │
-                     ▼
-          JSON stdout / HTTP daemon
-                     │
-        ┌────────────┴────────────┐
-        ▼                         ▼
-   CLI / Scripts            Web Dashboard
-```
+![Tiangong-Wiki: The Persistent AI Knowledge Framework](./assets/tiangong-wiki-framework.png)
 
 **Vault → Pages** — Raw materials land in the vault. An agentic workflow reads each file, discovers the current ontology via `tiangong-wiki type list / find / fts`, and decides whether to skip, create, or update a page.
 

package/README.zh-CN.md

@@ -24,6 +24,21 @@
 npm install -g @biaoo/tiangong-wiki
 ```
 
+## 更新
+
+升级 npm 包本身：
+
+```bash
+npm install -g @biaoo/tiangong-wiki@latest
+```
+
+升级 CLI 后，或上游 skill 内容有更新时，刷新工作区本地 managed skills：
+
+```bash
+tiangong-wiki skill status
+tiangong-wiki skill update --all
+```
+
 <details>
 <summary><strong>作为 AI Agent Skill 使用</strong></summary>
 
@@ -41,17 +56,36 @@ npx skills add Biaoo/tiangong-wiki -a codex -g       # 全局安装（跨项目
 tiangong-wiki setup
 ```
 
+如果需要把任意 repo/path 来源的 skill 作为工作区本地 managed skill 管理，可以继续使用：
+
+```bash
+tiangong-wiki skill add ../my-skills --skill notes
+tiangong-wiki skill status
+tiangong-wiki skill update notes
+tiangong-wiki skill update --all
+```
+
 </details>
 
 ## 快速开始
 
 ```bash
+cd /path/to/your/workspace                           # 在工作区根目录执行命令
 tiangong-wiki setup                                   # 交互式配置向导
 tiangong-wiki doctor                                  # 验证配置
 tiangong-wiki init                                    # 初始化工作区
 tiangong-wiki sync                                    # 索引 Markdown 文件
 ```
 
+`tiangong-wiki setup` 会创建工作区本地 `.wiki.env`，并将其记录为默认工作区配置。CLI 的配置解析优先级如下：
+
+1. `--env-file <path>`
+2. `WIKI_ENV_FILE`
+3. 从当前目录向上查找最近的 `.wiki.env`
+4. `tiangong-wiki setup` 写入的全局默认工作区配置
+
+这意味着命令仍然最适合在 workspace 内执行；但 setup 之后，即使在 workspace 外运行，也可以通过默认配置正常工作，或者通过 `--env-file` 显式指定目标工作区。
+
 ```bash
 tiangong-wiki find --type concept --status active     # 结构化查询
 tiangong-wiki fts "贝叶斯"                             # 全文搜索
@@ -60,16 +94,17 @@ tiangong-wiki graph bayes-theorem --depth 2           # 图遍历
 ```
 
 ```bash
-tiangong-wiki daemon run                              # 启动仪表盘和 HTTP API
+tiangong-wiki daemon start                            # 后台启动 daemon
 tiangong-wiki dashboard                               # 在浏览器中打开仪表盘
+# 或者：tiangong-wiki daemon run                      # 前台运行 daemon，适合调试
 ```
 
-> 环境变量通过 `.wiki.env` 管理（由 `tiangong-wiki setup` 创建）。完整参考见 [references/env.md](./references/env.md)。
+> 环境变量通过 `.wiki.env` 管理（由 `tiangong-wiki setup` 创建）。CLI 会优先使用最近的本地 `.wiki.env`，找不到时再 fallback 到全局默认工作区配置。完整参考见 [references/troubleshooting.md](./references/troubleshooting.md)。
 
 ## CLI
 
 ```
-配置引导      setup · doctor · check-config
+配置引导      setup · skill · doctor · check-config
 索引管理      init · sync
 查询          find · fts · search · graph
 自省          list · page-info · stat · lint
@@ -84,53 +119,7 @@ Vault        vault list | diff | queue
 
 ## 技术架构
 
-```
-┌──────────────────────────────────────────────────────────┐
-│                    Vault（原始素材）                        │
-│           PDF、文档、笔记、书签、剪藏                        │
-└────────────────────────┬─────────────────────────────────┘
-                         │ vault diff / vault queue
-                         ▼
-┌──────────────────────────────────────────────────────────┐
-│              Agentic Workflow（Codex SDK）                 │
-│                                                          │
-│  ┌─────────┐  解析    ┌────────────┐  发现体系  ┌─────┐  │
-│  │ Parser  │ ──────►  │ tiangong-wiki-skill │ ────────► │ LLM │  │
-│  │ Skills  │  素材    │ find / fts │  + 决策   │     │  │
-│  └─────────┘          └────────────┘           └─────┘  │
-│  pdf · docx · pptx                                       │
-│                                                          │
-│  → 跳过 / 创建页面 / 更新页面 / 仅提议                      │
-└────────────────────────┬─────────────────────────────────┘
-                         │ 写入页面
-                         ▼
-┌──────────────────────────────────────────────────────────┐
-│               Markdown 页面（唯一真实来源）                  │
-│                    wiki/pages/**/*.md                     │
-└────────────────────────┬─────────────────────────────────┘
-                         │ tiangong-wiki sync
-                         ▼
-┌──────────────────────────────────────────────────────────┐
-│                  SQLite 索引 (index.db)                    │
-│                                                          │
-│  pages          结构化元数据（动态列）                       │
-│  pages_fts      FTS5 全文搜索                              │
-│  vec_pages      sqlite-vec 向量嵌入                        │
-│  edges          知识图谱（source → target）                 │
-└──┬───────────┬───────────┬───────────┬───────────────────┘
-   │           │           │           │
-   ▼           ▼           ▼           ▼
-  find        fts       search       graph
-   │           │           │           │
-   └───────────┴───────────┴───────────┘
-                     │
-                     ▼
-          JSON stdout / HTTP daemon
-                     │
-        ┌────────────┴────────────┐
-        ▼                         ▼
-   CLI / 脚本              Web 仪表盘
-```
+![Tiangong-Wiki：持久化 AI 知识框架](./assets/tiangong-wiki-framework.png)
 
 **Vault → Pages** — 原始素材进入 vault，Agentic Workflow 逐个阅读，通过 `tiangong-wiki type list / find / fts` 发现当前知识体系，决定跳过、创建或更新页面。
 

package/SKILL.md

@@ -1,116 +1,84 @@
 ---
 name: tiangong-wiki-skill
-description: "Local-first wiki query and page-maintenance interface over Markdown knowledge pages indexed into SQLite. Use when an agent should discover existing knowledge before answering, inspect vault changes or queue state, choose how new durable knowledge fits the current ontology, or create/update wiki pages in a local knowledge workspace."
+description: "Use when you need to retrieve historically accumulated knowledge, methods, or behavioral patterns before answering or acting; when a conversation or workflow produces durable insights worth preserving for future reuse; or when you discover existing wiki content that is outdated or incorrect and needs correction."
 ---
 
 # Wiki Skill
 
 ## Core Goal
-- Use the local wiki as the durable knowledge layer for future work, not just the current conversation.
-- Query SQLite first, then read or edit the Markdown files that remain the source of truth.
-- Treat page types as runtime-discovered ontology. Do not hardcode a default destination for new knowledge.
-
-## Use When
-Use `tiangong-wiki-skill` when:
-- You should check whether the answer already exists in the local wiki before writing a fresh answer.
-- You need to inspect the current ontology, template structure, or type recommendations before creating a page.
-- A durable insight, correction, workflow, lesson, or source-derived knowledge should be preserved for reuse.
-- New files appeared in `vault/` and you need to inspect `vault diff` or `vault queue` before deciding what knowledge work to do.
-- You need a structured view of the graph, stale content, orphan pages, provenance, or general workspace health.
-- You need to create or update a page and immediately re-index it.
-
-## Retrieval Strategy
-- Exact metadata, type, tag, status, node id, or dynamic column filter: `tiangong-wiki find`
-- Keyword or short literal clue: `tiangong-wiki fts`
-- Fuzzy natural-language retrieval with embeddings configured: `tiangong-wiki search`
-- Graph neighborhood, prerequisites, or multi-hop relations: `tiangong-wiki graph`
-- Single-page metadata, edges, provenance, or file path: `tiangong-wiki page-info`
-- Workspace inventory or health: `tiangong-wiki list`, `tiangong-wiki stat`, `tiangong-wiki lint`
-- Ontology discovery: `tiangong-wiki type list`, `tiangong-wiki type show`, `tiangong-wiki type recommend`
-- Vault ingestion status: `tiangong-wiki vault diff`, `tiangong-wiki vault list`, `tiangong-wiki vault queue`
-
-## Knowledge Capture Workflow
-Use this when new knowledge should become part of the wiki.
-
-1. Query for close existing pages with `tiangong-wiki find`, `tiangong-wiki fts`, or `tiangong-wiki search`.
-2. Discover the current ontology with:
-   - `tiangong-wiki type list --format json`
-   - `tiangong-wiki type show <type> --format json`
-   - `tiangong-wiki type recommend --text "<summary>" --keywords "a,b,c" --format json`
-3. Update the best existing page when the knowledge object already exists.
-4. Create a new page only when the knowledge object is distinct and the current ontology supports it cleanly.
-5. Edit the Markdown file directly.
-6. Run `tiangong-wiki sync --path <page-id>`.
-7. Run `tiangong-wiki lint --path <page-id> --format json`.
-
-```bash
-tiangong-wiki find --type method --tag evidence
-tiangong-wiki type list --format json
-tiangong-wiki type recommend --text "A repeatable workflow for evidence review" --keywords "workflow,procedure" --limit 5 --format json
-tiangong-wiki create --type method --title "Evidence Review Workflow"
-tiangong-wiki sync --path methods/evidence-review-workflow.md
-tiangong-wiki lint --path methods/evidence-review-workflow.md --format json
-```
-
-## Vault Review Workflow
-Use this when `vault/` may contain source files that should influence wiki knowledge.
-
-1. Run `tiangong-wiki sync` to refresh indexes, vault metadata, and queue state.
-2. Inspect recent vault changes with `tiangong-wiki vault diff`.
-3. Inspect queue state with `tiangong-wiki vault queue`.
-4. Discover the ontology through `tiangong-wiki type list/show/recommend` before deciding what to create or update.
-5. Preserve provenance with `sourceRefs` and any source-specific fields required by the chosen page type.
-6. Remember that `source-summary` is only one possible type. A vault file may lead to `skip`, an update to an existing page, a new page of any registered type, or a proposal to evolve the ontology.
-
-```bash
-tiangong-wiki sync
-tiangong-wiki vault diff
-tiangong-wiki vault queue
-tiangong-wiki type list --format json
-tiangong-wiki type recommend --text "Operational brief about evidence review" --keywords "operations,evidence" --limit 5 --format json
-tiangong-wiki find --type method --tag evidence
-```
-
-## Maintenance Rules
-- Do not assume any single page type is the default landing zone for vault files.
-- Prefer updating the best existing page before creating near-duplicates.
-- Use CLI discovery instead of static assumptions about templates or registered types.
-- If the current ontology is not a clean fit, consider template evolution deliberately; do not improvise undocumented structure.
-- After every mutation, re-index and lint the changed page before trusting query results.
-
-## Layer Boundary
-- `SKILL.md` describes the on-demand skill interface used by agents during queries and manual knowledge maintenance.
-- Automatic vault-to-wiki processing, daemon scheduling, queue retries, NAS polling, and workflow artifacts belong to the service layer.
-- Service-layer operations are documented in `references/service-admin.md`.
-
-## Environment Contract
-Required:
-- `WIKI_PATH`
-
-Optional for semantic retrieval or vector-based type recommendation:
-- `EMBEDDING_BASE_URL`
-- `EMBEDDING_API_KEY`
-- `EMBEDDING_MODEL`
-- `EMBEDDING_DIMENSIONS`
-
-Automatic vault processing uses additional `WIKI_AGENT_*` variables, but those belong to the service layer rather than the skill interface. Read `references/service-admin.md` when operating the daemon or queue worker.
-
-## Output Contract
-- Query commands return JSON to stdout.
-- Mutating commands return JSON summaries or created file paths to stdout.
-- `lint`, `check-config`, `template list/show`, `type list/show/recommend`, and `daemon status` support text or JSON output where documented.
-- Errors are emitted as structured JSON to stderr with `type=config|runtime|not_found|not_configured`.
-
-## References
-- `references/cli-interface.md`
-- `references/data-model.md`
-- `references/template-design-guide.md`
-- `references/runtime.md`
-- `references/env.md`
-- `references/wiki-maintenance-instruction.md`
-- `references/vault-to-wiki-instruction.md`
-- `references/service-admin.md`
+
+Use the local wiki as the **durable knowledge layer** — not just for the current conversation, but for all future work. Query first, then read or edit the Markdown files that remain the source of truth.
+
+## When to Use
+
+Activate this skill in three scenarios:
+
+### 1. Knowledge Retrieval
+
+You need historical knowledge, methods, behavioral patterns, or prior decisions before answering or acting.
+
+**Trigger:** The current task could benefit from previously captured insights, or the user asks about something that may already exist in the wiki.
+
+**Minimal steps:**
+1. Choose a retrieval strategy based on what you know:
+   - Know the type, tag, or metadata → `tiangong-wiki find`
+   - Have a keyword or short phrase → `tiangong-wiki fts`
+   - Fuzzy intent, embeddings configured → `tiangong-wiki search`
+   - Need graph context or related pages → `tiangong-wiki graph`
+2. Inspect the best candidate with `tiangong-wiki page-info <id>`.
+3. Read the Markdown file if you need full content.
+
+**Stop when:** you have enough context to proceed, or no relevant pages exist.
+
+### 2. Knowledge Capture
+
+A conversation, task, or other skill produced a high-value insight, method, correction, or piece of information worth preserving.
+
+**Trigger:** You recognize durable knowledge — something that would be useful to retrieve in a future context.
+
+**Two paths:**
+
+- **Direct page creation** — when you can clearly identify the page type and structure the content yourself:
+  1. Search for existing pages to avoid duplicates (`find`, `fts`, or `search`).
+  2. Discover the ontology: `tiangong-wiki type recommend --text "<summary>" --keywords "a,b,c" --format json`.
+  3. Update an existing page if one covers the same knowledge object. Create a new page only when the object is distinct.
+  4. After writing: `tiangong-wiki sync --path <page-id>` then `tiangong-wiki lint --path <page-id> --format json`.
+
+- **Save to vault** — when the material is raw, complex, or needs further processing:
+  1. Save the file to `vault/`.
+  2. The vault-to-wiki workflow will handle triage and page creation.
+  3. See `references/vault-to-wiki-instruction.md` for the full decision model.
+
+**Key rules:**
+- Do not assume any page type is the default destination. Always discover via CLI.
+- Prefer updating the best existing page over creating near-duplicates.
+- Only use frontmatter fields declared by the chosen type (`tiangong-wiki type show <type>`). Do not invent ad-hoc fields.
+- Preserve provenance with `sourceRefs` and type-specific source fields.
+
+### 3. Knowledge Maintenance
+
+You discover that existing wiki content is outdated, incorrect, or incomplete during retrieval or conversation.
+
+**Trigger:** A retrieved page contains stale information, or new evidence contradicts existing content.
+
+**Minimal steps:**
+1. Locate the page: `tiangong-wiki find` or `tiangong-wiki page-info <id>`.
+2. Edit the Markdown file — keep edits minimal and provenance-preserving.
+3. After editing: `tiangong-wiki sync --path <page-id>` then `tiangong-wiki lint --path <page-id> --format json`.
+
+**For systematic maintenance** (health checks, orphan cleanup, stale content review), see `references/wiki-maintenance-instruction.md`.
+
+## References (read on demand)
+
+| Document | Read when... |
+|----------|-------------|
+| `references/cli-interface.md` | You need full command options, flags, or output format details |
+| `references/vault-to-wiki-instruction.md` | Processing vault files into wiki pages |
+| `references/wiki-maintenance-instruction.md` | Running systematic maintenance or health checks |
+| `references/template-design-guide.md` | Designing a new page type or evolving an existing template |
+| `references/troubleshooting.md` | Environment setup, configuration issues, or error diagnosis |
 
 ## Assets
-- `assets/wiki.config.default.json`
-- `assets/templates/`
+
+- `assets/wiki.config.default.json` — default configuration template
+- `assets/templates/` — Markdown page templates for each registered type

package/assets/templates/achievement.md

@@ -15,18 +15,18 @@ issuer:
 verifiable: "yes"
 ---
 
-## 成就描述
+## What
 
-简洁但具体地写出这项成就是什么，以及它代表了什么结果。
+State the achievement in one factual sentence. Include the scope, level, and issuing context. Do not editorialize — let the facts speak.
 
-## 获得过程
+## How
 
-说明获得这项成就经历了哪些关键步骤、难点和投入，而不是只写最终结果。
+Describe the key steps, investment, and challenges involved in earning this achievement. Focus on what is quantifiable or verifiable: duration, scale, constraints overcome. Do not write a narrative essay.
 
-## 能力体现
+## Demonstrated Capabilities
 
-解释这项成就证明了哪些能力、经验或可信度，方便后续被 resume 或 profile 引用。
+List the specific capabilities this achievement provides evidence for. Use terms that other pages (resume, person) can reference. Think of this as a reusable capability tag set.
 
-## 证明材料
+## Evidence
 
-列出证书、链接、发布记录、截图或其他可核验证据，并同步到 sourceRefs。
+Provide verifiable proof: certificate links, publication URLs, official records, screenshots, or third-party references. If the achievement claims to be verifiable (frontmatter `verifiable: "yes"`), this section must contain at least one checkable item.

package/assets/templates/bridge.md

@@ -16,18 +16,18 @@ fromConcepts: []
 toConcepts: []
 ---
 
-## 来源知识
+## Source Knowledge
 
-写清楚这个迁移起点来自什么课程、项目、领域或知识体系。
+Identify the origin domain, course, or knowledge system. Link to existing concept or method pages that represent the source-side knowledge being transferred. When a source-side concept already has a node in the wiki, record its nodeId in frontmatter `fromConcepts` instead of leaving the mapping only in prose.
 
-## 目标场景
+## Target Scenario
 
-写清楚这个迁移最终要解决什么目标问题，以及目标场景里的限制条件。
+Describe the target problem, domain, or context where the source knowledge is being applied. State the constraints and requirements specific to the target that make direct transfer non-trivial.
 
-## 迁移方式
+## Transfer Mapping
 
-分步骤说明原知识是如何被翻译、映射或改造后用于目标场景的。
+Describe how each source-side concept or method maps to its target-side equivalent. Use explicit A → B mappings where possible. For each mapping, note what adapts cleanly and what requires modification. Use the body to explain the mapping, and keep `fromConcepts` / `toConcepts` in sync for the key nodes so the graph retains the structure.
 
-## 迁移陷阱
+## Invalid Transfers
 
-指出最容易误迁移的地方，以及哪些条件不满足时这个 bridge 不应复用。
+State the conditions under which this bridge breaks down. Which assumptions from the source domain do not hold in the target? What would go wrong if the transfer were applied without these caveats?

package/assets/templates/concept.md

@@ -14,34 +14,30 @@ masteryLevel: medium
 prerequisites: []
 ---
 
-## 核心理解
+## Definition
 
-用两到四句话说明这个概念到底是什么，以及它为什么值得记住。
+Provide a precise, quotable definition of this concept. A reader should be able to cite this section without additional context. Do not write an introductory paragraph — write the definition.
 
-## 前置知识
+## Prerequisites
 
-列出理解这个概念之前必须已经掌握的知识、术语或背景。
+List the concepts, terms, or background knowledge required to understand this one. Link to existing wiki pages where possible.
 
-## 关键公式/定义
+## Formal Specification
 
-写下最关键的定义、公式、判别标准或符号约定，不要只写标题。
+Write the key formulas, criteria, thresholds, or formal rules that define this concept's behavior. If the concept has no formal specification, describe the decision boundary — under what conditions does something qualify as this concept vs. not?
 
-## 直觉/类比
+## Intuition & Analogy
 
-用一个直觉模型、类比或反例帮助未来的读者快速建立感觉。
+Provide one mental model, analogy, or worked example that builds correct intuition quickly. Prefer concrete examples over abstract explanations.
 
-## 典型应用
+## Typical Applications
 
-说明这个概念通常在哪些问题、项目或课程场景里真正会被用到。
+Name specific problems, project types, or domains where this concept is actively used. Do not list hypothetical uses — list real or well-documented ones.
 
-## 容易混淆
+## Boundary & Confusion
 
-写出它最容易和什么混淆，以及区分它们的判断线索。
+State what this concept is most easily confused with, and the specific test or criterion that distinguishes them. Do not just say "they are different" — describe what input or situation would produce a different outcome under each.
 
-## 开放问题
+## Open Questions
 
-记录你当前还没完全吃透的点、边界条件或后续要继续查的内容。
-
-## 来源
-
-说明这个概念主要来自哪些来源，并确保这些来源同步写入 frontmatter 的 sourceRefs。
+Record what remains unclear, what edge cases are unresolved, or what further investigation is needed. This section is expected to shrink as confidence increases.

package/assets/templates/faq.md

@@ -12,20 +12,18 @@ updatedAt: 2026-04-06
 frequency:
 ---
 
-## 问题
+## Question
 
-用用户真实会问出来的语言写下这个高频问题，而不是抽象化改写。
+Write the question in the exact phrasing a real person would use. Do not abstract, rephrase, or make it sound formal — preserve the natural language of the asker.
 
-## 简短回答
+## Quick Answer
 
-先给出一段可以直接复用的短答案，方便快速回复。
+Provide a self-contained answer in 2-3 sentences that can be directly reused in a reply. It must be correct and complete enough to stand alone without reading further.
 
-## 详细解释
+## Full Explanation
 
-补充条件、例外、例子和判断边界，说明为什么短答案成立。
+Expand with conditions, exceptions, edge cases, and examples. Explain why the quick answer is correct and under what circumstances it might not apply.
 
-## 相关概念
+## Related Pages
 
-列出应当一起阅读的 concept、method 或 source-summary 页面，帮助继续深入。
-
-如果这个问题已经不再高频，也请在正文里说明是否应该降级维护或归档。
+Link to concept, method, or source-summary pages that provide deeper context. Use relatedPages frontmatter to keep these connections in the graph.

package/assets/templates/lesson.md

@@ -14,18 +14,18 @@ severity: medium
 actionable: "yes"
 ---
 
-## 发生了什么
+## Event
 
-按事实顺序描述事件经过、背景条件和真正触发结果的关键节点。
+Describe what happened — only the facts that are necessary to understand the lesson. Do not write a chronological narrative; keep only the causal chain that led to the outcome.
 
-## 从中学到了什么
+## Stable Rule
 
-提炼这次事件留下的稳定认知，而不是只重复事件本身。
+State the durable insight extracted from this event. This should be a general rule or principle that applies beyond this specific incident. If you cannot state it as a rule, reconsider whether this is truly a lesson or just an event record.
 
-## 以后怎么做
+## Action Protocol
 
-写出未来遇到相似情况时的行动规则、检查步骤或预防动作。
+Write the concrete actions, checklist items, or decision rules to follow when a similar situation arises. Each item should be executable — "be more careful" is not an action.
 
-## 验证
+## Verification
 
-说明你打算如何验证这个 lesson 真的能改善结果，而不是停留在口头总结。
+Describe how you would test whether this lesson actually improves outcomes. What would you measure? What would indicate the lesson was applied correctly vs. ignored?