diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..e4a7058
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,57 @@
+# Project Sync Toolkit
+
+A bash toolkit for synchronizing projects between remote servers and local development machines.
+
+## Overview
+
+The main script `sync-project.sh` downloads a project from a remote server via tar archive and generates helper scripts for ongoing synchronization. It's designed to be symlinked from a projects directory so multiple projects can share the same toolkit.
+
+## Architecture
+
+```
+sync-project.sh          # Main orchestrator - generates all helper scripts
+MANUAL                   # CLI help text (displayed by -h flag)
+lazygit                  # Binary uploaded to server for git operations
+scripts/                 # Helper script templates
+    local-remote.sh      # Push files to server (rsync)
+    remote-local.sh      # Pull files from server (rsync)
+    ssh.sh               # SSH access with --db, --git, --todo flags
+    sftp-watch.sh        # Continuous sync using watchexec
+    watch-build.sh       # Build and deploy automation
+    split-conflicts.sh   # Git conflict resolution helper
+    find_image_size.php  # Image aspect ratio analyzer
+```
+
+## How It Works
+
+1. User runs `./sync-project.sh` from their projects directory (via symlink)
+2. Script prompts for: server, password, path (default ~/public_leo), local folder
+3. Creates tar archive on server, downloads and extracts locally
+4. Generates helper scripts with embedded credentials (from templates in `scripts/`)
+5. On full sync: syncs terminal info, uploads lazygit, updates .gitignore
+
+## Modes
+
+- **Default**: Full setup with all scripts, lazygit, terminfo sync
+- **--sftp-only**: Helper scripts only, no lazygit or .gitignore updates
+- **--files-only**: Quick sync, excludes node_modules/vendor, no scripts generated
+
+## Key Conventions
+
+- All SSH/SCP commands use `$SSH_OPTS` for consistent options (currently: auto-accept new hosts)
+- Paths starting with `~` are resolved to full paths via SSH before use
+- Helper scripts get credentials injected as variables at the top, then template content appended
+- Conflict prevention uses `.remote-in-progress` flag file
+- Terminal detection checks `$TERM` for "ghostty" or "kitty" substrings
+
+## Generated Script Structure
+
+Each helper script is built by:
+1. Writing a header with `#!/bin/bash`, `set -e`, and credential variables
+2. Appending the corresponding template from `scripts/` directory
+
+## Testing
+
+- `-h` flag should display MANUAL and exit
+- Path resolution requires valid SSH credentials
+- Terminfo sync only runs on full sync (no flags) and requires infocmp
diff --git a/README.md b/README.md
index 9c3151d..b518770 100644
--- a/README.md
+++ b/README.md
@@ -30,10 +30,12 @@ From your projects directory, run:
 ./sync-project.sh
 ```
 
-Or for SFTP-only setup (skips lazygit and .gitignore modifications):
+**Available flags:**
 
 ```bash
-./sync-project.sh --sftp-only
+./sync-project.sh -h            # Show help manual
+./sync-project.sh --files-only  # Quick sync (files only, no scripts)
+./sync-project.sh --sftp-only   # SFTP setup (no lazygit, no .gitignore updates)
 ```
 
 ## What the Script Does
@@ -42,16 +44,21 @@ When you run `sync-project.sh`, it will:
 
 1. **Ask for configuration:**
    - Server user@host (e.g., `user@example.com`)
-   - Server project path (e.g., `/home/user/public_html`)
-   - Local folder path (e.g., `my-project`)
    - SSH password
+   - Server project path (defaults to `~/public_leo`, supports `~` paths)
+   - Local folder path (e.g., `my-project`)
 
-2. **Sync your project:**
+2. **Prepare the connection:**
+   - Auto-accepts new server host keys (first-time connections work seamlessly)
+   - Resolves `~` paths to full paths via SSH
+   - Syncs terminal info for ghostty/kitty terminals (full sync only)
+
+3. **Sync your project:**
    - Creates a tar archive on the remote server
    - Downloads and extracts it to your local folder
    - Cleans up temporary files
 
-3. **Generate configuration and scripts:**
+4. **Generate configuration and scripts:**
    - Creates `.vscode/sftp.json` for VS Code SFTP extension
    - Generates helper scripts with your credentials pre-configured
    - Adds scripts to `.gitignore` (unless using `--sftp-only`)
@@ -94,18 +101,21 @@ After running the sync script, you'll have these helper scripts in your project:
 **What it does:**
 - Opens an SSH connection to your server
 - Changes directory to your project path
-- Supports `--db` flag for MySQL port forwarding
+- Multiple operation modes via flags
 
 **Usage:**
 ```bash
 ./ssh.sh           # Normal SSH connection
 ./ssh.sh --db      # SSH with MySQL port forwarding (local:3306 -> remote:3306)
+./ssh.sh --git     # Launch lazygit on server, sync changes back when done
+./ssh.sh --todo    # Search for TODO markers in project files
 ```
 
 **Use cases:**
 - Run commands on the server
 - Check logs
 - Access remote database via localhost:3306
+- Git operations via lazygit
 
 ### `sftp-watch.sh`
 **Purpose:** Continuous bidirectional sync
@@ -139,6 +149,32 @@ After running the sync script, you'll have these helper scripts in your project:
 - Automatic deployment of compiled assets
 - Continuous integration during development
 
+## Sync Modes
+
+### Default Mode
+Full setup with all features:
+- Syncs terminal info (xterm-ghostty or xterm-kitty)
+- Downloads all project files
+- Creates `.vscode/sftp.json`
+- Generates all helper scripts
+- Uploads lazygit to server
+- Updates `.gitignore`
+
+### `--files-only` Mode
+Quick sync for when you just need the files:
+- Downloads project files (excludes `node_modules`, `vendor`)
+- No helper scripts generated
+- No configuration files created
+- No lazygit upload
+
+### `--sftp-only` Mode
+Lightweight setup for SFTP workflows:
+- Downloads all project files
+- Creates `.vscode/sftp.json`
+- Generates: `local-remote.sh`, `remote-local.sh`, `sftp-watch.sh`, `ssh.sh`
+- No lazygit upload
+- No `.gitignore` modifications
+
 ## Requirements
 
 - **bash** - Shell scripting