knowzcode 0.1.0

package/knowzcode/knowzcode_project.md

@@ -0,0 +1,233 @@
+# ◆ KnowzCode Project Overview: [Agent: Infer a Project Name from UserProjectIdea]
+
+---
+
+**Purpose of this Document:** This `knowzcode_project.md` is a core artifact of the KnowzCode system. It provides a comprehensive high-level summary of the project, including its goals, scope, technology stack, architecture, coding standards, and quality priorities. The KnowzCode AI Agent will reference this document extensively for context and guidance throughout the development lifecycle, as detailed in `knowzcode_loop.md`.
+
+---
+
+### 1. Project Goal & Core Problem
+
+*   **Goal:** [Agent: Based on `UserProjectIdea`, concisely define the main objective of this project in 1-2 sentences.]
+*   **Core Problem Solved:** [Agent: Based on `UserProjectIdea`, describe the specific user problem or need this project addresses in 1-2 sentences.]
+
+---
+
+### 2. Scope & Key Features (MVP Focus)
+
+*   **Minimum Viable Product (MVP) Description:** [Agent: Briefly describe what constitutes the first usable version of the application, based on `UserProjectIdea`.]
+*   **Key Features (In Scope for MVP):**
+    *   `[Feature 1 Name]`: [Agent: Brief description of Feature 1. Infer from `UserProjectIdea`. Example: "User authentication (signup, login, logout)"]
+    *   `[Feature 2 Name]`: [Agent: Brief description of Feature 2.]
+    *   `[Feature 3 Name]`: [Agent: Brief description of Feature 3.]
+    *   *(Agent: Add more features as appropriate based on `UserProjectIdea`. Aim for 3-5 core MVP features.)*
+*   **Key Features (Explicitly OUT of Scope for MVP):**
+    *   `[Deferred Feature 1 Name]`: [Agent: Example: "Admin dashboard"]
+    *   `[Deferred Feature 2 Name]`: [Agent: Example: "Third-party API integrations beyond core needs"]
+    *   *(Agent: List 1-3 significant features that will not be part of the initial MVP to maintain focus.)*
+
+---
+
+### 3. Target Audience
+
+*   **Primary User Group(s):** [Agent: Based on `UserProjectIdea`, describe the primary intended users. E.g., "Small business owners needing simple invoicing," "Students learning web development," "Gamers looking for a community platform."]
+*   **Key User Needs Addressed:** [Agent: Briefly list the key needs of the target audience that this project aims to satisfy.]
+
+---
+
+### 4. Technology Stack (Specific Versions Critical for Agent)
+
+| Category             | Technology                                                                                                                                                        | Specific Version (or latest stable)      | Notes for AI Agent / Rationale                                         |
+|:---------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------|:----------------------------------------------------------------------------|
+| Language(s)          | [Agent: e.g., JavaScript (Node.js), Python. Recommend based on UserTechnicalPreferences or common platform usage. Specify version.]    | [Agent: e.g., nodejs-20, python-3.11]    | (Agent: Key for environment setup and tooling)                |
+| Backend Framework    | [Agent: e.g., Express.js, Flask, FastAPI, None. Recommend if applicable.]                                                                                        | [Agent: e.g., Express 4.18.x, Flask 2.3.x] | (Agent: Key for understanding server structure)                           |
+| Frontend Framework   | [Agent: e.g., React, Vue, Svelte, Static HTML/CSS/JS. Recommend if separate frontend envisioned.]                                                                | [Agent: e.g., React 18.2.x, Vue 3.3.x]   | (Agent: Key for UI component structure)                                    |
+| UI Library/Kit       | [Agent: e.g., Tailwind CSS, Bootstrap, Material UI, None. Recommend if applicable.]                                                                               | [Agent: e.g., Tailwind CSS 3.3.x]        |                                                                             |
+| Database             | [Agent: e.g., PostgreSQL, SQLite, MongoDB Atlas. Recommend platform-compatible options.]                                                          | [Agent: e.g., PostgreSQL 15.x]           | (Agent: Connection details via environment variables)         |
+| ORM/ODM (If any)     | [Agent: e.g., Prisma, SQLAlchemy, Drizzle ORM, Mongoose. Recommend if applicable.]                                                                               | [Agent: e.g., Prisma 5.x.x]              | (Agent: Important for DB interaction patterns and migrations)               |
+| Testing (Unit)       | [Agent: e.g., Jest, PyTest, Vitest. Recommend.]                                                                                                                  | [Agent: e.g., Jest 29.x]                 | (Agent: Use this for running unit tests)                          |
+| Testing (E2E/Integ.) | [Agent: e.g., Playwright, Cypress, Postman/Newman, None. Recommend if applicable for MVP.]                                                                       | [Agent: e.g., Playwright 1.4x.x]         | (Agent: Use this for running integration/E2E tests)               |
+| Version Control      | Git                                                                                                                                                               | N/A                                      | Repo hosted on [Agent: e.g., GitHub, GitLab, or local] |
+| Deployment Target    | [Agent: e.g., Vercel, Netlify, AWS, Local Docker]                                                                                                                                                | N/A                                      | Primary deployment target.                                              |
+| Key Libraries        | [Agent: e.g., axios for HTTP, bcryptjs for hashing. List 1-2 essential libraries and versions.]                                                                  | [Agent: Specify versions, e.g., axios@1.6.0] | (Agent: Key dependencies to install.)         |
+| Other (Specify)      |                                                                                                                                                                   |                                          |                                                                             |
+
+* **Tech Stack Rationale:** [Agent: Briefly explain why the chosen stack (especially language/framework) is suitable for this project. E.g., "Node.js with Express.js offers rapid development for web APIs and has a vast ecosystem of packages."]
+
+---
+
+### 5. High-Level Architecture
+
+* **Architectural Style:** [Agent: Describe the chosen style, e.g., "Monolithic Web Application," "Serverless API with Frontend Client," "Three-Tier Architecture." Suggest a simple, robust architecture.]
+* **Key Components & Interactions (Brief Textual Description):** [Agent: Describe the main pieces and how they generally communicate. This complements `knowzcode_architecture.md`. E.g., "The React frontend client makes API calls to the Express.js backend. The backend handles business logic and interacts with the PostgreSQL database via Prisma ORM."]
+* **Diagram (Mermaid - Agent to Generate):**
+    ```mermaid
+    graph TD
+        A[User via Browser/Client] --> B(Frontend SPA - [Agent: e.g., React]);
+        B --> C{Backend API - [Agent: e.g., Express.js]};
+        C --> D[(Database - [Agent: e.g., PostgreSQL])];
+        C --> E{{External Service API (Optional - [Agent: e.g., Stripe])}};
+
+        %% Agent: Define main components and primary interaction flows based on UserProjectIdea and chosen style. Keep it simple (2-5 components).
+        %% Example Subgraph for services
+        subgraph Backend Logic
+            direction LR
+            C --- S1[Auth Service (Handles Login/Signup)];
+            C --- S2[Core Feature Service (Manages [Primary Feature])];
+        end
+    ```
+    *(Agent: Generate a SIMPLE Mermaid diagram showing 2-5 main components and their primary interactions. The main detailed flowchart is in `knowzcode_architecture.md`.)*
+
+---
+
+### 6. Core Components/Modules (Logical Breakdown)
+
+* `[Component/Module 1 Name - Agent: e.g., User Authentication Module]`: [Agent: Brief responsibility. E.g., "Handles user registration, login, session management, password hashing."]
+* `[Component/Module 2 Name - Agent: e.g., Main Feature X Logic]`: [Agent: Brief responsibility. E.g., "Manages core logic for Feature X, including data processing and interactions with Y."]
+* `[Component/Module 3 Name - Agent: e.g., Primary UI View Components]`: [Agent: Brief responsibility. E.g., "Set of React components for rendering the main dashboard, forms, and user interactions."]
+* *(Agent: List 2-4 primary logical components based on the architecture and `UserProjectIdea`.)*
+
+---
+
+### 7. Key UI/UX Considerations
+
+* **Overall Feel:** [Agent: Describe the desired user experience. E.g., "Simple and intuitive," "Modern and professional," "Fast and responsive." Infer from `UserProjectIdea` or suggest a sensible default.]
+* **Key Principles:**
+    * `[Principle 1]`: [Agent: e.g., "Clarity: Ensure clear navigation and unambiguous calls to action."]
+    * `[Principle 2]`: [Agent: e.g., "Efficiency: Minimize clicks and streamline common workflows."]
+    * `[Principle 3]`: [Agent: e.g., "Responsiveness: Basic usability on common screen sizes (desktop primary, mobile secondary consideration for MVP)."]
+
+---
+
+### 8. Coding Standards & Conventions
+
+* **Primary Style Guide:** [Agent: e.g., "Airbnb JavaScript Style Guide (with Prettier for formatting)," "PEP 8 for Python (with Black for formatting)"]
+* **Formatter:** [Agent: e.g., "Prettier (config in `.prettierrc` - use default if not specified)," "Black (Python)"] (Agent: You will apply this during ARC-Based Verification)
+* **Linter:** [Agent: e.g., "ESLint (config in `.eslintrc.js` - use default if not specified)," "Flake8 (Python)"] (Agent: You will apply this during ARC-Based Verification)
+* **File Naming Conventions:** [Agent: e.g., `kebab-case.js` for files, `PascalCase.jsx` for React components, `snake_case.py` for Python files]
+* **Commit Message Convention:** [Agent: e.g., "Conventional Commits (e.g., `feat: add login button`, `fix: correct validation logic`)"]
+* **Code Commenting Style:** [Agent: e.g., "JSDoc for public functions/methods," "Python docstrings (Google style)," "Use comments sparingly only for complex, non-obvious logic."]
+* **Other Key Standards:**
+    * [Agent: e.g., "Avoid magic numbers/strings; use named constants."]
+    * [Agent: e.g., "All API endpoints must have basic input validation on the server-side."]
+    * [Agent: e.g., "Relative imports for intra-project modules."]
+
+### 8.1 Component Classification Criteria
+
+* **Standard**: Simple components with clear inputs/outputs, minimal business logic
+* **Complex**: Components with significant business logic, multiple dependencies, or state management
+* **Critical**: Components handling security, payments, user data, or system stability
+
+---
+
+### 9. Key Quality Criteria Focus (Priorities from `knowzcode/knowzcode_log.md`)
+* This project will prioritize the following **Top 3-5 quality criteria** from the "Reference Quality Criteria" section of `knowzcode/knowzcode_log.md`. Agent, you should pay special attention to these during ARC-Based Verification.
+    1.  [Agent: Suggest Priority 1 Quality Criterion - e.g., Reliability (Robust error handling)]
+    2.  [Agent: Suggest Priority 2 Quality Criterion - e.g., Maintainability (Clear, modular code)]
+    3.  [Agent: Suggest Priority 3 Quality Criterion - e.g., Security (Secure auth practices, input validation)]
+    4.  [Agent: Suggest Optional Priority 4, if applicable]
+    5.  [Agent: Suggest Optional Priority 5, if applicable]
+* **Rationale for Priorities:** [Agent: Briefly explain why these priorities are important for this specific project based on `UserProjectIdea`.]
+
+---
+
+### 10. Testing Strategy
+
+* **Required Test Types for MVP:**
+    * `Unit Tests`: [Agent: e.g., "Required for all core business logic functions/modules and critical utility functions."]
+    * `Integration Tests`: [Agent: e.g., "Required for API endpoint interactions and key service-to-service integrations."]
+    * `E2E Tests (Optional for MVP)`: [Agent: e.g., "Minimal set for 1-2 primary user flows (e.g., signup-login-perform core action)."]
+* **Testing Framework(s) & Version(s):** [Agent: Refer to Technology Stack, e.g., "Jest 29.x for unit/integration (JavaScript)", "PyTest 7.x for Python".]
+* **Test File Location & Naming:** [Agent: e.g., "Test files located adjacent to source files (`module.test.js`) or in a dedicated `__tests__`/`tests/` directory. Test names should be descriptive: `it('should return sum of two numbers')`."]
+* **Minimum Code Coverage Target (Conceptual Goal):** [Agent: e.g., "Aim for >70% for unit-tested core logic." State as an aim, not a strict CI blocker for MVP unless specified by user.]
+
+---
+
+### 11. Initial Setup Steps (Conceptual for a new developer/environment)
+
+1.  **Clone Repository:** `git clone [repository_url]`
+2.  **Install Language/Tools:** (Agent: Check versions against Tech Stack; use `knowzcode/EnvironmentContext.md` for specific commands).
+3.  **Install Dependencies:** (Agent: Use the dependency manager defined in `knowzcode/EnvironmentContext.md`, e.g., `npm install`).
+4.  **Environment Variables & Secrets:**
+    * [Agent: List any anticipated required environment variables based on common app needs or `UserProjectIdea`, e.g., `DATABASE_URL`, `SESSION_SECRET`, `ANY_EXTERNAL_API_KEY`].
+    * (Agent: Secrets must be stored securely, e.g., in a `.env` file loaded at runtime, and never committed to version control).
+5.  **Database Setup (If applicable):**
+    * [Agent: e.g., "Run database migrations using the command specified in `knowzcode/EnvironmentContext.md`, such as `npx prisma migrate dev`."]
+6.  **Run Development Server:**
+    * [Agent: Specify the typical run command for the chosen stack, e.g., `npm run dev`, `python main.py`.]
+    * (Agent: The server must bind to the host and port specified in `knowzcode/EnvironmentContext.md`).
+
+---
+
+### 12. Key Architectural Decisions & Rationale
+
+* **Decision 1: [Agent: e.g., Choice of Primary Language/Framework - e.g., Node.js with Express.js]**
+    * **Rationale:** [Agent: e.g., "Chosen for its non-blocking I/O suitable for web applications and its large ecosystem of packages." If user specified, use their rationale or infer and confirm.]
+* **Decision 2: [Agent: e.g., Database Choice - e.g., PostgreSQL]**
+    * **Rationale:** [Agent: e.g., "Selected for its robustness, SQL capabilities, and wide support from ORMs and cloud providers."]
+* **(Optional) Decision 3: [Agent: e.g., Architectural Style - e.g., Monolithic App for MVP]**
+    * **Rationale:** [Agent: e.g., "A monolithic approach was chosen for the MVP to simplify initial development and deployment, reducing complexity. Microservices can be considered for future scaling if needed."]
+
+---
+
+### 13. Repository Link
+
+* `[Agent: Link to Git Repository. User/Orchestrator will confirm/update.]` (Can be placeholder initially: "[To be confirmed/updated]")
+
+---
+
+### 14. Dependencies & Third-Party Services (Key Ones for MVP)
+
+* **[Service 1 Name - Agent: e.g., PostgreSQL Database]:**
+    * Purpose: Primary data storage.
+    * Integration: Via `DATABASE_URL` environment variable.
+* **(Optional) [External API Name - Agent: e.g., Stripe API]:**
+    * Purpose: [Agent: e.g., "To handle payments."]
+    * Integration: [Agent: e.g., "Via HTTP POST requests to their API endpoint. Requires API key."]
+    * Required Credentials: `[Agent: e.g., STRIPE_API_KEY]` (To be stored as an environment variable).
+* *(Agent: List only essential external services for the MVP based on `UserProjectIdea`.)*
+
+---
+
+### 15. Security Considerations (Initial High-Level)
+
+* **Authentication:** [Agent: e.g., "Session-based authentication using secure, HTTP-only cookies and a `SESSION_SECRET` stored as an environment variable / JWT-based authentication for APIs." Passwords **MUST** be hashed (e.g., using bcrypt or argon2).]
+* **Authorization:** [Agent: e.g., "Basic role-based access control if multiple user types exist. Check authorization on the server-side for all sensitive operations."]
+* **Input Validation:** [Agent: e.g., "All user inputs (forms, API request bodies/params) MUST be validated on the server-side to prevent common injection attacks (XSS, SQLi - though ORM mitigates SQLi largely)."]
+* **Data Protection:**
+    * "Sensitive data (e.g., PII, passwords) handled with care. Avoid logging sensitive data."
+    * "Use HTTPS in production environments."
+* **Dependency Management:** [Agent: e.g., "Dependencies will be kept updated. Use `npm audit` / `pip-audit` or similar tools periodically."]
+* **Secrets Management:** "All API keys, database credentials, and other secrets **MUST** be stored as environment variables and not hardcoded."
+
+---
+
+### 16. Performance Requirements (Initial Qualitative Goals)
+
+* **Response Time:** [Agent: e.g., "Web pages and API responses should generally feel responsive, aiming for <500ms for common operations under typical load." Suggest sensible defaults.]
+* **Load Capacity (Conceptual for MVP):** [Agent: e.g., "Application should handle a small number of concurrent users smoothly (e.g., 10-50)."]
+* **Scalability Approach (Future Consideration):** [Agent: e.g., "For MVP, vertical scaling is the primary approach. Horizontal scaling or more complex strategies are future considerations."]
+
+---
+
+### 17. Monitoring & Observability (Basic for MVP)
+
+* **Logging Strategy (Application-level):**
+    * [Agent: e.g., "Structured JSON logging to console for key application events, errors, and requests (e.g., using a library like Pino for Node.js or standard Python logging module)."]
+    * "Include timestamps, log levels (INFO, WARN, ERROR), and relevant context (e.g., request ID)."
+* **Monitoring Tools:** [Agent: e.g., "For MVP, rely on standard console/file logs. No complex external tools unless user specifies."]
+* **Key Metrics to Observe (Qualitative):** Error rates in logs, general application responsiveness.
+* **Alerting Criteria (Manual for MVP):** [Agent: e.g., "Monitor logs for frequent errors or performance degradation manually."]
+
+---
+
+### 18. Links to Other KnowzCode Artifacts
+* **Agent Main Loop & Protocol:** `knowzcode/knowzcode_loop.md`
+* **Operational Record & Quality Criteria:** `knowzcode/knowzcode_log.md`
+* **Architectural Flowchart (This Project):** `knowzcode/knowzcode_architecture.md`
+* **Status Map (This Project):** `knowzcode/knowzcode_tracker.md`
+* **Component Specifications Directory:** `knowzcode/specs/`
+* **Environment Protocol:** `knowzcode/environment_context.md` (or equivalent)
+
+---
+*(Agent: This document, once populated by you based on user input and sensible defaults, will become the single source of truth for high-level project information and guidelines. It will be kept up-to-date if major project parameters change.)*

package/knowzcode/knowzcode_tracker.md

@@ -0,0 +1,40 @@
+# ◆ KnowzCode - Status Map
+
+**Purpose:** This document tracks the development status of all implementable components (NodeIDs) defined in `knowzcode_architecture.md`. It guides task selection, groups related work via `WorkGroupID`, and provides a quick overview of project progress. It is updated by the KnowzCode AI Agent as per `knowzcode_loop.md`.
+
+**Note:** All paths are relative to the project root where the knowzcode files reside. The specs/ directory is within your project directory alongside other knowzcode files.
+
+---
+**Progress: 0%**
+---
+
+| Status | WorkGroupID | Node ID | Label | Dependencies | Logical Grouping | Spec Link | Classification | Notes / Issues |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| ⚪️ `[TODO]` | | `[ExampleNodeID]` | `[Example Node Label]` | `[DepNodeID1]` | `[Example Group]` | `[Spec](knowzcode/specs/ExampleNodeID.md)` | `[Standard]` | |
+| | | | | | | | | |
+| | | | | | | | | |
+
+---
+### ◆ KnowzCode Status Legend:
+
+*   ⚪️ **`[TODO]`**: Task is defined and ready to be picked up if dependencies are met. This status also applies to `REFACTOR_` tasks created from technical debt.
+*   📝 **`[NEEDS_SPEC]`**: Node has been identified in the architecture but requires a detailed specification to be drafted.
+*   ◆ **`[WIP]`**: ◆ **KnowzCode Working** - Work In Progress. The KnowzCode AI Agent is currently working on this node as part of the specified `WorkGroupID`.
+*   🟢 **`[VERIFIED]`**: The primary completion state. The node has been implemented, all ARC Verification Criteria are met, the spec is finalized to "as-built", and all outcomes are logged.
+*   ❗ **`[ISSUE]`**: A significant issue or blocker has been identified, preventing progress. Details should be in `knowzcode_log.md` or linked in the "Notes / Issues" column.
+
+---
+### Notes on Columns:
+
+*   **Status**: The current state of the NodeID (see Legend above).
+*   **WorkGroupID**: A unique ID assigned to a "Change Set" of nodes being worked on together. This is blank unless the `Status` is `[WIP]`.
+*   **Node ID**: The unique identifier for the component, matching the ID used in `knowzcode/knowzcode_architecture.md`.
+*   **Label**: A concise, human-readable name for the NodeID.
+*   **Dependencies**: A comma-separated list of `NodeID`s that must be `[VERIFIED]` before work on this node can begin. Only reference NodeIDs that exist in the architecture diagram. If a dependency's spec doesn't exist, that dependency must be `[NEEDS_SPEC]` status.
+*   **Logical Grouping**: An optional tag to categorize nodes by feature, module, or layer (e.g., "Authentication", "UserAPI").
+*   **Spec Link**: A relative Markdown link to the corresponding specification file in the `knowzcode/specs/` directory.
+*   **Classification**: Optional tag (e.g., `Critical`, `Complex`, `Standard`) to influence planning and review intensity.
+*   **Notes / Issues**: Brief comments, or a reference to a more detailed issue in `knowzcode/knowzcode_log.md`.
+
+---
+*(This table will be populated based on `knowzcode_architecture.md`. The AI Agent will then update the `Status` and `WorkGroupID` columns as it processes each Change Set according to `knowzcode_loop.md`.)*

package/knowzcode/knowzcode_vaults.md

@@ -0,0 +1,104 @@
+# KnowzCode Vault Configuration
+
+Multi-vault routing configuration for intelligent vault selection based on query intent.
+
+---
+
+## Connected Vaults
+
+> **No vaults configured yet.**
+>
+> Run `/kc:register` to set up your account and auto-configure your first vault,
+> or `/kc:connect-mcp --configure-vaults` to add vaults interactively.
+
+<!--
+When vaults are configured, they appear here in this format:
+
+### vault-abc123-def456
+- **Name**: Project Codebase
+- **ID**: vault-abc123-def456
+- **Type**: code
+- **Description**: Questions about the actual source code, current file structure, implementations, and how things work today. Use for "where is X defined?", "how does Y work?", "find implementations of Z".
+
+### vault-xyz789-ghi012
+- **Name**: Engineering Knowledge
+- **ID**: vault-xyz789-ghi012
+- **Type**: research
+- **Description**: Organizational decisions, architectural patterns, team conventions, and learnings. Use for "why did we choose X?", "what's our convention for Y?", "best practices for Z".
+-->
+
+---
+
+## Vault Routing Rules
+
+Routing rules determine which vault to query based on the type of question or operation.
+
+### Default Rules (when vaults are configured)
+
+| Query Type | Description | Target Vault Type |
+|------------|-------------|-------------------|
+| **Code questions** | Implementations, files, structure, "where is X?" | `code` |
+| **Convention questions** | Patterns, decisions, best practices, "why did we?" | `research` |
+| **Learning capture** | Saving new insights, patterns, decisions | `research` (prompt if multiple) |
+| **Standards queries** | Team standards, compliance rules, requirements | `enterprise` |
+| **Audit trail push** | Completion records, audit results | `enterprise` |
+
+### How Routing Works
+
+1. **For queries**: Agent reads vault descriptions and matches query intent
+2. **For writes**: If one research vault exists, use it; if multiple, prompt user
+3. **Fallback**: If no match found, query the default research vault
+
+---
+
+## Vault Types
+
+| Type | Purpose | Example Queries |
+|------|---------|-----------------|
+| **code** | Indexed source code (AST-chunked) | "Find auth middleware", "Where is PaymentService?" |
+| **research** | Architecture, conventions, learnings | "Error handling conventions", "Why Redis over Memcached?" |
+| **enterprise** | Team standards, audit trails, compliance | "Team standards for React", "Audit trail for kc-feat-auth" |
+
+---
+
+## Manual Configuration
+
+You can manually add vaults by editing this file. Use this format:
+
+```markdown
+### {vault-id}
+- **Name**: {Display Name}
+- **ID**: {vault-id}
+- **Type**: code | research
+- **Description**: {Detailed description of what this vault contains. Be specific about what types of questions should be routed here. Include example queries.}
+```
+
+**Tips for good descriptions:**
+- Be specific about content type (source code vs documentation)
+- Include example queries that should route to this vault
+- Mention key topics or domains covered
+- Describe the time period or version if relevant
+
+---
+
+## Configuration Commands
+
+- `/kc:register` - Create account and auto-configure first vault
+- `/kc:connect-mcp --configure-vaults` - Interactive vault setup
+- `/kc:status` - Check vault connection status
+
+---
+
+## Integration with Agents
+
+When configured, agents automatically route queries to the appropriate vault:
+
+| Agent | Uses Vault Routing For |
+|-------|------------------------|
+| `analyst` | Finding affected code + past decisions |
+| `architect` | Implementation examples + conventions |
+| `builder` | Similar patterns + best practices |
+| `reviewer` | Standards + precedent checks |
+| `closer` | Duplicate checking + learning capture |
+
+**Fallback behavior**: If vault routing cannot determine the best vault, agents use the first matching vault of the required type or prompt the user.

package/knowzcode/mcp_config.md

@@ -0,0 +1,166 @@
+# 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
+
+### Research Vault (Primary)
+- **Vault ID**: (not configured)
+- **Vault Name**: (not configured)
+- **Purpose**: Learnings, conventions, decisions, patterns
+- **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?"
+
+### Code Vault (Optional)
+- **Vault ID**: (not configured)
+- **Vault Name**: (not configured)
+- **Purpose**: Indexed source code for semantic search (AST-chunked)
+
+**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.
+
+**Query Patterns (when configured):**
+- "Find all auth middleware"
+- "Where is PaymentService?"
+- "Show database migrations"
+- "JWT validation code"
+
+### Enterprise Vault (Optional)
+- **Vault ID**: (not configured)
+- **Vault Name**: (not configured)
+- **Purpose**: Team-wide standards, audit trails, compliance records
+- **Auto-configured**: No
+
+**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`.
+
+**Query Patterns (when configured):**
+- "Team standards for React projects"
+- "Security requirements for API endpoints"
+- "Audit trail for WorkGroup kc-feat-auth"
+
+---
+
+## Single Vault Model (Recommended for New Users)
+
+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)      │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Why single vault?**
+- Simpler onboarding (no "what's code vault vs research vault?")
+- 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`
+
+---
+
+## 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 |
+
+**Fallback behavior**: When Code Vault is not configured, agents use local grep/glob
+for code search. This works well for most projects.
+
+---
+
+## MCP Tools Reference
+
+### Query Tools (Read)
+
+**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)`
+
+**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)`
+
+**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 (Learning Capture)
+
+**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[EXAMPLE]...",
+    "title": "Pattern: JWT Refresh Flow",
+    "knowledgeType": "Note",
+    "vaultId": "{research_vault_id}",
+    "tags": ["security", "jwt", "patterns"],
+    "source": "KnowzCode WorkGroup WG-feat-auth-20260128"
+  }
+  ```
+
+---
+
+## Auto-Learning Configuration
+
+- **Enabled**: Yes
+- **Prompt on Detection**: Yes
+- **Learning Categories**: Pattern, Decision, Workaround, Performance, Security, Convention
+
+### 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"
+
+---
+
+## 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 in research vault

package/knowzcode/planning/Readme.md

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