mosaic-headless 1.17.1 → 1.17.2

package/README.ja.md

@@ -19,6 +19,21 @@ npx mosaic-headless cursor --to ./my-project
 npx mosaic-headless --list                   # 対応 8 プラットフォーム
 ```
 
+| プラットフォーム | 何が入るか | どこに |
+|---|---|---|
+| Claude Code | スキル一式：SKILL.md + references/ + tools/ + data/ + sites/ | `~/.claude/skills/` または `./.claude/skills/` |
+| Codex CLI | スキル一式 | `~/.codex/` |
+| Gemini CLI | スキル一式 | `~/.gemini/` |
+| GitHub Copilot | スキル一式に加え、`copilot-instructions.md` へ追記 | `./.github/` |
+| Cursor | references を埋め込んだ `.mdc` ルール 1 本 | `~/.cursor/rules/` |
+| Windsurf | references を埋め込んだルールファイル 1 本 | `./.devin/` |
+| Continue | references を埋め込んだルールファイル 1 本 | `~/.continue/` |
+| Claude.ai | プロジェクトスキルとしてアップロードする zip | 保存した場所 |
+
+各プラットフォームのインストールはリリースゲートがテンプレートに対して検証する。ツールの
+実行には Python 3 と Playwright が必要。ルールファイル型のプラットフォームには知識だけが
+入り、ツールは入らない。
+
 **更新は自動では起きない。** npm に新版が出ても、エージェントが読み込むフォルダは変わらない。
 インストーラを `--force` 付きで再実行する（付けないと、手を入れた可能性のある SKILL.md の
 上書きを拒否する）：
@@ -27,7 +42,6 @@ npx mosaic-headless --list                   # 対応 8 プラットフォーム
 npx mosaic-headless@latest claude-code --global --force
 ```
 
-Python 3 と Playwright はツールを*動かす*ときに必要で、インストールには不要。
 
 ## これは何か
 
@@ -40,6 +54,40 @@ fractional-index の文字列。エディタはこのモデルの一クライア
 計測したもの — と、モデルを通して書き、出てきたものを検証し、Elementor からページを持ち込む
 ためのツール群である。
 
+## 部品のつながり
+
+```mermaid
+flowchart LR
+    subgraph measure["一度だけ、実サイトに対して計測"]
+        SRC[プラグインのソース] -->|extract_*.py| D[(data/*.csv)]
+        SW[sweep_*.py / probe_*.py] -->|commit・描画・断言| D
+    end
+
+    subgraph write["あなたが作るすべてのページ"]
+        Q[mo.py] -->|答えは一つ、計測結果が先頭| SPEC[ページ spec]
+        EL[Elementor _elementor_data] -->|from_elementor.py| SPEC
+        SPEC -->|build_page.py が壊れるものを拒否| REST[Mosaic REST：checkout・check・commit]
+        REST --> DB[(23 テーブル)]
+        DB --> PAGE[配信されたページ]
+    end
+
+    subgraph verify["commit を信用しない"]
+        PAGE --> V1[verify_rwd.py]
+        PAGE --> V2[verify_browser.py + デザイン監査]
+        PAGE --> V3[verify_intro.py / verify_loop.py]
+        PAGE --> V4[verify_conversion.py]
+        V1 & V2 & V3 & V4 --> CSV[(検証 CSV)]
+        CSV --> GATE[check-release.mjs]
+    end
+
+    D --> Q
+    D --> SPEC
+```
+
+左から右へ：表は一度だけ計測して同梱される；すべてのページは表を通して書かれ、表が否と
+言えば拒否される；配信されたページを読み戻し、結果がリリースゲートの見る表に記録される
+までは何も信用しない。
+
 ## 唯一のルール
 
 **ノード型、プロパティ名、列挙値、スタイルキー、Free/Pro の判断を記憶から書かない。
@@ -110,6 +158,25 @@ commit の成功はページが動く証拠ではないし、正しいスタイ
 `SKIPPED`、`NO_HOST`、`INCONCLUSIVE` は合格率に決して繰り込まない。自らの盲点を成功として
 数えるスイープこそ、このスキルが反対しているものだ。
 
+## 引くのに何トークンかかるか
+
+Mosaic のノード型やスタイルキーが実際に何を受け取るかをエージェントが知る方法は三つ。
+同じ六つの課題を tiktoken で計測（`tools/benchmark_tokens.py`、自分で実行できる）：
+
+| 課題 | ソースを読む | 全テーブル読込 | `mo.py` で引く |
+|---|---:|---:|---:|
+| 見出し・段落・リンク付きボタンを置く | 10,005 | 259,539 | **961** |
+| padding・ボーダー・角丸をレスポンシブに設定 | 3,490 | 259,539 | **396** |
+| アコーディオンが使えるか、どう入れ子にするか | 15,615 | 259,539 | **397** |
+| 実際にコンパイルされる hover/focus 状態を探す | 3,619 | 259,539 | **1,054** |
+| ある CSS を出す Mosaic のキーを探す | 1,862 | 259,539 | **51** |
+| commit 前に何が危険かを知る | 63,172 | 259,539 | **288** |
+
+**ソースを読むより 71〜99.5%、全テーブル読込より 99.6% 以上トークンが少ない** — しかも
+六つのうち四つはソースでは答えられない。「宣言されている」と「コンパイルされる」は別の
+問いで、後者を問うたのはスイープだけだからだ。テーブルは合計 259,539 トークン。決して
+まとめて読み込まないこと。`mo.py` がクエリである。
+
 ### 書く前に知っておくべき結果
 
 **`group` に属するプロパティは単独で設定しても無効。** 両方向で厳密：グループ外の 78 個は
@@ -167,14 +234,13 @@ loop grid、フォーム、カウントダウン、サードパーティ addon
 | `sweep_*.py` / `probe_*.py` | 表を作った計測器そのもの |
 | `bootstrap_probe_theme.php` / `mint_session.php` | ライセンス不要の実験用テーマと、WP-CLI から作る REST セッション |
 
-## 実例、ライブで
+## 実例
 
-`sites/_moksa.py` はテーブルだけで本物のスタジオサイトを構築し、参照実装として同梱される。
-**https://mosaic.moksaweb.com/** で公開中：1,286 ノードのホームページに、名前付き view timeline
-によるスクロール追従の条項インデックス；浮世絵の版を一枚ずつ刷っていく入場シーケンス；
-隅で永遠に刷り続け、タップで拡大する版；そして UI 全体が shortcode を実行する 1 つの `code`
-ノードから届く WooCommerce の [My Account](https://mosaic.moksaweb.com/my-account/) ページ。
-自前の JavaScript はどこにもない。
+`sites/_moksa.py` はテーブルだけで本物のスタジオサイトを構築し、参照実装として同梱される：
+1,286 ノードのホームページに、名前付き view timeline によるスクロール追従の条項インデックス；
+浮世絵の版を一枚ずつ刷っていく入場シーケンス；隅で永遠に刷り続け、タップで拡大する版；
+そして UI 全体が shortcode を実行する 1 つの `code` ノードから届く WooCommerce の My Account
+ページ。自前の JavaScript はどこにもない。`data/` のすべての検証表はこれに対して作られた。
 
 ## どこから始めるか
 

package/README.ko.md

@@ -19,6 +19,20 @@ npx mosaic-headless cursor --to ./my-project
 npx mosaic-headless --list                   # 지원하는 8개 플랫폼
 ```
 
+| 플랫폼 | 무엇이 설치되나 | 어디에 |
+|---|---|---|
+| Claude Code | 스킬 전체: SKILL.md + references/ + tools/ + data/ + sites/ | `~/.claude/skills/` 또는 `./.claude/skills/` |
+| Codex CLI | 스킬 전체 | `~/.codex/` |
+| Gemini CLI | 스킬 전체 | `~/.gemini/` |
+| GitHub Copilot | 스킬 전체, 그리고 `copilot-instructions.md`에 섹션 추가 | `./.github/` |
+| Cursor | references를 내장한 `.mdc` 규칙 파일 하나 | `~/.cursor/rules/` |
+| Windsurf | references를 내장한 규칙 파일 하나 | `./.devin/` |
+| Continue | references를 내장한 규칙 파일 하나 | `~/.continue/` |
+| Claude.ai | 프로젝트 스킬로 업로드할 zip | 저장한 곳 |
+
+모든 플랫폼 설치는 릴리스 게이트가 템플릿에 대해 검증한다. 도구 실행에는 Python 3와
+Playwright가 필요하다; 규칙 파일 플랫폼은 지식만 받고 도구는 받지 않는다.
+
 **업데이트는 저절로 되지 않는다.** npm에 새 버전이 올라가도 에이전트가 읽는 폴더는 그대로다.
 인스톨러를 `--force`와 함께 다시 실행할 것(없으면 손댔을지 모르는 SKILL.md 덮어쓰기를 거부한다):
 
@@ -26,7 +40,6 @@ npx mosaic-headless --list                   # 지원하는 8개 플랫폼
 npx mosaic-headless@latest claude-code --global --force
 ```
 
-Python 3와 Playwright는 도구를 *실행*할 때 필요하고, 설치에는 필요 없다.
 
 ## 이것은 무엇인가
 
@@ -37,6 +50,40 @@ Mosaic은 페이지를 **23개의 커스텀 테이블**에 보관한다. `post_c
 이 스킬은 그 모델의 지도 — 소스를 읽어 얻은 것이 아니라 실제 설치에 대해 측정한 것 — 에,
 모델을 통해 쓰고, 나온 것을 검증하고, Elementor에서 페이지를 들여오는 도구를 더한 것이다.
 
+## 부품이 맞물리는 방식
+
+```mermaid
+flowchart LR
+    subgraph measure["한 번만, 실제 사이트에 대해 측정"]
+        SRC[플러그인 소스] -->|extract_*.py| D[(data/*.csv)]
+        SW[sweep_*.py / probe_*.py] -->|commit·렌더·단언| D
+    end
+
+    subgraph write["당신이 만드는 모든 페이지"]
+        Q[mo.py] -->|답 하나, 측정 판정이 먼저| SPEC[페이지 spec]
+        EL[Elementor _elementor_data] -->|from_elementor.py| SPEC
+        SPEC -->|build_page.py가 깨질 것을 거부| REST[Mosaic REST: checkout·check·commit]
+        REST --> DB[(23 테이블)]
+        DB --> PAGE[전달된 페이지]
+    end
+
+    subgraph verify["commit을 믿지 않는다"]
+        PAGE --> V1[verify_rwd.py]
+        PAGE --> V2[verify_browser.py + 디자인 감사]
+        PAGE --> V3[verify_intro.py / verify_loop.py]
+        PAGE --> V4[verify_conversion.py]
+        V1 & V2 & V3 & V4 --> CSV[(검증 CSV)]
+        CSV --> GATE[check-release.mjs]
+    end
+
+    D --> Q
+    D --> SPEC
+```
+
+왼쪽에서 오른쪽으로: 표는 한 번만 측정해 동봉한다; 모든 페이지는 표를 통해 쓰이고 표가
+아니라고 하면 거부된다; 전달된 페이지를 읽어 되돌리고 그 결과가 릴리스 게이트가 검사하는
+표에 기록되기 전까지는 아무것도 믿지 않는다.
+
 ## 단 하나의 규칙
 
 **노드 타입, 프로퍼티 이름, 열거값, 스타일 키, Free/Pro 판단을 기억으로 쓰지 말 것.
@@ -107,6 +154,24 @@ commit 성공은 페이지가 동작한다는 증거가 아니고, 올바른 스
 `SKIPPED`, `NO_HOST`, `INCONCLUSIVE`는 결코 합격률에 섞지 않는다. 자기 사각지대를 성공으로
 세는 스윕이야말로 이 스킬이 반대하는 것이다.
 
+## 조회 한 번의 비용
+
+Mosaic 노드 타입이나 스타일 키가 실제로 무엇을 받는지 에이전트가 알아내는 방법은 셋. 같은
+여섯 과제를 tiktoken으로 측정(`tools/benchmark_tokens.py`, 직접 실행 가능):
+
+| 과제 | 소스 읽기 | 전체 표 로드 | `mo.py` 조회 |
+|---|---:|---:|---:|
+| 제목, 문단, 링크 버튼 배치 | 10,005 | 259,539 | **961** |
+| padding, 테두리, 둥근 모서리를 반응형으로 | 3,490 | 259,539 | **396** |
+| 아코디언이 쓸 만한지, 어떻게 중첩하는지 | 15,615 | 259,539 | **397** |
+| 실제로 컴파일되는 hover/focus 상태 찾기 | 3,619 | 259,539 | **1,054** |
+| 어떤 CSS를 내는 Mosaic 키 찾기 | 1,862 | 259,539 | **51** |
+| commit 전에 무엇이 위험한지 알기 | 63,172 | 259,539 | **288** |
+
+**소스 읽기보다 71–99.5%, 전체 표 로드보다 99.6% 이상 적은 토큰** — 게다가 여섯 중 넷은
+소스로는 애초에 답할 수 없다. "선언됨"과 "컴파일됨"은 다른 질문이고, 후자를 물은 것은
+스윕뿐이다. 표는 합쳐서 259,539 토큰; 절대 통째로 로드하지 말 것. `mo.py`가 쿼리다.
+
 ### 쓰기 전에 알아둘 결과
 
 **`group`에 속한 프로퍼티는 단독으로 설정하면 무효다.** 양방향 모두 정확: 그룹 밖 78개는
@@ -163,14 +228,13 @@ loop grid, 폼, 카운트다운, 서드파티 addon — 은 동적이라 될 노
 | `sweep_*.py` / `probe_*.py` | 표를 만든 계측기 그 자체 |
 | `bootstrap_probe_theme.php` / `mint_session.php` | 라이선스 없는 실험용 테마와 WP-CLI에서 만드는 REST 세션 |
 
-## 실제 예제, 라이브로
+## 실제 예제
 
-`sites/_moksa.py`는 테이블만으로 진짜 스튜디오 사이트를 구축하며 참조 구현으로 동봉된다.
-**https://mosaic.moksaweb.com/** 에 올라가 있다: 1,286 노드의 홈페이지에 이름 있는 view
-timeline으로 스크롤을 추적하는 조항 인덱스; 우키요에 판을 한 장씩 찍어내는 진입 시퀀스;
-구석에서 영원히 찍어내고 탭하면 확대되는 판; 그리고 UI 전체가 shortcode를 실행하는 하나의
-`code` 노드로 들어오는 WooCommerce [My Account](https://mosaic.moksaweb.com/my-account/)
-페이지. 자체 JavaScript는 어디에도 없다.
+`sites/_moksa.py`는 테이블만으로 진짜 스튜디오 사이트를 구축하며 참조 구현으로 동봉된다:
+1,286 노드의 홈페이지에 이름 있는 view timeline으로 스크롤을 추적하는 조항 인덱스; 우키요에
+판을 한 장씩 찍어내는 진입 시퀀스; 구석에서 영원히 찍어내고 탭하면 확대되는 판; 그리고 UI
+전체가 shortcode를 실행하는 하나의 `code` 노드로 들어오는 WooCommerce My Account 페이지.
+자체 JavaScript는 어디에도 없다. `data/`의 모든 검증 표는 이것에 대해 만들어졌다.
 
 ## 어디서 시작할까
 

package/README.md

@@ -19,6 +19,21 @@ npx mosaic-headless cursor --to ./my-project
 npx mosaic-headless --list                   # all eight platforms
 ```
 
+| platform | what is installed | where |
+|---|---|---|
+| Claude Code | full skill: SKILL.md + references/ + tools/ + data/ + sites/ | `~/.claude/skills/` or `./.claude/skills/` |
+| Codex CLI | full skill | `~/.codex/` |
+| Gemini CLI | full skill | `~/.gemini/` |
+| GitHub Copilot | full skill, plus a section appended to `copilot-instructions.md` | `./.github/` |
+| Cursor | one `.mdc` rule with the references embedded | `~/.cursor/rules/` |
+| Windsurf | one rule file with the references embedded | `./.devin/` |
+| Continue | one rule file with the references embedded | `~/.continue/` |
+| Claude.ai | a zip to upload as a project skill | wherever you save it |
+
+Every platform install is verified by the release gate against its template. The
+tools need Python 3 and Playwright to run; the rule-file platforms get the knowledge
+without the tools.
+
 **Updating does not happen on its own.** A new version on npm changes nothing in
 the folder your agent loads; re-run the installer with `--force` (without it, it
 refuses to overwrite a SKILL.md you may have edited):
@@ -27,7 +42,6 @@ refuses to overwrite a SKILL.md you may have edited):
 npx mosaic-headless@latest claude-code --global --force
 ```
 
-Python 3 and Playwright are needed to *run* the tools, not to install.
 
 ## What this is
 
@@ -40,6 +54,41 @@ This skill is the map of that model — measured against a live install rather t
 read off the source — plus the tools to write through it, check what came out, and
 bring pages in from Elementor.
 
+## How the pieces fit
+
+```mermaid
+flowchart LR
+    subgraph measure["measured once, against a live install"]
+        SRC[plugin source] -->|extract_*.py| D[(data/*.csv)]
+        SW[sweep_*.py / probe_*.py] -->|commit, render, assert| D
+    end
+
+    subgraph write["every page you build"]
+        Q[mo.py] -->|one answer, verdict first| SPEC[page spec]
+        EL[Elementor _elementor_data] -->|from_elementor.py| SPEC
+        SPEC -->|build_page.py refuses what breaks| REST[Mosaic REST: checkout, check, commit]
+        REST --> DB[(23 tables)]
+        DB --> PAGE[served page]
+    end
+
+    subgraph verify["never trust the commit"]
+        PAGE --> V1[verify_rwd.py]
+        PAGE --> V2[verify_browser.py + design audit]
+        PAGE --> V3[verify_intro.py / verify_loop.py]
+        PAGE --> V4[verify_conversion.py]
+        V1 & V2 & V3 & V4 --> CSV[(verification CSVs)]
+        CSV --> GATE[check-release.mjs]
+    end
+
+    D --> Q
+    D --> SPEC
+```
+
+Left to right: the tables are measured once and shipped; every page is written
+through them and refused when they say no; and nothing is believed until the
+delivered page has been read back and the result recorded in a table that the
+release gate checks.
+
 ## The one rule
 
 **Never write a node type, property name, enum value, style key or Free/Pro claim
@@ -114,6 +163,26 @@ factories, so Pro types register and render regardless.
 `SKIPPED`, `NO_HOST` and `INCONCLUSIVE` are never folded into a pass rate. A sweep
 that scores its own blind spots as successes is the thing this skill argues against.
 
+## What it costs to consult
+
+Three ways an agent can learn what a Mosaic node type or style key actually takes,
+priced on the same six tasks with tiktoken (`tools/benchmark_tokens.py`; run it
+yourself):
+
+| task | read the source | load every table | `mo.py` query |
+|---|---:|---:|---:|
+| place a heading, a paragraph and a linked button | 10,005 | 259,539 | **961** |
+| set padding, a border and a radius, responsively | 3,490 | 259,539 | **396** |
+| decide whether the accordion is usable, and how to nest it | 15,615 | 259,539 | **397** |
+| find which hover/focus states actually compile | 3,619 | 259,539 | **1,054** |
+| find which Mosaic key drives one CSS property | 1,862 | 259,539 | **51** |
+| know what is unsafe before committing anything | 63,172 | 259,539 | **288** |
+
+**71–99.5% fewer tokens than reading the source, 99.6%+ fewer than loading the
+tables** — and the source could not have answered four of the six at all, because
+"declared" and "compiles" are different questions and only the sweeps asked the
+second one. The tables total 259,539 tokens; never load them. `mo.py` is the query.
+
 ### Results worth knowing before you write anything
 
 **A property that belongs to a `group` is inert when set on its own.** Exact in both
@@ -174,15 +243,15 @@ and heading level — and it earned its place at once: it caught the converter l
 | `sweep_*.py` / `probe_*.py` | the instruments the tables were made with |
 | `bootstrap_probe_theme.php` / `mint_session.php` | a licence-free scratch theme and a REST session from WP-CLI |
 
-## The worked example, live
+## The worked example
 
 `sites/_moksa.py` builds a real studio site through the tables alone and ships as
-the reference. It is up at **https://mosaic.moksaweb.com/**: a homepage of 1,286
-nodes with a scroll-tracking clause index on named view timelines, an entrance
-sequence that prints an ukiyo-e sheet one carved block at a time, a corner plate
-that keeps printing forever and opens when tapped, and a WooCommerce
-[My Account](https://mosaic.moksaweb.com/my-account/) page whose UI arrives through
-one `code` node running a shortcode. No JavaScript of its own anywhere.
+the reference: a homepage of 1,286 nodes with a scroll-tracking clause index on named
+view timelines, an entrance sequence that prints an ukiyo-e sheet one carved block
+at a time, a corner plate that keeps printing forever and opens when tapped, and a
+WooCommerce My Account page whose UI arrives through one `code` node running a
+shortcode. No JavaScript of its own anywhere. Every verification table in `data/`
+was produced against it.
 
 ## Where to start
 

package/README.zh-TW.md

@@ -19,6 +19,20 @@ npx mosaic-headless cursor --to ./my-project
 npx mosaic-headless --list                   # 全部八個平台
 ```
 
+| 平台 | 裝什麼 | 裝到哪 |
+|---|---|---|
+| Claude Code | 完整技能：SKILL.md + references/ + tools/ + data/ + sites/ | `~/.claude/skills/` 或 `./.claude/skills/` |
+| Codex CLI | 完整技能 | `~/.codex/` |
+| Gemini CLI | 完整技能 | `~/.gemini/` |
+| GitHub Copilot | 完整技能，外加一段附到 `copilot-instructions.md` | `./.github/` |
+| Cursor | 一個內嵌 references 的 `.mdc` 規則檔 | `~/.cursor/rules/` |
+| Windsurf | 一個內嵌 references 的規則檔 | `./.devin/` |
+| Continue | 一個內嵌 references 的規則檔 | `~/.continue/` |
+| Claude.ai | 一個 zip，上傳為專案技能 | 你存的地方 |
+
+每個平台的安裝都由發布閘門對照其模板驗證。工具要跑需要 Python 3 和 Playwright；規則檔類的
+平台拿到的是知識，沒有工具。
+
 **更新不會自己發生。** npm 上有新版，不代表你的 agent 載入的那個資料夾有變；要重跑安裝器並加
 `--force`（不加的話它會拒絕覆蓋你可能改過的 SKILL.md）：
 
@@ -26,7 +40,6 @@ npx mosaic-headless --list                   # 全部八個平台
 npx mosaic-headless@latest claude-code --global --force
 ```
 
-Python 3 和 Playwright 是*跑工具*時才需要，安裝不用。
 
 ## 這是什麼
 
@@ -37,6 +50,39 @@ Mosaic 把一個頁面放在 **23 張自訂資料表**裡，不在 `post_content
 這個技能就是那個模型的地圖——對照真實站台量出來的，不是讀原始碼讀出來的——外加一組
 工具：透過模型寫入、檢查寫出來的東西、把 Elementor 的頁面搬進來。
 
+## 各部分怎麼接起來
+
+```mermaid
+flowchart LR
+    subgraph measure["量一次，對著真實站台"]
+        SRC[外掛原始碼] -->|extract_*.py| D[(data/*.csv)]
+        SW[sweep_*.py / probe_*.py] -->|寫入、渲染、斷言| D
+    end
+
+    subgraph write["你建的每一頁"]
+        Q[mo.py] -->|一個答案，量測結論在前| SPEC[頁面 spec]
+        EL[Elementor _elementor_data] -->|from_elementor.py| SPEC
+        SPEC -->|build_page.py 拒絕量到會壞的| REST[Mosaic REST：checkout、check、commit]
+        REST --> DB[(23 張表)]
+        DB --> PAGE[送出的頁面]
+    end
+
+    subgraph verify["永遠不信任 commit"]
+        PAGE --> V1[verify_rwd.py]
+        PAGE --> V2[verify_browser.py + 設計稽核]
+        PAGE --> V3[verify_intro.py / verify_loop.py]
+        PAGE --> V4[verify_conversion.py]
+        V1 & V2 & V3 & V4 --> CSV[(驗證表)]
+        CSV --> GATE[check-release.mjs]
+    end
+
+    D --> Q
+    D --> SPEC
+```
+
+由左到右：表格量一次、隨套件出貨；每一頁都透過表格寫入、表格說不行就拒絕；在送出的頁面被
+讀回來、結果記進發布閘門會檢查的表之前，什麼都不信。
+
 ## 唯一的規則
 
 **絕對不要憑記憶寫任何節點型別、屬性名稱、列舉值、樣式鍵或 Free/Pro 的判斷。去 `data/` 查。**
@@ -102,6 +148,24 @@ commit 成功不代表頁面能用，樣式表正確也不代表。這裡每個
 `SKIPPED`、`NO_HOST`、`INCONCLUSIVE` 從不折算進通過率。把自己的盲點算成成功的掃描，
 正是這個技能反對的東西。
 
+## 查一次要花多少
+
+agent 要知道一個 Mosaic 節點型別或樣式鍵到底吃什麼，有三條路。同樣六個任務，用 tiktoken
+算（`tools/benchmark_tokens.py`，可以自己跑）：
+
+| 任務 | 讀原始碼 | 整包表格載入 | `mo.py` 查詢 |
+|---|---:|---:|---:|
+| 放一個標題、一段文字、一顆帶連結的按鈕 | 10,005 | 259,539 | **961** |
+| 設定 padding、邊框、圓角，含響應式 | 3,490 | 259,539 | **396** |
+| 判斷 accordion 能不能用、怎麼嵌套 | 15,615 | 259,539 | **397** |
+| 找出哪些 hover/focus 狀態真的會編譯 | 3,619 | 259,539 | **1,054** |
+| 找出哪個 Mosaic 鍵驅動某條 CSS | 1,862 | 259,539 | **51** |
+| commit 之前知道什麼不安全 | 63,172 | 259,539 | **288** |
+
+**比讀原始碼省 71–99.5% 的 token，比整包載入省 99.6% 以上**——而且六題裡有四題原始碼根本
+答不了：「有宣告」和「會編譯」是兩個問題，只有掃描問了第二個。表格總共 259,539 tokens；
+永遠不要整包載入，`mo.py` 才是查詢。
+
 ### 動手前值得知道的結果
 
 **屬於某個 `group` 的屬性單獨設定時無效。** 兩個方向都精確：78 個未分組屬性給出 58 COMPILED、
@@ -154,13 +218,13 @@ button / html / icon-list / divider / image 佔了全部元素的 99.6%。長尾
 | `sweep_*.py` / `probe_*.py` | 那些表格是用這些儀器量出來的 |
 | `bootstrap_probe_theme.php` / `mint_session.php` | 免授權的實驗主題，以及從 WP-CLI 鑄出 REST session |
 
-## 線上的工作範例
+## 工作範例
 
-`sites/_moksa.py` 只透過資料表建出一個真實的工作室網站，隨套件出貨作為參考。它就在
-**https://mosaic.moksaweb.com/**：1,286 個節點的首頁，用具名 view timeline 做捲動追蹤的條款索引；
-一段一次印一塊版、把浮世繪印出來的入口動畫；一塊在角落永遠印下去、點了會放大的版子；
-還有一個 WooCommerce [My Account](https://mosaic.moksaweb.com/my-account/) 頁，它的 UI 全部
-透過一個跑 shortcode 的 `code` 節點進來。全程沒有自己寫任何 JavaScript。
+`sites/_moksa.py` 只透過資料表建出一個真實的工作室網站，隨套件出貨作為參考：1,286 個節點的
+首頁，用具名 view timeline 做捲動追蹤的條款索引；一段一次印一塊版、把浮世繪印出來的入口動畫；
+一塊在角落永遠印下去、點了會放大的版子；還有一個 WooCommerce My Account 頁，它的 UI 全部透過
+一個跑 shortcode 的 `code` 節點進來。全程沒有自己寫任何 JavaScript。`data/` 裡每一張驗證表
+都是對著它量出來的。
 
 ## 從哪裡開始
 

package/SKILL.md

@@ -4,7 +4,7 @@ description: |
   Build and modify Mosaic Pro (Nextend) sites by writing the underlying data model directly - no visual editor, no DOM. Query the real surface with `mo.py`, which joins every source table to the live sweeps so a lookup leads with the measured verdict rather than the declaration (122 node types, 181 properties, 98 style properties with 20 structured value shapes pinned down, 53 style states, 151 element classes, 74 dynamic variables, 12 interaction triggers, 114 REST routes, 23 tables) instead of guessing, with every node type placed on a live site one at a time and asserted against the delivered HTML, the design-token and element-class layers verified against compiled CSS, the @VAR() dynamic language verified against rendered output, nine designed pages built through the tables themselves, and the delivered pages re-read in Chromium at three viewports so a rule that is present, correct and still wrong cannot pass. Drives Mosaic's own theme export/import from outside the editor and holds the copy against the source tree for tree.
 license: "MIT"
 author: "moksa (https://moksaweb.com)"
-version: "1.17.1"
+version: "1.17.2"
 ---
 
 # Headless Mosaic
@@ -449,6 +449,7 @@ so the pattern is in the data, not just in this paragraph.
 | `data/accordion-verification.csv` | 7 | **driven live** - the accordion family nested the way its factory requires, against the guard that refuses it unparented. Resolves two BROKE_PAGE rows |
 | `data/conversion-verification.csv` | 8 | **converted then checked live** - an Elementor page rebuilt as Mosaic and held against its source (text, images, links, heading levels), then put through rwd, browser and the design audit with every finding classified inherited-or-introduced |
 | `data/conversion-batch.csv` | 19 | **converted, built and checked live, one page after another** - every Elementor page of a production site through the converter, with per-page element and content counts |
+| `data/token-benchmark.csv` | 6 | **measured with tiktoken** - the same six lookups priced three ways: reading the plugin source, loading every table, querying `mo.py`. 71-99.5% fewer tokens than the source and 99.6%+ fewer than the tables, which total 259,539 - never load them, query them |
 | `data/theme-zip-verification.csv` | 22 | **round-tripped live** - Mosaic's own ZIP export imported in test mode and compared to its source, table by table and tree by tree |
 | `data/node-type-notes.csv` | 8 | where a sweep outcome is true but misleading on its own, why. Surfaced by `mo.py type` |
 | `data/interaction-verification.csv` | 7 | **probed live** - interaction animation shapes, with negative controls and the stored row beside the payload |
@@ -622,6 +623,7 @@ post — `build_all.py` resets first for that reason.
 | tool | does |
 |---|---|
 | `mo.py` | query the measured surface - **the front door** |
+| `benchmark_tokens.py` | reproduce the token figures: source vs tables vs query, six tasks |
 | `build_page.py` | commit one page spec through the verified write path |
 | `build_site.py` | a whole site: one master with the shell, one document per page |
 | `verify_rwd.py` | does every `_t`/`_m` declaration reach the served stylesheet? |

package/assets/templates/platforms/claude-ai.json

@@ -20,7 +20,7 @@
     "description": "Build and modify Mosaic Pro (Nextend) sites by writing the underlying data model directly - no visual editor, no DOM. Query the real surface (122 node types, 181 node properties, 98 style properties, 53 style states, 151 element classes, 74 dynamic variables, 114 REST routes, 23 tables) instead of guessing, with every node type placed on a live site one at a time and asserted against the delivered HTML, every style and node property swept against the compiled CSS and markup, and 569 responsive declarations checked against the stylesheet the site actually served.",
     "license": "MIT",
     "author": "moksa (https://moksaweb.com)",
-    "version": "1.17.1"
+    "version": "1.17.2"
   },
   "loaderBehaviour": "Upload via Settings -> Skills -> Upload. Claude.ai parses SKILL.md frontmatter and surfaces the skill in your library. The extraction tool (extract-block-schema.php) needs a live WP-CLI connection and won't run in the sandbox; use it from a local terminal against your own site instead.",
   "uploadSteps": [

package/assets/templates/platforms/claude-code.json

@@ -20,7 +20,7 @@
     "description": "Build and modify Mosaic Pro (Nextend) sites by writing the underlying data model directly - no visual editor, no DOM. Query the real surface (122 node types, 181 node properties, 98 style properties, 53 style states, 151 element classes, 74 dynamic variables, 114 REST routes, 23 tables) instead of guessing, with every node type placed on a live site one at a time and asserted against the delivered HTML, every style and node property swept against the compiled CSS and markup, and 569 responsive declarations checked against the stylesheet the site actually served.",
     "license": "MIT",
     "author": "moksa (https://moksaweb.com)",
-    "version": "1.17.1"
+    "version": "1.17.2"
   },
   "loaderBehaviour": "Auto-loads on session start when SKILL.md frontmatter parses successfully.",
   "verified": true,

package/assets/templates/platforms/codex-cli.json

@@ -20,7 +20,7 @@
     "description": "Build and modify Mosaic Pro (Nextend) sites by writing the underlying data model directly - no visual editor, no DOM. Query the real surface (122 node types, 181 node properties, 98 style properties, 53 style states, 151 element classes, 74 dynamic variables, 114 REST routes, 23 tables) instead of guessing, with every node type placed on a live site one at a time and asserted against the delivered HTML, every style and node property swept against the compiled CSS and markup, and 569 responsive declarations checked against the stylesheet the site actually served.",
     "license": "MIT",
     "author": "moksa (https://moksaweb.com)",
-    "version": "1.17.1"
+    "version": "1.17.2"
   },
   "loaderBehaviour": "Confirmed (2026-07-11): Codex CLI natively supports the SKILL.md spec. Place SKILL.md under .codex/skills/<name>/ (project) or ~/.codex/skills/<name>/ (personal) and Codex loads the name+description at session start, then the full body on demand. A parallel, broader convention .agents/skills/ (searched from cwd up to repo root, then ~/.agents/skills/) also exists across multiple tools - if your Codex CLI version prioritizes that path instead, mirror the same SKILL.md there.",
   "verified": true,

package/assets/templates/platforms/copilot.json

@@ -20,7 +20,7 @@
     "description": "Build and modify Mosaic Pro (Nextend) sites by writing the underlying data model directly - no visual editor, no DOM. Query the real surface (122 node types, 181 node properties, 98 style properties, 53 style states, 151 element classes, 74 dynamic variables, 114 REST routes, 23 tables) instead of guessing, with every node type placed on a live site one at a time and asserted against the delivered HTML, every style and node property swept against the compiled CSS and markup, and 569 responsive declarations checked against the stylesheet the site actually served.",
     "license": "MIT",
     "author": "moksa (https://moksaweb.com)",
-    "version": "1.17.1"
+    "version": "1.17.2"
   },
   "loaderBehaviour": "CHANGED as of 2026-07-11: GitHub Copilot added a proper '.github/skills/' Agent Skills directory (December 2025), alongside the older single-file .github/copilot-instructions.md convention. This config targets the new skills-directory form. If your Copilot version predates this (pre Dec 2025), use the instructions-append fallback instead (see fallback below).",
   "fallback": {

package/assets/templates/platforms/gemini-cli.json

@@ -20,7 +20,7 @@
     "description": "Build and modify Mosaic Pro (Nextend) sites by writing the underlying data model directly - no visual editor, no DOM. Query the real surface (122 node types, 181 node properties, 98 style properties, 53 style states, 151 element classes, 74 dynamic variables, 114 REST routes, 23 tables) instead of guessing, with every node type placed on a live site one at a time and asserted against the delivered HTML, every style and node property swept against the compiled CSS and markup, and 569 responsive declarations checked against the stylesheet the site actually served.",
     "license": "MIT",
     "author": "moksa (https://moksaweb.com)",
-    "version": "1.17.1"
+    "version": "1.17.2"
   },
   "loaderBehaviour": "CHANGED as of 2026-07-11: Gemini CLI now natively supports the same SKILL.md standard as Claude Code and Codex CLI - the same directory-based skill works unmodified. Gemini CLI discovers skills in this precedence order: built-in, extension skills, ~/.gemini/skills/ (personal), .gemini/skills/ (project, shared via version control). At session start Gemini injects each discovered skill's name+description into the system prompt and calls activate_skill when a task matches.",
   "verified": true,

package/data/token-benchmark.csv

@@ -0,0 +1,7 @@
+task,commands,tokens_read_source,tokens_load_tables,tokens_query,saving_vs_source_pct,saving_vs_tables_pct
+"Place a heading, a paragraph and a linked button",mo.py params text ; mo.py params button ; mo.py prop url,10005,259539,961,90.4,99.63
+"Set padding, a border and a radius, responsively",mo.py style --grouped ; mo.py css border-left-width ; mo.py css border-radius,3490,259539,396,88.7,99.85
+"Decide whether the accordion is usable, and how to nest it",mo.py type accordion-content ; mo.py placement accordion-item,15615,259539,397,97.5,99.85
+Find which hover/focus states actually compile,mo.py states --verified,3619,259539,1054,70.9,99.59
+Find which Mosaic key drives one CSS property,mo.py css grid-column,1862,259539,51,97.3,99.98
+Know what is unsafe before committing anything,mo.py stats ; mo.py check div text button accordion-content,63172,259539,288,99.5,99.89

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mosaic-headless",
-  "version": "1.17.1",
+  "version": "1.17.2",
   "description": "AI-agent skill: build Mosaic Pro (Nextend) WordPress sites by writing the underlying data model directly - 23 custom tables, no visual editor, no DOM. Every node type, style property and node property swept against a live install and asserted on the delivered HTML and compiled CSS. Installs into Claude Code, Cursor, Codex CLI, Gemini CLI, Copilot, Continue, Windsurf and Claude.ai.",
   "keywords": [
     "wordpress",

package/tools/benchmark_tokens.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""benchmark_tokens.py - what this skill costs to consult, and what it saves.
+
+    pip install tiktoken
+    python tools/benchmark_tokens.py --mosaic-src ./mosaic --csv data/token-benchmark.csv
+
+Every token figure in the README comes from this script. Run it yourself.
+
+WHAT IS BEING COMPARED
+
+An agent about to write a Mosaic page needs, for the node types it is touching:
+which properties exist, what values they take, which style keys emit CSS, what may
+be nested where, and which of those claims survive contact with the compiler.
+Three ways to get that, priced on the same tasks:
+
+  A. READ THE SOURCE   open the plugin's PHP for the types and style records the
+                       task touches. Accurate about what is *declared*; silent
+                       about what is measured (a declared style key that emits
+                       nothing looks identical to one that works).
+  B. LOAD THE TABLES   put every data/*.csv in context. Complete, and wasteful:
+                       you pay for all of it to use one row.
+  C. QUERY             run tools/mo.py and read back only the answer, which
+                       leads with the measured verdict. This is what the skill
+                       does.
+
+HONESTY NOTES
+
+  - Token counts use tiktoken cl100k_base - OpenAI's tokenizer, not Claude's, so
+    absolute counts differ by roughly +-10% on Claude. The RATIOS are what matter,
+    and a ratio between two texts measured with the same tokenizer is stable.
+  - Baseline A counts exactly the files an agent would have to open to answer the
+    task from source: the node type's three files (factory, data, resource) plus
+    the style-property records and the validators those files lean on. Mosaic
+    spreads a type across a directory and its style surface across a hundred
+    small classes; the count is the files that hold the answer, not the whole
+    plugin - counting the whole plugin would flatter the skill.
+  - Baseline A also understates the real cost: source cannot answer "does this
+    compile?" at all, so the honest source-reading agent still has to commit and
+    render to find out. That round trip is not priced here.
+  - The mo.py outputs are captured by running the commands for real.
+  - Baseline B is charged once, not per task.
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+import glob
+import io
+import os
+import subprocess
+import sys
+
+try:
+    import tiktoken
+except ImportError:
+    sys.exit("pip install tiktoken")
+
+ENC = tiktoken.get_encoding("cl100k_base")
+HERE = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.dirname(HERE)
+
+
+def toks(text):
+    return len(ENC.encode(text, disallowed_special=()))
+
+
+def read_all(paths):
+    out = ""
+    for p in paths:
+        with io.open(p, encoding="utf-8", errors="replace") as fh:
+            out += fh.read()
+    return out
+
+
+def src(mosaic, *rel_globs):
+    paths = []
+    for g in rel_globs:
+        paths += glob.glob(os.path.join(mosaic, "Mosaic", g), recursive=True)
+    return sorted(set(p for p in paths if p.endswith(".php")))
+
+
+def run_mo(args):
+    r = subprocess.run([sys.executable, os.path.join(HERE, "mo.py")] + args,
+                       capture_output=True, text=True, encoding="utf-8", errors="replace",
+                       cwd=ROOT)
+    return r.stdout
+
+
+# task -> (mo.py commands, source globs that hold the declared answer)
+TASKS = [
+    ("Place a heading, a paragraph and a linked button",
+     [["params", "text"], ["params", "button"], ["prop", "url"]],
+     ["NodeTypes/Text/*.php", "NodeTypes/Button/*.php", "NodeTypes/Wysiwyg/**/*.php",
+      "Validators/Validate/ValidatorURL*.php", "Validators/Validate/ValidatorAcceptedValues.php"]),
+    ("Set padding, a border and a radius, responsively",
+     [["style", "--grouped"], ["css", "border-left-width"], ["css", "border-radius"]],
+     ["Builder/Style/BorderRadius/*.php", "Builder/Style/CSSGrouppedPropertyFactory.php",
+      "Builder/Style/CSSPropertyFactory.php", "Builder/Style/CSSProperty.php",
+      "Builder/Style/AbstractCSSProperty.php", "Builder/Breakpoint/*.php"]),
+    ("Decide whether the accordion is usable, and how to nest it",
+     [["type", "accordion-content"], ["placement", "accordion-item"]],
+     ["NodeTypes/Accordion/**/*.php", "NodeTypes/ElementAbstract/*.php"]),
+    ("Find which hover/focus states actually compile",
+     [["states", "--verified"]],
+     ["Builder/Style/StatesMeta.php", "Builder/Style/LocalStatesMeta.php",
+      "Builder/Style/CSS.php"]),
+    ("Find which Mosaic key drives one CSS property",
+     [["css", "grid-column"]],
+     ["Builder/Style/GridArea/*.php", "Builder/Style/GridTemplate/*.php",
+      "Builder/Style/CSSPropertyFactory.php"]),
+    ("Know what is unsafe before committing anything",
+     [["stats"], ["check", "div", "text", "button", "accordion-content"]],
+     ["NodeTypes/**/*TypeFactory.php"]),
+]
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--mosaic-src", help="path to the Mosaic plugin (for baseline A)")
+    ap.add_argument("--csv")
+    a = ap.parse_args()
+
+    tables = sorted(glob.glob(os.path.join(ROOT, "data", "*.csv")))
+    load_all = toks(read_all(tables))
+    print("baseline B - every table in data/ loaded at once: %s tokens (%d files)\n"
+          % (format(load_all, ","), len(tables)))
+
+    rows = []
+    print("%-58s %10s %10s %8s %8s" % ("task", "read src", "query", "vs src", "vs load"))
+    for label, cmds, globs in TASKS:
+        q = sum(toks(run_mo(c)) for c in cmds)
+        s = None
+        if a.mosaic_src:
+            files = src(a.mosaic_src, *globs)
+            s = toks(read_all(files)) if files else None
+        sv = (100.0 * (1 - q / s)) if s else None
+        lv = 100.0 * (1 - q / load_all)
+        print("%-58s %10s %10s %7s %7.2f%%" % (
+            label[:58], format(s, ",") if s else "-", format(q, ","),
+            "%.1f%%" % sv if sv is not None else "-", lv))
+        rows.append([label, " ; ".join("mo.py " + " ".join(c) for c in cmds),
+                     s or "", load_all, q, "%.1f" % sv if sv is not None else "",
+                     "%.2f" % lv])
+
+    if a.csv:
+        with open(a.csv, "w", newline="", encoding="utf-8") as fh:
+            w = csv.writer(fh)
+            w.writerow(["task", "commands", "tokens_read_source", "tokens_load_tables",
+                        "tokens_query", "saving_vs_source_pct", "saving_vs_tables_pct"])
+            w.writerows(rows)
+        print("\nwrote", a.csv)
+
+
+if __name__ == "__main__":
+    main()