feat: add guidance for beginners to get started

README.md

@@ -36,13 +36,94 @@ Each module is a self-contained challenge that teaches specific git concepts:
 5. Run `./verify.ps1` to check if you've solved it correctly
 6. Move to the next module
 
-**Quick Reference**: See [GIT-CHEATSHEET.md](GIT-CHEATSHEET.md) for a comprehensive list of all Git commands covered in this workshop.
+**Quick Reference**: See [GIT-CHEATSHEET.md](GIT-CHEATSHEET.md) for a comprehensive list of all Git commands covered in this workshop. Don't worry about memorizing everything - use this as a reference when you need to look up command syntax!
+
+## Running PowerShell Scripts
+
+Each module includes setup, verification, and reset scripts. Here's how to run them:
+
+### Windows
+
+If you encounter an "execution policy" error when running scripts, open PowerShell as Administrator and run:
+
+```powershell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+Then run scripts using:
+```powershell
+.\setup.ps1
+```
+
+### macOS/Linux
+
+First, make sure scripts are executable (only needed once):
+```bash
+chmod +x module-*/setup.ps1 module-*/verify.ps1 module-*/reset.ps1
+```
+
+Then run scripts using:
+```bash
+./setup.ps1
+```
+
+Or explicitly with PowerShell:
+```bash
+pwsh setup.ps1
+```
+
+**Note:** All examples in this workshop use Windows syntax (`.\script.ps1`). macOS/Linux users should use `./script.ps1` instead.
 
 ## Requirements
 
-- Git installed and configured
-- PowerShell (Windows PowerShell 5.1+ or PowerShell Core 7+)
-- Basic command line knowledge
+### Git
+
+You need Git version 2.23 or later (for `git switch` and `git restore` commands).
+
+**Check if Git is installed:**
+```powershell
+git --version
+```
+
+If you see a version number (e.g., "git version 2.34.1"), you're all set!
+
+If not, download and install from: https://git-scm.com/downloads
+
+**Configure Git (Required - First Time Only):**
+
+Before making your first commit, tell Git who you are:
+
+```powershell
+git config --global user.name "Your Name"
+git config --global user.email "your.email@example.com"
+```
+
+**Verify your configuration:**
+```powershell
+git config --global user.name
+git config --global user.email
+```
+
+You should see your name and email printed. This is required to make commits in Git.
+
+### PowerShell
+
+- **Windows**: PowerShell 5.1+ (already included in Windows 10/11)
+- **macOS/Linux**: Install PowerShell Core 7+ from https://github.com/PowerShell/PowerShell
+
+**Check PowerShell version:**
+```powershell
+$PSVersionTable.PSVersion
+```
+
+### Basic Command Line Knowledge
+
+You should know how to:
+- Navigate directories (`cd`, `ls` or `dir`)
+- See your current location (`pwd`)
+- Read text files (`cat` or `type`)
+
+Don't worry if you're not an expert - we'll guide you through each step!
 
 ## Optional: Install Glow for Pretty Markdown
 
@@ -66,6 +147,22 @@ After installation, read markdown files with:
 
 Without glow, you can still read markdown files with any text editor or `cat README.md`.
 
+## Common Git Terms
+
+New to Git? Here are the key terms you'll encounter:
+
+- **Repository (or "repo")**: A project folder tracked by Git, containing your files and their complete history
+- **Commit**: A snapshot of your project at a specific point in time (like a save point in a video game)
+- **Staging Area (or "Index")**: A preparation area where you select which changes to include in your next commit
+- **Working Directory**: The actual files you see and edit on your computer
+- **Branch**: An independent line of development (like a parallel universe for your code)
+- **HEAD**: A pointer showing which commit you're currently working from
+- **main/master**: The primary branch in a repository (main is the modern convention)
+- **Merge**: Combining changes from different branches
+- **Remote**: A version of your repository hosted elsewhere (like GitHub)
+
+Don't worry if these don't make sense yet - you'll learn them hands-on as you progress!
+
 ## Getting Started
 
 Start with Module 01:

module-01-basics/README.md

@@ -59,14 +59,47 @@ git log                            # View commit history
 
 ### Verification
 
-Once you think you've completed the challenge, run:
+Once you think you've completed the challenge, run the verification script.
+
+**Important:** Run this from the **module directory**, not the challenge directory.
 
 ```powershell
+# If you're in the challenge directory, go back up:
+cd ..
+
+# Then verify:
 .\verify.ps1
 ```
 
 This will check if you've successfully completed all the steps.
 
+### Troubleshooting
+
+**Error: "fatal: unable to auto-detect email address"**
+
+This means Git doesn't know who you are yet. You need to configure your name and email:
+
+```powershell
+git config user.name "Your Name"
+git config user.email "your.email@example.com"
+```
+
+Then try your commit again. For more details, see the "Requirements" section in the main README.md.
+
+**Error: "Not a git repository"**
+
+Make sure you ran `git init` in the challenge directory. This creates a hidden `.git` folder that tracks your project.
+
+**Can't find the challenge directory?**
+
+Make sure you ran `.\setup.ps1` first from the module directory. This creates the `challenge/` folder.
+
+**Where am I?**
+
+Use `pwd` (Print Working Directory) to see your current location:
+- If you're in something like `.../module-01-basics/challenge`, you're in the challenge directory
+- If you're in something like `.../module-01-basics`, you're in the module directory
+
 ### Need to Start Over?
 
 If you want to reset the challenge and start fresh, run: