@gethmy/mcp 2.0.0 → 2.1.1

package/dist/lib/tui/setup.js

@@ -0,0 +1,1068 @@
+import { existsSync, lstatSync, mkdirSync, symlinkSync, unlinkSync, } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import * as p from "@clack/prompts";
+import { areSkillsInstalled, getConfigPath, getLocalConfigPath, hasProjectContext, isConfigured, loadConfig, saveLocalConfig, } from "../config.js";
+import { detectAgents } from "./agents.js";
+import { runDocsStep } from "./docs.js";
+import { colors, formatPath, messages } from "./theme.js";
+import { getWriteSummary, writeFilesWithProgress } from "./writer.js";
+// Central skills directory for global installation
+const GLOBAL_SKILLS_DIR = join(homedir(), ".agents", "skills");
+// API base URL
+const API_URL = "https://gethmy.com/api";
+// Harmony workflow prompt - shared across agents
+const HARMONY_WORKFLOW_PROMPT = `# Harmony Card Workflow
+
+Start work on a Harmony card. Card reference: $ARGUMENTS
+
+## 1. Find & Fetch Card
+
+Parse the reference and fetch the card:
+- \`#42\` or \`42\` → \`harmony_get_card_by_short_id\` with \`shortId: 42\`
+- UUID → \`harmony_get_card\` with \`cardId\`
+- Name/text → \`harmony_search_cards\` with \`query\`
+
+## 2. Get Board State
+
+Call \`harmony_get_board\` to get columns and labels. From the response:
+- Find the "In Progress" (or "Progress") column ID
+- Find the "agent" label ID
+
+## 3. Setup Card for Work
+
+Execute these in sequence:
+1. \`harmony_move_card\` → Move to "In Progress" column
+2. \`harmony_add_label_to_card\` → Add "agent" label
+3. \`harmony_start_agent_session\`:
+   - \`cardId\`: Card UUID
+   - \`agentIdentifier\`: Your agent identifier
+   - \`agentName\`: Your agent name
+   - \`currentTask\`: "Analyzing card requirements"
+
+## 4. Generate Work Prompt
+
+Call \`harmony_generate_prompt\` with:
+- \`cardId\` or \`shortId\` (+ \`projectId\` if using shortId)
+- \`variant\`: Select based on task:
+  - \`"execute"\` (default) → Clear tasks, bug fixes, well-defined work
+  - \`"analysis"\` → Complex features, unclear requirements
+  - \`"draft"\` → Medium complexity, want feedback first
+
+The generated prompt provides role framing, focus areas, subtasks, linked cards, and suggested outputs.
+
+## 5. Display Card Summary
+
+Show the user: Card title, short ID, role, priority, labels, due date, description, and subtasks.
+
+## 6. Implement Solution
+
+Work on the card following the generated prompt's guidance. Update progress at milestones:
+- \`harmony_update_agent_progress\` with \`progressPercent\` (0-100), \`currentTask\`, \`status\`, \`blockers\`
+
+**Progress checkpoints:** 20% (exploration), 50% (implementation), 80% (testing), 100% (done)
+
+## 7. Complete Work
+
+When finished:
+1. \`harmony_end_agent_session\` with \`status: "completed"\`, \`progressPercent: 100\`
+2. \`harmony_move_card\` to "Review" column
+3. Summarize accomplishments
+
+If pausing: \`harmony_end_agent_session\` with \`status: "paused"\`
+
+## Key Tools Reference
+
+**Cards:** \`harmony_get_card\`, \`harmony_get_card_by_short_id\`, \`harmony_search_cards\`, \`harmony_create_card\`, \`harmony_update_card\`, \`harmony_move_card\`, \`harmony_delete_card\`, \`harmony_assign_card\`
+
+**Subtasks:** \`harmony_create_subtask\`, \`harmony_toggle_subtask\`, \`harmony_delete_subtask\`
+
+**Labels:** \`harmony_add_label_to_card\`, \`harmony_remove_label_from_card\`, \`harmony_create_label\`
+
+**Links:** \`harmony_add_link_to_card\`, \`harmony_remove_link_from_card\`, \`harmony_get_card_links\`
+
+**Board:** \`harmony_get_board\`, \`harmony_list_projects\`, \`harmony_get_context\`, \`harmony_set_project_context\`
+
+**Sessions:** \`harmony_start_agent_session\`, \`harmony_update_agent_progress\`, \`harmony_end_agent_session\`, \`harmony_get_agent_session\`
+
+**AI:** \`harmony_generate_prompt\`, \`harmony_process_command\`
+`;
+// Harmony plan prompt - unified plan creation and execution workflow
+const HARMONY_PLAN_PROMPT = `# Harmony Plan Workflow
+
+Create a new plan or work on an existing one. Argument: $ARGUMENTS
+
+## Step 1 — Detect Intent
+
+Parse \`$ARGUMENTS\` to determine the workflow:
+
+- **UUID** (contains dashes, 36 chars) → call \`harmony_get_plan\` with \`planId\` directly → **Step 2A**
+- **\`#N\`** (short ID) → call \`harmony_get_card_by_short_id\` to get the card, then \`harmony_get_plan\` with \`cardId\` → **Step 2A**
+- **Text** (anything else) → call \`harmony_list_plans\` with \`search\` set to the text
+  - If **one match** → use it → **Step 2A**
+  - If **multiple matches** → list them with title, status, phase, and updated date. Ask the user to pick one using \`AskUserQuestion\` → **Step 2A**
+  - If **no matches** → ask user: "No existing plans found for '$ARGUMENTS'. Would you like to create a new plan on this topic?" → **Step 2B**
+- **Empty / vague topic** → **Step 2B** (create new plan)
+
+---
+
+## Step 2A — Work on Existing Plan
+
+### 2A.1 — Analyze & Display
+
+Once you have the plan ID, call \`harmony_get_plan\` to fetch the full plan with tasks. Show a structured summary:
+
+\\\`\\\`\\\`
+## [Plan Title]
+**Status:** draft/active/archived | **Phase:** plan/execute/verify/done
+**Tasks:** N total (X pending, Y in_progress, Z completed)
+**URL:** https://gethmy.com/plans/{id}
+\\\`\\\`\\\`
+
+If plan is in execute phase and tasks already have linked cards, note which tasks have cards and which don't.
+
+### 2A.2 — Recall Context
+
+Call \`harmony_memory_search\` with the plan title to find related knowledge, patterns, or decisions that may inform execution.
+
+### 2A.3 — Present Options
+
+Use \`AskUserQuestion\` to offer execution choices. Adapt options based on plan state:
+
+#### Default options (plan in \`plan\` phase):
+
+**(A) Single card** — Create one card with plan summary + link to plan. Best for simple plans.
+**(B) Multiple cards** — Create one card per task via \`harmony_advance_plan\`. Best for complex plans with independent tasks.
+**(C) Analyze only** — Review the plan and design an implementation approach. Create cards later.
+**(D) Skip** — Do nothing.
+
+#### If plan has no tasks:
+Only offer **(A) Single card**, **(C) Analyze only**, or **(D) Skip**.
+
+#### If plan is already in \`execute\` phase with existing cards:
+**(A) Work on existing cards** — List cards with short IDs, suggest \`/hmy #N\` to start
+**(B) Create cards for remaining tasks** — Only create cards for tasks without linked cards
+**(C) Analyze progress** — Review what's done vs remaining
+**(D) Skip**
+
+### 2A.4 — Execute Choice
+
+#### Option A — Single card
+1. Call \`harmony_create_card\` with:
+   - \`title\`: Plan title
+   - \`description\`: Brief 2-3 sentence summary of the plan + \`\\n\\n[View plan](https://gethmy.com/plans/{planId})\`
+   - \`priority\`: based on plan task priorities (use highest)
+2. Call \`harmony_update_plan\` to set \`status: "active"\`, \`workflowPhase: "execute"\`
+
+#### Option B — Multiple cards (advance plan)
+1. Call \`harmony_advance_plan\` with:
+   - \`planId\`: the plan ID
+   - \`phase\`: \`"execute"\`
+   - \`summary\`: Brief summary of the plan scope
+2. Display the created cards with their short IDs
+
+#### Option C — Analyze only
+1. Present a structured implementation analysis:
+   - Suggested order of tasks
+   - Dependencies between tasks
+   - Key technical considerations from memory search
+   - Estimated complexity
+2. Suggest creating cards when ready
+
+#### Option D — Skip
+Acknowledge and stop.
+
+### 2A.5 — Summary
+
+After execution, show:
+- Created card(s) with short IDs
+- Current plan phase
+- Suggest next step: \`/hmy #N\` to start working on a card
+
+---
+
+## Step 2B — Create New Plan
+
+### 2B.1 — Context Gathering
+
+Before interviewing, gather existing context:
+
+1. Call \`harmony_get_board\` for board state (columns, cards, labels)
+2. Call \`harmony_recall\` with relevant tags to find existing knowledge on the topic
+3. Call \`harmony_memory_search\` with the topic to find related patterns/decisions/lessons
+
+Note what you learn — reference it during the interview to ask smarter questions.
+
+### 2B.2 — Structured Interview (3-5 questions)
+
+Interview the user with **3-5 focused questions** using AskUserQuestion. Adapt based on complexity.
+
+#### Core Questions
+1. **Problem & Audience**: What problem are we solving? Who benefits?
+2. **Scope**: What's in v1, what's deferred?
+3. **Technical Constraints**: Any technical preferences, constraints, or existing patterns to follow?
+
+#### Adaptive Follow-ups (if needed)
+- Key user flows or interactions?
+- Integration points with existing systems?
+- Performance, security, or accessibility requirements?
+
+#### Interview Rules
+- Reference what you found in Step 2B.1 (board state, memories) to ask informed questions
+- Skip questions that aren't relevant — simple features need fewer questions
+- Tell the user when you have enough information to draft
+
+### 2B.3 — Plan Document
+
+Create a structured markdown document:
+
+\\\`\\\`\\\`markdown
+# [Title]
+
+## Problem
+[What problem we're solving and why]
+
+## Scope
+
+### In Scope
+- [Feature/capability 1]
+- [Feature/capability 2]
+
+### Out of Scope
+- [Deferred items]
+
+## Approach
+[Technical design, architecture decisions, key patterns]
+
+### Key Decisions
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| ... | ... | ... |
+
+## Tasks
+1. **[Task title]** — priority: high
+   [Brief description]
+
+2. **[Task title]** — priority: medium
+   [Brief description]
+
+[Continue for all tasks...]
+
+## Risks & Mitigations
+| Risk | Mitigation |
+|------|------------|
+| ... | ... |
+
+## Success Criteria
+- [ ] [Measurable criterion]
+\\\`\\\`\\\`
+
+### 2B.4 — Create Plan
+
+Call \`harmony_create_plan\` with:
+- \`title\`: The plan title
+- \`content\`: Full markdown document from Step 2B.3
+- \`source\`: \`"agent"\`
+- \`workflowPhase\`: \`"plan"\`
+- \`tasks\`: Array of tasks from the Tasks section, each with:
+  - \`content\`: Task title + brief description
+  - \`priority\`: \`"high"\`, \`"medium"\`, or \`"low"\`
+  - \`status\`: \`"pending"\`
+
+### 2B.5 — User Approval
+
+Show the user:
+- Plan URL: \`https://gethmy.com/plans/{id}\`
+- Number of tasks created
+- Brief summary
+
+Then ask: **"Ready to execute? I'll create board cards from these tasks and start the execution phase."**
+
+Options:
+1. **Yes, advance to Execute** — proceed to Step 2B.6
+2. **Let me review first** — end here, they can advance later from the UI
+3. **Make changes** — iterate on the plan
+
+### 2B.6 — Advance to Execute
+
+Call \`harmony_advance_plan\` with:
+- \`planId\`: The plan ID from Step 2B.4
+- \`phase\`: \`"execute"\`
+- \`summary\`: A 2-3 sentence summary of the key decisions made during planning
+
+Report the result:
+- "Created N cards in 'To Do'. Use \`/hmy #<id>\` to start working on any card."
+- List the created cards with their short IDs
+
+## Key Tools Reference
+
+**Discovery:** \`harmony_list_plans\`, \`harmony_get_plan\`, \`harmony_get_card_by_short_id\`
+**Context:** \`harmony_get_board\`, \`harmony_recall\`, \`harmony_memory_search\`
+**Planning:** \`harmony_create_plan\`, \`harmony_advance_plan\`, \`harmony_update_plan\`
+**Execution:** \`harmony_create_card\`, \`harmony_update_card\`
+`;
+/**
+ * Register MCP server using Claude CLI
+ * Returns true if successful, false if CLI unavailable or failed
+ */
+async function registerMcpServer() {
+    try {
+        const { execSync } = await import("node:child_process");
+        // Use the official CLI command to register the MCP server (npx for no global install)
+        execSync("claude mcp add --transport stdio harmony -- npx -y @gethmy/mcp@latest serve", {
+            stdio: "pipe",
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Write MCP server config directly to settings.json (fallback method)
+ */
+async function writeMcpConfigFallback(home) {
+    const { readFileSync, writeFileSync, mkdirSync, existsSync } = await import("node:fs");
+    const settingsPath = join(home, ".claude", "settings.json");
+    const settingsDir = dirname(settingsPath);
+    // Ensure directory exists
+    if (!existsSync(settingsDir)) {
+        mkdirSync(settingsDir, { recursive: true });
+    }
+    // Read existing settings or start fresh
+    let settings = {};
+    if (existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+        }
+        catch {
+            // Invalid JSON, start fresh
+        }
+    }
+    // Merge mcpServers config
+    const mcpServers = settings.mcpServers || {};
+    mcpServers.harmony = {
+        command: "npx",
+        args: ["-y", "@gethmy/mcp@latest", "serve"],
+    };
+    settings.mcpServers = mcpServers;
+    // Write back
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+}
+/**
+ * Validate API key by testing connectivity
+ */
+async function validateApiKey(apiKey, apiUrl = API_URL) {
+    try {
+        const response = await fetch(`${apiUrl}/v1/workspaces`, {
+            method: "GET",
+            headers: {
+                "Content-Type": "application/json",
+                "X-API-Key": apiKey,
+            },
+        });
+        if (!response.ok) {
+            const data = await response.json().catch(() => ({}));
+            return {
+                valid: false,
+                error: data.error || `API returned ${response.status}`,
+            };
+        }
+        // Try to get user info from /me endpoint if available
+        const meResponse = await fetch(`${apiUrl}/v1/me`, {
+            method: "GET",
+            headers: {
+                "Content-Type": "application/json",
+                "X-API-Key": apiKey,
+            },
+        });
+        if (meResponse.ok) {
+            const meData = await meResponse.json();
+            return { valid: true, email: meData.user?.email };
+        }
+        return { valid: true };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            error: error instanceof Error ? error.message : "Connection failed",
+        };
+    }
+}
+/**
+ * Fetch workspaces from API
+ */
+async function fetchWorkspaces(apiKey) {
+    const response = await fetch(`${API_URL}/v1/workspaces`, {
+        method: "GET",
+        headers: {
+            "Content-Type": "application/json",
+            "X-API-Key": apiKey,
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch workspaces: ${response.status}`);
+    }
+    const data = await response.json();
+    return data.workspaces || [];
+}
+/**
+ * Fetch projects from API
+ */
+async function fetchProjects(apiKey, workspaceId) {
+    const response = await fetch(`${API_URL}/v1/workspaces/${workspaceId}/projects`, {
+        method: "GET",
+        headers: {
+            "Content-Type": "application/json",
+            "X-API-Key": apiKey,
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch projects: ${response.status}`);
+    }
+    const data = await response.json();
+    return data.projects || [];
+}
+/**
+ * Generate agent configuration files
+ */
+function getAgentFiles(agentId, cwd, installMode = "global") {
+    const home = homedir();
+    const files = [];
+    const symlinks = [];
+    switch (agentId) {
+        case "claude": {
+            // Claude Code skill file
+            const skillContent = `---
+name: hmy
+description: Start working on a Harmony card. Use when given a card reference like #42, UUID, or card name to implement.
+argument-hint: <card-reference>
+---
+
+${HARMONY_WORKFLOW_PROMPT.replace("Your agent identifier", "claude-code").replace("Your agent name", "Claude Code")}
+`;
+            // hmy-plan skill file (unified plan creation + execution)
+            const planSkillContent = `---
+name: hmy-plan
+description: Create a new plan or work on an existing one. Use when asked to plan a feature, execute a plan, review a plan, or given a plan reference.
+argument-hint: [plan name, ID, or topic to plan]
+---
+
+${HARMONY_PLAN_PROMPT.replace("$ARGUMENTS", "$ARGUMENTS")}
+`;
+            if (installMode === "global") {
+                // Global mode: Write skills to ~/.agents/skills/, symlink directories to ~/.claude/skills/
+                files.push({
+                    path: join(GLOBAL_SKILLS_DIR, "hmy", "SKILL.md"),
+                    content: skillContent,
+                    type: "text",
+                });
+                symlinks.push({
+                    target: join(GLOBAL_SKILLS_DIR, "hmy"),
+                    link: join(home, ".claude", "skills", "hmy"),
+                });
+                files.push({
+                    path: join(GLOBAL_SKILLS_DIR, "hmy-plan", "SKILL.md"),
+                    content: planSkillContent,
+                    type: "text",
+                });
+                symlinks.push({
+                    target: join(GLOBAL_SKILLS_DIR, "hmy-plan"),
+                    link: join(home, ".claude", "skills", "hmy-plan"),
+                });
+            }
+            else {
+                // Local mode: Write skills directly to project directory
+                files.push({
+                    path: join(cwd, ".claude", "skills", "hmy", "SKILL.md"),
+                    content: skillContent,
+                    type: "text",
+                });
+                files.push({
+                    path: join(cwd, ".claude", "skills", "hmy-plan", "SKILL.md"),
+                    content: planSkillContent,
+                    type: "text",
+                });
+            }
+            // Note: MCP server registration is handled separately via `claude mcp add` CLI
+            // in runSetup() after file writing, with fallback to settings.json if CLI unavailable
+            break;
+        }
+        case "codex": {
+            // AGENTS.md in project root (always local - project context)
+            const agentsContent = `# Harmony Integration
+
+This project uses Harmony for task management. When working on tasks:
+
+## Starting Work on a Card
+
+When given a card reference (e.g., #42 or a card name), follow this workflow:
+
+1. Use \`harmony_get_card_by_short_id\` or \`harmony_search_cards\` to find the card
+2. Move the card to "In Progress" using \`harmony_move_card\`
+3. Add the "agent" label using \`harmony_add_label_to_card\`
+4. Start a session with \`harmony_start_agent_session\` (agentIdentifier: "codex", agentName: "OpenAI Codex")
+5. Show the card details to the user
+6. Use \`harmony_generate_prompt\` to get guidance, then implement the solution
+7. Update progress periodically with \`harmony_update_agent_progress\`
+8. When done, call \`harmony_end_agent_session\` and move to "Review"
+
+## Available Harmony Tools
+
+- \`harmony_get_card\`, \`harmony_get_card_by_short_id\`, \`harmony_search_cards\` - Find cards
+- \`harmony_move_card\` - Move cards between columns
+- \`harmony_add_label_to_card\`, \`harmony_remove_label_from_card\` - Manage labels
+- \`harmony_start_agent_session\`, \`harmony_update_agent_progress\`, \`harmony_end_agent_session\` - Track work
+- \`harmony_get_board\` - Get board state
+- \`harmony_generate_prompt\` - Get role-based guidance and focus areas for the card
+`;
+            files.push({
+                path: join(cwd, "AGENTS.md"),
+                content: agentsContent,
+                type: "text",
+            });
+            // Codex prompt file
+            const promptContent = `---
+name: hmy
+description: Start working on a Harmony card
+arguments:
+  - name: card
+    description: Card reference (#42, UUID, or name)
+    required: true
+---
+
+${HARMONY_WORKFLOW_PROMPT.replace("$ARGUMENTS", "{{card}}").replace("Your agent identifier", "codex").replace("Your agent name", "OpenAI Codex")}
+`;
+            if (installMode === "global") {
+                // Global mode: Write prompt to central location, symlink to ~/.codex/prompts/
+                files.push({
+                    path: join(GLOBAL_SKILLS_DIR, "codex", "hmy.md"),
+                    content: promptContent,
+                    type: "text",
+                });
+                symlinks.push({
+                    target: join(GLOBAL_SKILLS_DIR, "codex", "hmy.md"),
+                    link: join(home, ".codex", "prompts", "hmy.md"),
+                });
+            }
+            else {
+                // Local mode: Write prompt directly to ~/.codex/prompts/
+                files.push({
+                    path: join(home, ".codex", "prompts", "hmy.md"),
+                    content: promptContent,
+                    type: "text",
+                });
+            }
+            // Codex config.toml (always global)
+            const tomlContent = `
+# Harmony MCP Server
+[mcp_servers.harmony]
+command = "npx"
+args = ["-y", "@gethmy/mcp@latest", "serve"]
+`;
+            files.push({
+                path: join(home, ".codex", "config.toml"),
+                content: tomlContent,
+                type: "toml",
+                tomlSection: "mcp_servers.harmony",
+            });
+            break;
+        }
+        case "cursor": {
+            // Cursor MCP config (always project-level)
+            files.push({
+                path: join(cwd, ".cursor", "mcp.json"),
+                content: JSON.stringify({
+                    mcpServers: {
+                        harmony: {
+                            command: "npx",
+                            args: ["-y", "@gethmy/mcp@latest", "serve"],
+                        },
+                    },
+                }, null, 2),
+                type: "json",
+            });
+            // Cursor rule file
+            const ruleContent = `---
+description: Harmony card workflow rule
+globs:
+  - "**/*"
+alwaysApply: false
+---
+
+# Harmony Integration
+
+When the user asks you to work on a Harmony card (references like #42, card names, or UUIDs):
+
+${HARMONY_WORKFLOW_PROMPT.replace("$ARGUMENTS", "the card reference").replace("Your agent identifier", "cursor").replace("Your agent name", "Cursor AI")}
+`;
+            if (installMode === "global") {
+                // Global mode: Write rule to central location, symlink to ~/.cursor/rules/
+                files.push({
+                    path: join(GLOBAL_SKILLS_DIR, "cursor", "harmony.mdc"),
+                    content: ruleContent,
+                    type: "text",
+                });
+                symlinks.push({
+                    target: join(GLOBAL_SKILLS_DIR, "cursor", "harmony.mdc"),
+                    link: join(home, ".cursor", "rules", "harmony.mdc"),
+                });
+            }
+            else {
+                // Local mode: Write rule directly to project directory
+                files.push({
+                    path: join(cwd, ".cursor", "rules", "harmony.mdc"),
+                    content: ruleContent,
+                    type: "text",
+                });
+            }
+            break;
+        }
+        case "windsurf": {
+            // Windsurf global MCP config (always global)
+            files.push({
+                path: join(home, ".codeium", "windsurf", "mcp_config.json"),
+                content: JSON.stringify({
+                    mcpServers: {
+                        harmony: {
+                            command: "npx",
+                            args: ["-y", "@gethmy/mcp@latest", "serve"],
+                            disabled: false,
+                            alwaysAllow: [],
+                        },
+                    },
+                }, null, 2),
+                type: "json",
+            });
+            // Windsurf rule file
+            const ruleContent = `---
+trigger: model_decision
+description: Activate when user asks to work on a Harmony card (references like #42, card names, or task management)
+---
+
+# Harmony Card Workflow
+
+When working on a Harmony card:
+
+${HARMONY_WORKFLOW_PROMPT.replace("$ARGUMENTS", "the card reference").replace("Your agent identifier", "windsurf").replace("Your agent name", "Windsurf AI")}
+`;
+            if (installMode === "global") {
+                // Global mode: Write rule to central location, symlink to ~/.codeium/windsurf/rules/
+                files.push({
+                    path: join(GLOBAL_SKILLS_DIR, "windsurf", "harmony.md"),
+                    content: ruleContent,
+                    type: "text",
+                });
+                symlinks.push({
+                    target: join(GLOBAL_SKILLS_DIR, "windsurf", "harmony.md"),
+                    link: join(home, ".codeium", "windsurf", "rules", "harmony.md"),
+                });
+            }
+            else {
+                // Local mode: Write rule directly to project directory
+                files.push({
+                    path: join(cwd, ".windsurf", "rules", "harmony.md"),
+                    content: ruleContent,
+                    type: "text",
+                });
+            }
+            break;
+        }
+    }
+    return { files, symlinks };
+}
+/**
+ * Main setup wizard with smart detection
+ */
+export async function runSetup(options = {}) {
+    const cwd = process.cwd();
+    const home = homedir();
+    console.clear();
+    console.log(messages.header());
+    // Check existing configuration
+    const existingConfig = loadConfig();
+    const alreadyConfigured = isConfigured();
+    const skillsStatus = areSkillsInstalled(cwd);
+    const hasContext = hasProjectContext(cwd);
+    // Track what we need to do
+    let needsApiKey = !alreadyConfigured;
+    let needsSkills = !skillsStatus.installed || options.force;
+    let needsContext = !hasContext && !options.skipContext;
+    // If workspace/project provided via flags, we'll set context
+    if (options.workspaceId || options.projectId) {
+        needsContext = true;
+    }
+    // Step 1: API Key
+    let apiKey = options.apiKey || existingConfig.apiKey;
+    let userEmail = options.userEmail || existingConfig.userEmail || undefined;
+    if (needsApiKey || !apiKey || !apiKey.startsWith("hmy_")) {
+        const keyInput = await p.text({
+            message: "Enter your Harmony API key",
+            placeholder: "hmy_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+            validate: (value) => {
+                if (!value)
+                    return "API key is required";
+                if (!value.startsWith("hmy_"))
+                    return 'API key must start with "hmy_"';
+                if (value.length < 20)
+                    return "API key is too short";
+                return undefined;
+            },
+        });
+        if (p.isCancel(keyInput)) {
+            p.cancel("Setup cancelled");
+            process.exit(0);
+        }
+        apiKey = keyInput;
+        needsApiKey = true;
+    }
+    else {
+        p.log.success(`Using existing API key: ${apiKey.slice(0, 8)}...`);
+    }
+    // Validate API key
+    const spinner = p.spinner();
+    spinner.start("Validating API key...");
+    const validation = await validateApiKey(apiKey);
+    if (!validation.valid) {
+        spinner.stop(colors.error("API key validation failed"));
+        p.log.error(validation.error || "Could not connect to Harmony API");
+        p.log.info("Get an API key at: https://gethmy.com/user/keys");
+        process.exit(1);
+    }
+    if (!userEmail) {
+        userEmail = validation.email;
+    }
+    spinner.stop(colors.success(userEmail ? `Connected as ${userEmail}` : "API key validated"));
+    // Step 2: Check if skills are already installed
+    let selectedAgents = [];
+    let installMode = options.installMode || "global";
+    if (skillsStatus.installed && !options.force) {
+        p.log.success(`Skills already installed (${skillsStatus.location})`);
+        const reinstall = await p.confirm({
+            message: "Reinstall skills?",
+            initialValue: false,
+        });
+        if (p.isCancel(reinstall)) {
+            p.cancel("Setup cancelled");
+            process.exit(0);
+        }
+        needsSkills = reinstall;
+    }
+    if (needsSkills) {
+        // Detect and select agents
+        const detectedAgents = detectAgents(cwd);
+        if (options.agents && options.agents.length > 0) {
+            selectedAgents = options.agents;
+        }
+        else {
+            const agentOptions = detectedAgents.map((agent) => ({
+                value: agent.id,
+                label: agent.name,
+                hint: agent.detected
+                    ? colors.success(`${agent.description} (detected)`)
+                    : colors.dim(`${agent.description}`),
+            }));
+            const agentSelection = await p.multiselect({
+                message: "Select agents to configure",
+                options: agentOptions,
+                initialValues: detectedAgents
+                    .filter((a) => a.detected)
+                    .map((a) => a.id),
+                required: true,
+            });
+            if (p.isCancel(agentSelection)) {
+                p.cancel("Setup cancelled");
+                process.exit(0);
+            }
+            selectedAgents = agentSelection;
+        }
+        if (selectedAgents.length === 0) {
+            p.log.warning("No agents selected. Skipping skills installation.");
+            needsSkills = false;
+        }
+        else if (!options.installMode) {
+            // Select install mode
+            const modeSelection = await p.select({
+                message: "Where should Harmony skills be installed?",
+                options: [
+                    {
+                        value: "global",
+                        label: "Global (shared) - Recommended",
+                        hint: "Skills in ~/.agents/skills/, available in all projects",
+                    },
+                    {
+                        value: "local",
+                        label: "Local (project directory)",
+                        hint: "Skills in .claude/skills/, committed to git",
+                    },
+                ],
+                initialValue: "global",
+            });
+            if (p.isCancel(modeSelection)) {
+                p.cancel("Setup cancelled");
+                process.exit(0);
+            }
+            installMode = modeSelection;
+        }
+    }
+    // Step 3: Workspace and Project Selection
+    let selectedWorkspaceId = options.workspaceId;
+    let selectedProjectId = options.projectId;
+    let selectedWorkspaceName;
+    let selectedProjectName;
+    if (needsContext && !options.skipContext) {
+        // Fetch workspaces
+        spinner.start("Fetching workspaces...");
+        let workspaces = [];
+        try {
+            workspaces = await fetchWorkspaces(apiKey);
+            spinner.stop(colors.success(`Found ${workspaces.length} workspace(s)`));
+        }
+        catch (_error) {
+            spinner.stop(colors.warning("Could not fetch workspaces"));
+            p.log.warning("Skipping workspace/project selection. You can set this later.");
+            needsContext = false;
+        }
+        if (needsContext && workspaces.length > 0) {
+            // Select workspace
+            if (!selectedWorkspaceId) {
+                const workspaceOptions = workspaces.map((ws) => ({
+                    value: ws.id,
+                    label: ws.name,
+                }));
+                const workspaceSelection = await p.select({
+                    message: "Select workspace",
+                    options: workspaceOptions,
+                });
+                if (p.isCancel(workspaceSelection)) {
+                    p.cancel("Setup cancelled");
+                    process.exit(0);
+                }
+                selectedWorkspaceId = workspaceSelection;
+            }
+            selectedWorkspaceName = workspaces.find((w) => w.id === selectedWorkspaceId)?.name;
+            // Fetch and select project
+            spinner.start("Fetching projects...");
+            let projects = [];
+            try {
+                projects = await fetchProjects(apiKey, selectedWorkspaceId);
+                spinner.stop(colors.success(`Found ${projects.length} project(s)`));
+            }
+            catch (_error) {
+                spinner.stop(colors.warning("Could not fetch projects"));
+                p.log.warning("Skipping project selection. You can set this later.");
+            }
+            if (projects.length > 0 && !selectedProjectId) {
+                const projectOptions = projects.map((proj) => ({
+                    value: proj.id,
+                    label: proj.name,
+                    hint: proj.description
+                        ? colors.dim(proj.description.slice(0, 50))
+                        : undefined,
+                }));
+                const projectSelection = await p.select({
+                    message: "Select project",
+                    options: projectOptions,
+                });
+                if (p.isCancel(projectSelection)) {
+                    p.cancel("Setup cancelled");
+                    process.exit(0);
+                }
+                selectedProjectId = projectSelection;
+                selectedProjectName = projects.find((p) => p.id === selectedProjectId)?.name;
+            }
+        }
+    }
+    // Step 4: Collect all files and symlinks to create
+    const allFiles = [];
+    const allSymlinks = [];
+    // Always save global config if we have an API key change
+    if (needsApiKey || !alreadyConfigured) {
+        allFiles.push({
+            path: getConfigPath(),
+            content: JSON.stringify({
+                apiKey,
+                apiUrl: API_URL,
+                userEmail: userEmail || null,
+                activeWorkspaceId: null,
+                activeProjectId: null,
+            }, null, 2),
+            type: "text", // Use text to avoid merging
+        });
+    }
+    // Project docs scaffold / verification
+    if (!options.skipDocs) {
+        const docsResult = await runDocsStep(cwd);
+        if (!docsResult.skipped) {
+            for (const file of docsResult.files) {
+                allFiles.push(file);
+            }
+        }
+    }
+    // Agent-specific files
+    if (needsSkills && selectedAgents.length > 0) {
+        for (const agentId of selectedAgents) {
+            const { files, symlinks } = getAgentFiles(agentId, cwd, installMode);
+            allFiles.push(...files);
+            allSymlinks.push(...symlinks);
+        }
+    }
+    // Step 5: Show summary
+    const detectedAgents = detectAgents(cwd);
+    console.log("");
+    p.log.step("Summary");
+    console.log("");
+    console.log(`  ${colors.bold("API Key:")} ${apiKey.slice(0, 8)}...`);
+    if (userEmail) {
+        console.log(`  ${colors.bold("Email:")} ${userEmail}`);
+    }
+    if (needsSkills && selectedAgents.length > 0) {
+        console.log(`  ${colors.bold("Agents:")} ${selectedAgents.map((a) => detectedAgents.find((d) => d.id === a)?.name).join(", ")}`);
+        console.log(`  ${colors.bold("Install:")} ${installMode === "global" ? "Global (~/.agents/skills/)" : "Local (project)"}`);
+    }
+    else {
+        console.log(`  ${colors.bold("Skills:")} Already installed (${skillsStatus.location || "none"})`);
+    }
+    if (selectedWorkspaceId) {
+        console.log(`  ${colors.bold("Workspace:")} ${selectedWorkspaceName || selectedWorkspaceId}`);
+    }
+    if (selectedProjectId) {
+        console.log(`  ${colors.bold("Project:")} ${selectedProjectName || selectedProjectId}`);
+    }
+    if (allFiles.length > 0) {
+        const summary = getWriteSummary(allFiles, { force: options.force });
+        if (summary.toCreate.length > 0) {
+            console.log("");
+            console.log(`  ${colors.success("Files to create:")}`);
+            for (const path of summary.toCreate) {
+                console.log(`    ${colors.dim("\u2022")} ${path}`);
+            }
+        }
+        if (allSymlinks.length > 0) {
+            console.log("");
+            console.log(`  ${colors.info("Symlinks to create:")}`);
+            for (const symlink of allSymlinks) {
+                console.log(`    ${colors.dim("\u{1F517}")} ${formatPath(symlink.link, home)} → ${formatPath(symlink.target, home)}`);
+            }
+        }
+        if (summary.toUpdate.length > 0) {
+            console.log("");
+            console.log(`  ${colors.info("Files to update:")}`);
+            for (const path of summary.toUpdate) {
+                console.log(`    ${colors.dim("\u2022")} ${path}`);
+            }
+        }
+        if (summary.toSkip.length > 0 && !options.force) {
+            console.log("");
+            console.log(`  ${colors.dim("Files to skip (already exist):")}`);
+            for (const path of summary.toSkip) {
+                console.log(`    ${colors.dim("\u2022")} ${path}`);
+            }
+        }
+    }
+    console.log("");
+    // Step 6: Confirm and execute
+    const shouldProceed = await p.confirm({
+        message: "Proceed with setup?",
+        initialValue: true,
+    });
+    if (p.isCancel(shouldProceed) || !shouldProceed) {
+        p.cancel("Setup cancelled");
+        process.exit(0);
+    }
+    console.log("");
+    // Step 7: Write files
+    if (allFiles.length > 0) {
+        await writeFilesWithProgress(allFiles, { force: options.force });
+    }
+    // Step 8: Create symlinks
+    if (allSymlinks.length > 0) {
+        for (const symlink of allSymlinks) {
+            try {
+                // Ensure parent directory exists
+                const linkDir = dirname(symlink.link);
+                if (!existsSync(linkDir)) {
+                    mkdirSync(linkDir, { recursive: true });
+                }
+                // Check if link already exists
+                let linkExists = false;
+                try {
+                    lstatSync(symlink.link);
+                    linkExists = true;
+                }
+                catch {
+                    // Link doesn't exist
+                }
+                if (linkExists) {
+                    if (options.force) {
+                        unlinkSync(symlink.link);
+                    }
+                    else {
+                        // Skip existing symlink
+                        continue;
+                    }
+                }
+                symlinkSync(symlink.target, symlink.link);
+            }
+            catch {
+                p.log.warning(`Failed to create symlink: ${symlink.link}`);
+            }
+        }
+    }
+    // Step 8b: Register MCP server for Claude (project-local scope)
+    const claudeDetected = detectAgents(cwd).some((a) => a.id === "claude" && a.detected);
+    if (claudeDetected || selectedAgents.includes("claude")) {
+        const mcpRegistered = await registerMcpServer();
+        if (mcpRegistered) {
+            console.log(`  ${colors.success("\u2713")} ${colors.dim("MCP server registered via claude CLI")}`);
+        }
+        else {
+            // Fallback: write directly to settings.json
+            try {
+                await writeMcpConfigFallback(home);
+                console.log(`  ${colors.success("\u2713")} ${colors.dim(formatPath(join(home, ".claude", "settings.json"), home))} ${colors.dim("(updated)")}`);
+            }
+            catch {
+                p.log.warning("Could not register MCP server. Run manually: claude mcp add --transport stdio harmony -- npx -y @gethmy/mcp@latest serve");
+            }
+        }
+    }
+    // Step 9: Save local context
+    if (selectedWorkspaceId || selectedProjectId) {
+        const localConfig = {};
+        if (selectedWorkspaceId)
+            localConfig.workspaceId = selectedWorkspaceId;
+        if (selectedProjectId)
+            localConfig.projectId = selectedProjectId;
+        saveLocalConfig(localConfig, cwd);
+        console.log(`  ${colors.success("\u2713")} ${colors.dim(formatPath(getLocalConfigPath(cwd), home))} ${colors.dim("(created)")}`);
+    }
+    // Step 10: Show completion message
+    console.log("");
+    p.outro(colors.success("Setup complete!"));
+    console.log("");
+    console.log(`  ${colors.bold("Configuration:")}`);
+    console.log(`    API key:   ${formatPath(getConfigPath(), home)}`);
+    if (needsSkills && selectedAgents.length > 0) {
+        console.log(`    Skills:    ${installMode === "global" ? "~/.agents/skills/ (global)" : ".claude/skills/ (local)"}`);
+    }
+    if (selectedWorkspaceId || selectedProjectId) {
+        console.log(`    Context:   ${formatPath(getLocalConfigPath(cwd), home)}`);
+    }
+    console.log("");
+    console.log(`  ${colors.bold("Usage:")}`);
+    if (!needsSkills || selectedAgents.includes("claude")) {
+        console.log(`    ${colors.brand("Claude Code:")} ${colors.highlight("/hmy #42")} or ${colors.highlight("/hmy-plan")} ${colors.dim("(create or execute plans)")}`);
+    }
+    if (selectedAgents.includes("codex")) {
+        console.log(`    ${colors.brand("Codex:")} ${colors.highlight("/prompts:hmy #42")}`);
+    }
+    if (selectedAgents.includes("cursor") ||
+        selectedAgents.includes("windsurf")) {
+        console.log(`    ${colors.brand("Cursor/Windsurf:")} MCP tools available automatically`);
+    }
+    console.log("");
+    console.log(`  ${colors.dim("Add to new project: npx @gethmy/mcp setup")}`);
+    console.log(`  ${colors.dim("Need help? Visit https://gethmy.com/docs/mcp")}`);
+    console.log("");
+}