@totalreclaw/totalreclaw 3.2.3 → 3.3.0-rc.2

package/README.md

@@ -96,7 +96,36 @@ openclaw plugins install @totalreclaw/totalreclaw
 
 ### 2. Configure
 
-Set one environment variable:
+You have three ways to set up TotalReclaw, depending on where your OpenClaw gateway runs.
+
+**Local gateway (laptop / workstation):** run the CLI wizard on the same machine:
+
+```bash
+openclaw totalreclaw onboard
+```
+
+The wizard generates or accepts a 12-word BIP-39 TotalReclaw account key directly on your terminal. The phrase never touches the LLM, the chat transcript, or the network -- it's written straight to `~/.totalreclaw/credentials.json` (mode 0600).
+
+**Remote gateway (VPS, home server, shared / team):** use QR-pairing (new in v3.3.0).
+
+On the gateway host:
+
+```bash
+openclaw totalreclaw pair           # generate a new account key
+openclaw totalreclaw pair import    # import an existing TotalReclaw key
+```
+
+You'll see a QR code, a 6-digit secondary code, and a URL. Scan the QR with your phone's camera or open the URL on any modern browser. The browser page:
+
+1. Asks you to enter the 6-digit code (prevents a bystander from hijacking the session).
+2. Generates or accepts your 12-word account key in-page.
+3. Encrypts it end-to-end (x25519 + ChaCha20-Poly1305, key derived from a DH shared secret the relay never sees) and delivers it to your gateway.
+
+The phrase never enters the LLM, the chat transcript, or the relay server in plaintext. The pairing URL embeds the gateway's ephemeral public key in the URL fragment -- this is TLS-MITM resistant and invisible to any server on the path. See `CHANGELOG.md` §3.3.0 for the full threat model.
+
+Browser support: Safari 17+, Chrome 123+, Firefox 130+ (these ship WebCrypto x25519 + ChaCha20-Poly1305).
+
+**Legacy / self-hosted:** set the env var directly (useful for containers / CI):
 
 ```bash
 export TOTALRECLAW_RECOVERY_PHRASE="your twelve word recovery phrase here"
@@ -104,7 +133,7 @@ export TOTALRECLAW_RECOVERY_PHRASE="your twelve word recovery phrase here"
 
 **That's it.** v1 is the default extraction and write path. Extraction cadence, importance floor, candidate pool size, and dedup thresholds are all server-tuned via the relay's billing response -- no client env vars to set. See [env vars reference](../../docs/guides/env-vars-reference.md).
 
-For self-hosted deployments:
+For self-hosted relays:
 
 ```bash
 export TOTALRECLAW_SERVER_URL="http://your-totalreclaw-server:8080"

package/config.ts

@@ -99,6 +99,11 @@ export const CONFIG = {
   // never contains secrets. Loaded on every plugin init + on every
   // before_tool_call gate check.
   onboardingStatePath: process.env.TOTALRECLAW_STATE_PATH || path.join(home, '.totalreclaw', 'state.json'),
+  // 3.3.0 QR-pairing session store. Separate file from both credentials.json
+  // and state.json so the session-store module does not have to touch either
+  // (keeps scanner surface isolated). Contains ephemeral x25519 secret keys
+  // for 15-min TTL windows; 0600 mode.
+  pairSessionsPath: process.env.TOTALRECLAW_PAIR_SESSIONS_PATH || path.join(home, '.totalreclaw', 'pair-sessions.json'),
 
   // Chain — chainId is no longer user-configurable. It is auto-detected from
   // the relay billing response (free = Base Sepolia / 84532, Pro = Gnosis /

package/first-run.ts

@@ -0,0 +1,131 @@
+/**
+ * first-run — detect a fresh machine and return the welcome/branch-question
+ * copy that the `before_agent_start` hook prepends to the first agent prompt
+ * after install.
+ *
+ * Shipped 2026-04-20 as part of the 3.3.0-rc.2 UX polish. Paired with the
+ * scanner false-positive fix that unblocked rc.1 install.
+ *
+ * Scope and scanner surface
+ * -------------------------
+ *   - This module reads credentials.json via `loadCredentialsJson` from
+ *     `fs-helpers.ts` (the one file in the plugin that is allowed to touch
+ *     disk) — we do NOT import `node:fs` directly. That preserves the
+ *     file-level isolation pattern introduced in 3.0.8 (see `fs-helpers.ts`
+ *     header) and ensures the expanded `check-scanner.mjs` rules cannot
+ *     flag this file even incidentally.
+ *   - No network. No env-var reads. No dynamic code execution.
+ *   - All user-facing copy is exported as `COPY` so tests can assert on
+ *     exact strings and a future localisation pass has a single seam.
+ *
+ * Design notes
+ * ------------
+ *   - `detectFirstRun` is deliberately lax: missing file, empty file,
+ *     JSON-parse-error, or a file that parses but carries no usable
+ *     mnemonic (neither `mnemonic` nor the `recovery_phrase` alias) all
+ *     count as first-run. Anything looser would risk double-welcoming a
+ *     returning user whose credentials.json has been hand-edited.
+ *   - `buildWelcomePrepend` branches on `'local'` vs `'remote'` gateway
+ *     mode. The caller in `index.ts` resolves the mode from
+ *     `api.config.gateway.remote.url` the same way `buildPairingUrl`
+ *     already does.
+ *   - Terminology: "recovery phrase" everywhere in user-facing copy. The
+ *     prior mix of "account key", "mnemonic", "seed phrase", and "recovery
+ *     phrase" across the plugin was confusing users; 3.3.0-rc.2
+ *     standardises on "recovery phrase". Internal variable names
+ *     (`mnemonic`, etc.) are intentionally kept so we do not churn the
+ *     crypto code for a copy change.
+ */
+
+import { loadCredentialsJson, extractBootstrapMnemonic } from './fs-helpers.js';
+
+// ---------------------------------------------------------------------------
+// Canonical copy — single source of truth for the welcome-on-first-run UX.
+// Tests import these constants and assert on exact-match substrings; the
+// `index.ts` before_agent_start hook consumes them via `buildWelcomePrepend`.
+// ---------------------------------------------------------------------------
+
+export const WELCOME =
+  'Welcome to TotalReclaw — encrypted, agent-portable memory.\n\n' +
+  'Your memories are stored end-to-end encrypted and on-chain. You can restore them on any agent — OpenClaw, Hermes, or NanoClaw — with a single recovery phrase.';
+
+export const BRANCH_QUESTION =
+  "Let's set up your account. Do you already have a recovery phrase, or should we generate a new one?";
+
+export const LOCAL_MODE_INSTRUCTIONS =
+  'If you have one, run: openclaw plugin totalreclaw onboard restore\n' +
+  'If you need a new one, run: openclaw plugin totalreclaw onboard generate';
+
+export const REMOTE_MODE_INSTRUCTIONS =
+  'Run: openclaw plugin totalreclaw pair start\n' +
+  'This opens a browser page with a QR code. Scan it (or open the URL) to complete setup securely — your recovery phrase never passes through the chat.';
+
+export const STORAGE_GUIDANCE =
+  'Your recovery phrase is 12 words. Store it somewhere safe — a password manager works well. Use it only for TotalReclaw. Don\'t reuse it anywhere else. Don\'t put funds on it.';
+
+export const RESTORE_PROMPT =
+  'Enter your 12-word recovery phrase to restore your account.';
+
+export const GENERATED_CONFIRMATION =
+  'A new recovery phrase has been generated. Write it down now, somewhere safe. This is the only way to restore your account later.';
+
+export const COPY = {
+  WELCOME,
+  BRANCH_QUESTION,
+  LOCAL_MODE_INSTRUCTIONS,
+  REMOTE_MODE_INSTRUCTIONS,
+  STORAGE_GUIDANCE,
+  RESTORE_PROMPT,
+  GENERATED_CONFIRMATION,
+} as const;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export type GatewayMode = 'local' | 'remote';
+
+/**
+ * Returns `true` when the machine at `credentialsPath` has never been
+ * onboarded. Specifically: the file is missing, unreadable, invalid JSON,
+ * or parses but carries neither `mnemonic` nor `recovery_phrase`.
+ *
+ * All failure modes collapse to "first run" so the welcome can always
+ * recover from a broken install. The caller is responsible for deciding
+ * whether to ALSO preserve the broken file for recovery (the onboarding
+ * wizard already handles that via `autoBootstrapCredentials`).
+ */
+export async function detectFirstRun(credentialsPath: string): Promise<boolean> {
+  const creds = loadCredentialsJson(credentialsPath);
+  if (!creds) return true;
+  const mnemonic = extractBootstrapMnemonic(creds);
+  return mnemonic === null || mnemonic.length === 0;
+}
+
+/**
+ * Build the exact text to feed `prependContext` on first run. The text is
+ * structured as a markdown block with a visible heading so the agent and
+ * user can both tell at a glance that this is the one-shot first-run
+ * banner, not arbitrary injected context.
+ *
+ * The mode-specific instructions branch on whether the gateway is running
+ * locally (user has shell access → CLI onboard wizard) or remotely (user
+ * needs QR-pairing). The caller resolves the mode from
+ * `api.config.gateway.remote.url` — same resolution `buildPairingUrl`
+ * uses.
+ */
+export function buildWelcomePrepend(mode: GatewayMode): string {
+  const instructions =
+    mode === 'local' ? LOCAL_MODE_INSTRUCTIONS : REMOTE_MODE_INSTRUCTIONS;
+
+  return (
+    '## Welcome to TotalReclaw\n\n' +
+    WELCOME +
+    '\n\n' +
+    BRANCH_QUESTION +
+    '\n\n' +
+    instructions +
+    '\n\n' +
+    STORAGE_GUIDANCE
+  );
+}

package/index.ts

@@ -136,6 +136,7 @@ import {
   type OnboardingState,
 } from './fs-helpers.js';
 import { decideToolGate, isGatedToolName } from './tool-gating.js';
+import { detectFirstRun, buildWelcomePrepend, type GatewayMode } from './first-run.js';
 import crypto from 'node:crypto';
 
 // ---------------------------------------------------------------------------
@@ -204,6 +205,16 @@ interface OpenClawPluginApi {
       config?: unknown;
     }) => { text: string } | Promise<{ text: string }>;
   }): void;
+  /**
+   * 3.3.0 — register an HTTP route on the gateway's HTTP server.
+   * Used by the QR-pairing flow to serve the pairing page + the
+   * encrypted-payload respond endpoint. Path is exact-match against
+   * `new URL(req.url, ...).pathname`; no params supported.
+   */
+  registerHttpRoute?(params: {
+    path: string;
+    handler: (req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse) => Promise<void> | void;
+  }): void;
 }
 
 // ---------------------------------------------------------------------------
@@ -245,6 +256,110 @@ function humanizeError(rawMessage: string): string {
 /** Path where we persist userId + salt across restarts. */
 const CREDENTIALS_PATH = CONFIG.credentialsPath;
 
+// ---------------------------------------------------------------------------
+// 3.3.0 — pairing URL resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the full pairing URL (including `#pk=` fragment) for a fresh
+ * pairing session. Pulls gateway config from `api.config.gateway`.
+ *
+ * Resolution order (mirrors the device-pair extension):
+ *   1. pluginConfig.publicUrl (if the operator set it explicitly)
+ *   2. gateway.remote.url (if the gateway is marked remote)
+ *   3. gateway.bind=custom + customBindHost + port
+ *   4. gateway.bind=tailnet/lan is acknowledged but we do NOT probe
+ *      the host here (network calls); we fall back to localhost with
+ *      a warning log.
+ *   5. gateway.port default = 18789 + localhost.
+ *
+ * Always returns a working URL string; never throws. The caller can
+ * log a warning if the URL is localhost and the gateway is remote,
+ * but the CLI always prints whatever we give it.
+ */
+function buildPairingUrl(
+  api: Pick<OpenClawPluginApi, 'config' | 'pluginConfig' | 'logger'>,
+  session: { sid: string; pkGatewayB64: string },
+): string {
+  const cfg = api.config as {
+    gateway?: {
+      port?: number;
+      bind?: string;
+      customBindHost?: string;
+      tls?: { enabled?: boolean };
+      remote?: { url?: string };
+    };
+  } | undefined;
+  const pluginCfg = (api.pluginConfig ?? {}) as { publicUrl?: string };
+
+  const tlsEnabled = cfg?.gateway?.tls?.enabled === true;
+  const scheme = tlsEnabled ? 'https' : 'http';
+  const port = cfg?.gateway?.port ?? 18789;
+
+  let base: string;
+  if (typeof pluginCfg.publicUrl === 'string' && pluginCfg.publicUrl.trim()) {
+    base = pluginCfg.publicUrl.replace(/\/+$/, '');
+    // If the user gave us a ws:// URL, rewrite to http(s)://
+    base = base.replace(/^wss:\/\//i, 'https://').replace(/^ws:\/\//i, 'http://');
+  } else if (typeof cfg?.gateway?.remote?.url === 'string' && cfg.gateway.remote.url.trim()) {
+    base = cfg.gateway.remote.url.trim().replace(/\/+$/, '');
+    base = base.replace(/^wss:\/\//i, 'https://').replace(/^ws:\/\//i, 'http://');
+  } else if (cfg?.gateway?.bind === 'custom' && cfg.gateway.customBindHost) {
+    base = `${scheme}://${cfg.gateway.customBindHost}:${port}`;
+  } else {
+    const bind = cfg?.gateway?.bind;
+    if (bind === 'lan' || bind === 'tailnet') {
+      api.logger.warn(
+        `TotalReclaw: pairing URL is falling back to localhost because gateway.bind=${bind} without explicit host probe. ` +
+          'Set plugins.entries.totalreclaw.config.publicUrl to override.',
+      );
+    }
+    base = `${scheme}://localhost:${port}`;
+  }
+
+  return `${base}/plugin/totalreclaw/pair/finish?sid=${encodeURIComponent(session.sid)}#pk=${encodeURIComponent(session.pkGatewayB64)}`;
+}
+
+/**
+ * Resolve whether this plugin is running on a `local` or `remote` gateway.
+ *
+ * Follows the same config surface `buildPairingUrl` uses:
+ *   - `pluginConfig.publicUrl` set + non-localhost     → remote
+ *   - `gateway.remote.url` set + non-localhost         → remote
+ *   - `gateway.bind === 'lan' | 'tailnet' | 'custom'`  → remote
+ *   - anything else                                    → local
+ *
+ * We treat a `publicUrl` or `remote.url` that points at `localhost` /
+ * `127.*` as local because that is what a dev-loopback override looks like;
+ * no one publishes a remote QR pairing for localhost.
+ */
+function resolveGatewayMode(
+  api: Pick<OpenClawPluginApi, 'config' | 'pluginConfig'>,
+): GatewayMode {
+  const cfg = api.config as
+    | { gateway?: { bind?: string; remote?: { url?: string } } }
+    | undefined;
+  const pluginCfg = (api.pluginConfig ?? {}) as { publicUrl?: string };
+  const looksLocal = (url: string | undefined): boolean => {
+    if (!url) return true;
+    const u = url.trim().toLowerCase();
+    if (u === '') return true;
+    return /^(?:wss?:\/\/|https?:\/\/)?(?:localhost|127\.|0\.0\.0\.0)/.test(u);
+  };
+  if (typeof pluginCfg.publicUrl === 'string' && !looksLocal(pluginCfg.publicUrl)) {
+    return 'remote';
+  }
+  const remoteUrl = cfg?.gateway?.remote?.url;
+  if (typeof remoteUrl === 'string' && !looksLocal(remoteUrl)) {
+    return 'remote';
+  }
+  const bind = cfg?.gateway?.bind;
+  if (bind === 'lan' || bind === 'tailnet' || bind === 'custom') {
+    return 'remote';
+  }
+  return 'local';
+}
+
 // ---------------------------------------------------------------------------
 // Cosine similarity threshold — skip injection when top result is below this
 // ---------------------------------------------------------------------------
@@ -458,6 +573,15 @@ let needsSetup = false;
 /** True on first before_agent_start after successful init — show welcome message once. */
 let firstRunAfterInit = true;
 
+/**
+ * Once-per-gateway-session flag for the 3.3.0-rc.2 first-run welcome banner.
+ * The banner fires on the first `before_agent_start` after install when
+ * credentials.json is absent/empty — exactly once per gateway process.
+ * A second before_agent_start in the same session finds this flipped and
+ * skips. A fresh gateway restart resets it back to `false`.
+ */
+let firstRunWelcomeShown = false;
+
 /**
  * Derive keys from the recovery phrase, load credentials, and register with
  * the server if this is the first run.
@@ -659,7 +783,7 @@ function buildSetupErrorMsg(): string {
 function buildSetupErrorMsgLegacy(): string {
   const base =
     'TotalReclaw setup required:\n' +
-    '1. Set TOTALRECLAW_RECOVERY_PHRASE — ask the user if they have an existing recovery phrase or generate a new 12-word BIP-39 mnemonic.\n' +
+    '1. Set TOTALRECLAW_RECOVERY_PHRASE — ask the user if they have an existing recovery phrase or generate a new 12-word recovery phrase.\n' +
     '2. Restart the gateway to apply changes.\n' +
     '   (Optional: set TOTALRECLAW_SELF_HOSTED=true if using your own server instead of the managed service.)\n\n';
 
@@ -2557,6 +2681,14 @@ const plugin = {
             statePath: CONFIG.onboardingStatePath,
             logger: api.logger,
           });
+          // 3.3.0 — `openclaw totalreclaw pair [generate|import]` attaches
+          // alongside the existing `onboard` + `status` subcommands.
+          const { registerPairCli } = await import('./pair-cli.js');
+          registerPairCli(program as import('commander').Command, {
+            sessionsPath: CONFIG.pairSessionsPath,
+            renderPairingUrl: (session) => buildPairingUrl(api, session),
+            logger: api.logger,
+          });
         },
         { commands: ['totalreclaw'] },
       );
@@ -2567,6 +2699,69 @@ const plugin = {
       );
     }
 
+    // ---------------------------------------------------------------
+    // 3.3.0 — HTTP routes for QR-pairing (pair-http)
+    // ---------------------------------------------------------------
+    //
+    // Four endpoints under /plugin/totalreclaw/pair/ are registered on
+    // the gateway's HTTP server. Collectively they serve the browser
+    // pairing page, verify the 6-digit secondary code, accept the
+    // encrypted mnemonic payload, and expose a status polled by the
+    // CLI. See pair-http.ts and the 2026-04-20 design doc.
+    if (typeof api.registerHttpRoute === 'function') {
+      (async () => {
+        try {
+          const { buildPairRoutes } = await import('./pair-http.js');
+          const { validateMnemonic } = await import('@scure/bip39');
+          const { wordlist } = await import('@scure/bip39/wordlists/english.js');
+          const bundle = buildPairRoutes({
+            sessionsPath: CONFIG.pairSessionsPath,
+            apiBase: '/plugin/totalreclaw/pair',
+            logger: api.logger,
+            validateMnemonic: (p) => validateMnemonic(p, wordlist),
+            completePairing: async ({ mnemonic }) => {
+              // Write credentials.json + flip state to 'active' via
+              // fs-helpers. This centralizes disk I/O off the
+              // pair-http surface (scanner isolation).
+              const creds = loadCredentialsJson(CREDENTIALS_PATH) ?? {};
+              const next = { ...creds, mnemonic };
+              if (!writeCredentialsJson(CREDENTIALS_PATH, next)) {
+                return { state: 'error', error: 'credentials_write_failed' };
+              }
+              // Hot-reload: update the runtime override so existing
+              // in-memory state picks up the new phrase without a
+              // process restart.
+              setRecoveryPhraseOverride(mnemonic);
+              // Flip onboarding state. writeOnboardingState is in
+              // fs-helpers; dynamic import to keep it out of any
+              // potential scanner collision surface in this file.
+              const { writeOnboardingState } = await import('./fs-helpers.js');
+              writeOnboardingState(CONFIG.onboardingStatePath, {
+                onboardingState: 'active',
+                createdBy: 'generate',
+                credentialsCreatedAt: new Date().toISOString(),
+                version: '3.3.0',
+              });
+              return { state: 'active' };
+            },
+          });
+          api.registerHttpRoute!({ path: bundle.finishPath, handler: bundle.handlers.finish });
+          api.registerHttpRoute!({ path: bundle.startPath, handler: bundle.handlers.start });
+          api.registerHttpRoute!({ path: bundle.respondPath, handler: bundle.handlers.respond });
+          api.registerHttpRoute!({ path: bundle.statusPath, handler: bundle.handlers.status });
+          api.logger.info('TotalReclaw: registered 4 QR-pairing HTTP routes');
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          api.logger.error(`TotalReclaw: failed to register pairing HTTP routes: ${msg}`);
+        }
+      })();
+    } else {
+      api.logger.warn(
+        'api.registerHttpRoute is unavailable on this OpenClaw version — /totalreclaw pair will not work. ' +
+          'Use `openclaw totalreclaw onboard` on the gateway host instead.',
+      );
+    }
+
     // ---------------------------------------------------------------
     // 3.2.0 — slash command `/totalreclaw {onboard,status}` (in-chat bridge)
     // ---------------------------------------------------------------
@@ -2583,17 +2778,48 @@ const plugin = {
         acceptsArgs: true,
         requireAuth: false,
         handler: async (ctx) => {
-          const sub = (ctx.args || '').trim().split(/\s+/)[0]?.toLowerCase() || 'help';
+          const args = (ctx.args || '').trim();
+          const parts = args.split(/\s+/).filter(Boolean);
+          const sub = (parts[0] || 'help').toLowerCase();
           if (sub === 'onboard' || sub === 'setup' || sub === 'init') {
             return {
               text:
-                'To set up TotalReclaw, open a terminal on this machine and run:\n\n' +
+                'To set up TotalReclaw on a local machine, run:\n\n' +
                 '    openclaw totalreclaw onboard\n\n' +
-                'Why a terminal? Your recovery phrase must never pass through the ' +
-                'LLM provider. This chat message is visible to the LLM, so we do ' +
-                'not show the phrase here. The wizard runs entirely on your local ' +
-                'machine — the phrase is generated, displayed, and stored on disk ' +
-                '(mode 0600) without ever touching the network.',
+                'For a REMOTE gateway (VPS, home server, etc.) use QR-pairing:\n\n' +
+                '    /totalreclaw pair\n\n' +
+                'Why not paste the phrase here? Chat messages are visible to the ' +
+                'LLM. Both flows keep your recovery phrase off the LLM transcript: ' +
+                'the CLI wizard runs on your terminal, and the QR-pair flow ' +
+                'encrypts the phrase in your browser before upload.',
+            };
+          }
+          if (sub === 'pair') {
+            // 3.3.0 — remote QR pairing. The slash command is a non-secret
+            // pointer: it tells the operator to run the CLI on the gateway
+            // host (which emits the QR + URL + code). Running the full
+            // pairing protocol directly from this handler would require
+            // sending the URL + code through the chat transcript, which
+            // the LLM would then see — acceptable for the URL + code (both
+            // are non-secret, because the gateway ephemeral pk lives in
+            // the URL fragment and the 6-digit code is one-shot), but
+            // requires the gateway to actually be reachable AND the user
+            // to type a code from chat into a browser on a different
+            // device. Design doc section 4a recommends the CLI path as
+            // primary. Chat-delivery is a future 3.4.0 enhancement.
+            return {
+              text:
+                'Remote pairing (QR):\n\n' +
+                '  On the gateway host, run:\n\n' +
+                '    openclaw totalreclaw pair         # generate new account\n' +
+                '    openclaw totalreclaw pair import  # import existing\n\n' +
+                'It will print a QR code + a 6-digit secondary code + a URL. ' +
+                'Scan the QR with your phone (or open the URL on any browser). ' +
+                'Enter the 6-digit code in the browser, write down (or paste) ' +
+                'your recovery phrase, and the gateway will activate.\n\n' +
+                'The phrase is generated (or pasted) in your BROWSER and ' +
+                'encrypted end-to-end before upload. It never touches the ' +
+                'LLM, this chat, or the relay server in plaintext.',
             };
           }
           if (sub === 'status') {
@@ -2610,13 +2836,14 @@ const plugin = {
                 `TotalReclaw onboarding state: ${stateLabel}.\n` +
                 (stateLabel === 'active'
                   ? 'Memory tools are active on this machine.'
-                  : 'Memory tools are gated. Run `openclaw totalreclaw onboard` in a terminal to complete setup.'),
+                  : 'Memory tools are gated. Run `openclaw totalreclaw onboard` (local) or `openclaw totalreclaw pair` (remote) to complete setup.'),
             };
           }
           return {
             text:
               'TotalReclaw slash commands:\n' +
               '  /totalreclaw onboard — how to set up TotalReclaw securely\n' +
+              '  /totalreclaw pair    — remote-gateway QR-pairing (3.3.0)\n' +
               '  /totalreclaw status  — current onboarding state',
           };
         },
@@ -4364,9 +4591,29 @@ const plugin = {
           // This contains ZERO secret material — the phrase never enters an
           // LLM request. The CLI wizard (`openclaw totalreclaw onboard`) is
           // the only surface that generates / reveals the recovery phrase.
+          //
+          // 3.3.0-rc.2: the FIRST time a fresh machine hits this branch we
+          // also include the welcome+branch-question banner (copy in
+          // `first-run.ts`). The flag is session-scoped so the welcome never
+          // fires twice in the same gateway process.
           if (needsSetup) {
+            let welcomeBlock = '';
+            try {
+              if (!firstRunWelcomeShown && (await detectFirstRun(CREDENTIALS_PATH))) {
+                const mode = resolveGatewayMode(api);
+                welcomeBlock = buildWelcomePrepend(mode) + '\n\n';
+                firstRunWelcomeShown = true;
+                api.logger.info(`TotalReclaw first-run welcome emitted (mode=${mode})`);
+              }
+            } catch (err) {
+              // Never block session start on the welcome — treat any failure
+              // as "skip the welcome, still emit the setup-pending banner".
+              const msg = err instanceof Error ? err.message : String(err);
+              api.logger.warn(`First-run welcome check failed: ${msg}`);
+            }
             return {
               prependContext:
+                welcomeBlock +
                 '## TotalReclaw setup pending\n\n' +
                 'TotalReclaw encrypted memory is installed but not yet set up on this machine. ' +
                 'If the user asks about memory features or wants to configure TotalReclaw, ' +

package/onboarding-cli.ts

@@ -124,7 +124,7 @@ export const COPY = {
     '\nWord mismatch. Please write the phrase down carefully and run this\n' +
     'wizard again. No credentials have been written.\n',
   importInvalid:
-    '\nInvalid BIP-39 phrase (12 words required, checksum must match).\n' +
+    '\nInvalid recovery phrase (12 words required, checksum must match).\n' +
     'No credentials have been written. Run the wizard again with the\n' +
     'correct phrase.\n',
   existingPhraseHint:
@@ -407,12 +407,19 @@ export async function runOnboardingWizard(deps: WizardDeps): Promise<WizardResul
     io.stdout.write(COPY.importRemoteLimitation);
     const mnemonic = genMnemonic();
     if (typeof mnemonic !== 'string' || mnemonic.trim().split(/\s+/).length !== 12) {
-      io.stderr.write('\nInternal error: mnemonic generator returned an invalid phrase.\n');
+      io.stderr.write('\nInternal error: recovery phrase generator returned an invalid phrase.\n');
       return { choice, error: 'generator-invalid' };
     }
 
     io.stdout.write('\nYour recovery phrase (WRITE THIS DOWN):\n\n');
     printMnemonicGrid(mnemonic, io.stdout);
+    // 3.3.0-rc.2: storage guidance canonical copy — emitted verbatim so
+    // the CLI, the browser page, and any future surface share identical
+    // wording. See first-run.ts COPY.STORAGE_GUIDANCE.
+    io.stdout.write(
+      '\n' +
+        'Your recovery phrase is 12 words. Store it somewhere safe — a password manager works well. Use it only for TotalReclaw. Don\'t reuse it anywhere else. Don\'t put funds on it.\n',
+    );
     io.stdout.write(COPY.clipboardHint);
     io.stdout.write('\n');
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.2.3",
+  "version": "3.3.0-rc.2",
   "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": [
@@ -34,7 +34,8 @@
     "@totalreclaw/client": "^1.2.0",
     "@totalreclaw/core": "^2.1.1",
     "@huggingface/transformers": "^4.0.1",
-    "onnxruntime-node": "^1.24.0"
+    "onnxruntime-node": "^1.24.0",
+    "qrcode-terminal": "^0.12.0"
   },
   "files": [
     "*.ts",
@@ -44,6 +45,7 @@
     "openclaw.plugin.json",
     "SKILL.md",
     "README.md",
+    "CHANGELOG.md",
     "CLAWHUB.md",
     "skill.json"
   ],