================================================================================
                           RP BUILD SYSTEM SHORTCUTS
                              Quick Reference Guide
================================================================================

OVERVIEW
--------
This document describes all keyboard shortcuts available during build
operations in the rp AI assistant. These shortcuts allow you to control
build execution, monitor costs, and customize output in real-time.

================================================================================
VISUAL CONTROL SHORTCUTS
================================================================================

Ctrl+K  -  Clear Current Step Output
         Clears the terminal display to remove clutter from previous steps.
         Use when output becomes too long and you want a fresh view.
         Works in any build phase.

Ctrl+L  -  Toggle Live Cost Ticker
         Shows or hides the real-time cost tracking panel that displays:
         - Current build cost
         - Session cost
         - Budget remaining
         - Burn rate (cost per second)
         Default: Enabled

Ctrl+H  -  Show Build History
         Displays the last 5 completed steps with their:
         - Success/failure status
         - Cost per step
         - Duration
         Useful for reviewing what has been accomplished.

Ctrl+I  -  Toggle Token Breakdown
         When enabled, the cost panel shows detailed token counts:
         - Input tokens and their cost
         - Output tokens and their cost
         Helps understand where costs are coming from.

================================================================================
EXECUTION CONTROL SHORTCUTS
================================================================================

Ctrl+Shift+P  -  Pause/Resume Execution
               Temporarily pauses the current build without canceling.
               Use to inspect intermediate results or add notes.
               Press again to resume from where you left off.

Ctrl+D  -  Dry-Run Mode Toggle
         When enabled, shows cost estimates without executing.
         Useful for:
         - Planning complex builds
         - Estimating costs before committing
         - Testing build configurations
         No API calls made in dry-run mode.

Ctrl+R  -  Retry Last Failed Step
         Re-executes the most recent step that failed.
         Only available when a step has failed.
         Does not affect previous successful steps.

Ctrl+E  -  Export Session Logs
         Saves all build logs to a timestamped JSON file.
         Location: ~/.local/share/rp/logs/build_session_YYYYMMDD_HHMMSS.json
         Includes:
         - All step results
         - Cost breakdown
         - Error messages
         - User notes

================================================================================
BUILD ANALYSIS SHORTCUTS
================================================================================

Alt+D  -  Decrease Verbosity
        Reduces the amount of detail shown per step.
        Levels: 3 (debug) -> 2 (detailed) -> 1 (normal) -> 0 (minimal)
        Use for cleaner output on simple builds.

Alt+V  -  Increase Verbosity
        Shows more detail per step.
        Levels: 0 (minimal) -> 1 (normal) -> 2 (detailed) -> 3 (debug)
        Debug level shows internal execution details.

Ctrl+T  -  Toggle Time Analysis
         When enabled, shows time spent on each operation:
         - API call duration
         - Tool execution time
         - Queue wait time
         Helps identify slow steps.

Ctrl+O  -  Open Output Directory
         Opens the rp data directory in your file browser:
         - Linux: Uses xdg-open
         - macOS: Uses open
         - Windows: Uses explorer
         Location: ~/.local/share/rp/

================================================================================
BUILD STATE SHORTCUTS
================================================================================

Ctrl+S  -  Save Session Config
         Saves current configuration settings as a template:
         - Verbosity level
         - Cost ticker state
         - Token breakdown state
         - Time analysis state
         Location: ~/.local/share/rp/configs/

Ctrl+N  -  Toggle Notes Mode
         When enabled, typed text is added to the build log.
         Use to:
         - Document decisions
         - Add context for future reference
         - Mark important checkpoints
         Notes appear in exported logs.

Ctrl+C  -  Interrupt (Graceful Stop)
         Single press: Initiates graceful shutdown
         - Completes current operation
         - Saves progress
         - Cleans up resources

         Double press (within 1 second): Force quit
         - Immediate termination
         - May lose unsaved progress

?  -  Show Help
     Displays the shortcuts help panel during builds.
     Press during any build phase.

================================================================================
COST TRACKING SYSTEM
================================================================================

HOW COSTS ARE CALCULATED
------------------------
Costs are tracked in EUR (Euro) using the following formula:

  Input Cost  = Input Tokens  x (0.20 EUR / 1,000,000 tokens)
  Output Cost = Output Tokens x (1.50 EUR / 1,000,000 tokens)
  Total Cost  = Input Cost + Output Cost

Token counts are provided by the API response and represent:
- Input Tokens: Your prompts, context, and system messages
- Output Tokens: AI-generated responses and tool outputs

COST DISPLAY FORMAT
-------------------
All costs shown to 4 decimal places for accuracy:
  Cost this step: EUR0.0023 (1,234 input + 567 output tokens)

COST PANEL COMPONENTS
---------------------
  This Build:  Total cost since build started
  Session:     Total cost since rp started
  Budget:      Configurable spending limit
  Remaining:   Budget minus session cost
  Burn Rate:   Cost per second (averaged over build)

================================================================================
EXAMPLE BUILD WITH COSTS
================================================================================

Below is an example build showing typical cost output:

  STEP [1/5]: Initialize Project
  ----------
  -> Scanning project directory
  -> Loading configuration
  [████████████████░░░░░░░░░░░░░░] 55%
  Cost this step: EUR0.0012 (800 input + 200 output tokens)

  STEP [2/5]: Analyze Dependencies
  ----------
  -> Parsing package.json
  -> Resolving versions
  [██████████████████████████████] 100%
  Cost this step: EUR0.0018 (1,100 input + 350 output tokens)

  ...

  BUILD COMPLETED SUCCESSFULLY

  Summary:
    Total steps:    5
    Duration:       45.2s

  Step-by-step cost breakdown:
    1. Initialize Project: EUR0.0012
    2. Analyze Dependencies: EUR0.0018
    3. Generate Code: EUR0.0089
    4. Run Tests: EUR0.0034
    5. Package Output: EUR0.0015

  Token breakdown:
    Input tokens:   12,450
    Output tokens:   3,280
    Total tokens:   15,730

  Total cost: EUR0.0168
  Average cost per step: EUR0.0034
  Output artifacts: 3

================================================================================
TERMINAL COMPATIBILITY
================================================================================

SUPPORTED TERMINALS
-------------------
The following terminals are fully supported:
- Linux: gnome-terminal, konsole, xterm, alacritty, kitty
- macOS: Terminal.app, iTerm2, Alacritty
- Windows: Windows Terminal, ConEmu, Cmder

TTY DETECTION
-------------
Features automatically disable when output is piped:
- Colors and formatting removed
- Progress bars show plain text
- Cost panels simplified
Non-TTY mode activates when: os.isatty(sys.stdout.fileno()) = False

READLINE REQUIREMENTS
---------------------
Full keybinding support requires GNU readline:
- Linux: Usually pre-installed (libreadline)
- macOS: Install via brew: brew install readline
- Windows: pyreadline3 package (pip install pyreadline3)

If readline is unavailable:
- Basic operation continues
- Keybindings show as disabled
- Manual commands still work

================================================================================
TROUBLESHOOTING
================================================================================

KEYBINDINGS NOT WORKING
-----------------------
1. Check readline is installed:
   python -c "import readline; print('OK')"

2. Check terminal type:
   echo $TERM
   (Should be xterm-256color or similar)

3. Some terminals intercept keys:
   - Ctrl+S may be captured for terminal suspend
   - Alt keys may conflict with menu shortcuts
   Try different terminal emulator.

COST PANEL NOT DISPLAYING
-------------------------
1. Ensure TTY mode:
   - Run directly in terminal, not piped
   - Check: python -c "import os,sys; print(os.isatty(sys.stdout.fileno()))"

2. Toggle with Ctrl+L to re-enable

3. Check verbosity level (Alt+V to increase)

EXPORT FAILING
--------------
1. Check permissions on: ~/.local/share/rp/logs/
2. Ensure disk space available
3. Try manual directory creation:
   mkdir -p ~/.local/share/rp/logs

COLORS NOT SHOWING
------------------
1. Check TERM environment:
   export TERM=xterm-256color

2. Check terminal color support:
   tput colors (should return 256 or higher)

3. Try --no-syntax flag if issues persist

================================================================================
VERSION INFORMATION
================================================================================
Document Version: 1.0
Compatible with: rp 1.59.0+
Last Updated: 2025

For updates and bug reports:
https://github.com/anthropics/rp

================================================================================
