sesame-kit 0.4.2 → 0.5.0

package/docs/{architecture.md → en/architecture.md}

@@ -1,8 +1,8 @@
-<!-- English | [日本語](./architecture.ja.md) -->
+<!-- English | [日本語](../ja/architecture.md) -->
 
 # Architecture / Design Notes
 
-> 日本語: [architecture.ja.md](./architecture.ja.md)
+> [日本語](../ja/architecture.md) · [Docs index](./index.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.
 
@@ -19,14 +19,14 @@ This implementation is a Node.js port of the **official biz3 admin web app (http
 | `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).
+**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).
+- itemCode has one source in `src/itemcodes.js` (the cloud refers to it as `CMD` in `src/crypto.js`, BLE as `ITEM` in `src/ble/protocol.js` — different aliases for the same thing).
+- Capability is held by `src/ble/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.
@@ -55,7 +55,7 @@ The protocol layer (`src/ble/protocol.js`: CMAC session key / AES-CCM / segments
 
 ## `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.
+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/`.
@@ -99,7 +99,7 @@ sesame-kit/
     │   ├── 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)
+    ├── config.js           # ConfigStore (~/.config/sesame-kit/config.json)
     ├── tokens.js           # FileTokenStore
     └── paths.js            # config directory resolution
 ```

package/docs/en/ble.md

@@ -0,0 +1,65 @@
+<!-- English | [日本語](../ja/ble.md) -->
+
+# BLE direct control
+
+> [日本語](../ja/ble.md) · [Docs index](./index.md)
+
+Drive a registered SESAME directly over Bluetooth from your PC, without going through the cloud. It works offline, and **settings such as autolock — which the cloud cannot change — take effect on the device over BLE**. No sign-in is required for BLE-only operation.
+
+## Commands
+
+BLE control is not a separate command — add `--ble-only` to the device operation (`autolock` requires BLE, so it uses BLE even without the flag):
+
+```bash
+sesame front status --ble-only   # current state (locked / unlocked, position)
+sesame front unlock --ble-only   # unlock (lock / Bike)
+sesame front lock   --ble-only   # lock
+sesame front toggle --ble-only   # toggle based on current state
+sesame kitchen click --ble-only  # SESAME Bot click (Bot2 / Bot3)
+sesame front autolock 30         # autolock (BLE required; actually takes effect)
+sesame front autolock 0          # disable
+```
+
+Without `--ble-only`, the route (cloud / BLE) is chosen automatically; `--cloud-only` pins it to the cloud.
+
+## Capabilities by device type (follows the official SesameSDK)
+
+The operation set differs by device type. The official SDK defines capabilities asymmetrically per type, and this CLI reproduces that from the `model` in your config. Unsupported operations are rejected (e.g. `lock` on a Bot → "use click").
+
+| Type (example model) | BLE operations | mechStatus |
+|---|---|---|
+| Lock `sesame_5` / `_pro` / `sesame_6` / `_pro` / `_us` / `miwa` | `lock` `unlock` `toggle` `autolock` `status` | locked / unlocked + position |
+| Bot `bot_2` / `bot_3` | `click` `status` | locked / unlocked (no position) |
+| Bike `bike_2` / `bike_3` | `unlock` `status` | locked / unlocked (no position) |
+| Touch / Face / Sensor / Remote, Hub3, WiFiModule2 | (no BLE lock operation) | — |
+| OS2 `sesame_2` / `_4`, `ssmbot_1`, `bike_1` | BLE not implemented (different key derivation / crypto). Operate via the cloud | — |
+
+> On OS3, "locked / unlocked" is a 2-state value based on `isInLockRange` only; there is no intermediate (moved) state (only OS2 devices like Sesame2 have it).
+
+## Error codes
+
+When a device returns a non-zero result, the library throws `BleResultError` (`.resultCode` / `.resultName`). `resultName` matches the official SesameSDK `SesameResultCode` (`success` / `invalidFormat` / `notSupported` / `invalidSig` / `notFound` / `unknown` / `busy` / `invalidParam` / `invalidAction`), so you can branch on it.
+
+This is the device-layer (SesameOS3) taxonomy and is only available over BLE; the cloud path does not surface these codes, so they do not appear in `sesame serve`'s `kind`.
+
+## Requirements
+
+- The BLE adapter `@abandonware/noble`. It is an `optionalDependency`, so `npm install` attempts it automatically and the install does not break on unsupported platforms (BLE is simply disabled). Install manually with `npm i @abandonware/noble`.
+- **macOS requires Bluetooth permission for the terminal** (System Settings → Privacy & Security → Bluetooth). This is an OS-level permission, unavoidable with any BLE implementation.
+- Be within Bluetooth range of the lock.
+
+## As a library
+
+```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, isInLockRange, position, batteryRaw, ... } (batteryRaw = voltage ADC raw, not mV)
+});
+```
+
+## Scope
+
+Targets **SesameOS3** (SESAME 5 / 5 Pro / Touch, etc.). New pairing (registering an unregistered device) is not supported; only operating already-registered devices. See the design notes in [architecture.md](./architecture.md).

package/docs/{commands.md → en/commands.md}

@@ -1,11 +1,11 @@
-<!-- English | [日本語](./commands.ja.md) -->
+<!-- English | [日本語](../ja/commands.md) -->
 
 # Command Reference
 
-> 日本語: [commands.ja.md](./commands.ja.md)
+> [日本語](../ja/commands.md) · [Docs index](./index.md)
 
-> Every CLI command. Each subcommand also accepts `sesame <cmd> --help`.
-> When calling from another language via `sesame serve`, `sesame rpc` (or `rpc.discover`) is the machine-readable source of truth.
+> The CLI commands, grouped by area. Each subcommand also accepts `sesame <cmd> --help` for its full options.
+> When calling from another language via `sesame serve`, `sesame rpc` (or `rpc.discover`) lists every method and its parameters, machine-readably.
 
 ## Device operations (device as the subject)
 
@@ -26,14 +26,14 @@ sesame                         # interactive menu for all devices (session)
 
 action: `unlock` / `lock` / `toggle` / `click` / `status` / `autolock <seconds>` (**which operations apply depends on the type** — see below).
 
-### The route (transport) defaults to all-routes mode
+### The route (transport) defaults to auto
 
-- The default is all-routes mode; the route is chosen automatically. Ops that the cloud can carry go over cloud, and only BLE-required ops such as `autolock` open a BLE connection (so you don't pay the BLE scan/connect cost every time).
+- The default is auto; the route is chosen automatically. Ops that the cloud can carry go over cloud, and only BLE-required ops such as `autolock` open a BLE connection (so you don't pay the BLE scan/connect cost every time).
 - Pin the route with `--ble-only` / `--cloud-only`. `--ble-only` takes a few seconds to connect. `--cloud-only` restricts some operations.
 - To hold a BLE connection open across a run of operations, use `sesame session` (the multi-device form of `sesame <device>`).
 
 ```bash
-sesame front unlock            # all-routes mode (the tool picks the route)
+sesame front unlock            # auto (the tool picks the route)
 sesame front autolock 30       # BLE-required op → connects over BLE automatically
 sesame front lock --ble-only   # pinned to BLE (a few seconds to connect)
 sesame front lock --cloud-only # pinned to cloud
@@ -54,7 +54,7 @@ sesame locks rm front
 
 A cloud operation returns only after the synchronous ack (`biz3TriggerLocker`, `success:true`) arrives (timeout 10s).
 
-> autolock cannot be set over the cloud (BLE only). Use `sesame autolock`. Background in [architecture.md](./architecture.md).
+> autolock cannot be set over the cloud (BLE only). Use `sesame <device> autolock <seconds>` (e.g. `sesame front autolock 30`, `0` = off). Background in [architecture.md](./architecture.md).
 
 ---
 
@@ -95,6 +95,19 @@ sesame ir match ac <hex波形>           # match a learned waveform against know
 
 > To refer to a self-learned remote, use the real type `0xFE00` (65024) for `irType`. Passing the menu id `0xFEFF` makes the server match fail and the remote is not found. See [architecture.md](./architecture.md) for details.
 
+### Register remotes and the Hub3
+
+`send` / `ir learn` need a remote (and its Hub3) imported into config first. The fastest path is to sync everything from the server:
+
+```bash
+sesame hub3 sync-from-devices    # import your Hub3(s)
+sesame remote sync-from-devices  # import remotes (Hub3 + irType auto-detected) and their keys
+sesame remote ls                 # list configured remotes
+sesame remote set-default ac     # default remote used by a bare `sesame send <key>`
+```
+
+Or add one at a time: `sesame hub3 add` / `sesame remote add` both pick from a list (no UUID/irType to type). `sesame remote sync-keys [name]` re-imports a remote's key list.
+
 ---
 
 ## Device management
@@ -198,13 +211,15 @@ Direct commands to the Hub3 itself (LED dimming, LTE relay, firmware update, Mat
 Pass `--device <hub3UUID> --secret <hex>`, or select from connected devices when interactive.
 
 ```bash
-sesame iot led 80 --device <uuid> --secret <hex>   # LED dimming (0-100)
+sesame iot led 80 --device <uuid> --secret <hex>   # LED dimming (duty 0-255)
 sesame iot led --get --device <uuid> --secret <hex># get the current dimming level
 sesame iot relay on  --device <uuid> --secret <hex># LTE relay open/close
 sesame iot firmware-update --device <uuid> --secret <hex> --wait 60
 sesame iot matter-code --device <uuid> --secret <hex>   # Matter pairing code
 ```
 
+> `relay` is fire-and-forget: the Hub3 sends no acknowledgement, so a successful send is not a confirmed switch. The `off` opcode mapping is unverified against the official source and may behave differently on real hardware.
+
 ---
 
 ## Preset IR remotes (HXD command)
@@ -218,7 +233,7 @@ sesame preset-ir send --device <hub3uuid> --command <hex> --irtype 49152   # emi
 ```
 
 > Preset command generation (biz3's HXDCommandProcessor) is not yet ported, so preset emit does not currently work.
-> Use a self-learned remote (`sesame ir learn`) instead ([known limitations](../README.md#known-limitations)).
+> Use a self-learned remote (`sesame ir learn`) instead ([known limitations](../../README.md#known-limitations)).
 
 ---
 
@@ -278,7 +293,7 @@ await SesameBle.use({ deviceUUID, secretKey }, async (lock) => {
 
 ## Interactive session
 
-The interactive session (`sesame` / `sesame <device>` / `sesame session`) is an **app-like all-routes mode**.
+The interactive session (`sesame` / `sesame <device>` / `sesame session`) is an **app-like auto**.
 It lists **every device you can operate**: Locks/Bots/Bikes (BLE + cloud) and, if you are logged in, **Hub3** (cloud: IR send / relay / LED).
 It attaches BLE best-effort but **does not exit even when BLE is zero**: devices out of range or without permission are **operated over cloud** when you are logged in (devices with a BLE connection prefer BLE = lower latency + autolock available).
 

package/docs/en/index.md

@@ -0,0 +1,20 @@
+<!-- English | [日本語](../ja/index.md) -->
+
+# sesame-kit documentation
+
+> [日本語](../ja/index.md) · [← Back to README](../../README.md)
+
+Pick the guide for how you want to use sesame-kit.
+
+## Getting started
+- [Quickstart](./quickstart.md) — install, sign in, and open a lock in a few minutes.
+
+## Guides (by usage)
+- [CLI](./commands.md) — full command reference for the `sesame` CLI.
+- [BLE direct control](./ble.md) — drive locks over Bluetooth without the cloud (autolock, permissions, per-device capabilities).
+- [Node library](./library.md) — embed sesame-kit in a Node.js app (`SesameHub3.use()`, direct API, events).
+- [Integrate from any language](./integration.md) — call every feature over JSON-RPC via `sesame serve` (Python / JS / HTTP / WebSocket / gRPC).
+
+## Reference & design
+- [Architecture](./architecture.md) — lineage, design decisions, file layout.
+- [Migration](./migration.md) — upgrading from older versions.

package/docs/en/integration.md

@@ -0,0 +1,181 @@
+<!-- English | [日本語](../ja/integration.md) -->
+
+# Integrate from any language (`sesame serve`)
+
+> [日本語](../ja/integration.md) · [Docs index](./index.md)
+
+`sesame serve` is a long-running JSON-RPC 2.0 daemon. It signs in once, keeps the cloud connection alive, and runs operations and pushes events repeatedly. Every feature is callable from any language.
+
+## 1. Sign in and start the daemon
+
+The daemon uses your stored login — it does not sign in itself. Sign in once with the CLI, then start the daemon.
+
+```bash
+sesame login your@email.com && sesame verify   # if not already signed in
+sesame serve --http 8080                        # serve over HTTP on port 8080
+```
+
+The daemon prints a token at startup (also saved to `~/.config/sesame-kit/serve.token`). Every HTTP request must send `Authorization: Bearer <token>`.
+
+> For same-machine use, `sesame serve` with no flags listens on a Unix socket and needs no token. HTTP is used here because it works from any language and any machine.
+
+## 2. Your first call — no library to install
+
+It is plain JSON-RPC over HTTP. Anything that can POST works.
+
+```bash
+TOKEN=...   # the token printed by `sesame serve`
+
+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
+```
+
+The same in Python, using only the standard library (no pip install):
+
+```python
+import json, urllib.request
+
+TOKEN = "..."   # the token printed by `sesame serve`
+
+def rpc(method, params=None):
+    body = json.dumps({"jsonrpc": "2.0", "id": 1, "method": method, "params": params or {}}).encode()
+    req = urllib.request.Request("http://127.0.0.1:8080/rpc", data=body,
+        headers={"content-type": "application/json", "authorization": f"Bearer {TOKEN}"})
+    return json.load(urllib.request.urlopen(req))
+
+print(rpc("status"))
+print(rpc("lock.unlock", {"name": "front"}))
+```
+
+A response is `{"jsonrpc":"2.0","id":1,"result": ...}` on success, or `{"jsonrpc":"2.0","id":1,"error":{"code","message","data":{"kind"}}}` on failure.
+
+## 3. Finding the method and the values to pass
+
+`sesame rpc` lists every method with its parameters (required shown plain, optional in `[brackets]`):
+
+```bash
+sesame rpc
+```
+
+```text
+lock.unlock                  [name] [deviceUUID] [secretKey]
+lock.status                  deviceUUID
+devices.list
+device.history               deviceUUID [pageSize]
+ir.send                      [remote] key
+org.getEmployees             companyID
+…
+79 methods.
+```
+
+Read the line for the method you want. Each line is `method  <required> [optional]`. For example, `device.history  deviceUUID [pageSize]` means **`deviceUUID` is required and `pageSize` is optional**.
+
+Then fill each parameter with a **value**. Values come from one of two places:
+
+- **IDs** (`deviceUUID`, `companyID`, …) are returned by another list method. For a `deviceUUID`, take one from `devices.list`:
+
+  ```bash
+  sesame rpc devices.list
+  # → [{"deviceUUID":"AB12CD34...","deviceName":"front", ...}, ...]
+  ```
+
+- **Values you choose** (`pageSize`, `name`, …) are optional and up to you. `pageSize` is the number of records.
+
+Put the values in the `--params` JSON and call it:
+
+```bash
+sesame rpc device.history --params '{"deviceUUID":"AB12CD34...","pageSize":10}'
+```
+
+The **method name and params you settle on here are exactly what you send from any client** (the `method` / `params` fields of the call in section 2).
+
+> Lock ops also accept a config name instead of a `deviceUUID` — `{"name":"front"}` works for `lock.unlock` / `lock.lock` / `lock.toggle` / `lock.click`. (`lock.status` takes a `deviceUUID`.)
+
+For exact parameter types (e.g. for code generation), `sesame rpc --json rpc.discover` returns the full OpenRPC document. Each method entry carries its param types:
+
+```json
+{
+  "name": "device.history",
+  "params": [
+    { "name": "deviceUUID", "required": true,  "schema": { "type": "string" } },
+    { "name": "pageSize",   "required": false, "schema": { "type": "number" } }
+  ]
+}
+```
+
+## 4. Bundled clients (optional)
+
+Thin clients wrap the above so you write `c.unlock("front")` instead of building JSON by hand. They are optional — section 2 already works without them.
+
+**Node** — after `npm install sesame-kit`:
+
+```js
+import { SesameClient } from "sesame-kit/client";
+
+const c = SesameClient.unix();                          // default Unix socket
+console.log(await c.unlock("front"));                   // convenience method
+console.log(await c.call("device.history", { deviceUUID: "AB12CD34...", pageSize: 10 })); // any method
+console.log((await c.discover()).methods.map((m) => m.name));  // list methods from JS
+await c.subscribe(["lockState"], (topic, p) => console.log(topic, p)); // always await
+
+// const h = SesameClient.http("http://127.0.0.1:8080");   // token auto-read from serve.token
+// const w = await SesameClient.ws("ws://127.0.0.1:8081");  // npm i ws for header auth
+```
+
+**Python** — the client is a single file shipped with the package:
+
+```bash
+pip install ./clients/python                       # from a cloned repo
+pip install "$(npm root -g)/sesame-kit/clients/python"   # from a global `npm install -g sesame-kit`
+```
+```python
+from sesame_client import SesameClient
+
+c = SesameClient.unix()                       # default Unix socket
+print(c.unlock("front"))                      # convenience method
+print(c.call("device.history", deviceUUID="AB12CD34...", pageSize=10))  # any method
+print(c.discover_names())                     # list methods from Python
+c.subscribe(["lockState"], lambda topic, payload: print(topic, payload))
+# HTTP: SesameClient.http("http://127.0.0.1:8080") / embedded: SesameClient.stdio()
+```
+
+## Transports (framings)
+
+The same methods are available over five transports. Use HTTP/WS/gRPC for network access, the Unix socket or stdio for the local machine.
+
+| Framing | Use | Events | Auth |
+|---|---|---|---|
+| stdio | embedded (child process) | `event.*` notifications | inherits parent trust |
+| Unix socket | local daemon, multiple clients | `event.*` notifications | file permission 0600 |
+| HTTP | any language / browser | `GET /events` (SSE) | `Authorization: Bearer <token>` |
+| WebSocket | any language / browser (full-duplex) | `event.*` notifications | token |
+| gRPC | typed stubs for many languages | `Subscribe` stream | token (metadata) |
+
+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`.
+Scalar/array params are protobuf-typed; dynamic params are a JSON-string field; responses are `JsonRpc{json}`. Ops without a typed method use the generic `Invoke`.
+
+## Events
+
+```jsonc
+// request (over Unix socket / WebSocket / stdio):
+{"jsonrpc":"2.0","id":1,"method":"events.subscribe","params":{"topics":["lockState","deviceUpdate"]}}
+// then notifications arrive (no id):
+{"jsonrpc":"2.0","method":"event.lockState","params":{ /* state */ }}
+```
+
+Topics: `lockState`, `deviceUpdate`. Over HTTP use `GET /events?topics=…` (SSE); over gRPC use the `Subscribe` stream. `POST /rpc` and gRPC `Invoke` are request/response only and reject `events.*`.
+
+## Errors
+
+Errors are `{error:{code, message, data:{kind}}}`. `kind` is one of:
+`not_authenticated` (sign in via the CLI, then restart the daemon) / `connection_lost` (cloud connection down) / `timeout` / `bad_params` / `not_implemented` (unknown method) / `internal` (anything else; details in `message`).
+
+## Compatibility
+
+The result shape is method-specific. To check compatibility, read the contract version: `status` returns `contractVersion`, and `rpc.discover` returns `info["x-contractVersion"]`. It is a SemVer for the machine contract; only breaking changes bump the major.
+
+## Security 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. They are plaintext (no TLS); expose them over loopback only, or tunnel via SSH / a TLS reverse proxy. POSIX only (Windows UDS is out of scope; stdio / HTTP / WS / gRPC work).

package/docs/{library.md → en/library.md}

@@ -1,12 +1,12 @@
-<!-- English | [日本語](./library.ja.md) -->
+<!-- English | [日本語](../ja/library.md) -->
 
 # Using sesame-kit as a library
 
-> 日本語: [library.ja.md](./library.ja.md)
+> [日本語](../ja/library.md) · [Docs index](./index.md)
 
-The same features as the `sesame` CLI can be called directly from Node.js. To use it from other languages, use [`sesame serve`](../README.md#language-agnostic-backend-sesame-serve); to use it inside Node, use this.
+The same features as the `sesame` CLI can be called directly from Node.js. To use it from other languages, use [`sesame serve`](../../README.md#language-agnostic-backend-sesame-serve); to use it inside Node, use this.
 
-## The simplest form: the `use()` helper (auto connect/close)
+## `use()` helper (auto connect/close)
 
 ```js
 import { SesameHub3 } from "sesame-kit";
@@ -53,10 +53,11 @@ await SesameHub3.use(async (hub) => {
   await hub.lockDevice({ deviceUUID, secretKey });
   await hub.toggleDevice({ deviceUUID, secretKey });
   await hub.botClickDevice({ deviceUUID, secretKey });
-  await hub.triggerLockDevice({ deviceUUID, secretKey, cmd: 83 });   // arbitrary cmd
+  await hub.triggerLockDevice({ deviceUUID, secretKey, cmd: 83 });   // raw itemCode: 83=unlock, 82=lock, 88=toggle, 89=click
 
   // IR
   await hub.sendIRDirect({
+    // irType selects the remote category: 49152 (0xC000)=air-conditioner, 8192=TV, 32768=fan, 57344=light
     hub3DeviceId, irDeviceUUID, irType: 49152, command: keyUUID, operation: "learnEmit",
   });
   const keys = await hub.getIRCodesDirect({ hub3DeviceId, irDeviceUUID });

package/docs/en/migration.md

@@ -0,0 +1,13 @@
+<!-- English | [日本語](../ja/migration.md) -->
+
+# Migrating from older versions
+
+> [日本語](../ja/migration.md) · [Docs index](./index.md)
+
+Upgrading from the old `sesame-hub3` (CLI = `hub3-ir`):
+
+- The CLI is renamed to `sesame` (the old `hub3-ir` is removed). Replace it in any shell scripts.
+- Config and tokens are stored in `~/.config/sesame-kit`.
+- Config is now stored under a single `devices` map; `locks` is a derived view rebuilt on each load, not a stored key. Populate `devices` from the server with `sesame locks sync-from-devices`.
+
+Migrating from an old `.env` + `.tokens.json` + `keys.json` works with `sesame migrate`.

package/docs/en/quickstart.md

@@ -0,0 +1,51 @@
+<!-- English | [日本語](../ja/quickstart.md) -->
+
+# Quickstart
+
+> [日本語](../ja/quickstart.md) · [Docs index](./index.md)
+
+Open a lock from the command line in a few minutes.
+
+## 1. Install
+
+```bash
+npm install -g sesame-kit     # global CLI: `sesame ...`
+# or without installing: npx sesame-kit ...
+```
+
+Requires Node.js 18+.
+
+## 2. Sign in
+
+```bash
+sesame init                 # create ~/.config/sesame-kit/ (first run only)
+sesame login your@email.com # sends a verification code to your email
+sesame verify               # enter the code
+```
+
+`verify` imports your devices together with their keys, so you can control them right away.
+
+## 3. Control a lock
+
+Run `sesame` for the interactive menu. It lists your devices and the actions each supports.
+
+```bash
+sesame      # ↑↓ move · → (or Enter) confirm · ← (or Esc) back · q quit
+```
+
+Or run an action directly. The subject is the device: `sesame <device> <action>` (substring match).
+
+```bash
+sesame front status            # current state (locked / unlocked)
+sesame front unlock            # unlock
+sesame front lock              # lock
+```
+
+## Next steps
+
+- All CLI commands: [CLI reference](./commands.md)
+- Operate over Bluetooth without the cloud: [BLE direct control](./ble.md)
+- Call from another language: [Integrate via `sesame serve`](./integration.md)
+- Use it from Node code: [Node library](./library.md)
+
+> Cloud control needs sign-in. BLE-only control works without sign-in — see [BLE direct control](./ble.md).