handoff-relay 0.1.0

package/docs/advanced-manual-setup.md

@@ -0,0 +1,196 @@
+# Advanced Manual Setup
+
+Use this path for automation, remote/self-hosted coordination servers, CI smoke tests, or explicit-auth MCP compatibility. Most users should start with:
+
+```bash
+npx -y handoff-relay start --lan
+npx -y handoff-relay invite alice
+npx -y handoff-relay join http://<host>:3737/invite/<invite-token>
+```
+
+Plain `start` is still useful for local demos and CI smoke tests, but its loopback invite links are not the normal teammate handoff path.
+
+The commands below intentionally expose low-level details: DB paths, server URLs, workspace IDs, member tokens, and approval secrets.
+They document the strict approval-token flow. For profile-backed MCP sessions that treat explicit agent-chat instruction as approval, use `server mcp --profile default --agent-approvals` instead of explicit-auth mode.
+
+## Start A Coordination Server
+
+```bash
+npx -y handoff-relay server start \
+  --db /srv/handoff/relay.db \
+  --host 10.0.0.10 \
+  --port 3737
+```
+
+For local-only testing:
+
+```bash
+npx -y handoff-relay server start \
+  --db .relay/team.db \
+  --host 127.0.0.1 \
+  --port 3737
+```
+
+## Create A Workspace
+
+```bash
+npx -y handoff-relay workspace create \
+  --server-url http://10.0.0.10:3737 \
+  --name "Relay Demo" \
+  --handle sam \
+  --display-name "Sam" \
+  --json
+```
+
+Save the returned:
+
+- `workspace.id`
+- `admin.token`
+- `admin.approval_secret`
+
+Member tokens authenticate API/MCP calls. Approval secrets stay outside MCP and are used only by the local approval-token command.
+
+## Invite And Accept A Member
+
+```bash
+npx -y handoff-relay member invite \
+  --server-url http://10.0.0.10:3737 \
+  --token <sam-token> \
+  --workspace <workspace-id> \
+  --handle alice \
+  --json
+
+npx -y handoff-relay member accept \
+  --server-url http://10.0.0.10:3737 \
+  --invite <invite-token> \
+  --display-name "Alice" \
+  --json
+```
+
+## Explicit-Auth MCP Mode
+
+Profile-backed MCP is the normal mode:
+
+```bash
+npx -y handoff-relay server mcp --profile default
+```
+
+Explicit-auth compatibility mode keeps the older schemas that include `authToken` and `workspaceId`:
+
+```bash
+npx -y handoff-relay server mcp \
+  --server-url http://10.0.0.10:3737 \
+  --explicit-auth
+```
+
+Use explicit-auth mode only when a script or test harness intentionally supplies auth fields. Do not put approval secrets in MCP config.
+
+## Draft, Approve, And Send
+
+```bash
+npx -y handoff-relay share-with @alice \
+  --server-url http://10.0.0.10:3737 \
+  --token <sam-token> \
+  --workspace <workspace-id> \
+  --title "Auth refresh handoff" \
+  --summary "The retry path still returns 401 after refresh-token rotation." \
+  --finding "The retry path appears to skip persistence before the second request." \
+  --source-client codex \
+  --evidence-json '[{"kind":"test_failure","label":"test output","source":"pnpm test auth-refresh","excerpt":"expected 200 received 401"}]' \
+  --files src/auth/refresh.ts,refreshSession \
+  --tests "pnpm test auth-refresh" \
+  --tried "Checked token expiry math,Re-ran the refresh integration test" \
+  --hypothesis "Refresh persistence ordering issue." \
+  --json
+
+npx -y handoff-relay approval-token <handoff-packet-id> \
+  --server-url http://10.0.0.10:3737 \
+  --token <sam-token> \
+  --approval-secret <sam-approval-secret> \
+  --action send \
+  --json
+
+npx -y handoff-relay approve <handoff-packet-id> \
+  --server-url http://10.0.0.10:3737 \
+  --token <sam-token> \
+  --approval-token <send-approval-token> \
+  --json
+```
+
+## Review And Hydrate
+
+```bash
+npx -y handoff-relay inbox \
+  --server-url http://10.0.0.10:3737 \
+  --token <alice-token> \
+  --workspace <workspace-id> \
+  --json
+
+npx -y handoff-relay view <handoff-packet-id> \
+  --server-url http://10.0.0.10:3737 \
+  --token <alice-token> \
+  --json
+
+npx -y handoff-relay accept <handoff-packet-id> \
+  --server-url http://10.0.0.10:3737 \
+  --token <alice-token> \
+  --json
+
+npx -y handoff-relay approval-token <handoff-packet-id> \
+  --server-url http://10.0.0.10:3737 \
+  --token <alice-token> \
+  --approval-secret <alice-approval-secret> \
+  --action hydrate \
+  --json
+
+npx -y handoff-relay hydrate <handoff-packet-id> \
+  --server-url http://10.0.0.10:3737 \
+  --token <alice-token> \
+  --client claude-code \
+  --approval-token <hydrate-approval-token>
+```
+
+## Reply
+
+```bash
+npx -y handoff-relay reply <ask-packet-id> "Persist the rotated refresh token before retrying." \
+  --server-url http://10.0.0.10:3737 \
+  --token <alice-token> \
+  --summary "Likely refresh persistence ordering issue." \
+  --source-client claude-code \
+  --json
+
+npx -y handoff-relay approval-token <reply-packet-id> \
+  --server-url http://10.0.0.10:3737 \
+  --token <alice-token> \
+  --approval-secret <alice-approval-secret> \
+  --action reply \
+  --json
+
+npx -y handoff-relay approve <reply-packet-id> \
+  --server-url http://10.0.0.10:3737 \
+  --token <alice-token> \
+  --approval-token <reply-approval-token> \
+  --json
+```
+
+## Watch
+
+```bash
+npx -y handoff-relay watch \
+  --server-url http://10.0.0.10:3737 \
+  --token <member-token> \
+  --workspace <workspace-id>
+
+npx -y handoff-relay watch \
+  --server-url http://10.0.0.10:3737 \
+  --token <member-token> \
+  --workspace <workspace-id> \
+  --desktop-notifications
+
+npx -y handoff-relay watch \
+  --server-url http://10.0.0.10:3737 \
+  --token <member-token> \
+  --workspace <workspace-id> \
+  --webhook-url https://hooks.example.test/relay
+```

package/docs/claude-code-setup.md

@@ -0,0 +1,143 @@
+# Claude Code Setup
+
+Handoff runs as a local stdio MCP server near each user's Claude Code session. The shared workspace lives on the host machine or server; every teammate joins it into their own local profile.
+
+## Team Setup
+
+On Sam's machine, host a LAN-reachable workspace:
+
+```bash
+npx -y handoff-relay start --lan
+npx -y handoff-relay invite alice
+npx -y handoff-relay doctor
+```
+
+On Alice's machine, run the invite command Sam sends her:
+
+```bash
+npx -y handoff-relay join http://<sam-lan-ip>:3737/invite/<invite-token>
+npx -y handoff-relay doctor
+```
+
+Alice does not run `start` for Sam's workspace. `join` accepts the invite, stores Alice's local profile and credentials, and prints the profile-backed MCP command for her Claude Code config.
+
+If Alice is not on the same network, host Handoff behind a reachable URL and use `start --public-url <url>` or the dedicated server path in [Local self-hosting](local-self-hosting.md).
+
+Handoff cannot safely edit every Claude Code config shape automatically, so setup prints the profile-backed command and the `claude mcp add-json` command below. `doctor` reports `WARN` until a supported MCP config contains that profile-backed command.
+
+For same-machine demos or CI smoke tests, plain `start` remains available, but its invite links are loopback-only.
+
+## Add Handoff To Claude Code
+
+Claude Code can add MCP servers with `claude mcp add-json`, and it can load MCP config JSON with `--mcp-config`.
+
+Add with the CLI:
+
+```bash
+claude mcp add-json handoff \
+  '{"type":"stdio","command":"npx","args":["-y","handoff-relay","server","mcp","--profile","default"]}'
+```
+
+Or create `handoff.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "handoff": {
+      "command": "npx",
+      "args": ["-y", "handoff-relay", "server", "mcp", "--profile", "default"]
+    }
+  }
+}
+```
+
+Start Claude Code with that config:
+
+```bash
+claude --mcp-config ./handoff.mcp.json
+```
+
+Inside Claude Code, use `/mcp` to inspect server status.
+
+## Invocation Pattern
+
+Ask Claude to create a handoff packet, then review the returned draft before approving:
+
+```text
+Use Handoff to create a Relay Packet for @alice from this session.
+Include files touched, commands run, known failures, current hypothesis, evidence excerpts, and suggested next steps.
+Draft only. Show me the packet summary, claims, evidence, expiry, and redaction report before sending.
+```
+
+In strict mode, before Claude calls `relay_approve`, generate a human approval token in a terminal:
+
+```bash
+npx -y handoff-relay approval-token <packet-id> --action send
+```
+
+Recipient side:
+
+```text
+Check my Handoff inbox. Show me the Relay Packet before hydration.
+If I approve, hydrate it into this Claude Code session.
+```
+
+Hydration also needs a human approval token:
+
+```bash
+npx -y handoff-relay approval-token <packet-id> --action hydrate
+```
+
+Approval-token minting is deliberately outside MCP so Claude cannot draft and approve a packet with only a member token. Keep approval secrets out of MCP config.
+
+For a smoother local workflow, profile-backed MCP can opt into agent-confirmed approvals:
+
+```bash
+npx -y handoff-relay server mcp --profile default --agent-approvals
+```
+
+With that flag, Claude may call `relay_approve` or `relay_hydrate` without a pasted token after it shows you the packet and you explicitly tell it to send or hydrate. The MCP process requests the short-lived approval token through the configured Handoff backend; remote profiles send the approval secret to that server API. Approval secrets still stay out of Claude config and tool schemas.
+
+## Remote Or Self-Hosted
+
+Profile mode is still preferred after `join` because the profile stores the server URL and credentials locally.
+
+Explicit-auth compatibility mode remains available for automation:
+
+```json
+{
+  "mcpServers": {
+    "handoff": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "handoff-relay",
+        "server",
+        "mcp",
+        "--server-url",
+        "http://10.0.0.10:3737",
+        "--explicit-auth"
+      ]
+    }
+  }
+}
+```
+
+## From A Local Checkout
+
+```bash
+pnpm install
+pnpm build
+```
+
+```json
+{
+  "mcpServers": {
+    "handoff": {
+      "command": "node",
+      "args": ["/absolute/path/to/handoff/dist/cli.js", "server", "mcp", "--profile", "default"],
+      "cwd": "/absolute/path/to/handoff"
+    }
+  }
+}
+```

package/docs/codex-setup.md

@@ -0,0 +1,135 @@
+# Codex Setup
+
+Handoff runs as a local stdio MCP server beside each user's Codex session. The shared workspace lives on the host machine or server; every teammate joins it into their own local profile.
+
+## Team Setup
+
+On Sam's machine, host a LAN-reachable workspace and install the Codex MCP entry:
+
+```bash
+npx -y handoff-relay start --lan --install-mcp codex
+npx -y handoff-relay invite alice
+npx -y handoff-relay doctor
+```
+
+On Alice's machine, run the invite command Sam sends her:
+
+```bash
+npx -y handoff-relay join http://<sam-lan-ip>:3737/invite/<invite-token> --install-mcp codex
+npx -y handoff-relay doctor
+```
+
+Alice does not run `start` for Sam's workspace. `join` accepts the invite, stores Alice's local profile and credentials, and wires Codex when `--install-mcp codex` is present.
+
+If Alice is not on the same network, host Handoff behind a reachable URL and use `start --public-url <url>` or the dedicated server path in [Local self-hosting](local-self-hosting.md).
+
+## Local Demo Setup
+
+For a same-machine demo or CI smoke test, use loopback-only setup:
+
+```bash
+npx -y handoff-relay start --install-mcp codex
+npx -y handoff-relay invite alice
+```
+
+## Add Handoff To Codex
+
+Codex stores MCP configuration in `~/.codex/config.toml` by default, and trusted projects can use `.codex/config.toml`. The CLI and IDE extension share this config.
+
+If you did not use `--install-mcp codex`, add this TOML:
+
+```toml
+[mcp_servers.handoff]
+command = "npx"
+args = ["-y", "handoff-relay", "server", "mcp", "--profile", "default"]
+startup_timeout_sec = 10
+tool_timeout_sec = 60
+enabled = true
+```
+
+In Codex, use `/mcp` to inspect active MCP servers.
+
+`npx -y handoff-relay doctor` reports `WARN` when no supported MCP client config contains the profile-backed Handoff command. That warning means Handoff setup exists, but Codex has not been wired to use it yet.
+
+## Invocation Pattern
+
+```text
+Use Handoff to package the current investigation context for @alice.
+Include files touched, commands run, known failures, current hypothesis, evidence excerpts, and suggested next steps.
+Show me the Relay Packet and redaction report before sending.
+```
+
+Recipient flow:
+
+```text
+Use Handoff to check my inbox. Show me any Relay Packet before hydration.
+Wait for my approval before calling relay_hydrate.
+```
+
+Strict approval tokens are generated outside MCP:
+
+```bash
+npx -y handoff-relay approval-token <packet-id> --action send
+npx -y handoff-relay approval-token <packet-id> --action hydrate
+```
+
+The command uses your active Handoff profile and asks for a local confirmation phrase. Do not put approval secrets in Codex config.
+
+For a smoother local workflow, profile-backed MCP can opt into agent-confirmed approvals:
+
+```toml
+[mcp_servers.handoff]
+command = "npx"
+args = ["-y", "handoff-relay", "server", "mcp", "--profile", "default", "--agent-approvals"]
+startup_timeout_sec = 10
+tool_timeout_sec = 60
+enabled = true
+```
+
+With that flag, Codex may call `relay_approve` or `relay_hydrate` without a pasted token after it shows you the packet and you explicitly tell it to send or hydrate. The MCP process requests the short-lived approval token through the configured Handoff backend; remote profiles send the approval secret to that server API. Approval secrets still stay out of Codex config and tool schemas.
+
+## Remote Or Self-Hosted
+
+For normal local/LAN use, keep the profile-backed command. For automation against a self-hosted server, explicit-auth compatibility mode remains available:
+
+```toml
+[mcp_servers.handoff]
+command = "npx"
+args = [
+  "-y",
+  "handoff-relay",
+  "server",
+  "mcp",
+  "--server-url",
+  "http://10.0.0.10:3737",
+  "--explicit-auth"
+]
+startup_timeout_sec = 10
+tool_timeout_sec = 60
+enabled = true
+```
+
+In explicit-auth mode, MCP tool schemas include `authToken` and `workspaceId`. Prefer profile mode for day-to-day agent use.
+
+## From A Local Checkout
+
+```bash
+pnpm install
+pnpm build
+```
+
+```toml
+[mcp_servers.handoff]
+command = "node"
+args = [
+  "/absolute/path/to/handoff/dist/cli.js",
+  "server",
+  "mcp",
+  "--profile",
+  "default"
+]
+cwd = "/absolute/path/to/handoff"
+startup_timeout_sec = 10
+tool_timeout_sec = 60
+enabled = true
+```

package/docs/demo-video-script.md

@@ -0,0 +1,49 @@
+# Short Video Demo Script
+
+Use this script to record a 60-90 second launch demo. It keeps the story narrow: one human-approved context handoff plus one optional reply handoff, with no hosted service.
+
+## Setup
+
+Record a terminal at 120 columns or wider.
+
+```bash
+cd handoff
+pnpm install
+pnpm build
+rm -f .relay/demo-video.db .relay/demo-video.db-shm .relay/demo-video.db-wal
+```
+
+## Recording Flow
+
+1. Show the product promise:
+   "Handoff packages selected agent-session context into a reviewable packet so another coding agent can continue from the right evidence."
+
+2. Run the full local demo:
+
+   ```bash
+   npx -y handoff-relay demo two-user --db .relay/demo-video.db --json
+   ```
+
+3. Point out the shape of the output:
+   - workspace-scoped member identities without raw tokens or approval secrets
+   - ask status ending in `closed_resolved`
+   - reply status ending in `hydrated`
+   - share status ending in `archived`
+   - audit receipts on the packets
+
+4. Show the watcher notification command users run in a second terminal:
+
+   ```bash
+   npx -y handoff-relay watch --db .relay/demo-video.db --token <alice-token> --workspace <workspace-id> --once
+   ```
+
+5. Show optional native desktop and webhook notification flags:
+
+   ```bash
+   npx -y handoff-relay watch --db .relay/demo-video.db --token <alice-token> --workspace <workspace-id> --desktop-notifications
+   npx -y handoff-relay watch --db .relay/demo-video.db --token <alice-token> --workspace <workspace-id> --webhook-url https://hooks.example.test/relay
+   ```
+
+## Closing Line
+
+"No passive team memory, no raw transcript dump, no autonomous agent chat. Just structured teammate handoffs with approval, redaction, permissions, and receipts."

package/docs/generic-mcp-setup.md

@@ -0,0 +1,163 @@
+# Generic MCP Setup
+
+Handoff is a stdio MCP server. Any MCP client that can launch a command with arguments can use it.
+
+## Team Setup
+
+On Sam's machine, host a LAN-reachable workspace:
+
+```bash
+npx -y handoff-relay start --lan
+npx -y handoff-relay invite alice
+npx -y handoff-relay doctor
+```
+
+On Alice's machine, run the invite command Sam sends her:
+
+```bash
+npx -y handoff-relay join http://<sam-lan-ip>:3737/invite/<invite-token>
+npx -y handoff-relay doctor
+```
+
+Alice does not run `start` for Sam's workspace. `join` accepts the invite, stores Alice's local profile and credentials, and prints the same profile-backed MCP command for her MCP client.
+
+Handoff can write MCP config for Codex and Cursor when you ask explicitly:
+
+```bash
+npx -y handoff-relay start --lan --install-mcp codex
+npx -y handoff-relay start --lan --install-mcp cursor
+npx -y handoff-relay join <invite-link> --install-mcp codex
+npx -y handoff-relay join <invite-link> --install-mcp cursor
+```
+
+For Claude Code and other MCP clients, use the printed profile-backed command. `doctor` reports `WARN` until it detects a supported Codex, Claude Code, or Cursor config that already includes Handoff profile mode.
+
+For same-machine demos or CI smoke tests, plain `start` remains available, but its invite links are loopback-only.
+
+## Profile-Backed Config
+
+Use profile mode for normal agent sessions:
+
+```json
+{
+  "mcpServers": {
+    "handoff": {
+      "command": "npx",
+      "args": ["-y", "handoff-relay", "server", "mcp", "--profile", "default"]
+    }
+  }
+}
+```
+
+In this mode, Handoff injects the member token and workspace ID from the local profile. Normal MCP tool schemas omit `authToken` and `workspaceId`. Approval secrets are never exposed through MCP.
+
+Strict approval remains the default. If you want the local agent session to treat your explicit chat instruction as approval, add `--agent-approvals`:
+
+```json
+{
+  "mcpServers": {
+    "handoff": {
+      "command": "npx",
+      "args": ["-y", "handoff-relay", "server", "mcp", "--profile", "default", "--agent-approvals"]
+    }
+  }
+}
+```
+
+With that flag, the MCP process requests and consumes short-lived approval tokens through the configured Handoff backend after the agent shows you the packet and you explicitly tell it to send, approve, or hydrate. Local database profiles keep that request local; remote profiles send the approval secret to the configured Handoff server API.
+
+## Cursor
+
+In Cursor, open Settings > Tools & MCP and add a new MCP server, or create `.cursor/mcp.json` for a project-scoped setup or `~/.cursor/mcp.json` for a global setup:
+
+```bash
+npx -y handoff-relay start --lan --install-mcp cursor
+npx -y handoff-relay join <invite-link> --install-mcp cursor
+```
+
+```json
+{
+  "mcpServers": {
+    "handoff": {
+      "command": "npx",
+      "args": ["-y", "handoff-relay", "server", "mcp", "--profile", "default"]
+    }
+  }
+}
+```
+
+Then ask Cursor Agent:
+
+```text
+Use Handoff to package the current investigation context for @alice.
+Show me the Relay Packet before sending.
+```
+
+## LAN And Remote Profiles
+
+For a same-network team setup:
+
+```bash
+npx -y handoff-relay start --lan
+npx -y handoff-relay invite alice
+```
+
+For remote/self-hosted setups, users should `join` an invite link from that server. The saved profile records the remote server URL, so the MCP command stays the same:
+
+```bash
+npx -y handoff-relay server mcp --profile default
+```
+
+## Explicit-Auth Compatibility
+
+For advanced scripts and tests that intentionally pass auth through tool inputs:
+
+```json
+{
+  "mcpServers": {
+    "handoff": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "handoff-relay",
+        "server",
+        "mcp",
+        "--server-url",
+        "http://10.0.0.10:3737",
+        "--explicit-auth"
+      ]
+    }
+  }
+}
+```
+
+Explicit-auth mode exposes `authToken` and `workspaceId` in schemas. Do not put approval secrets in config.
+
+## Tool Contract
+
+- `relay_ask`: draft an ask packet; returns `pending_sender_approval`.
+- `relay_share`: draft a share packet; returns `pending_sender_approval`.
+- `relay_update_draft`: edit a draft before sender approval.
+- `relay_configure_project_alias`: maps a clone/repo alias to a canonical project name.
+- `relay_project_aliases`: lists workspace project/repo aliases.
+- `relay_approve`: approves and sends ask/share packets, or approves reply packets. Requires a human approval token unless profile-backed MCP started with `--agent-approvals`.
+- `relay_inbox`: lists packets addressed to the current member.
+- `relay_status`: fetches a readable packet.
+- `relay_view`: records a review view.
+- `relay_accept`: records recipient acceptance before hydration.
+- `relay_hydrate`: returns bounded context plus a hydration receipt. Requires a human hydration approval token unless profile-backed MCP started with `--agent-approvals`.
+- `relay_reply`: drafts a reply packet; returns `pending_recipient_approval`.
+- `relay_clarify`: requests more information or evidence from the sender after packet review.
+- `relay_decline`: declines an addressed packet.
+- `relay_archive`: archives a readable packet.
+- `relay_search`: searches only permitted packet history and never hydrates results.
+- `relay_history`: lists drafts, sent packets, open work, or closed packets with typed filters.
+- `relay_audit`: lists packet audit receipts, or workspace receipts for admins.
+
+In strict mode, generate approval tokens through the local CLI:
+
+```bash
+npx -y handoff-relay approval-token <packet-id> --action send
+npx -y handoff-relay approval-token <packet-id> --action hydrate
+npx -y handoff-relay approval-token <reply-packet-id> --action reply
+```