[p-diogo]

Summary

This PR implements review §4.5 (passkey onboarding review, 2026-11-03, F9), which Pedro approved on 2026-11-03. It is docs only, but it is rail-adjacent: it changes phrase-handling guidance and adds a new public guide. Draft for Pedro's look.

It is retargeted per Pedro's direction (parity plan D5, decided 2026-11-03). The MCP integration's first audience is chat apps: Claude Desktop first, then other MCP-capable chat apps and personal agents. Coding harnesses get a separate hook/CLI-skill integration later. So the primary guide is now a Claude Desktop guide. The Claude Code guide stays accurate but is secondary.

Setup uses totalreclaw_pair. The recovery phrase is created or entered in the browser, and never goes into chat, a config file, an env var or a tool argument.

Depends on (merge order)

The guides describe the fixed server behaviour, so this should merge after these ship in a published @totalreclaw/mcp-server stable (3.5.1):

• fix(mcp): pair waits for the whole relay session, honest instructions #729 (L2): pair waits the whole relay session (~10 min, was 60 s), and the instructions say "You're all set" and quit-and-reopen. The guides' "link works for about 10 minutes" and "versions before 3.5.1 stopped waiting after 60 seconds" depend on it. Before fix(mcp): pair waits for the whole relay session, honest instructions #729, generate mode usually could not be finished at all.
• fix(mcp): pair never replaces existing credentials; start unconfigured on keychain files #730 (L3, needs Pedro's sign-off): pair refuses to overwrite an existing credentials.json, and a Hermes keychain file gives not_configured with a reason instead of a crash. These guide statements depend on it: "setup never replaces an existing account file", "already_configured", and "not_configured with a reason… don't pair". If fix(mcp): pair never replaces existing credentials; start unconfigured on keychain files #730 does not make 3.5.1, those lines need softening before this merges.

The canonical install command everywhere is the bare npx -y @totalreclaw/mcp-server, which resolves to stable. @rc appears only in the "pin a version" aside.

Changes by file

• docs/guides/claude-desktop-setup.md (new, primary MCP guide). The flow:

  1. Edit claude_desktop_config.json via Settings → Developer → Edit Config, with no env block.
  2. Fully quit and reopen the app.
  3. Say "Set up TotalReclaw". Claude runs totalreclaw_pair and gives a link and PIN; the user finishes on the page.
  4. When the page says "You're all set", quit and reopen again.
  5. Try a memory.

  The guide also has: tool-permission advice (Always allow for recall/remember), "Already using TotalReclaw on this computer?" (shared credentials.json, the Hermes keychain gap, pairing never replaces the file), agent instructions for a chat assistant that can't edit config, troubleshooting (npx/nvm PATH, logs location, expired link / old server, keychain reason), the phrase-in-config path as a marked Advanced (not recommended) section (moved here from the Claude Code guide's role), and an "Other chat apps" note that dedicated guides are planned. No steps are invented for ChatGPT desktop or others.

• docs/guides/claude-code-setup.md. Retitled "TotalReclaw for Claude Code, Cursor, and Windsurf". It points chat-app users to the Desktop guide and says a dedicated coding-harness integration (hooks plus CLI skill) is planned. Claude Desktop is removed from Steps 1/2B/3 and from the config table. Step 4 now matches the fixed server: the totalreclaw_status branches (configured → skip; not_configured with reason → explain, don't pair), already_configured from 3.5.1 on, "always import, never generate" kept for older servers, and "link works for about 10 minutes". The "needs 3.5.0" line is now 3.5.1. Troubleshooting covers the 60 s failure and already_configured. The leaked-phrase advice no longer says to create a new account with generate, which 3.5.1 refuses on a configured machine; it says to treat the phrase as exposed and use totalreclaw_support. The previous reviewer's corrections stand: no claude mcp restart, the short-link wording (now concrete), and always import when TotalReclaw is already on the machine. The canonical prompt still points at this guide, as the QA harness expects.

• mcp/README.md. The quick start adds the ~10 min link and the quit-and-reopen step, and links the Desktop guide. The Hermes-keychain sentence now says the server reports it and leaves the account untouched; it no longer says "set up with your existing phrase". The Advanced link now targets the Desktop guide.

• docs/guides/install.md. The dispatcher routes chat apps (Claude Desktop, other chat apps) to the Desktop guide, and coding tools / IronClaw to the Claude Code guide. Its ambiguity question was updated to match.

• README.md. The Quick Start row "Claude Desktop / Cursor / Windsurf → npx @totalreclaw/mcp-server setup" (the phrase-printing wizard) is split into a Claude Desktop row (config + "Set up TotalReclaw", links the guide) and a coding-tools row. The per-client links are split the same way.

• docs/README.md, docs/guides/{hermes-setup,openclaw-setup,client-setup-v1,feature-comparison,env-vars-reference,beta-tester-guide,beta-tester-guide-detailed}.md. Cross-links send Claude Desktop to the new guide. beta-tester-guide-detailed.md no longer says MCP has "no account-setup flow".

Copy for Pedro's review (new and changed user-facing lines)

Where	Old	New
Desktop guide intro	(new guide)	TotalReclaw gives Claude Desktop encrypted memory that lasts across chats and works with your other TotalReclaw apps. Setup takes about five minutes: you add TotalReclaw to Claude Desktop's settings file, restart the app, and ask Claude to set it up. Claude gives you a link to finish in your browser. Your recovery phrase never goes through the chat and is never written into a settings file.
Desktop step 1	—	Claude can't change its own settings from a chat, so you do this step yourself. Then Settings → Developer → Edit Config + JSON with no env. There is no recovery phrase to add here and no env block.
Desktop step 2 / 4	—	macOS: press Cmd-Q, or choose Claude → Quit Claude. Windows: right-click the Claude icon in the system tray and choose Quit. Closing the window is not enough, because the app keeps running in the background.
Desktop step 3	—	Set up TotalReclaw … The link works for about 10 minutes, so there is time to write the phrase down carefully. If it expires, ask Claude for a new one. New user: Write it down on paper or save it in a password manager, then retype 3 of the words to confirm. It is the only way back into your memories if you lose this computer.
Desktop step 4	—	When the page says "You're all set", quit Claude Desktop … and open it again. TotalReclaw reads your account only when the app starts … The page suggests going back to your chat to try a memory; restart first.
Desktop permissions	—	If it offers "Always allow", choose it for totalreclaw_recall and totalreclaw_remember … Keep the prompt for tools that change or remove things.
Desktop "Already using"	—	Setup never replaces an existing account file … Don't move, rename or delete the file to get around this, because that would switch every TotalReclaw app on the computer to a different account. Hermes keychain: TotalReclaw doesn't work in Claude Desktop on that computer until keychain support arrives.
Desktop agent pairing message	—	Open this link in any browser, on this computer or your phone: . Enter this PIN when asked: . The link works for about 10 minutes; if it stops working, tell me and I'll make a new one. Tell me when the page says "You're all set".
Desktop agent restart message	—	Last step: quit Claude Desktop completely (Cmd-Q on macOS, or Quit from the tray icon on Windows) and open it again. TotalReclaw will work after that.
Claude Code guide title	TotalReclaw for Claude Code, Claude Desktop, Cursor, and Windsurf	TotalReclaw for Claude Code, Cursor, and Windsurf, plus A dedicated integration for coding tools is planned: hooks plus a CLI skill, so recall and capture happen automatically. Until it ships, this guide sets up the same MCP server that chat apps use.
Claude Code Step 4 link	The link only works for a short time	The link works for about 10 minutes
Claude Code Step 4 mode (agent-facing)	Pairing replaces credentials.json … always import, never generate	From 3.5.1, totalreclaw_pair refuses with already_configured when the file exists; never move/rename/delete it. Older servers replaced it, so still always import with the same phrase if TotalReclaw is already used here.
Leaked phrase (both guides)	Create a fresh account with totalreclaw_pair (mode: "generate").	Treat it as exposed, file a bug, and ask totalreclaw_support for help moving to a new account.
README Quick Start	Claude Desktop / Cursor / Windsurf → npx @totalreclaw/mcp-server setup	Claude Desktop → add npx -y @totalreclaw/mcp-server to the MCP config, restart, ask "Set up TotalReclaw"; Claude Code / Cursor / Windsurf → claude mcp add … or the JSON config, then the same.

The earlier rows of this table (intro, Step 2B/3/5, prerequisites, manual install, Advanced section, multi-device, troubleshooting, MCP notes, mcp/README.md) still apply to the Claude Code guide as reviewed. The Advanced section's text is reused unchanged in the Desktop guide, with "host" changed to Claude Desktop.

Open items (not verified from the repo)

• Claude Desktop UI path "Settings → Developer → Edit Config": taken from Claude Desktop's MCP setup docs as I know them. The repo only has the config file paths (mcp/README.md). Please confirm on a current build.
• Quitting on Windows from the system tray: same caveat.
• Log location (~/Library/Logs/Claude/, %APPDATA%\Claude\logs\) and the nvm / npx PATH advice: common Claude Desktop MCP troubleshooting, not verified here.
• "Always allow" persisting per tool: the parity plan marks this unconfirmed.
• .mcpb desktop extension: the parity plan's target for guide 1 (one-click install, no JSON editing) does not exist in the repo yet, so this guide uses claude_desktop_config.json. When the .mcpb ships, step 1 becomes "double-click the extension".
• Real-user QA on Claude Desktop (macOS) from this guide against the 3.5.1 stable. That is the stable gate (parity plan D10). Not done.

Test plan

• scripts/check-docs.sh: OK (relative links resolve; I also checked the new anchors by hand).
• scripts/check-phrase-safety.sh: 82 artifacts clean.
• Claims checked against code. Credentials are read only at startup (mcp/src/index.ts main()), so a restart is needed after pairing. Relay SESSION_TTL_MS = 10 min. The relay page's success heading is "You're all set". The pair guard and not_configured.reason match fix(mcp): pair never replaces existing credentials; start unconfigured on keychain files #730. The env phrase takes precedence over credentials.json.
• Real-user QA on Claude Desktop (see above).

Follow-ups (not in this PR)

• The default not_configured message and the server instructions (mcp/src/prompts.ts, owned by feat(mcp): fit server instructions in 512 / 2,000 characters #717) still tell users to paste the phrase into the host config.
• README.md's "Then set one env var on your host: export TOTALRECLAW_RECOVERY_PHRASE…" still reads as applying to every client. docs/guides/client-setup-v1.md's MCP section still defaults to the env var.
• Review §4.8: migrate an MCP env-var phrase to a bundle on first run (L3).
• ChatGPT desktop guide (parity plan guide 2), and the .mcpb + Claude skill plugin for guide 1.
• Open PR feat(mcp): MCP 2026-07-28 dual-era stdio support via TypeScript SDK v2 (DEP-15) #700 also edits claude-code-setup.md and mcp/README.md. Expect a small rebase.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Bd3G1BkVMFSXkcdAQ7nFax