patchwork-os 0.2.0-beta.1 → 0.2.0-beta.10.canary.95

package/README.bridge.md

@@ -5,7 +5,7 @@
 [![Docker](https://img.shields.io/badge/docker-ghcr.io%2FOolab--labs%2Fclaude--ide--bridge-blue)](https://github.com/Oolab-labs/claude-ide-bridge/pkgs/container/claude-ide-bridge)
 [![License: MIT](https://img.shields.io/npm/l/claude-ide-bridge)](https://opensource.org/licenses/MIT)
 
-**MCP bridge giving Claude Code IDE superpowers: 141 tools for LSP, debugging, git, GitHub, terminals, and more.**
+**MCP bridge giving Claude Code IDE superpowers — 170+ tools for LSP, debugging, git, GitHub, terminals, and more (see [platform-docs](documents/platform-docs.md) for the full list).**
 
 A WebSocket bridge between Claude Code CLI and your VS Code extension. Claude sees what your IDE sees — live diagnostics, go-to-definition, call hierarchies, hover types, breakpoints, debugger state — and can act on it: edit files, run tests, commit, open PRs, all without you copy-pasting anything.
 
@@ -21,11 +21,11 @@ https://github.com/user-attachments/assets/a81a8d11-2cc3-46f3-88ad-6a905a221a2c
 
 ## Quick Start
 
-**Prerequisites:** [Claude Code CLI](https://claude.ai/code), Node.js ≥ 20
+**Prerequisites:** [Claude Code CLI](https://claude.ai/code), Node.js ≥ 22
 
 ```bash
 # 1. Install the bridge
-npm install -g claude-ide-bridge
+npm install -g patchwork-os
 
 # 2. One-command setup (installs extension, writes CLAUDE.md, registers MCP server)
 cd /your/project
@@ -38,7 +38,7 @@ claude-ide-bridge --watch
 claude --ide
 ```
 
-> **Updating?** Use `npm install -g claude-ide-bridge@latest` — `npm update -g` may lag the registry cache after a new release.
+> **Updating?** Use `npm install -g patchwork-os@latest` — `npm update -g` may lag the registry cache after a new release.
 
 > **macOS LaunchAgent users:** always install from the registry (`npm install -g patchwork-os`) or
 > from a tarball (`npm pack && npm install -g patchwork-os-*.tgz`).
@@ -81,7 +81,7 @@ Or search **Claude IDE Bridge** in the VS Code / Cursor / Windsurf marketplace.
 
 ## Slim vs Full Mode
 
-The bridge starts in **full mode** by default (changed in v2.43.0) — all ~140 tools, covering LSP/debugger/refactoring plus git, GitHub, terminal, file tree, and orchestration.
+The bridge starts in **full mode** by default (changed in v2.43.0) — all 177 tools, covering LSP/debugger/refactoring plus git, GitHub, terminal, file tree, and orchestration.
 
 Pass `--slim` to restrict to the ~60 IDE-exclusive tools (LSP, debugger, editor state only) — useful when you want Claude to use its native Read/Write/Bash tools for everything else:
 
@@ -144,7 +144,7 @@ Claude calls `refactorAnalyze` (checks blast radius and risk), `refactorPreview`
 Standard setup. Extension connects automatically. Full LSP, debugger, and editor state available.
 
 ### Remote SSH
-VS Code Remote-SSH and Cursor SSH load the extension on the VPS side (`extensionKind: ["workspace"]`). Start the bridge on the remote machine. All ~140 tools work over SSH.
+VS Code Remote-SSH and Cursor SSH load the extension on the VPS side (`extensionKind: ["workspace"]`). Start the bridge on the remote machine. All 177 tools work over SSH.
 
 ```bash
 # On the remote machine
@@ -192,7 +192,7 @@ claude-ide-bridge start-task "Refactor the auth module for clarity, keep behavio
 claude-ide-bridge continue-handoff
 ```
 
-Requires `--claude-driver subprocess` on the running bridge. All three subcommands accept `--json`, `--port`, `--source`. Enforces a 5s bridge-global cooldown per preset (shared with the sidebar).
+Requires `--driver subprocess` on the running bridge. All three subcommands accept `--json`, `--port`, `--source`. Enforces a 5s bridge-global cooldown per preset (shared with the sidebar).
 
 ---
 
@@ -223,7 +223,7 @@ Event-driven hooks that trigger Claude tasks automatically — no polling, no ma
 
 Start with:
 ```bash
-claude-ide-bridge --watch --automation --automation-policy ./policy.json --claude-driver subprocess
+claude-ide-bridge --watch --automation --automation-policy ./policy.json --driver subprocess
 ```
 
 **18 hook events:** `onFileSave`, `onFileChanged`, `onDiagnosticsError`, `onDiagnosticsCleared`, `onGitCommit`, `onGitPush`, `onGitPull`, `onBranchCheckout`, `onPullRequest`, `onTestRun`, `onTestPassAfterFailure`, `onPostCompact`, `onInstructionsLoaded`, `onTaskCreated`, `onTaskSuccess`, `onPermissionDenied`, `onCwdChanged`, `onDebugSessionEnd`
@@ -274,7 +274,7 @@ claude-ide-bridge install claude-mem
 |---|---|
 | `claude-ide-bridge init` | One-command setup: install extension + write CLAUDE.md + register MCP server |
 | `claude-ide-bridge --watch` | Start bridge with auto-restart on crash (2s → 30s backoff) |
-| `claude-ide-bridge --slim` | Restrict to ~60 IDE-exclusive tools (default: ~140 full tools) |
+| `claude-ide-bridge --slim` | Restrict to ~60 IDE-exclusive tools (default: 177 full tools) |
 | `claude-ide-bridge install-extension` | Install companion VS Code extension |
 | `claude-ide-bridge gen-claude-md --write` | Add bridge section to existing CLAUDE.md |
 | `claude-ide-bridge print-token` | Print auth token from active lock file |
@@ -291,7 +291,7 @@ claude-ide-bridge install claude-mem
 
 | Flag | Default | Description |
 |---|---|---|
-| `--slim` | off | Restrict to IDE-exclusive tools (default: full, ~140 tools) |
+| `--slim` | off | Restrict to IDE-exclusive tools (default: full, 177 tools) |
 | `--full` | on | No-op (retained for backward compat — full is the default since v2.43.0) |
 | `--watch` | off | Auto-restart on crash |
 | `--bind <host>` | `127.0.0.1` | Bind address (`0.0.0.0` for remote access) |
@@ -299,7 +299,7 @@ claude-ide-bridge install claude-mem
 | `--fixed-token <uuid>` | — | Stable auth token across restarts |
 | `--automation` | off | Enable automation hooks |
 | `--automation-policy <path>` | — | Path to policy JSON |
-| `--claude-driver subprocess` | none | Enable Claude subprocess orchestration |
+| `--driver subprocess` | none | Enable Claude subprocess orchestration |
 | `--plugin <path>` | — | Load a plugin (repeatable) |
 | `--plugin-watch` | off | Hot-reload plugins on change |
 | `--issuer-url <url>` | — | Activate OAuth 2.0 mode |
@@ -314,8 +314,8 @@ claude-ide-bridge install claude-mem
 | File | Description |
 |---|---|
 | [ARCHITECTURE.md](ARCHITECTURE.md) | System topology, request lifecycle, component map, design decisions |
-| [documents/platform-docs.md](documents/platform-docs.md) | Full tool reference — all 141 tools with parameters and examples |
-| [documents/prompts-reference.md](documents/prompts-reference.md) | All MCP prompts (31 prompts, 12 plugin skills, 4 subagents) |
+| [documents/platform-docs.md](documents/platform-docs.md) | Full tool reference — all 170+ tools with parameters and examples |
+| [documents/prompts-reference.md](documents/prompts-reference.md) | All MCP prompts (36 prompts, 12 plugin skills, 4 subagents) |
 | [docs/automation.md](docs/automation.md) | Automation hooks reference — all 18 events, policy schema, condition filters |
 | [docs/troubleshooting.md](docs/troubleshooting.md) | Diagnostics, common errors, and fixes |
 | [docs/remote-access.md](docs/remote-access.md) | VPS setup, OAuth 2.0, nginx/Caddy reverse proxy |
@@ -333,7 +333,7 @@ claude-ide-bridge install claude-mem
 
 ## Requirements
 
-- **Node.js ≥ 20** (bridge)
+- **Node.js ≥ 22** (bridge)
 - **VS Code, Cursor, or Windsurf** — optional. Headless mode covers git, terminals, GitHub, and LSP via `typescript-language-server`. Extension required for debugger, editor decorations, and live editor state.
 - **Claude Code CLI** — for local use. Remote MCP clients (claude.ai, Codex CLI) work via Streamable HTTP transport with OAuth 2.0.
 

package/README.md

@@ -1,14 +1,31 @@
 # Patchwork OS
 
+[![npm beta](https://img.shields.io/npm/v/patchwork-os/beta.svg?label=npm%20%40beta)](https://www.npmjs.com/package/patchwork-os)
+[![CI](https://github.com/Oolab-labs/patchwork-os/actions/workflows/ci.yml/badge.svg)](https://github.com/Oolab-labs/patchwork-os/actions/workflows/ci.yml)
+[![npm downloads](https://img.shields.io/npm/dm/patchwork-os.svg)](https://www.npmjs.com/package/patchwork-os)
+[![license](https://img.shields.io/npm/l/patchwork-os.svg)](LICENSE)
+
 ### Your personal AI runtime, local-first.
 
+**You decide which model. You decide which actions need a human nod. You own the credentials, the logs, and the deployment.** Nothing phones home unless you [opt in to anonymous analytics](#telemetry).
+
+![Patchwork OS dashboard — connected bridge, live telemetry, and a 45-recipe library](docs/images/dashboard-overview.png)
+
 > Patchwork OS is a local-first personal AI runtime: pluggable model providers, hot-reloadable tools, YAML recipes, a delegation policy with approval queue, and a durable trace memory — all running on your machine, all under your policy.
 
-You decide which model. You decide which actions need a human nod. You own the credentials, the logs, and the deployment. Nothing phones home.
+## Contents
+
+- [Two ways to use it](#the-same-codebase-ships-two-ways-to-use-it)
+- [Dashboard only — no editor required](#dashboard-only--no-code-editor-required)
+- [Claude IDE Bridge — quick start](#-claude-ide-bridge--quick-start)
+- [Windows](#windows)
+- [Architecture](#architecture)
+- [Telemetry](#telemetry)
+- [Contributing & support](#support)
 
 **Five primitives, one runtime:**
 
-- **Tools** — 170+ built-in (LSP, git, terminal, debugger, files) plus any plugin you write. Plugins hot-reload — Claude can author a tool mid-session and call it on the next turn. See [Live Toolsmithing](documents/live-toolsmithing.md).
+- **Tools** — 177 built-in (LSP, git, terminal, debugger, files) plus any plugin you write. Plugins hot-reload — Claude can author a tool mid-session and call it on the next turn. See [Live Toolsmithing](documents/live-toolsmithing.md).
 - **Recipes** — YAML automations triggered by cron, file save, git commit, test run, or webhook. Anything that can POST a JSON payload can fire a recipe.
 - **Delegation Policy** — three risk tiers, four-source precedence (managed → project-local → project → user). Auto-approve safe, require approval for risky, block dangerous.
 - **Trace memory** — every approval, every recipe run, every enrichment is durable JSONL. Past decisions are surfaced into future sessions automatically. Bundle and back up with [`patchwork traces export`](src/commands/tracesExport.ts).
@@ -20,20 +37,45 @@ You decide which model. You decide which actions need a human nod. You own the c
 
 ---
 
-The same codebase ships **two ways to use it.** Pick the layer you need.
+## The same codebase ships two ways to use it
+
+Pick the layer you need.
 
 | | What you get | Install | Best for |
 |---|---|---|---|
-| **🔌 Claude IDE Bridge** | MCP bridge connecting Claude Code to your IDE. 170+ tools — diagnostics, LSP, debugger, terminal, git, GitHub, file ops. | `npm i -g patchwork-os` then run `claude-ide-bridge` | Anyone who wants Claude Code to see and act on their editor state |
-| **🤖 Patchwork OS** | Everything in the bridge **plus** YAML recipes, approval queue, oversight dashboard, mobile push approvals, multi-model providers, JetBrains companion. | Same package, run `patchwork patchwork-init` | Power users running automation, agent workflows, or background tasks |
+| **🔌 Claude IDE Bridge** | MCP bridge connecting Claude Code to your IDE. 177 tools — diagnostics, LSP, debugger, terminal, git, GitHub, file ops. | `npm i -g patchwork-os` then run `claude-ide-bridge` | Anyone who wants Claude Code to see and act on their editor state |
+| **🤖 Patchwork OS** | Everything in the bridge **plus** YAML recipes, approval queue, oversight dashboard, mobile push approvals, multi-model providers, JetBrains companion. | Same package, run `patchwork init` | Power users running automation, agent workflows, or background tasks |
 
 Same codebase. Bridge is the foundation; Patchwork OS is the optional layer on top. **No vendor lock-in. Runs on your machine.**
 
 ---
 
+## Dashboard Only — No Code Editor Required
+
+> You do not need VS Code, Windsurf, Cursor, or Claude Code CLI to use the Patchwork dashboard.
+
+The dashboard is a standalone Next.js app that communicates with the bridge over HTTP. No editor extension required.
+
+**Prereqs:** [Node.js 22+](https://nodejs.org) · tmux on macOS/Linux (`brew install tmux` / `apt install tmux`) — auto-detected, falls back to background mode if absent. **Windows:** natively supported — no WSL required.
+
+```bash
+npx patchwork-os@beta init   # scaffolds ~/.patchwork and generates a dashboard login (no install needed)
+patchwork start              # launches bridge + dashboard (auto-detects tmux; falls back to background mode if absent)
+```
+
+Open **http://localhost:3200** — that's it. `npx patchwork-os@beta init` auto-generates a dashboard password and saves it to `~/.patchwork/.env` — it prints the password at the end of setup, save it for your first login.
+
+**What you get:** run and schedule YAML recipes, connect external services (Gmail, Calendar, Slack), review AI drafts in the approval queue, read your AI inbox — all from the browser. No coding required.
+
+> **Want IDE features too?** See [Claude IDE Bridge — Quick Start](#-claude-ide-bridge--quick-start) below to add LSP, debugger, and editor tools on top.
+
+---
+
 ## 🔌 Claude IDE Bridge — Quick Start
 
-**Prerequisites:** a supported code editor — **VS Code, Cursor, Windsurf, or Google Antigravity** (or JetBrains via the [companion plugin](#jetbrains-plugin)) — plus Node.js 20+ and the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code). The bridge's LSP, debugger, and editor-state tools run through the editor extension; without one you're limited to the headless CLI subset.
+> Developers only — skip to [Dashboard Only](#dashboard-only--no-code-editor-required) above if you just want the web dashboard.
+
+**Prerequisites:** a supported code editor — **VS Code, Cursor, Windsurf, or Google Antigravity** (or JetBrains via the [companion plugin](#jetbrains-plugin)) — plus Node.js 22+ and the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code). The bridge's LSP, debugger, and editor-state tools run through the editor extension; without one you're limited to the headless CLI subset.
 
 ```bash
 # 1. Install the npm package
@@ -47,10 +89,15 @@ claude-ide-bridge install-extension
 claude-ide-bridge --workspace .
 
 # 4. Connect Claude Code (in another terminal)
+#    The env var skips Claude Code's built-in IDE-detection check — the bridge
+#    manages this connection itself. Add `export CLAUDE_CODE_IDE_SKIP_VALID_CHECK=true`
+#    to your shell profile so `claude --ide` is all you need going forward.
 CLAUDE_CODE_IDE_SKIP_VALID_CHECK=true claude --ide
 ```
 
-Type `/ide` in Claude Code to confirm the connection. That's it — Claude now sees your diagnostics, open files, and editor state, and can call 170+ tools to act on them.
+Type `/ide` in Claude Code to confirm the connection. That's it — Claude now sees your diagnostics, open files, and editor state, and can call 177 tools to act on them.
+
+> ⭐ If this saves you a config file or a debug session, drop a star — it's the only signal I get that it's helping.
 
 **What the bridge gives Claude:**
 
@@ -72,23 +119,46 @@ The bridge runs without any flags. No recipes, no automation, no dashboard — j
 |---|---|
 | Claude Code CLI | WebSocket `ws://127.0.0.1:<port>` |
 | Claude Desktop | stdio shim → WebSocket |
-| Remote (claude.ai, Codex CLI) | Streamable HTTP + Bearer token |
+| Gemini CLI, Codex CLI, claude.ai | Streamable HTTP + Bearer token |
+
+**Connecting Gemini CLI:**
+
+```bash
+# Get the auth token from the bridge's lock file
+patchwork-os print-token
+
+# Add the bridge as an MCP server
+gemini mcp add patchwork http://127.0.0.1:<port>/mcp \
+  --header "Authorization: Bearer <token>"
+```
+
+The bridge auto-responds to the GET probe Gemini sends before initializing, so it shows as **Connected** immediately.
 
 **Tool modes:**
 
 | Mode | Tools | When to use |
 |---|---|---|
-| Full _(default)_ | ~170 | All git, GitHub, terminal, file ops, orchestration |
+| Full _(default)_ | 177 | All git, GitHub, terminal, file ops, orchestration |
 | Slim (`--slim`) | ~60 | LSP + debugger + editor state only |
 
 Bridge-only docs: [documents/platform-docs.md](documents/platform-docs.md)
 
 ---
 
+## Windows
+
+The bridge, VS Code extension, and orchestrator all run **natively on Windows — no WSL required**. Install the same way (`npm install -g patchwork-os`), then start the bridge with `npm run start:bridge` or the full stack with `npm run start-all:node` (cross-platform) / `npm run start-all:win` (PowerShell-native).
+
+A few bash+tmux entry points (`patchwork start`, `npm run remote`) still need WSL2 or Git Bash. Credential storage uses Windows DPAPI.
+
+**Full setup, the orchestrator flag reference, and the native-Windows limitations table:** [docs/windows.md](docs/windows.md).
+
+---
+
 ## 🤖 Patchwork OS — Quick Start
 
 ```bash
-npx patchwork-os@beta patchwork-init
+npx patchwork-os@beta init
 ```
 
 Sets up 5 local recipes, detects Ollama, and opens a terminal dashboard — under 90 seconds.
@@ -99,7 +169,7 @@ Get an AI digest of your Gmail, calendar, and tasks every morning — or on dema
 
 ```bash
 # First-time setup (connect Gmail + Google Calendar)
-patchwork-os patchwork-init
+patchwork-os init
 patchwork-os connections connect gmail
 patchwork-os connections connect google-calendar
 
@@ -125,25 +195,63 @@ Think of it as a background agent that acts on your behalf — but asks before s
 
 **Recipes** are plain YAML files. They declare a trigger (cron, file save, git commit, test run, webhook) and an action (run a prompt, write to inbox, call a connector). No code required. Share them like dotfiles.
 
-**Models** are yours. Claude, GPT, Gemini, Grok, or local Ollama. Swap at any time. Nothing phones home.
+**Models** are yours. Claude, GPT, Gemini, Grok, or local Ollama. Swap at any time. Nothing phones home unless you opt in (see [Telemetry](#telemetry)).
 
-**Oversight** is non-negotiable. Every write or external action lands in `~/.patchwork/inbox/` for approval. The web UI at `http://localhost:3200` shows pending approvals, live sessions, recipe run history, and analytics.
+**Oversight** is non-negotiable. Every write or external action lands in `~/.patchwork/inbox/` for approval. The web UI at `http://localhost:3200` shows pending approvals, live sessions, recipe run history, and local analytics (the dashboard's analytics panel is computed entirely from on-disk logs — it does not transmit anything).
 
 ### Patchwork commands
 
+Grouped by what they do. Full list: `patchwork --help`.
+
+**Setup**
+
 ```bash
-# One-command setup: extension + CLAUDE.md + starter recipes
-patchwork patchwork-init
+npx patchwork-os@beta init                # one-command first-time setup (no install needed)
+patchwork install-extension               # install the VS Code / Cursor / Windsurf extension
+patchwork gen-claude-md                   # generate a starter CLAUDE.md for this workspace
+patchwork gen-plugin-stub ./my-plugin --name "org/name" --prefix "myPrefix"
+```
+
+**Runtime**
+
+```bash
+patchwork start                           # bridge + dashboard (auto-detects tmux)
+patchwork start-all                       # bridge + extension watcher in tmux
+patchwork dashboard                       # launch dashboard standalone
+patchwork shim                            # stdio shim for Claude Desktop
+patchwork status                          # one-shot health check
+patchwork print-token                     # auth token from the active lock file
+```
 
-# Explore
-patchwork recipe list                      # installed recipes
+**Recipes & tasks**
+
+```bash
+patchwork recipe list                     # installed recipes
 patchwork recipe run daily-status         # run one now
-patchwork recipe run morning-brief --local # run with local Ollama
-patchwork tools list                      # browse 170+ tools
-patchwork                                 # open terminal dashboard
+patchwork recipe new my-recipe --interactive
+patchwork start-task "<description>"      # enqueue a free-form Claude task
+patchwork quick-task fixErrors            # context-aware preset task
+patchwork continue-handoff                # resume from stored handoff note
+patchwork suggest                         # AI-suggest a recipe for a goal
+```
+
+**Ops & insight**
+
+```bash
+patchwork halts --window overnight        # morning summary of recent recipe halts
+patchwork judgments                       # review recent approval / decision traces
+patchwork traces export                   # bundle durable trace memory for backup
+patchwork launchd                         # macOS LaunchAgent management
+patchwork notify <Event>                  # bridge ←→ Claude Code hook wiring
+```
+
+**Safety**
 
-# Web UI — bridge + extension watcher in tmux
-patchwork start-all                       # then http://localhost:3200
+```bash
+patchwork kill-switch engage              # stop all background automation immediately
+patchwork kill-switch status              # is the kill-switch active?
+patchwork kill-switch release             # resume automation
+patchwork panic                           # alias for `kill-switch engage`
 ```
 
 ### Starter recipes
@@ -169,11 +277,11 @@ The package ships these in `templates/recipes/`. Recipes that need API keys are
 
 **Delegation policy presets** ([`templates/policies/`](templates/policies/)): five persona starters — conservative, developer, headless-CI, regulated-industry, personal-assistant. Copy one into `~/.patchwork/config.json` and restart.
 
-**Webhook recipe starters** ([`templates/recipes/webhook/`](templates/recipes/webhook/)): five webhook-triggered recipes — capture-thought, morning-brief (on-demand), meeting-prep, incident-intake, customer-escalation. Anything that can POST HTTP can drive these — iPhone Shortcut, Stream Deck, Home Assistant, NFC tag, monitoring tool.
+**Webhook recipe starters** ([`templates/recipes/webhook/`](templates/recipes/webhook/)): six webhook-triggered recipes — capture-thought, morning-brief (on-demand), meeting-prep, incident-intake, customer-escalation, apple-watch-health-log. Anything that can POST HTTP can drive these — iPhone Shortcut, Stream Deck, Home Assistant, NFC tag, monitoring tool.
 
 ### Automation hooks
 
-Event-driven hooks trigger Claude tasks automatically. Activate with `--automation --automation-policy <path.json> --claude-driver subprocess`.
+Event-driven hooks trigger Claude tasks automatically. Activate with `--automation --automation-policy <path.json> --driver subprocess`.
 
 Key hooks:
 
@@ -193,13 +301,43 @@ All hooks support inline prompts, named prompt references, and a minimum 5s cool
 
 ---
 
+## More features
+
+### 🖥️ Cowork (computer-use handoff)
+
+Hand a task off to Claude's computer-use sandbox without losing IDE context. Run `/mcp__bridge__cowork` in a regular Claude chat to snapshot editor state, then open Cowork — it reads the handoff note for instant continuity. Cowork runs in an isolated git worktree. See [docs/cowork.md](docs/cowork.md).
+
+### 🔐 OAuth 2.0 — turn your runtime into a personal API
+
+Start the bridge with `--issuer-url https://your-domain.com` to expose a full OAuth 2.0 surface: PKCE S256, dynamic client registration (RFC 7591), `/oauth/authorize` approval page, opaque 24h access tokens. Connect claude.ai, Codex CLI, or any MCP client over Streamable HTTP. See [docs/remote-access.md](docs/remote-access.md).
+
+### 🛑 Kill-switch — stop everything, now
+
+`patchwork kill-switch engage` (or the `patchwork panic` alias) halts all running automation, recipes, and orchestrator tasks immediately. `patchwork kill-switch status` reports state; `release` resumes. Designed for the moment you realise an agent is doing the wrong thing.
+
+### 🪟 Native Windows support
+
+Bridge, VS Code extension, smoke harness, and CI are all green on native Windows — no WSL required. See [Windows Quick Start](#-windows-quick-start) above.
+
+### ☀️ Morning summary
+
+`patchwork halts --window overnight` prints a one-screen digest of recipe halts (categorised, 5 most recent reasons). Pair with `patchwork judgments` to review what Claude decided overnight before approving anything.
+
+### 🛒 Recipe marketplace — install + submit from the dashboard
+
+Browse the curated registry at [github.com/patchworkos/recipes](https://github.com/patchworkos/recipes) at **`/marketplace`** in the dashboard. One-click install if the bridge is running, with risk + connector preview before fetch.
+
+Contributing a recipe? **`/marketplace/submit`** is a full in-app submission flow: starter YAML presets (manual / scheduled / webhook), live `recipe.json` manifest preview, auto-save draft in `sessionStorage`, lint via the bridge before submit, and a "Submit to GitHub" button that opens a prefilled create-file PR on the registry repo. GitHub auto-forks for users without push access — no extra accounts needed.
+
+---
+
 ## Architecture
 
 ```
 patchwork-os (npm package)
 │
 ├── claude-ide-bridge          ← run alone for bridge-only mode
-│   ├── MCP server             170+ tools over WebSocket / HTTP / stdio
+│   ├── MCP server             177 tools over WebSocket / HTTP / stdio
 │   ├── VS Code extension      LSP, debugger, editor state, live diagnostics
 │   ├── Git / GitHub           gitCommit, gitPush, githubCreatePR, …
 │   ├── Terminal               runInTerminal, getTerminalOutput, …
@@ -225,13 +363,13 @@ Use whichever fits your mental model.
 
 ---
 
-## Tool surface (v0.2.0-beta.0)
+## Tool surface
 
-170+ MCP tools across 15 categories. Highlights:
+177 MCP tools across 15 categories. Highlights:
 
 | Category | Tools |
 |---|---|
-| LSP / Code Intelligence | `getDiagnostics`, `goToDefinition`, `findReferences`, `getCallHierarchy`, `renameSymbol`, `refactorAnalyze`, `explainSymbol`, … (37 tools) |
+| LSP / Code Intelligence | `getDiagnostics`, `goToDefinition`, `findReferences`, `getCallHierarchy`, `renameSymbol`, `refactorAnalyze`, `explainSymbol`, … (34 tools) |
 | Git | `getGitStatus`, `getGitDiff`, `gitCommit`, `gitPush`, `gitCheckout`, `gitBlame`, … (16 tools) |
 | GitHub | `githubCreatePR`, `githubListPRs`, `githubCreateIssue`, `githubPostPRReview`, … (13 tools) |
 | Terminal | `runInTerminal`, `createTerminal`, `getTerminalOutput`, `waitForTerminalOutput` |
@@ -293,17 +431,17 @@ Systemd service and deploy scripts in [`deploy/`](deploy/). Full guide: [docs/re
 
 | Feature | Status |
 |---|---|
-| 170+ MCP tools (LSP, git, tests, debugger, diagnostics) | **shipped** |
+| 177 MCP tools (LSP, git, tests, debugger, diagnostics) | **shipped** |
 | VS Code / Cursor / Windsurf / Antigravity extension | **shipped** |
 | JetBrains plugin (49 handlers) | **shipped** |
-| `patchwork-init` — one-command setup | **shipped** |
+| `patchwork init` — one-command setup | **shipped** |
 | Terminal dashboard | **shipped** |
 | Web oversight UI (approvals, sessions, recipes) | **shipped** |
 | Recipe runner (YAML, cron, manual, webhook) | **shipped** |
 | Multi-provider LLM (Claude, Gemini, OpenAI, Grok, Ollama) | **shipped** |
 | Connectors: Linear, Sentry, Slack, Google Calendar, Intercom, HubSpot, Datadog, Stripe | **shipped** |
 | Cross-session memory (traces, handoff notes) | **shipped** |
-| Mobile oversight PWA (push approvals) | **shipped (beta)** |
+| Mobile oversight PWA (push approvals) | **shipped** |
 | Community recipe bundles (`patchwork recipe install github:<org>/<repo>`) | **shipped** |
 | Community recipe registry / discovery UI | TBD |
 
@@ -320,17 +458,38 @@ npm install && npm run build
 # Symlink installs break the macOS LaunchAgent (EPERM at startup)
 npm pack
 npm install -g patchwork-os-*.tgz
-patchwork patchwork-init
+patchwork init
 ```
 
 ---
 
+## Telemetry
+
+Patchwork ships an **opt-in** anonymous usage summary. It is **disabled by default** — the bridge sends nothing unless you explicitly turn it on.
+
+**If you opt in**, on bridge shutdown an aggregate summary is POSTed to `https://analytics.claude-ide-bridge.dev/v1/usage`:
+
+- Total session count and total tool-call count (no per-call payloads)
+- Tool name → call count + median/p95 latency, capped at the top-N tools
+- Bridge version, Node version, OS family (`darwin` / `linux` / `win32`)
+- A per-install random salt (regenerated at any time by deleting `~/.claude/ide/analytics-salt`) used to coalesce repeated installs from the same machine without sending machine identifiers
+
+**What is never sent:** workspace paths, file contents, prompts, tool arguments, tool output, project names, git history, credentials, IPs (transport-level only, dropped server-side), or anything from `~/.patchwork/`.
+
+**How to opt in:** set `analyticsEnabled: true` in the dashboard's Settings panel, or write `{"enabled": true, "decidedAt": "<iso>"}` to `~/.claude/ide/analytics.json` (mode 0600).
+
+**How to opt out / stay out:** do nothing. Default state is `null` (no preference) which behaves as opt-out. To explicitly opt out and silence future prompts, write `{"enabled": false, ...}` to the same file.
+
+**Source:** [src/analyticsSend.ts](src/analyticsSend.ts), [src/analyticsAggregator.ts](src/analyticsAggregator.ts), [src/analyticsPrefs.ts](src/analyticsPrefs.ts) — endpoint is hardcoded (not runtime-configurable, by design, to prevent redirect attacks).
+
+---
+
 ## Documentation
 
 | Doc | Contents |
 |---|---|
-| [documents/platform-docs.md](documents/platform-docs.md) | Full tool reference (170+ tools), automation hooks, connectors |
-| [documents/prompts-reference.md](documents/prompts-reference.md) | All 72 MCP prompts |
+| [documents/platform-docs.md](documents/platform-docs.md) | Full tool reference (177 tools), automation hooks, connectors |
+| [documents/prompts-reference.md](documents/prompts-reference.md) | All 36 MCP prompts |
 | [documents/styleguide.md](documents/styleguide.md) | Code conventions, UI patterns |
 | [documents/roadmap.md](documents/roadmap.md) | Development direction |
 | [documents/data-reference.md](documents/data-reference.md) | Data flows, state management, protocol details |
@@ -345,6 +504,14 @@ patchwork patchwork-init
 
 ---
 
+## Support
+
+- **Bugs & feature requests:** [GitHub Issues](https://github.com/Oolab-labs/patchwork-os/issues)
+- **Questions & community:** [GitHub Discussions](https://github.com/Oolab-labs/patchwork-os/discussions)
+- **Contributing:** see [CONTRIBUTING.md](CONTRIBUTING.md)
+
+---
+
 ## License
 
 MIT © Oolab Labs

package/deploy/README.md

@@ -31,7 +31,7 @@ DOMAIN=bridge.example.com bash deploy/bootstrap-new-vps.sh
 ```
 
 The bootstrap script handles everything end-to-end:
-1. Installs Node.js 20, nginx, certbot
+1. Installs Node.js 22, nginx, certbot
 2. Creates a dedicated `claude-bridge` system user (non-root)
 3. Clones the repo to `/opt/claude-ide-bridge`
 4. Runs `npm ci && npm run build`

package/deploy/bootstrap-vps.sh

@@ -1,13 +1,15 @@
 #!/usr/bin/env bash
 # deploy/bootstrap-vps.sh
-# Full VPS bootstrap for patchworkos.com
-# Run as root on a fresh Ubuntu 24.04 VPS
-# Usage: bash bootstrap-vps.sh
+# Full VPS bootstrap for a single Patchwork OS bridge.
+# Run as root on a fresh Ubuntu 24.04 VPS.
+# Usage: PATCHWORK_DOMAIN=your.tld PATCHWORK_ACME_EMAIL=you@your.tld bash bootstrap-vps.sh
 
 set -euo pipefail
 
-DOMAIN="patchworkos.com"
-EMAIL="support@gigsecure.co.ke"
+# Domain + ACME contact are deployment-specific — supply them via the
+# environment so no real domain/email is committed to version control.
+DOMAIN="${PATCHWORK_DOMAIN:?set PATCHWORK_DOMAIN, e.g. your.tld}"
+EMAIL="${PATCHWORK_ACME_EMAIL:?set PATCHWORK_ACME_EMAIL, e.g. you@your.tld}"
 BRIDGE_PORT=3284
 BRIDGE_USER="patchwork"
 BRIDGE_HOME="/opt/patchwork"
@@ -81,7 +83,6 @@ ExecStart=${BRIDGE_BIN} \\
   --vps \\
   --issuer-url https://${DOMAIN} \\
   --cors-origin https://claude.ai \\
-  --cors-origin https://app.patchworkos.com \\
   --fixed-token ${FIXED_TOKEN}
 
 Restart=always
@@ -117,11 +118,11 @@ ufw status
 
 # ── 8. Nginx config — HTTP only first (certbot needs nginx up to issue cert) ──
 info "Writing nginx config (HTTP only)..."
-cat > /etc/nginx/sites-available/patchworkos <<'NGINX'
+cat > /etc/nginx/sites-available/patchwork <<'NGINX'
 server {
     listen 80;
     listen [::]:80;
-    server_name patchworkos.com www.patchworkos.com;
+    server_name __DOMAIN__ www.__DOMAIN__;
 
     location /.well-known/acme-challenge/ { root /var/www/html; }
 
@@ -140,7 +141,11 @@ server {
 }
 NGINX
 
-ln -sf /etc/nginx/sites-available/patchworkos /etc/nginx/sites-enabled/patchworkos
+# Substitute the deployment domain into the just-written config (the heredoc
+# is quoted so nginx's own $variables survive un-expanded).
+sed -i "s/__DOMAIN__/${DOMAIN}/g" /etc/nginx/sites-available/patchwork
+
+ln -sf /etc/nginx/sites-available/patchwork /etc/nginx/sites-enabled/patchwork
 rm -f /etc/nginx/sites-enabled/default
 
 nginx -t

package/deploy/deploy-dashboard.sh

@@ -39,9 +39,17 @@ echo "==> Copying tarball to VPS..."
 scp "$TARBALL" "$VPS:/tmp/patchwork-dashboard.tar.gz"
 
 echo "==> Deploying on VPS..."
+# Pass secrets as positional args (NOT inside the heredoc body) so the
+# single-quoted heredoc still preserves remote-shell `$X` references but
+# the operator's local env reaches the VPS. Without this, the previous
+# `${PATCHWORK_BRIDGE_TOKEN:-REPLACE_ME}` inside the heredoc evaluated on
+# the remote, where the var doesn't exist, and always wrote REPLACE_ME.
 # shellcheck disable=SC2087
-ssh "$VPS" bash <<'REMOTE'
+ssh "$VPS" bash -s -- "${PATCHWORK_BRIDGE_TOKEN:-REPLACE_ME}" "${DASHBOARD_PASSWORD:-}" <<'REMOTE'
 set -euo pipefail
+# `${N:-}` so an empty/missing positional arg doesn't trip `set -u`.
+PATCHWORK_BRIDGE_TOKEN="${1:-REPLACE_ME}"
+DASHBOARD_PASSWORD="${2:-}"
 REMOTE_DIR="/opt/patchwork-dashboard"
 PM2_NAME="patchwork-dashboard"
 PORT=3200
@@ -52,10 +60,26 @@ if pm2 list | grep -q "$PM2_NAME"; then
   pm2 delete "$PM2_NAME" || true
 fi
 
+# Preserve .env.local across the deploy. Without this stash/restore, the
+# `rm -rf "$REMOTE_DIR"` below blows away every secret the operator pasted
+# (VAPID, PATCHWORK_PUSH_TOKEN, custom DASHBOARD_PASSWORD), and the "if
+# already exists, preserve" branch later in this script never fires —
+# the file no longer exists by then.
+ENV_BACKUP=""
+if [ -f "$REMOTE_DIR/.env.local" ]; then
+  ENV_BACKUP="$(mktemp /tmp/patchwork-env.XXXXXX)"
+  cp -p "$REMOTE_DIR/.env.local" "$ENV_BACKUP"
+fi
+
 # Wipe and recreate deploy dir
 rm -rf "$REMOTE_DIR"
 mkdir -p "$REMOTE_DIR"
 
+if [ -n "$ENV_BACKUP" ] && [ -f "$ENV_BACKUP" ]; then
+  cp -p "$ENV_BACKUP" "$REMOTE_DIR/.env.local"
+  rm -f "$ENV_BACKUP"
+fi
+
 # Extract
 tar -xzf /tmp/patchwork-dashboard.tar.gz -C "$REMOTE_DIR"
 rm /tmp/patchwork-dashboard.tar.gz