# 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 orchestra (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_services.sh            # Services 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 orchestra command
├── cli_load.sh              # Main loader for orchestra-cli components
├── env_copy.sh              # Rust env copy helper/wrapper
├── build/                   # Build system components
│   ├── services.sh            # Services testing logic
│   ├── dependencies.sh      # Dependency checking
│   ├── install.sh           # Installation procedures
│   ├── load.sh              # Build system loader
│   ├── logging.sh           # Build-specific logging
│   ├── rust.sh              # Rust compilation logic
│   └── usage.sh             # Build command usage
├── git/                     # Git-specific utilities
│   └── gwr_worktree_title.sh # Worktree title generation
└── gwr/                     # TUI launcher components
    └── check-updates.sh     # Update checking functionality
```

## Core System Files

### gwr_load.sh
**Purpose**: Main loader for the orchestra Rust TUI launcher system
**Usage**: Sourced by orchestra.sh to load all necessary components
**Key Functions**: 
- Loads all TUI launcher 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 the TUI launcher
**Usage**: Provides consistent color scheme across TUI launcher 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 TUI launcher operations
**Key Functions**:
- `gwr_info()`, `gwr_success()`, `gwr_warn()`, `gwr_error()` - Colored logging functions
- Provides consistent output formatting across the TUI launcher system

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

### gwr_services.sh
**Purpose**: Services script validation and setup
**Usage**: Ensures services.sh is available and executable
**Key Functions**:
- `gwr_check_services_script()` - Validates services 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 tui binary location
**Key Functions**:
- `gwr_find_binary()` - Searches for 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 the orchestra 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 (cli_*)

### cli_load.sh
**Purpose**: Main loader for the orchestra-cli system
**Usage**: Sourced by orchestra-cli.sh to load CLI-specific components
**Key Functions**: 
- Loads all CLI-specific modules in correct order
- Provides `cli_load_core()` function
**Dependencies**: CLI helper files in shell/

### cli_info.sh, cli_err.sh, cli_debug.sh, cli_have_cmd.sh
**Purpose**: CLI equivalents of TUI launcher modules
**Usage**: Provide CLI-specific implementations of core functionality
**Key Differences**: Optimized for command-line usage rather than TUI interaction

## Shared System Files

### env_copy.sh
**Purpose**: Rust env copy helper for CLI and services flows
**Usage**: Locates and invokes the `env-copy` binary
**Key Functions**:
- `env_copy_bin()` - Resolve the env copy binary path
- `env_copy_files()` - Execute env copy with repo config

## Build System (build/)

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

### 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

### services.sh, dependencies.sh, install.sh, logging.sh, 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 `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 (shell/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

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

### orchestra-cli.sh Integration
- Sources `cli_load.sh` to load all CLI components
- Uses `env_copy.sh` to invoke the Rust env copy binary
- Provides CLI interface to same underlying functionality

### Services System Integration
- `gwr_services.sh` validates services script availability
- Root `services.sh` delegates to `server/services/dispatch.sh`
- Server services modules live under `server/services/`; keep shell modules focused on CLI/TUI launchers and shared command helpers.
- Services script enables Rust TUI to communicate with bash APIs
- Critical for the hybrid Rust/bash architecture

## Key Architectural Patterns

1. **Modular Loading**: The TUI and CLI systems each have a 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 TUI Launcher 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 `load.sh` if needed
3. Follow existing build system patterns
4. Update `usage.sh` for new build options

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