input:
  type: object
  properties:
    topic:
      type: string
      enum: [what-is-git, why-use-git, installation, first-setup, first-repo]
      default: what-is-git
    os:
      type: string
      enum: [macos, windows, linux, unknown]
      default: unknown
    experience_level:
      type: string
      enum: [complete-beginner, some-coding, used-other-vcs]
      default: complete-beginner
  validation:
    custom: true
    rules:
      - if_unknown_os: detect_from_environment

output:
  type: object
  required: [explanation, success]
  properties:
    explanation:
      type: string
      format: markdown
    success:
      type: boolean
    visual_aid:
      type: string
      description: ASCII diagram if applicable
    next_steps:
      type: array
      items:
        type: string
    commands_to_try:
      type: array
      items:
        type: object
        properties:
          command: string
          description: string
          safe: boolean

parameter_validation:
  topic:
    required: false
    sanitize: lowercase_trim
    fallback: what-is-git
  os:
    required: false
    auto_detect: true
    detection_command: uname -s || ver

retry_config:
  max_attempts: 2
  backoff_ms: [1000, 2000]
  retryable_scenarios:
    - command_timeout
    - os_detection_failed

fallback:
  - scenario: installation_failed
    action: provide_manual_instructions
  - scenario: command_not_found
    action: check_path_and_suggest

    Without Git                    With Git
    ──────────                     ─────────

    report_v1.doc                  report.doc
    report_v2.doc                     │
    report_final.doc                  ├─ commit 1: "Initial draft"
    report_final_v2.doc               ├─ commit 2: "Added intro"
    report_REALLY_final.doc           ├─ commit 3: "Fixed typos"
    report_final_final.doc            └─ commit 4: "Final version"

    Chaos!                         Clean history!

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   Working Directory    Staging Area      Repository         │
│   (Your Workspace)     (Ready Room)      (Safe Storage)     │
│                                                             │
│       📁 ──────────► 📦 ──────────────► 🏠               │
│              git add        git commit                      │
│                                                             │
└─────────────────────────────────────────────────────────────┘

commit 3 ← (HEAD - You are here)
    ↓
commit 2 ← You can go back
    ↓
commit 1 ← Or even further back!

# Option 1: Xcode Command Line Tools (recommended)
xcode-select --install

# Option 2: Homebrew
brew install git

# Option 1: Git for Windows (recommended)
# Download from https://git-scm.com/download/windows

# Option 2: winget
winget install --id Git.Git -e --source winget

# Ubuntu/Debian
sudo apt install git

# Fedora
sudo dnf install git

# Arch
sudo pacman -S git

git --version
# Expected: git version 2.42.0 (or similar)

# Tell Git who you are (REQUIRED)
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Optional but recommended
git config --global init.defaultBranch main
git config --global core.editor "code --wait"  # VS Code

# Verify your settings
git config --list

# 1. Create a folder
mkdir my-first-project
cd my-first-project

# 2. Initialize Git (creates .git folder)
git init
# Output: Initialized empty Git repository in .../my-first-project/.git/

# 3. Create a file
echo "# My Project" > README.md

# 4. Check status
git status
# Output: Untracked files: README.md

# 5. Stage the file
git add README.md

# 6. Commit (save!)
git commit -m "Initial commit: Add README"

# 7. View history
git log --oneline

┌────────────────────────────────────────────────────────────┐
│                    GIT CHEAT SHEET                         │
├────────────────────────────────────────────────────────────┤
│ START                                                      │
│   git init              Create new repo                    │
│   git clone <url>       Download existing repo             │
│                                                            │
│ DAILY WORK                                                 │
│   git status            What's going on?                   │
│   git add <file>        Stage file                         │
│   git add .             Stage all                          │
│   git commit -m "msg"   Save with message                  │
│                                                            │
│ HISTORY                                                    │
│   git log               View commits                       │
│   git log --oneline     Compact view                       │
│   git diff              See changes                        │
└────────────────────────────────────────────────────────────┘

□ 1. Is Git installed? → git --version
□ 2. Correct version? → Should be 2.x or higher
□ 3. User configured? → git config user.name
□ 4. Editor set? → git config core.editor

# Successful init
Initialized empty Git repository in /path/.git/

# Successful commit
[main abc1234] Your message
 1 file changed, 1 insertion(+)

#!/bin/bash
# test_git_intro.sh

test_git_installed() {
  git --version > /dev/null 2>&1
  assertEquals 0 $?
}

test_user_configured() {
  name=$(git config user.name)
  assertNotNull "$name"
}

test_init_creates_git_folder() {
  tmpdir=$(mktemp -d)
  cd "$tmpdir"
  git init
  assertTrue "[ -d .git ]"
  rm -rf "$tmpdir"
}

logging:
  level: INFO
  events:
    - skill_invoked
    - installation_checked
    - config_verified
    - first_commit_created

metrics:
  - installation_success_rate
  - time_to_first_commit
  - common_error_types