Build out README with full usage examples and documentation

README.md

@@ -1,3 +1,125 @@
 # Set-StudentEmail
 
-PowerShell script to assign email addresses to AD student users based on firstname+surname format
+PowerShell script to bulk-assign email addresses to Active Directory student users based on their first name and surname.
+
+## How It Works
+
+The script scans all user accounts in a specified Organisational Unit (OU) and sets each user's email address to:
+
+```
+[firstname][surname]@[domain]
+```
+
+For example, a student named **Jane Smith** would be assigned `janesmith@niddrieautisticschool.vic.edu.au`.
+
+- Emails are forced to **lowercase** and any leading/trailing spaces in names are stripped.
+- Users missing a `GivenName` or `Surname` in AD are skipped with a warning.
+
+## Requirements
+
+- Windows PowerShell 5.1+ or PowerShell 7+
+- **Active Directory** PowerShell module (`RSAT: Active Directory Domain Services`)
+- Sufficient AD permissions to modify user attributes in the target OU
+- Run from a domain-joined machine or via `Enter-PSSession` to a DC
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `-OU` | String | `OU=Student,OU=Users,OU=5362-NiddrieAutistic,DC=curric,DC=niddrieautistic,DC=wan` | Distinguished name of the OU to search |
+| `-Domain` | String | `niddrieautisticschool.vic.edu.au` | Email domain to append |
+| `-Force` | Switch | `$false` | Overwrite existing email addresses |
+| `-WhatIf` | Switch | `$false` | Preview changes without applying them |
+
+## Usage Examples
+
+### Preview changes (recommended first step)
+
+Dry-run that shows what *would* happen without touching AD:
+
+```powershell
+.\Set-StudentEmail.ps1 -WhatIf
+```
+
+### Run with defaults
+
+Uses the default OU and domain baked into the script:
+
+```powershell
+.\Set-StudentEmail.ps1
+```
+
+### Custom OU
+
+Target a different OU while keeping the default domain:
+
+```powershell
+.\Set-StudentEmail.ps1 -OU "OU=Year7,OU=Students,DC=school,DC=local"
+```
+
+### Custom domain
+
+Keep the default OU but use a different email domain:
+
+```powershell
+.\Set-StudentEmail.ps1 -Domain "anotherschool.vic.edu.au"
+```
+
+### Custom OU and domain together
+
+```powershell
+.\Set-StudentEmail.ps1 -OU "OU=Year7,DC=school,DC=local" -Domain "otherschool.edu.au"
+```
+
+### Overwrite existing emails
+
+By default the script skips users who already have an email set. Use `-Force` to overwrite:
+
+```powershell
+.\Set-StudentEmail.ps1 -Force
+```
+
+### Combine Force with WhatIf for a safe preview
+
+See what a forced run would change before committing:
+
+```powershell
+.\Set-StudentEmail.ps1 -Force -WhatIf
+```
+
+### Verbose output
+
+PowerShell's built-in `-Verbose` flag works too:
+
+```powershell
+.\Set-StudentEmail.ps1 -Verbose
+```
+
+## Output
+
+The script prints colour-coded status lines as it processes each user:
+
+| Prefix | Colour | Meaning |
+|--------|--------|---------|
+| `SET:` | Green | Email was successfully applied |
+| `OK:` | Grey | User already has the correct email (skipped) |
+| `SKIP:` | Yellow | User skipped (missing name or has a different email without `-Force`) |
+| `FAIL:` | Red | An error occurred updating the user |
+
+A summary is printed at the end:
+
+```
+--- Summary ---
+Updated: 12
+Skipped: 3
+Errors:  0
+```
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| `Get-ADUser : Unable to find a default server` | Run from a domain-joined machine, or specify `-Server` manually in the script |
+| `Access is denied` | Run as an account with write permissions to user objects in the target OU |
+| `Module 'ActiveDirectory' not found` | Install RSAT: `Add-WindowsCapability -Online -Name Rsat.ActiveDirectory.DS-LDS.Tools~~~~0.0.1.0` |
+| Users are skipped unexpectedly | Check that `GivenName` and `Surname` are populated in AD for those accounts |