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

package/CHANGELOG.md

@@ -4,6 +4,42 @@ 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:
+
+### Fixed
+
+- **QR delivery regression on Telegram.** rc.10-rc.3's FORBIDDEN list correctly banned saving the QR PNG to `/tmp/totalreclaw-pair-qr.png` (which OpenClaw's media-policy rejected with `LocalMediaAccessError`), but the existing "Rendering the QR on your transport" SKILL.md section still pointed agents at a non-existent `qr_png_b64` field and a `qr_unicode` field — leftover from an older skill/native-tool surface. The agent skipped QR entirely rather than render the wrong field. Fix: the section is rewritten around the actual `qr_ascii` field that `tr pair --json` returns. Single recommended path: emit `qr_ascii` inside a triple-backticked code block above user-visible line 3. Renders as block-char QR in monospace font on Telegram, Slack, web, and terminal — every transport. No PNG, no save-to-disk, no media-policy interaction.
+
+- **`--force` install path.** OpenClaw QA fed back that `openclaw plugins install` fails on a re-run when the plugin is already on disk. Both the quickstart and the long setup guide now document the `--force` flag for this case.
+
+- **`tr status --json` retry-fail escalation.** Quickstart spells out a three-level escalation: 1st failure → sleep 5s + retry; 2nd → re-run install with `--force`; 3rd → emit a tight error line and stop. The previous "retry once after 5s" guidance left the agent stranded when retry also failed.
+
+### Changed
+
+- **New file `docs/guides/openclaw-setup-quickstart.md` (~5 KB)** — agent-executable contract: hard rules, four user-visible lines, copy-paste shell snippets. No rationale prose. SKILL.md's header now points agents at the quickstart first; the long `openclaw-setup.md` is the human-readable companion. The 28 KB `openclaw-setup.md` was burning context on every agent fetch — quickstart cuts that ~5×.
+
+- **SKILL.md FORBIDDEN section trimmed.** OpenClaw's feedback noted the rc.3 list was patching past failures one by one with verbatim narration examples that bloated the skill without adding rules. The list is now four crisp action-bans (no gateway restart, no config write, no QR PNG save, mandatory `setsid -f` for pair) — the narration ban is folded into the existing top-level "emit only the numbered user-visible lines" rule.
+
+- **`openclaw-setup.md` audience map at top.** Explicit three-audience map (humans, agents, QA / Pedro) with cross-link to the quickstart, so agents that fetched the long URL by accident know to switch.
+
+### Implementation notes
+
+- `qr_ascii` already exists in `pair-cli-relay.ts` `PairCliJsonPayload`. No CLI change required.
+- The legacy SKILL.md QR-rendering section referenced the older native-`totalreclaw_pair` tool's payload shape (`qr_png_b64`, `qr_unicode`). The native tool surface is unchanged for back-compat — but it's deprioritized in 3.3.9-rc.1+ (issue #223 strips it). Hybrid CLI is now the documented path, and CLI returns `qr_ascii` only.
+- This RC is doc + SKILL.md only — no code changes. Same `tr-cli.js` binary as rc.3.
+
 ## [3.3.10-rc.3] — 2026-05-06
 
 Pedro's 2026-05-05 manual QA on rc.10-rc.2 confirmed that even with the `setsid -f` instruction in SKILL.md, the agent freelances during install + pair: it restarted the gateway unprompted, re-rendered the QR to `/tmp/` (which OpenClaw's media-access policy blocks → `LocalMediaAccessError` on Telegram), wrote extra config that triggered another deferred SIGUSR1 reload, and ran `tr pair` in the foreground — all of which killed the pair WS and produced the 502 on browser respond. Plus the CLI binary's hard-coded `PLUGIN_VERSION` constant lagged the package version (CLI reported `3.3.9-rc.1` while the install record was `3.3.10-rc.2`).

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.3
+version: 3.3.10-rc.5
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -24,7 +24,11 @@ metadata:
 
 # TotalReclaw — OpenClaw
 
-> The canonical install flow lives at <https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/openclaw-setup.md>. If a user pastes that URL in chat, fetch it and follow its agent-instructions section. This SKILL.md mirrors the same steps so you can act even if the URL is unreachable.
+> **Agent-executable quickstart (5 KB, copy-paste-runnable)**: <https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/openclaw-setup-quickstart.md>
+>
+> **Human-readable setup guide (full rationale, troubleshooting)**: <https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/openclaw-setup.md>
+>
+> If the user pastes either URL: prefer the quickstart for execution. Fetch the full guide only if the user asks for context or troubleshooting beyond what the quickstart covers. This SKILL.md mirrors the quickstart's hard rules so you can act even if the URL is unreachable.
 
 ## CRITICAL: Relay-based architecture (read before anything else)
 
@@ -46,30 +50,17 @@ If you find yourself about to say any of these, STOP. The correct statement is:
 
 **Emit ONLY the user-visible lines listed below. Do not narrate tool calls. Do not describe what you're doing or about to do. Errors are the only allowed deviation, and only as a single tight line.** The expected user-facing transcript for a healthy install is **4–5 short lines TOTAL**. Anything more is a SKILL violation. Telegram and similar transports edit the bot's messages live as your tool calls progress — every interim "Let me check…" / "Plugin loaded. Let me verify…" line shows up to the user as awkward edit churn, even if you "delete" it. The fix is to never emit it in the first place.
 
-## ⛔ FORBIDDEN — do NOT do these (3.3.10-rc.3, hard rules from Pedro's 2026-05-05 QA)
+## ⛔ FORBIDDEN ACTIONS (4 hard rules from 2026-05-05 QA)
 
-These are the freelancing patterns that have broken pair flows and made transcripts noisy. They are FORBIDDEN, full stop:
+These specific actions break the pair flow. Everything else is governed by the "emit only the numbered user-visible lines" rule above.
 
-1. **Do NOT issue `/totalreclaw-restart`.** Do NOT send `kill -USR1`. Do NOT call `openclaw gateway restart`. Do NOT `docker restart`. The plugin auto-patches the gateway config and emits a single restart-required warn IF (and only if) the gateway needs one. The gateway will restart itself when its reload pipeline decides to. **You restarting it KILLS the in-flight `setsid -f` pair subprocess and surfaces as a 502 on the browser respond.**
+1. **Do NOT restart the gateway.** No `/totalreclaw-restart`, no `kill -USR1`, no `docker restart`, no `openclaw gateway restart`. The plugin self-patches and signals its own restart needs. You restarting it kills the in-flight `setsid -f` pair subprocess → 502 on browser respond.
 
-2. **Do NOT write to `~/.openclaw/openclaw.json`.** The plugin's `patchOpenClawConfig()` already wrote `plugins.slots.memory`, `plugins.entries.totalreclaw.hooks.allowConversationAccess`, and `channels.telegram.streaming.mode` for you. Any further config write triggers a fresh deferred reload that eventually fires SIGUSR1 and kills the pair subprocess. Forbidden tool calls: `openclaw config set …`, `jq … > openclaw.json`, any `cat > openclaw.json`, any `sed -i openclaw.json`.
+2. **Do NOT write to `~/.openclaw/openclaw.json`.** The plugin's `patchOpenClawConfig()` already wrote `plugins.slots.memory`, `plugins.entries.totalreclaw.hooks.allowConversationAccess`, `channels.telegram.streaming.mode`. Any further write triggers a deferred SIGUSR1 reload that kills pair. No `openclaw config set …`, no `jq …>openclaw.json`, no `sed -i openclaw.json`.
 
-3. **Do NOT re-render the QR.** `tr pair --json` already returns the QR as `qr_ascii` (Unicode block chars) AND the pair page itself renders a real PNG QR. Do NOT save the QR to `/tmp/totalreclaw-pair-qr.png` — OpenClaw's media-access policy blocks `/tmp/` paths and Telegram delivery fails with `LocalMediaAccessError: Local media path is not under an allowed directory`. The agent's only QR responsibility is to copy the URL+PIN into user-visible line 3. The transport (Telegram/web/CLI) renders the QR from the URL the user can already click.
+3. **Do NOT save QR PNGs.** `tr pair --json` returns `qr_ascii` — emit that inline in a triple-backticked code block. No `/tmp/totalreclaw-pair-qr.png` (OpenClaw media-policy blocks it: `LocalMediaAccessError`). No PNG decode. No `qr_png_b64` (legacy field, no longer exists in payload).
 
-4. **Do NOT invoke `tr pair --json` in the foreground.** A foreground pair subprocess is killed when your shell-tool exec returns (the agent runtime cleans up child PIDs). The pair WS dies → relay returns 502 on the browser respond. **The setup-flow Step 4 below uses `setsid -f` for exactly this reason — copy that block VERBATIM. Do not "simplify" it. Do not drop the `setsid -f`. Do not redirect stdout differently. Do not omit `< /dev/null`.**
-
-5. **Do NOT narrate.** Examples of narration that have appeared in past QAs and MUST NEVER appear again:
-   - "Now let me verify the CLI and check for existing credentials." → silent.
-   - "Gateway needs a restart to load the plugin. Let me restart it." → DO NOT RESTART.
-   - "The gateway is running but as a container process, not via systemd. Let me find and signal the gateway process to reload." → DO NOT SIGNAL.
-   - "The CLI is at the npm path, not the extensions path. Let me use the correct path." → silent (the `TR_CLI` resolver below already handles both paths).
-   - "Plugin is X.Y.Z, CLI reports itself as A.B.C (version string lag in the CLI binary)." → silent (don't reveal CLI internals).
-   - "Now let me also add the required post-install config and render the QR as an image." → DO NOT WRITE CONFIG. DO NOT RE-RENDER QR.
-   - "The pair response already has the QR data. Let me save the QR as a PNG using the existing skill's pair-qr module." → DO NOT SAVE QR ANYWHERE.
-
-If `tr status --json` returns version that disagrees with `openclaw plugins inspect totalreclaw`, **that is fine — do not narrate it**. The plugin's CLI reports its own packaged version which may lag the install record by one RC during a publish cycle. Both work.
-
-If you find yourself about to do anything in this list, STOP. Re-read this section. Then run the literal commands in the setup flow below — exactly as written.
+4. **`tr pair --json` MUST run via `setsid -f`** (exact form below). Foreground invocation is killed when your shell-tool exec returns → 502.
 
 ## Hybrid-primary architecture (3.3.9-rc.1)
 
@@ -162,16 +153,40 @@ node "$TR_CLI" recall --json "where does the user work" --limit 5
 
 **Note on tool names**: `totalreclaw_remember`, `totalreclaw_recall`, etc. may or may not appear in your toolset depending on OpenClaw version. Under hybrid-primary, you use the `tr` CLI instead. If native tools ARE available (older OpenClaw or future OC fix), they work too — but always prefer `tr` for reliability.
 
-## Rendering the QR on your transport (rc.5+)
+## Rendering the QR on your transport (3.3.10-rc.4 — corrected)
+
+`tr pair --json` returns a `qr_ascii` field — Unicode block-char QR (43 lines × ~43 cols). That is the ONLY QR field in the payload. The legacy `qr_png_b64` and `qr_unicode` field names referenced by older skill docs no longer exist.
+
+The simplest path that works on every transport (Telegram, Slack, web, terminal SSH): emit `qr_ascii` INLINE inside a triple-backtick code block right above user-visible line 3. Block-char QR renders correctly in monospace fonts on every modern transport — the user scans from their phone. The pair PAGE itself renders a real PNG QR alongside, so users on a desktop browser see both.
+
+Format the line-3 message as:
+
+```
+<qr_ascii contents — 43 lines of ▄▀█▄▀█ block chars>
+```
 
-When you receive the `totalreclaw_pair` payload (from tool OR `tr pair --json`), render the QR based on your chat transport:
+Open <url> in your browser. Enter PIN <pin>. Generate or paste a 12-word recovery phrase. Reply `done` once it's sealed.
 
-- **Transport supports image attachments** (Telegram, Slack, web chat, any transport with file/image upload): decode `qr_png_b64` from base64 to bytes, save to a tempfile with a `.png` suffix, and attach the tempfile as an image. Also show the URL + PIN as text so users who prefer clicking can still do so.
-- **Terminal-only transport** (OpenClaw native CLI chat, bare SSH shell): emit `qr_unicode` inline in your reply. It renders as block characters in most terminal fonts; the user scans from their phone.
-- **Web chat with inline-image support**: embed as `<img src="data:image/png;base64,<qr_png_b64>" alt="TotalReclaw account-setup QR">` if the chat client renders HTML; otherwise fall back to attachment.
+Do NOT decode `qr_png_b64` (does not exist), do NOT save a PNG to `/tmp/totalreclaw-pair-qr.png` (`LocalMediaAccessError` blocks delivery), do NOT re-render the QR through any other library. The `qr_ascii` field is the single source of truth.
 
 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.3';
+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.3",
+  "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.3",
+  "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.3';
+const PLUGIN_VERSION = '3.3.10-rc.5';
 
 function die(msg: string, code = 1): never {
   process.stderr.write(`tr: ${msg}\n`);