knowzcode 0.4.0 → 0.5.2

package/knowzcode/mcp_config.md

@@ -1,191 +1,196 @@
-# KnowzCode MCP Configuration
-
-## Connection Status
-- **Connected**: No
-- **Endpoint**: (not configured)
-- **Last Verified**: (never)
-
-> **Not configured?** Run `/kc:register` to create an account and set up MCP automatically,
-> or `/kc:connect-mcp <api-key>` if you already have a key.
-
----
-
-## Vaults
-
-### Ecosystem Vault (Primary)
-- **Vault ID**: (not configured)
-- **Vault Name**: (not configured)
-- **Purpose**: Decisions, conventions, security practices, integrations, business rules, domain knowledge
-- **Auto-configured**: No
-
-**Query Patterns (when configured):**
-- "Our error handling conventions"
-- "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**: Implementation patterns, workarounds, performance optimizations
-
-**Note**: Code search works well with local grep/glob for most projects.
-Configure a code vault for teams that want semantic search over implementation patterns and reusable utilities.
-
-**Query Patterns (when configured):**
-- "Retry logic pattern"
-- "Workaround for rate limiting"
-- "Performance optimization for bulk inserts"
-- "JWT validation pattern"
-
-### Finalizations Vault (Optional)
-- **Vault ID**: (not configured)
-- **Vault Name**: (not configured)
-- **Purpose**: WorkGroup completion summaries, outcome records, finalization details
-
-**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):**
-- "What happened in WG-feat-auth?"
-- "Recent completion outcomes"
-- "Goals we worked on last week"
-
----
-
-## Single Vault Model (Recommended for New Users)
-
-KnowzCode recommends starting with a **single "KnowzCode" vault** for simplicity:
-
-```
-┌──────────────────────────────────────────────────────┐
-│                   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 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 specialized vaults later via `/kc:connect-mcp --configure-vaults`
-
----
-
-## Usage in Agents
-
-| 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 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 — 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", 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?", ecosystem_vault_id, true)`
-
-**find_entities(entityType, query, limit)**
-- Find people, locations, or events extracted from knowledge base
-- `entityType`: "person", "location", or "event"
-- Example: `find_entities("person", "John", 25)`
-
-**get_knowledge_item(id, includeRelated)**
-- Retrieve a specific knowledge item by ID
-- `includeRelated: true` to include related items
-
-**list_vaults(includeStats)**
-- List all accessible vaults with optional statistics
-
-### Write Tools (used by knowz-scribe and /kc:learn)
-
-**create_knowledge(content, title, knowledgeType, vaultId, tags, source)**
-- Create new knowledge item in vault
-- `knowledgeType`: "Document", "Note", or "Transcript"
-- Example:
-  ```json
-  {
-    "content": "[CONTEXT]...\n[INSIGHT]...\n[RATIONALE]...",
-    "title": "Decision: JWT Refresh Flow",
-    "knowledgeType": "Note",
-    "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, Integration
-
-### Detection Signals
-
-Learnings are auto-detected when WorkGroup contains:
-- **Pattern signals**: "created utility for", "new helper", "reusable"
-- **Decision signals**: "chose X over Y", "decided to", "opted for"
-- **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` |
-
----
-
-## Configuration Commands
-
-- `/kc:register` - Create account and auto-configure MCP + vault
-- `/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 (routes via knowz-scribe if available)
+# KnowzCode MCP Configuration
+
+## Connection Status
+- **Connected**: No
+- **Endpoint**: (not configured)
+- **Last Verified**: (never)
+- **API Key (last 4)**: (not configured)
+
+> **Not configured?** Run `/kc:register` to create an account and set up MCP automatically,
+> or `/kc:connect-mcp <api-key>` if you already have a key.
+
+> **Environment variable**: Set `KNOWZ_API_KEY` in your shell to enable automatic
+> MCP authentication on any platform without interactive prompts.
+> All `/kc:connect-mcp` and `/kc:register` commands check this variable first.
+
+---
+
+## Vaults
+
+### Ecosystem Vault (Primary)
+- **Vault ID**: (not configured)
+- **Vault Name**: (not configured)
+- **Purpose**: Decisions, conventions, security practices, integrations, business rules, domain knowledge
+- **Auto-configured**: No
+
+**Query Patterns (when configured):**
+- "Our error handling conventions"
+- "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**: Implementation patterns, workarounds, performance optimizations
+
+**Note**: Code search works well with local grep/glob for most projects.
+Configure a code vault for teams that want semantic search over implementation patterns and reusable utilities.
+
+**Query Patterns (when configured):**
+- "Retry logic pattern"
+- "Workaround for rate limiting"
+- "Performance optimization for bulk inserts"
+- "JWT validation pattern"
+
+### Finalizations Vault (Optional)
+- **Vault ID**: (not configured)
+- **Vault Name**: (not configured)
+- **Purpose**: WorkGroup completion summaries, outcome records, finalization details
+
+**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):**
+- "What happened in WG-feat-auth?"
+- "Recent completion outcomes"
+- "Goals we worked on last week"
+
+---
+
+## Single Vault Model (Recommended for New Users)
+
+KnowzCode recommends starting with a **single "KnowzCode" vault** for simplicity:
+
+```
+┌──────────────────────────────────────────────────────┐
+│                   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 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 specialized vaults later via `/kc:connect-mcp --configure-vaults`
+
+---
+
+## Usage in Agents
+
+| 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 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 — 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", 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?", ecosystem_vault_id, true)`
+
+**find_entities(entityType, query, limit)**
+- Find people, locations, or events extracted from knowledge base
+- `entityType`: "person", "location", or "event"
+- Example: `find_entities("person", "John", 25)`
+
+**get_knowledge_item(id, includeRelated)**
+- Retrieve a specific knowledge item by ID
+- `includeRelated: true` to include related items
+
+**list_vaults(includeStats)**
+- List all accessible vaults with optional statistics
+
+### Write Tools (used by knowz-scribe and /kc:learn)
+
+**create_knowledge(content, title, knowledgeType, vaultId, tags, source)**
+- Create new knowledge item in vault
+- `knowledgeType`: "Document", "Note", or "Transcript"
+- Example:
+  ```json
+  {
+    "content": "[CONTEXT]...\n[INSIGHT]...\n[RATIONALE]...",
+    "title": "Decision: JWT Refresh Flow",
+    "knowledgeType": "Note",
+    "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, Integration
+
+### Detection Signals
+
+Learnings are auto-detected when WorkGroup contains:
+- **Pattern signals**: "created utility for", "new helper", "reusable"
+- **Decision signals**: "chose X over Y", "decided to", "opted for"
+- **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` |
+
+---
+
+## Configuration Commands
+
+- `/kc:register` - Create account and auto-configure MCP + vault
+- `/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 (routes via knowz-scribe if available)

package/knowzcode/planning/Readme.md

@@ -1,6 +1,6 @@
-\# Planning Documents
-
-
-
-This directory stores strategic planning documents and feature analyses generated during development.
-
+\# Planning Documents
+
+
+
+This directory stores strategic planning documents and feature analyses generated during development.
+