# Blueprint-v1 Deployment (02.08.2026) — NFS-Pflicht-Setup & Skripte

Diese Referenz dokumentiert den Übergang auf die Blueprint-v1-Task-Queue
(JSON + offen/in_arbeit/fertig/bugfix/archiv) und die dabei verifizierten
Schritte. Ergänzt die SKILL.md mit dem tatsächlich getesteten Deployment.

## Netzwerk-Einzahl

- **Ein** ZeroTier-Netzwerk: `6ab565387a75e498` (172.24.0.0/16).
  Das frühere Netz `b9a18a606fb05ae6` (10.36.223.x) ist **gelöscht**.
- Agenten: A=172.24.196.119 (Master/Hub), B=172.24.34.142,
  SwitchHermes=172.24.20.26, LaptopHermes=172.24.178.202 (oft offline).
  Handy = kein Agent.

## NFS als Pflicht-Dateisystem (verifiziert)

Ein Task, der "Sub-Agenten selbst im Share schauen lässt" statt manuellem
Auffordern, erfordert einen gemeinsam sichtbaren Ordner. **NFS ist Pflicht**;
Samba/CIFS wird abgelehnt (Onboarding blockiert). Zwei Stolpersteine beim
Einrichten:

1. **UFW blockt NFS stumm.** Symptom: `ping` zum Export-Host geht, aber
   `mount -t nfs …` hängt/fails und auch der Porttest
   `timeout 5 bash -c "echo >/dev/tcp/172.24.196.119/2049"` schlägt fehl.
   Fix (nur aufs ZT-Subnetz):
   ```
   ufw allow from 172.24.0.0/16 to any port 2049 proto tcp   # nfs
   ufw allow from 172.24.0.0/16 to any port 111  proto tcp    # rpcbind
   ufw allow from 172.24.0.0/16 to any port 111  proto udp
   ufw allow from 172.24.0.0/16 to any port 20048 proto tcp   # nfs lockd
   ```
   Danach `exportfs -ra && systemctl restart nfs-kernel-server rpcbind`.

2. **requiretty/sudo auf Sub-Agenten (Zorin/PopOS).** `sudo` per SSH über
   stdin schlägt fehl ("ein Terminal ist erforderlich"). Lösung — Askpass:
   ```bash
   echo '#!/bin/bash' > /tmp/ap.sh && echo "echo <PW>" >> /tmp/ap.sh && chmod +x /tmp/ap.sh
   export SUDO_ASKPASS=/tmp/ap.sh
   sudo -A <befehl>
   ```

3. **NFS-Export nur aufs ZT-Subnetz** statt `*`:
   ```
   /srv/work/tasks  172.24.0.0/16(rw,sync,no_subtree_check,no_root_squash)
   ```

## Master-Skripte (auf dem Hub/VPS, /usr/local/bin/)

| Skript | Zweck |
|--------|-------|
| `duo-task-create.sh <ziel> <typ> <prio> <beschreibung>` | legt JSON-Task in `tasks/offen/` ab |
| `duo-master-poller.sh` | Ausfall-Fallback: Task >30s in `offen/` → `ziel_agent="beliebig"` (Original bleibt in `original_ziel_agent`) |
| `duo-master-report.sh` | generiert `dokumentationen.perfekt-ohne-en.de/index.html` live aus den Task-Ordnern |
| `duo-agent-poller.sh <meine-ip> <meine-id>` | Sub-Agent-Poller: 10s-Takt, atomarer `mv`-Lock nach `in_arbeit/` mit Präfix C.D_ |

### Master-Crontab (versetzt)
```
* * * * * /usr/local/bin/duo-master-poller.sh >> /var/log/mesh-poller.log 2>&1
* * * * * sleep 30; /usr/local/bin/duo-master-poller.sh >> /var/log/mesh-poller.log 2>&1
* * * * * sleep 30; /usr/local/bin/duo-master-report.sh >> /var/log/mesh-doku.log 2>&1
```

### Ausfall-Fallback (getestet)
Der Poller wurde mit künstlich auf 45s gealtertem Task verifiziert:
`ziel_agent` → `"beliebig"`, `original_ziel_agent` bleibt `"LaptopHermes"`.
Atomarer `mv`-Rename in `duo-agent-poller.sh` entscheidet bei Konkurrenz:
erster Erfolg gewinnt, zweiter scheitert und bricht still ab.

## Credential-Audit (Wichtig fürs nächste Mal)

- SSH-Zugangsdaten liegen **im Klartext im Skill** `multi-agent-mesh`
  (SSH-User/Passwort in Befehlen), NICHT in `.env` und es gibt keine SSH-Keys
  (`authorized_keys` leer). Rollen-Informationen stehen in `/srv/work/registry.json`.
- Empfehlung (nicht eigenmächtig): Migration zu `age`/`gpg`-Vault + SSH-Public-Key.
  Wenn der Skill geteilt/gesynct wird, sind Klartext-PWs ein Leak-Risiko.

## Task-Dateiformat (Blueprint v1)

Felder: `task_id, ziel_agent, aufgabentyp, prioritaet, budget_limit_eur,
status, ergebnis_pfad, original_ziel_agent` + z.B. `beschreibung, anlage_ts,
in_arbeit_ts, fertig_ts`. Status = Ordnerzugehörigkeit, nicht nur das Feld.

## Doku-Website

- Domain: `dokumentationen.perfekt-ohne-en.de` (Nginx vhost + Let's Encrypt
  via `certbot --nginx -d …`). Stellt die Live-Übersicht aller Tasks aus dem
  Share dar; Agenten-Tabelle mit Status (online/offline).
- Kein PHP nötig — statisches HTML wird durch `duo-master-report.sh` regeneriert.