# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a Windows remote administration toolkit designed for configuring and managing a specific Windows machine (PC-74269 at 192.168.88.112) from macOS/Linux systems. The toolkit provides automated scripts for system debloating, application installation, security configuration, and diagnostics.

## Architecture Pattern

**Dual-Script Architecture**: Each functionality consists of two files:
- `.ps1` - PowerShell script that runs on the target Windows machine
- `.sh` - macOS/Linux shell wrapper that uploads and executes the PowerShell script via SSH

**Execution Flow**:
1. Shell script uses `sshpass` + `scp` to upload PowerShell script to target
2. Executes PowerShell script remotely via SSH with `powershell -NoProfile -ExecutionPolicy Bypass`
3. Output is simultaneously displayed and logged to `logs/` with timestamps

## Key Commands

### Prerequisites
```bash
# Install sshpass (required for all operations)
brew install hudochenkov/sshpass/sshpass
```

### System Reconnaissance
```bash
./recon.sh                    # Complete system inventory (15 sections)
./verify-ai-removed.sh        # Verify Windows AI components removed
./verify-debloat.sh          # Verify Win11Debloat changes applied
```

### Core System Configuration
```bash
./firewall-allow-ssh.sh       # Enable permanent SSH access
./activate-windows.sh         # Activate Windows via KMS
./remove-windows-ai.sh        # Remove Windows AI/Copilot components
./win11debloat.sh            # Remove bloatware and disable telemetry
```

### Application Management
```bash
./install-thunderbird.sh     # Install Thunderbird email client
./setup-thunderbird.sh       # Configure IMAP/SMTP (edit thunderbird-config.json first)
./install-telegram.sh        # Install Telegram for target user
```

### Diagnostics and Tools
```bash
./install-nirsoft.sh         # Install 16 NirSoft diagnostic tools
./nirsoft-dump.sh           # Collect and package system diagnostic data
```

### Environment Variables
All scripts support connection overrides:
```bash
HOST=192.168.x.x USER_NAME=foo PASS='xxx' ./script.sh
MODE=Apply|Revert ./remove-windows-ai.sh    # AI removal modes
TARGET_USER=someone ./apply-ui-to-user.sh   # UI settings target
```

## Configuration Files

### `win11debloat-config.json`
Configuration for Win11Debloat operations. Uses schema with `Tweaks`, `Deployment`, and `Apps` sections. All tweak names must exist in Win11Debloat's `Config/Features.json` or they'll be rejected as "no importable data".

### `thunderbird-config.json`
Email account configuration for Thunderbird setup. Supports IMAP/SMTP with various providers (Gmail, Outlook, iCloud, custom servers).

### `nirsoft-config.json`
Defines the 16 NirSoft diagnostic tools to install, their download URLs, and installation paths.

## Important Gotchas

1. **PowerShell Encoding**: Chinese Windows systems read UTF-8 scripts as CP950 without BOM. Scripts automatically add UTF-8 BOM to downloaded PowerShell files.

2. **Firewall Persistence**: Windows firewall profiles reset on reboot. The firewall script creates permanent rules and enables all profiles.

3. **Thunderbird Profiles**: Thunderbird 72+ uses `[Install<HASH>]` sections in profiles.ini, not `Default=1`. Setup script handles this correctly.

4. **Win11Debloat Scope**: Silent mode only applies UI settings to the executing user. Use `apply-ui-to-user.sh` to sync settings to other users.

5. **Registry Paths**: Many "common knowledge" registry paths for Windows settings are incorrect. Always verify actual paths used by tools.

## Logging and Output

- All operations create timestamped logs in `logs/` directory
- Format: `{operation}-{host}-{timestamp}.log`
- Diagnostic dumps saved to `dumps/` directory as ZIP files
- Scripts provide real-time output while simultaneously logging

## Remote Target Requirements

- Windows machine with OpenSSH Server enabled on port 22
- Default credentials: `Admin@192.168.88.112` / `P@ssw0rd!`
- Target must be accessible from execution environment
- PowerShell 5.1 required (not PowerShell 7/Core)

## Connection Methods

This toolkit supports two connection methods with different strengths:

### SSH Method (Stable, for Large Scripts)
- ✅ Proven stability and reliability
- ✅ Handles large scripts (>3KB) without issues
- ✅ File upload capabilities via `scp`
- ✅ All existing `.sh` scripts use this method
- ⏱️ Execution time: ~22 seconds for recon
- Requires OpenSSH Server on target Windows machine

### WinRM Method (Fast, for Quick Tasks)  
- ⚡ **1.9x faster execution** (12s vs 22s for recon)
- ✅ Native Windows remote management
- ✅ Better PowerShell integration and error handling
- ✅ Structured logging and real-time output
- ⚠️ Limited by command line length for large scripts
- Requires WinRM service configuration on target

```bash
# SSH method (reliable for large scripts)
./recon.sh

# WinRM method (faster for small tasks)  
python3 test_simple_winrm.py
python3 benchmark_ssh_vs_winrm.py

# Smart method selection
python3 smart_executor.py script.ps1
```

## WinRM Setup and Usage

### Prerequisites for WinRM
```bash
# Install Python WinRM library
pip3 install pywinrm

# Generate WinRM wrapper scripts
python3 generate_winrm_wrappers.py
```

### WinRM Configuration Scripts
- `check-winrm.sh` - Verify WinRM configuration status
- `enable-winrm.sh` - Configure WinRM service for remote access
- `fix-winrm.sh` - Fix common WinRM connectivity issues
- `test_winrm_python.py` - Test WinRM connectivity with Python
- `winrm_executor.py` - Core WinRM execution framework

### WinRM Target Requirements
- WinRM service running on port 5985 (HTTP) or 5986 (HTTPS)
- `Enable-PSRemoting -Force` executed on target
- Firewall rules enabled for Windows Remote Management
- For HTTP: `AllowUnencrypted=true` in WinRM configuration

## Recommended Execution Order

For new machines, follow this sequence:
1. `firewall-allow-ssh.sh` - Ensure permanent SSH access
2. `enable-winrm.sh` - Configure WinRM (if using WinRM method)
3. `recon.sh` or `recon-winrm.py` - System inventory
4. `activate-windows.sh` - Windows activation
5. AI removal + reboot + verification
6. Win11Debloat + reboot + verification
7. Application installations
8. Account management (rename/hide should be done last)