@zenuml/core 3.32.6 → 3.32.7

package/.claude/commands/handoff.md

@@ -0,0 +1,146 @@
+You are concluding work on the VR Language Learning App project and need to create a comprehensive handoff for the next AI session. This command intelligently analyzes your current session achievements and updates the handoff document with both auto-detected progress and user-provided context.
+
+## Auto-Loaded Project Context:
+@docs/ai-context/HANDOFF.md
+@/CLAUDE.md
+
+## Step 1: Process User Arguments
+
+Handle the arguments flexibly:
+- **With Arguments**: `$ARGUMENTS` provides user context about what was accomplished or attempted
+- **Without Arguments**: Focus purely on auto-detection from session analysis
+
+User provided context: "$ARGUMENTS"
+
+## Step 2: Analyze Current Session Achievements
+
+Think about what was accomplished in this session and how to best capture it for handoff. Review your recent conversation and tool usage to identify significant work:
+
+**Auto-Detect Evidence of:**
+- **File Operations** (Write, Edit, MultiEdit tools) - what files were modified and why
+- **New Features** - functionality added or implemented
+- **Bug Fixes** - issues resolved or debugging attempts
+- **Architecture Changes** - structural improvements or refactoring
+- **Configuration Updates** - settings, dependencies, or environment changes
+- **Documentation Work** - updates to documentation files
+- **Incomplete Work** - attempts that didn't reach completion
+- **Blockers Encountered** - issues that prevented completion
+
+**Generate Session Summary:**
+```
+Session Analysis:
+- Primary work area: [component/domain affected]
+- Main accomplishments: [key achievements]
+- Files modified: [list of changed files]
+- Status: [completed/in-progress/blocked]
+- User context: [if $ARGUMENTS provided]
+```
+
+## Step 3: Analyze Auto-Loaded HANDOFF.md
+
+Analyze the auto-loaded `docs/ai-context/HANDOFF.md` to understand:
+- **Existing sections** and their current status
+- **Related ongoing work** that might connect to your session
+- **Structure and formatting** patterns to maintain consistency
+- **Unrelated content** that should be preserved
+
+## Step 4: Determine Update Strategy
+
+Think about how to best update the handoff based on this session's work. Based on your session analysis and the auto-loaded existing handoff content, decide:
+
+**If Current Work Relates to Existing Task:**
+- Update the existing section with new progress
+- Add accomplishments to "What Was Accomplished"
+- Update "Current Status" and "Current Issue" if resolved
+- Modify "Next Steps" based on new state
+
+**If Current Work is New/Unrelated:**
+- Create a new section with descriptive title
+- Include timestamp for session identification
+- Follow existing document structure and formatting
+
+**If Work Completed an Existing Task:**
+- Mark the task as completed
+- Summarize final outcome
+- Consider archiving or removing if fully resolved
+
+## Step 5: Update HANDOFF.md Intelligently
+
+Make targeted updates to the auto-loaded HANDOFF.md:
+
+### For New Sections, Include:
+```markdown
+## [Task Title] - [Status]
+
+### Current Status
+[Brief description of current state]
+
+### What Was Accomplished
+[Bulleted list of concrete achievements with file paths]
+
+### Current Issue (if applicable)
+[Any blockers or unresolved problems]
+
+### Next Steps to [Objective]
+[Actionable items for continuation]
+
+### Key Files to Review
+[List of relevant files organized by category]
+
+### Context for Next Session
+[Important notes for continuity]
+```
+
+### For Updates to Existing Sections:
+- **Add to accomplishments** without duplicating existing content
+- **Update status** if progress changed the situation
+- **Modify current issues** if problems were resolved or new ones discovered
+- **Refresh next steps** based on new progress
+
+## Step 6: Maintain Document Quality
+
+Ensure your updates follow these guidelines:
+
+**Content Quality:**
+- **Specific**: Include exact file paths and technical details
+- **Actionable**: Provide clear next steps for continuation
+- **Contextual**: Explain the reasoning behind decisions
+- **Current**: Reflect the actual state after your session
+
+**Formatting Consistency:**
+- Follow existing markdown structure and patterns
+- Use consistent heading levels and formatting
+- Maintain bullet point styles and organization
+- Preserve the document's overall structure
+
+**Information Management:**
+- **Don't duplicate** existing information unless updating it
+- **Preserve unrelated** sections that weren't part of your work
+- **Consolidate** related information rather than fragmenting it
+- **Archive completed** work appropriately
+
+## Step 7: Final Verification
+
+Before completing, verify that your handoff:
+- **Accurately reflects** what was accomplished in the session
+- **Combines** auto-detected technical changes with user-provided context
+- **Provides clear direction** for the next AI session
+- **Maintains continuity** with existing handoff content
+- **Is immediately actionable** for someone picking up the work
+
+## Quality Standards
+
+**Be Comprehensive But Concise:**
+- Include all relevant technical details
+- Focus on actionable information
+- Avoid redundancy with existing content
+
+**Maintain Professional Handoff Quality:**
+- Clear problem statements and current status
+- Specific file references and technical context
+- Logical next steps that build on current progress
+- Helpful context that speeds up the next session
+
+This intelligent handoff approach ensures smooth continuity between AI sessions while capturing both the technical reality of what was accomplished and the user's perspective on the work.
+
+Now analyze your session, combine it with the user context "$ARGUMENTS", and update the handoff document accordingly.

package/.claude/commands/refactor.md

@@ -0,0 +1,188 @@
+You are working on the VR Language Learning App project. The user has requested to refactor specific files tagged with @ symbols in their arguments: "$ARGUMENTS"
+
+## Auto-Loaded Project Context:
+@/CLAUDE.md
+@/docs/ai-context/project-structure.md
+@/docs/ai-context/docs-overview.md
+
+## Step 1: Parse Tagged Files
+Extract all @ tagged file paths from the user's arguments. Only process files that are explicitly tagged with @ symbols.
+
+**Example parsing:**
+- Input: "refactor @src/big-file.ts @components/Large.svelte"
+- Extract: ["src/big-file.ts", "components/Large.svelte"]
+
+## Step 2: Validate and Analyze Files
+For each tagged file:
+1. **Verify file exists** - If file doesn't exist, inform user and skip
+2. **Read file contents** - Understand the structure and dependencies
+3. **Analyze current directory structure** - Map existing patterns around the file
+
+## Step 3: Intelligent Analysis Strategy Decision
+Think deeply about the safest and most effective refactoring approach based on the auto-loaded project context. Based on the initial analysis from Step 2 and the auto-loaded project context, intelligently decide the optimal approach for each file:
+
+### Strategy Options:
+
+**Direct Refactoring** (0-1 sub-agents):
+- Simple files with clear, obvious split points
+- Files with minimal external dependencies
+- Standard refactoring patterns (e.g., extract utils, split large classes)
+- Low risk of breaking changes
+
+**Focused Analysis** (2-3 sub-agents):
+- Moderate complexity with specific concerns
+- Files with moderate dependency footprint
+- When one aspect needs deep analysis (e.g., complex dependencies OR intricate file structure)
+
+**Comprehensive Analysis** (3+ sub-agents):
+- High complexity files with multiple concerns
+- Extensive dependency networks
+- Novel refactoring patterns not seen in project
+- High risk of breaking changes
+- Files that are central to multiple systems
+
+## Step 4: Execute Chosen Strategy
+
+### For Direct Refactoring:
+Proceed with straightforward refactoring using the initial analysis and project context.
+
+### For Sub-Agent Approaches:
+You have complete autonomy to design and launch sub-agents based on the specific refactoring needs identified. Consider these key investigation areas and design custom agents to cover what's most relevant:
+
+**Core Investigation Areas to Consider:**
+- **File Structure Analysis**: Logical component boundaries, split points, cohesion assessment
+- **Dependency Network Mapping**: Import/export analysis, usage patterns, circular dependency risks
+- **Project Pattern Compliance**: Directory structures, naming conventions, organizational patterns
+- **Impact Assessment**: Test files, configuration files, build scripts that need updates
+- **Import Update Analysis**: All files that import from the target file and need updated import paths
+- **Technology Stack Considerations**: Language-specific patterns, framework conventions
+
+**Autonomous Sub-Agent Design Principles:**
+- **Custom Specialization**: Define agents based on the specific file's complexity and risks
+- **Flexible Agent Count**: Use as many agents as needed - scale based on actual complexity
+- **Adaptive Coverage**: Ensure critical aspects are covered without unnecessary overlap
+- **Risk-Focused Analysis**: Prioritize investigation of the highest-risk refactoring aspects
+
+**Sub-Agent Task Template:**
+```
+Task: "Analyze [SPECIFIC_INVESTIGATION_AREA] for safe refactoring of [TARGET_FILE] related to user request '$ARGUMENTS'"
+
+Standard Investigation Workflow:
+1. Review auto-loaded project context (CLAUDE.md, project-structure.md, docs-overview.md)
+2. [CUSTOM_ANALYSIS_STEPS] - Investigate the specific area thoroughly
+3. Return actionable findings that support safe and effective refactoring
+
+Return comprehensive findings addressing this investigation area."
+```
+
+**CRITICAL: When launching sub-agents, always use parallel execution with a single message containing multiple Task tool invocations.**
+
+
+## Step 5: Synthesize Analysis and Plan Refactoring
+
+Think deeply about integrating findings from all sub-agent investigations for safe and effective refactoring. Combine findings from all agents to create optimal refactoring strategy:
+
+### Integration Analysis
+- **File Structure**: Use File Analysis Agent's component breakdown
+- **Organization**: Apply Pattern Recognition Agent's directory recommendations
+- **Safety**: Implement Dependency Analysis Agent's import/export strategy
+- **Completeness**: Address Impact Assessment Agent's broader concerns
+
+### Refactoring Strategy Decision
+Based on synthesized analysis, determine:
+- **Split granularity**: How many files and what logical divisions
+- **Directory structure**: Same-level, subdirectory, or existing directory placement
+- **Import/export strategy**: How to restructure exports and update all consuming files
+- **File naming**: Following project conventions and clarity
+
+### Risk Assessment
+- **Breaking changes**: Identify and mitigate potential issues
+- **Dependency conflicts**: Plan import/export restructuring
+- **Test impacts**: Plan for test file updates
+- **Documentation needs**: Identify doc updates required
+
+## Step 6: Refactoring Value Assessment
+
+### Evaluate Refactoring Worth
+After synthesizing all analysis, critically evaluate whether the proposed refactoring will actually improve the codebase:
+
+**Positive Indicators (Worth Refactoring):**
+- File significantly exceeds reasonable size limits (500+ lines for components, 1000+ for utilities)
+- Clear separation of concerns violations (UI mixed with business logic, multiple unrelated features)
+- High cyclomatic complexity that would be reduced
+- Repeated code patterns that could be abstracted
+- Poor testability that would improve with modularization
+- Dependencies would become cleaner and more maintainable
+- Aligns with project's architectural patterns
+
+**Negative Indicators (Not Worth Refactoring):**
+- File is already well-organized despite its size
+- Splitting would create artificial boundaries that reduce clarity
+- Would introduce unnecessary complexity or abstraction
+- Dependencies would become more convoluted
+- File serves a single, cohesive purpose effectively
+- Refactoring would violate project conventions
+- Minimal actual improvement in maintainability
+
+### Decision Point
+Based on the assessment:
+
+**If Refactoring IS Worth It:**
+- Print clear summary of benefits: "✅ This refactoring will improve the codebase by: [specific benefits]"
+- Proceed automatically to Step 7 (Execute Refactoring)
+
+**If Refactoring IS NOT Worth It:**
+- Be brutally honest about why: "❌ This refactoring is not recommended because: [specific reasons]"
+- Explain what makes the current structure acceptable
+- Ask user explicitly: "The file is currently well-structured for its purpose. Do you still want to proceed with the refactoring? (yes/no)"
+- Only continue if user confirms
+
+## Step 7: Execute Refactoring
+
+Implement the refactoring based on the synthesized analysis:
+
+### File Creation Order
+1. **Create directories** - Create any new subdirectories needed
+2. **Create core files** - Start with main/index files
+3. **Create supporting files** - Types, utils, constants
+4. **Update imports** - Fix all import/export statements
+5. **Update original file** - Replace with new modular structure
+
+### Import/Export Management
+- **Update all consuming files** - Modify import statements to point to new file locations
+- **Restructure exports** - Organize exports in the new file structure
+- **Update relative imports** - Fix paths throughout the codebase
+- **Follow naming conventions** - Use project's established patterns
+
+### Quality Assurance
+- **Preserve functionality** - Ensure no breaking changes
+- **Maintain type safety** - Keep all TypeScript types intact
+- **Follow coding standards** - Apply project's style guidelines
+- **Test compatibility** - Verify imports work correctly
+
+
+## Step 8: Quality Verification
+
+For each refactored file:
+- **Check imports** - Verify all imports resolve correctly
+- **Run type checks** - Ensure TypeScript compilation passes
+- **Test functionality** - Confirm no breaking changes
+- **Validate structure** - Ensure new organization follows project patterns
+
+
+## Error Handling
+- **File not found** - Skip and inform user
+- **Not worth refactoring** - Skip files that are good as is and give users an explanation.
+- **Parse errors** - Report syntax issues and skip
+- **Import conflicts** - Resolve or report issues
+
+## Summary Format
+Provide a comprehensive summary of:
+- **Analysis Results**: Key findings from each sub-agent
+- **Refactoring Strategy**: Chosen approach and rationale
+- **Value Assessment**: Whether refactoring improves the code (from Step 6)
+- **Files Created**: New structure with explanations (if refactoring proceeded)
+- **Dependencies Fixed**: Import/export changes made (if refactoring proceeded)
+- **Issues Encountered**: Any problems and resolutions
+
+Now proceed with multi-agent analysis and refactoring of the tagged files: $ARGUMENTS

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

@@ -0,0 +1,314 @@
+You have just completed work on the VR Language Learning App project. Analyze changes based on the provided context and automatically update relevant documentation.
+
+## Auto-Loaded Project Context:
+@/CLAUDE.md
+@/docs/ai-context/project-structure.md
+@/docs/ai-context/docs-overview.md
+
+## Core Documentation Principle: Document Current State Only
+
+**CRITICAL: Always document the current "is" state of the system. Never reference legacy implementations, describe improvements made, or explain what changed. Documentation should read as if the current implementation has always existed.**
+
+### Documentation Anti-Patterns to Avoid:
+- ❌ "Refactored the voice pipeline to use streaming instead of batch processing"
+- ❌ "Improved performance by implementing caching"
+- ❌ "Previously used X, now uses Y for better results"
+- ❌ "Legacy implementation has been replaced with..."
+
+### Documentation Best Practices:
+- ✅ "The voice pipeline uses streaming for real-time processing"
+- ✅ "Implements caching for frequently accessed data"
+- ✅ "Uses Y for optimal results"
+- ✅ "The system architecture follows..."
+
+## Step 1: Analyze Changes Based on Input
+
+### Determine Analysis Mode:
+- **No input (default)**: Analyze recent conversation context
+- **Git commit ID** (e.g., "3b8d24e" or full hash): Analyze specific commit
+- **"uncommitted"/"staged"/"working"**: Analyze uncommitted changes
+- **"last N commits"** (e.g., "last 3 commits"): Analyze recent commits
+
+### Execute Analysis:
+Based on the input parameter:
+
+#### For Git Commit Analysis:
+```bash
+# Get commit details
+git show --name-status [COMMIT_ID]
+git diff [COMMIT_ID]^ [COMMIT_ID]
+```
+
+#### For Uncommitted Changes:
+```bash
+# Get staged and unstaged changes
+git status --porcelain
+git diff HEAD
+git diff --cached
+```
+
+#### For Recent Commits:
+```bash
+# Get recent commit history
+git log --oneline -n [N]
+git diff HEAD~[N] HEAD
+```
+
+#### For Session Context (default):
+Review your recent conversation and tool usage for significant changes.
+
+**Look for Evidence of Documentation-Relevant Changes:**
+- **New features or components** (functionality that needs documenting)
+- **Architecture decisions** (new patterns, structural changes, design decisions)
+- **Technology stack changes** (new dependencies, framework additions, integration changes)
+- **API changes** (new endpoints, modified interfaces, breaking changes)
+- **Configuration changes** (new environment variables, settings, deployment requirements)
+- **File structure changes** (new directories, moved components, reorganized code)
+
+**Exclude from Documentation Updates:**
+- Performance optimizations without architectural impact
+- Bug fixes that don't change interfaces or patterns
+- Code cleanup, refactoring that doesn't affect usage
+- Logging improvements, debugging enhancements
+- Test additions without new functionality
+
+**Generate a brief summary** of what was accomplished:
+```
+Analysis source: [session context/commit ID/uncommitted changes]
+Detected changes: [1-2 sentence summary of main work done]
+```
+
+## Step 2: Understand Project Context and Documentation Structure
+
+Analyze the auto-loaded foundational files:
+1. `/CLAUDE.md` - **CRITICAL:** Understand AI instructions, coding standards, and development protocols that govern the project
+2. `/docs/ai-context/project-structure.md` - **FOUNDATION:** Technology stack, complete file tree and architecture overview
+3. `/docs/ai-context/docs-overview.md` - Understand:
+   - What documentation files exist and their purposes
+   - How the documentation is organized
+   - Which types of changes map to which documentation
+
+**AI-First Documentation Principle**: Remember that documentation is primarily for AI consumption - optimize for file path references, clear structure markers, and machine-readable patterns that enable efficient context loading.
+
+## Step 3: Intelligent Update Strategy Decision
+
+Think deeply about the documentation updates needed based on the auto-loaded project context and detected changes. Based on the detected changes from Step 1 AND the auto-loaded project context, intelligently decide the optimal approach:
+
+### Strategy Options:
+
+**Direct Update** (0-1 sub-agents):
+- Simple file modifications with clear documentation mapping
+- Bug fixes or minor enhancements that don't affect architecture
+- Changes confined to a single component or feature area
+- Standard patterns already well-documented in the project
+
+**Focused Analysis** (2-3 sub-agents):
+- Moderate complexity changes affecting multiple files
+- New features that introduce novel patterns
+- Changes that span 2-3 components or documentation tiers
+- Technology stack updates requiring validation across docs
+
+**Comprehensive Analysis** (3+ sub-agents):
+- Complex architectural changes affecting multiple system areas
+- Major refactoring that restructures component relationships
+- New integrations that create cross-system dependencies
+- Changes that require extensive documentation cascade updates
+
+## Step 4: Execute Chosen Strategy
+
+### For Direct Update:
+Proceed with straightforward documentation updates using the detected changes and auto-loaded foundational context. Continue with Step 5 (Final Decision Making).
+
+### For Sub-Agent Approaches:
+You have complete autonomy to design sub-agents based on the specific changes detected. Consider these investigation areas and design custom agents to cover what's most relevant:
+
+**Core Investigation Areas to Consider:**
+- **Change Impact Analysis**: Map file modifications to affected documentation across all tiers
+- **Architecture Validation**: Verify existing architectural docs still reflect current implementation
+- **Cross-Component Dependency Mapping**: Identify documentation updates needed due to integration changes
+- **Documentation Accuracy Assessment**: Validate current docs against modified code patterns
+- **Tier Cascade Requirements**: Determine which documentation levels need updates based on change scope
+- **Technology Stack Verification**: Ensure tech stack changes are reflected across relevant documentation
+
+**Autonomous Sub-Agent Design Principles:**
+- **Custom Specialization**: Define agents based on the specific change complexity and documentation impact
+- **Flexible Agent Count**: Use as many agents as needed - scale based on actual change scope
+- **Adaptive Coverage**: Ensure all affected documentation areas are covered without unnecessary overlap
+- **Update-Focused Analysis**: Prioritize investigation that directly supports accurate documentation updates
+
+**Sub-Agent Task Template:**
+```
+Task: "Analyze [SPECIFIC_INVESTIGATION_AREA] for documentation updates based on changes from [SOURCE]: [DETECTED_CHANGES]"
+
+Standard Investigation Workflow:
+1. Review auto-loaded project context (CLAUDE.md, project-structure.md, docs-overview.md)
+2. [CUSTOM_ANALYSIS_STEPS] - Investigate the specific area thoroughly
+3. Return actionable findings that identify required documentation updates
+
+Return comprehensive findings addressing this investigation area for documentation updates.
+```
+
+**CRITICAL: When using sub-agents, always launch them in parallel using a single message with multiple Task tool invocations.**
+
+## Step 5: Synthesize Analysis and Plan Updates
+
+### For Sub-Agent Approaches:
+Think deeply about integrating findings from all sub-agent investigations for optimal documentation updates. Combine findings from all agents to create optimal documentation update strategy:
+
+**Integration Analysis:**
+- **Change Impact**: Use Change Impact Agent's mapping of modifications to documentation
+- **Architecture Validation**: Apply Architecture Validation Agent's findings on outdated information
+- **Dependency Updates**: Implement Cross-Component Agent's integration change requirements
+- **Accuracy Corrections**: Address Documentation Accuracy Agent's identified inconsistencies
+- **Cascade Planning**: Execute Tier Cascade Agent's multi-level update requirements
+
+**Update Strategy Decision:**
+Based on synthesized analysis, determine:
+- **Documentation scope**: Which files need updates and at what detail level
+- **Update priority**: Critical architectural changes vs. minor pattern updates
+- **Cascade requirements**: Which tier levels need coordinated updates
+- **New file creation**: Whether new documentation files are warranted
+
+## Step 6: Final Decision Making
+
+Based on your context analysis and the auto-loaded documentation structure (either direct or synthesized from sub-agents), decide:
+- **Which documents need updates** (match changes to appropriate documentation)
+- **What type of updates** (component changes, architecture decisions, new patterns, etc.)
+- **Update scope** (major changes get more detail, minor changes get brief updates)
+- **Whether new documentation files are needed** (see Smart File Creation guidelines below)
+
+## Step 7: Smart File Creation (If Needed)
+
+Before updating existing documentation, assess if new documentation files should be created based on the 3-tier system:
+
+### Guidelines for Creating New Documentation Files
+
+**Create new Component CONTEXT.md when:**
+- You detect an entirely new top-level component (new directory under `agents/`, `unity-client/`, `supabase-functions/`, etc.)
+- The component has significant functionality (5+ meaningful files)
+- Example: Adding `agents/lesson-generator/` → Create `agents/lesson-generator/CONTEXT.md`
+
+**Create new Feature-Specific CONTEXT.md when:**
+- You detect a new complex subsystem within an existing component
+- The subsystem has 3+ files and represents a distinct functional area
+- No existing granular CONTEXT.md file covers this area
+- Example: Adding `agents/tutor-server/src/features/translation/` with multiple files → Create `agents/tutor-server/src/features/CONTEXT.md`
+
+**When NOT to create new files:**
+- Small additions (1-2 files) that fit existing documentation scope
+- Bug fixes or minor modifications
+- Temporary or experimental code
+
+**File Creation Process:**
+1. **Create the new CONTEXT.md file** with placeholder content following the pattern of existing granular docs
+2. **Update `/docs/ai-context/docs-overview.md`** to include the new file in the appropriate tier
+3. **Document the addition** in the current update process
+
+### File Content Template for New Granular CONTEXT.md:
+```markdown
+# [Feature Area] Documentation
+
+*This file documents [specific area] patterns and implementations within [component].*
+
+## [Area] Architecture
+- [Key architectural elements]
+
+## Implementation Patterns
+- [Key patterns used]
+
+## Integration Points
+- [How this integrates with other parts]
+
+---
+
+*This file was created as part of the 3-tier documentation system to document [brief reason].*
+```
+
+## Step 8: Tier-First Documentation Updates
+
+**CRITICAL: Always start with Tier 3 (feature-specific) documentation and work upward through the tiers. Never skip tiers.**
+
+### Tier 3 (Feature-Specific) - START HERE
+**Always begin with the most granular documentation closest to your changes:**
+- **Identify affected Tier 3 files** (feature-specific CONTEXT.md files in subdirectories)
+- **Update these granular files first** with specific implementation details, patterns, and integration points
+- **Examples**: `agents/tutor-server/src/core/pipelines/CONTEXT.md`, `web-dashboard/src/lib/api/CONTEXT.md`, `agents/tutor-server/src/features/*/CONTEXT.md`
+- **Update guidelines**: Be specific about file names, technologies, implementation patterns
+
+### Tier 2 (Component-Level) - CASCADE UP
+**After completing Tier 3 updates, evaluate if component-level changes are needed:**
+- **Check parent component CONTEXT.md files** (e.g., `agents/tutor-server/CONTEXT.md` for changes in `agents/tutor-server/src/*/`)
+- **Update if changes represent significant architectural shifts** affecting the overall component
+- **Focus on**: How granular changes affect component architecture, new integration patterns, major feature additions
+- **Examples**: `agents/tutor-server/CONTEXT.md`, `web-dashboard/CONTEXT.md`, `unity-client/CONTEXT.md`
+
+### Tier 1 (Foundational) - CASCADE UP
+**Finally, check if foundational documentation needs updates for system-wide impacts:**
+
+#### Project Structure Updates (`/docs/ai-context/project-structure.md`)
+Update for any of these changes:
+- **File tree changes**: Created, moved, deleted files/directories; renamed components; restructured organization
+- **Technology stack updates**: New dependencies (check pyproject.toml, package.json), major version updates, new frameworks, AI service changes, development tool modifications
+
+#### Other Foundational Documentation
+Update other `/docs/ai-context/` files if changes affect:
+- **System-wide architectural patterns**
+- **Cross-component integration approaches**
+- **Development workflow or standards**
+
+### Cascade Decision Logic
+**What Constitutes "Significant Updates" Requiring Cascade:**
+- **New major feature areas** (not just bug fixes or minor enhancements)
+- **Architectural pattern changes** that affect how components integrate with others
+- **New technologies or frameworks** introduced to a component
+- **Major refactoring** that changes component structure or responsibilities
+- **New integration points** between components or external systems
+
+### Update Quality Guidelines (All Tiers)
+- **Be concise** (max 3 sentences unless major architectural change)
+- **Be specific** (include file names, technologies, key benefits)
+- **Follow existing patterns** in each document
+- **Avoid redundancy** (don't repeat what's already documented)
+- **Co-locate knowledge** (keep documentation near relevant code)
+
+## Step 9: Update Documentation Overview
+
+**IMPORTANT:** After updating any documentation files in steps 1-8, check if the documentation overview needs updates:
+- Reference the auto-loaded `/docs/ai-context/docs-overview.md`
+- If you added new documentation files (especially new CONTEXT.md files), update the overview to include them in the appropriate tier
+- If you significantly changed the structure/purpose of existing documentation, update the overview to reflect these changes
+- Keep the overview accurate and current so it serves as a reliable guide to the documentation architecture
+
+### Special Note for New CONTEXT.md Files:
+When you create new granular CONTEXT.md files, you MUST add them to the appropriate section in docs-overview.md:
+- **Tier 2 (Component-Level)**: For new top-level components
+- **Tier 3 (Feature-Specific)**: For new subsystem documentation within existing components
+
+## Quality Guidelines
+
+- **Concise:** Keep updates brief and focused
+- **Specific:** Include file names, technologies, key benefits
+- **Accurate:** Based on actual changes made, not assumptions
+- **Helpful:** Information that would be useful to another developer
+- **Current:** Ensure file tree reflects actual project structure
+- **Organized:** Follow the 3-tier documentation system principles
+
+## When Not to Update or Create Documentation
+
+Skip documentation updates/creation for:
+- Bug fixes (unless they change architecture)
+- Minor tweaks or cleanup
+- Debugging or temporary changes
+- Code formatting or comments
+- Trivial modifications
+- Single-file additions that fit existing documentation scope
+
+## 3-Tier System Benefits
+
+This enhanced approach leverages the 3-tier documentation system to:
+- **Minimize cascade effects**: Most changes update 1-2 granular files
+- **Scale intelligently**: New documentation created only when warranted
+- **Co-locate knowledge**: Documentation lives near relevant code
+- **Maintain consistency**: Clear guidelines for when and how to extend documentation
+
+Now analyze the specified changes and update the relevant documentation accordingly.