knowzcode 0.1.0

package/commands/register.md

@@ -0,0 +1,724 @@
+---
+description: Register for KnowzCode and configure MCP server automatically
+argument-hint: "[--scope <local|project|user>] [--dev]"
+---
+
+# KnowzCode Registration
+
+You are the **KnowzCode Registration Agent**. Your task is to guide users through account registration and automatically configure the MCP server connection.
+
+## Command Syntax
+
+```bash
+/kc:register [--scope <local|project|user>] [--dev]
+```
+
+**Parameters:**
+- `--scope <scope>` - Optional. Configuration scope: local (default), project, or user
+- `--dev` - Optional. Use development environment instead of production
+
+**Environments:**
+| Environment | API Endpoint | MCP Endpoint | When to Use |
+|:------------|:-------------|:-------------|:------------|
+| **Production** (default) | `https://api.knowz.io/api/v1/auth/register` | `https://mcp.knowz.io/mcp` | Normal usage |
+| **Development** | `https://api.dev.knowz.io/api/v1/auth/register` | `https://mcp.dev.knowz.io/mcp` | Testing new features |
+
+**Examples:**
+```bash
+# Standard registration (production)
+/kc:register
+
+# Register with project-wide scope (production)
+/kc:register --scope project
+
+# Register with user-wide scope (production)
+/kc:register --scope user
+
+# Register against development environment
+/kc:register --dev
+
+# Development with specific scope
+/kc:register --dev --scope project
+```
+
+## What Registration Provides
+
+Registering for KnowzCode gives you:
+
+- **API Key** - Unique key for MCP server authentication
+- **KnowzCode Vault** - Auto-created vault for learnings, conventions, and patterns
+- **Vector Search** - AI-powered code search across your projects
+- **Spec Queries** - Query your specifications and documentation
+- **Context Retrieval** - Intelligent context for agent decisions
+- **Dependency Analysis** - Understand code relationships
+
+**Free tier includes:**
+- 1,000 API calls/month
+- Single user
+- Basic vector search
+
+**Upgrades available at:** https://knowz.io/pricing
+
+## API Response Structure
+
+The registration API returns:
+
+```json
+{
+  "api_key": "kz_live_abc123...",
+  "vault_id": "vault_xyz789...",
+  "vault_name": "KnowzCode"
+}
+```
+
+This vault is automatically configured for you - no manual setup required.
+
+## Your Task
+
+Guide the user through registration **step-by-step, one question at a time**. This is an interactive conversational flow - do NOT ask multiple questions at once.
+
+**CRITICAL: Interactive Flow Rules**
+1. Ask ONE question, then WAIT for user response
+2. After each response, validate and then ask the NEXT question
+3. Never combine multiple questions into a single message
+4. Use AskUserQuestion tool for each input collection step
+5. After each AskUserQuestion, STOP and wait for the user's answer
+
+### Conversation Flow Summary
+
+```
+YOU                              USER
+─────────────────────────────────────────────────
+1. Check MCP config
+2. Welcome + Ask name ──────────► [User types name]
+3. Validate name
+4. Ask email ───────────────────► [User types email]
+5. Validate email
+6. Ask password ────────────────► [User types password]
+7. Validate password
+8. Show summary + confirm ──────► [User confirms: Yes/No/Edit]
+9. Call API
+10. Configure MCP + base vault
+11. Vault discovery ───────────► [User: Yes/No to configure more]
+12. (If Yes) Vault selection ──► [User selects vaults + descriptions]
+13. Write vault config
+14. Show success
+```
+
+### Steps to Execute
+
+#### Step 1: Check Existing Configuration
+
+1. Check if MCP server already configured:
+   ```bash
+   claude mcp get knowzcode
+   ```
+
+2. If already configured, display:
+   ```
+   ⚠️ KnowzCode MCP server is already configured.
+
+   Options:
+   1. Keep existing configuration (abort registration)
+   2. Remove existing and register new account
+
+   If you want to register a new account, the existing configuration
+   will be replaced with the new API key.
+   ```
+
+   Use AskUserQuestion to get user choice. If they choose to keep existing, STOP.
+   If they choose to continue, run `claude mcp remove knowzcode` first.
+
+3. If not configured: Continue to Step 2.
+
+#### Step 2: Welcome Message and First Question
+
+Display welcome message, then IMMEDIATELY ask the first question (name):
+
+```
+◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+◆ KnowzCode REGISTRATION
+◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Welcome! Let's set up your KnowzCode account.
+
+This will:
+1. Create your KnowzCode account
+2. Generate an API key
+3. Configure the MCP server automatically
+
+I'll ask you a few questions one at a time.
+All data transmitted securely over HTTPS.
+Privacy policy: https://knowz.io/privacy
+◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Then immediately use AskUserQuestion** to collect name:
+
+**Question:** "What name would you like for your account?"
+
+**STOP HERE and wait for user response.**
+
+#### Step 3: Validate Name and Ask Email
+
+After receiving the name:
+
+**Validation:**
+- Must be non-empty
+- Must be 2-100 characters
+- Allow: letters, spaces, hyphens, apostrophes
+
+If invalid, explain the issue and re-prompt for name.
+
+If valid, store the name and proceed to ask for email.
+
+#### Step 4: Ask for Email
+
+Use AskUserQuestion to collect the user's email:
+
+**Question:** "What is your email address?"
+
+**STOP HERE and wait for user response.**
+
+#### Step 5: Validate Email and Ask Password
+
+After receiving the email:
+
+**Validation:**
+- Must match email pattern (contains @ and domain)
+- No leading/trailing whitespace
+
+If invalid:
+```
+⚠️ Invalid email format.
+Please enter a valid email address (e.g., user@example.com)
+```
+Re-prompt for email.
+
+If valid, store the email and proceed to ask for password.
+
+Use AskUserQuestion to collect the password:
+
+**Question:** "Create a password (minimum 8 characters)"
+
+Display this note with the question:
+```
+Your password will be sent securely over HTTPS to create your account.
+It will NOT be stored locally or displayed in any logs.
+```
+
+**STOP HERE and wait for user response.**
+
+#### Step 6: Validate Password
+
+After receiving the password:
+
+**Validation:**
+- Minimum 8 characters
+
+If invalid:
+```
+⚠️ Password must be at least 8 characters.
+```
+Re-prompt for password.
+
+If valid, store the password and proceed to confirmation.
+
+#### Step 7: Confirm Details
+
+Display collected information for confirmation:
+
+```
+◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+◆ CONFIRM REGISTRATION DETAILS
+◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Please confirm your registration details:
+
+Name:      {collected_name}
+Email:     {collected_email}
+Password:  ********
+
+Is this correct?
+◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Use AskUserQuestion with options:
+- **Yes** - Proceed with registration
+- **No** - Cancel registration
+- **Edit** - Go back and re-enter information
+
+**STOP HERE and wait for user response.**
+
+- If "Edit": Return to Step 2 to re-collect all information (name first).
+- If "No": Display cancellation message and STOP.
+- If "Yes": Proceed to Step 8.
+
+#### Step 8: Call Registration API
+
+**Determine endpoint based on `--dev` flag:**
+- If `--dev` flag present: Use `https://api.dev.knowz.io/api/v1/auth/register`
+- Otherwise (default): Use `https://api.knowz.io/api/v1/auth/register`
+
+Make HTTP POST request to registration endpoint:
+
+```bash
+# Production (default)
+curl -X POST https://api.knowz.io/api/v1/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "{collected_name}",
+    "email": "{collected_email}",
+    "password": "{collected_password}"
+  }'
+
+# Development (with --dev flag)
+curl -X POST https://api.dev.knowz.io/api/v1/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "{collected_name}",
+    "email": "{collected_email}",
+    "password": "{collected_password}"
+  }'
+```
+
+**Handle Response Codes:**
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| 200/201 | Success | Extract API key AND vault_id, continue to Step 9 |
+| 400 | Validation error | Show error details, return to relevant step |
+| 409 | Email exists | Show recovery options (see Error Handling) |
+| 429 | Rate limited | Show wait message (see Error Handling) |
+| 500+ | Server error | Show error and support link |
+
+**Parse Response:**
+- Extract `api_key` (or `apiKey` or `token` field)
+- Extract `vault_id` (auto-created "KnowzCode" vault)
+- Extract `vault_name` (typically "KnowzCode")
+
+#### Step 9: Configure MCP, Vault, and Show Success
+
+**On successful registration:**
+
+1. **Extract from response:**
+   - API key (look for `apiKey`, `api_key`, or `token` field)
+   - Vault ID (look for `vault_id` or `vaultId` field)
+   - Vault name (look for `vault_name` or `vaultName` field, default: "KnowzCode")
+
+2. **Parse scope** from command arguments (default: `local`)
+
+3. **If scope is `project`**, show security warning:
+   ```
+   ⚠️ Security Note: Project Scope Selected
+
+   With project scope, your API key will be stored in .mcp.json
+   which is typically committed to git.
+
+   This is appropriate for:
+     • Team/shared API keys
+     • CI/CD automation keys
+
+   For personal keys, consider using --scope local (default)
+
+   Continue with project scope?
+   ```
+   Use AskUserQuestion to confirm. If user declines, use `local` scope instead.
+
+4. **Configure MCP server** (use same environment as registration):
+   ```bash
+   # Production (default)
+   claude mcp add --transport http \
+     --scope <chosen-scope> \
+     knowzcode \
+     https://mcp.knowz.io/mcp \
+     --header "Authorization: Bearer <api_key>" \
+     --header "X-Project-Path: $(pwd)"
+
+   # Development (with --dev flag)
+   claude mcp add --transport http \
+     --scope <chosen-scope> \
+     knowzcode \
+     https://mcp.dev.knowz.io/mcp \
+     --header "Authorization: Bearer <api_key>" \
+     --header "X-Project-Path: $(pwd)"
+   ```
+
+5. **Verify MCP configuration**:
+   ```bash
+   claude mcp get knowzcode
+   ```
+
+6. **Configure vault in mcp_config.md**:
+
+   Check if `knowzcode/mcp_config.md` exists:
+   - If exists: **Merge** vault configuration (preserve existing Code Vault if set)
+   - If not exists: Create from template with vault configured
+
+   Update `knowzcode/mcp_config.md` with:
+   ```markdown
+   # KnowzCode MCP Configuration
+
+   ## Connection Status
+   - **Connected**: Yes
+   - **Endpoint**: {endpoint}
+   - **Last Verified**: {ISO timestamp}
+
+   ---
+
+   ## Vaults
+
+   ### Research Vault (Primary)
+   - **Vault ID**: {vault_id from registration}
+   - **Vault Name**: {vault_name from registration}
+   - **Purpose**: Learnings, conventions, decisions, patterns
+   - **Auto-configured**: Yes (via /kc:register)
+
+   ### Code Vault (Optional)
+   - **Vault ID**: (not configured)
+   - **Purpose**: Indexed source code for semantic search
+   - **Note**: Code search uses local grep/glob by default.
+            Configure code vault for large codebases with /kc:connect-mcp --configure-vaults
+   ```
+
+   **Edge case - existing vault config**:
+   If `knowzcode/mcp_config.md` already has a Research Vault ID configured:
+   - Use AskUserQuestion: "You already have a vault configured. Replace with new vault from registration? [Yes/No/Keep both]"
+   - If "Yes": Replace Research Vault ID
+   - If "No": Keep existing vault config
+   - If "Keep both": Add new vault as secondary
+
+7. **Display success message** with vault info:
+
+```
+◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+◆ KnowzCode REGISTRATION COMPLETE
+◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✅ Account created and configured!
+
+Account Details:
+  • Email: {email}
+  • API Key: {masked_key}
+
+MCP Configuration:
+  • Scope: {chosen-scope}
+  • Endpoint: {endpoint}
+  • Environment: {Production OR Development}
+  • Status: Configured
+
+Vault Configuration:
+  • Vault: {vault_name} ({vault_id prefix...})
+  • Purpose: Learnings, conventions, patterns
+  • Status: Ready for use
+
+🔄 Please restart Claude Code to activate MCP features.
+
+After restart, you'll have access to:
+  • search_knowledge - Vector search across vaults
+  • ask_question - AI Q&A with research mode
+  • create_knowledge - Save learnings (via /kc:learn)
+  • update_knowledge - Update existing knowledge items
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Next Steps:
+  1. Restart Claude Code
+  2. Verify connection: /kc:status
+  3. Try learning capture: /kc:learn "Your first insight"
+  4. Start building: /kc:work "your feature"
+
+Need help? https://knowz.io/docs
+◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Masking:**
+- API Key: Show only first 6 and last 4 characters (e.g., `kz_liv...wxyz`)
+- Vault ID: Show only first 8 characters (e.g., `vault_xy...`)
+
+#### Step 9.5: Vault Discovery and Multi-Vault Selection
+
+After MCP is configured and before showing the final success message, offer vault discovery:
+
+1. **Fetch available vaults**
+
+   Use the `list_vaults` MCP tool (if available after restart) or display guidance:
+
+   ```
+   ◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   ◆ VAULT CONFIGURATION
+   ◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   Your account includes one vault by default:
+     • {vault_name} ({vault_id prefix...})
+
+   You can connect additional vaults for multi-vault routing.
+   This allows queries to be automatically routed to the right vault
+   based on the type of question (code vs. conventions vs. processes).
+
+   Would you like to configure additional vaults now?
+   ◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   ```
+
+   Use AskUserQuestion with options:
+   - **Yes** - Configure additional vaults now
+   - **No** - Skip for now (can configure later with /kc:connect-mcp --configure-vaults)
+
+   **STOP HERE and wait for user response.**
+
+   - If "No": Proceed to write single vault to `knowzcode_vaults.md` and show success message
+   - If "Yes": Continue with vault discovery
+
+2. **Call list_vaults() to discover available vaults**
+
+   If MCP tools are already active (rare after fresh registration):
+   ```
+   list_vaults(includeStats: true)
+   ```
+
+   If MCP tools not yet available (common - requires restart):
+   ```
+   Note: MCP tools require a restart to activate.
+   After restart, run /kc:connect-mcp --configure-vaults to add more vaults.
+   ```
+
+   If vaults are returned, display them:
+   ```
+   Available Vaults:
+   ┌────┬──────────────────────┬──────────────────┬───────────┐
+   │ #  │ Name                 │ Type             │ Documents │
+   ├────┼──────────────────────┼──────────────────┼───────────┤
+   │ 1  │ KnowzCode (default)  │ research         │ 0         │
+   │ 2  │ my-project-code      │ code             │ 1,234     │
+   │ 3  │ engineering-wiki     │ research         │ 89        │
+   └────┴──────────────────────┴──────────────────┴───────────┘
+   ```
+
+3. **Interactive vault selection loop**
+
+   For each vault discovered (including the default one):
+
+   a. Ask if user wants to connect this vault:
+      ```
+      Would you like to connect vault "KnowzCode" (research)?
+      ```
+      Options: [Yes] [No]
+
+   b. If "Yes", prompt for description:
+      ```
+      Describe what this vault contains (for intelligent routing):
+
+      Example descriptions:
+      • "Team learnings, conventions, architectural decisions"
+      • "Source code for the main API project"
+      • "Company processes, onboarding docs, team structure"
+
+      This helps KnowzCode route queries to the right vault automatically.
+      ```
+
+      Use AskUserQuestion to collect description (free text).
+
+   c. Store vault info: ID, name, type, description
+
+   d. Ask if user wants to connect another vault:
+      ```
+      Would you like to connect another vault?
+      ```
+      Options: [Yes] [No]
+
+      - If "Yes" and more vaults available: Loop back to step a
+      - If "No" or no more vaults: Exit loop
+
+4. **Write vault configuration to knowzcode_vaults.md**
+
+   Create or update `knowzcode/knowzcode_vaults.md` with selected vaults:
+
+   ```markdown
+   # KnowzCode Vault Configuration
+
+   Multi-vault routing configuration for intelligent vault selection.
+
+   ---
+
+   ## Connected Vaults
+
+   ### {vault_id_1}
+   - **Name**: {vault_name}
+   - **ID**: {vault_id}
+   - **Type**: {code | research}
+   - **Description**: {user_provided_description}
+
+   ### {vault_id_2}
+   - **Name**: {vault_name}
+   - **ID**: {vault_id}
+   - **Type**: {code | research}
+   - **Description**: {user_provided_description}
+
+   ---
+
+   ## Vault Routing Rules
+
+   - **Code questions** (implementations, files, structure) → {first code vault}
+   - **Convention questions** (patterns, decisions, best practices) → {first research vault}
+   - **Learning capture** → {default research vault}
+   ```
+
+5. **Show vault configuration summary**
+
+   After writing configuration:
+   ```
+   Vault configuration saved to knowzcode/knowzcode_vaults.md
+
+   Connected Vaults:
+     • KnowzCode (research) - "Team learnings and conventions"
+     • my-code (code) - "Source code for API project"
+
+   Queries will be automatically routed based on your descriptions.
+   You can edit knowzcode/knowzcode_vaults.md to update routing rules.
+   ```
+
+## Error Handling
+
+### Email Already Registered (HTTP 409)
+
+```
+⚠️ Email Already Registered
+
+The email {email} is already associated with a KnowzCode account.
+
+Options:
+1. Use a different email → Run /kc:register again
+2. Retrieve existing API key → Visit https://knowz.io/api-keys
+3. Reset password → https://knowz.io/forgot-password
+
+If this is your account, you can configure your existing key:
+  /kc:connect-mcp <your-existing-api-key>
+```
+
+### Invalid Input (HTTP 400)
+
+```
+❌ Registration Failed
+
+The server reported validation errors:
+{error_message_from_response}
+
+Please correct the issue and try again.
+```
+
+Return to the step corresponding to the invalid field.
+
+### Rate Limited (HTTP 429)
+
+```
+⏳ Too Many Requests
+
+Registration is temporarily rate limited.
+Please wait a few minutes and try again.
+
+If you continue to see this error, contact support:
+  https://knowz.io/support
+```
+
+### Network Error
+
+```
+❌ Network Error
+
+Cannot reach KnowzCode registration server.
+
+Troubleshooting:
+1. Check your internet connection
+2. Verify firewall/proxy settings allow HTTPS to api.knowz.io (or api.dev.knowz.io for --dev)
+3. Try again in a few moments
+
+If the issue persists:
+  • Status page: https://status.knowz.io
+  • Support: https://knowz.io/support
+```
+
+### Server Error (HTTP 500+)
+
+```
+❌ Server Error
+
+KnowzCode registration service encountered an error.
+
+This is not your fault. Please:
+1. Try again in a few minutes
+2. Check status: https://status.knowz.io
+3. Contact support if persists: https://knowz.io/support
+```
+
+### MCP Configuration Failed
+
+If registration succeeds but MCP configuration fails:
+
+```
+⚠️ Account Created, but MCP Configuration Failed
+
+Your account was created successfully:
+  • Email: {email}
+  • API Key: {masked_key}
+  • Vault: {vault_name} ({vault_id prefix...})
+
+However, automatic MCP configuration failed:
+  {error_details}
+
+You can configure manually:
+  /kc:connect-mcp {masked_key}
+
+Or visit https://knowz.io/api-keys to retrieve your key later.
+```
+
+### API Response Missing Vault ID
+
+If registration succeeds but API returns no vault_id:
+
+```
+⚠️ Account Created, but Vault Not Provisioned
+
+Your account was created and MCP is configured:
+  • Email: {email}
+  • API Key: {masked_key}
+  • MCP: Configured
+
+However, no vault was auto-created. This may indicate:
+  • Account provisioning is still in progress
+  • Server-side configuration needed
+
+You can:
+  1. Wait a few minutes and run /kc:status to check
+  2. Contact support: https://knowz.io/support
+  3. Manually configure vault later: /kc:connect-mcp --configure-vaults
+```
+
+## Security Considerations
+
+### Data Protection
+- **HTTPS only** - All API calls use HTTPS
+- **Password not stored** - Password sent once, never saved locally
+- **Password not logged** - Never display password in output
+- **Minimal data** - Only collect what's needed for registration
+
+### API Key Security
+- **Mask displayed keys**: Show only `kz_abc...xyz` format (first 6 + last 4 chars)
+- **Never log full keys**: Exclude from any diagnostic output
+- **Warn about project scope**: If `--scope project`, warn that API key will be in `.mcp.json`
+- **Recommend local scope**: Default to most secure option
+
+## Scope Comparison
+
+| Scope | Storage | Visibility | Best For |
+|-------|---------|------------|----------|
+| **local** (default) | Claude Code internal | Only you, this project | Personal development |
+| **project** | `.mcp.json` (git) | Team via git | Shared team key |
+| **user** | Claude Code user config | Only you, all projects | Personal, multi-project |
+
+## Related Commands
+
+- `/kc:connect-mcp` - Configure MCP with existing API key
+- `/kc:status` - Check MCP connection status
+- `/kc:init` - Initialize KnowzCode in project
+
+Execute this registration flow now.