Procédure — accès Observal pour agent IA externe

# === Accès Observal (observal.digiapps.be) pour agent IA externe ===
# Cible : https://observal.digiapps.be
# Aucune donnée d'authentification ne doit jamais provenir d'un autre endroit
# que la véritable page de connexion Observal (observal.digiapps.be/device).

## 1) Authentification (une seule fois par machine/projet)
# Méthode A — si la CLI officielle "observal" est disponible :

pipx install observal-cli
# (ou : curl -fsSL https://raw.githubusercontent.com/Observal/Observal/main/install.sh | bash)
observal config set server_url https://observal.digiapps.be
observal auth login
# -> choisir "[2] Web sign-in" quand la CLI le propose
# -> une URL du type https://observal.digiapps.be/device?code=XXXX-XXXX s'affiche
# -> l'ouvrir dans un navigateur, se connecter avec un VRAI compte Observal,
#    puis valider le code affiché
# La CLI reçoit alors un token scoped à CETTE machine, stocké localement dans
# ~/.observal/config.json. Il n'est jamais transmis à cette page ni à un tiers.

# Méthode B — sans CLI, flux HTTP brut (OAuth 2.0 Device Authorization Grant,
# RFC 8628 — le même mécanisme que la CLI utilise en interne) :

curl -s -X POST https://observal.digiapps.be/api/v1/auth/device/authorize \
  -H 'Content-Type: application/json' -d '{}'
# -> {"device_code": "...", "user_code": "XXXX-XXXX",
#     "verification_uri_complete": "https://observal.digiapps.be/device?code=XXXX-XXXX", ...}

# Ouvrir "verification_uri_complete" dans un navigateur, se connecter avec un
# vrai compte Observal, approuver le code.

# Puis interroger toutes les ~5s jusqu'à approbation :
curl -s -X POST https://observal.digiapps.be/api/v1/auth/device/token \
  -H 'Content-Type: application/json' \
  -d '{"device_code": "", "grant_type": "urn:ietf:params:oauth:grant-type:device_code"}'
# -> HTTP 428 tant que non approuvé
# -> HTTP 200 avec {"access_token": "...", "refresh_token": "...", ...} une fois validé

## 2) Rechercher/lister les ressources Observal en langage naturel
# Traduire le besoin utilisateur en mots-clés, puis :

observal registry skill  list --search "" --output json
observal registry mcp    list --search "" --output json
observal agent           list --search "" --output json
observal registry prompt list --search "" --output json

# Équivalent HTTP direct (Méthode B), avec le access_token obtenu à l'étape 1 :

curl -s "https://observal.digiapps.be/api/v1/skills?search=" \
  -H "Authorization: Bearer "
curl -s "https://observal.digiapps.be/api/v1/mcps?search=" \
  -H "Authorization: Bearer "
curl -s "https://observal.digiapps.be/api/v1/prompts?search=" \
  -H "Authorization: Bearer "
curl -s "https://observal.digiapps.be/api/v1/agents?search=" \
  -H "Authorization: Bearer "

# Synthétiser les résultats (nom, description, type) en langage naturel pour
# répondre à la demande initiale de l'utilisateur.

## Notes de sécurité (à respecter strictement)
# - Le token est personnel : il appartient au compte Observal qui a approuvé
#   l'appareil, et n'est valable que pour CETTE machine/projet.
# - Il est révocable indépendamment des autres sessions : "observal auth logout"
#   sur cette machine, ou révocation côté admin Observal (audit-log, security-events).
# - Ne jamais coller un access_token/refresh_token dans un chat, un ticket, un
#   dépôt git ou tout autre canal partagé.
# - Cette page (observal.digiapps.be/guide) ne voit, ne stocke et ne transmet
#   jamais aucun mot de passe ni token : toute l'authentification se fait en
#   direct entre la machine externe et l'API réelle d'Observal.