README.md

@@ -15,3 +15,251 @@
 `ssh code.kpuig.net`
 
 If this command gives you anything but an affirmative that you're configured correctly, that means you have misconfigured something, most likely in SSH but possibly in git.
+
+# Using PowerShell for Git/Gitea over SSH (Windows)
+
+This guide assumes some PowerShell experience. It walks you from setup → generating SSH keys → fixing permissions → testing → cloning/pushing with Git. It also includes simple PowerShell basics you’ll reuse later.
+
+### 1) Open PowerShell (two ways)
+
+---
+
+- **Normal window (most tasks):** Press **Start** → type **PowerShell** → Enter.
+- **Administrator window (needed for ownership/ACL fixes):** Start → type **PowerShell** → **Right‑click → Run as administrator**.
+
+How to tell: the title bar will say **Administrator: Windows PowerShell** if elevated.
+
+### 2) Check/OpenSSH is installed (client)
+
+---
+
+Most modern Windows include it already.
+
+```powershell
+ssh -V  # shows version if installed
+```
+
+If you see an error:
+
+1. **Settings** → **Apps** → **Optional features** → **Add a feature** → Install **OpenSSH Client**.
+2. Reopen PowerShell and try `ssh -V` again.
+
+### 3) PowerShell basics you’ll use
+
+---
+
+- **Current user home**: `C:\Users\<YourName>` (shortcut in PowerShell: `$env:USERPROFILE`)
+- **Change directory**: `cd <path>`
+  Example: `cd $env:USERPROFILE\.ssh`
+- **List files**: `dir` or `ls`
+- **Create folder**: `New-Item -ItemType Directory -Path <path>`
+- **View a file**: `type <file>` (or `notepad <file>` to open Notepad)
+
+### 4) Create the **.ssh** folder (if it doesn’t exist)
+
+---
+
+```powershell
+$ssh = "$env:USERPROFILE\.ssh"
+if (!(Test-Path $ssh)) { New-Item -ItemType Directory -Path $ssh | Out-Null }
+cd $ssh
+```
+
+### 5) Generate an SSH key pair (private + public)
+
+---
+
+Use **ed25519** unless your host requires RSA.
+
+```powershell
+ssh-keygen -t ed25519 -C "your.email@example.com" -f "$env:USERPROFILE\.ssh\some_id"
+```
+
+- When prompted for a passphrase: press **Enter** (no passphrase) or set one for extra security.
+- This creates two files:
+
+  - **`some_id`** (private key — **keep secret**)
+  - **`some_id.pub`** (public key — you’ll upload this)
+
+> If you already have a key, skip generation and just make sure you know the file name.
+
+### 6) Lock down private‑key permissions (Windows ACLs)
+
+---
+
+Open **PowerShell as Administrator** for this section.
+
+```powershell
+$k = "$env:USERPROFILE\.ssh\some_id"
+# Make you the owner
+icacls $k /setowner "$env:USERNAME"
+# Stop inheriting broader folder permissions
+icacls $k /inheritance:r
+# Remove groups that make it too open (ignore errors if not present)
+icacls $k /remove "BUILTIN\Administrators" "Users" "Authenticated Users" "Everyone" 2>$null
+# Grant yourself read access (enough for SSH)
+icacls $k /grant:r "$env:USERNAME:R"
+# (Optional) allow SYSTEM read
+icacls $k /grant:r "NT AUTHORITY\SYSTEM:R"
+# Verify
+icacls $k
+```
+
+Expected output includes only **`<YourName>:(R)`** (and optionally **`NT AUTHORITY\SYSTEM:(R)`**).
+
+> If you see: **“WARNING: UNPROTECTED PRIVATE KEY FILE!”** later, re‑run the ACL steps above.
+
+### 7) Upload your **public** key to Gitea
+
+---
+
+1. Show/copy your public key:
+
+   ```powershell
+   type "$env:USERPROFILE\.ssh\some_id.pub"
+   ```
+
+2. Go to your Gitea **Profile → Settings → SSH / GPG Keys → Add Key**.
+3. Paste the entire single‑line key (starts with `ssh-ed25519` or `ssh-rsa`). Save.
+
+> **Never** upload the private key (`some_id`). Only the `.pub` file.
+
+### 8) Tell SSH which key to use for your host
+
+---
+
+Create/edit `C:\Users\<You>\.ssh\config`:
+
+```text
+Host code.kpuig.net
+  User git
+  IdentityFile C:\Users\<You>\.ssh\some_id
+  IdentitiesOnly yes
+  # Port 22        # If your Gitea shows a different port, set it here
+```
+
+You can create this file via Notepad:
+
+```powershell
+notepad "$env:USERPROFILE\.ssh\config"
+```
+
+### 9) Test the SSH connection
+
+---
+
+```powershell
+ssh -T git@code.kpuig.net   # add -p <port> if needed
+```
+
+**Success looks like:**
+
+```
+Hi there, <username>! You've successfully authenticated ... but Gitea does not provide shell access.
+```
+
+If you see **PTY allocation request failed** — that’s normal; it’s just saying there’s no shell. Authentication still worked.
+
+### 10) Use Git with SSH (clone, fetch, push)
+
+---
+
+```powershell
+# Navigate to where you keep projects
+cd $env:USERPROFILE\Projects
+# Clone via SSH (check the clone URL in Gitea)
+git clone git@code.kpuig.net:owner/repo.git
+cd repo
+# Typical workflow
+git pull
+# make changes
+git add .
+git commit -m "Your message"
+git push
+```
+
+> If Git says “Permission denied (publickey)”: verify your `~/.ssh/config` host, the key path, and that the **matching** public key is in Gitea.
+
+### 11) Common errors & quick fixes
+
+---
+
+**A) `Load key "... .pub": invalid format`**
+You pointed SSH to the **public** key. Use the **private** key (no `.pub`).
+
+**B) `WARNING: UNPROTECTED PRIVATE KEY FILE!`**
+Reapply the ACLs from step 6 (only you should have Read on the private key).
+
+**C) `Permission denied (publickey)`**
+
+- Ensure the public key in Gitea matches your private key:
+
+  ```powershell
+  ssh-keygen -y -f "$env:USERPROFILE\.ssh\some_id" > "$env:USERPROFILE\.ssh\some_id.pub"
+  ```
+
+- Confirm your SSH config host & port; try `ssh -vvv -T git@code.kpuig.net` and read the last lines.
+
+**D) Host key changed / MITM warning**
+If the server was rebuilt, clear the old fingerprint:
+
+```powershell
+ssh-keygen -R code.kpuig.net
+```
+
+Retry to accept the new host key.
+
+### 12) Optional: `ssh-agent` convenience (cache passphrase)
+
+---
+
+If your private key has a passphrase:
+
+```powershell
+Start-Service ssh-agent  # may require admin the first time
+Get-Service ssh-agent
+ssh-add "$env:USERPROFILE\.ssh\some_id"
+```
+
+Now SSH/Git can use the key without asking for the passphrase every time.
+
+### 13) Quick glossary
+
+---
+
+- **PowerShell**: Windows command shell
+- **SSH**: Secure shell protocol for authentication and Git
+- **Private key**: Stays on your PC; keep secret
+- **Public key**: Safe to upload; server uses it to verify you
+- **ACL/Permissions**: Who can read a file
+- **Gitea**: Self‑hosted Git service
+
+### 14) Copy‑paste checklist (TL;DR)
+
+---
+
+```powershell
+# 1) Create folder
+mkdir $env:USERPROFILE\.ssh -ea 0
+
+# 2) Generate key
+ssh-keygen -t ed25519 -C "your.email@example.com" -f "$env:USERPROFILE\.ssh\some_id"
+
+# 3) Lock private key (Run PowerShell as Admin)
+$k = "$env:USERPROFILE\.ssh\some_id"
+icacls $k /setowner "$env:USERNAME"
+icacls $k /inheritance:r
+icacls $k /remove "BUILTIN\Administrators" "Users" "Authenticated Users" "Everyone" 2>$null
+icacls $k /grant:r "$env:USERNAME:R"
+
+# 4) Put pubkey into Gitea
+notepad "$env:USERPROFILE\.ssh\some_id.pub"  # copy to Gitea → Settings → SSH Keys
+
+# 5) SSH config
+notepad "$env:USERPROFILE\.ssh\config"  # paste Host block pointing to some_id
+
+# 6) Test
+ssh -T git@code.kpuig.net
+```
+
+You’re ready to clone and push.