@schoolai/shipyard-mcp 0.3.2 → 0.4.0-rc.20260126

package/README.md

@@ -1,139 +1,193 @@
 <div align="center">
   <img src="apps/web/public/icon.svg" alt="Shipyard Logo" width="120" height="120">
   <h1>Shipyard</h1>
-  <p><strong>Verify AI agent work with collaborative review and proof-of-work artifacts</strong></p>
+  <p><strong>Ship responsibly.</strong></p>
+  <p>Human-agent collaboration with receipts.</p>
 
   <p>
     <a href="https://github.com/SchoolAI/shipyard/actions"><img src="https://img.shields.io/github/actions/workflow/status/SchoolAI/shipyard/deploy.yml?branch=main&label=deploy" alt="Deploy Status"></a>
-    <img src="https://img.shields.io/badge/TypeScript-5.6-3178C6?logo=typescript&logoColor=white" alt="TypeScript">
-    <img src="https://img.shields.io/badge/pnpm-10.x-F69220?logo=pnpm&logoColor=white" alt="pnpm">
+    <a href="https://www.npmjs.com/package/@schoolai/shipyard-mcp"><img src="https://img.shields.io/npm/v/@schoolai/shipyard-mcp" alt="npm version"></a>
     <a href="./LICENSE.md"><img src="https://img.shields.io/badge/license-FSL--1.1-blue" alt="License"></a>
+    <a href="https://github.com/SchoolAI/shipyard/discussions"><img src="https://img.shields.io/github/discussions/SchoolAI/shipyard" alt="Discussions"></a>
   </p>
 </div>
 
 ---
 
+<div align="center">
+  <img src="docs/assets/hero-inbox-split.png" alt="Shipyard Inbox with Task Detail" width="800">
+  <p><em>Inbox showing tasks needing review with split panel detail view</em></p>
+</div>
+
 ## The Problem
 
-AI agents can generate implementation tasks, but there's no good way to:
-- **Verify** the agent actually did what it claimed
-- **Review** tasks collaboratively with humans in real-time
-- **Provide feedback** that agents can act on
+You're managing multiple AI agents (Claude, Cursor, Devin), but there's no workspace where humans and agents collaborate together:
+- **No verification** — Agent says "done" but you have no proof
+- **No collaboration layer** — Humans review in GitHub, agents work in chat logs
+- **No feedback loop** — You approve work, but the agent never sees it
 
-Shipyard solves this with P2P collaborative review and proof-of-work artifacts.
+Shipyard is the collaboration workspace for mixed human-agent teams. Agents create tasks with proof. Humans review in real-time. Feedback flows both ways.
 
-## Features
+## Why Shipyard
 
-- **Real-time collaboration** — Multiple reviewers sync via WebRTC, no server required
-- **Proof-of-work artifacts** — Screenshots, videos, test results stored in GitHub
-- **MCP integration** — Works with Claude Code, Cursor, and any MCP-compatible agent
-- **Zero infrastructure** — GitHub Pages + local MCP server, no paid services
-- **BlockNote editor** — Notion-like editing with inline comments and threads
-- **Offline-first** — IndexedDB persistence, works without network
+- **Human-agent collaboration** — The first workspace designed for mixed teams. Humans and AI agents work together with structured feedback loops.
+- **Built for mixed teams** — Not a human tool with AI bolted on, or an AI tool ignoring humans. Designed for how agents and humans actually work together.
+- **Receipts, not promises** — Screenshots, videos, and test results. Not just chat logs claiming work was done.
+- **Zero infrastructure** — Works completely locally. GitHub optional for remote artifact sharing. No paid services, no servers to maintain.
+- **Real-time P2P** — Multiple agents and reviewers sync via WebRTC. Works offline, no central server required.
 
-## Platform Support
-
-| Platform | Status | Installation | Notes |
-|----------|--------|--------------|-------|
-| **Claude Code** | ✅ Full support | GitHub plugin | Complete integration with hooks + skills |
-| **OpenCode** | ⚠️ Experimental | npm + config | Native plan mode, testing in progress |
-| **Cursor** | ⚠️ MCP only | npm + config | Works via MCP tools, manual workflow |
-| **Windsurf** | ⚠️ MCP only | npm + config | Works via MCP tools, testing needed |
-| **Devin** | ⚠️ MCP only | npm + config | API-only mode has limitations |
-| **Replit Agent** | ⚠️ MCP only | npm + config | Basic functionality |
-| **GitHub Copilot** | ⚠️ MCP only | npm + config | Basic functionality |
-| **Gemini Code Assist** | ⚠️ MCP only | npm + config | Basic functionality |
-| **Codex (OpenAI)** | ❓ Research needed | TBD | Feature completeness assessment in progress |
-
-**Key:** Only Claude Code provides the full experience with automatic plan creation and approval workflows. Other platforms work via manual MCP tool invocation.
+## Get Started
 
-See [Platform Compatibility Matrix](./docs/INSTALLATION.md#platform-compatibility-matrix) for detailed feature comparison.
+Shipyard is just an MCP server. One command or a simple JSON config—works with all major AI coding tools.
 
-## Installation
+**Prerequisite:** Node.js 22+ ([download](https://nodejs.org/))
 
-### For Claude Code Users
+### Claude Code (Recommended)
 
-Install the complete Shipyard plugin (MCP server + hooks + skills):
+Full experience with hooks, skills, and auto-task creation:
 
 ```bash
 # Step 1: Add the marketplace
-/plugin marketplace add SchoolAI/shipyard
+/plugin marketplace add https://github.com/SchoolAI/shipyard.git
 
 # Step 2: Install the plugin
 /plugin install shipyard@schoolai-shipyard
 ```
 
-> **Note:** Claude Code requires adding a marketplace before installing plugins from it. This is intentional design (similar to app stores).
+### Cursor
 
-**Enable auto-updates:** After installing, run `/plugin` → Marketplaces tab → select `schoolai-shipyard` → "Enable auto-update" to receive updates automatically.
+Add to `~/.cursor/mcp.json`:
 
-<details>
-<summary>Troubleshooting: If Step 1 fails with a cache error</summary>
+```json
+{
+  "mcpServers": {
+    "shipyard": {
+      "command": "npx",
+      "args": ["-y", "-p", "@schoolai/shipyard-mcp@latest", "mcp-server-shipyard"]
+    }
+  }
+}
+```
+
+### Codex (OpenAI)
 
-There's a known Claude Code bug (#14696) with case-sensitive GitHub org names. Try the full git URL instead:
+Add via CLI:
 
 ```bash
-/plugin marketplace add https://github.com/SchoolAI/shipyard.git
+codex mcp add shipyard -- npx -y -p @schoolai/shipyard-mcp@latest mcp-server-shipyard
 ```
 
-If that stalls, start a fresh Claude Code session and try again.
-</details>
-
-This gives you:
-- ✅ MCP tools for creating and managing plans
-- ✅ Automatic hooks for plan creation workflow
-- ✅ Skills for collaborative planning
+Or add to `~/.codex/config.toml`:
 
-### For Other Platforms (Cursor, Windsurf, Replit, etc.)
+```toml
+[mcp_servers.shipyard]
+command = "npx"
+args = ["-y", "-p", "@schoolai/shipyard-mcp@latest", "mcp-server-shipyard"]
+```
 
-Install the MCP server via npm:
+### VS Code / GitHub Copilot
 
 ```bash
-npx -y -p @schoolai/shipyard-mcp mcp-server-shipyard
+code --add-mcp '{"name":"shipyard","command":"npx","args":["-y","-p","@schoolai/shipyard-mcp@latest","mcp-server-shipyard"]}'
 ```
 
-Then configure in your platform's MCP settings:
+<details>
+<summary><strong>See all platforms (Claude Desktop, Windsurf, JetBrains, Zed, etc.)</strong></summary>
+
+### Claude Desktop
+
+Add to your config file:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/claude/claude_desktop_config.json`
 
-**Cursor** (`~/.cursor/mcp.json`):
 ```json
 {
   "mcpServers": {
     "shipyard": {
       "command": "npx",
-      "args": ["-y", "-p", "@schoolai/shipyard-mcp", "mcp-server-shipyard"]
+      "args": ["-y", "-p", "@schoolai/shipyard-mcp@latest", "mcp-server-shipyard"]
     }
   }
 }
 ```
 
-**Windsurf** (`~/.windsurf/settings.json`):
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
 ```json
 {
-  "mcp.servers": {
+  "mcpServers": {
     "shipyard": {
-      "command": "npx -y -p @schoolai/shipyard-mcp mcp-server-shipyard"
+      "command": "npx",
+      "args": ["-y", "-p", "@schoolai/shipyard-mcp@latest", "mcp-server-shipyard"]
     }
   }
 }
 ```
 
-See **[docs/INSTALLATION.md](./docs/INSTALLATION.md)** for comprehensive platform-specific guides.
+### JetBrains IDEs
 
-### For Development
+1. Settings > Tools > AI Assistant > Model Context Protocol (MCP)
+2. Click "Add"
+3. Paste JSON config above
 
-```bash
-# Clone and install
-git clone https://github.com/SchoolAI/shipyard.git
-cd shipyard
-pnpm install
+### Zed
+
+Add to `~/.config/zed/settings.json`:
 
-# Start all services
-pnpm dev:all
+```json
+{
+  "context_servers": {
+    "shipyard": {
+      "command": {
+        "path": "npx",
+        "args": ["-y", "-p", "@schoolai/shipyard-mcp@latest", "mcp-server-shipyard"]
+      }
+    }
+  }
+}
 ```
 
-**Important:** Do NOT install the `shipyard` plugin if you're developing this repo. The plugin is for end users only. Local hooks/skills/MCP are always used from the project directory.
+### Continue.dev
 
-See **[SETUP.md](./docs/SETUP.md)** for full development setup.
+Create `.continue/mcpServers/shipyard.yaml`:
+
+```yaml
+mcpServers:
+  - name: Shipyard
+    command: npx
+    args: ["-y", "-p", "@schoolai/shipyard-mcp@latest", "mcp-server-shipyard"]
+```
+
+</details>
+
+**[Full installation guide with troubleshooting →](./docs/INSTALLATION.md)**
+
+## Platform Support
+
+| Platform | Experience |
+|----------|-----------|
+| **Claude Code** | Full integration — hooks, skills, MCP tools, auto-task creation |
+| **Codex, VS Code, Cursor, Windsurf** | MCP tools — manual workflow, full functionality |
+| **Other MCP clients** | Basic — depends on platform capabilities |
+
+**[See detailed compatibility matrix →](./docs/INSTALLATION.md#feature-comparison)**
+
+<details>
+<summary><strong>Using Shipyard skills on other platforms</strong></summary>
+
+Shipyard includes a skill (`skills/shipyard/SKILL.md`) that teaches Claude Code how to use the MCP tools effectively. Other platforms can use this same instruction content through their native mechanisms:
+
+- **VS Code / Copilot**: Copy to `.github/skills/shipyard/` (Agent Skills preview)
+- **Cursor**: Create `.cursor/rules/shipyard.mdc` with skill content
+- **Windsurf**: Create `.windsurf/workflows/shipyard-task.md`
+- **JetBrains**: Add to `.junie/guidelines.md`
+
+See [skills/shipyard/README.md](./skills/shipyard/README.md) for platform-specific instructions.
+
+</details>
 
 ## How It Works
 
@@ -150,60 +204,101 @@ See **[SETUP.md](./docs/SETUP.md)** for full development setup.
 └─────────────────┘             └─────────────────┘
 ```
 
-1. Agent creates a task via MCP tool → Browser opens automatically
-2. Reviewers join via shared URL → Real-time P2P sync
-3. Add comments, approve, or request changes → Agent sees feedback
-4. Agent uploads artifacts (screenshots, etc.) → Stored in GitHub
+1. **Agent creates task** via MCP tool → Browser opens automatically
+2. **Reviewers join** via shared URL → Real-time P2P sync
+3. **Add comments**, approve, or request changes → Agent sees feedback
+4. **Agent uploads artifacts** (screenshots, videos) → Stored in GitHub
+5. **Task auto-completes** when all deliverables have receipts (screenshots, videos, test results)
+
+## Features
+
+- **BlockNote editor** — Notion-like editing with inline comments and threads
+- **Kanban board** — Drag-drop tasks between Draft, Review, In Progress, Done
+- **GitHub artifacts** — Screenshots, videos, test results stored in your repo
+- **Offline-first** — IndexedDB persistence, works without network
+- **Multi-agent** — Multiple Claude Code/Cursor instances can work on same task
+
+<details>
+<summary><strong>See more screenshots</strong></summary>
 
-## Packages
+### Kanban Board
+<img src="docs/assets/board-view.png" alt="Kanban board with drag-drop columns" width="600">
 
-| Package | Description |
-|---------|-------------|
-| [`@shipyard/server`](./apps/server) | MCP server with task tools |
-| [`@shipyard/web`](./apps/web) | React app with BlockNote editor |
-| [`@shipyard/schema`](./packages/schema) | Shared types, Yjs helpers, URL encoding |
-| [`@shipyard/signaling`](./apps/signaling) | WebRTC signaling server (Cloudflare Worker) |
-| [`@shipyard/hook`](./apps/hook) | Claude Code hooks for auto-task creation |
+### Full Task Detail
+<img src="docs/assets/task-detail-full.png" alt="Task with deliverables and content" width="600">
+
+</details>
+
+## Data & Privacy
+
+| Data | Where It Lives | Control |
+|------|---------------|---------|
+| Task content | Browser (IndexedDB) + P2P sync | You own it |
+| Artifacts (local) | `~/.shipyard/artifacts/` served via localhost | You own it |
+| Artifacts (shared) | Optional: GitHub (your repo, orphan branch) | You own it |
+| MCP server | Runs locally | Never leaves your machine |
+| URLs | Encoded snapshots | Shareable, regenerable |
+
+**No telemetry. No cloud storage. GitHub optional.**
+
+Works completely locally. Add GitHub only if you need remote reviewers to access artifacts.
 
 ## Documentation
 
 | Doc | Description |
 |-----|-------------|
-| [SETUP.md](./docs/SETUP.md) | Installation, configuration, troubleshooting |
-| [BRIEF.md](./docs/BRIEF.md) | 30-second project context |
-| [architecture.md](./docs/architecture.md) | Data model, sync topology, tech choices |
-| [milestones/](./docs/milestones/) | Implementation phases and progress |
+| **[Installation](./docs/INSTALLATION.md)** | Platform-specific setup guides |
+| **[Setup](./docs/SETUP.md)** | Development setup, troubleshooting |
+| **[Architecture](./docs/architecture.md)** | Data model, sync topology, tech choices |
+| **[Brief](./docs/BRIEF.md)** | 30-second project context |
 
-## Why "Shipyard"?
+## Architecture
 
-The name captures two ideas:
-1. **Workspace metaphor** — A shipyard is where work is built
-2. **Dev culture** — "Shipping" is how developers talk about delivering value
+Shipyard is a monorepo with multiple components:
 
-The Penrose triangle logo represents the "impossible triangle" of AI development: **quality**, **speed**, and **low effort**. Traditionally you sacrifice one. Shipyard enables all three through collaborative verification loops.
+| Component | Description |
+|-----------|-------------|
+| [**MCP Server**](./apps/server) | 12 tools for task creation, artifacts, feedback |
+| [**Web App**](./apps/web) | React + BlockNote editor with Kanban board |
+| [**Schema**](./packages/schema) | Shared Yjs CRDT types and URL encoding |
+| [**WebRTC Signaling**](./apps/signaling) | P2P discovery (Cloudflare Worker) |
+| [**Hooks**](./apps/hook) | Claude Code integration |
 
-> *See [ADR-0005](./docs/decisions/0005-rebrand-peer-plan-to-shipyard.md) for the full naming rationale.*
+**Published package:** [`@schoolai/shipyard-mcp`](https://www.npmjs.com/package/@schoolai/shipyard-mcp) - Includes MCP server + hook
 
-## Claude Cowork Integration
+## Community
 
-Use Shipyard with Claude Cowork via the included skill:
+- **[GitHub Discussions](https://github.com/SchoolAI/shipyard/discussions)** — Questions, ideas, show & tell
+- **[GitHub Issues](https://github.com/SchoolAI/shipyard/issues)** — Bug reports, feature requests
 
-```
-skills/shipyard/
-├── SKILL.md      # Instructions for Claude
-├── README.md     # Setup guide
-└── examples/     # Usage examples
-```
+## Contributing
 
-See [skills/shipyard/README.md](./skills/shipyard/README.md) for setup.
+We value **ideas over implementations**. Please start with discussion:
 
-## Contributing
+### How to Contribute
 
-We welcome contributions! Please read the codebase first:
+1. **Bug reports** — [Open an issue](https://github.com/SchoolAI/shipyard/issues/new)
+2. **Feature ideas** — [Start a discussion](https://github.com/SchoolAI/shipyard/discussions/new)
+3. **Questions** — [Ask in discussions](https://github.com/SchoolAI/shipyard/discussions)
 
-1. [BRIEF.md](./docs/BRIEF.md) — Understand the project
-2. [engineering-standards.md](./docs/engineering-standards.md) — Code quality expectations
-3. [architecture.md](./docs/architecture.md) — How it all fits together
+### Before Submitting Code
+
+Open an issue describing what you want to change and get maintainer approval first. This helps us:
+- Ensure changes align with project direction
+- Avoid duplicate efforts
+- Provide design guidance upfront
+
+PRs without a linked, approved issue may be closed.
+
+### AI Assistance
+
+AI-assisted contributions are welcome. We use AI ourselves. What matters is that **you** understand what you're submitting and can answer questions about it.
+
+### Learn the Codebase
+
+1. **[Brief](./docs/BRIEF.md)** — 30-second project context
+2. **[Engineering Standards](./docs/engineering-standards.md)** — Code quality expectations
+3. **[Architecture](./docs/architecture.md)** — How it all fits together
 
 ## License
 
@@ -212,10 +307,4 @@ We welcome contributions! Please read the codebase first:
 - **Free** for all non-competing use
 - **Converts to Apache 2.0** automatically in 2 years
 
-We chose this to ensure that all core improvements help grow this main repository while keeping it free for developers.
-
 ---
-
-<div align="center">
-  <sub>Built with Yjs, BlockNote, and the MCP protocol</sub>
-</div>