sesame-kit 0.4.0

package/docs/architecture.ja.md

@@ -0,0 +1,132 @@
+<!-- [English](./architecture.md) | 日本語 -->
+
+# アーキテクチャ / 設計ノート
+
+> English: [architecture.md](./architecture.md)
+
+実装の出自、設計判断、ファイル構成をまとめる。README は使い方を、ここは「なぜそうなっているか」を扱う。
+
+## 出自 (Lineage)
+
+本実装は **公式 biz3 管理 Web (https://github.com/CANDY-HOUSE/biz.candyhouse.co, MIT)** を Node.js に port したもの。主要部の port 関係:
+
+| この実装 | biz3 vendor 元 |
+|---|---|
+| `src/transport.js` | `references_web/src/websocket/WebSocketManager.ts` (window 依存除去、Node `ws` 化、reconnect/keepalive/idle/sleep 検知は biz3 と同値、callback registry は FIFO 化) |
+| `src/auth.js` | `references_web/src/api/useAuthState.js` (Amplify → AWS SDK 直叩きに置換) |
+| `src/lock.js` | `references_web/src/api/useIotCtrl.js` の `sendCommandToWM2` |
+| `src/ir.js` | `references_web/src/api/useRemoteCtrl.js` (hook 内 useCallback から JSON 構築部だけ抽出) |
+| `src/devices.js` | `references_web/src/api/useManageDevice.js` / `useManageGroup.js` / `useDeveloper.js` / `MobileBatteryChart.js` |
+| `src/crypto.js` | `references_web/src/utils/Cmac.js` + `biz3utils.js` + `constants/cmdCode.js` (CMAC は `node-aes-cmac` で実装) |
+
+**biz3 との唯一の機能的相違**: Cognito Client ID を biz3 の `21u50hboia4s5q0sbk6pbdfmss` から、公式
+iOS/Android アプリと同じ Consumer Client `6ialca0p8u0lsgvbmvsljfm305` に差し替え。これにより
+refreshToken が事実上失効しなくなる。biz3 の MIT ライセンス本文は [LICENSE.biz3](../LICENSE.biz3) として同梱。
+
+## クラウド / BLE の統合設計（経路は葉）
+
+クラウドと BLE は公式 SesameSDK と同様、**命令の正体 (itemCode) とデバイス能力モデルを共有**し、
+最後の送信経路 (transport) だけが葉として差し替わる単一設計。
+
+- itemCode は `src/itemcodes.js` の 1 ソース（クラウドは `crypto.js` の `CMD`、BLE は `protocol.js` の
+  `ITEM` という別名で同じものを参照）。
+- 能力は `devicemodel.js` が **型 × 経路** で持つ（各 kind に `cloud:[...]` と `ble:[...]` の op 集合）。
+  **操作できる op = 両者の和集合**で、session の対象・操作メニュー・`pickTransport` の経路選択はすべて
+  この和集合から導く。
+  - 例: ロックは `ble` に autolock があり `cloud` に無い → autolock は BLE 専用。
+  - OS2 ロックは `ble` 空・`cloud` に lock/unlock/toggle → クラウドのみで操作可。
+  - Hub3 は `cloud` に ir/relay/led。
+- 既定は経路を意識しない**全部モード**で、固定したいときだけ `--ble-only` / `--cloud-only`。
+
+## irType の非対称トラップ（自己学習リモコン）
+
+リモコンの種別は整数コード (= 実デバイスの `remote.type`)。主な値: `49152`(0xc000)=エアコン /
+`8192`(0x2000)=テレビ / `57344`=照明 / `32768`=扇風機 / **`65024`(0xFE00)=自己学習**。
+
+⚠️ **学習だけ非対称**: 公式 biz3 のメニューでは各項目に id が振られ、エアコン/テレビ等のプリセットは
+「メニュー id = 実デバイスの type」で一致する。ところが「学習」のメニュー id は `0xFEFF` なのに、学習して
+実際に作られるリモコンの type は **`0xFE00`(65024)**。`0xFEFF` は「学習メニューを押した」という UI 上の印に
+すぎず、デバイスや通信には現れない。**自己学習リモコンを指すときは必ず実 type `0xFE00` を使うこと**
+（`0xFEFF` を渡すとサーバ照合が一致せずリモコンが見つからない）。当ツールは `0xFE00` を採用。
+
+## autolock はクラウド経由では設定できない
+
+autolock (= `SesameItemCode` 11) の設定はクラウド経由では実機に反映されない。`biz3TriggerLocker` は cmd=11 に
+`success:true` を返すが、ロック本体の autolock 秒数は変化しない。biz3 web/SDK にも設定系のクラウド送信経路は無く
+（`useIotCtrl.js` の IoT cmd は ADD/REMOVE_SESAME・LED・RELAY 等のみで autolock は "Unsupported"）、公式アプリは
+autolock を BLE 直送する。よって autolock は BLE の `sesame autolock` のみで提供する。ライブラリには汎用レール
+`lock.triggerItemCommand` / `lock.setAutolock` があるが、クラウドでは lock/unlock/toggle/bot 以外は実機に効かない。
+
+`biz3TriggerLocker` は同期 ack (`{code:200, success:true}`) を返す。`unlock`/`lock`/`toggle`/`bot` は
+この ack で完了判定する (push 待ちのみだと「サーバ受理済みなのに timeout」と誤判定するため)。
+
+## BLE 直接制御の設計
+
+プロトコル層 (`src/ble/protocol.js`: CMAC セッション鍵 / AES-CCM / セグメント / フレーム) と
+セッション層 (`src/ble/session.js`) は **OS 非依存の純 JS**。無線 I/O だけを差し替え可能なアダプタ
+(`src/ble/transport.js`、既定 noble) に閉じ込めてあり、Web Bluetooth 等の別アダプタも注入できる。
+デバイス型モデル (`src/ble/devicemodel.js`) は公式 SesameSDK の `CHProductModel` と能力定義を移植したもので、
+`productType`/`model` → 種別 (lock5/bot2/bike2/…) → 対応操作・mechStatus 解釈を引く。`SesameBle` はこの能力に
+従って操作を許可/拒否する。プロトコルは Android SesameSDK / ESP32 リファレンス実装から移植。
+
+## config の単一 `devices{}` 設計
+
+**デバイスは単一の `devices{}` に丸ごと保存する** — ロック / Bot / Bike / Hub3 を型ごとに分けず、
+サーバの device レコードを (巨大な `stateInfo` を除き) そのまま格納する。型は `deviceModel` から導出し、
+どの操作 view (lock / hub3) に出すかは `category` で分類する。`model`/`secretKey` の取りこぼし
+(Hub3 が「解錠」と誤表示される等) を構造的に防ぐための設計。`remotes` は device ではない子エンティティ
+(親 Hub3 + irType + 学習 keys) なので独立コレクションのまま。
+
+## `sesame serve` 言語非依存バックエンド
+
+1 コア + 5 フレーミングで、単一常駐 `SesameHub3` に全機能を一様公開する。詳細は README の
+[言語非依存バックエンド](../README.ja.md#言語非依存バックエンド-sesame-serve) を参照。
+
+- **コア**: `src/serve/jsonrpc.js`（JSON-RPC 2.0、transport 非依存）+ `registry.js`（`NAMESPACE_OPS` から
+  メソッドを自動公開 + OpenRPC）+ `daemon.js`（直列化 / 購読一元 / 背圧 / shutdown）。
+- **フレーミング**: `framing/` 配下に stdio / socket(UDS) / http(+SSE) / ws / grpc + token。
+- **型抽出**: `scripts/gen-rpc-schema.mjs` が `.d.ts` から param 型を抽出 (`rpc-params.generated.json`)、
+  `scripts/gen-grpc-proto.mjs` が型付き `sesame.proto` を生成。両者は drift-guard テストで保護。
+
+## ファイル構成
+
+```
+sesame-kit/
+├── package.json
+├── README.md
+├── docs/                   # commands / architecture / library / migration
+├── LICENSE
+├── LICENSE.biz3
+├── bin/
+│   └── sesame.js           # CLI 実行エントリ
+├── clients/                # sesame serve に繋ぐ薄い公式クライアント (依存ゼロ)
+│   ├── python/sesame_client.py   #   UDS/stdio/HTTP + イベント購読
+│   └── js/sesame-client.mjs      #   同等 (Node 18+)
+├── vendor/
+│   └── biz3/constants/     # biz3 の import-zero 定数を逐語コピー (single source of truth)
+└── src/
+    ├── index.js            # 公開ライブラリエントリ
+    ├── cli.js              # commander 実装 (基本コマンド + makeCtx)
+    ├── cli/                # 機能別コマンド配線 (registerXxxCommands)
+    │   └── serve.js        #   sesame serve … (常駐 JSON-RPC バックエンド配線)
+    ├── serve/              # 言語非依存バックエンド (1 コア + 5 フレーミング)
+    │   ├── jsonrpc.js      #   JSON-RPC 2.0 プロトコルコア (transport 非依存)
+    │   ├── registry.js     #   メソッドカタログ (NAMESPACE_OPS から自動公開) + OpenRPC
+    │   ├── daemon.js       #   単一常駐 hub への多重化 (直列化/購読/背圧/shutdown)
+    │   ├── sesame.proto    #   gRPC 型付き定義 (生成物)
+    │   └── framing/        #   stdio / socket(UDS) / http(+SSE) / ws / grpc + token
+    ├── client.js           # SesameHub3 高レベルクラス (namespace getter で op を自動注入)
+    ├── transport.js        # Hub3WsClient (reconnect/keepalive/queue/sleep)
+    ├── auth.js             # Cognito CUSTOM_AUTH + REFRESH_TOKEN_AUTH + jwtSub
+    ├── crypto.js           # AES-CMAC + uuid→base64 + cmd code 定数
+    ├── lock.js / ir.js / presetir.js / sharekey.js   # ドメイン op
+    ├── ble/                # BLE 直接制御 (OS非依存コア + 差し替え可能トランスポート)
+    │   ├── protocol.js     #   純JS: CMAC鍵/AES-CCM/セグメント/フレーム/mechStatus
+    │   ├── session.js      #   状態機械 (initial→login→コマンド応答)
+    │   ├── transport.js    #   noble アダプタ (optionalDependency, 遅延require)
+    │   └── index.js        #   SesameBle ファサード
+    ├── iot.js / account.js / schedule.js / org.js / company.js / access.js / devices.js
+    ├── config.js           # ConfigStore (~/.config/sesame-hub3/config.json)
+    ├── tokens.js           # FileTokenStore
+    └── paths.js            # 設定ディレクトリ解決
+```

package/docs/architecture.md

@@ -0,0 +1,105 @@
+<!-- English | [日本語](./architecture.ja.md) -->
+
+# Architecture / Design Notes
+
+> 日本語: [architecture.ja.md](./architecture.ja.md)
+
+This document covers the lineage of the implementation, the design decisions, and the file layout. The README covers usage; this covers why things are the way they are.
+
+## Lineage
+
+This implementation is a Node.js port of the **official biz3 admin web app (https://github.com/CANDY-HOUSE/biz.candyhouse.co, MIT)**. The port mapping for the main parts:
+
+| This implementation | biz3 vendor source |
+|---|---|
+| `src/transport.js` | `references_web/src/websocket/WebSocketManager.ts` (window dependency removed, switched to Node `ws`; reconnect/keepalive/idle/sleep detection identical to biz3; callback registry made FIFO) |
+| `src/auth.js` | `references_web/src/api/useAuthState.js` (Amplify replaced with direct AWS SDK calls) |
+| `src/lock.js` | `sendCommandToWM2` in `references_web/src/api/useIotCtrl.js` |
+| `src/ir.js` | `references_web/src/api/useRemoteCtrl.js` (only the JSON-building part extracted from the hook's useCallback) |
+| `src/devices.js` | `references_web/src/api/useManageDevice.js` / `useManageGroup.js` / `useDeveloper.js` / `MobileBatteryChart.js` |
+| `src/crypto.js` | `references_web/src/utils/Cmac.js` + `biz3utils.js` + `constants/cmdCode.js` (CMAC implemented with `node-aes-cmac`) |
+
+**The only functional difference from biz3**: the Cognito Client ID is swapped from biz3's `21u50hboia4s5q0sbk6pbdfmss` to the same Consumer Client as the official iOS/Android apps, `6ialca0p8u0lsgvbmvsljfm305`. This keeps the refreshToken from effectively expiring. The biz3 MIT license text is bundled as [LICENSE.biz3](../LICENSE.biz3).
+
+## Unified cloud / BLE design (the route is the leaf)
+
+Like the official SesameSDK, cloud and BLE **share the underlying command (itemCode) and the device capability model**; only the final send route (transport) is swapped as a leaf. This is a single design.
+
+- itemCode has one source in `src/itemcodes.js` (the cloud refers to it as `CMD` in `crypto.js`, BLE as `ITEM` in `protocol.js` — different aliases for the same thing).
+- Capability is held by `devicemodel.js` as **type × route** (each kind has a `cloud:[...]` and a `ble:[...]` op set).
+  The **operable ops = the union of the two**, and the session's targets, operation menu, and `pickTransport` route selection are all derived from this union.
+  - Example: a lock has autolock under `ble` but not `cloud` → autolock is BLE-only.
+  - An OS2 lock has an empty `ble` set and lock/unlock/toggle under `cloud` → operable via cloud only.
+  - Hub3 has ir/relay/led under `cloud`.
+- The default is a **full mode** that is unaware of the route; pin it with `--ble-only` / `--cloud-only` only when desired.
+
+## The irType asymmetry trap (self-learned remote)
+
+A remote's kind is an integer code (= the device's `remote.type`). Main values: `49152` (0xc000) = air conditioner / `8192` (0x2000) = TV / `57344` = light / `32768` = fan / **`65024` (0xFE00) = self-learned**.
+
+⚠️ **Only learning is asymmetric**: in the official biz3 menu, each item has an id, and presets such as air conditioner / TV match by "menu id = device type." However, the "learn" menu id is `0xFEFF`, while the type of the remote actually created by learning is **`0xFE00` (65024)**. `0xFEFF` is only a UI-side marker for "the learn menu was pressed"; it never appears on the device or in communication. **Always use the real type `0xFE00` when referring to a self-learned remote** (passing `0xFEFF` fails the server-side match and the remote is not found). This tool uses `0xFE00`.
+
+## autolock cannot be set over the cloud
+
+Setting autolock (= `SesameItemCode` 11) over the cloud is not reflected on the physical device. `biz3TriggerLocker` returns `success:true` for cmd=11, but the lock's actual autolock duration does not change. biz3 web/SDK has no cloud send route for settings either (the IoT cmds in `useIotCtrl.js` are only ADD/REMOVE_SESAME, LED, RELAY, etc., and autolock is "Unsupported"), and the official app sends autolock directly over BLE. autolock is therefore provided only via BLE's `sesame autolock`. The library has the generic rails `lock.triggerItemCommand` / `lock.setAutolock`, but over the cloud only lock/unlock/toggle/bot take effect on the device.
+
+`biz3TriggerLocker` returns a synchronous ack (`{code:200, success:true}`). `unlock`/`lock`/`toggle`/`bot` use this ack to determine completion (waiting on the push alone would wrongly report a timeout even though the server already accepted the command).
+
+## BLE direct control design
+
+The protocol layer (`src/ble/protocol.js`: CMAC session key / AES-CCM / segments / frames) and the session layer (`src/ble/session.js`) are **OS-independent pure JS**. Only the radio I/O is confined to a swappable adapter (`src/ble/transport.js`, noble by default); an alternate adapter such as Web Bluetooth can also be injected. The device type model (`src/ble/devicemodel.js`) ports the capability definitions of the official SesameSDK's `CHProductModel`, mapping `productType`/`model` → kind (lock5/bot2/bike2/…) → supported operations and mechStatus interpretation. `SesameBle` allows or rejects operations according to this capability. The protocol is ported from the Android SesameSDK / ESP32 reference implementation.
+
+## The single `devices{}` config design
+
+**Devices are stored whole in a single `devices{}`** — locks / Bots / Bikes / Hub3 are not split by type; the server's device record is stored as-is (minus the huge `stateInfo`). The type is derived from `deviceModel`, and which operation view (lock / hub3) it appears in is classified by `category`. This design structurally prevents dropped `model`/`secretKey` (e.g., a Hub3 being mislabeled as "unlocked"). `remotes` is a child entity, not a device (parent Hub3 + irType + learned keys), so it stays an independent collection.
+
+## `sesame serve` language-agnostic backend
+
+With 1 core + 5 framings, the full feature set is uniformly exposed on a single resident `SesameHub3`. See the README's [language-agnostic backend](../README.md#language-agnostic-backend-sesame-serve) for details.
+
+- **Core**: `src/serve/jsonrpc.js` (JSON-RPC 2.0, transport-independent) + `registry.js` (auto-exposes methods from `NAMESPACE_OPS` + OpenRPC) + `daemon.js` (serialization / unified subscription / backpressure / shutdown).
+- **Framing**: stdio / socket(UDS) / http(+SSE) / ws / grpc + token under `framing/`.
+- **Type extraction**: `scripts/gen-rpc-schema.mjs` extracts param types from `.d.ts` (`rpc-params.generated.json`), and `scripts/gen-grpc-proto.mjs` generates a typed `sesame.proto`. Both are protected by drift-guard tests.
+
+## File layout
+
+```
+sesame-kit/
+├── package.json
+├── README.md
+├── docs/                   # commands / architecture / library / migration
+├── LICENSE
+├── LICENSE.biz3
+├── bin/
+│   └── sesame.js           # CLI entry point
+├── clients/                # thin official clients that connect to sesame serve (zero dependencies)
+│   ├── python/sesame_client.py   #   UDS/stdio/HTTP + event subscription
+│   └── js/sesame-client.mjs      #   equivalent (Node 18+)
+├── vendor/
+│   └── biz3/constants/     # verbatim copy of biz3's import-zero constants (single source of truth)
+└── src/
+    ├── index.js            # public library entry
+    ├── cli.js              # commander implementation (basic commands + makeCtx)
+    ├── cli/                # per-feature command wiring (registerXxxCommands)
+    │   └── serve.js        #   sesame serve … (resident JSON-RPC backend wiring)
+    ├── serve/              # language-agnostic backend (1 core + 5 framings)
+    │   ├── jsonrpc.js      #   JSON-RPC 2.0 protocol core (transport-independent)
+    │   ├── registry.js     #   method catalog (auto-exposed from NAMESPACE_OPS) + OpenRPC
+    │   ├── daemon.js       #   multiplexing onto a single resident hub (serialization/subscription/backpressure/shutdown)
+    │   ├── sesame.proto    #   gRPC typed definition (generated)
+    │   └── framing/        #   stdio / socket(UDS) / http(+SSE) / ws / grpc + token
+    ├── client.js           # SesameHub3 high-level class (auto-injects ops via namespace getters)
+    ├── transport.js        # Hub3WsClient (reconnect/keepalive/queue/sleep)
+    ├── auth.js             # Cognito CUSTOM_AUTH + REFRESH_TOKEN_AUTH + jwtSub
+    ├── crypto.js           # AES-CMAC + uuid→base64 + cmd code constants
+    ├── lock.js / ir.js / presetir.js / sharekey.js   # domain ops
+    ├── ble/                # BLE direct control (OS-independent core + swappable transport)
+    │   ├── protocol.js     #   pure JS: CMAC key/AES-CCM/segment/frame/mechStatus
+    │   ├── session.js      #   state machine (initial→login→command response)
+    │   ├── transport.js    #   noble adapter (optionalDependency, lazy require)
+    │   └── index.js        #   SesameBle facade
+    ├── iot.js / account.js / schedule.js / org.js / company.js / access.js / devices.js
+    ├── config.js           # ConfigStore (~/.config/sesame-hub3/config.json)
+    ├── tokens.js           # FileTokenStore
+    └── paths.js            # config directory resolution
+```

package/docs/commands.ja.md

@@ -0,0 +1,316 @@
+<!-- [English](./commands.md) | 日本語 -->
+
+# コマンドリファレンス
+
+> English: [commands.md](./commands.md)
+
+> CLI の全コマンド。各サブコマンドは `sesame <cmd> --help` でも引けます。
+> `sesame serve` 経由で他言語から叩く場合は `sesame rpc`（または `rpc.discover`）が機械可読な真実の源です。
+
+## デバイス操作（デバイス主語）
+
+主語は**デバイス**です。`sesame <device> <action>` は SDK の `device.action()` と同じ並び。
+device は名前（部分一致可）。action 省略でそのデバイスの対話メニュー、device も省略で全デバイスの
+対話メニュー（＝ `session`）。
+
+```bash
+sesame front unlock            # front.unlock()  (部分一致可: sesame 玄関 unlock)
+sesame front lock              # 施錠
+sesame front toggle            # 現在状態で反転
+sesame front status            # 状態 (施錠/解錠・位置)
+sesame front autolock 30       # オートロック (BLE 必須。0=無効)
+sesame kitchen click           # SESAME Bot クリック (Bot2/Bot3)
+
+sesame front                   # front の対話メニュー
+sesame                         # 全デバイスの対話メニュー (session)
+```
+
+action: `unlock` / `lock` / `toggle` / `click` / `status` / `autolock <秒>`（**使える操作は型で変わる** — 後述）。
+
+### 経路 (transport) は「全部モード」が既定
+
+- 既定は全部モード。経路は自動で選ばれる。cloud で運べる op は cloud、`autolock` のような BLE 必須の op だけ BLE 接続する (BLE のスキャン/接続コストを毎回は払わない)。
+- `--ble-only` / `--cloud-only` で経路を固定する。`--ble-only` は接続に数秒かかる。`--cloud-only` は一部操作が制限される。
+- BLE 接続を保持して連続操作するモードは `sesame session` (= `sesame <device>` の複数版)。
+
+```bash
+sesame front unlock            # 全部モード (ツールが経路を選ぶ)
+sesame front autolock 30       # BLE 必須の op → 自動で BLE 接続
+sesame front lock --ble-only   # BLE に固定 (接続に数秒)
+sesame front lock --cloud-only # クラウドに固定
+```
+
+> 設計の詳細（クラウド/BLE の能力モデル統合）は [architecture.md](./architecture.ja.md) を参照。
+
+ロック定義の管理は `locks` グループ:
+
+```bash
+sesame locks ls                # 登録ロック一覧
+sesame locks set-default front
+sesame locks add               # 対話で追加 (deviceUUID + secretKey)
+sesame locks add --name front --uuid <UUID> --secret <32hex> --model sesame_5_pro  # 非対話/フラグ追加
+sesame locks sync-from-devices # devices の結果から自動取り込み
+sesame locks rm front
+```
+
+クラウド操作の応答は同期 ack (`biz3TriggerLocker`, `success:true`) を待ってから戻ります (timeout 10s)。
+
+> autolock はクラウド経由では設定できません (BLE のみ)。`sesame autolock` を使ってください。背景は [architecture.md](./architecture.ja.md)。
+
+---
+
+## Hub3 IR
+
+### 既存キーの発射
+
+```bash
+sesame send 停止                         # デフォルトリモコンで発射
+sesame send 停止 --remote ac
+sesame list                              # リモコンに登録されているキー一覧
+```
+
+### 高度な操作
+
+```bash
+# 学習: 物理リモコンを Hub3 に向けてボタンを押す
+sesame ir learn ac 強風                  # remote=ac に "強風" キーを学習登録
+                                         # → Hub3 を REGISTER モード → 波形捕捉 → CONTROL に戻し → addIRCode
+
+# モード制御
+sesame ir mode get [hub3]                # 現在モード取得 (0=CONTROL / 1=REGISTER)
+sesame ir mode set 1 [hub3]              # 強制 REGISTER 切替 (デバッグ用)
+
+# キー CRUD
+sesame ir key rename ac 強風 強運転        # キー名変更 (server + config)
+sesame ir key rm ac 試運転                # キー削除
+
+# リモコン CRUD (server 側)
+sesame ir remote-list ac              # 登録済みリモコン (irType 指定)
+sesame ir remote-rm ac                   # server から削除
+sesame ir remote-rename "リビング" ac      # server alias 変更
+
+# プリセット DB
+sesame ir search ac ダイキン           # メーカー DB 検索 (max 1000)
+sesame ir match ac <hex波形>           # 学習波形 → 既知リモコン照合
+```
+
+> 自己学習リモコンを指すときは `irType` に実 type `0xFE00`(65024) を使う。メニュー id の `0xFEFF` を渡すと
+> サーバ照合が一致せずリモコンが見つからない。詳細は [architecture.md](./architecture.ja.md)。
+
+---
+
+## デバイス管理
+
+```bash
+sesame device user-ls                    # 個人デバイス一覧
+sesame device status <uuid>              # 現在状態
+sesame device rename <uuid> "玄関 SESAME"  # 名前変更
+sesame device rm <uuid>                  # company から削除
+
+sesame history <uuid>                    # ロック開閉履歴
+sesame history                           # 全デバイス
+sesame battery <uuid>                    # 電池履歴 (light/heavy 電圧 + 割合)
+sesame firmware                          # 配信中ファームウェア一覧
+```
+
+---
+
+## WebAPI proxy
+
+biz3 dev console で発行する REST API key (apiKeyId) を `config.apiKeyId` に設定すると、任意の REST WebAPI を WebSocket 経由で proxy 呼び出しできる:
+
+```bash
+# config.json に "apiKeyId": "..." を入れた状態で:
+sesame webapi webapi_ssm_shadow_get --query '{"device_id":"..."}'
+sesame webapi webapi_history_get --query '{"device_id":"...","page":0,"lg":"ja","isBiz":true}'
+sesame webapi webapi_cmd_send --body '{"device_id":"...","cmd":83,"sign":"...","history":"..."}'
+```
+
+---
+
+## 予約スケジュール (biz3Schedule)
+
+```bash
+sesame schedule ls                 # 登録済み予約 (lock/unlock/upgrade_firmware) 一覧
+sesame schedule cancel <id>        # 予約を取消 (id 省略時は一覧から対話選択)
+```
+
+> 予約の **新規作成 op は biz3 web に存在しない** ため、CLI も list / cancel のみ。
+
+---
+
+## アクセス制御 (NFC カード / 暗証番号)
+
+SESAME Touch (Pro) の NFC カード・キーパッド暗証番号の **サーバ DB 同期** op 群。
+実機ファームウェアへの書き込みは別系統 (BLE) で、ここは DB 側の同期のみを扱う 2 層構造。
+
+```bash
+sesame access cards ls --device <uuid> [--device <uuid2> ...]   # カード一覧
+sesame access cards clear --device <uuid>                       # 指定デバイスのカード全削除
+sesame access cards rm --json '[{"deviceID":"...","cardID":"..."}]'   # 個別削除 (応答なし)
+sesame access cards owner <cardID> [ownerSubUUID]               # 所有者割当 ('' で解除)
+sesame access passcodes ls --device <uuid>                      # 暗証番号一覧
+```
+
+> `rm` (delCards/delPasscodes) は biz3 に応答ハンドラが無く **fire-and-forget**。完了応答は返らない。
+
+---
+
+## 会社 / 組織管理 (biz3 enterprise)
+
+複数会社・社員・役割・デバイスグループを扱う法人向け機能。`companyID` はログイン情報から自動補完される。
+
+```bash
+# 会社
+sesame company ls                  # 所属会社一覧
+sesame company rename "新社名"      # 優先会社の改名
+sesame company add "新会社"         # 会社を新規登録
+sesame company payment             # 課金設定取得
+
+# 組織 (org)
+sesame org employee ls             # 社員一覧
+sesame org employee search <kw>    # CS 横断のユーザー検索
+sesame org role ls                 # 役割タグ一覧
+sesame org group ls                # 社員グループ一覧
+sesame org device-group ls         # デバイスグループ一覧
+sesame org keys device <deviceUUID>   # デバイス側の鍵保有従業員を列挙
+```
+
+### ゲスト共有 (鍵共有 URL / QR)
+
+SESAME アプリが読む共有 QR と同じ `ssm://UI?t=sk&sk=…&l=…&n=…` URL を生成する。
+`--level 2` (ゲスト) のときだけ使い捨て `guestKeyId` を発行して埋め込む (biz3 と同じ挙動)。
+
+```bash
+sesame org keys share-url --device <uuid> --level 2 --name "来客用"   # ゲスト共有 URL
+sesame org keys share-url --device <uuid> --level 1                  # マネージャ鍵共有
+sesame org keys share-url --device <uuid> --qr                       # 端末に QR 表示 (要 qrcode-terminal)
+```
+
+> 共有 URL の組み立て・解析は biz3 `generateInviteGuestQRCodeByInfo` / `readQrcode` を 1:1 移植。
+> **画像化ライブラリ非依存**で、出力 URL を任意の QR 生成器に貼っても共有できる。
+> 作成/更新系の多くは構造体を `--json '<…>'` で受ける（各サブコマンドの `--help` に例あり）。
+> `org employee confirm <email>` は biz3 仕様上、成功時に現セッションを signout する点に注意。
+
+---
+
+## Hub3 IoT 制御 (biz3OperateIoT)
+
+Hub3 本体への直接コマンド (LED 調光・LTE リレー・ファーム更新・Matter ペアリング等)。
+`--device <hub3UUID> --secret <hex>` を渡すか、対話時は接続デバイスから選択。
+
+```bash
+sesame iot led 80 --device <uuid> --secret <hex>   # LED 調光 (0-100)
+sesame iot led --get --device <uuid> --secret <hex># 現在の調光取得
+sesame iot relay on  --device <uuid> --secret <hex># LTE リレー開閉
+sesame iot firmware-update --device <uuid> --secret <hex> --wait 60
+sesame iot matter-code --device <uuid> --secret <hex>   # Matter ペアリングコード
+```
+
+---
+
+## プリセット IR リモコン (HXD command)
+
+エアコン等を「学習」ではなく **プリセット DB の命令で** 発射する。Hub3 を `--device` に指定:
+
+```bash
+sesame preset-ir air --device <hub3uuid> --code <n> --power --temp 26 --mode 1 --fan 2
+sesame preset-ir button --device <hub3uuid> --code <n> --button power --irtype 8192
+sesame preset-ir send --device <hub3uuid> --command <hex> --irtype 49152   # 生 hex 発射
+```
+
+> プリセットの command 生成 (biz3 の HXDCommandProcessor) は未移植のため、プリセット発射は現状機能しません。
+> 自己学習リモコン (`sesame ir learn`) を使ってください（[既知の制限](../README.ja.md#健全性--既知の制限)）。
+
+---
+
+## BLE 直接制御 (クラウド非経由)
+
+PC の Bluetooth から登録済み SESAME を**直接**操作する。クラウド (WS) を介さないので
+オフラインでも動き、**クラウドでは不可だった `autolock` 等の設定系が実機に反映される**。
+
+BLE 操作は専用コマンドではなく、デバイス主語の操作に **`--ble-only` を付ける**だけ
+（`autolock` は BLE 必須なので無指定でも自動で BLE）:
+
+```bash
+sesame front status --ble-only   # 現在状態 (施錠/解錠, 位置)
+sesame front unlock --ble-only   # 解錠 (ロック/Bike)
+sesame front lock   --ble-only   # 施錠 (ロック)
+sesame front toggle --ble-only   # 状態を見て反転 (ロック)
+sesame kitchen click --ble-only  # SESAME Bot のクリック (Bot2/Bot3)
+sesame front autolock 30         # オートロック (BLE 必須。本当に効く)
+sesame front autolock 0          # 無効化
+```
+
+> **BLE エラーは `SesameResultCode` で意味づけ済み** — デバイスが非 0 の結果を返すと、ライブラリは
+> `BleResultError`（`.resultCode` / `.resultName`）を投げる。`resultName` は公式 SesameSDK の
+> `SesameResultCode`（`success`/`invalidFormat`/`notSupported`/`invalidSig`/`notFound`/`unknown`/
+> `busy`/`invalidParam`/`invalidAction`）に一致し、機械的に分岐できる。
+> 注: これは**デバイス層 (SesameOS3) の taxonomy** で、BLE 直接経路でのみ取得できる
+> (クラウド経路はこの code を surface しないため `sesame serve` の `kind` には乗らない)。
+
+### デバイス型ごとの操作 (公式 SesameSDK 準拠)
+
+操作セットはデバイスの種別で異なる。SDK では能力が型ごとに非対称に定義されており、本 CLI もそれを `config` の
+`model` から判定して同じ非対称性を再現する。対応外の操作はコマンドが拒否される（例: Bot に `lock` → 「click を使え」）。
+
+| 種別 (model 例) | BLE 操作 | mechStatus |
+|---|---|---|
+| ロック `sesame_5`/`_pro`/`sesame_6`/`_pro`/`_us`/`miwa` | `lock` `unlock` `toggle` `autolock` `status` | 施錠/解錠 + 位置 |
+| Bot `bot_2`/`bot_3` | `click` `status` | 施錠/解錠 (位置なし) |
+| Bike `bike_2`/`bike_3` | `unlock` `status` | 施錠/解錠 (位置なし) |
+| Touch/Face/Sensor/Remote, Hub3, WiFiModule2 | (BLE 施錠操作なし) | — |
+| OS2 `sesame_2`/`_4`, `ssmbot_1`, `bike_1` | BLE 未実装 (鍵導出/暗号が別系統)。クラウド経由で操作 | — |
+
+> 「施錠/解錠」は OS3 では `isInLockRange` の有無による **2 値**のみ。OS3 に中間状態 (moved) は無い
+> (Sesame2 等 OS2 系のみ moved を持つ)。BLE 実装の設計は [architecture.md](./architecture.ja.md) を参照。
+
+ライブラリとしても利用可:
+
+```js
+import { SesameBle } from "sesame-kit";   // or: import { ble } from "sesame-kit"
+await SesameBle.use({ deviceUUID, secretKey }, async (lock) => {
+  await lock.unlock();
+  await lock.autolock(30);
+  console.log(lock.lastStatus);            // { state, batteryMv, position, ... }
+});
+```
+
+> 対象は **SesameOS3** (SESAME 5 / 5 Pro / Touch 等)。新規ペアリング (未登録デバイスの登録) は別フェーズ。
+
+---
+
+## 対話セッション
+
+対話セッション（`sesame` / `sesame <device>` / `sesame session`）は**アプリ的な全部モード**です。
+**操作できるデバイスを全部**載せます: ロック/Bot/Bike（BLE+クラウド）と、ログイン済みなら **Hub3**（クラウド: IR 送信 / リレー / LED）。
+BLE を best-effort で張りつつ、**BLE が 0 でも終了しません**: 圏外/権限なしのデバイスはログイン済みなら
+**クラウドで操作**します（BLE が張れたデバイスは BLE を優先＝低遅延＋autolock 可）。
+
+```text
+$ sesame                      # 全デバイス (alias: sesame session / watch)
+[ble] バックグラウンドで接続中... (クラウドで操作可能)
+─── SESAME セッション ── 矢印キーで選択 ───
+  front   [sesame_5·BLE]:   state=locked pos=-176
+  kitchen [bot_2·cloud]:    (BLE未接続)
+  hub3-居間 [hub3·hub3]:    (Hub3: IR / リレー / LED)
+
+? 操作するデバイス          ← ① デバイスを選ぶ
+? front の操作              ← ② 操作を選ぶ (型で変わる)
+  ロック  : 🔓 解錠 / 🔒 施錠 / ↕ トグル / ⏱ オートロック / ℹ 状態
+  Bot     : 👆 クリック / ℹ 状態
+  Hub3    : 📡 IR 送信 (リモコン→キー選択) / 🔌 リレー ON/OFF / 💡 LED 調光
+```
+
+各デバイスの末尾タグ `·BLE` / `·cloud` が経路。**`autolock` は BLE 必須**なので、cloud のデバイスでは
+「近づいて再試行」と案内します。接続が 1 個だけならデバイス選択を省略。
+
+**ライブ更新**: 画面は **Ink (React for CLI)** 製のライブダッシュボードで、BLE の状態変化や
+バックグラウンド接続の完了を受けて**その場で再描画**します（cloud→BLE への昇格もリアルタイム）。
+起動はクラウドで即メニュー表示し、BLE は裏で接続するので 8 秒のスキャンを待ちません。終了は `q` / Esc。
+
+**前提**:
+- 鍵は既存の `config.locks`（`sesame locks sync-from-devices` で取り込んだ deviceUUID/secretKey）を再利用。新規登録は不要。
+- BLE アダプタ `@abandonware/noble` が必要。`optionalDependency` なので `npm install` で**自動導入**を試み、未対応環境でもインストール自体は壊れない (BLE だけ無効)。手動で入れるなら `npm i @abandonware/noble`。
+- **macOS は Terminal/iTerm に Bluetooth 権限が必要**（システム設定 → プライバシーとセキュリティ → Bluetooth）。
+- ロックの BLE 圏内（近接）にいること。