agentcss 0.26.0 → 0.27.0

package/01-tokens/README.md

@@ -257,7 +257,7 @@ node ai/cli.js tree   [--set=light|dark] [--cat=color]   # 第二种
    （`contrast` / `gen-ai-contract` / `gen-tokens-tree` / `token-audience` /
    `theme-sync`）。真实事故：一条 `@layer` 让六个工具同时读错，且都没有报错。
 3. 选择器是 `:root[data-market="intl"]` (0,2,0)，**不是** `:where(...)` (0) ——
-   `:where()` 抢不过 `:root` 的 (0,1,0)，写了等于没写（E135）。
+   `:where()` 抢不过 `:root` 的 (0,1,0)，写了等于没写。
 
 > 精简档（`tierA-tokens.css`）**不含**这段交换：它是一份 `<style>` 内的
 > 令牌快照，没有配套文件可引。要国际口径就自己补一条规则 ——

package/01-tokens/responsive-demo.html

@@ -76,7 +76,7 @@ p { margin: 0 0 var(--sp-4); }
   </div>
   <p style="margin-top:var(--sp-4)">
     判据很简单：<strong>这个值变了会不会导致"控件大小跟着变"？会 → 不要流体。</strong>
-    `--fs-xs` / `--fs-sm`（UI 文本）和 `--sp-1`~`--sp-3`（小间距）都属这一类。
+    <code>--fs-xs</code> / <code>--fs-sm</code>（UI 文本）和 <code>--sp-1</code>~<code>--sp-3</code>（小间距）都属这一类。
   </p>
 
   <h2>三、该用断点的：布局结构</h2>

package/01-tokens/tokens.core.css

@@ -884,7 +884,7 @@
    —— 遍历所有声明、后者覆盖前者、**不看选择器**。
    把一段**条件性**的交换规则放在这里，它们会把它当成默认值叠上去，
    于是报告里「暗色 涨」显示成绿色，而浏览器里其实是对的 —— 门禁冤枉代码，
-   比漏判更难查（实测，见 E137）。
+   比漏判更难查（实测）。
    ⇒ 本文件只放「无条件声明」与「暗色媒体段」，条件规则一律外置。
    ========================================================================= */
 

package/01-tokens/tokens.css

@@ -926,7 +926,7 @@
    —— 遍历所有声明、后者覆盖前者、**不看选择器**。
    把一段**条件性**的交换规则放在这里，它们会把它当成默认值叠上去，
    于是报告里「暗色 涨」显示成绿色，而浏览器里其实是对的 —— 门禁冤枉代码，
-   比漏判更难查（实测，见 E137）。
+   比漏判更难查（实测）。
    ⇒ 本文件只放「无条件声明」与「暗色媒体段」，条件规则一律外置。
    ========================================================================= */
 
@@ -1117,7 +1117,7 @@ input[type="submit"],
   /* ⚠️ 模态的遮罩规则**不在这里**，在 03-patterns/overlay/overlay.css。
      原因不是洁癖：`.dialog-backdrop { position: static }` 写在这里会被
      overlay.css 里同特异性的 `position: fixed` 盖掉 —— 规则写了、不生效、
-     不报错（E254 的同一个形状，2026-11-02 由 print-policy-gate 的 L3 抓到）。 */
+     不报错（同一个形状，2026-11-02 由 print-policy-gate 的 L3 抓到）。 */
 
   /* 不跨页切断。代价：高于半页的卡片会被整体推到下一页 ⇒ 页数可能变多。 */
   tr, img, figure, svg,

package/02-primitives/date-range/date-range.js

@@ -194,7 +194,7 @@
     }
 
     function paintSummary(s) {
-      /* 🔴 不拼 innerHTML（E299）：`s` 来自两个 <input> 的 value，
+      /* 🔴 不拼 innerHTML：`s` 来自两个 <input> 的 value，
          而 `type=date` 在 Chromium 97 旧内核会回退成文本输入 ⇒ value 可为任意串。 */
       if (!summary) return;
       summary.textContent = '';

package/02-primitives/timeline/demo.html

@@ -90,7 +90,7 @@
   </div>
   <p class="small">
     <code>timeline--compact</code> 只做两件事：条目间距从 <code>--sp-4</code> 收到
-    <code>--sp-2</code>，时间挪回标题同一行。**它不改字号** ——
+    <code>--sp-2</code>，时间挪回标题同一行。<strong>它不改字号</strong> ——
     在侧栏里把字缩小，等于承认这块内容不重要，而事实往往相反。
   </p>
 

package/03-patterns/drawer/demo.html

@@ -74,7 +74,7 @@ ul.demo-list li { margin: var(--sp-1) 0; }
           <span class="dr-bar__title">筛选</span>
           <button class="dr-tiny" type="button" tabindex="-1" aria-label="关闭">×</button>
         </div>
-      <p class="cmp__why">关闭是**独立目标**：抽屉滑进来之后，用户第一件事就是找它。24px 的叉在触屏上要瞄准，点偏了就点到了背后的内容。</p>
+      <p class="cmp__why">关闭是<strong>独立目标</strong>：抽屉滑进来之后，用户第一件事就是找它。24px 的叉在触屏上要瞄准，点偏了就点到了背后的内容。</p>
     </div>
     <div class="cmp__pane cmp__good" data-good="button.drawer__close|h|>=44">
       <h3>✅ 本库：<code>drawer__close</code> 44px</h3>

package/03-patterns/overlay/overlay.css

@@ -289,7 +289,7 @@ body[data-scroll-locked] { overflow: hidden; }
       隐藏遮罩会把弹窗里的字一起吞掉（静默截断）。实测：屏幕开着 dialog 时
       打印，遮罩是 `position: fixed; inset: 0; rgba(21,24,28,.4)`，整页 40% 黑。
    ⚠️ 必须写在这个文件里：写进 tokens.css 会被这里同特异性的 `position: fixed`
-      盖掉 —— 规则写了、不生效、不报错（E254；由 print-policy-gate L3 抓到）。
+      盖掉 —— 规则写了、不生效、不报错（由 print-policy-gate L3 抓到）。
    ========================================================================= */
 @media print {
   .dialog-backdrop {

package/03-patterns/states/states.css

@@ -137,7 +137,7 @@
        ⇒ 减少动态效果的用户照样看到闪烁的微光；
      · 与 `02-primitives/skeleton/skeleton.css` 同特异性 ⇒ 谁后加载谁定生死。
 
-   即"要不要尊重减少动态效果"取决于 CSS 顺序。与 E254 同类。
+   即"要不要尊重减少动态效果"取决于 CSS 顺序。与同类。
    ⚠️ 这里与 skeleton.css 是**两份实现**（已登记在 css-ownership.json），
       修的时候两边都要看。 */
 @media (prefers-reduced-motion: no-preference) {

package/04-recipes/app-shell/README.md

@@ -243,7 +243,7 @@ rail 下硬塞一个 `.shell__side-label` 会被 CSS 藏掉（兜底，防止它
 
 - **❌ 侧栏 `position: fixed` + 主区 `margin-inline-start`** —— 看起来能用，但侧栏被摘出
   grid 流，主区宽度靠**手抄的数字**维持（改侧栏宽就要改两处）；`inset-inline-start`
-  与 `margin-inline-start` 只要有一处漏改，RTL 下侧栏跑到右边、主区仍在右边留白。**
+  与 `margin-inline-start` 只要有一处漏改，RTL 下侧栏跑到右边、主区仍在右边留白。
 
   正确的做法见上面「侧栏为什么是 `sticky` 而不是 `fixed`」。
 

package/04-recipes/app-shell/demo.html

@@ -48,7 +48,7 @@
 
 <h1>应用外壳 · app-shell</h1>
 <p class="lede">工具型页面的骨架：左边一列常驻导航、上面一条工具栏、右边是主区。
-它存在的理由不是"少写几个 div"，而是**两个每个人都会踩的坑** —— 见下面两节。</p>
+它存在的理由不是"少写几个 div"，而是<strong>两个每个人都会踩的坑</strong> —— 见下面两节。</p>
 
 <h2>1 · 标准三段式</h2>
 <div class="demo">

package/04-recipes/longform/content.html

@@ -934,7 +934,7 @@
    —— 遍历所有声明、后者覆盖前者、**不看选择器**。
    把一段**条件性**的交换规则放在这里，它们会把它当成默认值叠上去，
    于是报告里「暗色 涨」显示成绿色，而浏览器里其实是对的 —— 门禁冤枉代码，
-   比漏判更难查（实测，见 E137）。
+   比漏判更难查（实测）。
    ⇒ 本文件只放「无条件声明」与「暗色媒体段」，条件规则一律外置。
    ========================================================================= */
 
@@ -1125,7 +1125,7 @@ input[type="submit"],
   /* ⚠️ 模态的遮罩规则**不在这里**，在 03-patterns/overlay/overlay.css。
      原因不是洁癖：`.dialog-backdrop { position: static }` 写在这里会被
      overlay.css 里同特异性的 `position: fixed` 盖掉 —— 规则写了、不生效、
-     不报错（E254 的同一个形状，2026-11-02 由 print-policy-gate 的 L3 抓到）。 */
+     不报错（同一个形状，2026-11-02 由 print-policy-gate 的 L3 抓到）。 */
 
   /* 不跨页切断。代价：高于半页的卡片会被整体推到下一页 ⇒ 页数可能变多。 */
   tr, img, figure, svg,
@@ -1460,12 +1460,12 @@ body {
 指令与数据混在一起，地址按字计。</p>
 <h2>存储器构成</h2>
 <p>不同 Block II 的分段数有差异，引用时应以具体的手册为准。</p>
-<table>
+<table aria-label="存储器构成">
 <thead>
 <tr>
-<th>区域</th>
-<th>容量</th>
-<th>用途</th>
+<th scope="col">区域</th>
+<th scope="col">容量</th>
+<th scope="col">用途</th>
 </tr>
 </thead>
 <tbody>

package/04-recipes/report/demo.html

@@ -289,8 +289,8 @@
 <!-- ======================================================================== -->
 <h2 class="rule-top">4 · 🔴 本轮明确不做（不是"还没做"，是"这一版不管"）</h2>
 <ol>
-  <li><strong>分页 PDF / 印刷分页</strong>： @page 页边距、页眉页脚、页码、跨页不断行、
-      孤行寡行控制 —— 全部不在本版范围内，需要 `@page`、实物打样与 PDF 引擎验证。
+  <li><strong>分页 PDF / 印刷分页</strong>：<code>@page</code> 页边距、页眉页脚、页码、跨页不断行、
+      孤行寡行控制 —— 全部不在本版范围内，需要 <code>@page</code>、实物打样与 PDF 引擎验证。
       CSS 里只保留了"打印时不更糟"的最小保障（隐藏边注、图表不跨撕裂）。</li>
   <li><strong>自动目录、尾注/脚注、交叉引用、参考文献样式</strong>：图/表编号用 CSS counter
       做到"写第几就显示第几"，再往上的引用图（「详见图 3」这种自动维护）不支持。</li>

package/04-recipes/table/README.md

@@ -185,7 +185,7 @@ python -m http.server 8000
 会让同一格同时受两套颜色支配，谁赢取决于选择器权重 —— 那是最难查的一类 bug。
 `table-check` 的判据 ⑬ 会挡住给 `table.css` 添 `num--up` / `num--down` 的做法。
 
-### 零值：两边都不许有符号（0.12.1 修，E145）
+### 零值：两边都不许有符号（0.12.1 修）
 
 `format: 'signed-percent'` 的正号由类名触发，而旧实现判的是 `v < 0` ⇒
 `v === 0` 落进 else 分支得到 `num--pos`，渲染成「**+0.0%**」——

package/04-recipes/table/demo.html

@@ -260,7 +260,7 @@
     /* 符号：负数总是有 −（数值语义 + 无障碍第二线索）；
        正数只有 signed-* 才带 + —— 这就是"按列语义处理"。
 
-       🔴 但符号必须**跟打印出来的数字同号**（0.12.1 修，E145）：
+       🔴 但符号必须**跟打印出来的数字同号**（0.12.1 修）：
           旧实现判的是 `v < 0`，于是 `v === 0` 掉进 else 分支拿到 `num--pos`，
           渲染成「+0.0%」—— 一个没变化的数被念成"涨了"。
           同一条错还会在**四舍五入**处复现：0.0004 在 1 位精度下打印成

package/09-assets/bar/bar.css

@@ -167,7 +167,7 @@
    这里原来有一段针对 `prefers-color-scheme: dark` 的媒体查询块，
    里面只有两条：`.bar` 的 background 与 `.bar__label` 的 stroke。
    ⚠️ 那段文字在这里**故意不照抄**：多个门禁拿这个字符串当锚点，
-      注释里出现字面量会把它们带偏（E199 踩过一次）。
+      注释里出现字面量会把它们带偏（踩过一次）。
    它做的只有一件事：把 `var()` 的**兜底值**从 #fff 换成暗色值。
    令牌在的时候（本库的正式用法）两条声明解析结果完全相同 ⇒ 纯冗余。
 

package/09-assets/model-viewer/model-viewer.js

@@ -116,7 +116,7 @@
     this.ui.appendChild(this.btn);
 
     this.hint = el('p', 'mv__hint');
-    /* 🔴 文件名来自 `src`，可能是调用方拼出来的 URL（E299）。
+    /* 🔴 文件名来自 `src`，可能是调用方拼出来的 URL。
        原来用 innerHTML 直接拼 ⇒ `<img onerror>` 这类值会被解析成节点。
        改成 textContent 组装：`<code>` 与 `<b>` 仍然存在，但文本永远只是文本。 */
     var fname = el('code', null, this.src.split('/').pop() || '—');

package/AGENTS.md

@@ -4,6 +4,8 @@
 - **Known failure modes:** `ai/pitfalls.json`, or `npx agentcss ai pitfalls --json --component=<id>`.
 - **Print / PDF:** `npx agentcss ai pdf <page.html> --out page.pdf [--paper=a4|letter|a5] [--margin="18mm 15mm"] [--max-pages=N]`. `@page` belongs to the exporter, never to the library. To hold a document to paper standards use `ai check <doc.json> --medium=paper` — it then requires `pageBudget` and refuses `pagination:"server"` components.
 - **Query:** `npx agentcss ai components --json [--maturity=stable]` · `ai tokens --json [--set=dark]` · `ai tree --json`.
-- **Validate:** `npx agentcss ai validate <file> --schema=components --json`. Every subcommand accepts `--json`; failures print `{"ok":false,…}` and exit non-zero.
+- **Validate, then branch on the exit code:** `npx agentcss ai validate <file> --schema=components --json`. Every subcommand accepts `--json`; failures print exactly one document `{"ok":false,"command","error":{"kind","message"}}`. Codes are one table for the whole CLI: `0` pass · `1` what you checked is bad (a verdict) · `2` bad flag or value — unknown flag, unknown enum value, empty value and a repeated flag all land here · `3` environment missing (no browser / no `node`) · `4` render failed · `5` over budget · `6` tool bug. A typo can never degrade into "empty result, exit 0".
+- **Check the page you actually wrote:** `npx agentcss ai check <page.html> [--recipe=report/finance]`. Static — no network, no browser. It reports class names the library does not define, stylesheets that were never linked (naming the file that defines the class), missing `img alt` / table name / `th scope`, skipped heading levels, and the per-layout obligations in `ai/recipes.json`. `npx agentcss ai scaffold <recipe> --out <page.html>` gives a minimal shell that already passes.
+- **See it before shipping:** `npx agentcss ai shot <page.html> --out shot-{width}.png --width=390,1440 --full`. The viewport is exactly the width you ask for (a cropped window is not the same thing), and it reports horizontal-overflow culprits plus JS errors.
 - **Markup ground truth:** each component's `demo.html`. Restyle through tokens (CSS variables); never rewrite component selectors.
 - **Docs are Chinese:** `ai/START-HERE.md` (navigation). English entry points: `README.md`, `llms.txt`, `llms-full.txt`.

package/CHANGELOG.md

@@ -12,9 +12,107 @@
 - **次版本**：新增组件 / 新增能力（下游不改代码也能升级）
 - **修订号**：修 bug、修文案（下游无需任何改动）
 
+> **关于历史条目里的 `E123` 这类编号**：那是 0.26.0 及更早版本沿用的
+> 内部失误台账索引，台账本身不随包分发。从 0.27.0 起，本文件只描述
+> **改了什么、影响谁**，不再引用内部编号 —— 读者不需要一份查不到的索引。
+
 ## [Unreleased]
 
-（无）
+
+## [0.27.0] - 2026-11-06
+
+### Added
+
+- **`ai check <page.html>` —— 校验产物，而不只是计划。**
+  此前 `ai check` 只吃 `doc.json`（节点类型、组件档位），管不到"写出来的那一页"。
+  新增 16 条判据，查的都是**不会报错、只会静默失效**的东西：
+  类名库里没有 / 类名库里有但这页没引到定义它的样式表（指名到文件）/
+  引的样式表一个都读不到 / `<img>` 缺 `alt` / 表没有可访问名称 /
+  `th` 缺 `scope` / id 重复 / 标题跳级 / 表单控件没有可读名称 /
+  `target="_blank"` 缺 `rel="noopener"` / 缺 `lang`、`charset`、`viewport`。
+  纯静态：不联网、不启动浏览器。按扩展名分派，`check x.json` 的行为不变。
+- **`ai shot <page.html> --out shot-{width}.png` —— 出 PNG。**
+  用 Chrome 的调试管道（不开端口、不打包浏览器）把视口**设成**要的宽度，
+  再截图。为什么不用 `--window-size`：Windows 上窗口有最小宽度，
+  `--window-size=390` 实际按 500px 排版、只按 390 裁一刀 —— 图是好的，
+  内容不对，且不报错。输出里同时给出横向溢出（指名元素）、内容高度与 JS 报错。
+  同一台机器、同样参数两次逐字节一致（门禁验的就是这条）。
+- **`ai scaffold <版式> --out page.html` —— 三个最小壳**（`report/finance`、
+  `report/technical`、`report/magazine`）：只给正确的骨架与必有件的位置，
+  不含内容。三个壳都由门禁跑一遍 `ai check --recipe=<自己>`。
+- **`ai/recipes.json`** —— 版式"必有件"的机器可读事实：能从标记判定的写进
+  `requires`（少一件就报错），判不了的写进 `unchecked`（只打印，不判过）。
+- **`prose-gate`** —— 检查页面的**可见文本**：未渲染的 `**加粗**` / 反引号 / `](链接)`、
+  整页括号不配平（通常是把 `（…）` 切断），以及生成器是否切在语义边界上。
+  自带反向控制：四类注入必须全部抓到，注释与代码块里的同样字符不许误报。
+- **诊断可分辨**：`npm pack` 失败时 `pack-closure` 会打印 npm/node 版本、cwd、
+  stdout/stderr 尾，并区分"产品失败（package.json 坏了）"与"清单没拿到（无法判定）"；
+  `check-all.sh` 在 `node` 不在 PATH 时一次性说明并整体退出 `3`，
+  而不是让 5 道 python 门禁各抛一个 `WinError 2` 堆栈。
+
+### Changed
+
+- **退出码统一成一套，并且可以按码分支。** 以前同一个 `--profile` 写错，
+  `pdf` 给 2、其它子命令给 1；而 `1` 同时表示"页面有错"和"工具崩了"。
+  现在全 CLI 一张表：
+
+  | 码 | 含义 |
+  |---|---|
+  | 0 | 通过 |
+  | **1** | **判定不通过**（页面/文档确实有错 —— 是结论，不是工具坏了） |
+  | **2** | 用法错误（开关名、取值、重复、空值） |
+  | 3 | 环境不具备（没有浏览器 / 没有 node） |
+  | 4 | 渲染失败 |
+  | 5 | 超出预算（产物完整） |
+  | 6 | 工具内部错误 |
+
+  失败的 JSON 也统一成**一种形状**：`{"ok":false,"command","error":{"kind","message"}}`
+  （`pdf` 以前发的是顶层 `code`/`message`，调用方得写两个分支）。
+- **枚举开关的非法值一律报错，不再退化成"空结果"。** 以前：
+
+  ```
+  ai tokens --set=not-a-theme --json      → stdout 是字面量 undefined，退出码 0
+  ai tree   --set=not-a-theme --json      → 同上
+  ai components --maturity=not-a-level    → []，退出码 0
+  ```
+
+  对 Agent 这不是"没输出"，而是**错误的控制流**：它会把拼错的参数读成
+  "这个库没有 beta 组件"，然后据此写结论。现在非法值 / 空值 / 同一个开关给两次
+  / 开关后面吞掉另一个开关，全部 `2` 退出，并在 message 里列出合法取值。
+  合法取值**从数据现算**（`profiles.json` 的 `allowedMaturity`、`tokens.json` 的
+  `sets`、`tokens.tree.json` 的 `meta.categories`、`recipes.json` 的版式），
+  不在这里另抄一份。
+- **与本命令无关的开关不再被静默忽略。** `ai components --set=dark` 以前退出码 0、
+  什么都不说 —— 调用方会以为"按 dark 过滤过了"。现在每个子命令声明自己认识的开关
+  （`ai/cli.js` 的 `FLAGS` 表），不认识的给 `2`。
+- **`ai check <page.html> --profile` / `--medium` 明确报错**：这两个开关只对
+  `doc.json` 有效。以前静默忽略 ⇒ 调用方以为"按 strict 档查过了"。
+
+### Fixed
+
+- **Schema 校验器实现了 `uniqueItems` 与 `not`。** 这两个关键字一直挂在
+  "已实现"白名单里却没有实现：`validate({type:'array',uniqueItems:true},[1,1])`
+  返回 `ok:true`，`validate({type:'number',not:{const:1}},1)` 同样。
+  白名单只保证"允许出现"，不保证"真的校验" —— 现在逐个关键字都有正/负契约用例，
+  新加关键字却不写用例，门禁直接红。
+- **能力预扫从 4 份 schema 扩到全部 8 份。** 以前只扫 contract/components/tokens/patch，
+  `behaviors` / `deprecations` / `tokensAudience` / `tokensTree` 从来没被扫过 ——
+  它们里面出现未知关键字也不会有人知道。扩上去当场撞出一个真 bug：
+  `patternProperties` 的**键是正则**，被当成关键字检查，于是
+  `tokensAudience` 报"用了没实现的关键字"（schema 本身完全合法）。
+- **生成器不再按字符硬切句子。** 首页摘要以前是 `purpose[:56]`，于是
+  `delta` 结尾是「会计正负是 ta」、`timeline` 是「颜色在」，首页还因此括号不配平。
+  现在按语义边界切（句末标点 > 分句边界 > 硬切 + 省略号），并且括号必须配平。
+  `aria-label` 里的小节名走同一条规则 —— 读屏会把它逐字念出来。
+- **可见文本里不再有未渲染的 Markdown。** 修了 5 处：
+  `timeline` / `drawer` / `app-shell` 的 `**加粗**`，`responsive-demo` 与
+  `report` 页里的反引号代码；另有 `guide/app-shell.html` 的一个孤立 `**`
+  （源头是 `04-recipes/app-shell/README.md` 里一处没闭合的加粗）。
+- **`md-render.py` 产出的表格补 `scope="col"` 与可访问名称**
+  （取最近一节的小节标题作 `aria-label`）。此前每一份从 Markdown 出来的页面
+  都缺这两件 —— GFM 的表格语法里没有它们可写，而缺了不会报错，
+  只会让读屏用户听到一串没有表头的数字。
+- `04-recipes/longform/content.html` 随之重生成（差 4 行，纯属性）。
 
 ## [0.26.0] - 2026-11-04
 
@@ -141,7 +239,7 @@ F8（demo 对比度）、F10（model-viewer 小溢出）、F12（缺 SemVer/废
   按真值更正，历史段落只加注记、不改写。
 
 上述每一项都跑了正向、反向控制与真实发布包验证；发布前全量门禁 0 FAIL。
-新增的失误与纠正规则登记在内部 `ERRORS.md`（不随包分发）。
+新增的失误与纠正规则登记在内部失误台账（不随包分发）。
 
 ---
 
@@ -335,7 +433,7 @@ README 里「想知道我们踩过哪些坑」的指向，从内部文件改到
 
 ### 修复：9 处指向不存在文件的引用
 
-`ERRORS.md`（在内部目录，不入库）、`docs/ROADMAP.md`、`docs/GUIDANCE.md` 被
+内部失误台账（不入库）、`docs/ROADMAP.md`、`docs/GUIDANCE.md` 被
 README / CONTRIBUTING / 05-audit/README 引用，但文件不存在。
 现在全部改指向真实文件，或去掉编号（内部条号对外部读者没有意义）。
 
@@ -1339,7 +1437,7 @@ G0d 前提：G4 的替换真的改到了文件
 现在：
 
 - 词表统一走 `terms`（原来 outsider-audit 自己抄了一份，与 leak-scan 口径不同）
-- 真实代号与用户名模式搬进 `internal/private-terms.txt`
+- 真实代号与用户名模式移出公开树
   （`.gitignore` 里，也不在 npm `files` 里 ⇒ 不进包）
 - 读不到时**不假装扫过**：`terms.private_status()` 由三道扫描器打印
   「私有词表未加载 ⇒ 本次未覆盖」
@@ -2084,7 +2182,7 @@ Actions → release → Run workflow → 勾 `shoot_baseline`，
 ### 文档对齐
 
 - `CONTRIBUTING.md`：补「全量为什么**不**在 CI 上跑」的完整理由与责任边界；
-  补 `rc=3` 三态表；补「失败时先读 `internal/tmp/selftest-fail-*.log`」。
+  补 `rc=3` 三态表；补「失败时先读本地门禁日志」。
 - `docs/A11Y-MANUAL-PROTOCOL.md`：结果表补 `accordion` / `drawer` / `dropdown`
   三行 —— 三个 beta 组件此前一个都不在表内，而「beta 升 stable」的判据之一
   就是行为零欠账，人工读屏是唯一的用户侧证据。**状态仍写「未执行」**：

package/CONTRIBUTING.md

@@ -27,23 +27,45 @@
 npm ci                 # 按锁文件装（验证 lockfile 真能装）
 npm run gate           # 全量：含浏览器类
 npm run gate:fast      # 只跑静态层，不用装浏览器
+npm run gate:pre-commit # 提交前：五道秒级判据（实测约 7s）
 ```
 
+三档不是"快慢"的区别，是**判断边界**的区别：
+
+| 档 | 什么时候跑 | 能证明什么 |
+|---|---|---|
+| `gate:pre-commit` | 每次 `git commit` 前 | 契约 / 页面结构 / 文案 / 行为核心 / 类型没被改坏 |
+| `gate:fast` | push 前 | 加上静态层的全部判据（不含浏览器） |
+| `gate` | 收尾、发版前 | 全部，含浏览器、视觉基线、打包闭包 |
+
+`gate:pre-commit` 走绿只说明"可以提交"，**不说明可以发版**。想让它自动跑，
+把 `bash 05-audit/check-all.sh --pre-commit` 写进 `.git/hooks/pre-commit` 即可；
+本仓不替使用者装 hook —— 提交节奏是个人选择。
+
 全量的门禁条数由 `05-audit/check-all.sh` 实算，**不在文档里写死** —— 新增一道门禁
 就会变，写下来的第二天就是第二个会漂的真值（I-7）。默认 `min(核数, 6)` 路并发；
 组件层要起浏览器，还要逐张比浅色 / 暗色 / RTL 三套视觉基线（按平台分集，
 只比本平台那套）。条数、耗时、并发效率一律以**本轮门禁打印的结果**为准。
 只想确认没改坏静态契约的话用 `gate:fast`，几秒到几分钟。
 
-### 全量为什么**不**在 CI 上跑（这不是缺口，是结论）
+### CI 跑什么、不跑什么（边界，不是缺口）
 
 `.github/workflows/gate.yml` 分三层：`quick`（`MODE=fast`，静态 + 视觉）、
-`contract`（API 契约，需 Chromium）、`browsers`（nightly，三引擎矩阵）。
+`contract`（API 契约，需 Chromium）、`browsers`（三引擎矩阵）。
 **没有任何一处是 `MODE=full`**，而且不该有 —— 实测在 Linux runner 上跑全量会
 FAIL 10+ 道（字体渲染不同 ⇒ 视觉 diff 必然不一致；路径/编码不同 ⇒ 体积类误报；
 shallow clone ⇒ 依赖 git 状态的判据语义不同；浏览器版本不同 ⇒ 截图基线不匹配）。
 
 **一个长期红的 CI 比没有 CI 更糟**：大家会习惯性忽略它，真正的新问题也一起被忽略。
+
+触发面（2026-11-05 调整）：
+
+| 事件 | 跑哪些 | 为什么 |
+|---|---|---|
+| 直推 `master` | 只 `quick` | 这个仓库一直是直推，之前**完全没有 CI 保护**；quick 约 3–4 分钟，能挡住"本地没跑就推" |
+| PR | `quick` + `contract` | 合并前要契约 |
+| nightly / 手动 | 全部三个 job | 三引擎矩阵成本高，不该每次 push 都烧 |
+
 所以边界是：
 
 - **CI 负责**：跨平台可靠的那部分（静态契约、类型、API 形态、单引擎行为）
@@ -52,10 +74,29 @@ shallow clone ⇒ 依赖 git 状态的判据语义不同；浏览器版本不同
 `browsers` job 已覆盖三引擎的组件行为契约，但它**不替代**本机全量：
 它不跑视觉基线（基线按平台分集）、不跑 RTL/响应式/无障碍全量。
 
+### 私有词表（维护者；缺失时 leak 判据会变弱）
+
+`leak-scan` 的「真实代号 / 用户名」两类要靠一份**不随包分发**的词表才能生效。
+它放在 `internal/private-terms.txt`（已被 `.gitignore` 挡住，也不在 `package.json`
+的 `files` 里）。文件不在时，脚本会打印：
+
+```
+⚠️ 私有词表未加载（0 条）⇒ 真实代号 / 用户名判据**本次未覆盖**
+```
+
+**这不是通过**。本地开发把它放回去即可；CI 上因为拿不到这个文件，需要：
+
+1. GitHub 仓库 → Settings → Secrets and variables → Actions → 新建
+   `FL_PRIVATE_TERMS`，值就是词表全文（多行）；
+2. `gate.yml` 的 `quick` job 会把它写进 `internal/private-terms.txt` 再跑门禁；
+3. 没配时日志里会有一条 `::notice`，明确写着"这一类在 CI 上不覆盖"。
+
+⚠️ 不要把词表直接提交进仓库 —— 那等于把要防的东西本身公开了。
+
 ### 失败时先读哪里
 
 `selftest-all` 报红时，除屏幕上那 4 行摘要，**完整子输出会落盘**到
-`internal/tmp/selftest-fail-<脚本名>.log`（`internal/` 已被忽略，不进仓库）。
+`internal/tmp/selftest-fail-<脚本名>.log`（`internal/` 是本地忽略目录，不进仓库）。
 不可复现的红最需要这个 —— 摘要往往不够定位。
 
 只想验一条反向控制时，用 `SKIP_SELFTESTS="a.py,b.py" python3 05-audit/selftest-all.py`

package/README.md

@@ -31,6 +31,8 @@ The JS entry points (`esm/*.mjs`) are **ESM only** — `exports` has no `require
 
 - **Every demo page, one index** — https://owain323.github.io/frontend-lib/
 - **Component documentation with search** — https://owain323.github.io/frontend-lib/guide/
+- **How this project is organized** — [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+  (what each layer is, how the automated checks work — in plain language)
 
 Both are generated from `ai/components.json` and the per-component `README.md`
 files, so a page cannot quietly go missing from the index when a component is

package/README.zh-CN.md

@@ -15,6 +15,8 @@
 
 - **全部示例页，一个索引** —— https://owain323.github.io/frontend-lib/
 - **带搜索的组件文档** —— https://owain323.github.io/frontend-lib/guide/
+- **这个项目是怎么组成的** —— [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+  （四层组件、自动检查系统，用平话讲）
 
 两者都由 `ai/components.json` 与各组件的 `README.md` **生成**：
 新增组件时索引不会悄悄漏掉它，文档页里的每条链接都指向真实存在的文件。

package/START-HERE.md

@@ -122,11 +122,15 @@
 | `report/` | `04-recipes/report/` | 报告版式系统 v1：共享基础 + 三种版式取舍（杂志 / 科研技术 / 金融研究） |
 | `table/` | `04-recipes/table/` | 专业数据表格：列级格式与单位，三种用途预设 |
 
-## 抄完先做这三件事
-
-1. **看效果** —— 每个组件目录下有 `demo.html`，抄完对照着比
-2. **跑一遍无障碍** —— 浏览器控制台里（或用 axe）确认对比度达标
-3. **别改类名** —— 类名是 API（`.btn` `.btn--primary` `.field__input`），
+## 抄完先做这几件事
+
+1. **查一遍结构** —— `node ai/cli.js check 你的页面.html`
+   查的是产物：类名在库里存不存在、引没引到定义它的样式表、图有没有 alt、
+   表有没有名字、标题有没有跳级。**它不联网、不开浏览器，一秒出结果。**
+2. **看一眼** —— `node ai/cli.js shot 你的页面.html --out shot-{width}.png --width=390,1440 --full`
+   390 那张是按真 390 宽度排的（不是把宽图裁一刀），顺手报横向溢出与 JS 报错。
+3. **跑一遍无障碍** —— 浏览器控制台里（或用 axe）确认对比度达标
+4. **别改类名** —— 类名是 API（`.btn` `.btn--primary` `.field__input`），
    改名等于换组件。**要改样式就改令牌**，全库会一起变
 
 ---
@@ -146,6 +150,9 @@ CSS 类跨框架通用，React 组件会绑死框架。
 
 > **抄 `tierA-tokens.css`（A 档）或 `tokens.css`（B/C 档）→ 再抄你要的那几个 CSS → 保留类名。**
 
+**让模型来写页面时**，另有一份按「它需要知道什么」组织的清单：`ai/START-HERE.md`
+（`ai components` / `ai pitfalls` / `ai check` / `ai shot` / `ai scaffold` 都在那里）。
+
 ---
 
 ## 你可能还想找的（有 / 没有，一次说清）

package/ai/START-HERE.md

@@ -61,7 +61,9 @@
 | 令牌名与取值 | `node ai/cli.js tokens --mode=dark`、`node ai/cli.js tree`（分层视图） |
 | 组件真实长什么样 | 该组件目录下的 `demo.html` |
 | 英文一页速览 | `llms.txt` / `llms-full.txt`（发现层；本文件是中文详版） |
-| 页面怎么搭 | `04-recipes/` 下的示例 |
+| 页面怎么搭 | `04-recipes/` 下的示例；要写报告/长文就先 `node ai/cli.js scaffold list` |
+| 写完了对不对 | `node ai/cli.js check <页面.html>`（类名/结构/版式必有件） |
+| 写完好不看 | `node ai/cli.js shot <页面.html> --out shot-{width}.png --width=390,1440 --full` |
 | 令牌怎么改 | README「主题定制」（覆盖 CSS 变量，不需重新编译） |
 
 **类名即 API**（`.btn`、`.btn--primary`）。改样式改**令牌**，不要改类名，
@@ -71,7 +73,7 @@
 
 | 信号 | 怎么看 |
 |---|---|
-| 成熟度 | `ai/components.json` 的 `maturity` 是**算出来的**（判据在 `ai/components.meta.json`），不是人写的 |
+| 成熟度 | `ai/components.json` 的 `maturity` 是**算出来的**（判据在 `ai/components.meta.json`），不是人写的。它判的是**机制完整**：有 demo、有专属门禁、没有旧 `.is-*` 状态类、没有行为债。**它不判**视觉质量、真实模型生成效果、真机表现 —— `40/40 stable` 不等于 `40/40 好看`，更不等于有人在生产里用过 |
 | 有没有 demo | 组件目录下有 `demo.html` 就能直接跑起来对照 |
 | 有没有门禁守 | `05-audit/check-all.sh`（`npm run gate`）一次跑全，逐项打印 `PASS`/`FAIL`/`SKIP` |
 | 浏览器支持 | README「浏览器支持」表：桌面 Chrome/Edge/Firefox 已验证（自动化）；iOS Safari / 微信 / 企微 / QQ 等 7 个入口**人工实测过能力探针**（`🔍`，无回归保护）；**Android 系统 WebView 无数据** |
@@ -92,11 +94,42 @@
 npm ci                 # 按锁文件安装（首次）
 npm test               # 单元测试
 npm run test:types     # 类型契约：正例必过 + 反例必挂
-npm run gate:fast      # 静态检查（约 45 秒，改代码时跑）
-npm run gate           # 全量检查（含浏览器，提交前跑）
-node ai/cli.js check <doc.json>   # 校验契约文档（读 JSON，不解析原始 HTML）
+npm run gate:pre-commit # 提交前档（约 7 秒：契约 / 页面 / 文案 / 行为核心 / 类型）
+npm run gate:fast      # 静态层全部（约 4 分钟，不含浏览器类判据）
+npm run gate           # 全量（含浏览器与视觉基线；**发版前**跑，不是提交前）
+node ai/cli.js check <doc.json>   # 校验契约文档（计划：节点类型 / 组件档位）
+node ai/cli.js check <页面.html>  # 校验产物（类名 / 结构 / 版式必有件）
+node ai/cli.js shot  <页面.html> --out shot-{width}.png --width=390,1440 --full
+                                  # 截图（真实视口），顺带报横向溢出与 JS 报错
+node ai/cli.js scaffold report/finance --out report.html
+                                  # 生成最小壳（正确骨架 + 必有件位置），不含内容
 ```
 
+**退出码可以直接分支**（全部子命令同一套）：
+
+| 码 | 含义 | 你该做什么 |
+|---|---|---|
+| 0 | 通过 | — |
+| 1 | **判定不通过**（页面/文档确实有错） | 读 `findings` / `errors`，改产物 |
+| 2 | 用法错误（开关名、取值、重复、空值） | 改调用 |
+| 3 | 环境不具备（没有浏览器 / 没有 node） | 换机器或跳过，别改代码 |
+| 4 | 渲染失败 | 看 message |
+| 5 | 超出预算（产物是完整的） | 拆文档或放宽预算 |
+| 6 | 工具内部错误 | 报 bug，别改自己的参数 |
+
+> `1` 和 `2` 分开是有原因的：把「页面有 3 个错」和「`--profile` 拼错了」都返回 1，
+> 自动修复循环会去改**错的那一边**。
+
+**计划与产物是两件事，判据不重叠**：
+
+| 查什么 | 命令 | 能发现 | 发现不了 |
+|---|---|---|---|
+| 计划（doc.json） | `check <doc.json>` | 节点类型、组件是否在档位内、介质义务 | 写出来的 HTML 对不对 |
+| 产物（.html） | `check <页面.html>` | 类名未定义 / 引错样式表 / 缺 alt、caption、scope / 标题跳级 / 版式缺件 | 页面**好看不好看**（那要 `shot` 看一眼） |
+
+> 两个命令都**不联网、不启动浏览器**；`shot` 用你机器上已装的 Chrome/Edge，
+> 不打包浏览器（理由同 `ai pdf`）。
+
 改动本库**自身**时的分层（决定该动哪一层）：
 
 | 层 | 文件 | 性质 |
@@ -112,7 +145,8 @@ node ai/cli.js check <doc.json>   # 校验契约文档（读 JSON，不解析原
 
 有人问过要不要把 `ai/*.json` 包成一个 MCP server。结论是**不做**：
 
-1. 十一个子命令**全是只读查询** —— MCP 版本只是换一层传输，一个新能力都没有。
+1. 十四个子命令**全是本机命令**（读契约 / 校验文件 / 调本机浏览器）——
+   MCP 版本只是换一层传输，一个新能力都没有。
 2. 它会是**第二份真值**：命令怎么调、参数叫什么、返回什么形状，都得再写一遍。
    CLI 改了 server 没改，就多一处只有用户能发现的错（`--json` 那次已经踩过同类）。
 3. 用户要多信任一个常驻进程（安装、权限、升级），而 CLI 离线、可审计、跑完即退。