@totalreclaw/totalreclaw 3.3.12-rc.4 → 3.3.12-rc.7

package/CHANGELOG.md

@@ -4,6 +4,32 @@ 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.12-rc.5] — 2026-05-09
+
+Final RC for the 3.3.12 stable promote. Behavioral fix: Pedro's Pop-OS Telegram QA (zai/glm-5-turbo) on rc.4 found the agent storing user statements in `MEMORY.md` / `USER.md` via `write` tool calls instead of calling `totalreclaw_remember`. 28 `write` calls observed in one session, 0 TotalReclaw tool calls — facts never reached the chain. Root cause: SKILL.md trigger language was permissive ("call when the user asks") and the agent's default file-write reflex won out. rc.5 makes the memory-storage rule the TOP RULE of SKILL.md with an explicit prohibition on `write`/`edit` against `MEMORY.md`/`USER.md`, an exhaustive trigger-phrase list (preference / identity / decision / commitment / possessive-assertion patterns), and a multi-fact-per-message instruction so blob-style packing does not happen.
+
+### Changed
+
+- **SKILL.md TOP RULE rewrite — aggressive triggers, no MEMORY.md fallback.** Memory storage section moved to the very top of SKILL.md (before architecture, vocabulary, install flow). Adds: (1) absolute prohibition on `write`/`edit` against `MEMORY.md` / `USER.md` / `~/.claude/memory/*.md`; (2) trigger-phrase list covering preferences, identity, tools, decisions, commitments, explicit asks, possessive assertions; (3) multi-fact-per-message rule (split into one `totalreclaw_remember` call per atomic fact); (4) full 17-tool reference table with canonical use cases; (5) restart policy reaffirmed (gateway self-restarts via SIGUSR1; agent NEVER prompts user to manually restart); (6) phrase-safety hard rail (no phrase in chat / no phrase as tool input / browser-side only).
+- **Public quickstart guide audit** (`docs/guides/openclaw-setup-quickstart.md`) — already prose-style + clean from rc.6 revert. No edits required.
+- **Long-form setup guide cleanup** (`docs/guides/openclaw-setup.md`) — F-flip default URL corrected (`api.totalreclaw.xyz` for free tier, staging via env override; previous text said the relay was `api-staging.*`); line 1 wording aligned with SKILL.md (`Setting up TotalReclaw — this takes about a minute…`); legacy `qr_png_b64` / `qr_unicode` references replaced with `qr_ascii` (the only QR field in the current pair payload); manual restart fallback (`openclaw gateway restart` / `docker restart`) deemphasized — the plugin self-restarts via SIGUSR1; RC pin examples bumped from `3.3.11-rc.5` to `3.3.12-rc.5`.
+- **Version sync** — package.json, skill.json, SKILL.md frontmatter, tr-cli.ts PLUGIN_VERSION all aligned to 3.3.12-rc.5 via `sync-version.mjs`. `check-version-drift` green.
+
+### Verified
+
+- All 38 test suites pass (manifest-shape, config-schema, config, relay-headers, scope-address-visible, llm-profile-reader, llm-client (×2), gateway-url, retype-setscope, tool-gating, onboarding-noninteractive, pair-cli-json, pair-qr, pair-remote-client, qa-bug-report, nonce-serialization, phrase-safety-registry, onnx-download-ux, onboard-pair-only, import-time-smoke, install-staging-cleanup, partial-install-detection, install-reload-idempotency, json-stdout-cleanliness, load-manifest, url-binding, fs-helpers, pair-cli-default-mode, embedding-fallback-tag, staging-banner-gate, restart-auth, inbound-user-tracker, register-command-name, skill-md-hybrid-primary, tr-cli-json-output).
+- `check-scanner` green (0 flags).
+- `check-version-drift` green (3 sites + tr-cli.ts all = 3.3.12-rc.5).
+- E2E on clean OpenClaw 2026.5.7 container — agent given `"Hi, I'm Pedro. I live in Porto. I prefer PostgreSQL over MySQL."` calls `totalreclaw_remember` ≥1 time, with 0 `write`/`edit` calls against `MEMORY.md` / `USER.md`. (See PR description for the captured `toolSummary` JSON.)
+
+### Out of scope (unchanged from rc.4)
+
+- Plugin install lifecycle on OpenClaw 2026.5.7 (auto-QA PASS — plugin loads, SIGUSR1 self-restart works, in-process restart, managed-service-friendly).
+- `tr` CLI on-chain memory ops (rc.4 fix verified).
+- Pair flow (browser-side phrase, no leakage).
+- Trajectory poller (auto-extraction backup).
+- F flip (RC + stable both default to prod URL; staging via env override).
+
 ## [3.3.12-rc.2] — 2026-05-08
 
 Hot-fix on rc.1's F flip. Pair flow regression: rc.1 set `pairRelayUrl`'s default to `wss://api.totalreclaw.xyz` (production) independently of `serverUrl`. RC users who set `TOTALRECLAW_SERVER_URL=https://api-staging.totalreclaw.xyz` (per the staging-opt-in flow) had pair WS go to **prod**, which pre-dates the pair feature → 404 on WS upgrade → `totalreclaw_pair failed: Unexpected server response: 404`. End-to-end blocker: pair never completed → no credentials → no memories.

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.12-rc.4
+description: "End-to-end encrypted, decentralized memory for OpenClaw. Set up an account once, then call totalreclaw_remember / totalreclaw_recall (or the tr CLI under hybrid-primary) instead of writing to MEMORY.md / USER.md / local files. Trigger on 'install TotalReclaw', 'set up TotalReclaw', 'restore my recovery phrase', any remember / recall request, AND any user statement that contains a preference / fact / decision / commitment about themselves."
+version: 3.3.12-rc.7
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -22,276 +22,55 @@ metadata:
       - persistent-context
 ---
 
-# TotalReclaw — OpenClaw
+# TotalReclaw — OpenClaw plugin
 
-> **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.
+End-to-end encrypted memory stored across a decentralized network (not on a single company server). The plugin handles install + account-setup autonomously; this skill tells the agent what to call and when.
 
-## CRITICAL: How TotalReclaw actually stores memories (read before anything else)
+## TOP RULE — MEMORY STORAGE
 
-**TotalReclaw is end-to-end encrypted memory stored across a DECENTRALIZED NETWORK — not on a single company server.** Memories are encrypted with keys derived from the user's 12-word recovery phrase, submitted as Account Abstraction UserOps, and persisted on a public blockchain (Base / Gnosis depending on tier). The Graph subgraph indexes them. The TotalReclaw relay only forwards encrypted bundles to the bundler and proxies subgraph reads — it never sees plaintext, can't read memories, and could be replaced by any compatible relay without losing data. No single company controls or can read user memories.
+When the user states ANYTHING about themselves — preferences, decisions, identity, work, location, plans, tools, commitments — call `totalreclaw_remember` (or `tr remember --json "<fact>"` under hybrid-primary). NEVER write user facts to `MEMORY.md`, `USER.md`, or any local file. Those are agent-persona configuration; user memories live encrypted on-chain.
 
-Forbidden vocabulary — these claims are WRONG (some imply local-only storage; some imply a single-company server):
-- "local", "local-only", "stored locally", "on disk", "local memory", "local storage" — wrong direction (implies local-only). Memories require an account; they're encrypted and submitted on-chain.
-- "stored on a relay server", "stored on TotalReclaw's server", "single server owned by", "TotalReclaw stores your", "company server" — wrong direction (implies centralized custody). The relay forwards ciphertext; storage is decentralized on-chain.
-- "without an account" — wrong (an account is required to derive the encryption key).
+**Trigger immediately, no "should I?":** "I prefer / like / love / hate X", "my favorite is X", "I'm X", "my name is X", "I live / work at X", "I use X", "I decided X", "I'm going to X", "from now on X", "we agreed X", "I'll X by Y", "remind me to X", "remember that X", "save X", "note X". If a message contains MULTIPLE facts, call `totalreclaw_remember` once per fact — never blob.
 
-If you need to describe how it works, the canonical line is: **"Memories are encrypted with a key derived from your recovery phrase, submitted on-chain via Account Abstraction, and stored across a decentralized network. The relay only forwards encrypted bundles — it never sees plaintext. Only you can decrypt them, and only with your recovery phrase."**
+When the user asks about themselves ("what's my X?", "do I X?", "what do you remember?"), call `totalreclaw_recall` FIRST. If 0 results, say so plainly — don't guess from session history.
 
-## User-facing vocabulary (substitute internal jargon for plain words)
+Do not describe storage as `"local"`, `"local-only"`, `"stored locally"`, `"on disk"`, `"local memory"`, `"local storage"`, or `"without an account"` — memories are decentralized on-chain (not on any single company server) and an account is required to derive the encryption key.
 
-Internal terms that the user does NOT know — translate when you must speak:
+## Phrase safety (HARD)
 
-| Internal term | Say to the user |
-|---|---|
-| pair / pairing / paired account | "set up an account" / "your TotalReclaw account" |
-| relay / relay server | (don't mention; if forced, say "the encrypted-bundle forwarder") |
-| WS / WebSocket / handshake | (don't mention) |
-| trapdoor / blind index / dedup-key | (don't mention) |
-| subgraph / bundler / UserOp / Account Abstraction | (don't mention; if forced, "submitted on-chain to a decentralized network") |
-| credentials.json / mnemonic file | "your recovery phrase" |
-| `tr pair --json` / `setsid -f` / shell exec | (don't mention; just do the work silently) |
+The 12-word recovery phrase MUST NEVER enter chat or the agent's LLM context. The plugin's browser-based pair flow handles phrase generation and import. Never echo it, never ask the user to paste it, never pass it to any tool. If the user pastes one anyway, tell them it's compromised and re-pair for a fresh wallet.
 
-The word "pair" is internal jargon — never use it in user-visible prose. The user-visible vocabulary is "set up an account", "your account", "your recovery phrase", "your memories".
+## Install
 
-## Top-level rule (read this before anything else)
-
-**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.
-
-### ⚡ MANDATORY ACK BEFORE FIRST TOOL CALL
-
-**User-visible line 1 MUST be your FIRST output — emitted BEFORE you run any shell tool, plugin install, or `tr` command.** Install + setup takes 1–2 minutes of silent tool-execution; without an immediate ack the user assumes the request didn't register and may resend or abandon. The ack tells them work is happening.
-
-The ack is unconditional. It fires the moment you decide to install / set up TotalReclaw — even before you've resolved `TR_CLI`, even before you've checked whether the plugin is already installed, even before the first `openclaw plugins install` shell call. Send line 1, THEN start the work.
-
-Forbidden order (silent-then-narrate): ❌ run `openclaw plugins install` → wait 60s → emit line 1.
-Required order (ack-then-work): ✅ emit line 1 → run `openclaw plugins install` silently → emit line 2 when `tr status` returns.
-
-## ⛔ FORBIDDEN ACTIONS (4 hard rules from 2026-05-05 QA)
-
-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 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`, `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 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. **`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)
-
-OpenClaw 2026.5.2 has a tool-policy-pipeline bug (issue #223) that strips non-bundled plugin tools before they reach the agent toolset. **3.3.9-rc.1 makes the `tr` CLI the PRIMARY path for all memory operations.** Native tools (`totalreclaw_*`) are kept for back-compat with older OpenClaw versions where they work, but the agent MUST NOT depend on them. Use `tr` from your shell tool for everything.
-
-**The `tr` binary is installed at one of two paths depending on OpenClaw version:**
-- Modern (2026.5.x npm-managed): `~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/tr-cli.js`
-- Legacy (extensions tree): `~/.openclaw/extensions/totalreclaw/dist/tr-cli.js`
-
-**Resolve the path once at the top of your shell session and reuse:**
-```bash
-TR_CLI="$(ls -d ~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/tr-cli.js ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js 2>/dev/null | head -1)"
 ```
-Then invoke as `node "$TR_CLI" <cmd> [--json]`.
-
-**Never rely on `totalreclaw_*` tool binding** — it may not be available due to issue #223.
-
-## User-visible line set (THIS IS ALL YOU SAY)
-
-Speak only these lines, in order. Substitute the bracketed placeholders with the real values. No prefaces. No suffixes. No narration.
-
-1. (FIRST output, emitted BEFORE any shell tool call — see "MANDATORY ACK" rule above)
-   > Setting up TotalReclaw — this takes about a minute…
-2. (after install + CLI verify — `tr status` works)
-   > ✓ Installed (totalreclaw &lt;version&gt;, hybrid mode)
-3. (account-setup URL + PIN, IMMEDIATELY after `tr pair --json` returns — no consent gate)
-   > Open &lt;url&gt; in your browser. Enter PIN &lt;pin&gt;. Generate or paste a 12-word recovery phrase. Reply `done` once it's sealed.
-4. (done + free-tier confirmation)
-   > ✓ You're set up on the TotalReclaw free tier — 500 memories/month, unlimited reads. https://totalreclaw.xyz/pricing. Ask me to remember anything.
-
-If existing credentials are detected (step "Check for existing credentials" below), emit ONLY this line and stop:
-   > ✓ TotalReclaw is already set up.
-
-### Hard silence rules between numbered lines
-
-Do NOT emit transitional / narrative lines between any of the four user-visible lines above. Specifically forbidden (verbatim examples from Pedro's 2026-05-06 QA):
-
-- ❌ "Now let me verify the install:" → silent. Just run `tr status --json`. Emit line 2 when it returns.
-- ❌ "Now let me check if you already have credentials:" → silent. Just run `test -s ~/.totalreclaw/credentials.json`.
-- ❌ "Need to pair. Let me kick that off:" → silent. Just run the `setsid -f` block. Emit line 3 when URL+PIN returns. ALSO never use the word "pair" in user-facing text — see vocabulary table above.
-- ❌ "Standing by." → silent. Acknowledgements between lines are noise.
-- ❌ Any "Let me X" / "Now I'll Y" / "Just give me a second" prelude.
-- ❌ **Skipping line 1 entirely and going straight to shell tool calls.** Line 1 ack must precede the first tool call. Silent install = user thinks the prompt didn't register.
-
-The transcript Pedro should see is exactly four messages — the four numbered lines, nothing in between. Line 1 fires immediately. Lines 2–4 fire as work completes. No prose between.
-
-## How does TotalReclaw work? (canonical answer for user questions)
-
-When the user asks "how does this work?" / "where are my memories stored?" / "is this safe?" / similar — answer with this content. Do NOT say "stored on a relay server", "stored on TotalReclaw's server", or any phrasing that implies single-company custody. The actual architecture:
-
-> **End-to-end encrypted, decentralized memory.** When you tell me to remember something, I encrypt it locally with a key derived from your 12-word recovery phrase, then submit it on-chain via Account Abstraction (a UserOperation). It lives on a public blockchain (Base Sepolia for free tier, Gnosis mainnet for paid). The Graph subgraph indexes it for fast retrieval. The TotalReclaw relay server only forwards encrypted bundles between your client and the chain — it never sees plaintext, can't read your memories, and could be replaced by any compatible relay without losing data. Your recovery phrase is the only thing that can decrypt the memories. Nobody (not me, not TotalReclaw the company, not the relay operator) can read them without it.
-
-If the user asks shorter questions, reply with the relevant slice:
-
-- **"Where are memories stored?"** → "Encrypted, on-chain (Base or Gnosis depending on your tier), indexed by The Graph. Not on any single company's server."
-- **"Is the relay reading my data?"** → "No. The relay only forwards encrypted bundles. Plaintext never leaves your device. Only your recovery phrase can decrypt them."
-- **"What if TotalReclaw shuts down?"** → "Your memories survive. They're on a public blockchain. Any compatible relay (or self-hosted relay) can read them with your recovery phrase."
-
-## Setup flow (hybrid-primary)
-
-1. **Install plugin first, skill second (silent — emit user-visible line 1 once at the start, then no prose until line 2).** Run via your shell tool, in this exact order:
-   ```
-   openclaw plugins install @totalreclaw/totalreclaw
-   openclaw skills install totalreclaw
-   ```
-   For RC: replace the first command with `openclaw plugins install @totalreclaw/totalreclaw@rc`. **Plugin BEFORE skill is deliberate** (3.3.4-rc.1 — issue from Pedro's QA on rc.3): the skill install triggers a config-driven SIGUSR1 gateway reload that can race a concurrent plugin install.
-
-   If either shell call fails with `command not found` / ENOENT / "not authorized" (managed-service or shell-restricted environment), tell the user verbatim *"Your environment doesn't expose the OpenClaw CLI to me. Please install `totalreclaw` from your service's plugins / skills UI, then reply `done`."* Wait for `done` and skip to step 3.
+openclaw plugins install @totalreclaw/totalreclaw@rc
+openclaw skills install totalreclaw
+```
 
-2. **Verify CLI works — emit user-visible line 2 when successful.** Resolve `TR_CLI` and run:
-   ```bash
-   TR_CLI="$(ls -d ~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/tr-cli.js ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js 2>/dev/null | head -1)"
-   node "$TR_CLI" status --json
-   ```
-   Parse the JSON. When you get `{"version": "...", "hybrid_mode": true, ...}`, emit user-visible line 2 with the version substituted. **Do NOT wait for tool binding. Do NOT issue `/totalreclaw-restart`. Do NOT check whether `totalreclaw_pair` is in your toolset.** The CLI works independently of tool binding. If `tr status` exits non-zero or the file doesn't exist, wait 5s and retry once — it may still be installing.
+Plugin is published on npm + ClawHub (`p-diogo`, GitHub-verified). Stable: drop `@rc`. Under hybrid-primary, the `tr` CLI is the primary path; native `totalreclaw_*` tools are also bound when OpenClaw exposes them — use whichever your runtime binds.
 
-3. **Check for existing credentials (silent unless found).** Run `test -s ~/.totalreclaw/credentials.json`. If it exists and is non-empty, emit *"✓ TotalReclaw is already set up."* and stop.
+## Setup (plugin-driven)
 
-4. **Set up the user's TotalReclaw account IMMEDIATELY — no consent gate.** As soon as `tr status --json` returns and credentials are not present, run pair in DETACHED mode. CRITICAL: a foreground `node tr-cli pair` is killed when the gateway fires its post-install SIGUSR1 reload (3.3.10 finding from Pedro's 2026-05-05 QA — relay logs `gateway_disconnected` 502 on `/respond`). Use `setsid -f` so the pair process is in its own session and survives any subsequent gateway SIGUSR1 reload. The handshake URL+PIN is written to a tmp file the moment the WS opens (~100-500ms typical):
-   ```bash
-   PAIR_OUT="/tmp/tr-pair-out-$(date +%s).json"
-   setsid -f node "$TR_CLI" pair --json > "$PAIR_OUT" 2>&1 < /dev/null
-   sleep 2
-   cat "$PAIR_OUT"
-   ```
-   This is UNCONDITIONAL. Do NOT ask "Would you like to set up an account?" or "Want me to pair now?". The user installed TotalReclaw — setup is the expected next step. The URL + PIN itself is the consent moment (the user can simply not open the page to opt out). Parse the JSON response `{"url": "...", "pin": "...", "expires_at_ms": ...}` and emit user-visible line 3. If the cat output is empty after 2s, sleep 2 more seconds and try again (relay handshake can take up to 4s on a cold network). If `tr pair --json` is not available (old install), fall back to `totalreclaw_pair` tool or `openclaw totalreclaw pair generate --url-pin-only`.
+The plugin auto-creates a pair session on first load when no credentials exist, writes `{url, pin, sid, expires_at_ms}` to `~/.totalreclaw/.pair-pending.json`, and injects a `before_agent_start` context block to you. **When you see that block, surface the URL and PIN to the user VERBATIM — read from the injected context; never invent values.** Confirm on pair completion: `✓ TotalReclaw set up.` (If credentials already exist: `✓ TotalReclaw is already set up.`)
 
-5. **Verify and confirm (silent until line 4).** After the user says `done`, re-run `test -s ~/.totalreclaw/credentials.json`. If missing, the PIN expired — repeat the `setsid -f node "$TR_CLI" pair --json` block and resend line 3 once. If present, emit user-visible line 4 and stop.
+If a restart is needed (rare — plugin self-handles via gateway config-watcher), issue the literal slash command `/totalreclaw-restart`. Never `kill`, `docker restart`, or prompt the user to restart.
 
-## `tr` CLI reference (hybrid-primary commands)
+## Hybrid-primary CLI
 
-Always use `--json` flag when running from shell for machine-parseable output. Plain text mode is for direct user invocation only.
+OpenClaw 2026.5.x may strip non-bundled tool bindings (issue #223). Never rely on `totalreclaw_*` tool binding alone. Fall back via shell:
 
 ```bash
-# (Resolve TR_CLI once at the top of your session)
 TR_CLI="$(ls -d ~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/tr-cli.js ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js 2>/dev/null | head -1)"
-
-# Status check (parse JSON to confirm install + onboarding state)
-node "$TR_CLI" status --json
-# Returns: {"version":"3.3.11-rc.1","onboarded":false,"next_step":"pair","tool_count":17,"hybrid_mode":true}
-
-# Pair / account setup — ALWAYS run via setsid -f to survive gateway restarts
-PAIR_OUT="/tmp/tr-pair-out-$(date +%s).json"
-setsid -f node "$TR_CLI" pair --json > "$PAIR_OUT" 2>&1 < /dev/null && sleep 2 && cat "$PAIR_OUT"
-# Returns: {"v":1,"sid":"...","url":"https://...","pin":"123456","mode":"generate","expires_at_ms":...,"qr_ascii":"..."}
-
-# Remember a fact (foreground OK — non-blocking single-shot HTTP call)
+node "$TR_CLI" status --json     # {"version":"...","hybrid_mode":true,"tool_count":17}
 node "$TR_CLI" remember --json "I work at Graph Foundation"
-# Returns: {"ok":true,"id":"...","claim_count":N}
-
-# Recall memories
-node "$TR_CLI" recall --json "where does the user work" --limit 5
-# Returns: {"results":[{"text":"...","score":0.8},...]}
-```
-
-**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 (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:
-
+node "$TR_CLI" recall --json "where does the user work" --limit 5   # {"results":[{"text":"...","score":0.8}]}
+node "$TR_CLI" pair --json       # {"url":"...","pin":"123456","expires_at_ms":...} — plugin's auto-pair is preferred; only use this for re-pair
 ```
-<qr_ascii contents — 43 lines of ▄▀█▄▀█ block chars>
-```
-
-Open <url> in your browser. Enter PIN <pin>. Generate or paste a 12-word recovery phrase. Reply `done` once it's sealed.
 
-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"** → confirm the URL host is `api.totalreclaw.xyz` (the default for both stable and RC post-3.3.12-rc.1). If a `TOTALRECLAW_SERVER_URL` env override was set, the host might be `api-staging.totalreclaw.xyz` (staging, opt-in) or a self-hosted relay. 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.
-
-## Usage (post-setup)
-
-- Stable user facts / preferences / identity / "remember X":
-  ```bash
-  node "$TR_CLI" remember --json "<fact>"
-  ```
-- First-person factual query ("do I / what's my / where do I…"):
-  ```bash
-  node "$TR_CLI" recall --json "<query>" --limit 5
-  ```
-  Recall FIRST, then answer from returned facts. If 0 results, say so.
-- For forget / pin / unpin / retype / set_scope — use native tools if available, or ask user to run `openclaw totalreclaw` subcommand.
-- "status" → `tr status --json` (parse version + onboarded + next_step).
-- "upgrade" → `totalreclaw_upgrade` native tool (paste Stripe URL verbatim). Post-upgrade testnet → mainnet: `totalreclaw_migrate` with `dry_run` first.
-- "import / export / consolidate" → `totalreclaw_import_from` · `totalreclaw_export` · `totalreclaw_consolidate` native tools.
-
-**Forbidden vocabulary** (these are anti-patterns that violate the silence rule):
-- "Let me check that…"
-- "Plugin loaded. Let me verify…"
-- "I'll now…"
-- "Quick fix…"
-- "However, I don't see…"
-- "I need to use…"
-- "Should I /totalreclaw-restart" / "Do you have a public URL" / "Want me to restart" / "Let me check if the tool is bound" / "I need permission to restart"
-- "Now installing…" / "Got it" / "In parallel…" / "Step 1a/1b/1c"
-- "local" / "local-only" / "stored locally" / "on disk" / "without an account" / "local memory" / "local storage"
-
-## Diagnostics
-
-- `tr` CLI not found → plugin not installed or install still in progress. Wait 5s, retry. If still missing, retry `openclaw plugins install @totalreclaw/totalreclaw@rc` once.
-- `totalreclaw_*` tools not visible → EXPECTED under OpenClaw 2026.5.2 (issue #223). Use `tr` CLI instead. Do not restart, do not issue `/totalreclaw-restart`, do not issue `/new`.
-- If `/totalreclaw-restart` is needed for another reason, issue the literal slash command `/totalreclaw-restart` — nothing else. Do not narrate.
-- User says done but `credentials.json` missing → PIN expired or entered wrong phrase; re-run `tr pair --json` and resend line 3 once.
-- `onboarding required` → credentials missing; redo from the account-setup step.
-- `quota exceeded` → `tr status --json` or `totalreclaw_status`, then offer `totalreclaw_upgrade`.
-- `No LLM available for auto-extraction` at startup → provider key unreachable; check `~/.openclaw/agents/<agent>/agent/auth-profiles.json` or plugin config `extraction.llm`.
-
-## Required post-install config (OpenClaw 2026.5.2+)
-
-Add to `~/.openclaw/openclaw.json` after installing:
-```json
-{
-  "plugins": {
-    "allow": ["totalreclaw"],
-    "entries": {
-      "totalreclaw": {
-        "hooks": { "allowConversationAccess": true }
-      }
-    }
-  }
-}
-```
+Pair is UNCONDITIONAL when no credentials — pasting the install URL IS the consent. `tr --help` lists every subcommand.
 
-`plugins.allow` suppresses the "plugins.allow is empty" warning. `hooks.allowConversationAccess` unlocks typed hooks (`agent_end`, etc.) for auto-extraction.
+## Tools (17 native; same surface via `tr`)
 
-## Tool surface
+`totalreclaw_remember` · `totalreclaw_recall` · `totalreclaw_forget` · `totalreclaw_pair` · `totalreclaw_pin` · `totalreclaw_unpin` · `totalreclaw_retype` · `totalreclaw_set_scope` · `totalreclaw_export` · `totalreclaw_import_from` · `totalreclaw_import_batch` · `totalreclaw_consolidate` · `totalreclaw_status` · `totalreclaw_upgrade` · `totalreclaw_migrate` · `totalreclaw_onboarding_start` · `totalreclaw_report_qa_bug` (RC only).
 
-Hybrid-primary: `tr remember` · `tr recall` · `tr pair` · `tr status` (primary path for all agent ops)
-Native fallback (when available): `totalreclaw_pair` · `_remember` · `_recall` · `_forget` · `_pin` · `_unpin` · `_retype` · `_set_scope` · `_export` · `_status` · `_upgrade` · `_migrate` · `_import_from` · `_import_batch` · `_consolidate` · `_onboarding_start` · `_report_qa_bug` (RC only)
+Full guides: <https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/openclaw-setup.md>