dominds 1.17.1 → 1.17.2

package/README.md

@@ -55,7 +55,7 @@ Dominds is an AI-powered DevOps framework that creates autonomous agentic teams
 
 - **Local-first Runtime**: The orchestration layer runs on your machine and persists team state locally in your rtws (runtime workspace). LLM calls still go to your configured provider (so apply normal cost/privacy discipline).
 
-- **Transparent rtws Integration**: Agent knowledge, personas, lessons learned, and mindset artifacts are stored locally as part of your rtws. This maximizes transparency to humans and enables version control alongside your product code, creating a complete historical record of both human and AI contributions to your project.
+- **Transparent rtws Integration**: Agent personas, know-how, pitfalls, and other mindset artifacts are stored locally as part of your rtws. This maximizes transparency to humans and enables version control alongside your product code, creating a complete historical record of both human and AI contributions to your project.
 
 - **Persistent Team Memory**: Agents maintain context across conversations, remember past decisions, and build upon learned patterns. Teams evolve their practices and knowledge over time, with all insights preserved in your rtws.
 
@@ -280,7 +280,7 @@ Result: fewer bad side effects, higher plan fidelity, and more first‑try succe
 > Start from a template team, then curate and evolve both individual and shared memory as versioned artifacts.
 
 - Bootstrap from a domain-specific scaffold (team + workflows).
-- Keep individual and shared memory in `.minds/**` (personas, lessons, playbooks).
+- Keep individual and shared memory in `.minds/**` (personas, know-how, pitfalls, playbooks).
 - Evolve mindsets and governance as the product evolves.
 - Keep it transparent to humans: plain Markdown, version-tracked.
 

package/README.zh.md

@@ -192,7 +192,7 @@ Dominds 面向“长期开发运作（DevOps）”场景设计，基于社会化
 > 基于模板快速搭建团队，将个体及团队记忆作为版本追踪的数字资产，持续迭代优化。
 
 - 通过领域模板引导团队职责划分与工作流搭建
-- 将角色设定（personas）、经验教训（lessons）、操作手册（playbooks）存入 `.minds/**` 目录，对于人类完全透明，方便阅读审核
+- 将角色设定（personas）、经验知识（knowhow）、避坑指南（pitfalls）、操作手册（playbooks）存入 `.minds/**` 目录，对于人类完全透明，方便阅读审核
 - 伴随产品迭代，同步升级治理模式与团队结构
 
 ## 相关文档

package/dist/docs/app-constitution.md

@@ -70,7 +70,7 @@ Goal: let an integrator app ship publishable default overrides for dependency ap
 
 - Key capabilities (target):
   - app override: app packages may ship default overrides for dependency apps (publishable integration config), while rtws overrides still take precedence.
-  - Override surface expands to more `.minds/**` assets (persona/knowledge/lessons, memory, mcp, etc.).
+  - Override surface expands to more `.minds/**` assets (persona/knowhow/pitfalls, memory, mcp, etc.).
   - Problems mechanism enhancements: record and display “occurred at / resolved at / resolved state”, and allow “clear resolved” in UI.
   - More complete error-path contracts (corrupt YAML, partial availability, recovery strategy) with regression coverage.
 
@@ -360,7 +360,7 @@ So `Web Dev App` should make the `playwright-interactive` relationship explicit
 1. **Product-semantic layer (in scope for this design)**
    - define a stable toolset name such as `playwright_interactive`;
    - define which teammates receive it, what problem it solves, and when to use it;
-   - ship the related `.minds/team.yaml`, member persona/knowledge/lessons, `.minds/env.md`, toolset manual, etc.
+   - ship the related `.minds/team.yaml`, member persona/knowhow/pitfalls, `.minds/env.md`, toolset manual, etc.
 2. **Execution-backend layer (replaceable implementation detail)**
    - the app may provide its own dedicated tools and productize a browser-interaction capability in the same family as `playwright-interactive`;
    - or later be replaced by an equivalent MCP server / local App Host module;
@@ -368,7 +368,7 @@ So `Web Dev App` should make the `playwright-interactive` relationship explicit
 
 It must be explicit that **an app is not the same thing as a skill**, and that both are now first-class mechanisms in the current implementation:
 
-- An **app** is a Dominds install/resolve/composition unit. It has an `id`, a manifest (`.minds/app.yaml`), team-facing assets (`.minds/team.yaml`, persona/knowledge/lessons), env docs (`.minds/env.md`), and participates in rtws-level lock/configuration/resolution.
+- An **app** is a Dominds install/resolve/composition unit. It has an `id`, a manifest (`.minds/app.yaml`), team-facing assets (`.minds/team.yaml`, persona/knowhow/pitfalls), env docs (`.minds/env.md`), and participates in rtws-level lock/configuration/resolution.
 - A **skill** is a pure-Markdown capability asset inside the rtws. It is currently loaded from `.minds/skills/team_shared/**` and `.minds/skills/individual/**`, selects `SKILL.cn.md` / `SKILL.en.md` / `SKILL.md` by work language preference, and injects the body directly into the agent system prompt. It is best suited for soft guidance, checklists, decision heuristics, and team-specific methods, not for distributable product capability that depends on a stable tool contract.
 - Skill frontmatter currently supports `name`, `description`, `allowed-tools`, `user-invocable`, and `disable-model-invocation`; the last three are currently compatibility/migration metadata only. They do not automatically grant tool permissions and do not replace team/toolset runtime policy.
 - A **toolset manual / app-bundled manual** is a better place for guidance that is shipped together with tools: it is skill-like in tone, but distributed together with dedicated tools, toolsets, and app identity. That is a better fit for something like `web-dev`.
@@ -424,12 +424,12 @@ Suggested minimal asset shape:
 │   └── team/
 │       ├── web_tester/
 │       │   ├── persona.zh.md
-│       │   ├── knowledge.zh.md
-│       │   └── lessons.zh.md
+│       │   ├── knowhow.zh.md
+│       │   └── pitfalls.zh.md
 │       └── web_developer/
 │           ├── persona.zh.md
-│           ├── knowledge.zh.md
-│           └── lessons.zh.md
+│           ├── knowhow.zh.md
+│           └── pitfalls.zh.md
 ├── bin/
 │   └── <app>.js
 └── src/
@@ -506,7 +506,7 @@ Why this app shape matters:
 Intended uses:
 
 - store overrides for app assets.
-- provide complete override capability beyond team config, including persona/knowledge/lessons and memory.
+- provide complete override capability beyond team config, including persona/knowhow/pitfalls and memory.
 
 > Note: “runtime state” and “override” can be split structurally. This document focuses on override semantics and paths.
 
@@ -538,7 +538,7 @@ To allow an app to fully ship a reusable “team + knowledge/persona” bundle,
 - `.minds/team.yaml`
 - `.minds/mcp.yaml`
 - `.minds/env.md`
-- `.minds/team/<memberId>/{persona,knowledge,lessons}.md` and work-language variants (e.g. `persona.zh.md`)
+- `.minds/team/<memberId>/{persona,knowhow,pitfalls}.md` and work-language variants (e.g. `persona.zh.md`)
 - `.minds/memory/**` (shared + personal memory; see `dominds/main/tools/mem.ts` and `dominds/main/minds/load.ts`)
 
 #### Override example: pinning a dependency app port (v0 draft)
@@ -668,7 +668,7 @@ Analogy: in Node.js development, a repo is both source tree and working director
 
 ### cfg-only apps (configuration-only apps)
 
-(Target: planned) Allow “cfg-only apps” that do not contribute tools (no `contributes.tools`). They only ship `.minds/**` assets to reorganize AI teams (persona/knowledge/lessons/memory and related config).
+(Target: planned) Allow “cfg-only apps” that do not contribute tools (no `contributes.tools`). They only ship `.minds/**` assets to reorganize AI teams (persona/knowhow/pitfalls/memory and related config).
 
 This makes it possible that:
 

package/dist/docs/app-constitution.zh.md

@@ -69,7 +69,7 @@
 
 - 关键能力（目标）：
   - app override：app 包内可携带对依赖 app 的默认覆盖（作为 integrator 的可发布整合配置），且仍以 rtws override 为最高优先级。
-  - override 覆盖范围扩展到更多 `.minds/**` 资产（persona/knowledge/lessons、memory、mcp 等）。
+  - override 覆盖范围扩展到更多 `.minds/**` 资产（persona/knowhow/pitfalls、memory、mcp 等）。
   - Problems 机制增强：记录并展示“发生时间/解决时间/已解决状态”，并支持“一键清理已解决项目”。
   - 更完整的异常路径契约（损坏 YAML、部分可用、恢复策略）与回归覆盖。
 
@@ -359,7 +359,7 @@ Install JSON 是 app 与 Kernel/CLI 之间的**安装/运行握手载荷**。它
 1. **产品语义层（本次设计范围）**：
    - 定义一个稳定的工具集名，例如 `playwright_interactive`。
    - 规定哪些智能体队友拿到这个工具集、它解决什么问题、什么时候用。
-   - 配套 `.minds/team.yaml`、队友 persona/knowledge/lessons、`.minds/env.md`、工具集操作手册等资产。
+   - 配套 `.minds/team.yaml`、队友 persona/knowhow/pitfalls、`.minds/env.md`、工具集操作手册等资产。
 2. **执行后端层（后续实现可替换）**：
    - 可以由 app 自己提供一组专属工具，产品化一套与 `playwright-interactive` 同类的浏览器交互能力；
    - 也可以是未来替换成等价的 MCP server / 本地宿主模块；
@@ -367,7 +367,7 @@ Install JSON 是 app 与 Kernel/CLI 之间的**安装/运行握手载荷**。它
 
 这里必须明确 **app 与 skill 不是同一层概念**，而且两者在现有实现中都已经是正式机制：
 
-- **App** 是 Dominds 的安装/解析/组合单元：它有自己的 `id`、manifest（`.minds/app.yaml`）、团队资产（`.minds/team.yaml`、persona/knowledge/lessons）、环境说明（`.minds/env.md`），并可被 `dominds install` 纳入某个 rtws。
+- **App** 是 Dominds 的安装/解析/组合单元：它有自己的 `id`、manifest（`.minds/app.yaml`）、团队资产（`.minds/team.yaml`、persona/knowhow/pitfalls）、环境说明（`.minds/env.md`），并可被 `dominds install` 纳入某个 rtws。
 - **Skill** 是 rtws 内的纯 Markdown 技能资产：当前从 `.minds/skills/team_shared/**` 与 `.minds/skills/individual/**` 读取，按工作语言优先选择 `SKILL.cn.md` / `SKILL.en.md` / `SKILL.md`，并把正文直接注入智能体系统提示词。它更适合承载软性的操作指导、检查清单、判断口诀与团队特定方法学，而不是承载需要稳定工具契约的可分发产品能力。
 - Skill frontmatter 当前支持 `name`、`description`、`allowed-tools`、`user-invocable`、`disable-model-invocation`；其中后 3 项目前主要用于兼容/迁移语义，不会自动授予工具权限，也不会替代团队 / 工具集调度规则。
 - **工具集操作手册 / 随 App 附带的操作手册** 更适合表达“和工具一起分发的操作指导”：它的性质接近 skill，但会与专属工具、工具集和 App 身份一起打包，更适合像 `web-dev` 这种需要整体分发与安装解析的能力。
@@ -423,12 +423,12 @@ Web Dev App 需要明确区分三套命名，避免再次漂移：
 │   └── team/
 │       ├── web_tester/
 │       │   ├── persona.zh.md
-│       │   ├── knowledge.zh.md
-│       │   └── lessons.zh.md
+│       │   ├── knowhow.zh.md
+│       │   └── pitfalls.zh.md
 │       └── web_developer/
 │           ├── persona.zh.md
-│           ├── knowledge.zh.md
-│           └── lessons.zh.md
+│           ├── knowhow.zh.md
+│           └── pitfalls.zh.md
 ├── bin/
 │   └── <app>.js
 └── src/
@@ -505,7 +505,7 @@ members:
 用途：
 
 - 存放对 app 资产的覆盖（overrides）。
-- 覆盖范围需要足够完整（不仅是 team）：应包括 persona/knowledge/lessons、memory 等。
+- 覆盖范围需要足够完整（不仅是 team）：应包括 persona/knowhow/pitfalls、memory 等。
 
 > 说明：运行时状态（state）与覆盖层（override）在结构上可以拆分；本文先聚焦 override 语义与路径。
 
@@ -537,7 +537,7 @@ members:
 - `.minds/team.yaml`
 - `.minds/mcp.yaml`
 - `.minds/env.md`
-- `.minds/team/<memberId>/{persona,knowledge,lessons}.md` 及其工作语言版本（例如 `persona.zh.md`）
+- `.minds/team/<memberId>/{persona,knowhow,pitfalls}.md` 及其工作语言版本（例如 `persona.zh.md`）
 - `.minds/memory/**`（共享与个人记忆，见 `dominds/main/tools/mem.ts` 与 `dominds/main/minds/load.ts`）
 
 #### 覆盖示例：固化依赖 app 的端口（v0 草案）
@@ -666,7 +666,7 @@ Problem id 应体现“定义方 scope 的从属层级”，并保持短小稳
 
 ### cfg-only app（仅配置 app）
 
-（目标：拟实现）允许存在不注册工具（不 `contributes.tools`）的“cfg-only app”，它只提供 `.minds/**` 资产，用于 AI 团队的重组与知识/人格配置。
+（目标：拟实现）允许存在不注册工具（不 `contributes.tools`）的“cfg-only app”，它只提供 `.minds/**` 资产，用于 AI 团队的重组与 knowhow/pitfalls/人格配置。
 
 这使得：
 

package/dist/docs/dialog-persistence.md

@@ -62,8 +62,8 @@ rtws/
 │   ├── team/                 # Agent-specific configurations
 │   │   └── <member>/
 │   │       ├── persona.md    # Agent personality and role
-│   │       ├── knowledge.md  # Agent expertise and skills
-│   │       └── lessons.md    # Agent learning and adaptations
+│   │       ├── knowhow.md    # Agent positive know-how and proven methods
+│   │       └── pitfalls.md   # Agent anti-traps and negative lessons
 │   └── memory/               # rtws-persistent memories
 │       ├── team_shared/      # Team-shared memories (all `*.md` under this dir are loaded)
 │       │   └── *.md
@@ -121,17 +121,17 @@ providers:
 - Role-specific responsibilities and expertise
 - Collaboration preferences and patterns
 
-**Agent Knowledge** (`team/<member>/knowledge.md`):
+**Agent Know-How** (`team/<member>/knowhow.md`):
 
-- Technical expertise and specializations
-- Domain-specific knowledge and experience
-- Tool proficiencies and preferences
+- Positive, durable know-how and validated methods
+- Stable domain facts, conventions, and decision cues
+- Tool proficiencies, working preferences, and safety stance
 
-**Agent Lessons** (`team/<member>/lessons.md`):
+**Agent Pitfalls** (`team/<member>/pitfalls.md`):
 
-- Learning from past interactions and mistakes
-- Adaptation patterns and improvements
-- Performance optimizations and insights
+- Negative lessons and anti-traps
+- Risk signals, failure modes, and what not to repeat
+- “If X happens, do/avoid Y” style guardrails
 
 ### Memory Storage (`.minds/memory/`)
 

package/dist/docs/dialog-persistence.zh.md

@@ -60,8 +60,8 @@ rtws/
 │   ├── team/                 # 智能体特定配置
 │   │   └── <member>/
 │   │       ├── persona.md    # 智能体个性和角色
-│   │       ├── knowledge.md  # 智能体专业知识和技能
-│   │       └── lessons.md    # 智能体学习和适应
+│   │       ├── knowhow.md    # 智能体正向 know-how 与已验证方法
+│   │       └── pitfalls.md   # 智能体负向教训与避坑规则
 │   └── memory/               # rtws 持久化记忆
 │       ├── team_shared/      # 团队共享记忆（此目录下所有 `*.md` 都会被加载）
 │       │   └── *.md
@@ -119,17 +119,17 @@ providers:
 - 角色特定职责和专业技能
 - 协作偏好和模式
 
-**智能体知识** (`team/<member>/knowledge.md`)：
+**智能体经验知识** (`team/<member>/knowhow.md`)：
 
-- 技术专长和专业化
-- 领域特定知识和经验
-- 工具熟练度和偏好
+- 正向、可复用的 know-how 与已验证有效的方法
+- 稳定的领域事实、约定与判断依据
+- 工具熟练度、工作偏好与安全观
 
-**智能体经验** (`team/<member>/lessons.md`)：
+**智能体避坑指南** (`team/<member>/pitfalls.md`)：
 
-- 从过去交互和错误中学习
-- 适应模式和改进
-- 性能优化和见解
+- 负向经验教训与避坑规则
+- 风险信号、失败模式，以及哪些坑不要再踩
+- “出现 X 时做/避免 Y” 这类约束性指引
 
 ### 记忆存储 (`.minds/memory/`)
 

package/dist/docs/dominds-agent-collaboration.zh.md

@@ -31,7 +31,7 @@ Dominds 团队成员通常由以下几类信息组成：
 - **身份与职责**：这个成员负责什么，不负责什么。
 - **路由卡（`gofor` / `nogo`）**：告诉其他成员“什么时候应该找我”“什么事情不要找我”。
 - **能力边界**：模型、工具集、目录权限、是否能跑 shell、是否能改 `.minds/`、是否能维护团队记忆。
-- **长期心智**：`persona / knowledge / lessons`。
+- **长期心智**：`persona / knowhow / pitfalls`。
 
 对外部智能体来说，设计团队时不要先想“起几个炫酷角色名”，而要先想：每个成员是否对应了一个稳定职责包。
 
@@ -69,7 +69,7 @@ Dominds 团队成员通常由以下几类信息组成：
 - 什么时候应该把事情诉请给这个成员
 - 诉请后大概会得到什么帮助或产出
 
-它不应该替代完整的 `persona/knowledge/lessons`，也不应该塞满成员自己的全部操作细则。
+它不应该替代完整的 `persona/knowhow/pitfalls`，也不应该塞满成员自己的全部操作细则。
 
 如果你是外部智能体，要为用户设计团队，`gofor` 最适合写成“何时找我 + 我返回什么”的路由卡，而不是长篇职责描述。
 
@@ -386,7 +386,7 @@ Q4H 不是“顺手问一句”，而是一个正式的待答问题：
 - 让支线直接承担全局协调，却不给它差遣牒治理权。
 - 把所有协作都设计成长线诉请，导致上下文负担过重。
 - 把所有协作都设计成一次性诉请，导致持续工作线反复丢上下文。
-- 把 `gofor`、`persona`、`knowledge`、`lessons` 混成一坨。
+- 把 `gofor`、`persona`、`knowhow`、`pitfalls` 混成一坨。
 - 把关键约束留在聊天里，没有写进差遣牒或团队记忆。
 
 ## 给更强外部智能体的最后建议

package/dist/docs/i18n.md

@@ -15,10 +15,17 @@ Dominds has two independent language settings:
 
 ### Agent mindset loading (file preference)
 
-When loading an agent mindset document (e.g. `persona`, `knowledge`, `lessons`), prefer the work-language-specific filename first, then fall back to the default:
+When loading an agent mindset document (e.g. `persona`, `knowhow`, `pitfalls`), prefer the work-language-specific filename first, then follow the per-kind fallback order:
 
 1. `persona.<workLanguageCode>.md` (e.g. `persona.en.md` when work language is `en`)
 2. `persona.md`
+3. `knowhow.<workLanguageCode>.md` → `knowhow.md` → `knowledge.<workLanguageCode>.md` → `knowledge.md`
+4. `pitfalls.<workLanguageCode>.md` → `pitfalls.md` → `lessons.<workLanguageCode>.md` → `lessons.md`
+
+Migration note: `knowledge/lessons` are now legacy fallback names for rtws member files only. If a
+`knowhow` or `pitfalls` file exists, only the new file content is injected. Builtin minds only
+recognize canonical filenames and do not read legacy aliases. Rename promptly; future versions
+will remove legacy-name support after the transition period.
 
 Examples:
 

package/dist/docs/i18n.zh.md

@@ -15,10 +15,16 @@ Dominds 有两个独立的语言设置：
 
 ### 智能体思维加载（文件偏好）
 
-加载智能体思维文档（例如 `persona`、`knowledge`、`lessons`）时，优先使用工作语言特定的文件名，然后回退到默认：
+加载智能体思维文档（例如 `persona`、`knowhow`、`pitfalls`）时，优先使用工作语言特定的文件名，然后按各类型自己的回退顺序查找：
 
 1. `persona.<workLanguageCode>.md`（例如当工作语言是 `en` 时为 `persona.en.md`）
 2. `persona.md`
+3. `knowhow.<workLanguageCode>.md` → `knowhow.md` → `knowledge.<workLanguageCode>.md` → `knowledge.md`
+4. `pitfalls.<workLanguageCode>.md` → `pitfalls.md` → `lessons.<workLanguageCode>.md` → `lessons.md`
+
+迁移说明：`knowledge/lessons` 现在只是 rtws 成员文件的旧文件名 fallback。只要 `knowhow`
+或 `pitfalls` 文件存在，运行时就只注入新文件内容。builtin mind 只认 canonical 文件名，
+不读取旧别名。请尽快完成改名迁移；未来版本会在过渡期之后移除旧名支持。
 
 示例：
 

package/dist/docs/memory-system.md

@@ -31,7 +31,7 @@ Related terminology: [dominds-terminology.md](./dominds-terminology.md)
 The same information can be categorized by “who needs to see it / who maintains it”. This axis is orthogonal to long‑term vs short‑term, and helps avoid treating team agreements as personal worklogs (or vice versa).
 
 - **Individual-scope (per-agent / per-dialog)**:
-  - `persona` / `knowledge` / `lessons` (role definitions assigned per member)
+  - `persona` / `knowhow` / `pitfalls` (role definitions assigned per member)
   - individual memory (`personal_memory`)
   - dialog history (including tool calls and outputs)
   - reminders (working set / worklog)
@@ -56,7 +56,7 @@ team governance and team management are functions too.
 This doc uses three time horizons: long-term / task-term / short-term (dialog). This axis is orthogonal to sharing scope (individual vs collective): the same fact has both a time horizon and a scope.
 
 - **A) Long-term memory (stable, cross-dialog)**
-  - **Org structure (static definitions)**: `persona` / `knowledge` / `lessons`
+  - **Org structure (static definitions)**: `persona` / `knowhow` / `pitfalls`
   - **Team governance (shared)**: team memory
   - **Agent-owned**: individual memory
 - **B) Task-term memory (survives dialog courses)**
@@ -72,13 +72,13 @@ This doc uses three time horizons: long-term / task-term / short-term (dialog).
 
 Long-term memory is for things that should remain true across dialogs: who you are, what you own, and how the team operates.
 
-#### 1) `persona` / `knowledge` / `lessons`: static role allocation
+#### 1) `persona` / `knowhow` / `pitfalls`: static role allocation
 
 These docs “pin” an agent into a durable role in the team:
 
 - `persona`: identity + style (voice, working habits, scope boundaries, preference constraints)
-- `knowledge`: stable expertise and capability boundaries (what you’re good at; your tool/safety stance)
-- `lessons`: accumulated learnings (which paths are safer; which traps to avoid)
+- `knowhow`: positive, durable knowledge accumulation (what you’re good at, which methods are proven, your tool/safety stance)
+- `pitfalls`: negative lessons and anti-traps (which traps not to repeat, which signals imply risk, which paths are safer)
 
 They are not for task progress. Their job is to keep the division of labor stable, so the team doesn’t reinvent roles every time.
 

package/dist/docs/memory-system.zh.md

@@ -31,7 +31,7 @@ TL;DR：
 同一份信息可以按“谁需要看见/共同维护”来分。这个维度与“长期/中期/短期”等时间维度正交，用来避免把团队共识写进个人工作日志，或把个人工作集误当成团队公告板。
 
 - **个体记忆（个人/对话局部）**：
-  - `persona` / `knowledge` / `lessons`（按成员分配的角色定义）
+  - `persona` / `knowhow` / `pitfalls`（按成员分配的角色定义）
   - 个人记忆（`personal_memory`）
   - 对话历史（含工具调用与反馈）
   - 提醒项（工作集/工作日志）
@@ -55,7 +55,7 @@ TL;DR：
 按时间尺度记忆可以分三层：长期 / 中期（任务）/ 短期（对话历史）。它与“个体/集体”等空间维度正交：同一条信息既属于某个时间层，也属于某个共享范围。
 
 - **A) 长期记忆（稳定、跨对话生效）**
-  - **组织结构分配（静态定义）**：`persona` / `knowledge` / `lessons`
+  - **组织结构分配（静态定义）**：`persona` / `knowhow` / `pitfalls`
   - **动态治理维护（团队共享）**：团队记忆（team memory）
   - **个体智能体自主维护**：个人记忆（individual memory）
 - **B) 中期（任务）记忆（跨对话 course 生效）**
@@ -71,13 +71,13 @@ TL;DR：
 
 长期记忆的关键词是：**稳定**、**可复用**、**跨对话**。它们要么定义“我是谁/我负责什么”，要么定义“我们团队怎么做事”。
 
-#### 1) persona / knowledge / lessons：组织结构分配（静态定义）
+#### 1) persona / knowhow / pitfalls：组织结构分配（静态定义）
 
 这三类文档用于把一个智能体“定位”成团队里的某个角色：
 
 - `persona`：身份与风格（口吻、工作方式、职责边界、偏好约束）
-- `knowledge`：稳定的专业知识与能力范围（你擅长什么、你的工具观与安全观）
-- `lessons`：来自历史迭代的经验教训（哪些坑不要再踩、哪些路径更稳）
+- `knowhow`：偏正向的稳定知识与经验沉淀（你擅长什么、哪些方法已验证有效、你的工具观与安全观）
+- `pitfalls`：偏负向的历史教训与避坑规则（哪些坑不要再踩、哪些信号意味着风险、哪些路径更稳）
 
 它们的作用不是记录任务进度，而是让分工结构长期有效：减少反复解释、减少误解、减少“临时拼人格”的随机性。
 

package/dist/docs/team_mgmt-toolset.md

@@ -19,7 +19,7 @@ We want a safe way for a “team manager” agent (typically the shadow teammate
 - Create/update `.minds/team.yaml` (team roster + permissions + toolsets).
 - Create/update `.minds/llm.yaml` (LLM provider definitions overriding defaults).
 - Create/update `.minds/mcp.yaml` (MCP server definitions that register dynamic toolsets).
-- Create/update `.minds/team/<member>/{persona,knowledge,lessons}.md` (agent minds).
+- Create/update `.minds/team/<member>/{persona,knowhow,pitfalls}.md` (agent minds).
 
 At the same time, we do **not** want to hand that agent full rtws read/write (e.g. the
 equivalent of the `ws_mod` toolset + unrestricted `read_dirs`/`write_dirs`), because:
@@ -179,7 +179,7 @@ reading source code.
 - `man({ "toolsetId": "team_mgmt", "topics": ["mcp", "troubleshooting"] })` → common MCP failure modes and how to recover.
 - `man({ "toolsetId": "team_mgmt", "topics": ["team"] })` → how to manage `.minds/team.yaml` (+ templates).
 - `man({ "toolsetId": "team_mgmt", "topics": ["team", "member-properties"] })` → list supported member fields and meanings.
-- `man({ "toolsetId": "team_mgmt", "topics": ["minds"] })` → how to manage `.minds/team/<id>/*.md` (persona/knowledge/lessons).
+- `man({ "toolsetId": "team_mgmt", "topics": ["minds"] })` → how to manage `.minds/team/<id>/*.md` (persona/knowhow/pitfalls).
 - `man({ "toolsetId": "team_mgmt", "topics": ["skills"] })` → how to manage `.minds/skills/*` (injection point, tone, heading levels, migration boundaries).
 - `man({ "toolsetId": "team_mgmt", "topics": ["priming"] })` → how to manage startup scripts under `.minds/priming/*`.
 - `man({ "toolsetId": "team_mgmt", "topics": ["env"] })` → how to manage `.minds/env.*.md` (runtime-environment injection point, tone, heading levels).
@@ -225,7 +225,7 @@ must cover (at minimum) the information that used to live there:
 - `!env`:
   - Explain `.minds/env.*.md` as the place for current-rtws runtime-environment orientation, not
     persona definition or a dump of repo-wide policy.
-  - Explain its boundary relative to `persona/knowledge/lessons`, skills, and priming.
+  - Explain its boundary relative to `persona/knowhow/pitfalls`, skills, and priming.
 - `!toolsets`:
   - Explain that the visible toolsets include built-in toolsets, toolsets exposed by installed
     apps, and MCP toolsets dynamically registered from `.minds/mcp.yaml`.
@@ -542,7 +542,7 @@ Best practices:
 
 ## Managing `.minds/team/<member>/*.md` (agent minds)
 
-At dialog start, the runtime reads that member’s `persona.*.md` / `knowledge.*.md` / `lessons.*.md`
+At dialog start, the runtime reads that member’s `persona.*.md` / `knowhow.*.md` / `pitfalls.*.md`
 assets.
 
 - For exact language-file selection, fallback rules, injection order, and other current authoring
@@ -555,8 +555,9 @@ Authoring rule (important):
 - `persona.*.md` is spliced into that member's `role=system` prompt, so it should normally be written directly to the agent itself.
 - In practice, prefer second-person "you" when defining responsibilities, boundaries, working style, and delivery expectations.
 - Do not write `persona.*.md` as a third-person biography or as operator-facing documentation for a human/team manager.
-- `knowledge.*.md` / `lessons.*.md` also end up in the member's system prompt, specifically under `## Knowledge` / `## Lessons`. `knowledge` is better for stable facts, indexes, conventions, and decision cues; `lessons` is better for reusable heuristics such as “if X happens, do Y, avoid Z”. Both should still be written to help that member act, not to narrate the member from the outside.
-- Heading levels should follow the system-prompt wrapper too: the outer template already provides `## Persona` / `## Knowledge` / `## Lessons`, so bodies should usually start at `###` or plain bullets instead of repeating `#` / `##` or restating the wrapper title.
+- `knowhow.*.md` / `pitfalls.*.md` also end up in the member's system prompt, specifically under `## Know-How` / `## Pitfalls`. `knowhow` should lean toward positive knowledge accumulation such as stable facts, indexes, conventions, decision cues, and validated methods; `pitfalls` should lean toward negative lessons and anti-traps such as what not to repeat, which signals imply risk, and “if X happens, do Y, avoid Z”. Both should still be written to help that member act, not to narrate the member from the outside.
+- Migration rule: rtws member files now prefer `knowhow/pitfalls`, and only fall back to legacy `knowledge/lessons` when the new filenames do not exist. Once a new filename exists, only the new file content is injected and the legacy file is ignored. Builtin minds only recognize canonical filenames and do not read legacy aliases. Rename promptly; after the transition period, a future release will stop recognizing `knowledge/lessons`.
+- Heading levels should follow the system-prompt wrapper too: the outer template already provides `## Persona` / `## Know-How` / `## Pitfalls`, so bodies should usually start at `###` or plain bullets instead of repeating `#` / `##` or restating the wrapper title.
 
 Suggested structure:
 
@@ -567,12 +568,12 @@ Suggested structure:
   team/
     fuxi/
       persona.md
-      knowledge.md
-      lessons.md
+      knowhow.md
+      pitfalls.md
     pangu/
       persona.md
-      knowledge.md
-      lessons.md
+      knowhow.md
+      pitfalls.md
 ```
 
 ## Managing `.minds/skills/*` (skill assets)
@@ -597,7 +598,7 @@ Design-level positioning:
   members can orient themselves quickly.
 - It should not take on the role of persona definition, skill tutorial, giant operating manual, or
   repo-wide policy dump.
-- Those responsibilities belong, respectively, in `persona/knowledge/lessons`, skills, priming, or
+- Those responsibilities belong, respectively, in `persona/knowhow/pitfalls`, skills, priming, or
   the repo’s own policy files.
 - This design doc only defines that boundary. For the current injection position, fallback behavior,
   and authoring guidance, use `man({ "toolsetId": "team_mgmt", "topics": ["env"] })`.

package/dist/docs/team_mgmt-toolset.zh.md

@@ -16,7 +16,7 @@
 - 创建/更新 `.minds/team.yaml`（团队名单 + 权限 + 工具集）
 - 创建/更新 `.minds/llm.yaml`（覆盖默认值的 LLM 提供商定义）
 - 创建/更新 `.minds/mcp.yaml`（注册动态工具集的 MCP 服务器定义）
-- 创建/更新 `.minds/team/<member>/{persona,knowledge,lessons}.md`（智能体心智）
+- 创建/更新 `.minds/team/<member>/{persona,knowhow,pitfalls}.md`（智能体心智）
 
 同时，我们**不希望**赋予该智能体完整的 rtws 读写权限（例如 `ws_mod` 工具集 + 无限制的 `read_dirs`/`write_dirs`），因为：
 
@@ -145,7 +145,7 @@
 - `man({ "toolsetId": "team_mgmt", "topics": ["mcp", "troubleshooting"] })` → 常见 MCP 故障模式及如何恢复
 - `man({ "toolsetId": "team_mgmt", "topics": ["team"] })` → 如何管理 `.minds/team.yaml`（+ 模板）
 - `man({ "toolsetId": "team_mgmt", "topics": ["team", "member-properties"] })` → 列出支持的成员字段及其含义
-- `man({ "toolsetId": "team_mgmt", "topics": ["minds"] })` → 如何管理 `.minds/team/<id>/*.md`（persona/knowledge/lessons）
+- `man({ "toolsetId": "team_mgmt", "topics": ["minds"] })` → 如何管理 `.minds/team/<id>/*.md`（persona/knowhow/pitfalls）
 - `man({ "toolsetId": "team_mgmt", "topics": ["skills"] })` → 如何管理 `.minds/skills/*`（skills 的注入位置、口吻、标题层级、迁移边界）
 - `man({ "toolsetId": "team_mgmt", "topics": ["priming"] })` → 如何管理 `.minds/priming/*` 启动脚本（格式、维护、复用）
 - `man({ "toolsetId": "team_mgmt", "topics": ["env"] })` → 如何管理 `.minds/env.*.md`（运行环境提示的注入位置、口吻、标题层级）
@@ -181,7 +181,7 @@
   - 解释何时应继续保留为 skill，何时应升级为 app / toolset / teammates contract
 - `!env`：
   - 解释 `.minds/env.*.md` 用于描述当前 rtws 的运行环境，而不是定义人格或复制仓库总规范
-  - 解释它与 `persona/knowledge/lessons`、skills、priming 的分工边界
+  - 解释它与 `persona/knowhow/pitfalls`、skills、priming 的分工边界
 - `!toolsets`：
   - 解释当前可见 toolsets 包含内建 toolsets、已安装 apps 暴露的 toolsets、以及由 `.minds/mcp.yaml` 动态注册的 MCP toolsets
   - 解释为什么该主题必须以运行时动态视图为准，而不是在设计文档里维护一份静态名单
@@ -461,7 +461,7 @@ members:
 
 ## 管理 `.minds/team/<member>/*.md`（智能体心智）
 
-运行时在每次对话开始时会读取该成员的 `persona.*.md` / `knowledge.*.md` / `lessons.*.md` 资产。
+运行时在每次对话开始时会读取该成员的 `persona.*.md` / `knowhow.*.md` / `pitfalls.*.md` 资产。
 
 - 具体语言文件选择、回退规则、注入顺序与其它 authoring 细则，请以 `man({ "toolsetId": "team_mgmt", "topics": ["minds"] })` 为准。
 
@@ -472,8 +472,9 @@ members:
 - `persona.*.md` 会被拼进该成员的 `role=system` 提示，因此默认应该直接写给“这个成员智能体本人”。
 - 也就是说，`persona.*.md` 应优先使用第二人称“你”来规定职责边界、工作方式与交付标准。
 - 不要把 `persona.*.md` 写成第三人称人物简介，不要把它当成给团队管理员/人类读者的说明书，也不要使用“祂”这类旁白口吻。
-- `knowledge.*.md` / `lessons.*.md` 也同样会进入该成员的系统提示，分别落在 `## 知识` / `## 经验`。`knowledge` 更适合稳定事实、索引、约定、判断依据；`lessons` 更适合复用型经验规则（例如“遇到 X 信号先做 Y，不要做 Z”）。两者都应以“帮助该成员当下工作”为目标，而不是面向旁观者写注释。
-- 标题层级也要按 system prompt 模板来写：系统外层已经自动提供 `## 角色设定` / `## 知识` / `## 经验`，所以正文通常应从 `###` 或普通 bullet 开始，不要再写 `#` / `##`，也不要把文件名或这些章节名重复当标题。
+- `knowhow.*.md` / `pitfalls.*.md` 也同样会进入该成员的系统提示，分别落在 `## 经验知识` / `## 避坑指南`。`knowhow` 应偏向正向的知识与经验沉淀，例如稳定事实、索引、约定、判断依据、已验证有效的方法；`pitfalls` 应偏向负向的教训与避坑规则，例如哪些坑不要再踩、哪些信号意味着风险、遇到 X 时先做 Y 不要做 Z。两者都应以“帮助该成员当下工作”为目标，而不是面向旁观者写注释。
+- 迁移规则：rtws 成员文件现已优先读取 `knowhow/pitfalls`，只有在新文件名不存在时，才回退兼容旧的 `knowledge/lessons`。一旦新文件名存在，就只注入新文件内容，旧文件内容会被忽略。builtin mind 只认 canonical 文件名，不读取旧别名。请尽快完成改名迁移；过渡期之后，未来版本将不再识别 `knowledge/lessons`。
+- 标题层级也要按 system prompt 模板来写：系统外层已经自动提供 `## 角色设定` / `## 经验知识` / `## 避坑指南`，所以正文通常应从 `###` 或普通 bullet 开始，不要再写 `#` / `##`，也不要把文件名或这些章节名重复当标题。
 
 建议的结构：
 
@@ -484,12 +485,12 @@ members:
   team/
     fuxi/
       persona.md
-      knowledge.md
-      lessons.md
+      knowhow.md
+      pitfalls.md
     pangu/
       persona.md
-      knowledge.md
-      lessons.md
+      knowhow.md
+      pitfalls.md
 ```
 
 ## 管理 `.minds/skills/*`（技能资产）
@@ -507,7 +508,7 @@ members:
 
 - `.minds/env.*.md` 用来描述“当前 rtws 运行环境”的稳定背景信息，帮助成员理解所处环境。
 - 它不应承担 persona 定义、skill 教程、团队制度大全、或仓库全局规范汇总的职责。
-- 这类内容按分工应分别落在 `persona/knowledge/lessons`、skills、priming、或仓库自己的规范文件中。
+- 这类内容按分工应分别落在 `persona/knowhow/pitfalls`、skills、priming、或仓库自己的规范文件中。
 - 设计文档在这里仅强调用途边界；具体注入位置、回退规则、标题建议等，以运行时 `man({ "toolsetId": "team_mgmt", "topics": ["env"] })` 为准。
 
 ## 引导策略：影子成员引导