Quote Wallpaper / 名言壁纸

中文 — 生成暗色、多层排版的语录卡片。为 CJK 与拉丁混排而设计：排版引擎不拆开拉丁词、
不把句末标点留在行首、单行放不下时自动缩字号，作者手写的断行不会被重新拆解。每次渲染都跑
WCAG 对比度与字形缺失两道审计，不达标即失败退出，而不是产出一张坏卡。

English — Generate dark, typographically layered quote cards. Built for CJK +
latin mixed layouts: the text engine wraps without breaking latin words, never
leaves closing punctuation at the start of a line, shrinks the font when a single
token cannot fit, and treats author-written line breaks as atomic. Every render is
audited for WCAG contrast and missing glyphs, and fails loudly rather than
shipping a broken card.

何时使用 / When to use

中文 — 只要用户想把文字变成「纯文字类图片」就用它，不必说出「壁纸」这个词：

English — Use it whenever the user wants text turned into a type-only image —
they need not say the word "wallpaper":

中文 — 请求模糊时按这张表走：

English — When the request is vague, work from this:

中文 — 批量规模会改变工作方式（代码不用改）：

English — Batch size changes how you work, though not the code:

中文 — 容量上限（实测，不是估计）：

English — Capacity, measured rather than estimated:

中文 — 主题按情绪挑，不要随机；完整表在 references/style-guide.md：

English — Pick a theme by tone, never at random; full table in references/style-guide.md:

中文 — 只有这两件事值得问（改起来麻烦）：

• 配色方向 — 仅当用户完全没给暗示时问。情绪通常已经通过色调表定下来了；拿六个色板去问是浪费他的时间。
• 画布尺寸 — 用户提到屏幕就用 --auto-size。为 4K 屏渲染 1080p，是那种直到看起来发虚才有人发现的问题。

English — Ask only about these (hard to undo):

• Palette direction — only when the user gave no hint at all. Mood usually settles
  it via the tone table; quizzing them over six swatches wastes their time.
• Canvas size — if they name a screen, use --auto-size. Rendering 1080p for a
  4K display is the one mistake nobody notices until it looks soft.

中文 — 从不问字体、色块布局、要不要跑审计。那是这个技能的职责。

English — Never ask about fonts, blob layout, or whether to run the audits.
Those are this skill's job.

选材 / Content selection

中文 — 挑引文时按这一条判断：看它是否已经世俗化为通用俗语，不看它出自哪里。

English — Judge a quote by whether it has become common usage, not by where it
came from.

中文 — 拿不准就用保守判断：判为宗教内容，换掉。 未被世俗化的宗教文本一律避开。
另外三条与内容有关的硬性要求：生成或替换前先跑一次全库查重（check_dups.py）；
同一作者可以重复、同一句话不行；替换正文时把 zh_size / gap_scale 一起重置 ——
这两个参数是照着被删掉的那句话调的，留着就会让两行的短句用上五字句的字号、
让单语卡的呼吸间距在双语卡中间挖出空行。同批里两样都出过。

English — When in doubt, judge conservatively: call it religious and drop it.
Unsanctified devotional text is always out. Three more content rules: run a
whole-library duplicate check before writing or replacing any card
(check_dups.py) — replacing is how duplicates actually got in; a repeated
author is fine while a repeated quote is not; and when you replace a card's
text, reset zh_size / gap_scale with it. Those two were tuned for the quote
you just deleted. Left behind, a size meant for a five-character line renders a
two-line quote at 120px, and a gap meant for a sparse monolingual card punches a
hole through a bilingual one — both happened in the same batch.

最佳实践 / Practices that pay off

中文 — 按"省时间多少"排序；English — ordered by how much time they save:

1. 先检查环境 / Check the environment first. 缺 CJK 字体会让每一张卡看起来都是坏的，
   这是最常见的环境故障。 / A missing CJK font is the most common setup failure, and
   it makes every card look broken.
2. 渲染已经自带校验 / The render checks its own input now. render.py 在渲染前会
   拒绝会让它崩溃或静默出错的输入（坏 JSON、缺 name、空数组、字段类型错），并把
   软性问题（混排、未知字段、字数过多）作为警告打印出来。单独跑 lint_cards.py 仍然
   值得 —— 它给出完整清单，且能在渲染前一次性看完。 / render.py now refuses input that
   would crash it or render something silently wrong (broken JSON, a missing name, an
   empty array, a field of the wrong type), and prints the soft problems as warnings.
   Running lint_cards.py on its own is still worth it: it lists everything in one pass,
   with no rendering.
3. 让编号被算出来，而不是手打 / Let the index be computed, not typed. --auto-index
   读取输出目录里最大的 NN_；手工编号在实践中既产生过重号也产生过缺口。 / --auto-index
   reads the highest NN_ in the output dir. Hand-numbering produced both collisions
   and gaps in practice.
4. 验证一批，而不是一张张看 / Verify the batch, not the card. 任何批量修改之后：
   数卡片数 → 跑 check_dups.py → 再渲染。本项目历史上每一个内容错误都通过了逐张检查，
   都是被聚合校验抓出来的。 / After any bulk edit: count the cards, run check_dups.py,
   then render. Every content mistake in this project's history survived a card-by-card
   read and was caught by an aggregate check instead.
5. 优先按语义断行，而不是缩字号 / Prefer meaning-based breaks over font shrinking.
   单行字号掉到 ~90px 以下时，在逗号或分句处断开可换来 20–30% 的字号。例外：工整的
   7+7 对仗句整体更好看。 / If a single line drops below ~90px, split it at a comma or
   clause boundary — you gain 20–30% size. Exception: tidy 7+7 couplets read better whole.
6. 按情绪配主题，不是按作者 / Match the theme to the mood, not to the author.
   色调表是做出协调整套图最快的路径。 / The tone table is the fastest route to a
   coherent set.
7. 按显示器分辨率出图 / Render at the display's resolution（--auto-size，或显式 --size）。
8. 批量用 JPEG / Use JPEG for batches — 体积降到 1/7，暗色平坦背景上看不出损失。 /
   1/7 the size with no visible loss on flat dark fields.

环境准备（首次使用）/ Setup (first run)

中文 — 动第一张卡之前先检查运行时：

English — Check the runtime before touching a card:

python scripts/check_env.py            # 报告缺什么 / report what's missing
python scripts/check_env.py --install  # 自动安装，走国内镜像 / install via China mirrors

• Python — 中文：WorkBuddy 自带运行时，通常无需安装。优先用内置解释器而不是系统的
  python；Windows 下是 %USERPROFILE%\.workbuddy\binaries\python\envs\default\Scripts\python.exe，
  macOS/Linux 下是 ~/.workbuddy/binaries/python/envs/default/bin/python。只有在没有内置版本时
  才回退到系统解释器。永远不要把解释器路径写死，运行时探测。
  English — WorkBuddy ships its own runtime, so there is usually nothing to install.
  Prefer the bundled interpreter over a system python. Fall back to a system interpreter
  only if there is no bundled one. Never hardcode an interpreter path — discover it at run time.
• Pillow + numpy — 中文：只有这两个依赖。缺任何一个就用国内镜像安装：默认 PyPI 源
  在中国大陆很慢甚至不可达，装两个包可能卡几分钟。check_env.py --install 会自动依次尝试
  清华 → 阿里云 → 腾讯云。
  English — The only two dependencies. If either is missing, install via a China
  mirror: the default PyPI index is slow or unreachable from mainland China.
  check_env.py --install walks tuna → aliyun → tencent automatically.
• 字体 / Fonts — 中文：运行时按平台自动解析，Windows/macOS 上无需安装；某个角色找不到时
  会带说明退出。check_env.py 现在会打印每个角色最终解析到的字体文件，所以"到底用了哪个
  字面"不用再翻代码：

fonts : kai C:/Windows/Fonts/simkai.ttf serif C:/Windows/Fonts/timesi.ttf

找不到时它同时给出三种解法：--fonts kai=/path/font.ttf 直接指定、
--font-dir DIR 指向一个目录、或装系统字体（Debian/Ubuntu 上是 fonts-arphic-ukai）。
不建议在包里塞字体：simkai.ttf 是 Windows 授权字体不能分发，而 Noto CJK 一个就用掉
约 20 MB。

English — Resolved per platform at run time; nothing to install on Windows/macOS.
A missing role exits with an explanatory message. check_env.py now prints the file
each role resolved to, so you no longer have to read the code to find out which face
is rendering. Three fixes when nothing resolves: --fonts role=/path/font.ttf,
--font-dir DIR, or install a system font (fonts-arphic-ukai on Debian/Ubuntu).
Do not bundle fonts: simkai.ttf is a licensed Windows font and cannot be
redistributed, while one Noto CJK face costs ~20 MB.

工作流 / Workflow

1. 收集名言 —— 由源语言决定层数 / Collect the quotes — and let the source
   language decide the layer count. 中文：不要默认套用固定的三语堆叠。
   English: Do not default to a fixed three-language stack.

中文 — gap_scale 不作用于「中文 → 原文」那道缝。 那两行是同一句的两种文字，
中间是接缝不是层级；把它也放大，双语卡就变成上下各一半、中间被挖出一个空行
（2.4 倍时 66px 变成 158px）。现在这道缝固定 66px，分隔线以下照常撑开。
English — gap_scale never touches the quote → original seam. Those two lines are
the same sentence in two scripts; that gap is a seam, not hierarchy. Scaling it splits
a bilingual card into two halves with a blank row punched between them (66px → 158px at
2.4). The seam stays at 66px; everything below it still opens up.

中文：按上表收集中文句、原文与出处行。空槽位会被干净跳过，所以一张卡可以带任意子集。
理由见 references/style-guide.md 的「语言层」章节。
English：Gather the Chinese quote plus, where the table calls for it, the
original-language text and the attribution lines. Empty slots are skipped cleanly,
so a card may carry any subset.

2. 询问设计方向 / Ask for a design direction. 中文：这是真问题不是客套，因为背景
   占设计的一半。给出两个族，而不是平铺 11 个名字：
   English: This is a real question, not a formality, because the backdrop is half
   the design. Offer two families rather than a flat list of eleven names:

• flat（平涂） — 中文：一个宽而柔的单色场，没有独立色块，边缘完全融掉。
  主题：ash gold indigo crimson verdant。
  English: one wide, soft field in a single hue — no colour blocks, no visible
  edge. (These five used to be a black plate with a wash at strength 8-18, which
  measured p50 ≈ 1 and read as a failed render; see the style guide.)
• mesh（网格渐变） — 中文：边缘被融掉的柔和色场，文字会被染上与背景同色系的色调。
  主题：void nocturne ember jade ink dusk。 English: soft colour fields
  whose edges are blended away, with the type tinted to share the backdrop's hue.

中文：同样值得问的：观看距离（屏保还是近看），以及要统一主题还是逐张混搭。
English：Also worth asking: viewing distance (screensaver vs. near-view), and
whether they want one consistent theme or a per-card mix.

3. 按情绪给每张卡配主题 / Assign a theme per card by tone. 中文：不要随机分配 ——
   颜色应当与句子一致。色调表见 references/style-guide.md。一批之内混搭主题是推荐默认值：
   15 张同一个颜色读起来是平的，混搭才有节奏。
   English: Do not assign at random — the colour should agree with the sentence.
   Mixing themes across a batch is the recommended default: rotation through 15
   cards in one colour reads flat, whereas a mix gives the sequence rhythm.

4. 写一份 cards JSON / Write a cards JSON，照 assets/cards.example.json 的形状抄：
   ```json
   { "wallpapers": [
   { "name": "01_叔本华_命运与蠢事",
   "quote_zh": "但人们泛称为命运的事情，却通常都是自己做出的蠢事。",
   "source_text": "Was aber die Leute gemeiniglich das Schicksal nennen ...",
   "attribution": ["Parerga und Paralipomena", "亚瑟·叔本华『附录与补遗』"],
   "theme": "void" },

   { "name": "06_王阳明_破心中贼",
   "quote_zh": "破山中贼易，破心中贼难。",
   "attribution": ["王阳明『传习录』"],
   "theme": "ink", "zh_size": 108, "gap_scale": 2.2 }
   ]}
   `` **中文**：quote_zh/quote_ja/source_text可以接受字符串（自动折行）或列表 （钉死的断行）。attribution的每一项可以是纯字符串 —— 字体自动选（CJK 用 kai，拉丁用 serif 斜体）—— 也可以是对象{"text": ..., "font": "kai", "size": 34}。 **English**:quote_zh/quote_ja/source_textaccept a string (auto-wrapped) or a list (pinned line breaks).attribution` entries may be plain strings — the font is
   chosen automatically — or objects.

5. 渲染 / Render.
   bash python scripts/render.py --cards cards.json --out ./out --auto-size python scripts/render.py --cards cards.json --out ./out --format jpeg # 体积约 1/7 python scripts/render.py --cards cards.json --out ./out --palette gold # 强制单一主题 python scripts/render.py --cards cards.json --out ./out --size 2560x1440 python scripts/render.py --cards cards.json --out ./out --auto-index # 自动编 NN_ 号 python scripts/render.py --cards cards.json --out ./out --resume # 跳过已渲染的 python scripts/render.py --cards cards.json --out ./out --no-lint # 跳过渲染前的软性检查 python scripts/check_dups.py cards.json ./more-cards/ # 查重 + 查缺口 python scripts/render.py --list-palettes # 主题 + 对比度 + 背景自检
   中文：不给 --cards 时渲染内置的 assets/cards.example.json。
   English: With no --cards it renders assets/cards.example.json.

中文 — --cards 只接受文件路径：一个 .json 文件。不是 JSON 字符串、不是目录、
不是 stdin。整批一次读入，所以路径按当前工作目录解析，跨目录调用请用绝对路径。
English — --cards takes a file path. Not a JSON string, not a directory, not
stdin. The whole batch is read once; relative paths resolve against the CWD.

中文 — 批量输出体积很重要。 1080p 的 PNG 约 2.3 MB：那层用来防 OLED 色带的
颗粒同时也是压缩的天敌。--format jpeg（质量 92，4:4:4，无色彩二次采样）约 300 KB ——
也就是 1/7 —— 在暗色平坦背景上看不出损失。100 张一套：PNG 230 MB，JPEG 32 MB。
当用户要浏览或轮播整套时选 jpeg。
English — Output size matters for batches. A 1080p PNG runs ~2.3 MB: the grain
that prevents OLED banding also defeats compression. --format jpeg lands at ~300 KB
— about 1/7 — with no visible loss on flat dark fields.

中文 — 让画布匹配用户的显示器。 --auto-size 读取主显示器的物理像素
（它会先声明 DPI 感知，所以 150% 缩放的 2560×1440 屏报的是 2560×1440 而不是 1707×960）。
在 4K 屏上渲染 1920×1080，会被合成器放大后发虚 —— 要么问，要么直接加 --auto-size。
English — Match the canvas to the user's display. A 1920×1080 render on a 4K
screen gets upscaled by the compositor and looks soft.

6. 检查两行审计输出 / Check both audit lines. 中文：每次运行都会打印逐行 WCAG 对比度
   和字形审计；只要有任何一行低于 4.5:1，或某个字符在其字体里没有字形（豆腐块），就会打出
   FAIL 并以非零码退出。修掉出问题的调色板层级或字符，不要交付一批不合格的图。
   English：Every run prints per-line WCAG contrast ratios and a glyph audit, and exits
   non-zero with FAIL if any line drops below 4.5:1 or if a character has no glyph in its
   font (tofu). Fix the offending palette step or character rather than shipping a failing
   batch.

中文 — 一张坏卡只损失一张。 某张卡在渲染里抛异常时，其余卡照常出图，结尾的
render failed: 段列出卡名和异常，整次运行以非零码退出。输入字段不合法则反之：
那种错误在任何卡开始渲染前就整批拒收（E-IN-*），因为一条坏数据通常意味着作者
需要改文件再跑一次。

English — one bad card costs one card. If a card raises mid-render the rest still
get written; the render failed: block names it, and the run exits non-zero. Bad
fields are the opposite case: rejected up front for the whole batch (E-IN-*),
because a bad field means the file has to be fixed anyway.

### 错误码 / Error codes

中文 — 每条拒收与每条 FAIL 都带一个稳定错误码。措辞会改，码不会 ——
包装脚本或 CI 请 grep 码，不要匹配句子。
English — Every refusal and every FAIL carries a stable code. The wording gets
reworded; the code does not — grep the code, not the sentence.

验证输出 / Verifying output

中文 — 把渲染出的 PNG 读回来看一眼确认。这个技能存在，就是为了防止两种失败：

• 出处行技术上在场、但暗到读不出来（层级是靠调暗做的，而不是靠字号）；
• 一行溢出画布，或断在词中间。

English — Read the rendered PNGs back and confirm visually. Two failure modes this
skill exists to prevent:

• an attribution line that is technically present but too dim to read (hierarchy was
  made by dimming instead of by size);
• a line that overflows the canvas or wraps mid-word.

关键约束 / Key constraints

中文 — 完整规范见 references/style-guide.md：布局表、配色调性指南、背景参数、
各平台字体路径、踩坑清单。最要紧的规则：

English — Consult references/style-guide.md for the full spec. The rules that
matter most:

1. 中文：这些是屏保，在 1–3 米外看。 只算对比度不够：一行 10:1 但只有 180/255 的文字，
   隔着房间看依然发暗，因为距离消耗的是绝对亮度。每一级文字都在 219/255 以上，层级来自
   字号（64/56/43/38）和色相 —— 绝不靠把某行调暗进背景。
   English：These are screensavers, read at 1–3 m. A contrast ratio alone is not
   enough: a 10:1 line at 180/255 still looks dull across a room. Every text step sits at
   219/255 or above, and hierarchy comes from size (64/56/43/38) and hue — never from
   dimming a line into the background.
2. 中文：对比度要对背景最亮的像素测，绝不对纯黑测。
   English：Measure contrast against the brightest backdrop pixel, never pure black.
3. 中文：主句偏好单行：它宁可缩字号也不折行。
   English：The lead quote prefers to stay on one line: it shrinks rather than wraps.
4. 中文：CJK 没有词边界 —— 当断行位置重要时，用列表把日语断行钉死。
   English：CJK has no word boundaries — pin Japanese line breaks with a list when a
   clean break matters.
5. 中文：某行远看太细时，先加 --weight（默认 1），再考虑提亮文字。字重和描边不改变
   对比度 —— 它们改变的是边缘清晰度，而远距离真正吃掉的就是边缘。WCAG 给粗体 3:1 而不是
   4.5:1 的门槛，正是这个道理。
   English：When a line reads too thin at distance, raise --weight before
   brightening the text. Weight and shadow do not change the contrast ratio — they change
   edge definition, which is what distance actually destroys.
6. 中文：只有 CJK 逐字断行；其他所有文字按词整体。 永远不要枚举"需要特殊处理的
   文字"，而要枚举"可以断的"，让其余默认正确。旧的正向枚举做法曾静默地把俄语和古希腊语
   断在词中间。
   English：Only CJK breaks between glyphs; every other script stays whole per
   word. Never enumerate the scripts that need special handling — enumerate the ones
   that may break. The old enumeration approach silently split Russian and Ancient Greek.
7. 中文：mesh 主题的颜色场必须真的落地。 动过任何主题之后跑 --list-palettes：
   它会报出背景 P50 / P90 / spread，并标记出"配置了但看不见"的主题。声明式参数需要有一条
   测量证明它生效了。
   English：A mesh theme's colour field must actually land. After touching any
   theme, run --list-palettes. Declarative parameters need a measurement proving they
   took effect.

8. 中文：调用 render() 时，从 weight 起的参数一律用关键字传。 曾经一次位置错位把
   --format/--quality 挤进了 shadow_fill/fmt：运行把 PNG 字节写进了 .jpg 文件，
   而且什么都没报。静默的错误输出比崩溃更糟，因为没有东西提醒你去看。
   English：Pass render() options by keyword from weight onward. A positional
   slip once shifted --format / --quality into shadow_fill / fmt: the run wrote PNG
   bytes into .jpg files and raised nothing at all.

9. 中文：放不下的卡不是卡。 文字块被整块居中，所以一个过高的块会从 y<0 开始，
   首行直接被裁掉 —— 而对比度审计和字形审计照常通过，因为活下来的那些行确实
   有对比度也有字形。约 190 字是 1080px 画布的边界。height check 现在会拦下并报出
   裁掉多少像素。
   English：A card that does not fit is not a card. The block is centred as a whole,
   so an over-tall one starts above y=0 and its first lines are cropped — while both audits
   still pass, because what survived does have contrast and glyphs. ~190 characters is the
   edge of a 1080px canvas. height check now fails the run and reports the cropped depth.

10. 中文：错误码是契约，措辞不是。 输出里的 E-IN-JSON / E-RENDER /
    E-CONTRAST / E-GLYPH / E-HEIGHT 会被包装脚本和 CI 用来分流处理。改提示文案
    随意，改码等于改接口 —— 新增码要加进 ERROR_CODES，并同步 references/faq.md。
    另外记住两类失败的分工：字段坏 = 整批拒收（文件反正要改），渲染坏 = 只损失
    那一张（其余照常出图并计入失败清单）。
    English：The codes are the contract; the wording is not. E-IN-JSON /
    E-RENDER / E-CONTRAST / E-GLYPH / E-HEIGHT are what wrapper scripts and CI
    branch on. Reword freely, but changing a code changes the interface — new codes go
    into ERROR_CODES and references/faq.md. Keep the split in mind: bad fields
    reject the batch (the file needs editing anyway), a bad render costs one card
    (the rest still ship and the failure is listed).

支持的文字系统 / Supported scripts

中文 — 针对本技能实际解析到的字体（simkai.ttf、timesi.ttf）实测：

English — Measured against the fonts this skill actually resolves:

中文 — 含不支持字符的卡片依然会被字形审计拦下，而不是带着坏字上线——但请先看这张表
再承诺韩文或 Emoji 支持，因为审计只能在事后抓到它。
English — A card containing an unsupported character still fails the glyph audit
rather than shipping broken. The audit only catches it after the fact, so check this table
before promising Korean or emoji support.

中文 — 从右向左的文字（希伯来文）：有 raqm 就用 raqm，没有则手工重排。

PIL 本身没有 bidi 引擎，会把 RTL 文字镜像输出。render.py 走两条路：

• 有 raqm —— Pillow ≥ 8.2 的 wheel 自带改版 libraqm，只差一个 fribidi.dll。此时用
  direction="rtl" 交给真正的 Unicode 双向算法 + HarfBuzz 整形：元音符号（niqqud）
  落位正确，RTL 与拉丁/数字混排也能处理。脚本自动检测并启用。
• 没有 raqm —— 退回手工反转。纯 RTL 段落顺序正确，但 niqqud 会错位，
  混排无法处理（宁可不动，也不要半吊子修复）。

启用方法：在启动 Python 之前把 fribidi.dll 放进 Windows 的搜索路径（PATH，或 base
python.exe 旁边）。Pillow 在 import 时绑定它、之后不再重试 —— 同一进程里事后添加
无效，这是实测踩到的。check_env.py 会报告当前状态。Windows 构建：
github.com/ShiftMediaProject/fribidi/releases。

English — Right-to-left text (Hebrew): use raqm when it is there, reorder by hand
when it is not.

PIL has no bidi engine of its own and draws RTL text mirrored. render.py takes one of
two paths:

• raqm present — Pillow wheels since 8.2.0 carry a patched libraqm and need only a
  fribidi.dll. direction="rtl" then runs the real Unicode bidi algorithm plus
  HarfBuzz shaping: niqqud land correctly and mixed RTL + latin/digits works. The
  script detects and uses it automatically.
• raqm absent — falls back to reversing a pure RTL run. Order is right, but niqqud
  misplace and mixed direction is out of reach — left alone rather than half-fixed.

To enable it, put fribidi.dll where Windows looks (PATH, or beside the base
python.exe) before launching Python: Pillow binds it at import and never
retries, so adding it later in the same process does nothing — measured, not assumed.
check_env.py reports the current state. Windows build:
github.com/ShiftMediaProject/fribidi/releases.

中文 — 多词拉丁短语要粘在一起。 折行器在空白处断行，所以 cogito ergo sum 可能被
拆到两行。用不换行空格（U+00A0）连接这类短语即可。
English — Keep multi-word latin phrases together. Join such phrases with a
non-breaking space (U+00A0).

资源 / Resources

• scripts/render.py — 中文：渲染器及其 CLI，可独立执行；只在改布局、调色板或对比度审计时
  才需要读它。 English：the renderer and its CLI; read it only when patching layout,
  palettes, or the contrast audit.
• scripts/check_env.py — 中文：运行时检查；--install 走国内镜像。 / runtime check.
• scripts/lint_cards.py — 中文：渲染前校验卡片 JSON，能抓未知字段、乱码、文字系统混排、
  非法主题、越界字号。 / validate card JSON before rendering.
• scripts/check_dups.py — 中文：跨卡片文件查重复与编号缺口，也可直接扫渲染目录
  （--rendered=DIR）。 / duplicates and index gaps.
• references/style-guide.md — 中文：布局规范、调色板定义、背景参数、字体解析、出处格式、
  踩坑清单。 / layout spec, palettes, backdrop, pitfalls.
• references/faq.md — 中文：症状导向的排查手册。 出问题时从这里开始，它按「你看到
  什么」排序，而不是按主题。 / symptom-first troubleshooting.
• assets/cards.example.json — 中文：8 张卡——5 张原始示例，加上日文原文、古希腊语原文和
  一段超长文本。 / 8 cards, including ja / grc / over-long cases.
• tests/test_render.py — 中文：回归测试，每个用例对应一个曾经真实出现过的缺陷；跑
  python tests/test_render.py，无需第三方框架。 / regression tests, one per defect that
  ever shipped.