@schoolai/shipyard-mcp 0.2.2-next.507 → 0.2.2-next.508

package/apps/hook/dist/index.cjs

@@ -28490,383 +28490,18 @@ init_cjs_shims();
 
 // ../../packages/shared/dist/instructions/index.mjs
 init_cjs_shims();
-var CRITICAL_USAGE_SECTION = `## CRITICAL: When to Use Shipyard
-
-\u26A0\uFE0F **MANDATORY USAGE RULE:**
-
-If Shipyard is available, you MUST use it for:
-- Creating implementation plans
-- Tracking work that needs human review
-- Documenting proof of work (screenshots, videos, test results)
-- ANY user request involving "plan", "track", "verify", or "prove"
-
-**DO NOT:**
-- Create plans manually in chat or as markdown files
-- Write implementation docs yourself when Shipyard is available
-- Suggest alternatives to Shipyard for trackable work
-- Overthink whether to use it - WHEN IN DOUBT, USE SHIPYARD
-
-**Decision Tree:**
-\`\`\`
-Need to create/track/verify work?
-        \u2502
-        \u25BC
-  Shipyard available?
-     \u2502           \u2502
-    YES          NO
-     \u2502           \u2502
-     \u25BC           \u25BC
-  USE IT     Manual approach
-  NOW        (tell user why)
-\`\`\``;
-var DELIVERABLES_SECTION = `## What are Deliverables?
-
-Deliverables are measurable outcomes you can **prove** with artifacts (screenshots, videos, test results).
-
-**Good deliverables (provable):**
-\`\`\`
-- [ ] Screenshot of working login page {#deliverable}
-- [ ] Video showing drag-and-drop feature {#deliverable}
-- [ ] Test results showing all tests pass {#deliverable}
-\`\`\`
-
-**Bad deliverables (not provable - these are tasks, not deliverables):**
-\`\`\`
-- [ ] Implement getUserMedia API  \u2190 Implementation detail, not provable
-- [ ] Add error handling          \u2190 Can't capture this with an artifact
-- [ ] Refactor authentication     \u2190 Too vague, no visual proof
-\`\`\`
-
-**Rule:** If you can't screenshot/record/export it, it's not a deliverable.`;
-var ARTIFACT_TYPES_SECTION = `## Artifact Types
-
-| Type | Use For | File Formats |
-|------|---------|--------------|
-| \`screenshot\` | UI changes, visual proof, error states | .png, .jpg, .webp |
-| \`video\` | Complex flows, interactions, animations | .mp4, .webm |
-| \`test_results\` | Test output, coverage reports | .json, .txt, .xml |
-| \`diff\` | Code changes, before/after comparisons | .diff, .patch |`;
-var TIPS_SECTION = `## Tips for Effective Use
-
-1. **Plan deliverables first** - Decide what proves success before coding
-2. **Capture during work** - Take screenshots as you implement, not after
-3. **Be specific** - "Login page with error state" beats "Screenshot"
-4. **Link every artifact** - Always set \`deliverableId\` for auto-completion
-5. **Check feedback** - Read reviewer comments and iterate`;
-var WHEN_NOT_TO_USE_SECTION = `## When NOT to Use Shipyard
-
-Skip Shipyard for:
-- Quick answers or research questions (no artifacts to capture)
-- Internal refactoring with no visible output
-- Tasks where proof adds no value (trivial fixes)
-- Exploration or debugging sessions
-- Pure documentation without implementation`;
-var TROUBLESHOOTING_SECTION = `## Troubleshooting
-
-**Browser doesn't open:** Check MCP server is running and accessible.
-
-**Upload fails:** Verify file path exists. For GitHub uploads, check \`GITHUB_TOKEN\` has repo write access.
-
-**No auto-complete:** Ensure every deliverable has an artifact with matching \`deliverableId\`.
-
-**Plan not syncing:** Check WebSocket connection to registry server.`;
-var COMMON_INSTRUCTIONS = [
-  CRITICAL_USAGE_SECTION,
-  DELIVERABLES_SECTION,
-  ARTIFACT_TYPES_SECTION,
-  TIPS_SECTION,
-  WHEN_NOT_TO_USE_SECTION,
-  TROUBLESHOOTING_SECTION
-].join("\n\n");
-var CLAUDE_CODE_HEADER = `[SHIPYARD] Collaborative planning with human review & proof-of-work tracking.`;
-var PLAN_MODE_WORKFLOW = `## How to Use (Claude Code with Hooks)
-
-You have the **full Shipyard experience** with automatic hooks. Use native plan mode:
-
-### Workflow
-
-1. **Enter plan mode** (Shift+Tab) \u2192 Browser opens with live plan automatically
-2. **Write your plan** with \`{#deliverable}\` markers for provable outcomes
-3. **Exit plan mode** \u2192 Hook **BLOCKS** until human approves or requests changes
-4. **On approval** \u2192 You automatically receive: planId, sessionToken, deliverable IDs
-5. **Do the work** \u2192 Take screenshots/videos as you implement
-6. **Upload artifacts** \u2192 \`add_artifact(filePath, deliverableId)\` for each deliverable
-7. **Auto-complete** \u2192 When all deliverables have artifacts, task completes with snapshot URL
-
-### After Approval
-
-You only need ONE tool: \`add_artifact\`
-
-The hook automatically injects everything you need (planId, sessionToken, deliverables).
-Just call \`add_artifact\` with the file path and deliverable ID.
-
-\`\`\`typescript
-// Example: After approval, you'll have these in context
-// planId: "abc123"
-// sessionToken: "xyz..."
-// deliverables: [{ id: "del_xxx", text: "Screenshot of login" }]
-
-await addArtifact({
-  planId,
-  sessionToken,
-  type: 'screenshot',
-  filename: 'login-page.png',
-  source: 'file',
-  filePath: '/tmp/screenshot.png',
-  deliverableId: deliverables[0].id
-});
-\`\`\`
-
-When the last deliverable gets an artifact, the task auto-completes and returns a snapshot URL.`;
-var IMPORTANT_NOTES = `## Important Notes for Claude Code
-
-- **DO NOT call \`createPlan()\` directly** - The hook handles plan creation when you enter plan mode
-- **DO NOT use the Shipyard skill** - The hook provides everything you need
-- **DO NOT poll for approval** - The hook blocks automatically until human decides
-- **DO use plan mode** for ANY work that needs tracking, verification, or human review`;
-var CLAUDE_CODE_INSTRUCTIONS = [
-  CLAUDE_CODE_HEADER,
-  "",
-  CRITICAL_USAGE_SECTION,
-  "",
-  PLAN_MODE_WORKFLOW,
-  "",
-  DELIVERABLES_SECTION,
-  "",
-  ARTIFACT_TYPES_SECTION,
-  "",
-  IMPORTANT_NOTES,
-  "",
-  TIPS_SECTION,
-  "",
-  WHEN_NOT_TO_USE_SECTION,
-  "",
-  TROUBLESHOOTING_SECTION
-].join("\n");
-var MCP_DIRECT_HEADER = `# Shipyard: Verified Work Tasks
-
-> **MCP Integration:** Use \`execute_code\` to call Shipyard APIs. This skill teaches the workflow.
-
-Shipyard turns invisible agent work into reviewable, verifiable tasks. Instead of trusting that code was written correctly, reviewers see screenshots, videos, and test results as proof.`;
-var MCP_TOOLS_OVERVIEW = `## Available MCP Tools
-
-| Tool | Purpose |
-|------|---------|
-| \`execute_code\` | Run TypeScript that calls Shipyard APIs (recommended) |
-| \`request_user_input\` | Ask user questions via browser modal |
-
-**Preferred approach:** Use \`execute_code\` to chain multiple API calls in one step.`;
-var MCP_WORKFLOW = `## Workflow (MCP Direct)
-
-### Step 1: Create Plan
-
-\`\`\`typescript
-const plan = await createPlan({
-  title: "Add user authentication",
-  content: \`
-## Deliverables
-- [ ] Screenshot of login page {#deliverable}
-- [ ] Screenshot of error handling {#deliverable}
-
-## Implementation
-1. Create login form component
-2. Add validation
-3. Connect to auth API
-\`
-});
-
-const { planId, sessionToken, deliverables, monitoringScript } = plan;
-// deliverables = [{ id: "del_xxx", text: "Screenshot of login page" }, ...]
-\`\`\`
-
-### Step 2: Wait for Approval
-
-For platforms without hooks, run the monitoring script in the background:
-
-\`\`\`bash
-# The monitoringScript polls for approval status
-# Run it in background while you wait
-bash <(echo "$monitoringScript") &
-\`\`\`
-
-Or poll manually:
-
-\`\`\`typescript
-const status = await readPlan(planId, sessionToken);
-if (status.status === "in_progress") {
-  // Approved! Proceed with work
-}
-if (status.status === "changes_requested") {
-  // Read feedback, make changes
-}
-\`\`\`
-
-### Step 3: Do the Work
-
-Implement the feature, taking screenshots/recordings as you go.
-
-### Step 4: Upload Artifacts
-
-\`\`\`typescript
-await addArtifact({
-  planId,
-  sessionToken,
-  type: 'screenshot',
-  filename: 'login-page.png',
-  source: 'file',
-  filePath: '/path/to/screenshot.png',
-  deliverableId: deliverables[0].id  // Links to specific deliverable
-});
-
-const result = await addArtifact({
-  planId,
-  sessionToken,
-  type: 'screenshot',
-  filename: 'error-handling.png',
-  source: 'file',
-  filePath: '/path/to/error.png',
-  deliverableId: deliverables[1].id
-});
-
-// Auto-complete triggers when ALL deliverables have artifacts
-if (result.allDeliverablesComplete) {
-  console.log('Done!', result.snapshotUrl);
-}
-\`\`\``;
-var API_REFERENCE = `## API Reference
-
-### createPlan(options)
-
-Creates a new plan and opens it in the browser.
 
-**Parameters:**
-- \`title\` (string) - Plan title
-- \`content\` (string) - Markdown content with \`{#deliverable}\` markers
-- \`repo\` (string, optional) - GitHub repo for artifact storage
-- \`prNumber\` (number, optional) - PR number to link
+// ../../packages/schema/dist/index.mjs
+init_cjs_shims();
 
-**Returns:** \`{ planId, sessionToken, url, deliverables, monitoringScript }\`
+// ../../packages/schema/dist/yjs-helpers-Dg3vErAn.mjs
+init_cjs_shims();
 
-### readPlan(planId, sessionToken, options?)
+// ../../packages/schema/dist/plan.mjs
+init_cjs_shims();
 
-Reads current plan state.
-
-**Parameters:**
-- \`planId\` (string) - Plan ID
-- \`sessionToken\` (string) - Session token from createPlan
-- \`options.includeAnnotations\` (boolean) - Include reviewer comments
-
-**Returns:** \`{ content, status, title, deliverables }\`
-
-### addArtifact(options)
-
-Uploads proof-of-work artifact.
-
-**Parameters:**
-- \`planId\` (string) - Plan ID
-- \`sessionToken\` (string) - Session token
-- \`type\` ('screenshot' | 'video' | 'test_results' | 'diff')
-- \`filename\` (string) - File name
-- \`source\` ('file' | 'url' | 'base64')
-- \`filePath\` (string) - Local file path (when source='file')
-- \`deliverableId\` (string, optional) - Links artifact to deliverable
-
-**Returns:** \`{ artifactId, url, allDeliverablesComplete, snapshotUrl? }\`
-
-### requestUserInput(options)
-
-Asks user a question via browser modal.
-
-**Parameters:**
-- \`message\` (string) - Question to ask
-- \`type\` (string) - Input type (see below)
-- \`options\` (string[], for 'choice') - Available choices
-- \`timeout\` (number, optional) - Timeout in seconds
-- Type-specific parameters (min, max, format, etc.)
-
-**Returns:** \`{ success, response?, status }\`
-
-**Supported types (8 total):**
-1. \`text\` - Single-line text
-2. \`multiline\` - Multi-line text area
-3. \`choice\` - Radio/checkbox/dropdown (auto-adds "Other" option)
-   - Auto-switches: 1-8 options = radio/checkbox, 9+ = dropdown
-   - \`multiSelect: true\` for checkboxes
-   - \`displayAs: 'dropdown'\` to force dropdown UI
-4. \`confirm\` - Yes/No buttons
-5. \`number\` - Numeric input with validation
-   - \`min\`, \`max\`, \`format\` ('integer' | 'decimal' | 'currency' | 'percentage')
-6. \`email\` - Email validation
-   - \`domain\` for restriction
-7. \`date\` - Date picker with range
-   - \`minDate\`, \`maxDate\` (YYYY-MM-DD format)
-8. \`rating\` - Scale rating (auto-selects stars/numbers)
-   - \`min\`, \`max\`, \`style\` ('stars' | 'numbers' | 'emoji'), \`labels\`
-
-**Response format:**
-- All responses are strings
-- choice (single): \`"PostgreSQL"\` or custom text from "Other"
-- choice (multi): \`"option1, option2"\` (comma-space separated)
-- confirm: \`"yes"\` or \`"no"\` (lowercase)
-- number: \`"42"\` or \`"3.14"\`
-- email: \`"user@example.com"\`
-- date: \`"2026-01-24"\` (ISO 8601)
-- rating: \`"4"\` (integer as string)
-- See docs/INPUT-RESPONSE-FORMATS.md for complete specification`;
-var HANDLING_FEEDBACK = `## Handling Reviewer Feedback
-
-\`\`\`typescript
-const status = await readPlan(planId, sessionToken, {
-  includeAnnotations: true
-});
-
-if (status.status === "changes_requested") {
-  // Read the content for inline comments
-  console.log(status.content);
-
-  // Make changes based on feedback
-  // Upload new artifacts
-  // Plan will transition back to pending_review
-}
-\`\`\``;
-var MCP_DIRECT_INSTRUCTIONS = [
-  MCP_DIRECT_HEADER,
-  "",
-  CRITICAL_USAGE_SECTION,
-  "",
-  MCP_TOOLS_OVERVIEW,
-  "",
-  MCP_WORKFLOW,
-  "",
-  DELIVERABLES_SECTION,
-  "",
-  ARTIFACT_TYPES_SECTION,
-  "",
-  API_REFERENCE,
-  "",
-  HANDLING_FEEDBACK,
-  "",
-  TIPS_SECTION,
-  "",
-  WHEN_NOT_TO_USE_SECTION,
-  "",
-  TROUBLESHOOTING_SECTION
-].join("\n");
-
-// src/adapters/claude-code.ts
-init_cjs_shims();
-
-// ../../packages/schema/dist/index.mjs
-init_cjs_shims();
-
-// ../../packages/schema/dist/yjs-helpers-Dg3vErAn.mjs
-init_cjs_shims();
-
-// ../../packages/schema/dist/plan.mjs
-init_cjs_shims();
-
-// ../../node_modules/.pnpm/zod@4.3.5/node_modules/zod/index.js
-init_cjs_shims();
+// ../../node_modules/.pnpm/zod@4.3.5/node_modules/zod/index.js
+init_cjs_shims();
 
 // ../../node_modules/.pnpm/zod@4.3.5/node_modules/zod/v4/classic/external.js
 var external_exports = {};
@@ -44446,6 +44081,20 @@ function truncate(text, maxLength) {
   if (cleaned.length <= maxLength) return cleaned;
   return `${cleaned.slice(0, maxLength)}...`;
 }
+var TOOL_NAMES = {
+  ADD_ARTIFACT: "add_artifact",
+  ADD_PR_REVIEW_COMMENT: "add_pr_review_comment",
+  COMPLETE_TASK: "complete_task",
+  CREATE_PLAN: "create_plan",
+  EXECUTE_CODE: "execute_code",
+  LINK_PR: "link_pr",
+  READ_PLAN: "read_plan",
+  REGENERATE_SESSION_TOKEN: "regenerate_session_token",
+  REQUEST_USER_INPUT: "request_user_input",
+  SETUP_REVIEW_NOTIFICATION: "setup_review_notification",
+  UPDATE_BLOCK_CONTENT: "update_block_content",
+  UPDATE_PLAN: "update_plan"
+};
 var PlanIdSchema = external_exports.object({ planId: external_exports.string().min(1) });
 var PlanStatusResponseSchema = external_exports.object({ status: external_exports.string() });
 var HasConnectionsResponseSchema = external_exports.object({ hasConnections: external_exports.boolean() });
@@ -44557,86 +44206,520 @@ var hookRouter = router({
     return ctx.hookHandlers.getSessionContext(input.sessionId, ctx);
   })
 });
-var planRouter = router({
-  getStatus: publicProcedure.input(PlanIdSchema).output(PlanStatusResponseSchema).query(async ({ input, ctx }) => {
-    const metadata = getPlanMetadata(await ctx.getOrCreateDoc(input.planId));
-    if (!metadata) throw new TRPCError({
-      code: "NOT_FOUND",
-      message: "Plan not found"
-    });
-    return { status: metadata.status };
-  }),
-  hasConnections: publicProcedure.input(PlanIdSchema).output(HasConnectionsResponseSchema).query(async ({ input, ctx }) => {
-    return { hasConnections: await ctx.getPlanStore().hasActiveConnections(input.planId) };
-  }),
-  getLocalChanges: publicProcedure.input(PlanIdSchema).output(LocalChangesResultSchema).query(async ({ input, ctx }) => {
-    const metadata = getPlanMetadata(await ctx.getOrCreateDoc(input.planId));
-    if (!metadata) throw new TRPCError({
-      code: "NOT_FOUND",
-      message: "Plan not found"
-    });
-    const origin = metadata.origin;
-    const cwd = origin?.platform === "claude-code" ? origin.cwd : void 0;
-    if (!cwd) return {
-      available: false,
-      reason: "no_cwd",
-      message: "Plan has no associated working directory. Local changes are only available for plans created with working directory metadata."
-    };
-    return ctx.getLocalChanges(cwd);
-  }),
-  getFileContent: publicProcedure.input(external_exports.object({
-    planId: PlanIdSchema.shape.planId,
-    filePath: external_exports.string()
-  })).output(external_exports.object({
-    content: external_exports.string().nullable(),
-    error: external_exports.string().optional()
-  })).query(async ({ input, ctx }) => {
-    const metadata = getPlanMetadata(await ctx.getOrCreateDoc(input.planId));
-    if (!metadata) throw new TRPCError({
-      code: "NOT_FOUND",
-      message: "Plan not found"
-    });
-    const origin = metadata.origin;
-    const cwd = origin?.platform === "claude-code" ? origin.cwd : void 0;
-    if (!cwd) return {
-      content: null,
-      error: "No working directory available"
-    };
-    return ctx.getFileContent(cwd, input.filePath);
-  })
+var planRouter = router({
+  getStatus: publicProcedure.input(PlanIdSchema).output(PlanStatusResponseSchema).query(async ({ input, ctx }) => {
+    const metadata = getPlanMetadata(await ctx.getOrCreateDoc(input.planId));
+    if (!metadata) throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "Plan not found"
+    });
+    return { status: metadata.status };
+  }),
+  hasConnections: publicProcedure.input(PlanIdSchema).output(HasConnectionsResponseSchema).query(async ({ input, ctx }) => {
+    return { hasConnections: await ctx.getPlanStore().hasActiveConnections(input.planId) };
+  }),
+  getLocalChanges: publicProcedure.input(PlanIdSchema).output(LocalChangesResultSchema).query(async ({ input, ctx }) => {
+    const metadata = getPlanMetadata(await ctx.getOrCreateDoc(input.planId));
+    if (!metadata) throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "Plan not found"
+    });
+    const origin = metadata.origin;
+    const cwd = origin?.platform === "claude-code" ? origin.cwd : void 0;
+    if (!cwd) return {
+      available: false,
+      reason: "no_cwd",
+      message: "Plan has no associated working directory. Local changes are only available for plans created with working directory metadata."
+    };
+    return ctx.getLocalChanges(cwd);
+  }),
+  getFileContent: publicProcedure.input(external_exports.object({
+    planId: PlanIdSchema.shape.planId,
+    filePath: external_exports.string()
+  })).output(external_exports.object({
+    content: external_exports.string().nullable(),
+    error: external_exports.string().optional()
+  })).query(async ({ input, ctx }) => {
+    const metadata = getPlanMetadata(await ctx.getOrCreateDoc(input.planId));
+    if (!metadata) throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "Plan not found"
+    });
+    const origin = metadata.origin;
+    const cwd = origin?.platform === "claude-code" ? origin.cwd : void 0;
+    if (!cwd) return {
+      content: null,
+      error: "No working directory available"
+    };
+    return ctx.getFileContent(cwd, input.filePath);
+  })
+});
+var subscriptionRouter = router({
+  create: publicProcedure.input(PlanIdSchema.merge(CreateSubscriptionRequestSchema)).output(CreateSubscriptionResponseSchema).mutation(async ({ input, ctx }) => {
+    const { planId, subscribe, windowMs, maxWindowMs, threshold } = input;
+    return { clientId: ctx.getPlanStore().createSubscription({
+      planId,
+      subscribe: subscribe || ["status"],
+      windowMs: windowMs ?? 5e3,
+      maxWindowMs: maxWindowMs ?? 3e4,
+      threshold: threshold ?? 1
+    }) };
+  }),
+  getChanges: publicProcedure.input(SubscriptionClientIdSchema).output(ChangesResponseSchema).query(async ({ input, ctx }) => {
+    const { planId, clientId } = input;
+    const result = ctx.getPlanStore().getChanges(planId, clientId);
+    if (!result) throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "Subscription not found"
+    });
+    return result;
+  }),
+  delete: publicProcedure.input(SubscriptionClientIdSchema).output(DeleteSubscriptionResponseSchema).mutation(async ({ input, ctx }) => {
+    const { planId, clientId } = input;
+    return { success: ctx.getPlanStore().deleteSubscription(planId, clientId) };
+  })
+});
+var appRouter = router({
+  hook: hookRouter,
+  plan: planRouter,
+  subscription: subscriptionRouter,
+  conversation: conversationRouter
+});
+
+// ../../packages/shared/dist/instructions/index.mjs
+var CRITICAL_USAGE_SECTION = `## CRITICAL: When to Use Shipyard
+
+\u26A0\uFE0F **MANDATORY USAGE RULE:**
+
+If Shipyard is available, you MUST use it for:
+- Creating implementation plans
+- Tracking work that needs human review
+- Documenting proof of work (screenshots, videos, test results)
+- ANY user request involving "plan", "track", "verify", or "prove"
+
+**DO NOT:**
+- Create plans manually in chat or as markdown files
+- Write implementation docs yourself when Shipyard is available
+- Suggest alternatives to Shipyard for trackable work
+- Overthink whether to use it - WHEN IN DOUBT, USE SHIPYARD
+
+**Decision Tree:**
+\`\`\`
+Need to create/track/verify work?
+        \u2502
+        \u25BC
+  Shipyard available?
+     \u2502           \u2502
+    YES          NO
+     \u2502           \u2502
+     \u25BC           \u25BC
+  USE IT     Manual approach
+  NOW        (tell user why)
+\`\`\``;
+var DELIVERABLES_SECTION = `## What are Deliverables?
+
+Deliverables are measurable outcomes you can **prove** with artifacts (screenshots, videos, test results).
+
+**Good deliverables (provable):**
+\`\`\`
+- [ ] Screenshot of working login page {#deliverable}
+- [ ] Video showing drag-and-drop feature {#deliverable}
+- [ ] Test results showing all tests pass {#deliverable}
+\`\`\`
+
+**Bad deliverables (not provable - these are tasks, not deliverables):**
+\`\`\`
+- [ ] Implement getUserMedia API  \u2190 Implementation detail, not provable
+- [ ] Add error handling          \u2190 Can't capture this with an artifact
+- [ ] Refactor authentication     \u2190 Too vague, no visual proof
+\`\`\`
+
+**Rule:** If you can't screenshot/record/export it, it's not a deliverable.`;
+var ARTIFACT_TYPES_SECTION = `## Artifact Types
+
+| Type | Use For | File Formats |
+|------|---------|--------------|
+| \`screenshot\` | UI changes, visual proof, error states | .png, .jpg, .webp |
+| \`video\` | Complex flows, interactions, animations | .mp4, .webm |
+| \`test_results\` | Test output, coverage reports | .json, .txt, .xml |
+| \`diff\` | Code changes, before/after comparisons | .diff, .patch |`;
+var TIPS_SECTION = `## Tips for Effective Use
+
+1. **Plan deliverables first** - Decide what proves success before coding
+2. **Capture during work** - Take screenshots as you implement, not after
+3. **Be specific** - "Login page with error state" beats "Screenshot"
+4. **Link every artifact** - Always set \`deliverableId\` for auto-completion
+5. **Check feedback** - Read reviewer comments and iterate`;
+var WHEN_NOT_TO_USE_SECTION = `## When NOT to Use Shipyard
+
+Skip Shipyard for:
+- Quick answers or research questions (no artifacts to capture)
+- Internal refactoring with no visible output
+- Tasks where proof adds no value (trivial fixes)
+- Exploration or debugging sessions
+- Pure documentation without implementation`;
+var USER_INPUT_SECTION = `## Human-Agent Communication
+
+**\`${TOOL_NAMES.REQUEST_USER_INPUT}\` is THE primary way to communicate with humans during active work.**
+
+Shipyard is the central hub where humans manage AI agents. When you need to ask a question, get clarification, or request a decision - use \`${TOOL_NAMES.REQUEST_USER_INPUT}\`. The human is already in the browser viewing your plan. That's where conversations should happen.
+
+### Why Use ${TOOL_NAMES.REQUEST_USER_INPUT}
+
+- **Context:** The human sees your question alongside the plan, artifacts, and comments
+- **History:** All exchanges are logged in the plan's activity feed
+- **Continuity:** The conversation stays attached to the work, not scattered across chat windows
+- **Flexibility:** 8 input types, multi-question forms, "Other" escape hatch for custom answers
+
+### Replace Platform Tools
+
+**ALWAYS prefer \`${TOOL_NAMES.REQUEST_USER_INPUT}\` over platform-specific tools:**
+
+| Platform | DON'T Use | Use Instead |
+|----------|-----------|-------------|
+| Claude Code | \`AskUserQuestion\` | \`${TOOL_NAMES.REQUEST_USER_INPUT}\` |
+| Cursor | Built-in prompts | \`${TOOL_NAMES.REQUEST_USER_INPUT}\` |
+| Windsurf | Native dialogs | \`${TOOL_NAMES.REQUEST_USER_INPUT}\` |
+| Claude Desktop | Chat questions | \`${TOOL_NAMES.REQUEST_USER_INPUT}\` |
+
+### When to Ask
+
+Use \`${TOOL_NAMES.REQUEST_USER_INPUT}\` when you need:
+- Clarification on requirements ("Which auth provider?")
+- Decisions that affect implementation ("PostgreSQL or SQLite?")
+- Confirmation before destructive actions ("Delete this file?")
+- User preferences ("Rate this approach 1-5")
+- Any information you can't infer from context
+
+### Example
+
+\`\`\`typescript
+const result = await requestUserInput({
+  message: "Which database should we use?",
+  type: "choice",
+  options: ["PostgreSQL", "SQLite", "MongoDB"],
+  timeout: 600  // 10 minutes
+});
+
+if (result.success) {
+  console.log("User chose:", result.response);
+}
+\`\`\`
+
+**Note:** The MCP tool is named \`${TOOL_NAMES.REQUEST_USER_INPUT}\` (snake_case). Inside \`${TOOL_NAMES.EXECUTE_CODE}\`, it's available as \`requestUserInput()\` (camelCase).`;
+var TROUBLESHOOTING_SECTION = `## Troubleshooting
+
+**Browser doesn't open:** Check MCP server is running and accessible.
+
+**Upload fails:** Verify file path exists. For GitHub uploads, check \`GITHUB_TOKEN\` has repo write access.
+
+**No auto-complete:** Ensure every deliverable has an artifact with matching \`deliverableId\`.
+
+**Plan not syncing:** Check WebSocket connection to registry server.
+
+**Input request times out:** User may not have seen it or needs more time. Default timeout is 30 minutes. Try again with a longer timeout or rephrase the question.
+
+**Input request declined:** User clicked "Decline." Rephrase your question, proceed with a reasonable default, or use a different approach.
+
+**No response to input:** Check if browser is connected to the plan. User may have closed the browser window.`;
+var COMMON_INSTRUCTIONS = [
+  CRITICAL_USAGE_SECTION,
+  USER_INPUT_SECTION,
+  DELIVERABLES_SECTION,
+  ARTIFACT_TYPES_SECTION,
+  TIPS_SECTION,
+  WHEN_NOT_TO_USE_SECTION,
+  TROUBLESHOOTING_SECTION
+].join("\n\n");
+var CLAUDE_CODE_HEADER = `[SHIPYARD] Collaborative planning with human review & proof-of-work tracking.`;
+var PLAN_MODE_WORKFLOW = `## How to Use (Claude Code with Hooks)
+
+You have the **full Shipyard experience** with automatic hooks. Use native plan mode:
+
+### Workflow
+
+1. **Enter plan mode** (Shift+Tab) \u2192 Browser opens with live plan automatically
+2. **Write your plan** with \`{#deliverable}\` markers for provable outcomes
+3. **Exit plan mode** \u2192 Hook **BLOCKS** until human approves or requests changes
+4. **On approval** \u2192 You automatically receive: planId, sessionToken, deliverable IDs
+5. **Do the work** \u2192 Take screenshots/videos as you implement
+6. **Upload artifacts** \u2192 \`${TOOL_NAMES.ADD_ARTIFACT}(filePath, deliverableId)\` for each deliverable
+7. **Auto-complete** \u2192 When all deliverables have artifacts, task completes with snapshot URL
+
+### After Approval
+
+You only need ONE tool: \`${TOOL_NAMES.ADD_ARTIFACT}\`
+
+The hook automatically injects everything you need (planId, sessionToken, deliverables).
+Just call \`${TOOL_NAMES.ADD_ARTIFACT}\` with the file path and deliverable ID.
+
+\`\`\`typescript
+// Example: After approval, you'll have these in context
+// planId: "abc123"
+// sessionToken: "xyz..."
+// deliverables: [{ id: "del_xxx", text: "Screenshot of login" }]
+
+await addArtifact({
+  planId,
+  sessionToken,
+  type: 'screenshot',
+  filename: 'login-page.png',
+  source: 'file',
+  filePath: '/tmp/screenshot.png',
+  deliverableId: deliverables[0].id
+});
+\`\`\`
+
+When the last deliverable gets an artifact, the task auto-completes and returns a snapshot URL.`;
+var IMPORTANT_NOTES = `## Important Notes for Claude Code
+
+- **DO NOT call \`createPlan()\` directly** - The hook handles plan creation when you enter plan mode
+- **DO NOT use the Shipyard skill** - The hook provides everything you need
+- **DO NOT poll for approval** - The hook blocks automatically until human decides
+- **DO use plan mode** for ANY work that needs tracking, verification, or human review
+- **DO use \`${TOOL_NAMES.REQUEST_USER_INPUT}\`** instead of \`AskUserQuestion\` - The human is in the browser viewing your plan, questions should appear there`;
+var CLAUDE_CODE_INSTRUCTIONS = [
+  CLAUDE_CODE_HEADER,
+  "",
+  CRITICAL_USAGE_SECTION,
+  "",
+  USER_INPUT_SECTION,
+  "",
+  PLAN_MODE_WORKFLOW,
+  "",
+  DELIVERABLES_SECTION,
+  "",
+  ARTIFACT_TYPES_SECTION,
+  "",
+  IMPORTANT_NOTES,
+  "",
+  TIPS_SECTION,
+  "",
+  WHEN_NOT_TO_USE_SECTION,
+  "",
+  TROUBLESHOOTING_SECTION
+].join("\n");
+var MCP_DIRECT_HEADER = `# Shipyard: Your Agent Management Hub
+
+> **Shipyard is the central interface where humans manage AI agents.** Plans, artifacts, feedback, and communication all happen here.
+
+Shipyard turns invisible agent work into reviewable, verifiable tasks. Instead of trusting that code was written correctly, reviewers see screenshots, videos, and test results as proof.
+
+**Key principle:** When you're working in Shipyard, ALL human-agent communication should happen through Shipyard's \`${TOOL_NAMES.REQUEST_USER_INPUT}\` tool. The human is already in the browser viewing your plan - that's where they expect to interact with you.`;
+var MCP_TOOLS_OVERVIEW = `## Available MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| \`${TOOL_NAMES.REQUEST_USER_INPUT}\` | **THE primary human-agent communication channel** - Ask questions, get decisions, request clarification |
+| \`${TOOL_NAMES.EXECUTE_CODE}\` | Run TypeScript that calls Shipyard APIs (recommended for multi-step operations) |
+
+### ${TOOL_NAMES.REQUEST_USER_INPUT}: Your Direct Line to the Human
+
+This is how you talk to humans during active work. Don't use your platform's built-in question tools (AskUserQuestion, etc.) - use this instead. The human is in the browser viewing your plan, and that's where they expect to see your questions.
+
+**Preferred approach:** Use \`${TOOL_NAMES.EXECUTE_CODE}\` to chain multiple API calls in one step.`;
+var MCP_WORKFLOW = `## Workflow (MCP Direct)
+
+### Step 1: Create Plan
+
+\`\`\`typescript
+const plan = await createPlan({
+  title: "Add user authentication",
+  content: \`
+## Deliverables
+- [ ] Screenshot of login page {#deliverable}
+- [ ] Screenshot of error handling {#deliverable}
+
+## Implementation
+1. Create login form component
+2. Add validation
+3. Connect to auth API
+\`
+});
+
+const { planId, sessionToken, deliverables, monitoringScript } = plan;
+// deliverables = [{ id: "del_xxx", text: "Screenshot of login page" }, ...]
+\`\`\`
+
+### Step 2: Wait for Approval
+
+For platforms without hooks, run the monitoring script in the background:
+
+\`\`\`bash
+# The monitoringScript polls for approval status
+# Run it in background while you wait
+bash <(echo "$monitoringScript") &
+\`\`\`
+
+Or poll manually:
+
+\`\`\`typescript
+const status = await readPlan(planId, sessionToken);
+if (status.status === "in_progress") {
+  // Approved! Proceed with work
+}
+if (status.status === "changes_requested") {
+  // Read feedback, make changes
+}
+\`\`\`
+
+### Step 3: Do the Work
+
+Implement the feature, taking screenshots/recordings as you go.
+
+### Step 4: Upload Artifacts
+
+\`\`\`typescript
+await addArtifact({
+  planId,
+  sessionToken,
+  type: 'screenshot',
+  filename: 'login-page.png',
+  source: 'file',
+  filePath: '/path/to/screenshot.png',
+  deliverableId: deliverables[0].id  // Links to specific deliverable
 });
-var subscriptionRouter = router({
-  create: publicProcedure.input(PlanIdSchema.merge(CreateSubscriptionRequestSchema)).output(CreateSubscriptionResponseSchema).mutation(async ({ input, ctx }) => {
-    const { planId, subscribe, windowMs, maxWindowMs, threshold } = input;
-    return { clientId: ctx.getPlanStore().createSubscription({
-      planId,
-      subscribe: subscribe || ["status"],
-      windowMs: windowMs ?? 5e3,
-      maxWindowMs: maxWindowMs ?? 3e4,
-      threshold: threshold ?? 1
-    }) };
-  }),
-  getChanges: publicProcedure.input(SubscriptionClientIdSchema).output(ChangesResponseSchema).query(async ({ input, ctx }) => {
-    const { planId, clientId } = input;
-    const result = ctx.getPlanStore().getChanges(planId, clientId);
-    if (!result) throw new TRPCError({
-      code: "NOT_FOUND",
-      message: "Subscription not found"
-    });
-    return result;
-  }),
-  delete: publicProcedure.input(SubscriptionClientIdSchema).output(DeleteSubscriptionResponseSchema).mutation(async ({ input, ctx }) => {
-    const { planId, clientId } = input;
-    return { success: ctx.getPlanStore().deleteSubscription(planId, clientId) };
-  })
+
+const result = await addArtifact({
+  planId,
+  sessionToken,
+  type: 'screenshot',
+  filename: 'error-handling.png',
+  source: 'file',
+  filePath: '/path/to/error.png',
+  deliverableId: deliverables[1].id
 });
-var appRouter = router({
-  hook: hookRouter,
-  plan: planRouter,
-  subscription: subscriptionRouter,
-  conversation: conversationRouter
+
+// Auto-complete triggers when ALL deliverables have artifacts
+if (result.allDeliverablesComplete) {
+  console.log('Done!', result.snapshotUrl);
+}
+\`\`\``;
+var API_REFERENCE = `## API Reference
+
+### createPlan(options)
+
+Creates a new plan and opens it in the browser.
+
+**Parameters:**
+- \`title\` (string) - Plan title
+- \`content\` (string) - Markdown content with \`{#deliverable}\` markers
+- \`repo\` (string, optional) - GitHub repo for artifact storage
+- \`prNumber\` (number, optional) - PR number to link
+
+**Returns:** \`{ planId, sessionToken, url, deliverables, monitoringScript }\`
+
+### readPlan(planId, sessionToken, options?)
+
+Reads current plan state.
+
+**Parameters:**
+- \`planId\` (string) - Plan ID
+- \`sessionToken\` (string) - Session token from createPlan
+- \`options.includeAnnotations\` (boolean) - Include reviewer comments
+
+**Returns:** \`{ content, status, title, deliverables }\`
+
+### addArtifact(options)
+
+Uploads proof-of-work artifact.
+
+**Parameters:**
+- \`planId\` (string) - Plan ID
+- \`sessionToken\` (string) - Session token
+- \`type\` ('screenshot' | 'video' | 'test_results' | 'diff')
+- \`filename\` (string) - File name
+- \`source\` ('file' | 'url' | 'base64')
+- \`filePath\` (string) - Local file path (when source='file')
+- \`deliverableId\` (string, optional) - Links artifact to deliverable
+
+**Returns:** \`{ artifactId, url, allDeliverablesComplete, snapshotUrl? }\`
+
+### requestUserInput(options)
+
+Asks user a question via browser modal.
+
+**Parameters:**
+- \`message\` (string) - Question to ask
+- \`type\` (string) - Input type (see below)
+- \`options\` (string[], for 'choice') - Available choices
+- \`timeout\` (number, optional) - Timeout in seconds
+- Type-specific parameters (min, max, format, etc.)
+
+**Returns:** \`{ success, response?, status }\`
+
+**Supported types (8 total):**
+1. \`text\` - Single-line text
+2. \`multiline\` - Multi-line text area
+3. \`choice\` - Radio/checkbox/dropdown (auto-adds "Other" option)
+   - Auto-switches: 1-8 options = radio/checkbox, 9+ = dropdown
+   - \`multiSelect: true\` for checkboxes
+   - \`displayAs: 'dropdown'\` to force dropdown UI
+4. \`confirm\` - Yes/No buttons
+5. \`number\` - Numeric input with validation
+   - \`min\`, \`max\`, \`format\` ('integer' | 'decimal' | 'currency' | 'percentage')
+6. \`email\` - Email validation
+   - \`domain\` for restriction
+7. \`date\` - Date picker with range
+   - \`minDate\`, \`maxDate\` (YYYY-MM-DD format)
+8. \`rating\` - Scale rating (auto-selects stars/numbers)
+   - \`min\`, \`max\`, \`style\` ('stars' | 'numbers' | 'emoji'), \`labels\`
+
+**Response format:**
+- All responses are strings
+- choice (single): \`"PostgreSQL"\` or custom text from "Other"
+- choice (multi): \`"option1, option2"\` (comma-space separated)
+- confirm: \`"yes"\` or \`"no"\` (lowercase)
+- number: \`"42"\` or \`"3.14"\`
+- email: \`"user@example.com"\`
+- date: \`"2026-01-24"\` (ISO 8601)
+- rating: \`"4"\` (integer as string)
+- See docs/INPUT-RESPONSE-FORMATS.md for complete specification`;
+var HANDLING_FEEDBACK = `## Handling Reviewer Feedback
+
+\`\`\`typescript
+const status = await readPlan(planId, sessionToken, {
+  includeAnnotations: true
 });
 
+if (status.status === "changes_requested") {
+  // Read the content for inline comments
+  console.log(status.content);
+
+  // Make changes based on feedback
+  // Upload new artifacts
+  // Plan will transition back to pending_review
+}
+\`\`\``;
+var MCP_DIRECT_INSTRUCTIONS = [
+  MCP_DIRECT_HEADER,
+  "",
+  CRITICAL_USAGE_SECTION,
+  "",
+  USER_INPUT_SECTION,
+  "",
+  MCP_TOOLS_OVERVIEW,
+  "",
+  MCP_WORKFLOW,
+  "",
+  DELIVERABLES_SECTION,
+  "",
+  ARTIFACT_TYPES_SECTION,
+  "",
+  API_REFERENCE,
+  "",
+  HANDLING_FEEDBACK,
+  "",
+  TIPS_SECTION,
+  "",
+  WHEN_NOT_TO_USE_SECTION,
+  "",
+  TROUBLESHOOTING_SECTION
+].join("\n");
+
+// src/adapters/claude-code.ts
+init_cjs_shims();
+
 // src/constants.ts
 init_cjs_shims();
 var CLAUDE_TOOL_NAMES = {
@@ -44645,9 +44728,6 @@ var CLAUDE_TOOL_NAMES = {
   EXIT_PLAN_MODE: "ExitPlanMode",
   ASK_USER_QUESTION: "AskUserQuestion"
 };
-var MCP_TOOL_NAMES = {
-  REQUEST_USER_INPUT: "request_user_input"
-};
 var CLAUDE_PERMISSION_MODES = {
   PLAN: "plan",
   DEFAULT: "default",
@@ -44744,7 +44824,7 @@ function handlePreToolUse(input) {
     );
     return {
       type: "tool_deny",
-      reason: `BLOCKED: Use the ${MCP_TOOL_NAMES.REQUEST_USER_INPUT} MCP tool instead for consistent browser UI. See the tool description for available parameters.`
+      reason: `BLOCKED: Use the ${TOOL_NAMES.REQUEST_USER_INPUT} MCP tool instead. The human is in the browser viewing your plan - that's where they expect to interact with you. See the tool description for input types and parameters.`
     };
   }
   return { type: "passthrough" };

package/apps/server/dist/{chunk-PCIHPLAO.js → chunk-5MXBQ56Y.js}

@@ -4,7 +4,7 @@ import {
   createInputRequest,
   createMultiQuestionInputRequest,
   logPlanEvent
-} from "./chunk-KCIANDYW.js";
+} from "./chunk-T3A2NRND.js";
 import {
   logger
 } from "./chunk-GSGLHRWX.js";

package/apps/server/dist/{chunk-KCIANDYW.js → chunk-T3A2NRND.js}

@@ -2936,6 +2936,20 @@ function truncate(text, maxLength) {
   if (cleaned.length <= maxLength) return cleaned;
   return `${cleaned.slice(0, maxLength)}...`;
 }
+var TOOL_NAMES = {
+  ADD_ARTIFACT: "add_artifact",
+  ADD_PR_REVIEW_COMMENT: "add_pr_review_comment",
+  COMPLETE_TASK: "complete_task",
+  CREATE_PLAN: "create_plan",
+  EXECUTE_CODE: "execute_code",
+  LINK_PR: "link_pr",
+  READ_PLAN: "read_plan",
+  REGENERATE_SESSION_TOKEN: "regenerate_session_token",
+  REQUEST_USER_INPUT: "request_user_input",
+  SETUP_REVIEW_NOTIFICATION: "setup_review_notification",
+  UPDATE_BLOCK_CONTENT: "update_block_content",
+  UPDATE_PLAN: "update_plan"
+};
 var PlanIdSchema = z3.object({ planId: z3.string().min(1) });
 var PlanStatusResponseSchema = z3.object({ status: z3.string() });
 var HasConnectionsResponseSchema = z3.object({ hasConnections: z3.boolean() });
@@ -3338,6 +3352,7 @@ export {
   isEventUnread,
   getAllEventViewedByForPlan,
   formatThreadsForLLM,
+  TOOL_NAMES,
   PlanIdSchema,
   PlanStatusResponseSchema,
   HasConnectionsResponseSchema,

package/apps/server/dist/{dist-WVM5QEQC.js → dist-AXKS4K2F.js}

@@ -77,6 +77,7 @@ import {
   SetSessionTokenRequestSchema,
   SetSessionTokenResponseSchema,
   SubscriptionClientIdSchema,
+  TOOL_NAMES,
   ThreadCommentSchema,
   ThreadSchema,
   UnregisterServerRequestSchema,
@@ -221,7 +222,7 @@ import {
   updateLinkedPRStatus,
   updatePlanIndexViewedBy,
   validateA2AMessages
-} from "./chunk-KCIANDYW.js";
+} from "./chunk-T3A2NRND.js";
 import "./chunk-JSBRDJBE.js";
 export {
   A2ADataPartSchema,
@@ -302,6 +303,7 @@ export {
   SetSessionTokenRequestSchema,
   SetSessionTokenResponseSchema,
   SubscriptionClientIdSchema,
+  TOOL_NAMES,
   ThreadCommentSchema,
   ThreadSchema,
   UnregisterServerRequestSchema,

package/apps/server/dist/index.js

@@ -20,7 +20,7 @@ import {
 } from "./chunk-EBNL5ZX7.js";
 import {
   InputRequestManager
-} from "./chunk-PCIHPLAO.js";
+} from "./chunk-5MXBQ56Y.js";
 import {
   ArtifactSchema,
   DeliverableSchema,
@@ -34,6 +34,7 @@ import {
   PlanStatusValues,
   QuestionSchema,
   ROUTES,
+  TOOL_NAMES,
   YDOC_KEYS,
   a2aToClaudeCode,
   addArtifact,
@@ -73,7 +74,7 @@ import {
   setPlanMetadata,
   touchPlanIndexEntry,
   transitionPlanStatus
-} from "./chunk-KCIANDYW.js";
+} from "./chunk-T3A2NRND.js";
 import {
   loadEnv,
   logger
@@ -2813,22 +2814,6 @@ function verifySessionToken(token, storedHash) {
   }
 }
 
-// src/tools/tool-names.ts
-var TOOL_NAMES = {
-  ADD_ARTIFACT: "add_artifact",
-  ADD_PR_REVIEW_COMMENT: "add_pr_review_comment",
-  COMPLETE_TASK: "complete_task",
-  CREATE_PLAN: "create_plan",
-  EXECUTE_CODE: "execute_code",
-  LINK_PR: "link_pr",
-  READ_PLAN: "read_plan",
-  REGENERATE_SESSION_TOKEN: "regenerate_session_token",
-  REQUEST_USER_INPUT: "request_user_input",
-  SETUP_REVIEW_NOTIFICATION: "setup_review_notification",
-  UPDATE_BLOCK_CONTENT: "update_block_content",
-  UPDATE_PLAN: "update_plan"
-};
-
 // src/tools/add-artifact.ts
 var AddArtifactInputBase = z3.object({
   planId: z3.string().describe("The plan ID to add artifact to"),
@@ -5365,10 +5350,11 @@ Parameters:
 - multiSelect (boolean, optional): For 'choice' type - allow selecting multiple options (checkboxes)
 - displayAs (string, optional): For 'choice' type - override automatic UI ('radio' | 'checkbox' | 'dropdown')
 - defaultValue (string, optional): Pre-filled value for text/multiline inputs
-- timeout (number, optional): Timeout in seconds (default: 1800, min: 300, max: 1800)
+- timeout (number, optional): Timeout in seconds (default: 1800, min: 10, max: 14400)
   - Simple yes/no or quick choices: 300-600 seconds (5-10 minutes)
   - Complex questions with code examples: 600-1200 seconds (10-20 minutes)
   - Default (1800 = 30 minutes) is suitable for most cases
+  - Max (14400 = 4 hours) for extended user sessions
   - Note: System-level timeouts may cause earlier cancellation
 - planId (string, optional): Optional metadata to link request to plan (for activity log filtering)
 - min (number, optional): For 'number'/'rating' - minimum value
@@ -5813,7 +5799,7 @@ async function setupReviewNotification(planId, pollIntervalSeconds) {
   return { script, fullResponse: text };
 }
 async function requestUserInput(opts) {
-  const { InputRequestManager: InputRequestManager2 } = await import("./input-request-manager-TWCEIY2F.js");
+  const { InputRequestManager: InputRequestManager2 } = await import("./input-request-manager-S3AIP2PB.js");
   const ydoc = await getOrCreateDoc3(PLAN_INDEX_DOC_NAME);
   const manager = new InputRequestManager2();
   const baseParams = {
@@ -5825,7 +5811,6 @@ async function requestUserInput(opts) {
   let params;
   switch (opts.type) {
     case "choice":
-    case "dropdown":
       params = {
         ...baseParams,
         type: opts.type,
@@ -5902,7 +5887,7 @@ async function requestUserInput(opts) {
   };
 }
 async function postActivityUpdate(opts) {
-  const { logPlanEvent: logPlanEvent2 } = await import("./dist-WVM5QEQC.js");
+  const { logPlanEvent: logPlanEvent2 } = await import("./dist-AXKS4K2F.js");
   const { getGitHubUsername: getGitHubUsername2 } = await import("./server-identity-LSZ4CZRK.js");
   const { nanoid: nanoid8 } = await import("nanoid");
   const doc = await getOrCreateDoc3(opts.planId);
@@ -5925,7 +5910,7 @@ async function postActivityUpdate(opts) {
   return { success: true, eventId, requestId };
 }
 async function resolveActivityRequest(opts) {
-  const { logPlanEvent: logPlanEvent2, getPlanEvents } = await import("./dist-WVM5QEQC.js");
+  const { logPlanEvent: logPlanEvent2, getPlanEvents } = await import("./dist-AXKS4K2F.js");
   const { getGitHubUsername: getGitHubUsername2 } = await import("./server-identity-LSZ4CZRK.js");
   const doc = await getOrCreateDoc3(opts.planId);
   const actorName = await getGitHubUsername2();
@@ -6189,10 +6174,11 @@ function buildRequestParams(input) {
 var requestUserInputTool = {
   definition: {
     name: TOOL_NAMES.REQUEST_USER_INPUT,
-    description: `Request input from the user via browser modal.
+    description: `THE primary human-agent communication channel in Shipyard.
 
-IMPORTANT: Use this instead of your platform's built-in question/input tools (like AskUserQuestion).
-This provides a consistent browser UI experience and integrates with the shipyard workflow.
+**CRITICAL:** ALWAYS use this instead of platform-specific question tools (AskUserQuestion, Cursor prompts, etc.).
+The human is already in the browser viewing your plan - that's where they expect to interact with you.
+All communication should flow through Shipyard, not scattered across different interfaces.
 
 The request appears as a modal in the browser UI. The function blocks until:
 - User responds (success=true, status='answered')
@@ -6584,12 +6570,15 @@ if (!registryPort) {
 var server = new Server(
   {
     name: "shipyard",
-    version: "0.1.0"
+    version: "0.1.0",
+    description: "Your agent management hub - the central interface where humans manage AI agents. Plans, artifacts, feedback, and all human-agent communication happen here."
   },
   {
     capabilities: {
       tools: {}
-    }
+    },
+    // Instructions shown to clients during initialization
+    instructions: `IMPORTANT: When working with Shipyard, use ${TOOL_NAMES.REQUEST_USER_INPUT} for ALL human interaction instead of platform-specific question tools (AskUserQuestion, etc.). The human is in the browser viewing your plan - that's where they expect to interact with you.`
   }
 );
 server.setRequestHandler(ListToolsRequestSchema, async () => ({

package/apps/server/dist/{input-request-manager-TWCEIY2F.js → input-request-manager-S3AIP2PB.js}

@@ -1,7 +1,7 @@
 import {
   InputRequestManager
-} from "./chunk-PCIHPLAO.js";
-import "./chunk-KCIANDYW.js";
+} from "./chunk-5MXBQ56Y.js";
+import "./chunk-T3A2NRND.js";
 import "./chunk-GSGLHRWX.js";
 import "./chunk-JSBRDJBE.js";
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schoolai/shipyard-mcp",
-  "version": "0.2.2-next.507",
+  "version": "0.2.2-next.508",
   "description": "Shipyard MCP server and CLI tools for distributed planning with CRDTs",
   "type": "module",
   "bin": {