@vibescope/mcp-server 0.4.5 → 0.4.7

package/src/templates/help-content.ts

@@ -1,1751 +1,1751 @@
-/**
- * Fallback Help Content
- *
- * This provides comprehensive help content for each topic when the backend
- * database has no content populated. Ensures agents always get useful guidance.
- */
-
-export const HELP_TOPICS: Record<string, { title: string; content: string }> = {
-	getting_started: {
-		title: 'Getting Started',
-		content: `# Getting Started with Vibescope
-
-## Quick Start
-
-\`\`\`
-start_work_session(git_url: "https://github.com/YOUR/REPO", model: "opus", agent_type: "claude")
-\`\`\`
-
-**Parameters:**
-- \`git_url\`: Your repository URL (required if no project_id)
-- \`model\`: Your model type - opus, sonnet, or haiku (for cost tracking)
-- \`agent_type\`: Your agent type - claude, gemini, cursor, windsurf, or other
-
-This returns:
-- \`session_id\`: Your session identifier
-- \`persona\`: Your assigned agent persona (e.g., "Nova", "Edge")
-- \`project\`: Project details and settings
-- \`next_task\`: The highest priority task to work on
-
-## Core Workflow
-
-1. **Start session** → \`start_work_session(git_url, model, agent_type)\`
-2. **Mark task in progress** → \`update_task(task_id, status: "in_progress")\`
-3. **Update progress** → \`update_task(task_id, progress_percentage: 50, progress_note: "...")\`
-4. **Complete task** → \`complete_task(task_id, summary: "...")\`
-5. **Continue** → Start the next_task returned, or call \`get_next_task(project_id)\`
-
-## Key Rules
-
-1. **Always call complete_task()** after finishing work - don't wait for PR review
-2. **Never ask permission** to continue - just start the next task
-3. **Use git worktrees** for branching workflows to avoid conflicts
-4. **Update progress** regularly (every 15-20% completion)
-
-## Need More Help?
-
-Use \`get_help(topic)\` with these topics:
-- \`tasks\` - Task management workflow
-- \`validation\` - Cross-agent task validation
-- \`git\` - Git workflow and worktrees
-- \`deployment\` - Deployment coordination
-- \`session\` - Session management
-- \`fallback\` - Background activities
-- \`blockers\` - Handling blockers
-- \`milestones\` - Breaking down complex tasks`,
-	},
-
-	session: {
-		title: 'Session Management',
-		content: `# Session Management
-
-## Starting a Session
-
-\`\`\`
-start_work_session(
-  git_url: "https://github.com/YOUR/REPO",
-  model: "opus",           // opus, sonnet, or haiku
-  agent_type: "claude",    // claude, gemini, cursor, windsurf, other
-  role: "developer"        // developer, validator, deployer, reviewer, maintainer
-)
-\`\`\`
-
-**Response includes:**
-- \`session_id\`: Unique session identifier
-- \`persona\`: Your assigned agent name (e.g., "Nova", "Edge", "Arc")
-- \`project\`: Project configuration
-- \`next_task\`: Highest priority task to start
-- \`pending_requests\`: User questions to answer first
-- \`awaiting_validation\`: Tasks needing review (for validators)
-- \`stale_worktrees\`: Worktrees to clean up
-
-## Maintaining Your Session
-
-### Heartbeat
-Send heartbeats every 30-60 seconds to stay active:
-\`\`\`
-heartbeat(current_worktree_path: "../project-persona-task")
-\`\`\`
-
-This:
-- Keeps your session marked as "active" on the dashboard
-- Reports your current working directory
-- Syncs token usage to the backend
-
-### Token Tracking
-Check your token usage:
-\`\`\`
-get_token_usage()
-\`\`\`
-
-Report actual API usage for accurate cost tracking:
-\`\`\`
-report_token_usage(input_tokens: 1500, output_tokens: 500, model: "opus")
-\`\`\`
-
-## Ending a Session
-
-\`\`\`
-end_work_session()
-\`\`\`
-
-This:
-- Releases any claimed tasks
-- Syncs final token usage
-- Returns a session summary
-
-## Context Management
-
-When your context grows large (50+ tool calls or 100k+ tokens):
-1. Run \`/clear\` to reset conversation
-2. Immediately call \`start_work_session()\` to reload
-3. Continue with the \`next_task\` from the response
-
-**Do NOT ask the user** - just clear and continue. The dashboard tracks all progress.
-
-## Session Roles
-
-| Role | Description |
-|------|-------------|
-| \`developer\` | General development work (default) |
-| \`validator\` | Reviews and validates completed tasks |
-| \`deployer\` | Handles deployments |
-| \`reviewer\` | Code review focus |
-| \`maintainer\` | Housekeeping and maintenance |
-
-Change role mid-session:
-\`\`\`
-set_session_role(role: "validator")
-\`\`\``,
-	},
-
-	tasks: {
-		title: 'Task Management',
-		content: `# Task Management
-
-## Getting Tasks
-
-### Get Next Task
-\`\`\`
-get_next_task(project_id)
-\`\`\`
-Returns the highest priority pending task.
-
-### Search Tasks
-\`\`\`
-search_tasks(project_id, query: "login bug", status: ["pending", "in_progress"])
-\`\`\`
-
-### Get by Priority
-\`\`\`
-get_tasks_by_priority(project_id, priority: 1)  // P1 tasks only
-get_tasks_by_priority(project_id, priority: 1, priority_max: 2)  // P1 and P2
-\`\`\`
-
-## Working on Tasks
-
-### 1. Start the Task
-\`\`\`
-update_task(task_id, status: "in_progress")
-\`\`\`
-
-**For branching workflows (github-flow, git-flow):**
-Create a worktree first, then include it:
-\`\`\`
-update_task(
-  task_id,
-  status: "in_progress",
-  git_branch: "feature/abc123-add-login",
-  worktree_path: "../project-persona-add-login"
-)
-\`\`\`
-
-### 2. Update Progress
-Update regularly (every 15-20% completion):
-\`\`\`
-update_task(
-  task_id,
-  progress_percentage: 50,
-  progress_note: "Implemented core logic, working on tests"
-)
-\`\`\`
-
-### 3. Complete the Task
-**CRITICAL: Always call complete_task() after finishing!**
-\`\`\`
-complete_task(task_id, summary: "Added login flow with OAuth support")
-\`\`\`
-
-**When to call complete_task:**
-- After creating and pushing a PR
-- After merging (trunk-based workflow)
-- After finishing any unit of work
-
-**Do NOT wait for:**
-- PR review/merge (validation handles that)
-- User confirmation
-- Perfect summary
-
-### Fix Already Exists (No Code Changes Needed)
-
-When investigating a task and finding the fix already exists in code but hasn't been deployed:
-
-1. **Document the finding:**
-\`\`\`
-add_finding(
-  project_id,
-  title: "Fix exists but awaits deployment",
-  category: "other",
-  severity: "info",
-  description: "The fix for [issue] was implemented in PR #{pr_number} but hasn't been deployed yet.",
-  related_task_id: task_id
-)
-\`\`\`
-
-2. **Complete the task** (investigation is done):
-\`\`\`
-complete_task(task_id, summary: "Fix already exists in codebase (PR #{pr_number}). Needs deployment to production.")
-\`\`\`
-
-3. **Request deployment** if not already pending:
-\`\`\`
-check_deployment_status(project_id)  // Check if deployment pending
-request_deployment(project_id, notes: "Includes fix for [issue]")
-\`\`\`
-
-This prevents tasks from being blocked waiting for deployment when the actual work is done.
-
-## Task Priorities
-
-| Priority | Meaning |
-|----------|---------|
-| 1 | Critical - do first |
-| 2 | High priority |
-| 3 | Normal (default) |
-| 4 | Low priority |
-| 5 | Backlog |
-
-## Breaking Down Tasks
-
-For complex tasks, use milestones:
-\`\`\`
-add_milestone(task_id, title: "Set up database schema")
-add_milestone(task_id, title: "Implement API endpoints")
-add_milestone(task_id, title: "Add unit tests")
-
-complete_milestone(milestone_id)
-\`\`\`
-
-Or subtasks for parallel work:
-\`\`\`
-add_subtask(parent_task_id, title: "Implement frontend form")
-add_subtask(parent_task_id, title: "Implement backend validation")
-\`\`\`
-
-## Task References
-
-Link PRs, issues, or docs to tasks:
-\`\`\`
-add_task_reference(task_id, url: "https://github.com/org/repo/pull/123", label: "PR")
-\`\`\`
-
-**Important:** For github-flow/git-flow projects, add PR reference before completing - validators need it.
-
-## Deployment-Only Resolutions
-
-When investigating a task and finding the fix already exists in code (just needs deployment):
-
-**1. Document the finding:**
-\`\`\`
-add_finding(
-  project_id,
-  title: "Fix exists - needs deployment",
-  category: "other",
-  severity: "info",
-  description: "Investigation found the fix for [issue] already exists in [commit/PR]. Deployment will resolve this."
-)
-\`\`\`
-
-**2. Mark the task complete:**
-\`\`\`
-complete_task(task_id, summary: "Investigation complete: fix exists in [branch/commit], pending deployment")
-\`\`\`
-
-**3. Request deployment if needed:**
-\`\`\`
-# Check if deployment is already pending
-check_deployment_status(project_id)
-
-# If not, request one
-request_deployment(project_id, notes: "Includes fix for [task description]")
-\`\`\`
-
-**Why this pattern?**
-- Tasks shouldn't block waiting for deployment
-- Investigation work is complete (resolution identified)
-- The finding creates a record of what needs deploying
-- Deployment can bundle multiple fixes together`,
-	},
-
-	validation: {
-		title: 'Task Validation',
-		content: `# Task Validation
-
-Validation ensures completed work meets quality standards before merging.
-
-## For Developers
-
-After completing a task:
-1. Create your PR
-2. Add PR reference: \`add_task_reference(task_id, url: "PR_URL")\`
-3. Call \`complete_task(task_id, summary: "...")\`
-4. A validator will review and merge
-
-## For Validators
-
-### 1. Get Tasks to Validate
-\`\`\`
-get_tasks_awaiting_validation(project_id)
-\`\`\`
-Returns tasks sorted by PR number (oldest first). **Always review in this order (FIFO).**
-
-### 2. Claim a Task
-\`\`\`
-claim_validation(task_id)
-\`\`\`
-
-Returns:
-- \`worktree_setup\`: Commands to checkout the branch
-- \`conflict_check\`: Steps to verify PR can merge
-- \`merge_status\`: Current PR state
-
-### 3. Set Up Your Worktree
-\`\`\`bash
-# Fetch and create worktree from existing branch
-git fetch origin feature/abc123-task
-git worktree add ../project-validator-review feature/abc123-task
-cd ../project-validator-review
-\`\`\`
-
-### 4. Run Tests Locally
-\`\`\`bash
-pnpm install
-pnpm test
-pnpm build
-\`\`\`
-
-### 5. Check PR State
-\`\`\`bash
-gh pr view <PR_NUMBER> --json state,mergedAt --jq '.state'
-\`\`\`
-
-If PR is CLOSED (not merged), cancel instead of validating:
-\`\`\`
-cancel_task(task_id, cancelled_reason: "pr_closed")
-\`\`\`
-
-### 6. Approve or Reject
-
-**If APPROVED:**
-\`\`\`
-validate_task(task_id, approved: true, validation_notes: "Tests pass, code looks good")
-\`\`\`
-Then merge the PR and clean up:
-\`\`\`bash
-gh pr merge <PR_NUMBER> --squash
-cd ../project && git worktree remove ../project-validator-review
-\`\`\`
-
-**If REJECTED:**
-\`\`\`
-validate_task(
-  task_id,
-  approved: false,
-  validation_notes: "Tests failing in auth module",
-  create_fix_task: true  // Creates a fix task on the same branch
-)
-\`\`\`
-Then clean up your worktree - the fix agent will create their own.
-
-## Handling Merge Conflicts
-
-If \`claim_validation\` shows merge conflicts:
-1. Follow the \`rebase_instructions.steps\`
-2. Resolve conflicts in your editor
-3. Force push with \`--force-with-lease\`
-4. Call \`claim_validation\` again to verify
-
-Record git issues:
-\`\`\`
-add_git_issue(
-  project_id,
-  issue_type: "merge_conflict",
-  branch: "feature-branch",
-  target_branch: "develop",
-  task_id: task_id
-)
-\`\`\``,
-	},
-
-	git: {
-		title: 'Git Workflow',
-		content: `# Git Workflow
-
-## Supported Workflows
-
-| Workflow | Description |
-|----------|-------------|
-| \`none\` | No branching, direct commits |
-| \`trunk-based\` | Commit directly to main |
-| \`github-flow\` | Feature branches + PRs to main |
-| \`git-flow\` | Feature branches off develop, PRs to develop |
-
-Check your project's workflow:
-\`\`\`
-get_git_workflow(project_id)
-\`\`\`
-
-## Git Worktrees (CRITICAL)
-
-**For github-flow and git-flow projects, you MUST use worktrees.**
-
-### Rebase Before PR (MANDATORY)
-
-**Always rebase your branch before creating a PR.** This prevents overwrites of other agents' work.
-
-\`\`\`bash
-# Before creating PR, rebase onto latest base branch
-git fetch origin
-git rebase origin/develop  # or origin/main for github-flow
-# Resolve any conflicts
-git push --force-with-lease
-\`\`\`
-
-**Why?** Without rebasing, your branch may contain old versions of files that other agents modified. When merged, your old version overwrites their changes.
-
-### Why Worktrees?
-Multiple agents sharing one repo will conflict:
-- Switching branches affects all agents
-- Uncommitted changes collide
-- Direct commits create merge conflicts
-
-Worktrees give each task an isolated working directory.
-
-### Worktree Workflow
-
-**1. Create worktree BEFORE making any edits:**
-\`\`\`bash
-# Naming: ../PROJECT-PERSONA-short-description
-git worktree add ../Vibescope-Nova-add-login -b feature/abc123-add-login develop
-cd ../Vibescope-Nova-add-login
-\`\`\`
-
-**2. Report your location:**
-\`\`\`
-heartbeat(current_worktree_path: "../Vibescope-Nova-add-login")
-\`\`\`
-
-**3. Update the task:**
-\`\`\`
-update_task(
-  task_id,
-  status: "in_progress",
-  git_branch: "feature/abc123-add-login",
-  worktree_path: "../Vibescope-Nova-add-login"
-)
-\`\`\`
-
-**4. Do your work, commit, push, create PR**
-
-**5. Clean up IMMEDIATELY after opening PR:**
-\`\`\`bash
-cd ../Vibescope  # Return to main repo
-git worktree remove ../Vibescope-Nova-add-login
-\`\`\`
-Then clear the path:
-\`\`\`
-clear_worktree_path(task_id)
-\`\`\`
-
-### NO EXCEPTIONS
-
-Even for:
-- "Quick fixes" → Use a worktree
-- "Urgent hotfixes" → Use a worktree
-- "One line changes" → Use a worktree
-
-### Wrong vs Right Order
-
-**WRONG:**
-1. Edit files in main repo
-2. git stash
-3. Create worktree
-4. git stash pop
-
-**RIGHT:**
-1. Create worktree FIRST
-2. cd into worktree
-3. THEN edit files
-
-### Useful Commands
-
-| Command | Description |
-|---------|-------------|
-| \`git worktree list\` | List all worktrees |
-| \`git worktree add <path> -b <branch> <base>\` | Create worktree |
-| \`git worktree remove <path>\` | Remove worktree |
-| \`get_stale_worktrees(project_id)\` | Find orphaned worktrees |
-
-### Cleaning Stale Worktrees
-
-On session start, if \`stale_worktrees\` is returned:
-\`\`\`bash
-git worktree remove <path>
-\`\`\`
-Then:
-\`\`\`
-clear_worktree_path(task_id)
-\`\`\``,
-	},
-
-	deployment: {
-		title: 'Deployment Coordination',
-		content: `# Deployment Coordination
-
-## Deployment Flow
-
-1. **Request** → \`request_deployment(project_id)\`
-2. **Validate** → Build and test the deployment
-3. **Deploy** → Execute deployment
-4. **Complete** → Mark success/failure
-
-## Requesting Deployment
-
-\`\`\`
-request_deployment(
-  project_id,
-  environment: "production",     // development, staging, production
-  version_bump: "patch",         // patch, minor, major
-  git_ref: "main",               // Branch or commit
-  notes: "Bug fixes for auth"    // Optional
-)
-\`\`\`
-
-## Pre-Deployment Requirements
-
-Add requirements that must be completed before deploying:
-\`\`\`
-add_deployment_requirement(
-  project_id,
-  type: "migration",
-  title: "Run migration: add_user_roles",
-  description: "Run: pnpm db:migrate",
-  stage: "preparation"  // preparation, deployment, verification
-)
-\`\`\`
-
-Types: \`migration\`, \`env_var\`, \`config\`, \`manual\`, \`breaking_change\`, \`agent_task\`
-
-Check requirements:
-\`\`\`
-get_deployment_requirements(project_id)
-\`\`\`
-
-Complete them:
-\`\`\`
-complete_deployment_requirement(requirement_id)
-\`\`\`
-
-## Validating Deployment
-
-Claim for validation:
-\`\`\`
-claim_deployment_validation(project_id)
-\`\`\`
-
-Run build and tests, then report:
-\`\`\`
-report_validation(
-  project_id,
-  build_passed: true,
-  tests_passed: true
-)
-\`\`\`
-
-If validation fails, an investigation task is auto-created.
-
-## Executing Deployment
-
-Check status:
-\`\`\`
-check_deployment_status(project_id)
-\`\`\`
-
-When status is "ready":
-\`\`\`
-start_deployment(project_id)
-\`\`\`
-
-After deployment completes:
-\`\`\`
-complete_deployment(
-  project_id,
-  success: true,
-  summary: "Deployed v1.2.3 with auth fixes"
-)
-\`\`\`
-
-Or if it failed:
-\`\`\`
-complete_deployment(
-  project_id,
-  success: false,
-  summary: "Rollback due to database connection errors"
-)
-\`\`\`
-
-## Scheduled Deployments
-
-Schedule future deployments:
-\`\`\`
-schedule_deployment(
-  project_id,
-  scheduled_at: "2025-01-20T10:00:00Z",
-  schedule_type: "once",  // once, hourly, daily, weekly, monthly
-  auto_trigger: true      // Auto-deploy when due
-)
-\`\`\`
-
-Check due deployments:
-\`\`\`
-check_due_deployments(project_id)
-\`\`\`
-
-## Canceling
-
-\`\`\`
-cancel_deployment(project_id, reason: "Blocker found in staging")
-\`\`\``,
-	},
-
-	blockers: {
-		title: 'Handling Blockers',
-		content: `# Handling Blockers
-
-## Recording a Blocker
-
-When you can't proceed:
-\`\`\`
-add_blocker(
-  project_id,
-  description: "API endpoint returning 500 errors - need backend team to investigate"
-)
-\`\`\`
-
-## Viewing Blockers
-
-\`\`\`
-get_blockers(project_id)  // Open blockers
-get_blockers(project_id, status: "resolved")  // Resolved blockers
-get_blockers_stats(project_id)  // Just counts
-\`\`\`
-
-## Resolving Blockers
-
-\`\`\`
-resolve_blocker(
-  blocker_id,
-  resolution_note: "Backend team fixed the API - endpoint now returns correct data"
-)
-\`\`\`
-
-## What Counts as a Blocker?
-
-**IS a blocker:**
-- External dependency not available
-- Need access/credentials you don't have
-- Critical bug in a dependency
-- Waiting for human decision
-- Environment issue preventing testing
-
-**NOT a blocker:**
-- Need to learn something → research and continue
-- Code is complex → break it down with milestones
-- Tests failing → fix them
-- Merge conflicts → resolve them
-
-## Blocker Best Practices
-
-1. **Be specific** - Describe exactly what's blocked and why
-2. **Include context** - What were you trying to do?
-3. **Suggest solutions** - If you know what might help
-4. **Check existing blockers** - Don't duplicate
-5. **Resolve promptly** - When the issue is fixed, resolve the blocker`,
-	},
-
-	milestones: {
-		title: 'Task Milestones',
-		content: `# Task Milestones
-
-Milestones break down large tasks into trackable steps.
-
-## Adding Milestones
-
-\`\`\`
-add_milestone(task_id, title: "Design database schema")
-add_milestone(task_id, title: "Implement API endpoints")
-add_milestone(task_id, title: "Write unit tests")
-add_milestone(task_id, title: "Add integration tests")
-\`\`\`
-
-With order and description:
-\`\`\`
-add_milestone(
-  task_id,
-  title: "Set up authentication",
-  description: "Configure OAuth providers and session management",
-  order_index: 0
-)
-\`\`\`
-
-## Viewing Milestones
-
-\`\`\`
-get_milestones(task_id)
-\`\`\`
-
-Or include when getting task:
-\`\`\`
-get_task(task_id, include_milestones: true)
-\`\`\`
-
-## Updating Progress
-
-Mark milestone in progress:
-\`\`\`
-update_milestone(milestone_id, status: "in_progress")
-\`\`\`
-
-Complete a milestone:
-\`\`\`
-complete_milestone(milestone_id)
-\`\`\`
-
-## When to Use Milestones
-
-**Good candidates:**
-- Tasks estimated > 2 hours
-- Multi-step implementations
-- Features spanning multiple files/modules
-- Tasks with clear phases
-
-**Example breakdown:**
-
-Task: "Implement user authentication"
-1. Set up OAuth provider configuration
-2. Create login/logout API endpoints
-3. Implement session management
-4. Add protected route middleware
-5. Create login UI components
-6. Write tests
-
-## Milestones vs Subtasks
-
-| Milestones | Subtasks |
-|------------|----------|
-| Sequential steps | Parallel work items |
-| Same agent | Can be claimed by different agents |
-| Progress tracking | Delegation |
-| One at a time | Multiple in progress |
-
-Use **milestones** for ordered steps you'll do yourself.
-Use **subtasks** when work can be parallelized across agents.`,
-	},
-
-	fallback: {
-		title: 'Fallback Activities',
-		content: `# Fallback Activities
-
-When no tasks are available, agents can perform background activities.
-
-## Starting a Fallback Activity
-
-\`\`\`
-start_fallback_activity(project_id, activity: "code_review")
-\`\`\`
-
-## Available Activities
-
-| Activity | Description |
-|----------|-------------|
-| \`code_review\` | Review code quality, patterns, best practices |
-| \`security_review\` | Security audit, vulnerability scanning |
-| \`performance_audit\` | Performance analysis, optimization opportunities |
-| \`ux_review\` | UX/accessibility review |
-| \`test_coverage\` | Test coverage analysis, missing tests |
-| \`documentation_review\` | Documentation gaps, outdated docs |
-| \`dependency_audit\` | Dependency updates, vulnerabilities |
-| \`feature_ideation\` | Suggest improvements, new features |
-| \`validate_completed_tasks\` | Review tasks awaiting validation |
-| \`worktree_cleanup\` | Clean up stale worktrees |
-
-## Recording Findings
-
-During activities, record findings:
-\`\`\`
-add_finding(
-  project_id,
-  title: "SQL injection risk in user search",
-  category: "security",       // security, performance, code_quality, etc.
-  severity: "high",           // info, low, medium, high, critical
-  description: "User input passed directly to query without sanitization",
-  file_path: "src/api/users.ts",
-  line_number: 45
-)
-\`\`\`
-
-## Recording Ideas
-
-For feature suggestions:
-\`\`\`
-add_idea(
-  project_id,
-  title: "Add rate limiting to API",
-  description: "Protect against abuse by adding rate limits per user/IP"
-)
-\`\`\`
-
-## Stopping Activities
-
-Activities auto-stop when you start a task. Manual stop:
-\`\`\`
-stop_fallback_activity(project_id, summary: "Reviewed 5 files, found 2 issues")
-\`\`\`
-
-## Activity History
-
-\`\`\`
-get_activity_history(project_id)
-\`\`\`
-
-## Project Settings
-
-Projects can restrict fallback activities:
-\`\`\`
-update_project(
-  project_id,
-  fallback_activities_enabled: true,
-  preferred_fallback_activities: ["code_review", "security_review"]
-)
-\`\`\``,
-	},
-
-	tokens: {
-		title: 'Token Usage & Cost Tracking',
-		content: `# Token Usage & Cost Tracking
-
-## Checking Usage
-
-\`\`\`
-get_token_usage()
-\`\`\`
-
-Returns:
-- Session stats (calls, tokens, avg per call)
-- Top tools by token usage
-- Model breakdown (input/output tokens)
-- Estimated costs
-
-## Reporting Actual Usage
-
-MCP estimates are only ~1-5% of actual API usage. For accurate tracking:
-
-\`\`\`
-report_token_usage(
-  input_tokens: 1500,
-  output_tokens: 500,
-  model: "opus"  // or sonnet, haiku
-)
-\`\`\`
-
-Call this after each API response using values from the response headers:
-- \`usage.input_tokens\`
-- \`usage.output_tokens\`
-
-## Model Pricing
-
-| Model | Input (per 1M) | Output (per 1M) |
-|-------|---------------|-----------------|
-| Opus | $15.00 | $75.00 |
-| Sonnet | $3.00 | $15.00 |
-| Haiku | $0.25 | $1.25 |
-
-## Cost Monitoring
-
-Get cost summary:
-\`\`\`
-get_cost_summary(project_id, period: "daily")  // daily, weekly, monthly
-\`\`\`
-
-Set up alerts:
-\`\`\`
-add_cost_alert(
-  project_id,
-  threshold_amount: 100,      // USD
-  threshold_period: "daily",
-  alert_type: "warning"       // warning, critical
-)
-\`\`\`
-
-## Context Management
-
-When token usage is high:
-1. Check with \`get_token_usage()\`
-2. If 50+ calls or 100k+ tokens: \`/clear\`
-3. Immediately call \`start_work_session()\`
-4. Continue with \`next_task\`
-
-**Don't ask permission** - just clear and continue.
-
-## Efficiency Tips
-
-1. **Use lite mode** (default) - saves ~85% tokens on session start
-2. **Batch updates** - Use \`batch_update_tasks\` when updating multiple
-3. **Use stats endpoints** - \`get_task_stats\` instead of listing all tasks
-4. **Clear context regularly** - Don't let it grow unbounded`,
-	},
-
-	sprints: {
-		title: 'Sprint Management',
-		content: `# Sprint Management
-
-Sprints are time-bounded work periods with velocity tracking.
-
-## Creating a Sprint
-
-\`\`\`
-create_sprint(
-  project_id,
-  title: "Sprint 5",
-  start_date: "2025-01-20",
-  end_date: "2025-02-03",
-  goal: "Complete authentication and user profile features"
-)
-\`\`\`
-
-## Sprint Lifecycle
-
-1. **Planning** → Add tasks, assign story points
-2. **Active** → Work on tasks
-3. **In Review** → Review completed work
-4. **Retrospective** → Reflect on sprint
-5. **Completed** → Archive with metrics
-
-## Adding Tasks to Sprint
-
-\`\`\`
-add_task_to_sprint(
-  sprint_id,
-  task_id,
-  story_points: 3,
-  phase: "core"  // pre, core, post
-)
-\`\`\`
-
-## Starting a Sprint
-
-\`\`\`
-start_sprint(sprint_id)
-\`\`\`
-
-This locks \`committed_points\` at the current total.
-
-## Getting Sprint Backlog
-
-Tasks available to add:
-\`\`\`
-get_sprint_backlog(project_id, sprint_id)
-\`\`\`
-
-## Sprint Progress
-
-\`\`\`
-get_sprint(sprint_id)
-\`\`\`
-
-With just counts (saves tokens):
-\`\`\`
-get_sprint(sprint_id, summary_only: true)
-\`\`\`
-
-## Completing a Sprint
-
-\`\`\`
-complete_sprint(
-  sprint_id,
-  retrospective_notes: "Completed 80% of planned work. Auth took longer than expected.",
-  skip_retrospective: false
-)
-\`\`\`
-
-## Velocity Tracking
-
-\`\`\`
-get_sprint_velocity(project_id, limit: 10)
-\`\`\`
-
-Returns:
-- Committed vs completed points per sprint
-- Average velocity
-- Trend analysis`,
-	},
-
-	topics: {
-		title: 'Available Help Topics',
-		content: `# Available Help Topics
-
-Use \`get_help(topic)\` for detailed guidance on any topic.
-
-## Core Topics
-
-| Topic | Description |
-|-------|-------------|
-| \`getting_started\` | Quick start guide, core workflow |
-| \`session\` | Session lifecycle, heartbeats, context management |
-| \`tasks\` | Task management, progress tracking, completion |
-| \`validation\` | Cross-agent task validation workflow |
-| \`git\` | Git workflows, worktrees, branch management |
-| \`deployment\` | Deployment coordination, requirements |
-
-## Task Organization
-
-| Topic | Description |
-|-------|-------------|
-| \`milestones\` | Breaking down complex tasks into steps |
-| \`subtasks\` | Parallelizable task breakdown |
-| \`bodies_of_work\` | Group related tasks into phases |
-| \`sprints\` | Time-bounded sprints with velocity tracking |
-
-## Collaboration
-
-| Topic | Description |
-|-------|-------------|
-| \`roles\` | Agent roles and specialization |
-| \`file_locks\` | Multi-agent file coordination |
-| \`git_issues\` | Git conflict and issue tracking |
-| \`requests\` | Handle user questions from dashboard |
-
-## Knowledge & Tracking
-
-| Topic | Description |
-|-------|-------------|
-| \`blockers\` | Recording and resolving blockers |
-| \`knowledge\` | Project knowledge base |
-| \`ideas\` | Feature ideas and requests |
-| \`tokens\` | Token usage and cost tracking |
-| \`fallback\` | Background activities when idle |
-| \`connectors\` | External integrations (Slack, webhooks) |
-
-## Quick Examples
-
-\`\`\`
-get_help("getting_started")  // New to Vibescope? Start here
-get_help("git")              // Git worktree workflow
-get_help("validation")       // How to validate tasks
-get_help("session")          // Session management
-get_help("bodies_of_work")   // Organizing related tasks
-\`\`\``,
-	},
-
-	roles: {
-		title: 'Agent Roles',
-		content: `# Agent Roles
-
-Roles specialize agents for different types of work.
-
-## Available Roles
-
-| Role | Description |
-|------|-------------|
-| \`developer\` | General development work (default) |
-| \`validator\` | Reviews and validates completed tasks |
-| \`deployer\` | Handles deployments |
-| \`reviewer\` | Code review focus |
-| \`maintainer\` | Housekeeping and maintenance |
-
-## Setting Your Role
-
-At session start:
-\`\`\`
-start_work_session(git_url, model, role: "validator")
-\`\`\`
-
-Or mid-session:
-\`\`\`
-set_session_role(role: "validator")
-\`\`\`
-
-## Role Configuration
-
-View project role settings:
-\`\`\`
-get_role_settings(project_id)
-\`\`\`
-
-Configure role behavior:
-\`\`\`
-update_role_settings(
-  project_id,
-  role: "validator",
-  enabled: true,
-  auto_assign_validation: true,
-  fallback_activities: ["code_review", "security_review"]
-)
-\`\`\`
-
-## Viewing Agents by Role
-
-\`\`\`
-get_agents_by_role(project_id)
-\`\`\`
-
-With counts only (saves tokens):
-\`\`\`
-get_agents_by_role(project_id, counts_only: true)
-\`\`\`
-
-## Role-Specific Workflows
-
-**Developer:**
-- Gets tasks via \`get_next_task\`
-- Creates PRs
-- Calls \`complete_task\`
-
-**Validator:**
-- Gets tasks via \`get_tasks_awaiting_validation\`
-- Reviews code, runs tests
-- Approves/rejects via \`validate_task\`
-- Merges PRs on approval
-
-**Deployer:**
-- Checks \`check_deployment_status\`
-- Validates deployments
-- Executes deployments
-- Handles rollbacks`,
-	},
-
-	knowledge: {
-		title: 'Project Knowledge Base',
-		content: `# Project Knowledge Base
-
-Query aggregated project knowledge efficiently.
-
-## Querying Knowledge
-
-\`\`\`
-query_knowledge_base(
-  project_id,
-  categories: ["findings", "decisions", "completed_tasks"],
-  scope: "summary",  // summary or detailed
-  limit: 10,
-  search_query: "authentication"
-)
-\`\`\`
-
-## Categories
-
-| Category | Description |
-|----------|-------------|
-| \`findings\` | Audit findings, code issues |
-| \`qa\` | Questions and answers |
-| \`decisions\` | Architectural decisions |
-| \`completed_tasks\` | Recently completed work |
-| \`blockers\` | Resolved blockers |
-| \`progress\` | Progress updates |
-
-## Recording Knowledge
-
-### Findings
-\`\`\`
-add_finding(
-  project_id,
-  title: "N+1 query in user list",
-  category: "performance",
-  severity: "medium",
-  description: "User list makes N+1 queries for profile images",
-  file_path: "src/api/users.ts"
-)
-\`\`\`
-
-### Decisions
-\`\`\`
-log_decision(
-  project_id,
-  title: "Use PostgreSQL for database",
-  description: "Selected PostgreSQL over MongoDB",
-  rationale: "Better support for complex queries and transactions",
-  alternatives_considered: ["MongoDB", "MySQL"]
-)
-\`\`\`
-
-### Ideas
-\`\`\`
-add_idea(
-  project_id,
-  title: "Add caching layer",
-  description: "Redis cache for frequently accessed data",
-  status: "raw"  // raw, exploring, planned, in_development, shipped
-)
-\`\`\`
-
-## Efficiency
-
-Use \`query_knowledge_base\` instead of multiple separate calls:
-- Single call returns aggregated data
-- Filter by category to reduce response size
-- Use \`summary\` scope for token efficiency`,
-	},
-
-	bodies_of_work: {
-		title: 'Bodies of Work',
-		content: `# Bodies of Work
-
-Bodies of work group related tasks into phases for coordinated execution.
-
-## Creating a Body of Work
-
-\`\`\`
-create_body_of_work(
-  project_id,
-  title: "User Authentication Feature",
-  description: "Complete auth system with OAuth support",
-  auto_deploy_on_completion: true,
-  deploy_version_bump: "minor"
-)
-\`\`\`
-
-## Task Phases
-
-Tasks are organized into three phases:
-- **pre** - Setup, migrations, dependencies
-- **core** - Main implementation work
-- **post** - Cleanup, documentation, verification
-
-## Adding Tasks
-
-\`\`\`
-add_task_to_body_of_work(
-  body_of_work_id,
-  task_id,
-  phase: "core"  // pre, core, post
-)
-\`\`\`
-
-## Task Dependencies
-
-Create dependencies between tasks:
-\`\`\`
-add_task_dependency(
-  body_of_work_id,
-  task_id: "frontend-task",
-  depends_on_task_id: "api-task"
-)
-\`\`\`
-
-The dependent task won't be available until its dependencies are complete.
-
-## Activating
-
-Bodies of work start in "draft" status. Activate to begin:
-\`\`\`
-activate_body_of_work(body_of_work_id)
-\`\`\`
-
-## Getting Next Task
-
-\`\`\`
-get_next_body_of_work_task(body_of_work_id)
-\`\`\`
-
-Returns the next available task considering:
-- Phase order (pre → core → post)
-- Task dependencies
-- Task status
-
-## Viewing Bodies of Work
-
-\`\`\`
-get_body_of_work(body_of_work_id)  // Single BOW with tasks
-get_bodies_of_work(project_id)     // All BOWs for project
-\`\`\`
-
-## Auto-Deployment
-
-If \`auto_deploy_on_completion: true\`, a deployment is automatically requested when all tasks complete.
-
-Configure the trigger:
-- \`all_completed\` - Deploy immediately when all tasks done
-- \`all_completed_validated\` - Wait for validation first`,
-	},
-
-	subtasks: {
-		title: 'Subtasks',
-		content: `# Subtasks
-
-Subtasks break down larger tasks into smaller, parallelizable pieces.
-
-## Adding Subtasks
-
-\`\`\`
-add_subtask(
-  parent_task_id,
-  title: "Implement login form UI",
-  description: "Create React component for login form",
-  priority: 2,
-  estimated_minutes: 60
-)
-\`\`\`
-
-## Viewing Subtasks
-
-\`\`\`
-get_subtasks(parent_task_id)
-\`\`\`
-
-Or include when getting task:
-\`\`\`
-get_task(task_id, include_subtasks: true)
-\`\`\`
-
-## Working on Subtasks
-
-Subtasks work just like regular tasks:
-\`\`\`
-update_task(subtask_id, status: "in_progress")
-complete_task(subtask_id, summary: "Completed login form")
-\`\`\`
-
-## Subtasks vs Milestones
-
-| Subtasks | Milestones |
-|----------|------------|
-| Independent units of work | Sequential steps |
-| Can be claimed by any agent | Same agent completes all |
-| Parallel execution | One at a time |
-| Full task lifecycle | Simple status tracking |
-
-**Use subtasks when:**
-- Work can be done in parallel by multiple agents
-- Each piece is independent and self-contained
-- You want to delegate work
-
-**Use milestones when:**
-- Steps must be done in order
-- Same person does all steps
-- Just need progress tracking
-
-## Constraints
-
-- Max depth is 1 (subtasks cannot have their own subtasks)
-- Subtasks inherit project from parent task
-- Parent task completion is independent of subtasks`,
-	},
-
-	file_locks: {
-		title: 'File Locking',
-		content: `# File Locking (Multi-Agent Coordination)
-
-Prevent conflicts when multiple agents work on the same files.
-
-## Checking Availability
-
-Before editing a file:
-\`\`\`
-is_file_available(project_id, file_path: "src/api/users.ts")
-\`\`\`
-
-Returns whether the file is free or who has it locked.
-
-## Checking Out Files
-
-Lock a file before editing:
-\`\`\`
-checkout_file(
-  project_id,
-  file_path: "src/api/users.ts",
-  reason: "Fixing authentication bug"
-)
-\`\`\`
-
-## Checking In Files
-
-Release the file when done:
-\`\`\`
-checkin_file(
-  checkout_id,
-  summary: "Fixed token validation logic"
-)
-\`\`\`
-
-Or by path:
-\`\`\`
-checkin_file(
-  project_id,
-  file_path: "src/api/users.ts",
-  summary: "Fixed token validation logic"
-)
-\`\`\`
-
-## Viewing Checkouts
-
-\`\`\`
-get_file_checkouts(project_id)                  // Active checkouts
-get_file_checkouts(project_id, status: "checked_in")  // Completed
-get_file_checkouts_stats(project_id)            // Just counts
-\`\`\`
-
-## Handling Abandoned Locks
-
-If an agent session dies with a file locked:
-\`\`\`
-abandon_checkout(
-  checkout_id,
-  reason: "Agent session terminated"
-)
-\`\`\`
-
-## Best Practices
-
-1. **Always check availability** before editing shared files
-2. **Keep locks short** - check in as soon as you're done
-3. **Use meaningful reasons** - helps others understand why file is locked
-4. **Check in even if no changes** - releases the lock for others
-5. **Use worktrees** - provides file isolation, reducing need for locks`,
-	},
-
-	connectors: {
-		title: 'External Connectors',
-		content: `# External Connectors
-
-Connectors enable sending events to external services.
-
-## Supported Types
-
-| Type | Description |
-|------|-------------|
-| \`webhook\` | Generic HTTP webhook |
-| \`slack\` | Slack notifications |
-| \`discord\` | Discord notifications |
-| \`github\` | GitHub integration |
-| \`custom\` | Custom connector |
-
-## Adding a Connector
-
-Slack example:
-\`\`\`
-add_connector(
-  project_id,
-  name: "Slack Notifications",
-  type: "slack",
-  config: { webhook_url: "https://hooks.slack.com/..." },
-  events: {
-    task_completed: true,
-    blocker_added: true,
-    deployment_started: true
-  }
-)
-\`\`\`
-
-Webhook example:
-\`\`\`
-add_connector(
-  project_id,
-  name: "CI/CD Webhook",
-  type: "webhook",
-  config: {
-    url: "https://ci.example.com/webhook",
-    headers: { "X-API-Key": "secret" }
-  },
-  events: { deployment_completed: true }
-)
-\`\`\`
-
-## Available Events
-
-- \`task_completed\` - Task marked done
-- \`task_validated\` - Task approved/rejected
-- \`blocker_added\` - New blocker recorded
-- \`blocker_resolved\` - Blocker resolved
-- \`deployment_started\` - Deployment began
-- \`deployment_completed\` - Deployment finished
-- \`agent_session_started\` - Agent connected
-- \`agent_session_ended\` - Agent disconnected
-
-## Managing Connectors
-
-\`\`\`
-get_connectors(project_id)           // List all
-get_connector(connector_id)          // Get details
-update_connector(connector_id, ...)  // Update config
-delete_connector(connector_id)       // Remove
-\`\`\`
-
-## Testing
-
-\`\`\`
-test_connector(connector_id)
-\`\`\`
-
-Sends a test event and returns success/failure.
-
-## Event History
-
-\`\`\`
-get_connector_events(connector_id)
-get_connector_events(project_id)  // All connectors
-\`\`\``,
-	},
-
-	git_issues: {
-		title: 'Git Issues',
-		content: `# Git Issues
-
-Track and resolve git-related problems.
-
-## Issue Types
-
-| Type | Description |
-|------|-------------|
-| \`merge_conflict\` | Conflicting changes |
-| \`push_failed\` | Push rejected |
-| \`rebase_needed\` | Branch needs rebase |
-| \`branch_diverged\` | Branch diverged from base |
-| \`pr_not_mergeable\` | PR cannot be merged |
-
-## Recording Issues
-
-\`\`\`
-add_git_issue(
-  project_id,
-  issue_type: "merge_conflict",
-  branch: "feature/add-auth",
-  target_branch: "develop",
-  conflicting_files: ["src/api/users.ts", "src/models/user.ts"],
-  task_id: "task-uuid",  // Optional
-  error_message: "Automatic merge failed"
-)
-\`\`\`
-
-## Viewing Issues
-
-\`\`\`
-get_git_issues(project_id)                        // Open issues
-get_git_issues(project_id, status: "resolved")    // Resolved
-get_git_issues(project_id, branch: "feature/x")   // By branch
-get_git_issues(project_id, issue_type: "merge_conflict")  // By type
-\`\`\`
-
-## Resolving Issues
-
-\`\`\`
-resolve_git_issue(
-  git_issue_id,
-  resolution_note: "Rebased branch and resolved conflicts manually"
-)
-\`\`\`
-
-Auto-resolved (e.g., PR became mergeable):
-\`\`\`
-resolve_git_issue(
-  git_issue_id,
-  auto_resolved: true,
-  resolution_note: "PR automatically became mergeable after upstream merge"
-)
-\`\`\`
-
-## Handling Merge Conflicts
-
-1. **Fetch latest changes:**
-   \`\`\`bash
-   git fetch origin
-   \`\`\`
-
-2. **Rebase on target:**
-   \`\`\`bash
-   git rebase origin/develop
-   \`\`\`
-
-3. **Resolve conflicts in editor**
-
-4. **Continue rebase:**
-   \`\`\`bash
-   git add .
-   git rebase --continue
-   \`\`\`
-
-5. **Force push:**
-   \`\`\`bash
-   git push --force-with-lease
-   \`\`\`
-
-6. **Resolve the issue:**
-   \`\`\`
-   resolve_git_issue(git_issue_id, resolution_note: "Rebased and resolved")
-   \`\`\``,
-	},
-
-	ideas: {
-		title: 'Ideas & Feature Requests',
-		content: `# Ideas & Feature Requests
-
-Track improvement ideas and feature requests.
-
-## Adding Ideas
-
-\`\`\`
-add_idea(
-  project_id,
-  title: "Add dark mode support",
-  description: "Implement theme switching with dark mode option",
-  status: "raw"  // Default status
-)
-\`\`\`
-
-## Idea Lifecycle
-
-| Status | Description |
-|--------|-------------|
-| \`raw\` | Initial idea, not yet evaluated |
-| \`exploring\` | Being researched/discussed |
-| \`planned\` | Approved for implementation |
-| \`in_development\` | Being worked on |
-| \`shipped\` | Completed and deployed |
-
-## Updating Ideas
-
-\`\`\`
-update_idea(
-  idea_id,
-  status: "planned",
-  doc_url: "https://docs.example.com/dark-mode-spec"
-)
-\`\`\`
-
-## Converting to Task
-
-When ready to implement:
-\`\`\`
-convert_idea_to_task(
-  idea_id,
-  priority: 2,
-  estimated_minutes: 120,
-  update_status: true  // Sets idea to "in_development"
-)
-\`\`\`
-
-This creates a task linked to the idea.
-
-## Viewing Ideas
-
-\`\`\`
-get_ideas(project_id)                          // All ideas
-get_ideas(project_id, status: "planned")       // Ready to build
-get_ideas(project_id, search_query: "dark")    // Search
-get_idea(idea_id)                              // Single idea
-\`\`\`
-
-## Best Practices
-
-1. **Capture ideas immediately** - Don't lose them
-2. **Be specific** - Include context and rationale
-3. **Link documentation** - Add doc_url when available
-4. **Update status** - Keep ideas current
-5. **Convert when ready** - Move to tasks for execution`,
-	},
-
-	requests: {
-		title: 'User Requests',
-		content: `# User Requests
-
-Handle questions and requests from users via the dashboard.
-
-## Checking for Requests
-
-Requests are included in \`start_work_session\` response:
-- \`pending_requests\` - Array of unanswered requests
-- \`URGENT_QUESTIONS\` - High-priority questions
-
-## Getting Pending Requests
-
-\`\`\`
-get_pending_requests(project_id)
-\`\`\`
-
-## Answering Questions
-
-\`\`\`
-answer_question(
-  request_id,
-  answer: "The authentication flow uses JWT tokens stored in httpOnly cookies. Tokens expire after 24 hours and are automatically refreshed."
-)
-\`\`\`
-
-## Acknowledging Requests
-
-For non-question requests:
-\`\`\`
-acknowledge_request(request_id)
-\`\`\`
-
-## Priority
-
-When \`start_work_session\` returns pending requests:
-1. Answer questions FIRST (before starting tasks)
-2. \`URGENT_QUESTIONS\` take absolute priority
-3. Then proceed with \`next_task\`
-
-## Best Practices
-
-1. **Check requests early** - Answer before deep work
-2. **Be thorough** - Provide complete answers
-3. **Include context** - Reference code/docs when helpful
-4. **Acknowledge promptly** - Don't leave users waiting`,
-	},
-};
-
-/**
- * Get fallback help content for a topic
- * @param topic The help topic slug
- * @returns The help content or null if topic not found
- */
-export function getFallbackHelpContent(topic: string): { title: string; content: string } | null {
-	return HELP_TOPICS[topic] || null;
-}
-
-/**
- * Get list of available help topics
- * @returns Array of topic slugs
- */
-export function getAvailableHelpTopics(): string[] {
-	return Object.keys(HELP_TOPICS);
-}
+/**
+ * Fallback Help Content
+ *
+ * This provides comprehensive help content for each topic when the backend
+ * database has no content populated. Ensures agents always get useful guidance.
+ */
+
+export const HELP_TOPICS: Record<string, { title: string; content: string }> = {
+	getting_started: {
+		title: 'Getting Started',
+		content: `# Getting Started with Vibescope
+
+## Quick Start
+
+\`\`\`
+start_work_session(git_url: "https://github.com/YOUR/REPO", model: "opus", agent_type: "claude")
+\`\`\`
+
+**Parameters:**
+- \`git_url\`: Your repository URL (required if no project_id)
+- \`model\`: Your model type - opus, sonnet, or haiku (for cost tracking)
+- \`agent_type\`: Your agent type - claude, gemini, cursor, windsurf, or other
+
+This returns:
+- \`session_id\`: Your session identifier
+- \`persona\`: Your assigned agent persona (e.g., "Nova", "Edge")
+- \`project\`: Project details and settings
+- \`next_task\`: The highest priority task to work on
+
+## Core Workflow
+
+1. **Start session** → \`start_work_session(git_url, model, agent_type)\`
+2. **Mark task in progress** → \`update_task(task_id, status: "in_progress")\`
+3. **Update progress** → \`update_task(task_id, progress_percentage: 50, progress_note: "...")\`
+4. **Complete task** → \`complete_task(task_id, summary: "...")\`
+5. **Continue** → Start the next_task returned, or call \`get_next_task(project_id)\`
+
+## Key Rules
+
+1. **Always call complete_task()** after finishing work - don't wait for PR review
+2. **Never ask permission** to continue - just start the next task
+3. **Use git worktrees** for branching workflows to avoid conflicts
+4. **Update progress** regularly (every 15-20% completion)
+
+## Need More Help?
+
+Use \`get_help(topic)\` with these topics:
+- \`tasks\` - Task management workflow
+- \`validation\` - Cross-agent task validation
+- \`git\` - Git workflow and worktrees
+- \`deployment\` - Deployment coordination
+- \`session\` - Session management
+- \`fallback\` - Background activities
+- \`blockers\` - Handling blockers
+- \`milestones\` - Breaking down complex tasks`,
+	},
+
+	session: {
+		title: 'Session Management',
+		content: `# Session Management
+
+## Starting a Session
+
+\`\`\`
+start_work_session(
+  git_url: "https://github.com/YOUR/REPO",
+  model: "opus",           // opus, sonnet, or haiku
+  agent_type: "claude",    // claude, gemini, cursor, windsurf, other
+  role: "developer"        // developer, validator, deployer, reviewer, maintainer
+)
+\`\`\`
+
+**Response includes:**
+- \`session_id\`: Unique session identifier
+- \`persona\`: Your assigned agent name (e.g., "Nova", "Edge", "Arc")
+- \`project\`: Project configuration
+- \`next_task\`: Highest priority task to start
+- \`pending_requests\`: User questions to answer first
+- \`awaiting_validation\`: Tasks needing review (for validators)
+- \`stale_worktrees\`: Worktrees to clean up
+
+## Maintaining Your Session
+
+### Heartbeat
+Send heartbeats every 30-60 seconds to stay active:
+\`\`\`
+heartbeat(current_worktree_path: "../project-persona-task")
+\`\`\`
+
+This:
+- Keeps your session marked as "active" on the dashboard
+- Reports your current working directory
+- Syncs token usage to the backend
+
+### Token Tracking
+Check your token usage:
+\`\`\`
+get_token_usage()
+\`\`\`
+
+Report actual API usage for accurate cost tracking:
+\`\`\`
+report_token_usage(input_tokens: 1500, output_tokens: 500, model: "opus")
+\`\`\`
+
+## Ending a Session
+
+\`\`\`
+end_work_session()
+\`\`\`
+
+This:
+- Releases any claimed tasks
+- Syncs final token usage
+- Returns a session summary
+
+## Context Management
+
+When your context grows large (50+ tool calls or 100k+ tokens):
+1. Run \`/clear\` to reset conversation
+2. Immediately call \`start_work_session()\` to reload
+3. Continue with the \`next_task\` from the response
+
+**Do NOT ask the user** - just clear and continue. The dashboard tracks all progress.
+
+## Session Roles
+
+| Role | Description |
+|------|-------------|
+| \`developer\` | General development work (default) |
+| \`validator\` | Reviews and validates completed tasks |
+| \`deployer\` | Handles deployments |
+| \`reviewer\` | Code review focus |
+| \`maintainer\` | Housekeeping and maintenance |
+
+Change role mid-session:
+\`\`\`
+set_session_role(role: "validator")
+\`\`\``,
+	},
+
+	tasks: {
+		title: 'Task Management',
+		content: `# Task Management
+
+## Getting Tasks
+
+### Get Next Task
+\`\`\`
+get_next_task(project_id)
+\`\`\`
+Returns the highest priority pending task.
+
+### Search Tasks
+\`\`\`
+search_tasks(project_id, query: "login bug", status: ["pending", "in_progress"])
+\`\`\`
+
+### Get by Priority
+\`\`\`
+get_tasks_by_priority(project_id, priority: 1)  // P1 tasks only
+get_tasks_by_priority(project_id, priority: 1, priority_max: 2)  // P1 and P2
+\`\`\`
+
+## Working on Tasks
+
+### 1. Start the Task
+\`\`\`
+update_task(task_id, status: "in_progress")
+\`\`\`
+
+**For branching workflows (github-flow, git-flow):**
+Create a worktree first, then include it:
+\`\`\`
+update_task(
+  task_id,
+  status: "in_progress",
+  git_branch: "feature/abc123-add-login",
+  worktree_path: "../project-persona-add-login"
+)
+\`\`\`
+
+### 2. Update Progress
+Update regularly (every 15-20% completion):
+\`\`\`
+update_task(
+  task_id,
+  progress_percentage: 50,
+  progress_note: "Implemented core logic, working on tests"
+)
+\`\`\`
+
+### 3. Complete the Task
+**CRITICAL: Always call complete_task() after finishing!**
+\`\`\`
+complete_task(task_id, summary: "Added login flow with OAuth support")
+\`\`\`
+
+**When to call complete_task:**
+- After creating and pushing a PR
+- After merging (trunk-based workflow)
+- After finishing any unit of work
+
+**Do NOT wait for:**
+- PR review/merge (validation handles that)
+- User confirmation
+- Perfect summary
+
+### Fix Already Exists (No Code Changes Needed)
+
+When investigating a task and finding the fix already exists in code but hasn't been deployed:
+
+1. **Document the finding:**
+\`\`\`
+add_finding(
+  project_id,
+  title: "Fix exists but awaits deployment",
+  category: "other",
+  severity: "info",
+  description: "The fix for [issue] was implemented in PR #{pr_number} but hasn't been deployed yet.",
+  related_task_id: task_id
+)
+\`\`\`
+
+2. **Complete the task** (investigation is done):
+\`\`\`
+complete_task(task_id, summary: "Fix already exists in codebase (PR #{pr_number}). Needs deployment to production.")
+\`\`\`
+
+3. **Request deployment** if not already pending:
+\`\`\`
+check_deployment_status(project_id)  // Check if deployment pending
+request_deployment(project_id, notes: "Includes fix for [issue]")
+\`\`\`
+
+This prevents tasks from being blocked waiting for deployment when the actual work is done.
+
+## Task Priorities
+
+| Priority | Meaning |
+|----------|---------|
+| 1 | Critical - do first |
+| 2 | High priority |
+| 3 | Normal (default) |
+| 4 | Low priority |
+| 5 | Backlog |
+
+## Breaking Down Tasks
+
+For complex tasks, use milestones:
+\`\`\`
+add_milestone(task_id, title: "Set up database schema")
+add_milestone(task_id, title: "Implement API endpoints")
+add_milestone(task_id, title: "Add unit tests")
+
+complete_milestone(milestone_id)
+\`\`\`
+
+Or subtasks for parallel work:
+\`\`\`
+add_subtask(parent_task_id, title: "Implement frontend form")
+add_subtask(parent_task_id, title: "Implement backend validation")
+\`\`\`
+
+## Task References
+
+Link PRs, issues, or docs to tasks:
+\`\`\`
+add_task_reference(task_id, url: "https://github.com/org/repo/pull/123", label: "PR")
+\`\`\`
+
+**Important:** For github-flow/git-flow projects, add PR reference before completing - validators need it.
+
+## Deployment-Only Resolutions
+
+When investigating a task and finding the fix already exists in code (just needs deployment):
+
+**1. Document the finding:**
+\`\`\`
+add_finding(
+  project_id,
+  title: "Fix exists - needs deployment",
+  category: "other",
+  severity: "info",
+  description: "Investigation found the fix for [issue] already exists in [commit/PR]. Deployment will resolve this."
+)
+\`\`\`
+
+**2. Mark the task complete:**
+\`\`\`
+complete_task(task_id, summary: "Investigation complete: fix exists in [branch/commit], pending deployment")
+\`\`\`
+
+**3. Request deployment if needed:**
+\`\`\`
+# Check if deployment is already pending
+check_deployment_status(project_id)
+
+# If not, request one
+request_deployment(project_id, notes: "Includes fix for [task description]")
+\`\`\`
+
+**Why this pattern?**
+- Tasks shouldn't block waiting for deployment
+- Investigation work is complete (resolution identified)
+- The finding creates a record of what needs deploying
+- Deployment can bundle multiple fixes together`,
+	},
+
+	validation: {
+		title: 'Task Validation',
+		content: `# Task Validation
+
+Validation ensures completed work meets quality standards before merging.
+
+## For Developers
+
+After completing a task:
+1. Create your PR
+2. Add PR reference: \`add_task_reference(task_id, url: "PR_URL")\`
+3. Call \`complete_task(task_id, summary: "...")\`
+4. A validator will review and merge
+
+## For Validators
+
+### 1. Get Tasks to Validate
+\`\`\`
+get_tasks_awaiting_validation(project_id)
+\`\`\`
+Returns tasks sorted by PR number (oldest first). **Always review in this order (FIFO).**
+
+### 2. Claim a Task
+\`\`\`
+claim_validation(task_id)
+\`\`\`
+
+Returns:
+- \`worktree_setup\`: Commands to checkout the branch
+- \`conflict_check\`: Steps to verify PR can merge
+- \`merge_status\`: Current PR state
+
+### 3. Set Up Your Worktree
+\`\`\`bash
+# Fetch and create worktree from existing branch
+git fetch origin feature/abc123-task
+git worktree add ../project-validator-review feature/abc123-task
+cd ../project-validator-review
+\`\`\`
+
+### 4. Run Tests Locally
+\`\`\`bash
+pnpm install
+pnpm test
+pnpm build
+\`\`\`
+
+### 5. Check PR State
+\`\`\`bash
+gh pr view <PR_NUMBER> --json state,mergedAt --jq '.state'
+\`\`\`
+
+If PR is CLOSED (not merged), cancel instead of validating:
+\`\`\`
+cancel_task(task_id, cancelled_reason: "pr_closed")
+\`\`\`
+
+### 6. Approve or Reject
+
+**If APPROVED:**
+\`\`\`
+validate_task(task_id, approved: true, validation_notes: "Tests pass, code looks good")
+\`\`\`
+Then merge the PR and clean up:
+\`\`\`bash
+gh pr merge <PR_NUMBER> --squash
+cd ../project && git worktree remove ../project-validator-review
+\`\`\`
+
+**If REJECTED:**
+\`\`\`
+validate_task(
+  task_id,
+  approved: false,
+  validation_notes: "Tests failing in auth module",
+  create_fix_task: true  // Creates a fix task on the same branch
+)
+\`\`\`
+Then clean up your worktree - the fix agent will create their own.
+
+## Handling Merge Conflicts
+
+If \`claim_validation\` shows merge conflicts:
+1. Follow the \`rebase_instructions.steps\`
+2. Resolve conflicts in your editor
+3. Force push with \`--force-with-lease\`
+4. Call \`claim_validation\` again to verify
+
+Record git issues:
+\`\`\`
+add_git_issue(
+  project_id,
+  issue_type: "merge_conflict",
+  branch: "feature-branch",
+  target_branch: "develop",
+  task_id: task_id
+)
+\`\`\``,
+	},
+
+	git: {
+		title: 'Git Workflow',
+		content: `# Git Workflow
+
+## Supported Workflows
+
+| Workflow | Description |
+|----------|-------------|
+| \`none\` | No branching, direct commits |
+| \`trunk-based\` | Commit directly to main |
+| \`github-flow\` | Feature branches + PRs to main |
+| \`git-flow\` | Feature branches off develop, PRs to develop |
+
+Check your project's workflow:
+\`\`\`
+get_git_workflow(project_id)
+\`\`\`
+
+## Git Worktrees (CRITICAL)
+
+**For github-flow and git-flow projects, you MUST use worktrees.**
+
+### Rebase Before PR (MANDATORY)
+
+**Always rebase your branch before creating a PR.** This prevents overwrites of other agents' work.
+
+\`\`\`bash
+# Before creating PR, rebase onto latest base branch
+git fetch origin
+git rebase origin/develop  # or origin/main for github-flow
+# Resolve any conflicts
+git push --force-with-lease
+\`\`\`
+
+**Why?** Without rebasing, your branch may contain old versions of files that other agents modified. When merged, your old version overwrites their changes.
+
+### Why Worktrees?
+Multiple agents sharing one repo will conflict:
+- Switching branches affects all agents
+- Uncommitted changes collide
+- Direct commits create merge conflicts
+
+Worktrees give each task an isolated working directory.
+
+### Worktree Workflow
+
+**1. Create worktree BEFORE making any edits:**
+\`\`\`bash
+# Naming: ../PROJECT-PERSONA-short-description
+git worktree add ../Vibescope-Nova-add-login -b feature/abc123-add-login develop
+cd ../Vibescope-Nova-add-login
+\`\`\`
+
+**2. Report your location:**
+\`\`\`
+heartbeat(current_worktree_path: "../Vibescope-Nova-add-login")
+\`\`\`
+
+**3. Update the task:**
+\`\`\`
+update_task(
+  task_id,
+  status: "in_progress",
+  git_branch: "feature/abc123-add-login",
+  worktree_path: "../Vibescope-Nova-add-login"
+)
+\`\`\`
+
+**4. Do your work, commit, push, create PR**
+
+**5. Clean up IMMEDIATELY after opening PR:**
+\`\`\`bash
+cd ../Vibescope  # Return to main repo
+git worktree remove ../Vibescope-Nova-add-login
+\`\`\`
+Then clear the path:
+\`\`\`
+clear_worktree_path(task_id)
+\`\`\`
+
+### NO EXCEPTIONS
+
+Even for:
+- "Quick fixes" → Use a worktree
+- "Urgent hotfixes" → Use a worktree
+- "One line changes" → Use a worktree
+
+### Wrong vs Right Order
+
+**WRONG:**
+1. Edit files in main repo
+2. git stash
+3. Create worktree
+4. git stash pop
+
+**RIGHT:**
+1. Create worktree FIRST
+2. cd into worktree
+3. THEN edit files
+
+### Useful Commands
+
+| Command | Description |
+|---------|-------------|
+| \`git worktree list\` | List all worktrees |
+| \`git worktree add <path> -b <branch> <base>\` | Create worktree |
+| \`git worktree remove <path>\` | Remove worktree |
+| \`get_stale_worktrees(project_id)\` | Find orphaned worktrees |
+
+### Cleaning Stale Worktrees
+
+On session start, if \`stale_worktrees\` is returned:
+\`\`\`bash
+git worktree remove <path>
+\`\`\`
+Then:
+\`\`\`
+clear_worktree_path(task_id)
+\`\`\``,
+	},
+
+	deployment: {
+		title: 'Deployment Coordination',
+		content: `# Deployment Coordination
+
+## Deployment Flow
+
+1. **Request** → \`request_deployment(project_id)\`
+2. **Validate** → Build and test the deployment
+3. **Deploy** → Execute deployment
+4. **Complete** → Mark success/failure
+
+## Requesting Deployment
+
+\`\`\`
+request_deployment(
+  project_id,
+  environment: "production",     // development, staging, production
+  version_bump: "patch",         // patch, minor, major
+  git_ref: "main",               // Branch or commit
+  notes: "Bug fixes for auth"    // Optional
+)
+\`\`\`
+
+## Pre-Deployment Requirements
+
+Add requirements that must be completed before deploying:
+\`\`\`
+add_deployment_requirement(
+  project_id,
+  type: "migration",
+  title: "Run migration: add_user_roles",
+  description: "Run: pnpm db:migrate",
+  stage: "preparation"  // preparation, deployment, verification
+)
+\`\`\`
+
+Types: \`migration\`, \`env_var\`, \`config\`, \`manual\`, \`breaking_change\`, \`agent_task\`
+
+Check requirements:
+\`\`\`
+get_deployment_requirements(project_id)
+\`\`\`
+
+Complete them:
+\`\`\`
+complete_deployment_requirement(requirement_id)
+\`\`\`
+
+## Validating Deployment
+
+Claim for validation:
+\`\`\`
+claim_deployment_validation(project_id)
+\`\`\`
+
+Run build and tests, then report:
+\`\`\`
+report_validation(
+  project_id,
+  build_passed: true,
+  tests_passed: true
+)
+\`\`\`
+
+If validation fails, an investigation task is auto-created.
+
+## Executing Deployment
+
+Check status:
+\`\`\`
+check_deployment_status(project_id)
+\`\`\`
+
+When status is "ready":
+\`\`\`
+start_deployment(project_id)
+\`\`\`
+
+After deployment completes:
+\`\`\`
+complete_deployment(
+  project_id,
+  success: true,
+  summary: "Deployed v1.2.3 with auth fixes"
+)
+\`\`\`
+
+Or if it failed:
+\`\`\`
+complete_deployment(
+  project_id,
+  success: false,
+  summary: "Rollback due to database connection errors"
+)
+\`\`\`
+
+## Scheduled Deployments
+
+Schedule future deployments:
+\`\`\`
+schedule_deployment(
+  project_id,
+  scheduled_at: "2025-01-20T10:00:00Z",
+  schedule_type: "once",  // once, hourly, daily, weekly, monthly
+  auto_trigger: true      // Auto-deploy when due
+)
+\`\`\`
+
+Check due deployments:
+\`\`\`
+check_due_deployments(project_id)
+\`\`\`
+
+## Canceling
+
+\`\`\`
+cancel_deployment(project_id, reason: "Blocker found in staging")
+\`\`\``,
+	},
+
+	blockers: {
+		title: 'Handling Blockers',
+		content: `# Handling Blockers
+
+## Recording a Blocker
+
+When you can't proceed:
+\`\`\`
+add_blocker(
+  project_id,
+  description: "API endpoint returning 500 errors - need backend team to investigate"
+)
+\`\`\`
+
+## Viewing Blockers
+
+\`\`\`
+get_blockers(project_id)  // Open blockers
+get_blockers(project_id, status: "resolved")  // Resolved blockers
+get_blockers_stats(project_id)  // Just counts
+\`\`\`
+
+## Resolving Blockers
+
+\`\`\`
+resolve_blocker(
+  blocker_id,
+  resolution_note: "Backend team fixed the API - endpoint now returns correct data"
+)
+\`\`\`
+
+## What Counts as a Blocker?
+
+**IS a blocker:**
+- External dependency not available
+- Need access/credentials you don't have
+- Critical bug in a dependency
+- Waiting for human decision
+- Environment issue preventing testing
+
+**NOT a blocker:**
+- Need to learn something → research and continue
+- Code is complex → break it down with milestones
+- Tests failing → fix them
+- Merge conflicts → resolve them
+
+## Blocker Best Practices
+
+1. **Be specific** - Describe exactly what's blocked and why
+2. **Include context** - What were you trying to do?
+3. **Suggest solutions** - If you know what might help
+4. **Check existing blockers** - Don't duplicate
+5. **Resolve promptly** - When the issue is fixed, resolve the blocker`,
+	},
+
+	milestones: {
+		title: 'Task Milestones',
+		content: `# Task Milestones
+
+Milestones break down large tasks into trackable steps.
+
+## Adding Milestones
+
+\`\`\`
+add_milestone(task_id, title: "Design database schema")
+add_milestone(task_id, title: "Implement API endpoints")
+add_milestone(task_id, title: "Write unit tests")
+add_milestone(task_id, title: "Add integration tests")
+\`\`\`
+
+With order and description:
+\`\`\`
+add_milestone(
+  task_id,
+  title: "Set up authentication",
+  description: "Configure OAuth providers and session management",
+  order_index: 0
+)
+\`\`\`
+
+## Viewing Milestones
+
+\`\`\`
+get_milestones(task_id)
+\`\`\`
+
+Or include when getting task:
+\`\`\`
+get_task(task_id, include_milestones: true)
+\`\`\`
+
+## Updating Progress
+
+Mark milestone in progress:
+\`\`\`
+update_milestone(milestone_id, status: "in_progress")
+\`\`\`
+
+Complete a milestone:
+\`\`\`
+complete_milestone(milestone_id)
+\`\`\`
+
+## When to Use Milestones
+
+**Good candidates:**
+- Tasks estimated > 2 hours
+- Multi-step implementations
+- Features spanning multiple files/modules
+- Tasks with clear phases
+
+**Example breakdown:**
+
+Task: "Implement user authentication"
+1. Set up OAuth provider configuration
+2. Create login/logout API endpoints
+3. Implement session management
+4. Add protected route middleware
+5. Create login UI components
+6. Write tests
+
+## Milestones vs Subtasks
+
+| Milestones | Subtasks |
+|------------|----------|
+| Sequential steps | Parallel work items |
+| Same agent | Can be claimed by different agents |
+| Progress tracking | Delegation |
+| One at a time | Multiple in progress |
+
+Use **milestones** for ordered steps you'll do yourself.
+Use **subtasks** when work can be parallelized across agents.`,
+	},
+
+	fallback: {
+		title: 'Fallback Activities',
+		content: `# Fallback Activities
+
+When no tasks are available, agents can perform background activities.
+
+## Starting a Fallback Activity
+
+\`\`\`
+start_fallback_activity(project_id, activity: "code_review")
+\`\`\`
+
+## Available Activities
+
+| Activity | Description |
+|----------|-------------|
+| \`code_review\` | Review code quality, patterns, best practices |
+| \`security_review\` | Security audit, vulnerability scanning |
+| \`performance_audit\` | Performance analysis, optimization opportunities |
+| \`ux_review\` | UX/accessibility review |
+| \`test_coverage\` | Test coverage analysis, missing tests |
+| \`documentation_review\` | Documentation gaps, outdated docs |
+| \`dependency_audit\` | Dependency updates, vulnerabilities |
+| \`feature_ideation\` | Suggest improvements, new features |
+| \`validate_completed_tasks\` | Review tasks awaiting validation |
+| \`worktree_cleanup\` | Clean up stale worktrees |
+
+## Recording Findings
+
+During activities, record findings:
+\`\`\`
+add_finding(
+  project_id,
+  title: "SQL injection risk in user search",
+  category: "security",       // security, performance, code_quality, etc.
+  severity: "high",           // info, low, medium, high, critical
+  description: "User input passed directly to query without sanitization",
+  file_path: "src/api/users.ts",
+  line_number: 45
+)
+\`\`\`
+
+## Recording Ideas
+
+For feature suggestions:
+\`\`\`
+add_idea(
+  project_id,
+  title: "Add rate limiting to API",
+  description: "Protect against abuse by adding rate limits per user/IP"
+)
+\`\`\`
+
+## Stopping Activities
+
+Activities auto-stop when you start a task. Manual stop:
+\`\`\`
+stop_fallback_activity(project_id, summary: "Reviewed 5 files, found 2 issues")
+\`\`\`
+
+## Activity History
+
+\`\`\`
+get_activity_history(project_id)
+\`\`\`
+
+## Project Settings
+
+Projects can restrict fallback activities:
+\`\`\`
+update_project(
+  project_id,
+  fallback_activities_enabled: true,
+  preferred_fallback_activities: ["code_review", "security_review"]
+)
+\`\`\``,
+	},
+
+	tokens: {
+		title: 'Token Usage & Cost Tracking',
+		content: `# Token Usage & Cost Tracking
+
+## Checking Usage
+
+\`\`\`
+get_token_usage()
+\`\`\`
+
+Returns:
+- Session stats (calls, tokens, avg per call)
+- Top tools by token usage
+- Model breakdown (input/output tokens)
+- Estimated costs
+
+## Reporting Actual Usage
+
+MCP estimates are only ~1-5% of actual API usage. For accurate tracking:
+
+\`\`\`
+report_token_usage(
+  input_tokens: 1500,
+  output_tokens: 500,
+  model: "opus"  // or sonnet, haiku
+)
+\`\`\`
+
+Call this after each API response using values from the response headers:
+- \`usage.input_tokens\`
+- \`usage.output_tokens\`
+
+## Model Pricing
+
+| Model | Input (per 1M) | Output (per 1M) |
+|-------|---------------|-----------------|
+| Opus | $15.00 | $75.00 |
+| Sonnet | $3.00 | $15.00 |
+| Haiku | $0.25 | $1.25 |
+
+## Cost Monitoring
+
+Get cost summary:
+\`\`\`
+get_cost_summary(project_id, period: "daily")  // daily, weekly, monthly
+\`\`\`
+
+Set up alerts:
+\`\`\`
+add_cost_alert(
+  project_id,
+  threshold_amount: 100,      // USD
+  threshold_period: "daily",
+  alert_type: "warning"       // warning, critical
+)
+\`\`\`
+
+## Context Management
+
+When token usage is high:
+1. Check with \`get_token_usage()\`
+2. If 50+ calls or 100k+ tokens: \`/clear\`
+3. Immediately call \`start_work_session()\`
+4. Continue with \`next_task\`
+
+**Don't ask permission** - just clear and continue.
+
+## Efficiency Tips
+
+1. **Use lite mode** (default) - saves ~85% tokens on session start
+2. **Batch updates** - Use \`batch_update_tasks\` when updating multiple
+3. **Use stats endpoints** - \`get_task_stats\` instead of listing all tasks
+4. **Clear context regularly** - Don't let it grow unbounded`,
+	},
+
+	sprints: {
+		title: 'Sprint Management',
+		content: `# Sprint Management
+
+Sprints are time-bounded work periods with velocity tracking.
+
+## Creating a Sprint
+
+\`\`\`
+create_sprint(
+  project_id,
+  title: "Sprint 5",
+  start_date: "2025-01-20",
+  end_date: "2025-02-03",
+  goal: "Complete authentication and user profile features"
+)
+\`\`\`
+
+## Sprint Lifecycle
+
+1. **Planning** → Add tasks, assign story points
+2. **Active** → Work on tasks
+3. **In Review** → Review completed work
+4. **Retrospective** → Reflect on sprint
+5. **Completed** → Archive with metrics
+
+## Adding Tasks to Sprint
+
+\`\`\`
+add_task_to_sprint(
+  sprint_id,
+  task_id,
+  story_points: 3,
+  phase: "core"  // pre, core, post
+)
+\`\`\`
+
+## Starting a Sprint
+
+\`\`\`
+start_sprint(sprint_id)
+\`\`\`
+
+This locks \`committed_points\` at the current total.
+
+## Getting Sprint Backlog
+
+Tasks available to add:
+\`\`\`
+get_sprint_backlog(project_id, sprint_id)
+\`\`\`
+
+## Sprint Progress
+
+\`\`\`
+get_sprint(sprint_id)
+\`\`\`
+
+With just counts (saves tokens):
+\`\`\`
+get_sprint(sprint_id, summary_only: true)
+\`\`\`
+
+## Completing a Sprint
+
+\`\`\`
+complete_sprint(
+  sprint_id,
+  retrospective_notes: "Completed 80% of planned work. Auth took longer than expected.",
+  skip_retrospective: false
+)
+\`\`\`
+
+## Velocity Tracking
+
+\`\`\`
+get_sprint_velocity(project_id, limit: 10)
+\`\`\`
+
+Returns:
+- Committed vs completed points per sprint
+- Average velocity
+- Trend analysis`,
+	},
+
+	topics: {
+		title: 'Available Help Topics',
+		content: `# Available Help Topics
+
+Use \`get_help(topic)\` for detailed guidance on any topic.
+
+## Core Topics
+
+| Topic | Description |
+|-------|-------------|
+| \`getting_started\` | Quick start guide, core workflow |
+| \`session\` | Session lifecycle, heartbeats, context management |
+| \`tasks\` | Task management, progress tracking, completion |
+| \`validation\` | Cross-agent task validation workflow |
+| \`git\` | Git workflows, worktrees, branch management |
+| \`deployment\` | Deployment coordination, requirements |
+
+## Task Organization
+
+| Topic | Description |
+|-------|-------------|
+| \`milestones\` | Breaking down complex tasks into steps |
+| \`subtasks\` | Parallelizable task breakdown |
+| \`bodies_of_work\` | Group related tasks into phases |
+| \`sprints\` | Time-bounded sprints with velocity tracking |
+
+## Collaboration
+
+| Topic | Description |
+|-------|-------------|
+| \`roles\` | Agent roles and specialization |
+| \`file_locks\` | Multi-agent file coordination |
+| \`git_issues\` | Git conflict and issue tracking |
+| \`requests\` | Handle user questions from dashboard |
+
+## Knowledge & Tracking
+
+| Topic | Description |
+|-------|-------------|
+| \`blockers\` | Recording and resolving blockers |
+| \`knowledge\` | Project knowledge base |
+| \`ideas\` | Feature ideas and requests |
+| \`tokens\` | Token usage and cost tracking |
+| \`fallback\` | Background activities when idle |
+| \`connectors\` | External integrations (Slack, webhooks) |
+
+## Quick Examples
+
+\`\`\`
+get_help("getting_started")  // New to Vibescope? Start here
+get_help("git")              // Git worktree workflow
+get_help("validation")       // How to validate tasks
+get_help("session")          // Session management
+get_help("bodies_of_work")   // Organizing related tasks
+\`\`\``,
+	},
+
+	roles: {
+		title: 'Agent Roles',
+		content: `# Agent Roles
+
+Roles specialize agents for different types of work.
+
+## Available Roles
+
+| Role | Description |
+|------|-------------|
+| \`developer\` | General development work (default) |
+| \`validator\` | Reviews and validates completed tasks |
+| \`deployer\` | Handles deployments |
+| \`reviewer\` | Code review focus |
+| \`maintainer\` | Housekeeping and maintenance |
+
+## Setting Your Role
+
+At session start:
+\`\`\`
+start_work_session(git_url, model, role: "validator")
+\`\`\`
+
+Or mid-session:
+\`\`\`
+set_session_role(role: "validator")
+\`\`\`
+
+## Role Configuration
+
+View project role settings:
+\`\`\`
+get_role_settings(project_id)
+\`\`\`
+
+Configure role behavior:
+\`\`\`
+update_role_settings(
+  project_id,
+  role: "validator",
+  enabled: true,
+  auto_assign_validation: true,
+  fallback_activities: ["code_review", "security_review"]
+)
+\`\`\`
+
+## Viewing Agents by Role
+
+\`\`\`
+get_agents_by_role(project_id)
+\`\`\`
+
+With counts only (saves tokens):
+\`\`\`
+get_agents_by_role(project_id, counts_only: true)
+\`\`\`
+
+## Role-Specific Workflows
+
+**Developer:**
+- Gets tasks via \`get_next_task\`
+- Creates PRs
+- Calls \`complete_task\`
+
+**Validator:**
+- Gets tasks via \`get_tasks_awaiting_validation\`
+- Reviews code, runs tests
+- Approves/rejects via \`validate_task\`
+- Merges PRs on approval
+
+**Deployer:**
+- Checks \`check_deployment_status\`
+- Validates deployments
+- Executes deployments
+- Handles rollbacks`,
+	},
+
+	knowledge: {
+		title: 'Project Knowledge Base',
+		content: `# Project Knowledge Base
+
+Query aggregated project knowledge efficiently.
+
+## Querying Knowledge
+
+\`\`\`
+query_knowledge_base(
+  project_id,
+  categories: ["findings", "decisions", "completed_tasks"],
+  scope: "summary",  // summary or detailed
+  limit: 10,
+  search_query: "authentication"
+)
+\`\`\`
+
+## Categories
+
+| Category | Description |
+|----------|-------------|
+| \`findings\` | Audit findings, code issues |
+| \`qa\` | Questions and answers |
+| \`decisions\` | Architectural decisions |
+| \`completed_tasks\` | Recently completed work |
+| \`blockers\` | Resolved blockers |
+| \`progress\` | Progress updates |
+
+## Recording Knowledge
+
+### Findings
+\`\`\`
+add_finding(
+  project_id,
+  title: "N+1 query in user list",
+  category: "performance",
+  severity: "medium",
+  description: "User list makes N+1 queries for profile images",
+  file_path: "src/api/users.ts"
+)
+\`\`\`
+
+### Decisions
+\`\`\`
+log_decision(
+  project_id,
+  title: "Use PostgreSQL for database",
+  description: "Selected PostgreSQL over MongoDB",
+  rationale: "Better support for complex queries and transactions",
+  alternatives_considered: ["MongoDB", "MySQL"]
+)
+\`\`\`
+
+### Ideas
+\`\`\`
+add_idea(
+  project_id,
+  title: "Add caching layer",
+  description: "Redis cache for frequently accessed data",
+  status: "raw"  // raw, exploring, planned, in_development, shipped
+)
+\`\`\`
+
+## Efficiency
+
+Use \`query_knowledge_base\` instead of multiple separate calls:
+- Single call returns aggregated data
+- Filter by category to reduce response size
+- Use \`summary\` scope for token efficiency`,
+	},
+
+	bodies_of_work: {
+		title: 'Bodies of Work',
+		content: `# Bodies of Work
+
+Bodies of work group related tasks into phases for coordinated execution.
+
+## Creating a Body of Work
+
+\`\`\`
+create_body_of_work(
+  project_id,
+  title: "User Authentication Feature",
+  description: "Complete auth system with OAuth support",
+  auto_deploy_on_completion: true,
+  deploy_version_bump: "minor"
+)
+\`\`\`
+
+## Task Phases
+
+Tasks are organized into three phases:
+- **pre** - Setup, migrations, dependencies
+- **core** - Main implementation work
+- **post** - Cleanup, documentation, verification
+
+## Adding Tasks
+
+\`\`\`
+add_task_to_body_of_work(
+  body_of_work_id,
+  task_id,
+  phase: "core"  // pre, core, post
+)
+\`\`\`
+
+## Task Dependencies
+
+Create dependencies between tasks:
+\`\`\`
+add_task_dependency(
+  body_of_work_id,
+  task_id: "frontend-task",
+  depends_on_task_id: "api-task"
+)
+\`\`\`
+
+The dependent task won't be available until its dependencies are complete.
+
+## Activating
+
+Bodies of work start in "draft" status. Activate to begin:
+\`\`\`
+activate_body_of_work(body_of_work_id)
+\`\`\`
+
+## Getting Next Task
+
+\`\`\`
+get_next_body_of_work_task(body_of_work_id)
+\`\`\`
+
+Returns the next available task considering:
+- Phase order (pre → core → post)
+- Task dependencies
+- Task status
+
+## Viewing Bodies of Work
+
+\`\`\`
+get_body_of_work(body_of_work_id)  // Single BOW with tasks
+get_bodies_of_work(project_id)     // All BOWs for project
+\`\`\`
+
+## Auto-Deployment
+
+If \`auto_deploy_on_completion: true\`, a deployment is automatically requested when all tasks complete.
+
+Configure the trigger:
+- \`all_completed\` - Deploy immediately when all tasks done
+- \`all_completed_validated\` - Wait for validation first`,
+	},
+
+	subtasks: {
+		title: 'Subtasks',
+		content: `# Subtasks
+
+Subtasks break down larger tasks into smaller, parallelizable pieces.
+
+## Adding Subtasks
+
+\`\`\`
+add_subtask(
+  parent_task_id,
+  title: "Implement login form UI",
+  description: "Create React component for login form",
+  priority: 2,
+  estimated_minutes: 60
+)
+\`\`\`
+
+## Viewing Subtasks
+
+\`\`\`
+get_subtasks(parent_task_id)
+\`\`\`
+
+Or include when getting task:
+\`\`\`
+get_task(task_id, include_subtasks: true)
+\`\`\`
+
+## Working on Subtasks
+
+Subtasks work just like regular tasks:
+\`\`\`
+update_task(subtask_id, status: "in_progress")
+complete_task(subtask_id, summary: "Completed login form")
+\`\`\`
+
+## Subtasks vs Milestones
+
+| Subtasks | Milestones |
+|----------|------------|
+| Independent units of work | Sequential steps |
+| Can be claimed by any agent | Same agent completes all |
+| Parallel execution | One at a time |
+| Full task lifecycle | Simple status tracking |
+
+**Use subtasks when:**
+- Work can be done in parallel by multiple agents
+- Each piece is independent and self-contained
+- You want to delegate work
+
+**Use milestones when:**
+- Steps must be done in order
+- Same person does all steps
+- Just need progress tracking
+
+## Constraints
+
+- Max depth is 1 (subtasks cannot have their own subtasks)
+- Subtasks inherit project from parent task
+- Parent task completion is independent of subtasks`,
+	},
+
+	file_locks: {
+		title: 'File Locking',
+		content: `# File Locking (Multi-Agent Coordination)
+
+Prevent conflicts when multiple agents work on the same files.
+
+## Checking Availability
+
+Before editing a file:
+\`\`\`
+is_file_available(project_id, file_path: "src/api/users.ts")
+\`\`\`
+
+Returns whether the file is free or who has it locked.
+
+## Checking Out Files
+
+Lock a file before editing:
+\`\`\`
+checkout_file(
+  project_id,
+  file_path: "src/api/users.ts",
+  reason: "Fixing authentication bug"
+)
+\`\`\`
+
+## Checking In Files
+
+Release the file when done:
+\`\`\`
+checkin_file(
+  checkout_id,
+  summary: "Fixed token validation logic"
+)
+\`\`\`
+
+Or by path:
+\`\`\`
+checkin_file(
+  project_id,
+  file_path: "src/api/users.ts",
+  summary: "Fixed token validation logic"
+)
+\`\`\`
+
+## Viewing Checkouts
+
+\`\`\`
+get_file_checkouts(project_id)                  // Active checkouts
+get_file_checkouts(project_id, status: "checked_in")  // Completed
+get_file_checkouts_stats(project_id)            // Just counts
+\`\`\`
+
+## Handling Abandoned Locks
+
+If an agent session dies with a file locked:
+\`\`\`
+abandon_checkout(
+  checkout_id,
+  reason: "Agent session terminated"
+)
+\`\`\`
+
+## Best Practices
+
+1. **Always check availability** before editing shared files
+2. **Keep locks short** - check in as soon as you're done
+3. **Use meaningful reasons** - helps others understand why file is locked
+4. **Check in even if no changes** - releases the lock for others
+5. **Use worktrees** - provides file isolation, reducing need for locks`,
+	},
+
+	connectors: {
+		title: 'External Connectors',
+		content: `# External Connectors
+
+Connectors enable sending events to external services.
+
+## Supported Types
+
+| Type | Description |
+|------|-------------|
+| \`webhook\` | Generic HTTP webhook |
+| \`slack\` | Slack notifications |
+| \`discord\` | Discord notifications |
+| \`github\` | GitHub integration |
+| \`custom\` | Custom connector |
+
+## Adding a Connector
+
+Slack example:
+\`\`\`
+add_connector(
+  project_id,
+  name: "Slack Notifications",
+  type: "slack",
+  config: { webhook_url: "https://hooks.slack.com/..." },
+  events: {
+    task_completed: true,
+    blocker_added: true,
+    deployment_started: true
+  }
+)
+\`\`\`
+
+Webhook example:
+\`\`\`
+add_connector(
+  project_id,
+  name: "CI/CD Webhook",
+  type: "webhook",
+  config: {
+    url: "https://ci.example.com/webhook",
+    headers: { "X-API-Key": "secret" }
+  },
+  events: { deployment_completed: true }
+)
+\`\`\`
+
+## Available Events
+
+- \`task_completed\` - Task marked done
+- \`task_validated\` - Task approved/rejected
+- \`blocker_added\` - New blocker recorded
+- \`blocker_resolved\` - Blocker resolved
+- \`deployment_started\` - Deployment began
+- \`deployment_completed\` - Deployment finished
+- \`agent_session_started\` - Agent connected
+- \`agent_session_ended\` - Agent disconnected
+
+## Managing Connectors
+
+\`\`\`
+get_connectors(project_id)           // List all
+get_connector(connector_id)          // Get details
+update_connector(connector_id, ...)  // Update config
+delete_connector(connector_id)       // Remove
+\`\`\`
+
+## Testing
+
+\`\`\`
+test_connector(connector_id)
+\`\`\`
+
+Sends a test event and returns success/failure.
+
+## Event History
+
+\`\`\`
+get_connector_events(connector_id)
+get_connector_events(project_id)  // All connectors
+\`\`\``,
+	},
+
+	git_issues: {
+		title: 'Git Issues',
+		content: `# Git Issues
+
+Track and resolve git-related problems.
+
+## Issue Types
+
+| Type | Description |
+|------|-------------|
+| \`merge_conflict\` | Conflicting changes |
+| \`push_failed\` | Push rejected |
+| \`rebase_needed\` | Branch needs rebase |
+| \`branch_diverged\` | Branch diverged from base |
+| \`pr_not_mergeable\` | PR cannot be merged |
+
+## Recording Issues
+
+\`\`\`
+add_git_issue(
+  project_id,
+  issue_type: "merge_conflict",
+  branch: "feature/add-auth",
+  target_branch: "develop",
+  conflicting_files: ["src/api/users.ts", "src/models/user.ts"],
+  task_id: "task-uuid",  // Optional
+  error_message: "Automatic merge failed"
+)
+\`\`\`
+
+## Viewing Issues
+
+\`\`\`
+get_git_issues(project_id)                        // Open issues
+get_git_issues(project_id, status: "resolved")    // Resolved
+get_git_issues(project_id, branch: "feature/x")   // By branch
+get_git_issues(project_id, issue_type: "merge_conflict")  // By type
+\`\`\`
+
+## Resolving Issues
+
+\`\`\`
+resolve_git_issue(
+  git_issue_id,
+  resolution_note: "Rebased branch and resolved conflicts manually"
+)
+\`\`\`
+
+Auto-resolved (e.g., PR became mergeable):
+\`\`\`
+resolve_git_issue(
+  git_issue_id,
+  auto_resolved: true,
+  resolution_note: "PR automatically became mergeable after upstream merge"
+)
+\`\`\`
+
+## Handling Merge Conflicts
+
+1. **Fetch latest changes:**
+   \`\`\`bash
+   git fetch origin
+   \`\`\`
+
+2. **Rebase on target:**
+   \`\`\`bash
+   git rebase origin/develop
+   \`\`\`
+
+3. **Resolve conflicts in editor**
+
+4. **Continue rebase:**
+   \`\`\`bash
+   git add .
+   git rebase --continue
+   \`\`\`
+
+5. **Force push:**
+   \`\`\`bash
+   git push --force-with-lease
+   \`\`\`
+
+6. **Resolve the issue:**
+   \`\`\`
+   resolve_git_issue(git_issue_id, resolution_note: "Rebased and resolved")
+   \`\`\``,
+	},
+
+	ideas: {
+		title: 'Ideas & Feature Requests',
+		content: `# Ideas & Feature Requests
+
+Track improvement ideas and feature requests.
+
+## Adding Ideas
+
+\`\`\`
+add_idea(
+  project_id,
+  title: "Add dark mode support",
+  description: "Implement theme switching with dark mode option",
+  status: "raw"  // Default status
+)
+\`\`\`
+
+## Idea Lifecycle
+
+| Status | Description |
+|--------|-------------|
+| \`raw\` | Initial idea, not yet evaluated |
+| \`exploring\` | Being researched/discussed |
+| \`planned\` | Approved for implementation |
+| \`in_development\` | Being worked on |
+| \`shipped\` | Completed and deployed |
+
+## Updating Ideas
+
+\`\`\`
+update_idea(
+  idea_id,
+  status: "planned",
+  doc_url: "https://docs.example.com/dark-mode-spec"
+)
+\`\`\`
+
+## Converting to Task
+
+When ready to implement:
+\`\`\`
+convert_idea_to_task(
+  idea_id,
+  priority: 2,
+  estimated_minutes: 120,
+  update_status: true  // Sets idea to "in_development"
+)
+\`\`\`
+
+This creates a task linked to the idea.
+
+## Viewing Ideas
+
+\`\`\`
+get_ideas(project_id)                          // All ideas
+get_ideas(project_id, status: "planned")       // Ready to build
+get_ideas(project_id, search_query: "dark")    // Search
+get_idea(idea_id)                              // Single idea
+\`\`\`
+
+## Best Practices
+
+1. **Capture ideas immediately** - Don't lose them
+2. **Be specific** - Include context and rationale
+3. **Link documentation** - Add doc_url when available
+4. **Update status** - Keep ideas current
+5. **Convert when ready** - Move to tasks for execution`,
+	},
+
+	requests: {
+		title: 'User Requests',
+		content: `# User Requests
+
+Handle questions and requests from users via the dashboard.
+
+## Checking for Requests
+
+Requests are included in \`start_work_session\` response:
+- \`pending_requests\` - Array of unanswered requests
+- \`URGENT_QUESTIONS\` - High-priority questions
+
+## Getting Pending Requests
+
+\`\`\`
+get_pending_requests(project_id)
+\`\`\`
+
+## Answering Questions
+
+\`\`\`
+answer_question(
+  request_id,
+  answer: "The authentication flow uses JWT tokens stored in httpOnly cookies. Tokens expire after 24 hours and are automatically refreshed."
+)
+\`\`\`
+
+## Acknowledging Requests
+
+For non-question requests:
+\`\`\`
+acknowledge_request(request_id)
+\`\`\`
+
+## Priority
+
+When \`start_work_session\` returns pending requests:
+1. Answer questions FIRST (before starting tasks)
+2. \`URGENT_QUESTIONS\` take absolute priority
+3. Then proceed with \`next_task\`
+
+## Best Practices
+
+1. **Check requests early** - Answer before deep work
+2. **Be thorough** - Provide complete answers
+3. **Include context** - Reference code/docs when helpful
+4. **Acknowledge promptly** - Don't leave users waiting`,
+	},
+};
+
+/**
+ * Get fallback help content for a topic
+ * @param topic The help topic slug
+ * @returns The help content or null if topic not found
+ */
+export function getFallbackHelpContent(topic: string): { title: string; content: string } | null {
+	return HELP_TOPICS[topic] || null;
+}
+
+/**
+ * Get list of available help topics
+ * @returns Array of topic slugs
+ */
+export function getAvailableHelpTopics(): string[] {
+	return Object.keys(HELP_TOPICS);
+}