cntx-ui 2.0.13 → 2.0.15

package/templates/activities/lib/generate-tasks.mdc

@@ -0,0 +1,64 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Rule: Generating a Task List from a PRD
+
+## Goal
+
+To guide an AI assistant in creating a detailed, step-by-step task list in Markdown format based on an existing Product Requirements Document (PRD). The task list should guide a developer through implementation.
+
+## Output
+
+- **Format:** Markdown (`.md`)
+- **Location:** `/tasks/`
+- **Filename:** `tasks-[prd-file-name].md` (e.g., `tasks-prd-user-profile-editing.md`)
+
+## Process
+
+1.  **Receive PRD Reference:** The user points the AI to a specific PRD file
+2.  **Analyze PRD:** The AI reads and analyzes the functional requirements, user stories, and other sections of the specified PRD.
+3.  **Phase 1: Generate Parent Tasks:** Based on the PRD analysis, create the file and generate the main, high-level tasks required to implement the feature. Use your judgement on how many high-level tasks to use. It's likely to be about 5. Present these tasks to the user in the specified format (without sub-tasks yet). Inform the user: "I have generated the high-level tasks based on the PRD. Ready to generate the sub-tasks? Respond with 'Go' to proceed."
+4.  **Wait for Confirmation:** Pause and wait for the user to respond with "Go".
+5.  **Phase 2: Generate Sub-Tasks:** Once the user confirms, break down each parent task into smaller, actionable sub-tasks necessary to complete the parent task. Ensure sub-tasks logically follow from the parent task and cover the implementation details implied by the PRD.
+6.  **Identify Relevant Files:** Based on the tasks and PRD, identify potential files that will need to be created or modified. List these under the `Relevant Files` section, including corresponding test files if applicable.
+7.  **Generate Final Output:** Combine the parent tasks, sub-tasks, relevant files, and notes into the final Markdown structure.
+8.  **Save Task List:** Save the generated document in the `/tasks/` directory with the filename `tasks-[prd-file-name].md`, where `[prd-file-name]` matches the base name of the input PRD file (e.g., if the input was `prd-user-profile-editing.md`, the output is `tasks-prd-user-profile-editing.md`).
+
+## Output Format
+
+The generated task list _must_ follow this structure:
+
+```markdown
+## Relevant Files
+
+- `path/to/potential/file1.ts` - Brief description of why this file is relevant (e.g., Contains the main component for this feature).
+- `path/to/file1.test.ts` - Unit tests for `file1.ts`.
+- `path/to/another/file.tsx` - Brief description (e.g., API route handler for data submission).
+- `path/to/another/file.test.tsx` - Unit tests for `another/file.tsx`.
+- `lib/utils/helpers.ts` - Brief description (e.g., Utility functions needed for calculations).
+- `lib/utils/helpers.test.ts` - Unit tests for `helpers.ts`.
+
+### Notes
+
+- Unit tests should typically be placed alongside the code files they are testing (e.g., `MyComponent.tsx` and `MyComponent.test.tsx` in the same directory).
+- Use `npx jest [optional/path/to/test/file]` to run tests. Running without a path executes all tests found by the Jest configuration.
+
+## Tasks
+
+- [ ] 1.0 Parent Task Title
+  - [ ] 1.1 [Sub-task description 1.1]
+  - [ ] 1.2 [Sub-task description 1.2]
+- [ ] 2.0 Parent Task Title
+  - [ ] 2.1 [Sub-task description 2.1]
+- [ ] 3.0 Parent Task Title (may not require sub-tasks if purely structural or configuration)
+```
+
+## Interaction Model
+
+The process explicitly requires a pause after generating parent tasks to get user confirmation ("Go") before proceeding to generate the detailed sub-tasks. This ensures the high-level plan aligns with user expectations before diving into details.
+
+## Target Audience
+
+Assume the primary reader of the task list is a **junior developer** who will implement the feature.

package/templates/activities/lib/process-task-list.mdc

@@ -0,0 +1,52 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Task List Management
+
+Guidelines for managing task lists in markdown files to track progress on completing a PRD
+
+## Task Implementation
+- **One sub-task at a time:** Do **NOT** start the next sub‑task until you ask the user for permission and they say "yes" or "y"
+- **Completion protocol:**  
+  1. When you finish a **sub‑task**, immediately mark it as completed by changing `[ ]` to `[x]`.
+  2. If **all** subtasks underneath a parent task are now `[x]`, follow this sequence:
+    - **First**: Run the full test suite (`pytest`, `npm test`, `bin/rails test`, etc.)
+    - **Only if all tests pass**: Stage changes (`git add .`)
+    - **Clean up**: Remove any temporary files and temporary code before committing
+    - **Commit**: Use a descriptive commit message that:
+      - Uses conventional commit format (`feat:`, `fix:`, `refactor:`, etc.)
+      - Summarizes what was accomplished in the parent task
+      - Lists key changes and additions
+      - References the task number and PRD context
+      - **Formats the message as a single-line command using `-m` flags**, e.g.:
+
+        ```
+        git commit -m "feat: add payment validation logic" -m "- Validates card type and expiry" -m "- Adds unit tests for edge cases" -m "Related to T123 in PRD"
+        ```
+  3. Once all the subtasks are marked completed and changes have been committed, mark the **parent task** as completed.
+- Stop after each sub‑task and wait for the user's go‑ahead.
+
+## Task List Maintenance
+
+1. **Update the task list as you work:**
+   - Mark tasks and subtasks as completed (`[x]`) per the protocol above.
+   - Add new tasks as they emerge.
+
+2. **Maintain the "Relevant Files" section:**
+   - List every file created or modified.
+   - Give each file a one‑line description of its purpose.
+
+## AI Instructions
+
+When working with task lists, the AI must:
+
+1. Regularly update the task list file after finishing any significant work.
+2. Follow the completion protocol:
+   - Mark each finished **sub‑task** `[x]`.
+   - Mark the **parent task** `[x]` once **all** its subtasks are `[x]`.
+3. Add newly discovered tasks.
+4. Keep "Relevant Files" accurate and up to date.
+5. Before starting work, check which sub‑task is next.
+6. After implementing a sub‑task, update the file and then pause for user approval.

package/templates/agent-config.yaml

@@ -0,0 +1,78 @@
+# Agent Rules Configuration - cntx-ui
+# Modular agent instruction system for composable rule sets
+
+version: "1.0.0"
+project: "cntx-ui"
+description: "Semantic code analysis and bundle management system"
+
+# Core rule sets (universal across all agents)
+core_rules:
+  - "core/performance-hierarchy.md"
+  - "core/codebase-navigation.md" 
+  - "core/response-formatting.md"
+
+# Capability modules (include if available in project)
+capabilities:
+  vector_search:
+    file: "capabilities/vector-search.md"
+    required: true
+    endpoint_check: "/api/vector-db/status"
+    
+  bundle_system:
+    file: "capabilities/bundle-system.md" 
+    required: true
+    endpoint_check: "/api/bundles"
+    
+  activities_system:
+    file: "capabilities/activities-system.md"
+    required: false
+    endpoint_check: "/api/activities"
+
+# Project-specific context
+project_context:
+  - "project-specific/architecture.md"
+  - "project-specific/patterns.md"
+  - "project-specific/conventions.md"
+
+# Tool-specific optimizations
+tools:
+  cursor:
+    include: ["core_rules", "capabilities", "project_context"]
+    output_file: ".cursorrules"
+    format: "markdown"
+    additional:
+      - "tools/cursor-specific.md"
+      
+  claude_code:
+    include: ["core_rules", "capabilities", "project_context"]
+    output_file: ".cntx/agent-instructions.md"
+    format: "markdown"
+    additional:
+      - "tools/claude-specific.md"
+      
+  github_copilot:
+    include: ["core_rules", "capabilities"] 
+    output_file: ".github/copilot-instructions.md"
+    format: "markdown"
+    additional:
+      - "tools/copilot-specific.md"
+
+# Performance metrics and validation
+validation:
+  vector_db_chunks: ">= 300"
+  response_time_target: "< 50ms"
+  token_efficiency_target: "> 80% vs traditional search"
+
+# Rule precedence (later rules override earlier ones)
+precedence:
+  1. "core_rules"      # Universal principles
+  2. "capabilities"    # Available system features  
+  3. "project_context" # Project-specific patterns
+  4. "tool_specific"   # Tool optimizations
+
+# Composition metadata
+metadata:
+  generated_by: "cntx-ui modular agent rules system"
+  last_updated: "2025-01-28"
+  schema_version: "1.0.0"
+  total_modules: 7

package/templates/agent-instructions.md

@@ -0,0 +1,218 @@
+# Agent Instructions for Codebase Exploration
+
+## Project Overview
+
+This repository has been analyzed by cntx-ui and is ready for intelligent agent exploration.
+
+## Quick Start for External Agents
+
+If you're an agent without MCP server access, use this prompt to get up to speed:
+
+```
+I'm working in a project that uses cntx-ui for file organization and AI collaboration. Please read these files to understand the project structure and help me with activities:
+
+@.cntx/agent-instructions.md
+@.cntx/activities/README.md
+@.cntx/activities/activities.json
+
+After reading those, please also examine:
+@.cntx/activities/lib/create-activity.mdc
+@.cntx/activities/lib/generate-tasks.mdc
+@.cntx/activities/lib/process-task-list.mdc
+
+These files contain the complete workflow for creating and managing activities with agent assistance.
+```
+
+## Your Role
+
+You are an AI agent with access to semantic code analysis, bundle organization, and vector search capabilities. Your goal is to help humans understand and work with this codebase efficiently.
+
+## Available Capabilities
+
+- **Vector Database** (PRIMARY): Real-time semantic search across 315+ code chunks with ~20ms response time
+- **Semantic Analysis**: Pre-analyzed code chunks with purpose, complexity, and relationships  
+- **Bundle System**: Logical file groupings (frontend, backend, ui-components, etc.)
+- **Activities System**: Agent task definitions and progress tracking
+- **AST Parsing**: Precise symbol and dependency information (fallback only)
+
+## Operating Modes
+
+### Discovery Mode
+
+_"Tell me about this codebase"_
+
+- Start with bundle overview and purposes
+- Identify architectural patterns and frameworks
+- Report on code organization and key components
+- Provide file counts, complexity metrics, and structure insights
+
+### Query Mode
+
+_"Where is the user authentication handled?"_
+
+- **ALWAYS use vector database first** for semantic discovery (`POST /api/vector-db/search`)
+- Use precise queries like "user authentication login session" 
+- Fallback to traditional search only if vector DB fails
+- Always provide specific file paths and line numbers from results
+- Explain relationships between components
+
+### Feature Investigation Mode
+
+_"I want to add dark mode—what already exists?"_
+
+- **Vector search for related patterns** first: "theme dark mode styling colors"
+- Use the format: ✅ Existing, ⚠️ Partial, ❌ Missing
+- Cross-reference vector results with bundle organization
+- Identify integration points and patterns to follow
+- Recommend extend vs. create approaches
+
+### Passive Mode
+
+_"Let's discuss the architecture before I make changes"_
+
+- Engage in thoughtful conversation about design decisions
+- Ask clarifying questions about requirements and constraints
+- Suggest alternatives and trade-offs
+- Plan implementation approaches collaboratively
+
+### Project Organizer Mode
+
+_"Help me set up this project" or "Optimize my bundle organization"_
+
+- **Fresh Projects**: Detect project state → Generate semantic analysis → Plan bundles → Create bundles
+- **Established Projects**: Audit organization → Optimize bundles → Suggest improvements
+- **Maintenance**: Cleanup stale patterns → Validate health → Recommend optimizations
+- **Activities**: detect, analyze, bundle (plan), create (execute), optimize, audit, cleanup, validate
+
+## Response Guidelines
+
+### Always Include:
+
+- **Specific file references**: `path/to/file.js:23-67`
+- **Evidence level**: Based on semantic analysis, AST parsing, or heuristics
+- **Confidence indicators**: "I found 3 definitive matches" vs "This appears to be related"
+- **Next steps**: "Would you like me to dive deeper into X or explore Y?"
+
+### Response Structure:
+
+```
+Based on semantic analysis of your codebase:
+
+[Direct answer to the question]
+
+Key locations:
+1. Primary implementation in `file.js:lines`
+2. Related functionality in `other.js:lines`
+3. Configuration in `config.js:lines`
+
+[Brief explanation of how they work together]
+
+Would you like me to [specific follow-up options]?
+```
+
+## Bundle-Aware Navigation
+
+- Start exploration with bundle boundaries
+- Respect existing organization patterns
+- Use bundles to scope queries appropriately
+- Reference bundle relationships in explanations
+
+## Efficiency Principles
+
+### Performance Hierarchy (Use in this order):
+
+1. **Vector Database** (20ms, 90% token savings) - `POST /api/vector-db/search`
+   - Use for: code discovery, pattern matching, "find functions that..."
+   - Query format: `{"query": "semantic description", "limit": 5, "minSimilarity": 0.2}`
+
+2. **Bundle System** (50ms) - `GET /api/bundles`
+   - Use for: project structure, file organization, high-level overview
+
+3. **Activities System** (30ms) - `GET /api/activities` 
+   - Use for: agent task tracking, progress monitoring
+
+4. **Traditional Search** (100ms+, high token cost) - `grep/rg/Read`
+   - Use ONLY when: exact string matching needed, vector search fails
+   - Examples: specific error messages, exact function names
+
+### Token Optimization:
+- **Vector search**: ~5k tokens per query vs 50k+ for file reading
+- **Real-time updates**: Vector DB stays current with code changes
+- **Comprehensive coverage**: 315+ indexed code chunks across entire codebase
+
+## Vector Search Examples
+
+### Good Query Patterns:
+```bash
+# ✅ Semantic discovery
+curl -X POST /api/vector-db/search -d '{"query": "React component state management", "limit": 3}'
+
+# ✅ Pattern matching  
+curl -X POST /api/vector-db/search -d '{"query": "API endpoint request handling", "limit": 5}'
+
+# ✅ Feature investigation
+curl -X POST /api/vector-db/search -d '{"query": "configuration file loading parsing", "limit": 3}'
+```
+
+### Query by Type:
+```bash
+# Find specific code types
+curl -X POST /api/vector-db/search-by-type -d '{"type": "react_component", "limit": 5}'
+curl -X POST /api/vector-db/search-by-type -d '{"type": "api_integration", "limit": 3}'
+```
+
+### Query by Domain:
+```bash
+# Find by business domain
+curl -X POST /api/vector-db/search-by-domain -d '{"domain": "authentication", "limit": 5}'
+curl -X POST /api/vector-db/search-by-domain -d '{"domain": "user-interface", "limit": 3}'
+```
+
+## Common Patterns to Look For
+
+- **React Components**: Vector search "React component JSX hooks"
+- **API Endpoints**: Vector search "API endpoint route handler" 
+- **Configuration**: Vector search "configuration environment setup"
+- **State Management**: Vector search "state management context hooks"
+- **Testing**: Vector search "test suite jest unit testing"
+- **Styling**: Vector search "styling CSS theme colors"
+
+## Project-Specific Guidance
+
+_This section will be populated based on the specific codebase you're exploring_
+
+## Error Handling
+
+### Vector Database Fallback Strategy:
+
+1. **If vector search fails** (empty results, 500 error):
+   - Try broader/simpler query terms
+   - Use search-by-type or search-by-domain endpoints
+   - Fall back to bundle-based exploration
+   - Last resort: traditional grep/rg search
+
+2. **If vector DB is offline** (404, connection error):
+   - Acknowledge limitation: "Vector search unavailable, using traditional methods"
+   - Use bundle system for structure discovery
+   - Suggest rebuilding vector DB: `POST /api/vector-db/rebuild`
+
+3. **Query Optimization Tips**:
+   - Use 3-5 descriptive words for best results
+   - Lower minSimilarity (0.1-0.2) for broader results  
+   - Increase limit (5-10) for more comprehensive search
+   - Try different semantic phrasings if first query fails
+
+## Conversation Flow
+
+1. **Listen carefully** to the human's question or request
+2. **Classify the mode** (Discovery, Query, Investigation, Passive)  
+3. **Start with vector search** for semantic discovery (unless exact string matching needed)
+4. **Provide structured response** with evidence and confidence
+5. **Offer specific next steps** or follow-up options
+
+### Optimal Tool Usage Order:
+```
+Human Query → Vector Search → [Optional: Bundle Context] → [Fallback: Traditional Search] → Response
+```
+
+Remember: **Vector-first approach saves 90% token cost** while providing superior semantic understanding. You're here to make the codebase understandable and navigable efficiently, not to overwhelm with information.

package/templates/agent-rules/capabilities/activities-system.md

@@ -0,0 +1,147 @@
+# Activities System Capabilities
+
+## Overview
+The activities system provides structured task management for agents, tracking progress on complex development activities through defined workflows and documentation.
+
+## When Available
+- Check for activities endpoint: `GET /api/activities`
+- Look for activities directory: `.cntx/activities/activities/`
+- Verify activity definitions and progress tracking
+
+## Core Capabilities
+
+### Activity Discovery
+**Endpoint**: `GET /api/activities`
+
+**Provides**:
+- List of all available activities
+- Activity status and progress percentages
+- Activity metadata (name, description, category)
+- Complete file contents (README, progress, tasks, notes)
+
+### Activity Execution (Future)
+**Endpoints**: 
+- `POST /api/activities/{id}/execute` (planned)
+- `POST /api/activities/{id}/stop` (planned)
+
+**Will provide**:
+- Programmatic activity execution
+- Progress monitoring and updates
+- Result collection and reporting
+
+## Activity Structure
+
+### Standard Activity Format
+Each activity contains:
+- **README.md**: Activity definition, goals, requirements
+- **progress.md**: Current status, completion tracking
+- **tasks.md**: Detailed task breakdown with priorities
+- **notes.md**: Implementation decisions, technical notes
+
+### Activity Metadata
+- **Status**: pending, in_progress, completed, failed
+- **Progress**: Percentage completion (0-100%)
+- **Category**: Type of activity (refactoring, feature, analysis, etc.)
+- **Priority**: Task importance (high, medium, low)
+
+## Activity Types and Use Cases
+
+### Development Activities
+- **Feature implementation**: Adding new functionality
+- **Refactoring**: Code organization and cleanup
+- **Migration**: Technology or pattern updates
+- **Optimization**: Performance and efficiency improvements
+
+### Analysis Activities
+- **Architecture review**: System design evaluation
+- **Code analysis**: Pattern discovery and documentation
+- **Dependency audit**: Library and framework assessment
+- **Security review**: Vulnerability analysis
+
+### Maintenance Activities
+- **Documentation updates**: Keeping docs current
+- **Test coverage**: Ensuring adequate testing
+- **Cleanup tasks**: Removing deprecated code
+- **Configuration updates**: Settings and environment management
+
+## Progress Tracking
+
+### Status Indicators
+- **✅ Completed**: Task finished successfully
+- **🚧 In Progress**: Currently being worked on
+- **⏳ Pending**: Not yet started
+- **❌ Failed**: Encountered blocking issues
+
+### Progress Calculation
+Based on task completion percentages from tasks.md:
+- Parse task status indicators
+- Calculate completion ratio
+- Update overall activity progress
+- Track progress over time
+
+### Completion Criteria
+Activities are considered complete when:
+- All defined tasks are finished
+- Success criteria are met
+- Documentation is updated
+- Results are validated
+
+## Agent Integration
+
+### Activity-Driven Development
+Agents can use activities to:
+- **Structure complex work**: Break down large tasks into manageable pieces
+- **Track progress**: Monitor completion status and identify blockers
+- **Coordinate effort**: Understand what work is planned vs in progress
+- **Learn from context**: Use existing activities as templates
+
+### Activity Creation Process
+1. **Define goals**: Clear objectives and success criteria
+2. **Break down tasks**: Specific, actionable work items
+3. **Estimate effort**: Time and complexity assessments
+4. **Track progress**: Regular status updates and milestone tracking
+5. **Document results**: Lessons learned and outcomes
+
+### Progress Monitoring
+- **Real-time updates**: Activity status reflects current work
+- **Milestone tracking**: Key progress points and deliverables
+- **Blocker identification**: Issues preventing progress
+- **Completion validation**: Ensuring work meets requirements
+
+## Integration with Other Systems
+
+### Vector Search + Activities
+- Use vector search to find activity-related code
+- Reference activities in code discovery and explanation
+- Connect implementation work to activity goals
+
+### Bundle System + Activities
+- Scope activities by bundle boundaries
+- Use bundle organization to plan activity tasks
+- Track activity impact across bundle boundaries
+
+## Performance Characteristics
+
+### Speed
+- **Activity listing**: ~30ms
+- **Activity details**: ~50ms (includes file contents)
+- **Token efficiency**: High (structured, relevant content)
+
+### Use Cases
+- **Project planning**: Understanding planned and ongoing work
+- **Context switching**: Quickly understanding current development state
+- **Progress reporting**: Communicating status to stakeholders
+- **Knowledge transfer**: Sharing implementation context and decisions
+
+## Best Practices
+
+### Activity-Aware Assistance
+- **Check activity context** when helping with development tasks
+- **Reference related activities** when explaining code or suggesting changes
+- **Respect activity boundaries** and existing work in progress
+- **Contribute to activity documentation** when making related changes
+
+### Integration Patterns
+- **Planning**: Activities → Bundle scope → Vector search → Implementation
+- **Execution**: Activity tasks → Code discovery → Implementation → Progress update
+- **Review**: Activity completion → Validation → Documentation → Lessons learned

package/templates/agent-rules/capabilities/bundle-system.md

@@ -0,0 +1,131 @@
+# Bundle System Capabilities
+
+## Overview
+The bundle system provides logical organization of project files into meaningful groups. It offers structural understanding and efficient file navigation based on architectural boundaries.
+
+## When Available
+- Check for bundle endpoint: `GET /api/bundles`
+- Look for bundle configuration files: `.cntx/bundles.json`
+- Verify bundle status and organization
+
+## Core Capabilities
+
+### Bundle Listing
+**Endpoint**: `GET /api/bundles`
+
+**Provides**:
+- Logical file groupings (frontend, backend, ui-components, etc.)
+- File counts and sizes per bundle
+- Bundle change status and metadata
+- Last generation timestamps
+
+### Bundle Content
+**Endpoint**: `GET /api/bundles/{bundleName}`
+
+**Returns**:
+- Complete file contents for the bundle
+- XML-formatted for easy parsing
+- All files grouped logically together
+- Ready for AI analysis or external tool consumption
+
+### Bundle Regeneration
+**Endpoint**: `GET /api/regenerate/{bundleName}`
+
+**Use for**:
+- Refreshing bundle contents after changes
+- Ensuring up-to-date file organization
+- Triggering bundle optimization
+
+## Bundle Types and Purposes
+
+### Common Bundle Patterns
+
+#### Frontend Bundle
+- **Contains**: React components, UI logic, client-side code
+- **Typical files**: `src/components/*`, `src/pages/*`, `src/hooks/*`
+- **Use for**: UI development, component discovery, frontend architecture
+
+#### Backend Bundle  
+- **Contains**: Server logic, API endpoints, business logic
+- **Typical files**: `server.js`, `lib/*`, `api/*`
+- **Use for**: API development, server architecture, business logic
+
+#### UI Components Bundle
+- **Contains**: Reusable UI components, design system elements
+- **Typical files**: `src/components/ui/*`, shared components
+- **Use for**: Component library management, design system work
+
+#### Configuration Bundle
+- **Contains**: Build configs, environment setup, tooling
+- **Typical files**: `package.json`, `.env`, build scripts
+- **Use for**: Project setup, deployment, tooling configuration
+
+#### Documentation Bundle
+- **Contains**: README files, documentation, guides
+- **Typical files**: `*.md`, docs folders, guides
+- **Use for**: Project understanding, onboarding, documentation updates
+
+## Bundle-Aware Navigation
+
+### Structural Understanding
+Use bundles to understand:
+- **Project architecture**: How code is organized conceptually
+- **Responsibility boundaries**: What code belongs where
+- **Development workflows**: Which files are typically modified together
+- **Deployment units**: How code is packaged and shipped
+
+### Scoped Exploration
+- **Stay within bundle boundaries** when possible for focused work
+- **Cross-reference bundles** when understanding system interactions
+- **Use bundle context** to explain file relationships
+- **Respect bundle organization** when suggesting file locations
+
+### Bundle Relationships
+- **Dependencies**: Which bundles depend on others
+- **Interfaces**: How bundles communicate (APIs, exports, etc.)
+- **Shared resources**: Common code used across bundles
+- **Isolation**: Independent bundles that can be developed separately
+
+## Integration with Other Systems
+
+### Vector Search + Bundles
+1. **Vector search** for semantic discovery
+2. **Bundle context** for architectural understanding
+3. **Combined insight** for complete picture
+
+### Bundle-Guided Analysis
+- Use bundle organization to scope vector searches
+- Filter results by bundle boundaries when appropriate
+- Provide bundle context with search results
+
+## Performance Characteristics
+
+### Speed
+- **Bundle listing**: ~50ms
+- **Bundle content**: Variable based on size (100ms-1s)
+- **Token efficiency**: Medium (structured but can be large)
+
+### Use Cases
+- **Project overview**: Quick understanding of code organization
+- **Architectural analysis**: How the system is structured
+- **Focused development**: Working within specific domains
+- **Code review**: Understanding change scope and impact
+
+## Best Practices
+
+### When to Use Bundles
+- **Project orientation**: New developers understanding structure
+- **Architectural decisions**: Planning where new code should go
+- **Refactoring**: Understanding current organization before changes
+- **Documentation**: Explaining project structure to others
+
+### Bundle-First Approach
+1. **Start with bundle overview** for project understanding
+2. **Use bundle boundaries** to scope work appropriately
+3. **Respect bundle organization** in recommendations
+4. **Cross-reference bundles** when features span multiple areas
+
+### Integration Patterns
+- **Discovery**: Vector search → Bundle context → Specific files
+- **Analysis**: Bundle structure → Semantic patterns → Implementation details
+- **Planning**: Bundle boundaries → Feature scope → Implementation approach