@topmindspace/topmind-skills 4.15.4 → 4.15.6

package/README.en.md

@@ -1,175 +1,106 @@
 # topmind Skills
 
-Portable AI skill pack: the same content contract on Claude Code / Codex / OpenCode / Hermes and other hosts.
+Bring the topmind personal-knowledge workflow to your AI assistant (Claude Code, Codex, Cursor, OpenCode, Hermes and others). Say "save this", "organize this week" or "turn it into a draft", and the assistant stores everything in your own `topmind-workspace` folder under one shared set of conventions. Skill text is written in Chinese.
 
-[简体中文](README.md) · [English](README.en.md) · [Product](https://github.com/topmindspace/topmind) · [Install](./INSTALL.md) · [npm](https://www.npmjs.com/package/@topmindspace/topmind-skills)
+[简体中文](README.md) · [English](README.en.md) · [Install guide](./INSTALL.md) · [Changelog](./CHANGELOG.md) · [Product](https://github.com/topmindspace/topmind) · [npm](https://www.npmjs.com/package/@topmindspace/topmind-skills)
+
+## Install
 
 ```bash
-# 1) npm (recommended · pack-aware · includes shared/ · canonical .agents + agents)
 npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g
-# subset of agents
-npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g -a claude-code -a mimocode
-# upgrade
-npx @topmindspace/topmind-skills update -g
-
-# 2) Community CLI (fast try; omits shared/ — see INSTALL.md)
-npx skills add topmindspace/topmind-skills -g -y
-
-# 3) Pack-aware installer (from a source checkout)
-npm run add -- topmindspace/topmind-skills -g
-npm run update -- -g
-
-# 4) From GitHub Release (pinned version / offline)
-node bin/install-skills.mjs add release:latest -g
-
-# Inspect matrix / repair broken roots
-node bin/install-skills.mjs agents
-node bin/install-skills.mjs doctor --repair
 ```
 
-Install model: **one canonical body under `.agents/skills`** plus relative symlinks into private host roots (Claude Code, MiMoCode, …) — same as [`npx skills`](https://github.com/vercel-labs/skills). See [INSTALL.md](./INSTALL.md).
-
-**Version and manifest truth:** [`topmind-pack.json`](./topmind-pack.json) (`npm run versions`).  
-Each `SKILL.md` `metadata.version` **must** equal the pack version.
+Then say "topmind" or just ask for what you need. To upgrade:
 
----
-
-## Layout
-
-```text
-topmind-skills/              # pack root = repo root
-├── topmind/                 # only daily entry (router)
-├── topmind-capture|organize|write|memory|maintain|loop/
-├── topmind-weread|x/        # optional connectors
-├── topmind-ledger/          # optional bookkeeping (memory-plane ledgers)
-├── shared/                  # write receipts · degradation · auto-suggest · capture …
-├── install-targets/         # host install shapes
-├── evals/evals.json
-├── bin/install-skills.mjs   # pack-aware installer (shared/ aware)
-├── scripts/build-pack.mjs
-└── topmind-pack.json        # version truth
+```bash
+npx @topmindspace/topmind-skills update -g
 ```
 
-| Kind | Modules |
-|------|---------|
-| **Entry** | `topmind` only |
-| **Actions** | capture · organize · write · memory · maintain · loop |
-| **Connectors** | weread · x (optional) |
-| **Optional** | ledger (记账 · memory-plane books) |
-| **External optional (not bundled)** | WeChat `topmind-wechat-post` and other writing skills (topmind-writing-skills) · `topmind-research` · `topmind-presentation` · `topmind-handoff`; routing in `shared/trigger-disambiguation.md` |
+- A newer packaged skill overwrites the installed copy and prints `Upgraded <skill> <old> -> <new>`; the same version prints `Already up to date`; a newer installed version is kept unless you pass `--force`.
+- To install for some assistants only, add `-a claude-code -a codex` to `add`.
+- The community CLI `npx skills add topmindspace/topmind-skills -g -y` also works, but it leaves out the `shared/` folder, so some rules cannot be read. See [INSTALL.md](./INSTALL.md#社区-cli-npx-skills) for the extra step.
+- Pinned or offline installs, project scope and per-assistant folders are covered in [INSTALL.md](./INSTALL.md).
 
-> Sub-skill trigger words exist for host routing. They are **not** a second product front door.
+## Usage
 
----
+Expose only `topmind` as the daily entry. It decides which skill handles your request, so you never need to remember sub-skill names.
 
-## Product contract
+| You say | Handled by | Result |
+|---|---|---|
+| "Save this link" | `topmind-capture` | Stored in the weekly stream, a topic or the Inbox; the receipt says where |
+| "Remind me to do X" | `topmind-capture` | Material saved, to-do written to `memory/todo.md` |
+| "What's on my list?" | `topmind` | Open items from `memory/todo.md` |
+| "Organize this week", "summarize this topic" | `topmind-organize` | Tidies the week's stream or organizes, compares and distills a topic |
+| "Write it up", "polish this" | `topmind-write` | Drafts or revises into the delivery folder or the topic |
+| "Remember that I…", "update my profile" | `topmind-memory` | Updates `memory/profile.md` or a periodic reflection |
+| "Run a health check", "doctor" | `topmind-maintain` | Checks folder structure and config, with reversible cleanup |
+| "Run the loop" | `topmind-loop` | Walks every topic and can resume after an interruption |
+| "Sync WeRead" | `topmind-weread` | Optional: syncs WeRead highlights and notes into topics |
+| "Post to X", "archive my posts" | `topmind-x` | Optional: X archive, search and posting |
+| "Log 35 for lunch" | `topmind-ledger` | Optional: bookkeeping in `memory/ledgers/` |
 
-```text
-User experience:     capture-first
-Data organization:   category-first + topic-emerges
-Content truth:       topmind-workspace
-Capability model:    action-first
-Save settings:       auto | confirm
-Safety model:        reversible by default
-Suggestions:         L0 auto-land · L1 auto-prepare · L2 confirm-apply — shared/auto-suggest.md
-```
+The pack has 10 skills: the `topmind` entry, 6 actions, 2 optional connectors and 1 optional ledger. See [skills.md](./skills.md).
 
-Expose only `topmind` as the daily entry. Host session state must not become topmind content truth.  
-**Desktop is not required** for this pack. **UTR is optional** — use host file tools when UTR is absent.
-
-Workflow: `收进来 -> 继续做 -> 交付/沉淀 -> 找回/调整`  
-**Capture whenever / use whenever:** capture lands with zero questions; classification alternatives, todo extraction, and memory candidates are prepared as L1 suggestions for one-word accept ([`shared/auto-suggest.md`](./shared/auto-suggest.md)). `memory/todo.md` is a satellite — not a sixth concept.
-(If the user says “capture this”, “note it”, “organize”, “write it up”, or “run a loop”, the router infers category / topic / action.)
-
----
-
-## SKILL.md frontmatter
-
-```yaml
----
-name: <kebab-case-id>           # required; matches directory name
-description: >-                  # required; what + Use when + Do NOT use
-  …
-license: MIT
-compatibility: …                # optional; environment notes (≤500 chars)
-metadata:                       # Agent Skills spec: custom fields live here, string values
-  version: "<pack.version>"     # required; = topmind-pack.json version
-  action_category: "capture"    # skill taxonomy (not user note category)
-  entrypoint: "false"           # only the topmind router is "true"
-  triggers: "记一下, 收进, capture"   # comma-separated
-  tags: "capture, inbox"
-  author: "TopMindSpace"
-  homepage: "https://github.com/topmindspace/topmind-skills"
-  updated: "YYYY-MM-DD"
-  degradation: "../shared/capability-degradation.md"
----
-```
+### Companion skills (installed separately)
 
-Top level allows only `name / description / license / compatibility / metadata / allowed-tools`; CI runs the official validator `agentskills validate` (skills-ref) on every skill, and `tests/package-manifest.test.mjs` enforces fields and versions. The topmind Desktop parser reads both the legacy top-level layout and `metadata.*`.
+These are not part of this pack. When installed, `topmind` hands matching requests to them; otherwise it falls back to `topmind-write` or explains in the receipt.
 
----
+| Need | Skill | Repository |
+|---|---|---|
+| WeChat articles, X articles, short posts, covers, long images | `topmind-wechat-post` and 7 other writing skills | [topmind-writing-skills](https://github.com/topmindspace/topmind-writing-skills) |
+| AI industry news, papers, number checks | `topmind-research` | [topmind-research](https://github.com/topmindspace/topmind-research) |
+| Turn material into paged HTML and PPTX | `topmind-presentation` | [topmind-presentation](https://github.com/topmindspace/topmind-presentation) |
+| Hand memory over between tools | `topmind-handoff` | [topmind-handoff](https://github.com/topmindspace/topmind-handoff) |
 
-## Workspace contract
+Routing between them is defined in [`shared/trigger-disambiguation.md`](./shared/trigger-disambiguation.md).
 
-```text
-{workspace-root}/
-├── topmind.yaml                # contract v4
-├── memory/                     # profile.md · periodic/ · topics/ · todo.md · optional ledgers/
-├── .topmind/                   # rebuildable machine state
-├── 00-Inbox/                   # role: buffer (live dir name)
-├── 10-Stream/ …                # categories (template-driven)
-├── 88-Delivery/ or 88-交付/     # role: delivery
-└── 99-Archive/ or 99-归档/     # role: system
-```
+## Where content lives
 
-Topic:
+Everything is plain Markdown in your local `topmind-workspace`, readable in Obsidian or any editor.
 
 ```text
-{category}/{YYYY-theme}/
-├── topic.md                 # optional
-├── *.md                     # notes at topic root
-└── images/                  # optional
+topmind-workspace/
+├── topmind.yaml          # workspace config
+├── memory/               # profile, reflections, to-dos, ledgers
+├── 00-Inbox/             # anything not yet classified
+├── 10-动态/              # weekly stream notebooks
+├── …                     # other categories from your template; rename, hide or add
+├── 88-交付/              # finished drafts
+└── 99-归档/
 ```
 
-Loose note: `{category}/{note}.md` when no topic yet.
-
-**Do not create (deprecated):** default `outline.md` / `setting.md` / `style.md`; `project_type` frontmatter; nested topic `notes/` or `outputs/`; top-level `projects/`; `YYYY-类型-项目名` naming.
-
-**Categories:** discover `{NN-Name}/` at runtime + `topmind.yaml` v4 (`categories.extensions` / `categories.overrides` with `hidden`). Shared resolver: engine `lib/workspace-model.mjs`. Prefer role-based routing over hardcoded `10-`/`20-` numbers.
+- When enough notes share a theme, they gather into a topic folder `{category}/{YYYY-theme}/`; until then notes sit at the category root.
+- Categories do not overlap, topics emerge, the stream stays flat, the Inbox is cleared about every 30 days, references live apart, and category names stay stable. Full rules: [`shared/project-model-brief.md`](./shared/project-model-brief.md).
 
-Do not hardcode absolute paths — infer `workspace_root` from the host or ask.
+## Conventions
 
-### 6 core rules
+- **Save first**: unclear items go to the Inbox; imperfect classification never blocks a save.
+- **Every write has a receipt**: which file, why there, and what you can do next.
+- **Save settings**: `writeback_mode: auto | confirm`. auto writes and returns a receipt; confirm lets you review first. High-impact changes such as deleting memory or creating topics always need your OK; see [`shared/auto-suggest.md`](./shared/auto-suggest.md).
+- **Files are the only source of truth**: assistant session state must not become topmind content truth.
+- **Desktop is not required, UTR is optional**: without topmind Desktop or the UTR CLI, the assistant uses its own file tools under the same conventions.
+- **Nothing is posted for you**: skills only draft; you publish.
 
-1. **Categories never overlap**  
-2. **Topics emerge** (do not force-create)  
-3. **Dynamic/stream category is special** (flat-default)  
-4. **Catch-all cleanup** (~30 days)  
-5. **Reference materials stay reference-only**  
-6. **Category names stay stable** (rename via migration)  
+## For maintainers
 
-Full rules: [`shared/project-model-brief.md`](./shared/project-model-brief.md).
+- Version and skill list come from [`topmind-pack.json`](./topmind-pack.json) (`npm run versions`); every `SKILL.md` `metadata.version` must match.
+- `SKILL.md` frontmatter uses only Agent Skills spec fields (`name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`); custom fields go under `metadata` as strings. CI checks each skill with `agentskills validate`.
+- Run tests with `npm test`. Release steps are in [INSTALL.md](./INSTALL.md#发布维护者).
 
----
-
-## Rules (skills behavior)
-
-- Capture first; don’t block simple saves on perfect classification  
-- Auto-route when signal is strong; otherwise **role:buffer** (live inbox dir, not hardcoded-only `00-Inbox/`)  
-- Loose notes at category root when topic is unclear  
-- Every write returns a receipt (path, route reason when available, next step)  
-- `source_type`: `user-original` | `external-capture` | `ai-derived`  
-- UTR is optional — host file tools preserve the same contract  
-- Save settings protocol: `writeback_mode: auto | confirm`  
-- Locked: editable under auto (task-level first-write snapshot); permanent delete of locked/core is user-only  
-- Desktop is not required for this pack  
-- **Compound discipline (no structure change):** organize leaves synthesis on disk; write reads optional `topic.md` first; memory only on explicit confirm; capture never edits `topic.md`; **no** hard `INDEX.md` / parallel wiki trees (see `shared/project-model-brief.md`)  
-
----
-
-## Install targets
+```text
+topmind-skills/
+├── topmind/              # daily entry (router)
+├── topmind-capture/ … topmind-loop/   # 6 action skills
+├── topmind-weread/  topmind-x/        # optional connectors
+├── topmind-ledger/       # optional ledger
+├── shared/               # rules shared by all skills
+├── install-targets/      # install shapes per assistant
+├── integrations/         # Codex, Hermes, OpenCode notes
+├── evals/                # routing evals
+├── bin/install-skills.mjs
+└── topmind-pack.json
+```
 
-Packaged skill directories (7 core + 2 optional connectors + optional ledger; since 4.15.2 WeChat comes from `topmind-wechat-post` in the writing pack) can be symlinked/copied into Claude Code, Codex, OpenCode, Hermes, and similar hosts.  
-Prefer the pack-aware installer so `shared/` and `topmind-pack.json` stay intact — see [`INSTALL.md`](./INSTALL.md).
+## License
 
-Host adapters must **not** change content truth, add parallel daily entries, or store content in agent runtime state. See [`shared/capability-degradation.md`](./shared/capability-degradation.md).
+MIT

package/README.md

@@ -1,180 +1,106 @@
 # topmind Skills
 
-可移植 AI 技能包：在 Claude Code / Codex / OpenCode / Hermes 等 Host 上使用同一套内容约定。
+把 topmind 的个人知识工作流装进你的 AI 助手（Claude Code、Codex、Cursor、OpenCode、Hermes 等）。你只管说「记一下」「整理本周」「写成稿」，助手按同一套约定把内容存进你自己的 `topmind-workspace` 文件夹。
 
-[简体中文](README.md) · [English](README.en.md) · [产品总览](https://github.com/topmindspace/topmind) · [安装与发布](./INSTALL.md) · [npm](https://www.npmjs.com/package/@topmindspace/topmind-skills)
+[简体中文](README.md) · [English](README.en.md) · [安装说明](./INSTALL.md) · [更新记录](./CHANGELOG.md) · [产品总览](https://github.com/topmindspace/topmind) · [npm](https://www.npmjs.com/package/@topmindspace/topmind-skills)
+
+## 安装
 
 ```bash
-# 1) npm（推荐 · pack-aware · 含 shared/ · canonical .agents + 多智能体）
 npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g
-# 只装给部分智能体
-npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g -a claude-code -a mimocode
-# 升级
-npx @topmindspace/topmind-skills update -g
-
-# 2) 社区 CLI（快速试用；不含 shared/ — 见 INSTALL.md）
-npx skills add topmindspace/topmind-skills -g -y
-
-# 3) Pack-aware 安装器（源码仓内）
-npm run add -- topmindspace/topmind-skills -g
-npm run update -- -g
-
-# 4) 从 GitHub Release 装（离线/固定版本）
-node bin/install-skills.mjs add release:latest -g
-
-# 查看矩阵 / 修断链
-node bin/install-skills.mjs agents
-node bin/install-skills.mjs doctor --repair
 ```
 
-安装模型：**canonical `.agents/skills` 一份真身** + 私有目录（Claude Code / MiMoCode…）相对软链；与 [`npx skills`](https://github.com/vercel-labs/skills) 一致。详见 [INSTALL.md](./INSTALL.md)。
-
-**版本与清单真源：** [`topmind-pack.json`](./topmind-pack.json)（`npm run versions`）。  
-各 `SKILL.md` 的 `metadata.version` **必须**等于 pack 版本。
-
----
+装好后对助手说「topmind」或直接说要做的事即可。升级用：
 
-## 结构
-
-```text
-topmind-skills/              # pack 根 = 仓库根
-├── topmind/                 # 唯一日常入口（router）
-├── topmind-capture|organize|write|memory|maintain|loop/
-├── topmind-weread|x/        # 可选连接器
-├── topmind-ledger/          # 可选记账（记忆平面账本）
-├── shared/                  # 写回回执 · 降级 · 自动建议 · 捕获 …
-├── install-targets/         # Host 安装形状（claude-code / codex / mimocode / …）
-├── evals/evals.json
-├── bin/install-skills.mjs   # pack-aware + agent matrix 安装器
-├── scripts/build-pack.mjs
-└── topmind-pack.json        # 版本真源
+```bash
+npx @topmindspace/topmind-skills update -g
 ```
 
-| 类型 | 模块 |
-|------|------|
-| **入口** | `topmind` only |
-| **动作** | capture · organize · write · memory · maintain · loop |
-| **连接器** | weread · x（可选） |
-| **可选** | ledger（记账 · 记忆平面账本） |
-| **外部可选（不随包）** | 公众号 `topmind-wechat-post` 等写作技能（topmind-writing-skills）· `topmind-research` · `topmind-presentation` · `topmind-handoff`；路由见 `shared/trigger-disambiguation.md` |
+- 包里版本更新时直接覆盖，打印 `Upgraded <技能> <旧> -> <新>`；版本相同打印 `Already up to date`；已装版本更新时不降级，要降级加 `--force`。
+- 只装给部分助手：在 `add` 后面加 `-a claude-code -a codex`。
+- 社区 CLI `npx skills add topmindspace/topmind-skills -g -y` 也能装，但不带 `shared/` 目录，部分规则会读不到，装完要补一步，见 [INSTALL.md](./INSTALL.md#社区-cli-npx-skills)。
+- 固定版本或离线安装、项目级安装、各助手的目录位置，都在 [INSTALL.md](./INSTALL.md)。
 
-> 子 skill 触发词只服务 Host 路由，**不是**第二前台入口。
+## 怎么用
 
----
+日常入口只暴露 `topmind` 一个。你说的话由它判断交给哪个技能，你不用记子技能的名字。
 
-## 产品契约
+| 你说 | 交给 | 结果 |
+|---|---|---|
+| 「记一下这个链接」「收进来」 | `topmind-capture` | 存进动态周期本、专题或 Inbox，回执告诉你放在哪 |
+| 「记一下要做 X」「别忘了 X」 | `topmind-capture` | 材料落盘，待办写进 `memory/todo.md` |
+| 「有什么要做的」 | `topmind` | 列出 `memory/todo.md` 里没做完的事 |
+| 「整理本周」「总结一下这个专题」 | `topmind-organize` | 理顺本周动态，或在专题里整理、对比、提炼 |
+| 「写成稿」「润色一下」 | `topmind-write` | 起草或改稿，放到交付目录或专题里 |
+| 「记住我…」「更新我的情况」 | `topmind-memory` | 更新 `memory/profile.md` 或周期反思 |
+| 「体检一下」「doctor」 | `topmind-maintain` | 检查目录结构和配置，做可回退的清理 |
+| 「跑一遍 loop」 | `topmind-loop` | 逐个专题巡检，中断后能接着跑 |
+| 「同步微信读书」 | `topmind-weread` | 可选：把划线和想法同步到专题 |
+| 「发推」「归档我的推文」 | `topmind-x` | 可选：X 归档、搜索与发帖 |
+| 「记一笔，午饭 35」 | `topmind-ledger` | 可选：记账到 `memory/ledgers/` |
 
-```text
-User experience:     capture-first
-Data organization:   category-first + topic-emerges
-Content truth:       topmind-workspace
-Capability model:    action-first
-Save settings:       auto | confirm
-Safety model:        reversible by default
-Suggestions:         L0 auto-land · L1 auto-prepare · L2 confirm-apply — shared/auto-suggest.md
-```
+本包共 10 个技能：入口 `topmind`、6 个动作技能、2 个可选连接器、1 个可选记账。清单见 [skills.md](./skills.md)。
 
-日常入口只暴露 `topmind`。Host 会话状态不得成为 topmind 内容真源。  
-本 pack **不要求 Desktop**。**UTR 可选** — 没有 UTR 时用 Host 文件工具。
-
-工作流：`收进来 -> 继续做 -> 交付/沉淀 -> 找回/调整`  
-（用户说「收一下」「记一下」「整理」「写成稿」「跑一遍 loop」— router 推断类别 / 专题 / 动作。）
-
-**想记就记 / 随用随记**：捕获零提问落盘（L0）；分类备选 / 待办 / 记忆候选默认 L1 准备——显式行动语待办在 auto 下同轮写入 `memory/todo.md`，其余建议点头再落（[`shared/auto-suggest.md`](./shared/auto-suggest.md)）。
-
----
-
-## SKILL.md frontmatter
-
-```yaml
----
-name: <kebab-case-id>           # 必填；与目录名一致
-description: >-                  # 必填；做什么 + Use when + Do NOT use
-  …
-license: MIT
-compatibility: …                # 可选；运行环境说明（≤500 字符）
-metadata:                       # Agent Skills 规范：自定义字段一律放这里，值为字符串
-  version: "<pack.version>"     # 必填；= topmind-pack.json version
-  action_category: "capture"    # skill 分类（不是用户笔记的 category）
-  entrypoint: "false"           # 只有 topmind router 是 "true"
-  triggers: "记一下, 收进, capture"   # 逗号分隔
-  tags: "capture, inbox"
-  author: "TopMindSpace"
-  homepage: "https://github.com/topmindspace/topmind-skills"
-  updated: "YYYY-MM-DD"
-  degradation: "../shared/capability-degradation.md"
----
-```
+### 配套技能（单独安装）
 
-顶层只允许 `name / description / license / compatibility / metadata / allowed-tools`，CI 用官方校验器 `agentskills validate`（skills-ref）逐个检查；字段与版本由 `tests/package-manifest.test.mjs` 强制校验。topmind Desktop 的解析器同时认顶层旧写法与 `metadata.*`。一个 pack JSON（[`topmind-pack.json`](./topmind-pack.json)），无 per-skill 第二清单。
+下面这些不随本包发布，装了以后 `topmind` 会把对应请求转过去，没装时退回 `topmind-write` 或在回执里说明。
 
----
+| 需求 | 技能 | 仓库 |
+|---|---|---|
+| 公众号、X 长文、短文、段子、封面、长图 | `topmind-wechat-post` 等 8 个写作技能 | [topmind-writing-skills](https://github.com/topmindspace/topmind-writing-skills) |
+| AI 行业动态、读论文、核实数字 | `topmind-research` | [topmind-research](https://github.com/topmindspace/topmind-research) |
+| 把材料做成可翻页 HTML 和 PPTX | `topmind-presentation` | [topmind-presentation](https://github.com/topmindspace/topmind-presentation) |
+| 跨工具交接记忆 | `topmind-handoff` | [topmind-handoff](https://github.com/topmindspace/topmind-handoff) |
 
-## 工作区契约
+各技能怎么分工，见 [`shared/trigger-disambiguation.md`](./shared/trigger-disambiguation.md)。
 
-```text
-{workspace-root}/
-├── topmind.yaml                # contract v4
-├── memory/                     # profile.md · periodic/ · topics/ · todo.md · 可选 ledgers/
-├── .topmind/                   # rebuildable machine state
-├── 00-Inbox/                   # role: buffer (live dir name)
-├── 10-动态/ …                  # categories (template-driven)
-├── 88-交付/ or 88-Delivery/     # role: delivery
-└── 99-归档/ or 99-Archive/     # role: system
-```
+## 内容存在哪
 
-专题：
+所有内容都是你本机 `topmind-workspace` 里的 Markdown 文件，用 Obsidian 或任何编辑器都能打开。
 
 ```text
-{category}/{YYYY-theme}/
-├── topic.md                 # optional
-├── *.md                     # notes at topic root
-└── images/                  # optional
+topmind-workspace/
+├── topmind.yaml          # 工作区配置
+├── memory/               # 我的情况、周期反思、待办、账本
+├── 00-Inbox/             # 一时分不了类的先放这里
+├── 10-动态/              # 按周的动态周期本
+├── …                     # 其他大类，按模板生成，可以改名、隐藏、新增
+├── 88-交付/              # 写好的稿件
+└── 99-归档/
 ```
 
-尚无专题时，散篇放在 `{category}/{note}.md`。
-
-**不要创建（已废弃）：** 默认 `outline.md` / `setting.md` / `style.md`；`project_type` frontmatter；专题内嵌套 `notes/` 或 `outputs/`；顶层 `projects/`；`YYYY-类型-项目名` 命名。
-
-**类别：** 运行时发现 `{NN-Name}/` + `topmind.yaml` v4（`categories.extensions` / `categories.overrides` 含 `hidden`）。共享解析器：引擎 `lib/workspace-model.mjs`。优先按角色路由，不要写死 `10-` / `20-` 编号。
-
-不要硬编码绝对路径 — 从 Host 推断 `workspace_root`，或向用户询问。
-
-### 6 条核心规约
-
-1. **大类不重叠**  
-2. **专题自然涌现**  
-3. **动态类特殊**（默认平铺）  
-4. **兜底类清理**（约 30 天）  
-5. **参考资料定位**  
-6. **大类命名稳定**（rename via migration）  
+- 一个大类下面，同一主题的笔记多了会自然聚成专题文件夹 `{大类}/{YYYY-主题}/`；没有专题时笔记直接放在大类根。
+- 大类不重叠、专题自然形成、动态平铺、Inbox 约 30 天清一次、参考资料单独放、大类名称保持稳定。完整规则见 [`shared/project-model-brief.md`](./shared/project-model-brief.md)。
 
-完整规则：[`shared/project-model-brief.md`](./shared/project-model-brief.md)。
+## 几条约定
 
----
+- **先存下来再说**：分类不确定时先放 Inbox，不因为分类拦住保存。
+- **每次写入都有回执**：写了哪个文件、为什么放这里、下一步可以做什么。
+- **保存设置**：`writeback_mode: auto | confirm`。auto 直接写并给回执；confirm 先给你审阅。删除记忆、建专题这类高影响操作总要你点头，规则见 [`shared/auto-suggest.md`](./shared/auto-suggest.md)。
+- **文件是唯一的数据来源**：助手自己的会话状态不得成为 topmind 内容真源。
+- **不要求 Desktop，UTR 可选**：topmind Desktop 和 UTR 命令行都不是必需的，没有时用助手自带的文件工具，遵守同一套约定。
+- **不代发**：任何技能都只起草，发布由你操作。
 
-## 行为规则
+## 给维护者
 
-- 先捕获；不要因为分类不完美而挡住简单保存  
-- 信号足够强时自动路由；否则走 **role:buffer**（现场 Inbox 目录，不要只写死 `00-Inbox/`）  
-- 专题不清时，散篇放在大类根  
-- 每次写入返回回执（路径、路由原因、下一步）  
-- `source_type`: `user-original` | `external-capture` | `ai-derived`  
-- UTR 可选 — Host 文件工具遵守同一契约  
-- 保存设置协议：`writeback_mode: auto | confirm`  
-- locked：auto 下可编辑（任务级首写快照）；永久删 locked/core 仅用户  
-- 本 pack 不要求 Desktop  
-- **复合纪律（不改结构）：** organize 把综合写回磁盘；write 先读可选 `topic.md`；memory 仅在明确确认后写；capture 从不改 `topic.md`；**不要**硬造 `INDEX.md` / 平行 wiki 树（见 `shared/project-model-brief.md`）  
+- 版本和技能清单以 [`topmind-pack.json`](./topmind-pack.json) 为准（`npm run versions` 查看），各 `SKILL.md` 的 `metadata.version` 必须一致。
+- `SKILL.md` frontmatter 只用 Agent Skills 规范字段（`name`、`description`、`license`、`compatibility`、`metadata`、`allowed-tools`），自定义字段放在 `metadata` 下、值为字符串。CI 用 `agentskills validate` 逐个检查。
+- 本地测试：`npm test`。发布流程见 [INSTALL.md](./INSTALL.md#发布维护者)。
 
----
-
-## 安装目标
-
-已打包的 skill 目录（7 个核心 + 2 个可选连接器 + 可选记账；4.15.2 起公众号改由写作包的 `topmind-wechat-post` 提供）可以符号链接或复制到 Claude Code、Codex、OpenCode、Hermes 等。  
-优先使用 npm / pack-aware 安装器，保证 `shared/` 与 `topmind-pack.json` 完整 — 见 [`INSTALL.md`](./INSTALL.md)。
-
-```bash
-npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g
+```text
+topmind-skills/
+├── topmind/              # 日常入口（路由）
+├── topmind-capture/ … topmind-loop/   # 6 个动作技能
+├── topmind-weread/  topmind-x/        # 可选连接器
+├── topmind-ledger/       # 可选记账
+├── shared/               # 各技能共用的规则文档
+├── install-targets/      # 各助手的安装形状
+├── integrations/         # Codex、Hermes、OpenCode 接入说明
+├── evals/                # 路由评测
+├── bin/install-skills.mjs
+└── topmind-pack.json
 ```
 
-Host 适配器**不得**改变内容真源、新增并列日常入口，或把内容存进 agent 运行态。见 [`shared/capability-degradation.md`](./shared/capability-degradation.md)。
+## 许可证
+
+MIT