@topmindspace/topmind-skills 4.13.0

package/INSTALL.md

@@ -0,0 +1,295 @@
+# Install & update topmind Skills
+
+[简体中文](./README.md) · [English](./README.en.md) · [产品](https://github.com/topmindspace/topmind)
+
+**Model (same idea as open Agent Skills / `npx skills`):**
+
+```text
+指定源（GitHub 仓库 / 本地路径 / Release）
+    + 仓库即 pack 根（topmind-skills 无 monorepo 子目录）
+    + 安装目标（host 的 skills 根目录）
+    → 安装
+    → 以后在同一目标上 update 升级
+```
+
+```text
+Source  examples:  topmindspace/topmind-skills   .   release:latest
+Path    default:   .     (topmind-skills 仓根即 pack)
+Dest    examples:  $HOME/.claude/skills   ./.claude/skills   $HOME/.codex/skills
+```
+
+Repository: https://github.com/topmindspace/topmind-skills  
+Daily entry after install: **`topmind`**
+
+---
+
+## 0. Via Desktop（推荐 · 探测 + 装/升/卸）
+
+若已安装 **topmind Desktop**，不必先跑 CLI：
+
+1. 打开 **设置 → 关于与更新 (About & updates)**
+2. 查看已探测的 Agent 宿主（Claude Code · Codex · Hermes · OpenCode · CodeBuddy 等）  
+3. 对目标宿主点 **安装 / 升级 / 卸载**（优先全局 skills 根 + 回执；卸载只删托管条目，不动无关用户 skill）  
+4. 同一页还可：**准备剪藏扩展**（引导浏览器 Load unpacked）、**安装 Obsidian 插件**到当前工作区 vault  
+
+独立 CLI / pack 路径仍然有效（无 Desktop 时用本节后续命令）。宿主探测与装机逻辑在 Desktop 内为纯 FS，与本脚本语义对齐。
+
+---
+
+## Publishing to skills.sh & Open Agent Skills Registry
+
+**skills.sh**（与 `npx skills` 工具网络）采用基于 **GitHub 公开仓库的直连索引机制**。将本仓库的 Skills 发布并公开到 `skills.sh` 无需传统 npm publish，步骤如下：
+
+1. **规范校验与打包**：
+   确保技能文件符合 Agent Skills 规范（`SKILL.md` 包含 YAML frontmatter、Use when / Do NOT 边界、行数 <500）：
+   ```bash
+   npm run pack:skills
+   npm test
+   ```
+2. **Push 至 GitHub Public 仓库**：
+   ```bash
+   git add .
+   git commit -m "feat(skills): update skills definitions"
+   git push origin main
+   ```
+3. **发布 Tag & Release（推荐）**：
+   ```bash
+   npm run versions                 # 真源 stamp；全量 tag 用 Desktop 版本
+   git tag v<desktop-version>
+   git push origin v<desktop-version>
+   ```
+4. **生态发现与在线安装**：
+   发布后，全球开发者即可通过以下方式发现与安装：
+   - **CLI 直接索引**：`npx skills add topmindspace/topmind-skills -g -y`
+   - **查看目录**：`npx skills add topmindspace/topmind-skills -l`
+   - **网页版浏览**：访问 `https://skills.sh/topmindspace/topmind-skills`
+
+---
+
+## Two installers (pick one)
+
+### A. Community CLI — `npx skills`（和开源 skills 生态一致）
+
+已验证：本仓库可被直接发现 pack 内全部 skill（含可选 weread / x / ledger）。
+
+```bash
+# 安装到用户全局（$HOME/.claude/skills 等，按 agent 探测）
+npx skills add topmindspace/topmind-skills -g -y
+
+# 只装部分
+npx skills add topmindspace/topmind-skills -g -y -s topmind -s topmind-capture
+
+# 升级
+npx skills update -g -y
+
+# 列出仓库里有什么（不装）
+npx skills add topmindspace/topmind-skills -l
+```
+
+适用：Claude Code / Cursor / Codex / OpenCode 等认 Agent Skills 目录布局的 host。
+
+#### 关于 “Failed to install 9 / PromptScript”
+
+`npx skills add … -g` **多数已经成功**。日志里先有：
+
+```text
+◇  Installed 10 skills
+✓ $HOME/.agents/skills/topmind  (+ symlink → Claude Code / Codex / …)
+```
+
+末尾的 `Failed to install 9` **只针对 PromptScript**：该 host **不支持 global 安装**，不是 topmind 包损坏。可忽略，或不要装 PromptScript。
+
+验收：
+
+```bash
+ls $HOME/.agents/skills/topmind/SKILL.md
+ls $HOME/.claude/skills/topmind   # 常为 symlink → $HOME/.agents/skills/topmind
+```
+
+#### 社区 CLI 不会装 `shared/`（重要）
+
+社区 CLI 只复制含 `SKILL.md` 的目录。topmind skill 内有 `../shared/*.md` 渐进披露链接，**缺 `shared/` 时子文档打不开**。
+
+这是开放标准「单 skill 目录」与 topmind **pack 级 shared** 的已知差异。加载契约见 [`shared/host-loading.md`](./shared/host-loading.md)。
+
+装完社区 CLI 后**务必**再跑 pack-aware（或手动拷 shared）：
+
+```bash
+# ① 推荐：pack-aware 安装器（带 shared/ + topmind-pack.json）
+# 通用根（npx skills 主目录）
+node bin/install-skills.mjs add topmindspace/topmind-skills --dest $HOME/.agents/skills
+# 或 Claude 默认根
+node bin/install-skills.mjs add topmindspace/topmind-skills -g
+
+# ② 或手动把 monorepo / Release 包里的 shared 放到同级
+mkdir -p $HOME/.agents/skills
+cp -R /path/to/topmind-skills/shared $HOME/.agents/skills/shared
+```
+
+#### 其他 Host 也能装
+
+| Host 类型 | 做法 |
+|-----------|------|
+| Claude Code / Cursor / Codex / OpenCode | 目录布局 = Agent Skills：`{skillsRoot}/{name}/SKILL.md` |
+| 只认单路径 | symlink 整个 pack 根或 pack-aware 装到 host skills 根 |
+| MCP-only 宿主 | Skills 仍是 Markdown 指令；确定性命令可另接 UTR MCP（可选） |
+| 无 skill 系统 | 把 `topmind/SKILL.md` 当 system 片段粘贴；shared 按链接手动附上 |
+
+**Discovery**：Host 应只预加载各 skill 的 `name`+`description`（≤1024 字符）。  
+**Activation**：匹配任务后再读完整 `SKILL.md`。  
+**Resources**：需要时再读 `shared/` 与 `references/`。
+
+### Zip 加载报 `SKILL.md not found`？
+
+topmind Release 包是 **多 skill 组合包**，不是单目录 skill：
+
+```text
+topmind-skills-<ver>.zip
+└── topmind-skills-<ver>/
+    ├── SKILL.md              ← 根入口 = router
+    ├── topmind/SKILL.md      ← 推荐日常入口
+    ├── topmind-capture/…
+    └── shared/
+```
+
+| Host 行为 | 正确处理 |
+|-----------|----------|
+| 解压 zip 后在根找 `SKILL.md` | 用包内根 `SKILL.md`（router） |
+| 扫描 `*/SKILL.md` 多 skill | 装全部 `topmind*` 目录 + `shared/` |
+| 社区 `npx skills add` | 从 GitHub 仓根装 skill 目录（不依赖 zip 根） |
+
+`skills.md` 是 **包索引**（人类可读），不是 Agent Skills 标准的 `SKILL.md` 替代名——两者并存，不要把 `skills.md` 改成唯一入口。
+
+### B. Pack-aware 安装器 — `bin/install-skills.mjs`（推荐给 topmind）
+
+会装齐 **skill 目录 + `shared/` + `topmind-pack.json` + …**，保证 `../shared/*.md` 渐进披露链接可用。
+
+```bash
+# ① 指定仓库（默认 path=skills，装到 Claude 用户目录）
+node bin/install-skills.mjs add topmindspace/topmind-skills -g
+
+# ② 指定仓库 + 自定义 monorepo 子路径 + 自定义目标
+node bin/install-skills.mjs add topmindspace/topmind-skills \
+  --dest $HOME/.claude/skills
+
+# ③ 装到「当前项目」而不是用户全局
+node bin/install-skills.mjs add topmindspace/topmind-skills \
+  --dest ./.claude/skills
+
+# ④ 本地 monorepo / 任意目录当源
+node bin/install-skills.mjs add ./skills --dest $HOME/.claude/skills
+node bin/install-skills.mjs add ./skills --mode symlink --dest $HOME/.claude/skills
+
+# ⑤ 从 Release zip（有 topmind-skills-*.zip 时）
+node bin/install-skills.mjs add release:latest -g
+
+# ⑥ 升级（读目标目录里的回执，重新拉同一源）
+node bin/install-skills.mjs update --dest $HOME/.claude/skills
+
+# ⑦ 只看会装什么
+node bin/install-skills.mjs list topmindspace/topmind-skills
+```
+
+根脚本别名：
+
+```bash
+npm run install -- add topmindspace/topmind-skills -g
+npm run update -- --dest $HOME/.claude/skills
+```
+
+私有仓：
+
+```bash
+export GH_TOKEN=...    # 或 GITHUB_TOKEN
+node bin/install-skills.mjs add topmindspace/topmind-skills -g
+```
+
+---
+
+## Source 写法
+
+| Source | 含义 |
+|--------|------|
+| `topmindspace/topmind-skills` | GitHub `owner/repo`，默认分支，pack 在仓根 |
+| `topmindspace/topmind-skills@v*` | 指定 ref / tag（版本见 `topmind-pack.json`） |
+| `https://github.com/topmindspace/topmind-skills.git` | 任意 git URL |
+| `./skills` / 绝对路径 | 本地 pack 根（含 `topmind-pack.json` 或 `*/SKILL.md`） |
+| `release:latest` | GitHub Release 里的 `topmind-skills-*.zip` |
+
+| Option | 含义 |
+|--------|------|
+| `--path <subdir>` | 仓库内 pack 子目录（默认 `.` 仓根） |
+| `--dest <dir>` | 安装目标 = host 的 skills 根 |
+| `-g` / `--global` | dest → `$HOME/.claude/skills` |
+| `--host codex` 等 | 换默认 dest |
+| `--mode symlink` | 仅本地源；开发时热更新 |
+| `--skill topmind` | 只装列出的 skill id（可重复） |
+| `--locale en-US` | 安装 locale overlay（回退到 `topmind_LOCALE` 环境变量）。**当前未随包提供任何 overlay**——技能正文以 zh-CN 为准，`--locale` 会回退到中文正文，不是英文版技能。 |
+
+---
+
+## Host destinations
+
+| Host | 典型 dest | 写法 |
+|------|-----------|------|
+| Claude Code | `$HOME/.claude/skills` 或项目 `.claude/skills` | `-g` 或 `--dest ./.claude/skills` |
+| Codex | `$HOME/.codex/skills` | `--host codex` |
+| Hermes | `$HOME/.hermes/skills` | `--host hermes` |
+| OpenCode | 项目 skills 路径 / config `skills.paths` | `--host opencode` 或见 `integrations/opencode/` |
+
+`install-targets/*.json` 描述各 host 契约（无硬编码本机绝对路径）。
+
+---
+
+## Update 原理
+
+安装后在 dest 写入：
+
+```text
+{dest}/.topmind-skills-install.json
+```
+
+里面记录了 `source` / `path` / `version`。之后只需：
+
+```bash
+node bin/install-skills.mjs update --dest <同一 dest>
+```
+
+就会按原 source 再拉一遍并覆盖（升级）。
+
+社区 CLI 对应：
+
+```bash
+npx skills update -g -y
+```
+
+---
+
+## 装完长什么样
+
+```text
+$HOME/.claude/skills/          # 或你指定的 --dest
+├── topmind/SKILL.md       # 日常唯一入口
+├── topmind-capture/
+├── topmind-organize/
+├── …
+├── shared/                # pack-aware 安装器会带上
+├── topmind-pack.json
+└── .topmind-skills-install.json
+```
+
+在 host 里调用 **`topmind`**。子 skill 是模块，不是并列产品入口。
+
+---
+
+## OpenCode（可选）
+
+示例：`integrations/opencode/opencode.example.json` — 用 `skills.paths` 指向本仓根或已安装目录。
+
+---
+
+## Security
+
+- Skills 是 Markdown 指令；不信任的 fork 先审再装。
+- API Key 不要写进 skill 文件。
+- 安装器只写 `--dest`，不改 engine 仓库（除非 dest 故意指过去）。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TopMindSpace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,162 @@
+# topmind Skills
+
+Portable AI skill pack: the same content contract on Claude Code / Codex / OpenCode / Hermes and other hosts.
+
+[简体中文](README.md) · [English](README.en.md) · [Product](https://github.com/topmindspace/topmind) · [Install](./INSTALL.md) · [Publish to skills.sh](./INSTALL.md#publishing-to-skillssh--open-agent-skills-registry)
+
+```bash
+# 1) Community CLI (fast try; may omit shared/)
+npx skills add topmindspace/topmind-skills -g -y
+
+# 2) Pack-aware installer (recommended · includes shared/ · writes receipt)
+# From a topmind-skills checkout:
+npm run install -- add topmindspace/topmind-skills -g
+npm run update -- --dest $HOME/.claude/skills
+
+# Or without clone — run installer from GitHub:
+npx --yes github:topmindspace/topmind-skills install -g
+
+# 3) From GitHub Release (pinned version / offline)
+node bin/install-skills.mjs add release:latest -g
+# or after downloading topmind-skills-<ver>.zip:
+# node bin/install-skills.mjs add ./unpacked --dest $HOME/.claude/skills
+```
+
+**Version and manifest truth:** [`topmind-pack.json`](./topmind-pack.json) (`npm run versions`).  
+Each `SKILL.md` `version` **must** equal the pack version.
+
+---
+
+## 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)
+├── topmind-wechat/          # optional WeChat write sub-skill (not a peer entry)
+├── shared/                  # write receipts · degradation · 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
+```
+
+| Kind | Modules |
+|------|---------|
+| **Entry** | `topmind` only |
+| **Actions** | capture · organize · write · memory · maintain · loop |
+| **Connectors** | weread · x (optional) |
+| **Optional** | wechat (公众号 write 子技能) · ledger (记账 · memory-plane books) |
+
+> Sub-skill trigger words exist for host routing. They are **not** a second product front door.
+
+---
+
+## Product contract
+
+```text
+User experience:     capture-first
+Data organization:   category-first + topic-emerges
+Content truth:       topmind-workspace/categories-and-topics
+Capability model:    action-first
+Save settings:       auto | confirm
+Safety model:        reversible by default
+```
+
+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: `收进来 -> 继续做 -> 交付/沉淀 -> 找回/调整`  
+(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
+version: <pack.version>         # required; = topmind-pack.json version
+description: >-                  # required; Use when + Do not use
+  …
+action_category: capture        # skill taxonomy (not user note category)
+triggers: [...]
+entrypoint: false               # only topmind router is true
+author: TopMindSpace
+license: MIT
+homepage: https://github.com/topmindspace/topmind-skills
+degradation: ../shared/capability-degradation.md
+---
+```
+
+Enforced by `skills/tests/package-manifest.test.mjs`. One pack JSON; no per-skill second manifest. Full schema: [`../SKILL-ARCHITECTURE.md`](../SKILL-ARCHITECTURE.md).
+
+---
+
+## Workspace contract
+
+```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
+```
+
+Topic:
+
+```text
+{category}/{YYYY-theme}/
+├── topic.md                 # optional
+├── *.md                     # notes at topic root
+└── images/                  # optional
+```
+
+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.
+
+Do not hardcode absolute paths — infer `workspace_root` from the host or ask.
+
+### 6 条核心规约
+
+1. **大类不重叠**  
+2. **专题自然涌现**  
+3. **动态类特殊**（默认平铺）  
+4. **兜底类清理**（约 30 天）  
+5. **参考资料定位**  
+6. **大类命名稳定**（rename via migration）  
+
+Full rules: [`../PROJECT-MODEL.md`](../PROJECT-MODEL.md) §3.
+
+---
+
+## 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/final files → revision copy (`文章 - 修订版.md`), not in-place auto-edit  
+- 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
+
+Packaged skill directories (7 core + 2 optional connectors + optional ledger + optional wechat sub-skill) 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).
+
+Host adapters must **not** change content truth, add parallel daily entries, or store content in agent runtime state. See [`../PRODUCT-BOUNDARIES.md`](../PRODUCT-BOUNDARIES.md).

package/README.md

@@ -0,0 +1,162 @@
+# topmind Skills
+
+可移植 AI 技能包：在 Claude Code / Codex / OpenCode / Hermes 等 Host 上使用同一套内容约定。
+
+[简体中文](README.md) · [English](README.en.md) · [产品总览](https://github.com/topmindspace/topmind) · [安装与发布](./INSTALL.md) · [发布到 skills.sh](./INSTALL.md#publishing-to-skillssh--open-agent-skills-registry)
+
+```bash
+# 1) 社区 CLI（快速试用；可能不含 shared/）
+npx skills add topmindspace/topmind-skills -g -y
+
+# 2) Pack-aware 安装器（推荐生产 · 含 shared/ · 可写回执）
+# 在 topmind-skills 仓内：
+npm run install -- add topmindspace/topmind-skills -g
+npm run update -- --dest $HOME/.claude/skills
+
+# 或不 clone，直接用 npx 跑 GitHub 上的安装器：
+npx --yes github:topmindspace/topmind-skills install -g
+
+# 3) 从 GitHub Release 装（离线/固定版本）
+node bin/install-skills.mjs add release:latest -g
+# 或下载 topmind-skills-<ver>.zip 后：
+# node bin/install-skills.mjs add ./unpacked --dest $HOME/.claude/skills
+```
+
+**版本与清单真源：** [`topmind-pack.json`](./topmind-pack.json)（`npm run versions`）。  
+各 `SKILL.md` 的 `version` **必须**等于 pack 版本。
+
+---
+
+## 结构
+
+```text
+topmind-skills/              # pack 根 = 仓库根
+├── topmind/                 # 唯一日常入口（router）
+├── topmind-capture|organize|write|memory|maintain|loop/
+├── topmind-weread|x/        # 可选连接器
+├── topmind-ledger/          # 可选记账（记忆平面账本）
+├── topmind-wechat/          # 可选公众号 write 子技能（不是并列入口）
+├── shared/                  # 写回回执 · 降级 · 捕获 …
+├── install-targets/         # Host 安装形状
+├── evals/evals.json
+├── bin/install-skills.mjs   # pack-aware 安装器（含 shared/）
+├── scripts/build-pack.mjs
+└── topmind-pack.json        # 版本真源
+```
+
+| 类型 | 模块 |
+|------|------|
+| **入口** | `topmind` only |
+| **动作** | capture · organize · write · memory · maintain · loop |
+| **连接器** | weread · x（可选） |
+| **可选** | wechat（公众号 write 子技能）· ledger（记账 · 记忆平面账本） |
+
+> 子 skill 触发词只服务 Host 路由，**不是**第二前台入口。
+
+---
+
+## 产品契约
+
+```text
+User experience:     capture-first
+Data organization:   category-first + topic-emerges
+Content truth:       topmind-workspace/categories-and-topics
+Capability model:    action-first
+Save settings:       auto | confirm
+Safety model:        reversible by default
+```
+
+日常入口只暴露 `topmind`。Host 会话状态不得成为 topmind 内容真源。  
+本 pack **不要求 Desktop**。**UTR 可选** — 没有 UTR 时用 Host 文件工具。
+
+工作流：`收进来 -> 继续做 -> 交付/沉淀 -> 找回/调整`  
+（用户说「收一下」「记一下」「整理」「写成稿」「跑一遍 loop」— router 推断类别 / 专题 / 动作。）
+
+---
+
+## SKILL.md frontmatter
+
+```yaml
+---
+name: <kebab-case-id>           # required; matches directory name
+version: <pack.version>         # required; = topmind-pack.json version
+description: >-                  # required; Use when + Do not use
+  …
+action_category: capture        # skill taxonomy (not user note category)
+triggers: [...]
+entrypoint: false               # only topmind router is true
+author: TopMindSpace
+license: MIT
+homepage: https://github.com/topmindspace/topmind-skills
+degradation: ../shared/capability-degradation.md
+---
+```
+
+由 `skills/tests/package-manifest.test.mjs` 强制校验。一个 pack JSON，无 per-skill 第二清单。完整 schema：[`../SKILL-ARCHITECTURE.md`](../SKILL-ARCHITECTURE.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
+```
+
+专题：
+
+```text
+{category}/{YYYY-theme}/
+├── topic.md                 # optional
+├── *.md                     # notes at topic root
+└── images/                  # optional
+```
+
+尚无专题时，散篇放在 `{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）  
+
+完整规则：[`../PROJECT-MODEL.md`](../PROJECT-MODEL.md) §3。
+
+---
+
+## 行为规则
+
+- 先捕获；不要因为分类不完美而挡住简单保存  
+- 信号足够强时自动路由；否则走 **role:buffer**（现场 Inbox 目录，不要只写死 `00-Inbox/`）  
+- 专题不清时，散篇放在大类根  
+- 每次写入返回回执（路径、路由原因、下一步）  
+- `source_type`: `user-original` | `external-capture` | `ai-derived`  
+- UTR 可选 — Host 文件工具遵守同一契约  
+- 保存设置协议：`writeback_mode: auto | confirm`  
+- 锁定/定稿文件 → 修订副本（`文章 - 修订版.md`），不要原地自动改  
+- 本 pack 不要求 Desktop  
+- **复合纪律（不改结构）：** organize 把综合写回磁盘；write 先读可选 `topic.md`；memory 仅在明确确认后写；capture 从不改 `topic.md`；**不要**硬造 `INDEX.md` / 平行 wiki 树（见 `shared/project-model-brief.md`）  
+
+---
+
+## 安装目标
+
+已打包的 skill 目录（7 个核心 + 2 个可选连接器 + 可选记账）可以符号链接或复制到 Claude Code、Codex、OpenCode、Hermes 等。  
+优先使用 pack-aware 安装器，保证 `shared/` 与 `topmind-pack.json` 完整 — 见 [`INSTALL.md`](./INSTALL.md)。
+
+Host 适配器**不得**改变内容真源、新增并列日常入口，或把内容存进 agent 运行态。见 [`../PRODUCT-BOUNDARIES.md`](../PRODUCT-BOUNDARIES.md)。