# Shell Directory - AI Context Documentation

This document provides comprehensive context for AI agents and LLMs working with the Orchestrator shell system. It describes the purpose, structure, and usage of all files in the `shell/` directory and its subdirectories.

## Directory Structure Overview

```
shell/
├── gwr_load.sh              # Main loader for gwr (Rust TUI) components
├── gwr_colors.sh            # Color definitions and terminal styling
├── gwr_logging.sh           # Logging utilities and output formatting
├── gwr_git.sh               # Git repository validation functions
├── gwr_bridge.sh            # Bridge script validation and setup
├── gwr_binary.sh            # Binary discovery and validation
├── gwr_terminal.sh          # Terminal title and environment setup
├── gwr_usage.sh             # Usage/help text for gwr command
├── gw_load.sh               # Main loader for gw (CLI) components
├── gw_colors.sh             # Color definitions for gw CLI
├── gw_logging.sh            # Logging for gw CLI
├── gw_git.sh                # Git operations for gw CLI
├── gw_worktree.sh           # Worktree management for gw CLI
├── gw_usage.sh              # Usage text for gw command
├── gw_env_copy.sh           # Rust env copy helper/wrapper
├── commands.sh              # Shared command utilities
├── build/                   # Build system components
│   ├── build_bridge.sh      # Bridge building logic
│   ├── build_dependencies.sh # Dependency checking
│   ├── build_install.sh     # Installation procedures
│   ├── build_load.sh        # Build system loader
│   ├── build_logging.sh     # Build-specific logging
│   ├── build_rust.sh        # Rust compilation logic
│   └── build_usage.sh       # Build command usage
├── git/                     # Git-specific utilities
│   └── gwr_worktree_title.sh # Worktree title generation
└── gwr/                     # gwr-specific components
    └── check-updates.sh     # Update checking functionality
```

## Core System Files

### gwr_load.sh
**Purpose**: Main loader for the gwr (Rust TUI) system
**Usage**: Sourced by gwr.sh to load all necessary components
**Key Functions**: 
- Loads all gwr-specific modules in correct order
- Provides `gwr_load_core()` function
**Dependencies**: All gwr_*.sh files in shell/

### gwr_colors.sh
**Purpose**: Color definitions and terminal styling for gwr
**Usage**: Provides consistent color scheme across gwr components
**Key Variables**:
- `BLUE`, `GREEN`, `YELLOW`, `RED`, `NC` - ANSI color codes
- Used for status messages, errors, and UI feedback

### gwr_logging.sh
**Purpose**: Logging and output formatting utilities
**Usage**: Standardized logging functions for gwr operations
**Key Functions**:
- `gwr_info()`, `gwr_success()`, `gwr_warn()`, `gwr_error()` - Colored logging functions
- Provides consistent output formatting across gwr system

### gwr_git.sh
**Purpose**: Git repository validation and setup
**Usage**: Ensures gwr runs in valid git repositories
**Key Functions**:
- `gwr_check_git_repo()` - Validates git repository presence
- Provides error messages and guidance for git setup

### gwr_bridge.sh
**Purpose**: Bridge script validation and setup
**Usage**: Ensures gw-bridge.sh is available and executable
**Key Functions**:
- `gwr_check_bridge_script()` - Validates bridge script presence
- Critical for Rust TUI communication with bash APIs

### gwr_binary.sh
**Purpose**: Binary discovery and validation for Rust TUI
**Usage**: Finds and validates gw-tui binary location
**Key Functions**:
- `gwr_find_binary()` - Searches for gw-tui binary in multiple locations
- Supports development, release, and installed binary locations
- Handles GW_TUI_BIN environment variable override

### gwr_terminal.sh
**Purpose**: Terminal environment setup
**Usage**: Configures terminal for optimal TUI experience
**Key Functions**:
- `gwr_set_terminal_title()` - Sets terminal window title
- Provides terminal compatibility and environment setup

### gwr_usage.sh
**Purpose**: Help and usage information for gwr command
**Usage**: Displays comprehensive help text
**Key Functions**:
- `gwr_show_usage()` - Shows command-line options and navigation help
- Includes keyboard shortcuts, examples, and requirements

## CLI System Files (gw_*)

### gw_load.sh
**Purpose**: Main loader for the gw (CLI) system
**Usage**: Sourced by gw.sh to load CLI-specific components
**Key Functions**: 
- Loads all gw-specific modules in correct order
- Provides `gw_load_core()` function
**Dependencies**: All gw_*.sh files in shell/

### gw_colors.sh, gw_logging.sh, gw_git.sh, gw_worktree.sh, gw_usage.sh
**Purpose**: CLI equivalents of gwr modules
**Usage**: Provide CLI-specific implementations of core functionality
**Key Differences**: Optimized for command-line usage rather than TUI interaction

## Shared System Files

### gw_env_copy.sh
**Purpose**: Rust env copy helper for CLI and bridge flows
**Usage**: Locates and invokes the `gw-env-copy` binary
**Key Functions**:
- `gw_env_copy_bin()` - Resolve the env copy binary path
- `gw_env_copy_files()` - Execute env copy with repo config

### commands.sh
**Purpose**: Shared command utilities
**Usage**: Common command-line operations used across systems
**Key Functions**:
- `have_command()` - Command availability checking
- Shared utility functions for both gwr and gw systems

## Build System (build/)

### build_load.sh
**Purpose**: Loader for build system components
**Usage**: Loads all build-related modules
**Key Functions**: `build_load_core()` - Loads build system modules

### build_rust.sh
**Purpose**: Rust compilation and binary management
**Usage**: Handles Rust TUI compilation and installation
**Key Functions**:
- Rust project compilation
- Binary installation and management
- Cross-platform binary handling

### build_bridge.sh, build_dependencies.sh, build_install.sh, build_logging.sh, build_usage.sh
**Purpose**: Specialized build system components
**Usage**: Handle specific aspects of the build process
**Key Functions**: Each focuses on a specific build operation

## Rust Env Copy

Environment file copying is implemented in Rust via the `gw-env-copy` binary.
Shell wrappers invoke the binary and read `.orchestra/options.json` for
`copy_locations` when needed.

## Git Utilities (git/)

### gwr_worktree_title.sh
**Purpose**: Worktree title generation for tmux sessions
**Usage**: Creates descriptive titles for worktree-based tmux sessions
**Key Functions**: `gwr_worktree_title()` - Generates formatted worktree titles

## Update System (gwr/)

### check-updates.sh
**Purpose**: Update checking functionality
**Usage**: Checks for newer versions from npm and homebrew
**Key Functions**:
- `detect_installation_method()` - Determines how Orchestra was installed
- `get_npm_latest_version()`, `get_brew_latest_version()` - Fetches latest versions
- `check_updates()` - Main update checking logic
- Provides update instructions based on installation method

## Integration Points

### gwr.sh Integration
- Sources `gwr_load.sh` to load all gwr components
- Uses `--check-updates` flag to trigger update checking
- Passes bridge path to Rust TUI binary

### gw.sh Integration
- Sources `gw_load.sh` to load all gw components
- Uses `gw_env_copy.sh` to invoke the Rust env copy binary
- Provides CLI interface to same underlying functionality

### Bridge System Integration
- `gwr_bridge.sh` validates bridge script availability
- Bridge script enables Rust TUI to communicate with bash APIs
- Critical for the hybrid Rust/bash architecture

## Key Architectural Patterns

1. **Modular Loading**: Each system (gwr/gw) has its own loader that sources components in dependency order
2. **Color Consistency**: Separate color files ensure consistent theming across components
3. **Logging Standardization**: Standardized logging functions provide consistent output
4. **Environment Isolation**: Rust env copy binary handles .env file replication across worktrees
5. **Binary Discovery**: Sophisticated binary finding supports development, build, and installed scenarios
6. **Update Integration**: Update checking integrated into main launcher with installation method detection

## Usage Examples for AI Agents

### Adding New gwr Functionality
1. Create new function in appropriate module (e.g., `gwr_new_feature.sh`)
2. Add to `gwr_load.sh` loading sequence
3. Update `gwr_usage.sh` if adding user-facing features
4. Follow existing patterns for colors, logging, and error handling

### Modifying Update Checking
1. Edit `shell/gwr/check-updates.sh`
2. Update version constants if needed
3. Test with different installation methods (npm, brew, local)
4. Ensure graceful handling of missing package managers

### Adding Build System Features
1. Create new module in `shell/build/`
2. Add to `build_load.sh` if needed
3. Follow existing build system patterns
4. Update `build_usage.sh` for new build options

This documentation provides the foundation for AI agents to understand and work effectively with the Orchestrator shell system.
