@topmindspace/topmind-writing-skills 0.8.46 → 0.8.47

package/CHANGELOG.md

@@ -1,3 +1,29 @@
+## [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 味改成成稿后的审稿步骤，脚本只提示、人来判断。
@@ -1257,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,228 +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):
 
-### topmind-viral-posts · X viral short posts
+| 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 |
 
-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.
+Practices shared by every skill:
 
-```bash
-npx @topmindspace/topmind-writing-skills install topmind-viral-posts
-```
+- **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`.
 
-### topmind-format · X plain-text formatter
+### The long-form article folder
 
-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.
+One article, one folder, one source file; `article_scaffold.py` (or wechat-post's `new-article.py`) creates it:
 
-```bash
-npx @topmindspace/topmind-writing-skills install topmind-format
+```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-revise · Revision and quality check
+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.
 
-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: ⓪ structure review → 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.
+## Which skill, and how they combine
 
-```bash
-npx @topmindspace/topmind-writing-skills install topmind-revise
-```
-
-### Shared X plain-text rules (all skills that output X text)
+| 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 |
 
-Single source in `shared/references/`, distributed to each skill's `references/` via the manifest:
+## Skill highlights
 
-| 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 |
+### topmind-wechat-post · WeChat long-form
 
-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`).
+- 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-cover · Cover art generation
+### topmind-x-article · X long-form
 
-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).
+- 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-cover
-```
+### topmind-briefs · Short briefs
 
-<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>
+- 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.
 
-> Let ideas fly — make good thinking visible.
+### topmind-viral-posts · X viral short posts
 
-### topmind-poster · HTML → high-res long image
+- 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.
 
-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).
+### topmind-format · X plain-text formatter
 
-```bash
-npx @topmindspace/topmind-writing-skills install topmind-poster
-```
+- **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.
 
-> 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`.
+### topmind-revise · Revision and quality check
 
-> **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).
+- 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
 
-## Writing philosophy: principles first
+- 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).
 
-Social posts exist to get information and a point of view across: clear, simple, easy to read, with charts and lists instead of long paragraphs wherever the content allows. So these skills start with how to think, and only then with what to avoid. The writing skills share one layered rule set (`shared/references/`, copied into each skill so standalone installs work):
+<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>
 
-| Layer | Files | Covers |
-|---|---|---|
-| 0 · Principles | `social-writing-principles.md` | 8 principles: know what you want to say, lead with the conclusion, every sentence adds something new, form follows content, plain everyday words, originals and data over paraphrase, stand on the reader's side, honest and measured |
-| 1 · Information design | `information-design.md` | Skeleton before prose, a content → form decision table (list / table / image / paragraph), length and density reference lines, ways to spot padding |
-| 2 · Voice | `core-voice.md` | Ten wording principles; V01–V33 are worked examples for titles, openings, numbers, quotes, replies, jokes |
-| Review · De-AI | `de-ai-rules.md` + `de_ai_lint.py` | Pattern table (Z / E / P) grouped by root cause; used for self-review and revision only, not while drafting |
-| Execution | `topmind-revise` | ⓪ structure review → facts → logic → cut redundancy → de-AI → layout → fidelity check → over-edit check, with a revision report |
+### topmind-poster · HTML → high-res long image
 
-Also:
+- 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`.
 
-- **Principles are written as why + how to judge + example**: examples show the thinking, not a word list; concrete revision cases stay examples, never hard gates.
-- **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.
-- **Long-form starts with a skeleton**: `article_scaffold.py` creates `骨架.md` in the article folder (main message, reader, per-section points / form / chart plan / length), so the form is decided before drafting.
-- **Scripts hint, people decide**: each W warning needs a decision (not a zero count); H hints and I1–I8 information-design hints are advisory and never part of `--strict`; the regression sets `scripts/test_lint_rules.py` and `scripts/test_info_design.py` keep normal writing from being flagged.
-- **Revise only what is wrong**: rewrite boundaries first (change wording, never facts or certainty); by default only low-risk structural edits (parallel paragraphs → list, comparisons → table, remove repeats); reordering sections needs `depth=structure`.
+> The business presentation skill lives in its own repo: [`topmind-presentation`](https://github.com/topmindspace/topmind-presentation).
 
-## Original examples
+## Shared X plain-text rules
 
-Every skill ships sample outputs written by us (fictional or neutral topics; no third-party text or images):
+Used by every skill that outputs X text (`shared/references/`):
 
-| Skill | Examples |
+| Doc | Covers |
 |---|---|
-| 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.
+| `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】 |
 
+Three output levels of `lint_x_post.py` / `de_ai_lint.py`:
 
-| 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.46** (whole-repo same-tag releases).
+| Level | Meaning | Required |
+|---|---|---|
+| 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` |
 
-### Which skill, and how they combine
+Pick the genre with `--genre long|short|duanzi|reply|title`; hide hints with `--no-hints`.
 
-| 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 |
+## Original examples
 
-> 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 (`social-writing-principles.md`, `information-design.md`, `core-voice.md`, `de-ai-rules.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