better error message

Author: bhouston

.changeset/all-pianos-divide.md

@@ -0,0 +1,6 @@
+---
+'mycoder-agent': patch
+'mycoder': patch
+---
+
+Improve check for API keys with better help messages.

docs/analysis/roo-code-memory-bank-analysis.md

@@ -33,6 +33,7 @@ By dividing the context into specific files with distinct purposes, the system o
 ### 3. Enhanced AI Performance
 
 With access to this persistent context, the AI can:
+
 - Make more consistent recommendations
 - Understand project history and decisions
 - Reference previous work
@@ -50,11 +51,13 @@ The Memory Bank allows the AI to pick up where it left off, even after the user
 To implement similar functionality while prioritizing human-readable documentation, mycoder could:
 
 1. **Use Standard Documentation Formats**:
+
    - Store context in standard README.md files, DEVELOPMENT.md, ARCHITECTURE.md, etc.
    - Follow established documentation patterns that developers are already familiar with
    - Ensure all generated documentation follows best practices for human readability
 
 2. **Leverage Existing Project Artifacts**:
+
    - Treat GitHub Issues, Pull Requests, and Commit Messages as part of the context
    - Parse and understand existing documentation
    - Contribute to and update standard documentation rather than creating AI-specific formats
@@ -67,7 +70,7 @@ To implement similar functionality while prioritizing human-readable documentati
 ### Proposed Implementation Approach
 
 1. **Documentation-First Context Management**:
-   
+
    Instead of creating AI-specific context files, mycoder could use a documentation-first approach:
 
    - **Project README.md**: Overall project context, goals, and high-level architecture
@@ -77,15 +80,15 @@ To implement similar functionality while prioritizing human-readable documentati
    - **docs/**: Directory for more detailed documentation
 
 2. **Metadata Integration**:
-   
+
    To help the AI understand and navigate the documentation:
 
    - Use front matter in Markdown files to provide structured metadata
    - Implement a lightweight indexing system that doesn't interfere with human readability
    - Store AI-specific metadata in comments or separate configuration files
 
 3. **Version Control Integration**:
-   
+
    Leverage Git history and metadata:
 
    - Parse commit messages for context
@@ -94,7 +97,7 @@ To implement similar functionality while prioritizing human-readable documentati
    - Integrate with GitHub Issues and PRs through API
 
 4. **Context Awareness Through Standard Tools**:
-   
+
    Build context awareness using standard development tools:
 
    - Parse package.json, requirements.txt, and other dependency files
@@ -104,35 +107,40 @@ To implement similar functionality while prioritizing human-readable documentati
 
 ## Comparison: Roo Code Memory Bank vs. Human-Readable Documentation Approach
 
-| Feature | Roo Code Memory Bank | mycoder Human-Readable Approach |
-|---------|---------------------|--------------------------------|
-| **Format** | AI-specific Markdown files | Standard documentation formats |
-| **Primary Audience** | AI assistant | Human developers (with AI as secondary user) |
-| **Integration** | Custom system | Works with existing documentation workflows |
-| **Maintenance** | Requires specific knowledge of the Memory Bank system | Uses familiar documentation practices |
-| **Portability** | Tied to Roo Code | Usable with or without mycoder |
-| **Transparency** | May contain AI-specific formatting | Fully human-readable and standard |
-| **Version Control** | Files tracked in Git | Fully integrated with Git workflow |
+| Feature              | Roo Code Memory Bank                                  | mycoder Human-Readable Approach              |
+| -------------------- | ----------------------------------------------------- | -------------------------------------------- |
+| **Format**           | AI-specific Markdown files                            | Standard documentation formats               |
+| **Primary Audience** | AI assistant                                          | Human developers (with AI as secondary user) |
+| **Integration**      | Custom system                                         | Works with existing documentation workflows  |
+| **Maintenance**      | Requires specific knowledge of the Memory Bank system | Uses familiar documentation practices        |
+| **Portability**      | Tied to Roo Code                                      | Usable with or without mycoder               |
+| **Transparency**     | May contain AI-specific formatting                    | Fully human-readable and standard            |
+| **Version Control**  | Files tracked in Git                                  | Fully integrated with Git workflow           |
 
 ## Recommendations for mycoder
 
 1. **Create a Documentation-Based Context System**:
+
    - Implement a system that reads, understands, and contributes to standard documentation
    - Focus on generating high-quality human documentation rather than AI-specific formats
 
 2. **Build a Documentation Index**:
+
    - Develop a lightweight indexing system that helps the AI navigate project documentation
    - Store the index in a format that doesn't interfere with human readability
 
 3. **Implement Documentation Templates**:
+
    - Provide templates for common documentation needs
    - Ensure all generated documentation follows best practices
 
 4. **Version Control Integration**:
+
    - Deeply integrate with Git to understand project history
    - Use GitHub Issues and PRs as part of the context model
 
 5. **Contextual Awareness**:
+
    - Build systems to understand project structure and dependencies
    - Implement code analysis to understand functionality
 
@@ -144,4 +152,4 @@ To implement similar functionality while prioritizing human-readable documentati
 
 While Roo Code's Memory Bank system provides excellent persistent context management, mycoder can achieve similar functionality through a documentation-first approach that prioritizes human readability and standard practices. By leveraging existing documentation formats, version control metadata, and project artifacts, mycoder can maintain rich context while ensuring that all generated content remains valuable for human developers, with or without AI assistance.
 
-This approach aligns with the goal of making mycoder a tool that enhances standard development workflows rather than creating parallel AI-specific systems. The documentation-first strategy ensures that project knowledge remains accessible, maintainable, and useful beyond the AI assistant itself.
+This approach aligns with the goal of making mycoder a tool that enhances standard development workflows rather than creating parallel AI-specific systems. The documentation-first strategy ensures that project knowledge remains accessible, maintainable, and useful beyond the AI assistant itself.

docs/comparisons/persistent-context-approaches.md

@@ -4,30 +4,33 @@ This document compares different approaches to persistent context management in
 
 ## Comparison of Approaches
 
-| Approach | Description | Pros | Cons | Human-Readability |
-|----------|-------------|------|------|-------------------|
-| **Roo Code Memory Bank** | Dedicated Markdown files for different aspects of context (activeContext.md, decisionLog.md, etc.) | - Highly structured<br>- Optimized for AI consumption<br>- Clear separation of concerns | - Creates parallel documentation<br>- Requires understanding of specific format<br>- May duplicate information | Medium - Files are in Markdown but may contain AI-specific formatting |
-| **Standard Documentation** | Uses README.md, ARCHITECTURE.md, DECISIONS.md, etc. | - Follows established practices<br>- Useful with or without AI<br>- Integrates with existing workflows | - May lack structure for AI<br>- Could be incomplete<br>- Might need additional indexing | High - Follows standard documentation practices intended for humans |
-| **Code Comments & Docstrings** | Context embedded directly in code | - Directly connected to relevant code<br>- Updated alongside code changes<br>- Standard development practice | - Scattered across codebase<br>- May be inconsistent<br>- Limited space for detailed context | High - Standard practice for developers |
-| **Version Control Metadata** | Uses Git history, commit messages, PRs, and Issues | - Already part of development workflow<br>- Rich historical context<br>- Captures decision points | - Requires API integration<br>- Quality depends on commit practices<br>- May be noisy | High - Standard development artifacts |
-| **Hidden Metadata Files** | JSON/YAML files with AI-specific context | - Highly structured for AI<br>- Can be comprehensive<br>- Separates AI needs from human docs | - Not human-friendly<br>- Creates parallel knowledge base<br>- Maintenance burden | Low - Not intended for human consumption |
-| **Hybrid Approach** | Combines standard docs with lightweight indexing | - Leverages existing docs<br>- Enhances without replacing<br>- Balances AI and human needs | - More complex implementation<br>- Requires synchronization<br>- Needs careful design | High - Primarily uses human documentation with minimal AI-specific additions |
+| Approach                       | Description                                                                                        | Pros                                                                                                         | Cons                                                                                                           | Human-Readability                                                            |
+| ------------------------------ | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| **Roo Code Memory Bank**       | Dedicated Markdown files for different aspects of context (activeContext.md, decisionLog.md, etc.) | - Highly structured<br>- Optimized for AI consumption<br>- Clear separation of concerns                      | - Creates parallel documentation<br>- Requires understanding of specific format<br>- May duplicate information | Medium - Files are in Markdown but may contain AI-specific formatting        |
+| **Standard Documentation**     | Uses README.md, ARCHITECTURE.md, DECISIONS.md, etc.                                                | - Follows established practices<br>- Useful with or without AI<br>- Integrates with existing workflows       | - May lack structure for AI<br>- Could be incomplete<br>- Might need additional indexing                       | High - Follows standard documentation practices intended for humans          |
+| **Code Comments & Docstrings** | Context embedded directly in code                                                                  | - Directly connected to relevant code<br>- Updated alongside code changes<br>- Standard development practice | - Scattered across codebase<br>- May be inconsistent<br>- Limited space for detailed context                   | High - Standard practice for developers                                      |
+| **Version Control Metadata**   | Uses Git history, commit messages, PRs, and Issues                                                 | - Already part of development workflow<br>- Rich historical context<br>- Captures decision points            | - Requires API integration<br>- Quality depends on commit practices<br>- May be noisy                          | High - Standard development artifacts                                        |
+| **Hidden Metadata Files**      | JSON/YAML files with AI-specific context                                                           | - Highly structured for AI<br>- Can be comprehensive<br>- Separates AI needs from human docs                 | - Not human-friendly<br>- Creates parallel knowledge base<br>- Maintenance burden                              | Low - Not intended for human consumption                                     |
+| **Hybrid Approach**            | Combines standard docs with lightweight indexing                                                   | - Leverages existing docs<br>- Enhances without replacing<br>- Balances AI and human needs                   | - More complex implementation<br>- Requires synchronization<br>- Needs careful design                          | High - Primarily uses human documentation with minimal AI-specific additions |
 
 ## Implementation Considerations
 
 When implementing persistent context management, several factors should be considered:
 
 1. **Information Storage**:
+
    - Where should context be stored?
    - How should it be structured?
    - Who is the primary audience?
 
 2. **Information Retrieval**:
+
    - How does the AI find relevant context?
    - How is context prioritized?
    - What indexing or search capabilities are needed?
 
 3. **Information Maintenance**:
+
    - How is context kept up-to-date?
    - Who is responsible for maintenance?
    - How are conflicts resolved?
@@ -42,16 +45,19 @@ When implementing persistent context management, several factors should be consi
 Based on the analysis, we recommend a **Hybrid Documentation-First Approach** that:
 
 1. **Prioritizes Standard Documentation**:
+
    - Uses README.md, ARCHITECTURE.md, DECISIONS.md, ROADMAP.md, etc.
    - Follows established documentation practices
    - Ensures all persistent context is valuable to human developers
 
 2. **Implements Lightweight Indexing**:
+
    - Creates a small index file (.mycoder-index.json) that helps the AI navigate documentation
    - Uses front matter in Markdown files for additional metadata
    - Keeps AI-specific information minimal and separate
 
 3. **Leverages Version Control**:
+
    - Integrates with Git history and GitHub artifacts
    - Uses Issues and PRs as context sources
    - Analyzes commit messages for additional context
@@ -83,4 +89,4 @@ project/
     └── PULL_REQUEST_TEMPLATE/  # PR templates
 ```
 
-In this structure, the `.mycoder-index.json` file would contain minimal metadata to help the AI understand the documentation structure, but all substantive content would be in standard, human-readable documentation files.
+In this structure, the `.mycoder-index.json` file would contain minimal metadata to help the AI understand the documentation structure, but all substantive content would be in standard, human-readable documentation files.