@topmindspace/topmind-writing-skills 0.8.45 → 0.8.47

package/CHANGELOG.md

@@ -1,3 +1,109 @@
+## [0.8.47] - 2026-10-18
+
+> 全面整理文档：README 和各技能文档按「原则优先」四层结构重写，剩余的「铁律」措辞改成「原则 + 怎么判断」，清理废弃文件和过时说明；新增多环境协作字段，渲染脚本去掉 HTML 注释。
+> 根包 0.8.46 → **0.8.47**（patch）；技能版本：topmind-briefs 0.2.25 → 0.2.26、topmind-cover 0.4.14 → 0.4.15、topmind-format 0.1.10 → 0.1.11、topmind-poster 0.1.7 → 0.1.8、topmind-revise 0.1.2 → 0.1.3、topmind-viral-posts 0.3.17 → 0.3.18、topmind-wechat-post 0.3.17 → 0.3.18、topmind-x-article 0.4.23 → 0.4.24。
+
+### 优化（文档整理）
+
+- 根 README（中 / 英）重写：结论先行，技能表带当前版本，新增「写作理念」四层表（第 0 层写作原则 → 第 1 层信息设计 → 第 2 层措辞口吻 → 第 3 层审稿）、文章文件夹结构（`骨架.md`、`参考/`）和多环境协作说明；旧版本号表更新。
+- 深层参考里剩余的「铁律 / 红线 / 纪律」改成「原则 + 怎么判断」：cover 的 `cover-styles.md`（各风格「怎么判断」）、`md3-foundation.md`，wechat-post 的 `known-pits.md`（「怎么避免」）、`typography-rules.md`、`writing-quality.md`、`theme-map.md`，viral-posts 的 `patterns.md`，poster 的内容原则。真正的硬约束（安全区、原创、事实、不改字、平台格式检测、交付格式）保留并标「硬约束」。
+- 「必读必守」统一改成「必读（交付格式是硬约束）」，「核心经验对照」改名「措辞原则对照」。
+- topmind-revise：流程写明「声明 + 备份 → ⓪ 结构 → ① 事实 → …」；README 的「三层规则」换成四层表；第 ⑤ 步按 `core-voice.md` 十条原则和人设抽查。
+- topmind-briefs：删除无引用的 `style-guide.md`（禁止清单式写法），其中的开头写法和发前自检改写成表格并入 `platform-specs.md`；写作步骤加上人设一行。
+- topmind-revise、topmind-viral-posts 的 SKILL.md 补上 `research-mode.md` 入口（之前分发了但没有链接）。
+- topmind-x-article README 的文件夹说明补上 `骨架.md`、`参考/` 和多环境字段。
+- topmind-wechat-post `element-spec.md` 的 `:::` 容器一节标明「只用于旧交付包」；脚本帮助文本同步说明 `:::` 和扩展标记只为旧稿兼容。
+- 公开仓库清理：去掉示例里的私有环境名和「用户偏好」类个人化表述，示例改用中性名称。
+- `core-voice.md` 原则 9 的人设改成「还在学习的普通人」：不是专家，不像科普老师，可以带一点老司机式的自嘲；topmind-viral-posts 的写作要点同步。
+- 删除 `writing-principles.md` 迁移说明文件（0.8.46 已按内容拆到各层，仓库里不再有引用），`shared/manifest.json` 同步去掉；briefs / viral-posts / wechat-post / x-article 不再带这份副本。
+
+### 特性支持
+
+- 渲染脚本（`md2wechat.py`、`md2x-html.py`、`md2x.py`）去掉 HTML 注释：源稿里临时写的 `<!-- 提示 -->`（可跨行）不进公众号版和 X 版；代码块和行内代码里的注释原样保留。负例测试同步。
+- 多环境协作字段：`article_scaffold.py`（以及 wechat-post 的 `new-article.py`）新建源稿时写 `updated_at`（当前时间，ISO 8601 带时区）、`updated_env`、`updated_by`，后两项用 `--env` / `--by` 填，缺省留空；文章文件夹多建一个 `参考/`，放其他环境写的同主题稿件和素材（`参考-<环境>-<YYYYMMDD>.md`，永远不当源稿）。
+- `check_article.py` 新增 H1 提示：`updated_at` 写了但没有时区时提醒；三个字段都是可选的，旧稿缺了不报，退出码不变。
+- `workspace.md` 新增「多环境协作」一条：字段写法、新旧以 `updated_at` 为准、两边都改过时不覆盖而是存进 `参考/`、提交信息带一致前缀（wechat-post / x-article 的 SKILL.md 与 README 的文件夹说明同步）。
+
+## [0.8.46] - 2026-10-18
+
+> 经过 8 轮对练，写作技能改为原则优先：先想清楚要传达什么、内容用什么形式最好读，再谈措辞；去 AI 味改成成稿后的审稿步骤，脚本只提示、人来判断。
+> 根包 0.8.45 → **0.8.46**（patch）；技能版本：topmind-briefs 0.2.24 → 0.2.25、topmind-cover 0.4.13 → 0.4.14、topmind-format 0.1.9 → 0.1.10、topmind-poster 0.1.6 → 0.1.7、topmind-revise 0.1.1 → 0.1.2、topmind-viral-posts 0.3.16 → 0.3.17、topmind-wechat-post 0.3.16 → 0.3.17、topmind-x-article 0.4.22 → 0.4.23。
+
+### 优化（原则优先的第 0、1 层）
+
+- 新增 `social-writing-principles.md`（第 0 层）：8 条社交媒体写作原则（先想清楚要传达什么、结论先行、每一句都给读者新信息、形式跟着内容走、简单清楚常用词、原图和数据胜过转述、站在读者那边、真实有分寸），每条按「原则 → 为什么 → 怎么判断 → 怎么做 → 例子」写，例子只做说明，不是硬门禁。
+- 新增 `information-design.md`（第 1 层）：先写骨架再写文字、内容 → 形式决策表、篇幅和密度参考线、六个去啰嗦的判断法、X 与公众号的形式差异、I1–I8 信息设计提示的说明。
+- 两份文件分发到全部 8 个技能（含之前没有共享写作原则的 cover、poster、format、revise）；每个 SKILL.md 开头新增「先读：写作原则与信息设计」，并按技能定位写一句怎么用。
+
+### 特性支持（信息设计骨架与结构复查）
+
+- `article_scaffold.py` 新建文章文件夹时生成 `骨架.md`：类型、主要信息、读者、篇幅预算，以及每节要点 / 形式 / 图表计划 / 字数。骨架单独放文件、不写进源稿，不会漏进公众号版或 X 版。
+- topmind-wechat-post、topmind-x-article 的长文流程在找图、写字之前加「先写骨架」，写完回头对一遍。
+- topmind-revise 新增 ⓪ 结构复查（先于事实关）和 `depth` 参数：默认 `light` 只诊断，外加低风险的结构改动（并列段转列表、对照转表格、删重复段）；`depth=structure` 才重排、拆合章节。随笔类稿子不按「段落多」诊断。
+- 改稿报告新增「信息设计诊断（⓪ 结构）」一节（`revise_check.py --report` 骨架和报告模板同步）；改动表依据可写「⓪ 结构」，`--declare` 时这类改动不计入过度改稿比例。
+- 负例测试新增：scaffold 生成骨架.md 且源稿里不写骨架；⓪ 结构登记不计入过度改稿；报告骨架里信息设计诊断在改动表之前。
+
+### 优化（措辞层改成原则优先，拆分旧写作规范）
+
+- `core-voice.md`（第 2 层）开头改成十条原则（平实好懂、开门见山、结构就是路标、观点句要有内容、数字给对象、出处可查、按读者定详略、语气看场景、具体胜于泛称、改稿只动有问题的地方），每条写「为什么 → 怎么判断 → 例子 → 对应 V 编号」；V01–V33 保留编号，作为场景里的例子，脚本提示照常引用。
+- `de-ai-rules.md` 标明「审稿用，不在生成时加载」：写的时候按第 0–2 层的正向写法，成稿后自查和改稿时再对照；新增「零、AI 味从哪来」，按七类根因归组 Z / E / P 模式，并指回对应原则；自查办法（朗读、删句、替换）并入「怎么跑」。
+- 旧的 `writing-principles.md` 按内容拆到各层：研究类选题 → 新增 `research-mode.md`；工作区与交付规约 → 新增 `workspace.md`（topmind-wechat-post / topmind-x-article）；图说事实 → `image-sourcing.md`；可视化和篇幅 → `information-design.md`；措辞和吸引力 → `core-voice.md`。原文件留一版迁移对照表，下个版本删除。
+- `image-sourcing.md` 新增分发到 topmind-cover、topmind-poster。
+- SKILL.md 里的「铁律」措辞放软：语言、写作、配图、设计改成原则 / 约定；事实、不改字、图片文件名一致这类真正的硬约束保留并标「硬约束」。
+- 各技能里指向旧文件章节的链接全部改到新位置。
+
+### 特性支持（信息设计提示 I1–I8）
+
+- 新增共享脚本 `info_design_hints.py`：I1 连续纯文字块过多、I2 图表列表太少、I3 并列项可转列表、I4 对照可转表格、I5 相邻段落重复或首句复读小标题、I6 首段太长或没交底、I7 长节全是段落、I8 超出 `骨架.md` 的篇幅预算。只提示、不判卷：永远不进 `--strict`，不新增禁用词；`type: essay` 的随笔不提示 I1、I2、I7。
+- `de_ai_lint.py` 对长文 Markdown 附带 I 提示（和 W / H 分开显示，`--json` 多一个 `design` 字段，`--no-design` 关掉）；`lint-wechat.py` 体检多一节「信息设计提示」；`revise_check.py` 给出改前 / 改后的 I 提示数，`--report` 把改后稿的 I 提示填进「信息设计诊断」。
+- 新增回归测试 `scripts/test_info_design.py`（应报 12 条、不应报 9 条，另查 I 提示不让 `--strict` 失败、`--no-design`、`--json`、读骨架预算），由 `test_lint_rules.py` 一起跑；revise 负例新增长文 I 提示数检查；评测用例新增「大段文字看着累，帮我改稿」。
+
+### 优化（其余技能对齐第 0、1 层，README 写作理念）
+
+- topmind-poster 新增「内容 → 图表」：按信息设计决策表选版式（排名、时间变化、多维比较、流程、占比、关键数字），一张图一个结论、图标题写结论、能用原图就不重画。
+- topmind-cover 设计原则开头加一条：先想清楚这张图要传达的一个信息，有官方原图、产品截图的优先用原图做主体。
+- topmind-format 新增「可转列表 / 表格的地方只报告」：跑 `info_design_hints.py` 拿 I3 / I4 / I1 提示，原文是一段话但像列表的，不替用户拆，写进改动说明。
+- topmind-briefs 写内容第一步改成先想清楚要传达的一件事，并列、对比、步骤先按决策表定形式。
+- 各技能「没装 revise 时手动走」的流程都加上 ⓪ 结构；topmind-viral-posts 的去 AI 味改成成稿后自查。
+- README / README.en 的「共用写作流程」改写成「写作理念：原则优先」：第 0 层写作原则 → 第 1 层信息设计 → 第 2 层措辞口吻 → 审稿时的去 AI 味 → revise 执行；脚本只提示、人来判断。
+
+### 优化（长文交付结构）
+
+- frontmatter 新增可选 `subtitle`（副标题）：`article_scaffold.py` 生成空字段；`check_article.py` 留空不报，写了但和标题一样或超过 40 字给 W6；`md2wechat.py` 把它写进图片上传清单的「摘要」（公众号后台摘要栏可直接用），`md2x-html.py` 只在页顶预览里给出（no-paste，不进复制内容）；两边都不往正文里塞。
+- `check_article.py` 新增封面检查：草稿期 cover 指向的文件还没做（或 cover 留空）给 W5，status 是定稿 / 已发布时是 E7。刚用 `article_scaffold.py` 建好的文件夹跑体检只有 W5，脚手架和体检口径对齐。
+- 文档：wechat-post `theme-map.md`、`element-spec.md` 的章节编号描述改成「手写序号原样保留，都没写时才自动编号」，和 `md2wechat.py` 的实际行为一致；wechat-post / x-article SKILL.md 补上 subtitle、W5 / E7 和 raw/ 下的改稿备份位置；`revision-workflow.md` 提示可以在 Obsidian 里排除 raw/，免得搜出两份同名文章。
+- 回归：wechat-post 负向测试新增 6 条（subtitle 进清单 / 留空不出、脚手架只有 W5、写出 subtitle 字段、W6、定稿缺封面 E7）；x-article 新增 1 条（subtitle 只在 no-paste 预览出现一次）。
+
+### 优化（改稿流程补全与规则层）
+
+- topmind-revise：写清 revise 和 embed 的边界（用户直接说「改稿」就是 revise；embed 步骤、备份、报告都一样，只是对话里只回终稿和三行摘要）；长文备份位置统一为 `<文章文件夹>/raw/备份-<时间戳>/`，单个短文件放同目录 `备份-<时间戳>-<稿名>/`。
+- `revise_check.py --report` 报告骨架：改动表按段落 diff 预填「原文 / 改后」；「保留未改的命中」列出改后稿全部 W 和 H（不会再出现写着「无」却还有命中）；新增「人工检查（事实关 / 逻辑关）」清单。
+- `revise_check.py --declare 改稿报告.md`：改动表里依据写「① 事实」「② 逻辑」「作者意见」的段落单独列出、不计入过度改稿；依据是规则编号的照算。
+- `core-voice.md`：33 条场景规则每条都有 ✅ / ❌ 虚构示例；新增「人设是普通使用者，吐槽不科普」（现为十条原则的第 9 条）；吸收新的通用写法：短文开头可以先亮态度或用一句惊叹式设问（V05）、立场清楚但留反驳余地、不写「理由就一条」式总结腔（V08）、不用短句对子和互动问句收尾（V10）、比较选知名对手、作者自述的大概数照原话（V12）、推测写成问句、真疑问可以装傻问（V22）、回复态度放第一个字、带保留的赞同用口语转折、不重复原帖数字（V29）、段子一个主角不堆细节（V31）、同一个词全文一种写法（V32）。
+- `de_ai_lint.py` W9 新增总结腔：「理由就一条：」「原因只有一个，」「说到底就一句：」；`de-ai-rules.md` Z05 同步。
+- `fact-check.md` 新增「作者自述与回忆」：作者经历类说法要有记录支撑，没有就列进未核实条目；`revision-workflow.md` 的事实关、逻辑关、过度改稿和报告要求同步。
+- 新增 `topmind-revise/references/calibration-drill.md`：可选的风格校准对练方法（AI 出候选不标答案、作者答选择和理由、记冲突、复测、整篇验收），结果写进作者私有规则。
+- briefs / viral-posts 的短文、段子、回复写作要点同步上面的新写法。
+- 回归：`test_lint_rules.py` 新增应报 W 4 条（总结腔）、不应报 W 4 条；revise 负向测试新增 6 条（--declare 2 条和坏输入 1 条、报告骨架 3 条）。
+
+### 优化（检查脚本少误报、少漏报）
+
+- `de_ai_lint.py`：「」“”里讨论的短词，以及「改前：」「原文：」「反例：」「A：」「B：」开头的示例行，不再参与词面和句式检查（段长照查），教学 / 复盘类文章不再被自己引用的反例刷屏。
+- `de_ai_lint.py` H4：摘录取完整数字（「约 120」不再显示成「约 1」）；「约 / 大约 + 数字」只在带万 / 亿 / 千或同一句在做对比时提示，作者自述的大概数（「试了约 50 个提示词」）不报；「左右」「较…高出」照旧。
+- `de_ai_lint.py` 新增：H5 补「段末两个等长短分句」（「它写稿，我挑刺。」）；H13 小标题格式（序号有的写有的没写、一个小标题里标点叠在一起，V06）；H14 同一个中英混排说法有带空格和不带空格两种写法（「去AI味」/「去 AI 味」）。
+- 字数口径统一到 `count_words.py`：`de_ai_lint` 的 W14、`lint-wechat.py` 的字数与段长、`scan_ai_flavor` 的字数用同一个算法，三处数字一致。
+- `revise_check.py`：数字、引语、英文专名、确定性词改成按出现次数比，新增「次数变化」（删掉一处「多半」、多引用一次数字都会列出）；「」里少于 6 个字且不带标点的内容当作讨论某个词，不算引语。
+- `check_article.py`：草稿期还没补的占位截图（文件名带「待补 / 占位 / placeholder / 截图」，或在 `素材来源.md` 里登记过）只给新 W4，不再报 E3；status 是定稿 / 已发布时照样 E3，放着占位图报新 E6；占位图参与编号顺序检查，不再误报编号不连续。
+- 文档：`de-ai-rules.md`（Z21 / Z25 / Z36 与「怎么跑」）、revise / wechat-post 的 SKILL.md 脚本说明同步；wechat-post `typography-rules.md` 的「结尾三段式（抛出问题 / 邀请讨论 / 引导关注）」改成 V10 的收尾写法。
+- 回归：`test_lint_rules.py` 新增「不应报 H」一组 9 条、应报 W 3 条（反例行 / 讨论词不报 W 的反向样例）、应报 H 5 条，外加 H4 摘录完整性和 W14 / count_words 口径一致两项断言；revise 负向测试新增 6 条（次数比对 3 条、占位截图 3 条）。
+
+### 优化（去掉 `++关键词++` 标记层）
+
+- `lint-wechat.py`：不再检查「标记覆盖率 ≥60%」、不再建议用 `++关键词++` 标重点；和它绑定的「锚点层加粗 ≤5 处」一并去掉，重点过多只看原有的强调占比（> 20% 提醒）。体检摘要改为「字数 · 正文段数 · 加粗处数 · 预计阅读」。
+- 旧稿里已有的 `++x++` / `<u>` / `==x==` / `~~x~~`：`md2wechat.py` 照常渲染（兼容读取），lint 不报、不计覆盖率。
+- 文档：wechat-post 的 `element-spec.md`（「视觉层级」三层改为「强调」：源稿只用标准加粗和引用块）、`typography-rules.md` 第 5 条、`theme-map.md` 的强调规则表同步改写，不再教人写扩展标记。
+- 回归：wechat-post 负向测试新增 3 条（不报覆盖率、不报加粗上限、旧稿扩展标记照常读）。
+
 ## [0.8.45] - 2026-10-18
 
 > 根包 0.8.44 → **0.8.45**（patch）；技能版本：topmind-wechat-post 0.3.15 → 0.3.16、topmind-x-article 0.4.21 → 0.4.22、topmind-revise 0.1.0 → 0.1.1、topmind-briefs 0.2.23 → 0.2.24、topmind-cover 0.4.12 → 0.4.13、topmind-format 0.1.8 → 0.1.9、topmind-viral-posts 0.3.15 → 0.3.16（后四个只是随包共享副本更新）；topmind-poster 0.1.6 不变。
@@ -1177,7 +1283,7 @@
   交付包 / 审校改写 / 质量三关（事实·逻辑·去 AI 味 ≥85）/ 状态同步 / 微信内联排版（`md2wechat --embed-images`）/ 发布清单。
   适配点：frontmatter 去 topmind-pack 专有键（`degradation`/`action_category`/`entrypoint`），
   跨 skill 引用改为通用表述，`writing-quality.md` 改用技能自带 `scan_ai_flavor.py`
-  （原引用本机 `~/.workbuddy` 路径），`md2wechat.py` 缺失输入改干净报错（原 Traceback）。
+  （原引用本机私有路径），`md2wechat.py` 缺失输入改干净报错（原 Traceback）。
 - **topmind-x-article `0.1.0`**：X 长文一键发布。`md2x.py` 把 Markdown 转可直接粘贴进
   X Article 编辑器的纯文本（标题→纯文本行、加粗/斜体去标记、链接→`文字（url）`、
   图片→`[图N]`+文末配图清单、表格→"项：值"列表）；`references/publish-checklist.md`

package/README.en.md

@@ -2,224 +2,202 @@
 
 **[中文](./README.md)** | English
 
-> Language note: **Chinese is the default** (`README.md`). This file is the full English parallel.
+> Chinese is the default (`README.md`); this file is the English parallel.
 
 [![Release](https://img.shields.io/github/v/release/topmindspace/topmind-writing-skills?style=flat-square&color=blue)](https://github.com/topmindspace/topmind-writing-skills/releases)
 [![npm](https://img.shields.io/npm/v/@topmindspace/topmind-writing-skills?style=flat-square)](https://www.npmjs.com/package/@topmindspace/topmind-writing-skills)
 [![CI](https://img.shields.io/github/actions/workflow/status/topmindspace/topmind-writing-skills/ci.yml?style=flat-square&label=CI)](https://github.com/topmindspace/topmind-writing-skills/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](LICENSE)
 
-**TopMindSpace writing-skills collection** — WeChat articles, X long-form posts, short-form briefs, viral short posts, revision and quality checks, cover art, long-image rendering: seven skills, one repo.
+**TopMindSpace writing skills**: WeChat articles, X long-form, short briefs, viral short posts, formatting, revision, covers and long images — eight skills, one repo. Principles first: decide what you want to say and which form reads best, then worry about wording. Scripts hint; people decide.
 
 <p align="center">
   <img src="docs/assets/writing-cover.png" alt="topmind-writing-skills · writing skills collection" width="960" />
 </p>
 
-> The formal business presentation skill now lives on its own: [`topmind-presentation`](https://github.com/topmindspace/topmind-presentation) (repo `topmind-presentation`; the repo is the skill — clone and copy the root into your skills directory).
-
-### topmind-wechat-post · WeChat article authoring
-
-Full lifecycle for WeChat articles: single-source article folder (`<title>/<title>.md`), review & rewrite, three quality gates (run by topmind-revise by default: facts / logic / de-AI-flavor), WeChat inline typography on request (images must be embedded, output goes to `out/`), publish checklist and status sync. Hand-written heading numbers are kept as written; legacy `公众号稿.md` packages stay readable. Python stdlib only — zero dependencies.
-
 ```bash
-npx @topmindspace/topmind-writing-skills install topmind-wechat-post
+npx @topmindspace/topmind-writing-skills list
+npx @topmindspace/topmind-writing-skills install topmind-briefs
 ```
 
-### topmind-x-article · One-click X long-form publishing
+## Skills
 
-Delivers one `<title>.md` by default (after topmind-revise); when you want to post on X, derives into `out/` on request: one-click-copy HTML (rich text; reads the source's `![]()` lines and embeds images in order, "来源：" lines become captions) / plain-text fallback (`md2x.py`: images → `[图N]`, tables → "item: value" lists, lists → "·" / "1）" with emoji optional, because plain-text X does not render Markdown lists) + cover art + publish checklist. Publishing is done by hand-pasting; fetch the text back for verification after posting.
+> Terms: **short post (短文)** = a plain-text X post, up to about 1000 Chinese characters (no 280-character limit); **long-form (长文)** = an X Article or a WeChat article; **duanzi (段子)** = a one-sentence-per-line short-post style.
 
-```bash
-npx @topmindspace/topmind-writing-skills install topmind-x-article
-```
+| Skill | Version | What it does |
+|---|---|---|
+| [`topmind-wechat-post`](./topmind-wechat-post/) | **0.3.18** | WeChat long-form: single-source article folder, three quality gates (revise by default), inline typography on request (images embedded), publish checklist and status sync |
+| [`topmind-x-article`](./topmind-x-article/) | **0.4.24** | X long-form: single-source Markdown (revise by default) → on-request one-click-copy HTML / plain-text fallback + cover + checklist |
+| [`topmind-briefs`](./topmind-briefs/) | **0.2.26** | Short briefs (X + WeChat): one topic, stop when done; sources → original images → content → layout; one copy-ready plain-text X block, links and images sent separately |
+| [`topmind-viral-posts`](./topmind-viral-posts/) | **0.3.18** | X viral short posts: 18 templates + hook × body × closer combinations; duanzi layout with no emoji |
+| [`topmind-format`](./topmind-format/) | **0.1.11** | X plain-text formatter: to duanzi / to short post; layout only, words unchanged, with a fidelity check |
+| [`topmind-revise`](./topmind-revise/) | **0.1.3** | Revision and quality check: ⓪ structure → facts → logic → de-AI → fidelity audit; four modes; every change maps to a rule code |
+| [`topmind-cover`](./topmind-cover/) | **0.4.15** | Cover art (X 1500×600 / WeChat 900×383): 22 styles, seven-layer scene recipe, whole-image generation + title proofing |
+| [`topmind-poster`](./topmind-poster/) | **0.1.8** | HTML+CSS → high-res long image / poster / infographic: headless Chrome 2× + auto-trim; one image per section |
 
-### topmind-briefs · Short-form briefs
+Installer [`@topmindspace/topmind-writing-skills`](https://www.npmjs.com/package/@topmindspace/topmind-writing-skills) is **0.8.47** (whole-repo, same-tag releases).
 
-Short-form briefs for WeChat + X: one topic, one chart (data rankings / paper explainers / product alerts / mechanism explainers). A brief is not long-form: **no HTML by default**. Workflow: verify first-hand sources → find the original post and images → write (no AI tone, a real hook) → lay out (sensible paragraphs and lists). The X version is one copy-ready plain-text block (emoji optional, 0–2 hashtags); **links (with source and publish time), 1–2 original images and generated images are sent separately**; the WeChat version is ~300–800 Chinese characters of Markdown. Draft only — never auto-post.
+## Writing philosophy: principles first
 
-```bash
-npx @topmindspace/topmind-writing-skills install topmind-briefs
+Social posts exist to get information and a point of view across: clear, simple, easy to read; use images, tables and lists instead of long paragraphs wherever the content allows. All writing skills share one layered rule set (single source `shared/references/`, copied into each skill so standalone installs work):
+
+| Layer | Files | Covers |
+|---|---|---|
+| 0 · Principles | `social-writing-principles.md` | 8 principles: know what to say, conclusion first, every sentence adds something, form follows content, everyday words, originals and data over paraphrase, the reader's side, honest and measured |
+| 1 · Information design | `information-design.md` | Skeleton first, content → form table (list / table / image / paragraph), length and density, spotting padding, what the I1–I8 hints mean |
+| 2 · Voice | `core-voice.md` | Ten wording principles; V01–V33 are worked examples for titles, openings, numbers, quotes, replies, jokes |
+| 3 · Review | `topmind-revise` + `de-ai-rules.md` | ⓪ structure → facts → logic → cut → de-AI → layout → fidelity audit; the de-AI rules are for reviewing finished drafts, not for drafting |
+
+Practices shared by every skill:
+
+- **Principles are written as why + how to judge + example**: examples show the thinking, not a word list. Only real hard constraints (platform limits, facts, compliance) stay strict, labeled 「硬约束」 (hard constraint).
+- **Persona: an ordinary person who is still learning** — not an expert, not a lecturer; a little self-mockery is fine; say so when unsure.
+- **Originals first** (`image-sourcing.md`): find official / original-post / third-party images before writing and log sources in `素材来源.md`; self-made charts are a fallback, labeled 自制 with the data source.
+- **Scripts hint**: E errors must be zero; each W warning needs a decision; H hints and I1–I8 information-design hints are advisory and never part of `--strict`.
+- **Revise only what is wrong**: keep rewrite boundaries (wording only, never facts or certainty); reordering sections needs `depth=structure`.
+
+### The long-form article folder
+
+One article, one folder, one source file; `article_scaffold.py` (or wechat-post's `new-article.py`) creates it:
+
+```text
+<title>/
+├─ <title>.md     the only source (readable in Obsidian; HTML comments with writing notes never reach derived output)
+├─ 骨架.md        skeleton: main message, reader, per-section points / form / chart plan / length
+├─ 素材来源.md    source for every image and number
+├─ images/  cover/
+├─ raw/           originals, screenshots, notes (not published)
+├─ out/           derived output: X HTML, plain text, WeChat HTML (rebuild any time)
+└─ 参考/          same-topic drafts and assets from other environments (reference only, never the source)
 ```
 
-### topmind-viral-posts · X viral short posts
+Multi-environment work (optional): the source frontmatter carries `updated_at` (ISO 8601 with time zone), `updated_env` and `updated_by`; `updated_at` decides which copy is newer. When both sides changed and the order is unclear, nothing is overwritten — the older copy goes into `参考/`. See `workspace.md`. Legacy `公众号稿.md` packages stay readable.
 
-18 post types plus hook × body × closer combinations, summarised from common high-engagement writing patterns in the Chinese X community (all examples are original): **duanzi layout** (one sentence per line, a blank line between lines), conversational tone, an engagement hook; original images first; asks before generating one via `topmind-cover`. Hashtags (1–3) are part of the post body; classification tags (type / purpose / platform / tone) are listed separately. Duanzi posts use no emoji at all — no persona motif, no reaction emoji, no bullet symbols; bullets are plain lines separated by blank lines. Each post body is one copy-ready plain-text block; links, original images and generated images are sent separately.
+## Which skill, and how they combine
 
-```bash
-npx @topmindspace/topmind-writing-skills install topmind-viral-posts
-```
+| Task | Skill | Typical combination |
+|---|---|---|
+| A data-driven brief (numbers, rankings, launches) | `topmind-briefs` | → `topmind-format` for layout; no original image → ask, then `topmind-cover` 16:9 |
+| Engagement jokes, follower posts | `topmind-viral-posts` | → `topmind-format` to re-lay duanzi |
+| Existing text, layout only | `topmind-format` | words unchanged; rewriting → `topmind-revise` |
+| Edit, tighten, de-AI, quality check | `topmind-revise` | standalone, or called by the long-form skills |
+| Thousands-of-words X article | `topmind-x-article` | + `topmind-revise` + `topmind-cover` (5:2) |
+| WeChat long-form & layout | `topmind-wechat-post` | + `topmind-revise` + `topmind-cover`; 300–800-character pieces → briefs |
+| Long images, posters, infographics | `topmind-poster` | copy written first by briefs / wechat-post |
 
-### topmind-format · X plain-text formatter
+## Skill highlights
 
-Paste existing text: **to duanzi** → one sentence per line with blank lines between, all emoji and bullet symbols removed; **to short post** → paragraphing, lists as 「·」/「1）」 or emoji; title emoji and persona motif optional. Layout only — words never change; `format_text.py` enforces fidelity and pulls links, source lines and image notes out of the body to be sent separately.
+### topmind-wechat-post · WeChat long-form
 
-```bash
-npx @topmindspace/topmind-writing-skills install topmind-format
-```
+- Single-source article folder; review and rewrite through `topmind-revise` by default; typography output goes to `out/` with base64-embedded images.
+- Hand-written heading numbers are kept as written; Python stdlib only.
 
-### topmind-revise · Revision and quality check
+### topmind-x-article · X long-form
 
-Makes a draft shorter, more accurate and closer to the author's voice, and proves the facts survived. Four modes: audit (report only), revise (back up, then write back), embed (called by the WeChat / X long-form skills; returns only the final draft) and quick (titles, short posts, one-liners, replies). Pipeline: facts → logic → cut redundancy → de-AI → voice check → layout → fidelity check → over-edit check; `revise_check.py` diffs numbers, quotes, proper nouns and hedging words, and reports the share of clean paragraphs that were rewritten anyway.
+- Delivers only `<title>.md` by default; for X, derives one-click-copy HTML (images embedded in `![]()` order, 「来源：」 lines as captions) or a plain-text fallback (`md2x.py`: images → `[图N]`, tables → "item: value", lists → 「·」 / 「1）」).
+- Publishing is a manual paste; fetch the post back afterwards to verify.
 
-```bash
-npx @topmindspace/topmind-writing-skills install topmind-revise
-```
+### topmind-briefs · Short briefs
 
-### Shared X plain-text rules (all skills that output X text)
+- No HTML by default: verify first-hand sources → find the original post and images → write → lay out.
+- The X version is one copy-ready plain-text block (emoji optional, 0–2 hashtags); links (with source and publish time) and images are sent separately; the WeChat version is about 300–800 characters. Draft only.
 
-Single source in `shared/references/`, distributed to each skill's `references/` via the manifest:
+### topmind-viral-posts · X viral short posts
 
-| Doc | Covers |
-|---|---|
-| `x-delivery-contract.md` (must read) | Short-post workflow: sources → original post/images → content → layout; emoji optional for short posts (bullets default to 「·」, 「1）」 for longer lists, emoji only for short lists, 【headings】 for longer posts), none at all in duanzi; never `- ` / `1. `; the X short-post / duanzi body is one copy-ready plain-text block (hashtags last); **links (including sources), original images and generated images are sent separately**; X long-form and WeChat articles may keep in-text links |
-| `x-post-format.md` | No Markdown, bullet sets, spacing, sources, skeletons, images, WeChat → X |
-| `emoji-system.md` | The TopMind emoji system (short posts only, optional): 0–2 persona motifs (🐔 🐱 🌱) at start/end; 0–1 keyword-matched title emoji; one bullet set per post |
-| `x-layout-patterns.md` | Layout patterns in our own words |
+- 18 templates (advice, self-mockery, hot news, little-known facts, contrast, self-Q&A, …) + hook × body × closer combinations; all examples are original.
+- Duanzi layout: one sentence per line, blank lines between, no emoji; 1–3 hashtags on the last line, classification tags listed separately.
 
-Checks: `lint_x_post.py` reports three levels. **E errors** (E1–E9 Markdown leftovers; E10–E12 URLs / source lines / image notes in the body) must be zero. **W warnings** (W9 AI-sounding phrases, W10 first line too long, W12 notes / internal tags, W14 paragraph too long, W15 / W16 Chinese / English structural patterns, W17 punctuation tics, W18 self-made image without data source, W19 「name 说：」, W20 transition sentences, W21 retelling an image; W13 any emoji in a duanzi post with `--duanzi`) each need a decision. **H hints** (context words, news-style precision, parallel closing lines, emoji density, etc.) are advisory and never fail `--strict`. Pick the genre with `--genre long|short|duanzi|reply|title`; hide hints with `--no-hints`. The de-AI part shares one rule set with `de_ai_lint.py` (`de-ai-rules.md`).
+### topmind-format · X plain-text formatter
 
-### topmind-cover · Cover art generation
+- **To duanzi**: one sentence per line with blank lines, emoji and bullets removed; **to short post**: paragraphing, lists as 「·」 / 「1）」 or emoji.
+- `format_text.py` changes layout only and checks fidelity; links, source lines and image notes are pulled out to be sent separately.
 
-Shared cover art for X long-form and WeChat: striking, eye-catching, theme-focused. **Theme → seven-layer scene recipe → 2–3 style-combo options → layered prompt → seven-item score** (default: whole-image generation from 16 prompt patterns + character proofing and local fixes; fallback: scene + `title-engine.py` overlay), then one-click crop to both platform sizes with `crop-cover.py` (X 1500×600, WeChat 900×383). 22-style index and recipes: [`references/cover-styles.md`](./topmind-cover/references/cover-styles.md).
+### topmind-revise · Revision and quality check
 
-```bash
-npx @topmindspace/topmind-writing-skills install topmind-cover
-```
+- Four modes: audit (report only), revise (back up, then write back), embed (called by long-form skills; returns only the final draft), quick (titles, short posts, one-liners, replies).
+- `revise_check.py` diffs numbers, quotes, proper nouns and hedging words, and reports the share of clean paragraphs that were rewritten anyway.
+
+### topmind-cover · Cover art
+
+- Theme → seven-layer scene recipe → 2–3 style combos → layered prompt → seven-item score; whole-image generation with character proofing by default, `title-engine.py` overlay as a fallback.
+- `crop-cover.py` crops both platform sizes; style index in [`cover-styles.md`](./topmind-cover/references/cover-styles.md).
 
 <p align="center">
   <img src="https://github.com/topmindspace/topmind-writing-skills/raw/main/topmind-cover/assets/examples/overview.png" alt="topmind-cover · 22 cover-style overview" width="960" />
 </p>
 
-> Let ideas fly — make good thinking visible.
-
 ### topmind-poster · HTML → high-res long image
 
-The **rendering step** for rankings, infographics, monthly-report long images and posters: HTML+CSS layout → headless Chrome 2× screenshot → auto-trimmed bottom whitespace. Includes the "one image per section" workflow (generator + renderer) that splits a long article into N individually shareable images. `render_poster.py` runs all three steps in one command; layout recipes (canvas / type scale / light & dark palettes / grid / progress bars) are in [`references/layout-recipes.md`](./topmind-poster/references/layout-recipes.md).
+- HTML+CSS layout → headless Chrome 2× screenshot → auto-trim, all in `render_poster.py`; layout recipes in [`layout-recipes.md`](./topmind-poster/references/layout-recipes.md).
+- Why not an image model: rankings carry text and numbers that must be exact, and generation mangles them. Covers have no dense text and go through `topmind-cover`.
 
-```bash
-npx @topmindspace/topmind-writing-skills install topmind-poster
-```
+> The business presentation skill lives in its own repo: [`topmind-presentation`](https://github.com/topmindspace/topmind-presentation).
 
-> Why not an image generation model: rankings carry dense text and numbers that must be character-exact, and generation mangles glyphs and invents figures. Covers are the exception (no dense text) and go through `topmind-cover`.
+## Shared X plain-text rules
 
-> **Rename note**: this repo was renamed from `tms-skills` to `topmind-writing-skills`;
-> the npm package is `@topmindspace/topmind-writing-skills` and the old package is no longer updated.
-> Also do not install the old package's `^2` (2.0.0–2.1.1 deprecated).
+Used by every skill that outputs X text (`shared/references/`):
 
+| Doc | Covers |
+|---|---|
+| `x-delivery-contract.md` | Short-post workflow (sources → original post/images → content → layout); one copy-ready plain-text body, hashtags last; links and images sent separately |
+| `x-post-format.md` | No Markdown, bullet sets, spacing, sources, images, WeChat → X |
+| `emoji-system.md` | Emoji system (short posts only, optional): 0–2 persona motifs, 0–1 title emoji, one bullet set per post |
+| `x-layout-patterns.md` | Layout patterns: conclusion on the first line, list lead-ins, 【headings】 |
 
-## Shared writing workflow (since 0.8.44: three layers)
-
-The writing skills share one rule set (`shared/references/`, copied into each skill so standalone installs work):
+Three output levels of `lint_x_post.py` / `de_ai_lint.py`:
 
-| Layer | Files | Covers |
+| Level | Meaning | Required |
 |---|---|---|
-| Voice | `core-voice.md` | Scenario rules (V01–V33): titles, openings, endings, numbers, quotes, source lines, lists, emoji, replies, joke recipe |
-| De-AI | `de-ai-rules.md` + `de_ai_lint.py` | Rewrite boundaries plus structural patterns (Z / E / P codes); the linter reports W (each needs a decision) and H (advisory) |
-| Execution | `topmind-revise` | Runs `revision-workflow.md` end to end, with a fidelity check, an over-edit check and a revision report |
+| E error | Markdown leftovers (E1–E9); URLs / source lines / image notes in the body (E10–E12) | must be zero |
+| W warning | AI-sounding phrases, long first line, long paragraphs, structural patterns, punctuation tics, unlabeled self-made images, … | each needs a decision: fix, or note why it stays |
+| H hint / I1–I8 | context words, parallel closers, emoji density; information design (long runs of prose, list / table candidates, opening that doesn't deliver, …) | advisory, never in `--strict` |
 
-Also:
-
-- **Originals first** (`image-sourcing.md`): find official / original-post / third-party images before writing and log sources in the private `素材来源.md` inside the article folder; self-made charts are a fallback and must be labeled 自制 with the data source.
-- **De-AI pass is mandatory**: rewrite boundaries first (change wording, never facts or certainty); W warnings need a decision rather than a zero count; the regression set `scripts/test_lint_rules.py` keeps normal writing from being flagged. topmind-format reports hits without rewriting.
-- **Fixed revision order** (`revision-workflow.md`): facts → logic → cut redundancy → de-AI → voice check → layout → fidelity check → over-edit check; back up first and report before/after word counts (`count_words.py`). `topmind-revise` runs it when installed.
+Pick the genre with `--genre long|short|duanzi|reply|title`; hide hints with `--no-hints`.
 
 ## Original examples
 
-Every skill ships sample outputs written by us (fictional or neutral topics; no third-party text or images):
-
-| Skill | Examples |
-|---|---|
-| topmind-viral-posts (one-liners) | [`topmind-viral-posts/examples/`](./topmind-viral-posts/examples/) |
-| topmind-briefs (short posts) | [`topmind-briefs/examples/`](./topmind-briefs/examples/) |
-| topmind-format (formatting) | [`topmind-format/examples/`](./topmind-format/examples/) |
-| topmind-revise (revision) | [`topmind-revise/examples/`](./topmind-revise/examples/) |
-| topmind-x-article (X long-form) | [`topmind-x-article/examples/`](./topmind-x-article/examples/) |
-| topmind-wechat-post (WeChat) | [`topmind-wechat-post/examples/`](./topmind-wechat-post/examples/) |
-| topmind-poster (posters) | [`topmind-poster/examples/`](./topmind-poster/examples/) |
-| topmind-cover (covers) | [`topmind-cover/assets/examples/`](./topmind-cover/assets/examples/) |
-
-## Skills
-
-> Terms: **short post (短文)** = a plain-text X post, anything up to about 1000 Chinese characters (no 280-character limit); **long-form (长文)** = an X Article; **duanzi (段子)** = a one-sentence-per-line short-post style.
-
-
-| Skill | Version | What it does |
-|-------|---------|--------------|
-| [`topmind-wechat-post`](./topmind-wechat-post/) | **0.3.16** | WeChat article lifecycle: single-source article folder, review, 3 quality gates (revise by default), inline typography on request & publish checklist |
-| [`topmind-x-article`](./topmind-x-article/) | **0.4.22** | X long-form: single-source Markdown (revise by default) → on-request one-click-copy HTML (images/prompt copy, click-to-zoom images) / plain-text fallback + cover + checklist |
-| [`topmind-cover`](./topmind-cover/) | **0.4.13** | Cover art for X / WeChat (X master 1500×600 / 5:2): striking, theme-focused; 22-style cover style library + 16:9 X short-post cover scene + 24 title treatments + 7-layer scene recipe + 55 example images (22 styles × 2 sizes + 11 variant samples) + 1 style overview |
-| [`topmind-briefs`](./topmind-briefs/) | **0.2.24** | Short-form briefs (WeChat + X): one topic, one chart; data rankings / paper explainers / product alerts / mechanism explainers; sources → images → content → layout; one copy-ready plain-text X block (no HTML by default, emoji optional, no AI tone), links / images sent separately; asks before generating any image |
-| [`topmind-viral-posts`](./topmind-viral-posts/) | **0.3.16** | X viral short posts: 18 template types + combinations, duanzi layout (blank lines, no emoji, plain bullet lines), one copy-ready plain-text block per post with hashtags last, links / images sent separately, classification tags listed separately; asks before generating an image |
-| [`topmind-format`](./topmind-format/) | **0.1.9** | X plain-text formatter: to duanzi (blank lines, no emoji) / to short post (paragraphing + sensible lists, emoji optional); layout only, words unchanged, with a fidelity check; one copy-ready plain-text body, links / images sent separately |
-| [`topmind-revise`](./topmind-revise/) | **0.1.1** | Revision and quality check: edit, tighten, de-AI, three quality gates and fidelity audit; four modes (audit / revise / embed / quick); every change maps to a rule code, with an over-edit guard; the long-form skills use it by default |
-| [`topmind-poster`](./topmind-poster/) | **0.1.6** | HTML+CSS → high-res long image / poster / infographic PNG: headless Chrome 2× screenshot + auto-trim; "one image per section" batch workflow (generator + renderer) |
-
-Installer [`@topmindspace/topmind-writing-skills`](https://www.npmjs.com/package/@topmindspace/topmind-writing-skills) is **0.8.45** (whole-repo same-tag releases).
-
-### Which skill, and how they combine
-
-| Task | Skill | Typical combination |
-|---|---|---|
-| A data-driven brief (numbers, rankings, launches) | `topmind-briefs` | → `topmind-format` for layout; no original image → `topmind-cover` 16:9 |
-| Engagement jokes, follower posts | `topmind-viral-posts` | → `topmind-format` to re-lay duanzi; pair with a briefs version for the same event |
-| Existing text, layout only | `topmind-format` | words unchanged; rewriting → `topmind-revise` |
-| Edit, tighten, de-AI, quality check | `topmind-revise` | standalone, or called by x-article / wechat-post after drafting |
-| Thousands-of-words X article | `topmind-x-article` | + `topmind-revise` + `topmind-cover` (5:2); shorter than a post → briefs |
-| WeChat long-form & layout | `topmind-wechat-post` | + `topmind-revise` + `topmind-cover`; 300–800-char briefs → briefs |
-| Long images, posters, infographics | `topmind-poster` | copy written first by briefs / wechat-post |
-
-> SKILL.md frontmatter uses only Agent Skills spec keys at the top level (`name` / `description` / `license` / `metadata`); version, `action_category`, `triggers` and other custom keys live under `metadata` as strings, so `skills-ref validate` passes. Shared scripts and references (`core-voice.md`, `de-ai-rules.md`, `writing-principles.md` and more) have a single source in `shared/`; skill folders keep byte-identical copies (CI checks with `node scripts/sync_shared.js --check`). The npm package ships only `overview.png` from the cover examples; the per-style samples stay on GitHub / in the Release zip.
+All examples are written by us (fictional or neutral topics; no third-party text or images): [viral-posts](./topmind-viral-posts/examples/) · [briefs](./topmind-briefs/examples/) · [format](./topmind-format/examples/) · [revise](./topmind-revise/examples/) · [x-article](./topmind-x-article/examples/) · [wechat-post](./topmind-wechat-post/examples/) · [poster](./topmind-poster/examples/) · [cover](./topmind-cover/assets/examples/).
 
 ## Install
 
-**npm = pinned snapshot**; **GitHub = track repo HEAD**.
+**npm = pinned snapshot; GitHub = repo HEAD.**
 
 ```bash
-npx @topmindspace/topmind-writing-skills list
-npx @topmindspace/topmind-writing-skills install topmind-briefs
 npx @topmindspace/topmind-writing-skills install topmind-briefs --to ./.claude/skills
-npx @topmindspace/topmind-writing-skills@latest install topmind-briefs   # upgrade: older install is overwritten, no --force needed
+npx @topmindspace/topmind-writing-skills@latest install topmind-briefs   # upgrade: an older install is overwritten
 npx @topmindspace/topmind-writing-skills install topmind-briefs --force   # reinstall same version / downgrade
-npx @topmindspace/topmind-writing-skills@0.8.4 install topmind-briefs   # pin (needs --force if a newer version is installed)
+npx @topmindspace/topmind-writing-skills@0.8.4 install topmind-briefs     # pin a version
 npx @topmindspace/topmind-writing-skills uninstall topmind-briefs --to ./.claude/skills
+npx github:topmindspace/topmind-writing-skills install topmind-briefs     # track HEAD
 ```
 
-```bash
-# track HEAD
-npx github:topmindspace/topmind-writing-skills install topmind-briefs
-```
-
-Default probe order: `./.agents` → `./.claude` → `./.cursor` → `./.codex` → `./.mimocode`, then user-level `~/.claude`, etc. Or pass `--to`. When `--to` is omitted, the install summary explicitly prints the auto-detected target directory. Do not `npm install topmind-briefs` (skill id is not a standalone package).
-
-`install` details: upgrades by default: if the installed version is older (or unreadable), it is overwritten in place (no backup) and `Upgraded <skill> <old> -> <new>` is printed; the same version prints `Already up to date` (`--force` reinstalls); an installed version newer than the package is refused unless `--force`. On success, a three-line summary is printed: where it was installed / installed skill version and installer version / next steps.
+- Default probe order: `./.agents` → `./.claude` → `./.cursor` → `./.codex` → `./.mimocode`, then user-level `~/.claude`, etc.; the install summary prints the actual target.
+- An older install is overwritten (`Upgraded <skill> <old> -> <new>`); the same version prints `Already up to date`; a newer installed version is never downgraded without `--force`.
+- Do not `npm install topmind-briefs`: skill ids are not standalone packages. The old `tms-skills` package is no longer updated, and its `^2` (2.0.0–2.1.1) is deprecated.
 
 ## Repo layout
 
-```
+```text
 topmind-writing-skills/
-├─ topmind-briefs/                    # skill (SKILL.md + assets + references + scripts)
-├─ topmind-viral-posts/               # skill (X viral short posts, duanzi layout)
-├─ topmind-format/                    # skill (X plain-text formatter: duanzi / short post)
-├─ topmind-revise/                    # skill (revision and quality check)
-├─ topmind-poster/                    # skill (HTML → high-res long image / section images)
-├─ topmind-cover/                     # skill
-├─ topmind-wechat-post/               # skill
-├─ topmind-x-article/                 # skill
-├─ bin/topmind-writing-skills.js      # CLI: list / install / uninstall
-├─ shared/                            # single source for shared scripts + writing principles (manifest.json lists targets)
-├─ evals/                             # routing eval cases (not shipped to npm)
-├─ docs/                              # publishing guide · CI notes
-├─ scripts/                           # repo gates / privacy scan
-├─ package.json                       # @topmindspace/topmind-writing-skills
-└─ LICENSE · CHANGELOG.md · README.md · README.en.md
+├─ topmind-*/                    # eight skills (SKILL.md + references + scripts + examples)
+├─ shared/                       # single source for shared scripts and writing rules (manifest.json lists targets)
+├─ bin/topmind-writing-skills.js # CLI: list / install / uninstall
+├─ evals/                        # routing eval cases (not shipped to npm)
+├─ docs/                         # publishing guide · CI notes
+├─ scripts/                      # repo gates, sync, privacy scan
+└─ package.json · CHANGELOG.md · LICENSE
 ```
 
+- Edit shared files only in `shared/`, then run `npm run sync:shared`; CI checks that every skill copy is byte-identical.
+- SKILL.md frontmatter keeps only Agent Skills spec keys at the top level (`name` / `description` / `license` / `metadata`), so `skills-ref validate` passes.
+- The npm package ships only `overview.png` from the cover examples; per-style samples are on GitHub and in the Release zip.
+
 ## Release & CI
 
 | Action | GitHub | npm |
-|--------|:------:|:---:|
-| push main | live | **unchanged** |
-| tag `vX.Y.Z` | Release + zip | **auto publish** |
+|---|:---:|:---:|
+| push main | live | unchanged |
+| tag `vX.Y.Z` | Release + zip | auto publish |
 
 ```bash
 npm run check && npm run audit && npm run privacy