sesame-kit 0.4.1 → 0.5.0

package/README.ja.md

@@ -8,9 +8,9 @@
 
 > **ステータス** — pre-1.0 でありバグが残っている可能性があります。実運用で概ね安定が確認できた時点で 1.0 にします。依存する場合はバージョンを固定してください。
 >
-> **免責** — 非公式。CANDY HOUSE とは無関係で、公式の承認も受けていません。公式アプリと同じ方法でクラウド API を叩くため、予告なく変更・破損する可能性があります。`secretKey` とトークンはロックの全権を握るので外部に漏らさないでください。自己責任で利用してください。
+> **免責** — 非公式。CANDY HOUSE とは無関係・非公認であり、非公式クライアントの利用は同社の利用規約の範囲外となる可能性があります。公式アプリと同じ方法でクラウド API を叩くため、予告なく変更・破損する可能性があります。`secretKey` とトークンはロックの全権を握り、`~/.config/sesame-kit` に暗号化されず保存されるので外部に漏らさないでください。自己責任で利用してください。
 
-公式 SESAME iOS / Android アプリと同じ Cognito Consumer Client で、SESAME クラウドの WebSocket API を叩く Node.js 実装。ロックの開閉、Hub3 IR の発射・学習、デバイス管理、開閉履歴、電池残量を CLI とライブラリで提供する。`sesame serve` を使えば全機能を JSON-RPC として公開し、任意の言語から組み込める。
+**公式 SESAME アプリでできる操作を、あなたのコードから。** `sesame-kit` は登録済みの SESAME デバイスを公式 iOS / Android アプリと同じように操作します — 施錠 / 解錠、Hub3 IR（発射・学習）、デバイス管理、開閉履歴、電池残量。CLI、Node ライブラリ、`sesame serve`（JSON-RPC）で任意の言語から呼べます。`npm install` して、スクリプトやホームオートメーション、自作アプリに SESAME を組み込みましょう。
 
 ## 何ができるか
 
@@ -21,21 +21,21 @@
 - アクセス制御: NFC カード / キーパッド暗証番号の DB 同期
 - 予約 / 会社・組織: スケジュール、法人機能 (社員・役割・デバイスグループ・鍵共有)
 - Hub3 IoT: LED 調光、LTE リレー、ファーム更新、Matter ペアリング
-- BLE 直接制御: Bluetooth でロックを直接操作する。autolock 等の設定系は BLE でのみ実機に反映される
-- 言語非依存バックエンド: `sesame serve` が全機能を stdio / UDS / HTTP / WS / gRPC に JSON-RPC として公開する
+- BLE 直接制御: Bluetooth でロックを直接操作します。autolock 等の設定系は BLE でのみ実機に反映されます
+- 言語非依存バックエンド: `sesame serve` が全機能を stdio / UDS / HTTP / WS / gRPC に JSON-RPC として公開します
 - 対話モード、ライブラリ API
 
-詳細は [コマンドリファレンス](./docs/commands.ja.md) / [ライブラリ利用](./docs/library.ja.md) / [設計ノート](./docs/architecture.ja.md) を参照。
+詳細は [コマンドリファレンス](./docs/ja/commands.md) / [ライブラリ利用](./docs/ja/library.md) / [設計ノート](./docs/ja/architecture.md) を参照してください。
 
 ## 出自 (Lineage)
 
-公式 biz3 管理 Web ([CANDY-HOUSE/biz.candyhouse.co](https://github.com/CANDY-HOUSE/biz.candyhouse.co), MIT) の Node.js port。biz3 との差分は Cognito Client ID を公式 iOS / Android アプリと同じ Consumer Client にした点のみで、これにより refreshToken が事実上失効しない。biz3 の MIT ライセンスは [LICENSE.biz3](./LICENSE.biz3) に同梱する。port 対応表は [docs/architecture.md](./docs/architecture.ja.md) を参照。
+公式 biz3 管理 Web ([CANDY-HOUSE/biz.candyhouse.co](https://github.com/CANDY-HOUSE/biz.candyhouse.co), MIT) の Node.js port。biz3 との差分は Cognito Client ID を公式 iOS / Android アプリと同じ Consumer Client にした点のみで、これにより refreshToken が事実上失効しません。biz3 の MIT ライセンスは [LICENSE.biz3](./LICENSE.biz3) に同梱します。port 対応表は [docs/ja/architecture.md](./docs/ja/architecture.md) を参照してください。
 
 ---
 
 ## インストール
 
-要件は Node.js 18 以上 (ESM / `node:` プロトコルを使用)。
+要件は Node.js 18 以上です (ESM / `node:` プロトコルを使用)。
 
 ```bash
 npm install -g sesame-kit     # グローバル CLI: `sesame ...`
@@ -54,50 +54,54 @@ cd sesame-kit && npm install && npm link
 
 ## セットアップ
 
-`login` と `verify` で認証する。`verify` は companyID・ロック・Hub3 IR を自動で取り込む。
+デバイスは公式 SESAME アプリで先に登録済みである必要があります。本ツールは既存デバイスを操作するもので、新規ペアリングは行いません。
+
+`login` と `verify` で認証します。`verify` はデバイスを**鍵ごと**（companyID・Hub3 IR リモコンも）`~/.config/sesame-kit/` に取り込むので、以後 `sesame <device> <action>` は追加の鍵設定なしで動きます。
 
 ```bash
-sesame init                 # 設定ディレクトリ初期化 (~/.config/sesame-hub3/)
+sesame init                 # 設定ディレクトリ初期化 (~/.config/sesame-kit/)
 sesame login your@email.com # email に確認コードを送る
-sesame verify               # コードを入力。companyID / ロック / Hub3 IR を取り込む
+sesame verify               # コードを入力。デバイスを鍵ごと取り込む
+sesame devices              # 取り込んだデバイスと名前を一覧 (以降この名前を使う)
 ```
 
-デバイスを後から追加したら `sesame setup` で取り込みを再実行する。
-IR を使うには Hub3 と Remote の両方の登録が必要。ロック開閉だけなら Lock の登録だけでよい。
+公式アプリでデバイスを後から追加したら `sesame setup` で取り込みを再実行します。
+IR を使うには Hub3 と Remote の両方が登録済みである必要があります。ロック開閉だけなら Lock だけでよいです。
 
 ---
 
 ## 基本操作
 
-主語はデバイス: `sesame <device> <action>` (device は部分一致)。
+引数なしで `sesame` を実行すると対話メニューが出ます。デバイスと各デバイスで使える操作が一覧されます。
+
+```bash
+sesame                         # デバイス→操作を選ぶ。  ↑↓ 移動 · → 決定 · ← 戻る · q 終了
+```
+
+操作を直接指定する場合、主語はデバイスです: `sesame <device> <action>`。`sesame devices` で出た自分のデバイス名を使います（部分一致。下の `front` は例）。
 
 ```bash
 sesame front unlock            # 解錠 (部分一致: sesame 玄関 unlock)
 sesame front lock              # 施錠
-sesame front toggle            # 現在状態で反転
 sesame front status            # 状態 (施錠 / 解錠・位置)
 sesame front autolock 30       # オートロック (BLE 必須。0=無効)
 sesame send 停止 --remote ac   # Hub3 IR 発射
-sesame                         # 全デバイスの対話メニュー (session)
 ```
 
-経路 (cloud / BLE) は自動で選ばれる。固定するときは `--ble-only` / `--cloud-only` を付ける。
-IR 学習・デバイス管理・予約・アクセス制御・会社組織・IoT・BLE の全コマンドは [docs/commands.md](./docs/commands.ja.md) を参照。
-
-### 対話モード
+経路 (cloud / BLE) は既定で自動選択されます（"auto" モード）。固定するときは `--ble-only` / `--cloud-only` を付けます。
+全コマンドは [CLI リファレンス](./docs/ja/commands.md) を参照してください (IR 学習・デバイス管理・予約・アクセス制御・会社組織・IoT・BLE)。
 
-TTY 環境 (`--json` 指定なし) では、足りない引数を矢印キー (↑↓) で選択できる。`sesame` だけでトップメニュー。
-`--json` / 非 TTY では prompt を出さず、引数不足はエラーになる (CI 互換)。
+> TTY では引数不足のコマンドは矢印キーのプロンプトにフォールバックします。`--json` / 非 TTY では prompt を出さず引数不足はエラーです (CI 互換)。
 
 ---
 
 ## JSON 出力契約 (他言語からの subprocess 呼び出し)
 
-`--json` を付けると、subprocess から扱える契約で動く。
+`--json` を付けると、subprocess から扱える契約で動きます。
 
-- 成功: stdout に純 JSON を 1 件だけ出力する (進捗・ログは stderr)。
-- エラー: stderr に `{"error": "...", "code": <n>}` を出し、非 0 で終了する。
-- `--json` / 非対話では prompt を出さず、引数不足は即エラー。
+- 成功: stdout に純 JSON を 1 件だけ出力します (進捗・ログは stderr)。
+- エラー: stderr に `{"error": "...", "code": <n>}` を出し、非 0 で終了します。
+- `--json` / 非対話では prompt を出さず、引数不足は即エラーです。
 - 終了コード: `0`=成功 / `1`=実行時エラー / `2`=使い方エラー。
 
 ```bash
@@ -105,26 +109,26 @@ sesame front status --json        # → stdout: {...}  exit 0
 sesame login --json               # → stderr: {"error":"...","code":1}  exit≠0
 ```
 
-出力 JSON の形は各コマンド固有。互換性の判定には契約バージョンを使う:
+出力 JSON の形は各コマンド固有です。互換性の判定には契約バージョンを使います:
 常駐デーモンの `status` が返す `contractVersion`、または `rpc.discover` の `info["x-contractVersion"]`。
-機械契約の SemVer で、破壊的変更でのみ major が上がる。消費者は major を pin して fail-fast できる。
+機械契約の SemVer で、破壊的変更でのみ major が上がります。消費者は major を pin して fail-fast できます。
 
 ---
 
 ## 言語非依存バックエンド (`sesame serve`)
 
-`sesame serve` は常駐 JSON-RPC 2.0 デーモン。1 回ログインして WS 接続を保持したまま、何度でも op を実行し、
-イベントを push する。全機能を、どの言語からでも同一の API で呼べる。
+`sesame serve` は常駐 JSON-RPC 2.0 デーモンです。1 回ログインして WS 接続を保持したまま、何度でも op を実行し、
+イベントを push します。全機能を、どの言語からでも同一の API で呼べます。
 
 ```bash
-sesame serve                          # Unix socket のみ (既定。~/.config/sesame-hub3/sesame.sock)
+sesame serve                          # Unix socket のみ (既定。~/.config/sesame-kit/sesame.sock)
 sesame serve --stdio                  # 埋め込み: 親が子プロセスとして spawn し stdin/stdout で対話
 sesame serve --http 8080 --ws 8081 --grpc 50051   # ネットワーク経由 (token 認証)
 ```
 
-5 つの繋ぎ口があり、どれも同じメソッドを公開する:
+5 つの接続方式 (トランスポート) があり、どれも同じメソッドを公開します:
 
-| 繋ぎ口 | 用途 | イベント | 認証 |
+| トランスポート | 用途 | イベント | 認証 |
 |---|---|---|---|
 | stdio | 埋め込み (子プロセス) | `event.*` 通知 | 親の信頼を継承 |
 | Unix socket | ローカル常駐・多クライアント | `event.*` 通知 | ファイル権限 0600 |
@@ -132,12 +136,12 @@ sesame serve --http 8080 --ws 8081 --grpc 50051   # ネットワーク経由 (to
 | WebSocket | 全言語 / ブラウザ (全二重) | `event.*` 通知 | token |
 | gRPC | 多言語の型付きスタブ生成 | `Subscribe` ストリーム | token (metadata) |
 
-- メソッドは `rpc.discover` で機械可読に全列挙する (OpenRPC)。param 名・必須・型は実コードから抽出済み。
-- ロック: `lock.lock` / `lock.unlock` / `lock.toggle` / `lock.status`。名前空間 op は `<ns>.<op>` で全公開する (`org.*` / `iot.*` / `access.*` …)。
-- イベント: `events.subscribe {topics:["lockState","deviceUpdate"]}` で以後 `event.<topic>` 通知が届く。
-- エラーは `{error:{code, message, data:{kind}}}`。`kind` は `not_authenticated` / `connection_lost` / `timeout` / `bad_params` / `not_implemented` / `internal` の 6 種。
+- メソッドは `rpc.discover` で機械可読に全列挙します (OpenRPC)。param 名・必須・型は実コードから抽出済みです。
+- ロック: `lock.lock` / `lock.unlock` / `lock.toggle` / `lock.status`。名前空間 op は `<ns>.<op>` で全公開します (`org.*` / `iot.*` / `access.*` …)。
+- イベント: `events.subscribe {topics:["lockState","deviceUpdate"]}` で以後 `event.<topic>` 通知が届きます。
+- エラーは `{error:{code, message, data:{kind}}}`。`kind` は `not_authenticated` / `connection_lost` / `timeout` / `bad_params` / `not_implemented` / `internal` の 6 種です。
 
-別端末で `sesame serve` を起動しておけば、`sesame rpc` が UDS 越しにそのデーモンを叩く:
+別端末で `sesame serve` を起動しておけば、`sesame rpc` が UDS 越しにそのデーモンを叩きます:
 
 ```bash
 sesame rpc                                   # rpc.discover を人間向けの表で表示
@@ -146,83 +150,112 @@ sesame rpc --subscribe lockState             # イベントを表示し続ける
 sesame rpc --paths                           # 接続情報 (socket / token のパス) を JSON で出力
 ```
 
+HTTP 経由（任意の言語・クライアント不要）: `POST /rpc` に Bearer token を付けます。token は起動時に表示され `~/.config/sesame-kit/serve.token` にも保存されます。
+
+```bash
+sesame serve --http 8080                          # HTTP リスナを起動 (既定の serve は socket のみ)
+TOKEN=$(cat ~/.config/sesame-kit/serve.token)    # 起動時に表示されるトークン
+curl -s -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"lock.unlock","params":{"name":"front"}}' \
+  http://127.0.0.1:8080/rpc
+```
+
 ### 同梱クライアント
 
-`clients/` に依存ゼロの薄いクライアントを同梱する。
+JSON-RPC をラップした薄いクライアントで、`c.unlock("front")` のように書けます。任意であり、上の `curl` でもクライアント無しで動きます。Node は `npm install sesame-kit` 後に `import { SesameClient } from "sesame-kit/client"`。Python はパッケージ同梱の単一ファイルです。
 
-- Python: `pip install ./clients/python` で、どこからでも `import sesame_client`。試すだけなら `PYTHONPATH=clients/python`。
-- JS: `clients/js/sesame-client.mjs` を自プロジェクトにコピー、または相対 import。WebSocket をヘッダ認証で使うなら `npm i ws` (無ければ URL `?token=` にフォールバックする)。
+```js
+import { SesameClient } from "sesame-kit/client";   // npm install sesame-kit の後
+const c = SesameClient.unix();                       // 既定 Unix ソケット
+console.log(await c.unlock("front"));
+console.log(await c.call("device.history", { deviceUUID: "AB12CD34...", pageSize: 10 })); // 任意のメソッド。deviceUUID は `sesame devices` から
+await c.subscribe(["lockState"], (topic, p) => console.log(topic, p)); // 常に await
+```
 
 ```python
+# Python — 連携ガイドの手順でインストールしてから:
 from sesame_client import SesameClient
-c = SesameClient.unix()              # 既定 UDS パスを自動解決
-print(c.status()); print(c.unlock("front"))
-c.subscribe(["lockState"], lambda topic, payload: print("EVENT", topic, payload))
-# HTTP: SesameClient.http("http://127.0.0.1:8080") / 埋め込み: SesameClient.stdio()
+c = SesameClient.unix()                       # 既定 Unix ソケット
+print(c.unlock("front"))
+print(c.call("device.history", deviceUUID="AB12CD34...", pageSize=10))  # 任意のメソッド。deviceUUID は `sesame devices` から
 ```
 
+インストール不要の HTTP 経路・Python のインストール（グローバル npm 含む）・メソッド/値の調べ方・イベント・gRPC・セキュリティは [連携ガイド](./docs/ja/integration.md) を参照してください。
+
+gRPC は型付きです。`src/serve/sesame.proto` が op ごとに型付きメソッドを持ちます。
+ソースチェックアウトでスタブ生成（`pip install grpcio-tools` 後）: `python -m grpc_tools.protoc -I src/serve --python_out=. --grpc_python_out=. src/serve/sesame.proto`。
+
+認証境界: 対話ログインは CLI 専用で、デーモンには載りません。Unix socket は同一ユーザの任意プロセスが操作できます
+(CLI と同じ境界)。HTTP / WS / gRPC は TCP のため、起動時に生成する loopback token を要求します。POSIX 専用です
+(Windows の UDS は非対象です。stdio / HTTP / WS / gRPC は動きます)。
+
+---
+
+## Node から使う（インプロセス）
+
+デーモンを別に立てず、Node アプリ内で直接ロックを操作するにはライブラリエントリを使います。CLI のログイン情報（`~/.config/sesame-kit`、`sesame login` を一度実行）を読み、接続と切断を自動で行います。
+
 ```js
-import { SesameClient } from "./sesame-client.mjs";
-const c = SesameClient.unix();                       // UDS (POSIX)
-console.log(await c.unlock("front"));
-await c.subscribe(["lockState"], (topic, p) => console.log("EVENT", topic, p)); // 常に await
-const w = await SesameClient.ws("ws://127.0.0.1:8081"); // WebSocket (全二重)
-```
+import { SesameHub3 } from "sesame-kit";
 
-gRPC は型付き。`src/serve/sesame.proto` が op ごとに型付きメソッドを持つ。
-スタブ生成: `python -m grpc_tools.protoc -I src/serve --python_out=. --grpc_python_out=. src/serve/sesame.proto`。
+await SesameHub3.use(async (hub) => {
+  await hub.unlock("front");
+  await hub.send("ac", "停止");        // Hub3 IR
+});
+```
 
-認証境界: 対話ログインは CLI 専用で、デーモンには載らない。Unix socket は同一ユーザの任意プロセスが操作できる
-(CLI と同じ境界)。HTTP / WS / gRPC は TCP のため、起動時に生成する loopback token を要求する。POSIX 専用
-(Windows の UDS は非対象。stdio / HTTP / WS / gRPC は動く)。
+直接 API（`deviceUUID` / `secretKey` 指定）、イベント購読、config ファイルでなくコードでトークンを渡す方法は [Node ライブラリガイド](./docs/ja/library.md) を参照してください。
 
 ---
 
 ## 設定ディレクトリ
 
-優先順位: `--config-dir <path>` → `SESAME_HUB3_HOME` → `$XDG_CONFIG_HOME/sesame-hub3` → `~/.config/sesame-hub3`。
+優先順位: `--config-dir <path>` → `SESAME_KIT_HOME` → `$XDG_CONFIG_HOME/sesame-kit` → `~/.config/sesame-kit`。
 
 ```
-~/.config/sesame-hub3/
+~/.config/sesame-kit/
 ├── config.json         # devices / remotes / default / apiKeyId
 ├── tokens.json         # Cognito state (gitignore 必須)
 ├── login_state.json    # sign-in 進行中の一時状態
 └── devices.json        # `devices` コマンドの dump
 ```
 
-config スキーマと「単一 `devices{}` に保存する」設計は [docs/architecture.md](./docs/architecture.ja.md) を参照。
+config スキーマと「単一 `devices{}` に保存する」設計は [docs/ja/architecture.md](./docs/ja/architecture.md) を参照してください。
 
 ---
 
 ## ドキュメント
 
-- [docs/commands.md](./docs/commands.ja.md) — 全 CLI コマンドのリファレンス
-- [docs/library.md](./docs/library.ja.md) — Node ライブラリとしての利用
-- [docs/architecture.md](./docs/architecture.ja.md) — 出自・設計判断・ファイル構成
-- [docs/migration.md](./docs/migration.ja.md) — 旧版からの移行
+ドキュメント全体: **[docs/ja/](./docs/ja/index.md)** ([English](./docs/en/index.md))。
+
+- [クイックスタート](./docs/ja/quickstart.md) — 導入・ログイン・解錠まで
+- [CLI リファレンス](./docs/ja/commands.md) — 全コマンド
+- [BLE 直接制御](./docs/ja/ble.md) — クラウド非経由で Bluetooth 操作
+- [Node ライブラリ](./docs/ja/library.md) — Node.js アプリへ埋め込み
+- [他言語からの組み込み](./docs/ja/integration.md) — `sesame serve` 経由 (Python / JS / HTTP / WS / gRPC)
+- [アーキテクチャ](./docs/ja/architecture.md) · [マイグレーション](./docs/ja/migration.md)
 
 ---
 
 ## 既知の制限
 
-- 常駐用途では auto-reconnect (exponential backoff 1s→10s)、token refresh callback、idle / sleep 検知が動く。
-- 対応リモコンは自己学習 (`learnEmit`) のみ。プリセットリモコン (メーカー DB から選ぶ方式) の command 生成は未移植。`sesame ir learn` で物理リモコンを取り込んで使う。
-- autolock はクラウド経由では設定できない。BLE の `sesame autolock` を使う。
-- 未実装 op は Stripe 課金切替のみ。それ以外の biz3 op (社員 / グループ / 役割 / デバイスグループ / 鍵共有 / アクセス制御 / 予約 / IoT) はコマンド化済み。
-- WS ステージの既定は `/public`。`/production` は使用しない (config に残っていれば load 時に `/public` へ書き換える)。
-- AWS IoT WS は IPv4 必須。IPv6-only 回線では繋がらない。
-- 新規ペアリング (未登録デバイスの登録) は未対応。登録済みデバイスの操作のみ。
+- 対応リモコンは自己学習 (`learnEmit`) のみです。プリセットリモコン (メーカー DB から選ぶ方式) の command 生成は未移植です。`sesame ir learn` で物理リモコンを取り込んで使います。
+- autolock はクラウド経由では設定できません。BLE で `sesame <device> autolock <秒>`（例: `sesame front autolock 30`）を使います。
+- 未実装 op は Stripe 課金切替のみです。それ以外の biz3 op (社員 / グループ / 役割 / デバイスグループ / 鍵共有 / アクセス制御 / 予約 / IoT) はコマンド化済みです。
+- WS ステージの既定は `/public` です。`/production` は使用しません (config に残っていれば load 時に `/public` へ書き換えます)。
+- AWS IoT WS は IPv4 必須です。IPv6-only 回線では繋がりません。
+- 新規ペアリング (未登録デバイスの登録) は未対応です。登録済みデバイスの操作のみです。
 
 ---
 
 ## トラブルシュート
 
 - `No tokens stored` / `No config at ...`: `sesame init` → `sesame login`、または `sesame migrate`。
-- `UserNotFoundException`: 自動 SignUp は組み込み済み。それでも出る場合は Cognito 側の特殊ケース。
-- `Cognito refresh returned no IdToken`: refreshToken が無効化された (公式アプリでログアウト等)。再 sign-in する。
+- `UserNotFoundException`: 自動 SignUp は組み込み済みです。それでも出る場合は Cognito 側の特殊ケースです。
+- `Cognito refresh returned no IdToken`: refreshToken が無効化されました (公式アプリでログアウト等)。再 sign-in します。
 - `triggerLock timeout`: `secretKey` 不一致、Hub3 オフライン、または WS の半開接続 (自動再接続で復帰)。
-- `learn timeout`: Hub3 が REGISTER に入ったが波形を受け取れなかった。距離を縮める、別ボタンを試す。
-- `apiKeyId required`: `webapi` 系は config.json に `apiKeyId` を入れる (biz3 dev console で発行)。
+- `learn timeout`: Hub3 が REGISTER に入りましたが波形を受け取れませんでした。距離を縮めるか、別のボタンを試してください。
+- `apiKeyId required`: `webapi` 系は config.json に `apiKeyId` を入れます (biz3 dev console で発行)。
 
 ## 関連
 

package/README.md

@@ -4,13 +4,13 @@
 
 [![npm](https://img.shields.io/npm/v/sesame-kit)](https://www.npmjs.com/package/sesame-kit) [![license](https://img.shields.io/npm/l/sesame-kit)](./LICENSE) [![node](https://img.shields.io/node/v/sesame-kit)](https://nodejs.org)
 
-A Node.js CLI and library that drives the SESAME cloud WebSocket API using the same Cognito consumer client as the official SESAME iOS / Android apps. It covers lock control, Hub3 IR (emit and learn), device management, history, and battery level. With `sesame serve` it exposes every feature as JSON-RPC so you can drive SESAME from any language.
+**Do what the official SESAME app does — from your own code.** `sesame-kit` operates your existing SESAME devices the way the official iOS / Android apps do — lock / unlock, Hub3 IR (emit and learn), device management, history, battery — from a CLI, a Node library, or any language via `sesame serve` (JSON-RPC). `npm install` it and build SESAME into your scripts, home automation, or app.
 
 > 日本語版: [README.ja.md](./README.ja.md)
 
 > **Status** — Pre-1.0 and may contain bugs. It will reach 1.0 once it has proven stable in real use. Pin a version if you depend on it.
 >
-> **Disclaimer** — Unofficial. Not affiliated with or endorsed by CANDY HOUSE. It drives the cloud API the same way the official apps do, which may change or break without notice. Your `secretKey` and tokens grant full control of your lock; keep them private. Use at your own risk.
+> **Disclaimer** — Unofficial. Not affiliated with or endorsed by CANDY HOUSE, and using an unofficial client may fall outside their terms of service. It drives the cloud API the same way the official apps do, which may change or break without notice. Your `secretKey` and tokens grant full control of your lock and are stored unencrypted under `~/.config/sesame-kit`; keep them private. Use at your own risk.
 
 ## Features
 
@@ -25,11 +25,11 @@ A Node.js CLI and library that drives the SESAME cloud WebSocket API using the s
 - Language-agnostic backend: `sesame serve` exposes every feature as JSON-RPC over stdio / UDS / HTTP / WS / gRPC
 - Interactive mode and a library API
 
-See [command reference](./docs/commands.md), [library usage](./docs/library.md), and [design notes](./docs/architecture.md) for details.
+See [command reference](./docs/en/commands.md), [library usage](./docs/en/library.md), and [design notes](./docs/en/architecture.md) for details.
 
 ## Lineage
 
-A Node.js port of the official biz3 admin web app ([CANDY-HOUSE/biz.candyhouse.co](https://github.com/CANDY-HOUSE/biz.candyhouse.co), MIT). The only functional difference from biz3 is that the Cognito client ID is set to the same consumer client as the official iOS / Android apps, which keeps the refresh token from effectively expiring. The biz3 MIT license is bundled as [LICENSE.biz3](./LICENSE.biz3). The port mapping is in [docs/architecture.md](./docs/architecture.md).
+A Node.js port of the official biz3 admin web app ([CANDY-HOUSE/biz.candyhouse.co](https://github.com/CANDY-HOUSE/biz.candyhouse.co), MIT). The only functional difference from biz3 is that the Cognito client ID is set to the same consumer client as the official iOS / Android apps, which keeps the refresh token from effectively expiring. The biz3 MIT license is bundled as [LICENSE.biz3](./LICENSE.biz3). The port mapping is in [docs/en/architecture.md](./docs/en/architecture.md).
 
 ---
 
@@ -54,40 +54,44 @@ cd sesame-kit && npm install && npm link
 
 ## Setup
 
-Authenticate with `login` and `verify`. `verify` imports your companyID, locks, and Hub3 IR remotes automatically.
+Your devices must already be set up in the official SESAME app — this tool operates existing devices and does not pair new ones.
+
+Authenticate with `login` and `verify`. `verify` imports your devices **together with their keys** (and companyID and Hub3 IR remotes) into `~/.config/sesame-kit/`, so `sesame <device> <action>` works afterward with no further key setup.
 
 ```bash
-sesame init                 # initialize the config directory (~/.config/sesame-hub3/)
+sesame init                 # initialize the config directory (~/.config/sesame-kit/)
 sesame login your@email.com # send a verification code to your email
-sesame verify               # enter the code; imports companyID / locks / Hub3 IR
+sesame verify               # enter the code; imports your devices (with keys)
+sesame devices              # list your devices and their names (use these names below)
 ```
 
-Run `sesame setup` to re-import after adding devices later.
-IR requires both a Hub3 and a Remote to be registered. For lock control alone, only the Lock is needed.
+Run `sesame setup` to re-import after adding devices in the official app later.
+IR requires both a Hub3 and a Remote to be set up. For lock control alone, only the Lock is needed.
 
 ---
 
 ## Basic usage
 
-The subject is the device: `sesame <device> <action>` (device matches by substring).
+Run `sesame` with no arguments for the interactive menu. It lists your devices and the actions each one supports.
+
+```bash
+sesame                         # pick a device, then an action.  ↑↓ move · → confirm · ← back · q quit
+```
+
+To run an action directly, the subject is the device: `sesame <device> <action>`. Use one of your device names from `sesame devices` (matched by substring; `front` below is just an example).
 
 ```bash
 sesame front unlock            # unlock (substring match: sesame 玄関 unlock)
 sesame front lock              # lock
-sesame front toggle            # toggle from current state
 sesame front status            # state (locked / unlocked, position)
 sesame front autolock 30       # autolock (BLE only. 0 = off)
 sesame send 停止 --remote ac   # Hub3 IR emit
-sesame                         # interactive menu for all devices (session)
 ```
 
-The route (cloud / BLE) is chosen automatically. Pin it with `--ble-only` / `--cloud-only`.
-See [docs/commands.md](./docs/commands.md) for the full command set (IR learning, device management, scheduling, access control, org, IoT, BLE).
-
-### Interactive mode
+The route (cloud / BLE) is chosen automatically (**auto**). Pin it with `--ble-only` / `--cloud-only`.
+See the [CLI reference](./docs/en/commands.md) for every command (IR learning, device management, scheduling, access control, org, IoT, BLE).
 
-In a TTY (no `--json`), missing arguments can be selected with the arrow keys (↑↓). `sesame` alone opens the top menu.
-With `--json` or in a non-TTY, no prompts are shown and missing arguments are errors (CI-friendly).
+> In a TTY, a command with missing arguments falls back to arrow-key prompts. With `--json` or in a non-TTY, there are no prompts and missing arguments are errors (CI-friendly).
 
 ---
 
@@ -116,7 +120,7 @@ It is a SemVer for the machine contract; only breaking changes bump the major. C
 `sesame serve` is a long-running JSON-RPC 2.0 daemon. It logs in once, keeps the WS connection alive, runs ops repeatedly, and pushes events. Every feature is callable from any language through the same API.
 
 ```bash
-sesame serve                          # Unix socket only (default. ~/.config/sesame-hub3/sesame.sock)
+sesame serve                          # Unix socket only (default. ~/.config/sesame-kit/sesame.sock)
 sesame serve --stdio                  # embedded: a parent spawns it and talks over stdin/stdout
 sesame serve --http 8080 --ws 8081 --grpc 50051   # over the network (token auth)
 ```
@@ -145,66 +149,95 @@ sesame rpc --subscribe lockState             # keep printing events (Ctrl-C to s
 sesame rpc --paths                           # print connection info (socket / token paths) as JSON
 ```
 
+Over HTTP (any language, no client): `POST /rpc` with a Bearer token. The token is printed when the daemon starts and saved to `~/.config/sesame-kit/serve.token`.
+
+```bash
+sesame serve --http 8080                          # start the HTTP listener (the default serve is socket-only)
+TOKEN=$(cat ~/.config/sesame-kit/serve.token)    # the token printed at startup
+curl -s -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"lock.unlock","params":{"name":"front"}}' \
+  http://127.0.0.1:8080/rpc
+```
+
 ### Bundled clients
 
-Thin zero-dependency clients live under `clients/`.
+Thin clients wrap the JSON-RPC so you can write `c.unlock("front")`. They are optional — the `curl` call above works without any client. Node: `import { SesameClient } from "sesame-kit/client"` after `npm install sesame-kit`. Python: a single file shipped with the package.
 
-- Python: `pip install ./clients/python`, then `import sesame_client` from anywhere. For a quick try, `PYTHONPATH=clients/python`.
-- JS: copy `clients/js/sesame-client.mjs` into your project, or import it by relative path. For header-authenticated WebSocket, `npm i ws` (otherwise it falls back to URL `?token=`).
+```js
+import { SesameClient } from "sesame-kit/client";   // after: npm install sesame-kit
+const c = SesameClient.unix();                       // default Unix socket
+console.log(await c.unlock("front"));
+console.log(await c.call("device.history", { deviceUUID: "AB12CD34...", pageSize: 10 })); // any method; deviceUUID from `sesame devices`
+await c.subscribe(["lockState"], (topic, p) => console.log(topic, p)); // always await
+```
 
 ```python
+# Python — install per the integration guide, then:
 from sesame_client import SesameClient
-c = SesameClient.unix()              # resolves the default UDS path
-print(c.status()); print(c.unlock("front"))
-c.subscribe(["lockState"], lambda topic, payload: print("EVENT", topic, payload))
-# HTTP: SesameClient.http("http://127.0.0.1:8080") / embedded: SesameClient.stdio()
+c = SesameClient.unix()                       # default Unix socket
+print(c.unlock("front"))
+print(c.call("device.history", deviceUUID="AB12CD34...", pageSize=10))  # any method; deviceUUID from `sesame devices`
 ```
 
-```js
-import { SesameClient } from "./sesame-client.mjs";
-const c = SesameClient.unix();                       // UDS (POSIX)
-console.log(await c.unlock("front"));
-await c.subscribe(["lockState"], (topic, p) => console.log("EVENT", topic, p)); // always await
-const w = await SesameClient.ws("ws://127.0.0.1:8081"); // WebSocket (full-duplex)
-```
+See the [integration guide](./docs/en/integration.md) for the no-install HTTP path, Python install (incl. global npm installs), discovering methods/values, events, gRPC, and security.
 
 gRPC is typed. `src/serve/sesame.proto` has a typed method per op.
-Generate stubs with: `python -m grpc_tools.protoc -I src/serve --python_out=. --grpc_python_out=. src/serve/sesame.proto`.
+Generate stubs from a source checkout (after `pip install grpcio-tools`): `python -m grpc_tools.protoc -I src/serve --python_out=. --grpc_python_out=. src/serve/sesame.proto`.
 
 Auth boundary: interactive login is CLI-only and never runs in the daemon. A Unix socket can be used by any process of the same user (the same boundary as the CLI). HTTP / WS / gRPC are over TCP and require a loopback token generated at startup. POSIX only (Windows UDS is out of scope; stdio / HTTP / WS / gRPC work).
 
 ---
 
+## Use from Node (in-process)
+
+To control locks directly inside a Node app — without a separate daemon — use the library entry. It reads your CLI login from `~/.config/sesame-kit` (run `sesame login` once), then connects and closes automatically.
+
+```js
+import { SesameHub3 } from "sesame-kit";
+
+await SesameHub3.use(async (hub) => {
+  await hub.unlock("front");
+  await hub.send("ac", "停止");        // Hub3 IR
+});
+```
+
+See the [Node library guide](./docs/en/library.md) for the direct API (by `deviceUUID` / `secretKey`), event subscriptions, and supplying tokens in code instead of the config file.
+
+---
+
 ## Config directory
 
-Precedence: `--config-dir <path>` → `SESAME_HUB3_HOME` → `$XDG_CONFIG_HOME/sesame-hub3` → `~/.config/sesame-hub3`.
+Precedence: `--config-dir <path>` → `SESAME_KIT_HOME` → `$XDG_CONFIG_HOME/sesame-kit` → `~/.config/sesame-kit`.
 
 ```
-~/.config/sesame-hub3/
+~/.config/sesame-kit/
 ├── config.json         # devices / remotes / default / apiKeyId
 ├── tokens.json         # Cognito state (must be gitignored)
 ├── login_state.json    # transient state during sign-in
 └── devices.json        # dump from the `devices` command
 ```
 
-The config schema and the "store all devices in a single `devices{}`" design are in [docs/architecture.md](./docs/architecture.md).
+The config schema and the "store all devices in a single `devices{}`" design are in [docs/en/architecture.md](./docs/en/architecture.md).
 
 ---
 
 ## Documentation
 
-- [docs/commands.md](./docs/commands.md) — full CLI command reference
-- [docs/library.md](./docs/library.md) — using it as a Node library
-- [docs/architecture.md](./docs/architecture.md) — lineage, design decisions, file layout
-- [docs/migration.md](./docs/migration.md) — migrating from older versions
+Full docs: **[docs/en/](./docs/en/index.md)** ([日本語](./docs/ja/index.md)).
+
+- [Quickstart](./docs/en/quickstart.md) — install, sign in, open a lock
+- [CLI reference](./docs/en/commands.md) — every command
+- [BLE direct control](./docs/en/ble.md) — operate over Bluetooth without the cloud
+- [Node library](./docs/en/library.md) — embed in a Node.js app
+- [Integrate from any language](./docs/en/integration.md) — via `sesame serve` (Python / JS / HTTP / WS / gRPC)
+- [Architecture](./docs/en/architecture.md) · [Migration](./docs/en/migration.md)
 
 ---
 
 ## Known limitations
 
-- For long-running use, auto-reconnect (exponential backoff 1s→10s), a token refresh callback, and idle / sleep detection are in place.
 - Only self-learned remotes (`learnEmit`) are supported. Command generation for preset remotes (picked from a manufacturer DB) is not ported. Use `sesame ir learn` to capture a physical remote.
-- autolock cannot be set over the cloud. Use `sesame autolock` over BLE.
+- autolock cannot be set over the cloud — use `sesame <device> autolock <seconds>` over BLE (e.g. `sesame front autolock 30`).
 - The only unimplemented op is Stripe billing changes. Every other biz3 op (employees / groups / roles / device groups / key sharing / access control / scheduling / IoT) is available as a command.
 - The default WS stage is `/public`. `/production` is never used (if it lingers in config it is rewritten to `/public` on load).
 - AWS IoT WS requires IPv4. It will not connect on IPv6-only networks.

package/clients/js/sesame-client.mjs

@@ -20,11 +20,11 @@ import { readFileSync } from "node:fs";
 
 function defaultSocketPath() {
   const base = process.env.XDG_CONFIG_HOME || join(os.homedir(), ".config");
-  return join(base, "sesame-hub3", "sesame.sock");
+  return join(base, "sesame-kit", "sesame.sock");
 }
 function defaultTokenPath() {
   const base = process.env.XDG_CONFIG_HOME || join(os.homedir(), ".config");
-  return join(base, "sesame-hub3", "serve.token");
+  return join(base, "sesame-kit", "serve.token");
 }
 function defaultToken() {
   try { return readFileSync(defaultTokenPath(), "utf8").trim(); } catch { return null; }

package/clients/python/sesame_client.py

@@ -35,12 +35,12 @@ from typing import Any, Callable, Optional
 
 def _default_socket_path() -> str:
     base = os.environ.get("XDG_CONFIG_HOME") or os.path.join(os.path.expanduser("~"), ".config")
-    return os.path.join(base, "sesame-hub3", "sesame.sock")
+    return os.path.join(base, "sesame-kit", "sesame.sock")
 
 
 def _default_token_path() -> str:
     base = os.environ.get("XDG_CONFIG_HOME") or os.path.join(os.path.expanduser("~"), ".config")
-    return os.path.join(base, "sesame-hub3", "serve.token")
+    return os.path.join(base, "sesame-kit", "serve.token")
 
 
 class SesameError(RuntimeError):