docs: refine workshop flow and Argo repo credential guidance

README.md

@@ -58,6 +58,7 @@ http://localhost:8080
 ```
 
 Volg daarna de oefeningen in volgorde. Zie [docs/vm-setup.md](docs/vm-setup.md) als er iets misgaat bij de VM.
+Deze quickstart voert bootstrap al uit. In Oefening 01 kun je dan direct door naar verificatie en commit/push van `apps/root.yaml`.
 
 Belangrijk:
 - Je hoeft het VM-IP niet te weten om in te loggen of te tunnelen; gebruik `vagrant ssh`.
@@ -110,6 +111,30 @@ naar jouw eigen branch om precies te zien wat er mist.
 
 ---
 
+## Troubleshooting
+
+| Probleem                                                       | Oplossing                                                                                                                                                                                          |
+|----------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `A VirtualBox machine with the name 'ops-demo' already exists` | Je hebt waarschijnlijk twee repo-kopieen met dezelfde VM-naam. Check `vagrant global-status --prune`. Stop of destroy de andere omgeving, of geef een unieke VM-naam in een van de `Vagrantfile`s. |
+| `vagrant up` faalt terwijl `vagrant status` zegt `poweroff`    | Je zit mogelijk in een andere repo-map dan de VM die nu draait. Controleer de `directory` kolom in `vagrant global-status --prune`.                                                                |
+| Ik weet het ArgoCD admin-wachtwoord niet (meer)                | Lees het opnieuw uit: `vagrant ssh -c "export KUBECONFIG=/home/vagrant/.kube/config; kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath='{.data.password}' \| base64 -d"`        |
+| Ik kan niet inloggen met `vagrant ssh`                         | Controleer eerst of je in de juiste repo-map staat (`pwd`) en run `vagrant status`. Als de VM niet draait: `vagrant up`. Helpt dat niet: `vagrant global-status --prune` en check de `directory`.  |
+| ArgoCD UI niet bereikbaar op `http://localhost:8080`           | Start de tunnel opnieuw: `./scripts/host/argocd-ui-tunnel.sh` (of `.ps1` op Windows).                                                                                                               |
+| `kubectl` lijkt naar de verkeerde cluster te wijzen            | Gebruik de host-scripts (`./scripts/host/bootstrap-from-host.sh` en `./scripts/host/argocd-ui-tunnel.sh`) of log in met `vagrant ssh` en werk vanuit `/vagrant`. De bootstrap heeft cluster-checks en stopt bij mismatch. |
+| `root` app blijft `Unknown` of `OutOfSync`                     | Controleer of `apps/root.yaml` naar jouw fork verwijst en of je die commit/push hebt gedaan. Daarna in ArgoCD op **Refresh** klikken.                                                              |
+| Tekton pipeline kan niet pushen naar GitHub                    | Controleer credentials opnieuw met `./scripts/vm/set-git-credentials.sh <github-user> <github-pat>` en gebruik een PAT met juiste repo-rechten.                                                     |
+| MetalLB/Ingress hostnames werken niet                          | Wacht tot networking apps `Healthy` zijn in ArgoCD en controleer of het host-only netwerk `192.168.56.x` actief is.                                                                                |
+
+Handige debug-commando's:
+```bash
+vagrant global-status --prune
+vagrant status
+kubectl get applications -n argocd
+kubectl get pods -A
+```
+
+---
+
 ## Netwerk
 
 ```

docs/01-argocd-bootstrap.md

@@ -29,7 +29,12 @@ kubectl get nodes
 
 ## Stappen
 
-### 1. Bootstrap-script uitvoeren
+### 1. Startpunt kiezen
+
+Als je de quickstart uit `README.md` al hebt gedaan (`./scripts/host/bootstrap-from-host.sh`), dan is bootstrap al uitgevoerd.
+Ga in dat geval direct naar stap 3.
+
+Wil je vanaf een blanke VM starten, voer dan bootstrap handmatig uit in de VM:
 
 ```bash
 ./scripts/vm/bootstrap.sh
@@ -48,18 +53,78 @@ Aan het einde zie je het admin-wachtwoord. **Kopieer het nu.**
 
 ### 2. ArgoCD UI openen
 
-In een tweede terminal op je laptop:
+Op je laptop:
 
 ```bash
-kubectl port-forward svc/argocd-server -n argocd 8080:443
+./scripts/host/argocd-ui-tunnel.sh
 ```
 
-Open **https://localhost:8080** (accepteer het self-signed certificaat).
+Open **http://localhost:8080**.
 Login: `admin` / het wachtwoord uit de output van het script.
 
 ---
 
-### 3. root.yaml committen en pushen
+### 3. Repository in ArgoCD registreren
+
+Het bootstrap-script installeert ArgoCD, maar registreert jouw Git-repo niet in ArgoCD.
+Daarom moet je in deze stap expliciet je repo toevoegen, anders blijft `root` op `Unknown`/`authentication required`.
+
+Kies een van deze twee paden:
+
+**Pad A — via ArgoCD UI**
+- Ga naar **Settings → Repositories → Connect Repo**
+- Vul je repo-URL in
+- Auth type: username + password (bij HTTPS)
+- Username: je GitHub username
+- Password: je GitHub PAT
+- Project: `workshop`
+
+**Pad B — via Kubernetes Secret (zonder UI)**
+- Maak een Secret in namespace `argocd`
+- Label op die Secret: `argocd.argoproj.io/secret-type=repository`
+- Secret-data met minimaal:
+  - `type: git`
+  - `url: <jouw-repo-url>`
+  - `username: <jouw-github-user>`
+  - `password: <jouw-github-pat>`
+  - `project: workshop`
+
+`<jouw-repo-url>` kan technisch HTTPS of SSH zijn, maar:
+- Gebruik je een **GitHub PAT** (fine-grained of classic), dan gebruik je een **HTTPS repo-URL**:
+  - `https://github.com/<user>/<repo>.git`
+- Gebruik je een **SSH repo-URL**:
+  - `git@github.com:<user>/<repo>.git`
+  - dan authenticate je met een SSH key (niet met PAT).
+
+#### Token/credentials kiezen
+Gebruik credentials die read-toegang geven tot je Git-repo.
+
+Als je **GitHub** gebruikt:
+1. Ga naar **Settings → Developer settings → [Personal access tokens](https://github.com/settings/tokens)**
+2. Maak bij voorkeur een **fine-grained token**
+3. Geef de token toegang tot jouw workshop-repo
+4. Zet minimaal repository permission:
+   - `Contents: Read`
+
+Dit is voldoende voor ArgoCD sync (read-only).  
+Gebruik je later Tekton om te pushen, dan heb je `Contents: Read and write` nodig.
+
+Bij HTTPS + PAT geldt:
+- `username` = je accountnaam op je Git-provider (bij GitHub: je GitHub username, niet je e-mailadres)
+- `password` = de PAT zelf
+
+Een classic token kan ook, met scope `repo`, maar fine-grained heeft de voorkeur.
+
+#### Wat is “Project” in ArgoCD?
+Een ArgoCD Project (AppProject) bepaalt welke repos en destinations een set Applications mag gebruiken.
+In deze workshop is dat project `workshop` (zie `apps/project.yaml`).
+
+Gebruik hier dus `workshop` als projectwaarde.
+`default` werkt soms technisch ook, maar dan omzeil je de workshop-grenzen die we juist willen laten zien.
+
+---
+
+### 4. root.yaml committen en pushen
 
 Het bootstrap-script heeft `apps/root.yaml` aangemaakt met jouw fork-URL. Dit bestand moet in je repo staan zodat ArgoCD het kan synchroniseren:
 
@@ -71,7 +136,7 @@ git push
 
 ---
 
-### 4. De root Application bekijken
+### 5. De root Application bekijken
 
 In de ArgoCD UI zie je nu de **root** application verschijnen. Klik erop.
 
@@ -86,7 +151,7 @@ kubectl get applications -n argocd
 
 ---
 
-### 5. ArgoCD zichzelf laten beheren (optioneel maar mooi)
+### 6. ArgoCD zichzelf laten beheren (optioneel maar mooi)
 
 Maak `apps/argocd.yaml` aan:
 
@@ -139,8 +204,9 @@ argocd   Synced        Healthy
 ## Probleemoplossing
 
 | Symptoom                                         | Oplossing                                                                                                         |
-|----------|-----------|
+|--------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|
 | root Application toont "Unknown"                 | Nog niet gepusht, of ArgoCD kan de repo nog niet bereiken — even wachten                                          |
+| root toont `Unknown` + `authentication required` | Repository-toegang ontbreekt of credentials zijn fout. Controleer stap 3 (UI of Secret) en refresh daarna de app. |
 | Helm install time-out                            | `kubectl get pods -n argocd` — waarschijnlijk nog images aan het downloaden                                       |
 | UI toont "Unknown" sync status                   | Klik **Refresh** op de application                                                                                |
 

docs/vm-setup.md

@@ -8,11 +8,11 @@ Alles draait in een VirtualBox-VM die Vagrant voor je opzet. Volg deze stappen v
 
 Doe dit de dag ervoor — niet op de ochtend van de workshop zelf.
 
-| Tool           | Versie      | Download |
+| Tool       | Versie      | Download                                          | Of op Mac                 |
-|----------------|-------------|----------|
+|------------|-------------|---------------------------------------------------|---------------------------|
-| VirtualBox     | 7.x         | https://www.virtualbox.org/wiki/Downloads |
+| VirtualBox | 7.x         | https://www.virtualbox.org/wiki/Downloads         | `brew install virtualbox` |
-| Vagrant        | 2.4.x       | https://developer.hashicorp.com/vagrant/downloads |
+| Vagrant    | 2.4.x       | https://developer.hashicorp.com/vagrant/downloads | `brew install vagrant`    |
-| Git            | willekeurig | https://git-scm.com/downloads |
+| Git        | willekeurig | https://git-scm.com/downloads                     |                           |
 
 Minimaal 12 GB vrij RAM, ~15 GB schijfruimte.
 
@@ -121,7 +121,7 @@ vagrant destroy    # VM volledig verwijderen
 ## Probleemoplossing
 
 | Symptoom                       | Oplossing                                             |
-|----------|-----------|
+|--------------------------------|-------------------------------------------------------|
 | "No usable default provider"   | VirtualBox niet geïnstalleerd of laptop niet herstart |
 | VT-x/AMD-V niet beschikbaar    | Schakel virtualisatie in via BIOS/UEFI                |
 | `kubectl get nodes` → NotReady | k3s start nog op, wacht 30–60 seconden                |