初期検討段階のドキュメントと運用ルールを取り込む

ルール策定前に書かれた設計ドキュメント7点を、以降の基準点として
そのままの状態で記録する。CLAUDE.md のルール1〜4は未適用。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MdLT5x5ka5y6CaWLeE3EKb

.claude/skills/decide/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: decide
+description: 設計上の決定を記録する。メインドキュメントの更新・検討済み案の記録・journal作成・コミットを一度に行う。
+disable-model-invocation: true
+argument-hint: [決定の要旨]
+---
+
+# 決定を記録する
+
+CLAUDE.md のルール1〜4に従い、決定を4箇所に分散して記録する。
+どれか1つでも欠けると後から追えなくなるので、全部やる。
+
+## 手順
+
+### 0. 決定内容を確認する
+
+以下が揃っているか確認し、足りなければユーザーに聞く。推測で埋めない。
+
+- 採用した案は何か
+- それによって**今後効く制約**は何か(却下理由ではなく、現在の状態として書ける文)
+- 落とした案があるか
+- この決定が未確認の推測に依存していないか
+
+### 1. メインドキュメントを更新する
+
+該当する直下の `*.md` を更新する。
+
+- 採用した案・現在の設定を書く。「なぜAなのか」は1〜3行まで。
+- 「なぜBではないのか」は書かない。代わりに**制約文**として書く。
+  - ✗ `B案はKLEパーサーが壊れるので却下した`
+  - ○ `クラスター情報はKLE JSONに出力しない(KLE互換性の制約)`
+- 比較表・検討過程・ベンチマーク結果をここに書かない。
+
+### 2. 落とした案を1行残す
+
+メインドキュメント末尾の `## 検討済み・非採用` に追記する。
+
+```
+- labels[9] へのID埋め込み (journal/2026-09-16-cluster-metadata.md)
+```
+
+- 理由は書かない。journalファイル名だけ。
+- セクションが5行を超えたら、古いものから落とす。長くなるのは書きすぎのサイン。
+
+### 3. journal を書く
+
+`journal/YYYY-MM-DD-<topic>.md` を作る。トピックを詰め込まない(1決定1ファイル)。
+
+構成は上から順に:
+
+1. **結論** — 何を採用したか
+2. **案の比較** — 簡潔な表。メリット/デメリットを1行ずつ
+3. 検証ログ・根拠・捨てた案の詳細
+
+冒頭20行で結論と選択肢が分かること。整形は最低限でよい。
+他ファイルへのリンクも、他ファイルからのリンクも張らない。
+
+### 4. 推測を扱う
+
+この決定が未確認の推測に依存する場合:
+
+- メインドキュメント本文に `[推測:P-n]` を付ける
+- 末尾の `## 未確認事項` に項目を足し、**何を確認できれば事実に格上げできるか**を書く
+
+逆に、この決定で検証が済んだ推測があれば、タグを外して `## 未確認事項` から削除する。
+本文タグと末尾項目は必ず対で操作する(片方だけ残さない)。
+
+### 5. コミットする
+
+メインドキュメントと journal を**同じコミット**に入れる。1コミット1決定。
+
+メッセージ:
+
+```
+<何を変えたか(1行)>
+
+<なぜそうしたか 数行>
+
+Journal: journal/2026-09-16-cluster-metadata.md
+```
+
+「なぜ」の詳細はコミットメッセージに書ききらない。journal 側にある。
+
+## 注意
+
+- 決定が固まっていない段階では使わない。調査中は journal だけ書けばよい。
+- 複数の決定をまとめてコミットしない。分ける。

.claude/skills/doc-lint/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: doc-lint
+description: ドキュメントがCLAUDE.mdの運用ルール1〜4に沿っているか検査する。推測タグと未確認事項の対応漏れ、journalへのリンク、比較表の混入などを検出する。
+argument-hint: [ファイル...]
+---
+
+# ドキュメントのルール違反を検査する
+
+機械的に判定できる項目はスクリプトで検出し、判断が要る項目だけ目視で見る。
+**検出して報告するだけで、勝手に直さない。** 修正は内容を確認してもらってから。
+
+## 1. スクリプトを走らせる
+
+```
+python .claude/skills/doc-lint/doc-lint.py [ファイル...]
+```
+
+引数なしで直下の `*.md` と `journal/*.md` を全部見る。ERROR があれば終了コード 1。
+
+検出する項目:
+
+| 種別 | 内容 |
+|---|---|
+| ERROR | 本文の `[推測:P-n]` に対応する `## 未確認事項` の項目がない |
+| ERROR | `## 未確認事項` の項目に `- 格上げ条件:` の行がない |
+| ERROR | `## 未確認事項` のIDが重複している |
+| ERROR | journal へのリンク / journal から他ファイルへのリンク |
+| ERROR | `## 検討済み・非採用` の項目が journal ファイル名を参照していない |
+| ERROR | journal のファイル名が `YYYY-MM-DD-<topic>.md` 形式でない |
+| WARN | `## 検討済み・非採用` が5件を超えた |
+| WARN | journal の冒頭20行に結論が見当たらない |
+| WARN | メインドキュメントに比較表・優先度評価・却下案の記述らしきもの |
+
+**本文タグのない `## 未確認事項` の項目はエラーにしない。** 「まだ本文に書けない未解決の問い」として正当。
+
+WARN の散文検出は当たりが粗い。取りこぼしも誤検出もあるので、出た/出ないを結論にしない。
+
+## 2. スクリプトで見られない項目を確認する
+
+こちらが本体。ファイルを読んで判断する。
+
+- **「なぜBではないのか」が理由として残っていないか。**
+  却下理由ではなく、現在効いている制約として書かれているか。
+  - ✗ `階層構造はKLEが非対応なので諦めた`
+  - ○ `階層クラスターはKLE JSONに出力しない(KLE互換性の制約)`
+- **裏取りしていない記述にタグが付いていないか。** 検査項目の中で最も重要で、
+  機械では判定できない。「〜できるはず」「〜と考えられる」「実現可能」で実際に試していない
+  記述を探し、`[推測:P-n]` が付いているか確認する。
+- **同じ事実が複数ドキュメントに複製されていないか。** 片方だけ古くなる。
+- **journal の冒頭20行で、結論と選択肢が分かるか。** 見出しの有無ではなく中身を読む。
+- **コミット規約**(必要なら `git log --oneline` を見る)
+  - 1コミット1決定になっているか
+  - journal を伴う決定のメッセージに `Journal:` 行があるか
+
+## 3. 報告する
+
+ERROR / WARN / 目視で見つけたもの を分けて出す。
+修正案は出してよいが、適用は確認を取ってから。事実関係の誤りを見つけた場合も、直さず指摘する。
+
+## 注意
+
+- 運用ルール策定前に書かれた既存ドキュメントは、まだルール1〜4が適用されていない。
+  WARN が大量に出るのは想定内で、再編(`/restructure-doc`)のタイミングで解消する。
+  再編前のファイルの WARN を個別に直そうとしない。

.claude/skills/doc-lint/doc-lint.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""CLAUDE.md の運用ルール1〜4のうち、機械的に判定できる項目を検査する。
+
+使い方:
+    python .claude/skills/doc-lint/doc-lint.py [ファイル...]
+引数なしなら リポジトリ直下の *.md と journal/*.md を対象にする。
+ERROR が1件でもあれば終了コード 1。
+"""
+import sys, re, os, io, glob
+
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+
+TAG      = re.compile(r"\[推測:(P-\d+)\]")
+ENTRY    = re.compile(r"^###\s+(P-\d+)\b")
+H2       = re.compile(r"^##\s+(.*?)\s*$")
+MDLINK   = re.compile(r"\]\(([^)]+\.md[^)]*)\)")
+JOURNALFN= re.compile(r"^\d{4}-\d{2}-\d{2}-.+\.md$")
+PROMOTE  = re.compile(r"^\s*[-*]\s*格上げ条件\s*[:：]\s*\S")
+
+# ルールブック自身は、アンチパターンを例として引用するため散文ヒューリスティックの対象外
+PROSE_EXEMPT = {"CLAUDE.md"}
+
+issues = []
+def add(sev, path, line, msg):
+    issues.append((sev, path, line, msg))
+
+def load(path):
+    """コードフェンス内を空行に潰した (行番号, 本文) の列を返す。"""
+    raw = io.open(path, encoding="utf-8").read().splitlines()
+    out, fence = [], False
+    for i, l in enumerate(raw, 1):
+        if l.lstrip().startswith("```"):
+            fence = not fence
+            out.append((i, ""))
+            continue
+        out.append((i, "" if fence else l))
+    return out
+
+def section(lines, title):
+    """## <title> 配下の (行番号, 本文) を返す。無ければ None。"""
+    start = None
+    for idx, (n, l) in enumerate(lines):
+        m = H2.match(l)
+        if m and m.group(1) == title:
+            start = idx + 1
+            break
+    if start is None:
+        return None
+    body = []
+    for n, l in lines[start:]:
+        if H2.match(l):
+            break
+        body.append((n, l))
+    return body
+
+def check(path):
+    rel = path.replace(os.sep, "/")
+    base = os.path.basename(rel)
+    is_journal = rel.startswith("journal/")
+    lines = load(path)
+
+    unconf = section(lines, "未確認事項")
+    rejected = section(lines, "検討済み・非採用")
+    unconf_span = set(n for n, _ in unconf) if unconf else set()
+
+    # --- ルール4: 推測タグと未確認事項の対応 ---
+    entries = set()
+    if unconf is not None:
+        blocks = []          # [(pid, 行番号, [本文行])] 重複IDも個別に検査する
+        for n, l in unconf:
+            m = ENTRY.match(l)
+            if m:
+                pid = m.group(1)
+                if pid in entries:
+                    add("ERROR", rel, n, "未確認事項のID %s が重複している" % pid)
+                entries.add(pid)
+                blocks.append((pid, n, []))
+            elif blocks:
+                blocks[-1][2].append(l)
+        for pid, ln, body in blocks:
+            if not any(PROMOTE.match(x) for x in body):
+                add("ERROR", rel, ln,
+                    "%s に「- 格上げ条件:」の行がない(何を確認すれば事実に格上げできるか)" % pid)
+
+    for n, l in lines:
+        if n in unconf_span:
+            continue
+        for pid in TAG.findall(l):
+            if unconf is None or pid not in entries:
+                add("ERROR", rel, n,
+                    "本文の [推測:%s] に対応する項目が ## 未確認事項 にない" % pid)
+    # 逆向き(本文タグのない未確認事項)は「未解決の問い」として正当なのでエラーにしない
+
+    # --- ルール3: journal への/からのリンク禁止 ---
+    for n, l in lines:
+        for target in MDLINK.findall(l):
+            if target.lstrip("./").startswith("journal/"):
+                add("ERROR", rel, n, "journal へのリンクが張られている: %s" % target)
+            elif is_journal:
+                add("ERROR", rel, n, "journal から他ファイルへのリンクが張られている: %s" % target)
+
+    # --- ルール1: 検討済み・非採用 ---
+    if rejected is not None:
+        items = [(n, l) for n, l in rejected if l.strip().startswith(("-", "*"))]
+        for n, l in items:
+            if not re.search(r"\(journal/[^)]+\.md\)", l):
+                add("ERROR", rel, n,
+                    "検討済み・非採用の項目が journal ファイル名を参照していない")
+        if len(items) > 5:
+            add("WARN", rel, items[5][0],
+                "検討済み・非採用が %d 件(目安5件)。古いものから落とす" % len(items))
+
+    # --- journal 固有 ---
+    if is_journal:
+        if not JOURNALFN.match(base):
+            add("ERROR", rel, 1, "journal のファイル名が YYYY-MM-DD-<topic>.md 形式でない")
+        head = " ".join(l for n, l in lines[:20])
+        if "結論" not in head:
+            add("WARN", rel, 1, "冒頭20行に結論が見当たらない(結論を先頭に置く)")
+
+    # --- ルール1: 調査・比較の混入(要目視確認) ---
+    if not is_journal and base not in PROSE_EXEMPT:
+        # 検討済み・非採用 は却下案を列挙する場所なので対象外
+        skip = set(n for n, _ in rejected) if rejected else set()
+        for n, l in lines:
+            if n in skip:
+                continue
+            if "メリット" in l and "デメリット" in l:
+                add("WARN", rel, n, "比較表らしき記述(メリット/デメリット)。journal 行きでは?")
+            elif re.search(r"却下|不採用|見送っ|も検討したが|案[A-Z]|[A-Z]案", l):
+                add("WARN", rel, n, "却下案の検討過程らしき記述。制約文に書き換えるか journal へ")
+            elif re.search(r"優先度", l) and l.lstrip().startswith("#"):
+                add("WARN", rel, n, "優先度評価は journal 行きでは?")
+
+def main(argv):
+    targets = argv[1:]
+    if not targets:
+        targets = sorted(glob.glob("*.md")) + sorted(glob.glob("journal/*.md"))
+    if not targets:
+        print("対象ファイルなし"); return 0
+    for t in targets:
+        if os.path.isfile(t):
+            check(t)
+        else:
+            print("見つからない: %s" % t)
+
+    errs  = [i for i in issues if i[0] == "ERROR"]
+    warns = [i for i in issues if i[0] == "WARN"]
+    for sev, path, line, msg in errs + warns:
+        print("%-5s %s:%d  %s" % (sev, path, line, msg))
+    print("\n%d files / ERROR %d / WARN %d" % (len(targets), len(errs), len(warns)))
+    return 1 if errs else 0
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

.claude/skills/restructure-doc/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: restructure-doc
+description: 既存ドキュメント1ファイルをCLAUDE.mdのルール1〜4に沿って仕分ける。事実・推測・採用案を残し、調査過程をjournalへ移す。
+disable-model-invocation: true
+argument-hint: <ファイル名>
+---
+
+# ドキュメントを再編する
+
+運用ルール策定前に書かれたドキュメントを、CLAUDE.md のルール1〜4に沿った形に作り直す。
+**1回の実行で1ファイルだけ**扱う。
+
+## 最重要の制約
+
+**情報を失わせない。** この作業は「移動と再配置」であって、要約でも削除でもない。
+
+- 内容を短くしない。判断に迷った記述は、消さずに残してユーザーに聞く。
+- メインドキュメントから外す記述は、必ず journal に移す。捨てない。
+- 元の主張を勝手に言い換えない。特に断定度を上げ下げしない。
+
+## 手順
+
+### 1. 全体を読む
+
+対象ファイルを最初から最後まで読む。部分的に読んで判断しない。
+
+### 2. 4分類する
+
+各ブロック(見出し単位、または段落単位)を次のどれかに分ける。
+
+| 分類 | 行き先 |
+|---|---|
+| a. 採用した案 / 現在の設定 / 設計に影響する制約 | メインドキュメントに残す |
+| b. 裏取りの済んだ事実 | メインドキュメントに残す(文中のどこでもよい) |
+| c. 未確認の推測・未解決の問い | メインドキュメント末尾の `## 未確認事項` |
+| d. 調査過程 / 案の比較 / 却下案 / 優先度評価 | `journal/` へ移す |
+
+判定のヒント:
+
+- メリット/デメリット表、優先度リスト、「〜も検討したが」 → d
+- 「〜できるはず」「〜と考えられる」「実現可能」で、実際に試していない → c
+- 外部仕様の記述(KLEのプロパティ定義など)は、出典を確認できていれば b、していなければ c
+
+### 3. 分類結果を提示して承認を得る
+
+**ここで必ず止まる。** ファイルを書き換える前に、分類の一覧をユーザーに見せて確認する。
+特に b と c の境目(裏取りできているか)は自分で判断せず聞く。
+
+### 4. メインドキュメントを書き直す
+
+- a を中心に再構成する。b は文中に自然に置く。
+- 「なぜBではないのか」の記述が残っていたら、**制約文**に書き換える。
+  - ✗ `階層構造はKLEが非対応なので諦めた`
+  - ○ `階層クラスターはKLE JSONに出力しない(KLE互換性の制約)`
+- 落とした案があれば末尾 `## 検討済み・非採用` に1案1行(理由なし、journalファイル名を参照)。
+
+### 5. 未確認事項を立てる
+
+c に分類したものを末尾の `## 未確認事項` にまとめる。
+
+- 本文が前提にしている推測 → 本文に `[推測:P-n]` を付け、対応する項目を置く
+- まだ本文に書けない未解決の問い → 本文タグなしで項目だけ置く
+- 各項目に**格上げ条件**を必ず書く。思いつかないものはユーザーに聞く(空欄で残さない)
+
+```markdown
+### P-1 KLEはlabels[9]の内容を保存時に保持する
+- 位置づけ: 本文「クラスター管理」が前提にしている
+- 格上げ条件: KLE本家でインポート→エクスポートし、labels[9]が残ることを確認する
+```
+
+### 6. journal へ移す
+
+d を `journal/YYYY-MM-DD-<元ファイル名>.md` に移す。
+
+- 冒頭に**結論**(このファイルの再編で何が確定し、何を落としたか)
+- 次に案の比較(元ファイルの表をそのまま持ってきてよい)
+- 以下に元の調査記述
+- 整形は最低限でよい
+
+### 7. コミットする
+
+1ファイル1コミット。メインドキュメントと journal を同じコミットに入れる。
+
+```
+<ファイル名> を運用ルールに沿って再編
+
+<何を残し、何をjournalへ移したか 数行>
+
+Journal: journal/2026-09-16-<元ファイル名>.md
+```
+
+## 注意
+
+- 複数ファイルを一度に触らない。ファイル間で内容が重複していると気づいた場合は、
+  勝手に統合せず、指摘だけしてそのファイルの再編を終える。
+- 再編の途中で事実関係の誤りを見つけても、勝手に直さない。指摘する。

CLAUDE.md

@@ -0,0 +1,91 @@
+# Beyond KLE
+
+キーボード設計のデータモデルとワークフローを再設計するプロジェクト。
+PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ) / IME(入力変換) の5層に分離する。
+
+- 応答・ドキュメントは日本語。
+- 現状はコード未着手、設計ドキュメントのみ。
+
+## ドキュメント地図
+
+| ファイル | 内容 |
+|---|---|
+| `keyboard-design-layers.md` | レイヤー構造とツール分割方針(最上位) |
+| `PHYレイヤー.md` | PHY層の仕様 |
+| `phase1-json-schema.md` | 各層のJSON Schema |
+| `kle-compatibility.md` | KLEとの双方向変換仕様 |
+| `kle-compatibility-analysis.md` | KLE互換性の調査・案比較 |
+| `keyboard-making-workflow.md` | 既存の自作キーボード制作フローとの対応 |
+| `typescript-implementation-plan.md` | 実装計画・技術スタック |
+
+**既存ドキュメントは下記ルールの策定前に書かれたもので、ルール1〜4は未適用。**
+全体の再編は別タスクとして行う。それまで各ファイルをメイン/journalのどちらに分類するかは未確定なので、
+指示なく移動・分割・書き直しをしない。
+
+初期コミット以前の経緯は追跡できない。現在のドキュメント群を「初期検討段階」のベースラインとして扱い、
+それ以前の決定理由を掘り起こそうとしない。
+
+## ドキュメント運用ルール
+
+### 1. メインドキュメント(リポジトリ直下の `*.md`)
+
+書くもの: **採用した案 / 現在の設定 / 設計に影響する制約**。
+
+- 複数案から選んだ場合、「なぜAなのか」を1〜3行で書く。「なぜBではないのか」は書かない。
+- 却下案の比較表・検討過程・ベンチマーク結果はここに置かない(→ `journal/`)。
+- 却下案の再提案を防ぐ情報は、比較ではなく**制約文**として書く。
+  - ✗ `B案はKLEパーサーが壊れるので却下した`
+  - ○ `クラスター情報はKLE JSONに出力しない(KLE互換性の制約)`
+- 末尾に `## 検討済み・非採用` を置き、落とした案を**1案1行**で残す。理由は書かず、journalファイル名を参照する。
+  - 例: `- labels[9] へのID埋め込み (journal/2026-09-16-cluster-metadata.md)`
+  - コミットは `git log --oneline -- journal/2026-09-16-cluster-metadata.md` で引ける(journal削除後も追跡可)
+  - 目安5行まで。増えたら古いものから落とす。ここが長くなるのは書きすぎのサイン。
+
+### 2. 履歴と根拠
+
+- **何を変えたか** + 理由数行 → コミットメッセージ。`git log --oneline` で意思決定の流れが追えること。1コミット1決定。
+- **なぜそう決めたか / 調査 / 案の比較** → `journal/` に置き、その決定と**同じコミット**に含める。
+- コミットメッセージ末尾に参照を1行入れる: `Journal: journal/2026-09-16-cluster-metadata.md`
+- journal は作業ツリーから削除する前提(人間にとってのノイズになるため)。履歴には残るので、
+  削除後は `git show <sha>:journal/...` で読む。
+
+### 3. journal の書き方
+
+- 1ファイル1トピック。`journal/YYYY-MM-DD-<topic>.md`。トピックを詰め込まない。
+- 構成は上から順に: **結論** → **案の比較(簡潔な表)** → 検証ログ・根拠・捨てた案。
+  冒頭20行で結論と選択肢が分かること。
+- 他のファイルから journal へリンクを張らない。journal 同士も張らない。参照経路はコミットメッセージのみ。
+- 結論がメインドキュメントに反映されたら削除してよい。
+- 整形は最低限でよい。人間向けの読みやすさは要求しない。
+
+### 4. 事実と推測
+
+- **裏取りの済んだ事実**は、ドキュメント内のどこに書いてもよい。文中に自然に混ぜてよい。
+  ただし同じ事実を複数ドキュメントに複製しない。必要ならリンクする。
+- **未確認の推測**だけを末尾に隔離する。2種類ある:
+  - 本文が前提にしている推測 → 本文に `[推測:P-n]` を付け、末尾の `## 未確認事項` に対応項目を置く
+  - まだ本文に書けない未解決の問い → 本文タグなしで `## 未確認事項` に直接置く
+- `## 未確認事項` の各項目には、**何を確認できれば事実に格上げできるか**を必ず書く。
+- 検証できたらタグを外し、該当項目を削除する。
+- 「今回検討して捨てた仮説」は `## 未確認事項` に書かない。journal に残して消す。
+- 推測に基づいて実装しない。先に検証するか、ユーザーに確認する。
+
+書式:
+
+```markdown
+## 未確認事項
+
+### P-1 KLEはlabels[9]の内容を保存時に保持する
+- 位置づけ: 本文「クラスター管理」が前提にしている
+- 格上げ条件: KLE本家でインポート→エクスポートし、labels[9]が残ることを確認する
+```
+
+## Claude への作業指示
+
+- ドキュメントを更新するときは、上のルール1〜4のどこに属する情報かを判断してから書く。分類に迷うものは書く前に確認する。
+- 調査タスクの結果は、結論だけをメインドキュメントに書き、調査過程は `journal/` に落とす。
+- 既存ドキュメントの記述と食い違う事実を見つけたら、勝手に上書きせず指摘する。
+
+## 未確認事項
+
+(なし)

PHYレイヤー.md

@@ -0,0 +1,188 @@
+# PHYレイヤー
+
+## 概要
+
+PHYレイヤーは、キースイッチやキーキャップ、その他周辺部品の物理的な配置に関する情報を提供する。  
+付加的な情報として、matrix情報(ELCレイヤー)や入力キー情報(MAP/IMEレイヤー)を含ませることができるが、必須ではない。
+
+## 構造
+
+### キースイッチ/キーキャップの配置
+
+各キーはスイッチ・キャップの情報を統合された状態で持ち、キャップの位置・サイズからスイッチ座標を特定する。  
+以下、単に「キー」と呼ぶ場合、キーキャップの位置・サイズを表すオブジェクトをさすこととする。
+
+### プロファイル設定
+
+1ファイル内に複数のプロファイルを持たせることができる。  
+ユニットサイズ(1Uが何mmか、x軸・y軸それぞれ)を規定。  
+ビジュアル表現として、内側へのオフセット位置及びオフセット距離(mm or U単位)・R(U単位)を規定。
+
+### キーの座標
+
+キーキャップの左上角をローカル原点とする。  
+座標単位はU。1Uのサイズは別途指定する。  
+回転中心はローカル原点からの相対座標で表す。グローバル  
+座標・回転角度は0.25U単位・15度単位でスナップするが正規化しない。
+
+### キーのサイズ
+
+0.25U単位でスナップするが正規化しない。
+
+### グルーピング
+
+複数のキーを「クラスター」としてまとめて運用することができる。  
+クラスターのみにフォーカスして編集が可能。  
+クラスターごとの回転中心を設定できる。  
+
+**内部処理での利用**：
+
+- クラスターごとの一括編集・移動・回転
+- 階層構造による管理（クラスターの入れ子構造）
+- 編集時のフォーカス制御
+
+**外部連携での扱い**：
+
+- KLE JSON出力時は、個別のキー配置のみを出力（クラスター情報は含めない）
+- 別途クラスター情報JSONとして構造を保存
+- キーIDによる紐づけで関連性を管理
+
+### 何かある？
+
+## 保存形式
+
+キーごとに絶対座標を持つ。  
+全てのキー、またはキー及びクラスターをまとめたクラスターを配列として持つ
+
+```ts
+type Position={
+    x:number,
+    y:number,
+    w:number,
+    h:number,
+    rx:number,
+    ry:number,
+    ra:number
+}
+type Key={
+    position:Position,
+    profile:Profile
+}
+type Cluster={
+    position:Position,
+    clusters:(Key[]|Cluster[])
+}
+const keys:(Key|Cluster)[]=[]
+```
+
+## 連携用出力形式
+
+### 設計方針
+
+KLE向けの出力は既存のKLE JSON形式を維持し、クラスター情報は別のJSONファイルとして出力する。
+両者の紐づけは、KLEのlabel部分に埋め込むユニークIDを使用する。
+
+### KLE JSON出力
+
+標準的なKLE JSON形式で出力。各キーのlabelにはユニークIDを含める。
+
+```ts
+type ConfigObject = {
+    x?: number,
+    y?: number,
+    w?: number,
+    h?: number,
+    x2?: number,
+    y2?: number,
+    w2?: number,
+    h2?: number,
+    rx?: number,
+    ry?: number,
+    ra?: number,
+    l?: boolean,
+    n?: boolean,
+    d?: boolean,
+    c?: string,
+    t?: string,
+    g?: boolean,
+    a?: number,
+    f?: number,
+    f2?: number,
+    p?: string,
+    s?: string
+}
+
+type KeyLabel = string  // ユニークID + 表示用ラベルを含む
+const kleData = (ConfigObject | KeyLabel)[][]
+```
+
+### クラスター情報JSON
+
+キーのクラスター構造を管理する別ファイル。
+
+```ts
+interface ClusterInfo {
+    id: string,              // クラスターのユニークID
+    name?: string,           // 表示用クラスター名
+    position?: Position,     // クラスター自体の位置・回転情報
+    keyIds: string[],        // 所属するキーのIDリスト
+    subClusters?: string[]   // 子クラスターのIDリスト（ネスト構造用）
+}
+
+interface ClusterData {
+    version: string,
+    profiles: Profile[],     // プロファイル定義
+    keys: {                  // キーID -> 追加情報のマップ
+        [keyId: string]: {
+            originalLabel?: string,   // KLEのlabelから抽出した表示用文字列
+            matrix?: MatrixPosition,  // matrix情報（オプション）
+            mapping?: KeyMapping      // キーマッピング情報（オプション）
+        }
+    },
+    clusters: ClusterInfo[]  // クラスター構造定義
+}
+```
+
+### 出力例
+
+#### keyboard.json (KLE形式)
+
+```json
+[
+    ["key-001\nQ", "key-002\nW", "key-003\nE"],
+    ["key-004\nA", "key-005\nS", "key-006\nD"]
+]
+```
+
+#### keyboard-clusters.json
+
+```json
+{
+    "version": "1.0.0",
+    "keys": {
+        "key-001": { "originalLabel": "Q", "matrix": [0, 0] },
+        "key-002": { "originalLabel": "W", "matrix": [0, 1] },
+        "key-003": { "originalLabel": "E", "matrix": [0, 2] },
+        "key-004": { "originalLabel": "A", "matrix": [1, 0] },
+        "key-005": { "originalLabel": "S", "matrix": [1, 1] },
+        "key-006": { "originalLabel": "D", "matrix": [1, 2] }
+    },
+    "clusters": [
+        {
+            "id": "cluster-alpha",
+            "name": "英字キー",
+            "keyIds": ["key-001", "key-002", "key-003", "key-004", "key-005", "key-006"]
+        }
+    ]
+}
+```
+
+### 分離設計のメリット
+
+この設計により以下の利点が得られる：
+
+1. **KLE互換性の維持**：既存のKLE関連ツールとの完全な互換性を保持
+2. **柔軟な拡張性**：クラスター情報を独立して管理・拡張可能
+3. **段階的移行**：既存のKLEユーザーが段階的に拡張機能を利用可能
+4. **ツール間連携**：KLE標準形式での出力により、他のキーボード設計ツールとの相互運用性を確保
+5. **データの軽量化**：KLE出力時に不要な情報を含めず、ファイルサイズを最小化

keyboard-design-layers.md

@@ -0,0 +1,167 @@
+# Beyond KLE: キーボード設計レイヤー構造とツール設計方針
+
+## 背景
+
+### KLEの問題点
+
+- **物理配置と論理構造の混同**: y座標や回転角度で行を判定するため、カラムスタッガードや曲線配列で大量の行が生成される
+- **データモデルの限界**: 物理配置(PHY)のみを扱い、マトリックス座標やキーマップ情報を保持できない
+- **VIAのhackyな対応**: ラベルフィールドに"1,5"と入れて`matrix:[1,5]`を表現
+
+### 設計思想
+
+- 「Better KLE」ではなく「Beyond KLE」: UIではなくデータモデルとワークフロー全体の再設計
+- UNIX哲想の適用: 小さな役割のツールがそれぞれしっかり機能する
+- 統合環境(IDE)の提供: 独立したツール群をオーケストレート
+
+## レイヤー構造
+
+### 1. PHYレイヤー (物理配置)
+
+- **役割**: キーの物理的な位置、サイズ、回転
+- **対応ツール**: PCBエディタ、KLE
+- **出力**: 座標とキーサイズの配列
+
+### 2. ELCレイヤー (電気配線)
+
+- **役割**: マイコンのpinと各キーの対応
+- **対応ツール**: 回路図エディタ、ファームウェア
+- **出力**: ピン配列定義、マトリックス配線情報
+- **備考**: charlieplexingなど非標準的な実装にも対応
+
+### 3. IDXレイヤー (キー識別)
+
+- **役割**: 物理位置と"キー番号"の対応付け
+- **重要性**: 物理世界と論理世界を繋ぐ最も重要な抽象化層
+- **出力**: `{x, y, matrix:[row,col], label}[]`
+- **備考**: 現状のエコシステムで最も欠けている層
+
+### 4. MAPレイヤー (キーマップ)
+
+- **役割**: キー番号とキーコードの対応
+- **対応ツール**: ファームウェア、VIA、Remap
+- **出力**: レイヤー別キーコード配列
+
+### 5. IMEレイヤー (入力変換)
+
+- **役割**: キーコードと実際の入力文字の対応
+- **対応ツール**: OS
+- **備考**: MAPレイヤー設計時に考慮が必要
+
+## ツール設計方針
+
+### 個別ツール (独立動作可能)
+
+#### PHY Editor
+
+- 物理配置の視覚的編集
+- KLE互換フォーマット対応
+- 出力: PHY JSON
+
+#### Matrix Mapper
+
+- PHY Editorの出力を入力
+- キーにrow/colを割り当て
+- 視覚的にマトリックス配線を確認
+- 出力: IDX JSON
+
+#### Pin Configurator
+
+- マトリックス定義を入力
+- マイコンのピン配置を指定
+- 配線図を出力
+- 出力: ELC JSON
+
+#### Keymap Designer
+
+- キー識別子リストを入力
+- レイヤー別キーコード割り当て
+- VIA/Remapとの互換性
+- 出力: MAP JSON
+
+#### Firmware Generator
+
+- 全レイヤーの情報を統合
+- QMK/VIA/KMK等へ変換
+- 出力: ターゲット固有の設定ファイル
+
+### 統合環境 (IDE)
+
+- **プロジェクトファイル**: 全レイヤーの状態を一元管理
+- **リアルタイムプレビュー**: レイヤー間の依存関係を可視化
+- **バージョン管理統合**: テキストベース定義でgit管理
+- **ワークフローサポート**: ガイド付きウィザード、テンプレート
+
+## プロトコル設計
+
+### レイヤー間インターフェース
+
+```txt
+PHY → IDX
+  Input:  KLE JSON (or compatible)
+  Output: Augmented layout (coordinates + key IDs)
+
+IDX → ELC
+  Input:  Key ID list
+  Output: Matrix definition + Pin mapping
+
+IDX → MAP
+  Input:  Key ID list
+  Output: Keymap arrays
+
+All → Firmware
+  Output: QMK keyboard.json / VIA JSON / KMK .py
+```
+
+### データフォーマット
+
+- JSON Schema で各レイヤーの入出力を定義
+- 後方互換性の維持 (KLE JSONからのインポート)
+- 拡張可能な設計 (3D配置、非標準マトリックス対応)
+
+## 実装戦略
+
+### Phase 1: プロトコル策定
+
+- JSON Schemaでフォーマット定義
+- TypeScriptでリファレンス実装
+- CLIツールとして動作確認
+
+### Phase 2: 個別ツール開発
+
+- 各レイヤー用エディタを独立開発
+- 既存ツールからのインポート機能
+- 単独利用可能な設計
+
+### Phase 3: IDE統合
+
+- Electron/Tauri or Webアプリ
+- プロジェクト管理機能
+- ワークフロー支援
+
+## 既存ツールとの関係
+
+- **KLE**: PHY Editorの一実装、インポート対応
+- **VIA/Remap**: MAP Layerクライアントとして連携
+- **QMK Configurator**: Firmware Generatorのターゲット
+
+## 配慮事項
+
+### 学習コスト
+
+- テンプレートプロジェクト提供 (60%, Split等)
+- 簡易モード/詳細モードの切り替え
+- 段階的な機能開示
+
+### 互換性
+
+- 既存KLE JSONの完全サポート
+- 段階的移行パスの提供
+- レガシーツールとの共存
+
+## 次のステップ
+
+1. プロトコル仕様ドラフト作成
+2. GitHubでRFCリポジトリ立ち上げ
+3. 小規模コミュニティでフィードバック収集
+4. リファレンス実装の開発

keyboard-making-workflow.md

@@ -0,0 +1,157 @@
+# 自作キーボード制作ワークフロー分析
+
+## 現在の一般的な制作手順
+
+### 1. デザイン・設計段階
+
+#### a) レイアウト設計
+
+- **ツール**: KLE (Keyboard Layout Editor)
+- **作業内容**:
+  - キーの物理配置を決定
+  - キーサイズ・間隔・角度を調整
+  - 視覚的な配置確認
+- **出力**: KLE JSON ファイル
+- **Beyond KLE対応**: **PHYレイヤー**
+
+#### b) 回路設計・マトリックス設計
+
+- **ツール**: 手動計算、KiCad等の回路図エディタ
+- **作業内容**:
+  - キーマトリックスの行列構成を決定
+  - マイコンピンとの対応付け
+  - ダイオード配置の検討
+- **出力**: 回路図、ピン配置表
+- **現在の課題**: KLEからマトリックス情報への変換が手動
+- **Beyond KLE対応**: **ELCレイヤー** + **IDXレイヤー**
+
+### 2. PCB設計段階
+
+#### a) フットプリント配置
+
+- **ツール**: KiCad、Eagle、Fusion360等
+- **作業内容**:
+  - KLE JSONから座標を抽出（手動またはスクリプト）
+  - スイッチフットプリントの配置
+  - マイコン・コネクタ等の部品配置
+- **現在の課題**: KLEとPCBツール間の座標変換
+- **Beyond KLE対応**: **PHYレイヤー** → PCBツール連携
+
+#### b) 配線・ルーティング
+
+- **ツール**: PCB CADソフト
+- **作業内容**:
+  - マトリックス配線の実装
+  - 電源・信号線のルーティング
+- **Beyond KLE対応**: **ELCレイヤー**情報の活用
+
+### 3. ファームウェア設定段階
+
+#### a) ファームウェア基本設定
+
+- **ツール**: QMK、KMK、VIA等
+- **作業内容**:
+  - マトリックス定義（ROW/COL）
+  - ピン配置設定
+  - 物理レイアウト定義
+- **現在の課題**:
+  - KLEとファームウェア設定の手動変換
+  - VIAではlabelフィールドに"1,5"等を記入してmatrix座標を表現
+- **Beyond KLE対応**: **IDXレイヤー** + **ELCレイヤー** → ファームウェア自動生成
+
+#### b) キーマップ設定
+
+- **ツール**: QMK Configurator、VIA、Remap等
+- **作業内容**:
+  - 各キーへのキーコード割り当て
+  - レイヤー設計
+  - マクロ・特殊機能の設定
+- **Beyond KLE対応**: **MAPレイヤー**
+
+### 4. 製造・組み立て段階
+
+#### a) PCB製造
+
+- **出力**: Gerberファイル、BOM、Pick&Place
+- **Beyond KLE対応**: PHY/ELCレイヤーからの自動生成
+
+#### b) 部品調達・組み立て
+
+- **作業内容**: はんだ付け、組み立て、動作確認
+
+## 現在のワークフローの問題点
+
+### 1. データの分断
+
+- **問題**: KLE → PCB → ファームウェアで毎回手動変換
+- **影響**: 一箇所変更時の全体への反映が困難
+
+### 2. マトリックス情報の欠落
+
+- **問題**: KLEは物理配置のみ、論理構造（マトリックス）は別管理
+- **影響**: VIAでのhackyな対応（labelフィールド悪用）
+
+### 3. 設計変更時のトレーサビリティ不足
+
+- **問題**: どのレイヤーでの変更が他に影響するかが不明確
+- **影響**: デバッグ・修正作業の複雑化
+
+### 4. ツール間連携の脆弱性
+
+- **問題**: 手動変換によるヒューマンエラー
+- **影響**: 設計ミス、製造後の修正コスト
+
+## Beyond KLEによる解決策
+
+### 1. 統一データモデル
+
+```
+物理設計(PHY) → キー識別(IDX) → 電気設計(ELC) → キーマップ(MAP)
+     ↓              ↓             ↓            ↓
+  PCBツール    ファームウェア   回路図    VIA/Remap
+```
+
+### 2. レイヤー間の明確な責任分離
+
+- **PHY**: 物理配置のみに集中
+- **IDX**: 物理と論理の橋渡し（最重要レイヤー）
+- **ELC**: 電気的接続の明確化
+- **MAP**: キーマップロジックの分離
+
+### 3. 双方向の依存関係管理
+
+- 上流レイヤーの変更が下流に自動反映
+- 下流での制約が上流設計にフィードバック
+
+### 4. 既存ツールとの互換性維持
+
+- KLE JSONの完全サポート
+- VIA/QMK等への出力対応
+- 段階的移行の実現
+
+## Phase 1で策定すべきプロトコル
+
+### 1. レイヤー間インターフェース仕様
+
+- 各レイヤーの入出力JSON Schema
+- 依存関係の明確化
+- エラーハンドリング規則
+
+### 2. 既存フォーマットとの変換仕様
+
+- KLE JSON → PHY変換
+- QMK設定 ← IDX+ELC+MAP変換
+- VIA JSON ← 全レイヤー統合
+
+### 3. 拡張性設計
+
+- 非標準マトリックス（charlieplexing等）対応
+- 3D配置への拡張可能性
+- カスタムキーコードサポート
+
+## 次のアクション
+
+1. **JSON Schema策定**: 各レイヤーのデータ構造定義
+2. **変換ロジック設計**: レイヤー間の変換アルゴリズム
+3. **リファレンス実装**: TypeScript/Rust等でのプロトタイプ
+4. **テストケース作成**: 代表的なキーボード設計での検証

kle-compatibility-analysis.md

@@ -0,0 +1,453 @@
+# PHYレイヤーとKLE（Keyboard Layout Editor）の互換性分析
+
+## 概要
+
+検討中のPHYレイヤー構造とKeyboard Layout Editor（KLE）の互換性について詳細に分析した結果をまとめます。KLEをベースとしたフロントエンドの実現可能性を評価します。
+
+## KLEデータモデルの特徴
+
+### KLEで対応可能な主要プロパティ
+
+KLEの`Key`オブジェクトは以下の構造を持ちます：
+
+```typescript
+export class Key {
+  // 位置・サイズ関連
+  x: number;                    // 絶対位置 (U単位)
+  y: number;                    // 絶対位置 (U単位)
+  width: number;                // サイズ (U単位)
+  height: number;               // サイズ (U単位)
+  
+  // 回転関連
+  rotation_x: number;           // 回転中心X座標
+  rotation_y: number;           // 回転中心Y座標
+  rotation_angle: number;       // 回転角度
+  
+  // 複雑な形状対応
+  x2: number;                   // 第2矩形の相対位置
+  y2: number;                   // 第2矩形の相対位置
+  width2: number;               // 第2矩形のサイズ
+  height2: number;              // 第2矩形のサイズ
+  
+  // 表示・装飾関連
+  color: string;                // キーキャップ色
+  labels: string[];             // 最大12個のラベル
+  textColor: Array<string | undefined>;
+  textSize: Array<number | undefined>;
+  profile: string;              // キープロファイル
+  
+  // フラグ類
+  decal: boolean;               // デカールモード
+  ghost: boolean;               // ゴーストモード
+  stepped: boolean;             // ステップキー
+  nub: boolean;                 // ホーミング突起
+  
+  // スイッチ情報
+  sm: string;                   // スイッチマウント
+  sb: string;                   // スイッチブランド
+  st: string;                   // スイッチタイプ
+}
+```
+
+## 互換性マトリックス
+
+### ✅ 完全対応可能
+
+| PHYレイヤー機能 | KLEプロパティ | 備考 |
+|---|---|---|
+| キー座標（x,y） | `x`, `y` | 1:1対応、U単位 |
+| キーサイズ（w,h） | `width`, `height` | 1:1対応、U単位 |
+| 回転角度 | `rotation_angle` | 1:1対応 |
+| 回転中心 | `rotation_x`, `rotation_y` | 1:1対応 |
+| 0.25U単位スナップ | - | KLEも小数点座標対応 |
+| 複雑形状キー | `x2`, `y2`, `width2`, `height2` | ISO Enter等に対応 |
+| プロファイル設定 | `profile` | SA、DCS、OEM等対応 |
+
+### ⚠️ 部分対応・要改造
+
+| PHYレイヤー機能 | KLE対応状況 | 改造内容 |
+|---|---|---|
+| クラスター管理 | 非対応 | カスタムメタデータとしてlabelsに格納 |
+| 複数プロファイル | 一部対応 | メタデータで管理、UI拡張必要 |
+| ユニットサイズ設定 | 非対応 | グローバル設定として追加実装 |
+| ビジュアルオフセット | 非対応 | レンダリング層で独自実装 |
+
+### ❌ 対応困難・KLE制約
+
+| PHYレイヤー機能 | KLE制約 | 回避策 |
+|---|---|---|
+| 15度以外の回転角度 | UI制約（内部は対応可能） | UI改造またはAPI直接操作 |
+| 階層的クラスター | データモデル非対応 | ゴーストキーによるメタデータ保存 |
+| クラスター別回転中心 | 直接非対応 | 各キーの回転中心で代替 |
+
+## 具体的な実装戦略
+
+### 1. KLEベースデータ変換
+
+PHYレイヤーからKLE形式への変換：
+
+```typescript
+// PHYレイヤー → KLE変換例
+function convertToKLE(phyData: PHYLayer): KLEData {
+  return phyData.elements.map(element => {
+    if (element.type === 'key') {
+      return {
+        x: element.position.x,
+        y: element.position.y,
+        width: element.size.width,
+        height: element.size.height,
+        rotation_x: element.position.rotationOrigin?.x || 0,
+        rotation_y: element.position.rotationOrigin?.y || 0,
+        rotation_angle: element.position.rotation || 0,
+        // クラスター情報をlabelsの特定位置に格納
+        labels: [element.clusterId || '', '', '', '', '', '', '', '', '', '', '', ''],
+        // プロファイル情報
+        profile: element.profile || 'OEM'
+      };
+    }
+    // クラスターの場合は展開処理
+  });
+}
+```
+
+### 2. KLE UI改造点
+
+#### 必要な改造項目
+
+1. **クラスター管理UI**
+   - クラスター作成・編集パネル
+   - クラスター単位の選択・移動
+   - クラスター階層表示
+
+2. **プロファイル管理**
+   - 複数プロファイル切り替えUI
+   - プロファイル別ユニットサイズ設定
+
+3. **メタデータ拡張**
+   - PHYレイヤー固有情報の保存
+   - 互換性情報の管理
+
+#### UI改造の難易度
+
+- **低難易度**: 既存プロパティパネルの拡張
+- **中難易度**: クラスター管理機能の追加
+- **高難易度**: レンダリングエンジンの改造
+
+### 3. 制限事項と回避策
+
+#### 現在のKLE制約
+
+1. **データモデル制約**
+   - フラットな配列構造のみ対応
+   - 階層的クラスター管理は困難
+
+2. **レンダリング制約**
+   - HTMLベースのレンダリング
+   - 複雑な視覚効果には限界
+
+#### 回避策
+
+1. **段階的対応**
+   - Phase 1: 基本的な位置・サイズ・回転のみ対応
+   - Phase 2: クラスター管理機能追加
+   - Phase 3: 高度なビジュアル機能
+
+2. **ハイブリッドアプローチ**
+   - KLEをベースエディタとして使用
+   - 独自機能は別パネルで管理
+   - 最終出力時にPHYレイヤー形式で統合
+
+## 推奨実装アプローチ
+
+### フェーズ1: KLE最小改造アプローチ（推奨）
+
+1. **KLEの既存機能をそのまま活用**
+   - 基本的な配置・サイズ・回転
+   - プロファイル設定
+   - 色・ラベル設定
+
+2. **最小限の拡張**
+   - カスタムメタデータ保存機能
+   - PHYレイヤー形式エクスポート
+
+3. **段階的機能追加**
+   - クラスター管理（Phase 2）
+   - 高度なビジュアル機能（Phase 3）
+
+### 実装優先順位
+
+1. **高優先度** - 即座に対応可能
+   - ✅ 基本位置・サイズ・回転
+   - ✅ プロファイル設定
+   - ✅ KLE→PHYレイヤー変換
+
+2. **中優先度** - 改造が必要だが実現可能
+   - ⚠️ 簡易クラスター管理
+   - ⚠️ 複数プロファイル対応
+   - ⚠️ カスタムユニットサイズ
+
+3. **低優先度** - 大規模改造が必要
+   - ❌ 階層的クラスター
+   - ❌ 高度なビジュアルオフセット
+   - ❌ リアルタイム3Dプレビュー
+
+## 結論
+
+**KLEをベースとしたPHYレイヤーエディタの実現は十分可能**です。
+
+### 対応可能な機能（約80%）
+
+- 基本的なキー配置・サイズ・回転
+- 複雑形状キー（ISO Enter等）
+- プロファイル管理
+- 基本的なクラスター管理
+
+### 改造が必要な機能（約15%）
+
+- 高度なクラスター管理
+- 複数プロファイル切り替え
+- カスタムユニットサイズ
+
+### 対応困難な機能（約5%）
+
+- 完全階層的クラスター構造
+- 高度なビジュアルエフェクト
+
+PHYレイヤーの主要機能はKLEで十分実現可能であり、段階的な改造により完全対応も期待できます。
+
+## 階層型クラスターの実装戦略
+
+### 問題提起
+
+ユーザーからの要求：
+
+- **階層型クラスター管理は絶対に実装したい**
+- 出力時はフラット化してもOK（階層情報を何らかの形で記録できれば）
+- ラベルに突っ込むと見づらくなる懸念
+- **ゴーストキーによる情報保存**のアイデア
+
+### ゴーストキーアプローチの詳細設計
+
+#### 基本概念
+
+クラスター情報を`ghost: true`のキーとして保存し、実際のキーレンダリングには影響を与えずにメタデータとして扱う。
+
+```typescript
+// クラスター情報保存用ゴーストキー
+type ClusterGhostKey = {
+  ghost: true,
+  decal: false,
+  x: number,           // クラスター範囲の左上角
+  y: number,           // クラスター範囲の左上角
+  width: number,       // クラスター範囲の幅
+  height: number,      // クラスター範囲の高さ
+  rotation_x: number,  // クラスター回転中心
+  rotation_y: number,  // クラスター回転中心
+  rotation_angle: number, // クラスター回転角度
+  color: "#transparent", // 透明
+  labels: [
+    "CLUSTER_META",           // [0] 識別子
+    clusterId,                // [1] クラスターID
+    parentClusterId,          // [2] 親クラスターID（階層用）
+    clusterName,              // [3] クラスター名
+    JSON.stringify(metadata), // [4] その他メタデータ
+    "", "", "", "", "", "", "" // [5-11] 予約
+  ]
+}
+```
+
+#### 階層構造の表現
+
+```typescript
+// 例：分割キーボードの左右ブロック + 各ブロック内のキークラスター
+const clusterHierarchy = {
+  "root": {
+    children: ["left_block", "right_block"]
+  },
+  "left_block": {
+    parent: "root",
+    children: ["left_alpha", "left_modifiers"]
+  },
+  "right_block": {
+    parent: "root", 
+    children: ["right_alpha", "right_modifiers"]
+  },
+  "left_alpha": {
+    parent: "left_block",
+    keyIds: ["Q", "W", "E", "R", "T", "A", "S", "D", "F", "G", ...]
+  }
+  // ...
+}
+```
+
+#### KLE UI拡張による階層管理
+
+1. **クラスター管理パネル**
+
+   ```html
+   <!-- 新しいサイドパネル -->
+   <div id="cluster-manager">
+     <tree-view>
+       <cluster-node id="root">
+         <cluster-node id="left_block">
+           <cluster-node id="left_alpha" />
+           <cluster-node id="left_modifiers" />
+         </cluster-node>
+         <cluster-node id="right_block">
+           <cluster-node id="right_alpha" />
+           <cluster-node id="right_modifiers" />
+         </cluster-node>
+       </cluster-node>
+     </tree-view>
+   </div>
+   ```
+
+2. **クラスター操作機能**
+   - ドラッグ&ドロップによるキーのクラスター移動
+   - 階層ツリーでのクラスター選択
+   - クラスター単位での一括変換（移動・回転・リサイズ）
+   - クラスター単位でのコピー&ペースト
+
+### データフロー設計
+
+#### 1. 編集時（UI → 内部データ）
+
+```javascript
+// クラスター作成時
+function createCluster(name, parentId, selectedKeys) {
+  const clusterId = generateUniqueId();
+  
+  // ゴーストキーを作成
+  const ghostKey = createClusterGhostKey({
+    id: clusterId,
+    name: name,
+    parentId: parentId,
+    boundingBox: calculateBoundingBox(selectedKeys)
+  });
+  
+  // 選択されたキーにクラスターIDを付与
+  selectedKeys.forEach(key => {
+    key.clusterId = clusterId; // カスタムプロパティとして追加
+  });
+  
+  // KLEのキー配列に追加
+  scope.keys().push(ghostKey);
+}
+```
+
+#### 2. 保存時（内部データ → KLE JSON）
+
+```javascript
+function serializeWithClusters(keyboard) {
+  const kleData = serial.serialize(keyboard);
+  
+  // 通常のキーとゴーストキーが混在した状態で保存
+  // ゴーストキーがクラスター情報を保持
+  return kleData;
+}
+```
+
+#### 3. 読み込み時（KLE JSON → 内部データ）
+
+```javascript
+function deserializeWithClusters(kleData) {
+  const keyboard = serial.deserialize(kleData);
+  
+  // ゴーストキーからクラスター情報を復元
+  const clusterMap = new Map();
+  const normalKeys = [];
+  
+  keyboard.keys.forEach(key => {
+    if (key.ghost && key.labels[0] === 'CLUSTER_META') {
+      const clusterId = key.labels[1];
+      const parentId = key.labels[2];
+      const metadata = JSON.parse(key.labels[4]);
+      
+      clusterMap.set(clusterId, {
+        ghostKey: key,
+        parentId: parentId,
+        metadata: metadata,
+        children: new Set()
+      });
+    } else {
+      normalKeys.push(key);
+    }
+  });
+  
+  // 階層構造を再構築
+  buildClusterHierarchy(clusterMap);
+  
+  return { keyboard: { ...keyboard, keys: normalKeys }, clusters: clusterMap };
+}
+```
+
+### 15度回転制約について
+
+#### 現在の制約の詳細
+
+KLEのソースコード分析結果：
+
+```javascript
+$scope.rotateStep = 15; // UI上のデフォルト回転ステップ
+
+// 実際の制約チェック（kb.js内）
+rotation_angle: function() { 
+  return Math.max(-180, Math.min(180, value)); // ±180度の範囲制約のみ
+}
+```
+
+**つまり：**
+
+- **UIでは15度ステップで回転操作**（ユーザビリティのため）
+- **内部データには制約なし**（任意の角度を保存可能）
+- **JSON出力も制約なし**（小数点を含む任意の角度値）
+
+#### PHYレイヤーでの対応
+
+```javascript
+// PHY → KLE変換時に任意角度をそのまま渡す
+function convertRotation(phyRotation) {
+  return phyRotation; // 制約なし、そのまま変換
+}
+
+// KLE UI拡張で任意角度入力を許可
+function enableCustomRotation() {
+  // 既存の15度ステップに加えて、直接入力機能を追加
+  scope.customRotateStep = 1; // 1度ステップ
+  scope.allowCustomAngle = true; // 任意角度入力許可
+}
+```
+
+## 実装優先度の再評価
+
+### 修正版優先度
+
+1. **最高優先度** - 即座に対応可能
+   - ✅ 基本位置・サイズ・回転（任意角度対応）
+   - ✅ プロファイル設定
+   - ✅ KLE→PHYレイヤー変換
+
+2. **高優先度** - ゴーストキーアプローチで対応
+   - 🔶 階層型クラスター管理（ゴーストキー方式）
+   - 🔶 クラスターメタデータ保存
+   - 🔶 クラスター単位操作UI
+
+3. **中優先度** - UI改造が必要
+   - ⚠️ 複数プロファイル対応
+   - ⚠️ カスタムユニットサイズ
+   - ⚠️ 15度以外の回転角度UI対応
+
+4. **低優先度** - 大規模改造が必要
+   - ❌ 高度なビジュアルオフセット
+   - ❌ リアルタイム3Dプレビュー
+
+### 実装結論
+
+**ゴーストキーアプローチにより、階層型クラスター管理は実現可能**です。この方法なら：
+
+- KLEの既存データモデルを活用
+- 見た目に影響しない形でメタデータ保存
+- 階層構造の完全な再現が可能
+- 段階的な実装が可能
+
+階層型クラスターが「絶対実装したい」要求に対して、技術的に実現可能な解決策を提供できます。

kle-compatibility.md

@@ -0,0 +1,249 @@
+# KLE JSON 互換性設計
+
+## 双方向変換戦略
+
+### Beyond KLE → KLE JSON
+
+#### 1. フラット化プロセス
+
+```typescript
+interface ConversionOptions {
+  preserveIds: boolean;           // IDを保持するか
+  preserveClusterInfo: boolean;   // クラスター情報を保持するか
+  idEmbedMethod: 'metadata' | 'label' | 'comment';
+}
+
+function convertToKLE(beyondKle: PHYLayer, options: ConversionOptions): KLELayout {
+  const flatKeys = flattenElements(beyondKle.elements);
+  return {
+    name: beyondKle.metadata.name,
+    keys: flatKeys.map(key => convertKey(key, options))
+  };
+}
+
+function flattenElements(elements: Element[], parentTransform?: Transform): FlatKey[] {
+  const result: FlatKey[] = [];
+  
+  for (const element of elements) {
+    if (element.type === 'key') {
+      const absolutePos = applyTransform(element.position, parentTransform);
+      result.push({
+        ...element,
+        absolutePosition: absolutePos,
+        clusterPath: getClusterPath(element)
+      });
+    } else if (element.type === 'cluster') {
+      const clusterTransform = combineTransforms(parentTransform, element.position);
+      result.push(...flattenElements(element.elements, clusterTransform));
+    }
+  }
+  
+  return result;
+}
+```
+
+#### 2. ID保持方法の比較
+
+| 方法 | メリット | デメリット | KLE互換性 |
+|------|----------|------------|-----------|
+| `_beyondkle` メタデータ | 構造化された情報保持 | KLEパーサーが無視する可能性 | △ |
+| ラベル9番目位置 | 確実に保存される | 表示されてしまう | ○ |
+| コメントフィールド | 非表示 | 標準的でない | △ |
+
+#### 3. 推奨アプローチ: ハイブリッド方式
+
+```json
+{
+  "name": "Split Layout (Generated by Beyond KLE)",
+  "_beyondkle": {
+    "version": "1.0.0",
+    "sourceFile": "layout.beyond.json",
+    "conversionSettings": {
+      "flattenClusters": true,
+      "preserveRotations": true
+    }
+  },
+  "keys": [
+    {
+      "x": 0, "y": 0, "w": 1, "h": 1,
+      "t": "#000000\n\n\n\n\n\n\n\n\nk00",
+      "_beyondkle": {
+        "id": "k00",
+        "clusterPath": ["left_half", "left_main"],
+        "relativePosition": { "x": 0, "y": 0 },
+        "absolutePosition": { "x": 0, "y": 0 }
+      }
+    }
+  ]
+}
+```
+
+### KLE JSON → Beyond KLE
+
+#### 1. ID復元戦略
+
+```typescript
+function convertFromKLE(kleLayout: KLELayout): PHYLayer {
+  // 1. メタデータからBeyond KLE情報を取得
+  const beyondKleInfo = kleLayout._beyondkle;
+  
+  if (beyondKleInfo?.sourceFile) {
+    // 元のBeyond KLEファイルが指定されている場合
+    return reconstructFromSource(kleLayout, beyondKleInfo);
+  }
+  
+  // 2. キーからIDとクラスター情報を抽出
+  const keys = kleLayout.keys.map(kleKey => {
+    const id = extractId(kleKey);
+    const clusterInfo = extractClusterInfo(kleKey);
+    
+    return {
+      type: 'key' as const,
+      id: id || generateId(kleKey),
+      profile: 'default',
+      position: { x: kleKey.x, y: kleKey.y },
+      size: { width: kleKey.w || 1, height: kleKey.h || 1 },
+      metadata: extractMetadata(kleKey)
+    };
+  });
+  
+  // 3. クラスター構造の再構築
+  return reconstructClusters(keys);
+}
+
+function extractId(kleKey: any): string | null {
+  // 1. _beyondkle メタデータから
+  if (kleKey._beyondkle?.id) return kleKey._beyondkle.id;
+  
+  // 2. ラベル9番目から
+  if (kleKey.labels?.[8]) return kleKey.labels[8];
+  
+  // 3. t文字列の解析
+  const tMatch = kleKey.t?.match(/\n([a-zA-Z0-9_]+)$/);
+  if (tMatch) return tMatch[1];
+  
+  return null;
+}
+```
+
+#### 2. クラスター再構築アルゴリズム
+
+```typescript
+function reconstructClusters(flatKeys: Key[]): Element[] {
+  // クラスター情報が保持されている場合
+  const clusteredKeys = groupByCluster(flatKeys);
+  
+  if (Object.keys(clusteredKeys).length > 1) {
+    return Object.entries(clusteredKeys).map(([clusterName, keys]) => ({
+      type: 'cluster' as const,
+      id: clusterName,
+      name: clusterName,
+      position: calculateClusterOrigin(keys),
+      elements: keys.map(key => ({
+        ...key,
+        position: makeRelativeToCluster(key.position, clusterOrigin)
+      }))
+    }));
+  }
+  
+  // クラスター情報がない場合は自動推定
+  return autoDetectClusters(flatKeys);
+}
+
+function autoDetectClusters(keys: Key[]): Element[] {
+  // 座標の近さとレイアウトパターンからクラスターを推定
+  // 1. 連続する矩形領域の検出
+  // 2. 回転角度の類似性
+  // 3. 一定の間隔での分離
+  
+  const clusters = detectSpatialClusters(keys);
+  
+  if (clusters.length === 1) {
+    // 単一クラスターの場合はフラットに
+    return keys;
+  }
+  
+  return clusters;
+}
+```
+
+## 実装における考慮事項
+
+### 1. バージョン管理
+
+```json
+{
+  "_beyondkle": {
+    "version": "1.0.0",
+    "generator": "beyond-kle-converter",
+    "timestamp": "2025-11-09T12:00:00Z",
+    "preservedData": {
+      "clusters": true,
+      "rotations": true,
+      "profiles": false
+    }
+  }
+}
+```
+
+### 2. 設定可能な変換オプション
+
+```typescript
+interface ConversionSettings {
+  // ID保持方法
+  idPreservation: 'metadata' | 'label' | 'both' | 'none';
+  
+  // クラスター処理
+  clusterHandling: 'preserve' | 'flatten' | 'auto';
+  
+  // 回転の処理
+  rotationHandling: 'preserve' | 'flatten';
+  
+  // プロファイル情報
+  includeProfiles: boolean;
+  
+  // 互換性レベル
+  compatibilityLevel: 'strict' | 'extended' | 'beyondkle';
+}
+```
+
+### 3. 往復変換の整合性保証
+
+```typescript
+// テストケース
+const originalBeyondKLE = loadBeyondKLE('test.beyond.json');
+const kleJson = convertToKLE(originalBeyondKLE, settings);
+const reconstructed = convertFromKLE(kleJson);
+
+// 構造的等価性の検証
+assert(structurallyEquivalent(originalBeyondKLE, reconstructed));
+```
+
+## ワークフロー例
+
+### 1. Beyond KLE → 外部ツール → Beyond KLE
+
+```bash
+# Beyond KLE → KLE JSON (ID付き)
+beyond-kle export --format=kle --preserve-ids layout.beyond.json
+
+# 外部ツール（KLE等）で編集
+# ...
+
+# KLE JSON → Beyond KLE (構造復元)
+beyond-kle import --format=kle --auto-cluster edited.kle.json
+```
+
+### 2. 段階的移行
+
+```bash
+# 既存のKLE JSON → Beyond KLE
+beyond-kle import legacy.kle.json
+
+# Beyond KLE で編集・管理
+
+# 必要に応じてKLE JSONで共有
+beyond-kle export --format=kle-compatible project.beyond.json
+```
+
+この設計により、Beyond KLEの高度な機能を使いながらも、既存のKLEエコシステムとの互換性を保てると思いますが、いかがでしょうか？

phase1-json-schema.md

@@ -0,0 +1,483 @@
+# Phase 1: JSON Schema仕様策定
+
+## レイヤー間データフロー
+
+```
+PHY (物理配置) → IDX (キー識別) → ELC (電気配線) + MAP (キーマップ)
+                                      ↓                    ↓
+                               ファームウェア生成    VIA/Remap出力
+```
+
+## 1. PHYレイヤー JSON Schema
+
+### 基本構造
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://beyond-kle.org/schemas/phy-layer.json",
+  "title": "PHY Layer - Physical Key Layout",
+  "description": "Physical positioning and sizing of keys",
+  "type": "object",
+  "required": ["version", "metadata", "profiles", "elements"],
+  "properties": {
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Schema version (semver)"
+    },
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "author": { "type": "string" },
+        "description": { "type": "string" },
+        "created": { "type": "string", "format": "date-time" },
+        "modified": { "type": "string", "format": "date-time" }
+      }
+    },
+    "compatibility": {
+      "type": "object",
+      "description": "Information for external tool compatibility",
+      "properties": {
+        "kleJson": {
+          "type": "object",
+          "properties": {
+            "source": { "type": "string" },
+            "checksum": { "type": "string" },
+            "preservedFields": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "originalFormat": {
+          "type": "string",
+          "enum": ["kle", "via", "qmk", "native"]
+        }
+      }
+    },
+    "profiles": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/profile"
+      }
+    },
+    "elements": {
+      "type": "array",
+      "items": {
+        "oneOf": [
+          { "$ref": "#/$defs/key" },
+          { "$ref": "#/$defs/cluster" }
+        ]
+      }
+    }
+  },
+  "$defs": {
+    "profile": {
+      "type": "object",
+      "required": ["id", "name", "unitSize"],
+      "properties": {
+        "id": { "type": "string" },
+        "name": { "type": "string" },
+        "unitSize": {
+          "type": "object",
+          "required": ["x", "y"],
+          "properties": {
+            "x": { "type": "number", "minimum": 0 },
+            "y": { "type": "number", "minimum": 0 }
+          }
+        },
+        "visualOffset": {
+          "type": "object",
+          "properties": {
+            "x": { "type": "number" },
+            "y": { "type": "number" },
+            "radius": { "type": "number", "minimum": 0 }
+          }
+        }
+      }
+    },
+    "key": {
+      "type": "object",
+      "required": ["type", "id", "profile", "position", "size"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "key"
+        },
+        "id": {
+          "type": "string",
+          "description": "Unique key identifier"
+        },
+        "profile": {
+          "type": "string",
+          "description": "Reference to profile ID"
+        },
+        "position": {
+          "type": "object",
+          "required": ["x", "y"],
+          "properties": {
+            "x": { "type": "number" },
+            "y": { "type": "number" },
+            "rotation": { "type": "number" },
+            "rotationOrigin": {
+              "type": "object",
+              "properties": {
+                "x": { "type": "number" },
+                "y": { "type": "number" }
+              }
+            }
+          }
+        },
+        "size": {
+          "type": "object",
+          "required": ["width", "height"],
+          "properties": {
+            "width": { "type": "number", "minimum": 0 },
+            "height": { "type": "number", "minimum": 0 }
+          }
+        },
+        "metadata": {
+          "type": "object",
+          "properties": {
+            "label": { "type": "string" },
+            "color": { "type": "string" },
+            "textColor": { "type": "string" },
+            "kleCompatibility": {
+              "type": "object",
+              "description": "Original KLE fields for round-trip compatibility",
+              "properties": {
+                "originalIndex": { "type": "integer" },
+                "labels": { "type": "array", "items": { "type": "string" } },
+                "textSizes": { "type": "array", "items": { "type": "number" } },
+                "decalData": { "type": "object" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "cluster": {
+      "type": "object",
+      "required": ["type", "id", "name", "elements"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "cluster"
+        },
+        "id": { "type": "string" },
+        "name": { "type": "string" },
+        "position": {
+          "type": "object",
+          "properties": {
+            "x": { "type": "number" },
+            "y": { "type": "number" },
+            "rotation": { "type": "number" },
+            "rotationOrigin": {
+              "type": "object",
+              "properties": {
+                "x": { "type": "number" },
+                "y": { "type": "number" }
+              }
+            }
+          }
+        },
+        "elements": {
+          "type": "array",
+          "items": {
+            "oneOf": [
+              { "$ref": "#/$defs/key" },
+              { "$ref": "#/$defs/cluster" }
+            ]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### 使用例
+
+```json
+{
+  "version": "1.0.0",
+  "metadata": {
+    "name": "Split Keyboard Layout",
+    "author": "John Doe",
+    "description": "Ergonomic split keyboard with rotated thumb clusters",
+    "created": "2025-01-01T00:00:00Z"
+  },
+  "profiles": [
+    {
+      "id": "standard",
+      "name": "Standard Cherry MX",
+      "unitSize": { "x": 19.05, "y": 19.05 },
+      "visualOffset": { "x": 1, "y": 1, "radius": 1 }
+    }
+  ],
+  "elements": [
+    {
+      "type": "cluster",
+      "id": "left_main",
+      "name": "Left Main Block",
+      "position": { 
+        "x": 0, "y": 0, 
+        "rotation": 0,
+        "rotationOrigin": { "x": 3, "y": 2 }
+      },
+      "elements": [
+        {
+          "type": "key",
+          "id": "k00",
+          "profile": "standard",
+          "position": { "x": 0, "y": 0 },
+          "size": { "width": 1, "height": 1 },
+          "metadata": { "label": "Q" }
+        },
+        {
+          "type": "key", 
+          "id": "k01",
+          "profile": "standard",
+          "position": { "x": 1, "y": 0 },
+          "size": { "width": 1, "height": 1 },
+          "metadata": { "label": "W" }
+        }
+      ]
+    },
+    {
+      "type": "cluster",
+      "id": "left_thumb",
+      "name": "Left Thumb Cluster", 
+      "position": { 
+        "x": 2, "y": 3, 
+        "rotation": 15,
+        "rotationOrigin": { "x": 1, "y": 0.5 }
+      },
+      "elements": [
+        {
+          "type": "key",
+          "id": "k30",
+          "profile": "standard",
+          "position": { "x": 0, "y": 0 },
+          "size": { "width": 1.25, "height": 1 },
+          "metadata": { "label": "Space" }
+        },
+        {
+          "type": "key",
+          "id": "k31", 
+          "profile": "standard",
+          "position": { "x": 1.25, "y": 0 },
+          "size": { "width": 1, "height": 1 },
+          "metadata": { "label": "Enter" }
+        }
+      ]
+    }
+  ]
+}
+```
+
+## 2. IDXレイヤー JSON Schema
+
+### 基本構造
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://beyond-kle.org/schemas/idx-layer.json",
+  "title": "IDX Layer - Key Identification",
+  "description": "Mapping between physical keys and logical identifiers",
+  "type": "object",
+  "required": ["version", "phyReference", "keyMap"],
+  "properties": {
+    "version": { "type": "string" },
+    "phyReference": {
+      "type": "object",
+      "required": ["source", "checksum"],
+      "properties": {
+        "source": { "type": "string" },
+        "checksum": { "type": "string" }
+      }
+    },
+    "keyMap": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/keyMapping"
+      }
+    }
+  },
+  "$defs": {
+    "keyMapping": {
+      "type": "object",
+      "required": ["physicalId", "logicalId"],
+      "properties": {
+        "physicalId": {
+          "type": "string",
+          "description": "Reference to PHY layer key ID"
+        },
+        "logicalId": {
+          "type": "object",
+          "required": ["index"],
+          "properties": {
+            "index": { "type": "integer", "minimum": 0 },
+            "matrix": {
+              "type": "object",
+              "properties": {
+                "row": { "type": "integer", "minimum": 0 },
+                "col": { "type": "integer", "minimum": 0 }
+              }
+            },
+            "label": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## 3. ELCレイヤー JSON Schema
+
+### 基本構造
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://beyond-kle.org/schemas/elc-layer.json",
+  "title": "ELC Layer - Electrical Configuration",
+  "description": "Electrical wiring and pin mapping",
+  "type": "object",
+  "required": ["version", "idxReference", "microcontroller", "matrix"],
+  "properties": {
+    "version": { "type": "string" },
+    "idxReference": {
+      "type": "object",
+      "required": ["source", "checksum"],
+      "properties": {
+        "source": { "type": "string" },
+        "checksum": { "type": "string" }
+      }
+    },
+    "microcontroller": {
+      "type": "object",
+      "required": ["type", "pinMapping"],
+      "properties": {
+        "type": { "type": "string" },
+        "pinMapping": {
+          "type": "object",
+          "properties": {
+            "rows": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "cols": {
+              "type": "array", 
+              "items": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "matrix": {
+      "type": "object",
+      "required": ["type", "dimensions"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["standard", "charlieplexing", "direct"]
+        },
+        "dimensions": {
+          "type": "object",
+          "required": ["rows", "cols"],
+          "properties": {
+            "rows": { "type": "integer", "minimum": 1 },
+            "cols": { "type": "integer", "minimum": 1 }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## 4. MAPレイヤー JSON Schema
+
+### 基本構造
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://beyond-kle.org/schemas/map-layer.json", 
+  "title": "MAP Layer - Keymap Configuration",
+  "description": "Key code assignments and layers",
+  "type": "object",
+  "required": ["version", "idxReference", "layers"],
+  "properties": {
+    "version": { "type": "string" },
+    "idxReference": {
+      "type": "object",
+      "required": ["source", "checksum"],
+      "properties": {
+        "source": { "type": "string" },
+        "checksum": { "type": "string" }
+      }
+    },
+    "layers": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/layer"
+      }
+    }
+  },
+  "$defs": {
+    "layer": {
+      "type": "object",
+      "required": ["id", "name", "keymap"],
+      "properties": {
+        "id": { "type": "integer", "minimum": 0 },
+        "name": { "type": "string" },
+        "keymap": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/keyAssignment"
+          }
+        }
+      }
+    },
+    "keyAssignment": {
+      "type": "object",
+      "required": ["keyIndex", "keycode"],
+      "properties": {
+        "keyIndex": { "type": "integer" },
+        "keycode": { "type": "string" }
+      }
+    }
+  }
+}
+```
+
+## 変換フロー設計
+
+### PHY → IDX変換
+
+1. PHYレイヤーから物理キーリストを取得
+2. 各キーに論理IDを割り当て
+3. マトリックス座標の自動生成（行列最適化）
+
+### IDX → ELC変換
+
+1. マトリックス次元を算出
+2. ピン配置の最適化提案
+3. 配線効率の検証
+
+### IDX + ELC → MAP変換
+
+1. キーインデックス配列の生成
+2. デフォルトキーマップの提案
+3. VIA/QMK形式への出力
+
+## 次のステップ
+
+1. **TypeScriptでの型定義作成**
+2. **変換ロジックのプロトタイプ実装**
+3. **テストケース（60%、Split等）での検証**
+4. **既存KLE JSONからの変換機能**

typescript-implementation-plan.md

@@ -0,0 +1,203 @@
+# Beyond KLE: TypeScript実装計画
+
+## プロジェクト構造
+
+```
+beyond-kle/
+├── packages/
+│   ├── core/                 # 共通型定義とユーティリティ
+│   │   ├── src/
+│   │   │   ├── types/       # 各レイヤーの型定義
+│   │   │   ├── validators/  # JSON Schema バリデーター
+│   │   │   └── utils/       # 共通ユーティリティ
+│   │   └── package.json
+│   ├── phy-editor/          # PHYレイヤーエディタ
+│   ├── matrix-mapper/       # IDX/ELCレイヤーマッパー
+│   ├── keymap-designer/     # MAPレイヤーデザイナー
+│   ├── converter/           # 既存フォーマット変換
+│   └── firmware-gen/        # ファームウェア生成
+├── tools/
+│   ├── cli/                 # CLI ツール
+│   └── web-editor/          # Web統合エディタ
+├── schemas/                 # JSON Schema定義
+├── examples/               # サンプルプロジェクト
+└── docs/                   # ドキュメント
+```
+
+## 開発フェーズ
+
+### Phase 1a: 基盤実装
+
+1. **型定義とSchema**
+   - TypeScript型定義
+   - JSON Schema validation
+   - テスト用サンプルデータ
+
+2. **変換エンジン**
+   - KLE JSON → PHY変換
+   - PHY → IDX自動生成
+   - QMK/VIA出力
+
+3. **CLIツール**
+   - 変換機能のコマンドライン提供
+   - バリデーション機能
+
+### Phase 1b: エディタプロトタイプ
+
+1. **PHY Editor (Web)**
+   - React + Canvas での編集機能
+   - KLE互換インポート
+
+2. **Matrix Mapper**
+   - 視覚的マトリックス割り当て
+   - 最適化アルゴリズム
+
+## 技術スタック
+
+### コア
+
+- **言語**: TypeScript
+- **ランタイム**: Node.js / Bun
+- **パッケージ管理**: pnpm + workspace
+- **バリデーション**: Ajv (JSON Schema)
+
+### CLI
+
+- **フレームワーク**: Commander.js
+- **出力**: chalk (色付き), table
+
+### Web Editor
+
+- **フロントエンド**: React + Vite
+- **描画**: Konva.js / Fabric.js
+- **状態管理**: Zustand
+- **UI**: Mantine / shadcn/ui
+
+### テスト
+
+- **テストランナー**: Vitest
+- **E2E**: Playwright
+
+## 実装優先度
+
+### 最優先 (2週間)
+
+1. 型定義とJSON Schema
+2. KLE → PHY変換
+3. PHY → IDX基本変換
+4. CLIでの変換確認
+
+### 高優先 (1ヶ月)
+
+1. QMK/VIA出力
+2. 基本的なWebエディタ
+3. マトリックス最適化
+
+### 中優先 (2ヶ月)
+
+1. 高度なエディタ機能
+2. プロジェクト管理
+3. 既存ツール連携
+
+## 開発環境セットアップ
+
+### 1. プロジェクト初期化
+
+```bash
+# プロジェクト作成
+mkdir beyond-kle-proto
+cd beyond-kle-proto
+
+# pnpm workspace設定
+echo 'packages:\n  - "packages/*"\n  - "tools/*"' > pnpm-workspace.yaml
+
+# TypeScript設定
+pnpm add -D typescript @types/node
+npx tsc --init
+
+# 共通依存関係
+pnpm add -D vitest ajv
+```
+
+### 2. パッケージ構成
+
+```bash
+# Core package
+mkdir -p packages/core/src/{types,validators,utils}
+cd packages/core && pnpm init
+
+# CLI tool
+mkdir -p tools/cli/src
+cd tools/cli && pnpm init
+
+# 各エディタパッケージ
+mkdir -p packages/{phy-editor,matrix-mapper,keymap-designer}
+```
+
+### 3. 開発ツール設定
+
+```bash
+# Linting & Formatting
+pnpm add -D eslint prettier @typescript-eslint/eslint-plugin
+
+# Testing
+pnpm add -D @vitest/ui
+
+# Build tools
+pnpm add -D tsup
+```
+
+## サンプルプロジェクト設計
+
+### テストケース
+
+1. **60% ANSI** - 標準的なレイアウト
+2. **Split keyboard** - 左右分離型
+3. **Ergonomic layout** - カラムスタッガード + 回転
+4. **Macro pad** - シンプルな4x4
+
+### データ例
+
+#### 60% ANSI PHY Layer
+
+```json
+{
+  "version": "1.0.0",
+  "metadata": {
+    "name": "60% ANSI",
+    "description": "Standard 60% layout"
+  },
+  "profiles": [
+    {
+      "id": "standard",
+      "name": "Cherry MX",
+      "unitSize": { "x": 19.05, "y": 19.05 }
+    }
+  ],
+  "keys": [
+    // Escape key
+    {
+      "id": "k00", "profile": "standard",
+      "position": { "x": 0, "y": 0 },
+      "size": { "width": 1, "height": 1 },
+      "metadata": { "label": "Esc" }
+    },
+    // Space bar
+    {
+      "id": "k60", "profile": "standard", 
+      "position": { "x": 5, "y": 4 },
+      "size": { "width": 6.25, "height": 1 },
+      "metadata": { "label": "Space" }
+    }
+  ]
+}
+```
+
+## 次のアクション
+
+1. **GitHub リポジトリ作成**
+2. **開発環境セットアップ**
+3. **型定義の実装開始**
+4. **KLE変換機能のプロトタイプ**
+
+実装を開始しますか？最初にどの部分から取り組みたいでしょうか？