docs/TERMINAL_CORRUPTION_FIX.md

Terminal Corruption Prevention Guide

What Happened

Terminal pagers (like less, more) use an "alternate screen buffer" that can get corrupted, causing command output to be written as files in your current directory. This is compounded when you're in the wrong directory (like frontend/).

Symptoms

Random files appearing with names like:

• = f.readlines()
• 245 fluoride bills across all 50 states (was only 5 states)
• lativesession s ON b.legislative_session_id = s.id

These are fragments of command output or SQL queries.

Immediate Fix

1. Clean up garbage files:

bash scripts/cleanup_frontend_junk.sh

2. Reset your terminal:

reset
cd /home/developer/projects/open-navigator

Prevention (CRITICAL)

Add to your ~/.bashrc or ~/.zshrc:

# Prevent pager corruption
export PAGER=cat
export GIT_PAGER=cat
export PSQL_PAGER=
export SYSTEMD_PAGER=cat

# Git config
git config --global core.pager cat

Then reload your shell:

source ~/.bashrc  # or source ~/.zshrc

Best Practices

1. Always check your working directory:

   pwd  # Before running commands
   

2. Run commands from project root:

   cd /home/developer/projects/open-navigator
   # NOT from frontend/, api/, etc.
   

3. Use --no-pager flags:

   git log --no-pager
   psql --no-pager
   

4. If terminal gets corrupted:

   reset && stty sane
   

Updated Files

• ✅ frontend/.gitignore - Ignores garbage files
• ✅ scripts/cleanup_frontend_junk.sh - Cleanup script
• ✅ scripts/prevent_terminal_corruption.sh - Prevention config

Why This Happens

1. Alternate screen buffer - Commands like less, more, git log, psql output
2. Terminal state corruption - Buffer doesn't close properly
3. Wrong working directory - Your psql terminal had cwd: frontend/
4. Output redirection - Corrupted state writes output as files

Never Again

Run this once:

source scripts/prevent_terminal_corruption.sh

Add to your shell profile permanently:

echo 'export PAGER=cat' >> ~/.bashrc