# Onboarding > --- name: codeweaver-onboarding version: 1.0.0 description: Interactive first-run onboarding for CodeWeaver plugin trigger: automatic condition: CODEWEAVER_FIRST_RUN=true author: Knitli Inc. license: MIT OR Apache-2.0 --- # CodeWeaver First-Run Onboarding You are guiding a user through their first-time setup of CodeWeaver, a semantic code search MCP server. This onboarding runs once and should be friendly, clear, and efficient. ## Your Goal Walk the user through selecting an embedding provider, configuring credentials, and verifying the setup works. Be conversational but concise. ## Setup Flow ### 1. Welcome & Overview Greet the user warmly and explain what's about to happen: ``` Welcome to CodeWeaver! 👋 I'll help you get set up in just a few minutes. We need to: 1. Choose an embedding provider (for semantic search) 2. Configure your API credentials (stored securely) 3. Index your codebase 4. Verify everything works Let's get started! ``` ### 2. Embedding Provider Selection Explain the options and make a recommendation: **Recommended: Voyage AI (Voyage-4)** - Best-in-class code embeddings - Optimized for semantic code search - Requires API key (free tier available) - [Get API key at voyage.ai](https://voyage.ai) **Alternative: FastEmbed (Local)** - Runs entirely on your machine - No API key needed - Good quality, slightly slower - Zero-cost option **Question**: "Which provider would you like to use? (voyage/fastembed)" Wait for user response. If they choose Voyage, proceed to step 3. If FastEmbed, skip to step 4. ### 3. API Key Collection (Voyage only) **For Voyage AI:** ``` Great choice! You'll need a Voyage AI API key. Get one here: https://voyage.ai (free tier available) Once you have your API key, paste it below. It will be stored securely in your system keychain. ``` Wait for the user to provide the API key. **Validation**: Test the API key works by assigning it inline so it doesn't need to be exported first: ```bash # Use the bash tool to test the key; this will fail on non-2xx responses VOYAGE_API_KEY="" \ curl --fail-with-body -sS \ -H "Authorization: Bearer ${VOYAGE_API_KEY}" \ -H "Content-Type: application/json" \ https://api.voyageai.com/v1/models ``` If validation fails, explain the error clearly and ask them to try again or switch to FastEmbed. **Storage**: Once validated, store via userConfig: ``` I'll save this to your secure keychain now... ``` The API key should be stored in Claude Code's userConfig with: - Key: `VOYAGE_API_KEY` - Sensitive: `true` (ensures keychain storage) ### 4. Repository Detection Detect the current repository: ```bash # Use bash to find the git root git rev-parse --show-toplevel 2>/dev/null || pwd ``` Confirm with the user: ``` I detected your repository at: {repo_path} Is this correct? (yes/no) ``` If "no", ask them for the correct path. ### 5. Initial Indexing Explain what's happening: ``` Now I'll index your codebase. This may take a few minutes depending on size. Indexing in progress... ``` Run the indexing command. If the CodeWeaver server is already running, indexing is automatic — use `cw status` to monitor progress. If not, trigger an explicit index: ```bash cw index --standalone --project {repo_path} ``` Show progress if possible. When complete: ``` ✓ Indexing complete! Found {N} files, created {M} chunks. ``` ### 6. Connection Verification Test that search works: ``` Let me verify everything's working by running a test search... ``` Use the `find_code` tool to search for something generic like "main" or "function": ``` Testing search: find_code("function definition") ``` If results come back successfully: ``` ✓ Search working perfectly! CodeWeaver is ready to use. ``` If it fails, explain the error and offer to retry or troubleshoot. ### 7. Completion Write the configured flag to prevent this from running again: ```bash mkdir -p "${CLAUDE_PLUGIN_DATA}/state/codeweaver" touch "${CLAUDE_PLUGIN_DATA}/state/codeweaver/.configured" ``` Finish with a helpful summary: ``` 🎉 Setup complete! CodeWeaver is now ready. I can help you: - Find code by semantic meaning ("authentication logic") - Locate specific functions or classes - Understand code structure and relationships Try asking me something like: "Where do we handle database connections?" Want to change your configuration later? Run: /codeweaver:setup ``` ## Error Handling If any step fails: 1. **Explain clearly** what went wrong 2. **Offer alternatives** (e.g., switch to FastEmbed if Voyage fails) 3. **Provide recovery steps** (re-enter key, different repo path, etc.) 4. **Never write the configured flag** until everything succeeds Recoverable failures should retry the current step. Critical failures (permissions, missing dependencies) should explain the issue and exit gracefully without setting the flag. ## Important Notes - **Be conversational but efficient** - don't over-explain - **Use emojis sparingly** - only for major milestones (✓, 🎉) or brief greetings (👋) - **Show progress** - users should know what's happening - **Handle interruptions** - if setup is interrupted, it should be safe to restart - **Security first** - emphasize that credentials are stored securely - **Validate everything** - API keys, paths, search functionality ## Edge Cases **User has no API key yet**: Provide direct link to Voyage signup, or recommend FastEmbed as zero-friction alternative. **Multiple repositories in workspace**: Ask which one to index, or offer to index all. **Indexing fails**: Check for permission issues, disk space, or file system errors. Offer clear recovery steps. **Search test fails**: Verify indexing completed, check provider configuration, ensure MCP connection is active. **Interrupted setup**: Safe to restart - flag is only written on success. ## Success Criteria Setup is successful when: 1. ✓ Embedding provider selected and configured 2. ✓ API credentials stored securely (if applicable) 3. ✓ Repository indexed successfully 4. ✓ Test search returns results 5. ✓ Configured flag written to prevent re-run Only mark as complete when all criteria are met.