docs: CLI in README, Architektur und Konventionen

Refs #013

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

README.md

@@ -20,7 +20,7 @@ In Entwicklung. Version und Fortschritt stehen im [CHANGELOG](CHANGELOG.md), der
 | 1 · v0.1.0 | Server-Verwaltung, Fingerprint-Pinning, Verbindungstest mit Fähigkeitserkennung | ✓ fertig, auf PVE 9.2 geprüft |
 | 2 · v0.2.0 | Katalog, Template-Bau, Debian-13-VM, Live-Fortschritt, Assistent | ✓ fertig, auf PVE 9.2 geprüft |
 | 3 · v0.3.0 | LXC, Ubuntu, Profile, Vorlagen, Profile im Template, SSH-Schlüssel | ✓ fertig, auf PVE 9.2 geprüft (Bau-Adresse #021: Abnahme offen) |
-| 4 · v0.4.0 | CLI `proxdeploy` (Go) | ◐ als Nächstes |
+| 4 · v0.4.0 | CLI `proxdeploy` (Go), API-Tokens | ◐ in Arbeit |
 | 5 · v0.5.0 | Verlauf, Audit-Log, Rollen, OIDC | ○ geplant |
 | 6 · v0.6.0 | Branding, README mit Screenshots, Installer | ○ geplant |
 
@@ -37,6 +37,72 @@ Maßgeblich ist die Proxmox-API (geprüft gegen PVE 8.x und 9.2):
 Das API-Token braucht eine eigene Rolle; die Befehle stehen in
 [docs/proxmox-rechte.md](docs/proxmox-rechte.md).
 
+## CLI
+
+`proxdeploy` ist ein einzelnes Binary (Linux, macOS, Windows; amd64 und arm64) und spricht nur die
+REST-API – dieselbe wie die Web-GUI, mit denselben Phasentexten.
+
+```bash
+proxdeploy login https://proxdeploy.example        # fragt Benutzer und Passwort, speichert ein Token
+proxdeploy servers
+proxdeploy distros --type lxc
+proxdeploy profiles
+proxdeploy vm web01 --server rz1 --distro debian-13 --profile base,docker --ip 10.0.20.15/24 --gw 10.0.20.1 --vlan 20
+proxdeploy lxc dns01 --server rz1 --distro ubuntu-24.04 --dry-run
+proxdeploy template build --server rz1 --distro debian-13 --profile base,docker
+proxdeploy batch gaeste.yaml
+proxdeploy status a-7f3k
+proxdeploy logs a-7f3k --follow
+```
+
+```
+⬡ ProxDeploy v0.4 · Server rz1 · Node pve01 · Debian 13 (Template 9013)
+
+✓ Prüfungen        VMID 120 frei · local-zfs · vmbr0 VLAN 20
+✓ Klonen           full clone 9013 → 120 · Disk auf 40G
+✓ cloud-init       user florian · SSH-Key · Profile base, docker
+✓ Start            VM 120 läuft
+✓ Guest-Agent      antwortet nach 18s
+◐ Provisionierung  cloud-init läuft … 1m 12s
+```
+
+- Was nicht angegeben ist, füllt der Server: Storage, Bridge und Node aus den Server-Einstellungen
+  bzw. dem Verbindungstest, Benutzer = eigener Benutzername, SSH-Schlüssel = die in den Einstellungen
+  hinterlegten. `--preset` belegt aus einer Vorlage vor; Flags gehen vor.
+- Konfiguration in `~/.config/proxdeploy/config.toml` (Rechte 0600): `url`, `token`, optional
+  `server` als Standard für `--server` und `[instances.<name>]` für weitere Instanzen
+  (`--instance`). `PROXDEPLOY_URL`, `PROXDEPLOY_TOKEN`, `PROXDEPLOY_INSTANCE` gehen vor.
+- Tokens für Skripte und CI: Web-GUI → Einstellungen → API-Tokens, dann `proxdeploy login <url> --token pd_…`.
+- Ausgabe: Farben (24-bit, sonst 256) nur im Terminal und ohne `NO_COLOR`/`--no-color`; `--ascii`
+  ersetzt Symbole durch `[OK]`, `[..]`, `[!!]`; `--quiet` zeigt nur die Abschlussbox; `--json` ist
+  maschinenlesbar. Ohne Terminal (Pipe, CI) erscheint jede Phase als eine Zeile, sobald sie fertig ist.
+- Exit-Codes: `0` Erfolg, `1` Auftrag fehlgeschlagen, `2` Bedienfehler, `3` Verbindung/Anmeldung.
+- `Strg+C` hängt nur ab – der Auftrag läuft weiter (`proxdeploy status <id>`); abbrechen mit
+  `proxdeploy cancel <id>`.
+
+`batch` rollt mehrere Gäste aus; die Schlüssel heißen wie die Flags. Die Datei wird vollständig
+geprüft, bevor der erste Auftrag startet:
+
+```yaml
+defaults:
+  server: rz1
+  distro: debian-13
+  profile: [base]
+guests:
+  - name: web01
+    type: vm
+    profile: [base, docker]
+    ip: 10.0.20.15/24
+    gw: 10.0.20.1
+    memory: 4096
+  - name: mon01
+    type: lxc
+    profile: [base, zabbix-agent]
+    vars: { zabbix-agent: { server: zbx.example } }
+```
+
+Bauen: `cli/bauen.sh 0.4.0` legt die sechs Binaries und `SHA256SUMS` unter `cli/bin/` ab (Go 1.27).
+
 ## Entwicklung
 
 Voraussetzungen: Node 24 (z. B. über nvm), pnpm 12 (corepack), Docker für PostgreSQL.
@@ -54,8 +120,12 @@ Prüfen vor jedem Commit:
 ```bash
 pnpm lint && pnpm typecheck && pnpm format:pruefen && pnpm test
 pnpm test:e2e                 # Browser-Abläufe gegen den gebauten Stand (Desktop und 390 px)
+pnpm cli:pruefen              # openapi.json und Go-Typen aktuell, go vet, go test (Golden-Files)
 ```
 
+Ändert sich ein Schema der API, erst `pnpm openapi`, dann in `cli/` `go generate ./...` – der
+Go-Client nutzt die aus `cli/api/openapi.json` erzeugten Typen.
+
 Konventionen (deutsche Bezeichner, Schichtung, Versionen) stehen in [CLAUDE.md](CLAUDE.md).
 
 ## Betrieb