knowzcode 0.4.0 → 0.5.2

package/commands/register.md

@@ -1,733 +1,757 @@
----
-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
-   CLAUDECODE= claude mcp get knowz
-   ```
-
-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 `CLAUDECODE= claude mcp remove knowz` 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> \
-     knowz \
-     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> \
-     knowz \
-     https://mcp.dev.knowz.io/mcp \
-     --header "Authorization: Bearer <api_key>" \
-     --header "X-Project-Path: $(pwd)"
-   ```
-
-5. **Verify MCP configuration**:
-   ```bash
-   CLAUDECODE= claude mcp get knowz
-   ```
-
-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
-
-   ### Ecosystem Vault (Primary)
-   - **Vault ID**: {vault_id from registration}
-   - **Vault Name**: {vault_name from registration}
-   - **Purpose**: Decisions, conventions, security, integrations, business rules
-   - **Auto-configured**: Yes (via /kc:register)
-
-   ### Code Vault (Optional)
-   - **Vault ID**: (not configured)
-   - **Purpose**: Implementation patterns, workarounds, performance
-   - **Note**: Code search uses local grep/glob by default.
-            Configure code vault for large codebases with /kc:connect-mcp --configure-vaults
-
-   ### Finalizations Vault (Optional)
-   - **Vault ID**: (not configured)
-   - **Purpose**: WorkGroup completion summaries, outcome records
-   - **Note**: Finalizations vault tracks completed work.
-            Configure for teams that want searchable completion history.
-   ```
-
-   **Edge case - existing vault config**:
-   If `knowzcode/mcp_config.md` already has an Ecosystem Vault ID configured:
-   - Use AskUserQuestion: "You already have a vault configured. Replace with new vault from registration? [Yes/No/Keep both]"
-   - If "Yes": Replace Ecosystem 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)  │ ecosystem        │ 0         │
-   │ 2  │ my-project-code      │ code             │ 1,234     │
-   │ 3  │ engineering-wiki     │ ecosystem        │ 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 | ecosystem | finalizations}
-   - **Description**: {user_provided_description}
-
-   ### {vault_id_2}
-   - **Name**: {vault_name}
-   - **ID**: {vault_id}
-   - **Type**: {code | ecosystem | finalizations}
-   - **Description**: {user_provided_description}
-
-   ---
-
-   ## Vault Routing Rules
-
-   - **Code questions** (implementations, files, structure) → {first code vault}
-   - **Convention questions** (patterns, decisions, best practices) → {first ecosystem vault}
-   - **Completion records** → {first finalizations vault}
-   - **Learning capture** → {default ecosystem vault}
-   ```
-
-   **Null GUID detection**: After writing vault configuration to `knowzcode_vaults.md`, check for entries with empty **ID** fields. If found, prompt: "Found {N} default vault(s) not yet created. Create them now?" On confirmation, create each vault via MCP and update the ID fields.
-
-5. **Show vault configuration summary**
-
-   After writing configuration:
-   ```
-   Vault configuration saved to knowzcode/knowzcode_vaults.md
-
-   Connected Vaults:
-     • KnowzCode (ecosystem) - "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.
+---
+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 0: Smart Discovery
+
+Before starting registration, check if user already has a KnowzCode API key:
+
+1. Check `KNOWZ_API_KEY` environment variable
+2. Check `knowzcode/mcp_config.md` — if `Connected: Yes`, existing config exists
+3. Check cross-platform configs: `.gemini/settings.json`, `.vscode/mcp.json`, `.mcp.json`
+   - Extract Bearer token from Authorization headers if found
+
+If existing API key found:
+```
+You already have a KnowzCode API key configured (ending ...{last4}) from {source}.
+
+Options:
+1. Use existing key — run /kc:connect-mcp to configure this platform
+2. Register a new account anyway
+3. Cancel
+```
+
+If user chooses option 1: advise running `/kc:connect-mcp` with discovered key.
+If user chooses option 2: proceed with registration normally (Step 1).
+If user chooses option 3: stop.
+
+#### Step 1: Check Existing Configuration
+
+1. Check if MCP server already configured:
+   ```bash
+   CLAUDECODE= claude mcp get knowz
+   ```
+
+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 `CLAUDECODE= claude mcp remove knowz` 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> \
+     knowz \
+     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> \
+     knowz \
+     https://mcp.dev.knowz.io/mcp \
+     --header "Authorization: Bearer <api_key>" \
+     --header "X-Project-Path: $(pwd)"
+   ```
+
+5. **Verify MCP configuration**:
+   ```bash
+   CLAUDECODE= claude mcp get knowz
+   ```
+
+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}
+   - **API Key (last 4)**: {last 4 characters of the API key}
+
+   ---
+
+   ## Vaults
+
+   ### Ecosystem Vault (Primary)
+   - **Vault ID**: {vault_id from registration}
+   - **Vault Name**: {vault_name from registration}
+   - **Purpose**: Decisions, conventions, security, integrations, business rules
+   - **Auto-configured**: Yes (via /kc:register)
+
+   ### Code Vault (Optional)
+   - **Vault ID**: (not configured)
+   - **Purpose**: Implementation patterns, workarounds, performance
+   - **Note**: Code search uses local grep/glob by default.
+            Configure code vault for large codebases with /kc:connect-mcp --configure-vaults
+
+   ### Finalizations Vault (Optional)
+   - **Vault ID**: (not configured)
+   - **Purpose**: WorkGroup completion summaries, outcome records
+   - **Note**: Finalizations vault tracks completed work.
+            Configure for teams that want searchable completion history.
+   ```
+
+   **Edge case - existing vault config**:
+   If `knowzcode/mcp_config.md` already has an Ecosystem Vault ID configured:
+   - Use AskUserQuestion: "You already have a vault configured. Replace with new vault from registration? [Yes/No/Keep both]"
+   - If "Yes": Replace Ecosystem 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)  │ ecosystem        │ 0         │
+   │ 2  │ my-project-code      │ code             │ 1,234     │
+   │ 3  │ engineering-wiki     │ ecosystem        │ 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 | ecosystem | finalizations}
+   - **Description**: {user_provided_description}
+
+   ### {vault_id_2}
+   - **Name**: {vault_name}
+   - **ID**: {vault_id}
+   - **Type**: {code | ecosystem | finalizations}
+   - **Description**: {user_provided_description}
+
+   ---
+
+   ## Vault Routing Rules
+
+   - **Code questions** (implementations, files, structure) → {first code vault}
+   - **Convention questions** (patterns, decisions, best practices) → {first ecosystem vault}
+   - **Completion records** → {first finalizations vault}
+   - **Learning capture** → {default ecosystem vault}
+   ```
+
+   **Null GUID detection**: After writing vault configuration to `knowzcode_vaults.md`, check for entries with empty **ID** fields. If found, prompt: "Found {N} default vault(s) not yet created. Create them now?" On confirmation, create each vault via MCP and update the ID fields.
+
+5. **Show vault configuration summary**
+
+   After writing configuration:
+   ```
+   Vault configuration saved to knowzcode/knowzcode_vaults.md
+
+   Connected Vaults:
+     • KnowzCode (ecosystem) - "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.