@zenuml/core 3.32.5 → 3.32.7

package/.claude/commands/create-docs.md

@@ -0,0 +1,309 @@
+You are working on the VR Language Learning App project. The user has requested to create or regenerate documentation with the arguments: "$ARGUMENTS"
+
+## Auto-Loaded Project Context:
+@/CLAUDE.md
+@/docs/ai-context/project-structure.md
+@/docs/ai-context/docs-overview.md
+
+## CRITICAL: AI-Optimized Documentation Principles
+All documentation must be optimized for AI consumption and future-proofing:
+- **Structured & Concise**: Use clear sections, lists, and hierarchies. Provide essential information only.
+- **Contextually Complete**: Include necessary context, decision rationale ("why"), and cross-references.
+- **Pattern-Oriented**: Make architectural patterns, conventions, and data flow explicit.
+- **Modular & Scalable**: Structure for partial updates and project growth.
+- **Cross-references**: Link related concepts with file paths, function names, and stable identifiers
+
+
+---
+
+## Step 1: Analyze & Strategize
+
+Using the auto-loaded project context, analyze the user's request and determine the optimal documentation strategy.
+
+### 1.1. Parse Target & Assess Complexity
+**Action**: Analyze `$ARGUMENTS` to identify the `target_path` and its documentation tier.
+
+**Target Classification:**
+- **Tier 3 (Feature-Specific)**: Paths containing `/src/` and ending in `/CONTEXT.md`
+- **Tier 2 (Component-Level)**: Paths ending in component root `/CONTEXT.md`
+
+**Complexity Assessment Criteria:**
+- **Codebase Size**: File count and lines of code in target directory
+- **Technology Mix**: Diversity of languages and frameworks (Python, TypeScript, etc.)
+- **Architectural Complexity**: Dependency graph and cross-component imports
+- **Existing Documentation**: Presence and state of any CLAUDE.md files in the area
+
+### 1.2. Select Strategy
+Think deeply about this documentation generation task and strategy based on the auto-loaded project context. Based on the assessment, select and announce the strategy.
+
+**Strategy Logic:**
+- **Direct Creation**: Simple targets (< 15 files, single tech, standard patterns)
+- **Focused Analysis**: Moderate complexity (15-75 files, 2-3 techs, some novel patterns)
+- **Comprehensive Analysis**: High complexity (> 75 files, 3+ techs, significant architectural depth)
+
+---
+
+## Step 2: Information Gathering (Analysis Phase)
+
+Based on the chosen strategy, gather the necessary information.
+
+### Strategy A: Direct Creation
+Proceed directly to **Step 3.1**. Perform lightweight analysis during content generation.
+
+### Strategy B: Focused or Comprehensive Analysis (Sub-Agent Orchestration)
+
+#### 2.1. Sub-Agent Roles
+Select from these specialized roles based on complexity assessment:
+- **`Code_Analyzer`**: File structure, implementation patterns, logic flow, coding conventions
+- **`Tech_Stack_Identifier`**: Frameworks, libraries, dependencies, technology-specific patterns
+- **`Architecture_Mapper`**: Cross-component dependencies, integration points, data flow
+- **`Doc_Validator`**: Existing documentation accuracy, gaps, valuable insights, content overlap analysis
+
+#### 2.2. Launch Sub-Agents
+**Execution Plan:**
+- **Focused Analysis (2-3 agents)**: `Code_Analyzer` + `Tech_Stack_Identifier` + `Doc_Validator` (if existing docs)
+- **Comprehensive Analysis (3-4 agents)**: All agents as needed
+
+**CRITICAL: Launch agents in parallel using a single message with multiple Task tool invocations for optimal performance.**
+
+**Task Template:**
+```
+Task: "As the [Agent_Role], analyze the codebase at `[target_path]` to support documentation generation.
+
+Your focus: [role-specific goal, e.g., 'identifying all architectural patterns and dependencies']
+
+Standard workflow:
+1. Review auto-loaded project context (CLAUDE.md, project-structure.md, docs-overview.md)
+2. Analyze the target path for your specialized area
+3. Return structured findings for documentation generation
+
+Return a comprehensive summary of your findings for this role."
+```
+
+---
+
+## Step 3: Documentation Generation
+
+Think deeply about synthesizing findings and generating comprehensive documentation. Using gathered information, intelligently synthesize and generate the documentation content.
+
+### 3.1. Content Synthesis & Generation
+
+#### For Direct Creation (No Sub-Agents)
+**Code-First Analysis Methodology:**
+1. **Directory Structure Analysis**: Map file organization and purposes using Glob/LS
+2. **Import Dependency Analysis**: Use Grep to identify integration patterns and dependencies  
+3. **Pattern Extraction**: Read key files to identify architectural patterns and coding conventions
+4. **Technology Usage Analysis**: Detect frameworks, libraries, and technology-specific patterns
+5. **Existing Documentation Assessment**: Read any current CLAUDE.md files for valuable insights
+
+#### For Sub-Agent Strategies  
+**Synthesis Integration Process:**
+1. **Compile Core Findings**: Merge agent findings for immediate documentation generation
+2. **Extract Cross-Tier Patterns**: Identify system-wide patterns that may impact foundational documentation
+3. **Resolve Information Conflicts**: When code contradicts existing docs, use code as source of truth
+4. **Identify Content Gaps**: Find areas needing new documentation based on analysis
+5. **Apply Project Conventions**: Use coding standards and naming conventions from the auto-loaded /CLAUDE.md
+6. **Content Overlap Identification**: From Doc_Validator findings, identify existing documentation that overlaps with target content for later migration analysis
+
+#### Content Generation Process
+**For Both Approaches:**
+1. **Select Template**: Choose Tier 2 or Tier 3 based on target classification
+2. **Apply Content Treatment Strategy**:
+   - **Preserve**: Validated architectural insights from existing documentation
+   - **Enhance**: Extend existing patterns with newly discovered implementation details
+   - **Replace**: Outdated content that conflicts with current code reality
+   - **Create**: New documentation for undocumented patterns and decisions
+3. **Populate Sections**: Fill template sections with synthesized findings
+4. **Ensure Completeness**: Include architectural decisions, patterns, dependencies, and integration points
+5. **Follow AI-Optimized Principles**: Structure for AI consumption with clear cross-references
+
+### 3.2. Template Guidelines
+
+**Tier 2 (Component-Level):**
+```markdown
+# [Component Name] - Component Context
+
+## Purpose
+[Component purpose and key responsibilities]
+
+## Current Status: [Status]
+[Status with evolution context and rationale]
+
+## Component-Specific Development Guidelines
+[Technology-specific patterns and conventions]
+
+## Major Subsystem Organization
+[High-level structure based on actual code organization]
+
+## Architectural Patterns
+[Core patterns and design decisions]
+
+## Integration Points
+[Dependencies and connections with other components]
+```
+
+**Tier 3 (Feature-Specific):**
+```markdown
+# [Feature Area] Documentation
+
+## [Area] Architecture
+[Key architectural elements and integration patterns]
+
+## Implementation Patterns
+[Core patterns and error handling strategies]
+
+## Key Files and Structure
+[File organization with purposes]
+
+## Integration Points
+[How this integrates with other parts of the system]
+
+## Development Patterns
+[Testing approaches and debugging strategies]
+```
+
+---
+
+## Step 4: Finalization & Housekeeping
+
+### 4.1. Write Documentation File
+**Action**: Write the generated content to the target path.
+
+### 4.2. Update Documentation Registry
+
+#### Update docs-overview.md
+**For new documentation files:**
+- Add to appropriate tier section (Feature-Specific or Component-Level)
+- Follow established entry format with path and description
+- Maintain alphabetical ordering within sections
+
+**For updated existing files:**
+- Verify entry exists and description is current
+- Update any changed purposes or scopes
+
+#### Update Project Structure (if needed)
+**If new directories were created:**
+- Update file tree in `/docs/ai-context/project-structure.md`
+- Add directory comments explaining purpose
+- Maintain tree structure formatting and organization
+
+### 4.3. Quality Validation
+**Action**: Verify tier appropriateness, code accuracy, cross-reference validity, and consistency with existing documentation patterns.
+
+### 4.4. Tier 1 Validation & Recommendations
+
+**Action**: Compare discovered code patterns against foundational documentation to identify inconsistencies and improvement opportunities.
+
+#### Process
+1. **Discover Tier 1 Files**: Read `/docs/ai-context/docs-overview.md` to identify all foundational documentation files
+2. **Read Foundational Docs**: Load discovered Tier 1 files to understand documented architecture
+3. **Cross-Tier Analysis**: Using analysis findings from previous steps, compare:
+   - **Technology Stack**: Discovered frameworks/tools vs documented stack
+   - **Architecture Patterns**: Implementation reality vs documented decisions  
+   - **Integration Points**: Actual dependencies vs documented integrations
+4. **Generate Recommendations**: Output evidence-based suggestions for foundational documentation updates
+
+### 4.5. Content Migration & Redundancy Management
+
+**Action**: Intelligently manage content hierarchy and eliminate redundancy across documentation tiers.
+
+#### Cross-Reference Analysis
+1. **Identify Related Documentation**: Using Doc_Validator findings from Step 3.1 synthesis and target tier classification, identify existing documentation that may contain overlapping content
+2. **Content Overlap Detection**: Compare new documentation content with existing files to identify:
+   - **Duplicate Information**: Identical content that should exist in only one location
+   - **Hierarchical Overlaps**: Content that exists at wrong tier level (implementation details in architectural docs)
+   - **Cross-Reference Opportunities**: Content that should be linked rather than duplicated
+
+#### Smart Content Migration Strategy
+**Content Classification Framework:**
+- **Tier-Appropriate Duplication**: High-level architectural context can exist at both Tier 2 and Tier 3 with different detail levels
+- **Migration Candidates**: Detailed implementation patterns, specific code examples, feature-specific technical details
+- **Reference Targets**: Stable architectural decisions, design rationale, cross-cutting concerns
+
+**Migration Decision Logic:**
+1. **For Tier 3 Creation (Feature-Specific)**:
+   - **Extract from Tier 2**: Move feature-specific implementation details to new Tier 3 file
+   - **Preserve in Tier 2**: Keep high-level architectural overview and design decisions
+   - **Add Cross-References**: Link Tier 2 overview to detailed Tier 3 implementation
+
+2. **For Tier 2 Creation (Component-Level)**:
+   - **Consolidate from Multiple Tier 3**: Aggregate architectural insights from existing feature docs
+   - **Preserve Tier 3 Details**: Keep implementation specifics in feature documentation
+   - **Create Navigation Structure**: Add references to relevant Tier 3 documentation
+
+#### Content Migration Execution
+**Migration Process:**
+1. **Identify Source Content**: Extract content that should migrate from existing files
+2. **Content Transformation**: Adapt content to appropriate tier level (architectural vs implementation focus)
+3. **Update Source Files**: Remove migrated content and add cross-references to new location
+4. **Preserve Context**: Ensure source files maintain coherence after content removal
+5. **Validate Migrations**: Confirm no broken references or lost information
+
+**Safety Framework:**
+- **Conservative Defaults**: When uncertain, preserve content in original location and add references
+- **Content Preservation**: Never delete content without creating it elsewhere first
+- **Migration Reversibility**: Document all migrations to enable rollback if needed
+
+---
+
+## Step 5: Generate Summary
+
+Provide a comprehensive summary including:
+
+### Documentation Creation Results
+- **Documentation type and location** (Tier 2 or Tier 3)
+- **Strategy used** (Direct Creation, Focused Analysis, or Comprehensive Analysis)
+- **Key patterns documented** (architectural decisions, implementation patterns)
+- **Registry updates made** (docs-overview.md, project-structure.md entries)
+
+### Tier 1 Architectural Intelligence
+**Based on Step 4.4 analysis, provide structured recommendations:**
+
+#### Critical Updates Needed
+- **File**: [specific foundational doc path]
+- **Issue**: [specific inconsistency with evidence]
+- **Recommendation**: [specific update needed]
+- **Evidence**: [code references supporting the recommendation]
+
+#### Architecture Enhancement Opportunities  
+- **Gap Identified**: [missing foundational documentation area]
+- **Scope**: [what should be documented]
+- **Rationale**: [why this deserves foundational documentation]
+- **Implementation Evidence**: [code patterns discovered]
+
+#### Documentation Health Assessment
+- **Alignment Score**: [overall consistency between code and docs]
+- **Most Accurate Areas**: [foundational docs that match implementation well]
+- **Areas Needing Attention**: [foundational docs with significant gaps/inconsistencies]
+- **Systematic Improvement Priority**: [recommended order for addressing issues]
+
+#### Content Migration Results
+**Document all content hierarchy changes and redundancy eliminations:**
+
+- **Content Migrated From**: [source file path] → [target file path]
+  - **Content Type**: [e.g., "implementation patterns", "technical details", "architectural decisions"]
+  - **Rationale**: [why this content belongs at the target tier]
+  - **Cross-References Added**: [navigation links created between tiers]
+
+- **Content Preserved At**: [broader tier file]
+  - **Content Type**: [e.g., "architectural overview", "design decisions", "integration patterns"]
+  - **Rationale**: [why this content remains at the broader tier]
+
+- **Redundancies Eliminated**: 
+  - **Duplicate Content Removed**: [specific duplications eliminated]
+  - **Hierarchical Corrections**: [content moved to appropriate tier level]
+  - **Reference Consolidations**: [areas where links replaced duplication]
+
+- **Migration Safety**: 
+  - **Content Preserved**: [confirmation that no information was lost]
+  - **Rollback Information**: [documentation of changes for potential reversal]
+  - **Validation Results**: [confirmation of no broken references]
+
+#### Next Documentation Steps (Optional Recommendations)
+- **Feature-Specific Documentation Candidates**: [suggest additional Tier 3 docs that would be valuable]
+- **Cross-Component Documentation Needs**: [identify other components needing similar analysis]
+- **Documentation Debt Eliminated**: [summary of redundancies and inconsistencies resolved]
+
+---
+
+Now proceed to create/regenerate documentation based on the request: $ARGUMENTS

package/.claude/commands/full-context.md

@@ -0,0 +1,121 @@
+You are working on the VR Language Learning App project. Before proceeding with the user's request "$ARGUMENTS", you need to intelligently gather relevant project context using an adaptive sub-agent strategy.
+
+## Auto-Loaded Project Context:
+@/CLAUDE.md
+@/docs/ai-context/project-structure.md
+@/docs/ai-context/docs-overview.md
+
+## Step 1: Intelligent Analysis Strategy Decision
+Think deeply about the optimal approach based on the project context that has been auto-loaded above. Based on the user's request "$ARGUMENTS" and the project structure/documentation overview, intelligently decide the optimal approach:
+
+### Strategy Options:
+**Direct Approach** (0-1 sub-agents):
+- When the request can be handled efficiently with targeted documentation reading and direct analysis
+- Simple questions about existing code or straightforward tasks
+
+**Focused Investigation** (2-3 sub-agents):
+- When deep analysis of a specific area would benefit the response
+- For complex single-domain questions or tasks requiring thorough exploration
+- When dependencies and impacts need careful assessment
+
+**Multi-Perspective Analysis** (3+ sub-agents):
+- When the request involves multiple areas, components, or technical domains
+- When comprehensive understanding requires different analytical perspectives
+- For tasks requiring careful dependency mapping and impact assessment
+- Scale the number of agents based on actual complexity, not predetermined patterns
+
+## Step 2: Autonomous Sub-Agent Design
+
+### For Sub-Agent Approach:
+You have complete freedom to design sub-agent tasks based on:
+- **Project structure discovered** from the auto-loaded `/docs/ai-context/project-structure.md` file tree
+- **Documentation architecture** from the auto-loaded `/docs/ai-context/docs-overview.md`
+- **Specific user request requirements**
+- **Your assessment** of what investigation approach would be most effective
+
+**CRITICAL: When using sub-agents, always launch them in parallel using a single message with multiple Task tool invocations. Never launch sequentially.**
+
+### Sub-Agent Autonomy Principles:
+- **Custom Specialization**: Define agent focus areas based on the specific request and project structure
+- **Flexible Scope**: Agents can analyze any combination of documentation, code files, and architectural patterns
+- **Adaptive Coverage**: Ensure all relevant aspects of the user's request are covered without overlap
+- **Documentation + Code**: Each agent should read relevant documentation files AND examine actual implementation code
+- **Dependency Mapping**: For tasks involving code changes, analyze import/export relationships and identify all files that would be affected
+- **Impact Assessment**: Consider ripple effects across the codebase, including tests, configurations, and related components
+- **Pattern Compliance**: Ensure solutions follow existing project conventions for naming, structure, and architecture
+- **Cleanup Planning**: For structural changes, identify obsolete code, unused imports, and deprecated files that should be removed to prevent code accumulation
+- **Web Research**: Consider, optionally, deploying sub-agents for web searches when current best practices, security advisories, or external compatibility research would enhance the response
+
+### Sub-Agent Task Design Template:
+```
+Task: "Analyze [SPECIFIC_COMPONENT(S)] for [TASK_OBJECTIVE] related to user request '$ARGUMENTS'"
+
+Standard Investigation Workflow:
+1. Review auto-loaded project context (CLAUDE.md, project-structure.md, docs-overview.md)
+2. (Optionally) Read additional relevant documentation files for architectural context
+3. Analyze actual code files in [COMPONENT(S)] for implementation reality
+4. For code-related tasks: Map import/export dependencies and identify affected files
+5. Assess impact on tests, configurations, and related components
+6. Verify alignment with project patterns and conventions
+7. For structural changes: Identify obsolete code, unused imports, and files that should be removed
+
+Return comprehensive findings that address the user's request from this component perspective, including architectural insights, implementation details, dependency mapping, and practical considerations for safe execution."
+```
+
+Example Usage:
+```
+Analysis Task: "Analyze web-dashboard audio processing components to understand current visualization capabilities and identify integration points for user request about adding waveform display"
+
+Implementation Task: "Analyze agents/tutor-server voice pipeline components for latency optimization related to user request about improving response times, including dependency mapping and impact assessment"
+
+Cross-Component Task: "Analyze Socket.IO integration patterns across web-dashboard and tutor-server to plan streaming enhancement for user request about adding live transcription, focusing on import/export changes, affected test files, and cleanup of deprecated socket handlers"
+```
+
+## Step 3: Execution and Synthesis
+
+### For Sub-Agent Approach:
+Think deeply about integrating findings from all investigation perspectives.
+1. **Design and launch custom sub-agents** based on your strategic analysis
+2. **Collect findings** from all successfully completed agents
+3. **Synthesize comprehensive understanding** by combining all perspectives
+4. **Handle partial failures** by working with available agent findings
+5. **Create implementation plan** (for code changes): Include dependency updates, affected files, cleanup tasks, and verification steps
+6. **Execute user request** using the integrated knowledge from all agents
+
+### For Direct Approach:
+1. **Load relevant documentation and code** based on request analysis
+2. **Proceed directly** with user request using targeted context
+
+## Step 4: Consider MCP Server Usage (Optional)
+
+After gathering context, you may leverage MCP servers for complex technical questions as specified in the auto-loaded `/CLAUDE.md` Section 4:
+- **Gemini Consultation**: Deep analysis of complex coding problems
+- **Context7**: Up-to-date documentation for external libraries
+
+## Step 5: Context Summary and Implementation Plan
+
+After gathering context using your chosen approach:
+1. **Provide concise status update** summarizing findings and approach:
+   - Brief description of what was discovered through your analysis
+   - Your planned implementation strategy based on the findings
+   - Keep it informative but concise (2-4 sentences max)
+
+Example status updates:
+```
+"Analysis revealed the voice pipelines use Socket.IO for real-time communication with separate endpoints for each pipeline type. I'll implement the new transcription feature by extending the existing Socket.IO event handling in both the FastAPI backend and SvelteKit frontend, following the established pattern used in the Gemini Live pipeline. This will require updating 3 import statements and adding exports to the socket handler module."
+
+"Found that audio processing currently uses a modular client architecture with separate recorder, processor, and stream-player components. I'll add the requested audio visualization by creating a new component that taps into the existing audio stream data and integrates with the current debug panel structure. The implementation will follow the existing component patterns and requires updates to 2 parent components for proper integration."
+```
+
+2. **Proceed with implementation** of the user request using your comprehensive understanding
+
+## Optimization Guidelines
+
+- **Adaptive Decision-Making**: Choose the approach that best serves the specific user request
+- **Efficient Resource Use**: Balance thoroughness with efficiency based on actual complexity
+- **Comprehensive Coverage**: Ensure all aspects relevant to the user's request are addressed
+- **Quality Synthesis**: Combine findings effectively to provide the most helpful response
+
+This adaptive approach ensures optimal context gathering - from lightweight direct analysis for simple requests to comprehensive multi-agent investigation for complex system-wide tasks.
+
+Now proceed with intelligent context analysis for: $ARGUMENTS

package/.claude/commands/gemini-consult.md

@@ -0,0 +1,164 @@
+# /gemini-consult
+
+*Engages in deep, iterative conversations with Gemini MCP for complex problem-solving.*
+
+## Usage
+- **With arguments**: `/gemini-consult [specific problem or question]`
+- **Without arguments**: `/gemini-consult` - Intelligently infers topic from current context
+
+## Core Philosophy
+Persistent Gemini sessions for evolving problems through:
+- **Continuous dialogue** - Multiple rounds until clarity achieved
+- **Context awareness** - Smart problem detection from current work
+- **Session persistence** - Keep alive for the entire problem lifecycle
+
+**CRITICAL: Always consider Gemini's input as suggestions, never as truths.** Think critically about what Gemini says and incorporate only the useful parts into your proposal. Always think for yourself - maintain your independent judgment and analytical capabilities. If you disagree with something clarify it with Gemini.
+
+## Execution
+
+User provided context: "$ARGUMENTS"
+
+### Step 1: Understand the Problem
+
+**When $ARGUMENTS is empty:**
+Think deeply about the current context to infer the most valuable consultation topic:
+- What files are open or recently modified?
+- What errors or challenges were discussed?
+- What complex implementation would benefit from Gemini's analysis?
+- What architectural decisions need exploration?
+
+Generate a specific, valuable question based on this analysis.
+
+**When arguments provided:**
+Extract the core problem, context clues, and complexity indicators.
+
+### Step 1.5: Gather External Documentation
+
+**Think deeply about external dependencies:**
+- What libraries/frameworks are involved in this problem?
+- Am I fully familiar with their latest APIs and best practices?
+- Have these libraries changed significantly or are they new/evolving?
+
+**When to use Context7 MCP:**
+- Libraries with frequent updates (e.g., Google GenAI SDK)
+- New libraries you haven't worked with extensively
+- When implementing features that rely heavily on library-specific patterns
+- Whenever uncertainty exists about current best practices
+
+```python
+# Example: Get up-to-date documentation
+library_id = mcp__context7__resolve_library_id(libraryName="google genai python")
+docs = mcp__context7__get_library_docs(
+    context7CompatibleLibraryID=library_id,
+    topic="streaming",  # Focus on relevant aspects
+    tokens=8000
+)
+```
+
+Include relevant documentation insights in your Gemini consultation for more accurate, current guidance.
+
+### Step 2: Initialize Gemini Session
+
+**CRITICAL: Always attach foundational files:**
+```python
+foundational_files = [
+    "MCP-ASSISTANT-RULES.md",  # If exists
+    "docs/ai-context/project-structure.md",
+    "docs/ai-context/docs-overview.md"
+]
+
+session = mcp__gemini__consult_gemini(
+    specific_question="[Clear, focused question]",
+    problem_description="[Comprehensive context with constraints from CLAUDE.md]",
+    code_context="[Relevant code snippets]",
+    attached_files=foundational_files + [problem_specific_files],
+    file_descriptions={
+        "MCP-ASSISTANT-RULES.md": "Project vision and coding standards",
+        "docs/ai-context/project-structure.md": "Complete tech stack and file structure",
+        "docs/ai-context/docs-overview.md": "Documentation architecture",
+        # Add problem-specific descriptions
+    },
+    preferred_approach="[solution/review/debug/optimize/explain]"
+)
+```
+
+### Step 3: Engage in Deep Dialogue
+
+**Think deeply about how to maximize value from the conversation:**
+
+1. **Active Analysis**
+   - What assumptions did Gemini make?
+   - What needs clarification or deeper exploration?
+   - What edge cases or alternatives should be discussed?
+   - **If Gemini mentions external libraries:** Check Context7 MCP for current documentation to verify or supplement Gemini's guidance
+
+2. **Iterative Refinement**
+   ```python
+   follow_up = mcp__gemini__consult_gemini(
+       specific_question="[Targeted follow-up]",
+       session_id=session["session_id"],
+       additional_context="[New insights, questions, or implementation feedback]",
+       attached_files=[newly_relevant_files]
+   )
+   ```
+
+3. **Implementation Feedback Loop**
+   Share actual code changes and real-world results to refine the approach.
+
+### Step 4: Session Management
+
+**Keep Sessions Open** - Don't close immediately. Maintain for the entire problem lifecycle.
+
+**Only close when:**
+- Problem is definitively solved and tested
+- Topic is no longer relevant
+- Fresh start would be more beneficial
+
+**Monitor sessions:**
+```python
+active = mcp__gemini__list_sessions()
+requests = mcp__gemini__get_gemini_requests(session_id="...")
+```
+
+## Key Patterns
+
+### Clarification Pattern
+"You mentioned [X]. In our context of [project specifics], how does this apply to [specific concern]?"
+
+### Deep Dive Pattern
+"Let's explore [aspect] further. What are the trade-offs given our [constraints]?"
+
+### Alternative Pattern
+"What if we approached this as [alternative]? How would that affect [concern]?"
+
+### Progress Check Pattern
+"I've implemented [changes]. Here's what happened: [results]. Should I adjust the approach?"
+
+## Best Practices
+
+1. **Think deeply** before each interaction - what will extract maximum insight?
+2. **Be specific** - Vague questions get vague answers
+3. **Show actual code** - Not descriptions
+4. **Challenge assumptions** - Don't accept unclear guidance
+5. **Document decisions** - Capture the "why" for future reference
+6. **Stay curious** - Explore alternatives and edge cases
+7. **Trust but verify** - Test all suggestions thoroughly
+
+## Implementation Approach
+
+When implementing Gemini's suggestions:
+1. Start with the highest-impact changes
+2. Test incrementally
+3. Share results back with Gemini
+4. Iterate based on real-world feedback
+5. Document key insights in appropriate CONTEXT.md files
+
+## Remember
+
+- This is a **conversation**, not a query service
+- **Context is king** - More context yields better guidance
+- **Gemini sees patterns you might miss** - Be open to unexpected insights
+- **Implementation reveals truth** - Share what actually happens
+- Treat Gemini as a **collaborative thinking partner**, not an oracle
+
+The goal is deep understanding and optimal solutions through iterative refinement, not quick answers.