knowzcode 0.1.0

package/commands/status.md

@@ -0,0 +1,291 @@
+---
+description: Check KnowzCode MCP server connection status and available tools
+---
+
+# KnowzCode MCP Connection Status
+
+You are the **KnowzCode Status Agent**. Your task is to verify the KnowzCode MCP server configuration and test connectivity.
+
+## What This Checks
+
+- MCP server configuration status
+- Connection to KnowzCode API
+- Available tools and their status
+- API key validity
+- **Code Vault** configuration and status
+- **Research Vault** configuration and status
+- Project indexing status
+
+## Your Task
+
+Check the KnowzCode MCP server status and report findings to the user.
+
+### Steps to Execute
+
+1. **Check MCP server configuration**
+   ```bash
+   claude mcp get knowzcode
+   ```
+
+   - If configured: Extract scope, endpoint, headers
+   - If not configured: Report and suggest `/kc:connect`
+
+2. **Check vault configuration**
+   - **Primary**: Read `knowzcode/knowzcode_vaults.md` for multi-vault routing
+     - Parse `## Connected Vaults` section
+     - Extract all configured vaults (ID, Name, Type, Description)
+   - **Fallback**: Read `knowzcode/mcp_config.md` for legacy single-vault config
+     - Extract Code Vault ID and name
+     - Extract Research Vault ID and name
+   - Note if no vaults are configured
+
+3. **Verify connection and vault health (if configured)**
+   - The MCP server should automatically list its available tools
+   - Check if tools are accessible
+   - If vaults are configured, attempt `list_vaults(includeStats=true)` to verify vault accessibility
+   - Report vault document counts and last sync times
+   - If vault IDs are configured but inaccessible, show warning with remediation steps
+
+4. **Report status**
+
+   **If configured and working**:
+   ```
+   ✅ KnowzCode MCP Server: Connected
+
+   Configuration:
+     • Scope: <local|project|user>
+     • Endpoint: https://mcp.knowz.io/mcp
+     • Status: Active
+
+   Connected Vaults (from knowzcode_vaults.md):
+     ┌────┬──────────────────────┬──────────┬─────────────────────────────────┐
+     │ #  │ Name                 │ Type     │ Description (routing)           │
+     ├────┼──────────────────────┼──────────┼─────────────────────────────────┤
+     │ 1  │ Engineering Knowledge│ research │ Patterns, decisions, conventions│
+     │ 2  │ my-project-code      │ code     │ Source code for main API        │
+     │ 3  │ Team Wiki            │ research │ Processes, onboarding           │
+     └────┴──────────────────────┴──────────┴─────────────────────────────────┘
+
+   Vault Routing:
+     • Code questions → my-project-code
+     • Convention questions → Engineering Knowledge (default research)
+     • Learning capture → Engineering Knowledge (or prompt if ambiguous)
+
+   Available Tools:
+     ✓ search_knowledge - Vector search across vaults
+     ✓ ask_question - AI Q&A with research mode
+     ✓ create_knowledge - Save learnings to vault
+     ✓ update_knowledge - Update existing items
+     ✓ find_entities - Find people/locations/events
+
+   Project: <project-path>
+   Last sync: <if available>
+
+   All systems operational. Agents can use MCP tools.
+   ```
+
+   **If configured but not working**:
+   ```
+   ⚠️ KnowzCode MCP Server: Configured but unavailable
+
+   Configuration:
+     • Scope: <scope>
+     • Endpoint: <endpoint>
+     • Status: Cannot connect
+
+   Possible issues:
+     • API key may be invalid or expired
+     • Network connectivity issues
+     • KnowzCode API may be down
+
+   Troubleshooting:
+     1. Check your internet connection
+     2. Verify API key: https://knowz.io/api-keys
+     3. Reconfigure: /kc:connect-mcp <new-key>
+     4. Check status: https://status.knowz.io
+   ```
+
+   **If MCP connected but vaults not configured**:
+   ```
+   ⚠️ KnowzCode MCP Server: Connected (vaults not configured)
+
+   Configuration:
+     • Scope: <scope>
+     • Endpoint: <endpoint>
+     • Status: Active
+
+   Connected Vaults: ⚠️ None configured
+
+   MCP is connected but you haven't configured your vaults yet.
+   Vaults enable semantic search and learning capture.
+
+   To configure vaults:
+     /kc:connect-mcp --configure-vaults
+     (Interactive vault discovery and selection)
+
+   Or manually edit: knowzcode/knowzcode_vaults.md
+   ```
+
+   **If not configured at all**:
+   ```
+   ℹ️ KnowzCode MCP Server: Not configured
+
+   KnowzCode works fine without MCP! All core features work:
+     ✓ TDD workflow (/kc:work)
+     ✓ Spec generation
+     ✓ Impact analysis
+     ✓ Quality audits
+
+   MCP adds enhanced capabilities:
+     • Vector search across indexed code (Code Vault)
+     • Convention and pattern lookups (Research Vault)
+     • AI-powered Q&A with research mode
+     • Automatic learning capture
+
+   To enable these features:
+     New user?     /kc:register              (creates account + configures)
+     Have a key?   /kc:connect-mcp <api-key>
+   ```
+
+5. **Additional diagnostics (if helpful)**
+   - Check if project is indexed (if MCP connected)
+   - Show vault document counts and last sync times
+   - Report any rate limiting or quota issues
+   - List any cached data available
+   - Show learning capture status (enabled/disabled)
+
+## Output Format
+
+Use clear status indicators:
+- ✅ Green check: Working perfectly
+- ⚠️ Warning: Configured but issues
+- ℹ️ Info: Not configured
+- ❌ Error: Critical failure
+
+## Connection Details
+
+If connection is active, optionally show:
+
+```
+Connection Details:
+  • Response time: <ms>
+  • Tools loaded: <count>
+  • Cache status: <enabled/disabled>
+  • Rate limit: <remaining/total>
+```
+
+## MCP Tool Details
+
+For each available tool, can optionally show:
+
+```
+search_knowledge
+  Description: Vector similarity search across vaults
+  Vaults: Code Vault, Research Vault
+  Status: ✓ Available
+  Last used: <time>
+
+ask_question
+  Description: AI-powered Q&A with optional research mode
+  Vaults: Research Vault (primary)
+  Research Mode: Enabled (8000+ token comprehensive answers)
+  Status: ✓ Available
+  Last used: <time>
+
+create_knowledge
+  Description: Save learnings to research vault
+  Vaults: Research Vault (write)
+  Used by: closer, /kc:learn
+  Status: ✓ Available
+  Last used: <time>
+```
+
+## Vault Status Details
+
+If vaults are configured, optionally show:
+
+```
+Code Vault: my-project-code
+  • Documents indexed: <count>
+  • Last index: <timestamp>
+  • Index status: Up to date / Stale / Indexing...
+  • Paths: src/, tests/, packages/
+
+Research Vault: engineering-knowledge
+  • Documents: <count>
+  • Notes: <count>
+  • Last updated: <timestamp>
+  • Top tags: architecture, security, patterns
+```
+
+## Error States
+
+### Invalid API Key
+```
+❌ Authentication Error
+The API key is invalid or expired.
+
+Update: /kc:connect-mcp <new-key>
+```
+
+### Network Issues
+```
+❌ Connection Error
+Cannot reach KnowzCode API at <endpoint>
+
+Check:
+  • Internet connection
+  • Firewall settings
+  • VPN configuration
+```
+
+### Service Down
+```
+❌ Service Unavailable
+KnowzCode API is not responding.
+
+Status: https://status.knowz.io
+```
+
+## Usage Examples
+
+### Basic status check
+```bash
+/kc:status
+```
+
+### After configuration
+```bash
+/kc:connect-mcp <api-key>
+# ... restart Claude Code ...
+/kc:status  # Verify everything works
+```
+
+### Troubleshooting
+```bash
+/kc:status  # Check what's wrong
+# Follow suggested remediation steps
+```
+
+## Integration Notes
+
+This command is useful:
+- **After initial setup**: Verify `/kc:connect` worked
+- **When tools seem unavailable**: Debug MCP connection
+- **Before starting work**: Confirm enhanced features active
+- **Troubleshooting**: Diagnose connectivity issues
+
+## Related Commands
+
+- `/kc:connect-mcp` - Configure MCP server
+- `/kc:init` - Initialize KnowzCode
+- `/kc:work` - Start feature (uses MCP if available)
+
+## Important Notes
+
+- **Restart required**: After `/kc:connect-mcp`, Claude Code must restart
+- **Graceful degradation**: KnowzCode works without MCP (just less powerful)
+- **No credentials shown**: Never display full API keys
+- **Clear guidance**: Always suggest next steps if issues found
+
+Execute this status check now.

package/commands/telemetry-setup.md

@@ -0,0 +1,368 @@
+---
+description: "Configure telemetry sources (Sentry, App Insights) for /kc:telemetry"
+argument-hint: "[sentry|appinsights|all]"
+---
+
+# KnowzCode Telemetry Setup
+
+Configure telemetry sources for `/kc:telemetry` investigations.
+
+**Usage**: `/kc:telemetry-setup [scope]`
+
+| Scope | Description |
+|-------|-------------|
+| `all` | Configure all detected sources (default) |
+| `sentry` | Configure Sentry only |
+| `appinsights` | Configure Azure App Insights only |
+
+**Examples**:
+```
+/kc:telemetry-setup
+/kc:telemetry-setup sentry
+/kc:telemetry-setup appinsights
+```
+
+---
+
+## Workflow
+
+### Step 1: Detect Available Tools
+
+Check which telemetry tools are available. **CLI is preferred when properly configured; MCP is a fallback.**
+
+#### 1.1 Check Sentry CLI (Preferred)
+
+```bash
+# Check Sentry CLI installation
+which sentry-cli 2>/dev/null && echo "SENTRY_CLI_INSTALLED" || echo "NO_SENTRY_CLI"
+```
+
+If installed, verify authentication:
+```bash
+# Verify Sentry CLI is authenticated
+sentry-cli info 2>&1 | grep -q "Organization" && echo "SENTRY_AUTHENTICATED" || echo "SENTRY_NOT_AUTHENTICATED"
+```
+
+**If Sentry CLI installed + authenticated → use CLI method, skip MCP check for Sentry.**
+
+#### 1.2 Check Sentry MCP (Fallback)
+
+**Only check MCP if CLI is not available or not authenticated.**
+
+Attempt to detect MCP by checking if Sentry MCP tools respond. The agent should:
+1. Try to use `sentry_search_issues` or `mcp__sentry__search_issues` with a minimal test query
+2. If it responds (even with "no results") → MCP is available
+3. If it errors with "tool not found" → MCP not configured
+
+**If MCP available → use MCP method for Sentry.**
+
+#### 1.3 Check Azure CLI + App Insights
+
+```bash
+# Check Azure CLI
+which az 2>/dev/null && echo "AZURE_CLI_INSTALLED" || echo "NO_AZURE_CLI"
+
+# Check App Insights extension
+az extension list --query "[?name=='application-insights'].name" -o tsv 2>/dev/null || echo "NO_APPINSIGHTS_EXTENSION"
+```
+
+**Report detected tools and methods** before proceeding:
+
+```markdown
+**Detection Results:**
+
+| Source | Status | Method |
+|--------|--------|--------|
+| Sentry | ✓ Available | CLI (preferred) |
+| App Insights | ✓ Available | CLI |
+
+or
+
+| Source | Status | Method |
+|--------|--------|--------|
+| Sentry | ✓ Available | MCP (CLI not configured) |
+| App Insights | ✗ Not available | - |
+```
+
+### Step 2: Verify Authentication
+
+For each installed tool, verify authentication:
+
+```bash
+# Sentry: Check if authenticated
+sentry-cli info 2>&1 | head -5
+
+# Azure: Check if authenticated
+az account show --query "{name:name, user:user.name}" -o table 2>&1 | head -5
+```
+
+**If not authenticated**, provide setup instructions and stop for that source:
+
+**For Sentry**:
+```markdown
+⚠️ Sentry CLI is installed but not authenticated.
+
+Run these commands to authenticate:
+\`\`\`bash
+sentry-cli login
+# OR set the auth token directly
+export SENTRY_AUTH_TOKEN="your-token-here"
+\`\`\`
+
+Then run `/kc:telemetry-setup sentry` again.
+```
+
+**For Azure**:
+```markdown
+⚠️ Azure CLI is installed but not authenticated.
+
+Run these commands to authenticate:
+\`\`\`bash
+az login
+az extension add --name application-insights  # If not installed
+\`\`\`
+
+Then run `/kc:telemetry-setup appinsights` again.
+```
+
+### Step 3: Auto-Discover Resources
+
+For each authenticated source, discover available resources:
+
+**Sentry**:
+```bash
+# List organizations
+sentry-cli organizations list 2>/dev/null
+
+# List projects (for each org)
+sentry-cli projects list --org {org-slug} 2>/dev/null
+```
+
+**Azure App Insights**:
+```bash
+# List all App Insights resources
+az monitor app-insights component list \
+  --query "[].{name:name, appId:appId, resourceGroup:resourceGroup}" \
+  -o table 2>/dev/null
+```
+
+**Report discovered resources** in a clear format.
+
+### Step 4: Interactive Configuration
+
+Present discovered resources and ask user to map environments:
+
+```markdown
+## Discovered Resources
+
+### Sentry Projects
+| # | Organization | Project |
+|---|--------------|---------|
+| 1 | my-company | backend-api |
+| 2 | my-company | frontend-web |
+| 3 | my-company | worker-service |
+
+### App Insights Resources
+| # | Name | App ID | Resource Group |
+|---|------|--------|----------------|
+| 1 | appinsights-prod | abc-123-def | rg-production |
+| 2 | appinsights-staging | ghi-456-jkl | rg-staging |
+| 3 | appinsights-dev | mno-789-pqr | rg-development |
+
+---
+
+**Please map each environment to a resource:**
+
+For Sentry:
+- Production → (enter project number or skip)
+- Staging → (enter project number or skip)
+- Dev → (enter project number or skip)
+
+For App Insights:
+- Production → (enter resource number or skip)
+- Staging → (enter resource number or skip)
+- Dev → (enter resource number or skip)
+```
+
+Use the AskUserQuestion tool to collect mappings if multiple resources exist.
+
+### Step 5: Save Configuration
+
+Update `knowzcode/telemetry_config.md` with the discovered and mapped values.
+
+**Include the detection method** (cli or mcp) for each source.
+
+**Example result** (CLI method):
+
+```markdown
+## Sentry
+
+| Field | Value |
+|-------|-------|
+| Enabled | true |
+| Method | cli |
+| Organization | my-company |
+
+### Environment Mapping
+
+| Environment | Project |
+|-------------|---------|
+| production | my-company/backend-api |
+| staging | my-company/backend-staging |
+| dev | my-company/backend-dev |
+
+## Azure Application Insights
+
+| Field | Value |
+|-------|-------|
+| Enabled | true |
+| Subscription | 12345678-1234-1234-1234-123456789012 |
+| Resource Group | rg-production |
+
+### Environment Mapping
+
+| Environment | App Name | App ID |
+|-------------|----------|--------|
+| production | appinsights-prod | abc-123-def |
+| staging | appinsights-staging | ghi-456-jkl |
+| dev | appinsights-dev | mno-789-pqr |
+```
+
+**Example result** (MCP method - when CLI not available):
+
+```markdown
+## Sentry
+
+| Field | Value |
+|-------|-------|
+| Enabled | true |
+| Method | mcp |
+| Organization | my-company |
+
+### Environment Mapping
+
+| Environment | Project |
+|-------------|---------|
+| production | my-company/backend-api |
+| staging | my-company/backend-staging |
+| dev | my-company/backend-dev |
+```
+
+### Step 6: Confirm Setup
+
+After saving, show a summary **including the detection method**:
+
+```markdown
+◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+◆ TELEMETRY CONFIGURATION COMPLETE
+◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Sentry**: ✓ Configured
+- Method: CLI (preferred)
+- Organization: my-company
+- Environments mapped: production, staging, dev
+
+**App Insights**: ✓ Configured
+- Method: CLI
+- Subscription: my-subscription
+- Environments mapped: production, staging, dev
+
+**Configuration saved to**: knowzcode/telemetry_config.md
+
+You can now run:
+  /kc:telemetry "error 500 in staging in the last hour"
+
+The telemetry investigator will automatically use the correct
+project/resource for the specified environment.
+◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## Error Handling
+
+### No Tools Installed
+
+If NEITHER CLI nor MCP is available for a source, ask which to install:
+
+```markdown
+⚠️ No Sentry connection detected.
+
+Would you like to set up Sentry? Choose an option:
+
+**Option 1: Sentry CLI** (Recommended)
+- Better error details and breadcrumbs
+- Full issue management capabilities
+\`\`\`bash
+npm install -g @sentry/cli
+sentry-cli login
+\`\`\`
+
+**Option 2: Sentry MCP**
+- Configure Sentry MCP server in Claude Code settings
+- Tools: `sentry_search_issues`, `sentry_get_issue_details`, `sentry_list_events`
+- See: https://github.com/modelcontextprotocol/servers/tree/main/sentry
+
+---
+
+⚠️ No Azure App Insights connection detected.
+
+**For Azure App Insights** (CLI only):
+\`\`\`bash
+# Install Azure CLI (if not installed)
+brew install azure-cli  # macOS
+# or see https://docs.microsoft.com/en-us/cli/azure/install-azure-cli
+
+az login
+az extension add --name application-insights
+\`\`\`
+
+Then run `/kc:telemetry-setup` again.
+```
+
+### No Resources Found
+
+```markdown
+⚠️ Authenticated but no resources found.
+
+**Sentry**: No projects found for your account.
+- Create a project at https://sentry.io
+
+**App Insights**: No Application Insights resources found.
+- Create one in Azure portal or via CLI:
+  \`\`\`bash
+  az monitor app-insights component create \
+    --app my-app-name \
+    --location eastus \
+    --resource-group my-rg
+  \`\`\`
+```
+
+---
+
+## Configuration File Location
+
+The configuration is saved to:
+- **Path**: `knowzcode/telemetry_config.md`
+- **Git**: Should be committed (shared team configuration)
+- **Override**: Team members can edit locally if needed
+
+For sensitive tokens, use environment variables instead of the config file:
+- `SENTRY_AUTH_TOKEN` - Sentry authentication
+- `AZURE_*` - Azure CLI uses `az login` session
+
+---
+
+## Verification
+
+After setup, test the configuration:
+
+```bash
+/kc:telemetry "test query in production in the last 5 min"
+```
+
+This should:
+1. Load the config from `knowzcode/telemetry_config.md`
+2. Map "production" to the configured project/app
+3. Query the correct telemetry source
+4. Return results (or "no events found" if no matching errors)