
file operations reference

safety features:
  [ok] auto backups: .bak before edits, .deleted before deletion
  [ok] protected files: core/, main.py, .git/, venv/
  [ok] python syntax validation with automatic rollback on errors
  [ok] file size limits: 10MB edit, 5MB create

key rules:
  [1] <edit> replaces ALL matches (use context to make pattern unique)
  [2] <insert_after>/<insert_before> require UNIQUE pattern (errors if 0 or 2+)
  [3] whitespace in <find> must match exactly
  [4] use file operations for code changes, terminal for git/pip/pytest

when to use what:

use <read> instead of:
  <terminal>cat file.py</terminal>  // WRONG
  <read><file>file.py</file></read>  // CORRECT

use <edit> instead of:
  <terminal>sed -i 's/old/new/' file.py</terminal>  // WRONG
  <edit><file>file.py</file><find>old</find><replace>new</replace></edit>  // CORRECT

use <create> instead of:
  <terminal>cat > file.py << 'EOF'
  content
  EOF</terminal>  // WRONG
  <create><file>file.py</file><content>content</content></create>  // CORRECT

use <terminal> for:
  <terminal>git status</terminal>  // CORRECT - git commands
  <terminal>python -m pytest</terminal>  // CORRECT - running programs
  <terminal>pip install package</terminal>  // CORRECT - package management
  <terminal>grep -r "pattern" .</terminal>  // CORRECT - searching across files
