@totalreclaw/totalreclaw 3.3.10-rc.4 → 3.3.10-rc.5

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to `@totalreclaw/totalreclaw` (the OpenClaw plugin) are docu
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.3.10-rc.5] — 2026-05-06
+
+Pedro flagged a gap in rc.10-rc.4: the agent terse line 3 ("Open <url>, enter PIN, generate phrase, reply `done`") doesn't tell the user what the BROWSER side will look like (3-step wizard, countdown, "I've written this down" checkbox, generate-vs-import tabs), and gives the agent no recovery script when the user reports browser-side issues like "page won't load" / "PIN expired" / "clicked button but nothing happened".
+
+### Changed
+
+- **SKILL.md and `openclaw-setup-quickstart.md` now include a "Browser flow context" section** describing the 3-step browser wizard so the agent KNOWS what the user is doing without proactively narrating it (silence rules still hold). Plus a 5-bullet "Common user issues" recovery script: page-won't-load → check URL host; PIN-expired → re-run pair; invalid-phrase on Log in → re-paste or switch tab; clicked-but-nothing-happened → 30 s wait then re-pair; where-do-I-write-it-down → paper / password manager / encrypted note.
+
+This RC is doc only — no plugin or CLI code changes. Same `tr-cli.js` binary as rc.4.
+
 ## [3.3.10-rc.4] — 2026-05-06
 
 Address OpenClaw's own meta-feedback on the rc.10-rc.3 setup guide (collected during a clean retest run by Pedro). Two functional fixes alongside doc cleanup:

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: totalreclaw
 description: "Install + set up TotalReclaw encrypted memory for OpenClaw, then use tr CLI for remember / recall. Trigger on 'install TotalReclaw', 'set up TotalReclaw', 'restore my recovery phrase', or any remember / recall request."
-version: 3.3.10-rc.4
+version: 3.3.10-rc.5
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -171,6 +171,22 @@ Do NOT decode `qr_png_b64` (does not exist), do NOT save a PNG to `/tmp/totalrec
 
 The QR encodes ONLY the account-setup URL. The 6-digit PIN is a separate out-of-band confirmation — deliberately NOT baked into the QR (dual-channel design: scan + type). Never log, print, or re-emit the PIN outside the user-facing reply. The PIN must NOT end up in any other tool call, log file, or memory store.
 
+## Browser flow context (know it, narrate only on user question)
+
+After you emit user-visible line 3, the user opens the URL on their phone or desktop browser. They walk through a 3-step wizard before the relay forwards the encrypted phrase to the plugin. You don't narrate this proactively (silence rules). But you MUST know it so you can answer questions and recover from issues:
+
+1. **Step 1 of 3 — Enter your PIN.** Six PIN cells. The user types or pastes the 6-digit PIN you sent in line 3. "Continue" is disabled until all 6 digits match. There's a 10-minute countdown displayed in the corner.
+2. **Step 2 of 3 — Your recovery phrase.** Two tabs: **Set up** (default — generates a fresh 12-word BIP-39 phrase locally in the browser) and **Log in** (paste an existing phrase to restore on a new device). User must check **"I've written this down and stored it somewhere safe"** then click **Set up TotalReclaw**.
+3. **Step 3 of 3 — You're all set.** Confirmation screen with a "Close this page" link. The browser already POSTed the encrypted phrase by this point — the relay forwards to your gateway, the plugin decrypts, writes `~/.totalreclaw/credentials.json`, and your `awaitPhraseUpload` resolves.
+
+Common user-side issues during pair (recover gracefully — emit ONE tight line, don't pre-narrate):
+
+- **"The page won't load"** → check the URL is the staging URL (`api-staging.totalreclaw.xyz` for RC builds, `api.totalreclaw.xyz` for stable). If they used the wrong stub host, generate a fresh URL.
+- **"PIN says expired"** or countdown ran out → re-run the pair block (Step 4 above) and emit line 3 again with the fresh URL+PIN. The previous session is dead.
+- **"It says invalid phrase"** during Log in → the user pasted a phrase that isn't BIP-39 valid (typo or wrong source). Tell them to double-check and re-paste; or switch to **Set up** tab to generate a fresh one (loses existing memories).
+- **"I clicked Set up TotalReclaw but nothing happened"** / **502** → the gateway WS dropped before respond. The pair subprocess is alive (you used `setsid -f`). Wait 30s; if the user still sees the 502, re-run Step 4 (the deferred reload should have completed by then).
+- **"Where do I write down the phrase?"** → tell them: anywhere safe and durable — paper, password manager, encrypted note. NOT in this chat. NOT in a screenshot to cloud-synced photos. The phrase IS the account; losing it means losing all memories.
+
 ## Phrase safety (HARD — never break)
 
 NEVER echo / generate / ask the user to paste a recovery phrase in chat. NEVER invoke `openclaw totalreclaw onboard` (bare interactive form), `totalreclaw setup`, or any phrase-touching CLI via your shell tool (stdout enters LLM context). The ONLY agent-facilitated account-setup paths are (in order of preference): (1) `tr pair --json`; (2) the `totalreclaw_pair` account-setup tool; (3) if both are missing — shell out to EITHER `openclaw totalreclaw pair generate --url-pin-only` (single-line JSON `{v,url,pin,expires_at_ms}`) OR `openclaw totalreclaw onboard --pair-only` (single-line JSON `{v,pair_url,pin,expires_at_ms}`). Both have zero phrase material on stdout (account-setup crypto is x25519-only, not BIP-39). If the user pastes a phrase anyway: tell them it is compromised, re-run `tr pair --json` for a fresh wallet.

package/dist/tr-cli.js

@@ -41,7 +41,7 @@ const STATE_PATH = CONFIG.onboardingStatePath;
 // Auto-synced by skill/scripts/sync-version.mjs from skill/plugin/package.json::version.
 // Do not edit by hand — running tests will catch drift but the publish workflow
 // rewrites this constant at the start of every npm/ClawHub publish.
-const PLUGIN_VERSION = '3.3.10-rc.4';
+const PLUGIN_VERSION = '3.3.10-rc.5';
 function die(msg, code = 1) {
     process.stderr.write(`tr: ${msg}\n`);
     process.exit(code);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.10-rc.4",
+  "version": "3.3.10-rc.5",
   "description": "End-to-end encrypted, agent-portable memory for OpenClaw and any LLM-agent runtime. XChaCha20-Poly1305 with protobuf v4 + on-chain Memory Taxonomy v1 (claim / preference / directive / commitment / episode / summary).",
   "type": "module",
   "keywords": [

package/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "totalreclaw",
-  "version": "3.3.10-rc.4",
+  "version": "3.3.10-rc.5",
   "description": "End-to-end encrypted memory for AI agents — portable, yours forever. XChaCha20-Poly1305 E2EE: server never sees plaintext.",
   "author": "TotalReclaw Team",
   "license": "MIT",

package/tr-cli.ts

@@ -52,7 +52,7 @@ const STATE_PATH = CONFIG.onboardingStatePath;
 // Auto-synced by skill/scripts/sync-version.mjs from skill/plugin/package.json::version.
 // Do not edit by hand — running tests will catch drift but the publish workflow
 // rewrites this constant at the start of every npm/ClawHub publish.
-const PLUGIN_VERSION = '3.3.10-rc.4';
+const PLUGIN_VERSION = '3.3.10-rc.5';
 
 function die(msg: string, code = 1): never {
   process.stderr.write(`tr: ${msg}\n`);