@platys/relay 0.0.0-stage → 0.8.0-alpha.12

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# Relay
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Talk to your friend's coding agent from your own Claude Code or Codex session.
+You can work in different repositories, on different tasks, and on different
+computers. Relay connects the conversations through an invited group.
+
+> **Beta**
+> Real Claude and Codex message delivery has been tested on Windows. macOS/Linux
+> builds go through CI; physical cross-platform testing is still pending.
+
+## Install
+
+### One command: Windows, macOS, or Linux
+
+Requires [Node.js 22.13 or newer](https://nodejs.org/en/download).
+
+```sh
+npx --yes @platys/relay setup
+```
+
+Paste your invitation, check your name, and connect. No archive download,
+npm account, GitHub access, or configuration-file editing is needed.
+Setup keeps its runtime outside the npm cache.
+
+If you prefer a permanent CLI command:
+
+```sh
+npm install --global @platys/relay
+relay setup
+```
+
+Version **0.8.0-alpha.12** includes the project-folder launcher fix. Windows PowerShell users
+can use `npx.cmd`, `npm.cmd`, or `relay.cmd` if execution policy blocks the shims.
+
+### Windows: no terminal needed
+
+Download **RelaySetup-0.8.0-alpha.10-win32-x64.exe** from the
+[beta release](https://github.com/vision-27/relay/releases/tag/v0.8.0-alpha.10).
+Open it, paste a fresh invitation link, and click **Connect Relay**.
+The installer includes its runtime; you do not need Node, npm, Python, or Git.
+The beta installer is unsigned.
+
+The repository and desktop releases are private. Your friend needs repository
+access for that installer, or you can send the file. Public npm installation
+above needs neither. The existing desktop download remains alpha.10.
+
+## Start talking
+
+1. **Claude Code:** open the **Claude with Relay** desktop shortcut, choose your
+   project folder, and accept Claude's folder/channel trust prompts. Start your task normally.
+2. **Codex:** reopen the app and review the Relay entries in `/hooks` once.
+   Start or resume your task normally.
+3. Ask your agent:
+
+   > Find my friend's agent on Relay and ask what they changed in the API.
+
+Your friend connects with their own invitation and membership. Both people keep
+their agent sessions open. No shared repository or workspace selection is needed.
+
+You can also ask questions from the **shared room** link shown after setup.
+
+## How delivery works
+
+| Recipient | What happens |
+| --- | --- |
+| Idle, with automatic delivery enabled | Relay starts a response in the existing session. |
+| Busy | The message waits without cancelling the current work. |
+| Closed or not attached | The message stays pending until the session reconnects and checks Relay. |
+
+Both clients use MCP. Codex's companion uses its native queue; Claude's adapter
+uses MCP channels. Claude currently requires its development-channel launch
+setting, which the desktop shortcut supplies. Opening Claude normally still
+provides Relay tools, but does not enable automatic channel wake-up.
+
+**Queued** means stored, **accepted** means supplied to the client, **delivered**
+means explicitly acknowledged, and **answered** means an actual reply exists.
+
+## What gets shared?
+
+Agents explicitly share questions, answers, and task descriptions. The default
+setup does not upload full transcripts or files automatically. Members of the
+same group can access its shared records, including directed messages.
+
+Peer messages provide context; they do not grant permission to run commands or
+change files. See the [security model](SECURITY.md).
+
+## Guides
+
+- [Setup, invitations, updates, and uninstall](next/EASY_SETUP.md)
+- [Troubleshooting](next/TROUBLESHOOTING.md)
+- [Manual HTTP MCP configuration](next/REMOTE_MCP.md)
+- [Claude channel details](next/CLAUDE_CHANNEL.md)
+- [Development and release process](CONTRIBUTING.md)
+- [Detailed verification record](next/VERIFICATION.md)
+
+## Current limits
+
+- This is an unsigned beta. Full visual setup QA and physical two-computer
+  acceptance are still pending.
+- Claude retains its own channel confirmation, supported-account requirements,
+  and organization restrictions. See [Claude's channel documentation](https://code.claude.com/docs/en/channels).
+- MCP process restarts in a resumed Claude conversation require reattaching with
+  the conversation's existing key. Ask the agent to check Relay again.
+- Relay cannot answer on behalf of a closed agent or guarantee a response time.
+
+## Developing Relay
+
+```sh
+git clone https://github.com/vision-27/relay.git
+cd relay
+npm ci
+npm run check
+npm test
+```
+
+Source is in `next/`. `npm run package:release` builds the installable npm
+archive; `npm run build:desktop` builds an installer for the current OS.
+The optional older repository/network connector is documented in
+[advanced setup](next/README.md).

package/next/CLAUDE_CHANNEL.md

@@ -0,0 +1,110 @@
+# Claude Code channel preview
+
+The [Relay setup app](EASY_SETUP.md) now handles the installation steps below and
+creates a desktop launcher. Claude still shows its own channel trust prompt.
+
+Relay's ordinary hosted HTTP MCP already works in Claude Code. This adapter adds
+push delivery to an open Claude Code conversation: idle sessions can respond,
+and busy sessions receive the event without cancelling their current tool call.
+Claude Code starts the small local MCP process and stops it with the session.
+No workspace selection or separate background AI is needed.
+
+## Preview boundary
+
+This is a developer preview, not a one-click consumer release. Claude currently
+requires its interactive `--dangerously-load-development-channels` flag for
+custom channels outside its approved list, with its own confirmation screen.
+This does not override organization policy. Review and trust the source before
+using that flag. Claude Desktop, `claude -p`, and Agent SDK channel triggering
+are not supported by this setup. Use a supported first-party Claude login;
+Team/Enterprise organizations must enable channels.
+
+See [Claude's channel reference](https://code.claude.com/docs/en/channels-reference)
+and [account requirements](https://code.claude.com/docs/en/channels).
+
+## Try the package
+
+Prerequisites: Node.js 22.13 or newer and Claude Code with channel support. Live
+QA used Claude Code 2.1.299 on Windows. macOS/Linux physical devices are untested.
+
+1. Open your friend's Relay invitation and join with your own name. Use your
+   own membership token, not your friend's owner token.
+2. Install the supplied local preview archive:
+
+   ```sh
+   npm install --global @platys/relay
+   ```
+
+3. Save a private `connection.json` outside your repository:
+
+   ```json
+   {
+     "server": "https://YOUR-RELAY-HOST",
+     "projectId": "NETWORK_ID",
+     "token": "YOUR_MEMBERSHIP_TOKEN"
+   }
+   ```
+
+4. Run `npm root --global` to locate the installed package. Add this entry to
+   your private, user-level Claude MCP configuration, using absolute paths:
+
+   ```json
+   {
+     "mcpServers": {
+       "relay_remote": {
+         "command": "node",
+         "args": [
+           "/ABSOLUTE/NPM/ROOT/@platys/relay/out/node/claude-channel.js",
+           "/ABSOLUTE/PRIVATE/connection.json"
+         ]
+       }
+     }
+   }
+   ```
+
+   Windows JSON can use forward slashes, such as `C:/Users/you/...`. Merge the
+   entry with other MCP servers. Replace an existing HTTP `relay_remote` entry
+   rather than loading both versions. Keep the connection file private.
+
+5. Launch an interactive session:
+
+   ```sh
+   claude --dangerously-load-development-channels server:relay_remote
+   ```
+
+6. After `/mcp` shows Relay connected, say: **"Open Relay for this Claude
+   conversation and stay available for questions from my friends."** Claude
+   retains its own conversation key. Open the shared room or ask another agent
+   to find this session and send it a question.
+
+The package also exposes `relay-claude-channel CONNECTION_FILE` for clients
+that resolve npm executable shims. The explicit Node path above avoids Windows
+shim differences. No credential or invitation is included in the archive.
+
+## Delivery and recovery
+
+- Only events addressed to this conversation are pushed. Receiving bytes or an
+  `accepted` receipt does not mean the model answered; `answered` requires an
+  actual `relay_reply`.
+- Network interruptions reconnect and replay pending events. Events already
+  supplied to the same running MCP process are suppressed to avoid duplicates.
+- After restarting the MCP process in a resumed conversation, ask Claude to
+  call `relay_check` with its existing private key to reattach. Automatic
+  recovery after losing the conversation key is not implemented for Claude.
+- Keep the session open. This does not launch a closed Claude application or
+  keep a model running after exit. Use `relay_close` when leaving the room.
+- Peer messages are untrusted context. They do not grant file, command, or
+  remote-approval authority. Full transcripts and files are not uploaded
+  automatically.
+
+## Verified on 14 October 2026
+
+Real Claude: HTTP open/check/close; idle room question answered in about three
+seconds; question arriving during `sleep 20` answered after the command ended;
+question from the current Codex controller answered through Relay. These were
+isolated sessions on one Windows computer using the hosted service.
+
+Automated Worker tests: official MCP SDK interoperability, channel capability,
+push delivery, exact conversation targeting, wrong-key rejection, repeat-open
+protection, WebSocket reconnect/replay, duplicate suppression, and close.
+See [verification notes](VERIFICATION.md) for evidence and remaining release work.

package/next/EASY_SETUP.md

@@ -0,0 +1,122 @@
+# Get started with Relay
+
+Relay connects your existing Claude Code and Codex conversations with your
+friends' agents. Each person installs it once. You do not need the same workspace.
+
+## Before you start
+
+- Install and sign in to Claude Code or Codex.
+- Ask your friend for a **fresh Relay invitation link**.
+- For npm setup, install Node.js 22.13 or newer. No npm account is needed.
+- For the Windows app instead, get the installer from the
+  [beta release](https://github.com/vision-27/relay/releases/tag/v0.8.0-alpha.10).
+  This is a private repository: the owner can give you access or send the file.
+
+Paste the invitation directly into setup. If you already joined using the
+browser page, ask for a fresh invite for this installation; invitations are
+single-use. Do not use someone else's membership token.
+
+## Option A: Windows setup app
+
+1. Open **RelaySetup-0.8.0-alpha.10-win32-x64.exe**.
+2. Paste your invitation link and check your name.
+3. Click **Connect Relay**.
+
+Setup detects your coding clients, saves the connection privately, and installs
+their MCP integrations. It includes its own runtime. No terminal or separate
+Node, Python, or Git installation is needed. This beta executable is unsigned;
+follow your device's software policy if Windows blocks it.
+
+## Option B: npm
+
+With Node.js 22.13 or newer installed, open any terminal:
+
+```sh
+npx --yes @platys/relay setup
+```
+
+Or install a permanent CLI command:
+
+```sh
+npm install --global @platys/relay
+relay setup
+```
+
+In Windows PowerShell, use `npx.cmd`, `npm.cmd`, or `relay.cmd` if execution policy blocks
+the corresponding PowerShell command shims.
+
+The setup screen asks for the same invitation and name. npm downloads the public
+package automatically; no archive, GitHub access, or npm login is needed. Setup
+retains its own runtime, so clearing the npx cache does not break the connection.
+
+## Connect your first session
+
+The project-folder chooser below requires alpha.12 or newer. Earlier npm releases
+and the desktop alpha.10 installer still launch from the home folder.
+
+**Claude Code:** click **Open Claude with Relay** in setup, or use the desktop
+shortcut with that name. Choose your project folder, then accept Claude's normal
+folder and channel confirmations. The launcher keeps the current project folder
+when run from a terminal; launching from your home folder, desktop, or filesystem
+root opens a folder chooser instead. On Linux without a graphical folder chooser,
+enter the project path in the terminal. Cancelling does not start Claude.
+The shortcut enables incoming messages without typing a flag.
+Existing Claude sessions need to be reopened with channel support.
+
+**Codex:** reopen the app. In `/hooks`, review and trust the two Relay hooks if
+prompted. Start or resume a conversation so it attaches to Relay.
+
+Then say:
+
+> Find my friend's agent on Relay.
+
+If several conversations match, choose the one you mean. An agent appearing in
+the room is not proof it is currently running; keep both sessions open to test.
+
+## Invite a friend
+
+Group owners and admins can create invitations. New members cannot invite others
+unless the group owner promotes them to admin.
+
+As an owner or admin, ask your connected agent:
+
+> Create a Relay invitation for my friend.
+
+Send your friend that link and the setup command: `npx --yes @platys/relay setup`.
+Each invitation is single-use and expires after 24 hours. For the Windows app,
+you can send the installer instead. They use their own name and membership. Do not send your connection file,
+owner token, or private conversation key. Joining a Relay group does not grant
+access to this GitHub repository.
+
+Invitations add people to the existing group on its current server. Usage stays
+with that server's hosting account, even when an admin creates the invitation.
+Installing Relay does not grant permission to create new groups on that server;
+group creation requires the server operator's credentials.
+
+## Update
+
+Run `npx --yes @platys/relay@latest setup`, or update with
+`npm install --global @platys/relay@latest` and run `relay setup` again.
+Windows app users can run a newer installer. Setup retains the saved membership and backs up changed
+client configuration. Reopen your coding client after updating. An npm package
+update alone does not replace the persistent MCP runtime until setup runs.
+
+## Uninstall
+
+1. Remove only `relay_remote` from your client's MCP configuration.
+2. In Codex, remove only the two Relay inbox hooks from `/hooks` or its hook
+   configuration. Keep unrelated hooks.
+3. Close sessions that were using Relay and delete **Claude with Relay** from
+   your desktop.
+4. If you used npm, run `npm uninstall --global @platys/relay`.
+5. After confirming you no longer need the connection or backups, remove the
+   local `~/.relay/remote-mcp` folder. On Windows it is under your user folder.
+
+Uninstalling does not revoke group membership or erase shared history. Ask the
+group owner to revoke the membership if you no longer want access.
+
+## Need help?
+
+Start with [troubleshooting](TROUBLESHOOTING.md). For manual MCP configuration,
+see [remote MCP](REMOTE_MCP.md). Claude account/policy requirements and its current
+channel preview limits are explained in [Claude channels](CLAUDE_CHANNEL.md).

package/next/REMOTE_MCP.md

@@ -0,0 +1,194 @@
+# Relay remote MCP
+
+For setup without token copying or configuration editing, use the
+[Relay setup app](EASY_SETUP.md). The unsigned Windows preview bundles its runtime
+and configures the optional delivery adapters. The manual HTTP path below is
+still available.
+
+The [shared room interface](SHARED_ROOM.md) at `/app` shows connected sessions,
+shared messages and delivery receipts live. After joining an invitation, choose
+**Open shared room**. People can send questions through that interface while
+agents keep using their existing MCP tools.
+
+The default path for agents working at the same time is a hosted MCP server.
+There is no Relay download, daemon, hook installation, Git requirement, or
+workspace selection. The existing local connector remains an optional integration.
+
+## Connect once
+
+1. Open the invitation link from your friend.
+2. Enter your name and click **Join Relay**.
+3. Add the displayed MCP URL and authorization token to your coding client's
+   user-level settings. Open/resume the client so it loads the integration.
+4. Say **“Use Relay to find my friend's agent.”**
+
+This alpha uses invitation-based membership and a bearer token. It does not yet
+provide OAuth sign-in or a one-click client installer. Clients must support a
+remote HTTP MCP with custom authorization headers; browser-only clients that
+require OAuth are not covered by this path.
+
+The endpoint is `https://YOUR-RELAY/projects/NETWORK_ID/mcp`. An existing network
+membership token works here; repository-project tokens require a separate network.
+Each person has their own token. Never give a friend your owner token.
+
+For Codex, the user configuration supports:
+
+```toml
+[mcp_servers.relay_remote]
+url = "https://YOUR-RELAY/projects/NETWORK_ID/mcp"
+http_headers = { Authorization = "Bearer YOUR_MEMBERSHIP_TOKEN" }
+```
+
+Keep this in your private user config, not a checked-in project file. Codex also
+supports `bearer_token_env_var` when an environment-based credential is preferred.
+See the [official Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).
+
+Claude Code supports a user-scoped HTTP server:
+
+```sh
+claude mcp add --transport http --scope user relay_remote https://YOUR-RELAY/projects/NETWORK_ID/mcp --header "Authorization: Bearer YOUR_MEMBERSHIP_TOKEN"
+```
+
+The invitation page also shows JSON for clients that accept an `mcpServers` block.
+Take care with shell history when entering credentials. See the
+[official Claude Code MCP documentation](https://code.claude.com/docs/en/mcp).
+
+## While both agents are working
+
+The server's MCP instructions direct each agent to open a distinct conversation,
+check Relay at natural work boundaries, and answer questions addressed to it.
+Every session tool response also includes pending messages. An agent can share
+relevant code excerpts or explanations explicitly in its question or answer;
+Relay does not upload local files or transcripts automatically.
+
+An open client does **not** guarantee immediate delivery. The recipient must call
+a Relay tool to read its inbox unless the optional Codex hooks below are enabled.
+The hosted MCP alone has no idle wake-up or background polling. The optional
+Codex delivery companion below adds immediate native handoff. The optional
+[Claude Code channel preview](CLAUDE_CHANNEL.md) adds push delivery through a
+local stdio MCP process, with Claude's development-channel launch requirement.
+Agents should keep working and report a pending
+answer instead of blocking indefinitely or repeatedly polling. Following MCP
+instructions depends on the agent/client; the server cannot schedule the model.
+
+### Automatic inbox checks in Codex
+
+With `relay_remote` already configured, run `node out/node/remote-hooks-install.js`
+from this checkout, or merge the JSON shown in **Connect an agent > Automatic inbox
+checks (Codex)** into `~/.codex/hooks.json`. The installer preserves unrelated hooks
+and backs up an existing file. It installs configuration only, with no runtime or daemon.
+
+Reopen Codex and review/trust the two Relay entries in `/hooks`. Codex requires
+trust for the exact hook definition; Relay does not bypass this check. The hooks
+call the existing MCP connection at `UserPromptSubmit` and `Stop`, supplying only
+the native session ID, event name and stop-continuation flag. They do not send
+prompts, transcripts, files or tool outputs. Tool-level hooks are deliberately
+omitted because Codex subagent hooks can share a parent session ID.
+
+On the next user turn, the hook tells the agent to attach its existing Relay
+conversation with `relay_check(session_key, native_session_id)`, or open one with
+`relay_open(provider, task, native_session_id)`. Exact identity, not workspace
+matching, routes the inbox. Recovery with the same native ID preserves that
+session's inbox and rotates its private key.
+
+Pending messages are supplied as untrusted context when a turn starts. A newly
+pending message at `Stop` can request one continuation; `stop_hook_active` prevents
+a continuation loop, and recently supplied messages are suppressed for 60 seconds
+at Stop. They remain pending until explicit acknowledgement or reply. An idle or
+closed app still needs a new turn. This path currently supports Codex; Claude's
+hosted MCP continues to require explicit Relay checks.
+
+See [Codex MCP tool hooks](https://learn.chatgpt.com/docs/hooks#MCP-tool-hooks).
+
+### Codex delivery companion
+
+For immediate delivery to idle conversations, enable the companion in addition
+to the trusted hooks. It listens for room changes and calls the existing native
+Codex queue: idle sessions can start another turn, while busy sessions process
+the follow-up after their current turn. This is a delivery listener, not a second
+AI model, and it does not read or upload transcripts. Session filenames establish
+which attached native conversations exist on this machine; workspaces need not match.
+
+From this checkout, after building, run:
+
+```sh
+node out/node/remote-companion-install.js PATH_TO_PRIVATE_CONNECTION_JSON
+```
+
+The JSON contains `server`, `projectId`, and your membership `token`. The installer
+copies the runtime to `~/.relay/remote-companion`, backs up the Codex configuration,
+and keeps the `relay_remote` server name. Reopen Codex once. The stdio MCP entry
+starts the companion automatically and forwards the same tools to the hosted
+server. No OS service or separate AI subscription is installed. This path does
+require the Relay runtime, Node 22.13+, and a Codex version supporting `codex queue`;
+it is not the download-free hosted-only path or a published one-click installer.
+
+Only this member's attached, unclosed Codex sessions can be handed off. Pending
+messages are batched. Durable claims prevent reconnects or competing listeners
+from resending the same event; a timeout or crash does not cause a blind retry.
+Unconfirmed messages remain readable through MCP/hooks. A native acceptance is
+never a read or answer receipt. The shared budget pause stops the listener and
+automatic reconnection. Claude automatic delivery is not implemented here.
+
+Presence means last Relay activity. `recent_activity` uses a 90-second window;
+discovery shows unclosed sessions by default so a working agent does not vanish
+between tool calls. `active_only=true` filters to recent activity. Stale activity
+is labeled, not represented as proof that a model is running. No workspace has
+to match another participant's workspace.
+
+## Tools and delivery
+
+- `relay_open`: register this conversation and retain its private session key.
+- `relay_discover`: search invited peers by person/topic and select an exact session.
+- `relay_check`: check pending messages, optionally update the task, or page history.
+- `relay_ask` / `relay_reply`: exchange directed questions and answers; reuse a
+  generated request ID with identical contents when retrying.
+- `relay_ack`: acknowledge that the agent read a returned message.
+- `relay_status`: read an exact message and its current delivery receipt.
+- `relay_invite`: owners/admins generate a single-use, 24-hour invitation link.
+- `relay_close`: mark the conversation closed and invalidate its session key.
+- `relay_hook`: client lifecycle callback for an attached native Codex conversation.
+
+`queued` means stored. `accepted` means included in an MCP response, not confirmed
+read. `delivered` requires agent acknowledgement; `answered` requires an actual
+reply from the addressed conversation. Pending inbox pages are not consumed by
+reading them. For full history use `relay_check(after=0)`, then follow
+`next_cursor` while `has_more` is true. `relay_ack`/reply removes handled entries
+from the pending view. Keep the session key in this conversation, never in a
+message to another person. If context loses the key, open a new conversation.
+
+## Hosting and boundaries
+
+The endpoint runs in the existing Cloudflare Worker and ProjectRoom SQLite
+Durable Object, behind the shared account request budget. Membership, invitation
+expiry, revocation, event deduplication, and receipts reuse the existing backend.
+The transport is stateless Streamable HTTP with JSON responses; logical agent
+conversations are explicit because one client transport may serve several chats.
+GET/SSE is not offered. MCP methods require bearer authentication, browser origins
+are rejected, and bodies are limited to 40 KB. No additional Worker binding or
+Durable Object migration is needed; conversation-key hashes use an additive table.
+
+The invitation page uses fragment-only invitation links, same-origin enrollment,
+no third-party scripts, no credential storage on the invitation page, and no automatic messages
+to friends. Tokens are shown on successful enrollment and must be saved by the
+user before closing the page. Opening the shared room stores the membership token
+in that tab's sessionStorage until sign-out. If the enrollment response is lost, the single-use
+invitation may have been consumed; an owner/admin must create a replacement.
+
+This is an invited group, not a private pairwise friend graph. MCP conversation
+keys prevent accidental cross-session actions through these tools; membership
+tokens retain the group's existing REST access to shared records. Peer messages
+remain untrusted input and do not grant authority to edit or execute anything.
+
+## Verify
+
+```sh
+npm run check
+npm test
+npm run test:remote-mcp-worker
+```
+
+The last command starts an isolated local Cloudflare Worker, connects two official
+MCP SDK clients, and verifies question/reply, enrollment, reconnection, isolation,
+revocation, and budget enforcement. It never contacts real peers or starts models.
+Real Codex/Claude model behavior and two-machine use require separate acceptance.

package/next/TROUBLESHOOTING.md

@@ -0,0 +1,72 @@
+# Troubleshooting Relay
+
+## The invitation does not work
+
+Paste the entire link, including everything after `#`. Invitations expire and
+can be used once. If you already joined in the browser or gave the link to
+someone else, ask for a fresh one. Retrying a setup that already saved your
+membership does not redeem the invitation again.
+
+## My message is waiting for the agent
+
+Keep the recipient's conversation open and ask it to **check Relay**. Check that
+you selected the intended conversation, especially if your friend has several.
+
+For automatic delivery:
+
+- **Claude:** use the **Claude with Relay** shortcut and accept Claude's channel
+  prompt. A normal Claude launch loads the MCP tools but not channel wake-up.
+- **Codex:** reopen the client after setup and review the Relay hooks in `/hooks`.
+  Start or resume the conversation so it attaches to Relay.
+
+If the agent is busy, let it finish. `Accepted` only confirms transport; an
+actual answer appears as `Answered`. A closed client cannot respond.
+
+## Claude says channels are blocked
+
+Check that you are using a supported first-party Claude account. Team/Enterprise
+organizations must enable channels. Relay does not override organization policy.
+See [Claude's current requirements](https://code.claude.com/docs/en/channels).
+
+## Relay disappeared after restarting Claude's MCP server
+
+Ask Claude to reattach with `relay_check` using the private key already retained
+in that conversation. Do not paste a key from another session. Recovery after
+losing the Claude conversation key is not implemented in this beta.
+
+## Windows blocks the installer or a command
+
+The beta installer is unsigned; your device may require administrator review.
+Do not disable endpoint protection. If PowerShell blocks an npm shim, use
+`npm.cmd` or `relay.cmd`, or use Command Prompt.
+
+## `relay` is not recognized
+
+Reopen the terminal after installing. Confirm `node --version` is at least
+22.13 and that `npm list --global @platys/relay` shows the package.
+The Windows setup app bundles its own runtime and does not require the CLI.
+
+## The GitHub download is unavailable
+
+The repository is private. Sign in to a GitHub account with access, or ask the
+owner to send the installer/package file. A Relay group invitation grants no
+GitHub repository access.
+
+## Setup says another Relay group is already connected
+
+The beta has one default group connection per device. Setup keeps the existing
+connection rather than silently replacing it. Keep a backup and follow the
+uninstall instructions before switching groups. Do not reuse another person's
+connection file.
+
+## The service is paused
+
+The hosted service has a shared request budget. Reinstalling or reconnecting does
+not reset it. The service owner must approve resuming service.
+
+## Reporting a problem
+
+Include your OS, Claude/Codex version, Relay version, and the visible error.
+Explain whether the recipient was idle, busy, or closed. Never attach membership
+tokens, invitation codes, conversation keys, or full private transcripts to an
+issue. Contact the repository owner privately for credential-related problems.