knowzcode 0.1.0 → 0.3.1

package/knowzcode/mcp_config.md

@@ -12,10 +12,10 @@
 
 ## Vaults
 
-### Research Vault (Primary)
+### Ecosystem Vault (Primary)
 - **Vault ID**: (not configured)
 - **Vault Name**: (not configured)
-- **Purpose**: Learnings, conventions, decisions, patterns
+- **Purpose**: Decisions, conventions, security practices, integrations, business rules, domain knowledge
 - **Auto-configured**: No
 
 **Query Patterns (when configured):**
@@ -23,36 +23,36 @@
 - "What patterns for API versioning?"
 - "Security best practices we use"
 - "Why did we choose Redis cache?"
+- "Stripe webhook setup"
+
+> **Backwards compatibility**: Vaults previously configured as type `research`, `domain`, or `platform` are treated identically to `ecosystem`. No migration needed.
 
 ### Code Vault (Optional)
 - **Vault ID**: (not configured)
 - **Vault Name**: (not configured)
-- **Purpose**: Indexed source code for semantic search (AST-chunked)
+- **Purpose**: Implementation patterns, workarounds, performance optimizations
 
 **Note**: Code search works well with local grep/glob for most projects.
-Configure a code vault for large codebases (50k+ LOC) where semantic search
-provides significant benefit.
+Configure a code vault for teams that want semantic search over implementation patterns and reusable utilities.
 
 **Query Patterns (when configured):**
-- "Find all auth middleware"
-- "Where is PaymentService?"
-- "Show database migrations"
-- "JWT validation code"
+- "Retry logic pattern"
+- "Workaround for rate limiting"
+- "Performance optimization for bulk inserts"
+- "JWT validation pattern"
 
-### Enterprise Vault (Optional)
+### Finalizations Vault (Optional)
 - **Vault ID**: (not configured)
 - **Vault Name**: (not configured)
-- **Purpose**: Team-wide standards, audit trails, compliance records
-- **Auto-configured**: No
+- **Purpose**: WorkGroup completion summaries, outcome records, finalization details
 
-**Note**: Enterprise vault is for organizations that want centralized standards
-and audit trails across projects. Configure via `knowzcode/enterprise/compliance_manifest.md`
-with `mcp_compliance_enabled: true`.
+**Note**: Finalizations vault provides a searchable history of completed work.
+Useful for teams that want to review past work patterns and outcomes.
 
 **Query Patterns (when configured):**
-- "Team standards for React projects"
-- "Security requirements for API endpoints"
-- "Audit trail for WorkGroup kc-feat-auth"
+- "What happened in WG-feat-auth?"
+- "Recent completion outcomes"
+- "Goals we worked on last week"
 
 ---
 
@@ -61,53 +61,56 @@ with `mcp_compliance_enabled: true`.
 KnowzCode recommends starting with a **single "KnowzCode" vault** for simplicity:
 
 ```
-┌─────────────────────────────────────────────────────────┐
-│                    KnowzCode Vault                       │
-│                                                         │
-│  Purpose: Learnings, conventions, decisions, patterns   │
-│  Used by: /kc:learn, closer, agents                     │
-│  Code search: Uses local grep/glob (no code vault)      │
-│                                                         │
-└─────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────┐
+│                   KnowzCode Vault                    │
+│                                                      │
+│  Purpose: All learnings, decisions, patterns, etc.   │
+│  Read by: knowz-scout, knowz-scribe, all agents       │
+│  Written by: knowz-scribe, knowz-scout, /kc:learn    │
+│  Code search: Uses local grep/glob (no code vault)   │
+│                                                      │
+└──────────────────────────────────────────────────────┘
 ```
 
 **Why single vault?**
-- Simpler onboarding (no "what's code vault vs research vault?")
+- Simpler onboarding (no vault type decisions needed)
 - Code search works fine with grep/glob for most projects
 - MCP vault is optimized for organizational knowledge, not code indexing
-- Advanced users can add code vault later via `/kc:connect-mcp --configure-vaults`
+- Advanced users can add specialized vaults later via `/kc:connect-mcp --configure-vaults`
 
 ---
 
 ## Usage in Agents
 
-| Agent | Research Vault | Code Vault | Purpose |
-|-------|----------------|------------|---------|
-| analyst | Query | Query (if configured) | Find past decisions + affected code |
-| architect | Query | Query (if configured) | Conventions + implementation examples |
-| builder | Query | Query (if configured) | Best practices + similar patterns |
-| reviewer | Query | Query (if configured) | Standards + precedent check |
-| closer | **Write** | - | Capture learnings |
+| Agent | Vault Interaction | Purpose |
+|-------|-------------------|---------|
+| knowz-scout | Read all configured vaults | Find past decisions, conventions, patterns |
+| knowz-scribe | Read and write to matching vaults | Route learnings per write conditions |
+| analyst | Read via knowz-scout | Past decisions + affected code patterns |
+| architect | Read via knowz-scout | Conventions + implementation examples |
+| builder | Read via knowz-scout | Best practices + similar patterns |
+| reviewer | Read via knowz-scout | Standards + precedent check |
+| closer | Triggers knowz-scribe captures | Finalization learnings |
 
-**Fallback behavior**: When Code Vault is not configured, agents use local grep/glob
-for code search. This works well for most projects.
+**Fallback behavior**: When specialized vaults are not configured, agents use local grep/glob
+for code search and the single vault for all knowledge queries.
 
 ---
 
 ## MCP Tools Reference
 
-### Query Tools (Read)
+### Query Tools (Read — used by knowz-scout)
 
 **search_knowledge(query, vaultId, limit)**
 - Vector similarity search across indexed content
 - Use for: finding code patterns or documentation
-- Example: `search_knowledge("authentication logic", research_vault_id, 10)`
+- Example: `search_knowledge("authentication logic", ecosystem_vault_id, 10)`
 
 **ask_question(question, vaultId, researchMode)**
 - AI-powered question answering with document synthesis
 - `researchMode: false` - Quick answer (faster)
 - `researchMode: true` - Comprehensive answer (8000+ tokens, multi-document)
-- Example: `ask_question("What are our error handling conventions?", research_vault_id, true)`
+- Example: `ask_question("What are our error handling conventions?", ecosystem_vault_id, true)`
 
 **find_entities(entityType, query, limit)**
 - Find people, locations, or events extracted from knowledge base
@@ -121,7 +124,7 @@ for code search. This works well for most projects.
 **list_vaults(includeStats)**
 - List all accessible vaults with optional statistics
 
-### Write Tools (Learning Capture)
+### Write Tools (used by knowz-scribe and /kc:learn)
 
 **create_knowledge(content, title, knowledgeType, vaultId, tags, source)**
 - Create new knowledge item in vault
@@ -129,22 +132,30 @@ for code search. This works well for most projects.
 - Example:
   ```json
   {
-    "content": "[CONTEXT]...\n[INSIGHT]...\n[EXAMPLE]...",
-    "title": "Pattern: JWT Refresh Flow",
+    "content": "[CONTEXT]...\n[INSIGHT]...\n[RATIONALE]...",
+    "title": "Decision: JWT Refresh Flow",
     "knowledgeType": "Note",
-    "vaultId": "{research_vault_id}",
-    "tags": ["security", "jwt", "patterns"],
+    "vaultId": "{ecosystem_vault_id}",
+    "tags": ["security", "jwt", "decision"],
     "source": "KnowzCode WorkGroup WG-feat-auth-20260128"
   }
   ```
 
+**create_vault(name, description)**
+- Create a new vault on the Knowz server
+- `name`: Display name for the vault (e.g., "Code Patterns")
+- `description`: Description of the vault's purpose and content
+- Returns the created vault's ID
+- Used during vault setup when default entries have empty IDs
+- **Note**: Availability depends on MCP server version. If not available, fall back to matching by name against `list_vaults()` results.
+
 ---
 
 ## Auto-Learning Configuration
 
 - **Enabled**: Yes
 - **Prompt on Detection**: Yes
-- **Learning Categories**: Pattern, Decision, Workaround, Performance, Security, Convention
+- **Learning Categories**: Pattern, Decision, Workaround, Performance, Security, Convention, Integration
 
 ### Detection Signals
 
@@ -154,6 +165,20 @@ Learnings are auto-detected when WorkGroup contains:
 - **Workaround signals**: "workaround", "limitation", "temporary"
 - **Performance signals**: "optimized", "reduced from X to Y"
 - **Security signals**: "security", "vulnerability", "sanitize"
+- **Integration signals**: "integrated with", "API behavior", "third-party"
+
+### Learning Category Routing
+
+| Category | Target Vault Type |
+|----------|-------------------|
+| Pattern | `code` |
+| Workaround | `code` |
+| Performance | `code` |
+| Decision | `ecosystem` |
+| Convention | `ecosystem` |
+| Security | `ecosystem` |
+| Integration | `ecosystem` |
+| Completion record | `finalizations` |
 
 ---
 
@@ -163,4 +188,4 @@ Learnings are auto-detected when WorkGroup contains:
 - `/kc:connect-mcp` - Configure MCP server (use existing API key)
 - `/kc:connect-mcp --configure-vaults` - Reconfigure vault IDs
 - `/kc:status` - Check connection status and vault info
-- `/kc:learn "insight"` - Manually create learning in research vault
+- `/kc:learn "insight"` - Manually create learning (routes via knowz-scribe if available)