mosaic-headless 1.17.1 → 1.18.0

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 の判断を記憶から書かない。
@@ -61,8 +109,8 @@ python tools/mo.py states --verified        # コンパイルされることが
 python tools/mo.py css grid-column          # この CSS を出す Mosaic のキー
 ```
 
-そのうえでページを見る。Mosaic には **7 つ**の失敗モードがあり、HTTP ステータスが変わるのは
-そのうち 2 つだけ：
+そのうえでページを見る。Mosaic には **8 つ**の失敗モードがあり、HTTP ステータスが変わるのは
+そのうち 3 つだけ：
 
 ```
 バリデータの正常な拒否       HTTP 200 + 本文に `exceptions` 配列
@@ -76,6 +124,11 @@ URL にテンプレートがない     HTTP 406、未ログインには空の本
                              `code` ノードの内容はテンプレートで、minifier が書く `@media(` は
                              関数呼び出しとして読まれる。`@media (` なら描画される。
                              build_page は前者を拒否する。
+プラグイン更新で出力が変わる HTTP 200、ページは無事、行も移行済み — だが出力クラスに対して
+                             書いた CSS が何にも当たらない。1.0.8 は `M_EL4 M_EL_Div` を
+                             `m-div _e` に、状態クラスも一緒に、`customStyles` を
+                             `customDeclarations` に改名した。例のタップ拡大が開かなくなり、
+                             それを言ったのは verify_loop.py だった。
 ```
 
 commit の成功はページが動く証拠ではないし、正しいスタイルシートもそうではない。ここの
@@ -84,20 +137,20 @@ commit の成功はページが動く証拠ではないし、正しいスタイ
 
 ## 何を、どう検証したか
 
-すべて実際のインストールに対して実行 — WordPress 7.1、WooCommerce 11.1、Mosaic Pro 1.0.7、
+すべて実際のインストールに対して実行 — WordPress 7.1、WooCommerce 11.1、Mosaic Pro 1.0.8、
 **ライセンスなし**：ライセンスが制限するのはテーマライブラリと更新であってノードファクトリ
 ではないので、Pro の型も登録・描画される。
 
 | 項目 | 結果 |
 |---|---|
-| **ノード型** | 122 / 122 を 1 型 1 ドキュメントでスイープ、commit → 描画 → 断言 → 削除：70 RENDERED、30 COMMITTED、15 COMMIT_5xx、7 BROKE_PAGE。描画されなかった行のうち 3 つは「必要な親なしで commit した」というスイープ手法の産物で、その旨が行の横にある |
+| **ノード型** | 122 / 122 を 1 型 1 ドキュメントでスイープ、commit → 描画 → 断言 → 削除：70 RENDERED、25 COMMITTED、15 COMMIT_5xx、12 BROKE_PAGE。1.0.8 で再スイープ：以前は黙って commit されていた 5 型が、親なしではページを落とすようになった。描画されなかった行のうち 3 つは「必要な親なしで commit した」というスイープ手法の産物で、その旨が行の横にある |
 | **スタイルプロパティ** | 98 / 98 を実ページに書き、コンパイル済み CSS と照合：58 COMPILED、18 ABSENT、21 SKIPPED |
-| **ノードプロパティ** | 181 / 181 を各プロパティ自身のバリデータ連鎖から導いた値で再探査：35 APPLIED、42 NO_EFFECT、55 NO_HOST、47 SKIPPED |
+| **ノードプロパティ** | 182 / 182 を各プロパティ自身のバリデータ連鎖から導いた値で再探査：35 APPLIED、43 NO_EFFECT、55 NO_HOST、47 SKIPPED |
 | **レスポンシブ** | 2 サイト計 731 件の `_t`/`_m` 宣言を、サイトが実際に配信したスタイルシートに対して 1 件ずつ断言 — 全件検証済み |
 | **ブラウザ** | 配信された 2 ページを Chromium の 3 つのビューポートで計算スタイル 3,988 件読み取り：2,929 件が一致、912 件は比較不能として明示、**上書き 0 件** |
 | **デザイン監査** | コントラスト、フォントフォールバック、CJK の字送り、横溢れ、テキストの切れ、1 行の文字数 — ブラウザ上で実行、**指摘 26 件、すべて理由付きで裁定済み** — 理由のない容認はリリースゲートが拒否する |
 | **コンポーネント** | コンポーネントシステムを端から端まで駆動、**8 件中 8 件**：カテゴリの下に作成、ドキュメントが自己修復、書き込み可能インスタンス経由でツリーを充填、読み取り専用インスタンスは同じ書き込みを拒否（ネガティブコントロール）、ページ上の 2 インスタンスが 1 つの定義を 2 度描画 |
-| **スタイル状態** | 53 状態のうち 52 を実ページに書き、表が約束するセレクタと照合：**36 が完全一致**、12 NO_HOST、3 SKIPPED、1 BROKE_PAGE。擬似クラスは大文字で出力される（`.M_EL9:HOVER`） |
+| **スタイル状態** | 53 状態のうち 52 を実ページに書き、表が約束するセレクタと照合：**36 が完全一致**、13 NO_HOST、3 SKIPPED、0 BROKE_PAGE。擬似クラスは大文字で出力される（`.M_EL9:HOVER`） |
 | **インタラクション** | JS アニメーション経路をネガティブコントロール付きで探査し行を読み戻し：`propertyMetas` **は**受理・保存される；プロパティ値は依然として結び付かず、その境界は正確になった |
 | **アコーディオン** | `accordion-item` と `accordion-content` はスイープ表では BROKE_PAGE。ファクトリが要求する通りに入れ子にすれば commit も描画も通る、**7 件中 7 件** |
 | **入場アニメーション** | 単調時計で 15 時点をサンプリングし 8 項目を断言。文書の初回レイアウトを待ってから始まるため、アニメーションの全くないページに対して遅れフレームは 1 つだけ |
@@ -105,20 +158,40 @@ commit の成功はページが動く証拠ではないし、正しいスタイ
 | **Elementor 変換** | 本番サイトの全 Elementor ページ — 19 ページ、3,292 要素 — を変換・構築し、元と照合：**19 件中 19 件**、3,281 要素を運び、11 要素を明示的に除外。さらに変換後ページをレスポンシブ・ブラウザ・監査にかけ、指摘をすべて「継承」か「導入」かに分類：**導入 0 件** |
 | **テーマの書き出し／読み込み** | 経路は二つ、どちらも往復検証済み。`theme_export.php` は WP-CLI で行を JSON として移し、id は不変。`theme_zip.py` は Mosaic **自身**の ZIP 書き出し／読み込みを駆動 — 読み込みは `--activate` を付けない限りテストモードに入る、既定がライブサイトの切り替えだからだ — **22 項目**でコピーを元とツリー単位で突き合わせる |
 | **スキル自身** | `claude plugin eval .` — ユーザーが実際に尋ねる 5 問を各 3 回、スキルあり／なしの 2 腕、1 回ごとに LLM 審査 3 名。**あり：5 問すべて 1.00。なし：5 問すべて 0.00。** ベースラインの最善の回答は回答拒否だった |
-| **ライブ計測** | REST ルート 114、element class 151、条件サブジェクト 59、23 テーブル / 206 カラム |
+| **ライブ計測** | REST ルート 114、variant 152、条件サブジェクト 59、23 テーブル / 210 カラム |
+| **ライブ更新** | 1.0.7 → 1.0.8 をプラグイン自身の milestone ルートで wp-admin の外から駆動：6 milestone、4 テーブル改名、出力クラス名は全部変わり、`customStyles` は全部書き換え — その結果に対して上の計測をすべて再実行 |
 
 `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 個は
 58 COMPILED・0 ABSENT、グループ内の 20 個はすべて 0 COMPILED。`borderLeftWidth`、`outlineColor`、
 `gridColumnStart` は一つのルールの三つの例。グループの形 — `border` は `{width, style, color}` —
-か `customStyles` を使う。
+か `customDeclarations` を使う。
 
 **ブレークポイントの上書きはプロパティを「変える」ことはできても「消す」ことはできない。**
-狭い画面の `customStyles` が単にボーダーを書かないだけなら、広い画面のボーダーは立ったままだ。
+狭い画面の `customDeclarations` が単にボーダーを書かないだけなら、広い画面のボーダーは立ったままだ。
 `border-left:0` と声に出す。
 
 **`url` を受け取る型は 4 つだけ**：`button`、`menu-link`、`wysiwyg-link`、`dropdown-toggle`。
@@ -164,17 +237,17 @@ loop grid、フォーム、カウントダウン、サードパーティ addon
 | `verify_intro.py` / `verify_loop.py` | 「終わる」ロードアニメーション；ループし、何も隠さず、開く常時アニメーション |
 | `theme_export.php` / `theme_import.php` | テーマ全体を JSON 行として WP-CLI で移動、id は不変 |
 | `theme_zip.py` / `theme_zip_compare.php` / `theme_delete.php` | Mosaic 自身の ZIP 書き出し／読み込みをエディタの外から駆動、コピーを元とツリー単位で照合、ライブテーマを拒否する完全削除 |
+| `data_upgrade.py` | プラグイン更新後、Mosaic のデータ移行を自身の milestone ルートで実行 — 終わるまでエディタ API は存在しない |
 | `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/` のすべての検証表はこれに対して作られた。
 
 ## どこから始めるか
 
@@ -183,7 +256,7 @@ loop grid、フォーム、カウントダウン、サードパーティ addon
 3. `references/failure-modes.md` — Mosaic の失敗のしかた、計測版。**書く前に読む。**
 4. `references/responsive.md` — 状態／ブレークポイント／プロパティの軸。
 5. `references/styling.md` — スタイル値が CSS になるまで。
-6. `references/design-system.md` — element class とデザイントークン。
+6. `references/design-system.md` — variant（element class）とデザイントークン。
 
 ## リリース
 

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 판단을 기억으로 쓰지 말 것.
@@ -58,8 +105,8 @@ python tools/mo.py states --verified        # 컴파일됨이 측정된 상태
 python tools/mo.py css grid-column          # 이 CSS를 내는 Mosaic 키
 ```
 
-그다음 페이지를 본다. Mosaic에는 **일곱 가지** 실패 모드가 있고, HTTP 상태 코드가 바뀌는 것은
-그중 둘뿐이다:
+그다음 페이지를 본다. Mosaic에는 **여덟 가지** 실패 모드가 있고, HTTP 상태 코드가 바뀌는 것은
+그중 셋뿐이다:
 
 ```
 검증기의 정상적 거부         HTTP 200 + 본문에 `exceptions` 배열
@@ -73,6 +120,11 @@ URL에 템플릿 없음            HTTP 406, 비로그인에게는 빈 본문
                              `code` 노드의 내용은 템플릿이라, minifier가 쓰는 `@media(`는
                              함수 호출로 읽힌다. `@media (`는 렌더링된다. build_page는
                              전자를 거부한다.
+플러그인 업그레이드가 출력을 바꿈 HTTP 200, 페이지 멀쩡, 행도 이관됨 — 그런데 출력 클래스를 겨냥해
+                             쓴 CSS가 아무것에도 안 맞는다. 1.0.8은 `M_EL4 M_EL_Div`를
+                             `m-div _e`로, 상태 클래스도 함께, `customStyles`를
+                             `customDeclarations`로 바꿨다. 예제의 탭 확대가 안 열리게 됐고,
+                             그걸 말해준 건 verify_loop.py였다.
 ```
 
 commit 성공은 페이지가 동작한다는 증거가 아니고, 올바른 스타일시트도 마찬가지다. 여기의 모든
@@ -81,20 +133,20 @@ commit 성공은 페이지가 동작한다는 증거가 아니고, 올바른 스
 
 ## 무엇을, 어떻게 검증했나
 
-전부 실제 설치에서 실행 — WordPress 7.1, WooCommerce 11.1, Mosaic Pro 1.0.7, **라이선스 없음**:
+전부 실제 설치에서 실행 — WordPress 7.1, WooCommerce 11.1, Mosaic Pro 1.0.8, **라이선스 없음**:
 라이선스가 막는 것은 테마 라이브러리와 업데이트지 노드 팩토리가 아니라서 Pro 타입도 등록되고
 렌더링된다.
 
 | 항목 | 결과 |
 |---|---|
-| **노드 타입** | 122 / 122를 문서당 하나씩 스윕, commit → 렌더 → 단언 → 삭제: 70 RENDERED, 30 COMMITTED, 15 COMMIT_5xx, 7 BROKE_PAGE. 렌더되지 않은 행 중 셋은 "필요한 부모 없이 commit"한 스윕 방식의 산물이며, 그 사실이 행 옆에 적혀 있다 |
+| **노드 타입** | 122 / 122를 문서당 하나씩 스윕, commit → 렌더 → 단언 → 삭제: 70 RENDERED, 25 COMMITTED, 15 COMMIT_5xx, 12 BROKE_PAGE. 1.0.8에서 재스윕: 전에는 조용히 commit되던 5개 타입이 부모 없이는 페이지를 죽인다. 렌더되지 않은 행 중 셋은 "필요한 부모 없이 commit"한 스윕 방식의 산물이며, 그 사실이 행 옆에 적혀 있다 |
 | **스타일 프로퍼티** | 98 / 98을 실제 페이지에 쓰고 컴파일된 CSS와 대조: 58 COMPILED, 18 ABSENT, 21 SKIPPED |
-| **노드 프로퍼티** | 181 / 181을 각 프로퍼티 자신의 검증기 체인에서 도출한 값으로 재탐사: 35 APPLIED, 42 NO_EFFECT, 55 NO_HOST, 47 SKIPPED |
+| **노드 프로퍼티** | 182 / 182을 각 프로퍼티 자신의 검증기 체인에서 도출한 값으로 재탐사: 35 APPLIED, 43 NO_EFFECT, 55 NO_HOST, 47 SKIPPED |
 | **반응형** | 두 사이트 합쳐 731개의 `_t`/`_m` 선언을, 사이트가 실제로 내보낸 스타일시트에 대해 하나씩 단언 — 전부 검증됨 |
 | **브라우저** | 전달된 두 페이지를 Chromium의 세 가지 뷰포트에서 계산 스타일 3,988건 판독: 2,929건 일치, 912건은 비교 불가로 명시, **덮어쓰기 0건** |
 | **디자인 감사** | 명암비, 폰트 폴백, CJK 자간, 가로 넘침, 텍스트 잘림, 한 줄 글자 수 — 브라우저에서 실행, **지적 26건, 모두 서면으로 판정** — 이유 없는 승인은 릴리스 게이트가 거부한다 |
 | **컴포넌트** | 컴포넌트 시스템을 끝에서 끝까지 구동, **8건 중 8건**: 카테고리 아래 생성, 문서 자가 치유, 쓰기 가능 인스턴스로 트리 채움, 읽기 전용 인스턴스는 같은 쓰기를 거부(네거티브 컨트롤), 페이지의 두 인스턴스가 하나의 정의를 두 번 렌더 |
-| **스타일 상태** | 53개 상태 중 52개를 실제 페이지에 쓰고 표가 약속한 셀렉터와 대조: **36개 정확히 일치**, 12 NO_HOST, 3 SKIPPED, 1 BROKE_PAGE. 의사 클래스는 대문자로 출력된다(`.M_EL9:HOVER`) |
+| **스타일 상태** | 53개 상태 중 52개를 실제 페이지에 쓰고 표가 약속한 셀렉터와 대조: **36개 정확히 일치**, 13 NO_HOST, 3 SKIPPED, 0 BROKE_PAGE. 의사 클래스는 대문자로 출력된다(`.M_EL9:HOVER`) |
 | **인터랙션** | JS 애니메이션 경로를 네거티브 컨트롤과 함께 탐사하고 행을 읽어 되돌림: `propertyMetas`**는** 수락·저장된다; 프로퍼티 값은 여전히 바인딩되지 않으며, 그 경계는 이제 정확하다 |
 | **아코디언** | `accordion-item`과 `accordion-content`는 스윕 표에서 BROKE_PAGE. 팩토리가 요구하는 대로 중첩하면 commit과 렌더링이 되며, **7건 중 7건** |
 | **인트로 애니메이션** | 단조 시계로 15개 시점을 샘플링해 8가지를 단언. 문서의 첫 레이아웃을 기다린 뒤 시작하므로, 애니메이션이 전혀 없는 페이지 대비 늦은 프레임은 하나뿐 |
@@ -102,20 +154,39 @@ commit 성공은 페이지가 동작한다는 증거가 아니고, 올바른 스
 | **Elementor 변환** | 운영 사이트의 모든 Elementor 페이지 — 19페이지, 3,292 요소 — 를 변환·구축하고 원본과 대조: **19건 중 19건**, 3,281 요소 이전, 11 요소 명시적 제외. 이어 변환된 페이지를 반응형·브라우저·감사에 통과시키고 모든 지적을 "상속"과 "도입"으로 분류: **도입 0건** |
 | **테마 내보내기/가져오기** | 두 경로, 모두 왕복 검증. `theme_export.php`는 WP-CLI로 행을 JSON으로 옮기며 id는 그대로. `theme_zip.py`는 Mosaic **자체**의 ZIP 내보내기/가져오기를 구동 — 가져오기는 `--activate`가 없으면 테스트 모드에 놓이는데, 기본값이 라이브 사이트 전환이기 때문이다 — **22개 검사**로 사본을 원본과 트리 단위로 대조 |
 | **스킬 자체** | `claude plugin eval .` — 사용자가 실제로 묻는 5문항을 각 3회, 스킬 있음/없음 두 팔로, 매회 LLM 심사 3명. **있음: 5문항 모두 1.00. 없음: 5문항 모두 0.00.** 베이스라인의 최선은 답변 거부였다 |
-| **라이브 측정** | REST 라우트 114, element class 151, 조건 subject 59, 23 테이블 / 206 컬럼 |
+| **라이브 측정** | REST 라우트 114, variant 152, 조건 subject 59, 23 테이블 / 210 컬럼 |
+| **라이브 업그레이드** | 1.0.7 → 1.0.8을 플러그인 자체 milestone 라우트로 wp-admin 밖에서 구동: 6 milestone, 테이블 4개 이름 변경, 출력 클래스 이름 전부 변경, `customStyles` 전부 재작성 — 그 결과 위에서 위의 측정을 전부 다시 실행 |
 
 `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개는
 58 COMPILED·0 ABSENT, 그룹 안 20개는 모두 0 COMPILED. `borderLeftWidth`, `outlineColor`,
 `gridColumnStart`는 한 규칙의 세 사례다. 그룹 형태 — `border`는 `{width, style, color}` — 나
-`customStyles`를 쓸 것.
+`customDeclarations`를 쓸 것.
 
 **브레이크포인트 오버라이드는 프로퍼티를 "바꿀" 수는 있어도 "지울" 수는 없다.** 좁은 화면의
-`customStyles`가 테두리를 그저 언급하지 않으면, 넓은 화면의 테두리는 그대로 서 있다.
+`customDeclarations`가 테두리를 그저 언급하지 않으면, 넓은 화면의 테두리는 그대로 서 있다.
 `border-left:0`을 소리 내어 말할 것.
 
 **`url`을 받는 타입은 넷뿐**: `button`, `menu-link`, `wysiwyg-link`, `dropdown-toggle`.
@@ -160,17 +231,17 @@ loop grid, 폼, 카운트다운, 서드파티 addon — 은 동적이라 될 노
 | `verify_intro.py` / `verify_loop.py` | "끝나는" 로드 애니메이션; 루프하고, 아무것도 가리지 않고, 열리는 상시 애니메이션 |
 | `theme_export.php` / `theme_import.php` | 테마 전체를 JSON 행으로 WP-CLI를 통해 이동, id 그대로 |
 | `theme_zip.py` / `theme_zip_compare.php` / `theme_delete.php` | Mosaic 자체 ZIP 내보내기/가져오기를 에디터 밖에서 구동, 사본을 원본과 트리 단위로 대조, 라이브 테마를 거부하는 깨끗한 삭제 |
+| `data_upgrade.py` | 플러그인 업데이트 후 Mosaic의 데이터 이관을 자체 milestone 라우트로 실행 — 끝나기 전까지 에디터 API는 존재하지 않는다 |
 | `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/`의 모든 검증 표는 이것에 대해 만들어졌다.
 
 ## 어디서 시작할까
 
@@ -179,7 +250,7 @@ timeline으로 스크롤을 추적하는 조항 인덱스; 우키요에 판을
 3. `references/failure-modes.md` — Mosaic이 실패하는 방식, 측정판. **쓰기 전에 읽을 것.**
 4. `references/responsive.md` — 상태/브레이크포인트/프로퍼티 축.
 5. `references/styling.md` — 스타일 값이 CSS가 되기까지.
-6. `references/design-system.md` — element class와 디자인 토큰.
+6. `references/design-system.md` — variant(element class)와 디자인 토큰.
 
 ## 릴리스
 

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
@@ -62,7 +111,7 @@ python tools/mo.py states --verified        # the states measured to compile
 python tools/mo.py css grid-column          # which Mosaic key drives this CSS
 ```
 
-Then check the page. Mosaic has **seven** failure modes and only two of them change
+Then check the page. Mosaic has **eight** failure modes and only three of them change
 the HTTP status code:
 
 ```
@@ -79,6 +128,11 @@ CONTENT                     Mosaic parses it. A `code` node's content is a templ
                             `@media(` as every minifier writes it is read as a
                             function call. `@media (` renders. build_page refuses
                             the former.
+plugin upgrade renamed      HTTP 200, page intact, rows migrated - and CSS you wrote
+what the page emits         against an emitted class matches nothing. 1.0.8 turned
+                            `M_EL4 M_EL_Div` into `m-div _e`, state classes with it,
+                            `customStyles` into `customDeclarations`. The example's
+                            tap-to-enlarge stopped opening; verify_loop.py said so.
 ```
 
 A successful commit is not evidence of a working page, and neither is a correct
@@ -89,19 +143,19 @@ than any naive healthy-page floor.
 ## What was verified, and how
 
 Everything ran against a live install — WordPress 7.1, WooCommerce 11.1, Mosaic Pro
-1.0.7, **unlicensed**: the licence gates the theme library and updates, not the node
+1.0.8, **unlicensed**: the licence gates the theme library and updates, not the node
 factories, so Pro types register and render regardless.
 
 | pass | result |
 |---|---|
-| **node types** | 122 / 122 swept one per document, committed → rendered → asserted → deleted: 70 RENDERED, 30 COMMITTED, 15 COMMIT_5xx, 7 BROKE_PAGE. Three of the non-rendering rows are artefacts of committing without the required parent, and say so beside the row |
+| **node types** | 122 / 122 swept one per document, committed → rendered → asserted → deleted: 70 RENDERED, 25 COMMITTED, 15 COMMIT_5xx, 12 BROKE_PAGE. Re-swept on 1.0.8: five types that used to commit silently now kill the page unparented. The non-rendering rows that are artefacts of committing without the required parent say so beside the row |
 | **style properties** | 98 / 98 written to a live page and checked against the compiled CSS: 58 COMPILED, 18 ABSENT, 21 SKIPPED |
-| **node properties** | 181 / 181 re-probed with a value shaped by each property's own validator chain: 35 APPLIED, 42 NO_EFFECT, 55 NO_HOST, 47 SKIPPED |
+| **node properties** | 182 / 182 re-probed with a value shaped by each property's own validator chain: 35 APPLIED, 43 NO_EFFECT, 55 NO_HOST, 47 SKIPPED |
 | **responsive** | 731 `_t`/`_m` declarations across two sites asserted against the stylesheet the site actually served — all verified |
 | **browser** | 3,988 computed-style readings on two delivered pages in Chromium at three viewports: 2,929 compared and agreed, 912 not-comparable and labelled, **0 overridden** |
 | **design audit** | contrast, font fallback, CJK tracking, overflow, clipped text, line measure — run in the browser, **26 findings, every one ruled on in writing** — an acknowledgement without a reason is refused by the release gate |
 | **components** | the component system driven end to end, **8 of 8**: created under a category, document healed, tree filled through the writable instance, the read-only one refused the same write as a negative control, two instances on a page rendering one definition twice |
-| **style states** | 52 of the 53 states written to a live page and matched against the selector the table promises: **36 compiled exactly**, 12 NO_HOST, 3 SKIPPED, 1 BROKE_PAGE. Pseudo-classes are emitted UPPERCASE (`.M_EL9:HOVER`) |
+| **style states** | 52 of the 53 states written to a live page and matched against the selector the table promises: **36 compiled exactly**, 13 NO_HOST, 3 SKIPPED, 0 BROKE_PAGE. Pseudo-classes are emitted UPPERCASE (`.M_EL9:HOVER`) |
 | **interactions** | the JS animation path probed with negative controls and the row read back: `propertyMetas` **is** accepted and stored; the property values still do not bind, and the boundary is now exact |
 | **accordion** | `accordion-item` and `accordion-content` sit in the sweep table as BROKE_PAGE; nested as their factory requires they commit and render, **7 of 7** |
 | **entrance animation** | the page-load sequence sampled at fifteen timestamps on a monotonic clock and asserted on eight counts. Costs one late frame over a page with no animation at all, because it waits for the document's first layout |
@@ -109,21 +163,42 @@ factories, so Pro types register and render regardless.
 | **Elementor conversion** | every Elementor page of a production site — 19 pages, 3,292 elements — converted, built and checked against its source: **19 of 19**, 3,281 elements carried, 11 declared. Then the converted page through rwd, browser and the audit, with every finding classified inherited-or-introduced: **0 introduced** |
 | **theme export/import** | two paths, both round-tripped. `theme_export.php` moves rows as JSON over WP-CLI, ids intact. `theme_zip.py` drives Mosaic's **own** ZIP export/import — import lands in test mode unless told `--activate`, because the default is to switch the live site — and **22 checks** hold the copy against the source tree for tree |
 | **the skill itself** | `claude plugin eval .` — five cases a user would ask, three runs each, with and without the skill loaded, three LLM judges a run. **With: 1.00 on all five. Without: 0.00 on all five.** The baseline's best answer was to refuse |
-| **measured live** | 114 REST routes, 151 element classes, 59 condition subjects, 23 tables / 206 columns |
+| **measured live** | 114 REST routes, 152 variants, 59 condition subjects, 23 tables / 210 columns |
+| **upgraded live** | 1.0.7 -> 1.0.8 over the plugin's own milestone route, from outside wp-admin: 6 milestones, four tables renamed, every emitted class name changed, every `customStyles` rewritten - then every sweep above re-run on the result |
 
 `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
 directions: 78 ungrouped properties gave 58 COMPILED and 0 ABSENT; all 20 grouped
 ones gave 0 COMPILED. So `borderLeftWidth`, `outlineColor` and `gridColumnStart` are
 three instances of one rule, not three oddities. Use the grouped shape — `border`
-takes `{width, style, color}` — or `customStyles`.
+takes `{width, style, color}` — or `customDeclarations`.
 
 **A breakpoint override can CHANGE a property but never REMOVE one.** Narrow-screen
-`customStyles` that merely omits a border leaves the wide-screen border standing.
+`customDeclarations` that merely omits a border leaves the wide-screen border standing.
 Say `border-left:0` out loud.
 
 **Only four types take a `url`**: `button`, `menu-link`, `wysiwyg-link`,
@@ -171,18 +246,19 @@ and heading level — and it earned its place at once: it caught the converter l
 | `verify_intro.py` / `verify_loop.py` | a page-load sequence that ENDS; a perpetual one that loops, hides nothing, and opens |
 | `theme_export.php` / `theme_import.php` | a whole theme as JSON rows over WP-CLI, ids intact |
 | `theme_zip.py` / `theme_zip_compare.php` / `theme_delete.php` | Mosaic's own ZIP export/import from outside the editor, the copy held against the source, and a clean delete that refuses the live theme |
+| `data_upgrade.py` | after a plugin update, Mosaic's data migration over its own milestone route - the editor API is gone until it runs |
 | `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
 
@@ -191,7 +267,7 @@ one `code` node running a shortcode. No JavaScript of its own anywhere.
 3. `references/failure-modes.md` — how Mosaic fails, measured. **Read before writing.**
 4. `references/responsive.md` — the state/breakpoint/property axis.
 5. `references/styling.md` — how a style value becomes CSS.
-6. `references/design-system.md` — element classes and design tokens.
+6. `references/design-system.md` — variants (element classes) and design tokens.
 
 ## Releasing