@ezmodo/mcp-server 0.13.0

package/prompts/zephly-usage-guide-content.txt

@@ -0,0 +1,631 @@
+            type: 'text',
+            text: `# Zephly MCP Integration Guide
+
+You have access to Zephly's intelligent project management tools. Use them to help users with project planning, task management, and team coordination.
+
+## When to Use Zephly Tools
+
+**Proactively use these tools when:**
+- User mentions tasks, projects, sprints, or team coordination
+- User asks about project status, health, or blockers
+- User needs help prioritizing work or deciding what to work on next
+- User is planning team assignments or workload distribution
+- User is breaking down epics/features into tasks
+- User asks about project timelines or estimates
+- User mentions dependencies, blockers, or handoffs
+
+## Tool Categories
+
+### Project Context Management (4 tools) 🆕
+- \`detect_git_repository\` - Auto-detect git repo and match to Zephly projects by URL (with confidence scores)
+- \`get_current_project_context\` - Auto-detect which Zephly project from .zephly/config.json (walks up directory tree, includes validation)
+- \`initialize_project_context\` - Interactive setup to create .zephly/config.json (now with git auto-detection!)
+- \`search_projects\` - Search/filter projects by name, type, or organization
+
+**IMPORTANT**: Use these tools at the start of ANY work session to establish which Zephly project you're working on. This eliminates the need to pass projectId to every tool call.
+
+### Organization Discovery (3 tools)
+- \`list_organizations\` - List all workspaces the user has access to (use first when creating projects/goals)
+- \`get_default_organization\` - Get user's default/primary workspace (use as fallback)
+- \`list_projects\` - List all projects accessible to API key (with org info, git URLs, roles)
+
+### Basic Operations (7 tools)
+- \`create_task\` - Create tasks with AI context, metadata, and implementation steps
+- \`update_task\` - Update task properties, status, and manage steps (add/toggle/update/delete)
+- \`complete_task\` - Mark tasks completed with notes
+- \`get_project_context\` - Retrieve project memory/knowledge/config
+- \`add_task_context\` - Add knowledge/memory to tasks
+- \`search_tasks\` - **Semantic/vector search** with natural language queries OR filter-based search (automatically uses AI-powered similarity when searchText provided)
+- \`get_documentation\` - Retrieve project documentation
+
+### Intelligence Tools (4 tools)
+- \`get_project_insights\` - Comprehensive project health: blockers, at-risk tasks, velocity trends, team workload
+- \`suggest_next_actions\` - Personalized recommendations based on dependencies, deadlines, capacity
+- \`analyze_dependency_graph\` - Critical path analysis, bottleneck detection, parallel opportunities
+- \`estimate_task_duration\` - AI-powered estimates based on historical data
+
+### Team Coordination (6 tools)
+- \`analyze_team_capacity\` - Resource allocation and availability analysis
+- \`suggest_task_assignments\` - Smart task-to-person matching by skills and capacity
+- \`identify_handoff_needs\` - Detect blocked tasks grouped by blocker with urgency
+- \`bulk_task_operations\` - Atomic batch operations (create/update/delete multiple tasks)
+- \`apply_task_template\` - Reusable workflows with variable substitution (feature, bug, design)
+- \`pull_ai_task_from_queue\` - Get intelligent task queue for AI agents with auto-assignment (NEW)
+
+### Git Worktree Tools (5 tools) 🆕
+- \`create_epic_worktree\` - Create worktree for an entire epic (all tasks share one branch) ⭐ NEW
+- \`create_task_worktree\` - Create isolated git worktree for a task with automatic branch generation
+- \`sync_task_worktree_status\` - Sync git status to task (dirty, ahead/behind, conflicts)
+- \`cleanup_task_worktrees\` - Clean up worktrees for completed tasks (with dry-run mode)
+- \`list_project_worktrees\` - List all worktrees with task associations and status
+
+**What are worktrees?** Git worktrees allow multiple working directories for the same repository, enabling parallel development. Zephly supports two approaches:
+
+1. **Epic-Level Worktrees** (Recommended for related tasks): Create one worktree for an entire epic, allowing all tasks to share the same branch. Perfect for feature batches, dependent tasks, or work that should be in one PR.
+
+2. **Task-Level Worktrees**: Create separate worktrees for individual tasks (1:1:1 mapping: Task → Branch → Worktree).
+
+**Key benefits:**
+- Work on multiple tasks/epics simultaneously without branch switching
+- Each task has isolated workspace (no stashing needed)
+- Automatic branch naming from task/epic metadata
+- Team visibility into active development work
+- Clean context switching for AI agents and developers
+
+## Working with Task Steps
+
+Task steps are lightweight implementation checklists within tasks. Use them to break down work into concrete, actionable items.
+
+**Creating tasks with steps:**
+\`\`\`javascript
+create_task({
+  projectId: "abc123",
+  title: "Implement user authentication",
+  description: "Add OAuth2 login flow...",
+  steps: [
+    "Set up OAuth2 provider configuration",
+    "Create login UI components",
+    "Implement token validation middleware",
+    "Add session management",
+    "Write integration tests"
+  ]
+})
+\`\`\`
+
+**Managing steps:**
+- \`update_task({ taskId, addStep: "New step content" })\` - Add a new step
+- \`update_task({ taskId, toggleStep: { stepId: "xyz", completed: true } })\` - Mark step complete
+- \`update_task({ taskId, updateStepContent: { stepId: "xyz", content: "Updated text" } })\` - Edit step
+- \`update_task({ taskId, deleteStep: "xyz" })\` - Remove step
+
+**Best practices:**
+- Break tasks into 3-7 steps for optimal tracking
+- Use clear, action-oriented step descriptions
+- Mark steps complete as you progress for real-time visibility
+- Use steps for implementation details within a single task
+
+## Best Practices
+
+1. **🆕 Establish project context FIRST**: Call \`get_current_project_context\` at the start of every session. If not found, use \`initialize_project_context\` to set it up. This eliminates repetitive projectId parameters and enables git workflow integration.
+2. **Start with context**: After establishing which project, call \`get_project_context\` to understand project state (memory, knowledge, config)
+3. **Check health proactively**: Use \`get_project_insights\` to identify issues before planning
+4. **Estimate before creating**: Use \`estimate_task_duration\` when creating tasks to set realistic expectations
+5. **Check capacity before assigning**: Use \`analyze_team_capacity\` to avoid overloading team members
+6. **Batch related operations**: Use \`bulk_task_operations\` for efficiency when creating/updating multiple tasks
+7. **Use templates**: Apply \`apply_task_template\` for common workflows (features, bugs, design iterations)
+8. **Track dependencies**: Use \`analyze_dependency_graph\` to identify critical path and bottlenecks
+9. **🆕 Use worktrees for parallel development**: Choose epic-level (\`create_epic_worktree\`) for related tasks that should be in one PR, or task-level (\`create_task_worktree\`) for independent work. Epic worktrees are recommended when multiple tasks form a cohesive feature. Sync status with \`sync_task_worktree_status\` for team visibility.
+
+## 🤖 AI Workflow Automation (NEW!)
+
+**IMPORTANT:** When you (as an AI agent) are implementing features or working on complex tasks, **automatically track your work in Zephly in real-time**. Don't wait for users to ask you to update documentation or check off tasks.
+
+**When to Use Workflow Automation:**
+- User asks you to implement a feature (not just explain or plan)
+- Task involves multiple implementation steps (>3 steps)
+- Work needs team visibility or historical tracking
+- You're working in a codebase with \`.zephly/config.json\`
+
+**Workflow Steps:**
+1. **Create Epic** - Use \`create_epic\` to create the high-level feature container with success criteria
+2. **Break Down Tasks** - Create 3-7 tasks with \`create_task\`, each with implementation steps
+3. **Track Progress** - Update steps with \`update_task\` (toggle, add, modify) as you work
+4. **Update Status** - Move tasks through workflow: backlog → todo → in_progress → in_review → completed
+5. **Document** - Use \`create_document\` to create setup guides, API docs, or troubleshooting guides
+6. **Wrap Up** - Use \`update_epic\` to mark epic completed when all tasks are done
+
+**Example:**
+\`\`\`javascript
+// 1. Create epic
+const epic = await create_epic({
+  projectId: "abc123",
+  title: "User Authentication System",
+  successCriteria: ["Users can sign up", "Sessions persist", "Admin roles work"]
+})
+
+// 2. Create tasks with steps
+await create_task({
+  epicId: epic.id,
+  title: "Implement OAuth2 backend",
+  steps: ["Set up OAuth2 config", "JWT generation", "Validation middleware", "Tests"],
+  assigneeType: "ai",
+  assigneeId: "claude"
+})
+
+// 3. Track progress
+await update_task({ taskId: "task1", status: "in_progress" })
+await update_task({ taskId: "task1", toggleStep: { stepId: "step1", completed: true } })
+
+// 4. Document
+await create_document({
+  projectId: "abc123",
+  title: "Authentication Setup Guide",
+  content: "# How to configure OAuth2...",
+  type: "setup"
+})
+
+// 5. Complete
+await complete_task({ taskId: "task1", completionNotes: "OAuth2 implementation complete" })
+await update_epic({ epicId: epic.id, status: "completed" })
+\`\`\`
+
+**See the \`ai-workflow-automation\` prompt for complete guidelines** (use "Invoke prompt: ai-workflow-automation" in Claude Desktop).
+
+**Benefits:**
+- Real-time visibility for users (no "black box" AI work)
+- Historical record of decisions and implementation details
+- Documentation created alongside code
+- Competitive advantage: "The only PM tool where AI agents manage their own project tracking"
+
+## Example Workflows
+
+### Setting Up Project Context (FIRST THING TO DO!)
+When starting work in any directory, establish project context FIRST:
+
+**Step 1: Check if context exists**
+\`\`\`javascript
+const context = await get_current_project_context()
+
+if (context.found) {
+  // ✅ Context found! Use it
+  console.log(\`Working on: \${context.projectName} (\${context.projectId})\`)
+  // Now you can use context.projectId in all subsequent calls
+} else {
+  // ❌ No context - need to initialize
+  await initialize_project_context() // Interactive mode
+}
+\`\`\`
+
+**Step 2a: Interactive initialization (recommended)**
+\`\`\`javascript
+// Call without params - tool returns available projects
+const result = await initialize_project_context()
+// Returns: { mode: 'interactive', organizations: [...] }
+
+// Present options to user, then call again with selection:
+await initialize_project_context({
+  projectId: 'selected-project-id',
+  organizationId: 'selected-org-id'
+})
+// Creates .zephly/config.json automatically
+\`\`\`
+
+**Step 2b: Automated initialization (if you know the IDs)**
+\`\`\`javascript
+await initialize_project_context({
+  projectId: 'abc123',
+  organizationId: 'org456'
+})
+// ✅ Creates .zephly/config.json
+// ✅ Updates .gitignore
+\`\`\`
+
+**Step 3: Monorepo support**
+\`\`\`javascript
+await initialize_project_context({
+  projectId: 'monorepo-root-id',
+  organizationId: 'org456',
+  monorepoProjects: [
+    { projectId: 'backend-id', name: 'Backend API', path: 'packages/api' },
+    { projectId: 'frontend-id', name: 'Frontend', path: 'packages/web' }
+  ]
+})
+
+// Later, when you cd into packages/api, get_current_project_context
+// will automatically return backend-id!
+\`\`\`
+
+**Why this matters:**
+- Eliminates repetitive projectId parameters
+- Survives git operations (committed or gitignored)
+- Works offline (no API calls needed to know context)
+- AI task queue can use this for git clone workflows
+
+### Git Repository Auto-Detection (NEW!)
+When working in a git repository, automatically match to Zephly projects:
+
+\`\`\`javascript
+// 1. Detect git and match to projects
+const gitInfo = await detect_git_repository()
+
+if (gitInfo.matchCount > 0) {
+  // High confidence match found!
+  const bestMatch = gitInfo.matches[0]
+  console.log(\`Found match: \${bestMatch.project.name} (confidence: \${bestMatch.confidence})\`)
+
+  // Use it to initialize context
+  await initialize_project_context({
+    projectId: bestMatch.project.id,
+    organizationId: bestMatch.project.organizationId
+  })
+} else if (gitInfo.isGitRepository) {
+  // Git repo but no matches - ask user to select
+  console.log(\`Git repo detected: \${gitInfo.remoteUrl}\`)
+  console.log(\`No matching projects found. Please select one.\`)
+}
+\`\`\`
+
+**How URL Matching Works:**
+- **Exact match (1.0)**: URLs are identical (ignoring protocol/trailing slashes)
+- **High confidence (0.95)**: Same repository, different protocol (https vs git@)
+- **Medium confidence (0.5)**: Same repository name
+- **Low confidence (<0.5)**: Not shown
+
+**Supported URL formats:**
+- \`https://github.com/user/repo.git\`
+- \`git@github.com:user/repo.git\`
+- \`https://gitlab.com/user/repo\`
+- Any git hosting service
+
+### Choosing a Workspace (Organization Selection)
+When a user wants to create a project or goal without specifying which workspace:
+1. \`list_organizations\` - Get all available workspaces
+2. Present options to user: "Which workspace? 1) Acme Corp, 2) Personal, 3) Startup Inc"
+3. User selects one → use that \`organizationId\`
+4. If user has only one org, skip to step 4 directly
+5. Alternative: \`get_default_organization\` - Use default if user doesn't want to choose
+
+**Example:**
+\`\`\`javascript
+// User: "Create a new project called Marketing Campaign"
+const orgs = await list_organizations()
+// Returns: [
+//   { id: "org1", name: "Acme Corp", slug: "acme", type: "team" },
+//   { id: "org2", name: "Personal Workspace", slug: "personal", type: "individual" }
+// ]
+
+// Present to user: "Which workspace? 1) Acme Corp, 2) Personal Workspace"
+// User selects: "Acme Corp"
+const organizationId = "org1"
+
+// Now create the project
+await create_project({
+  organizationId,
+  name: "Marketing Campaign",
+  description: "Q2 marketing push"
+})
+\`\`\`
+
+### Starting a New Feature
+1. \`get_project_context\` - Understand current project state
+2. \`get_project_insights\` - Check for existing blockers
+3. \`estimate_task_duration\` - Estimate the feature work
+4. \`apply_task_template\` - Use "feature" template (specs → dev → test → docs)
+5. \`analyze_team_capacity\` - Check team bandwidth
+6. \`suggest_task_assignments\` - Assign to right people
+
+### Daily Standup / Status Check
+1. \`get_project_insights\` - Get health score, blockers, velocity
+2. \`identify_handoff_needs\` - Find what's blocking what
+3. \`suggest_next_actions\` - Prioritized work queue for each team member
+4. \`analyze_team_capacity\` - Check for overallocation
+
+### Sprint Planning
+1. \`get_project_context\` - Review project goals and context
+2. \`analyze_dependency_graph\` - Understand task dependencies
+3. \`analyze_team_capacity\` - Check available capacity
+4. \`estimate_task_duration\` - Estimate new tasks
+5. \`suggest_task_assignments\` - Match tasks to team members
+6. \`bulk_task_operations\` - Create sprint tasks in batch
+
+### Breaking Down an Epic
+1. \`get_project_context\` - Understand project architecture
+2. \`estimate_task_duration\` - Estimate each task
+3. \`apply_task_template\` - Use templates for common patterns
+4. \`bulk_task_operations\` - Create all tasks with dependencies
+5. \`analyze_dependency_graph\` - Verify dependency structure
+
+### AI Agent Task Queue (NEW!)
+When you (as an AI agent) need to find work:
+1. \`pull_ai_task_from_queue\` - Get prioritized queue (no selection)
+   - Shows unassigned tasks + tasks already assigned to AI agents
+   - Intelligent scoring: urgency (40%) + importance (40%) + status (20%)
+   - Filters: priority, status, labels
+2. Review the queue and select the highest-priority task that matches your capabilities
+3. \`pull_ai_task_from_queue\` - Auto-assign by passing \`selectTaskId\`
+4. Work on the task and update status as you progress
+5. \`complete_task\` - Mark done when finished
+
+**Example:**
+\`\`\`javascript
+// 1. Get queue (browse available work)
+const queue = await pull_ai_task_from_queue({
+  projectId: "proj123",
+  agentId: "claude",
+  agentName: "Claude",
+  priority: "high", // Optional: filter to high priority only
+  status: "todo", // Optional: filter to ready-to-start tasks
+  limit: 10
+})
+// Returns: { tasks: [{taskId, title, score, reason, ...}, ...], queueSize: 10 }
+
+// 2. Select and claim a task
+const claimed = await pull_ai_task_from_queue({
+  projectId: "proj123",
+  agentId: "claude",
+  agentName: "Claude",
+  selectTaskId: "task456" // Auto-assigns to you
+})
+// Returns: { task: {...full task details...}, assigned: true }
+
+// 3. If git context included, clone repo
+if (claimed.gitContext) {
+  // Git context automatically included if project has gitRepositoryUrl!
+  console.log(\`Clone: \${claimed.gitContext.cloneCommand}\`)
+  console.log(\`Checkout: \${claimed.gitContext.checkoutCommand}\`)
+}
+
+// 4. Work on it, then complete
+await complete_task({ taskId: "task456", notes: "Implemented feature X" })
+\`\`\`
+
+**Git Context in Task Assignment:**
+When a task is assigned, if the project has a \`gitRepositoryUrl\` configured, the response automatically includes:
+\`\`\`javascript
+{
+  task: {...},
+  gitContext: {
+    repository: "https://github.com/user/repo.git",
+    branch: "main",
+    cloneCommand: "git clone https://github.com/user/repo.git",
+    checkoutCommand: "git checkout main"
+  }
+}
+\`\`\`
+
+**Smart Scoring Explained:**
+- **Urgency (40%)**: Overdue tasks = 1.0, due today = 0.9, due in 3 days = 0.75, etc.
+- **Importance (40%)**: Based on task priority + how many other tasks it blocks
+- **Status (20%)**: Unassigned > assigned to you > assigned to other AI agents
+
+**Use Cases:**
+- Autonomous AI agents running on cron jobs
+- AI pair programming sessions ("What should I work on next?")
+- AI agents specializing in certain types of work (frontend vs backend)
+
+### Working with Git Worktrees (NEW!)
+Enable parallel development by creating isolated workspaces for tasks or epics.
+
+**Choose Your Approach:**
+- **Epic-Level**: Multiple related tasks share one worktree/branch (one PR for entire feature)
+- **Task-Level**: Each task gets its own isolated worktree/branch (separate PRs)
+
+---
+
+**Option A: Epic-Level Worktrees (Recommended for Related Tasks)**
+
+**Step 1: Create epic worktree**
+\`\`\`javascript
+// Create worktree for entire epic
+const worktree = await create_epic_worktree({
+  epicId: "epic123",
+  baseBranch: "develop", // optional
+  updateTasks: true // Updates all tasks in epic to reference this branch
+})
+
+// Result:
+// {
+//   success: true,
+//   worktreePath: "/Users/dev/worktrees/epic-123",
+//   branchName: "feature/epic-123-user-authentication",
+//   baseBranch: "develop",
+//   baseCommit: "abc123...",
+//   updatedTaskCount: 5 // All 5 tasks now reference this branch
+// }
+
+// Navigate to worktree and work on any task in the epic
+console.log(\`cd \${worktree.worktreePath}\`)
+\`\`\`
+
+**Step 2: Work on tasks within the epic**
+All tasks in the epic share the same worktree and branch. You can work on them together, commit incrementally, and create one PR for the entire feature.
+
+**Step 3: Sync status**
+\`\`\`javascript
+// Sync status at epic level (updates all tasks)
+const status = await sync_task_worktree_status({
+  taskId: "any-task-in-epic" // Status syncs to epic branch
+})
+\`\`\`
+
+**Benefits:**
+- ✅ Single PR for related work
+- ✅ Test tasks together (dependencies)
+- ✅ Fewer context switches
+- ✅ Natural grouping by epic
+
+---
+
+**Option B: Task-Level Worktrees (For Independent Tasks)**
+
+**Step 1: Create a worktree when starting a task**
+\`\`\`javascript
+// Get task details (by task number - preferred)
+const task = await get_task({
+  taskNumber: 42,
+  projectId: "project123"
+})
+
+// Or by document ID (backward compatible)
+// const task = await get_task({ taskId: "task123" })
+
+// Create worktree with automatic branch generation
+const worktree = await create_task_worktree({
+  taskId: task.id,
+  // Optional: specify custom paths/branches
+  baseBranch: "develop", // defaults to project.gitContext.defaultBranch
+  worktreePath: "../worktrees/task123" // defaults to project setting
+})
+
+// Result:
+// {
+//   success: true,
+//   worktreePath: "/Users/dev/worktrees/task123",
+//   branchName: "feature/task123-add-user-auth",
+//   baseBranch: "develop",
+//   baseCommit: "abc123..."
+// }
+
+// Now navigate to worktree and start coding
+console.log(\`cd \${worktree.worktreePath}\`)
+\`\`\`
+
+**Step 2: Sync status as you work**
+\`\`\`javascript
+// After making changes, sync status to Firestore
+const status = await sync_task_worktree_status({
+  taskId: "task123"
+})
+
+// Result shows current state:
+// {
+//   isDirty: true, // Has uncommitted changes
+//   aheadBy: 2, // 2 commits ahead of base branch
+//   behindBy: 0, // Up to date with base
+//   hasConflicts: false,
+//   files: [
+//     { status: "M ", file: "src/auth.ts" },
+//     { status: "??", file: "src/auth.test.ts" }
+//   ]
+// }
+
+// This updates task.gitContext for team visibility
+\`\`\`
+
+**Step 3: Clean up when done**
+\`\`\`javascript
+// After completing task, clean up worktree
+const cleanup = await cleanup_task_worktrees({
+  projectId: "proj123",
+  taskIds: ["task123"],
+  deleteBranches: true, // Also delete branch if merged
+  dryRun: false
+})
+
+// Result:
+// {
+//   cleaned: 1,
+//   results: [{
+//     taskId: "task123",
+//     action: "removed",
+//     worktreePath: "/Users/dev/worktrees/task123",
+//     branchAction: "deleted",
+//     reason: "Branch was merged"
+//   }]
+// }
+\`\`\`
+
+**Step 4: List all worktrees (team visibility)**
+\`\`\`javascript
+// See all active worktrees for a project
+const worktrees = await list_project_worktrees({
+  projectId: "proj123"
+})
+
+// Result shows active development:
+// {
+//   worktrees: [
+//     {
+//       path: "/Users/alice/worktrees/task123",
+//       branch: "feature/task123-add-auth",
+//       taskId: "task123",
+//       taskTitle: "Add user authentication",
+//       taskStatus: "in_progress",
+//       assignee: { type: "human", name: "Alice" },
+//       isDirty: true,
+//       aheadBy: 3,
+//       behindBy: 0
+//     },
+//     {
+//       path: "/Users/bob/worktrees/task456",
+//       branch: "fix/task456-memory-leak",
+//       taskId: "task456",
+//       taskTitle: "Fix memory leak",
+//       taskStatus: "in_review",
+//       assignee: { type: "human", name: "Bob" },
+//       isDirty: false,
+//       aheadBy: 5,
+//       behindBy: 1
+//     }
+//   ],
+//   totalCount: 2,
+//   orphanedCount: 0
+// }
+\`\`\`
+
+**Workflow Benefits:**
+- **Context switching**: Jump between tasks without losing work
+- **Parallel development**: Work on multiple features simultaneously
+- **Team coordination**: See what everyone is working on
+- **AI-friendly**: Clean workspace boundaries for AI agents
+- **Automatic cleanup**: No stale branches accumulating
+
+**Branch Naming Conventions:**
+
+**Epic Branches:**
+- \`feature/epic-{epic-id}-{title}\` - All epic branches use 'feature' prefix
+- Example: \`feature/epic-123-user-authentication-system\`
+
+**Task Branches:**
+- \`feature/{task-id}-{title}\` - For new features
+- \`fix/{task-id}-{title}\` - For bug fixes
+- \`refactor/{task-id}-{title}\` - For refactoring
+- \`docs/{task-id}-{title}\` - For documentation
+- Example: \`feature/ZEP-123-add-login-page\`
+
+## Tips for AI Assistants
+
+- **Discover workspaces first**: When creating projects/goals, always call \`list_organizations\` first and let the user choose which workspace to use. Don't assume!
+- **Handle single organization gracefully**: If user has only one org, use it directly without prompting
+- **Be proactive**: Don't wait for users to ask about Zephly - suggest using these tools when relevant
+- **Explain insights**: When showing project insights, interpret the data (e.g., "Your velocity is declining - this suggests...")
+- **Provide context**: When suggesting actions, explain the reasoning (dependencies, deadlines, capacity)
+- **Batch operations**: When creating multiple related tasks, use \`bulk_task_operations\` for atomicity
+- **Follow up**: After creating tasks, offer to analyze dependencies or suggest assignments
+- **Track context**: Use \`add_task_context\` to maintain AI memory across sessions
+- **Use worktrees for parallel work**: When starting work on an epic, use \`create_epic_worktree\` to create a shared workspace for all related tasks (recommended for features). For independent tasks, use \`create_task_worktree\`. Sync status periodically with \`sync_task_worktree_status\` for team visibility. Clean up with \`cleanup_task_worktrees\` when done.
+
+## Authentication & Access Control
+
+All tools require a valid Zephly API key (set in ZEPHLY_API_KEY environment variable).
+
+**API Key Workspace Permissions:**
+- Each API key can be restricted to specific workspaces (organizations) or granted access to all workspaces
+- When creating an API key at https://zephly.app/settings/api-keys, you specify which workspaces it can access
+- API keys with "all workspaces" access work in any workspace the user is an active member of (including future workspaces)
+- API keys with specific workspace restrictions only work in those designated workspaces
+- All MCP functions automatically validate both API key permissions AND active workspace membership
+
+**Access Control Flow:**
+1. API key is validated
+2. Workspace/project access is checked based on API key permissions
+3. User's active membership in the workspace is verified
+4. Operation proceeds only if all checks pass
+
+**Error Messages:**
+- "API key does not have access to workspace..." - API key lacks permission for that workspace
+- "User is not an active member of workspace..." - User membership was revoked
+- "Project not found" - Project doesn't exist or belongs to inaccessible workspace
+
+This dual-layer security ensures that even with a valid API key, access requires both explicit key permissions and active workspace membership.`,
+          },